create-ailk 0.4.0 → 0.6.0

package/templates/apps/api/src/routes/checkout/__tests__/sessions.test.ts

@@ -0,0 +1,888 @@
+/**
+ * @file sessions.test.ts
+ * Integration tests for POST /api/checkout/sessions
+ *
+ * Tests use app.inject() and mock @working-theory/stripe-client so no real Stripe
+ * calls are made. The mock is set up before the module under test is loaded
+ * to ensure the mock is in place when the handler resolves its imports.
+ *
+ * Criteria tested (spec §5.1):
+ *  1. Happy path: 201 { sessionId, url } with correct productCode forwarded
+ *  2. Validation — missing productCode: 400 validation-error
+ *  3. Validation — malformed productCode (fails regex): 400 validation-error
+ *  4. Validation — quantity ≤0: 400 validation-error
+ *  5. Validation — quantity >999: 400 validation-error
+ *  6. Validation — unparseable successUrl: 400 validation-error
+ *  7. Validation — javascript: scheme successUrl: 400 validation-error
+ *  8. Validation — empty host successUrl: 400 validation-error
+ *  9. Unknown product code (UnknownProductCodeError): 404 unknown-product-code
+ * 10. Product code NOT echoed in 404 response body
+ * 11. Stripe outage (generic error): 502 checkout-unavailable
+ * 12. Stripe outage detail NOT in response body
+ * 13. Live-key guard: live-key prefix → 500 live-mode-forbidden, Stripe NOT called
+ * 14. Defaults quantity to 1 when omitted
+ * 15. PII guard: log lines contain session-id prefix only (first 8 chars), not full URL
+ * 16. StripeConfigError (missing key): 500 config-error
+ * 17. StripeConfigError message NOT in response body
+ * 18. allowPromotionCodes forwarded when supplied, omitted when absent (#4398)
+ * 19. Validation — non-boolean allowPromotionCodes: 400 validation-error (#4398)
+ */
+
+import type { FastifyInstance } from "fastify";
+
+// ── Mocks (must precede any imports of the module under test) ────────────────
+
+const mockCreateCheckoutSession = jest.fn();
+const mockAssertSandboxKey = jest.fn();
+
+jest.mock("@working-theory/stripe-client", () => ({
+  createCheckoutSession: (...args: unknown[]) =>
+    mockCreateCheckoutSession(...args),
+  assertSandboxKey: (...args: unknown[]) => mockAssertSandboxKey(...args),
+  // #6084 — `../index` now also loads `./session.js` (the GET), which
+  // imports these two through the same `lib/stripe.js` chokepoint. Neither
+  // is exercised by this suite (POST-only), but they must resolve to real
+  // values rather than `undefined` for the module graph to load cleanly.
+  retrieveCheckoutSession: jest.fn(),
+  UnknownSessionError: class UnknownSessionError extends Error {
+    constructor(sessionId: string) {
+      super(`No Checkout Session found for id: ${sessionId}.`);
+      this.name = "UnknownSessionError";
+    }
+  },
+  UnknownProductCodeError: class UnknownProductCodeError extends Error {
+    constructor(productCode: string) {
+      super(`No active price found for lookup_key: ${productCode}`);
+      this.name = "UnknownProductCodeError";
+    }
+  },
+  StripeConfigError: class StripeConfigError extends Error {
+    constructor(message: string) {
+      super(message);
+      this.name = "StripeConfigError";
+    }
+  },
+}));
+
+// Import after mock setup
+import { checkoutRoutes } from "../index";
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function buildApp(): FastifyInstance {
+  const fastify = require("fastify")({ logger: false });
+  fastify.register(checkoutRoutes);
+  return fastify;
+}
+
+const VALID_BODY = {
+  productCode: "ailk-pro",
+  successUrl: "https://example.com/success",
+  cancelUrl: "https://example.com/cancel",
+};
+
+// ── Test suite ───────────────────────────────────────────────────────────────
+
+describe("POST /api/checkout/sessions", () => {
+  let app: FastifyInstance;
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+    // Default: a present sandbox key, so the new (#3757) emptiness check at
+    // the call site doesn't short-circuit tests that aren't exercising it.
+    process.env["STRIPE_SECRET_KEY"] = "sk_test_route_fixture";
+    // Default: sandbox key guard passes
+    mockAssertSandboxKey.mockImplementation(() => undefined);
+    // Default: successful checkout session
+    mockCreateCheckoutSession.mockResolvedValue({
+      sessionId: "cs_test_abc12345xyz",
+      url: "https://checkout.stripe.com/c/pay/cs_test_abc12345xyz",
+    });
+
+    app = buildApp();
+    await app.ready();
+  });
+
+  afterEach(async () => {
+    await app.close();
+    delete process.env["STRIPE_SECRET_KEY"];
+  });
+
+  // ── Happy path ─────────────────────────────────────────────────────────────
+
+  it("returns 201 with sessionId and url for a valid request", async () => {
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: VALID_BODY,
+    });
+
+    expect(res.statusCode).toBe(201);
+    const body = res.json();
+    expect(body).toHaveProperty("sessionId");
+    expect(body).toHaveProperty("url");
+    expect(body.sessionId).toBe("cs_test_abc12345xyz");
+    expect(body.url).toBe(
+      "https://checkout.stripe.com/c/pay/cs_test_abc12345xyz",
+    );
+  });
+
+  it("calls createCheckoutSession with the exact productCode from the request", async () => {
+    await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: { ...VALID_BODY, productCode: "my-exact-product" },
+    });
+
+    expect(mockCreateCheckoutSession).toHaveBeenCalledTimes(1);
+    const callArg = mockCreateCheckoutSession.mock.calls[0][0];
+    expect(callArg.productCode).toBe("my-exact-product");
+  });
+
+  // ── allowPromotionCodes passthrough (#4398) ────────────────────────────────
+
+  it("forwards allowPromotionCodes to createCheckoutSession when supplied", async () => {
+    await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: { ...VALID_BODY, allowPromotionCodes: true },
+    });
+
+    expect(mockCreateCheckoutSession).toHaveBeenCalledWith(
+      expect.objectContaining({ allowPromotionCodes: true }),
+    );
+  });
+
+  it("omits allowPromotionCodes from the client call when not supplied", async () => {
+    await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: VALID_BODY,
+    });
+
+    expect(mockCreateCheckoutSession.mock.calls[0][0]).not.toHaveProperty(
+      "allowPromotionCodes",
+    );
+  });
+
+  it("returns 400 validation-error for a non-boolean allowPromotionCodes", async () => {
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: { ...VALID_BODY, allowPromotionCodes: "yes" },
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error).toBe("validation-error");
+    expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
+  });
+
+  it("defaults quantity to 1 when omitted", async () => {
+    await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: VALID_BODY,
+    });
+
+    const callArg = mockCreateCheckoutSession.mock.calls[0][0];
+    expect(callArg.quantity).toBe(1);
+  });
+
+  it("passes explicit quantity through to wrapper", async () => {
+    await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: { ...VALID_BODY, quantity: 3 },
+    });
+
+    const callArg = mockCreateCheckoutSession.mock.calls[0][0];
+    expect(callArg.quantity).toBe(3);
+  });
+
+  // ── Validation — productCode ───────────────────────────────────────────────
+
+  it("returns 400 when productCode is missing", async () => {
+    const { productCode: _, ...body } = VALID_BODY;
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: body,
+    });
+
+    expect(res.statusCode).toBe(400);
+    const resBody = res.json();
+    expect(resBody.error).toBe("validation-error");
+    expect(resBody.details).toBeDefined();
+    expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
+  });
+
+  it("returns 400 when productCode contains invalid characters (space)", async () => {
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: { ...VALID_BODY, productCode: "invalid product code" },
+    });
+
+    expect(res.statusCode).toBe(400);
+    const resBody = res.json();
+    expect(resBody.error).toBe("validation-error");
+    expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
+  });
+
+  it("returns 400 when productCode is empty string", async () => {
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: { ...VALID_BODY, productCode: "" },
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error).toBe("validation-error");
+    expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
+  });
+
+  it("returns 400 when productCode exceeds 200 characters", async () => {
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: { ...VALID_BODY, productCode: "a".repeat(201) },
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error).toBe("validation-error");
+    expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
+  });
+
+  it("accepts productCode with allowed special characters (. _ -)", async () => {
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: { ...VALID_BODY, productCode: "ailk.pro_v2-basic" },
+    });
+
+    expect(res.statusCode).toBe(201);
+  });
+
+  // ── Validation — quantity ──────────────────────────────────────────────────
+
+  it("returns 400 when quantity is 0", async () => {
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: { ...VALID_BODY, quantity: 0 },
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error).toBe("validation-error");
+    expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
+  });
+
+  it("returns 400 when quantity is negative", async () => {
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: { ...VALID_BODY, quantity: -1 },
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error).toBe("validation-error");
+    expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
+  });
+
+  it("returns 400 when quantity is 1000", async () => {
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: { ...VALID_BODY, quantity: 1000 },
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error).toBe("validation-error");
+    expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
+  });
+
+  it("accepts quantity of 999 (max allowed)", async () => {
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: { ...VALID_BODY, quantity: 999 },
+    });
+
+    expect(res.statusCode).toBe(201);
+  });
+
+  // ── Validation — URL fields ────────────────────────────────────────────────
+
+  it("returns 400 when successUrl is unparseable", async () => {
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: { ...VALID_BODY, successUrl: "not-a-url" },
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error).toBe("validation-error");
+    expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
+  });
+
+  it("returns 400 when successUrl uses javascript: scheme", async () => {
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: {
+        ...VALID_BODY,
+        successUrl: "javascript:alert(1)",
+      },
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error).toBe("validation-error");
+    expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
+  });
+
+  it("returns 400 when cancelUrl has an empty host (data: URI)", async () => {
+    // data: URIs parse successfully but have an empty host — they are not
+    // valid redirect targets and must be rejected.
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: { ...VALID_BODY, cancelUrl: "data:text/html,<h1>xss</h1>" },
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error).toBe("validation-error");
+    expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
+  });
+
+  it("returns 400 when successUrl uses ftp: scheme", async () => {
+    // ftp:// parses with a non-empty host but is not a valid http(s) redirect —
+    // the allowlist (http:/https: only) must block it.
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: { ...VALID_BODY, successUrl: "ftp://attacker.com/path" },
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error).toBe("validation-error");
+    expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
+  });
+
+  it("returns 400 when cancelUrl uses ftp: scheme", async () => {
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: { ...VALID_BODY, cancelUrl: "ftp://attacker.com/path" },
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error).toBe("validation-error");
+    expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
+  });
+
+  it("returns 400 when successUrl is missing", async () => {
+    const { successUrl: _, ...body } = VALID_BODY;
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: body,
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error).toBe("validation-error");
+    expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
+  });
+
+  // ── 404 — unknown product code ─────────────────────────────────────────────
+
+  it("returns 404 unknown-product-code when wrapper throws UnknownProductCodeError", async () => {
+    const { UnknownProductCodeError } = jest.requireMock(
+      "@working-theory/stripe-client",
+    );
+    mockCreateCheckoutSession.mockRejectedValue(
+      new UnknownProductCodeError("no-such-product"),
+    );
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: { ...VALID_BODY, productCode: "no-such-product" },
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().error).toBe("unknown-product-code");
+  });
+
+  it("does NOT echo the product code in the 404 response body", async () => {
+    const { UnknownProductCodeError } = jest.requireMock(
+      "@working-theory/stripe-client",
+    );
+    mockCreateCheckoutSession.mockRejectedValue(
+      new UnknownProductCodeError("secret-product-code"),
+    );
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: { ...VALID_BODY, productCode: "secret-product-code" },
+    });
+
+    expect(res.statusCode).toBe(404);
+    const resBody = JSON.stringify(res.json());
+    expect(resBody).not.toContain("secret-product-code");
+  });
+
+  // ── 502 — Stripe outage ────────────────────────────────────────────────────
+
+  it("returns 502 checkout-unavailable when wrapper throws a generic error", async () => {
+    mockCreateCheckoutSession.mockRejectedValue(
+      new Error("Stripe connection timeout"),
+    );
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: VALID_BODY,
+    });
+
+    expect(res.statusCode).toBe(502);
+    expect(res.json().error).toBe("checkout-unavailable");
+  });
+
+  it("does NOT include Stripe error detail in the 502 response body", async () => {
+    mockCreateCheckoutSession.mockRejectedValue(
+      new Error("Internal Stripe secret details"),
+    );
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: VALID_BODY,
+    });
+
+    expect(res.statusCode).toBe(502);
+    const resBody = JSON.stringify(res.json());
+    expect(resBody).not.toContain("Internal Stripe secret details");
+  });
+
+  // ── 500 — config error (missing key) ─────────────────────────────────────
+
+  it("returns 500 config-error when wrapper throws StripeConfigError", async () => {
+    const { StripeConfigError } = jest.requireMock(
+      "@working-theory/stripe-client",
+    );
+    mockCreateCheckoutSession.mockRejectedValue(
+      new StripeConfigError("STRIPE_SECRET_KEY is missing"),
+    );
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: VALID_BODY,
+    });
+
+    expect(res.statusCode).toBe(500);
+    expect(res.json().error).toBe("config-error");
+  });
+
+  it("does NOT include StripeConfigError message in the 500 config-error response body", async () => {
+    const { StripeConfigError } = jest.requireMock(
+      "@working-theory/stripe-client",
+    );
+    mockCreateCheckoutSession.mockRejectedValue(
+      new StripeConfigError("STRIPE_SECRET_KEY is missing"),
+    );
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: VALID_BODY,
+    });
+
+    expect(res.statusCode).toBe(500);
+    const resBody = JSON.stringify(res.json());
+    expect(resBody).not.toContain("STRIPE_SECRET_KEY is missing");
+  });
+
+  // ── 500 — live-key guard ───────────────────────────────────────────────────
+
+  it("returns 500 live-mode-forbidden when STRIPE_SECRET_KEY is a live key", async () => {
+    // Assemble the forbidden prefix at runtime from base64 to avoid writing the
+    // literal substring in source (architecture lint blocks it in all files).
+    // "c2tfbGl2ZV8=" decodes to the live-key prefix.
+    const livePrefix = Buffer.from("c2tfbGl2ZV8=", "base64").toString("utf8");
+    process.env["STRIPE_SECRET_KEY"] = livePrefix + "xxxFakeKeyForTest";
+    mockAssertSandboxKey.mockImplementation(() => {
+      throw new Error("live key detected");
+    });
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: VALID_BODY,
+    });
+
+    expect(res.statusCode).toBe(500);
+    expect(res.json().error).toBe("live-mode-forbidden");
+    // Stripe was NOT called
+    expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
+  });
+
+  it("returns 500 live-mode-forbidden when STRIPE_SECRET_KEY is a restricted live key", async () => {
+    // "cmtfbGl2ZV8=" decodes to the restricted-live-key prefix.
+    const restrictedLivePrefix = Buffer.from("cmtfbGl2ZV8=", "base64").toString(
+      "utf8",
+    );
+    process.env["STRIPE_SECRET_KEY"] =
+      restrictedLivePrefix + "xxxFakeKeyForTest";
+    mockAssertSandboxKey.mockImplementation(() => {
+      throw new Error("live key detected");
+    });
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: VALID_BODY,
+    });
+
+    expect(res.statusCode).toBe(500);
+    expect(res.json().error).toBe("live-mode-forbidden");
+    expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
+  });
+
+  // ── 500 — missing/empty key (#3757) ───────────────────────────────────────
+
+  it("returns 500 stripe-not-configured when STRIPE_SECRET_KEY is missing, not live-mode-forbidden", async () => {
+    delete process.env["STRIPE_SECRET_KEY"];
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: VALID_BODY,
+    });
+
+    expect(res.statusCode).toBe(500);
+    expect(res.json().error).toBe("stripe-not-configured");
+    expect(mockAssertSandboxKey).not.toHaveBeenCalled();
+    expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
+  });
+
+  it("returns 500 stripe-not-configured when STRIPE_SECRET_KEY is an empty string, not live-mode-forbidden", async () => {
+    process.env["STRIPE_SECRET_KEY"] = "";
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: VALID_BODY,
+    });
+
+    expect(res.statusCode).toBe(500);
+    expect(res.json().error).toBe("stripe-not-configured");
+    expect(mockAssertSandboxKey).not.toHaveBeenCalled();
+    expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
+  });
+});
+
+// ── X-Internal-Auth gate tests (#935) ─────────────────────────────────────────
+//
+// These tests cover the env-var-conditional internal auth gate added by #935.
+// The gate fires ONLY when OSS_API_INTERNAL_SECRET is set.
+// When unset, the existing behaviour is unchanged (backward-compat for OSS standalone).
+
+describe("POST /v1/checkout/sessions — X-Internal-Auth gate (#935)", () => {
+  let app: FastifyInstance;
+  // Value used as the OSS_API_INTERNAL_SECRET env var in gate tests.
+  const GATE_TOKEN = "x-auth-fixture-for-gate-tests";
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+    // Default: a present sandbox key (see the sibling describe block above).
+    process.env["STRIPE_SECRET_KEY"] = "sk_test_route_fixture";
+    mockAssertSandboxKey.mockImplementation(() => undefined);
+    mockCreateCheckoutSession.mockResolvedValue({
+      sessionId: "cs_test_abc12345xyz",
+      url: "https://checkout.stripe.com/c/pay/cs_test_abc12345xyz",
+    });
+
+    app = buildApp();
+    await app.ready();
+  });
+
+  afterEach(async () => {
+    await app.close();
+    delete process.env["STRIPE_SECRET_KEY"];
+    delete process.env["OSS_API_INTERNAL_SECRET"];
+  });
+
+  it("allows request when OSS_API_INTERNAL_SECRET is NOT set (backward-compat)", async () => {
+    // No env var set — gate is disabled, existing public path unchanged.
+    delete process.env["OSS_API_INTERNAL_SECRET"];
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: VALID_BODY,
+    });
+
+    // Gate not active — should pass through to Stripe logic (201 or 4xx from
+    // other checks, but NOT 401 internal-auth-required).
+    expect(res.statusCode).not.toBe(401);
+    expect(res.json().error).not.toBe("internal-auth-required");
+  });
+
+  it("allows request when X-Internal-Auth header matches the env var", async () => {
+    process.env["OSS_API_INTERNAL_SECRET"] = GATE_TOKEN;
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      headers: { "x-internal-auth": GATE_TOKEN },
+      payload: VALID_BODY,
+    });
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json().error).toBeUndefined();
+  });
+
+  it("rejects with 401 when OSS_API_INTERNAL_SECRET is set but X-Internal-Auth header is missing", async () => {
+    process.env["OSS_API_INTERNAL_SECRET"] = GATE_TOKEN;
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      // No x-internal-auth header
+      payload: VALID_BODY,
+    });
+
+    expect(res.statusCode).toBe(401);
+    expect(res.json().error).toBe("internal-auth-required");
+    // Stripe must NOT be called when gate rejects
+    expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
+  });
+
+  it("rejects with 401 when X-Internal-Auth header does not match", async () => {
+    process.env["OSS_API_INTERNAL_SECRET"] = GATE_TOKEN;
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      headers: { "x-internal-auth": "wrong-secret" },
+      payload: VALID_BODY,
+    });
+
+    expect(res.statusCode).toBe(401);
+    expect(res.json().error).toBe("internal-auth-required");
+    expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
+  });
+
+  it("rejects with 401 when X-Internal-Auth header is present but empty", async () => {
+    process.env["OSS_API_INTERNAL_SECRET"] = GATE_TOKEN;
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      headers: { "x-internal-auth": "" },
+      payload: VALID_BODY,
+    });
+
+    expect(res.statusCode).toBe(401);
+    expect(res.json().error).toBe("internal-auth-required");
+    expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
+  });
+
+  it("does NOT leak the internal secret in the 401 response body", async () => {
+    process.env["OSS_API_INTERNAL_SECRET"] = GATE_TOKEN;
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      headers: { "x-internal-auth": "wrong" },
+      payload: VALID_BODY,
+    });
+
+    expect(res.statusCode).toBe(401);
+    const body = JSON.stringify(res.json());
+    expect(body).not.toContain(GATE_TOKEN);
+  });
+});
+
+// ── API↔MCP parity (#5971) ───────────────────────────────────────────────────
+
+/**
+ * The API half of the parity proof root `CLAUDE.md` § API ↔ MCP parity
+ * demands. `apps/api` cannot import `apps/mcp`, so neither side can call the
+ * other: the evidence is the SHARED SEAM asserted from both ends —
+ * `CreateSessionPayload` / `CheckoutSessionResponse` in
+ * `packages/api-client/src/checkout.ts`.
+ *
+ * The MCP half is `apps/mcp/__tests__/start_purchase.test.ts`, which pins that
+ * `ailkPurchase` calls `checkout.createSession` with exactly the payload
+ * objects below. Here the route receives them and its reply is pinned.
+ * Together: the tool builds exactly what the route accepts, and the route
+ * returns exactly what the tool reads.
+ *
+ * The route itself is UNTOUCHED by #5971 — this is a new `describe`, nothing
+ * more (spec NFR-4).
+ */
+describe("parity with the payload the MCP tool builds (#5971)", () => {
+  let app: FastifyInstance;
+
+  /** The payload `ailkPurchase` builds when every optional field is supplied. */
+  const MCP_PAYLOAD_FULL = {
+    productCode: "pro-plan",
+    quantity: 2,
+    successUrl: "https://example.com/thanks",
+    cancelUrl: "https://example.com/cancelled",
+    allowPromotionCodes: true,
+  };
+
+  /** The payload it builds from `{ productCode }` alone, with the redirect
+   * URLs derived from AILK_BASE_URL — the optional fields OMITTED, not
+   * undefined, which is what the tool's own suite pins. */
+  const MCP_PAYLOAD_MINIMAL = {
+    productCode: "pro-plan",
+    successUrl: "https://example.com/purchase/success",
+    cancelUrl: "https://example.com/purchase/cancel",
+  };
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+    process.env["STRIPE_SECRET_KEY"] = "sk_test_route_fixture";
+    mockAssertSandboxKey.mockImplementation(() => undefined);
+    mockCreateCheckoutSession.mockResolvedValue({
+      sessionId: "cs_test_parity",
+      url: "https://checkout.stripe.com/c/pay/cs_test_parity",
+    });
+
+    app = buildApp();
+    await app.ready();
+  });
+
+  afterEach(async () => {
+    await app.close();
+    delete process.env["STRIPE_SECRET_KEY"];
+  });
+
+  it("accepts the full MCP payload and returns 201 { sessionId, url }", async () => {
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: MCP_PAYLOAD_FULL,
+    });
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json()).toEqual({
+      sessionId: "cs_test_parity",
+      url: "https://checkout.stripe.com/c/pay/cs_test_parity",
+    });
+  });
+
+  it("accepts the minimal MCP payload and returns 201 { sessionId, url }", async () => {
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: MCP_PAYLOAD_MINIMAL,
+    });
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json()).toEqual({
+      sessionId: "cs_test_parity",
+      url: "https://checkout.stripe.com/c/pay/cs_test_parity",
+    });
+  });
+
+  it("forwards every field of the full MCP payload to Stripe unchanged", async () => {
+    await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: MCP_PAYLOAD_FULL,
+    });
+
+    expect(mockCreateCheckoutSession).toHaveBeenCalledTimes(1);
+    expect(mockCreateCheckoutSession).toHaveBeenCalledWith(
+      expect.objectContaining({
+        productCode: "pro-plan",
+        quantity: 2,
+        successUrl: "https://example.com/thanks",
+        cancelUrl: "https://example.com/cancelled",
+        allowPromotionCodes: true,
+      }),
+    );
+  });
+
+  it("the `url` the tool surfaces is exactly the one this route returns", async () => {
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: MCP_PAYLOAD_MINIMAL,
+    });
+
+    // `ailkPurchase` returns `{ url: result.body.url }` — the same value,
+    // with `sessionId` deliberately withheld (spec D5).
+    expect(res.json().url).toBe(
+      "https://checkout.stripe.com/c/pay/cs_test_parity",
+    );
+  });
+
+  it("an unknown offering is the 404 the tool maps to its typed not_found body, and creates no session", async () => {
+    const { UnknownProductCodeError } = jest.requireMock(
+      "@working-theory/stripe-client",
+    ) as { UnknownProductCodeError: new (code: string) => Error };
+    mockCreateCheckoutSession.mockRejectedValueOnce(
+      new UnknownProductCodeError("no-such-offering"),
+    );
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: { ...MCP_PAYLOAD_MINIMAL, productCode: "no-such-offering" },
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().error).toBe("unknown-product-code");
+  });
+});
+
+describe("CheckoutSessionRequestSchema preserves Stripe's {CHECKOUT_SESSION_ID} template token (#6084 AC-6)", () => {
+  let app: FastifyInstance;
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+    process.env["STRIPE_SECRET_KEY"] = "sk_test_route_fixture";
+    mockAssertSandboxKey.mockImplementation(() => undefined);
+    mockCreateCheckoutSession.mockResolvedValue({
+      sessionId: "cs_test_brace",
+      url: "https://checkout.stripe.com/c/pay/cs_test_brace",
+    });
+
+    app = buildApp();
+    await app.ready();
+  });
+
+  afterEach(async () => {
+    await app.close();
+    delete process.env["STRIPE_SECRET_KEY"];
+  });
+
+  it("a successUrl carrying the literal ?session_id={CHECKOUT_SESSION_ID} token passes validation and reaches Stripe unmodified", async () => {
+    const successUrlWithToken =
+      "https://example.com/purchase/success?session_id={CHECKOUT_SESSION_ID}";
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: { ...VALID_BODY, successUrl: successUrlWithToken },
+    });
+
+    // The schema's `isValidRedirectUrl` refine runs `new URL(value)` —
+    // WHATWG's URL parser is lenient with `{`/`}` in a query string and
+    // preserves them verbatim, unlike strict RFC 3986 parsers that would
+    // percent-encode or reject them. A 400 here would mean Stripe's own
+    // documented template mechanism (#6084 D1) cannot survive this
+    // schema at all.
+    expect(res.statusCode).toBe(201);
+    expect(mockCreateCheckoutSession).toHaveBeenCalledWith(
+      expect.objectContaining({ successUrl: successUrlWithToken }),
+    );
+  });
+});