mandrel-platform 0.18.0 → 0.19.0

package/README.md

@@ -155,32 +155,45 @@ 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`
@@ -229,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

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/default.json

@@ -80,34 +80,19 @@
       "groupSlug": "clerk"
     },
     {
-      "description": "Keep .nvmrc and engines.node in lockstep — bump both when Node.js advances",
+      "description": "Keep .nvmrc and engines.node in lockstep — Renovate's nvm manager bumps .nvmrc; group the matching engines.node bump into the same PR. NOTE: automatically rewriting engines.node requires a postUpgradeTasks command, which hosted Mend (the Renovate app) DISABLES for security. Self-hosted Renovate runners must allowlist the command via allowedCommands; on hosted Mend, bump engines.node by hand in the same PR — see docs/runbooks/dependency-update.md.",
       "matchManagers": ["nvm"],
       "matchPackageNames": ["node"],
-      "postUpdateOptions": ["nodeToolchainFile"],
-      "postUpgradeTasks": {
-        "commands": [
-          "node -e \"const fs=require('fs'),path=require('path');const ver=fs.readFileSync('.nvmrc','utf8').trim().replace(/^v/,'');function walk(d){return fs.readdirSync(d,{withFileTypes:true}).flatMap(e=>{const p=path.join(d,e.name);return e.isDirectory()&&e.name!=='node_modules'?walk(p):e.isFile()&&e.name==='package.json'?[p]:[]});}walk('.').forEach(f=>{try{const pkg=JSON.parse(fs.readFileSync(f,'utf8'));if(pkg.engines&&pkg.engines.node){pkg.engines.node=ver;fs.writeFileSync(f,JSON.stringify(pkg,null,2)+'\\n','utf8');console.log('Updated engines.node to '+ver+' in '+f);}}catch(e){}});\""
-        ],
-        "fileFilters": ["**/.nvmrc", "**/package.json"]
-      },
       "automerge": true,
       "automergeType": "pr",
       "platformAutomerge": true
     },
     {
-      "description": "Advance wrangler compatibility_date to today when wrangler is bumped",
+      "description": "Group wrangler bumps so the wrangler compatibility_date can be advanced alongside. NOTE: automatically rewriting compatibility_date requires a postUpgradeTasks command, which hosted Mend (the Renovate app) DISABLES for security. Self-hosted Renovate runners must allowlist the command via allowedCommands; on hosted Mend, advance compatibility_date by hand in the same PR — see docs/runbooks/dependency-update.md.",
       "matchManagers": ["npm"],
       "matchPackageNames": ["wrangler"],
-      "postUpgradeTasks": {
-        "commands": [
-          "node -e \"const fs=require('fs'),path=require('path');function walk(d){return fs.readdirSync(d,{withFileTypes:true}).flatMap(e=>{const p=path.join(d,e.name);return e.isDirectory()&&e.name!=='node_modules'?walk(p):e.isFile()&&/wrangler\\.(json|jsonc|toml)$/.test(e.name)?[p]:[]});}const today=new Date().toISOString().slice(0,10);walk('.').forEach(f=>{let c=fs.readFileSync(f,'utf8');const u=c.replace(/compatibility_date\\s*=\\s*\\\"[0-9-]+\\\"/g,'compatibility_date = \\\"'+today+'\\\"').replace(/\\\"compatibility_date\\\"\\s*:\\s*\\\"[0-9-]+\\\"/g,'\\\"compatibility_date\\\": \\\"'+today+'\\\"');if(u!==c){fs.writeFileSync(f,u,'utf8');console.log('Updated compatibility_date in '+f);}});\""
-        ],
-        "fileFilters": [
-          "**/wrangler.json",
-          "**/wrangler.jsonc",
-          "**/wrangler.toml"
-        ]
-      }
+      "groupName": "wrangler",
+      "groupSlug": "wrangler"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
   "license": "MIT",
   "repository": {