create-ailk 0.19.0 → 0.20.0

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.",
+      });
+    }
+  });
+};

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,
@@ -249,6 +253,17 @@ function makeLeadsRoute(kind: LeadKind): FastifyPluginAsync {
       // 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/README.md

@@ -163,13 +163,41 @@ through `metadata.site`.
   open (a session lives up to 24 hours). A session whose stamp no longer
   matches is acked as foreign and never retried, so its hub side effects are
   lost; the `stamp` / `ownSite` pair in the log line is how to spot that drift.
-- **Not filtered.** `customer.*`, `invoice.*` and subscription events carry no
-  session metadata and are handled as before. Filtering them needs a stamp on
-  those objects, which the spoke-checkout package writes (spoke pattern
-  Phase 3).
+  A subscription keeps its stamp for its whole life and each finalized
+  invoice keeps an immutable copy of it, so a slug collision or a mis-stamp
+  on those lasts as long as the subscription — not the 24 hours a session
+  lives.
+- **Billing events (#8024).** One gate before the event switch applies the
+  same test to every `customer.*`, `customer.subscription.*` and `invoice.*`
+  event, handled type or not. It reads the stamp from the event object's own
+  metadata — the Subscription's (where spoke-checkout writes `site` through
+  `subscription_data.metadata`) or the Customer's — and, for an invoice, from
+  its own metadata, then the subscription snapshot under
+  `parent.subscription_details.metadata` (the pinned API version), then the
+  top-level `subscription_details.metadata` (an endpoint on a pre-`basil`
+  version). Any foreign source makes the event foreign; the first is logged.
+  A source is read only when `data.object.object` is the family's own type
+  (`subscription`, `customer`, `invoice`), so a `customer.source.*` card or a
+  `customer.tax_id.*` object is never read. A foreign event answers 200,
+  logs `outcome: "foreign_site"` (the same five fields), writes nothing — no
+  billing bind, request-paid stamp or dunning record — and is marked seen.
+  The decision uses the payload alone: no Stripe call.
+- **What stays unstamped.** The filter cannot see a stamp nobody wrote, so
+  these are still handled as the hub's own, exactly as before: spoke
+  customers (Checkout cannot put metadata on a customer it creates); quoted
+  spoke subscriptions and their invoices (`createQuotedCheckoutSession`
+  sends no `subscription_data` yet); a fixed spoke subscription whose `site`
+  was later removed; spoke subscriptions created before the stamp shipped,
+  or through a Payment Link or the Dashboard; and the billing app's sessions
+  and subscriptions on the shared account. Where such a subscription sits on
+  a hub User's own Stripe customer (a known buyer reused by a spoke), its
+  events keep reaching that User's dunning record.
 - **A label, not a boundary.** The stamp is written by whoever holds the
   account's secret key. It separates cooperating sites on one account, not
-  tenants.
+  tenants. Whoever holds a write key on the account can also make the hub
+  skip one of its own objects' billing events by stamping it with another
+  site, which silences the hub's dunning record for that subscription — the
+  same key can already cancel or re-price it outright.
 
 ## Dunning (#6034)
 

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