create-ailk 0.19.0 → 0.20.0

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

@@ -1,13 +1,22 @@
 /**
  * Per-IP rate limit middleware for anonymous write routes.
  *
- * SINGLE-REPLICA CAVEAT: This module uses an in-process Map to store request
- * counts. Each Fastify instance maintains its own bucket state. In a
- * multi-replica deployment (e.g. 3 Vercel functions), an attacker can issue
- * up to N × perIpPerMinute requests per minute per IP, where N is the replica
- * count. For OSS v1 (single-replica), this is acceptable. A Redis-backed swap
- * is tracked in the follow-up issue "Phase 6+ — Redis-backed rate limit for
- * multi-replica deploys."
+ * 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
@@ -23,7 +32,9 @@
  * 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.
+ * 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
@@ -51,8 +62,10 @@
  * 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`. The
- * global limiter (`server.ts`) passes the hub's digests, so a listed call is
+ * (#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`). 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
@@ -78,8 +91,17 @@ 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.
@@ -101,7 +123,8 @@ export type RateLimitOptions = {
   /**
    * 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.
+   * 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;
   /**
@@ -123,11 +146,15 @@ export type RateLimitOptions = {
    * visitors (#7394). Default: 300.
    */
   perKeyPerMinute?: number;
-};
-
-type Bucket = {
-  count: number;
-  windowStartMs: number;
+  /**
+   * 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;
@@ -154,15 +181,26 @@ export const MAX_BUCKETS = 10_000;
  */
 export const DEFAULT_SCHEDULE_PER_KEY_PER_MINUTE = 60;
 
+/**
+ * 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, and the two schedule calls a site's
+ * (#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). Matched against `req.method` and `req.routeOptions.url`, the
+ * 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";
+  method: "GET" | "POST" | "PATCH";
   url: string;
 }>[] = [
   { method: "POST", url: "/v1/leads/submit" },
@@ -170,6 +208,16 @@ export const FORWARDED_VISITOR_ROUTES: readonly Readonly<{
   { 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" },
 ];
 
 const VISITOR_IP_HEADER = "x-ailk-visitor-ip";
@@ -330,16 +378,17 @@ function resolveScopedLimit(
   return fallback;
 }
 
-// Module-scoped bucket store. One entry per unique identity, per named scope
-// (#7394). Per-forwarding-key buckets live in `keyBuckets` below.
-const buckets = new Map<string, Bucket>();
+// 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, Bucket>();
+const keyBuckets = new Map<string, RateLimitBucket>();
 
 // Request counter used to trigger periodic cleanup.
 let requestsSinceLastClean = 0;
@@ -356,7 +405,6 @@ function evictStaleBuckets(now: number, windowMs: number): void {
       keyBuckets.delete(key);
     }
   }
-  requestsSinceLastClean = 0;
 }
 
 /**
@@ -377,6 +425,145 @@ 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.
@@ -391,6 +578,7 @@ export const rateLimitMiddleware: FastifyPluginCallback<RateLimitOptions> = (
     maxBuckets = MAX_BUCKETS,
     scope,
     trustedKeyDigests = [],
+    storeTimeoutMs = STORE_TIMEOUT_MS,
   } = opts;
 
   if (scope !== undefined && !SCOPE_RE.test(scope)) {
@@ -430,45 +618,57 @@ export const rateLimitMiddleware: FastifyPluginCallback<RateLimitOptions> = (
   const bucketKey = (identity: string) =>
     scope === undefined ? identity : `${scope}|${identity}`;
 
-  /** Count one request against `key`, opening a new window when needed. */
-  function hit(key: string, now: number): Bucket {
-    let bucket = buckets.get(key);
+  const fallbackStore = memoryRateLimitStore(maxBuckets);
+  const primaryStore: RateLimitStore =
+    opts.store ?? resolveProcessDefaultStore(warn, fastify.log, maxBuckets);
 
-    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);
+  /**
+   * 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,
+    now: number,
+    sweepOnInterval: boolean,
+  ): Promise<{
+    tripped: RateLimitBucket | undefined;
+    visitorOver: boolean;
+    keyOver: boolean;
+  }> {
+    if (sweepOnInterval) {
+      await activeStore.sweep(now, windowMs, "interval");
     }
 
-    bucket.count += 1;
-    return bucket;
-  }
-
-  /** True when `key` has a bucket whose window has not yet ended. */
-  function hasOpenWindow(key: string, now: number): boolean {
-    const bucket = buckets.get(key);
-    return bucket !== undefined && now - bucket.windowStartMs < windowMs;
-  }
-
-  /** Count one request against a forwarding key's own bucket (DD-8). */
-  function hitKey(key: string, now: number): Bucket {
-    let bucket = keyBuckets.get(key);
-    if (!bucket || now - bucket.windowStartMs >= windowMs) {
-      bucket = { count: 0, windowStartMs: now };
-      keyBuckets.set(key, bucket);
+    // #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");
     }
-    bucket.count += 1;
-    return bucket;
+
+    return { tripped, visitorOver, keyOver };
   }
 
   fastify.addHook(
@@ -478,37 +678,50 @@ export const rateLimitMiddleware: FastifyPluginCallback<RateLimitOptions> = (
       const { identity: ip, keyIndex } = identityOf(req);
 
       requestsSinceLastClean += 1;
-      if (requestsSinceLastClean >= CLEAN_INTERVAL_REQUESTS) {
-        evictStaleBuckets(now, windowMs);
+      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, 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,
+          now,
+          sweepOnInterval,
+        );
       }
 
-      // #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 : hitKey(`${scope}|key,${keyIndex}`, now);
-      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 && !hasOpenWindow(visitorKey, now)
-          ? undefined
-          : hit(visitorKey, now);
-      const visitorOver = bucket !== undefined && bucket.count > perIpPerMinute;
-      const tripped = visitorOver ? bucket : keyOver ? keyBucket : undefined;
+      const { tripped, visitorOver } = outcome;
 
       if (tripped) {
         const retryAfterSeconds = Math.ceil(
           (tripped.windowStartMs + windowMs - now) / 1_000,
         );
 
-        // Evict stale buckets on every 429 to cap memory under abuse.
-        evictStaleBuckets(now, windowMs);
-
         // 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

package/templates/apps/api/src/routes/checkout/__tests__/live-key.test.ts

@@ -0,0 +1,167 @@
+/**
+ * @file live-key.test.ts
+ *
+ * The hub checkout with a live key (#8450 AC 1, AC 2): `POST
+ * /v1/checkout/sessions` and the return page's `GET
+ * /v1/checkout/sessions/:id`. Unlike `sessions.test.ts` and
+ * `session.test.ts`, BOTH guards here are real: `lib/stripe.ts` runs as
+ * itself (only the two Stripe calls are mocked, so nothing leaves the
+ * process), and `@working-theory/stripe-client` runs as itself with
+ * `assertSandboxKey` wrapped in a spy, so the test can see whether a route
+ * still calls the sandbox-only guard.
+ *
+ * The process admits a restricted live key once, in `beforeAll`, exactly as
+ * `build()` does at boot. Every live-shaped key is composed at runtime from
+ * fragments — never a literal (architecture.yaml's live-key pattern).
+ */
+import type { FastifyInstance } from "fastify";
+
+const mockCreateCheckoutSession = jest.fn();
+const mockRetrieveCheckoutSession = jest.fn();
+
+jest.mock("@working-theory/stripe-client", () => {
+  const actual = jest.requireActual("@working-theory/stripe-client");
+  return { ...actual, assertSandboxKey: jest.fn(actual.assertSandboxKey) };
+});
+
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../../lib/stripe.js", () => ({
+  ...jest.requireActual("../../../lib/stripe.js"),
+  createCheckoutSession: (...args: unknown[]) => mockCreateCheckoutSession(...args),
+  retrieveCheckoutSession: (...args: unknown[]) => mockRetrieveCheckoutSession(...args),
+}));
+
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted; the DB boundary, mirrors sessions.test.ts
+jest.mock("../../../lib/prisma.js", () => ({
+  prisma: {
+    session: { findUnique: jest.fn() },
+    user: { findUnique: jest.fn() },
+    apiToken: { findUnique: jest.fn(), update: jest.fn() },
+  },
+}));
+
+import { assertSandboxKey } from "@working-theory/stripe-client";
+
+import { config } from "../../../config/index.js";
+import { admitApiStripeKey, stripeKeyMode } from "../../../lib/stripe.js";
+import { __resetBuckets } from "../../../middleware/rate-limit.js";
+import { checkoutRoutes } from "../index";
+
+config.FRONTEND_URL = "https://example.com";
+config.TRUSTED_ORIGINS = ["https://example.com"];
+
+const TAIL = "FixtureOnlyCheckout";
+const restrictedLiveKey = ["rk", "live", ""].join("_") + TAIL;
+const secretLiveKey = ["sk", "live", ""].join("_") + TAIL;
+const publishableLiveKey = ["pk", "live", ""].join("_") + TAIL;
+
+const sandboxSpy = assertSandboxKey as jest.MockedFunction<typeof assertSandboxKey>;
+
+const ENV_KEYS = ["STRIPE_SECRET_KEY", "STRIPE_MODE", "VERCEL_ENV", "OSS_API_INTERNAL_SECRET"] as const;
+const savedEnv = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
+
+const VALID_BODY = {
+  productCode: "ailk-pro",
+  successUrl: "https://example.com/success",
+  cancelUrl: "https://example.com/cancel",
+};
+
+const SESSION_ID = "cs_live_fixture12345";
+
+function buildApp(): FastifyInstance {
+  const fastify = require("fastify")({ logger: false });
+  fastify.register(checkoutRoutes);
+  return fastify;
+}
+
+describe("the hub checkout — an admitted live key (#8450)", () => {
+  let app: FastifyInstance;
+
+  beforeAll(() => {
+    delete process.env["OSS_API_INTERNAL_SECRET"];
+    process.env["STRIPE_SECRET_KEY"] = restrictedLiveKey;
+    process.env["STRIPE_MODE"] = "live";
+    process.env["VERCEL_ENV"] = "production";
+    expect(admitApiStripeKey()).toBe("live");
+    expect(stripeKeyMode()).toBe("live");
+  });
+
+  afterAll(() => {
+    for (const k of ENV_KEYS) {
+      if (savedEnv[k] === undefined) delete process.env[k];
+      else process.env[k] = savedEnv[k];
+    }
+  });
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+    __resetBuckets();
+    process.env["STRIPE_SECRET_KEY"] = restrictedLiveKey;
+    mockCreateCheckoutSession.mockResolvedValue({
+      sessionId: "cs_live_fixture12345",
+      url: "https://checkout.stripe.com/c/pay/fixture",
+    });
+    mockRetrieveCheckoutSession.mockResolvedValue({
+      id: SESSION_ID,
+      status: "complete",
+      paymentStatus: "paid",
+      currency: "usd",
+      amountTotal: 4800,
+      lineItems: [],
+    });
+    app = buildApp();
+    await app.ready();
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  describe("POST /v1/checkout/sessions", () => {
+    it("gets past the key check on the restricted live key, without the sandbox-only guard", async () => {
+      const res = await app.inject({ method: "POST", url: "/v1/checkout/sessions", payload: VALID_BODY });
+
+      expect(res.statusCode).toBe(201);
+      expect(mockCreateCheckoutSession).toHaveBeenCalledTimes(1);
+      expect(sandboxSpy).not.toHaveBeenCalled();
+    });
+
+    it.each([
+      ["an unrestricted live key", secretLiveKey],
+      ["a publishable live key", publishableLiveKey],
+    ])("still refuses %s with 500 live-mode-forbidden and no Stripe call", async (_label, key) => {
+      process.env["STRIPE_SECRET_KEY"] = key;
+
+      const res = await app.inject({ method: "POST", url: "/v1/checkout/sessions", payload: VALID_BODY });
+
+      expect(res.statusCode).toBe(500);
+      expect(res.json()).toEqual({ error: "live-mode-forbidden" });
+      expect(res.body).not.toContain(TAIL);
+      expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("GET /v1/checkout/sessions/:id", () => {
+    it("gets past the key check on the restricted live key, without the sandbox-only guard", async () => {
+      const res = await app.inject({ method: "GET", url: `/v1/checkout/sessions/${SESSION_ID}` });
+
+      expect(res.statusCode).toBe(200);
+      expect(mockRetrieveCheckoutSession).toHaveBeenCalledTimes(1);
+      expect(sandboxSpy).not.toHaveBeenCalled();
+    });
+
+    it.each([
+      ["an unrestricted live key", secretLiveKey],
+      ["a publishable live key", publishableLiveKey],
+    ])("still refuses %s with 500 live-mode-forbidden and no Stripe call", async (_label, key) => {
+      process.env["STRIPE_SECRET_KEY"] = key;
+
+      const res = await app.inject({ method: "GET", url: `/v1/checkout/sessions/${SESSION_ID}` });
+
+      expect(res.statusCode).toBe(500);
+      expect(res.json()).toEqual({ error: "live-mode-forbidden" });
+      expect(res.body).not.toContain(TAIL);
+      expect(mockRetrieveCheckoutSession).not.toHaveBeenCalled();
+    });
+  });
+});