Interface CsrfOptions

Accept Origin: null when the browser also sends Sec-Fetch-Site: same-origin. Default true (since 0.11.0, M119c).

Under the default Referrer-Policy: no-referrer a browser sends Origin: null on a same-origin HTML form POST; Sec-Fetch-Site is set by the browser and cannot be written by page script, and a sandboxed, opaque-origin or cross-site initiator reports cross-site. false restores the pre-0.11.0 refusal of every null origin, for an application that prefers to send a real origin instead (referrerPolicy: 'same-origin'). A non-boolean value throws TypeError when the middleware is built.

When set, unsafe methods must carry this custom header or the request is rejected with 403. Simple form submits cannot set custom headers without a preflight, making this a CSRF defense.

Enable/disable CSRF protection. Defaults to true when present.

Request paths exempt from CSRF validation, matched against ctx.request.path by exact string equality or RegExp.test. An excluded path is checked FIRST — before the method test — and is never inspected. Default: [] (no path is exempt).

Use this only for a protocol endpoint whose own defences make the CSRF check redundant — the SAML ACS, whose signed assertion, single-use request and browser-binding cookie are the check this middleware would otherwise add (M101c, V8-9). Do not use it to bypass CSRF for application form routes.

Additional trusted origins (scheme+host) beyond the request's own origin. Implicitly trusts the URL origin; the published public origin unless the browser reports Sec-Fetch-Site as anything but same-origin; and — only when it reports same-origin — the validated leftmost X-Forwarded protocol/host candidate. Scripts cannot set Sec-Fetch-Site, while they can set X-Forwarded-* on a CORS request the server admits, so either forwarded candidate alone would let a credentialed CORS origin pass. This comparison grants no proxy trust to other consumers. Default: [].

An origin allowlist cannot admit an IdP that serves Referrer-Policy: no-referrer (Keycloak does): the browser posts the ACS with Origin: null, and trustedOrigins: ['null'] admits every opaque-origin POST on every route. For such an endpoint use CsrfOptions.exclude instead (M101c, V8-9).