mandrel-platform 0.12.0 → 0.14.2

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

@@ -0,0 +1,111 @@
+/**
+ * cors-hono.mjs — closed-allowlist CORS as a `hono/cors` options factory.
+ *
+ * `hono`-based consumers (athportal, swarm-os) reach for the built-in
+ * `hono/cors` middleware, whose options object takes an `origin` that may be a
+ * function `(origin, c) => string | null`. This variant builds exactly that
+ * options object — pre-wired with the closed-allowlist resolver — so the
+ * consumer writes `app.use("*", cors(createHonoCorsOptions({...})))` and
+ * inherits the invariant instead of re-deriving the origin callback.
+ *
+ * The no-wildcard-with-credentials invariant is inherited *by construction*
+ * from `createAllowlist`: building these options with `['*']` +
+ * `credentials: true` throws before the app ever starts.
+ */
+
+import { createAllowlist } from "./allowlist.mjs";
+
+/**
+ * @typedef {Object} HonoCorsOptions
+ * @property {string[]} allowedOrigins
+ *   Per-env allowed origins (absolute, or a single `*`). Required.
+ * @property {boolean} [credentials=false]
+ *   Maps to the `hono/cors` `credentials` option. Rejected at construction
+ *   when combined with a wildcard origin.
+ * @property {string[]} [methods=["GET","HEAD","POST","PUT","PATCH","DELETE","OPTIONS"]]
+ * @property {string[]} [allowedHeaders=["Content-Type","Authorization"]]
+ * @property {string[]} [exposedHeaders=[]]
+ * @property {number} [maxAge=86400]
+ */
+
+const DEFAULT_METHODS = [
+  "GET",
+  "HEAD",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "OPTIONS",
+];
+const DEFAULT_ALLOWED_HEADERS = ["Content-Type", "Authorization"];
+
+/**
+ * Build the options object for `hono/cors`'s `cors()` middleware.
+ *
+ * The returned `origin` is a function so the closed allowlist is applied
+ * per-request: it echoes the request origin only when trusted, and returns
+ * `null` otherwise (no `Access-Control-Allow-Origin` header — `hono/cors`
+ * omits the header for a `null` return, which is the closed-allowlist
+ * behaviour). For a wildcard env it returns the literal `*` (credentials are
+ * proven `false` by construction in that case).
+ *
+ * ```ts
+ * import { Hono } from "hono";
+ * import { cors } from "hono/cors";
+ * import { createHonoCorsOptions } from "mandrel-platform/edge-security/cors-hono.mjs";
+ *
+ * const app = new Hono();
+ * app.use(
+ *   "*",
+ *   cors(
+ *     createHonoCorsOptions({
+ *       allowedOrigins: ["https://athportal.com"],
+ *       credentials: true,
+ *     }),
+ *   ),
+ * );
+ * ```
+ *
+ * @param {HonoCorsOptions} options
+ * @returns {{
+ *   origin: (origin: string) => string | null,
+ *   allowMethods: string[],
+ *   allowHeaders: string[],
+ *   exposeHeaders: string[],
+ *   credentials: boolean,
+ *   maxAge: number,
+ * }}
+ */
+export function createHonoCorsOptions(options) {
+  if (!options || !Array.isArray(options.allowedOrigins)) {
+    throw new TypeError(
+      "[edge-security] createHonoCorsOptions({ 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 allowMethods = options.methods ?? DEFAULT_METHODS;
+  const allowHeaders = options.allowedHeaders ?? DEFAULT_ALLOWED_HEADERS;
+  const exposeHeaders = options.exposedHeaders ?? [];
+  const maxAge = options.maxAge ?? 86400;
+
+  return {
+    /**
+     * `hono/cors` origin callback. Returns the value for
+     * `Access-Control-Allow-Origin`, or `null` when the origin is untrusted.
+     * @param {string} requestOrigin
+     * @returns {string | null}
+     */
+    origin(requestOrigin) {
+      return allowlist.resolve(requestOrigin);
+    },
+    allowMethods,
+    allowHeaders,
+    exposeHeaders,
+    credentials,
+    maxAge,
+  };
+}

package/config/edge-security/index.mjs

@@ -0,0 +1,34 @@
+/**
+ * edge-security — reusable per-env edge-security middleware units for
+ * mandrel-platform consumers.
+ *
+ * Covers the three invariants every consumer was hand-rolling per env:
+ *   - **CORS** (closed allowlist; Astro + hono variants), with the
+ *     no-wildcard-with-credentials invariant enforced *by construction*.
+ *   - **Security headers** (CSP / HSTS / XFO / XCTO / Referrer-Policy).
+ *   - **App-layer rate limiting** (fixed-window; Astro + hono adapters).
+ *
+ * Distributed through the npm package-export channel (see
+ * `mandrel-platform/edge-security/*`), consistent with the platform's other
+ * reusable code (`config/*.base.json`, `scripts/*`). Import the barrel for
+ * everything, or a single sub-path for one unit.
+ *
+ * The CORS code legitimately differs by architecture (Astro middleware vs
+ * `hono/cors`), so both variants ship — the divergence is preserved, not
+ * flattened.
+ */
+
+export { createAllowlist, normalizeOrigin, WILDCARD } from "./allowlist.mjs";
+export { createAstroCors } from "./cors-astro.mjs";
+export { createHonoCorsOptions } from "./cors-hono.mjs";
+export {
+  applySecurityHeaders,
+  buildSecurityHeaders,
+} from "./security-headers.mjs";
+export {
+  createAstroRateLimit,
+  createHonoRateLimit,
+  createMemoryStore,
+  createRateLimiter,
+  rateLimitHeaders,
+} from "./rate-limit.mjs";

package/config/edge-security/rate-limit.mjs

@@ -0,0 +1,219 @@
+/**
+ * rate-limit.mjs — app-layer rate limiting as a framework-agnostic fixed-window
+ * limiter plus thin Astro / hono adapters.
+ *
+ * Consumers were each hand-rolling an in-memory / KV-backed limiter with the
+ * same intent (N requests per window per key). This unit ships the core
+ * decision function — `createRateLimiter` — parameterized by limit, window, a
+ * key extractor, and a pluggable store, so a consumer swaps the in-memory store
+ * for a Cloudflare KV / Durable Object store without re-deriving the limiter
+ * logic. The default store is a self-pruning in-memory `Map` suitable for a
+ * single-isolate dev / small deployment; production multi-isolate consumers
+ * pass a shared store.
+ */
+
+/**
+ * @typedef {Object} RateLimitStore
+ * @property {(key: string) => Promise<{ count: number, resetAt: number } | null> | { count: number, resetAt: number } | null} get
+ * @property {(key: string, value: { count: number, resetAt: number }) => Promise<void> | void} set
+ */
+
+/**
+ * In-memory fixed-window store. Self-prunes expired buckets on access so it
+ * does not leak unboundedly. NOT shared across isolates — fine for dev / single
+ * instance; pass a KV-backed store in production.
+ * @returns {RateLimitStore}
+ */
+export function createMemoryStore() {
+  /** @type {Map<string, { count: number, resetAt: number }>} */
+  const buckets = new Map();
+  return {
+    get(key) {
+      const bucket = buckets.get(key);
+      if (!bucket) {
+        return null;
+      }
+      if (bucket.resetAt <= Date.now()) {
+        buckets.delete(key);
+        return null;
+      }
+      return bucket;
+    },
+    set(key, value) {
+      buckets.set(key, value);
+    },
+  };
+}
+
+/**
+ * @typedef {Object} RateLimiterOptions
+ * @property {number} limit          Max requests allowed per window. Required.
+ * @property {number} windowMs       Window length in milliseconds. Required.
+ * @property {(request: Request) => string} [keyExtractor]
+ *   Derives the rate-limit bucket key from the request. Defaults to the
+ *   client IP from `CF-Connecting-IP` / `X-Forwarded-For` (first hop), falling
+ *   back to a constant so a missing IP fails *closed* into one shared bucket
+ *   rather than bypassing the limit per-request.
+ * @property {RateLimitStore} [store] Defaults to `createMemoryStore()`.
+ */
+
+/**
+ * @typedef {Object} RateLimitDecision
+ * @property {boolean} allowed
+ * @property {number} limit
+ * @property {number} remaining
+ * @property {number} resetAt    Epoch ms when the current window resets.
+ * @property {number} retryAfter Seconds until reset (0 when allowed).
+ */
+
+/**
+ * Default key extractor: client IP, failing closed to a shared bucket.
+ * @param {Request} request
+ * @returns {string}
+ */
+function defaultKeyExtractor(request) {
+  const cf = request.headers.get("CF-Connecting-IP");
+  if (cf) {
+    return cf;
+  }
+  const xff = request.headers.get("X-Forwarded-For");
+  if (xff) {
+    const first = xff.split(",")[0];
+    if (first) {
+      return first.trim();
+    }
+  }
+  // No identifiable client — fail closed into one shared bucket rather than
+  // handing every anonymous request its own unlimited allowance.
+  return "anonymous";
+}
+
+/**
+ * Build a fixed-window rate limiter. The returned `check(request)` resolves to
+ * a decision object the caller turns into a 429 (or passes through).
+ *
+ * @param {RateLimiterOptions} options
+ * @returns {{ check: (request: Request) => Promise<RateLimitDecision> }}
+ */
+export function createRateLimiter(options) {
+  if (
+    !options ||
+    typeof options.limit !== "number" ||
+    typeof options.windowMs !== "number"
+  ) {
+    throw new TypeError(
+      "[edge-security] createRateLimiter({ limit, windowMs }): numeric `limit` and `windowMs` are required",
+    );
+  }
+  if (options.limit < 1 || options.windowMs < 1) {
+    throw new RangeError(
+      "[edge-security] createRateLimiter: `limit` and `windowMs` must be >= 1",
+    );
+  }
+  const limit = options.limit;
+  const windowMs = options.windowMs;
+  const keyExtractor = options.keyExtractor ?? defaultKeyExtractor;
+  const store = options.store ?? createMemoryStore();
+
+  return {
+    /**
+     * @param {Request} request
+     * @returns {Promise<RateLimitDecision>}
+     */
+    async check(request) {
+      const key = keyExtractor(request);
+      const now = Date.now();
+      const existing = await store.get(key);
+
+      let count;
+      let resetAt;
+      if (existing && existing.resetAt > now) {
+        count = existing.count + 1;
+        resetAt = existing.resetAt;
+      } else {
+        count = 1;
+        resetAt = now + windowMs;
+      }
+
+      await store.set(key, { count, resetAt });
+
+      const allowed = count <= limit;
+      const remaining = Math.max(0, limit - count);
+      const retryAfter = allowed ? 0 : Math.ceil((resetAt - now) / 1000);
+
+      return { allowed, limit, remaining, resetAt, retryAfter };
+    },
+  };
+}
+
+/**
+ * Standard rate-limit response headers for a decision. Spread onto a 429 (or a
+ * passed-through response) so clients see their budget.
+ * @param {RateLimitDecision} decision
+ * @returns {Record<string, string>}
+ */
+export function rateLimitHeaders(decision) {
+  /** @type {Record<string, string>} */
+  const headers = {
+    "RateLimit-Limit": String(decision.limit),
+    "RateLimit-Remaining": String(decision.remaining),
+    "RateLimit-Reset": String(Math.ceil((decision.resetAt - Date.now()) / 1000)),
+  };
+  if (!decision.allowed) {
+    headers["Retry-After"] = String(decision.retryAfter);
+  }
+  return headers;
+}
+
+/**
+ * Astro middleware adapter: returns `(context, next) => Response`. Short-circuits
+ * with a 429 when the limiter denies the request, otherwise annotates the
+ * downstream response with the budget headers.
+ *
+ * @param {RateLimiterOptions} options
+ * @returns {(context: { request: Request }, next: () => Promise<Response>) => Promise<Response>}
+ */
+export function createAstroRateLimit(options) {
+  const limiter = createRateLimiter(options);
+  return async function astroRateLimitMiddleware(context, next) {
+    const decision = await limiter.check(context.request);
+    if (!decision.allowed) {
+      return new Response("Too Many Requests", {
+        status: 429,
+        headers: rateLimitHeaders(decision),
+      });
+    }
+    const response = await next();
+    for (const [key, value] of Object.entries(rateLimitHeaders(decision))) {
+      response.headers.set(key, value);
+    }
+    return response;
+  };
+}
+
+/**
+ * hono middleware adapter: returns `(c, next) => Promise<Response | void>`.
+ * Short-circuits with `c.text("Too Many Requests", 429)` when denied.
+ *
+ * ```ts
+ * import { createHonoRateLimit } from "mandrel-platform/edge-security/rate-limit.mjs";
+ * app.use("*", createHonoRateLimit({ limit: 100, windowMs: 60_000 }));
+ * ```
+ *
+ * @param {RateLimiterOptions} options
+ * @returns {(c: any, next: () => Promise<void>) => Promise<Response | void>}
+ */
+export function createHonoRateLimit(options) {
+  const limiter = createRateLimiter(options);
+  return async function honoRateLimitMiddleware(c, next) {
+    const decision = await limiter.check(c.req.raw);
+    const headers = rateLimitHeaders(decision);
+    if (!decision.allowed) {
+      return c.text("Too Many Requests", 429, headers);
+    }
+    await next();
+    for (const [key, value] of Object.entries(headers)) {
+      c.res.headers.set(key, value);
+    }
+  };
+}

package/config/edge-security/security-headers.mjs

@@ -0,0 +1,148 @@
+/**
+ * security-headers.mjs — the uniform security-header set every consumer was
+ * hand-rolling per env: CSP, HSTS, X-Frame-Options, X-Content-Type-Options,
+ * and Referrer-Policy.
+ *
+ * Ships two surfaces so both architectures inherit the same invariant:
+ *   - `buildSecurityHeaders(options)` — a framework-agnostic `Record<string,string>`
+ *     a consumer can spread onto any `Headers` / response (Astro, hono, plain
+ *     Workers `fetch`).
+ *   - `applySecurityHeaders(headers, options)` — mutates a `Headers` instance
+ *     in place (the common middleware path).
+ *
+ * Every header is parameterized but ships a safe default, so a consumer that
+ * passes `{}` still inherits a hardened baseline rather than re-deriving the
+ * directive strings.
+ */
+
+/**
+ * @typedef {Object} SecurityHeaderOptions
+ * @property {string | false} [contentSecurityPolicy]
+ *   The full CSP string. Defaults to a strict self-only policy. Pass `false`
+ *   to omit the CSP header entirely (e.g. when a CDN injects it).
+ * @property {Object} [hsts]
+ * @property {number} [hsts.maxAge=63072000]   `max-age` seconds (default 2y).
+ * @property {boolean} [hsts.includeSubDomains=true]
+ * @property {boolean} [hsts.preload=false]
+ * @property {false} [hsts.enabled]
+ *   Pass `{ enabled: false }`-style by setting `hsts: false` to omit HSTS
+ *   (e.g. on a non-HTTPS preview host).
+ * @property {string | false} [frameOptions="DENY"]
+ *   `X-Frame-Options`. `false` omits it (rely on CSP `frame-ancestors`).
+ * @property {string | false} [contentTypeOptions="nosniff"]
+ *   `X-Content-Type-Options`. `false` omits it.
+ * @property {string | false} [referrerPolicy="strict-origin-when-cross-origin"]
+ *   `Referrer-Policy`. `false` omits it.
+ */
+
+const DEFAULT_CSP = [
+  "default-src 'self'",
+  "base-uri 'self'",
+  "frame-ancestors 'none'",
+  "object-src 'none'",
+  "upgrade-insecure-requests",
+].join("; ");
+
+const DEFAULT_HSTS_MAX_AGE = 63072000; // 2 years
+
+/**
+ * Build the `Strict-Transport-Security` value from the hsts option, or `null`
+ * when HSTS is disabled.
+ * @param {SecurityHeaderOptions["hsts"] | false | undefined} hsts
+ * @returns {string | null}
+ */
+function buildHsts(hsts) {
+  if (hsts === false) {
+    return null;
+  }
+  const maxAge =
+    hsts && typeof hsts.maxAge === "number" ? hsts.maxAge : DEFAULT_HSTS_MAX_AGE;
+  const includeSubDomains = !hsts || hsts.includeSubDomains !== false;
+  const preload = Boolean(hsts && hsts.preload);
+
+  let value = `max-age=${maxAge}`;
+  if (includeSubDomains) {
+    value += "; includeSubDomains";
+  }
+  if (preload) {
+    value += "; preload";
+  }
+  return value;
+}
+
+/**
+ * Build the security-header set as a plain object. Keys are only present when
+ * the corresponding header is enabled (a disabled header is omitted, not set
+ * empty).
+ *
+ * @param {SecurityHeaderOptions} [options]
+ * @returns {Record<string, string>}
+ */
+export function buildSecurityHeaders(options = {}) {
+  /** @type {Record<string, string>} */
+  const headers = {};
+
+  const csp =
+    options.contentSecurityPolicy === undefined
+      ? DEFAULT_CSP
+      : options.contentSecurityPolicy;
+  if (csp !== false) {
+    headers["Content-Security-Policy"] = csp;
+  }
+
+  const hsts = buildHsts(options.hsts);
+  if (hsts !== null) {
+    headers["Strict-Transport-Security"] = hsts;
+  }
+
+  const frameOptions =
+    options.frameOptions === undefined ? "DENY" : options.frameOptions;
+  if (frameOptions !== false) {
+    headers["X-Frame-Options"] = frameOptions;
+  }
+
+  const contentTypeOptions =
+    options.contentTypeOptions === undefined
+      ? "nosniff"
+      : options.contentTypeOptions;
+  if (contentTypeOptions !== false) {
+    headers["X-Content-Type-Options"] = contentTypeOptions;
+  }
+
+  const referrerPolicy =
+    options.referrerPolicy === undefined
+      ? "strict-origin-when-cross-origin"
+      : options.referrerPolicy;
+  if (referrerPolicy !== false) {
+    headers["Referrer-Policy"] = referrerPolicy;
+  }
+
+  return headers;
+}
+
+/**
+ * Mutate a `Headers` instance in place with the security-header set. Returns
+ * the same instance for chaining.
+ *
+ * ```ts
+ * import { applySecurityHeaders } from "mandrel-platform/edge-security/security-headers.mjs";
+ * const response = await next();
+ * applySecurityHeaders(response.headers);
+ * return response;
+ * ```
+ *
+ * @param {Headers} headers
+ * @param {SecurityHeaderOptions} [options]
+ * @returns {Headers}
+ */
+export function applySecurityHeaders(headers, options = {}) {
+  if (!headers || typeof headers.set !== "function") {
+    throw new TypeError(
+      "[edge-security] applySecurityHeaders(headers): `headers` must be a Headers instance",
+    );
+  }
+  for (const [key, value] of Object.entries(buildSecurityHeaders(options))) {
+    headers.set(key, value);
+  }
+  return headers;
+}

package/config/knip.base.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://unpkg.com/knip@5/schema.json",
+  "ignoreBinaries": ["mandrel"],
+  "ignoreDependencies": ["mandrel-platform"],
+  "ignoreExportsUsedInFile": true,
+  "includeEntryExports": false
+}

package/config/lighthouse.base.json

@@ -0,0 +1,27 @@
+{
+  "_comment": "Shared Lighthouse CI base for mandrel-platform consumers. Lighthouse's `lighthouserc.json` has no whole-file `extends`, so this ships the shared `ci` block (collect settings + category assertions on the recommended preset). Consumers deep-merge it and add repo-specific `ci.collect.url` / `ci.collect.staticDistDir` and any per-repo assertion overrides (see README). Category score floors stay consumer-tunable.",
+  "ci": {
+    "collect": {
+      "numberOfRuns": 3,
+      "settings": {
+        "preset": "desktop"
+      }
+    },
+    "assert": {
+      "preset": "lighthouse:recommended",
+      "assertions": {
+        "categories:performance": ["error", { "minScore": 0.9 }],
+        "categories:accessibility": ["error", { "minScore": 0.9 }],
+        "categories:best-practices": ["error", { "minScore": 0.9 }],
+        "categories:seo": ["error", { "minScore": 0.9 }],
+        "uses-responsive-images": "off",
+        "unused-javascript": "warn",
+        "unused-css-rules": "warn",
+        "csp-xss": "warn"
+      }
+    },
+    "upload": {
+      "target": "temporary-public-storage"
+    }
+  }
+}

package/config/size-limit.base.json

@@ -0,0 +1,6 @@
+{
+  "_comment": "Shared size-limit check defaults for mandrel-platform consumers. size-limit's own config is a per-entry array whose paths/limits are inherently repo-specific, so this base ships the *shared check options* (gzip sizing, time budget off, import-cost mode) rather than entry paths. Consumers spread it into each entry of their `.size-limit.json` array: `[{ ...base, \"path\": \"dist/index.js\", \"limit\": \"10 kB\" }]` (see README). `path` and `limit` stay consumer-tunable.",
+  "gzip": true,
+  "brotli": false,
+  "running": false
+}

package/config/stryker.base.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://raw.githubusercontent.com/stryker-mutator/stryker-js/master/packages/api/schema/stryker-core.json",
+  "_comment": "Shared Stryker base for mandrel-platform consumers. Consumers extend via stryker.config.json's `extends` (string or array): { \"extends\": [\"mandrel-platform/stryker.base.json\"], \"testRunner\": \"vitest\", \"mutate\": [\"src/**/*.ts\"] }. testRunner, mutate, and per-repo thresholds stay consumer-tunable.",
+  "packageManager": "pnpm",
+  "reporters": ["html", "clear-text", "progress"],
+  "coverageAnalysis": "perTest",
+  "ignoreStatic": true,
+  "cleanTempDir": true,
+  "timeoutMS": 60000,
+  "thresholds": {
+    "high": 80,
+    "low": 60,
+    "break": 50
+  }
+}

package/package.json

@@ -1,8 +1,17 @@
 {
   "name": "mandrel-platform",
-  "version": "0.12.0",
+  "version": "0.14.2",
   "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dsj1984/mandrel-platform.git"
+  },
+  "homepage": "https://github.com/dsj1984/mandrel-platform#readme",
+  "bugs": {
+    "url": "https://github.com/dsj1984/mandrel-platform/issues"
+  },
+  "packageManager": "pnpm@11.5.2",
   "engines": {
     "node": "24.16.0",
     "pnpm": ">=11.5.2"
@@ -10,6 +19,13 @@
   "exports": {
     "./tsconfig.base.json": "./config/tsconfig.base.json",
     "./biome.base.json": "./config/biome.base.json",
+    "./knip.base.json": "./config/knip.base.json",
+    "./stryker.base.json": "./config/stryker.base.json",
+    "./dependency-cruiser.base.json": "./config/dependency-cruiser.base.json",
+    "./size-limit.base.json": "./config/size-limit.base.json",
+    "./lighthouse.base.json": "./config/lighthouse.base.json",
+    "./edge-security": "./config/edge-security/index.mjs",
+    "./edge-security/*": "./config/edge-security/*",
     "./scripts/*": "./scripts/*"
   },
   "files": [
@@ -18,6 +34,10 @@
     "scripts/",
     "templates/"
   ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "dependencies": {
     "mandrel": "^1.78.0"
   },
@@ -27,8 +47,9 @@
     "test": "node --test \"scripts/**/*.test.mjs\"",
     "platform:sync": "node scripts/platform-sync.mjs",
     "sync:commands": "node .agents/scripts/sync-claude-commands.js",
+    "prepare": "node .agents/scripts/sync-claude-commands.js",
     "bootstrap": "node .agents/scripts/bootstrap.js",
     "quality:preview": "node .agents/scripts/quality-preview.js --changed-since HEAD",
     "quality:watch": "node .agents/scripts/quality-watch.js"
   }
-}
+}