create-ailk 0.22.0 → 0.23.0

package/templates/apps/api/src/routes/checkout/__tests__/offerings-authorization.test.ts

@@ -0,0 +1,1300 @@
+/**
+ * The Offerings checkout (#8931; spec
+ * docs/specs/8931-offerings-checkout-authorization-server-side-spec.md AC-1 …
+ * AC-6 and AC-3's composed A9 and A13 cases; contract A-T1, A-T2, A-T3).
+ *
+ * The harness drives `checkoutRoutes` through `app.inject()` on a Fastify
+ * instance configured as `server.ts` configures its own (`trustProxy`, the
+ * `req` serializer), with a logger whose stream captures every line.
+ * Mocked: the resolver, `store.js`, `connection.js`, the session record store
+ * and `chargeWriteBudget`. Real: `getSellableProductIds`, `normalizeCatalog`,
+ * `parseLookupKey` and the `stripe-client` calls, run against a fake client
+ * object. `STRIPE_SECRET_KEY` is unset, so any env-path answer is
+ * `500 stripe-not-configured`, distinguishable from every Offerings answer.
+ * The A9 cases set a composed `sk_test_` key and mock the `stripe` SDK, so the
+ * real `createCheckoutSession` runs the real `isOfferingsProduct`; the #9126
+ * cases set one too, so the env path they keep is a sale, not a 500.
+ */
+import { Writable } from "node:stream";
+
+import { logger } from "@working-theory/observability";
+import Fastify, { type FastifyInstance } from "fastify";
+
+jest.mock("@working-theory/analytics/server", () => ({
+  track: jest.fn().mockResolvedValue(undefined),
+}));
+// `server.ts` (for `requestLogSerializer`) reaches the email package, whose
+// React Email dependency is ESM-only.
+jest.mock("@working-theory/email", () => ({
+  sendLeadNotification: jest.fn().mockResolvedValue({ ok: true }),
+}));
+
+const mockEnvPricesList = jest.fn();
+const mockEnvSessionsCreate = jest.fn();
+const mockEnvSessionsRetrieve = jest.fn();
+const mockEnvCustomersCreate = jest.fn();
+jest.mock("stripe", () =>
+  jest.fn().mockImplementation(() => ({
+    prices: { list: mockEnvPricesList },
+    customers: { create: mockEnvCustomersCreate },
+    checkout: {
+      sessions: {
+        create: mockEnvSessionsCreate,
+        retrieve: mockEnvSessionsRetrieve,
+      },
+    },
+  })),
+);
+
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted; the DB boundary, mirrors sessions.test.ts
+jest.mock("../../../lib/prisma.js", () => ({
+  prisma: {
+    session: { findUnique: jest.fn() },
+    user: { findUnique: jest.fn() },
+    apiToken: { findUnique: jest.fn(), update: jest.fn() },
+  },
+}));
+
+const mockResolvePublicWorkspace = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- the resolver reads the spoke registry and the workspace table; the spec's harness (§5) stubs its answers.
+jest.mock("../../../services/public-site-resolver.js", () => ({
+  ...jest.requireActual("../../../services/public-site-resolver.js"),
+  resolvePublicWorkspace: (...args: unknown[]) =>
+    mockResolvePublicWorkspace(...args),
+}));
+
+const mockOrganizationIdOfWorkspace = jest.fn();
+const mockReadWorkspaceSelection = jest.fn();
+const mockReadEnabledProductIds = jest.fn();
+const mockReadWorkspaceSnapshot = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- store.js is the Offerings rows' one database file (#8876); the rows are stubbed here, the readers above them run as themselves.
+jest.mock("../../../services/offerings/store.js", () => ({
+  ...jest.requireActual("../../../services/offerings/store.js"),
+  organizationIdOfWorkspace: (...args: unknown[]) =>
+    mockOrganizationIdOfWorkspace(...args),
+  readWorkspaceSelection: (...args: unknown[]) =>
+    mockReadWorkspaceSelection(...args),
+  readEnabledProductIds: (...args: unknown[]) =>
+    mockReadEnabledProductIds(...args),
+  readWorkspaceSnapshot: (...args: unknown[]) =>
+    mockReadWorkspaceSnapshot(...args),
+}));
+
+const mockConnectionSummary = jest.fn();
+const mockClientForOrganization = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- the connection custody wraps the database and the AES-GCM key (#8907); the spec's harness stubs its two answers.
+jest.mock("../../../services/offerings/connection.js", () => ({
+  getStripeConnectionSummary: (...args: unknown[]) =>
+    mockConnectionSummary(...args),
+  stripeClientForOrganization: (...args: unknown[]) =>
+    mockClientForOrganization(...args),
+}));
+
+const mockRecordCheckoutSession = jest.fn();
+const mockReadCheckoutSessionRecord = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- the session record wraps the database (#8930); its write and read are stubbed.
+jest.mock("../../../services/offerings/checkout-session-record.js", () => ({
+  ...jest.requireActual(
+    "../../../services/offerings/checkout-session-record.js",
+  ),
+  recordCheckoutSession: (...args: unknown[]) =>
+    mockRecordCheckoutSession(...args),
+  readCheckoutSessionRecord: (...args: unknown[]) =>
+    mockReadCheckoutSessionRecord(...args),
+}));
+
+const mockChargeWriteBudget = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- chargeWriteBudget runs on the database store (#8907); the bucket's answers are stubbed, the rest of the module is real.
+jest.mock("../../../middleware/rate-limit.js", () => ({
+  ...jest.requireActual("../../../middleware/rate-limit.js"),
+  chargeWriteBudget: (...args: unknown[]) => mockChargeWriteBudget(...args),
+}));
+
+import { config } from "../../../config/index.js";
+import { prisma } from "../../../lib/prisma.js";
+import { requestLogSerializer } from "../../../server.js";
+import { CheckoutSessionRecordError } from "../../../services/offerings/checkout-session-record.js";
+import { checkoutRoutes } from "../index";
+
+config.FRONTEND_URL = "https://example.com";
+config.TRUSTED_ORIGINS = ["https://example.com"];
+
+/** The mocked SDK constructor: a call to it is the env client being built. */
+const envStripeConstructor = () => jest.requireMock("stripe") as jest.Mock;
+
+// ── Fixture ──────────────────────────────────────────────────────────────────
+
+const WS = "wksp_00000000-0000-7000-8000-000000008931";
+const ORG = "org_00000000-0000-7000-8000-000000008931";
+const SESSION_ID = "cs_test_a1B2c3D4e5F6g7H8offerings8931";
+const SESSION_URL = `https://checkout.stripe.com/c/pay/${SESSION_ID}`;
+const SUMMARY = {
+  mode: "test",
+  last4: "4242",
+  connectedAt: "2026-10-18T00:00:00.000Z",
+  liveAt: null,
+  updatedAt: "2026-10-18T00:00:00.000Z",
+};
+
+function product(id: string, overrides: Record<string, unknown> = {}) {
+  return {
+    id,
+    object: "product",
+    active: true,
+    name: `Product ${id.slice(5)}`,
+    metadata: { ailk_group: "plan" },
+    ...overrides,
+  };
+}
+
+function recurringPrice(id: string, lookupKey: string, prod: unknown) {
+  return {
+    id,
+    object: "price",
+    active: true,
+    product: prod,
+    lookup_key: lookupKey,
+    type: "recurring",
+    recurring: { interval: "month", interval_count: 1, usage_type: "licensed" },
+    billing_scheme: "per_unit",
+    unit_amount: 2900,
+    currency: "usd",
+  };
+}
+
+function oneTimePrice(id: string, lookupKey: string, prod: unknown) {
+  return {
+    id,
+    object: "price",
+    active: true,
+    product: prod,
+    lookup_key: lookupKey,
+    type: "one_time",
+    recurring: null,
+    billing_scheme: "per_unit",
+    unit_amount: 9900,
+    currency: "usd",
+  };
+}
+
+const PROD_A = product("prod_A8931");
+const PROD_B = product("prod_B8931");
+const PROD_C = product("prod_C8931");
+const PROD_D = product("prod_D8931");
+const PROD_X = product("prod_X8931");
+const PRICE_A = recurringPrice("price_A8931growth", "growth_monthly", PROD_A);
+const PRICE_B = recurringPrice("price_B8931scale", "scale_monthly", PROD_B);
+const PRICE_C = recurringPrice("price_C8931team", "team_monthly", PROD_C);
+const PRICE_D = oneTimePrice("price_D8931basic", "basic_once", PROD_D);
+/** PROD_A's yearly Price, for the per-Price shown set (#9070 D5). */
+const PRICE_A_YEARLY = {
+  ...recurringPrice("price_A8931growthyear", "growth_yearly", PROD_A),
+  recurring: { interval: "year", interval_count: 1, usage_type: "licensed" },
+  unit_amount: 29000,
+};
+const PRICE_MOVED = recurringPrice(
+  "price_X8931moved",
+  "growth_monthly",
+  PROD_X,
+);
+
+/** Every id, key and URL that must never reach a log line or a refusal body (AC-6). */
+const SECRETS = [
+  "growth_monthly",
+  "growth_yearly",
+  "scale_monthly",
+  "team_monthly",
+  "basic_once",
+  "enterprise_monthly",
+  "Growth_Monthly",
+  "growth_pro_monthly",
+  "wendi_retainer",
+  PROD_A.id,
+  PROD_B.id,
+  PROD_C.id,
+  PROD_D.id,
+  PROD_X.id,
+  PRICE_A.id,
+  PRICE_A_YEARLY.id,
+  PRICE_B.id,
+  PRICE_C.id,
+  PRICE_D.id,
+  PRICE_MOVED.id,
+  SESSION_ID,
+  SESSION_URL,
+];
+
+const BODY = {
+  productCode: "growth_monthly",
+  successUrl: "https://example.com/thanks",
+  cancelUrl: "https://example.com/pricing",
+};
+
+type Fake = ReturnType<typeof fakeClient>;
+
+/** The Organization's own client: `prices.list` answers from `catalog` by key. */
+function fakeClient(
+  catalog: Record<string, unknown[]> = { growth_monthly: [PRICE_A] },
+) {
+  return {
+    prices: {
+      list: jest.fn(async (params: { lookup_keys: string[] }) => ({
+        data: catalog[params.lookup_keys[0]!] ?? [],
+      })),
+    },
+    checkout: {
+      sessions: {
+        create: jest
+          .fn()
+          .mockResolvedValue({ id: SESSION_ID, url: SESSION_URL }),
+        expire: jest.fn().mockResolvedValue({}),
+        retrieve: jest.fn(),
+      },
+    },
+  };
+}
+
+// ── The log capture (AC-6) ──────────────────────────────────────────────────
+
+const logged: string[] = [];
+const bodies: Array<{ status: number; body: string }> = [];
+
+function captureStream(): Writable {
+  return new Writable({
+    write(chunk, _enc, done) {
+      logged.push(chunk.toString());
+      done();
+    },
+  });
+}
+
+function buildApp(): FastifyInstance {
+  const app = Fastify({
+    logger: {
+      level: "info",
+      stream: captureStream(),
+      serializers: { req: requestLogSerializer },
+    },
+    trustProxy: true,
+  });
+  app.register(checkoutRoutes);
+  return app;
+}
+
+let app: FastifyInstance;
+let client: Fake;
+const savedKey = process.env.STRIPE_SECRET_KEY;
+const savedDatabaseUrl = process.env.DATABASE_URL;
+
+async function post(
+  body: Record<string, unknown> = BODY,
+  headers: Record<string, string> = {},
+) {
+  const res = await app.inject({
+    method: "POST",
+    url: "/v1/checkout/sessions",
+    payload: body,
+    headers,
+  });
+  bodies.push({ status: res.statusCode, body: res.body });
+  return res;
+}
+
+async function get(id = SESSION_ID) {
+  const res = await app.inject({
+    method: "GET",
+    url: `/v1/checkout/sessions/${id}`,
+  });
+  bodies.push({ status: res.statusCode, body: res.body });
+  return res;
+}
+
+function givenRows(enabled: string[], shown: string[], shownPrices: string[] = []) {
+  mockReadEnabledProductIds.mockResolvedValue(enabled);
+  mockReadWorkspaceSelection.mockResolvedValue({
+    shownProductIds: shown,
+    shownPriceIds: shownPrices,
+    recommendedPlanProductId: null,
+    recommendedAddonProductId: null,
+  });
+}
+
+beforeAll(() => {
+  for (const level of ["info", "warn", "error", "debug"] as const) {
+    jest.spyOn(logger, level).mockImplementation(((...args: unknown[]) => {
+      logged.push(JSON.stringify(args));
+    }) as never);
+  }
+});
+
+beforeEach(async () => {
+  jest.clearAllMocks();
+  delete process.env.STRIPE_SECRET_KEY;
+  process.env.DATABASE_URL = savedDatabaseUrl;
+  client = fakeClient();
+  mockResolvePublicWorkspace.mockResolvedValue({
+    kind: "resolved",
+    workspaceId: WS,
+  });
+  mockOrganizationIdOfWorkspace.mockResolvedValue(ORG);
+  mockConnectionSummary.mockResolvedValue(SUMMARY);
+  mockClientForOrganization.mockImplementation(async () => ({
+    kind: "ok",
+    client,
+    mode: "test",
+  }));
+  givenRows([PROD_A.id, PROD_B.id], [PROD_A.id, PROD_C.id]);
+  mockReadWorkspaceSnapshot.mockResolvedValue(null);
+  mockRecordCheckoutSession.mockResolvedValue(undefined);
+  mockReadCheckoutSessionRecord.mockResolvedValue(null);
+  mockChargeWriteBudget.mockResolvedValue({ ok: true });
+  app = buildApp();
+  await app.ready();
+});
+
+afterEach(async () => {
+  await app.close();
+});
+
+afterAll(() => {
+  process.env.STRIPE_SECRET_KEY = savedKey;
+  process.env.DATABASE_URL = savedDatabaseUrl;
+});
+
+// ── AC-1: one identical 404 for every miss (A3, A4, A5, A-T1, A-T2) ─────────
+
+describe("AC-1 — every miss is one 404 that never echoes the key", () => {
+  const NOT_FOUND = JSON.stringify({ error: "unknown-product-code" });
+
+  function expectMiss(res: { statusCode: number; body: string }, key: string) {
+    expect(res.statusCode).toBe(404);
+    expect(res.body).toBe(NOT_FOUND);
+    expect(res.body).not.toContain(key);
+    expect(client.checkout.sessions.create).not.toHaveBeenCalled();
+    expect(mockRecordCheckoutSession).not.toHaveBeenCalled();
+  }
+
+  it.each<[string, string, Record<string, unknown[]>]>([
+    ["enabled but not shown", "scale_monthly", { scale_monthly: [PRICE_B] }],
+    ["shown but not enabled", "team_monthly", { team_monthly: [PRICE_C] }],
+    [
+      "moved to another Product",
+      "growth_monthly",
+      { growth_monthly: [PRICE_MOVED] },
+    ],
+    ["nonexistent", "enterprise_monthly", {}],
+  ])("a key %s answers the 404", async (_label, key, catalog) => {
+    client = fakeClient(catalog);
+    const res = await post({ ...BODY, productCode: key });
+    expectMiss(res, key);
+    expect(client.prices.list).toHaveBeenCalledTimes(1);
+  });
+
+  it.each(["Growth_Monthly", "growth_pro_monthly", "wendi_retainer"])(
+    "the ungrammatical %s answers the 404 with no Stripe or database call",
+    async (key) => {
+      const res = await post({ ...BODY, productCode: key });
+      expectMiss(res, key);
+      expect(client.prices.list).not.toHaveBeenCalled();
+      expect(mockClientForOrganization).not.toHaveBeenCalled();
+      expect(mockReadWorkspaceSelection).not.toHaveBeenCalled();
+    },
+  );
+
+  it("a key in the shown set's snapshot but not the live read answers 404 with no session (A-T2)", async () => {
+    mockReadWorkspaceSnapshot.mockResolvedValue({
+      snapshot: {
+        offerings: [
+          { productId: PROD_A.id, prices: [{ lookupKey: "growth_monthly" }] },
+        ],
+      },
+      snapshotAt: new Date(),
+    });
+    client = fakeClient({});
+    const res = await post();
+    expectMiss(res, "growth_monthly");
+    expect(mockReadWorkspaceSnapshot).not.toHaveBeenCalled();
+  });
+
+  it("the same fixtures sell growth_monthly (so each 404 above is the check, not the fixture)", async () => {
+    const res = await post();
+    expect(res.statusCode).toBe(201);
+  });
+
+  it("a workspace that sells nothing answers the 404 with no Stripe call", async () => {
+    givenRows([PROD_A.id], [PROD_C.id]);
+    const res = await post();
+    expectMiss(res, "growth_monthly");
+    expect(client.prices.list).not.toHaveBeenCalled();
+  });
+
+  it("a Price whose period disagrees with its key answers the 404", async () => {
+    const yearly = {
+      ...PRICE_A,
+      recurring: {
+        interval: "year",
+        interval_count: 1,
+        usage_type: "licensed",
+      },
+    };
+    client = fakeClient({ growth_monthly: [yearly] });
+    expectMiss(await post(), "growth_monthly");
+  });
+
+  it("a Product the normalizer holds (no ailk_group) answers the 404", async () => {
+    const unmarked = recurringPrice(PRICE_A.id, "growth_monthly", {
+      ...PROD_A,
+      metadata: {},
+    });
+    client = fakeClient({ growth_monthly: [unmarked] });
+    expectMiss(await post(), "growth_monthly");
+  });
+});
+
+// ── AC-2: the stamped, anonymous, recorded session (A6, A7, A11) ────────────
+
+describe("#9070 D5 (AC-5) — a workspace saved per Price sells only its shown Prices", () => {
+  const catalog = { growth_monthly: [PRICE_A], growth_yearly: [PRICE_A_YEARLY] };
+
+  it("sells the shown yearly Price and refuses its switched-off monthly sibling as the one 404", async () => {
+    client = fakeClient(catalog);
+    givenRows([PROD_A.id], [PROD_A.id], [PRICE_A_YEARLY.id]);
+
+    const yearly = await post({ ...BODY, productCode: "growth_yearly" });
+    expect(yearly.statusCode).toBe(201);
+    expect(client.checkout.sessions.create).toHaveBeenCalledTimes(1);
+    expect(client.checkout.sessions.create.mock.calls[0][0].line_items).toEqual([
+      { price: PRICE_A_YEARLY.id, quantity: 1 },
+    ]);
+
+    jest.clearAllMocks();
+    const monthly = await post();
+    expect(monthly.statusCode).toBe(404);
+    expect(monthly.json()).toEqual({ error: "unknown-product-code" });
+    expect(monthly.body).not.toContain("growth_monthly");
+    expect(client.checkout.sessions.create).not.toHaveBeenCalled();
+    expect(mockRecordCheckoutSession).not.toHaveBeenCalled();
+  });
+
+  it("with no stored Prices both Prices of a shown Product sell", async () => {
+    client = fakeClient(catalog);
+    givenRows([PROD_A.id], [PROD_A.id]);
+
+    expect((await post({ ...BODY, productCode: "growth_yearly" })).statusCode).toBe(201);
+    expect((await post()).statusCode).toBe(201);
+    expect(client.checkout.sessions.create).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe("AC-2 — an authorized key sells its Price in a stamped hosted session", () => {
+  it("answers 201 { sessionId, url } from a session created for the authorized Price", async () => {
+    const res = await post();
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json()).toEqual({ sessionId: SESSION_ID, url: SESSION_URL });
+    expect(client.prices.list).toHaveBeenCalledTimes(1);
+    expect(client.prices.list).toHaveBeenCalledWith({
+      lookup_keys: ["growth_monthly"],
+      active: true,
+      limit: 1,
+      expand: ["data.product"],
+    });
+    expect(client.checkout.sessions.create).toHaveBeenCalledTimes(1);
+    const params = client.checkout.sessions.create.mock.calls[0][0];
+    expect(params.line_items).toEqual([{ price: PRICE_A.id, quantity: 1 }]);
+    expect(params.mode).toBe("subscription");
+    expect(params.allow_promotion_codes).toBe(true);
+    expect(Object.keys(params.metadata).sort()).toEqual([
+      "ailk_offering",
+      "ailk_terms",
+      "site",
+    ]);
+    expect(params.metadata.site).toBe(WS);
+    expect(params.metadata.ailk_offering).toBe("growth_monthly");
+    expect(params.subscription_data).toEqual({
+      metadata: { site: WS, ailk_offering: "growth_monthly" },
+    });
+    expect(params).not.toHaveProperty("customer");
+    expect(params).not.toHaveProperty("customer_creation");
+    // The env client is never built.
+    expect(envStripeConstructor()).not.toHaveBeenCalled();
+  });
+
+  it("allows promotion codes even when the body says false (C3)", async () => {
+    await post({ ...BODY, allowPromotionCodes: false });
+    expect(
+      client.checkout.sessions.create.mock.calls[0][0].allow_promotion_codes,
+    ).toBe(true);
+  });
+
+  it("a one-time Price opens a payment session that creates a customer, with no subscription_data", async () => {
+    givenRows([PROD_D.id], [PROD_D.id]);
+    client = fakeClient({ basic_once: [PRICE_D] });
+
+    const res = await post({ ...BODY, productCode: "basic_once" });
+
+    expect(res.statusCode).toBe(201);
+    const params = client.checkout.sessions.create.mock.calls[0][0];
+    expect(params.mode).toBe("payment");
+    expect(params.customer_creation).toBe("always");
+    expect(params).not.toHaveProperty("subscription_data");
+    expect(params).not.toHaveProperty("customer");
+  });
+
+  it("a signed-in cookie is never read and no param carries ailk_user_id (C4)", async () => {
+    (prisma.session.findUnique as jest.Mock).mockResolvedValue({
+      id: "ses_1",
+      userId: "usr_buyer",
+      expiresAt: new Date(Date.now() + 60_000),
+      activeOrganizationId: null,
+      activeWorkspaceId: null,
+    });
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue({
+      id: "usr_buyer",
+      email: "buyer@example.com",
+      emailVerified: true,
+      billingProvider: null,
+      billingCustomerId: null,
+    });
+
+    const res = await post(BODY, {
+      cookie: "better-auth.session_token=sess_tok_buyer.signature",
+      origin: "https://example.com",
+    });
+
+    expect(res.statusCode).toBe(201);
+    expect(prisma.session.findUnique).not.toHaveBeenCalled();
+    expect(
+      JSON.stringify(client.checkout.sessions.create.mock.calls),
+    ).not.toContain("ailk_user_id");
+  });
+
+  it("records the session through the keystone store, after the create", async () => {
+    await post();
+
+    expect(mockRecordCheckoutSession).toHaveBeenCalledTimes(1);
+    expect(mockRecordCheckoutSession).toHaveBeenCalledWith({
+      sessionId: SESSION_ID,
+      workspaceId: WS,
+      organizationId: ORG,
+      priceId: PRICE_A.id,
+      lookupKey: "growth_monthly",
+      mode: "test",
+    });
+    expect(
+      mockRecordCheckoutSession.mock.invocationCallOrder[0],
+    ).toBeGreaterThan(
+      client.checkout.sessions.create.mock.invocationCallOrder[0]!,
+    );
+  });
+
+  it("does not answer while the record is pending", async () => {
+    let release!: () => void;
+    mockRecordCheckoutSession.mockReturnValue(
+      new Promise<void>((resolve) => {
+        release = resolve;
+      }),
+    );
+    let answered = false;
+    const pending = post().then((res) => {
+      answered = true;
+      return res;
+    });
+    for (
+      let i = 0;
+      i < 20 && mockRecordCheckoutSession.mock.calls.length === 0;
+      i++
+    ) {
+      await new Promise((resolve) => setImmediate(resolve));
+    }
+    expect(mockRecordCheckoutSession).toHaveBeenCalledTimes(1);
+    await new Promise((resolve) => setImmediate(resolve));
+    expect(answered).toBe(false);
+
+    release();
+    const res = await pending;
+    expect(res.statusCode).toBe(201);
+  });
+
+  it.each([
+    "invalid",
+    "workspace_mismatch",
+    "conflict",
+    "write_failed",
+  ] as const)(
+    "a record that rejects %s expires the session and answers 502",
+    async (reason) => {
+      mockRecordCheckoutSession.mockRejectedValue(
+        new CheckoutSessionRecordError(reason),
+      );
+
+      const res = await post();
+
+      expect(res.statusCode).toBe(502);
+      expect(res.json()).toEqual({ error: "checkout-unavailable" });
+      expect(client.checkout.sessions.expire).toHaveBeenCalledWith(SESSION_ID);
+    },
+  );
+
+  it("a budget store that throws answers 502 with no Stripe call (code review #9032)", async () => {
+    mockChargeWriteBudget.mockRejectedValueOnce(new Error("store down"));
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(502);
+    expect(res.json()).toEqual({ error: "checkout-unavailable" });
+    expect(client.checkout.sessions.create).not.toHaveBeenCalled();
+  });
+
+  it("a failed record whose expire also fails still answers 502", async () => {
+    mockRecordCheckoutSession.mockRejectedValue(
+      new CheckoutSessionRecordError("write_failed"),
+    );
+    client.checkout.sessions.expire.mockRejectedValue(new Error("stripe down"));
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(502);
+    expect(res.json()).toEqual({ error: "checkout-unavailable" });
+    expect(client.checkout.sessions.expire).toHaveBeenCalledWith(SESSION_ID);
+  });
+});
+
+// ── AC-3: the env path refuses an Offerings product (A9) ────────────────────
+
+describe("AC-3 (A9) — the env path, composed with the real stripe-client and marker", () => {
+  beforeEach(() => {
+    mockResolvePublicWorkspace.mockResolvedValue({ kind: "not-required" });
+    process.env.STRIPE_SECRET_KEY =
+      ["sk", "test", ""].join("_") + "OfferingsEnv8931";
+    mockEnvSessionsCreate.mockResolvedValue({
+      id: "cs_test_env8931",
+      url: "https://checkout.stripe.com/c/pay/cs_test_env8931",
+    });
+  });
+
+  it.each<[string, unknown]>([
+    [
+      "a Product carrying metadata.ailk_group",
+      { id: "prod_Env1", metadata: { ailk_group: "plan" } },
+    ],
+    ["a bare product id the expand did not turn into an object", "prod_Env2"],
+  ])("%s answers the 404 with no session", async (_label, prod) => {
+    mockEnvPricesList.mockResolvedValue({
+      data: [{ id: "price_Env", type: "recurring", product: prod }],
+    });
+
+    const res = await post({ ...BODY, productCode: "ailk-pro" });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json()).toEqual({ error: "unknown-product-code" });
+    expect(mockEnvPricesList).toHaveBeenCalledWith({
+      lookup_keys: ["ailk-pro"],
+      active: true,
+      limit: 1,
+      expand: ["data.product"],
+    });
+    expect(mockEnvSessionsCreate).not.toHaveBeenCalled();
+    expect(mockChargeWriteBudget).not.toHaveBeenCalled();
+  });
+
+  it("a Product with no ailk_group still sells on the env path", async () => {
+    mockEnvPricesList.mockResolvedValue({
+      data: [
+        {
+          id: "price_Env",
+          type: "recurring",
+          product: { id: "prod_Env3", metadata: {} },
+        },
+      ],
+    });
+
+    const res = await post({ ...BODY, productCode: "ailk-pro" });
+
+    expect(res.statusCode).toBe(201);
+    expect(mockEnvSessionsCreate).toHaveBeenCalledTimes(1);
+    expect(mockEnvSessionsCreate.mock.calls[0][0].metadata).toHaveProperty(
+      "site",
+    );
+  });
+});
+
+// ── AC-3: the session read uses the record's own connection (A13) ───────────
+
+describe("AC-3 (A13) — GET /v1/checkout/sessions/:id for a recorded session", () => {
+  const RECORD = {
+    sessionId: SESSION_ID,
+    workspaceId: WS,
+    organizationId: ORG,
+    priceId: PRICE_A.id,
+    lookupKey: "growth_monthly",
+    mode: "test" as const,
+    createdAt: new Date("2026-10-18T00:00:00Z"),
+  };
+  const LONG_NAME = "Growth‮ plan" + "x".repeat(300);
+
+  function stripeSession() {
+    return {
+      id: SESSION_ID,
+      status: "complete",
+      payment_status: "paid",
+      currency: "usd",
+      amount_total: 2900,
+      line_items: {
+        data: [
+          {
+            description: LONG_NAME,
+            quantity: 1,
+            amount_total: 2900,
+            currency: "usd",
+          },
+        ],
+      },
+    };
+  }
+
+  beforeEach(() => {
+    mockReadCheckoutSessionRecord.mockResolvedValue(RECORD);
+    client.checkout.sessions.retrieve.mockResolvedValue(stripeSession());
+  });
+
+  it("reads on the record's connection and serves today's 200 body and headers", async () => {
+    const res = await get();
+
+    expect(res.statusCode).toBe(200);
+    expect(mockClientForOrganization).toHaveBeenCalledWith(ORG);
+    expect(client.checkout.sessions.retrieve).toHaveBeenCalledWith(SESSION_ID, {
+      expand: ["line_items"],
+    });
+    expect(envStripeConstructor()).not.toHaveBeenCalled();
+    expect(res.headers["cache-control"]).toBe("no-store");
+    expect(res.headers["x-robots-tag"]).toBe("noindex, nofollow");
+    expect(res.headers["referrer-policy"]).toBe("no-referrer");
+    const body = res.json();
+    expect(Object.keys(body).sort()).toEqual(
+      [
+        "amountTotal",
+        "currency",
+        "id",
+        "lineItems",
+        "paymentStatus",
+        "status",
+      ].sort(),
+    );
+    expect(body).toMatchObject({
+      id: SESSION_ID,
+      status: "complete",
+      paymentStatus: "paid",
+      currency: "usd",
+      amountTotal: 2900,
+    });
+    const description: string = body.lineItems[0].description;
+    expect(description).not.toContain("‮");
+    expect([...description].length).toBeLessThanOrEqual(200);
+    expect(description.startsWith("Growth plan")).toBe(true);
+  });
+
+  it.each<[string, () => void]>([
+    [
+      "a connection in another mode",
+      () =>
+        mockClientForOrganization.mockResolvedValue({
+          kind: "ok",
+          client,
+          mode: "live",
+        }),
+    ],
+    [
+      "no connection",
+      () => mockClientForOrganization.mockResolvedValue({ kind: "none" }),
+    ],
+    [
+      "an unusable connection",
+      () => mockClientForOrganization.mockResolvedValue({ kind: "unusable" }),
+    ],
+    [
+      "an unreadable record",
+      () => mockReadCheckoutSessionRecord.mockResolvedValue("unreadable"),
+    ],
+    [
+      "a rejected record read",
+      () =>
+        mockReadCheckoutSessionRecord.mockRejectedValue(
+          new CheckoutSessionRecordError("read_failed"),
+        ),
+    ],
+    [
+      "a rejected connection read",
+      () =>
+        mockClientForOrganization.mockRejectedValue(new Error("store down")),
+    ],
+  ])(
+    "%s answers 502 with no retrieve on any client",
+    async (_label, arrange) => {
+      arrange();
+
+      const res = await get();
+
+      expect(res.statusCode).toBe(502);
+      expect(res.json()).toEqual({ error: "checkout-unavailable" });
+      expect(client.checkout.sessions.retrieve).not.toHaveBeenCalled();
+      expect(mockEnvSessionsRetrieve).not.toHaveBeenCalled();
+    },
+  );
+
+  it("a recorded session Stripe does not know answers 404 unknown-session", async () => {
+    client.checkout.sessions.retrieve.mockRejectedValue(
+      Object.assign(new Error("No such checkout.session"), {
+        code: "resource_missing",
+      }),
+    );
+    const res = await get();
+    expect(res.statusCode).toBe(404);
+    expect(res.json()).toEqual({ error: "unknown-session" });
+  });
+
+  it("no record answers as the env path does", async () => {
+    mockReadCheckoutSessionRecord.mockResolvedValue(null);
+    const res = await get();
+    expect(res.statusCode).toBe(500);
+    expect(res.json()).toEqual({ error: "stripe-not-configured" });
+    expect(client.checkout.sessions.retrieve).not.toHaveBeenCalled();
+  });
+
+  it("with no database the record store is never called", async () => {
+    delete process.env.DATABASE_URL;
+    const res = await get();
+    expect(mockReadCheckoutSessionRecord).not.toHaveBeenCalled();
+    expect(res.statusCode).toBe(500);
+    expect(res.json()).toEqual({ error: "stripe-not-configured" });
+  });
+});
+
+// ── AC-4: the path decision (A1, A2, A-T3) ──────────────────────────────────
+
+describe("AC-4 — the workspace is the server's, and a refused spoke key is 503", () => {
+  it("a refused spoke key answers 503 tenant_unresolved with no Stripe, budget or Organization call", async () => {
+    mockResolvePublicWorkspace.mockResolvedValue({
+      kind: "unresolved",
+      reason: "spoke-refused",
+    });
+
+    const res = await post(BODY, { "x-ailk-spoke-key": "revoked-key" });
+
+    expect(res.statusCode).toBe(503);
+    expect(res.json()).toEqual({ error: "tenant_unresolved" });
+    expect(client.prices.list).not.toHaveBeenCalled();
+    expect(mockClientForOrganization).not.toHaveBeenCalled();
+    expect(mockChargeWriteBudget).not.toHaveBeenCalled();
+    expect(mockOrganizationIdOfWorkspace).not.toHaveBeenCalled();
+  });
+
+  it.each<[string, () => void]>([
+    [
+      "a header-less call refused as key-required",
+      () =>
+        mockResolvePublicWorkspace.mockResolvedValue({
+          kind: "unresolved",
+          reason: "spoke-refused",
+        }),
+    ],
+    [
+      "an ambiguous resolution",
+      () =>
+        mockResolvePublicWorkspace.mockResolvedValue({
+          kind: "unresolved",
+          reason: "ambiguous",
+        }),
+    ],
+    [
+      "an unmatched host",
+      () =>
+        mockResolvePublicWorkspace.mockResolvedValue({
+          kind: "unresolved",
+          reason: "host-unmatched",
+        }),
+    ],
+    [
+      "a deployment off the database adapter",
+      () =>
+        mockResolvePublicWorkspace.mockResolvedValue({ kind: "not-required" }),
+    ],
+    [
+      "a workspace with no Organization row",
+      () => mockOrganizationIdOfWorkspace.mockResolvedValue(null),
+    ],
+    [
+      "an Organization with no connection",
+      () => mockConnectionSummary.mockResolvedValue(null),
+    ],
+  ])("%s takes the env path", async (_label, arrange) => {
+    arrange();
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(500);
+    expect(res.json()).toEqual({ error: "stripe-not-configured" });
+    expect(mockChargeWriteBudget).not.toHaveBeenCalled();
+    expect(client.prices.list).not.toHaveBeenCalled();
+  });
+
+  it("an unreadable connection answers 502, never the env path", async () => {
+    mockConnectionSummary.mockResolvedValue("unreadable");
+    const res = await post();
+    expect(res.statusCode).toBe(502);
+    expect(res.json()).toEqual({ error: "checkout-unavailable" });
+    expect(mockReadWorkspaceSelection).not.toHaveBeenCalled();
+  });
+
+  it.each<[string, () => void]>([
+    [
+      "the resolver",
+      () =>
+        mockResolvePublicWorkspace.mockRejectedValue(
+          new Error("registry down"),
+        ),
+    ],
+    [
+      "the Organization read",
+      () =>
+        mockOrganizationIdOfWorkspace.mockRejectedValue(new Error("db down")),
+    ],
+    [
+      "the summary read",
+      () => mockConnectionSummary.mockRejectedValue(new Error("db down")),
+    ],
+  ])("a rejecting %s answers 502", async (_label, arrange) => {
+    arrange();
+    const res = await post();
+    expect(res.statusCode).toBe(502);
+    expect(res.json()).toEqual({ error: "checkout-unavailable" });
+  });
+
+  it("a body naming a workspace, an Organization or a site is ignored", async () => {
+    const res = await post({
+      ...BODY,
+      workspaceId: "wksp_00000000-0000-7000-8000-00000000dead",
+      organizationId: "org_00000000-0000-7000-8000-00000000dead",
+      site: "wksp_00000000-0000-7000-8000-00000000dead",
+    });
+
+    expect(res.statusCode).toBe(201);
+    expect(mockRecordCheckoutSession.mock.calls[0][0]).toMatchObject({
+      workspaceId: WS,
+      organizationId: ORG,
+    });
+    expect(client.checkout.sessions.create.mock.calls[0][0].metadata.site).toBe(
+      WS,
+    );
+    expect(mockOrganizationIdOfWorkspace).toHaveBeenCalledWith(WS);
+  });
+});
+
+// ── #9126: a resolved spoke with no connection never takes the env path ─────
+
+describe("#9126 — a spoke's workspace with no Stripe connection is refused, never the env path", () => {
+  const SPOKE = { "x-ailk-spoke-key": "spoke-key-9126" };
+  const ENV_SESSION_ID = "cs_test_env9126";
+  const LOGGER_KEYS = new Set([
+    "level",
+    "time",
+    "pid",
+    "hostname",
+    "reqId",
+    "msg",
+  ]);
+
+  beforeEach(() => {
+    // An env key is set and its Price sells, so the env path would answer
+    // 201: a 404 below is the refusal, not a missing key or Price.
+    process.env.STRIPE_SECRET_KEY =
+      ["sk", "test", ""].join("_") + "Unconnected9126";
+    mockEnvPricesList.mockResolvedValue({
+      data: [
+        {
+          id: "price_Env9126",
+          type: "recurring",
+          product: { id: "prod_Env9126", metadata: {} },
+        },
+      ],
+    });
+    mockEnvSessionsCreate.mockResolvedValue({
+      id: ENV_SESSION_ID,
+      url: `https://checkout.stripe.com/c/pay/${ENV_SESSION_ID}`,
+    });
+  });
+
+  function unconnectedLines(from: number): Array<Record<string, unknown>> {
+    return logged
+      .slice(from)
+      .flatMap((line) => {
+        try {
+          return [JSON.parse(line) as Record<string, unknown>];
+        } catch {
+          return [];
+        }
+      })
+      .filter((entry) => entry.outcome === "unconnected");
+  }
+
+  it.each<[string, () => void]>([
+    [
+      "no Organization row",
+      () => mockOrganizationIdOfWorkspace.mockResolvedValue(null),
+    ],
+    [
+      "an Organization with no connection",
+      () => mockConnectionSummary.mockResolvedValue(null),
+    ],
+  ])(
+    "a spoke's workspace with %s answers the one 404 with no Stripe call",
+    async (_label, arrange) => {
+      arrange();
+      const from = logged.length;
+
+      const res = await post(BODY, SPOKE);
+
+      expect(res.statusCode).toBe(404);
+      expect(res.json()).toEqual({ error: "unknown-product-code" });
+      expect(envStripeConstructor()).not.toHaveBeenCalled();
+      expect(mockEnvPricesList).not.toHaveBeenCalled();
+      expect(mockEnvSessionsCreate).not.toHaveBeenCalled();
+      expect(mockClientForOrganization).not.toHaveBeenCalled();
+      expect(client.prices.list).not.toHaveBeenCalled();
+      expect(mockChargeWriteBudget).not.toHaveBeenCalled();
+      expect(mockRecordCheckoutSession).not.toHaveBeenCalled();
+
+      const lines = unconnectedLines(from);
+      expect(lines).toHaveLength(1);
+      // Everything but the logger's own bindings is what the route chose to log.
+      const fields = Object.fromEntries(
+        Object.entries(lines[0]!).filter(([key]) => !LOGGER_KEYS.has(key)),
+      );
+      expect(fields).toEqual({ outcome: "unconnected", workspaceId: WS });
+    },
+  );
+
+  it("answers before the env key is read: with no STRIPE_SECRET_KEY it is still the 404, never 500", async () => {
+    delete process.env.STRIPE_SECRET_KEY;
+    mockConnectionSummary.mockResolvedValue(null);
+
+    const res = await post(BODY, SPOKE);
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json()).toEqual({ error: "unknown-product-code" });
+  });
+
+  it("a spoke's workspace whose Organization is connected still takes the Offerings path", async () => {
+    const res = await post(BODY, SPOKE);
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json()).toEqual({ sessionId: SESSION_ID, url: SESSION_URL });
+    expect(envStripeConstructor()).not.toHaveBeenCalled();
+  });
+
+  it.each<[string, () => void]>([
+    [
+      "a deployment off the database adapter (not-required)",
+      () =>
+        mockResolvePublicWorkspace.mockResolvedValue({ kind: "not-required" }),
+    ],
+    [
+      "a keyless call on a non-hub whose workspace has no Organization row",
+      () => mockOrganizationIdOfWorkspace.mockResolvedValue(null),
+    ],
+    [
+      "a keyless call on a non-hub whose Organization has no connection",
+      () => mockConnectionSummary.mockResolvedValue(null),
+    ],
+    [
+      "a keyless call a hub refused",
+      () =>
+        mockResolvePublicWorkspace.mockResolvedValue({
+          kind: "unresolved",
+          reason: "spoke-refused",
+        }),
+    ],
+  ])("%s takes the env path, unchanged", async (_label, arrange) => {
+    arrange();
+    const from = logged.length;
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json()).toEqual({
+      sessionId: ENV_SESSION_ID,
+      url: `https://checkout.stripe.com/c/pay/${ENV_SESSION_ID}`,
+    });
+    expect(mockEnvSessionsCreate).toHaveBeenCalledTimes(1);
+    expect(mockChargeWriteBudget).not.toHaveBeenCalled();
+    expect(client.prices.list).not.toHaveBeenCalled();
+    expect(unconnectedLines(from)).toHaveLength(0);
+  });
+});
+
+// ── AC-5: the bucket, and every failure is 502 (A5, A8, K6) ─────────────────
+
+describe("AC-5 — the per-request bucket and the failure answers", () => {
+  function charge(key: string, limit: number) {
+    return {
+      scope: "offeringscheckout",
+      charges: [{ key, limit }],
+      windowMs: 60000,
+      now: expect.any(Number),
+      warn: expect.any(Function),
+    };
+  }
+
+  function expectCharged(ip: string) {
+    expect(mockChargeWriteBudget).toHaveBeenCalledWith(charge(`ip,${ip}`, 10));
+    expect(mockChargeWriteBudget).toHaveBeenCalledWith(charge(`ws,${WS}`, 60));
+  }
+
+  function chargedKeys(): string[] {
+    return mockChargeWriteBudget.mock.calls.flatMap(([input]) =>
+      (input as { charges: Array<{ key: string }> }).charges.map((c) => c.key),
+    );
+  }
+
+  it("charges the per-IP and per-workspace buckets once per request, whatever the forwarded address", async () => {
+    await post(BODY, { "x-forwarded-for": "203.0.113.7" });
+    await post(BODY, { "x-forwarded-for": "198.51.100.9" });
+
+    expect(mockChargeWriteBudget).toHaveBeenCalledTimes(4);
+    expectCharged("203.0.113.7");
+    expectCharged("198.51.100.9");
+    expect(chargedKeys()).toEqual([
+      "ip,203.0.113.7",
+      `ws,${WS}`,
+      "ip,198.51.100.9",
+      `ws,${WS}`,
+    ]);
+  });
+
+  it("a request its IP bucket refuses never spends the workspace's bucket", async () => {
+    mockChargeWriteBudget.mockResolvedValueOnce({
+      ok: false,
+      retryAfterSeconds: 5,
+    });
+
+    const res = await post(BODY, { "x-forwarded-for": "203.0.113.7" });
+
+    expect(res.statusCode).toBe(429);
+    expect(chargedKeys()).toEqual(["ip,203.0.113.7"]);
+  });
+
+  it.each<[string, Record<string, unknown>, number]>([
+    [
+      "a malformed body",
+      { productCode: "bad/code", successUrl: "x", cancelUrl: "y" },
+      400,
+    ],
+    ["an ungrammatical key", { ...BODY, productCode: "Growth_Monthly" }, 404],
+  ])("charges %s before the body is read", async (_label, body, status) => {
+    const res = await post(body, { "x-forwarded-for": "203.0.113.7" });
+    expect(res.statusCode).toBe(status);
+    expect(mockChargeWriteBudget).toHaveBeenCalledTimes(2);
+    expectCharged("203.0.113.7");
+  });
+
+  it("an exhausted bucket answers 429 with Retry-After and no Stripe call", async () => {
+    mockChargeWriteBudget.mockResolvedValue({
+      ok: false,
+      retryAfterSeconds: 7,
+    });
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(429);
+    expect(res.headers["retry-after"]).toBe("7");
+    expect(res.json()).toEqual({ error: "rate_limited", retryAfterSeconds: 7 });
+    expect(client.prices.list).not.toHaveBeenCalled();
+    expect(mockClientForOrganization).not.toHaveBeenCalled();
+    expect(client.checkout.sessions.create).not.toHaveBeenCalled();
+  });
+
+  it("the env path never charges it", async () => {
+    mockConnectionSummary.mockResolvedValue(null);
+    await post();
+    expect(mockChargeWriteBudget).not.toHaveBeenCalled();
+  });
+
+  it.each<[string, () => void]>([
+    [
+      "prices.list rejecting",
+      () => client.prices.list.mockRejectedValue(new Error("unreachable")),
+    ],
+    [
+      "checkout.sessions.create rejecting",
+      () =>
+        client.checkout.sessions.create.mockRejectedValue(
+          new Error("stripe down"),
+        ),
+    ],
+    [
+      "a refused terms box",
+      () =>
+        client.checkout.sessions.create.mockRejectedValue(
+          Object.assign(new Error("You must set a Terms of Service URL"), {
+            type: "StripeInvalidRequestError",
+            param: "consent_collection[terms_of_service]",
+          }),
+        ),
+    ],
+    [
+      "the rows' store rejecting",
+      () => mockReadWorkspaceSelection.mockRejectedValue(new Error("db down")),
+    ],
+    [
+      "an unusable connection",
+      () => mockClientForOrganization.mockResolvedValue({ kind: "unusable" }),
+    ],
+    [
+      "a connection gone since the path decision",
+      () => mockClientForOrganization.mockResolvedValue({ kind: "none" }),
+    ],
+    [
+      "a rejected connection read",
+      () => mockClientForOrganization.mockRejectedValue(new Error("db down")),
+    ],
+    [
+      "rows read for another Organization than the path decision's",
+      () =>
+        mockOrganizationIdOfWorkspace
+          .mockResolvedValueOnce(ORG)
+          .mockResolvedValueOnce("org_00000000-0000-7000-8000-00000000dead"),
+    ],
+  ])("%s answers 502, never 500 or 201", async (_label, arrange) => {
+    arrange();
+
+    const res = await post();
+
+    expect(res.statusCode).toBe(502);
+    expect(res.json()).toEqual({ error: "checkout-unavailable" });
+    expect(mockRecordCheckoutSession).not.toHaveBeenCalled();
+  });
+});
+
+// ── AC-6: no key, id or URL in a log line or a refusal body (C5, T6, NFR1) ──
+
+describe("AC-6 — what the logs and the bodies never carry", () => {
+  it("no log line holds a lookup key, a Price or Product id, a full session id or a URL", () => {
+    expect(logged.length).toBeGreaterThan(0);
+    const all = logged.join("\n");
+    for (const secret of SECRETS) {
+      expect(all).not.toContain(secret);
+    }
+  });
+
+  it("only the two success bodies hold a session id or URL, and no body holds a key or id", () => {
+    expect(bodies.length).toBeGreaterThan(0);
+    for (const { status, body } of bodies) {
+      for (const secret of SECRETS) {
+        if (secret === SESSION_ID && (status === 200 || status === 201))
+          continue;
+        if (secret === SESSION_URL && status === 201) continue;
+        expect(body).not.toContain(secret);
+      }
+    }
+  });
+});