feat(server): replace simple CSRF protection with GET method CSRF protection (#1846)

Adds `GetMethodCsrfProtectionHandlerPlugin`, a zero-config safeguard
that makes enabling `GET` on handlers safe with `SameSite=Lax` cookie
authentication, and removes `SimpleCsrfProtectionHandlerPlugin`
entirely. The new plugin rejects `GET` requests arriving as cross-site
or browser-initiated top-level navigations, the only context where
another site can make a browser attach explicitly marked `SameSite=Lax`
cookies to a safe-method request. Cookie-less cross-site requests keep
working, so public APIs need no origin allowlist.

## Behavior

- `GET` requests get a `403` before routing when `Sec-Fetch-Site`
reports `cross-site` or `none` on a top-level navigation
(`Sec-Fetch-Mode: navigate` targeting `Sec-Fetch-Dest: document`); a
request stripped of either header is rejected rather than passed.
- Only `GET` is guarded: navigations can use no method besides `GET` and
the unsafe `POST` per the HTML spec, so `HEAD`, `QUERY`, and every other
method pass untouched.
- Same-origin and same-site requests always pass: the site is the
`SameSite` trust boundary, so sibling-subdomain fetches and dev setups
need no configuration.
- Cross-site `fetch`, `<img>`, `<iframe>`, and other non-top-level
contexts pass, since browsers never attach `Lax` cookies to them.
- Non-browser clients and plain-HTTP deployments pass unchanged (no
Fetch Metadata), and batch requests are judged before splitting, so
forged sub-request headers cannot overturn the verdict.

## Breaking changes

- `SimpleCsrfProtectionHandlerPlugin` no longer exists; imports fail at
compile time. The replacement for cookie-based apps is
`GetMethodCsrfProtectionHandlerPlugin` with cookies explicitly marked
`SameSite=Lax` or `Strict`; apps that relied on rejecting all cross-site
traffic need their own safeguard, such as a synchronizer token.
- The v1 migration guide now maps the old CSRF plugin pair to the new
plugin.

## Docs

- New page documents which request contexts send `SameSite=Lax` cookies
(links, address bar, email links, `<img>`, `<iframe>`, `fetch`, forms)
and the resulting verdicts, plus cookie requirements: only Chrome
defaults unmarked cookies to `Lax`, so the attribute must be set
explicitly.
- The RPC handler page's "Enabling the GET Method" section now
recommends the new plugin.

## Testing

- Tests cover every navigation vector, cookie-less context, ignored
methods, stripped and repeated headers, and batch forgery, with 100%
statement and branch coverage on the plugin.
- Full suite green: root vitest, `pnpm type:check`, and `pnpm
docs:validate` (JSDoc backlinks + strict link check) all pass.

Author: dinwwwh

apps/content/docs/migrations/from-v1.mdx

@@ -517,12 +517,12 @@ v1 shipped `StrictGetMethodPlugin` enabled by default. v2 removed that plugin (a
 <CodeGroup>
 
 ```ts v2
-import { SimpleCsrfProtectionHandlerPlugin } from '@orpc/server/plugins'
+import { GetMethodCsrfProtectionHandlerPlugin } from '@orpc/server/plugins'
 import { RPC_DEFAULT_ALLOW_METHODS } from '@orpc/server/standard'
 
 const handler = new RPCHandler(router, {
   allowMethods: ['GET', ...RPC_DEFAULT_ALLOW_METHODS],
-  plugins: [new SimpleCsrfProtectionHandlerPlugin()],
+  plugins: [new GetMethodCsrfProtectionHandlerPlugin()],
 })
 ```
 
@@ -538,7 +538,7 @@ const handler = new RPCHandler(router)
 The simplest migration is to stop sending GET instead of allowing it: remove the `method` option from your [RPC Link](/docs/rpc/link) so every call uses POST (the default), and keep the handler's default `allowMethods`. Only allow GET when you really need it, for example for HTTP caching.
 :::
 
-The v2 [Simple CSRF Protection Plugin](/docs/plugins/simple-csrf-protection) checks the browser's `Sec-Fetch-*` headers, so it no longer needs a matching link plugin. Remove `SimpleCsrfProtectionLinkPlugin` from your client; it no longer exists. If your client runs on a different site than your API, list its origin in the plugin's `origin` option.
+The v2 [GET Method CSRF Protection Plugin](/docs/plugins/get-method-csrf-protection) replaces the v1 CSRF plugin pair. It checks the browser's `Sec-Fetch-*` headers, so it needs no matching link plugin and no configuration. Remove `SimpleCsrfProtectionPlugin` from your handler and `SimpleCsrfProtectionLinkPlugin` from your client; they no longer exist.
 
 ### Interceptor options renamed
 

apps/content/docs/plugins/get-method-csrf-protection.mdx

@@ -0,0 +1,61 @@
+---
+title: "GET Method CSRF Protection Plugin"
+description: "Use GetMethodCsrfProtectionHandlerPlugin to make the safe GET method as secure as POST by rejecting navigations that may carry SameSite=Lax cookies from another site."
+sidebar:
+  label: "GET Method CSRF Protection"
+---
+
+## How It Works
+
+Cross-site, browsers withhold explicitly marked [`SameSite=Lax`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#samesitesamesite-value) cookies from unsafe methods such as `POST`, but still attach them to [safe methods](https://developer.mozilla.org/en-US/docs/Glossary/Safe/HTTP) like `GET` on top-level navigations, per [RFC 6265bis](https://datatracker.ietf.org/doc/draft-ietf-httpbis-rfc6265bis/). The plugin closes that gap by rejecting exactly those navigations with a `403` before routing:
+
+| Request from another site | Sends `SameSite=Lax` cookies | |
+| --- | --- | --- |
+| link click, redirect, `window.open`, GET form | yes | rejected |
+| address bar, bookmark, link from an email or native app | yes | rejected |
+| `fetch`, `XMLHttpRequest` | no | allowed, CORS governs the response |
+| `<img>`, `<script>`, media, prefetch | no | allowed |
+| `<iframe>`, `<embed>`, `<object>`, which are not top-level | no | allowed |
+| any method other than `GET` | no | ignored |
+
+The verdict comes from [Fetch Metadata](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers#fetch_metadata_request_headers): a `GET` request is rejected when [`Sec-Fetch-Site`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Sec-Fetch-Site) reports `cross-site` or `none` on a top-level navigation (`Sec-Fetch-Mode: navigate` targeting `Sec-Fetch-Dest: document`). A guarded request stripped of either header is rejected. Only `GET` needs guarding, since [navigations use no method](https://html.spec.whatwg.org/multipage/browsing-the-web.html) besides `GET` and the unsafe `POST`. The result resembles upgrading your cookies to `SameSite=Strict` for safe methods, and also covers links opened from outside the browser, where browsers attach even `Strict` cookies.
+
+Cookie-less cross-site requests pass, which makes the plugin the natural safeguard for [enabling the `GET` method](/docs/rpc/handler#enabling-the-get-method). Requests from your own site always pass, including sibling subdomains, since the `SameSite` cookie model makes the site the trust boundary. Host untrusted content on a separate site, not a subdomain.
+
+## Setup
+
+```ts twoslash
+import { RPCHandler } from '@orpc/server/fetch'
+import { router } from './shared/planet'
+// ---cut---
+import { GetMethodCsrfProtectionHandlerPlugin } from '@orpc/server/plugins'
+import { RPC_DEFAULT_ALLOW_METHODS } from '@orpc/server/standard'
+
+const handler = new RPCHandler(router, {
+  allowMethods: ['GET', ...RPC_DEFAULT_ALLOW_METHODS],
+  plugins: [
+    new GetMethodCsrfProtectionHandlerPlugin(),
+  ],
+})
+```
+
+:::info
+The `handler` can be any supported oRPC handler, such as [RPCHandler](/docs/rpc/handler), [OpenAPIHandler](/docs/openapi/handler), or a custom one.
+:::
+
+## Cookie Requirements
+
+Mark authentication cookies `SameSite=Lax` or `SameSite=Strict` explicitly. Do not rely on browser defaults: only Chrome treats unmarked cookies as `Lax`, while Firefox and Safari treat them like `SameSite=None`, and Chrome still sends fresh unmarked cookies on cross-site `POST` for [two minutes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#lax).
+
+With `SameSite=None` or unmarked cookies, cross-site requests the plugin allows, such as `fetch` and `<img>`, can still carry them. In that case, fix the cookie attribute or add a [synchronizer token](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#synchronizer-token-pattern).
+
+## Limitations
+
+- Fetch Metadata is [Baseline widely available](https://developer.mozilla.org/en-US/docs/Glossary/Baseline/Compatibility), supported by every major browser since Safari 16.4 in March 2023. Older browsers and header-stripping proxies pass through unchecked.
+- Browsers [send Fetch Metadata only to trustworthy URLs](https://w3c.github.io/webappsec-fetch-metadata/): HTTPS and `localhost`. Over plain HTTP the headers are absent while cookies are not, so every request passes, and `localhost` qualifying hides this in development.
+- Users cannot open guarded procedures by typing the URL, following a bookmark, or clicking a link, since those navigations look identical to a forged one. Test with `curl` or a same-origin page instead.
+- Prefer `SameSite=Strict` or a [synchronizer token](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#synchronizer-token-pattern) for high-value requests.
+
+## Learn More
+
+Learn more about the attack this plugin prevents on [MDN](https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/CSRF) and in the [OWASP CSRF Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html). For implementation details, see the [source code](https://github.com/middleapi/orpc/blob/main/packages/server/src/plugins/get-method-csrf-protection.ts).

apps/content/docs/plugins/simple-csrf-protection.mdx

@@ -81,12 +81,12 @@ const handler = new RPCHandler(router, {
 ### Enabling the GET Method
 
 :::danger[Dangerous with cookie-based authentication]
-Enabling `GET` is dangerous when your application stores tokens in cookies with `SameSite=Lax` (the browser default) or `SameSite=None`. These cookies **are still sent on cross-site top-level navigations**, so an attacker only needs a signed-in user to click a link like `https://example.com/rpc/planet/delete?data=...` and the procedure runs with the victim's cookies. No JavaScript, no CORS bypass.
+Enabling `GET` is dangerous when your application stores tokens in cookies not marked `SameSite=Strict`. These cookies **are still sent on cross-site top-level navigations**, so an attacker only needs a signed-in user to click a link like `https://example.com/rpc/planet/delete?data=...` and the procedure runs with the victim's cookies. No JavaScript, no CORS bypass.
 
 To enable `GET` safely, do one of the following:
 
 - Set authentication cookies to `SameSite=Strict`, which browsers never send cross-site
-- Use an independent protection, such as the [Simple CSRF Protection Plugin](/docs/plugins/simple-csrf-protection)
+- Use an independent protection, such as the [GET Method CSRF Protection Plugin](/docs/plugins/get-method-csrf-protection)
 - Allow `GET` only for safe procedures that never modify data, as shown below
 
 Learn more about this attack on [MDN](https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/CSRF) and in the [OWASP CSRF Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html).
@@ -95,18 +95,18 @@ Learn more about this attack on [MDN](https://developer.mozilla.org/en-US/docs/W
 Add `GET` to `allowMethods` to enable it for every procedure:
 
 ```ts
-import { SimpleCsrfProtectionHandlerPlugin } from '@orpc/server/plugins'
+import { GetMethodCsrfProtectionHandlerPlugin } from '@orpc/server/plugins'
 import { RPC_DEFAULT_ALLOW_METHODS } from '@orpc/server/standard'
 
 const handler = new RPCHandler(router, {
   allowMethods: ['GET', ...RPC_DEFAULT_ALLOW_METHODS],
   plugins: [
-    new SimpleCsrfProtectionHandlerPlugin(), // reject requests initiated by another site
+    new GetMethodCsrfProtectionHandlerPlugin(), // reject GET navigations that may carry SameSite=Lax cookies
   ],
 })
 ```
 
-The plugin rejects any request the browser reports as initiated elsewhere. List the origins of clients on other sites in its `origin` option.
+The plugin rejects the navigations another site can use to send `SameSite=Lax` cookies, such as link clicks and redirects, while cookie-less requests such as `fetch` keep working. See the [GET Method CSRF Protection Plugin](/docs/plugins/get-method-csrf-protection) page for its cookie requirements.
 
 Or pass a function to decide per request. For example, only allow `GET` for procedures that declare it via [OpenAPI metadata](/docs/openapi/routing):