create-ailk 0.18.0 → 0.19.1

package/templates/apps/api/src/middleware/auth.ts

@@ -33,10 +33,19 @@
  *      (`lib/hub-sign-in-store.ts`). It is admitted only beside the SAME
  *      spoke's key (`x-ailk-spoke-key`), only while its grant is unrevoked and
  *      unexpired, its client enabled and its person's email verified, and only
- *      on `HUB_SESSION_ROUTES` — an exact list of four reads; any other route
- *      is 404 (never 403, so the account area's `read()` loads "nothing for
- *      this caller"). It acts as its person (`request.userId`) and carries
- *      `request.hubSession` — never `request.sessionTenant`.
+ *      on `HUB_SESSION_ROUTES` — an exact list of METHOD + registered URL
+ *      pairs — the credential's own `me` and the member routes, 20 in all
+ *      (#8220); any other route is 404 (never 403, so the account area's
+ *      `read()` loads "nothing for this caller"). It acts as its person
+ *      (`request.userId`) and carries `request.hubSession` — never
+ *      `request.sessionTenant` — and its request logger names the spoke
+ *      (`spokeId`). Each person is limited, at each spoke, to 60 requests and
+ *      10 writes a minute and 30 writes an hour — a fixed hour window from
+ *      the bucket's first admitted write (#8220 D2, SEC-8169-4): the bucket is
+ *      keyed on the VERIFIED spoke and person, never a header, and charged
+ *      only after every check above passes, so a refused credential or an
+ *      off-list route never gets one. The write limits refuse only writes,
+ *      and a request the budget refuses is not counted.
  *
  * Every authenticated request carries `request.actor` — the person, or the
  * agent and the person it acts for — and its request/reply loggers are
@@ -141,21 +150,47 @@ export type HubSession = {
 };
 
 /**
- * The only routes a hub-issued credential reaches (#7894 D6): an EXACT list of
- * method + registered URL, never a prefix, so a route added later joins only
- * by a reviewed edit of this list (SEC-7894-3). The first is the credential's
- * own `me`; the other three are #7877's member reads. Not admitted,
- * deliberately: `GET /v1/waitlist-signups/me`, `GET /v1/flow-checkouts/me`,
- * `GET /v1/subscription/me` and `POST /v1/subscription/portal-session` (they
- * answer for the HUB's site and the person's platform billing, SEC-7894-1,
- * -2), and the token and profile routes.
+ * The only routes a hub-issued credential reaches (#7894 D6, #8220 D1): an
+ * EXACT list of method + registered URL, never a prefix and never computed,
+ * so a route added later joins only by a reviewed edit of this list
+ * (SEC-7894-3). Four groups, in this order: the credential's own `me` and
+ * #7877's three member reads; #8169's eight member reads; #8170's six member
+ * writes (roadmap §7.2 row order); #8438's member consents read and write.
+ * `GET /v1/consent/platform` is not admitted — it is the Admin owner's own
+ * consent to Working Theory, on the hub's cookie session. The member profile write IS admitted — it
+ * is the person's own account, which roadmap D9 saves through it. Not
+ * admitted, deliberately: `GET /v1/waitlist-signups/me`,
+ * `GET /v1/flow-checkouts/me`, `GET /v1/subscription/me` and
+ * `POST /v1/subscription/portal-session` (they answer for the HUB's site and
+ * the person's platform billing, SEC-7894-1, -2), the token routes and the
+ * hub's own-account `/v1/user/*` routes, `PATCH /v1/user/profile` among them.
  */
-export const HUB_SESSION_ROUTES: readonly string[] = [
+export const HUB_SESSION_ROUTES: readonly string[] = Object.freeze([
   "GET /v1/hub-sign-in/me",
   "GET /v1/member/pieces",
   "GET /v1/member/messages",
   "GET /v1/member/messages/:id/file",
-];
+  "GET /v1/member/purchases",
+  "GET /v1/member/appointments",
+  "GET /v1/member/artifacts",
+  "GET /v1/member/artifacts/:pieceId/versions/:version/file",
+  "GET /v1/member/meeting-types",
+  "GET /v1/member/availability",
+  "GET /v1/member/request-form",
+  "GET /v1/member/billing",
+  "POST /v1/member/artifacts/:pieceId/review",
+  "POST /v1/member/bookings",
+  "POST /v1/member/requests",
+  "POST /v1/member/messages",
+  "PATCH /v1/member/profile",
+  "GET /v1/member/profile/contact",
+  "PATCH /v1/member/profile/contact",
+  "POST /v1/member/deletion-request",
+  // #8438 D6 — the member's own consents. `GET /v1/consent/platform` is NOT
+  // admitted: those are the Admin owner's, on the hub's own cookie session.
+  "GET /v1/member/consents",
+  "POST /v1/member/consents",
+]);
 
 /**
  * Who made a request (#3591 D9). A cookie session and a personal `ApiToken`
@@ -311,12 +346,13 @@ function bindActor(
   reply.log = request.log;
 }
 
-// ── The per-agent limit (#3591 D4 step 5, SEC-3591-04/-14) ─────────────────
+// ── The per-caller limits (#3591 D4 step 5, SEC-3591-04/-14; #8220 D2) ──────
 //
 // In the handler, not `onRequest`: the shared limiter runs before any
-// identity exists, and a bucket must only ever be keyed on a VERIFIED agent
-// id, so an invented key never gets one. The shape of
-// `routes/subscription/portal.ts`'s per-user budget.
+// identity exists, and a bucket must only ever be keyed on a VERIFIED id, so
+// an invented key or credential never gets one. The shape of
+// `routes/subscription/portal.ts`'s per-user budget. An agent and a person
+// never share a map.
 
 const AGENT_WINDOW_MS = 60_000;
 const AGENT_REQUESTS_PER_WINDOW = 60;
@@ -324,53 +360,159 @@ const AGENT_WRITES_PER_WINDOW = 10;
 /** Cap on distinct buckets — the oldest is evicted at capacity (DEF-011's shape). */
 const MAX_AGENT_BUCKETS = 5_000;
 
-type AgentBucket = { windowStartMs: number; requests: number; writes: number };
-const agentBuckets = new Map<string, AgentBucket>();
+const HUB_SESSION_WINDOW_MS = 60_000;
+const HUB_SESSION_REQUESTS_PER_WINDOW = 60;
+const HUB_SESSION_WRITES_PER_WINDOW = 10;
+const HUB_SESSION_WRITE_HOUR_MS = 3_600_000;
+const HUB_SESSION_WRITES_PER_HOUR = 30;
+const MAX_HUB_SESSION_BUCKETS = 5_000;
+
+type CallerBucket = {
+  windowStartMs: number;
+  requests: number;
+  writes: number;
+  /** The hourly write window — set by the bucket's first admitted write. */
+  hourStartMs: number | null;
+  hourWrites: number;
+};
+
+type CallerLimits = {
+  windowMs: number;
+  maxBuckets: number;
+  requests: number;
+  writes: number;
+  /** An hourly write ceiling — the hub-credential path's alone. */
+  writesPerHour?: { limit: number; windowMs: number };
+  /** When true, the write limits refuse only writes; a read meets only `requests`. */
+  refuseOnlyWrites: boolean;
+  /** When true, a refused request still counts toward every limit. */
+  countRefused: boolean;
+};
+
+const AGENT_LIMITS: CallerLimits = {
+  windowMs: AGENT_WINDOW_MS,
+  maxBuckets: MAX_AGENT_BUCKETS,
+  requests: AGENT_REQUESTS_PER_WINDOW,
+  writes: AGENT_WRITES_PER_WINDOW,
+  refuseOnlyWrites: false,
+  countRefused: true,
+};
+
+const HUB_SESSION_LIMITS: CallerLimits = {
+  windowMs: HUB_SESSION_WINDOW_MS,
+  maxBuckets: MAX_HUB_SESSION_BUCKETS,
+  requests: HUB_SESSION_REQUESTS_PER_WINDOW,
+  writes: HUB_SESSION_WRITES_PER_WINDOW,
+  writesPerHour: {
+    limit: HUB_SESSION_WRITES_PER_HOUR,
+    windowMs: HUB_SESSION_WRITE_HOUR_MS,
+  },
+  refuseOnlyWrites: true,
+  countRefused: false,
+};
+
+const agentBuckets = new Map<string, CallerBucket>();
+const hubSessionBuckets = new Map<string, CallerBucket>();
 
 /** Test-only reset. Not intended for production use. */
 export function __resetAgentRateBuckets(): void {
   agentBuckets.clear();
 }
 
+/** Test-only reset. Not intended for production use. */
+export function __resetHubSessionRateBuckets(): void {
+  hubSessionBuckets.clear();
+}
+
 function isWrite(method: string): boolean {
   const m = method.toUpperCase();
   return m !== "GET" && m !== "HEAD";
 }
 
-/** `undefined` when admitted; the seconds to wait when the agent is over budget. */
-function chargeAgentRateLimit(
-  agentId: string,
+/** A bucket no window still holds — the eviction pass may drop it. */
+function isStale(
+  bucket: CallerBucket,
+  now: number,
+  limits: CallerLimits,
+): boolean {
+  if (now - bucket.windowStartMs < limits.windowMs) return false;
+  return (
+    bucket.hourStartMs === null ||
+    limits.writesPerHour === undefined ||
+    now - bucket.hourStartMs >= limits.writesPerHour.windowMs
+  );
+}
+
+/**
+ * Charge one request to `key`'s bucket. `undefined` when admitted; the
+ * seconds to wait — to the end of the latest window that refused, at least
+ * 1 — when over budget.
+ */
+function chargeCallerBucket(
+  buckets: Map<string, CallerBucket>,
+  key: string,
   method: string,
   now: number,
+  limits: CallerLimits,
 ): number | undefined {
-  let bucket = agentBuckets.get(agentId);
-  if (!bucket || now - bucket.windowStartMs >= AGENT_WINDOW_MS) {
-    if (!agentBuckets.has(agentId) && agentBuckets.size >= MAX_AGENT_BUCKETS) {
-      for (const [id, b] of agentBuckets) {
-        if (now - b.windowStartMs >= AGENT_WINDOW_MS) agentBuckets.delete(id);
+  let bucket = buckets.get(key);
+  if (!bucket || now - bucket.windowStartMs >= limits.windowMs) {
+    if (!bucket && buckets.size >= limits.maxBuckets) {
+      for (const [k, b] of buckets) {
+        if (isStale(b, now, limits)) buckets.delete(k);
       }
-      if (agentBuckets.size >= MAX_AGENT_BUCKETS) {
-        const oldest = agentBuckets.keys().next().value;
-        if (oldest !== undefined) agentBuckets.delete(oldest);
+      if (buckets.size >= limits.maxBuckets) {
+        const oldest = buckets.keys().next().value;
+        if (oldest !== undefined) buckets.delete(oldest);
       }
     }
-    // Re-insert, so Map order stays oldest-window-first for the eviction above.
-    agentBuckets.delete(agentId);
-    bucket = { windowStartMs: now, requests: 0, writes: 0 };
-    agentBuckets.set(agentId, bucket);
+    // Re-insert, so Map order stays oldest-window-first for the eviction
+    // above. A new minute keeps the hour's start and count.
+    buckets.delete(key);
+    bucket = {
+      windowStartMs: now,
+      requests: 0,
+      writes: 0,
+      hourStartMs: bucket?.hourStartMs ?? null,
+      hourWrites: bucket?.hourWrites ?? 0,
+    };
+    buckets.set(key, bucket);
   }
-  bucket.requests += 1;
-  if (isWrite(method)) bucket.writes += 1;
+  const hour = limits.writesPerHour;
   if (
-    bucket.requests > AGENT_REQUESTS_PER_WINDOW ||
-    bucket.writes > AGENT_WRITES_PER_WINDOW
+    hour !== undefined &&
+    bucket.hourStartMs !== null &&
+    now - bucket.hourStartMs >= hour.windowMs
   ) {
-    return Math.max(
-      1,
-      Math.ceil((bucket.windowStartMs + AGENT_WINDOW_MS - now) / 1_000),
-    );
+    bucket.hourStartMs = null;
+    bucket.hourWrites = 0;
   }
-  return undefined;
+
+  const write = isWrite(method);
+  const requests = bucket.requests + 1;
+  const writes = bucket.writes + (write ? 1 : 0);
+  const hourWrites = bucket.hourWrites + (write ? 1 : 0);
+  const minuteEnd = bucket.windowStartMs + limits.windowMs;
+  const refusedUntil: number[] = [];
+  if (requests > limits.requests) refusedUntil.push(minuteEnd);
+  if (write || !limits.refuseOnlyWrites) {
+    if (writes > limits.writes) refusedUntil.push(minuteEnd);
+    if (write && hour !== undefined && hourWrites > hour.limit) {
+      refusedUntil.push((bucket.hourStartMs ?? now) + hour.windowMs);
+    }
+  }
+
+  const refused = refusedUntil.length > 0;
+  if (!refused || limits.countRefused) {
+    bucket.requests = requests;
+    bucket.writes = writes;
+    if (write && hour !== undefined) {
+      bucket.hourWrites = hourWrites;
+      bucket.hourStartMs ??= now;
+    }
+  }
+  if (!refused) return undefined;
+  return Math.max(1, Math.ceil((Math.max(...refusedUntil) - now) / 1_000));
 }
 
 /**
@@ -412,7 +554,13 @@ async function authenticateAgent(
     onBehalfOfUserId: personId,
   });
 
-  const retryAfter = chargeAgentRateLimit(agentId, request.method, now);
+  const retryAfter = chargeCallerBucket(
+    agentBuckets,
+    agentId,
+    request.method,
+    now,
+    AGENT_LIMITS,
+  );
   if (retryAfter !== undefined) {
     reply.code(429).header("Retry-After", String(retryAfter)).send(RATE_LIMITED);
     return;
@@ -440,7 +588,9 @@ async function authenticateAgent(
 /**
  * The hub-credential path (#7894 D6). The credential is never logged and
  * never echoed: every refusal is a fixed body. (1)-(3) failing is the one 401;
- * (4), the route not being on `HUB_SESSION_ROUTES`, is 404 with no handler run.
+ * (4), the route not being on `HUB_SESSION_ROUTES`, is 404 with no handler run;
+ * (5), the person over budget at this spoke (#8220 D2), is 429 with no
+ * handler run.
  */
 async function authenticateHubSession(
   request: FastifyRequest,
@@ -490,6 +640,24 @@ async function authenticateHubSession(
     workspaceId: spoke.workspaceId as Id<"workspace">,
   };
   bindActor(request, reply, { type: "user", userId: request.userId });
+  // #8220 D10 — every line the request logger writes after admission names
+  // the spoke that acted: its id, never its key or the credential. (Lines a
+  // helper writes through the module-level `logger` carry no request binding.)
+  request.log = request.log.child({ spokeId: spoke.id });
+  reply.log = request.log;
+
+  // (5) The verified (spoke, person) is within its budget.
+  const retryAfter = chargeCallerBucket(
+    hubSessionBuckets,
+    `${spoke.id}:${grant.userId}`,
+    request.method,
+    now,
+    HUB_SESSION_LIMITS,
+  );
+  if (retryAfter !== undefined) {
+    reply.code(429).header("Retry-After", String(retryAfter)).send(RATE_LIMITED);
+    return;
+  }
 }
 
 export type AuthPreHandlerOptions = {

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

@@ -170,6 +170,11 @@ 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" },
 ];
 
 const VISITOR_IP_HEADER = "x-ailk-visitor-ip";

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();
+    });
+  });
+});

package/templates/apps/api/src/routes/checkout/session.ts

@@ -27,7 +27,7 @@
  *   400 validation-error      — `:id` fails the shape check
  *   404 unknown-session       — Stripe raised `resource_missing`
  *   500 stripe-not-configured — STRIPE_SECRET_KEY is missing/empty
- *   500 live-mode-forbidden   — STRIPE_SECRET_KEY is a live key
+ *   500 live-mode-forbidden   — STRIPE_SECRET_KEY is a live key the process did not admit
  *   500 config-error          — STRIPE_SECRET_KEY invalid configuration
  *   502 checkout-unavailable  — Stripe SDK threw an unexpected error
  */
@@ -35,7 +35,7 @@ import type { FastifyReply, FastifyRequest } from "fastify";
 import { z } from "zod";
 
 import {
-  assertSandboxKey,
+  assertAdmittedStripeKey,
   retrieveCheckoutSession,
   StripeConfigError,
   UnknownSessionError,
@@ -80,7 +80,7 @@ export async function checkoutSessionReadHandler(
     return reply.status(500).send({ error: "stripe-not-configured" });
   }
   try {
-    assertSandboxKey(stripeSecretKey);
+    assertAdmittedStripeKey(stripeSecretKey);
   } catch {
     return reply.status(500).send({ error: "live-mode-forbidden" });
   }

package/templates/apps/api/src/routes/checkout/sessions.ts

@@ -7,7 +7,9 @@
  * price opens a subscription session), so this route serves both (#4398).
  *
  * Security invariants:
- *   - Sandbox-only: live Stripe keys are rejected at runtime before any Stripe call.
+ *   - Admitted key only (#8450): before any Stripe call, a test-mode key or
+ *     the restricted live key the process admitted at boot passes
+ *     (`assertAdmittedStripeKey`); every other live key is refused.
  *   - No PII in logs: successUrl/cancelUrl and full session IDs are never logged.
  *     Only the first 8 chars of the session ID appear in log lines.
  *   - Error responses never echo user input (productCode, URLs).
@@ -48,7 +50,7 @@
  *                               unauthenticated redirect is off the site origin (#6877)
  *   404 unknown-product-code  — no active Stripe price for the given productCode
  *   500 stripe-not-configured — STRIPE_SECRET_KEY is missing/empty (no Stripe call)
- *   500 live-mode-forbidden   — STRIPE_SECRET_KEY is a live key
+ *   500 live-mode-forbidden   — STRIPE_SECRET_KEY is a live key the process did not admit
  *   500 config-error          — STRIPE_SECRET_KEY invalid configuration (from the SDK wrapper),
  *                               or no trusted browser origin is configured when the origin
  *                               lock applies (#6877, #7395)
@@ -62,7 +64,7 @@ import { z } from "zod";
 import { config } from "../../config/index.js";
 import { siteStamp } from "../../lib/site.js";
 import {
-  assertSandboxKey,
+  assertAdmittedStripeKey,
   createCheckoutSession,
   StripeConfigError,
   UnknownCustomerError,
@@ -248,7 +250,7 @@ export async function checkoutSessionsHandler(
     return reply.status(500).send({ error: "stripe-not-configured" });
   }
   try {
-    assertSandboxKey(stripeSecretKey);
+    assertAdmittedStripeKey(stripeSecretKey);
   } catch {
     return reply.status(500).send({ error: "live-mode-forbidden" });
   }

package/templates/apps/api/src/routes/consent/cookie.ts

@@ -0,0 +1,90 @@
+/**
+ * The cookie banner's log (#8438, spec
+ * docs/specs/8438-consent-registry-and-ledger-step-spec.md D5).
+ *
+ *   POST /v1/consent/cookie
+ *       `{ visitorId, choice: "accepted" | "declined", locale }` — one row
+ *       in the consent ledger against the visitor id, source
+ *       `cookie_banner`. Answers `201 { recorded: true }`, or
+ *       `200 { recorded: false }` when the site declares no cookie purpose
+ *       or the visitor's newest row already records the same choice.
+ *
+ * The workspace comes from `resolvePublicWorkspace(request)` — the spoke
+ * key, else the one-workspace deployment — and NEVER from the body, which is
+ * strict and names no site, workspace, person or user. An unresolved
+ * workspace is `503 tenant_unresolved`; no database `503
+ * consent_store_unavailable`; a failed write the same.
+ *
+ * Registered at the top level in its own rate-limited scope, outside every
+ * module gate: consent logging is part of the never-gated privacy floor.
+ * The browser cookie `ailk-consent` stays the operative switch (C3) — this
+ * route only records the choice.
+ *
+ * Logs carry `{ event, outcome }` only: never a visitor id or a statement.
+ *
+ * MCP parity note: no MCP twin, a recorded exception — it logs a browser's
+ * banner choice against a browser-held id, and an agent holds neither
+ * (tests/parity/README.md).
+ */
+import { consentCookieBodySchema } from "@working-theory/validation";
+import type { FastifyPluginAsync } from "fastify";
+
+import { recordCookieChoice } from "../../services/consent.js";
+import { resolvePublicWorkspace } from "../../services/public-site-resolver.js";
+
+const EVENT = "consent-cookie";
+
+export const consentCookieRoute: FastifyPluginAsync = async (fastify) => {
+  fastify.post("/v1/consent/cookie", async (request, reply) => {
+    const body = consentCookieBodySchema.safeParse(request.body);
+    if (!body.success) {
+      return reply.status(400).send({
+        error: "invalid_input",
+        message: "The request was not valid.",
+      });
+    }
+    if (!process.env["DATABASE_URL"]) {
+      return reply.status(503).send({
+        error: "consent_store_unavailable",
+        message: "Consent cannot be recorded on this site.",
+      });
+    }
+
+    const site = await resolvePublicWorkspace(request);
+    if (site.kind !== "resolved") {
+      request.log.warn(
+        { event: EVENT, outcome: "tenant_unresolved" },
+        "[consent] refused",
+      );
+      return reply.status(503).send({
+        error: "tenant_unresolved",
+        message: "This site is not configured to record consent.",
+      });
+    }
+
+    try {
+      const result = await recordCookieChoice({
+        workspaceId: site.workspaceId,
+        visitorId: body.data.visitorId,
+        choice: body.data.choice,
+        locale: body.data.locale,
+      });
+      request.log.info(
+        { event: EVENT, outcome: result.recorded ? "recorded" : "unchanged" },
+        "[consent] cookie choice",
+      );
+      return reply
+        .status(result.recorded ? 201 : 200)
+        .send({ recorded: result.recorded });
+    } catch {
+      request.log.error(
+        { event: EVENT, outcome: "failed" },
+        "[consent] cookie choice failed",
+      );
+      return reply.status(503).send({
+        error: "consent_store_unavailable",
+        message: "Consent cannot be recorded right now.",
+      });
+    }
+  });
+};