create-ailk 0.24.0 → 0.26.0

package/templates/apps/api/src/middleware/rate-limit.ts

@@ -1,983 +0,0 @@
-/**
- * Per-IP rate limit middleware for anonymous write routes.
- *
- * SINGLE-REPLICA CAVEAT: the memory store below keeps an in-process Map of
- * request counts. Each Fastify instance maintains its own bucket state. On a
- * deployment with no database (or `AILK_RATE_LIMIT_STORE=memory`), an
- * attacker can issue up to N × perIpPerMinute requests per minute per IP,
- * where N is the replica/isolate count.
- *
- * SHARED STORE (#5040): on a deployment with a database, every registration
- * defaults to counting in `rate_limit_counters` instead (D4), so one
- * visitor's limit holds across every concurrent isolate. See
- * `apps/api/src/lib/rate-limit-store.ts` for the store seam and
- * `docs/specs/5040-the-api-s-rate-limiter-spec.md` D11 for the full list of
- * what this protects against and what it does not — in short: it stops one
- * identity from exceeding its ceiling by spreading requests over isolates,
- * but a caller that mints a fresh identity per request (a forged
- * `x-forwarded-for` the edge passes through unmodified) still gets a fresh
- * bucket every time, in either store.
- *
- * Cleanup strategy: evict stale buckets on every 429 emission and every 100
- * allowed requests (bounded, O(n) over bucket count — negligible for typical
- * IP cardinality). No setInterval is started until the middleware is registered,
- * keeping the module import-side-effect-free.
- *
- * Entry-count cap (#5111/#4780 AC-3): the eviction above is time-based only —
- * it removes buckets whose WINDOW has expired, never bounding the TOTAL
- * distinct-identity count within a still-open window. Once `trustProxy: true`
- * made `req.ip` a caller-influenced value (see below), a caller minting a
- * fresh identity on every request (e.g. varying `X-Forwarded-For`) can grow
- * `buckets` without bound for the lifetime of one isolate. `MAX_BUCKETS`
- * caps total entries independent of the time-based eviction: once at
- * capacity, a genuinely new identity evicts the single oldest-inserted entry
- * (`Map` iteration order is insertion order) before inserting itself — O(1)
- * amortized, no behavior change for any caller under the cap. The database
- * store has no such cap: it relies entirely on the sweep (D6) to bound its
- * row count.
- *
- * Trust-proxy boundary: this middleware reads req.ip, which Fastify populates
- * from the socket address and any trusted proxy headers (X-Forwarded-For) per
- * the server's own trustProxy config. This middleware does NOT parse
- * X-Forwarded-For itself. `server.ts` enables `trustProxy: true`, so req.ip
- * resolves to the leftmost (originating) address of a multi-hop
- * X-Forwarded-For chain.
- *
- * Consumer double-hop caveat (#4730): when a consumer site's own Next.js
- * server action calls one of the rate-limited scopes below (flows/leads/aeo/
- * schedule) on a visitor's behalf, `req.ip` would otherwise reflect the
- * calling web function's shared egress IP, not the visitor's — every visitor
- * of that consumer site would collapse into one bucket. The fix lives on the
- * caller's side: `@working-theory/api-client`'s `post()`/`get()` accept an
- * `init.headers` override, and the flows server action
- * (`apps/web/app/[locale]/flows/[slug]/flow.actions.ts`) forwards the
- * visitor's own `x-forwarded-for` (read from ITS OWN incoming request via
- * Next's `headers()`) as an explicit `x-forwarded-for` header on the outbound
- * call — appending to, not replacing, whatever hop this API's own edge adds,
- * so trustProxy's leftmost-address resolution still lands on the real
- * visitor.
- *
- * Per-visitor lead writes from a keyed spoke (#7394): a spoke's lead writes
- * carry the visitor's IP in `x-ailk-visitor-ip`, which this middleware
- * believes only alongside a hub-issued key in `x-ailk-visitor-forward-key`,
- * and only on the `FORWARDED_VISITOR_ROUTES`: the three lead writes, and
- * since #7633 the two schedule calls a site's same-origin relay forwards
- * (#7644) — `GET /v1/schedule/availability` and `POST /v1/schedule/book` — and
- * since #7479 the three listing-draft calls a spoke makes for its applicant
- * (`POST /v1/project-listings`, `PATCH /v1/project-listings/drafts/:id`,
- * `POST /v1/project-listings/drafts/:id/submit`), and since #8848 the open
- * file read (`GET /v1/deliverables/open/:slug`). The global limiter (`server.ts`) passes the hub's digests, so a listed call is
- * counted per visitor there; a scope's own limiter does so only when its
- * registration passes `trustedKeyDigests` too, as the leads and schedule
- * scopes do. A believed visitor is
- * counted as `v<n>,<ip>` (n = the key's position in
- * `AILK_VISITOR_FORWARD_KEYS`), and every such request also counts against
- * its key's own `key,<n>` bucket. Both forms contain a comma, which `req.ip`
- * never does, so no unkeyed caller can reach either bucket. Every other
- * request keys on `req.ip`, as before. Spec:
- * docs/specs/7394-the-leads-rate-limit-scope-spec.md.
- *
- * Per-site-key sign-up evidence (#8805): the web's server reads
- * `GET /v1/consent/sign-up` on every sign-up, and every web instance behind
- * one egress address shared one per-IP bucket, which an anonymous caller
- * spoofing that address's `X-Forwarded-For` could fill. A registration that
- * passes `siteKeyOf` (built by `siteKeyReader`) counts a request on one of
- * the `SITE_KEYED_ROUTES` that presents a VERIFIED site key
- * (`x-ailk-spoke-key`, the key the web's api-client already sends) against
- * that key's own `site,<spokeId>` bucket and the scope's per-key ceiling
- * only — never an IP bucket. No other identity starts with `site,` (`req.ip`
- * holds no comma, a forwarded visitor is `v<n>,<ip>`), so no unkeyed caller
- * can reach it. An invalid or absent key, or a verification that fails or
- * outlasts `SITE_KEY_TIMEOUT_MS`, is counted on `req.ip` as before. The key changes
- * the request's rate-limit identity and nothing else: the route still serves
- * the deployment's own site workspace.
- *
- * Scope namespace and env limit (#7394): a registration with a `scope` keys
- * its buckets as `<scope>|<identity>`, so its count is not shared with any
- * other registration, and reads its limits from
- * `AILK_RATE_LIMIT_<SCOPE>_PER_MINUTE` / `..._PER_KEY_PER_MINUTE`, which win
- * over the code values. A registration with no `scope` behaves as it did.
- */
-
-import { createHash, timingSafeEqual } from "node:crypto";
-import { isIP } from "node:net";
-
-import { getClock } from "@working-theory/common";
-import type {
-  FastifyRequest,
-  FastifyReply,
-  FastifyPluginCallback,
-  FastifyBaseLogger,
-} from "fastify";
-
-import { prisma } from "../lib/prisma.js";
-import {
-  createDatabaseRateLimitStore,
-  resolveRateLimitStoreKind,
-  type RateLimitBucket,
-  type RateLimitStore,
-} from "../lib/rate-limit-store.js";
-
-export type RateLimitOptions = {
-  /**
-   * Requests allowed per IP per window.
-   * Default: AILK_RATE_LIMIT_PER_IP_PER_MINUTE env var ?? 20 (#4730 — sized
-   * to cover a full flow: the longest shipped flow, ailk-founder-diagnostic,
-   * is 13 steps + 1 GET, plus headroom for an invisible aeo_score
-   * submission and one legitimate resubmit; see apps/api/src/routes/flows/
-   * README.md).
-   */
-  perIpPerMinute?: number;
-  /** Window duration in milliseconds. Default: 60_000 */
-  windowMs?: number;
-  /**
-   * Extract the IP key from a request. Default: the identity
-   * `resolveRateLimitIdentity` returns, which is `req.ip` unless
-   * `trustedKeyDigests` is non-empty. A caller-supplied function wins.
-   */
-  ipFromRequest?: (req: FastifyRequest) => string;
-  /**
-   * Maximum distinct entries `buckets` may hold at once, independent of the
-   * time-based eviction. Default: `MAX_BUCKETS`. Exposed for tests only —
-   * no production caller overrides this. Has no effect on the database
-   * store, which has no entry cap of its own (D6's sweep bounds it instead).
-   */
-  maxBuckets?: number;
-  /**
-   * Bucket namespace (#7394). With one, buckets are keyed
-   * `<scope>|<identity>` and the limits are read from
-   * `AILK_RATE_LIMIT_<SCOPE>_PER_MINUTE` and
-   * `AILK_RATE_LIMIT_<SCOPE>_PER_KEY_PER_MINUTE` first. Must match
-   * `/^[a-z][a-z0-9]*$/`. Without one, buckets are keyed on the bare identity.
-   */
-  scope?: string;
-  /**
-   * The hub's forwarding-key digests, from `buildTrustedKeyDigests` (#7394).
-   * Default: `[]`, which believes no forwarded visitor. A non-empty list
-   * needs a `scope`.
-   */
-  trustedKeyDigests?: readonly (Buffer | null)[];
-  /**
-   * Requests allowed per forwarding key per window, across all of that key's
-   * visitors (#7394). Default: 300.
-   */
-  perKeyPerMinute?: number;
-  /**
-   * The verified site key a request presents, as its spoke id, or `null`
-   * (#8805). Build it with `siteKeyReader`. A request it names is counted
-   * against `<scope>|site,<spokeId>` and `perKeyPerMinute` only, never an IP
-   * bucket. Needs a `scope`.
-   */
-  siteKeyOf?: (req: FastifyRequest) => Promise<string | null>;
-  /**
-   * Override the process-default store (#5040 D4). Test-only, like
-   * `maxBuckets` — no production caller overrides this.
-   */
-  store?: RateLimitStore;
-  /**
-   * Override `STORE_TIMEOUT_MS` (#5040 D5). Test-only.
-   */
-  storeTimeoutMs?: number;
-};
-
-const RATE_LIMITED = "rate_limited" as const;
-
-/**
- * The pre-#4730 per-scope default (10/min) — leads/aeo/schedule's own
- * `perIpPerMinute` (#5111, DEF-004). `flowsScope` keeps the wider
- * env-var-driven default below; it is NOT built from this constant.
- */
-export const DEFAULT_PER_IP_PER_MINUTE_STRICT = 10;
-
-/**
- * Default cap on `buckets`' total distinct entries (#5111/#4780 AC-3). Sized
- * generously above any plausible legitimate per-minute visitor cardinality
- * for this product's anonymous scopes, while still bounding worst-case
- * memory growth under an unbounded-identity-churn attack.
- */
-export const MAX_BUCKETS = 10_000;
-
-/**
- * The schedule scope's per-forwarding-key ceiling (#7633): well below the
- * lead routes' 300, because a booking is a real booking at the provider.
- * `AILK_RATE_LIMIT_SCHEDULE_PER_KEY_PER_MINUTE` overrides it.
- */
-export const DEFAULT_SCHEDULE_PER_KEY_PER_MINUTE = 60;
-
-/**
- * The sign-up evidence read's per-site-key ceiling (#8805). The web's cache
- * keeps each instance to about one read a minute per enabled locale, so this
- * covers many instances of one site at once.
- * `AILK_RATE_LIMIT_SIGNUPEVIDENCE_PER_KEY_PER_MINUTE` overrides it.
- */
-export const DEFAULT_SIGNUPEVIDENCE_PER_KEY_PER_MINUTE = 120;
-
-/**
- * How long a database-store call may run before the middleware falls back to
- * the memory store for that request (#5040 D5). `RateLimitOptions.storeTimeoutMs`
- * overrides it, test-only.
- */
-export const STORE_TIMEOUT_MS = 1_000;
-
-/** How often a `rate_limit_store_fallback` warn line may be logged (D5). */
-const FALLBACK_WARN_THROTTLE_MS = 60_000;
-
-/**
- * The only (method, route) pairs on which a forwarded visitor IP is believed
- * (#7394 DD-2): the three lead writes, the two schedule calls a site's
- * relay forwards on its visitors' behalf (#7633, the relay's security
- * review), the two consent writes (#8438) and the three listing-draft calls
- * (#7479). Matched against `req.method` and `req.routeOptions.url`, the
- * registered route pattern.
- */
-export const FORWARDED_VISITOR_ROUTES: readonly Readonly<{
-  method: "GET" | "POST" | "PATCH";
-  url: string;
-}>[] = [
-  { method: "POST", url: "/v1/leads/submit" },
-  { method: "POST", url: "/v1/leads/subscribe" },
-  { method: "POST", url: "/v1/leads/callback" },
-  { method: "GET", url: "/v1/schedule/availability" },
-  { method: "POST", url: "/v1/schedule/book" },
-  // #8438 D5/D9 — the cookie banner's log and the unsubscribe landing: a
-  // site's server forwards each visitor's IP, so one spoke's visitors are
-  // counted one by one rather than in one bucket keyed on its egress IP.
-  { method: "POST", url: "/v1/consent/cookie" },
-  { method: "POST", url: "/v1/consent/unsubscribe" },
-  // #7479 — the listing-draft lifecycle a spoke's Server Action calls on its
-  // applicant's behalf (`start`, the draft `patch`, `submit`), in `leadsScope`.
-  { method: "POST", url: "/v1/project-listings" },
-  { method: "PATCH", url: "/v1/project-listings/drafts/:id" },
-  { method: "POST", url: "/v1/project-listings/drafts/:id/submit" },
-  // #8848 D5 — an ungated file's bytes, which a site's own route handler
-  // reads for its visitor (`/reports/<slug>/file`), in `deliverableopen`.
-  { method: "GET", url: "/v1/deliverables/open/:slug" },
-];
-
-/**
- * The only (method, route) pairs on which a verified site key is the
- * caller's rate-limit identity (#8805): the sign-up agreements' evidence read.
- */
-export const SITE_KEYED_ROUTES: readonly Readonly<{
-  method: "GET";
-  url: string;
-}>[] = [{ method: "GET", url: "/v1/consent/sign-up" }];
-
-/**
- * A verified site key's identity prefix. No other identity starts with it:
- * `req.ip` never holds a comma, and a forwarded visitor is `v<n>,<ip>`.
- */
-export const SITE_KEY_IDENTITY_PREFIX = "site,";
-
-/**
- * How long a site-key lookup may run before the request is counted per IP
- * instead (#8805) — the store's own bound (#5040 D5).
- */
-export const SITE_KEY_TIMEOUT_MS = 1_000;
-
-const SITE_KEY_HEADER = "x-ailk-spoke-key";
-
-/**
- * The `siteKeyOf` reader (#8805). `verify` turns a request's site key into
- * its spoke id, or `null` for a key that is not a registered, unrevoked one;
- * it is called only for a request on one of the `SITE_KEYED_ROUTES` that
- * carries a non-empty `x-ailk-spoke-key`, and at most once per request, so
- * the global limiter and the scope's own share one lookup. A `verify` that
- * throws, or has not answered within `timeoutMs`, reads as `null` — the
- * request is counted per IP, never unlimited — and logs the error's name only.
- */
-export function siteKeyReader(
-  verify: (req: FastifyRequest) => Promise<string | null>,
-  timeoutMs: number = SITE_KEY_TIMEOUT_MS,
-): (req: FastifyRequest) => Promise<string | null> {
-  const verified = new WeakMap<FastifyRequest, Promise<string | null>>();
-  return (req) => {
-    const url = req.routeOptions.url ?? "";
-    const listed = SITE_KEYED_ROUTES.some(
-      (route) => route.method === req.method && route.url === url,
-    );
-    const presented = req.headers[SITE_KEY_HEADER];
-    if (!listed || typeof presented !== "string" || presented.trim() === "") {
-      return Promise.resolve(null);
-    }
-    let pending = verified.get(req);
-    if (pending === undefined) {
-      pending = withTimeout(verify(req), timeoutMs).catch((err: unknown) => {
-        req.log.warn(
-          {
-            event: "rate_limit_site_key_unverified",
-            err: err instanceof Error ? err.name : "unknown",
-          },
-          "rate_limit_site_key_unverified",
-        );
-        return null;
-      });
-      verified.set(req, pending);
-    }
-    return pending;
-  };
-}
-
-const VISITOR_IP_HEADER = "x-ailk-visitor-ip";
-const FORWARD_KEY_HEADER = "x-ailk-visitor-forward-key";
-const MIN_FORWARD_KEY_LENGTH = 32;
-const MAX_VISITOR_IP_LENGTH = 45;
-const DEFAULT_PER_KEY_PER_MINUTE = 300;
-const SCOPE_RE = /^[a-z][a-z0-9]*$/;
-const ENV_LIMIT_RE = /^[1-9][0-9]{0,5}$/;
-
-function sha256(value: string): Buffer {
-  return createHash("sha256").update(value).digest();
-}
-
-/**
- * Parse `AILK_VISITOR_FORWARD_KEYS` (comma-separated, one entry per spoke)
- * into one SHA-256 digest per accepted entry. An empty entry, or one shorter
- * than 32 characters, becomes `null` so every other entry keeps its position.
- * A short entry is reported by its 1-based position, never its value.
- */
-export function buildTrustedKeyDigests(
-  raw: string | undefined,
-  warn: (msg: string) => void,
-): readonly (Buffer | null)[] {
-  if (raw === undefined || raw.trim() === "") return [];
-  return raw.split(",").map((entry, index) => {
-    const key = entry.trim();
-    if (key === "") return null;
-    if (key.length < MIN_FORWARD_KEY_LENGTH) {
-      warn(
-        `AILK_VISITOR_FORWARD_KEYS entry ${index + 1} has fewer than ${MIN_FORWARD_KEY_LENGTH} characters and is ignored`,
-      );
-      return null;
-    }
-    return sha256(key);
-  });
-}
-
-/** The eight hextets of a valid IPv6 address, or `null`. */
-function expandIpv6(address: string): number[] | null {
-  let text = address;
-  const tail: number[] = [];
-  const lastColon = text.lastIndexOf(":");
-  const last = text.slice(lastColon + 1);
-  if (last.includes(".")) {
-    const octets = last.split(".").map(Number);
-    tail.push(((octets[0] ?? 0) << 8) | (octets[1] ?? 0));
-    tail.push(((octets[2] ?? 0) << 8) | (octets[3] ?? 0));
-    text = `${text.slice(0, lastColon + 1)}0`;
-  }
-  const halves = text.split("::");
-  const parse = (part: string | undefined): number[] =>
-    part ? part.split(":").map((hextet) => parseInt(hextet, 16)) : [];
-  const head = parse(halves[0]);
-  const rest = parse(halves[1]);
-  if (tail.length > 0) {
-    // The `0` placeholder stood in for the dotted tail's two hextets.
-    (halves.length > 1 ? rest : head).pop();
-  }
-  const fill = 8 - head.length - rest.length - tail.length;
-  if (fill < 0 || (halves.length === 1 && fill !== 0)) return null;
-  const hextets = [
-    ...head,
-    ...new Array<number>(fill).fill(0),
-    ...rest,
-    ...tail,
-  ];
-  return hextets.every((h) => Number.isInteger(h) && h >= 0 && h <= 0xffff)
-    ? hextets
-    : null;
-}
-
-/**
- * Validate and normalise a forwarded visitor IP (#7394 DD-1): IPv4 as is, an
- * IPv4-mapped IPv6 address as its IPv4 form, any other IPv6 address as its
- * /64 prefix. `null` for anything else.
- */
-function normaliseVisitorIp(raw: string): string | null {
-  const value = raw.trim().toLowerCase();
-  if (value.length > MAX_VISITOR_IP_LENGTH || value.includes("%")) return null;
-  const family = isIP(value);
-  if (family === 4) return value;
-  if (family !== 6) return null;
-  const hextets = expandIpv6(value);
-  if (!hextets) return null;
-  const isV4Mapped =
-    hextets.slice(0, 5).every((h) => h === 0) && hextets[5] === 0xffff;
-  if (isV4Mapped) {
-    const high = hextets[6] ?? 0;
-    const low = hextets[7] ?? 0;
-    return [high >> 8, high & 0xff, low >> 8, low & 0xff].join(".");
-  }
-  const prefix = hextets
-    .slice(0, 4)
-    .map((h) => h.toString(16).padStart(4, "0"))
-    .join(":");
-  return `${prefix}::/64`;
-}
-
-/**
- * The rate-limit identity of a request (#7394 DD-2). A request matching one
- * of `FORWARDED_VISITOR_ROUTES` by method and route, presenting a key whose
- * digest matches a
- * non-null slot, with a valid `x-ailk-visitor-ip`, is `v<n>,<ip>` where `n`
- * is the first matching slot. Everything else is `req.ip`. Every slot is
- * compared, in constant time per slot, without stopping at the first match.
- */
-export function resolveRateLimitIdentity(
-  req: FastifyRequest,
-  trustedKeyDigests: readonly (Buffer | null)[],
-): { identity: string; keyIndex: number | null } {
-  const fallback = { identity: req.ip, keyIndex: null };
-  if (!trustedKeyDigests.some((digest) => digest !== null)) return fallback;
-  const url = req.routeOptions.url ?? "";
-  const listed = FORWARDED_VISITOR_ROUTES.some(
-    (route) => route.method === req.method && route.url === url,
-  );
-  if (!listed) return fallback;
-
-  const presented = req.headers[FORWARD_KEY_HEADER];
-  if (typeof presented !== "string" || presented === "") return fallback;
-  const presentedDigest = sha256(presented);
-  let keyIndex: number | null = null;
-  for (const [index, digest] of trustedKeyDigests.entries()) {
-    if (digest === null) continue;
-    const matched = timingSafeEqual(digest, presentedDigest);
-    if (matched && keyIndex === null) keyIndex = index;
-  }
-  if (keyIndex === null) return fallback;
-
-  const visitorIp = req.headers[VISITOR_IP_HEADER];
-  const normalised =
-    typeof visitorIp === "string" ? normaliseVisitorIp(visitorIp) : null;
-  if (normalised === null) return fallback;
-  return { identity: `v${keyIndex},${normalised}`, keyIndex };
-}
-
-/**
- * A named scope's limit (#7394 DD-4): `AILK_RATE_LIMIT_<SCOPE>_<suffix>` when
- * it is a whole number from 1 to 999999, else `fallback`. A set but invalid
- * value is reported once and ignored. An unnamed registration always gets
- * `fallback`.
- */
-function resolveScopedLimit(
-  scope: string | undefined,
-  suffix: "PER_MINUTE" | "PER_KEY_PER_MINUTE",
-  fallback: number,
-  warn: (msg: string) => void,
-): number {
-  if (scope === undefined) return fallback;
-  const name = `AILK_RATE_LIMIT_${scope.toUpperCase()}_${suffix}`;
-  const raw = process.env[name];
-  if (raw === undefined || raw === "") return fallback;
-  if (ENV_LIMIT_RE.test(raw)) return Number(raw);
-  warn(
-    `${name} is not a whole number from 1 to 999999 and is ignored; using ${fallback}`,
-  );
-  return fallback;
-}
-
-// Module-scoped bucket store (the memory store's backing state). One entry
-// per unique identity, per named scope (#7394). Per-forwarding-key buckets
-// live in `keyBuckets` below.
-const buckets = new Map<string, RateLimitBucket>();
-
-// Per-forwarding-key buckets (#7394 DD-8), kept apart from `buckets` so the
-// `maxBuckets` FIFO eviction can never drop one: a keyed caller churning
-// visitor IPs would otherwise push its own key bucket out and reset its
-// ceiling. At most one entry per configured key per named scope, so it
-// needs no capacity cap of its own.
-const keyBuckets = new Map<string, RateLimitBucket>();
-
-// Request counter used to trigger periodic cleanup.
-let requestsSinceLastClean = 0;
-const CLEAN_INTERVAL_REQUESTS = 100;
-
-function evictStaleBuckets(now: number, windowMs: number): void {
-  for (const [ip, bucket] of buckets) {
-    if (now - bucket.windowStartMs >= windowMs) {
-      buckets.delete(ip);
-    }
-  }
-  for (const [key, bucket] of keyBuckets) {
-    if (now - bucket.windowStartMs >= windowMs) {
-      keyBuckets.delete(key);
-    }
-  }
-}
-
-/**
- * Test-only reset. Clears all bucket state between test cases so they do not
- * interfere with each other. Not intended for production use.
- */
-export function __resetBuckets(): void {
-  buckets.clear();
-  keyBuckets.clear();
-  requestsSinceLastClean = 0;
-}
-
-/**
- * Test-only accessor for the current distinct-bucket count. Not intended for
- * production use.
- */
-export function __bucketCount(): number {
-  return buckets.size;
-}
-
-/**
- * The memory store (#5040 D1/D7): the Maps and eviction logic above, wrapped
- * behind the `RateLimitStore` seam, unchanged in behavior. `maxBuckets` is
- * captured per call (registrations may pass their own, test-only) but every
- * instance still operates on the SAME shared `buckets` / `keyBuckets` Maps —
- * there has never been more than one memory store's worth of state in this
- * process.
- */
-function memoryRateLimitStore(maxBuckets: number): RateLimitStore {
-  function hit(key: string, now: number, windowMs: number): Promise<RateLimitBucket> {
-    let bucket = buckets.get(key);
-
-    if (!bucket || now - bucket.windowStartMs >= windowMs) {
-      // A genuinely new distinct identity (not a window roll on an
-      // existing bucket) at capacity evicts the single oldest-inserted
-      // entry first — independent of the time-based eviction above,
-      // which only removes EXPIRED windows and may leave `buckets` at or
-      // above `maxBuckets` when every entry is still within its window.
-      if (!buckets.has(key) && buckets.size >= maxBuckets) {
-        const oldestKey = buckets.keys().next().value;
-        if (oldestKey !== undefined) {
-          buckets.delete(oldestKey);
-        }
-      }
-      bucket = { count: 0, windowStartMs: now };
-      buckets.set(key, bucket);
-    }
-
-    bucket.count += 1;
-    return Promise.resolve(bucket);
-  }
-
-  function hitKey(key: string, now: number, windowMs: number): Promise<RateLimitBucket> {
-    let bucket = keyBuckets.get(key);
-    if (!bucket || now - bucket.windowStartMs >= windowMs) {
-      bucket = { count: 0, windowStartMs: now };
-      keyBuckets.set(key, bucket);
-    }
-    bucket.count += 1;
-    return Promise.resolve(bucket);
-  }
-
-  function hasOpenWindow(key: string, now: number, windowMs: number): Promise<boolean> {
-    const bucket = buckets.get(key);
-    return Promise.resolve(
-      bucket !== undefined && now - bucket.windowStartMs < windowMs,
-    );
-  }
-
-  // D6 — the memory store sweeps on both triggers, exactly as
-  // evictStaleBuckets always has; `reason` only matters to the database
-  // store.
-  function sweep(now: number, windowMs: number): Promise<void> {
-    evictStaleBuckets(now, windowMs);
-    return Promise.resolve();
-  }
-
-  return { hit, hitKey, hasOpenWindow, sweep };
-}
-
-// The process-wide default store (#5040 D4), resolved once and memoized —
-// NOT reset by __resetBuckets(), since only a fresh module instance
-// (jest.isolateModules) changes which store the environment resolves to.
-let processStoreKind: "memory" | "database" | undefined;
-let processDatabaseStore: RateLimitStore | undefined;
-let loggedStoreKind = false;
-
-/**
- * A rejection or timeout fired this long ago, within `FALLBACK_WARN_THROTTLE_MS`
- * — do not log another `rate_limit_store_fallback` line yet.
- */
-let lastFallbackWarnAt: number | undefined;
-
-/** The process default store for a registration with no explicit `store` option. */
-function resolveProcessDefaultStore(
-  warn: (msg: string) => void,
-  log: Pick<FastifyBaseLogger, "info">,
-  maxBuckets: number,
-): RateLimitStore {
-  if (processStoreKind === undefined) {
-    processStoreKind = resolveRateLimitStoreKind(
-      {
-        DATABASE_URL: process.env.DATABASE_URL,
-        AILK_RATE_LIMIT_STORE: process.env.AILK_RATE_LIMIT_STORE,
-      },
-      warn,
-    );
-  }
-  if (!loggedStoreKind) {
-    loggedStoreKind = true;
-    log.info({ rateLimitStore: processStoreKind }, "rate_limit_store");
-  }
-  if (processStoreKind === "database") {
-    processDatabaseStore ??= createDatabaseRateLimitStore(prisma);
-    return processDatabaseStore;
-  }
-  return memoryRateLimitStore(maxBuckets);
-}
-
-class RateLimitStoreTimeoutError extends Error {}
-
-/** Reject with a `RateLimitStoreTimeoutError` if `promise` has not settled within `ms`. */
-function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
-  return new Promise<T>((resolve, reject) => {
-    const timer = setTimeout(() => {
-      reject(new RateLimitStoreTimeoutError("rate limit store call timed out"));
-    }, ms);
-    promise.then(
-      (value) => {
-        clearTimeout(timer);
-        resolve(value);
-      },
-      (err: unknown) => {
-        clearTimeout(timer);
-        reject(err instanceof Error ? err : new Error(String(err)));
-      },
-    );
-  });
-}
-
-/**
- * Log at most one `rate_limit_store_fallback` warn per `FALLBACK_WARN_THROTTLE_MS`
- * per process (#5040 D5). Carries no key, IP, hash or error message.
- */
-function warnFallback(
-  warn: (obj: Record<string, unknown>, msg: string) => void,
-  now: number,
-  reason: "error" | "timeout",
-): void {
-  if (
-    lastFallbackWarnAt !== undefined &&
-    now - lastFallbackWarnAt < FALLBACK_WARN_THROTTLE_MS
-  ) {
-    return;
-  }
-  lastFallbackWarnAt = now;
-  warn({ event: "rate_limit_store_fallback", reason }, "rate_limit_store_fallback");
-}
-
-// Break Fastify's plugin encapsulation so the onRequest hook propagates to
-// parent and sibling scopes. This is the manual equivalent of fastify-plugin's
-// `skip-override` mechanism — documented in Fastify's plugin guide.
-// Without this, routes registered outside this plugin's scope do not see the hook.
-export const rateLimitMiddleware: FastifyPluginCallback<RateLimitOptions> = (
-  fastify,
-  opts,
-  done,
-) => {
-  const {
-    windowMs = 60_000,
-    maxBuckets = MAX_BUCKETS,
-    scope,
-    trustedKeyDigests = [],
-    storeTimeoutMs = STORE_TIMEOUT_MS,
-  } = opts;
-
-  if (scope !== undefined && !SCOPE_RE.test(scope)) {
-    done(
-      new Error(
-        `rate-limit scope ${JSON.stringify(scope)} must match ${SCOPE_RE}`,
-      ),
-    );
-    return;
-  }
-  if (trustedKeyDigests.length > 0 && scope === undefined) {
-    done(new Error("rate-limit trustedKeyDigests needs a scope"));
-    return;
-  }
-  if (opts.siteKeyOf !== undefined && scope === undefined) {
-    done(new Error("rate-limit siteKeyOf needs a scope"));
-    return;
-  }
-
-  const warn = (msg: string) => fastify.log.warn(msg);
-  const perIpPerMinute = resolveScopedLimit(
-    scope,
-    "PER_MINUTE",
-    opts.perIpPerMinute ??
-      (Number(process.env.AILK_RATE_LIMIT_PER_IP_PER_MINUTE) || 20),
-    warn,
-  );
-  const perKeyPerMinute = resolveScopedLimit(
-    scope,
-    "PER_KEY_PER_MINUTE",
-    opts.perKeyPerMinute ?? DEFAULT_PER_KEY_PER_MINUTE,
-    warn,
-  );
-  const { ipFromRequest, siteKeyOf } = opts;
-  const identityOf: (req: FastifyRequest) => {
-    identity: string;
-    keyIndex: number | null;
-  } = ipFromRequest
-    ? (req) => ({ identity: ipFromRequest(req), keyIndex: null })
-    : (req) => resolveRateLimitIdentity(req, trustedKeyDigests);
-  const bucketKey = (identity: string) =>
-    scope === undefined ? identity : `${scope}|${identity}`;
-
-  const fallbackStore = memoryRateLimitStore(maxBuckets);
-  const primaryStore: RateLimitStore =
-    opts.store ?? resolveProcessDefaultStore(warn, fastify.log, maxBuckets);
-
-  /**
-   * Run the whole request's counting against `activeStore` (D7's unchanged
-   * control flow: hitKey → keyOver → R-1 check (hasOpenWindow) → hit →
-   * tripped), plus the periodic/on-429 sweep (D6).
-   */
-  async function countRequest(
-    activeStore: RateLimitStore,
-    ip: string,
-    keyIndex: number | null,
-    siteId: string | null,
-    now: number,
-    sweepOnInterval: boolean,
-  ): Promise<{
-    tripped: RateLimitBucket | undefined;
-    visitorOver: boolean;
-    keyOver: boolean;
-  }> {
-    if (sweepOnInterval) {
-      await activeStore.sweep(now, windowMs, "interval");
-    }
-
-    // #8805: a verified site key is counted against its own bucket and the
-    // per-key ceiling only — no IP bucket is read or opened.
-    if (siteId !== null) {
-      const siteBucket = await activeStore.hitKey(
-        bucketKey(`${SITE_KEY_IDENTITY_PREFIX}${siteId}`),
-        now,
-        windowMs,
-      );
-      const siteOver = siteBucket.count > perKeyPerMinute;
-      if (siteOver) await activeStore.sweep(now, windowMs, "limited");
-      return {
-        tripped: siteOver ? siteBucket : undefined,
-        visitorOver: false,
-        keyOver: siteOver,
-      };
-    }
-
-    // #7394 DD-8: a keyed request also counts against its key's own
-    // bucket, even when the visitor bucket is already over its limit.
-    const keyBucket =
-      keyIndex === null
-        ? undefined
-        : await activeStore.hitKey(`${scope}|key,${keyIndex}`, now, windowMs);
-    const keyOver =
-      keyBucket !== undefined && keyBucket.count > perKeyPerMinute;
-    // A key over its ceiling opens no NEW visitor bucket (#7394 security
-    // review R-1). Each new entry can evict the oldest one in `buckets`,
-    // another scope's counter included, so without this a key holder
-    // rotating visitor IPs could wipe every strict limiter at will. A
-    // visitor whose window is still open is counted as usual.
-    const visitorKey = bucketKey(ip);
-    const bucket =
-      keyOver && !(await activeStore.hasOpenWindow(visitorKey, now, windowMs))
-        ? undefined
-        : await activeStore.hit(visitorKey, now, windowMs);
-    const visitorOver = bucket !== undefined && bucket.count > perIpPerMinute;
-    const tripped = visitorOver ? bucket : keyOver ? keyBucket : undefined;
-
-    if (tripped) {
-      // Evict stale buckets on every 429 to cap memory under abuse.
-      await activeStore.sweep(now, windowMs, "limited");
-    }
-
-    return { tripped, visitorOver, keyOver };
-  }
-
-  fastify.addHook(
-    "onRequest",
-    async (req: FastifyRequest, reply: FastifyReply) => {
-      const now = getClock().now();
-      const siteId = siteKeyOf ? await siteKeyOf(req) : null;
-      const { identity: ip, keyIndex } =
-        siteId === null
-          ? identityOf(req)
-          : { identity: `${SITE_KEY_IDENTITY_PREFIX}${siteId}`, keyIndex: null };
-
-      requestsSinceLastClean += 1;
-      const sweepOnInterval = requestsSinceLastClean >= CLEAN_INTERVAL_REQUESTS;
-      if (sweepOnInterval) requestsSinceLastClean = 0;
-
-      // #5040 D5 — fail open to the memory store, never to "no limit": a
-      // rejection or a timeout on ANY call of the primary store redoes the
-      // WHOLE request's counting against the memory store, so one request
-      // never mixes stores. withTimeout does not cancel the primary store's
-      // in-flight call, so a write that already landed before the failure
-      // stays counted, and a timed-out query may still land later — the
-      // request can be counted in BOTH stores, over-counting by at most
-      // one. That is the safe direction (D5): never under-counts, never
-      // lets a request through uncounted.
-      let outcome: {
-        tripped: RateLimitBucket | undefined;
-        visitorOver: boolean;
-        keyOver: boolean;
-      };
-      try {
-        outcome = await withTimeout(
-          countRequest(primaryStore, ip, keyIndex, siteId, now, sweepOnInterval),
-          storeTimeoutMs,
-        );
-      } catch (err) {
-        warnFallback(
-          (obj, msg) => fastify.log.warn(obj, msg),
-          now,
-          err instanceof RateLimitStoreTimeoutError ? "timeout" : "error",
-        );
-        outcome = await countRequest(
-          fallbackStore,
-          ip,
-          keyIndex,
-          siteId,
-          now,
-          sweepOnInterval,
-        );
-      }
-
-      const { tripped, visitorOver } = outcome;
-
-      if (tripped) {
-        const retryAfterSeconds = Math.ceil(
-          (tripped.windowStartMs + windowMs - now) / 1_000,
-        );
-
-        // The path WITHOUT its query string (#5970 security review, finding 1): a
-        // route may carry its credential there (`/v1/requests/:id/confirm?token=…`
-        // does), and a rate-limit warning is a line an attacker can provoke at
-        // will — logging the raw target would let them farm credentials out of
-        // the operator's own log by tripping the limiter.
-        const pathOnly = req.url.split("?")[0] ?? req.url;
-        // A keyed 429 names the bucket that tripped and the key's position,
-        // so a misused key can be traced to its spoke; never the key itself.
-        // A site-keyed 429 (#8805) names `bucket: "site"` and the spoke id.
-        req.log.warn(
-          {
-            ip,
-            path: pathOnly,
-            count: tripped.count,
-            ...(keyIndex !== null && {
-              bucket: visitorOver ? "visitor" : "key",
-              keyIndex,
-            }),
-            ...(siteId !== null && { bucket: "site" }),
-          },
-          RATE_LIMITED,
-        );
-
-        return reply
-          .status(429)
-          .header("Retry-After", String(retryAfterSeconds))
-          .send({ error: RATE_LIMITED, retryAfterSeconds });
-      }
-    },
-  );
-
-  done();
-};
-
-// Skip Fastify's plugin encapsulation — hooks registered inside propagate to
-// all scopes (parent + siblings), not just descendants of this plugin.
-(rateLimitMiddleware as FastifyPluginCallback & { [key: symbol]: boolean })[
-  Symbol.for("skip-override")
-] = true;
-
-// ─── The Stripe connection write budget (#8907 D9, contract K10) ────────────
-
-/** One Organization's connection writes in an hour (K10). */
-export const STRIPE_CONNECTION_WRITES_PER_ORG_PER_HOUR = 10;
-/** One person's connection writes in an hour, across Organizations (K10). */
-export const STRIPE_CONNECTION_WRITES_PER_USER_PER_HOUR = 20;
-
-/** One bucket a write is counted against: `org,<id>` or `user,<id>`. */
-export type WriteBudgetCharge = { key: string; limit: number };
-
-export type WriteBudgetResult = { ok: true } | { ok: false; retryAfterSeconds: number };
-
-/**
- * The budget's own database store (D9, SEC-8907-2) — never the process
- * default, so `AILK_RATE_LIMIT_STORE=memory` can never send an hourly bucket
- * into the shared `keyBuckets` map a per-minute sweep clears. Each database
- * row keeps its own `window_ms`, so no sweep shortens it.
- */
-let writeBudgetStore: RateLimitStore | undefined;
-
-/**
- * Where a request is counted while the database store rejects or times out.
- * Module-private and never touched by `evictStaleBuckets`; capped at
- * `MAX_BUCKETS`, the oldest entry dropped first, and an entry replaced only
- * once its own window has ended. Per instance while the database is
- * degraded — the residual SEC-8907-15 accepts.
- */
-const writeBudgetFallback = new Map<string, RateLimitBucket>();
-
-function fallbackHit(key: string, now: number, windowMs: number): RateLimitBucket {
-  let bucket = writeBudgetFallback.get(key);
-  if (!bucket || now - bucket.windowStartMs >= windowMs) {
-    writeBudgetFallback.delete(key);
-    if (writeBudgetFallback.size >= MAX_BUCKETS) {
-      const oldestKey = writeBudgetFallback.keys().next().value;
-      if (oldestKey !== undefined) writeBudgetFallback.delete(oldestKey);
-    }
-    bucket = { count: 0, windowStartMs: now };
-    writeBudgetFallback.set(key, bucket);
-  }
-  bucket.count += 1;
-  return bucket;
-}
-
-/**
- * Count one write against every charge's bucket and answer whether all of
- * them are still within their limit (D9). Every call counts — a refused key
- * costs a write too, so the probes are never a key-validity oracle. On a
- * refusal, `retryAfterSeconds` is the latest window end among the refusing
- * buckets, at least 1.
- */
-export async function chargeWriteBudget(input: {
-  scope: string;
-  charges: readonly WriteBudgetCharge[];
-  windowMs: number;
-  now: number;
-  warn?: (obj: Record<string, unknown>, msg: string) => void;
-}): Promise<WriteBudgetResult> {
-  const { scope, charges, windowMs, now } = input;
-  writeBudgetStore ??= createDatabaseRateLimitStore(prisma);
-  const activeStore = writeBudgetStore;
-
-  let retryAfterSeconds = 0;
-  for (const charge of charges) {
-    const key = `writebudget:${scope}|${charge.key}`;
-    let bucket: RateLimitBucket;
-    try {
-      bucket = await withTimeout(activeStore.hitKey(key, now, windowMs), STORE_TIMEOUT_MS);
-    } catch (err) {
-      warnFallback(
-        input.warn ?? (() => undefined),
-        now,
-        err instanceof RateLimitStoreTimeoutError ? "timeout" : "error",
-      );
-      bucket = fallbackHit(key, now, windowMs);
-    }
-    if (bucket.count > charge.limit) {
-      const endsInMs = bucket.windowStartMs + windowMs - now;
-      retryAfterSeconds = Math.max(retryAfterSeconds, Math.ceil(endsInMs / 1000), 1);
-    }
-  }
-  return retryAfterSeconds > 0 ? { ok: false, retryAfterSeconds } : { ok: true };
-}
-
-/** Test-only: replace the budget's store, as the middleware's `store` option does for a registration. */
-export function __setWriteBudgetStoreForTests(store: RateLimitStore | undefined): void {
-  writeBudgetStore = store;
-  writeBudgetFallback.clear();
-}
-
-/** Test-only: the fallback map's size. */
-export function __writeBudgetFallbackCount(): number {
-  return writeBudgetFallback.size;
-}