create-ailk 0.1.0

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

@@ -0,0 +1,588 @@
+/**
+ * @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
+ */
+
+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),
+  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: 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");
+  });
+
+  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();
+  });
+});
+
+// ── 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();
+    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["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);
+  });
+});

package/templates/apps/api/src/routes/checkout/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Checkout route group.
+ *
+ * Routes:
+ *   POST /v1/checkout/sessions — create a Stripe hosted-page checkout session
+ */
+import type { FastifyPluginAsync } from "fastify";
+
+import { checkoutSessionsHandler } from "./sessions.js";
+
+export const checkoutRoutes: FastifyPluginAsync = async (fastify) => {
+  fastify.post("/v1/checkout/sessions", checkoutSessionsHandler);
+};