create-ailk 0.18.0 → 0.19.1

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

@@ -0,0 +1,18 @@
+/**
+ * The consent routes (#8438, spec
+ * docs/specs/8438-consent-registry-and-ledger-step-spec.md D5, D8, D9).
+ *
+ *   cookie.ts       POST /v1/consent/cookie       — the banner's log
+ *   unsubscribe.ts  POST /v1/consent/unsubscribe  — a signed link's landing
+ *   platform.ts     GET/POST /v1/consent/platform — the Admin owner's
+ *                   consents to Working Theory (multi-tenant module only)
+ *
+ * The first two are the never-gated privacy floor: registered at the top
+ * level, each in its OWN rate-limited scope (`consent`, `unsubscribe`) so
+ * filling one never blocks the other, and both on the forwarded-visitor
+ * route list (`middleware/rate-limit.ts`). This barrel re-exports exactly
+ * those two; the platform routes belong to the multi-tenant slice and are
+ * loaded only through `server.ts`'s slice table.
+ */
+export { consentCookieRoute } from "./cookie.js";
+export { consentUnsubscribeRoute } from "./unsubscribe.js";

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

@@ -0,0 +1,127 @@
+/**
+ * The one unsubscribe landing every email link will call (#8438, spec
+ * docs/specs/8438-consent-registry-and-ledger-step-spec.md D9, SEC-8438-9).
+ *
+ *   POST /v1/consent/unsubscribe
+ *       `{ token }` — a signed token minted by `consentUnsubscribeToken`.
+ *       Withdraws the communications purpose it names for the Person it
+ *       names, source `email_unsubscribe`, unless the Person's own and
+ *       any-source readings both already say "not granted". Answers `200 { purpose: { id, description },
+ *       changed }`; a second click is `changed: false` with nothing written.
+ *
+ * The token is the only authority: it names no email, and a forged one fails
+ * its HMAC. Any defect — a flipped character, another workspace's Person, a
+ * purpose that is not a communications consent or preference, a token older
+ * than 400 days, a malformed body — is ONE uniform `400 invalid_link`. With
+ * `AILK_CONSENT_LINK_SECRET` unset or under 32 bytes the route answers `503
+ * link_secret_not_configured` (the 503/400 split tells an outsider only
+ * whether the feature is configured, which the absence of links in mail
+ * already shows — accepted in SEC-8438-9).
+ *
+ * Registered at the top level in its own rate-limited scope (`unsubscribe`),
+ * outside every module gate, beside the cookie route. The page that calls it
+ * (apps/web `/unsubscribe`) performs no write on GET, so a mail scanner's
+ * prefetch changes nothing.
+ *
+ * Logs carry `{ event, outcome }` only: never a token, an id or a statement.
+ *
+ * MCP parity note: no MCP twin — the route is a capability link's own
+ * landing, the `/v1/deliverables/:grantId` footing (tests/parity/README.md).
+ */
+import {
+  consentPurposeById,
+  consentPurposeKind,
+  consentUnsubscribeBodySchema,
+  resolveLocalizedString,
+} from "@working-theory/validation";
+import type { FastifyPluginAsync } from "fastify";
+
+import {
+  consentConfigForSite,
+  consentLinkSecretConfigured,
+  consentPersonExists,
+  recordPersonConsent,
+  verifyConsentUnsubscribeToken,
+} from "../../services/consent.js";
+
+const EVENT = "consent-unsubscribe";
+
+const INVALID_LINK = {
+  error: "invalid_link",
+  message: "This link isn't valid.",
+} as const;
+
+export const consentUnsubscribeRoute: FastifyPluginAsync = async (fastify) => {
+  fastify.post("/v1/consent/unsubscribe", async (request, reply) => {
+    if (!consentLinkSecretConfigured()) {
+      request.log.warn(
+        { event: EVENT, outcome: "secret_missing" },
+        "[consent] refused",
+      );
+      return reply.status(503).send({
+        error: "link_secret_not_configured",
+        message: "Unsubscribing isn't available on this site.",
+      });
+    }
+    const refuse = (outcome: string) => {
+      request.log.warn({ event: EVENT, outcome }, "[consent] refused");
+      return reply.status(400).send(INVALID_LINK);
+    };
+
+    const body = consentUnsubscribeBodySchema.safeParse(request.body);
+    if (!body.success) return refuse("invalid_body");
+    const claims = verifyConsentUnsubscribeToken(body.data.token);
+    if (claims === null) return refuse("invalid_token");
+
+    try {
+      const config = await consentConfigForSite(claims.workspaceId);
+      const purpose = consentPurposeById(config, claims.purposeId);
+      if (
+        !purpose ||
+        purpose.area !== "communications" ||
+        consentPurposeKind(purpose) === "agreement"
+      ) {
+        return refuse("purpose_not_unsubscribable");
+      }
+      if (!(await consentPersonExists(claims.workspaceId, claims.personId))) {
+        return refuse("person_unknown");
+      }
+
+      const result = await recordPersonConsent({
+        workspaceId: claims.workspaceId,
+        personId: claims.personId,
+        purposeId: purpose.id,
+        granted: false,
+        source: "email_unsubscribe",
+        locale: "en",
+        config,
+        subject: { subjectType: "person", subjectId: claims.personId },
+      });
+      if (!result.ok) return refuse(result.code);
+
+      request.log.info(
+        { event: EVENT, outcome: result.changed ? "withdrawn" : "unchanged" },
+        "[consent] unsubscribe",
+      );
+      return reply.send({
+        purpose: {
+          id: purpose.id,
+          description:
+            purpose.description === undefined
+              ? purpose.id
+              : resolveLocalizedString(purpose.description, "en", "en"),
+        },
+        changed: result.changed,
+      });
+    } catch {
+      request.log.error(
+        { event: EVENT, outcome: "failed" },
+        "[consent] unsubscribe failed",
+      );
+      return reply.status(503).send({
+        error: "consent_store_unavailable",
+        message: "Unsubscribing isn't available right now.",
+      });
+    }
+  });
+};

package/templates/apps/api/src/routes/leads/index.ts

@@ -71,6 +71,10 @@ import type { FastifyPluginAsync } from "fastify";
 
 import { acceptsKind, resolveLeadDelivery } from "../../lib/lead-delivery.js";
 import { currentSiteId, resolveSiteWorkspaceId } from "../../lib/site.js";
+import {
+  CONSENT_VISITOR_HEADER,
+  consentVisitorFromHeader,
+} from "../../services/consent.js";
 import {
   type LeadKind,
   type RouteLeadInput,
@@ -245,6 +249,21 @@ function makeLeadsRoute(kind: LeadKind): FastifyPluginAsync {
         }
       }
 
+      // #8185 D3 — a spoke's same-origin relay marks every forwarded call.
+      // The mark can only remove the spoke-checkout marker, never grant it.
+      sourceMeta.relayed = request.headers["x-ailk-relayed"] !== undefined;
+
+      // #8438 D11 — the cookie banner's visitor id, forwarded by the site's
+      // own server from its first-party cookie. Only a v4 UUID counts; the
+      // header is never echoed or logged. It links the visitor to the
+      // lead's Person after the write, and changes nothing about the answer.
+      const consentVisitorId = consentVisitorFromHeader(
+        request.headers[CONSENT_VISITOR_HEADER],
+      );
+      if (consentVisitorId !== undefined) {
+        sourceMeta.consentVisitorId = consentVisitorId;
+      }
+
       const result = await routeLead(
         buildInput(kind, body, workspaceId),
         sourceMeta,

package/templates/apps/api/src/routes/project-listings/__tests__/drafts.test.ts

@@ -516,6 +516,10 @@ describe("the draft lifecycle (#5036 D1)", () => {
       locale: "en",
       statement,
       statementHash: sha256(statement),
+      // #8438 D3 — a listing names no magnet slug, so the source is `api`.
+      source: "api",
+      personId: null,
+      policyVersion: 1,
     });
     expect(data[0]!["statement"]).not.toBe(UNRECOVERABLE_CONSENT_STATEMENT);
     // The row's own consentAt is untouched by the grant write (spec §2.3).
@@ -539,6 +543,7 @@ describe("the draft lifecycle (#5036 D1)", () => {
       locale: "und",
       statement: UNRECOVERABLE_CONSENT_STATEMENT,
       statementHash: sha256(UNRECOVERABLE_CONSENT_STATEMENT),
+      source: "api",
     });
     // Never today's wording for a legacy call — that would fabricate evidence (D11).
     expect(data[0]!["statement"]).not.toContain("You agree to being contacted");

package/templates/apps/api/src/routes/webhooks/__tests__/stripe-flow-checkout.test.ts

@@ -52,6 +52,15 @@ jest.mock("@working-theory/stripe-client", () => ({
   WEBHOOK_TOLERANCE_SECONDS: 300,
 }));
 
+// #8450 D10 — the handler drops an event whose livemode is not the process's,
+// so the Person cases below run the process in their event's own mode.
+let mockKeyMode: "test" | "live" = "test";
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../../lib/stripe.js", () => ({
+  ...jest.requireActual("../../../lib/stripe.js"),
+  stripeKeyMode: () => mockKeyMode,
+}));
+
 import * as configModule from "../../../config/index.js";
 import { stripeWebhookHandler } from "../stripe.js";
 import { __resetIdempotencyStore } from "../../../lib/webhook-idempotency.js";
@@ -115,6 +124,7 @@ let server: FastifyInstance;
 
 beforeEach(async () => {
   jest.clearAllMocks();
+  mockKeyMode = "test";
   logCalls.length = 0;
   __resetIdempotencyStore();
   jest.replaceProperty(configModule, "config", {
@@ -349,10 +359,13 @@ describe("the hub checkout's Person (#852 D6, AC-3)", () => {
     logCalls.filter(
       (c) => typeof c[0] === "object" && c[0] !== null && String((c[0] as { outcome?: string }).outcome).startsWith("person_"),
     );
-  const liveEvent = (livemode: boolean, object: Record<string, unknown> = {}) => ({
-    ...sessionEvent("checkout.session.completed", { customer: "cus_9", ...object }),
-    livemode,
-  });
+  const liveEvent = (livemode: boolean, object: Record<string, unknown> = {}) => {
+    mockKeyMode = livemode ? "live" : "test";
+    return {
+      ...sessionEvent("checkout.session.completed", { customer: "cus_9", ...object }),
+      livemode,
+    };
+  };
 
   beforeEach(() => {
     (prisma.flowCheckout.findFirst as jest.Mock).mockResolvedValue({ leadId: LEAD, workspaceId: WORKSPACE });

package/templates/apps/api/src/routes/webhooks/__tests__/stripe-idempotency.test.ts

@@ -57,6 +57,8 @@ jest.mock("../../../lib/stripe.js", () => ({
   verifyWebhookSignature: (...args: unknown[]) =>
     mockVerifyWebhookSignature(...args),
   StripeWebhookSignatureError: MockStripeWebhookSignatureError,
+  // #8450 D10 — the handler compares each event's livemode with this.
+  stripeKeyMode: () => "test",
 }));
 
 import { stripeWebhookHandler } from "../stripe.js";

package/templates/apps/api/src/routes/webhooks/__tests__/stripe-livemode-live.test.ts

@@ -0,0 +1,159 @@
+/**
+ * POST /api/webhooks/stripe — the livemode guard, live-mode process (#8450
+ * D10; #6852 SEC-03). The mirror of `stripe-livemode.test.ts`.
+ *
+ * `lib/stripe.ts` runs as itself except `stripeKeyMode`, which answers
+ * `"live"` — the state `build()` leaves a process in after admitting a
+ * restricted live key. A signed event whose `livemode` is `false` (a
+ * test-mode event, forgeable by anyone holding the test key) is answered
+ * 200, writes nothing, is not marked seen and logs one `livemode_mismatch`
+ * warn; the same event with `livemode: true` reaches its arm.
+ *
+ * The stripe-site-filter.test.ts harness: the commerce claim mocked present,
+ * the prisma manual mock, the idempotency store reset per test.
+ */
+import type { FastifyInstance } from "fastify";
+import Fastify from "fastify";
+
+jest.mock("@working-theory/license", () => ({
+  checkLicense: jest.fn().mockResolvedValue({
+    tier: "pro",
+    plan: "pro-monthly",
+    features: ["commerce"],
+    expiresAt: null,
+    revoked: false,
+  }),
+}));
+
+jest.mock("@working-theory/analytics/server", () => ({
+  track: jest.fn().mockResolvedValue(undefined),
+}));
+
+// eslint-disable-next-line no-restricted-syntax -- lib/prisma.ts wraps the external DB boundary (PrismaClient requires a live connection); __mocks__/prisma.ts is the repo-standard test double for this boundary.
+jest.mock("../../../lib/prisma.js");
+
+const mockVerifyWebhookSignature = jest.fn();
+jest.mock("@working-theory/stripe-client", () => ({
+  ...jest.requireActual("@working-theory/stripe-client"),
+  verifyWebhookSignature: (...args: unknown[]) => mockVerifyWebhookSignature(...args),
+}));
+
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../../lib/stripe.js", () => ({
+  ...jest.requireActual("../../../lib/stripe.js"),
+  stripeKeyMode: () => "live",
+}));
+
+import * as configModule from "../../../config/index.js";
+import { prisma } from "../../../lib/prisma.js";
+import { __resetIdempotencyStore, hasSeen } from "../../../lib/webhook-idempotency.js";
+import { stripeWebhookHandler } from "../stripe.js";
+
+const EVENT_ID = "evt_livemode_12345678";
+
+function customerCreated(livemode: boolean) {
+  return {
+    id: EVENT_ID,
+    type: "customer.created",
+    livemode,
+    data: {
+      object: {
+        id: "cus_livemode_fixture",
+        email: "client@example.com",
+        metadata: { ailk_user_id: "usr_livemode" },
+      },
+    },
+  };
+}
+
+type LogCall = [unknown, string?];
+const logCalls: LogCall[] = [];
+
+async function buildTestServer(): Promise<FastifyInstance> {
+  const server = Fastify({ logger: false });
+  await server.register(async (webhooksScope) => {
+    webhooksScope.addContentTypeParser("application/json", { parseAs: "buffer" }, (_req, body, done) => {
+      done(null, body);
+    });
+    webhooksScope.addHook("onRequest", async (request) => {
+      for (const level of ["info", "warn", "error"] as const) {
+        const original = request.log[level].bind(request.log);
+        request.log[level] = ((...args: unknown[]) => {
+          logCalls.push(args as LogCall);
+          return (original as (...a: unknown[]) => void)(...args);
+        }) as typeof request.log.info;
+      }
+    });
+    webhooksScope.post("/v1/webhooks/stripe", stripeWebhookHandler);
+  });
+  await server.ready();
+  return server;
+}
+
+function mismatchLogs(): LogCall[] {
+  return logCalls.filter(
+    ([obj]) =>
+      typeof obj === "object" && obj !== null && (obj as Record<string, unknown>)["outcome"] === "livemode_mismatch",
+  );
+}
+
+let server: FastifyInstance;
+
+beforeEach(async () => {
+  jest.clearAllMocks();
+  logCalls.length = 0;
+  __resetIdempotencyStore();
+  jest.replaceProperty(configModule, "config", {
+    ...configModule.config,
+    STRIPE_WEBHOOK_SECRET: "whsec_test_secret",
+  });
+  (prisma.user.findFirst as jest.Mock).mockResolvedValue(null);
+  (prisma.user.findUnique as jest.Mock).mockResolvedValue(null);
+  server = await buildTestServer();
+});
+
+afterEach(async () => {
+  await server.close();
+  jest.restoreAllMocks();
+});
+
+async function post() {
+  return server.inject({
+    method: "POST",
+    url: "/v1/webhooks/stripe",
+    payload: Buffer.from(JSON.stringify({ type: "test" })),
+    headers: { "content-type": "application/json", "stripe-signature": "t=1234,v1=abc" },
+  });
+}
+
+describe("stripe webhook — livemode guard in a live-mode process (#8450 D10)", () => {
+  it("drops a test-mode event: 200, no write, not marked seen, one warn", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(customerCreated(false));
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({ received: true });
+    expect(prisma.user.findFirst).not.toHaveBeenCalled();
+    expect(prisma.user.findUnique).not.toHaveBeenCalled();
+    expect(prisma.user.update).not.toHaveBeenCalled();
+    expect(hasSeen(EVENT_ID)).toBe(false);
+    expect(mismatchLogs()).toHaveLength(1);
+    expect(mismatchLogs()[0]?.[0]).toEqual({
+      eventType: "customer.created",
+      eventIdPrefix: EVENT_ID.substring(0, 8),
+      outcome: "livemode_mismatch",
+    });
+  });
+
+  it("handles a live-mode event: it reaches its arm and is marked seen", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(customerCreated(true));
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(prisma.user.findFirst).toHaveBeenCalled();
+    expect(hasSeen(EVENT_ID)).toBe(true);
+    expect(mismatchLogs()).toHaveLength(0);
+  });
+});

package/templates/apps/api/src/routes/webhooks/__tests__/stripe-livemode.test.ts

@@ -0,0 +1,158 @@
+/**
+ * POST /api/webhooks/stripe — the livemode guard, test-mode process (#8450
+ * D10; #6852 SEC-03).
+ *
+ * The real `lib/stripe.ts` runs over the package mocked for
+ * `verifyWebhookSignature` only, and nothing admits a live key, so the
+ * process is in test mode: a signed event whose `livemode` is `true` is
+ * answered 200, writes nothing, is not marked seen and logs one
+ * `livemode_mismatch` warn; the same event with `livemode: false` reaches
+ * its arm. The live-mode mirror is `stripe-livemode-live.test.ts`.
+ *
+ * The stripe-site-filter.test.ts harness: the commerce claim mocked present,
+ * the prisma manual mock, the idempotency store reset per test.
+ */
+import type { FastifyInstance } from "fastify";
+import Fastify from "fastify";
+
+jest.mock("@working-theory/license", () => ({
+  checkLicense: jest.fn().mockResolvedValue({
+    tier: "pro",
+    plan: "pro-monthly",
+    features: ["commerce"],
+    expiresAt: null,
+    revoked: false,
+  }),
+}));
+
+jest.mock("@working-theory/analytics/server", () => ({
+  track: jest.fn().mockResolvedValue(undefined),
+}));
+
+// eslint-disable-next-line no-restricted-syntax -- lib/prisma.ts wraps the external DB boundary (PrismaClient requires a live connection); __mocks__/prisma.ts is the repo-standard test double for this boundary.
+jest.mock("../../../lib/prisma.js");
+
+const mockVerifyWebhookSignature = jest.fn();
+jest.mock("@working-theory/stripe-client", () => ({
+  ...jest.requireActual("@working-theory/stripe-client"),
+  verifyWebhookSignature: (...args: unknown[]) => mockVerifyWebhookSignature(...args),
+}));
+
+import * as configModule from "../../../config/index.js";
+import { prisma } from "../../../lib/prisma.js";
+import { stripeKeyMode } from "../../../lib/stripe.js";
+import { __resetIdempotencyStore, hasSeen } from "../../../lib/webhook-idempotency.js";
+import { stripeWebhookHandler } from "../stripe.js";
+
+const EVENT_ID = "evt_livemode_12345678";
+
+function customerCreated(livemode: boolean) {
+  return {
+    id: EVENT_ID,
+    type: "customer.created",
+    livemode,
+    data: {
+      object: {
+        id: "cus_livemode_fixture",
+        email: "client@example.com",
+        metadata: { ailk_user_id: "usr_livemode" },
+      },
+    },
+  };
+}
+
+type LogCall = [unknown, string?];
+const logCalls: LogCall[] = [];
+
+async function buildTestServer(): Promise<FastifyInstance> {
+  const server = Fastify({ logger: false });
+  await server.register(async (webhooksScope) => {
+    webhooksScope.addContentTypeParser("application/json", { parseAs: "buffer" }, (_req, body, done) => {
+      done(null, body);
+    });
+    webhooksScope.addHook("onRequest", async (request) => {
+      for (const level of ["info", "warn", "error"] as const) {
+        const original = request.log[level].bind(request.log);
+        request.log[level] = ((...args: unknown[]) => {
+          logCalls.push(args as LogCall);
+          return (original as (...a: unknown[]) => void)(...args);
+        }) as typeof request.log.info;
+      }
+    });
+    webhooksScope.post("/v1/webhooks/stripe", stripeWebhookHandler);
+  });
+  await server.ready();
+  return server;
+}
+
+function mismatchLogs(): LogCall[] {
+  return logCalls.filter(
+    ([obj]) =>
+      typeof obj === "object" && obj !== null && (obj as Record<string, unknown>)["outcome"] === "livemode_mismatch",
+  );
+}
+
+let server: FastifyInstance;
+
+beforeEach(async () => {
+  jest.clearAllMocks();
+  logCalls.length = 0;
+  __resetIdempotencyStore();
+  jest.replaceProperty(configModule, "config", {
+    ...configModule.config,
+    STRIPE_WEBHOOK_SECRET: "whsec_test_secret",
+  });
+  (prisma.user.findFirst as jest.Mock).mockResolvedValue(null);
+  (prisma.user.findUnique as jest.Mock).mockResolvedValue(null);
+  server = await buildTestServer();
+});
+
+afterEach(async () => {
+  await server.close();
+  jest.restoreAllMocks();
+});
+
+async function post() {
+  return server.inject({
+    method: "POST",
+    url: "/v1/webhooks/stripe",
+    payload: Buffer.from(JSON.stringify({ type: "test" })),
+    headers: { "content-type": "application/json", "stripe-signature": "t=1234,v1=abc" },
+  });
+}
+
+describe("stripe webhook — livemode guard in a test-mode process (#8450 D10)", () => {
+  it("the process is in test mode", () => {
+    expect(stripeKeyMode()).toBe("test");
+  });
+
+  it("drops a live-mode event: 200, no write, not marked seen, one warn", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(customerCreated(true));
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({ received: true });
+    expect(prisma.user.findFirst).not.toHaveBeenCalled();
+    expect(prisma.user.findUnique).not.toHaveBeenCalled();
+    expect(prisma.user.update).not.toHaveBeenCalled();
+    expect(hasSeen(EVENT_ID)).toBe(false);
+    expect(mismatchLogs()).toHaveLength(1);
+    expect(mismatchLogs()[0]?.[0]).toEqual({
+      eventType: "customer.created",
+      eventIdPrefix: EVENT_ID.substring(0, 8),
+      outcome: "livemode_mismatch",
+    });
+  });
+
+  it("handles a test-mode event as before: it reaches its arm and is marked seen", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(customerCreated(false));
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(prisma.user.findFirst).toHaveBeenCalled();
+    expect(hasSeen(EVENT_ID)).toBe(true);
+    expect(mismatchLogs()).toHaveLength(0);
+  });
+});

package/templates/apps/api/src/routes/webhooks/__tests__/stripe-rate-limit.test.ts

@@ -60,6 +60,8 @@ jest.mock("../../../lib/stripe.js", () => ({
   verifyWebhookSignature: (...args: unknown[]) =>
     mockVerifyWebhookSignature(...args),
   StripeWebhookSignatureError: MockStripeWebhookSignatureError,
+  // #8450 D10 — the handler compares each event's livemode with this.
+  stripeKeyMode: () => "test",
 }));
 
 import { webhooksRoutes } from "../index.js";

package/templates/apps/api/src/routes/webhooks/stripe.ts

@@ -104,6 +104,7 @@ import {
   SITE_STAMP_KEY,
 } from "../../lib/site.js";
 import {
+  stripeKeyMode,
   StripeWebhookSignatureError,
   toSubscriptionLifecycleStatus,
   verifyWebhookSignature,
@@ -274,6 +275,22 @@ export const stripeWebhookHandler = async (
 
   const event = settled.event;
   const eventIdPrefix = event.id.substring(0, 8);
+
+  // #8450 D10 (#6852 SEC-03) — an event whose livemode is not the key class
+  // this process admitted is never one of its own: a live hub must not act on
+  // a test-mode event anyone with the test key can forge, nor a test hub on a
+  // live one. Dropped before the idempotency check and any write; 200 so
+  // Stripe stops retrying, and NOT marked seen, so a corrected deployment
+  // still accepts a redelivery.
+  if ((event.livemode === true) !== (stripeKeyMode() === "live")) {
+    request.log.warn(
+      { eventType: event.type, eventIdPrefix, outcome: "livemode_mismatch" },
+      "stripe webhook event dropped — livemode differs from the admitted key class",
+    );
+    await reply.code(200).send({ received: true });
+    return;
+  }
+
   request.log.info(
     { eventType: event.type, eventIdPrefix },
     "stripe webhook event received",