feat: add Fetch Metadata CSRF protection

[memleakd]

Description

This PR proposes adding Fetch Metadata-based CSRF protection to CodeIgniter.

CSRF tokens work, and this PR keeps them as the compatibility fallback. But the web platform and modern frameworks are clearly moving toward browser-provided request context as the better default for browser CSRF protection. Other frameworks have already moved in this direction, or have active work around the same idea, and OWASP documents Fetch Metadata as a defense-in-depth layer for CSRF protection.

The reason is pretty simple: token-based CSRF protection has always been awkward and a source of headaches for many developers. Forms need hidden fields, JavaScript requests need special headers, JSON requests need special handling, cached pages and long-lived tabs can produce stale-token failures, token regeneration can surprise users, and teams regularly end up debugging "why did this normal request fail?" instead of working on the application.

Fetch Metadata gives the framework a cleaner browser-native signal. Modern browsers send the Sec-Fetch-Site header, which tells the server whether an unsafe request came from the same origin, the same site, or another site. That lets CodeIgniter ask a simpler question before touching token verification:

Is this unsafe browser request clearly coming from this application?

If yes, same-origin browser requests can pass without token plumbing. If it is clearly cross-site, it can be rejected before token verification. If the browser does not provide enough information, CodeIgniter falls back to the existing token check.

This keeps the change conservative while still moving new applications in the right direction:

• New applications use Fetch Metadata first, with token fallback.
• Upgraded applications without the new config value continue using token-only verification.
• Missing, none, unknown, or same-site Sec-Fetch-Site values fall back to token verification.
• cross-site requests are rejected before token verification.
• Apps can opt back into token-only behavior with $csrfFetchMetadata = false.
• Apps that do not trust sibling subdomains can reject same-site requests before token verification with $csrfFetchMetadataRejectSameSite = true.

public bool $csrfFetchMetadata = true;
public bool $csrfFetchMetadataRejectSameSite = false;

With Fetch Metadata enabled:

• Sec-Fetch-Site: same-origin passes without a token.
• Sec-Fetch-Site: cross-site is rejected.
• Sec-Fetch-Site: same-site falls back to token verification by default.
• Missing, none, or unknown values fall back to token verification.

So this PR does not remove CSRF tokens. They remain supported and useful as the migration fallback, especially for upgraded applications. But the direction is intentional: new CodeIgniter applications should get a more modern, browser-native CSRF protection path by default, and token-heavy CSRF handling can gradually become the legacy compatibility path rather than the everyday developer experience.

The CSRF filter also adds Vary: Sec-Fetch-Site to normal shared responses, CSRF redirect responses, and CSRF exception responses for unsafe requests when Fetch Metadata protection is enabled, so caches do not mix responses across request contexts.

Tests cover same-origin, same-site, cross-site, token fallback, token-only compatibility, upgraded config compatibility, redirect responses, Vary behavior, and request body preservation.

References

• MDN Fetch Metadata guide: https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Fetch_metadata
• MDN Sec-Fetch-Site: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Sec-Fetch-Site
• W3C Fetch Metadata Request Headers: https://www.w3.org/TR/fetch-metadata/
• OWASP CSRF Cheat Sheet, Fetch Metadata section: https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#fetch-metadata-headers
• Browser support: https://caniuse.com/mdn-http_headers_sec-fetch-site
• A Modern Approach to Preventing CSRF in Go: https://www.alexedwards.net/blog/preventing-csrf-in-go

Checklist:

• Securely signed commits
• Component(s) with PHPDoc blocks, only if necessary or adds value (without duplication)
• Unit testing, with >80% coverage
• User guide updated
• Conforms to style guide

[michalsn]

The new name csrfFetchMetadataRejectSameSite also implies a behavior change. Can we add/modify tests to make sure that:

• same-site with valid token passes by default via token fallback
• same-site with missing/invalid token fails via token fallback
• same-site with csrfFetchMetadataRejectSameSite = true fails even with a valid token

[memleakd]

Thanks for the review @michalsn. Just pushed an update addressing your feedback.