@remix-run/cors-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,174 @@
-# Placeholder Package
+# cors-middleware
 
-This package is a placeholder published at `0.0.0` to reserve the npm name and configure CI publish permissions.
+CORS middleware for Remix. It adds standard CORS response headers to Fetch API servers and can either short-circuit preflight requests or pass them through to app-defined `OPTIONS` handlers.
+
+## Features
+
+- **Preflight Handling** - Automatically handles `OPTIONS` preflight requests
+- **Flexible Origin Rules** - Supports static, regex, list, and function-based origin policies
+- **Credential Support** - Supports credentialed requests with spec-safe origin reflection
+- **Header Controls** - Configure allowed and exposed headers, preflight methods, and max age
+- **Private Network Support** - Optionally allow private network preflight requests
+
+## Installation
+
+```sh
+npm i remix
+```
+
+## Usage
+
+```ts
+import { createRouter } from 'remix/fetch-router'
+import { cors } from 'remix/cors-middleware'
+
+let router = createRouter({
+  middleware: [
+    cors({
+      origin: ['https://app.example.com', 'https://admin.example.com'],
+      credentials: true,
+      exposedHeaders: ['X-Request-Id'],
+    }),
+  ],
+})
+
+router.get('/api/projects', () => {
+  return Response.json([{ id: 'p1', name: 'Remix' }], {
+    headers: {
+      'X-Request-Id': 'req_123',
+    },
+  })
+})
+```
+
+## Origin Policies
+
+`origin` supports:
+
+- `'*'` to allow all origins
+- `string` for a single exact origin
+- `RegExp` for pattern-based matching
+- `Array<string | RegExp>` for multiple exact and pattern matches
+- `true` to reflect the request origin
+- `(origin, context) => boolean | string` for dynamic policies
+
+### Restrict Origins
+
+```ts
+let router = createRouter({
+  middleware: [
+    cors({
+      origin: ['https://app.example.com', 'https://admin.example.com'],
+      credentials: true,
+    }),
+  ],
+})
+```
+
+### Dynamic Origin Policies
+
+```ts
+let router = createRouter({
+  middleware: [
+    cors({
+      origin(origin, context) {
+        if (context.url.pathname.startsWith('/public/')) {
+          return '*'
+        }
+
+        return origin.endsWith('.trusted.example')
+      },
+    }),
+  ],
+})
+```
+
+## Preflight Behavior
+
+By default, preflight requests are short-circuited with status `204`.
+
+```ts
+let router = createRouter({
+  middleware: [
+    cors({
+      methods: ['GET', 'POST', 'PATCH'],
+      allowedHeaders: ['Authorization', 'Content-Type'],
+      maxAge: 600,
+    }),
+  ],
+})
+```
+
+Use a function-based `allowedHeaders` policy when the header allowlist depends on the request:
+
+```ts
+let router = createRouter({
+  middleware: [
+    cors({
+      allowedHeaders(request) {
+        let requestedHeaders = request.headers.get('Access-Control-Request-Headers')
+
+        if (requestedHeaders?.includes('x-admin-token')) {
+          return ['Authorization', 'Content-Type', 'X-Admin-Token']
+        }
+
+        return ['Authorization', 'Content-Type']
+      },
+    }),
+  ],
+})
+```
+
+Function-based `allowedHeaders` responses vary on `Access-Control-Request-Headers`, so caches do not reuse a preflight response for a different requested-header set.
+
+Set `preflightContinue: true` to let downstream handlers process preflight requests. Use `preflightStatusCode` when you want short-circuited preflight responses to return a status other than `204`.
+
+## Private Network Preflights
+
+```ts
+let router = createRouter({
+  middleware: [
+    cors({
+      allowPrivateNetwork: true,
+    }),
+  ],
+})
+```
+
+When `allowPrivateNetwork` is enabled, the middleware adds `Access-Control-Allow-Private-Network: true` for preflight requests that ask for private network access.
+
+## Expose Response Headers
+
+```ts
+let router = createRouter({
+  middleware: [
+    cors({
+      exposedHeaders: ['X-Request-Id', 'X-Trace-Id'],
+    }),
+  ],
+})
+```
+
+## Caveats
+
+- CORS is primarily a browser enforcement mechanism. Disallowed non-preflight requests still reach your handlers unless you add separate request validation.
+- When `credentials: true` is used with `origin: '*'`, the middleware reflects the request origin and adds `Vary: Origin` so the response stays cache-safe.
+- When `allowedHeaders` is a function, preflight responses vary on `Access-Control-Request-Headers` so caches do not reuse a response for a different requested-header set.
+- `preflightContinue` and `preflightStatusCode` only affect how preflight `OPTIONS` requests are handled. They do not change actual request authorization.
+
+## Related Packages
+
+- [`cop-middleware`](https://github.com/remix-run/remix/tree/main/packages/cop-middleware) - Browser-origin protection middleware for unsafe cross-origin requests
+- [`fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router) - Router for the web Fetch API
+- [`headers`](https://github.com/remix-run/remix/tree/main/packages/headers) - Typed HTTP header utilities
+
+## Related Work
+
+- [MDN: Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
+- [Fetch Standard: CORS protocol](https://fetch.spec.whatwg.org/#http-cors-protocol)
+- [expressjs/cors](https://github.com/expressjs/cors)
+- [rack-cors](https://github.com/cyu/rack-cors)
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { cors, type CorsAllowedHeadersResolver, type CorsAllowedHeadersResolverResult, type CorsOptions, type CorsOrigin, type CorsOriginResolver, type CorsOriginResolverResult, } from './lib/cors.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,KAAK,0BAA0B,EAC/B,KAAK,gCAAgC,EACrC,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,GAC9B,MAAM,eAAe,CAAA"}

package/dist/index.js

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

package/dist/lib/cors.d.ts

@@ -0,0 +1,100 @@
+import type { Middleware, RequestContext } from '@remix-run/fetch-router';
+type OriginMatcher = string | RegExp | ReadonlyArray<string | RegExp>;
+/**
+ * Return shape for a dynamic CORS origin resolver.
+ */
+export type CorsOriginResolverResult = '*' | string | boolean | null | undefined;
+/**
+ * Resolves the allowed origin for a given request origin.
+ */
+export interface CorsOriginResolver {
+    /**
+     * Resolves the allowed origin for a request with an `Origin` header.
+     */
+    (origin: string, context: RequestContext): CorsOriginResolverResult | Promise<CorsOriginResolverResult>;
+}
+/**
+ * Accepted forms for configuring allowed CORS origins.
+ */
+export type CorsOrigin = OriginMatcher | boolean | CorsOriginResolver;
+/**
+ * Return shape for a dynamic allowed-headers resolver.
+ */
+export type CorsAllowedHeadersResolverResult = readonly string[] | null | undefined;
+/**
+ * Resolves the allowed request headers for a preflight request.
+ */
+export interface CorsAllowedHeadersResolver {
+    /**
+     * Resolves the request headers allowed by a preflight request.
+     */
+    (request: Request, context: RequestContext): CorsAllowedHeadersResolverResult | Promise<CorsAllowedHeadersResolverResult>;
+}
+/**
+ * Options for CORS middleware.
+ */
+export interface CorsOptions {
+    /**
+     * Allowed origins. Defaults to '*'.
+     *
+     * - `true` reflects the request Origin
+     * - `false` disables CORS headers
+     * - `'*'` allows all origins
+     * - `string`/`RegExp`/array allow matching origins
+     * - `function` allows dynamic origin checks
+     */
+    origin?: CorsOrigin;
+    /**
+     * Allowed methods for preflight responses.
+     *
+     * @default ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE']
+     */
+    methods?: readonly string[];
+    /**
+     * Allowed request headers for preflight responses.
+     *
+     * Defaults to reflecting Access-Control-Request-Headers.
+     */
+    allowedHeaders?: readonly string[] | CorsAllowedHeadersResolver;
+    /**
+     * Exposed response headers for non-preflight requests.
+     */
+    exposedHeaders?: readonly string[];
+    /**
+     * Include Access-Control-Allow-Credentials: true.
+     *
+     * @default false
+     */
+    credentials?: boolean;
+    /**
+     * Access-Control-Max-Age value for preflight responses (seconds).
+     */
+    maxAge?: number;
+    /**
+     * Continue to downstream handlers for preflight requests.
+     *
+     * @default false
+     */
+    preflightContinue?: boolean;
+    /**
+     * Status code to use when short-circuiting preflight responses.
+     *
+     * @default 204
+     */
+    preflightStatusCode?: number;
+    /**
+     * Include Access-Control-Allow-Private-Network: true when requested.
+     *
+     * @default false
+     */
+    allowPrivateNetwork?: boolean;
+}
+/**
+ * Middleware that adds CORS headers and handles CORS preflight requests.
+ *
+ * @param options CORS options
+ * @returns CORS middleware
+ */
+export declare function cors(options?: CorsOptions): Middleware;
+export {};
+//# sourceMappingURL=cors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../../src/lib/cors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAKzE,KAAK,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,aAAa,CAAC,MAAM,GAAG,MAAM,CAAC,CAAA;AAErE;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG,GAAG,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAA;AAEhF;;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,OAAO,GAAG,kBAAkB,CAAA;AAErE;;GAEG;AACH,MAAM,MAAM,gCAAgC,GAAG,SAAS,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,CAAA;AAEnF;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;OAEG;IACH,CACE,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,cAAc,GACtB,gCAAgC,GAAG,OAAO,CAAC,gCAAgC,CAAC,CAAA;CAChF;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,UAAU,CAAA;IAEnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAE3B;;;;OAIG;IACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,0BAA0B,CAAA;IAE/D;;OAEG;IACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAElC;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IAErB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAE3B;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAE5B;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAC9B;AAOD;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,UAAU,CA0F1D"}

package/dist/lib/cors.js

@@ -0,0 +1,218 @@
+import { Vary } from '@remix-run/headers';
+const defaultCorsMethods = ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE'];
+/**
+ * Middleware that adds CORS headers and handles CORS preflight requests.
+ *
+ * @param options CORS options
+ * @returns CORS middleware
+ */
+export function cors(options = {}) {
+    let methods = normalizeMethodList(options.methods ?? defaultCorsMethods);
+    let exposedHeaders = options.exposedHeaders ? normalizeHeaderList(options.exposedHeaders) : '';
+    let allowCredentials = options.credentials ?? false;
+    let preflightContinue = options.preflightContinue ?? false;
+    let preflightStatusCode = options.preflightStatusCode ?? 204;
+    return async (context, next) => {
+        let requestOrigin = context.headers.get('Origin');
+        let preflightRequest = isPreflightRequest(context);
+        if (requestOrigin == null) {
+            if (preflightRequest && !preflightContinue) {
+                return new Response(null, { status: preflightStatusCode });
+            }
+            return next();
+        }
+        let allowedOrigin = await resolveAllowedOrigin(requestOrigin, context, options.origin);
+        if (allowedOrigin == null) {
+            if (preflightRequest && !preflightContinue) {
+                return new Response(null, { status: 403 });
+            }
+            return next();
+        }
+        let corsHeaders = new Headers();
+        let vary = new Vary();
+        let allowOriginHeader = allowedOrigin;
+        if (allowCredentials && allowedOrigin === '*') {
+            allowOriginHeader = requestOrigin;
+        }
+        corsHeaders.set('Access-Control-Allow-Origin', allowOriginHeader);
+        if (allowOriginHeader !== '*') {
+            vary.add('Origin');
+        }
+        if (allowCredentials) {
+            corsHeaders.set('Access-Control-Allow-Credentials', 'true');
+        }
+        if (preflightRequest) {
+            corsHeaders.set('Access-Control-Allow-Methods', methods);
+            vary.add('Access-Control-Request-Method');
+            let allowedHeaders = await resolveAllowedHeaders(context, options.allowedHeaders);
+            if (allowedHeaders.headerValue != null) {
+                corsHeaders.set('Access-Control-Allow-Headers', allowedHeaders.headerValue);
+            }
+            if (allowedHeaders.varyOnRequestHeaders) {
+                vary.add('Access-Control-Request-Headers');
+            }
+            if (options.maxAge != null) {
+                let maxAge = Math.max(0, Math.floor(options.maxAge));
+                corsHeaders.set('Access-Control-Max-Age', String(maxAge));
+            }
+            if (options.allowPrivateNetwork &&
+                context.headers.get('Access-Control-Request-Private-Network')?.toLowerCase() === 'true') {
+                corsHeaders.set('Access-Control-Allow-Private-Network', 'true');
+                vary.add('Access-Control-Request-Private-Network');
+            }
+            if (!preflightContinue) {
+                if (vary.size > 0) {
+                    corsHeaders.set('Vary', vary.toString());
+                }
+                return new Response(null, {
+                    status: preflightStatusCode,
+                    headers: corsHeaders,
+                });
+            }
+        }
+        else if (exposedHeaders !== '') {
+            corsHeaders.set('Access-Control-Expose-Headers', exposedHeaders);
+        }
+        let response = await next();
+        return withCorsHeaders(response, corsHeaders, vary);
+    };
+}
+function isPreflightRequest(context) {
+    return context.method === 'OPTIONS' && context.headers.has('Access-Control-Request-Method');
+}
+function normalizeMethodList(methods) {
+    let normalized = [];
+    for (let method of methods) {
+        let value = method.trim().toUpperCase();
+        if (value === '') {
+            continue;
+        }
+        if (normalized.includes(value)) {
+            continue;
+        }
+        normalized.push(value);
+    }
+    return normalized.join(', ');
+}
+function normalizeHeaderList(headerNames) {
+    let normalized = [];
+    for (let headerName of headerNames) {
+        let value = headerName.trim();
+        if (value === '') {
+            continue;
+        }
+        let duplicate = normalized.some((existing) => existing.toLowerCase() === value.toLowerCase());
+        if (duplicate) {
+            continue;
+        }
+        normalized.push(value);
+    }
+    return normalized.join(', ');
+}
+async function resolveAllowedOrigin(requestOrigin, context, configuredOrigin) {
+    let origin = configuredOrigin ?? '*';
+    if (typeof origin === 'function') {
+        let result = await origin(requestOrigin, context);
+        return normalizeResolvedOrigin(result, requestOrigin);
+    }
+    if (origin === true) {
+        return requestOrigin;
+    }
+    if (origin === false) {
+        return null;
+    }
+    if (typeof origin === 'string') {
+        if (origin === '*') {
+            return '*';
+        }
+        return origin === requestOrigin ? requestOrigin : null;
+    }
+    if (origin instanceof RegExp) {
+        return matchesOriginPattern(origin, requestOrigin) ? requestOrigin : null;
+    }
+    for (let allowed of origin) {
+        if (allowed === '*') {
+            return '*';
+        }
+        if (typeof allowed === 'string' && allowed === requestOrigin) {
+            return requestOrigin;
+        }
+        if (allowed instanceof RegExp && matchesOriginPattern(allowed, requestOrigin)) {
+            return requestOrigin;
+        }
+    }
+    return null;
+}
+function matchesOriginPattern(pattern, requestOrigin) {
+    let normalizedPattern = new RegExp(pattern.source, pattern.flags);
+    return normalizedPattern.test(requestOrigin);
+}
+function normalizeResolvedOrigin(resolved, requestOrigin) {
+    if (resolved == null || resolved === false) {
+        return null;
+    }
+    if (resolved === true) {
+        return requestOrigin;
+    }
+    if (resolved === '*') {
+        return '*';
+    }
+    return resolved;
+}
+async function resolveAllowedHeaders(context, configuredAllowedHeaders) {
+    if (Array.isArray(configuredAllowedHeaders)) {
+        let headerValue = normalizeHeaderList(configuredAllowedHeaders);
+        return {
+            headerValue: headerValue === '' ? null : headerValue,
+            varyOnRequestHeaders: false,
+        };
+    }
+    if (typeof configuredAllowedHeaders === 'function') {
+        let resolved = await configuredAllowedHeaders(context.request, context);
+        if (resolved != null) {
+            let headerValue = normalizeHeaderList(resolved);
+            return {
+                headerValue: headerValue === '' ? null : headerValue,
+                varyOnRequestHeaders: true,
+            };
+        }
+        let requestedHeaders = context.headers.get('Access-Control-Request-Headers');
+        if (requestedHeaders == null || requestedHeaders.trim() === '') {
+            return {
+                headerValue: null,
+                varyOnRequestHeaders: true,
+            };
+        }
+        return {
+            headerValue: requestedHeaders,
+            varyOnRequestHeaders: true,
+        };
+    }
+    let requestedHeaders = context.headers.get('Access-Control-Request-Headers');
+    if (requestedHeaders == null || requestedHeaders.trim() === '') {
+        return {
+            headerValue: null,
+            varyOnRequestHeaders: false,
+        };
+    }
+    return {
+        headerValue: requestedHeaders,
+        varyOnRequestHeaders: true,
+    };
+}
+function withCorsHeaders(response, corsHeaders, vary) {
+    let responseHeaders = new Headers(response.headers);
+    for (let [headerName, headerValue] of corsHeaders) {
+        responseHeaders.set(headerName, headerValue);
+    }
+    if (vary.size > 0) {
+        let responseVary = Vary.from(responseHeaders.get('Vary'));
+        vary.forEach((headerName) => responseVary.add(headerName));
+        responseHeaders.set('Vary', responseVary.toString());
+    }
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: responseHeaders,
+    });
+}

package/package.json

@@ -1,14 +1,54 @@
 {
   "name": "@remix-run/cors-middleware",
-  "version": "0.0.0",
-  "description": "Placeholder package for Remix CI/OIDC setup",
+  "version": "0.1.1",
+  "description": "Middleware for handling CORS 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/cors-middleware"
   },
-  "publishConfig": {
-    "access": "public"
+  "homepage": "https://github.com/remix-run/remix/tree/main/packages/cors-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/assert": "0.1.0",
+    "@remix-run/test": "0.1.0",
+    "@remix-run/headers": "0.19.0",
+    "@remix-run/fetch-router": "0.18.1"
+  },
+  "dependencies": {
+    "@remix-run/headers": "^0.19.0",
+    "@remix-run/fetch-router": "^0.18.1"
+  },
+  "keywords": [
+    "fetch",
+    "router",
+    "middleware",
+    "cors",
+    "cross-origin",
+    "preflight"
+  ],
+  "scripts": {
+    "build": "tsgo -p tsconfig.build.json",
+    "clean": "git clean -fdX",
+    "test": "remix-test",
+    "typecheck": "tsgo --noEmit"
   }
-}
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export {
+  cors,
+  type CorsAllowedHeadersResolver,
+  type CorsAllowedHeadersResolverResult,
+  type CorsOptions,
+  type CorsOrigin,
+  type CorsOriginResolver,
+  type CorsOriginResolverResult,
+} from './lib/cors.ts'

package/src/lib/cors.ts

@@ -0,0 +1,406 @@
+import type { Middleware, RequestContext } from '@remix-run/fetch-router'
+import { Vary } from '@remix-run/headers'
+
+const defaultCorsMethods = ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE']
+
+type OriginMatcher = string | RegExp | ReadonlyArray<string | RegExp>
+
+/**
+ * Return shape for a dynamic CORS origin resolver.
+ */
+export type CorsOriginResolverResult = '*' | string | boolean | null | undefined
+
+/**
+ * Resolves the allowed origin for a given request origin.
+ */
+export interface CorsOriginResolver {
+  /**
+   * Resolves the allowed origin for a request with an `Origin` header.
+   */
+  (
+    origin: string,
+    context: RequestContext,
+  ): CorsOriginResolverResult | Promise<CorsOriginResolverResult>
+}
+
+/**
+ * Accepted forms for configuring allowed CORS origins.
+ */
+export type CorsOrigin = OriginMatcher | boolean | CorsOriginResolver
+
+/**
+ * Return shape for a dynamic allowed-headers resolver.
+ */
+export type CorsAllowedHeadersResolverResult = readonly string[] | null | undefined
+
+/**
+ * Resolves the allowed request headers for a preflight request.
+ */
+export interface CorsAllowedHeadersResolver {
+  /**
+   * Resolves the request headers allowed by a preflight request.
+   */
+  (
+    request: Request,
+    context: RequestContext,
+  ): CorsAllowedHeadersResolverResult | Promise<CorsAllowedHeadersResolverResult>
+}
+
+/**
+ * Options for CORS middleware.
+ */
+export interface CorsOptions {
+  /**
+   * Allowed origins. Defaults to '*'.
+   *
+   * - `true` reflects the request Origin
+   * - `false` disables CORS headers
+   * - `'*'` allows all origins
+   * - `string`/`RegExp`/array allow matching origins
+   * - `function` allows dynamic origin checks
+   */
+  origin?: CorsOrigin
+
+  /**
+   * Allowed methods for preflight responses.
+   *
+   * @default ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE']
+   */
+  methods?: readonly string[]
+
+  /**
+   * Allowed request headers for preflight responses.
+   *
+   * Defaults to reflecting Access-Control-Request-Headers.
+   */
+  allowedHeaders?: readonly string[] | CorsAllowedHeadersResolver
+
+  /**
+   * Exposed response headers for non-preflight requests.
+   */
+  exposedHeaders?: readonly string[]
+
+  /**
+   * Include Access-Control-Allow-Credentials: true.
+   *
+   * @default false
+   */
+  credentials?: boolean
+
+  /**
+   * Access-Control-Max-Age value for preflight responses (seconds).
+   */
+  maxAge?: number
+
+  /**
+   * Continue to downstream handlers for preflight requests.
+   *
+   * @default false
+   */
+  preflightContinue?: boolean
+
+  /**
+   * Status code to use when short-circuiting preflight responses.
+   *
+   * @default 204
+   */
+  preflightStatusCode?: number
+
+  /**
+   * Include Access-Control-Allow-Private-Network: true when requested.
+   *
+   * @default false
+   */
+  allowPrivateNetwork?: boolean
+}
+
+type ResolvedAllowedHeaders = {
+  headerValue: string | null
+  varyOnRequestHeaders: boolean
+}
+
+/**
+ * Middleware that adds CORS headers and handles CORS preflight requests.
+ *
+ * @param options CORS options
+ * @returns CORS middleware
+ */
+export function cors(options: CorsOptions = {}): Middleware {
+  let methods = normalizeMethodList(options.methods ?? defaultCorsMethods)
+  let exposedHeaders = options.exposedHeaders ? normalizeHeaderList(options.exposedHeaders) : ''
+  let allowCredentials = options.credentials ?? false
+  let preflightContinue = options.preflightContinue ?? false
+  let preflightStatusCode = options.preflightStatusCode ?? 204
+
+  return async (context, next) => {
+    let requestOrigin = context.headers.get('Origin')
+    let preflightRequest = isPreflightRequest(context)
+
+    if (requestOrigin == null) {
+      if (preflightRequest && !preflightContinue) {
+        return new Response(null, { status: preflightStatusCode })
+      }
+
+      return next()
+    }
+
+    let allowedOrigin = await resolveAllowedOrigin(requestOrigin, context, options.origin)
+    if (allowedOrigin == null) {
+      if (preflightRequest && !preflightContinue) {
+        return new Response(null, { status: 403 })
+      }
+
+      return next()
+    }
+
+    let corsHeaders = new Headers()
+    let vary = new Vary()
+
+    let allowOriginHeader = allowedOrigin
+    if (allowCredentials && allowedOrigin === '*') {
+      allowOriginHeader = requestOrigin
+    }
+
+    corsHeaders.set('Access-Control-Allow-Origin', allowOriginHeader)
+
+    if (allowOriginHeader !== '*') {
+      vary.add('Origin')
+    }
+
+    if (allowCredentials) {
+      corsHeaders.set('Access-Control-Allow-Credentials', 'true')
+    }
+
+    if (preflightRequest) {
+      corsHeaders.set('Access-Control-Allow-Methods', methods)
+      vary.add('Access-Control-Request-Method')
+
+      let allowedHeaders = await resolveAllowedHeaders(context, options.allowedHeaders)
+      if (allowedHeaders.headerValue != null) {
+        corsHeaders.set('Access-Control-Allow-Headers', allowedHeaders.headerValue)
+      }
+
+      if (allowedHeaders.varyOnRequestHeaders) {
+        vary.add('Access-Control-Request-Headers')
+      }
+
+      if (options.maxAge != null) {
+        let maxAge = Math.max(0, Math.floor(options.maxAge))
+        corsHeaders.set('Access-Control-Max-Age', String(maxAge))
+      }
+
+      if (
+        options.allowPrivateNetwork &&
+        context.headers.get('Access-Control-Request-Private-Network')?.toLowerCase() === 'true'
+      ) {
+        corsHeaders.set('Access-Control-Allow-Private-Network', 'true')
+        vary.add('Access-Control-Request-Private-Network')
+      }
+
+      if (!preflightContinue) {
+        if (vary.size > 0) {
+          corsHeaders.set('Vary', vary.toString())
+        }
+
+        return new Response(null, {
+          status: preflightStatusCode,
+          headers: corsHeaders,
+        })
+      }
+    } else if (exposedHeaders !== '') {
+      corsHeaders.set('Access-Control-Expose-Headers', exposedHeaders)
+    }
+
+    let response = await next()
+
+    return withCorsHeaders(response, corsHeaders, vary)
+  }
+}
+
+function isPreflightRequest(context: RequestContext): boolean {
+  return context.method === 'OPTIONS' && context.headers.has('Access-Control-Request-Method')
+}
+
+function normalizeMethodList(methods: readonly string[]): string {
+  let normalized: string[] = []
+
+  for (let method of methods) {
+    let value = method.trim().toUpperCase()
+    if (value === '') {
+      continue
+    }
+
+    if (normalized.includes(value)) {
+      continue
+    }
+
+    normalized.push(value)
+  }
+
+  return normalized.join(', ')
+}
+
+function normalizeHeaderList(headerNames: readonly string[]): string {
+  let normalized: string[] = []
+
+  for (let headerName of headerNames) {
+    let value = headerName.trim()
+    if (value === '') {
+      continue
+    }
+
+    let duplicate = normalized.some((existing) => existing.toLowerCase() === value.toLowerCase())
+    if (duplicate) {
+      continue
+    }
+
+    normalized.push(value)
+  }
+
+  return normalized.join(', ')
+}
+
+async function resolveAllowedOrigin(
+  requestOrigin: string,
+  context: RequestContext,
+  configuredOrigin: CorsOrigin | undefined,
+): Promise<string | '*' | null> {
+  let origin = configuredOrigin ?? '*'
+
+  if (typeof origin === 'function') {
+    let result = await origin(requestOrigin, context)
+    return normalizeResolvedOrigin(result, requestOrigin)
+  }
+
+  if (origin === true) {
+    return requestOrigin
+  }
+
+  if (origin === false) {
+    return null
+  }
+
+  if (typeof origin === 'string') {
+    if (origin === '*') {
+      return '*'
+    }
+
+    return origin === requestOrigin ? requestOrigin : null
+  }
+
+  if (origin instanceof RegExp) {
+    return matchesOriginPattern(origin, requestOrigin) ? requestOrigin : null
+  }
+
+  for (let allowed of origin) {
+    if (allowed === '*') {
+      return '*'
+    }
+
+    if (typeof allowed === 'string' && allowed === requestOrigin) {
+      return requestOrigin
+    }
+
+    if (allowed instanceof RegExp && matchesOriginPattern(allowed, requestOrigin)) {
+      return requestOrigin
+    }
+  }
+
+  return null
+}
+
+function matchesOriginPattern(pattern: RegExp, requestOrigin: string): boolean {
+  let normalizedPattern = new RegExp(pattern.source, pattern.flags)
+  return normalizedPattern.test(requestOrigin)
+}
+
+function normalizeResolvedOrigin(
+  resolved: CorsOriginResolverResult,
+  requestOrigin: string,
+): string | '*' | null {
+  if (resolved == null || resolved === false) {
+    return null
+  }
+
+  if (resolved === true) {
+    return requestOrigin
+  }
+
+  if (resolved === '*') {
+    return '*'
+  }
+
+  return resolved
+}
+
+async function resolveAllowedHeaders(
+  context: RequestContext,
+  configuredAllowedHeaders: readonly string[] | CorsAllowedHeadersResolver | undefined,
+): Promise<ResolvedAllowedHeaders> {
+  if (Array.isArray(configuredAllowedHeaders)) {
+    let headerValue = normalizeHeaderList(configuredAllowedHeaders)
+
+    return {
+      headerValue: headerValue === '' ? null : headerValue,
+      varyOnRequestHeaders: false,
+    }
+  }
+
+  if (typeof configuredAllowedHeaders === 'function') {
+    let resolved = await configuredAllowedHeaders(context.request, context)
+    if (resolved != null) {
+      let headerValue = normalizeHeaderList(resolved)
+
+      return {
+        headerValue: headerValue === '' ? null : headerValue,
+        varyOnRequestHeaders: true,
+      }
+    }
+
+    let requestedHeaders = context.headers.get('Access-Control-Request-Headers')
+    if (requestedHeaders == null || requestedHeaders.trim() === '') {
+      return {
+        headerValue: null,
+        varyOnRequestHeaders: true,
+      }
+    }
+
+    return {
+      headerValue: requestedHeaders,
+      varyOnRequestHeaders: true,
+    }
+  }
+
+  let requestedHeaders = context.headers.get('Access-Control-Request-Headers')
+  if (requestedHeaders == null || requestedHeaders.trim() === '') {
+    return {
+      headerValue: null,
+      varyOnRequestHeaders: false,
+    }
+  }
+
+  return {
+    headerValue: requestedHeaders,
+    varyOnRequestHeaders: true,
+  }
+}
+
+function withCorsHeaders(response: Response, corsHeaders: Headers, vary: Vary): Response {
+  let responseHeaders = new Headers(response.headers)
+
+  for (let [headerName, headerValue] of corsHeaders) {
+    responseHeaders.set(headerName, headerValue)
+  }
+
+  if (vary.size > 0) {
+    let responseVary = Vary.from(responseHeaders.get('Vary'))
+    vary.forEach((headerName) => responseVary.add(headerName))
+    responseHeaders.set('Vary', responseVary.toString())
+  }
+
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: responseHeaders,
+  })
+}