@remix-run/csrf-middleware 0.0.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shopify Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,99 @@
-# Placeholder Package
+# csrf-middleware
 
-This package is a placeholder published at `0.0.0` to reserve the npm name and configure CI publish permissions.
+CSRF protection middleware for Remix. It provides synchronizer-token validation backed by session storage, plus origin checks for unsafe requests.
+
+## Features
+
+- **Session-Backed Tokens** - Creates and persists CSRF tokens in the request session
+- **Flexible Token Extraction** - Reads tokens from headers, form fields, query params, or a custom resolver
+- **Origin Validation** - Validates `Origin`/`Referer` for unsafe methods with customizable policies
+- **Configurable Enforcement** - Control safe methods, token keys, and failure responses
+
+## Installation
+
+```sh
+npm i remix
+```
+
+## Usage
+
+This middleware requires [`session-middleware`](https://github.com/remix-run/remix/tree/main/packages/session-middleware) to run before it.
+
+```ts
+import { createCookie } from 'remix/cookie'
+import { createRouter } from 'remix/fetch-router'
+import { createCookieSessionStorage } from 'remix/session/cookie-storage'
+import { session } from 'remix/session-middleware'
+import { csrf, getCsrfToken } from 'remix/csrf-middleware'
+
+let sessionCookie = createCookie('__session', { secrets: ['secret1'] })
+let sessionStorage = createCookieSessionStorage()
+
+let router = createRouter({
+  middleware: [session(sessionCookie, sessionStorage), csrf()],
+})
+
+router.get('/form', (context) => {
+  let token = getCsrfToken(context)
+
+  return new Response(`
+    <form method="post" action="/submit">
+      <input type="hidden" name="_csrf" value="${token}" />
+      <button type="submit">Submit</button>
+    </form>
+  `)
+})
+```
+
+## Token Sources
+
+By default, `csrf()` checks token values in this order:
+
+1. Request headers: `x-csrf-token`, `x-xsrf-token`, `csrf-token`
+2. Form field: `_csrf` (requires `formData()` middleware to parse request bodies)
+3. Query param: `_csrf`
+
+You can override extraction using `value(context)`.
+
+Headers and form fields are the preferred transports. Query param fallback exists for compatibility, but it is the weakest option because tokens are more likely to be exposed in logs, history, and copied URLs.
+
+## Origin Validation
+
+For unsafe methods (`POST`, `PUT`, `PATCH`, `DELETE`), the middleware validates request origin.
+
+- Default: same-origin validation when `Origin` or `Referer` is present
+- Custom: provide `origin` as string, regex, array, or function
+- Missing origin behavior: controlled by `allowMissingOrigin` (default `true`)
+
+## Caveats
+
+- The synchronizer token is the primary defense in `csrf()`. `Origin` and `Referer` checks are an additional signal, not the only protection.
+- By default, unsafe requests with a valid token still pass when `Origin` and `Referer` are both missing. Set `allowMissingOrigin: false` if your deployment wants to require provenance headers on unsafe requests.
+- Query param tokens are supported for compatibility, but they should not be the default recommendation. Prefer headers or hidden form fields when you control the client.
+- If you want to reject more unsafe requests before token validation, especially when browser provenance headers are available, layer [`cop-middleware`](https://github.com/remix-run/remix/tree/main/packages/cop-middleware) in front of `csrf()`.
+
+## Why This Exists
+
+Modern browsers now provide stronger cross-origin signals like `Sec-Fetch-Site`, and explicit
+`SameSite=Lax` cookies already block many CSRF attacks. We have considered the lighter,
+tokenless model used by Go's `CrossOriginProtection`, and we think it is a good fit when a
+deployment can make all of the guarantees that model depends on.
+
+Remix cannot assume those guarantees for every app. `csrf()` still exists as the conservative
+option for apps that want synchronizer tokens in addition to origin checks, especially for
+session-backed HTML form workflows and mixed deployment environments.
+
+If your deployment can guarantee the prerequisites for the tokenless model, this middleware is
+optional. In that case, [`cop-middleware`](https://github.com/remix-run/remix/tree/main/packages/cop-middleware)
+may be a better fit.
+
+## Related Packages
+
+- [`cop-middleware`](https://github.com/remix-run/remix/tree/main/packages/cop-middleware) - Middleware for tokenless cross-origin protection using browser provenance headers
+- [`fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router) - Router for the web Fetch API
+- [`session-middleware`](https://github.com/remix-run/remix/tree/main/packages/session-middleware) - Session middleware required by `csrf()`
+- [`form-data-middleware`](https://github.com/remix-run/remix/tree/main/packages/form-data-middleware) - Needed for form body token extraction
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { csrf, getCsrfToken, type CsrfFailureReason, type CsrfOptions, type CsrfOrigin, type CsrfOriginResolver, type CsrfOriginResolverResult, type CsrfTokenResolver, type CsrfTokenResolverResult, } from './lib/csrf.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,IAAI,EACJ,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,GAC7B,MAAM,eAAe,CAAA"}

package/dist/index.js

@@ -0,0 +1 @@
+export { csrf, getCsrfToken, } from "./lib/csrf.js";

package/dist/lib/csrf.d.ts

@@ -0,0 +1,104 @@
+import type { Middleware, RequestContext, RequestMethod } from '@remix-run/fetch-router';
+type OriginMatcher = string | RegExp | ReadonlyArray<string | RegExp>;
+/**
+ * Return shape for a dynamic CSRF origin resolver.
+ */
+export type CsrfOriginResolverResult = boolean | null | undefined;
+/**
+ * Resolves whether an unsafe cross-origin request should be allowed.
+ */
+export interface CsrfOriginResolver {
+    /**
+     * Resolves whether an unsafe request origin should be trusted.
+     */
+    (origin: string, context: RequestContext): CsrfOriginResolverResult | Promise<CsrfOriginResolverResult>;
+}
+/**
+ * Accepted forms for configuring allowed CSRF origins.
+ */
+export type CsrfOrigin = OriginMatcher | CsrfOriginResolver;
+/**
+ * Return shape for a dynamic CSRF token resolver.
+ */
+export type CsrfTokenResolverResult = string | null | undefined;
+/**
+ * Resolves the submitted CSRF token for a request.
+ */
+export interface CsrfTokenResolver {
+    /**
+     * Resolves the submitted CSRF token for the current request.
+     */
+    (context: RequestContext): CsrfTokenResolverResult | Promise<CsrfTokenResolverResult>;
+}
+/**
+ * The reason a CSRF request was rejected.
+ */
+export type CsrfFailureReason = 'invalid-origin' | 'missing-token' | 'invalid-token';
+/**
+ * Options for the CSRF middleware.
+ */
+export interface CsrfOptions {
+    /**
+     * Session key used to store the server-generated CSRF token.
+     *
+     * @default '_csrf'
+     */
+    tokenKey?: string;
+    /**
+     * Form field name to read CSRF tokens from.
+     *
+     * @default '_csrf'
+     */
+    fieldName?: string;
+    /**
+     * Header names checked (in order) for CSRF tokens.
+     *
+     * @default ['x-csrf-token', 'x-xsrf-token', 'csrf-token']
+     */
+    headerNames?: readonly string[];
+    /**
+     * Methods that do not require CSRF validation.
+     *
+     * @default ['GET', 'HEAD', 'OPTIONS']
+     */
+    safeMethods?: readonly RequestMethod[];
+    /**
+     * Allowed cross-origin origins for unsafe requests.
+     *
+     * When omitted, requests are validated as same-origin.
+     */
+    origin?: CsrfOrigin;
+    /**
+     * Allow requests without Origin/Referer headers.
+     *
+     * @default true
+     */
+    allowMissingOrigin?: boolean;
+    /**
+     * Custom function for extracting the submitted token.
+     */
+    value?: CsrfTokenResolver;
+    /**
+     * Optional custom error response for rejected requests.
+     */
+    onError?: (reason: CsrfFailureReason, context: RequestContext) => Response | Promise<Response>;
+}
+/**
+ * Session-backed CSRF protection middleware.
+ *
+ * This middleware requires the session middleware to run before it.
+ *
+ * @param options CSRF options
+ * @returns CSRF middleware
+ */
+export declare function csrf(options?: CsrfOptions): Middleware;
+/**
+ * Gets the CSRF token from the session. Creates one if missing.
+ *
+ * @param context Request context with a started session
+ * @param tokenKey Session key that stores the token
+ * @returns The active CSRF token
+ */
+export declare function getCsrfToken(context: RequestContext, tokenKey?: string): string;
+export {};
+//# sourceMappingURL=csrf.d.ts.map

package/dist/lib/csrf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csrf.d.ts","sourceRoot":"","sources":["../../src/lib/csrf.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AAMxF,KAAK,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,aAAa,CAAC,MAAM,GAAG,MAAM,CAAC,CAAA;AAErE;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAA;AAEjE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,CACE,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,cAAc,GACtB,wBAAwB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAA;CAChE;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,aAAa,GAAG,kBAAkB,CAAA;AAE3D;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;AAE/D;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,CAAC,OAAO,EAAE,cAAc,GAAG,uBAAuB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAA;CACtF;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,gBAAgB,GAAG,eAAe,GAAG,eAAe,CAAA;AAEpF;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;;;OAIG;IACH,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAE/B;;;;OAIG;IACH,WAAW,CAAC,EAAE,SAAS,aAAa,EAAE,CAAA;IAEtC;;;;OAIG;IACH,MAAM,CAAC,EAAE,UAAU,CAAA;IAEnB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAE5B;;OAEG;IACH,KAAK,CAAC,EAAE,iBAAiB,CAAA;IAEzB;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,EAAE,OAAO,EAAE,cAAc,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;CAC/F;AAED;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,UAAU,CAwC1D;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,cAAc,EAAE,QAAQ,SAAU,GAAG,MAAM,CAehF"}

package/dist/lib/csrf.js

@@ -0,0 +1,167 @@
+import { Session } from '@remix-run/session';
+const defaultSafeMethods = ['GET', 'HEAD', 'OPTIONS'];
+const defaultTokenHeaderNames = ['x-csrf-token', 'x-xsrf-token', 'csrf-token'];
+/**
+ * Session-backed CSRF protection middleware.
+ *
+ * This middleware requires the session middleware to run before it.
+ *
+ * @param options CSRF options
+ * @returns CSRF middleware
+ */
+export function csrf(options = {}) {
+    let safeMethods = options.safeMethods ?? defaultSafeMethods;
+    let tokenKey = options.tokenKey ?? '_csrf';
+    let fieldName = options.fieldName ?? '_csrf';
+    let headerNames = options.headerNames ?? defaultTokenHeaderNames;
+    let allowMissingOrigin = options.allowMissingOrigin ?? true;
+    return async (context, next) => {
+        if (!context.has(Session)) {
+            throw new Error('csrf middleware requires session() middleware to run before it');
+        }
+        let expectedToken = getCsrfToken(context, tokenKey);
+        if (safeMethods.includes(context.method)) {
+            return next();
+        }
+        let validOrigin = await validateRequestOrigin(context, options.origin, allowMissingOrigin, context.url.origin);
+        if (!validOrigin) {
+            return getErrorResponse(options, 'invalid-origin', context);
+        }
+        let submittedToken = await resolveSubmittedToken(context, options.value, fieldName, headerNames);
+        if (submittedToken == null || submittedToken === '') {
+            return getErrorResponse(options, 'missing-token', context);
+        }
+        if (!constantTimeEqual(submittedToken, expectedToken)) {
+            return getErrorResponse(options, 'invalid-token', context);
+        }
+        return next();
+    };
+}
+/**
+ * Gets the CSRF token from the session. Creates one if missing.
+ *
+ * @param context Request context with a started session
+ * @param tokenKey Session key that stores the token
+ * @returns The active CSRF token
+ */
+export function getCsrfToken(context, tokenKey = '_csrf') {
+    if (!context.has(Session)) {
+        throw new Error('Session is not started. Use session() middleware before csrf().');
+    }
+    let session = context.get(Session);
+    let token = session.get(tokenKey);
+    if (typeof token === 'string' && token !== '') {
+        return token;
+    }
+    let createdToken = createCsrfToken();
+    session.set(tokenKey, createdToken);
+    return createdToken;
+}
+function createCsrfToken() {
+    let bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    let token = '';
+    for (let byte of bytes) {
+        token += byte.toString(16).padStart(2, '0');
+    }
+    return token;
+}
+function getErrorResponse(options, reason, context) {
+    if (options.onError) {
+        return options.onError(reason, context);
+    }
+    if (reason === 'invalid-origin') {
+        return new Response('Forbidden: invalid CSRF origin', { status: 403 });
+    }
+    if (reason === 'missing-token') {
+        return new Response('Forbidden: missing CSRF token', { status: 403 });
+    }
+    return new Response('Forbidden: invalid CSRF token', { status: 403 });
+}
+async function resolveSubmittedToken(context, valueResolver, fieldName, headerNames) {
+    if (valueResolver) {
+        let value = await valueResolver(context);
+        if (value == null) {
+            return null;
+        }
+        let trimmedValue = value.trim();
+        return trimmedValue === '' ? null : trimmedValue;
+    }
+    for (let headerName of headerNames) {
+        let headerValue = context.headers.get(headerName);
+        if (headerValue == null) {
+            continue;
+        }
+        let trimmedHeaderValue = headerValue.trim();
+        if (trimmedHeaderValue !== '') {
+            return trimmedHeaderValue;
+        }
+    }
+    let formValue = context.has(FormData) ? context.get(FormData).get(fieldName) : undefined;
+    if (typeof formValue === 'string') {
+        let trimmedFormValue = formValue.trim();
+        if (trimmedFormValue !== '') {
+            return trimmedFormValue;
+        }
+    }
+    let queryValue = context.url.searchParams.get(fieldName);
+    if (queryValue == null) {
+        return null;
+    }
+    let trimmedQueryValue = queryValue.trim();
+    return trimmedQueryValue === '' ? null : trimmedQueryValue;
+}
+async function validateRequestOrigin(context, configuredOrigin, allowMissingOrigin, defaultOrigin) {
+    let requestOrigin = getRequestOrigin(context);
+    if (requestOrigin == null) {
+        return allowMissingOrigin;
+    }
+    if (configuredOrigin == null) {
+        return requestOrigin === defaultOrigin;
+    }
+    if (typeof configuredOrigin === 'function') {
+        let result = await configuredOrigin(requestOrigin, context);
+        return result === true;
+    }
+    if (typeof configuredOrigin === 'string') {
+        return configuredOrigin === requestOrigin;
+    }
+    if (configuredOrigin instanceof RegExp) {
+        return configuredOrigin.test(requestOrigin);
+    }
+    for (let allowedOrigin of configuredOrigin) {
+        if (typeof allowedOrigin === 'string' && allowedOrigin === requestOrigin) {
+            return true;
+        }
+        if (allowedOrigin instanceof RegExp && allowedOrigin.test(requestOrigin)) {
+            return true;
+        }
+    }
+    return false;
+}
+function getRequestOrigin(context) {
+    let origin = context.headers.get('Origin');
+    if (origin != null && origin.trim() !== '') {
+        return origin;
+    }
+    let referer = context.headers.get('Referer');
+    if (referer == null || referer.trim() === '') {
+        return null;
+    }
+    try {
+        return new URL(referer).origin;
+    }
+    catch {
+        return null;
+    }
+}
+function constantTimeEqual(left, right) {
+    let mismatch = left.length === right.length ? 0 : 1;
+    let maxLength = Math.max(left.length, right.length);
+    for (let index = 0; index < maxLength; index++) {
+        let leftCode = left.charCodeAt(index) || 0;
+        let rightCode = right.charCodeAt(index) || 0;
+        mismatch |= leftCode ^ rightCode;
+    }
+    return mismatch === 0;
+}

package/package.json

@@ -1,14 +1,57 @@
 {
   "name": "@remix-run/csrf-middleware",
-  "version": "0.0.0",
-  "description": "Placeholder package for Remix CI/OIDC setup",
+  "version": "0.1.1",
+  "description": "Middleware for CSRF protection in Fetch API servers",
+  "author": "Michael Jackson <mjijackson@gmail.com>",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/remix-run/remix.git",
     "directory": "packages/csrf-middleware"
   },
-  "publishConfig": {
-    "access": "public"
+  "homepage": "https://github.com/remix-run/remix/tree/main/packages/csrf-middleware#readme",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "@typescript/native-preview": "7.0.0-dev.20251125.1",
+    "@remix-run/cookie": "0.5.1",
+    "@remix-run/assert": "0.1.0",
+    "@remix-run/form-data-middleware": "0.2.1",
+    "@remix-run/fetch-router": "0.18.1",
+    "@remix-run/session-middleware": "0.2.1",
+    "@remix-run/session": "0.4.1",
+    "@remix-run/test": "0.1.0"
+  },
+  "dependencies": {
+    "@remix-run/fetch-router": "^0.18.1",
+    "@remix-run/session": "^0.4.1"
+  },
+  "keywords": [
+    "fetch",
+    "router",
+    "middleware",
+    "csrf",
+    "security",
+    "origin"
+  ],
+  "scripts": {
+    "build": "tsgo -p tsconfig.build.json",
+    "clean": "git clean -fdX",
+    "test": "remix-test",
+    "typecheck": "tsgo --noEmit"
   }
-}
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export {
+  csrf,
+  getCsrfToken,
+  type CsrfFailureReason,
+  type CsrfOptions,
+  type CsrfOrigin,
+  type CsrfOriginResolver,
+  type CsrfOriginResolverResult,
+  type CsrfTokenResolver,
+  type CsrfTokenResolverResult,
+} from './lib/csrf.ts'

package/src/lib/csrf.ts

@@ -0,0 +1,330 @@
+import type { Middleware, RequestContext, RequestMethod } from '@remix-run/fetch-router'
+import { Session } from '@remix-run/session'
+
+const defaultSafeMethods: RequestMethod[] = ['GET', 'HEAD', 'OPTIONS']
+const defaultTokenHeaderNames = ['x-csrf-token', 'x-xsrf-token', 'csrf-token']
+
+type OriginMatcher = string | RegExp | ReadonlyArray<string | RegExp>
+
+/**
+ * Return shape for a dynamic CSRF origin resolver.
+ */
+export type CsrfOriginResolverResult = boolean | null | undefined
+
+/**
+ * Resolves whether an unsafe cross-origin request should be allowed.
+ */
+export interface CsrfOriginResolver {
+  /**
+   * Resolves whether an unsafe request origin should be trusted.
+   */
+  (
+    origin: string,
+    context: RequestContext,
+  ): CsrfOriginResolverResult | Promise<CsrfOriginResolverResult>
+}
+
+/**
+ * Accepted forms for configuring allowed CSRF origins.
+ */
+export type CsrfOrigin = OriginMatcher | CsrfOriginResolver
+
+/**
+ * Return shape for a dynamic CSRF token resolver.
+ */
+export type CsrfTokenResolverResult = string | null | undefined
+
+/**
+ * Resolves the submitted CSRF token for a request.
+ */
+export interface CsrfTokenResolver {
+  /**
+   * Resolves the submitted CSRF token for the current request.
+   */
+  (context: RequestContext): CsrfTokenResolverResult | Promise<CsrfTokenResolverResult>
+}
+
+/**
+ * The reason a CSRF request was rejected.
+ */
+export type CsrfFailureReason = 'invalid-origin' | 'missing-token' | 'invalid-token'
+
+/**
+ * Options for the CSRF middleware.
+ */
+export interface CsrfOptions {
+  /**
+   * Session key used to store the server-generated CSRF token.
+   *
+   * @default '_csrf'
+   */
+  tokenKey?: string
+
+  /**
+   * Form field name to read CSRF tokens from.
+   *
+   * @default '_csrf'
+   */
+  fieldName?: string
+
+  /**
+   * Header names checked (in order) for CSRF tokens.
+   *
+   * @default ['x-csrf-token', 'x-xsrf-token', 'csrf-token']
+   */
+  headerNames?: readonly string[]
+
+  /**
+   * Methods that do not require CSRF validation.
+   *
+   * @default ['GET', 'HEAD', 'OPTIONS']
+   */
+  safeMethods?: readonly RequestMethod[]
+
+  /**
+   * Allowed cross-origin origins for unsafe requests.
+   *
+   * When omitted, requests are validated as same-origin.
+   */
+  origin?: CsrfOrigin
+
+  /**
+   * Allow requests without Origin/Referer headers.
+   *
+   * @default true
+   */
+  allowMissingOrigin?: boolean
+
+  /**
+   * Custom function for extracting the submitted token.
+   */
+  value?: CsrfTokenResolver
+
+  /**
+   * Optional custom error response for rejected requests.
+   */
+  onError?: (reason: CsrfFailureReason, context: RequestContext) => Response | Promise<Response>
+}
+
+/**
+ * Session-backed CSRF protection middleware.
+ *
+ * This middleware requires the session middleware to run before it.
+ *
+ * @param options CSRF options
+ * @returns CSRF middleware
+ */
+export function csrf(options: CsrfOptions = {}): Middleware {
+  let safeMethods = options.safeMethods ?? defaultSafeMethods
+  let tokenKey = options.tokenKey ?? '_csrf'
+  let fieldName = options.fieldName ?? '_csrf'
+  let headerNames = options.headerNames ?? defaultTokenHeaderNames
+  let allowMissingOrigin = options.allowMissingOrigin ?? true
+
+  return async (context, next) => {
+    if (!context.has(Session)) {
+      throw new Error('csrf middleware requires session() middleware to run before it')
+    }
+
+    let expectedToken = getCsrfToken(context, tokenKey)
+
+    if (safeMethods.includes(context.method)) {
+      return next()
+    }
+
+    let validOrigin = await validateRequestOrigin(
+      context,
+      options.origin,
+      allowMissingOrigin,
+      context.url.origin,
+    )
+    if (!validOrigin) {
+      return getErrorResponse(options, 'invalid-origin', context)
+    }
+
+    let submittedToken = await resolveSubmittedToken(context, options.value, fieldName, headerNames)
+
+    if (submittedToken == null || submittedToken === '') {
+      return getErrorResponse(options, 'missing-token', context)
+    }
+
+    if (!constantTimeEqual(submittedToken, expectedToken)) {
+      return getErrorResponse(options, 'invalid-token', context)
+    }
+
+    return next()
+  }
+}
+
+/**
+ * Gets the CSRF token from the session. Creates one if missing.
+ *
+ * @param context Request context with a started session
+ * @param tokenKey Session key that stores the token
+ * @returns The active CSRF token
+ */
+export function getCsrfToken(context: RequestContext, tokenKey = '_csrf'): string {
+  if (!context.has(Session)) {
+    throw new Error('Session is not started. Use session() middleware before csrf().')
+  }
+
+  let session = context.get(Session)
+  let token = session.get(tokenKey)
+  if (typeof token === 'string' && token !== '') {
+    return token
+  }
+
+  let createdToken = createCsrfToken()
+  session.set(tokenKey, createdToken)
+
+  return createdToken
+}
+
+function createCsrfToken(): string {
+  let bytes = new Uint8Array(32)
+  crypto.getRandomValues(bytes)
+
+  let token = ''
+  for (let byte of bytes) {
+    token += byte.toString(16).padStart(2, '0')
+  }
+
+  return token
+}
+
+function getErrorResponse(
+  options: CsrfOptions,
+  reason: CsrfFailureReason,
+  context: RequestContext,
+): Response | Promise<Response> {
+  if (options.onError) {
+    return options.onError(reason, context)
+  }
+
+  if (reason === 'invalid-origin') {
+    return new Response('Forbidden: invalid CSRF origin', { status: 403 })
+  }
+
+  if (reason === 'missing-token') {
+    return new Response('Forbidden: missing CSRF token', { status: 403 })
+  }
+
+  return new Response('Forbidden: invalid CSRF token', { status: 403 })
+}
+
+async function resolveSubmittedToken(
+  context: RequestContext,
+  valueResolver: CsrfTokenResolver | undefined,
+  fieldName: string,
+  headerNames: readonly string[],
+): Promise<string | null> {
+  if (valueResolver) {
+    let value = await valueResolver(context)
+    if (value == null) {
+      return null
+    }
+
+    let trimmedValue = value.trim()
+    return trimmedValue === '' ? null : trimmedValue
+  }
+
+  for (let headerName of headerNames) {
+    let headerValue = context.headers.get(headerName)
+    if (headerValue == null) {
+      continue
+    }
+
+    let trimmedHeaderValue = headerValue.trim()
+    if (trimmedHeaderValue !== '') {
+      return trimmedHeaderValue
+    }
+  }
+
+  let formValue = context.has(FormData) ? context.get(FormData).get(fieldName) : undefined
+  if (typeof formValue === 'string') {
+    let trimmedFormValue = formValue.trim()
+    if (trimmedFormValue !== '') {
+      return trimmedFormValue
+    }
+  }
+
+  let queryValue = context.url.searchParams.get(fieldName)
+  if (queryValue == null) {
+    return null
+  }
+
+  let trimmedQueryValue = queryValue.trim()
+  return trimmedQueryValue === '' ? null : trimmedQueryValue
+}
+
+async function validateRequestOrigin(
+  context: RequestContext,
+  configuredOrigin: CsrfOrigin | undefined,
+  allowMissingOrigin: boolean,
+  defaultOrigin: string,
+): Promise<boolean> {
+  let requestOrigin = getRequestOrigin(context)
+  if (requestOrigin == null) {
+    return allowMissingOrigin
+  }
+
+  if (configuredOrigin == null) {
+    return requestOrigin === defaultOrigin
+  }
+
+  if (typeof configuredOrigin === 'function') {
+    let result = await configuredOrigin(requestOrigin, context)
+    return result === true
+  }
+
+  if (typeof configuredOrigin === 'string') {
+    return configuredOrigin === requestOrigin
+  }
+
+  if (configuredOrigin instanceof RegExp) {
+    return configuredOrigin.test(requestOrigin)
+  }
+
+  for (let allowedOrigin of configuredOrigin) {
+    if (typeof allowedOrigin === 'string' && allowedOrigin === requestOrigin) {
+      return true
+    }
+
+    if (allowedOrigin instanceof RegExp && allowedOrigin.test(requestOrigin)) {
+      return true
+    }
+  }
+
+  return false
+}
+
+function getRequestOrigin(context: RequestContext): string | null {
+  let origin = context.headers.get('Origin')
+  if (origin != null && origin.trim() !== '') {
+    return origin
+  }
+
+  let referer = context.headers.get('Referer')
+  if (referer == null || referer.trim() === '') {
+    return null
+  }
+
+  try {
+    return new URL(referer).origin
+  } catch {
+    return null
+  }
+}
+
+function constantTimeEqual(left: string, right: string): boolean {
+  let mismatch = left.length === right.length ? 0 : 1
+  let maxLength = Math.max(left.length, right.length)
+
+  for (let index = 0; index < maxLength; index++) {
+    let leftCode = left.charCodeAt(index) || 0
+    let rightCode = right.charCodeAt(index) || 0
+    mismatch |= leftCode ^ rightCode
+  }
+
+  return mismatch === 0
+}