create-ailk 0.21.0 → 0.23.0

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

@@ -0,0 +1,649 @@
+/**
+ * POST /v1/webhooks/stripe — the buyer's terms grant (#8765 D13, D14; spec
+ * docs/specs/8765-sign-up-refuses-without-the-spec.md AC-8).
+ *
+ * A `checkout.session.completed` whose Stripe terms box was accepted, and
+ * whose session carries the server-written `metadata.ailk_terms` stamp at the
+ * current `account_terms` version, writes ONE `checkout` grant for the
+ * buyer's Person. Absent consent, a missing or stale stamp, and an
+ * unresolvable buyer each log one `checkout-consent` line and write nothing;
+ * the order always completes (200).
+ *
+ * Harness: the signed-event harness of `stripe-livemode-live.test.ts` (the
+ * commerce claim present, `stripeKeyMode` controlled per test, the request
+ * logger captured), over the manual Prisma mock armed with
+ * `consent-ledger-double.ts` so the REAL `services/consent.ts` and
+ * `lib/consent-store.ts` run. The Person table is a small in-test store
+ * honouring `(workspaceId, email)`; the replay read is answered from the
+ * ledger double's rows. A proposal's Person is the mock's `piece.findFirst`
+ * answer, and a flow checkout's lead the `flowCheckout` / `lead` reads.
+ */
+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),
+}));
+
+let mockKeyMode: "live" | "test" = "live";
+// 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,
+}));
+
+const SITE_WS = "wksp_0190f3a2-7c1d-7e4a-9b2c-0000000000a1";
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../../lib/site.js", () => ({
+  ...jest.requireActual("../../../lib/site.js"),
+  resolveSiteWorkspaceId: jest.fn(async () => SITE_WS),
+}));
+
+import {
+  ACCOUNT_TERMS_PURPOSE_ID,
+  consentPurposeById,
+  resolveConsentStatement,
+  SITE_CONSENT_CONFIG_DEFAULTS,
+} from "@working-theory/validation";
+
+import * as configModule from "../../../config/index.js";
+import {
+  armConsentLedger,
+  type ConsentLedgerDouble,
+} from "../../../lib/__tests__/consent-ledger-double.js";
+import { prisma } from "../../../lib/prisma.js";
+import { recordCheckoutConsent } from "../../../services/consent.js";
+import { __resetIdempotencyStore } from "../../../lib/webhook-idempotency.js";
+import { stripeWebhookHandler } from "../stripe.js";
+
+const ACCOUNT_TERMS = consentPurposeById(
+  SITE_CONSENT_CONFIG_DEFAULTS,
+  ACCOUNT_TERMS_PURPOSE_ID,
+)!;
+const VERSION = ACCOUNT_TERMS.policyVersion;
+const STAMP = `${ACCOUNT_TERMS_PURPOSE_ID}@${VERSION}`;
+
+const PROPOSAL_WS = "wksp_0190f3a2-7c1d-7e4a-9b2c-0000000000a2";
+const PIECE_ID = "piece_0190f3a2-7c1d-7e4a-9b2c-0000000000b1";
+const SESSION_ID = "cs_live_a1b2c3d4e5f6";
+const PAYER_EMAIL = "b@x.example";
+const U1_EMAIL = "u1@verified.example";
+
+// ── The Person store ──────────────────────────────────────────────────────
+
+type PersonRow = {
+  id: string;
+  workspaceId: string;
+  email: string;
+  name: string | null;
+  userId: string | null;
+  billingCustomerId: string | null;
+};
+let people: PersonRow[] = [];
+let personSeq = 0;
+
+function nextPersonId(): string {
+  personSeq += 1;
+  return `person_0190f3a2-7c1d-7e4a-9b2c-${String(personSeq).padStart(12, "0")}`;
+}
+
+function matches(row: Record<string, unknown>, where: Record<string, unknown>) {
+  return Object.entries(where).every(([k, v]) => row[k] === v);
+}
+
+function armPeople(): void {
+  (prisma.person.findFirst as jest.Mock).mockImplementation(
+    async ({ where }: { where: Record<string, unknown> }) =>
+      people.find((p) => matches(p, where)) ?? null,
+  );
+  (prisma.person.createMany as jest.Mock).mockImplementation(
+    async ({ data }: { data: Array<Partial<PersonRow>> }) => {
+      let count = 0;
+      for (const d of data) {
+        if (
+          people.some(
+            (p) => p.workspaceId === d.workspaceId && p.email === d.email,
+          )
+        ) {
+          continue;
+        }
+        people.push({
+          id: nextPersonId(),
+          workspaceId: d.workspaceId!,
+          email: d.email!,
+          name: d.name ?? null,
+          userId: null,
+          billingCustomerId: null,
+        });
+        count += 1;
+      }
+      return { count };
+    },
+  );
+  (prisma.person.updateMany as jest.Mock).mockResolvedValue({ count: 0 });
+}
+
+// ── The ledger, plus the replay read the double does not model ────────────
+
+let double: ConsentLedgerDouble;
+
+function armLedger(): void {
+  double = armConsentLedger(prisma);
+  const ledgerRead = (prisma.$queryRaw as jest.Mock).getMockImplementation()!;
+  (prisma.$queryRaw as jest.Mock).mockImplementation(
+    (strings: TemplateStringsArray, ...values: unknown[]) => {
+      const sql = strings.join("?");
+      // recordCheckoutConsent's replay read: this Person's checkout row of
+      // this session, filtered by (workspace, person, purpose) first.
+      if (sql.includes(`"source" = 'checkout'`)) {
+        const [workspaceId, personId, purposeId, sessionId] =
+          values as string[];
+        return Promise.resolve(
+          double.ledger
+            .filter(
+              (r) =>
+                r.workspaceId === workspaceId &&
+                r.personId === personId &&
+                r.purposeId === purposeId &&
+                r.source === "checkout" &&
+                r.sourceRef === sessionId,
+            )
+            .map(() => ({ found: 1 })),
+        );
+      }
+      return ledgerRead(strings, ...values);
+    },
+  );
+}
+
+// ── The request log ───────────────────────────────────────────────────────
+
+type LogCall = [unknown, string?];
+const logCalls: LogCall[] = [];
+
+function consentLines(): Array<Record<string, unknown>> {
+  return logCalls
+    .map(([obj]) => obj)
+    .filter(
+      (obj): obj is Record<string, unknown> =>
+        typeof obj === "object" &&
+        obj !== null &&
+        (obj as Record<string, unknown>)["event"] === "checkout-consent",
+    );
+}
+
+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);
+      },
+    );
+    // With `logger: false` every request shares one logger object, so it is
+    // wrapped once, not once per request (which would repeat each line).
+    const wrapped = new WeakSet<object>();
+    webhooksScope.addHook("onRequest", async (request) => {
+      if (wrapped.has(request.log)) return;
+      wrapped.add(request.log);
+      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;
+}
+
+// ── Events ────────────────────────────────────────────────────────────────
+
+function completed(
+  eventId: string,
+  session: Record<string, unknown> = {},
+  livemode = true,
+): Record<string, unknown> {
+  return {
+    id: eventId,
+    type: "checkout.session.completed",
+    livemode,
+    data: {
+      object: {
+        id: SESSION_ID,
+        payment_status: "paid",
+        amount_total: 4900,
+        currency: "usd",
+        payment_link: null,
+        consent: { terms_of_service: "accepted" },
+        customer_details: { email: PAYER_EMAIL },
+        metadata: { ailk_terms: STAMP },
+        ...session,
+      },
+    },
+  };
+}
+
+/** The manual mock, seen as the host of the `auditLog` delegate it lacks. */
+function auditHost(): { auditLog: { create: jest.Mock } } {
+  // eslint-disable-next-line no-restricted-syntax -- the manual Prisma mock declares no auditLog delegate; this suite attaches one so the real audit writer runs
+  return prisma as unknown as { auditLog: { create: jest.Mock } };
+}
+
+let server: FastifyInstance;
+
+beforeEach(async () => {
+  jest.clearAllMocks();
+  logCalls.length = 0;
+  people = [];
+  personSeq = 0;
+  mockKeyMode = "live";
+  __resetIdempotencyStore();
+  jest.replaceProperty(configModule, "config", {
+    ...configModule.config,
+    STRIPE_WEBHOOK_SECRET: "whsec_test_secret",
+  });
+  armPeople();
+  armLedger();
+  (prisma.user.findUnique as jest.Mock).mockResolvedValue(null);
+  (prisma.user.findFirst as jest.Mock).mockResolvedValue(null);
+  (prisma.piece.updateMany as jest.Mock).mockResolvedValue({ count: 1 });
+  // No proposal Person and no completed flow checkout unless a test arranges
+  // one (clearAllMocks keeps a previous test's implementation).
+  (prisma.piece.findFirst as jest.Mock).mockResolvedValue(null);
+  (prisma.flowCheckout.findFirst as jest.Mock).mockResolvedValue(null);
+  (prisma.lead.findFirst as jest.Mock).mockResolvedValue(null);
+  // The proposal stamp's audit writer (`services/audit-log.ts`) writes through
+  // `auditLog.create`, which the manual mock does not carry.
+  auditHost().auditLog = { create: jest.fn().mockResolvedValue({}) };
+  server = await buildTestServer();
+});
+
+afterEach(async () => {
+  await server.close();
+});
+
+async function post(event: Record<string, unknown>) {
+  mockVerifyWebhookSignature.mockReturnValue(event);
+  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",
+    },
+  });
+}
+
+function personOf(workspaceId: string, email: string): PersonRow | undefined {
+  return people.find((p) => p.workspaceId === workspaceId && p.email === email);
+}
+
+// ── A standard session ────────────────────────────────────────────────────
+
+describe("a standard live session whose terms box was accepted", () => {
+  it("writes one dated checkout grant for the payer's Person in the site workspace", async () => {
+    const res = await post(completed("evt_consent_standard"));
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({ received: true });
+
+    const person = personOf(SITE_WS, PAYER_EMAIL);
+    expect(person).toBeDefined();
+    expect(double.ledger).toHaveLength(1);
+    const { statement } = resolveConsentStatement(ACCOUNT_TERMS, "en");
+    expect(double.ledger[0]).toMatchObject({
+      workspaceId: SITE_WS,
+      subjectType: "person",
+      subjectId: person!.id,
+      personId: person!.id,
+      purposeId: "account_terms",
+      granted: true,
+      source: "checkout",
+      sourceRef: SESSION_ID,
+      policyVersion: VERSION,
+      locale: "en",
+      statement,
+    });
+    expect(VERSION).toBe(2);
+    expect(double.ledger[0]!.createdAt).toBeInstanceOf(Date);
+
+    // One transaction whose first statement is the session's advisory lock.
+    expect(prisma.$transaction).toHaveBeenCalledTimes(1);
+    expect(prisma.$executeRaw).toHaveBeenCalledTimes(1);
+    const [, lockKey] = (prisma.$executeRaw as jest.Mock).mock.calls[0] as [
+      TemplateStringsArray,
+      string,
+    ];
+    expect(lockKey).toBe(`ailk:consent:${SITE_WS}:checkout:${SESSION_ID}`);
+
+    expect(consentLines()).toEqual([
+      {
+        event: "checkout-consent",
+        outcome: "recorded",
+        eventIdPrefix: "evt_cons",
+      },
+    ]);
+  });
+
+  it("the same event replayed — in-process and after a restart — still leaves one row", async () => {
+    const event = completed("evt_consent_replay");
+    await post(event);
+    expect(double.ledger).toHaveLength(1);
+
+    // In-process: the idempotency store short-circuits.
+    expect((await post(event)).statusCode).toBe(200);
+    expect(double.ledger).toHaveLength(1);
+
+    // After a restart (the in-memory store cleared): the ledger read refuses.
+    __resetIdempotencyStore();
+    logCalls.length = 0;
+    expect((await post(event)).statusCode).toBe(200);
+    expect(double.ledger).toHaveLength(1);
+    expect(consentLines()).toEqual([
+      {
+        event: "checkout-consent",
+        outcome: "unchanged",
+        eventIdPrefix: "evt_cons",
+      },
+    ]);
+  });
+
+  it("a signed-in buyer's session (metadata ailk_user_id u1) names the Person of u1's verified email", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue({
+      id: "u1",
+      email: "U1@Verified.example",
+      emailVerified: true,
+      billingProvider: null,
+      billingCustomerId: null,
+    });
+    const res = await post(
+      completed("evt_consent_buyer", {
+        metadata: { ailk_terms: STAMP, ailk_user_id: "u1" },
+      }),
+    );
+    expect(res.statusCode).toBe(200);
+
+    const buyer = personOf(SITE_WS, U1_EMAIL);
+    expect(buyer).toBeDefined();
+    expect(personOf(SITE_WS, PAYER_EMAIL)).toBeUndefined();
+    expect(double.ledger).toHaveLength(1);
+    expect(double.ledger[0]).toMatchObject({
+      personId: buyer!.id,
+      source: "checkout",
+    });
+  });
+
+  it("a test-mode standard session with an email and no buyer writes no row and creates no Person", async () => {
+    mockKeyMode = "test";
+    const res = await post(completed("evt_consent_testmode", {}, false));
+    expect(res.statusCode).toBe(200);
+    expect(double.ledger).toHaveLength(0);
+    expect(people).toHaveLength(0);
+    expect(prisma.person.createMany).not.toHaveBeenCalled();
+    expect(consentLines()).toEqual([
+      {
+        event: "checkout-consent",
+        outcome: "person_unresolved",
+        eventIdPrefix: "evt_cons",
+      },
+    ]);
+  });
+});
+
+// ── Proposal and flow sessions ────────────────────────────────────────────
+
+describe("a proposal or flow session", () => {
+  it("a proposal session → the row names the proposal's Person and workspace", async () => {
+    const PROPOSAL_PERSON = "person_0190f3a2-7c1d-7e4a-9b2c-0000000000c1";
+    (prisma.piece.findFirst as jest.Mock).mockImplementation(
+      async ({ where }: { where: Record<string, unknown> }) =>
+        where["id"] === PIECE_ID &&
+        where["workspaceId"] === PROPOSAL_WS &&
+        where["kind"] === "proposal"
+          ? { personId: PROPOSAL_PERSON }
+          : null,
+    );
+    const res = await post(
+      completed("evt_consent_proposal_person", {
+        metadata: {
+          ailk_terms: STAMP,
+          ailk_proposal: PIECE_ID,
+          ailk_workspace: PROPOSAL_WS,
+        },
+      }),
+    );
+    expect(res.statusCode).toBe(200);
+    expect(prisma.piece.findFirst).toHaveBeenCalledWith({
+      where: { id: PIECE_ID, workspaceId: PROPOSAL_WS, kind: "proposal" },
+      select: { personId: true },
+    });
+    expect(double.ledger).toHaveLength(1);
+    expect(double.ledger[0]).toMatchObject({
+      workspaceId: PROPOSAL_WS,
+      personId: PROPOSAL_PERSON,
+      subjectId: PROPOSAL_PERSON,
+      source: "checkout",
+      sourceRef: SESSION_ID,
+    });
+    // The payer's typed email minted no Person.
+    expect(people).toHaveLength(0);
+  });
+
+  it("a flow session → the row names the flow checkout's Person", async () => {
+    const FLOW_WS = "wksp_0190f3a2-7c1d-7e4a-9b2c-0000000000a3";
+    const FLOW_SESSION = "cs_live_flow00002";
+    const LEAD_EMAIL = "lead@flow.example";
+    (prisma.flowCheckout.findFirst as jest.Mock).mockImplementation(
+      async ({ where }: { where: Record<string, unknown> }) =>
+        where["id"] === "fco_00000001" &&
+        where["stripeSessionId"] === FLOW_SESSION &&
+        where["status"] === "completed"
+          ? { leadId: "lead_00000001", workspaceId: FLOW_WS }
+          : null,
+    );
+    (prisma.lead.findFirst as jest.Mock).mockResolvedValue({
+      email: LEAD_EMAIL,
+    });
+    const res = await post(
+      completed("evt_consent_flow_person", {
+        id: FLOW_SESSION,
+        metadata: { ailk_terms: STAMP, flowCheckoutId: "fco_00000001" },
+      }),
+    );
+    expect(res.statusCode).toBe(200);
+
+    const flowPerson = personOf(FLOW_WS, LEAD_EMAIL);
+    expect(flowPerson).toBeDefined();
+    expect(personOf(SITE_WS, PAYER_EMAIL)).toBeUndefined();
+    expect(people).toHaveLength(1);
+    expect(double.ledger).toHaveLength(1);
+    expect(double.ledger[0]).toMatchObject({
+      workspaceId: FLOW_WS,
+      personId: flowPerson!.id,
+      source: "checkout",
+      sourceRef: FLOW_SESSION,
+    });
+  });
+
+  it("an accepted proposal or flow session never falls through to the payer's email", async () => {
+    await post(
+      completed("evt_consent_proposal", {
+        metadata: {
+          ailk_terms: STAMP,
+          ailk_proposal: PIECE_ID,
+          ailk_workspace: PROPOSAL_WS,
+        },
+      }),
+    );
+    await post(
+      completed("evt_consent_flow", {
+        id: "cs_live_flow00001",
+        metadata: { ailk_terms: STAMP, flowCheckoutId: "fco_nope" },
+      }),
+    );
+    expect(personOf(SITE_WS, PAYER_EMAIL)).toBeUndefined();
+    expect(
+      double.ledger.filter(
+        (r) => r.personId !== null && r.workspaceId === SITE_WS,
+      ),
+    ).toEqual([]);
+  });
+});
+
+// ── Unstamped sessions ────────────────────────────────────────────────────
+
+describe("a session without the current terms stamp", () => {
+  it.each([
+    ["no metadata.ailk_terms", { metadata: {} }],
+    ["no metadata at all", { metadata: null }],
+    [
+      "an old version (account_terms@1)",
+      {
+        metadata: { ailk_terms: `${ACCOUNT_TERMS_PURPOSE_ID}@${VERSION - 1}` },
+      },
+    ],
+    [
+      "other terms (wt_platform_terms)",
+      { metadata: { ailk_terms: `wt_platform_terms@${VERSION}` } },
+    ],
+    ["a Payment Link session", { payment_link: "plink_1abc", metadata: {} }],
+  ])("%s → 200, no row, one terms_unstamped line", async (_label, session) => {
+    const res = await post(completed("evt_consent_unstamped", session));
+    expect(res.statusCode).toBe(200);
+    expect(double.ledger).toHaveLength(0);
+    expect(people).toHaveLength(0);
+    expect(consentLines()).toEqual([
+      {
+        event: "checkout-consent",
+        outcome: "terms_unstamped",
+        eventIdPrefix: "evt_cons",
+      },
+    ]);
+  });
+});
+
+// ── Absent consent ────────────────────────────────────────────────────────
+
+describe("a session whose terms box was not accepted", () => {
+  it.each([
+    ["consent: null", { consent: null }],
+    ["consent absent", { consent: undefined }],
+    [
+      "terms_of_service: declined",
+      { consent: { terms_of_service: "declined" } },
+    ],
+  ])("%s → 200, no row, one consent_absent line", async (_label, session) => {
+    const res = await post(completed("evt_consent_absent", session));
+    expect(res.statusCode).toBe(200);
+    expect(double.ledger).toHaveLength(0);
+    expect(consentLines()).toEqual([
+      {
+        event: "checkout-consent",
+        outcome: "consent_absent",
+        eventIdPrefix: "evt_cons",
+      },
+    ]);
+  });
+
+  it("the other stamps still run: the proposal stamp's audit row is written", async () => {
+    const res = await post(
+      completed("evt_consent_absent_proposal", {
+        consent: null,
+        metadata: {
+          ailk_terms: STAMP,
+          ailk_proposal: PIECE_ID,
+          ailk_workspace: PROPOSAL_WS,
+        },
+      }),
+    );
+    expect(res.statusCode).toBe(200);
+    expect(double.ledger).toHaveLength(0);
+    const auditCreate = auditHost().auditLog.create;
+    expect(auditCreate).toHaveBeenCalledTimes(1);
+    expect(auditCreate.mock.calls[0]![0]).toMatchObject({
+      data: {
+        workspaceId: PROPOSAL_WS,
+        action: "people.proposal.paid",
+        targetId: PIECE_ID,
+      },
+    });
+    expect(consentLines().map((l) => l["outcome"])).toEqual(["consent_absent"]);
+  });
+});
+
+// ── The stamp's version binds the write ───────────────────────────────────
+
+describe("recordCheckoutConsent", () => {
+  it("writes nothing when the stamped version is not the site registry's", async () => {
+    expect(
+      await recordCheckoutConsent({
+        workspaceId: SITE_WS,
+        personId: "person_0190f3a2-7c1d-7e4a-9b2c-0000000000d1",
+        sessionId: SESSION_ID,
+        policyVersion: VERSION + 1,
+      }),
+    ).toBe("version_changed");
+    expect(double.ledger).toHaveLength(0);
+    expect(prisma.$transaction).not.toHaveBeenCalled();
+  });
+});
+
+// ── Log hygiene ───────────────────────────────────────────────────────────
+
+describe("the log", () => {
+  it("no line carries the email or a full Person id", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue({
+      id: "u1",
+      email: U1_EMAIL,
+      emailVerified: true,
+      billingProvider: null,
+      billingCustomerId: null,
+    });
+    await post(completed("evt_consent_log_a"));
+    await post(
+      completed("evt_consent_log_b", {
+        id: "cs_live_second0001",
+        metadata: { ailk_terms: STAMP, ailk_user_id: "u1" },
+      }),
+    );
+    await post(completed("evt_consent_log_c", { consent: null }));
+    expect(people.length).toBeGreaterThan(0);
+    const text = JSON.stringify(logCalls);
+    expect(text).not.toContain(PAYER_EMAIL);
+    expect(text).not.toContain(U1_EMAIL);
+    for (const p of people) expect(text).not.toContain(p.id);
+    for (const line of consentLines()) {
+      expect(Object.keys(line).sort()).toEqual([
+        "event",
+        "eventIdPrefix",
+        "outcome",
+      ]);
+    }
+  });
+});