create-ailk 0.22.0 → 0.24.0

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

@@ -0,0 +1,814 @@
+/**
+ * POST /v1/webhooks/stripe/:connectionToken — the per-Organization Stripe
+ * webhook (#8932; spec docs/specs/8932-the-per-organization-stripe-webhook-spec.md
+ * AC-1 … AC-4, AC-6, AC-7; contract W-T1, W-T2, W-T3).
+ *
+ * The shared harness (spec §5): one Fastify instance with the webhooks
+ * raw-body parser, `registerErrorSerializer`, and `webhooksRoutes` itself —
+ * so the rate-limit plugin, the token route and the legacy route are
+ * registered exactly as production registers them — with a logger whose
+ * `req` serializer is `requestLogSerializer` and whose stream captures every
+ * line. Mocked: the connection custody, the session record, the Stripe
+ * verify functions and key mode, the commerce claim, `routeLead`, prisma
+ * (the manual mock) and `@working-theory/observability`'s logger (spied).
+ */
+import { logger } from "@working-theory/observability";
+import Fastify, { type FastifyInstance } from "fastify";
+
+jest.mock("@working-theory/analytics/server", () => ({
+  track: jest.fn().mockResolvedValue(undefined),
+}));
+// `server.ts` (for `requestLogSerializer`) reaches the email package, whose
+// React Email dependency is ESM-only.
+jest.mock("@working-theory/email", () => ({
+  sendLeadNotification: jest.fn().mockResolvedValue({ ok: true }),
+}));
+
+// 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 mockFindConnection = jest.fn();
+const mockClientForOrganization = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- the connection custody wraps the database and the AES-GCM key (#8907); the spec's harness (§5) stubs its two answers.
+jest.mock("../../../services/offerings/connection.js", () => ({
+  findStripeConnectionByWebhookToken: (...args: unknown[]) => mockFindConnection(...args),
+  stripeClientForOrganization: (...args: unknown[]) => mockClientForOrganization(...args),
+}));
+
+const mockReadRecord = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- the session record wraps the database (#8930); the spec's harness (§5) stubs its three answers.
+jest.mock("../../../services/offerings/checkout-session-record.js", () => ({
+  readCheckoutSessionRecord: (...args: unknown[]) => mockReadRecord(...args),
+}));
+
+const mockRouteLead = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- routeLead is the seam the route hands its lead to; its own behaviour is proved in lead-routing.test.ts (AC-5).
+jest.mock("../../../services/lead-routing.js", () => ({
+  routeLead: (...args: unknown[]) => mockRouteLead(...args),
+}));
+
+const mockVerifyKeyless = jest.fn();
+const mockVerifyEnv = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- lib/stripe.ts is apps/api's one Stripe SDK boundary; the verify and the boot-time key mode are stubbed there.
+jest.mock("../../../lib/stripe.js", () => ({
+  ...jest.requireActual("../../../lib/stripe.js"),
+  stripeKeyMode: () => "live",
+  verifyWebhookSignature: (...args: unknown[]) => mockVerifyEnv(...args),
+  verifyWebhookSignatureKeyless: (...args: unknown[]) => mockVerifyKeyless(...args),
+}));
+
+const mockClaim = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- the commerce claim wraps the licence JWT read; stubbing its tri-state drives ladder steps 4 and 5.
+jest.mock("../../../lib/require-commerce-claim.js", () => ({
+  ...jest.requireActual("../../../lib/require-commerce-claim.js"),
+  resolveCommerceClaim: () => mockClaim(),
+}));
+
+import * as configModule from "../../../config/index.js";
+import { registerErrorSerializer } from "../../../lib/error-serializer.js";
+import { prisma } from "../../../lib/prisma.js";
+import { StripeWebhookSignatureError } from "../../../lib/stripe.js";
+import {
+  __resetIdempotencyStore,
+  hasSeen,
+  hasSeenForOrganization,
+} from "../../../lib/webhook-idempotency.js";
+import { requestLogSerializer } from "../../../server.js";
+import { STRIPE_OFFERINGS_WEBHOOK_RATE_LIMIT_PER_MIN, webhooksRoutes } from "../index.js";
+
+// ── Fixture (spec §5 "The shared harness") ────────────────────────────────────
+
+const TOKEN_A = "Tk8932aaaaBBBBccccDDDDeeeeFFFFgggg_HHHH-iii"; // 43 chars
+const WHSEC_A = "whsec_A8932secret";
+const ORG_A = "org_00000000-0000-7000-8000-00000000893a";
+const ORG_B = "org_00000000-0000-7000-8000-00000000893b";
+const WS_A = "wksp_00000000-0000-7000-8000-00000000893a";
+const WS_A2 = "wksp_00000000-0000-7000-8000-00000000893c";
+const SESSION = "cs_live_a1B2c3D4e5F6g7H8i9J0k8932"; // gitleaks:allow -- a synthetic Checkout Session id shape (#8932), not a credential
+const PRICE_A = "price_A8932aaaa";
+const PRICE_B = "price_B8932bbbb";
+const EMAIL = "buyer@example.com";
+const LOOKUP_KEY = "growth_monthly";
+const TERMS = "account_terms@1";
+const EVENT_ID = "evt_1Q8932E1xxxxxxxxxxxxxx";
+const EVENT_ID_2 = "evt_1Q8932E2yyyyyyyyyyyyyy";
+const RECORD = {
+  sessionId: SESSION,
+  workspaceId: WS_A,
+  organizationId: ORG_A,
+  priceId: PRICE_A,
+  lookupKey: LOOKUP_KEY,
+  mode: "live" as const,
+  createdAt: new Date("2026-10-18T00:00:00Z"),
+};
+const RAW_BODY = Buffer.from(JSON.stringify({ any: "signed bytes" }));
+
+type Json = Record<string, unknown>;
+
+function sessionEvent(overrides: {
+  id?: string;
+  type?: string;
+  livemode?: boolean;
+  metadata?: Json | null;
+  object?: Json;
+} = {}): Json {
+  return {
+    id: overrides.id ?? EVENT_ID,
+    type: overrides.type ?? "checkout.session.completed",
+    livemode: overrides.livemode ?? true,
+    data: {
+      object: {
+        object: "checkout.session",
+        id: SESSION,
+        payment_status: "paid",
+        amount_total: 4900,
+        currency: "usd",
+        customer: "cus_8932buyer",
+        customer_details: { email: EMAIL },
+        consent: { terms_of_service: "accepted" },
+        metadata:
+          overrides.metadata === undefined
+            ? { site: WS_A, ailk_offering: LOOKUP_KEY, ailk_terms: TERMS }
+            : overrides.metadata,
+        ...overrides.object,
+      },
+    },
+  };
+}
+
+const listLineItems = jest.fn();
+function okClient() {
+  return { kind: "ok", mode: "live", client: { checkout: { sessions: { listLineItems } } } };
+}
+function lineItems(...priceIds: string[]) {
+  return {
+    data: priceIds.map((id) => ({ price: { id }, description: "Growth <b>Plan</b>" })),
+  };
+}
+
+// ── Log capture ──────────────────────────────────────────────────────────────
+
+const lines: string[] = [];
+const loggerLines: unknown[][] = [];
+const PINO_KEYS = new Set(["level", "time", "pid", "hostname", "reqId", "msg"]);
+
+/** The handler's own lines: the request-bound lines carrying an `outcome`. */
+function handlerLines(from = 0): Json[] {
+  return lines
+    .slice(from)
+    .map((l) => JSON.parse(l) as Json)
+    .filter((l) => "outcome" in l);
+}
+/** A handler line's own keys — pino's bookkeeping keys removed. */
+function keysOf(line: Json): string[] {
+  return Object.keys(line)
+    .filter((k) => !PINO_KEYS.has(k))
+    .sort();
+}
+const EVENT_KEYS = ["eventIdPrefix", "eventType", "organizationId", "outcome"];
+
+let server: FastifyInstance;
+
+async function buildTestServer(): Promise<FastifyInstance> {
+  const app = Fastify({
+    logger: {
+      level: "info",
+      serializers: { req: requestLogSerializer },
+      stream: { write: (msg: string) => lines.push(msg) },
+    },
+  });
+  registerErrorSerializer(app);
+  await app.register(async (webhooksScope) => {
+    webhooksScope.addContentTypeParser(
+      "application/json",
+      { parseAs: "buffer" },
+      (_req, body, done) => done(null, body),
+    );
+    await webhooksScope.register(webhooksRoutes);
+  });
+  await app.ready();
+  return app;
+}
+
+beforeEach(async () => {
+  jest.clearAllMocks();
+  lines.length = 0;
+  loggerLines.length = 0;
+  __resetIdempotencyStore();
+  jest.replaceProperty(configModule, "config", {
+    ...configModule.config,
+    STRIPE_WEBHOOK_SECRET: "whsec_legacy_env",
+  });
+  for (const level of ["debug", "info", "warn", "error"] as const) {
+    jest.spyOn(logger, level).mockImplementation(((...args: unknown[]) => {
+      loggerLines.push(args);
+    }) as never);
+  }
+  mockFindConnection.mockImplementation(async (token: unknown) =>
+    token === TOKEN_A
+      ? { kind: "ok", organizationId: ORG_A, mode: "live", webhookSecret: WHSEC_A }
+      : { kind: "not-found" },
+  );
+  mockClientForOrganization.mockResolvedValue(okClient());
+  listLineItems.mockResolvedValue(lineItems(PRICE_A));
+  mockReadRecord.mockResolvedValue(RECORD);
+  mockClaim.mockResolvedValue("claimed");
+  mockVerifyKeyless.mockReturnValue(sessionEvent());
+  mockVerifyEnv.mockReturnValue(sessionEvent());
+  mockRouteLead.mockResolvedValue({
+    ok: true,
+    id: "lead_8932",
+    persisted: "db",
+    email: { skipped: true, reason: "env_unset" },
+  });
+  (prisma.callback.updateMany as jest.Mock).mockResolvedValue({ count: 0 });
+  server = await buildTestServer();
+});
+
+afterEach(async () => {
+  await server.close();
+  jest.restoreAllMocks();
+});
+
+const HEADERS = { "content-type": "application/json", "stripe-signature": "t=1,v1=sig" };
+
+async function postToken(token = TOKEN_A, headers: Json = HEADERS) {
+  const from = lines.length;
+  const res = await server.inject({
+    method: "POST",
+    url: `/v1/webhooks/stripe/${token}`,
+    payload: RAW_BODY,
+    headers: headers as Record<string, string>,
+  });
+  return { res, lines: handlerLines(from), from };
+}
+
+async function postLegacy() {
+  const from = lines.length;
+  const res = await server.inject({
+    method: "POST",
+    url: "/v1/webhooks/stripe",
+    payload: RAW_BODY,
+    headers: HEADERS,
+  });
+  return { res, lines: handlerLines(from) };
+}
+
+/** "Answers X" (C1): a 200 `{ received: true }` whose one handler line carries `outcome: X`. */
+function expectAnswers(
+  result: { res: { statusCode: number; json: () => unknown }; lines: Json[] },
+  outcome: string,
+) {
+  expect(result.res.statusCode).toBe(200);
+  expect(result.res.json()).toEqual({ received: true });
+  expect(result.lines.map((l) => l["outcome"])).toEqual([outcome]);
+}
+
+/** Every prisma method the route could reach — none was called. */
+function expectNoPrismaCall() {
+  for (const model of ["lead", "person", "user", "organization", "callback"] as const) {
+    for (const fn of Object.values(prisma[model] as Record<string, jest.Mock>)) {
+      expect(fn).not.toHaveBeenCalled();
+    }
+  }
+}
+
+function expectNothingWritten() {
+  expect(mockRouteLead).not.toHaveBeenCalled();
+  expect(mockClientForOrganization).not.toHaveBeenCalled();
+  expectNoPrismaCall();
+}
+
+// ── AC-1 — attribution is the hub's own record (W-T1) ────────────────────────
+
+describe("AC-1 — attribution is the hub's own record (W-T1)", () => {
+  it("a session with no record answers unrecorded, writes nothing, and is not marked seen", async () => {
+    mockReadRecord.mockResolvedValueOnce(null);
+    expectAnswers(await postToken(), "unrecorded");
+    expectNothingWritten();
+    expect(mockReadRecord).toHaveBeenCalledWith(SESSION);
+    expect(hasSeenForOrganization(ORG_A, EVENT_ID)).toBe(false);
+    // A redelivery with a matching record then fulfils.
+    expectAnswers(await postToken(), "fulfilled");
+  });
+
+  it.each([
+    ["another Organization's record", { ...RECORD, organizationId: ORG_B }, undefined],
+    [
+      "metadata.site naming another workspace of this Organization",
+      RECORD,
+      { site: WS_A2, ailk_offering: LOOKUP_KEY },
+    ],
+    ["metadata.site absent", RECORD, { ailk_offering: LOOKUP_KEY }],
+    ["no metadata at all", RECORD, null],
+  ])("%s answers foreign_organization", async (_label, record, metadata) => {
+    mockReadRecord.mockResolvedValueOnce(record);
+    if (metadata !== undefined) mockVerifyKeyless.mockReturnValueOnce(sessionEvent({ metadata }));
+    expectAnswers(await postToken(), "foreign_organization");
+    expectNothingWritten();
+    expect(hasSeenForOrganization(ORG_A, EVENT_ID)).toBe(false);
+    expectAnswers(await postToken(), "fulfilled");
+  });
+});
+
+// ── AC-2 — the two endpoints never both act (W-T2) ───────────────────────────
+
+describe("AC-2 — the legacy endpoint steps aside and the token endpoint fulfils once (W-T2)", () => {
+  it("E at the legacy endpoint is offerings_path; at the token endpoint fulfilled once, then duplicate; E2 replays", async () => {
+    const legacy = await postLegacy();
+    expect(legacy.res.statusCode).toBe(200);
+    expect(legacy.res.json()).toEqual({ received: true });
+    expect(legacy.lines.map((l) => l["outcome"])).toEqual(["offerings_path"]);
+    expectNoPrismaCall();
+    expect(hasSeen(EVENT_ID)).toBe(false);
+
+    expectAnswers(await postToken(), "fulfilled");
+    expect(mockRouteLead).toHaveBeenCalledTimes(1);
+    expect(mockRouteLead.mock.calls[0][2]).toEqual({
+      idempotencyKey: `stripe-offerings ${SESSION}`,
+      offeringsCheckout: true,
+    });
+
+    expectAnswers(await postToken(), "duplicate");
+    expect(mockRouteLead).toHaveBeenCalledTimes(1);
+
+    mockVerifyKeyless.mockReturnValue(
+      sessionEvent({ id: EVENT_ID_2, type: "checkout.session.async_payment_succeeded" }),
+    );
+    mockRouteLead.mockResolvedValueOnce({
+      ok: true,
+      replayed: true,
+      id: "lead_8932",
+      persisted: "db",
+      email: { skipped: true, reason: "idempotent_replay" },
+    });
+    expectAnswers(await postToken(), "already_fulfilled");
+    expect(mockRouteLead.mock.calls[1][2]).toEqual({
+      idempotencyKey: `stripe-offerings ${SESSION}`,
+      offeringsCheckout: true,
+    });
+
+    expect(hasSeen(EVENT_ID)).toBe(false);
+    expect(hasSeenForOrganization(ORG_A, EVENT_ID)).toBe(true);
+    expect(hasSeenForOrganization(ORG_B, EVENT_ID)).toBe(false);
+  });
+
+  it("an idempotency conflict is already_fulfilled", async () => {
+    mockRouteLead.mockResolvedValueOnce({
+      ok: false,
+      error: { kind: "idempotency_conflict", message: "x" },
+    });
+    expectAnswers(await postToken(), "already_fulfilled");
+  });
+});
+
+// ── AC-3 — the legacy step-aside reads every stamp source (W8) ───────────────
+
+describe("AC-3 — the legacy step-aside reads every stamp source (W8)", () => {
+  const STAMP = { ailk_offering: LOOKUP_KEY };
+  const invoice = (fields: Json) => ({
+    id: "evt_inv8932aaaaaaaaaa",
+    type: "invoice.paid",
+    livemode: true,
+    data: { object: { object: "invoice", id: "in_8932invoice", ...fields } },
+  });
+
+  it.each([
+    ["parent.subscription_details.metadata", invoice({ parent: { subscription_details: { metadata: STAMP } } })],
+    ["pre-basil subscription_details.metadata", invoice({ subscription_details: { metadata: STAMP } })],
+    ["the invoice's own metadata", invoice({ metadata: STAMP })],
+    [
+      "a subscription's own metadata",
+      {
+        id: "evt_sub8932aaaaaaaaaa",
+        type: "customer.subscription.updated",
+        livemode: true,
+        data: { object: { object: "subscription", id: "sub_8932", metadata: STAMP } },
+      },
+    ],
+    [
+      "an expired session's metadata with an empty value",
+      sessionEvent({ type: "checkout.session.expired", metadata: { ailk_offering: "" } }),
+    ],
+  ])("an event stamped in %s answers offerings_path and is not seen", async (_label, event) => {
+    mockVerifyEnv.mockReturnValueOnce(event);
+    const legacy = await postLegacy();
+    expect(legacy.res.statusCode).toBe(200);
+    expect(legacy.res.json()).toEqual({ received: true });
+    expect(legacy.lines.map((l) => l["outcome"])).toEqual(["offerings_path"]);
+    expectNoPrismaCall();
+    expect(hasSeen(event["id"] as string)).toBe(false);
+  });
+
+  it("an unstamped invoice.paid still reaches its arm and is marked seen", async () => {
+    const event = invoice({ metadata: { other: "x" } });
+    mockVerifyEnv.mockReturnValueOnce(event);
+    const legacy = await postLegacy();
+    expect(legacy.res.statusCode).toBe(200);
+    expect(prisma.callback.updateMany).toHaveBeenCalledWith(
+      expect.objectContaining({ where: { stripeInvoiceId: "in_8932invoice", paidAt: null } }),
+    );
+    expect(hasSeen(event.id)).toBe(true);
+  });
+});
+
+// ── AC-4 — only the recorded Price is fulfilled (W-T3, W6) ───────────────────
+
+describe("AC-4 — only the recorded Price is fulfilled (W-T3, W6)", () => {
+  it.each([
+    ["one item of another Price", [PRICE_B]],
+    ["two items", [PRICE_A, PRICE_B]],
+    ["no items", []],
+  ])("%s answers offering_mismatch and fulfils nothing", async (_label, prices) => {
+    listLineItems.mockResolvedValueOnce(lineItems(...prices));
+    expectAnswers(await postToken(), "offering_mismatch");
+    expect(mockRouteLead).not.toHaveBeenCalled();
+    expect(listLineItems).toHaveBeenCalledWith(SESSION, { limit: 2 });
+    expect(mockClientForOrganization).toHaveBeenCalledWith(ORG_A);
+  });
+
+  it("an unpaid completed session answers unpaid with no line-item read", async () => {
+    mockVerifyKeyless.mockReturnValueOnce(sessionEvent({ object: { payment_status: "unpaid" } }));
+    expectAnswers(await postToken(), "unpaid");
+    expect(listLineItems).not.toHaveBeenCalled();
+    expect(mockRouteLead).not.toHaveBeenCalled();
+  });
+
+  it("no_payment_required counts as paid", async () => {
+    mockVerifyKeyless.mockReturnValueOnce(
+      sessionEvent({ object: { payment_status: "no_payment_required" } }),
+    );
+    expectAnswers(await postToken(), "fulfilled");
+  });
+
+  it.each([
+    ["no connection", () => mockClientForOrganization.mockResolvedValueOnce({ kind: "none" })],
+    ["an unusable connection", () => mockClientForOrganization.mockResolvedValueOnce({ kind: "unusable" })],
+    ["a rejected client read", () => mockClientForOrganization.mockRejectedValueOnce(new Error("db"))],
+    ["a rejected Stripe call", () => listLineItems.mockRejectedValueOnce(new Error("Growth stripe"))],
+  ])("%s answers 503 stripe-unavailable and is retried", async (_label, arrange) => {
+    arrange();
+    const first = await postToken();
+    expect(first.res.statusCode).toBe(503);
+    expect(first.res.json()).toEqual({ error: "stripe-unavailable" });
+    expect(first.lines.map((l) => l["outcome"])).toEqual(["stripe_unavailable"]);
+    expect(mockRouteLead).not.toHaveBeenCalled();
+    expectAnswers(await postToken(), "fulfilled");
+  });
+});
+
+// ── AC-5 (route half) — the lead the route writes ────────────────────────────
+
+describe("AC-5 — a fulfilment writes D6's lead on the record's full key", () => {
+  it("calls routeLead once with exactly D6's input and options", async () => {
+    expectAnswers(await postToken(), "fulfilled");
+    expect(mockRouteLead).toHaveBeenCalledTimes(1);
+    const [input, meta, options] = mockRouteLead.mock.calls[0];
+    expect(input).toEqual({
+      kind: "submit",
+      siteId: WS_A,
+      source: "web",
+      email: EMAIL,
+      payload: {
+        page: "checkout",
+        offering: LOOKUP_KEY,
+        site: WS_A,
+        amountTotal: 4900,
+        currency: "usd",
+        termsAccepted: TERMS,
+      },
+    });
+    expect(meta).toEqual(
+      expect.objectContaining({ ip: expect.any(String), receivedAt: expect.any(String) }),
+    );
+    expect(options).toEqual({ idempotencyKey: `stripe-offerings ${SESSION}`, offeringsCheckout: true });
+  });
+
+  it("takes the offering from the record, never from metadata.ailk_offering", async () => {
+    mockVerifyKeyless.mockReturnValueOnce(
+      sessionEvent({ metadata: { site: WS_A, ailk_offering: "basic_once", ailk_terms: TERMS } }),
+    );
+    expectAnswers(await postToken(), "fulfilled");
+    expect(mockRouteLead.mock.calls[0][0].payload.offering).toBe(LOOKUP_KEY);
+  });
+
+  it("carries no terms stamp when the buyer did not tick the box", async () => {
+    mockVerifyKeyless.mockReturnValueOnce(sessionEvent({ object: { consent: null } }));
+    expectAnswers(await postToken(), "fulfilled");
+    expect(mockRouteLead.mock.calls[0][0].payload.termsAccepted).toBeNull();
+  });
+
+  it("an unstorable email is unfulfillable and marked seen", async () => {
+    mockRouteLead.mockResolvedValueOnce({ ok: false, error: { kind: "invalid_input", message: "x" } });
+    expectAnswers(await postToken(), "unfulfillable");
+    expect(hasSeenForOrganization(ORG_A, EVENT_ID)).toBe(true);
+  });
+
+  it.each([
+    ["a file-fallback write", { ok: true, id: "x", persisted: "file", email: { skipped: true, reason: "r" } }],
+    ["an email delivery", { ok: true, id: "x", persisted: "email", email: { skipped: true, reason: "r" } }],
+    ["a persist failure", { ok: false, error: { kind: "persist_failed", message: "x" } }],
+  ])("%s answers 503 fulfilment-unavailable and is retried", async (_label, answer) => {
+    mockRouteLead.mockResolvedValueOnce(answer);
+    const first = await postToken();
+    expect(first.res.statusCode).toBe(503);
+    expect(first.res.json()).toEqual({ error: "fulfilment-unavailable" });
+    expect(first.lines.map((l) => l["outcome"])).toEqual(["fulfilment_unavailable"]);
+    expect(hasSeenForOrganization(ORG_A, EVENT_ID)).toBe(false);
+    expectAnswers(await postToken(), "fulfilled");
+  });
+
+  it("a rejected routeLead answers 503 fulfilment-unavailable", async () => {
+    mockRouteLead.mockRejectedValueOnce(new Error(`boom ${EMAIL}`));
+    const first = await postToken();
+    expect(first.res.statusCode).toBe(503);
+    expect(first.res.json()).toEqual({ error: "fulfilment-unavailable" });
+  });
+});
+
+// ── AC-7 — the ladder holds its order and its non-2xx answers retry ──────────
+
+describe("AC-7 — the ladder holds its order and its non-2xx answers retry", () => {
+  const ORIGINAL_KEY = process.env.STRIPE_SECRET_KEY;
+  beforeEach(() => {
+    delete process.env.STRIPE_SECRET_KEY;
+  });
+  afterEach(() => {
+    if (ORIGINAL_KEY === undefined) delete process.env.STRIPE_SECRET_KEY;
+    else process.env.STRIPE_SECRET_KEY = ORIGINAL_KEY;
+  });
+
+  it("verifies with the raw body, the header and the row's secret — never the env-key verify", async () => {
+    expectAnswers(await postToken(), "fulfilled");
+    expect(mockVerifyKeyless).toHaveBeenCalledTimes(1);
+    const [body, header, secret] = mockVerifyKeyless.mock.calls[0];
+    expect(Buffer.isBuffer(body)).toBe(true);
+    expect((body as Buffer).equals(RAW_BODY)).toBe(true);
+    expect(header).toBe("t=1,v1=sig");
+    expect(secret).toBe(WHSEC_A);
+    expect(mockVerifyEnv).not.toHaveBeenCalled();
+  });
+
+  it("a rejected token lookup answers 503 webhook-unavailable", async () => {
+    mockFindConnection.mockRejectedValueOnce(new Error("store"));
+    const { res, lines: out } = await postToken();
+    expect(res.statusCode).toBe(503);
+    expect(res.json()).toEqual({ error: "webhook-unavailable" });
+    expect(out.map((l) => l["outcome"])).toEqual(["connection_unavailable"]);
+    expect(mockVerifyKeyless).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ["not-configured", { kind: "not-configured", organizationId: ORG_A, mode: "live" }],
+    ["unreadable", { kind: "unreadable", organizationId: ORG_A }],
+  ])("%s answers 503 webhook-not-configured with no verify", async (_label, answer) => {
+    mockFindConnection.mockResolvedValueOnce(answer);
+    const { res, lines: out } = await postToken();
+    expect(res.statusCode).toBe(503);
+    expect(res.json()).toEqual({ error: "webhook-not-configured" });
+    expect(out.map((l) => l["outcome"])).toEqual(["webhook_not_configured"]);
+    expect(mockVerifyKeyless).not.toHaveBeenCalled();
+  });
+
+  it("a missing stripe-signature answers 400 signature-missing before the record read", async () => {
+    const { res, lines: out } = await postToken(TOKEN_A, { "content-type": "application/json" });
+    expect(res.statusCode).toBe(400);
+    expect(res.json()).toEqual({ error: "signature-missing" });
+    expect(out).toEqual([]);
+    expect(mockReadRecord).not.toHaveBeenCalled();
+  });
+
+  it("a throwing verify answers 400 signature-invalid before the record read", async () => {
+    mockVerifyKeyless.mockImplementationOnce(() => {
+      throw new StripeWebhookSignatureError("Webhook signature verification failed.");
+    });
+    const { res, lines: out } = await postToken();
+    expect(res.statusCode).toBe(400);
+    expect(res.json()).toEqual({ error: "signature-invalid" });
+    expect(out.map((l) => l["outcome"])).toEqual(["signature_invalid"]);
+    expect(mockReadRecord).not.toHaveBeenCalled();
+  });
+
+  it("an undetermined claim answers 503 with Retry-After: 300", async () => {
+    mockClaim.mockResolvedValueOnce("undetermined");
+    const { res, lines: out } = await postToken();
+    expect(res.statusCode).toBe(503);
+    expect(res.headers["retry-after"]).toBe("300");
+    expect(res.json()).toEqual({ error: "license-undetermined" });
+    expect(out.map((l) => l["outcome"])).toEqual(["license_undetermined"]);
+    expectAnswers(await postToken(), "fulfilled");
+  });
+
+  it("an unclaimed signed event is dropped_no_commerce_claim; an unclaimed unsigned body is the module-disabled 404", async () => {
+    mockClaim.mockResolvedValueOnce("unclaimed");
+    expectAnswers(await postToken(), "dropped_no_commerce_claim");
+    mockClaim.mockResolvedValueOnce("unclaimed");
+    const unsigned = await postToken(TOKEN_A, { "content-type": "application/json" });
+    expect(unsigned.res.statusCode).toBe(404);
+    expect(unsigned.lines).toEqual([]);
+    expectAnswers(await postToken(), "fulfilled");
+  });
+
+  it("a test-mode event on the live row is livemode_mismatch", async () => {
+    mockVerifyKeyless.mockReturnValueOnce(sessionEvent({ livemode: false }));
+    expectAnswers(await postToken(), "livemode_mismatch");
+    expect(mockReadRecord).not.toHaveBeenCalled();
+    expectAnswers(await postToken(), "fulfilled");
+  });
+
+  it("a record whose mode is test is livemode_mismatch", async () => {
+    mockReadRecord.mockResolvedValueOnce({ ...RECORD, mode: "test" });
+    expectAnswers(await postToken(), "livemode_mismatch");
+    expectAnswers(await postToken(), "fulfilled");
+  });
+
+  it.each([
+    ["customer.subscription.updated", sessionEvent({ type: "customer.subscription.updated" })],
+    ["a session-typed event whose object is not a session", sessionEvent({ object: { object: "invoice" } })],
+  ])("%s is ignored_type", async (_label, event) => {
+    mockVerifyKeyless.mockReturnValueOnce(event);
+    expectAnswers(await postToken(), "ignored_type");
+    expect(mockReadRecord).not.toHaveBeenCalled();
+    expectAnswers(await postToken(), "fulfilled");
+  });
+
+  it("a rejected record read answers 503 record-unavailable; an unreadable one 500 record-unreadable", async () => {
+    mockReadRecord.mockRejectedValueOnce(new Error("read_failed"));
+    const unavailable = await postToken();
+    expect(unavailable.res.statusCode).toBe(503);
+    expect(unavailable.res.json()).toEqual({ error: "record-unavailable" });
+    expect(unavailable.lines.map((l) => l["outcome"])).toEqual(["record_unavailable"]);
+
+    mockReadRecord.mockResolvedValueOnce("unreadable");
+    const unreadable = await postToken();
+    expect(unreadable.res.statusCode).toBe(500);
+    expect(unreadable.res.json()).toEqual({ error: "record-unreadable" });
+    expect(unreadable.lines.map((l) => l["outcome"])).toEqual(["record_unreadable"]);
+
+    expectAnswers(await postToken(), "fulfilled");
+  });
+
+  it("no handler path touches a user or organization row (W11)", async () => {
+    expectAnswers(await postToken(), "fulfilled");
+    for (const model of ["user", "organization"] as const) {
+      for (const fn of Object.values(prisma[model] as Record<string, jest.Mock>)) {
+        expect(fn).not.toHaveBeenCalled();
+      }
+    }
+  });
+});
+
+// ── AC-6 — no log line carries a secret, an id, an email, metadata or text ───
+
+describe("AC-6 — the logs carry none of C6's forbidden values", () => {
+  const FORBIDDEN = [
+    TOKEN_A,
+    WHSEC_A,
+    EVENT_ID.slice(0, 9),
+    EVENT_ID_2.slice(0, 9),
+    SESSION,
+    PRICE_A,
+    PRICE_B,
+    EMAIL,
+    LOOKUP_KEY,
+    TERMS,
+    "Growth",
+    "ailk_",
+  ];
+
+  function expectClean(): void {
+    const all = [...lines, ...loggerLines.map((args) => JSON.stringify(args))];
+    for (const line of all) {
+      for (const value of FORBIDDEN) expect(line).not.toContain(value);
+    }
+  }
+
+  /** Every handler line's key set is D2's for its step. */
+  function expectKeySets(): void {
+    for (const line of handlerLines()) {
+      const outcome = line["outcome"];
+      if (outcome === "connection_unavailable") expect(keysOf(line)).toEqual(["outcome"]);
+      else if (outcome === "webhook_not_configured" || outcome === "signature_invalid") {
+        expect(keysOf(line)).toEqual(["organizationId", "outcome"]);
+      } else if (outcome === "offerings_path") {
+        // The legacy endpoint's line: no Organization is known there.
+        expect(keysOf(line)).toEqual(["eventIdPrefix", "eventType", "outcome"]);
+      } else if (outcome === "license_undetermined" && !("eventType" in line)) {
+        expect(keysOf(line)).toEqual(["organizationId", "outcome"]);
+      } else if (line["organizationId"] !== undefined) {
+        expect(keysOf(line)).toEqual(EVENT_KEYS);
+        expect(line["eventIdPrefix"]).toHaveLength(8);
+      }
+    }
+  }
+
+  it("across a run of every ladder step, no line is forbidden and every key set is D2's", async () => {
+    // Every step, in one run, each from a fresh state of its mocks.
+    mockFindConnection.mockRejectedValueOnce(new Error(`store ${TOKEN_A}`));
+    await postToken();
+    mockFindConnection.mockResolvedValueOnce({ kind: "unreadable", organizationId: ORG_A });
+    await postToken();
+    await postToken(TOKEN_A, { "content-type": "application/json" });
+    mockVerifyKeyless.mockImplementationOnce(() => {
+      throw new StripeWebhookSignatureError("Webhook signature verification failed.");
+    });
+    await postToken();
+    mockClaim.mockResolvedValueOnce("undetermined");
+    await postToken();
+    mockClaim.mockResolvedValueOnce("undetermined");
+    await postToken(TOKEN_A, { "content-type": "application/json" });
+    mockClaim.mockResolvedValueOnce("unclaimed");
+    await postToken();
+    mockVerifyKeyless.mockReturnValueOnce(sessionEvent({ livemode: false }));
+    await postToken();
+    mockVerifyKeyless.mockReturnValueOnce(sessionEvent({ type: "invoice.paid" }));
+    await postToken();
+    mockReadRecord.mockRejectedValueOnce(new Error(`read ${SESSION}`));
+    await postToken();
+    mockReadRecord.mockResolvedValueOnce("unreadable");
+    await postToken();
+    mockReadRecord.mockResolvedValueOnce(null);
+    await postToken();
+    mockReadRecord.mockResolvedValueOnce({ ...RECORD, organizationId: ORG_B });
+    await postToken();
+    mockVerifyKeyless.mockReturnValueOnce(sessionEvent({ object: { payment_status: "unpaid" } }));
+    await postToken();
+    __resetIdempotencyStore();
+    listLineItems.mockRejectedValueOnce(new Error(`Stripe ${PRICE_A} Growth`));
+    await postToken();
+    listLineItems.mockResolvedValueOnce(lineItems(PRICE_B));
+    await postToken();
+    __resetIdempotencyStore();
+    mockRouteLead.mockRejectedValueOnce(new Error(`lead ${EMAIL}`));
+    await postToken();
+    await postToken();
+    await postToken();
+    await postLegacy();
+
+    const outcomes = new Set(handlerLines().map((l) => l["outcome"]));
+    for (const outcome of [
+      "connection_unavailable",
+      "webhook_not_configured",
+      "signature_invalid",
+      "license_undetermined",
+      "dropped_no_commerce_claim",
+      "livemode_mismatch",
+      "ignored_type",
+      "record_unavailable",
+      "record_unreadable",
+      "unrecorded",
+      "foreign_organization",
+      "unpaid",
+      "stripe_unavailable",
+      "offering_mismatch",
+      "fulfilment_unavailable",
+      "fulfilled",
+      "duplicate",
+      "offerings_path",
+    ]) {
+      expect(outcomes).toContain(outcome);
+    }
+    expectClean();
+    expectKeySets();
+  });
+
+  it.each([
+    ["a well-formed unknown token", "Uu8932unknownUNKNOWNunknownUNKNOWNunknown_x"],
+    ["abc", "abc"],
+    ["TOKEN_A.", `${TOKEN_A}.`],
+    ["a 44-character string", `${TOKEN_A}x`],
+  ])("%s answers 404 not-found, logs nothing and never verifies or reads the claim", async (_label, token) => {
+    const { res, lines: out, from } = await postToken(token);
+    expect(res.statusCode).toBe(404);
+    expect(res.json()).toEqual({ error: "not-found" });
+    expect(out).toEqual([]);
+    expect(loggerLines).toEqual([]);
+    expect(mockVerifyKeyless).not.toHaveBeenCalled();
+    expect(mockClaim).not.toHaveBeenCalled();
+    const requestLines = lines
+      .slice(from)
+      .map((l) => JSON.parse(l) as { req?: { url?: string } })
+      .filter((l) => l.req !== undefined);
+    expect(requestLines.length).toBeGreaterThan(0);
+    for (const line of requestLines) {
+      expect(line.req?.url).toBe("/v1/webhooks/stripe/:connectionToken");
+    }
+    expectClean();
+  });
+
+  it("the rate limit's 429 error-handler line logs the redacted path", async () => {
+    for (let i = 0; i < STRIPE_OFFERINGS_WEBHOOK_RATE_LIMIT_PER_MIN; i += 1) {
+      await postToken("abc");
+    }
+    const from = lines.length;
+    const limited = await postToken(TOKEN_A);
+    expect(limited.res.statusCode).toBe(429);
+    const errorLines = lines
+      .slice(from)
+      .map((l) => JSON.parse(l) as Json)
+      .filter((l) => l["statusCode"] === 429 && "path" in l);
+    expect(errorLines).toHaveLength(1);
+    expect(errorLines[0]?.["path"]).toBe("/v1/webhooks/stripe/:connectionToken");
+    expectClean();
+  });
+});