mandrel-platform 0.17.2 → 0.19.0

package/README.md

@@ -1,7 +1,34 @@
 # mandrel-platform
 
-Shared CI/deploy workflows, composite toolchain action, npm config package,
-Renovate preset, and operator runbook templates for the Mandrel platform.
+The **single source of truth (SSOT)** for CI/CD, security, and configuration
+across the Mandrel fleet. A consumer repo adopts this platform once and inherits
+a converged, hardened baseline — reusable GitHub Actions workflows, a composite
+toolchain action, importable config bases, guardrail scripts, edge-security
+middleware, a Renovate preset, and operator runbook templates — instead of
+hand-maintaining its own copies and drifting apart over time.
+
+## What's in scope
+
+| Pillar | What it provides |
+| ------ | ---------------- |
+| **Reusable workflows** | `workflow_call` CI, deploy, secret-scan, release, and CodeQL pipelines, consumed by tag/SHA pin. |
+| **Composite action** | `setup-toolchain` — pnpm + Node + frozen install in one step. |
+| **Config bases (npm)** | `extends`-able baselines: TypeScript, Biome, Knip, Stryker, commitlint, dependency-cruiser, size-limit, Lighthouse. |
+| **Edge-security middleware (npm)** | Per-env closed-allowlist CORS, security headers, and app-layer rate limiting for Astro + Hono. |
+| **Guardrail scripts (npm)** | Dependency-free policy checks: CVE gate, action-pin ratchet, coverage floor, destructive-migration guard, workflow-portability, required-contexts, docs-staleness. |
+| **Renovate preset** | Shared dependency-update policy, including auto-bumping this repo's own `uses:` pins. |
+| **Supply-chain config** | pnpm-native hardening fragment (`blockExoticSubdeps`, `trustPolicy`, 7-day `minimumReleaseAge`). |
+| **Adoption & drift control** | `platform-sync` (adopt/repair) plus a scheduled cross-consumer pin-drift dashboard and auto-repair-PR loop. |
+| **Runbook templates** | Copyable thin-stub operator runbooks that link back to the canonical process docs. |
+
+**Out of scope.** mandrel-platform is not an application and ships no runtime
+service — it deploys nothing of its own beyond its release train. Consumers keep
+every project-specific knob (entrypoints, budgets, score floors, deploy targets)
+local: the platform sets the floor, the consumer sets the ceiling. The `.agents/`
+tree in this repo is the Mandrel agent framework used to *develop* the platform
+(sourced from the separate `mandrel` CLI) — it is dev-time only and is **not**
+part of the published npm package, whose `files` allowlist ships only `config/`,
+`default.json`, `scripts/`, and `templates/`.
 
 **Docs:** [reusable-workflows.md](docs/reusable-workflows.md) (the `workflow_call`
 contract) · [decisions.md](docs/decisions.md) (decision log). Status, the
@@ -11,15 +38,24 @@ 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 `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).
+Five workflows expose a stable `workflow_call` contract and are consumed by
+tag/SHA pin. Configure your callers from
+**[docs/reusable-workflows.md](docs/reusable-workflows.md)** — the authoritative
+reference for 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.
+
+| Workflow | Purpose |
+| -------- | ------- |
+| [`pr-quality.yml`](docs/reusable-workflows.md#pr-qualityyml) | Tiered PR gate — lint/format → typecheck → unit → contract → e2e/smoke → migration-guard → security → osv-scan, each tier independently toggled, behind one `ci-required` aggregator. |
+| [`deploy-cloudflare.yml`](docs/reusable-workflows.md#deploy-cloudflareyml) | Defence-in-depth Cloudflare deploy with a frozen deploy-secret allowlist. |
+| [`secret-scan-push.yml`](docs/reusable-workflows.md#secret-scan-pushyml) | Full-history gitleaks secret scan on push to the default branch. |
+| [`release-automation.yml`](docs/reusable-workflows.md#release-automationyml) | Conventional-commit release lifecycle (version bump + `CHANGELOG.md` + tag) via release-please. |
+| [`codeql.yml`](docs/reusable-workflows.md#codeqlyml) | CodeQL SAST analysis — dual-mode: runs on this repo's push/PR/schedule **and** is `workflow_call`-consumable. |
+
+> `smoke-dispatch.yml` is a **platform-internal** cross-repo smoke trigger
+> (`push` / `workflow_dispatch`, not `workflow_call`). It appears in the
+> reference for completeness but is not part of the consumer caller surface.
 
 `release-automation.yml` extends the platform from CI/deploy into the **full
 release lifecycle**: a thin caller gets conventional-commit-driven version
@@ -119,34 +155,71 @@ mutate globs, bundle paths, score floors, and budgets — stays
 #### `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`):
+`mandrel-platform` dependency ignores). Knip has **no native top-level
+`extends`** to an npm-package config, so consumers import the base JSON in a
+`knip.config.ts` (or `.js`) module and spread it, layering their own `entry`
+/ `project` globs on top:
 
-```jsonc
-{
-  "extends": ["mandrel-platform/knip.base.json"],
-  "entry": ["src/index.ts", "scripts/*.ts"],
-  "project": ["src/**", "scripts/**"]
-}
+```ts
+// knip.config.ts — import the base and spread it
+import type { KnipConfig } from "knip";
+import base from "mandrel-platform/knip.base.json" with { type: "json" };
+
+const config: KnipConfig = {
+  ...base,
+  entry: ["src/index.ts", "scripts/*.ts"],
+  project: ["src/**", "scripts/**"],
+};
+
+export default config;
 ```
 
 #### `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`):
+`ignoreStatic`, a 60 s timeout, and high/low/break thresholds). Stryker's
+`extends` resolves a **local JSON path**, not an npm-package specifier, so
+the working mechanism is a `stryker.config.mjs` (or `.js` when
+`"type": "module"`) module that imports the base JSON and spreads it, then
+pins the test runner and mutate set:
 
-```jsonc
-{
-  "extends": ["mandrel-platform/stryker.base.json"],
-  "testRunner": "vitest",
-  "mutate": ["src/**/*.ts", "!src/**/*.test.ts"]
-}
+```js
+// stryker.config.mjs — import the base and spread it
+import base from "mandrel-platform/stryker.base.json" with { type: "json" };
+
+/** @type {import('@stryker-mutator/api/core').PartialStrykerOptions} */
+export default {
+  ...base,
+  testRunner: "vitest",
+  mutate: ["src/**/*.ts", "!src/**/*.test.ts"],
+};
+```
+
+#### `commitlint.base.mjs`
+
+Single-sources the conventional-commit **type-enum** — the eleven types
+(`feat`, `fix`, `perf`, `refactor`, `revert`, `docs`, `style`, `chore`,
+`test`, `build`, `ci`) documented in
+[`.agents/rules/git-conventions.md`](.agents/rules/git-conventions.md) — so
+consumers stop hand-copying the list into their own
+`commitlint.config.js`. Extends `@commitlint/config-conventional` for
+everything else (header casing/length, body/footer blank-line rules) and
+narrows `type-enum` to the fleet list. commitlint supports a native
+`extends`, so a consumer's local config reduces to the extend plus any
+repo-specific scope enforcement (`commitlint.config.js`):
+
+```js
+export default {
+  extends: ["mandrel-platform/commitlint.base.mjs"],
+  // repo-specific scope-enum, etc. — optional
+};
 ```
 
+Keep this base's `type-enum`, the git-conventions.md prose list, and
+`release-please-config.json`'s `changelog-sections` in sync when adding a
+type — all three must agree.
+
 #### `dependency-cruiser.base.json`
 
 Shared dependency-cruiser rule set (no-circular, no-orphans,
@@ -169,8 +242,9 @@ resolve the package export and add repo-specific rules
 
 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`:
+options* (gzip sizing, `running: false`). A JSON config can't `import` the
+base, so use a JS-module config (`.size-limit.js`) that imports the base
+JSON and spreads it into each entry:
 
 ```jsonc
 // .size-limit.js — spread the base into each entry
@@ -362,6 +436,78 @@ is detected by Renovate).
 
 ---
 
+### Guardrail & policy-check scripts
+
+Beyond the CVE gate, the package ships a set of **dependency-free guardrail
+lints** (`node`-only, nothing to install) that enforce cross-repo CI and
+security invariants. Several are already wired into the reusable workflows, so a
+consumer that adopts those inherits the check for free; each is also runnable
+standalone (`node node_modules/mandrel-platform/scripts/<name>.mjs`) or copyable
+into a repo's own `scripts/`.
+
+| Script | Enforces | Wired into |
+| ------ | -------- | ---------- |
+| `check-coverage-threshold.mjs` | Coverage floor (lines/statements/functions/branches) read from `coverage-summary.json`; threshold `0` disables the gate. | `pr-quality.yml` (unit tier) |
+| `check-destructive-migration.mjs` | Blocks `DROP` / `TRUNCATE` / `ALTER … DROP` (and Drizzle `.dropTable()`) in migration files unless a reviewer applies the override label. | `pr-quality.yml` (migration-guard tier, opt-in) |
+| `check-workflow-portability.mjs` | Catches cross-repo footguns in reusable workflows / composite actions: relative `uses:` paths, `${{ }}` in `workflow_call` input metadata, and lagging first-party pins. | `pr-quality.yml` + `ci.yml` |
+| `check-action-pins.mjs` | Ratchet requiring every third-party Action to be pinned to a full 40-char commit SHA (tag-swap defence); local and first-party refs are exempt. | `ci.yml` |
+| `check-required-contexts.mjs` | Validates that every branch-protection required check in `main-protection.json` maps to a real CI job — no phantom required checks. Also **warns** (never blocks) when the caller file / display `name:` / caller job id diverge from the canonical `ci.yml` / `CI` / `ci` triplet ([details](docs/reusable-workflows.md#canonical-caller-naming-the-ciyml--ci--ci-triplet)). | `ci.yml` |
+| `check-docs-staleness.mjs` | Lints markdown/JSON docs for known staleness patterns (stale URLs, expired dates, dead runbook paths); suppressible per-rule. | standalone |
+| `check-repo-settings.mjs` | Cross-consumer dashboard for the GitHub-side repo-settings baseline (merge methods, squash source, auto-merge, Actions default token permissions, PR-approval-by-Actions) — see below. | standalone / `platform-sync --check-settings` |
+
+> **`config/main-protection.schema.json`** is the JSON Schema for the
+> branch-protection contract (`docs/runbooks/main-protection.json`) — required
+> status checks, the aggregator job, upstream jobs, and enforcement flags.
+> `check-required-contexts.mjs` validates the contract against the actual
+> workflow job graph; see the
+> [branch-protection runbook](docs/runbooks/branch-protection-setup.md).
+
+> **`config/repo-settings.schema.json`** is the JSON Schema for the
+> repo-settings baseline contract (`docs/runbooks/repo-settings.json`),
+> sibling to `main-protection.schema.json` — merge methods, squash-commit
+> source, auto-merge/delete-branch-on-merge, Actions default workflow token
+> permissions, and whether Actions can approve pull requests. Fleet baseline
+> decided 2026-07-01 (see `docs/decisions.md`): squash-only merges, squash
+> source `PR_TITLE`/`PR_BODY`, auto-merge + delete-branch-on-merge on, Actions
+> default token permissions `read`, `can_approve_pull_request_reviews` off.
+>
+> **Because `squashMergeCommitMessage` is `PR_BODY`, PR templates must stay
+> commit-body-safe.** The PR description becomes the literal squash-commit
+> body on `main`, which `release-please` and `commitlint` then parse — a
+> template that injects checklist boilerplate, HTML comments, or
+> non-conventional-commit prose into that body will land in commit history and
+> can break changelog generation or commitlint's body rules. Keep PR templates
+> to short, commit-message-safe prose, or put checklists in sections authors
+> delete before merge.
+>
+> **Check + apply.** `scripts/check-repo-settings.mjs` is the GitHub-side
+> drift dashboard (mirrors `check-pin-drift.mjs`'s shape: data-driven consumer
+> registry — reuses `scripts/pin-drift-consumers.json` — injectable `gh`
+> runner, `--json`/`--strict`). `scripts/platform-sync.mjs` gained a
+> settings mode for the per-consumer check/apply flow:
+>
+> ```bash
+> # Report drift for one consumer against the baseline — never mutates, never
+> # fails the exit code unless the read itself errors (standing decision #10).
+> node scripts/platform-sync.mjs --check-settings --consumer-repo dsj1984/domio
+>
+> # Same read, then PATCH the drifted fields to match the baseline.
+> node scripts/platform-sync.mjs --apply-settings --consumer-repo dsj1984/domio
+>
+> # Preview what --apply-settings would PATCH without mutating anything.
+> node scripts/platform-sync.mjs --apply-settings --dry-run --consumer-repo dsj1984/domio
+> ```
+>
+> Both commands accept `--baseline <path>` (default:
+> `docs/runbooks/repo-settings.json`) and `--json` for a machine-readable
+> envelope. **Non-blocking by design** (standing decision #10, same posture as
+> the pin-drift dashboard and `check-ruleset.mjs`): drift is reported, not a
+> hard gate — it never fails CI on a consumer's `main`. Branch-protection
+> ruleset drift is out of scope here (see the companion `check-ruleset.mjs`
+> story); this contract covers repo-settings only.
+
+---
+
 ## Renovate preset
 
 The shared Renovate preset (`default.json`, also exposed at
@@ -464,12 +610,27 @@ reports `already in sync`):
    actions (`actions/checkout`, …) are left untouched. The trailing
    `# <ref>` comment is refreshed so the pin stays human-auditable and the
    Renovate auto-bump rule above can track it.
-2. **Materializes runbook reference stubs** (§2.2 *link, don't copy*). Copies
+2. **Checks CI-caller naming** (advisory only, Story #173). Reports whether
+   `.github/workflows/ci.yml` matches the canonical caller triplet — file
+   `ci.yml`, display name `CI`, caller job id `ci` (required context
+   `ci / ci-required`; see
+   [reusable-workflows.md § "Canonical caller naming"](docs/reusable-workflows.md#canonical-caller-naming-the-ciyml--ci--ci-triplet)).
+   Never renames or rewrites anything — a caller rename must land atomically
+   with its own branch-protection ruleset context update, which is a
+   deliberate per-consumer Story, not an automatic sync side-effect.
+3. **Materializes runbook reference stubs** (§2.2 *link, don't copy*). Copies
    the thin stubs from `templates/runbooks/` into the consumer's
    `docs/runbooks/` **only when absent** — an already-adopted stub is skipped,
    and a full local copy (no stub marker) is surfaced as a warning to
    reconcile by hand, never silently overwritten.
-3. **Reconciles `extends`.** Prepends `github>dsj1984/mandrel-platform` to the
+4. **Materializes workflow caller templates.** Copies canonical callers from
+   `templates/workflows/` (e.g. `deploy-staging.yml`, the one-paved-road
+   `workflow_run` caller for `deploy-cloudflare.yml`'s CI-green guard — see
+   [`docs/reusable-workflows.md`](docs/reusable-workflows.md#deploy-cloudflareyml))
+   into the consumer's `.github/workflows/` — same link-don't-copy semantics:
+   only when absent, and a hand-authored file without the template marker is
+   surfaced as a warning rather than overwritten.
+5. **Reconciles `extends`.** Prepends `github>dsj1984/mandrel-platform` to the
    consumer's Renovate `extends` and `mandrel-platform/tsconfig.base.json` to
    its `tsconfig.json` `extends`. The SSOT goes first so the consumer's own
    later entries continue to override it.
@@ -481,16 +642,74 @@ result envelope on stdout).
 
 ---
 
+## Drift control & auto-repair
+
+The platform actively keeps consumers converged rather than trusting them to
+stay in sync by hand. Two scheduled workflows run this loop against the consumer
+registry in
+[`scripts/pin-drift-consumers.json`](scripts/pin-drift-consumers.json):
+
+- **Detect** — [`pin-drift.yml`](.github/workflows/pin-drift.yml) (weekly +
+  `workflow_dispatch`) runs `check-pin-drift.mjs`, a cross-consumer dashboard
+  that flags split pins (multiple mandrel-platform SHAs in one repo), release
+  lag, npm lag, and npm-vs-workflow surface skew. Advisory by default; `--strict`
+  turns drift into a failure. See the
+  [pin-drift dashboard runbook](docs/runbooks/pin-drift-dashboard.md).
+- **Repair** — [`platform-sync-repair.yml`](.github/workflows/platform-sync-repair.yml)
+  runs `platform-repair.mjs`, which clones each drifting consumer, runs
+  `platform-sync`, and opens (or updates) an **idempotent** repair PR on a stable
+  head branch. Requires a fine-grained `PIN_REPAIR_TOKEN` scoped to the consumer
+  repos' contents + pull-requests.
+
+`update-semgrep-rules.mjs` is a related maintenance script that vendors Semgrep's
+`p/default` ruleset — filtered to the languages actually in-repo — into
+`.semgrep/rules.json` against a pinned Semgrep version, so the SAST step in
+`pr-quality.yml` scans deterministically. Run it deliberately when bumping the
+ruleset, not on every CI run.
+
+---
+
+## Runbook templates
+
+`templates/runbooks/` ships **copyable thin-stub** operator runbooks — one per
+canonical runbook in [`docs/runbooks/`](docs/runbooks). The adoption model is
+*link, don't copy*: each stub links to the canonical process doc (the source of
+truth) and carries only `<PLACEHOLDER>` slots for project-specific values, so an
+upstream process change is picked up by re-reading the link rather than
+re-authoring the stub. `platform-sync` materializes them for you — link-only, and
+never clobbering a stub you have already filled in.
+
+| Stub | Canonical runbook |
+| ---- | ----------------- |
+| `deploy-promotion.md` | staging → production promotion |
+| `incident-response.md` | severity, escalation, postmortem |
+| `database-backup-restore.md` | backup, PITR, restore/rollback |
+| `observability.md` | logs, Sentry, uptime, metrics |
+| `post-deploy-smoke.md` | boot-smoke gate + diagnosis |
+| `environments-provisioning.md` | env model + provisioning steps |
+| `dependency-update.md` | Renovate, CVE gate, catalog |
+| `branch-protection-setup.md` | aggregator required-check model |
+
+---
+
 ## Development
 
 ```bash
-# Install dependencies
+# Install dependencies (packageManager: pnpm@11.5.2)
 pnpm install
 
 # Bootstrap agent scaffolding
 pnpm run bootstrap
+
+# Run the guardrail-script test suite (node:test)
+pnpm test
 ```
 
+Every script under `scripts/` (the guardrail lints, `platform-sync`,
+`platform-repair`, `update-semgrep-rules`) carries a colocated `*.test.mjs`
+suite run by `pnpm test`. The `.agents/` tree is the Mandrel agent framework this
+repo is developed with — dev-time only, and not shipped in the npm package.
+
 ---
 
 ## Package exports
@@ -501,6 +720,7 @@ pnpm run bootstrap
 | `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/commitlint.base.mjs`          | `config/commitlint.base.mjs`          |
 | `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`         |

package/config/commitlint.base.mjs

@@ -0,0 +1,36 @@
+/**
+ * commitlint.base.mjs — shared commitlint config for mandrel-platform
+ * consumers.
+ *
+ * Single-sources the conventional-commit type-enum from
+ * `.agents/rules/git-conventions.md` (§ Conventional Commits) so the eleven
+ * allowed types live in exactly one place instead of being hand-copied into
+ * each consumer's own `commitlint.config.js`. Keep this list, the
+ * git-conventions.md prose list, and `release-please-config.json`'s
+ * `changelog-sections` in sync when adding a type — all three must agree.
+ *
+ * Extends `@commitlint/config-conventional` for everything else (header
+ * casing/length, body/footer leading-blank-line, etc.) and narrows
+ * `type-enum` to the fleet's eleven types.
+ */
+
+const TYPE_ENUM = [
+  "feat",
+  "fix",
+  "perf",
+  "refactor",
+  "revert",
+  "docs",
+  "style",
+  "chore",
+  "test",
+  "build",
+  "ci",
+];
+
+export default {
+  extends: ["@commitlint/config-conventional"],
+  rules: {
+    "type-enum": [2, "always", TYPE_ENUM],
+  },
+};

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

@@ -7,11 +7,22 @@
  * 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
+ * logic. The default store is a bounded in-memory `Map` suitable for a
  * single-isolate dev / small deployment; production multi-isolate consumers
  * pass a shared store.
  */
 
+/**
+ * Max number of live buckets the default in-memory store retains before it
+ * evicts. A stream of distinct keys (e.g. a rotating-IP flood, or a spoofed
+ * forwarded header — see `defaultKeyExtractor`) would otherwise grow the
+ * backing `Map` without bound. Once the store holds this many buckets, the
+ * least-recently-touched entry is evicted (LRU) on the next `set`. The value
+ * is large enough to be a non-event for legitimate single-isolate traffic
+ * while capping worst-case memory.
+ */
+const DEFAULT_MAX_BUCKETS = 10_000;
+
 /**
  * @typedef {Object} RateLimitStore
  * @property {(key: string) => Promise<{ count: number, resetAt: number } | null> | { count: number, resetAt: number } | null} get
@@ -19,14 +30,45 @@
  */
 
 /**
- * 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.
+ * In-memory fixed-window store. Bounded two ways so a stream of distinct keys
+ * cannot grow the backing `Map` without bound:
+ *
+ *  1. **Expired-bucket sweep.** `get` evicts a bucket the moment its window has
+ *     elapsed, and `set` amortizes a full sweep of expired buckets across
+ *     writes. Keys that stop being seen do not linger past their window.
+ *  2. **Max-size LRU cap.** The `Map` retains at most `maxBuckets` live
+ *     entries. When a `set` would exceed the cap after sweeping, the
+ *     least-recently-touched entry is evicted first (a `Map` preserves
+ *     insertion order, and every touch re-inserts, so the first key is the
+ *     LRU one). This caps worst-case memory even under an active flood of
+ *     keys that have not yet expired.
+ *
+ * NOT shared across isolates — fine for dev / single instance; pass a
+ * KV-backed store in production.
+ *
+ * @param {{ maxBuckets?: number }} [options]
+ *   Optional cap override. Defaults to {@link DEFAULT_MAX_BUCKETS}. Callers
+ *   that pass no argument get the default — the zero-arg signature is
+ *   preserved for existing consumers.
  * @returns {RateLimitStore}
  */
-export function createMemoryStore() {
+export function createMemoryStore(options) {
+  const maxBuckets =
+    options && typeof options.maxBuckets === "number" && options.maxBuckets >= 1
+      ? Math.floor(options.maxBuckets)
+      : DEFAULT_MAX_BUCKETS;
   /** @type {Map<string, { count: number, resetAt: number }>} */
   const buckets = new Map();
+
+  /** Evict every bucket whose window has already elapsed. */
+  function sweepExpired(now) {
+    for (const [key, bucket] of buckets) {
+      if (bucket.resetAt <= now) {
+        buckets.delete(key);
+      }
+    }
+  }
+
   return {
     get(key) {
       const bucket = buckets.get(key);
@@ -37,10 +79,31 @@ export function createMemoryStore() {
         buckets.delete(key);
         return null;
       }
+      // Re-insert so the touched key moves to the most-recently-used end,
+      // keeping the LRU eviction order in `set` honest.
+      buckets.delete(key);
+      buckets.set(key, bucket);
       return bucket;
     },
     set(key, value) {
+      const now = Date.now();
+      // A re-`set` of an existing key must not double-count toward the cap;
+      // drop it first so the size check and LRU ordering stay correct.
+      buckets.delete(key);
       buckets.set(key, value);
+      if (buckets.size > maxBuckets) {
+        // Cheap first: reclaim anything already expired.
+        sweepExpired(now);
+      }
+      // Still over cap (an active flood of un-expired keys) — evict LRU
+      // entries (insertion-order-oldest) until we are back within bound.
+      while (buckets.size > maxBuckets) {
+        const oldest = buckets.keys().next().value;
+        if (oldest === undefined) {
+          break;
+        }
+        buckets.delete(oldest);
+      }
     },
   };
 }
@@ -50,10 +113,12 @@ export function createMemoryStore() {
  * @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.
+ *   Derives the rate-limit bucket key from the request. Defaults to
+ *   {@link defaultKeyExtractor}, which trusts only `CF-Connecting-IP` and
+ *   falls back to a constant shared bucket — it does NOT read
+ *   `X-Forwarded-For`, which is client-spoofable. See that function's doc for
+ *   the trust boundary and how to opt back into `X-Forwarded-For` when your
+ *   own edge is known to overwrite it.
  * @property {RateLimitStore} [store] Defaults to `createMemoryStore()`.
  */
 
@@ -67,24 +132,42 @@ export function createMemoryStore() {
  */
 
 /**
- * Default key extractor: client IP, failing closed to a shared bucket.
+ * Default key extractor: the Cloudflare-supplied client IP, failing closed to
+ * a shared bucket.
+ *
+ * **Trust boundary.** Identity is derived only from `CF-Connecting-IP`, a
+ * header Cloudflare's edge sets (and overwrites) from the terminating TCP
+ * connection — a client cannot forge it. `X-Forwarded-For` is deliberately
+ * NOT consulted: any client can send an arbitrary `X-Forwarded-For`, so
+ * keying off it lets an attacker mint a fresh bucket per request (defeating
+ * the limit) or impersonate another client's bucket. When no trusted client
+ * IP is present, we fail *closed* into one shared `"anonymous"` bucket rather
+ * than handing every request its own unlimited allowance.
+ *
+ * If your own reverse proxy is known to strip inbound `X-Forwarded-For` and
+ * append the real client, opt back in explicitly with a custom
+ * `keyExtractor`, e.g.:
+ *
+ * ```js
+ * createRateLimiter({
+ *   limit, windowMs,
+ *   keyExtractor: (req) =>
+ *     req.headers.get("CF-Connecting-IP") ??
+ *     req.headers.get("X-Forwarded-For")?.split(",").pop()?.trim() ??
+ *     "anonymous",
+ * });
+ * ```
+ *
  * @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();
-    }
+    return cf.trim();
   }
-  // No identifiable client — fail closed into one shared bucket rather than
-  // handing every anonymous request its own unlimited allowance.
+  // No trusted client identity. `X-Forwarded-For` is intentionally ignored
+  // here because it is client-spoofable; fail closed into one shared bucket.
   return "anonymous";
 }
 

package/config/repo-settings.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/dsj1984/mandrel-platform/blob/main/config/repo-settings.schema.json",
+  "title": "Repository Settings Baseline Contract",
+  "description": "Defines the GitHub-side repository settings baseline (merge methods, squash-commit source, auto-merge, Actions default token permissions, PR-approval-by-Actions) the fleet must converge on. Validated by scripts/check-repo-settings.mjs against each consumer's live settings (gh api repos/{owner}/{repo}); applied where safe by scripts/platform-sync.mjs --apply-settings. Non-blocking by design (standing decision #10) — drift is reported, never a hard gate on a consumer's main.",
+  "type": "object",
+  "required": [
+    "allowSquashMerge",
+    "allowMergeCommit",
+    "allowRebaseMerge",
+    "squashMergeCommitTitle",
+    "squashMergeCommitMessage",
+    "deleteBranchOnMerge",
+    "allowAutoMerge",
+    "actionsDefaultWorkflowPermissions",
+    "actionsCanApprovePullRequestReviews"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference."
+    },
+    "allowSquashMerge": {
+      "type": "boolean",
+      "description": "Whether squash merging is allowed. The fleet baseline requires this true (squash-only).",
+      "default": true
+    },
+    "allowMergeCommit": {
+      "type": "boolean",
+      "description": "Whether merge commits are allowed. The fleet baseline requires this false (squash-only).",
+      "default": false
+    },
+    "allowRebaseMerge": {
+      "type": "boolean",
+      "description": "Whether rebase merging is allowed. The fleet baseline requires this false (squash-only).",
+      "default": false
+    },
+    "squashMergeCommitTitle": {
+      "type": "string",
+      "description": "Source of the squash-commit title.",
+      "enum": ["PR_TITLE", "COMMIT_OR_PR_TITLE"],
+      "default": "PR_TITLE"
+    },
+    "squashMergeCommitMessage": {
+      "type": "string",
+      "description": "Source of the squash-commit message body. The fleet baseline requires PR_BODY — commits landing on main feed release-please + commitlint, so the PR body becomes the literal commit body and must stay commit-body-safe (see the _note below).",
+      "enum": ["PR_BODY", "COMMIT_MESSAGES", "BLANK"],
+      "default": "PR_BODY"
+    },
+    "deleteBranchOnMerge": {
+      "type": "boolean",
+      "description": "Whether head branches are auto-deleted after a merge.",
+      "default": true
+    },
+    "allowAutoMerge": {
+      "type": "boolean",
+      "description": "Whether GitHub's native auto-merge feature is enabled for the repo.",
+      "default": true
+    },
+    "actionsDefaultWorkflowPermissions": {
+      "type": "string",
+      "description": "Default GITHUB_TOKEN permissions granted to Actions workflows. The fleet baseline requires 'read' (least-privilege) — a workflow that needs write scopes requests it explicitly via a `permissions:` block.",
+      "enum": ["read", "write"],
+      "default": "read"
+    },
+    "actionsCanApprovePullRequestReviews": {
+      "type": "boolean",
+      "description": "Whether GitHub Actions workflows are permitted to approve pull requests. The fleet baseline requires this false — an automated actor approving its own (or any) PR is a bypass of human review, not a feature.",
+      "default": false
+    },
+    "_note": {
+      "type": "string",
+      "description": "Human-readable note for maintainers."
+    }
+  },
+  "_note": "PR templates must stay commit-body-safe: with squashMergeCommitMessage=PR_BODY, the full PR description becomes the literal squash-commit body on main, which release-please and commitlint then parse. A PR template that injects checklist boilerplate, HTML comments, or non-conventional-commit prose into that body will land in the commit history and can break release-please's changelog generation or commitlint's body-line rules. Keep PR templates short, commit-message-safe prose, or move checklists into template sections that authors delete before merge."
+}