feat(server): GET method guard plugin (#347)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **New Features**
- Introduced a security enhancement to restrict unauthorized GET
requests.
	- Added a new sidebar entry for the GET Method Guard Plugin.
- **Documentation**
	- Expanded documentation for the GET Method Guard Plugin.
- Enhanced guidance on CSRF prevention and updated the description of
the Simple CSRF Protection Plugin.
- **Tests**
- Implemented tests to validate the behavior of the new GET Method Guard
Plugin.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: unnoq

apps/content/.vitepress/config.ts

@@ -110,6 +110,7 @@ export default defineConfig({
             { text: 'CORS', link: '/docs/plugins/cors' },
             { text: 'Response Headers', link: '/docs/plugins/response-headers' },
             { text: 'Batch Request/Response', link: '/docs/plugins/batch-request-response' },
+            { text: 'GET method guard', link: '/docs/plugins/get-method-guard' },
             { text: 'Client Retry', link: '/docs/plugins/client-retry' },
             { text: 'Body Limit', link: '/docs/plugins/body-limit' },
             { text: 'Simple CSRF Protection', link: '/docs/plugins/simple-csrf-protection' },

apps/content/docs/advanced/rpc-protocol.md

@@ -29,6 +29,10 @@ const router = {
 
 Any HTTP method can be used. Input can be provided via URL query parameters or the request body.
 
+:::info
+To help prevent [Cross-Site Request Forgery (CSRF)](https://developer.mozilla.org/en-US/docs/Web/Security/Practical_implementation_guides/CSRF_prevention) attacks, you can use the [GET Method Guard Plugin](/docs/plugins/get-method-guard) to restrict the use of the `GET` method.
+:::
+
 ### Input in URL Query
 
 ```ts

apps/content/docs/plugins/get-method-guard.md

@@ -0,0 +1,39 @@
+---
+title: GET Method Guard Plugin
+description: Enhance security by restricting GET requests to explicitly allowed procedures, mitigating Cross-Site Request Forgery (CSRF) risks.
+---
+
+# GET Method Guard Plugin
+
+This plugin enhances security by ensuring only procedures explicitly marked to accept `GET` requests can be called using the HTTP `GET` method for [RPC Protocol](/docs/advanced/rpc-protocol). This helps prevent certain types of [Cross-Site Request Forgery (CSRF)](https://developer.mozilla.org/en-US/docs/Web/Security/Practical_implementation_guides/CSRF_prevention) attacks.
+
+## When to Use
+
+This plugin is beneficial if your application stores sensitive data (like session or auth tokens) in Cookie storage using `SameSite=Lax` (the default) or `SameSite=None`.
+
+## How it works
+
+The plugin enforces a simple rule: only procedures explicitly configured with `method: 'GET'` can be invoked via a `GET` request. All other procedures will reject `GET` requests.
+
+```ts
+import { os } from '@orpc/server'
+
+const ping = os
+  .route({ method: 'GET' }) // [!code highlight]
+  .handler(() => 'pong')
+```
+
+## Setup
+
+```ts twoslash
+import { RPCHandler } from '@orpc/server/fetch'
+import { router } from './shared/planet'
+// ---cut---
+import { GetMethodGuardPlugin } from '@orpc/server/plugins'
+
+const handler = new RPCHandler(router, {
+  plugins: [
+    new GetMethodGuardPlugin()
+  ],
+})
+```

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

@@ -1,11 +1,11 @@
 ---
 title: Simple CSRF Protection Plugin
-description: Simple CSRF Protection plugin for oRPC.
+description: Add basic Cross-Site Request Forgery (CSRF) protection to your oRPC application. It helps ensure that requests to your procedures originate from JavaScript code, not from other sources like standard HTML forms or direct browser navigation.
 ---
 
-# Simple CSRF Protection
+# Simple CSRF Protection Plugin
 
-This plugin adds basic Cross-Site Request Forgery (CSRF) protection to your oRPC application. It helps ensure that requests to your procedures originate from JavaScript code, not from other sources like standard HTML forms or direct browser navigation.
+This plugin adds basic [Cross-Site Request Forgery (CSRF)](https://developer.mozilla.org/en-US/docs/Web/Security/Practical_implementation_guides/CSRF_prevention) protection to your oRPC application. It helps ensure that requests to your procedures originate from JavaScript code, not from other sources like standard HTML forms or direct browser navigation.
 
 ## When to Use
 

packages/server/src/plugins/get-method-guard.test.ts

@@ -0,0 +1,58 @@
+import { RPCHandler } from '../adapters/fetch'
+import { os } from '../builder'
+import { GetMethodGuardPlugin } from './get-method-guard'
+
+describe('getMethodGuardPlugin', () => {
+  const interceptor = vi.fn(({ next }) => next())
+
+  const handler = new RPCHandler({
+    ping: os.handler(() => 'pong'),
+    pong: os.route({ method: 'GET' }).handler(() => 'pong'),
+  }, {
+    plugins: [
+      new GetMethodGuardPlugin(),
+    ],
+    rootInterceptors: [interceptor],
+  })
+
+  it('not allow use GET method for procedure not explicitly marked as GET', async () => {
+    await expect(
+      handler.handle(new Request('http://localhost/ping?data=%7B%7D')),
+    ).resolves.toEqual({ matched: true, response: expect.toSatisfy(response => response.status === 405) })
+
+    await expect(
+      handler.handle(new Request('http://localhost/ping', {
+        method: 'POST',
+        body: JSON.stringify({ }),
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      })),
+    ).resolves.toEqual({ matched: true, response: expect.toSatisfy(response => response.status === 200) })
+  })
+
+  it('allow use GET method for procedure explicitly marked as GET', async () => {
+    await expect(
+      handler.handle(new Request('http://localhost/pong?data=%7B%7D')),
+    ).resolves.toEqual({ matched: true, response: expect.toSatisfy(response => response.status === 200) })
+  })
+
+  it('should throw error when interceptor messes with the context', async () => {
+    interceptor.mockImplementation((options) => {
+      return options.next({
+        ...options,
+        context: {}, // <-- interceptor messes with the context
+      })
+    })
+
+    await expect(
+      handler.handle(new Request('http://localhost/ping', {
+        method: 'POST',
+        body: JSON.stringify({}),
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      })),
+    ).resolves.toEqual({ matched: true, response: expect.toSatisfy(response => response.status === 500) })
+  })
+})

packages/server/src/plugins/get-method-guard.ts

@@ -0,0 +1,56 @@
+import type { StandardHandlerOptions, StandardHandlerPlugin } from '../adapters/standard'
+import type { Context } from '../context'
+import { fallbackContractConfig, ORPCError } from '@orpc/contract'
+
+export interface GetMethodGuardPluginOptions {
+
+  /**
+   * The error thrown when a GET request is made to a procedure that doesn't allow GET.
+   *
+   * @default new ORPCError('METHOD_NOT_SUPPORTED')
+   */
+  error?: InstanceType<typeof ORPCError>
+}
+
+const GET_METHOD_GUARD_PLUGIN_IS_GET_METHOD_CONTEXT_SYMBOL = Symbol('GET_METHOD_GUARD_PLUGIN_IS_GET_METHOD_CONTEXT')
+
+export class GetMethodGuardPlugin<T extends Context> implements StandardHandlerPlugin<T> {
+  private readonly error: Exclude<GetMethodGuardPluginOptions['error'], undefined>
+
+  order = 7_000_000
+
+  constructor(options: GetMethodGuardPluginOptions = {}) {
+    this.error = options.error ?? new ORPCError('METHOD_NOT_SUPPORTED')
+  }
+
+  init(options: StandardHandlerOptions<T>): void {
+    options.rootInterceptors ??= []
+    options.clientInterceptors ??= []
+
+    options.rootInterceptors.unshift((options) => {
+      const isGetMethod = options.request.method === 'GET'
+
+      return options.next({
+        ...options,
+        context: {
+          ...options.context,
+          [GET_METHOD_GUARD_PLUGIN_IS_GET_METHOD_CONTEXT_SYMBOL]: isGetMethod,
+        },
+      })
+    })
+
+    options.clientInterceptors.unshift((options) => {
+      if (typeof options.context[GET_METHOD_GUARD_PLUGIN_IS_GET_METHOD_CONTEXT_SYMBOL] !== 'boolean') {
+        throw new TypeError('[GetMethodGuardPlugin] GET method guard context has been corrupted or modified by another plugin or interceptor')
+      }
+
+      const procedureMethod = fallbackContractConfig('defaultMethod', options.procedure['~orpc'].route.method)
+
+      if (options.context[GET_METHOD_GUARD_PLUGIN_IS_GET_METHOD_CONTEXT_SYMBOL] && procedureMethod !== 'GET') {
+        throw this.error
+      }
+
+      return options.next()
+    })
+  }
+}

packages/server/src/plugins/index.ts

@@ -1,4 +1,5 @@
 export * from './batch'
 export * from './cors'
+export * from './get-method-guard'
 export * from './response-headers'
 export * from './simple-csrf-protection'