mandrel-platform 0.13.0 → 0.14.2

package/README.md

@@ -12,14 +12,23 @@ consumer convergence matrix, and the forward roadmap are tracked privately.
 ## Reusable workflows
 
 The shared `workflow_call` workflows — `pr-quality.yml` and
-`deploy-cloudflare.yml` (plus `codeql.yml` and `smoke-dispatch.yml`) — and
-their public input/secret contract are documented in
+`deploy-cloudflare.yml` (plus `secret-scan-push.yml`, `release-automation.yml`,
+`codeql.yml`, and `smoke-dispatch.yml`) — and their public input/secret
+contract are documented in
 **[docs/reusable-workflows.md](docs/reusable-workflows.md)**. Consumers should
 configure their callers from that reference (input types, defaults,
 when-to-override, the frozen `{CLOUDFLARE_*, TURSO_*}` deploy secret allowlist,
 the single `ci-required` aggregator context, and the pin-by-tag/SHA versioning
 model).
 
+`release-automation.yml` extends the platform from CI/deploy into the **full
+release lifecycle**: a thin caller gets conventional-commit-driven version
+bumps, a `CHANGELOG.md`, and tags via release-please — the same convention the
+platform's own release train uses. It does not publish to a registry (consumers
+deploy to Cloudflare, not npm); see its section in the reference for the
+out-of-scope boundary and the `release_created` / `tag_name` outputs a
+publish/deploy job keys off.
+
 ---
 
 ## Shared Composite Actions
@@ -89,6 +98,186 @@ and standard formatter defaults (2-space indent, 100-char line width).
 }
 ```
 
+### Code-quality tooling base configs
+
+The package also ships shared base configs for the five code-quality /
+hygiene tools every consumer runs — **Knip**, **Stryker**,
+**dependency-cruiser**, **size-limit**, and **Lighthouse**. Each is the
+best-of-breed union of the consumers' previously hand-maintained configs.
+Adoption is opt-in via `extends` (or a spread / deep-merge where the tool
+has no native `extends`), and every project-specific knob — entrypoints,
+mutate globs, bundle paths, score floors, and budgets — stays
+**consumer-tunable** locally.
+
+#### `knip.base.json`
+
+Shared Knip defaults (`ignoreExportsUsedInFile`, the `mandrel` binary +
+`mandrel-platform` dependency ignores). Knip supports a native `extends`,
+so consumers point at the base and add their own `entry` / `project`
+globs (`knip.json`):
+
+```jsonc
+{
+  "extends": ["mandrel-platform/knip.base.json"],
+  "entry": ["src/index.ts", "scripts/*.ts"],
+  "project": ["src/**", "scripts/**"]
+}
+```
+
+#### `stryker.base.json`
+
+Shared Stryker mutation-testing defaults (pnpm package manager,
+`perTest` coverage analysis, HTML + clear-text + progress reporters,
+`ignoreStatic`, a 60 s timeout, and high/low/break thresholds). Stryker
+supports a native `extends`; the consumer pins its test runner and
+mutate set (`stryker.config.json`):
+
+```jsonc
+{
+  "extends": ["mandrel-platform/stryker.base.json"],
+  "testRunner": "vitest",
+  "mutate": ["src/**/*.ts", "!src/**/*.test.ts"]
+}
+```
+
+#### `dependency-cruiser.base.json`
+
+Shared dependency-cruiser rule set (no-circular, no-orphans,
+not-to-unresolvable, no-non-package-json, not-to-dev-dep,
+no-deprecated-core, and the dep-type hygiene rules) plus resolver
+options. dependency-cruiser supports a native `extends` to a JSON path —
+resolve the package export and add repo-specific rules
+(`.dependency-cruiser.json`):
+
+```jsonc
+{
+  "extends": "mandrel-platform/dependency-cruiser.base.json",
+  "forbidden": [
+    // repo-specific layering rules only
+  ]
+}
+```
+
+#### `size-limit.base.json`
+
+size-limit's own config is a per-entry **array** whose paths and limits
+are inherently repo-specific, so the base ships the shared *check
+options* (gzip sizing, `running: false`). Spread it into each entry of
+your `.size-limit.json`:
+
+```jsonc
+// .size-limit.js — spread the base into each entry
+import base from "mandrel-platform/size-limit.base.json" with { type: "json" };
+
+export default [
+  { ...base, path: "dist/index.js", limit: "10 kB" },
+  { ...base, path: "dist/cli.js", limit: "25 kB" }
+];
+```
+
+#### `lighthouse.base.json`
+
+Lighthouse's `lighthouserc.json` has no whole-file `extends`, so the
+base ships the shared `ci` block — collect settings plus the four
+category assertions on the `lighthouse:recommended` preset. Deep-merge
+it and add your repo-specific `ci.collect.url` /
+`ci.collect.staticDistDir`:
+
+```jsonc
+// lighthouserc.js — deep-merge the base, add repo-specific collect targets
+import base from "mandrel-platform/lighthouse.base.json" with { type: "json" };
+
+export default {
+  ci: {
+    ...base.ci,
+    collect: {
+      ...base.ci.collect,
+      staticDistDir: "./dist"
+    }
+  }
+};
+```
+
+> **Budgets stay consumer-tunable.** These bases standardize *which*
+> tools run and their shared defaults — not *what each tool gates on*
+> per consumer. Override any threshold, score floor, or budget locally;
+> the base provides the floor, the consumer sets the ceiling.
+
+### Edge-security middleware units
+
+The package ships reusable **per-env edge-security middleware** so the next
+consumer inherits the closed-allowlist CORS, security-header, and app-layer
+rate-limit invariants instead of re-deriving them. They are distributed through
+the **npm package-export channel** (the same channel as the base configs and
+`scripts/*`), under `mandrel-platform/edge-security`:
+
+| Sub-path                                              | Unit                                                                 |
+| ----------------------------------------------------- | -------------------------------------------------------------------- |
+| `mandrel-platform/edge-security`                      | Barrel — re-exports every unit below.                                |
+| `mandrel-platform/edge-security/cors-astro.mjs`       | `createAstroCors()` — closed-allowlist CORS as Astro middleware.     |
+| `mandrel-platform/edge-security/cors-hono.mjs`        | `createHonoCorsOptions()` — closed-allowlist options for `hono/cors`.|
+| `mandrel-platform/edge-security/security-headers.mjs` | `buildSecurityHeaders()` / `applySecurityHeaders()` — CSP/HSTS/XFO/XCTO/Referrer-Policy. |
+| `mandrel-platform/edge-security/rate-limit.mjs`       | `createRateLimiter()` + Astro/hono adapters — fixed-window app-layer limiter. |
+| `mandrel-platform/edge-security/allowlist.mjs`        | `createAllowlist()` — the shared closed-allowlist origin resolver.   |
+
+**Two CORS variants, by design.** CORS code legitimately differs by
+architecture: domio drives an Astro `(context, next)` middleware, while
+athportal / swarm-os use `hono/cors`. Both variants ship — the divergence is
+preserved, not flattened into one form. Both inherit the same closed allowlist
+and the **no-wildcard-with-credentials invariant, enforced by construction**:
+building either unit with `['*']` + `credentials: true` throws at construction
+time (before a request is ever served), so a consumer cannot mis-configure the
+forbidden `Access-Control-Allow-Origin: *` + `Access-Control-Allow-Credentials: true`
+shape.
+
+**Per-env allowlist.** Each unit takes the allowed-origin set for the current
+deployment environment, so the same code path applies in production and preview:
+
+```ts
+// Astro — src/middleware.ts
+import { defineMiddleware, sequence } from "astro:middleware";
+import { createAstroCors } from "mandrel-platform/edge-security/cors-astro.mjs";
+import { applySecurityHeaders } from "mandrel-platform/edge-security/security-headers.mjs";
+import { createAstroRateLimit } from "mandrel-platform/edge-security/rate-limit.mjs";
+
+const cors = createAstroCors({
+  allowedOrigins: import.meta.env.PROD ? ["https://godomio.com"] : ["http://localhost:4321"],
+  credentials: true,
+});
+const rateLimit = createAstroRateLimit({ limit: 100, windowMs: 60_000 });
+
+export const onRequest = sequence(
+  defineMiddleware(cors),
+  defineMiddleware(rateLimit),
+  defineMiddleware(async (_ctx, next) => {
+    const res = await next();
+    applySecurityHeaders(res.headers);
+    return res;
+  }),
+);
+```
+
+```ts
+// hono — app entry
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { createHonoCorsOptions } from "mandrel-platform/edge-security/cors-hono.mjs";
+import { createHonoRateLimit } from "mandrel-platform/edge-security/rate-limit.mjs";
+
+const app = new Hono();
+app.use("*", cors(createHonoCorsOptions({ allowedOrigins: ["https://athportal.com"], credentials: true })));
+app.use("*", createHonoRateLimit({ limit: 100, windowMs: 60_000 }));
+```
+
+> **Headers / rate-limit are framework-agnostic.** `buildSecurityHeaders()`
+> returns a plain `Record<string,string>` you can spread onto any response, and
+> `createRateLimiter()` exposes a `check(request)` decision function with a
+> pluggable store (swap the default in-memory store for a Cloudflare KV /
+> Durable Object store in production). The Astro/hono adapters are thin wrappers
+> over those cores.
+
+---
+
 ### `scripts/audit-check.mjs`
 
 CVE gate script. Runs `pnpm audit --prod` and blocks on any **unsuppressed**
@@ -235,8 +424,15 @@ pnpm run bootstrap
 
 ## Package exports
 
-| Export                                | Path                        |
-| ------------------------------------- | --------------------------- |
-| `mandrel-platform/tsconfig.base.json` | `config/tsconfig.base.json` |
-| `mandrel-platform/biome.base.json`    | `config/biome.base.json`    |
-| `mandrel-platform/scripts/*`          | `scripts/*`                 |
+| Export                                          | Path                                  |
+| ----------------------------------------------- | ------------------------------------- |
+| `mandrel-platform/tsconfig.base.json`           | `config/tsconfig.base.json`           |
+| `mandrel-platform/biome.base.json`              | `config/biome.base.json`              |
+| `mandrel-platform/knip.base.json`               | `config/knip.base.json`               |
+| `mandrel-platform/stryker.base.json`            | `config/stryker.base.json`            |
+| `mandrel-platform/dependency-cruiser.base.json` | `config/dependency-cruiser.base.json` |
+| `mandrel-platform/size-limit.base.json`         | `config/size-limit.base.json`         |
+| `mandrel-platform/lighthouse.base.json`         | `config/lighthouse.base.json`         |
+| `mandrel-platform/edge-security`                | `config/edge-security/index.mjs`      |
+| `mandrel-platform/edge-security/*`              | `config/edge-security/*`              |
+| `mandrel-platform/scripts/*`                    | `scripts/*`                           |

package/config/dependency-cruiser.base.json

@@ -0,0 +1,121 @@
+{
+  "$schema": "https://raw.githubusercontent.com/sverweij/dependency-cruiser/main/src/schema/configuration.schema.json",
+  "forbidden": [
+    {
+      "name": "no-circular",
+      "comment": "Circular dependencies make code hard to reason about and refactor. Break the cycle by extracting the shared part, or invert a dependency.",
+      "severity": "error",
+      "from": {},
+      "to": { "circular": true }
+    },
+    {
+      "name": "no-orphans",
+      "comment": "Orphan modules (imported by nothing, importing nothing relevant) are usually dead code. Remove them, or add to the ignore list if intentional.",
+      "severity": "warn",
+      "from": {
+        "orphan": true,
+        "pathNot": [
+          "(^|/)\\.[^/]+\\.(js|cjs|mjs|ts|cts|mts|json)$",
+          "\\.d\\.ts$",
+          "(^|/)tsconfig\\.json$",
+          "(^|/)(babel|webpack)\\.config\\.(js|cjs|mjs|ts|json)$"
+        ]
+      },
+      "to": {}
+    },
+    {
+      "name": "no-deprecated-core",
+      "comment": "Deprecated Node core modules will be removed in a future Node release. Migrate to the documented replacement.",
+      "severity": "error",
+      "from": {},
+      "to": {
+        "dependencyTypes": ["core"],
+        "path": ["^v8/tools/codemap$", "^node-inspect/lib/_inspect$", "^punycode$", "^domain$", "^constants$", "^sys$", "^_linklist$", "^_stream_wrap$"]
+      }
+    },
+    {
+      "name": "not-to-deprecated",
+      "comment": "This module uses a (version of an) npm module marked as deprecated. Upgrade to a non-deprecated version.",
+      "severity": "warn",
+      "from": {},
+      "to": { "dependencyTypes": ["deprecated"] }
+    },
+    {
+      "name": "no-non-package-json",
+      "comment": "This module depends on an npm package not in package.json. Add it as a dependency to keep installs reproducible.",
+      "severity": "error",
+      "from": {},
+      "to": {
+        "dependencyTypes": ["npm-no-pkg", "npm-unknown"]
+      }
+    },
+    {
+      "name": "not-to-unresolvable",
+      "comment": "This module depends on something that cannot be resolved on disk. Fix the import path or install the missing dependency.",
+      "severity": "error",
+      "from": {},
+      "to": { "couldNotResolve": true }
+    },
+    {
+      "name": "no-duplicate-dep-types",
+      "comment": "A module is in more than one dependency-type bucket (e.g. both dependencies and devDependencies). Consolidate to a single bucket.",
+      "severity": "warn",
+      "from": {},
+      "to": {
+        "moreThanOneDependencyType": true,
+        "dependencyTypesNot": ["type-only"]
+      }
+    },
+    {
+      "name": "not-to-dev-dep",
+      "comment": "Production code must not depend on a devDependency. Move the package to dependencies, or move the importing code into a non-shipped path.",
+      "severity": "error",
+      "from": {
+        "path": "^(src)",
+        "pathNot": "\\.(spec|test)\\.(js|mjs|cjs|ts|mts|cts)$"
+      },
+      "to": {
+        "dependencyTypes": ["npm-dev"],
+        "dependencyTypesNot": ["type-only"],
+        "pathNot": ["node_modules/@types/"]
+      }
+    },
+    {
+      "name": "optional-deps-used",
+      "comment": "An optionalDependency is required without a guarded fallback. Either make the require optional or promote it to a regular dependency.",
+      "severity": "info",
+      "from": {},
+      "to": {
+        "dependencyTypes": ["npm-optional"]
+      }
+    },
+    {
+      "name": "peer-deps-used",
+      "comment": "This module depends on a peerDependency, which is brittle. Inject it as a parameter instead.",
+      "severity": "warn",
+      "from": {},
+      "to": {
+        "dependencyTypes": ["npm-peer"]
+      }
+    }
+  ],
+  "options": {
+    "doNotFollow": {
+      "path": ["node_modules"]
+    },
+    "tsConfig": {
+      "fileName": "tsconfig.json"
+    },
+    "tsPreCompilationDeps": true,
+    "enhancedResolveOptions": {
+      "exportsFields": ["exports"],
+      "conditionNames": ["import", "require", "node", "default", "types"],
+      "mainFields": ["module", "main", "types", "typings"]
+    },
+    "reporterOptions": {
+      "text": {
+        "highlightFocused": true
+      }
+    }
+  }
+}

package/config/edge-security/allowlist.mjs

@@ -0,0 +1,138 @@
+/**
+ * allowlist.mjs — the closed-allowlist origin resolver shared by both CORS
+ * variants (Astro middleware + `hono/cors`).
+ *
+ * This module is the single home of the **no-wildcard-with-credentials
+ * invariant**, enforced *by construction*: the resolver never echoes a request
+ * `Origin` it has not been told to trust, and the factories that build a CORS
+ * unit refuse — at construction time — to combine a wildcard origin with
+ * `credentials: true`. A consumer cannot mis-configure the unit into the
+ * forbidden `Access-Control-Allow-Origin: *` + `Access-Control-Allow-Credentials: true`
+ * shape that the Fetch spec itself rejects and that browsers treat as a CORS
+ * failure (and which, when a server hand-rolls it, silently disables the
+ * credentialed-request protection the allowlist is meant to provide).
+ *
+ * The resolver is per-env: a consumer passes the allowlist for the current
+ * deployment environment (e.g. the production origin set vs. the preview /
+ * localhost set) and the same code path applies in every env.
+ */
+
+export const WILDCARD = "*";
+
+/**
+ * @typedef {Object} AllowlistOptions
+ * @property {boolean} [credentials=false]
+ *   When true the unit will send `Access-Control-Allow-Credentials: true`. A
+ *   wildcard origin is **rejected at construction** when this is true — that is
+ *   the no-wildcard-with-credentials invariant, enforced by construction.
+ */
+
+/**
+ * Normalize a single allowed-origin entry to its scheme+host+port form so that
+ * `https://app.example.com` and `https://app.example.com/` (trailing slash)
+ * compare equal, and a bare host is rejected rather than silently matching.
+ *
+ * @param {string} entry
+ * @returns {string} normalized origin, or the literal `*` wildcard
+ */
+export function normalizeOrigin(entry) {
+  if (typeof entry !== "string") {
+    throw new TypeError(
+      `[edge-security] allowlist entry must be a string, got ${typeof entry}`,
+    );
+  }
+  const trimmed = entry.trim();
+  if (trimmed === WILDCARD) {
+    return WILDCARD;
+  }
+  let url;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    throw new TypeError(
+      `[edge-security] allowlist entry "${entry}" is not a valid absolute origin ` +
+        `(expected e.g. "https://app.example.com" or "*")`,
+    );
+  }
+  // `URL.origin` is already scheme://host[:port] with no trailing slash.
+  return url.origin;
+}
+
+/**
+ * Build a closed-allowlist origin resolver from a per-env list of allowed
+ * origins.
+ *
+ * The returned object exposes:
+ *   - `isWildcard` — whether the env trusts every origin (`*`).
+ *   - `credentials` — the resolved credentials flag (always `false` when wildcard).
+ *   - `origins` — the normalized, de-duplicated allowed-origin set (frozen).
+ *   - `resolve(requestOrigin)` — returns the value to echo into
+ *     `Access-Control-Allow-Origin` for this request, or `null` when the origin
+ *     is not trusted (the request gets NO ACAO header — a closed allowlist).
+ *
+ * @param {string[]} allowed   Per-env allowed origins (absolute, or a single `*`).
+ * @param {AllowlistOptions} [options]
+ * @returns {{
+ *   isWildcard: boolean,
+ *   credentials: boolean,
+ *   origins: ReadonlySet<string>,
+ *   resolve: (requestOrigin: string | null | undefined) => string | null,
+ * }}
+ */
+export function createAllowlist(allowed, options = {}) {
+  if (!Array.isArray(allowed)) {
+    throw new TypeError(
+      "[edge-security] createAllowlist(allowed): `allowed` must be an array of origins",
+    );
+  }
+  const credentials = options.credentials === true;
+
+  const normalized = allowed.map(normalizeOrigin);
+  const isWildcard = normalized.includes(WILDCARD);
+
+  // ── The no-wildcard-with-credentials invariant, enforced by construction ──
+  if (isWildcard && credentials) {
+    throw new Error(
+      "[edge-security] Refusing to build a CORS unit with a wildcard origin (`*`) " +
+        "AND credentials enabled. `Access-Control-Allow-Origin: *` with " +
+        "`Access-Control-Allow-Credentials: true` is forbidden by the Fetch spec " +
+        "and disables the credentialed-request protection. Either enumerate the " +
+        "allowed origins explicitly, or set credentials: false.",
+    );
+  }
+
+  if (isWildcard && normalized.length > 1) {
+    throw new Error(
+      "[edge-security] Wildcard `*` cannot be combined with explicit origins — " +
+        "pass either `['*']` or an explicit allowlist, not both.",
+    );
+  }
+
+  const origins = Object.freeze(new Set(normalized));
+
+  /**
+   * @param {string | null | undefined} requestOrigin
+   * @returns {string | null}
+   */
+  function resolve(requestOrigin) {
+    if (isWildcard) {
+      // Wildcard env, credentials already proven false above: a literal `*` is
+      // the correct, safe ACAO value (any origin, no credentials).
+      return WILDCARD;
+    }
+    if (!requestOrigin) {
+      return null;
+    }
+    let candidate;
+    try {
+      candidate = new URL(requestOrigin).origin;
+    } catch {
+      return null;
+    }
+    // Closed allowlist: echo the request origin *only* when it is trusted.
+    // Never reflect an untrusted Origin back (the reflection footgun).
+    return origins.has(candidate) ? candidate : null;
+  }
+
+  return { isWildcard, credentials, origins, resolve };
+}

package/config/edge-security/cors-astro.mjs

@@ -0,0 +1,131 @@
+/**
+ * cors-astro.mjs — closed-allowlist CORS as an Astro middleware factory.
+ *
+ * Astro consumers (e.g. domio) hand-roll CORS in `src/middleware.ts` rather
+ * than reaching for a `hono/cors`-style helper, because Astro's middleware
+ * signature is `(context, next) => Response`. This variant ships the same
+ * closed-allowlist invariant as `cors-hono.mjs` but in the shape Astro's
+ * `defineMiddleware` expects — the architecture-driven divergence the Story
+ * preserves (two variants, not one flattened form).
+ *
+ * The no-wildcard-with-credentials invariant is inherited *by construction*
+ * from `createAllowlist`: building this middleware with `['*']` +
+ * `credentials: true` throws before a request is ever served.
+ */
+
+import { createAllowlist } from "./allowlist.mjs";
+
+/**
+ * @typedef {Object} AstroCorsOptions
+ * @property {string[]} allowedOrigins
+ *   Per-env allowed origins (absolute, or a single `*`). Required.
+ * @property {boolean} [credentials=false]
+ *   Send `Access-Control-Allow-Credentials: true`. Rejected at construction
+ *   when combined with a wildcard origin.
+ * @property {string[]} [methods=["GET","HEAD","POST","PUT","PATCH","DELETE","OPTIONS"]]
+ *   Methods echoed into `Access-Control-Allow-Methods` on preflight.
+ * @property {string[]} [allowedHeaders=["Content-Type","Authorization"]]
+ *   Request headers echoed into `Access-Control-Allow-Headers` on preflight.
+ * @property {string[]} [exposedHeaders=[]]
+ *   Response headers echoed into `Access-Control-Expose-Headers`.
+ * @property {number} [maxAge=86400]
+ *   Preflight cache lifetime, seconds (`Access-Control-Max-Age`).
+ */
+
+const DEFAULT_METHODS = [
+  "GET",
+  "HEAD",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "OPTIONS",
+];
+const DEFAULT_ALLOWED_HEADERS = ["Content-Type", "Authorization"];
+
+/**
+ * Build an Astro-shaped CORS middleware: `(context, next) => Promise<Response>`.
+ *
+ * Wire it in `src/middleware.ts`:
+ *
+ * ```ts
+ * import { defineMiddleware, sequence } from "astro:middleware";
+ * import { createAstroCors } from "mandrel-platform/edge-security/cors-astro.mjs";
+ *
+ * const cors = createAstroCors({
+ *   allowedOrigins: import.meta.env.PROD
+ *     ? ["https://godomio.com"]
+ *     : ["http://localhost:4321"],
+ *   credentials: true,
+ * });
+ *
+ * export const onRequest = sequence(defineMiddleware(cors));
+ * ```
+ *
+ * @param {AstroCorsOptions} options
+ * @returns {(context: { request: Request }, next: () => Promise<Response>) => Promise<Response>}
+ */
+export function createAstroCors(options) {
+  if (!options || !Array.isArray(options.allowedOrigins)) {
+    throw new TypeError(
+      "[edge-security] createAstroCors({ allowedOrigins }): `allowedOrigins` (string[]) is required",
+    );
+  }
+
+  const credentials = options.credentials === true;
+  // Constructs the allowlist — throws here on wildcard + credentials.
+  const allowlist = createAllowlist(options.allowedOrigins, { credentials });
+
+  const methods = options.methods ?? DEFAULT_METHODS;
+  const allowedHeaders = options.allowedHeaders ?? DEFAULT_ALLOWED_HEADERS;
+  const exposedHeaders = options.exposedHeaders ?? [];
+  const maxAge = options.maxAge ?? 86400;
+
+  /**
+   * Apply the CORS response headers for a resolved (trusted) origin.
+   * @param {Headers} headers
+   * @param {string} allowOrigin
+   */
+  function applyCorsHeaders(headers, allowOrigin) {
+    headers.set("Access-Control-Allow-Origin", allowOrigin);
+    // When we echo a specific origin (not `*`), Vary: Origin is mandatory so
+    // shared caches don't serve one origin's ACAO to another.
+    if (allowOrigin !== "*") {
+      headers.append("Vary", "Origin");
+    }
+    if (credentials) {
+      headers.set("Access-Control-Allow-Credentials", "true");
+    }
+    if (exposedHeaders.length > 0) {
+      headers.set("Access-Control-Expose-Headers", exposedHeaders.join(", "));
+    }
+  }
+
+  return async function astroCorsMiddleware(context, next) {
+    const request = context.request;
+    const requestOrigin = request.headers.get("Origin");
+    const allowOrigin = allowlist.resolve(requestOrigin);
+
+    // ── Preflight (OPTIONS) ──
+    if (request.method === "OPTIONS") {
+      const headers = new Headers();
+      if (allowOrigin) {
+        applyCorsHeaders(headers, allowOrigin);
+        headers.set("Access-Control-Allow-Methods", methods.join(", "));
+        headers.set("Access-Control-Allow-Headers", allowedHeaders.join(", "));
+        headers.set("Access-Control-Max-Age", String(maxAge));
+      }
+      // 204 No Content is the conventional preflight response. Untrusted
+      // origins get a 204 with no CORS headers — the browser then blocks the
+      // real request (a closed allowlist, not a hard 4xx).
+      return new Response(null, { status: 204, headers });
+    }
+
+    // ── Actual request ──
+    const response = await next();
+    if (allowOrigin) {
+      applyCorsHeaders(response.headers, allowOrigin);
+    }
+    return response;
+  };
+}