create-ailk 0.4.0 → 0.6.0

package/templates/apps/api/src/routes/requests/__tests__/confirm.test.ts

@@ -0,0 +1,686 @@
+/**
+ * GET/POST /v1/requests/:id/confirm (#5970) — the pay half of
+ * request-and-confirm.
+ *
+ * Driven through `server.inject` against a Fastify instance that registers the
+ * real route group, so the urlencoded parser, the path shapes and the headers
+ * are all exercised rather than stubbed. The Stripe package is mocked at the
+ * PACKAGE boundary (`@working-theory/stripe-client`, which `lib/stripe.ts`
+ * re-exports), and Prisma through the repo-standard `__mocks__/prisma.ts`.
+ *
+ * "Before any Stripe call" is asserted by MEASURING the doubles rather than by
+ * reading the handler: every refusal case ends with both
+ * `createAdHocPrice` and `createPaymentLink` at zero calls.
+ */
+
+import type { FastifyInstance } from "fastify";
+import Fastify from "fastify";
+
+const mockCreateAdHocPrice = jest.fn();
+const mockCreatePaymentLink = jest.fn();
+const mockAssertSandboxKey = jest.fn();
+const mockSendRequestPaidLinkEmail = jest.fn();
+
+class MockUnknownProductCodeError extends Error {
+  constructor(code: string) {
+    super(`Unknown product code: ${code}`);
+    this.name = "UnknownProductCodeError";
+  }
+}
+class MockStripeConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "StripeConfigError";
+  }
+}
+
+jest.mock("@working-theory/stripe-client", () => ({
+  assertSandboxKey: (...args: unknown[]) => mockAssertSandboxKey(...args),
+  createAdHocPrice: (...args: unknown[]) => mockCreateAdHocPrice(...args),
+  createPaymentLink: (...args: unknown[]) => mockCreatePaymentLink(...args),
+  getStripeClient: jest.fn(),
+  UnknownProductCodeError: MockUnknownProductCodeError,
+  StripeConfigError: MockStripeConfigError,
+  STRIPE_API_VERSION: "2024-06-20",
+}));
+
+// The licence PACKAGE is the boundary the commerce gate reads, so that is what
+// is doubled — never `lib/require-commerce-claim.js` itself. The gate exercised
+// in the last describe block is therefore the REAL one, resolving a real
+// tri-state off a fake licence, which is the only way that test could notice
+// the gate being removed.
+const mockCheckLicense = jest.fn();
+jest.mock("@working-theory/license", () => ({
+  checkLicense: (...args: unknown[]) => mockCheckLicense(...args),
+  readStoredJwtState: jest.fn().mockResolvedValue({ state: "absent" }),
+}));
+
+jest.mock("@working-theory/email", () => ({
+  sendRequestConfirmEmail: jest.fn(),
+  sendRequestPaidLinkEmail: (...args: unknown[]) =>
+    mockSendRequestPaidLinkEmail(...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");
+
+import { prisma } from "../../../lib/prisma.js";
+import { hashConfirmToken } from "../../../services/request-confirm.js";
+import { requireCommerceClaim } from "../../../lib/require-commerce-claim.js";
+import { requestRoutes } from "../index.js";
+
+// A valid prefixed-UUIDv7 shape (ADR-0031) — `confirm.ts` now validates
+// `request.params.id` with `zCallbackId` (#6019 AC-3), and this fixture must
+// pass that gate exactly as a database-generated id would.
+const ID = "callbk_00000000-0000-7000-8000-000000000001";
+const TOKEN = "confirm-token-value";
+const PATH = `/v1/requests/${ID}/confirm`;
+const ROW = {
+  id: ID,
+  name: "Ada Lovelace",
+  phone: "+44 7700 900000",
+  preferredTime: "Tuesday morning",
+  payload: { email: "buyer@example.com" },
+};
+
+const ENV_KEYS = [
+  "AILK_REQUEST_CONFIRM_ENABLED",
+  "AILK_REQUEST_CONFIRM_TO",
+  "AILK_REQUEST_CONFIRM_FROM",
+  "AILK_REQUEST_CONFIRM_MAX_MINOR",
+  "AILK_PUBLIC_API_URL",
+  "STRIPE_SECRET_KEY",
+] as const;
+
+function enable(overrides: Record<string, string | undefined> = {}) {
+  process.env["AILK_REQUEST_CONFIRM_ENABLED"] = "true";
+  process.env["AILK_REQUEST_CONFIRM_TO"] = "owner@example.com";
+  process.env["AILK_REQUEST_CONFIRM_FROM"] = "hello@example.com";
+  process.env["AILK_PUBLIC_API_URL"] = "https://api.example.com";
+  process.env["STRIPE_SECRET_KEY"] = "sk_test_confirm_route";
+  for (const [key, value] of Object.entries(overrides)) {
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+}
+
+let server: FastifyInstance;
+
+beforeEach(async () => {
+  jest.clearAllMocks();
+  for (const key of ENV_KEYS) delete process.env[key];
+  enable();
+
+  mockAssertSandboxKey.mockImplementation(() => undefined);
+  mockCreateAdHocPrice.mockResolvedValue({
+    priceId: "price_1",
+    lookupKey: `ailk-request-${ID}`,
+  });
+  mockCreatePaymentLink.mockResolvedValue({
+    paymentLinkId: "plink_abc12345",
+    url: "https://buy.stripe.com/test_abc",
+  });
+  mockSendRequestPaidLinkEmail.mockResolvedValue({ ok: true, messageId: "m" });
+  (prisma.callback.findFirst as jest.Mock).mockResolvedValue(ROW);
+  (prisma.callback.updateMany as jest.Mock).mockResolvedValue({ count: 1 });
+  (prisma.callback.update as jest.Mock).mockResolvedValue({});
+
+  server = Fastify({ logger: false });
+  await server.register(requestRoutes);
+  await server.ready();
+});
+
+afterEach(async () => {
+  await server.close();
+  for (const key of ENV_KEYS) delete process.env[key];
+});
+
+function get(query = `?token=${TOKEN}`) {
+  return server.inject({ method: "GET", url: `${PATH}${query}` });
+}
+
+function post(fields: Record<string, string>) {
+  return server.inject({
+    method: "POST",
+    url: PATH,
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    payload: new URLSearchParams(fields).toString(),
+  });
+}
+
+const VALID_AMOUNT_FORM = {
+  token: TOKEN,
+  confirmedTime: "Tuesday 9am",
+  buyerEmail: "buyer@example.com",
+  amountMinor: "12900",
+  currency: "usd",
+};
+
+function noStripeCalls() {
+  expect(mockCreateAdHocPrice).not.toHaveBeenCalled();
+  expect(mockCreatePaymentLink).not.toHaveBeenCalled();
+}
+
+// ── GET — the form, its headers and its escaping (D7) ──────────────────────
+
+describe("GET — the confirm form", () => {
+  it("renders the form as html with the five security headers", async () => {
+    const res = await get();
+    expect(res.statusCode).toBe(200);
+    expect(res.headers["content-type"]).toBe("text/html; charset=utf-8");
+    expect(res.headers["cache-control"]).toBe("no-store");
+    // The token is in the query string — this is what keeps it out of a third
+    // party's referrer log.
+    expect(res.headers["referrer-policy"]).toBe("no-referrer");
+    expect(res.headers["x-robots-tag"]).toBe("noindex, nofollow");
+    expect(res.headers["content-security-policy"]).toContain(
+      "default-src 'none'",
+    );
+    expect(res.headers["content-security-policy"]).toContain(
+      "frame-ancestors 'none'",
+    );
+    // Neither of these falls back to `default-src` under CSP3.
+    expect(res.headers["content-security-policy"]).toContain(
+      "form-action 'self'",
+    );
+    expect(res.headers["content-security-policy"]).toContain("base-uri 'none'");
+    expect(res.headers["x-content-type-options"]).toBe("nosniff");
+    expect(res.body).toContain("Ada Lovelace");
+    expect(res.body).toContain("Confirm this request");
+  });
+
+  it("prefills the buyer email from the captured payload", async () => {
+    expect((await get()).body).toContain('value="buyer@example.com"');
+  });
+
+  it("escapes an attacker-supplied name rather than rendering it as markup", async () => {
+    (prisma.callback.findFirst as jest.Mock).mockResolvedValue({
+      ...ROW,
+      name: "<script>alert(1)</script>",
+    });
+    const res = await get();
+    expect(res.body).not.toContain("<script>alert(1)</script>");
+    expect(res.body).toContain("&lt;script&gt;alert(1)&lt;/script&gt;");
+  });
+
+  it("answers one 404 for a token that does not resolve, whatever the reason", async () => {
+    (prisma.callback.findFirst as jest.Mock).mockResolvedValue(null);
+    const res = await get("?token=tampered");
+    expect(res.statusCode).toBe(404);
+    noStripeCalls();
+  });
+
+  it("answers 404 with no token at all", async () => {
+    expect((await get("")).statusCode).toBe(404);
+  });
+
+  it("answers 404 when the feature is not configured", async () => {
+    delete process.env["AILK_REQUEST_CONFIRM_ENABLED"];
+    expect((await get()).statusCode).toBe(404);
+    expect(prisma.callback.findFirst).not.toHaveBeenCalled();
+  });
+
+  // #6019 AC-3: `:id` is validated with `zCallbackId` (the sibling routes'
+  // idiom) before anything else runs — a malformed id can never resolve a
+  // row anyway, so this changes nothing about what a caller learns, only
+  // where the request stops.
+  it("answers 404 for a malformed id, without ever querying Prisma", async () => {
+    const res = await server.inject({
+      method: "GET",
+      url: `/v1/requests/not-a-callback-id/confirm?token=${TOKEN}`,
+    });
+    expect(res.statusCode).toBe(404);
+    expect(prisma.callback.findFirst).not.toHaveBeenCalled();
+  });
+});
+
+// ── POST — the happy paths, both of D4's price routes ──────────────────────
+
+describe("POST — D4 path 2, an amount priced at confirm time", () => {
+  it("stamps, mints ONE Payment Link through an ad-hoc price, and emails the buyer", async () => {
+    const res = await post(VALID_AMOUNT_FORM);
+    expect(res.statusCode).toBe(200);
+
+    // The claim carries the stamp AND spends the credential, in one update.
+    const claim = (prisma.callback.updateMany as jest.Mock).mock.calls[0][0];
+    expect(claim.where.confirmTokenHash).toBe(hashConfirmToken(TOKEN));
+    expect(claim.data.confirmedAt).toBeInstanceOf(Date);
+    expect(claim.data.confirmedTime).toBe("Tuesday 9am");
+    expect(claim.data.confirmTokenHash).toBeNull();
+
+    expect(mockCreateAdHocPrice).toHaveBeenCalledTimes(1);
+    expect(mockCreateAdHocPrice.mock.calls[0][0]).toMatchObject({
+      currency: "usd",
+      unitAmountMinor: 12900,
+      lookupKey: `ailk-request-${ID}`,
+    });
+    expect(mockCreatePaymentLink).toHaveBeenCalledTimes(1);
+    // `completedSessionsLimit: 1` is what stops the emailed link staying
+    // permanently payable (#5970 security review round 2, M1).
+    expect(mockCreatePaymentLink).toHaveBeenCalledWith({
+      lookupKey: `ailk-request-${ID}`,
+      completedSessionsLimit: 1,
+    });
+
+    // The artifact id lands on the row — the key the webhook stamp matches on.
+    expect(prisma.callback.update).toHaveBeenCalledWith({
+      where: { id: ID },
+      data: { stripePaymentLinkId: "plink_abc12345" },
+    });
+
+    expect(mockSendRequestPaidLinkEmail).toHaveBeenCalledTimes(1);
+    expect(mockSendRequestPaidLinkEmail.mock.calls[0][0]).toMatchObject({
+      to: "buyer@example.com",
+      paymentUrl: "https://buy.stripe.com/test_abc",
+    });
+    expect(res.body).toContain("https://buy.stripe.com/test_abc");
+  });
+});
+
+describe("POST — D4 path 1, a price already in the tenant's catalogue", () => {
+  it("passes the lookup key straight to createPaymentLink and mints no price", async () => {
+    const res = await post({
+      token: TOKEN,
+      confirmedTime: "Tuesday 9am",
+      buyerEmail: "buyer@example.com",
+      lookupKey: "gutter-clean-standard",
+    });
+    expect(res.statusCode).toBe(200);
+    expect(mockCreateAdHocPrice).not.toHaveBeenCalled();
+    expect(mockCreatePaymentLink).toHaveBeenCalledWith({
+      lookupKey: "gutter-clean-standard",
+      completedSessionsLimit: 1,
+    });
+    // No amount was ever known, so none is stamped and none is emailed.
+    const claim = (prisma.callback.updateMany as jest.Mock).mock.calls[0][0];
+    expect(claim.data).not.toHaveProperty("amountMinor");
+    expect(mockSendRequestPaidLinkEmail.mock.calls[0][0]).not.toHaveProperty(
+      "amountMinor",
+    );
+  });
+});
+
+// ── POST — the refusals, every one before any Stripe call ──────────────────
+
+describe("POST — refusals before any Stripe call", () => {
+  it("refuses a form carrying BOTH a price and a lookup key", async () => {
+    const res = await post({ ...VALID_AMOUNT_FORM, lookupKey: "x" });
+    expect(res.statusCode).toBe(400);
+    noStripeCalls();
+    expect(prisma.callback.updateMany).not.toHaveBeenCalled();
+  });
+
+  it("refuses a form carrying NEITHER", async () => {
+    const { amountMinor: _a, currency: _c, ...rest } = VALID_AMOUNT_FORM;
+    const res = await post(rest);
+    expect(res.statusCode).toBe(400);
+    noStripeCalls();
+  });
+
+  it.each([
+    ["a zero amount", { amountMinor: "0" }],
+    ["a negative amount", { amountMinor: "-100" }],
+    ["a fractional amount", { amountMinor: "129.5" }],
+    ["a non-numeric amount", { amountMinor: "lots" }],
+    // #5970 security review round 3, L3 — a money amount must never be
+    // silently reinterpreted from exponent or hex notation.
+    ["an exponent-notation amount", { amountMinor: "1e5" }],
+    ["a hexadecimal amount", { amountMinor: "0x2710" }],
+    ["a padded amount", { amountMinor: " 500 " }],
+    ["a malformed currency", { currency: "dollars" }],
+    ["an unparseable buyer email", { buyerEmail: "not-an-address" }],
+    ["an empty confirmed time", { confirmedTime: "" }],
+  ])("refuses %s", async (_label, override) => {
+    const res = await post({ ...VALID_AMOUNT_FORM, ...override });
+    expect(res.statusCode).toBe(400);
+    noStripeCalls();
+    expect(prisma.callback.updateMany).not.toHaveBeenCalled();
+  });
+
+  it("refuses an amount above the configured ceiling", async () => {
+    enable({ AILK_REQUEST_CONFIRM_MAX_MINOR: "10000" });
+    const res = await post(VALID_AMOUNT_FORM);
+    expect(res.statusCode).toBe(400);
+    noStripeCalls();
+    expect(prisma.callback.updateMany).not.toHaveBeenCalled();
+  });
+
+  it("refuses a token that does not resolve, and mints nothing", async () => {
+    // The guarded claim reports zero rows — a tampered, expired, spent or
+    // cross-row token all land here identically.
+    (prisma.callback.updateMany as jest.Mock).mockResolvedValue({ count: 0 });
+    const res = await post(VALID_AMOUNT_FORM);
+    expect(res.statusCode).toBe(404);
+    noStripeCalls();
+  });
+
+  it("is single-use: a second POST with the same token is a 404 and mints nothing more", async () => {
+    const first = await post(VALID_AMOUNT_FORM);
+    expect(first.statusCode).toBe(200);
+    (prisma.callback.updateMany as jest.Mock).mockResolvedValue({ count: 0 });
+    const second = await post(VALID_AMOUNT_FORM);
+    expect(second.statusCode).toBe(404);
+    // One Payment Link across both requests.
+    expect(mockCreatePaymentLink).toHaveBeenCalledTimes(1);
+  });
+
+  it("refuses a live Stripe key before claiming the credential", async () => {
+    mockAssertSandboxKey.mockImplementation(() => {
+      throw new MockStripeConfigError("live mode blocked");
+    });
+    const res = await post(VALID_AMOUNT_FORM);
+    expect(res.statusCode).toBe(500);
+    noStripeCalls();
+    expect(prisma.callback.updateMany).not.toHaveBeenCalled();
+  });
+
+  it("answers 500 when Stripe is not configured at all", async () => {
+    delete process.env["STRIPE_SECRET_KEY"];
+    const res = await post(VALID_AMOUNT_FORM);
+    expect(res.statusCode).toBe(500);
+    noStripeCalls();
+  });
+
+  it("answers 404 when the feature is not configured", async () => {
+    delete process.env["AILK_REQUEST_CONFIRM_ENABLED"];
+    const res = await post(VALID_AMOUNT_FORM);
+    expect(res.statusCode).toBe(404);
+    noStripeCalls();
+  });
+
+  // #6019 AC-3 — the same params-first check as the GET handler; a malformed
+  // `:id` is refused before the credential preflight touches Prisma.
+  it("answers 404 for a malformed id, without ever querying Prisma or Stripe", async () => {
+    const res = await server.inject({
+      method: "POST",
+      url: "/v1/requests/not-a-callback-id/confirm",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      payload: new URLSearchParams(VALID_AMOUNT_FORM).toString(),
+    });
+    expect(res.statusCode).toBe(404);
+    noStripeCalls();
+    expect(prisma.callback.findFirst).not.toHaveBeenCalled();
+    expect(prisma.callback.updateMany).not.toHaveBeenCalled();
+  });
+});
+
+// ── POST — Stripe's own failures ───────────────────────────────────────────
+
+describe("POST — Stripe failures", () => {
+  it("maps an unknown lookup key to a 400 and creates no link", async () => {
+    mockCreatePaymentLink.mockRejectedValue(
+      new MockUnknownProductCodeError("nope"),
+    );
+    const res = await post({
+      token: TOKEN,
+      confirmedTime: "Tuesday 9am",
+      buyerEmail: "buyer@example.com",
+      lookupKey: "nope",
+    });
+    expect(res.statusCode).toBe(400);
+    expect(prisma.callback.update).not.toHaveBeenCalled();
+    expect(mockSendRequestPaidLinkEmail).not.toHaveBeenCalled();
+  });
+
+  it("answers 502 when the Stripe call fails for any other reason, and says the link is spent", async () => {
+    mockCreatePaymentLink.mockRejectedValue(new Error("socket hang up"));
+    const res = await post(VALID_AMOUNT_FORM);
+    expect(res.statusCode).toBe(502);
+    expect(mockSendRequestPaidLinkEmail).not.toHaveBeenCalled();
+    // #5970 security review round 3, L2: the page must not promise a retry
+    // the system cannot honour — there is no path that mints a fresh link.
+    expect(res.body).toContain("now used up");
+    expect(res.body).not.toContain("try again from a fresh link");
+  });
+
+  it("still returns the link, with different wording, when the buyer email fails", async () => {
+    mockSendRequestPaidLinkEmail.mockResolvedValue({
+      ok: false,
+      error: { kind: "send_failed", message: "rejected" },
+    });
+    const res = await post(VALID_AMOUNT_FORM);
+    expect(res.statusCode).toBe(200);
+    expect(res.body).toContain("https://buy.stripe.com/test_abc");
+    expect(res.body).toContain("could not email the customer");
+  });
+});
+
+// ── The claim-free property (AC-4 / D9) ────────────────────────────────────
+
+describe("no licence claim is read by this route's own files (AC-4)", () => {
+  it("has no @working-theory/license import in any file this feature added", () => {
+    const { readFileSync } = require("node:fs");
+    const files = [
+      "src/routes/requests/index.ts",
+      "src/routes/requests/confirm.ts",
+      "src/services/request-confirm.ts",
+    ];
+    for (const file of files) {
+      const source = readFileSync(`${__dirname}/../../../../${file}`, "utf8");
+      expect(source).not.toMatch(/from ["']@working-theory\/license["']/);
+      expect(source).not.toMatch(/\bcheckLicense\(/);
+      expect(source).not.toMatch(/\bresolveCommerceClaim\(/);
+    }
+  });
+});
+
+// ── The credential is checked before anything configuration-dependent ──────
+//
+// #5970 security review, finding 6. Every one of these cases holds NO valid
+// token, and every one must answer the same 404 an unresolvable token gets —
+// otherwise an anonymous caller reads the deployment's money posture off the
+// status codes, and can bisect `amountMinor` to recover the configured
+// ceiling.
+describe("POST — a caller with no credential learns nothing (finding 6)", () => {
+  beforeEach(() => {
+    // Nothing resolves: this caller holds no live token.
+    (prisma.callback.findFirst as jest.Mock).mockResolvedValue(null);
+  });
+
+  it.each([
+    [
+      "an amount above the ceiling",
+      VALID_AMOUNT_FORM,
+      { AILK_REQUEST_CONFIRM_MAX_MINOR: "10000" },
+    ],
+    ["both price paths at once", { ...VALID_AMOUNT_FORM, lookupKey: "x" }, {}],
+    ["a malformed body", { token: "nope" }, {}],
+    ["a live Stripe key", VALID_AMOUNT_FORM, {}],
+  ])("answers the uniform 404 for %s", async (label, form, env) => {
+    if (Object.keys(env).length > 0) enable(env);
+    if (label === "a live Stripe key") {
+      mockAssertSandboxKey.mockImplementation(() => {
+        throw new MockStripeConfigError("live mode blocked");
+      });
+    }
+    const res = await post(form as Record<string, string>);
+    expect(res.statusCode).toBe(404);
+    noStripeCalls();
+    expect(prisma.callback.updateMany).not.toHaveBeenCalled();
+  });
+
+  it("cannot be used to read the configured ceiling by bisection", async () => {
+    enable({ AILK_REQUEST_CONFIRM_MAX_MINOR: "10000" });
+    const under = await post({ ...VALID_AMOUNT_FORM, amountMinor: "5000" });
+    const over = await post({ ...VALID_AMOUNT_FORM, amountMinor: "50000" });
+    // Identical: the ceiling is invisible without a credential.
+    expect(under.statusCode).toBe(over.statusCode);
+    expect(under.statusCode).toBe(404);
+  });
+});
+
+// ── A typo'd lookup key gives the credential back (finding 4) ──────────────
+
+describe("POST — an unknown lookup key does not burn the credential", () => {
+  it("restores the digest and clears the stamp so the operator can retry", async () => {
+    mockCreatePaymentLink.mockRejectedValue(
+      new MockUnknownProductCodeError("typo"),
+    );
+    const res = await post({
+      token: TOKEN,
+      confirmedTime: "Tuesday 9am",
+      buyerEmail: "buyer@example.com",
+      lookupKey: "typo",
+    });
+    expect(res.statusCode).toBe(400);
+
+    // Two updateMany calls: the claim, then the release.
+    const calls = (prisma.callback.updateMany as jest.Mock).mock.calls;
+    expect(calls).toHaveLength(2);
+    const release = calls[1][0];
+    // `stripePaymentLinkId: null` is what makes "a row that produced nothing"
+    // a predicate rather than a claim about the one caller (round 2).
+    expect(release.where).toEqual({
+      id: ID,
+      confirmTokenHash: null,
+      stripePaymentLinkId: null,
+      paidAt: null,
+    });
+    // The digest comes back, and the stamp is cleared.
+    expect(release.data.confirmTokenHash).toBe(hashConfirmToken(TOKEN));
+    expect(release.data.confirmedAt).toBeNull();
+    expect(release.data.confirmedTime).toBeNull();
+    // The expiry is NOT rewritten — a release cannot extend a credential.
+    expect(release.data).not.toHaveProperty("confirmTokenExpiresAt");
+  });
+
+  it("does NOT release on a generic Stripe failure, which may have created a link", async () => {
+    mockCreatePaymentLink.mockRejectedValue(new Error("socket hang up"));
+    const res = await post(VALID_AMOUNT_FORM);
+    expect(res.statusCode).toBe(502);
+    expect((prisma.callback.updateMany as jest.Mock).mock.calls).toHaveLength(
+      1,
+    );
+  });
+});
+
+// ── The commerce gate covers BOTH verbs (AC-4 / spec D3) ───────────────────
+//
+// #5970 security review, § 8: every other case in this file registers
+// `requestRoutes` directly, which is the right isolation for the handlers but
+// leaves the GATE untested — and the gate is applied by COMPOSITION in
+// `server.ts` rather than by anything in the route files, which is precisely
+// why no route-level test would notice it disappearing. So this block builds
+// the scope the way `server.ts` builds it and drives both verbs through it.
+describe("the commerce claim gates both verbs (spec D3)", () => {
+  const gateLogLines: string[] = [];
+
+  async function buildGatedServer(): Promise<FastifyInstance> {
+    gateLogLines.length = 0;
+    const gated = Fastify({
+      logger: {
+        level: "warn",
+        stream: { write: (msg: string) => gateLogLines.push(msg) },
+      },
+    });
+    // The shape of `server.ts`'s own registration: the preHandler is attached
+    // to the scope BEFORE the routes are registered into it.
+    await gated.register(async (requestsScope) => {
+      // The wrapper `server.ts` registers, not the bare gate — so the
+      // unclaimed WARN line (spec D3's disclosed residual) is covered too.
+      requestsScope.addHook("preHandler", async (request, reply) => {
+        await requireCommerceClaim(request, reply);
+        if (reply.sent) {
+          request.log.warn(
+            {
+              outcome: "confirm_link_unclaimed",
+              path: request.routeOptions.url,
+            },
+            "request-confirm: a confirm link was opened on a site without the commerce claim",
+          );
+        }
+      });
+      await requestsScope.register(requestRoutes);
+    });
+    await gated.ready();
+    return gated;
+  }
+
+  it("answers the module-disabled 404 on GET and POST without the claim, touching nothing", async () => {
+    // What `requireCommerceClaim` does on an unclaimed site: short-circuits
+    // with the canonical not-found body.
+    // A licence that reads successfully and simply lacks the claim — the
+    // positively-established "no" the gate answers 404 on.
+    delete process.env["AILK_LICENSE_KEY"];
+    mockCheckLicense.mockResolvedValue({
+      tier: "free",
+      plan: "free",
+      features: [],
+      expiresAt: null,
+      revoked: false,
+    });
+    const gated = await buildGatedServer();
+    try {
+      const got = await gated.inject({
+        method: "GET",
+        url: `${PATH}?token=${TOKEN}`,
+      });
+      expect(got.statusCode).toBe(404);
+
+      const posted = await gated.inject({
+        method: "POST",
+        url: PATH,
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        payload: new URLSearchParams(VALID_AMOUNT_FORM).toString(),
+      });
+      expect(posted.statusCode).toBe(404);
+
+      // The gate ran BEFORE any handler: no row was read, none was stamped,
+      // and Stripe was never reached.
+      expect(prisma.callback.findFirst).not.toHaveBeenCalled();
+      expect(prisma.callback.updateMany).not.toHaveBeenCalled();
+      noStripeCalls();
+
+      // Spec D3 names this line as a bound on its own disclosed residual: a
+      // site configured for request-and-confirm but carrying no claim emails a
+      // confirm link that 404s. Without the line, the only place that
+      // misconfiguration surfaces is the tenant's inbox.
+      const warned = gateLogLines.join("\n");
+      expect(warned).toContain("confirm_link_unclaimed");
+      // Once per refused verb, GET and POST alike.
+      expect(warned.split("confirm_link_unclaimed")).toHaveLength(3);
+    } finally {
+      await gated.close();
+    }
+  });
+
+  it("lets the GET through once the claim is present", async () => {
+    mockCheckLicense.mockResolvedValue({
+      tier: "pro",
+      plan: "pro-monthly",
+      features: ["commerce"],
+      expiresAt: null,
+      revoked: false,
+    });
+    const gated = await buildGatedServer();
+    try {
+      const got = await gated.inject({
+        method: "GET",
+        url: `${PATH}?token=${TOKEN}`,
+      });
+      expect(got.statusCode).toBe(200);
+      expect(prisma.callback.findFirst).toHaveBeenCalled();
+    } finally {
+      await gated.close();
+    }
+  });
+});
+
+// ── A DB fault after Stripe succeeded is reported as itself (L3) ───────────
+
+describe("POST — the artifact id fails to record", () => {
+  it("still shows the live link, and does not claim the payment will be tracked", async () => {
+    // #5970 security review round 2, L3. Reporting this as a Stripe failure
+    // told the operator to retry from a fresh link when Stripe HAD created
+    // one — a live, chargeable link with no row to stamp.
+    (prisma.callback.update as jest.Mock).mockRejectedValue(
+      new Error("connection reset"),
+    );
+    const res = await post(VALID_AMOUNT_FORM);
+    expect(res.statusCode).toBe(200);
+    expect(res.body).toContain("https://buy.stripe.com/test_abc");
+    expect(res.body).toContain("could not record it against this request");
+    // And it does NOT tell them to try again from a fresh link.
+    expect(res.body).not.toContain("try again from a fresh link");
+  });
+});