create-ailk 0.4.0 → 0.6.0

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

@@ -0,0 +1,749 @@
+/**
+ * POST /v1/webhooks/stripe — the dunning arms (#6034): `invoice.payment_failed`
+ * (FR-1) and `customer.subscription.updated` (FR-2/FR-4), the § D6
+ * ordering/tie/durable-replay admission rule, and the § D5 grace/revocation
+ * computation.
+ *
+ * Mock shape is `stripe-request-paid.test.ts`'s, deliberately unchanged: the
+ * six pre-existing webhook suites are the regression floor for this issue and
+ * none of them is edited, so this file mirrors their setup rather than
+ * refactoring a shared one.
+ */
+import type { FastifyInstance } from "fastify";
+import Fastify from "fastify";
+
+const mockTrack = jest.fn().mockResolvedValue(undefined);
+
+// Commerce claim (D-64, #5796): every case here is a COMMERCE-CLAIMED
+// deployment, the same posture the sibling webhook suites take.
+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: (...args: unknown[]) => mockTrack(...args),
+}));
+
+// 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");
+
+// eslint-disable-next-line no-restricted-syntax -- @working-theory/config-modules is not a DB boundary; this repo has no __mocks__/modules.ts fixture, so a factory is the standard shape here.
+jest.mock("../../../config/modules.js", () => ({
+  isModuleEnabled: () => false,
+}));
+
+const mockVerifyWebhookSignature = jest.fn();
+class MockStripeWebhookSignatureError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "StripeWebhookSignatureError";
+  }
+}
+jest.mock("@working-theory/stripe-client", () => {
+  // toSubscriptionLifecycleStatus (#6034 § D3) is REAL here, not stubbed —
+  // this is the exact "which Stripe statuses imply access" narrowing the
+  // webhook reuses, and AC-2 tests its behavior (unpaid → past_due, an
+  // unrecognized status → canceled) through this suite.
+  const actual = jest.requireActual("@working-theory/stripe-client");
+  return {
+    verifyWebhookSignature: (...args: unknown[]) =>
+      mockVerifyWebhookSignature(...args),
+    StripeWebhookSignatureError: MockStripeWebhookSignatureError,
+    assertSandboxKey: jest.fn(),
+    createCheckoutSession: jest.fn(),
+    getStripeClient: jest.fn(),
+    STRIPE_API_VERSION: "2024-06-20",
+    StripeConfigError: class StripeConfigError extends Error {},
+    UnknownProductCodeError: class UnknownProductCodeError extends Error {},
+    WEBHOOK_TOLERANCE_SECONDS: 300,
+    toSubscriptionLifecycleStatus: actual.toSubscriptionLifecycleStatus,
+  };
+});
+
+import * as configModule from "../../../config/index.js";
+import { stripeWebhookHandler } from "../stripe.js";
+import { __resetIdempotencyStore } from "../../../lib/webhook-idempotency.js";
+import { prisma } from "../../../lib/prisma.js";
+import { isSubscriberActionRequired } from "../../../services/dunning-policy.js";
+
+const CUSTOMER_ID = "cus_test_1234567890";
+const SUBSCRIPTION_ID = "sub_test_1234567890";
+const USER_ID = "user_test_1234567890";
+const DAY_SEC = 24 * 60 * 60;
+
+let eventCounter = 0;
+function invoicePaymentFailedEvent(
+  object: Record<string, unknown> = {},
+  created = 1_700_000_000,
+  eventId?: string,
+) {
+  eventCounter += 1;
+  return {
+    id: eventId ?? `evt_test_${eventCounter}`,
+    type: "invoice.payment_failed",
+    created,
+    data: {
+      object: {
+        subscription: SUBSCRIPTION_ID,
+        customer: CUSTOMER_ID,
+        ...object,
+      },
+    },
+  };
+}
+
+function subscriptionUpdatedEvent(
+  object: Record<string, unknown> = {},
+  created = 1_700_000_000,
+  eventId?: string,
+) {
+  eventCounter += 1;
+  return {
+    id: eventId ?? `evt_test_${eventCounter}`,
+    type: "customer.subscription.updated",
+    created,
+    data: {
+      object: {
+        id: SUBSCRIPTION_ID,
+        customer: CUSTOMER_ID,
+        status: "past_due",
+        ...object,
+      },
+    },
+  };
+}
+
+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.post("/v1/webhooks/stripe", stripeWebhookHandler);
+  });
+  await server.ready();
+  return server;
+}
+
+const VALID_BODY = Buffer.from(JSON.stringify({ type: "test" }));
+const HEADERS = {
+  "content-type": "application/json",
+  "stripe-signature": "t=1234,v1=abc",
+};
+
+let server: FastifyInstance;
+
+beforeEach(async () => {
+  jest.clearAllMocks();
+  __resetIdempotencyStore();
+  jest.replaceProperty(configModule, "config", {
+    ...configModule.config,
+    STRIPE_WEBHOOK_SECRET: "whsec_test_secret",
+  });
+  (prisma.user.findUnique as jest.Mock).mockResolvedValue({ id: USER_ID });
+  (prisma.user.findFirst as jest.Mock).mockResolvedValue(null);
+  (prisma.userData.findUnique as jest.Mock).mockResolvedValue(null);
+  (prisma.userData.create as jest.Mock).mockResolvedValue({});
+  (prisma.userData.updateMany as jest.Mock).mockResolvedValue({ count: 1 });
+  (prisma.siteSetting.findUnique as jest.Mock).mockResolvedValue({
+    value: { graceDays: 14 },
+  });
+  server = await buildTestServer();
+});
+
+afterEach(async () => {
+  await server.close();
+  jest.restoreAllMocks();
+});
+
+async function post() {
+  return server.inject({
+    method: "POST",
+    url: "/v1/webhooks/stripe",
+    payload: VALID_BODY,
+    headers: HEADERS,
+  });
+}
+
+// ── AC-1 — invoice.payment_failed arms dunning, never revokes, still 200 ───
+
+describe("invoice.payment_failed arms dunning and never revokes (AC-1)", () => {
+  it("creates a fresh past_due record for the matched subscriber", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(invoicePaymentFailedEvent());
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(JSON.parse(res.body)).toEqual({ received: true });
+
+    expect(prisma.userData.create).toHaveBeenCalledTimes(1);
+    const call = (prisma.userData.create as jest.Mock).mock.calls[0][0];
+    const entry = call.data.value.subscriptions[SUBSCRIPTION_ID];
+    expect(entry.status).toBe("past_due");
+    expect(entry.accessState).toBe("granted");
+    expect(entry.dunningArmedAt).not.toBeNull();
+    expect(entry.accessRevokesAt).toBeNull();
+
+    expect(prisma.userData.updateMany).not.toHaveBeenCalled();
+    for (const [{ data }] of (prisma.userData.create as jest.Mock).mock.calls) {
+      const written = Object.values(data.value.subscriptions) as Array<{
+        accessState: string;
+      }>;
+      expect(written.some((e) => e.accessState === "revoked")).toBe(false);
+    }
+  });
+
+  it("issues zero prisma.userData.* and prisma.user.* calls for an invoice with no subscription", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      invoicePaymentFailedEvent({ subscription: null }),
+    );
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(prisma.userData.findUnique).not.toHaveBeenCalled();
+    expect(prisma.userData.create).not.toHaveBeenCalled();
+    expect(prisma.userData.updateMany).not.toHaveBeenCalled();
+    expect(prisma.user.findUnique).not.toHaveBeenCalled();
+  });
+});
+
+// ── invoice.payment_failed never un-revokes an already-canceled subscriber ──
+// (code review finding, #6034 — a late Smart-Retries webhook for an invoice
+// predating a cancellation can arrive with a genuinely NEWER event.created
+// than the cancellation itself; only customer.subscription.updated may ever
+// clear a recorded `canceled` entry.)
+
+describe("invoice.payment_failed never un-revokes an already-canceled subscriber", () => {
+  const T = 1_700_000_000;
+
+  it("preserves a fully-revoked entry even when the invoice event is strictly newer", async () => {
+    const canceledEntry = {
+      status: "canceled",
+      accessState: "revoked",
+      dunningArmedAt: new Date((T - 20 * DAY_SEC) * 1000).toISOString(),
+      accessRevokesAt: new Date((T - 1 * DAY_SEC) * 1000).toISOString(),
+      lastEventAt: T,
+      lastEventId: "evt_cancel",
+    };
+    (prisma.userData.findUnique as jest.Mock).mockResolvedValue({
+      value: { v: 1, subscriptions: { [SUBSCRIPTION_ID]: canceledEntry } },
+      updatedAt: new Date(),
+    });
+
+    mockVerifyWebhookSignature.mockReturnValue(
+      invoicePaymentFailedEvent({}, T + 3600, "evt_late_retry"),
+    );
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    // A write may or may not occur (any write is content-identical); what
+    // matters is the persisted content is never relaxed.
+    for (const [{ data }] of (prisma.userData.updateMany as jest.Mock).mock.calls) {
+      expect(data.value.subscriptions[SUBSCRIPTION_ID]).toEqual(canceledEntry);
+    }
+    expect(prisma.userData.create).not.toHaveBeenCalled();
+  });
+
+  it("preserves an in-grace canceled entry (accessState still granted) the same way", async () => {
+    const inGraceEntry = {
+      status: "canceled",
+      accessState: "granted",
+      dunningArmedAt: new Date((T - 9 * DAY_SEC) * 1000).toISOString(),
+      accessRevokesAt: new Date((T + 5 * DAY_SEC) * 1000).toISOString(),
+      lastEventAt: T,
+      lastEventId: "evt_cancel_grace",
+    };
+    (prisma.userData.findUnique as jest.Mock).mockResolvedValue({
+      value: { v: 1, subscriptions: { [SUBSCRIPTION_ID]: inGraceEntry } },
+      updatedAt: new Date(),
+    });
+
+    mockVerifyWebhookSignature.mockReturnValue(
+      invoicePaymentFailedEvent({}, T + 3600, "evt_late_retry2"),
+    );
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    for (const [{ data }] of (prisma.userData.updateMany as jest.Mock).mock.calls) {
+      expect(data.value.subscriptions[SUBSCRIPTION_ID]).toEqual(inGraceEntry);
+    }
+    expect(prisma.userData.create).not.toHaveBeenCalled();
+  });
+});
+
+// ── AC-2 — the three statuses, and grace before revocation ─────────────────
+
+describe("customer.subscription.updated — three statuses, grace before revocation (AC-2)", () => {
+  it("(a) past_due narrows to a granted past_due record", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      subscriptionUpdatedEvent({ status: "past_due" }),
+    );
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    const call = (prisma.userData.create as jest.Mock).mock.calls[0][0];
+    const entry = call.data.value.subscriptions[SUBSCRIPTION_ID];
+    expect(entry.status).toBe("past_due");
+    expect(entry.accessState).toBe("granted");
+  });
+
+  it("(b) unpaid narrows to the SAME past_due record (§ 1.10)", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      subscriptionUpdatedEvent({ status: "unpaid" }),
+    );
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    const call = (prisma.userData.create as jest.Mock).mock.calls[0][0];
+    const entry = call.data.value.subscriptions[SUBSCRIPTION_ID];
+    expect(entry.status).toBe("past_due");
+    expect(entry.accessState).toBe("granted");
+  });
+
+  it("(c) canceled inside the grace window retains access and schedules accessRevokesAt", async () => {
+    const armedAtMs = Date.now() - 13 * DAY_SEC * 1000;
+    const armedAt = new Date(armedAtMs).toISOString();
+    (prisma.userData.findUnique as jest.Mock).mockResolvedValue({
+      value: {
+        v: 1,
+        subscriptions: {
+          [SUBSCRIPTION_ID]: {
+            status: "past_due",
+            accessState: "granted",
+            dunningArmedAt: armedAt,
+            accessRevokesAt: null,
+            lastEventAt: 1_600_000_000,
+            lastEventId: "evt_prev",
+          },
+        },
+      },
+      updatedAt: new Date(),
+    });
+
+    mockVerifyWebhookSignature.mockReturnValue(
+      subscriptionUpdatedEvent({ status: "canceled" }, 1_700_000_000),
+    );
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    const call = (prisma.userData.updateMany as jest.Mock).mock.calls[0][0];
+    const entry = call.data.value.subscriptions[SUBSCRIPTION_ID];
+    expect(entry.status).toBe("canceled");
+    expect(entry.accessState).toBe("granted");
+    expect(entry.dunningArmedAt).toBe(armedAt);
+    expect(entry.accessRevokesAt).toBe(
+      new Date(armedAtMs + 14 * DAY_SEC * 1000).toISOString(),
+    );
+  });
+
+  it("(d) canceled past the grace window revokes access", async () => {
+    const armedAtMs = Date.now() - 15 * DAY_SEC * 1000;
+    (prisma.userData.findUnique as jest.Mock).mockResolvedValue({
+      value: {
+        v: 1,
+        subscriptions: {
+          [SUBSCRIPTION_ID]: {
+            status: "past_due",
+            accessState: "granted",
+            dunningArmedAt: new Date(armedAtMs).toISOString(),
+            accessRevokesAt: null,
+            lastEventAt: 1_600_000_000,
+            lastEventId: "evt_prev",
+          },
+        },
+      },
+      updatedAt: new Date(),
+    });
+
+    mockVerifyWebhookSignature.mockReturnValue(
+      subscriptionUpdatedEvent({ status: "canceled" }, 1_700_000_000),
+    );
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    const call = (prisma.userData.updateMany as jest.Mock).mock.calls[0][0];
+    const entry = call.data.value.subscriptions[SUBSCRIPTION_ID];
+    expect(entry.status).toBe("canceled");
+    expect(entry.accessState).toBe("revoked");
+  });
+});
+
+// ── AC-4 — recovery is clean ────────────────────────────────────────────────
+
+describe("recovery is clean (AC-4)", () => {
+  it("a strictly-newer active event returns the entry to a clean state", async () => {
+    (prisma.userData.findUnique as jest.Mock).mockResolvedValue({
+      value: {
+        v: 1,
+        subscriptions: {
+          [SUBSCRIPTION_ID]: {
+            status: "past_due",
+            accessState: "granted",
+            dunningArmedAt: new Date(
+              Date.now() - 3 * DAY_SEC * 1000,
+            ).toISOString(),
+            accessRevokesAt: null,
+            lastEventAt: 1_600_000_000,
+            lastEventId: "evt_prev",
+          },
+        },
+      },
+      updatedAt: new Date(),
+    });
+
+    mockVerifyWebhookSignature.mockReturnValue(
+      subscriptionUpdatedEvent(
+        { status: "active" },
+        1_700_000_000,
+        "evt_recover",
+      ),
+    );
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    const call = (prisma.userData.updateMany as jest.Mock).mock.calls[0][0];
+    const entry = call.data.value.subscriptions[SUBSCRIPTION_ID];
+    expect(entry).toEqual({
+      status: "active",
+      accessState: "granted",
+      dunningArmedAt: null,
+      accessRevokesAt: null,
+      lastEventAt: 1_700_000_000,
+      lastEventId: "evt_recover",
+    });
+    // #6038's read shows nothing for this shape — pinned via the EXPORTED
+    // predicate, not the superseded inline expression (finalize-spec
+    // required-change on § 5.1 AC-4).
+    expect(isSubscriberActionRequired(entry)).toBe(false);
+  });
+});
+
+// ── AC-5 — both arms honor the replay short-circuit ────────────────────────
+
+describe("both arms honor the replay short-circuit (AC-5)", () => {
+  it("invoice.payment_failed — a replayed event id makes zero additional Prisma calls", async () => {
+    const event = invoicePaymentFailedEvent(
+      {},
+      1_700_000_000,
+      "evt_replay_invoice",
+    );
+    mockVerifyWebhookSignature.mockReturnValue(event);
+    await post();
+    expect(prisma.userData.create).toHaveBeenCalledTimes(1);
+
+    jest.clearAllMocks();
+    mockVerifyWebhookSignature.mockReturnValue(event);
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(prisma.user.findUnique).not.toHaveBeenCalled();
+    expect(prisma.userData.findUnique).not.toHaveBeenCalled();
+    expect(prisma.userData.create).not.toHaveBeenCalled();
+  });
+
+  it("customer.subscription.updated — a replayed event id makes zero additional Prisma calls", async () => {
+    const event = subscriptionUpdatedEvent(
+      { status: "past_due" },
+      1_700_000_000,
+      "evt_replay_sub",
+    );
+    mockVerifyWebhookSignature.mockReturnValue(event);
+    await post();
+    expect(prisma.userData.create).toHaveBeenCalledTimes(1);
+
+    jest.clearAllMocks();
+    mockVerifyWebhookSignature.mockReturnValue(event);
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(prisma.user.findUnique).not.toHaveBeenCalled();
+    expect(prisma.userData.findUnique).not.toHaveBeenCalled();
+  });
+});
+
+// ── AC-6 — ordering, ties, and the durable replay twin (§ D6) ──────────────
+
+describe("ordering, ties, and the durable replay twin (AC-6, § D6)", () => {
+  const T = 1_700_000_000;
+
+  it("(a) a strictly older event is rejected as stale — the entry is unchanged", async () => {
+    (prisma.userData.findUnique as jest.Mock).mockResolvedValue({
+      value: {
+        v: 1,
+        subscriptions: {
+          [SUBSCRIPTION_ID]: {
+            status: "canceled",
+            accessState: "revoked",
+            dunningArmedAt: new Date((T - 20 * DAY_SEC) * 1000).toISOString(),
+            accessRevokesAt: new Date((T - 1 * DAY_SEC) * 1000).toISOString(),
+            lastEventAt: T,
+            lastEventId: "evt_current",
+          },
+        },
+      },
+      updatedAt: new Date(),
+    });
+
+    mockVerifyWebhookSignature.mockReturnValue(
+      subscriptionUpdatedEvent({ status: "active" }, T - 3600, "evt_stale"),
+    );
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(prisma.userData.updateMany).not.toHaveBeenCalled();
+    expect(prisma.userData.create).not.toHaveBeenCalled();
+  });
+
+  it("(b) an equal-timestamp de-escalating write is rejected as a stale tie — SEC-03", async () => {
+    (prisma.userData.findUnique as jest.Mock).mockResolvedValue({
+      value: {
+        v: 1,
+        subscriptions: {
+          [SUBSCRIPTION_ID]: {
+            status: "canceled",
+            accessState: "granted", // in-grace cancellation
+            dunningArmedAt: new Date((T - 9 * DAY_SEC) * 1000).toISOString(),
+            accessRevokesAt: new Date((T + 5 * DAY_SEC) * 1000).toISOString(),
+            lastEventAt: T,
+            lastEventId: "evt_current",
+          },
+        },
+      },
+      updatedAt: new Date(),
+    });
+
+    mockVerifyWebhookSignature.mockReturnValue(
+      subscriptionUpdatedEvent({ status: "active" }, T, "evt_reordered_tie"),
+    );
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(prisma.userData.updateMany).not.toHaveBeenCalled();
+    expect(prisma.userData.create).not.toHaveBeenCalled();
+  });
+
+  it("(c) a durable replay (same event id, hasSeen forgotten) is a no-op via lastEventId", async () => {
+    (prisma.userData.findUnique as jest.Mock)
+      .mockResolvedValueOnce(null)
+      .mockResolvedValue({
+        value: {
+          v: 1,
+          subscriptions: {
+            [SUBSCRIPTION_ID]: {
+              status: "past_due",
+              accessState: "granted",
+              dunningArmedAt: new Date().toISOString(),
+              accessRevokesAt: null,
+              lastEventAt: T,
+              lastEventId: "evt_dup",
+            },
+          },
+        },
+        updatedAt: new Date(),
+      });
+
+    const event = subscriptionUpdatedEvent(
+      { status: "past_due" },
+      T,
+      "evt_dup",
+    );
+    mockVerifyWebhookSignature.mockReturnValue(event);
+    const first = await post();
+    expect(first.statusCode).toBe(200);
+    expect(prisma.userData.create).toHaveBeenCalledTimes(1);
+
+    // The process-restart case — hasSeen has forgotten the id, but the
+    // DURABLE record (lastEventId) has not.
+    __resetIdempotencyStore();
+    mockVerifyWebhookSignature.mockReturnValue(event);
+    const second = await post();
+
+    expect(second.statusCode).toBe(200);
+    expect(prisma.userData.create).toHaveBeenCalledTimes(1);
+    expect(prisma.userData.updateMany).not.toHaveBeenCalled();
+  });
+
+  it("(d) a genuinely newer event DOES restore granted access", async () => {
+    (prisma.userData.findUnique as jest.Mock).mockResolvedValue({
+      value: {
+        v: 1,
+        subscriptions: {
+          [SUBSCRIPTION_ID]: {
+            status: "canceled",
+            accessState: "revoked",
+            dunningArmedAt: new Date((T - 20 * DAY_SEC) * 1000).toISOString(),
+            accessRevokesAt: new Date((T - 1 * DAY_SEC) * 1000).toISOString(),
+            lastEventAt: T,
+            lastEventId: "evt_current",
+          },
+        },
+      },
+      updatedAt: new Date(),
+    });
+
+    mockVerifyWebhookSignature.mockReturnValue(
+      subscriptionUpdatedEvent({ status: "active" }, T + 3600, "evt_newer"),
+    );
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(prisma.userData.updateMany).toHaveBeenCalledTimes(1);
+    const call = (prisma.userData.updateMany as jest.Mock).mock.calls[0][0];
+    const entry = call.data.value.subscriptions[SUBSCRIPTION_ID];
+    expect(entry).toEqual({
+      status: "active",
+      accessState: "granted",
+      dunningArmedAt: null,
+      accessRevokesAt: null,
+      lastEventAt: T + 3600,
+      lastEventId: "evt_newer",
+    });
+  });
+
+  describe("(e) the CAS conflict path", () => {
+    it("retries exactly three times, then answers 200 with no write on exhaustion", async () => {
+      (prisma.userData.findUnique as jest.Mock).mockResolvedValue({
+        value: { v: 1, subscriptions: {} },
+        updatedAt: new Date(),
+      });
+      (prisma.userData.updateMany as jest.Mock).mockResolvedValue({ count: 0 });
+
+      mockVerifyWebhookSignature.mockReturnValue(
+        subscriptionUpdatedEvent({ status: "past_due" }),
+      );
+
+      const res = await post();
+
+      expect(res.statusCode).toBe(200);
+      expect(prisma.userData.updateMany).toHaveBeenCalledTimes(3);
+      for (const [{ where }] of (prisma.userData.updateMany as jest.Mock).mock
+        .calls) {
+        expect(where).toHaveProperty("updatedAt");
+        expect(where.value).toEqual({ equals: { v: 1, subscriptions: {} } });
+      }
+    });
+
+    it("a retry that succeeds on the second attempt writes exactly once more", async () => {
+      (prisma.userData.findUnique as jest.Mock).mockResolvedValue({
+        value: { v: 1, subscriptions: {} },
+        updatedAt: new Date(),
+      });
+      (prisma.userData.updateMany as jest.Mock)
+        .mockResolvedValueOnce({ count: 0 })
+        .mockResolvedValueOnce({ count: 1 });
+
+      mockVerifyWebhookSignature.mockReturnValue(
+        subscriptionUpdatedEvent({ status: "past_due" }),
+      );
+
+      const res = await post();
+
+      expect(res.statusCode).toBe(200);
+      expect(prisma.userData.updateMany).toHaveBeenCalledTimes(2);
+    });
+  });
+});
+
+// ── § D9 — every identifier is guarded before use ──────────────────────────
+
+describe("D9 — every identifier is guarded before use", () => {
+  it("customer.subscription.updated with no resolvable customer never queries", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      subscriptionUpdatedEvent({ customer: null }),
+    );
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(prisma.user.findUnique).not.toHaveBeenCalled();
+    expect(prisma.userData.findUnique).not.toHaveBeenCalled();
+  });
+
+  it("customer.subscription.updated with no resolvable subscription id never queries userData", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      subscriptionUpdatedEvent({ id: undefined }),
+    );
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(prisma.user.findUnique).not.toHaveBeenCalled();
+    expect(prisma.userData.findUnique).not.toHaveBeenCalled();
+  });
+
+  it("invoice.payment_failed with no resolvable customer never queries", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      invoicePaymentFailedEvent({ customer: null }),
+    );
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(prisma.user.findUnique).not.toHaveBeenCalled();
+  });
+
+  it("an unrecognized subscription.status narrows to canceled — never an implied grant", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      subscriptionUpdatedEvent({ status: "some_future_status" }),
+    );
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    const call = (prisma.userData.create as jest.Mock).mock.calls[0][0];
+    const entry = call.data.value.subscriptions[SUBSCRIPTION_ID];
+    expect(entry.status).toBe("canceled");
+  });
+
+  it("no matching User row is a warn-and-continue — 200, no write, no User created", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(null);
+    mockVerifyWebhookSignature.mockReturnValue(invoicePaymentFailedEvent());
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(prisma.userData.findUnique).not.toHaveBeenCalled();
+    expect(prisma.user.create).not.toHaveBeenCalled();
+  });
+});
+
+// ── The signature still settles first ──────────────────────────────────────
+
+describe("the signature is still settled before anything else", () => {
+  it("answers 400 on an unsigned body and touches no dunning record", async () => {
+    mockVerifyWebhookSignature.mockImplementation(() => {
+      throw new MockStripeWebhookSignatureError("bad signature");
+    });
+
+    const res = await server.inject({
+      method: "POST",
+      url: "/v1/webhooks/stripe",
+      payload: VALID_BODY,
+      headers: { "content-type": "application/json" },
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(prisma.userData.findUnique).not.toHaveBeenCalled();
+  });
+});