create-ailk 0.1.0 → 0.2.0

package/templates/apps/api/src/routes/flows/__tests__/recommender.test.ts

@@ -0,0 +1,671 @@
+/**
+ * @file recommender.test.ts
+ * Route-level inject tests for POST /v1/flows/:slug/save and
+ * POST /v1/flows/:slug/checkout (#4841).
+ *
+ * Mocks (external boundaries only — the repo's test rule):
+ *   - ../../../lib/prisma (auto-mock via __mocks__/prisma.ts) — the DB
+ *   - the `stripe` SDK itself — so the REAL @working-theory/stripe-client
+ *     (`createQuotedCheckoutSession`, `assertSandboxKey`) runs and AC-1's
+ *     assertions land on `stripe.checkout.sessions.create`'s own arguments
+ *   - @working-theory/email + @working-theory/license — reached through the
+ *     REAL routeLead, the recommender-capture.test.ts idiom
+ *
+ * The capture service (`captureRecommenderChoice` / `recordCheckout` /
+ * `attachStripeSession`) is the REAL module: "was it called" is asserted on
+ * its own prisma writes (`flowSession.create`, `lead.create`,
+ * `flowCheckout.create`, `flowCheckout.update`).
+ */
+
+import type { FastifyInstance } from "fastify";
+
+// eslint-disable-next-line no-restricted-syntax -- prisma is a DB boundary; __mocks__/prisma.ts activates the auto-mock (Jest requires explicit call for local files)
+jest.mock("../../../lib/prisma.js");
+
+const mockCheckoutSessionsCreate = jest.fn();
+const mockCheckoutSessionsExpire = jest.fn();
+jest.mock("stripe", () =>
+  jest.fn().mockImplementation(() => ({
+    checkout: {
+      sessions: { create: mockCheckoutSessionsCreate, expire: mockCheckoutSessionsExpire },
+    },
+  })),
+);
+
+jest.mock("@working-theory/email", () => ({
+  sendLeadNotification: jest.fn().mockResolvedValue({ ok: true, messageId: "msg-test" }),
+  sendDeliverableEmail: jest.fn().mockResolvedValue({ ok: true, messageId: "msg-deliverable" }),
+}));
+
+jest.mock("@working-theory/license", () => ({
+  checkLicense: jest.fn().mockResolvedValue({
+    tier: "free",
+    plan: null,
+    features: [],
+    expiresAt: null,
+    revoked: false,
+  }),
+}));
+
+import { encodePermalink, PERMALINK_VERSION } from "@working-theory/validation";
+
+import { prisma } from "../../../lib/prisma.js";
+import { __resetBuckets, rateLimitMiddleware } from "../../../middleware/rate-limit.js";
+import { checkoutRecommendationRoute, permalinkMetadata, saveRecommendationRoute } from "../recommender";
+
+// ─── Fixtures (the recommender-capture.test.ts register + config) ────────────
+
+const SITE = "default";
+const SLUG = "ailk-reco";
+const EMAIL = "buyer@example.com";
+const en = (s: string) => ({ en: s });
+
+const QUESTION_OPTIONS = [
+  { value: "solo", label: en("Solo") },
+  { value: "small_team", label: en("Small team") },
+];
+
+function offers(proAmount = 249, proPeriod: "annual" | "monthly" | "one-time" = "annual") {
+  return [
+    {
+      key: "free_oss",
+      copy: { name: en("Free (OSS)") },
+      price: { kind: "label" as const, label: en("Free — self-hosted") },
+      rules: [{ when: { answer: "q_team", eq: "solo" }, reason: en("Solo builders get it free.") }],
+    },
+    {
+      key: "pro",
+      copy: { name: en("Pro") },
+      price: { kind: "exact" as const, amount: proAmount, period: proPeriod },
+      rules: [{ when: { answer: "q_team", eq: "small_team" }, reason: en("Teams need seats.") }],
+    },
+  ];
+}
+
+function rateTable(opts: { currency?: string; amount?: number; period?: "annual" | "monthly" | "one-time" } = {}) {
+  return {
+    seatRates: [{ offer: "pro", amount: opts.amount ?? 249, period: opts.period ?? ("annual" as const) }],
+    creditLadder: {
+      denomination: "monthly" as const,
+      tiers: [{ credits: 10, amount: 99 }],
+      custom: en("Contact us for larger packages"),
+    },
+    ...(opts.currency !== undefined ? { currency: opts.currency } : {}),
+  };
+}
+
+type RegisterOpts = {
+  stripeConfigRef?: string | null;
+  rateTable?: Record<string, unknown>;
+  amount?: number;
+  period?: "annual" | "monthly" | "one-time";
+};
+
+function register(opts: RegisterOpts = {}) {
+  const table =
+    "rateTable" in opts
+      ? opts.rateTable
+      : rateTable({ currency: "usd", amount: opts.amount, period: opts.period });
+  return {
+    key: "reco-exp",
+    mode: "recommending" as const,
+    status: "live" as const,
+    waitlists: [{ key: "main", flowSlug: SLUG }],
+    questionSet: {
+      version: 1 as const,
+      questions: [
+        { id: "q_team", prompt: en("Team?"), answerType: "single" as const, options: QUESTION_OPTIONS },
+      ],
+    },
+    tracking: {
+      version: 1 as const,
+      utm: { source: "utm_source", medium: "utm_medium", campaign: "utm_campaign" },
+      waitlists: { main: { campaign: "reco-campaign", channels: ["organic"] } },
+    },
+    stripeConfigRef: "stripeConfigRef" in opts ? opts.stripeConfigRef : "stripe-main",
+    offers: offers(opts.amount, opts.period),
+    ...(table !== undefined ? { rateTable: table } : {}),
+  };
+}
+
+function flowConfig(opts: RegisterOpts = {}) {
+  const reg = register(opts);
+  return {
+    slug: SLUG,
+    defaultLocale: "en",
+    mode: "recommending" as const,
+    steps: [
+      {
+        key: "team",
+        type: "segmentation" as const,
+        copy: { title: en("Tell us about your team") },
+        questions: [{ name: "q_team", options: QUESTION_OPTIONS }],
+      },
+    ],
+    offers: reg.offers,
+    ...(reg.rateTable !== undefined ? { rateTable: reg.rateTable } : {}),
+    recommendation: { key: "recommendation", copy: { title: en("Your recommendation") } },
+    experiment: { key: "reco-exp", waitlist: "main" },
+  };
+}
+
+const ANSWERS = { q_team: "small_team" };
+
+function arm(opts: RegisterOpts = {}) {
+  const definition = { id: "flow_1", siteId: SITE, slug: SLUG, config: flowConfig(opts) };
+  (prisma.flowDefinition.findUnique as jest.Mock).mockImplementation(
+    async (args: { where: { siteId_slug: { slug: string } } }) =>
+      args.where.siteId_slug.slug === SLUG ? definition : null,
+  );
+  (prisma.waitlistExperiment.findMany as jest.Mock).mockResolvedValue([
+    { id: "wlexp_1", config: register(opts) },
+  ]);
+  (prisma.flowSession.create as jest.Mock).mockResolvedValue({ id: "flsess_new" });
+  (prisma.flowSession.findUnique as jest.Mock).mockImplementation(async (args: { where: { id: string } }) =>
+    args.where.id === "flsess_new"
+      ? { id: "flsess_new", siteId: SITE, flowSlug: SLUG, leadId: "lead_1", email: EMAIL }
+      : null,
+  );
+  (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+  (prisma.flowCheckout.create as jest.Mock).mockResolvedValue({ id: "flchk_1" });
+  (prisma.flowCheckout.updateMany as jest.Mock).mockResolvedValue({ count: 1 });
+  // #4912 — no prior keyed attempt unless a test arms one.
+  (prisma.flowCheckout.findUnique as jest.Mock).mockResolvedValue(null);
+  (prisma.lead.create as jest.Mock).mockResolvedValue({ id: "lead_1" });
+}
+
+const SAVE_BODY = { answers: ANSWERS, email: EMAIL, locale: "en" };
+const CHECKOUT_BODY = {
+  ...SAVE_BODY,
+  offerKey: "pro",
+  seats: 1,
+  period: "annual",
+  creditStop: { kind: "none" },
+  successUrl: "https://example.com/success",
+  cancelUrl: "https://example.com/cancel",
+};
+
+function buildApp(rateLimit?: { perIpPerMinute: number }): FastifyInstance {
+  const fastify = require("fastify")({ logger: false });
+  fastify.register(async (scope: FastifyInstance) => {
+    if (rateLimit) scope.register(rateLimitMiddleware, rateLimit);
+    await scope.register(saveRecommendationRoute);
+    await scope.register(checkoutRecommendationRoute);
+  });
+  return fastify;
+}
+
+let app: FastifyInstance;
+
+beforeEach(async () => {
+  jest.clearAllMocks();
+  __resetBuckets();
+  process.env.DATABASE_URL = "postgres://test";
+  // Split literal — create-ailk's build-templates secret-shape scanner
+  // (`\bsk_test_[A-Za-z0-9]{8,}`) must not see a contiguous test key in a
+  // file its snapshot copies; assertSandboxKey still sees the sk_test_ prefix.
+  process.env.STRIPE_SECRET_KEY = "sk_test_" + "recommender_route_key";
+  process.env.AILK_INBOX_FALLBACK_DIR = "/dev/null/ailk-fallback-unwritable";
+  // #4912 FR1 — the site origin the redirect allow-list is derived from. The
+  // CHECKOUT_BODY fixtures below are already on it, so every pre-#4912
+  // assertion is unchanged.
+  process.env.FRONTEND_URL = "https://example.com";
+  delete process.env.AILK_LEAD_NOTIFICATION_TO;
+  delete process.env.AILK_SITE_ID;
+  mockCheckoutSessionsExpire.mockResolvedValue({ id: "cs_test_reco_1", status: "expired" });
+  mockCheckoutSessionsCreate.mockResolvedValue({
+    id: "cs_test_reco_1",
+    url: "https://checkout.stripe.com/c/pay/cs_test_reco_1",
+  });
+  app = buildApp();
+  await app.ready();
+});
+
+afterEach(async () => {
+  await app.close();
+  delete process.env.STRIPE_SECRET_KEY;
+  delete process.env.FRONTEND_URL;
+});
+
+const checkout = (payload: unknown = CHECKOUT_BODY, slug = SLUG) =>
+  app.inject({ method: "POST", url: `/v1/flows/${slug}/checkout`, payload: payload as object });
+const save = (payload: unknown = SAVE_BODY, slug = SLUG) =>
+  app.inject({ method: "POST", url: `/v1/flows/${slug}/save`, payload: payload as object });
+
+function sessionCreateArg() {
+  expect(mockCheckoutSessionsCreate).toHaveBeenCalledTimes(1);
+  return mockCheckoutSessionsCreate.mock.calls[0][0];
+}
+
+// ─── AC-1 — metadata + amount + mode reach Stripe in TEST mode ───────────────
+
+describe("AC-1 — metadata + amount + mode reach Stripe in TEST mode", () => {
+  it("opens one subscription session at 24900 usd / year with the permalink + offer + row id in metadata, then attaches it", async () => {
+    arm();
+    const res = await checkout();
+    expect(res.statusCode).toBe(201);
+    expect(res.json()).toEqual({
+      ok: true,
+      data: { url: "https://checkout.stripe.com/c/pay/cs_test_reco_1", sessionId: "cs_test_reco_1" },
+    });
+
+    const arg = sessionCreateArg();
+    expect(arg.mode).toBe("subscription");
+    expect(arg.customer_email).toBe(EMAIL);
+    expect(arg.line_items).toHaveLength(1);
+    expect(arg.line_items[0].price_data.unit_amount).toBe(24900);
+    expect(arg.line_items[0].price_data.unit_amount).not.toBe(249);
+    expect(arg.line_items[0].price_data.currency).toBe("usd");
+    expect(arg.line_items[0].price_data.recurring).toEqual({ interval: "year" });
+    expect(arg.line_items[0].price_data.product_data.name).toBe("Pro");
+    expect(arg.metadata.permalink).toBe(
+      encodePermalink({ version: PERMALINK_VERSION, flowSlug: SLUG, answers: ANSWERS }),
+    );
+    expect(arg.metadata.offerKey).toBe("pro");
+    expect(arg.metadata.flowCheckoutId).toBe("flchk_1");
+    expect(arg.metadata.flowSlug).toBe(SLUG);
+    expect(arg.metadata.sessionId).toBe("flsess_new");
+    expect(arg.metadata.leadId).toBe("lead_1");
+
+    // attachStripeSession — the row's stripeSessionId stamp (+ #4912's replay
+    // URL, written in the same update), site-scoped.
+    expect(prisma.flowCheckout.updateMany).toHaveBeenCalledTimes(1);
+    expect((prisma.flowCheckout.updateMany as jest.Mock).mock.calls[0][0]).toEqual({
+      where: { id: "flchk_1", siteId: SITE, status: "created" },
+      data: {
+        stripeSessionId: "cs_test_reco_1",
+        checkoutUrl: "https://checkout.stripe.com/c/pay/cs_test_reco_1",
+      },
+    });
+  });
+
+  it("a one-time seat rate opens mode: payment with no recurring", async () => {
+    arm({ period: "one-time" });
+    const res = await checkout({ ...CHECKOUT_BODY, period: "one-time" });
+    expect(res.statusCode).toBe(201);
+    const arg = sessionCreateArg();
+    expect(arg.mode).toBe("payment");
+    expect(arg.line_items[0].price_data.recurring).toBeUndefined();
+  });
+
+  it("chunks a permalink past Stripe's 500-char metadata cap instead of truncating it", () => {
+    const long = "x".repeat(1201);
+    const meta = permalinkMetadata(long);
+    expect(Object.keys(meta)).toEqual(["permalink", "permalink_2", "permalink_3"]);
+    expect(meta.permalink + meta.permalink_2 + meta.permalink_3).toBe(long);
+    expect(permalinkMetadata("short")).toEqual({ permalink: "short" });
+  });
+});
+
+// ─── AC-2 — the server is the price authority ────────────────────────────────
+
+describe("AC-2 — the server is the price authority", () => {
+  it.each(["amount", "total", "unitAmount"])("a body carrying `%s` is a 400 invalid_input", async (field) => {
+    arm();
+    const res = await checkout({ ...CHECKOUT_BODY, [field]: 1 });
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error.code).toBe("invalid_input");
+    expect(mockCheckoutSessionsCreate).not.toHaveBeenCalled();
+    expect(prisma.flowCheckout.create).not.toHaveBeenCalled();
+  });
+
+  it("changing only the served seat rate changes unit_amount for the identical body", async () => {
+    arm({ amount: 300 });
+    const res = await checkout();
+    expect(res.statusCode).toBe(201);
+    expect(sessionCreateArg().line_items[0].price_data.unit_amount).toBe(30000);
+    expect((prisma.flowCheckout.create as jest.Mock).mock.calls[0][0].data.amountMinor).toBe(30000);
+  });
+});
+
+// ─── AC-3 — a non-sandbox key is refused before any side effect ──────────────
+
+describe("AC-3 — a non-sandbox key is refused before any side effect", () => {
+  it("returns 500 live-mode-forbidden and touches nothing", async () => {
+    arm();
+    process.env.STRIPE_SECRET_KEY = "sk_nope_" + "not_a_test_prefix";
+    const res = await checkout();
+    expect(res.statusCode).toBe(500);
+    expect(res.json().error.code).toBe("live-mode-forbidden");
+    expect(prisma.flowSession.create).not.toHaveBeenCalled();
+    expect(prisma.lead.create).not.toHaveBeenCalled();
+    expect(prisma.flowCheckout.create).not.toHaveBeenCalled();
+    expect(mockCheckoutSessionsCreate).not.toHaveBeenCalled();
+    expect(prisma.waitlistExperiment.findMany).not.toHaveBeenCalled();
+  });
+
+  it("returns 500 config-error when STRIPE_SECRET_KEY is unset", async () => {
+    arm();
+    delete process.env.STRIPE_SECRET_KEY;
+    const res = await checkout();
+    expect(res.statusCode).toBe(500);
+    expect(res.json().error.code).toBe("config-error");
+    expect(prisma.waitlistExperiment.findMany).not.toHaveBeenCalled();
+  });
+});
+
+// ─── AC-4 — gates and failure ordering ───────────────────────────────────────
+
+describe("AC-4 — gates and failure ordering", () => {
+  it("stripeConfigRef: null → 409 checkout_not_configured, no capture, no Stripe", async () => {
+    arm({ stripeConfigRef: null });
+    const res = await checkout();
+    expect(res.statusCode).toBe(409);
+    expect(res.json().error.code).toBe("checkout_not_configured");
+    expect(prisma.flowSession.create).not.toHaveBeenCalled();
+    expect(mockCheckoutSessionsCreate).not.toHaveBeenCalled();
+  });
+
+  it("no rateTable.currency → 409 checkout_not_configured, no capture, no Stripe", async () => {
+    arm({ rateTable: rateTable() });
+    const res = await checkout();
+    expect(res.statusCode).toBe(409);
+    expect(res.json().error.code).toBe("checkout_not_configured");
+    expect(prisma.flowSession.create).not.toHaveBeenCalled();
+    expect(mockCheckoutSessionsCreate).not.toHaveBeenCalled();
+  });
+
+  it("an unknown slug → 404 flow_not_found", async () => {
+    arm();
+    const res = await checkout(CHECKOUT_BODY, "no-such-flow");
+    expect(res.statusCode).toBe(404);
+    expect(res.json().error.code).toBe("flow_not_found");
+    expect(mockCheckoutSessionsCreate).not.toHaveBeenCalled();
+  });
+
+  it("an offerKey the register does not declare → 400 invalid_input", async () => {
+    arm();
+    const res = await checkout({ ...CHECKOUT_BODY, offerKey: "enterprise" });
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error.code).toBe("invalid_input");
+    expect(res.body).not.toContain("enterprise");
+    expect(prisma.flowSession.create).not.toHaveBeenCalled();
+  });
+
+  it("a Stripe rejection → 502 checkout-unavailable AFTER the session, lead and row exist; never attached", async () => {
+    arm();
+    mockCheckoutSessionsCreate.mockRejectedValue(new Error("stripe down"));
+    const res = await checkout();
+    expect(res.statusCode).toBe(502);
+    expect(res.json().error.code).toBe("checkout-unavailable");
+    expect(res.body).not.toContain("stripe down");
+    expect(prisma.flowSession.create).toHaveBeenCalledTimes(1);
+    expect(prisma.lead.create).toHaveBeenCalledTimes(1);
+    expect(prisma.flowCheckout.create).toHaveBeenCalledTimes(1);
+    expect(mockCheckoutSessionsCreate).toHaveBeenCalledTimes(1);
+    expect(prisma.flowCheckout.updateMany).not.toHaveBeenCalled();
+  });
+
+  it("a stripe session id that attaches to no row → 502 checkout-unavailable with an attach_miss warn, never a 201", async () => {
+    arm();
+    (prisma.flowCheckout.updateMany as jest.Mock).mockResolvedValue({ count: 0 });
+    const warns: unknown[][] = [];
+    await app.close();
+    app = buildApp();
+    app.addHook("onRequest", async (request) => {
+      const original = request.log.warn.bind(request.log);
+      request.log.warn = ((...args: unknown[]) => {
+        warns.push(args);
+        return (original as (...a: unknown[]) => void)(...args);
+      }) as typeof request.log.warn;
+    });
+    await app.ready();
+    const res = await checkout();
+    expect(res.statusCode).toBe(502);
+    expect(res.json().error.code).toBe("checkout-unavailable");
+    expect(mockCheckoutSessionsCreate).toHaveBeenCalledTimes(1);
+    const miss = warns.find((w) => (w[0] as { outcome?: string })?.outcome === "attach_miss");
+    expect(miss?.[0]).toEqual({
+      slug: SLUG,
+      flowCheckoutIdPrefix: "flchk_1",
+      outcome: "attach_miss",
+      sessionCompensation: "expired",
+      // The row mark uses the same match that just failed to attach, so it
+      // reports the miss rather than claiming it acted.
+      rowCompensation: "row_mark_missed",
+    });
+    expect(JSON.stringify(warns)).not.toContain(EMAIL);
+  });
+
+  it("seats above the ceiling is a 400 invalid_input, no row (the service enforces the same bound — recommender-capture.test.ts)", async () => {
+    arm();
+    const res = await checkout({ ...CHECKOUT_BODY, seats: 1000 });
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error.code).toBe("invalid_input");
+    expect(prisma.flowCheckout.create).not.toHaveBeenCalled();
+  });
+
+  it("a lead-routing failure → 502 lead_failed with no row and no Stripe call", async () => {
+    arm();
+    (prisma.lead.create as jest.Mock).mockRejectedValue(new Error("db down"));
+    const res = await checkout();
+    expect(res.statusCode).toBe(502);
+    expect(res.json().error.code).toBe("lead_failed");
+    expect(prisma.flowCheckout.create).not.toHaveBeenCalled();
+    expect(mockCheckoutSessionsCreate).not.toHaveBeenCalled();
+  });
+});
+
+// ─── AC-5 — save ─────────────────────────────────────────────────────────────
+
+describe("AC-5 — save", () => {
+  it("returns 200 { leadId, sessionId } after one save capture, never touching Stripe or the checkout row", async () => {
+    arm();
+    const res = await save();
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({ ok: true, data: { leadId: "lead_1", sessionId: "flsess_new" } });
+    expect(prisma.flowSession.create).toHaveBeenCalledTimes(1);
+    const leadData = (prisma.lead.create as jest.Mock).mock.calls[0][0].data;
+    expect(leadData.payload.recommender.choice).toBe("save");
+    expect(prisma.flowCheckout.create).not.toHaveBeenCalled();
+    expect(mockCheckoutSessionsCreate).not.toHaveBeenCalled();
+  });
+
+  it("rejects a body with no email (400) and an unknown slug (404)", async () => {
+    arm();
+    const bad = await save({ answers: ANSWERS });
+    expect(bad.statusCode).toBe(400);
+    expect(bad.json().error.code).toBe("invalid_input");
+    const missing = await save(SAVE_BODY, "no-such-flow");
+    expect(missing.statusCode).toBe(404);
+    expect(missing.json().error.code).toBe("flow_not_found");
+    expect(prisma.lead.create).not.toHaveBeenCalled();
+  });
+
+  it("a save on a non-recommending flow is a 409 checkout_not_configured", async () => {
+    arm();
+    const { slug, defaultLocale, steps } = flowConfig();
+    (prisma.flowDefinition.findUnique as jest.Mock).mockResolvedValue({
+      id: "flow_1",
+      siteId: SITE,
+      slug: SLUG,
+      config: { slug, defaultLocale, steps },
+    });
+    const res = await save();
+    expect(res.statusCode).toBe(409);
+    expect(res.json().error.code).toBe("checkout_not_configured");
+  });
+});
+
+// ─── #4912 AC-1 — the redirect-origin allow-list ─────────────────────────────
+
+describe("#4912 AC-1 — a redirect off the site's own origin never reaches Stripe", () => {
+  it.each([
+    ["successUrl", { successUrl: "https://evil.example/success" }],
+    ["cancelUrl", { cancelUrl: "https://evil.example/cancel" }],
+    ["a look-alike host", { successUrl: "https://example.com.evil.example/success" }],
+    ["a subdomain of the site origin", { successUrl: "https://checkout.example.com/success" }],
+    ["a different scheme on the same host", { successUrl: "http://example.com/success" }],
+    ["a different port on the same host", { successUrl: "https://example.com:8443/success" }],
+  ])("refuses %s with 400 invalid_input and writes nothing", async (_label, override) => {
+    arm();
+    const res = await checkout({ ...CHECKOUT_BODY, ...override });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error.code).toBe("invalid_input");
+    // The offending URL is never echoed back.
+    expect(res.body).not.toContain("evil.example");
+    // Refused before every side effect: no session, no lead, no row, no Stripe.
+    expect(prisma.flowSession.create).not.toHaveBeenCalled();
+    expect(prisma.lead.create).not.toHaveBeenCalled();
+    expect(prisma.flowCheckout.create).not.toHaveBeenCalled();
+    expect(mockCheckoutSessionsCreate).not.toHaveBeenCalled();
+  });
+
+  it("passes an allow-listed origin through to Stripe unchanged", async () => {
+    arm();
+    const res = await checkout();
+
+    expect(res.statusCode).toBe(201);
+    const arg = sessionCreateArg();
+    expect(arg.success_url).toBe("https://example.com/success");
+    expect(arg.cancel_url).toBe("https://example.com/cancel");
+  });
+
+  it("follows FRONTEND_URL — the same body is refused once the site origin moves", async () => {
+    arm();
+    process.env.FRONTEND_URL = "https://other-site.example";
+    const res = await checkout();
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error.code).toBe("invalid_input");
+    expect(mockCheckoutSessionsCreate).not.toHaveBeenCalled();
+  });
+
+  it("an unparseable FRONTEND_URL is a 500 config-error, never a widened allow-list", async () => {
+    arm();
+    process.env.FRONTEND_URL = "not-a-url";
+    const res = await checkout();
+
+    expect(res.statusCode).toBe(500);
+    expect(res.json().error.code).toBe("config-error");
+    expect(mockCheckoutSessionsCreate).not.toHaveBeenCalled();
+  });
+});
+
+// ─── #4912 AC-3 — one row and one Stripe session per identical submission ────
+
+describe("#4912 AC-3 — a double submit is idempotent", () => {
+  it("replays the first /checkout's { url, sessionId } — one row, one Stripe session", async () => {
+    arm();
+    // The second call's keyed lookup finds what the first call wrote.
+    (prisma.flowCheckout.findUnique as jest.Mock)
+      .mockResolvedValueOnce(null)
+      .mockResolvedValue({
+        id: "flchk_1",
+        status: "created",
+        stripeSessionId: "cs_test_reco_1",
+        checkoutUrl: "https://checkout.stripe.com/c/pay/cs_test_reco_1",
+        createdAt: new Date(),
+      });
+
+    const first = await checkout();
+    const second = await checkout();
+
+    expect(first.statusCode).toBe(201);
+    expect(second.statusCode).toBe(201);
+    expect(second.json()).toEqual(first.json());
+    expect(second.json()).toEqual({
+      ok: true,
+      data: { url: "https://checkout.stripe.com/c/pay/cs_test_reco_1", sessionId: "cs_test_reco_1" },
+    });
+    expect(prisma.flowCheckout.create).toHaveBeenCalledTimes(1);
+    expect(mockCheckoutSessionsCreate).toHaveBeenCalledTimes(1);
+  });
+
+  it("two identical /save submissions produce ONE Lead", async () => {
+    arm();
+    const first = await save();
+    expect(first.statusCode).toBe(200);
+    const { sessionId, leadId } = first.json().data;
+
+    // The browser holds the session id it was just handed (FlowStepperClient
+    // persists it to sessionStorage) and sends it again on the resubmit.
+    const second = await save({ ...SAVE_BODY, sessionId });
+
+    expect(second.statusCode).toBe(200);
+    expect(second.json().data).toEqual({ leadId, sessionId });
+    expect(prisma.lead.create).toHaveBeenCalledTimes(1);
+    expect(prisma.flowSession.create).toHaveBeenCalledTimes(1);
+  });
+});
+
+// ─── #4912 AC-4 — the attach-miss compensation ───────────────────────────────
+
+describe("#4912 AC-4 — an attach-miss expires the orphaned Stripe session", () => {
+  it("expires the session and marks the row before the 502 returns", async () => {
+    arm();
+    (prisma.flowCheckout.updateMany as jest.Mock).mockResolvedValue({ count: 0 });
+
+    const res = await checkout();
+
+    expect(res.statusCode).toBe(502);
+    expect(res.json().error.code).toBe("checkout-unavailable");
+    // The session Stripe opened is closed, not left live and payable.
+    expect(mockCheckoutSessionsExpire).toHaveBeenCalledTimes(1);
+    expect(mockCheckoutSessionsExpire).toHaveBeenCalledWith("cs_test_reco_1");
+    // …and the row mark is attempted, guarded on `status: "created"` so it can
+    // never downgrade a row the webhook already completed.
+    const marks = (prisma.flowCheckout.updateMany as jest.Mock).mock.calls.filter(
+      (call: [{ data: Record<string, unknown> }]) => call[0].data["status"] === "expired",
+    );
+    expect(marks).toHaveLength(1);
+    expect(marks[0][0]).toEqual({
+      where: { id: "flchk_1", siteId: SITE, status: "created" },
+      data: { status: "expired", idempotencyKey: null, checkoutUrl: null },
+    });
+  });
+
+  it("refuses a 201 for a row another attempt already killed — the payment would be unrecordable", async () => {
+    arm();
+    // The stamp is guarded on `status: "created"`, the same leg the #4838
+    // webhook joins on. A row reconciled out from under this request therefore
+    // matches nothing, and handing the visitor that URL would produce a real
+    // payment the webhook could never attribute.
+    (prisma.flowCheckout.updateMany as jest.Mock).mockImplementation(
+      async (args: { where: { status?: string } }) =>
+        args.where.status === "created" ? { count: 0 } : { count: 1 },
+    );
+
+    const res = await checkout();
+
+    expect(res.statusCode).toBe(502);
+    expect(res.json().error.code).toBe("checkout-unavailable");
+    expect(mockCheckoutSessionsExpire).toHaveBeenCalledWith("cs_test_reco_1");
+  });
+
+  it("still returns the 502 when the expire call itself fails", async () => {
+    arm();
+    (prisma.flowCheckout.updateMany as jest.Mock).mockResolvedValue({ count: 0 });
+    mockCheckoutSessionsExpire.mockRejectedValue(new Error("stripe down"));
+
+    const res = await checkout();
+
+    expect(res.statusCode).toBe(502);
+    expect(res.json().error.code).toBe("checkout-unavailable");
+    expect(res.body).not.toContain("stripe down");
+  });
+
+  it("never expires a session on the happy path", async () => {
+    arm();
+    const res = await checkout();
+    expect(res.statusCode).toBe(201);
+    expect(mockCheckoutSessionsExpire).not.toHaveBeenCalled();
+  });
+});
+
+// ─── AC-6 — the scope's rate limit ───────────────────────────────────────────
+
+describe("AC-6 — the flows scope's per-IP rate limit covers both routes", () => {
+  it("returns 429 past the limit", async () => {
+    await app.close();
+    app = buildApp({ perIpPerMinute: 2 });
+    await app.ready();
+    arm();
+    expect((await save()).statusCode).toBe(200);
+    expect((await save()).statusCode).toBe(200);
+    const limited = await checkout();
+    expect(limited.statusCode).toBe(429);
+    expect(mockCheckoutSessionsCreate).not.toHaveBeenCalled();
+  });
+});