create-ailk 0.1.0

package/templates/apps/api/src/routes/webhooks/__tests__/stripe.test.ts

@@ -0,0 +1,633 @@
+/**
+ * POST /api/webhooks/stripe — handler unit tests
+ *
+ * Uses jest.useFakeTimers for the telemetry-timeout test so the 2s wall-clock
+ * wait doesn't slow the suite.
+ */
+import type { FastifyInstance } from "fastify";
+import Fastify from "fastify";
+
+// ── Mocks ────────────────────────────────────────────────────────────────────
+
+// Mock analytics track (external boundary: @working-theory/analytics/server)
+const mockTrack = jest.fn().mockResolvedValue(undefined);
+jest.mock("@working-theory/analytics/server", () => ({
+  track: (...args: unknown[]) => mockTrack(...args),
+}));
+
+// Mock Prisma — lib/prisma.ts wraps the external DB boundary (PrismaClient
+// requires a live connection). This call auto-resolves to the manual mock at
+// src/lib/__mocks__/prisma.ts (covers user.findFirst/findUnique/update/create).
+// eslint-disable-next-line no-restricted-syntax -- lib/prisma.ts wraps the external DB boundary (PrismaClient requires a live connection); __mocks__/prisma.ts is the repo-standard test double for this boundary.
+jest.mock("../../../lib/prisma.js");
+
+// Mock verifyWebhookSignature at the external boundary (@working-theory/stripe-client)
+// rather than the internal wrapper (lib/stripe.js). lib/stripe.js is a
+// thin re-export with no logic of its own; the external SDK boundary is the
+// correct mock point for signature verification.
+const mockVerifyWebhookSignature = jest.fn();
+class MockStripeWebhookSignatureError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "StripeWebhookSignatureError";
+  }
+}
+jest.mock("@working-theory/stripe-client", () => ({
+  verifyWebhookSignature: (...args: unknown[]) =>
+    mockVerifyWebhookSignature(...args),
+  StripeWebhookSignatureError: MockStripeWebhookSignatureError,
+  assertSandboxKey: jest.fn(),
+  createCheckoutSession: jest.fn(),
+  getStripeClient: jest.fn(),
+  STRIPE_API_VERSION: "2024-06-20",
+  StripeConfigError: class StripeConfigError extends Error {},
+  UnknownProductCodeError: class UnknownProductCodeError extends Error {},
+  WEBHOOK_TOLERANCE_SECONDS: 300,
+}));
+
+// Import after mocks are in place
+import * as configModule from "../../../config/index.js";
+import { stripeWebhookHandler } from "../stripe.js";
+import { __resetIdempotencyStore } from "../../../lib/webhook-idempotency.js";
+import { prisma } from "../../../lib/prisma.js";
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function buildFakeEvent(overrides: Record<string, unknown> = {}) {
+  return {
+    id: "evt_test_12345678abcdef",
+    type: "checkout.session.completed",
+    data: {
+      object: {
+        amount_total: 4999,
+        currency: "usd",
+        metadata: { productId: "starter" },
+        customer_details: { email: "alice@example.com" },
+        id: "cs_test_session_12345678901234567890",
+      },
+    },
+    ...overrides,
+  };
+}
+
+async function buildTestServer(): Promise<FastifyInstance> {
+  const server = Fastify({ logger: false });
+
+  await server.register(async (webhooksScope) => {
+    webhooksScope.addContentTypeParser(
+      "application/json",
+      { parseAs: "buffer" },
+      (_req, body, done) => {
+        done(null, body);
+      },
+    );
+    webhooksScope.post("/v1/webhooks/stripe", stripeWebhookHandler);
+  });
+
+  await server.ready();
+  return server;
+}
+
+// Valid raw body payload
+const VALID_BODY = Buffer.from(JSON.stringify({ type: "test" }));
+const VALID_SIGNATURE = "t=1234,v1=abc";
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+describe("POST /api/webhooks/stripe", () => {
+  let server: FastifyInstance;
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+    __resetIdempotencyStore();
+    // Control STRIPE_WEBHOOK_SECRET per-test via jest.replaceProperty.
+    // config is a module-level singleton frozen at load time; replaceProperty
+    // restores the original value automatically in afterEach.
+    jest.replaceProperty(configModule, "config", {
+      ...configModule.config,
+      STRIPE_WEBHOOK_SECRET: "whsec_test_secret",
+    });
+    server = await buildTestServer();
+  });
+
+  afterEach(async () => {
+    await server.close();
+    jest.restoreAllMocks();
+  });
+
+  // ── Case 1: Missing config returns 503 ──────────────────────────────────
+
+  it("returns 503 when STRIPE_WEBHOOK_SECRET is not set", async () => {
+    jest.replaceProperty(configModule, "config", {
+      ...configModule.config,
+      STRIPE_WEBHOOK_SECRET: undefined,
+    });
+
+    const response = await server.inject({
+      method: "POST",
+      url: "/v1/webhooks/stripe",
+      payload: VALID_BODY,
+      headers: {
+        "content-type": "application/json",
+        "stripe-signature": VALID_SIGNATURE,
+      },
+    });
+
+    expect(response.statusCode).toBe(503);
+    expect(JSON.parse(response.body)).toEqual({
+      error: "webhook-not-configured",
+    });
+    expect(mockVerifyWebhookSignature).not.toHaveBeenCalled();
+    expect(mockTrack).not.toHaveBeenCalled();
+  });
+
+  // ── Case 2: Invalid signature returns 400 ──────────────────────────────
+
+  it("returns 400 when signature verification fails", async () => {
+    mockVerifyWebhookSignature.mockImplementation(() => {
+      throw new MockStripeWebhookSignatureError(
+        "Signature verification failed.",
+      );
+    });
+
+    const response = await server.inject({
+      method: "POST",
+      url: "/v1/webhooks/stripe",
+      payload: VALID_BODY,
+      headers: {
+        "content-type": "application/json",
+        "stripe-signature": VALID_SIGNATURE,
+      },
+    });
+
+    expect(response.statusCode).toBe(400);
+    expect(JSON.parse(response.body)).toEqual({ error: "signature-invalid" });
+    expect(mockTrack).not.toHaveBeenCalled();
+  });
+
+  // ── Case 3: Missing Stripe-Signature header returns 400 ─────────────────
+
+  it("returns 400 when Stripe-Signature header is missing", async () => {
+    const response = await server.inject({
+      method: "POST",
+      url: "/v1/webhooks/stripe",
+      payload: VALID_BODY,
+      headers: {
+        "content-type": "application/json",
+        // no stripe-signature
+      },
+    });
+
+    expect(response.statusCode).toBe(400);
+    expect(JSON.parse(response.body)).toEqual({ error: "signature-missing" });
+    expect(mockTrack).not.toHaveBeenCalled();
+  });
+
+  // ── Case 4: Body not a Buffer returns 400 ──────────────────────────────
+
+  it("returns 400 when body is not a Buffer (parser misconfig)", async () => {
+    // Build a server that passes a string body instead of Buffer
+    const stringBodyServer = Fastify({ logger: false });
+    await stringBodyServer.register(async (scope) => {
+      scope.addContentTypeParser(
+        "application/json",
+        { parseAs: "string" },
+        (_req, body, done) => {
+          done(null, body);
+        },
+      );
+      scope.post("/v1/webhooks/stripe", stripeWebhookHandler);
+    });
+    await stringBodyServer.ready();
+
+    try {
+      const response = await stringBodyServer.inject({
+        method: "POST",
+        url: "/v1/webhooks/stripe",
+        payload: '{"type":"test"}',
+        headers: {
+          "content-type": "application/json",
+          "stripe-signature": VALID_SIGNATURE,
+        },
+      });
+
+      expect(response.statusCode).toBe(400);
+      expect(JSON.parse(response.body)).toEqual({ error: "invalid-request" });
+      expect(mockTrack).not.toHaveBeenCalled();
+    } finally {
+      await stringBodyServer.close();
+    }
+  });
+
+  // ── Case 5: Valid checkout.session.completed fires telemetry and 200s ──
+
+  it("returns 200 and fires track on valid checkout.session.completed", async () => {
+    const fakeEvent = buildFakeEvent();
+    mockVerifyWebhookSignature.mockReturnValue(fakeEvent);
+
+    const response = await server.inject({
+      method: "POST",
+      url: "/v1/webhooks/stripe",
+      payload: VALID_BODY,
+      headers: {
+        "content-type": "application/json",
+        "stripe-signature": VALID_SIGNATURE,
+      },
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(JSON.parse(response.body)).toEqual({ received: true });
+    expect(mockTrack).toHaveBeenCalledTimes(1);
+    expect(mockTrack).toHaveBeenCalledWith("purchase-completed", {
+      amount: 4999,
+      currency: "usd",
+      productId: "starter",
+      eventType: "checkout.session.completed",
+      eventIdPrefix: "evt_test",
+    });
+  });
+
+  // ── Case 6: metadata.product_id (snake_case) is accepted ───────────────
+
+  it("accepts metadata.product_id (snake_case) for productId", async () => {
+    const fakeEvent = buildFakeEvent({
+      data: {
+        object: {
+          amount_total: 9900,
+          currency: "usd",
+          metadata: { product_id: "pro" },
+        },
+      },
+    });
+    mockVerifyWebhookSignature.mockReturnValue(fakeEvent);
+
+    const response = await server.inject({
+      method: "POST",
+      url: "/v1/webhooks/stripe",
+      payload: VALID_BODY,
+      headers: {
+        "content-type": "application/json",
+        "stripe-signature": VALID_SIGNATURE,
+      },
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(mockTrack).toHaveBeenCalledWith("purchase-completed", {
+      amount: 9900,
+      currency: "usd",
+      productId: "pro",
+      eventType: "checkout.session.completed",
+      eventIdPrefix: "evt_test",
+    });
+  });
+
+  // ── Case 7: no metadata produces undefined productId ───────────────────
+
+  it("sends undefined productId when metadata is absent", async () => {
+    const fakeEvent = buildFakeEvent({
+      data: {
+        object: {
+          amount_total: 1999,
+          currency: "gbp",
+          metadata: null,
+        },
+      },
+    });
+    mockVerifyWebhookSignature.mockReturnValue(fakeEvent);
+
+    await server.inject({
+      method: "POST",
+      url: "/v1/webhooks/stripe",
+      payload: VALID_BODY,
+      headers: {
+        "content-type": "application/json",
+        "stripe-signature": VALID_SIGNATURE,
+      },
+    });
+
+    const call = mockTrack.mock.calls[0];
+    expect(call[1]).toMatchObject({ productId: undefined });
+  });
+
+  // ── Case 8: Unknown event type 200s with info log ───────────────────────
+
+  it("returns 200 and does not call track for unknown event type", async () => {
+    const fakeEvent = buildFakeEvent({ type: "payment_intent.created" });
+    mockVerifyWebhookSignature.mockReturnValue(fakeEvent);
+
+    const response = await server.inject({
+      method: "POST",
+      url: "/v1/webhooks/stripe",
+      payload: VALID_BODY,
+      headers: {
+        "content-type": "application/json",
+        "stripe-signature": VALID_SIGNATURE,
+      },
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(JSON.parse(response.body)).toEqual({ received: true });
+    expect(mockTrack).not.toHaveBeenCalled();
+  });
+
+  // ── Case 9: Telemetry failure does not block 200 ────────────────────────
+
+  it("returns 200 even when track throws synchronously", async () => {
+    const fakeEvent = buildFakeEvent();
+    mockVerifyWebhookSignature.mockReturnValue(fakeEvent);
+    mockTrack.mockRejectedValueOnce(new Error("analytics unreachable"));
+
+    const response = await server.inject({
+      method: "POST",
+      url: "/v1/webhooks/stripe",
+      payload: VALID_BODY,
+      headers: {
+        "content-type": "application/json",
+        "stripe-signature": VALID_SIGNATURE,
+      },
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(JSON.parse(response.body)).toEqual({ received: true });
+  });
+
+  // ── Case 10: Telemetry timeout does not block 200 ───────────────────────
+
+  it("returns 200 within timeout window when track never resolves", async () => {
+    const fakeEvent = buildFakeEvent();
+    mockVerifyWebhookSignature.mockReturnValue(fakeEvent);
+
+    // track returns a promise that never resolves — simulates a hung adapter
+    let resolveTimeout!: () => void;
+    const neverResolves = new Promise<void>((resolve) => {
+      resolveTimeout = resolve;
+    });
+    mockTrack.mockReturnValueOnce(neverResolves);
+
+    // Use real timers; inject completes once the 2s timeout fires.
+    // We set a generous test timeout so jest doesn't kill it first.
+    const responsePromise = server.inject({
+      method: "POST",
+      url: "/v1/webhooks/stripe",
+      payload: VALID_BODY,
+      headers: {
+        "content-type": "application/json",
+        "stripe-signature": VALID_SIGNATURE,
+      },
+    });
+
+    // Wait for the 2s telemetry timeout to fire naturally, then resolve the
+    // hung track promise so the suite doesn't leak a pending microtask.
+    const response = await responsePromise;
+    resolveTimeout();
+
+    expect(response.statusCode).toBe(200);
+    expect(JSON.parse(response.body)).toEqual({ received: true });
+  }, 6000); // 6s test timeout > 2s TELEMETRY_TIMEOUT_MS
+
+  // ── Case 11: Logs contain no PII ────────────────────────────────────────
+
+  it("does not log customer email, full event ID, or full session ID", async () => {
+    const logLines: unknown[] = [];
+    const logCapture = Fastify({
+      logger: {
+        level: "info",
+        stream: {
+          write(msg: string) {
+            logLines.push(JSON.parse(msg));
+          },
+        },
+      },
+    });
+
+    await logCapture.register(async (scope) => {
+      scope.addContentTypeParser(
+        "application/json",
+        { parseAs: "buffer" },
+        (_req, body, done) => {
+          done(null, body);
+        },
+      );
+      scope.post("/v1/webhooks/stripe", stripeWebhookHandler);
+    });
+    await logCapture.ready();
+
+    try {
+      const fakeEvent = buildFakeEvent();
+      mockVerifyWebhookSignature.mockReturnValue(fakeEvent);
+
+      await logCapture.inject({
+        method: "POST",
+        url: "/v1/webhooks/stripe",
+        payload: VALID_BODY,
+        headers: {
+          "content-type": "application/json",
+          "stripe-signature": VALID_SIGNATURE,
+        },
+      });
+
+      const logText = JSON.stringify(logLines);
+      // Must NOT contain full event ID
+      expect(logText).not.toContain("evt_test_12345678abcdef");
+      // Must NOT contain customer email
+      expect(logText).not.toContain("alice@example.com");
+      // Must NOT contain full session ID
+      expect(logText).not.toContain("cs_test_session_12345678901234567890");
+      // Should contain the 8-char prefix
+      expect(logText).toContain("evt_test");
+    } finally {
+      await logCapture.close();
+    }
+  });
+
+  // ── Case 12: Non-POST methods return 404 ────────────────────────────────
+
+  it("returns 404 for GET /api/webhooks/stripe", async () => {
+    const response = await server.inject({
+      method: "GET",
+      url: "/v1/webhooks/stripe",
+    });
+    expect(response.statusCode).toBe(404);
+  });
+
+  it("returns 404 for PUT /api/webhooks/stripe", async () => {
+    const response = await server.inject({
+      method: "PUT",
+      url: "/v1/webhooks/stripe",
+      payload: VALID_BODY,
+      headers: { "content-type": "application/json" },
+    });
+    expect(response.statusCode).toBe(404);
+  });
+
+  it("returns 404 for DELETE /api/webhooks/stripe", async () => {
+    const response = await server.inject({
+      method: "DELETE",
+      url: "/v1/webhooks/stripe",
+    });
+    expect(response.statusCode).toBe(404);
+  });
+
+  // ── Billing upsert tests (AC bullets 4-6) ──────────────────────────────────
+
+  // AC bullet 4: customer.created → upsert; re-fire same event = no second write
+  it("upserts billing fields on customer.created and is idempotent on re-fire", async () => {
+    const customerId = "cus_test_abc123";
+    const fakeCustomerCreated = {
+      id: "evt_customer_created_001",
+      type: "customer.created",
+      data: {
+        object: {
+          id: customerId,
+          email: "alice@example.com",
+        },
+      },
+    };
+    const upsertedUser = {
+      id: "usr_1",
+      email: "alice@example.com",
+      billingProvider: "stripe",
+      billingCustomerId: customerId,
+    };
+
+    // First fire: typed composite match misses (user not yet linked)
+    (prisma.user.findFirst as jest.Mock).mockResolvedValueOnce(null);
+    // email fallback finds the user
+    (prisma.user.findUnique as jest.Mock).mockResolvedValueOnce({
+      id: "usr_1",
+      email: "alice@example.com",
+      billingProvider: null,
+      billingCustomerId: null,
+    });
+    (prisma.user.update as jest.Mock).mockResolvedValueOnce(upsertedUser);
+
+    mockVerifyWebhookSignature.mockReturnValue(fakeCustomerCreated);
+    const response1 = await server.inject({
+      method: "POST",
+      url: "/v1/webhooks/stripe",
+      payload: VALID_BODY,
+      headers: {
+        "content-type": "application/json",
+        "stripe-signature": VALID_SIGNATURE,
+      },
+    });
+    expect(response1.statusCode).toBe(200);
+    expect(prisma.user.update).toHaveBeenCalledTimes(1);
+    expect(prisma.user.update).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({
+          billingProvider: "stripe",
+          billingCustomerId: customerId,
+        }),
+      }),
+    );
+
+    // Re-fire same event: idempotency store short-circuits — no second write
+    mockVerifyWebhookSignature.mockReturnValue(fakeCustomerCreated);
+    const response2 = await server.inject({
+      method: "POST",
+      url: "/v1/webhooks/stripe",
+      payload: VALID_BODY,
+      headers: {
+        "content-type": "application/json",
+        "stripe-signature": VALID_SIGNATURE,
+      },
+    });
+    expect(response2.statusCode).toBe(200);
+    // update should still be 1 — idempotency store prevented second execution
+    expect(prisma.user.update).toHaveBeenCalledTimes(1);
+  });
+
+  // AC bullet 5: checkout.session.completed + existing User matched by email → billing fields populated
+  it("populates billingProvider/Id on checkout.session.completed for user matched by email", async () => {
+    const customerId = "cus_test_checkout_xyz";
+    const fakeCheckout = {
+      id: "evt_checkout_002",
+      type: "checkout.session.completed",
+      data: {
+        object: {
+          id: "cs_test_abc",
+          amount_total: 4999,
+          currency: "usd",
+          customer: customerId,
+          customer_details: { email: "bob@example.com" },
+          metadata: { productId: "pro" },
+        },
+      },
+    };
+    const updatedUser = {
+      id: "usr_2",
+      email: "bob@example.com",
+      billingProvider: "stripe",
+      billingCustomerId: customerId,
+    };
+
+    // Typed composite lookup misses (no prior link)
+    (prisma.user.findFirst as jest.Mock).mockResolvedValueOnce(null);
+    // Email fallback finds user
+    (prisma.user.findUnique as jest.Mock).mockResolvedValueOnce({
+      id: "usr_2",
+      email: "bob@example.com",
+      billingProvider: null,
+      billingCustomerId: null,
+    });
+    (prisma.user.update as jest.Mock).mockResolvedValueOnce(updatedUser);
+
+    mockVerifyWebhookSignature.mockReturnValue(fakeCheckout);
+    const response = await server.inject({
+      method: "POST",
+      url: "/v1/webhooks/stripe",
+      payload: VALID_BODY,
+      headers: {
+        "content-type": "application/json",
+        "stripe-signature": VALID_SIGNATURE,
+      },
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(prisma.user.update).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { id: "usr_2" },
+        data: expect.objectContaining({
+          billingProvider: "stripe",
+          billingCustomerId: customerId,
+        }),
+      }),
+    );
+  });
+
+  // AC bullet 6: event with neither typed match nor email match → 200 + warning, no User row created
+  it("returns 200 and logs warning when no user match found — no row created", async () => {
+    const fakeOrphan = {
+      id: "evt_orphan_003",
+      type: "customer.created",
+      data: {
+        object: {
+          id: "cus_test_orphan",
+          email: null, // no email — can't even do email fallback
+        },
+      },
+    };
+
+    // Typed composite lookup misses
+    (prisma.user.findFirst as jest.Mock).mockResolvedValueOnce(null);
+    // No email fallback possible (email is null)
+
+    mockVerifyWebhookSignature.mockReturnValue(fakeOrphan);
+    const response = await server.inject({
+      method: "POST",
+      url: "/v1/webhooks/stripe",
+      payload: VALID_BODY,
+      headers: {
+        "content-type": "application/json",
+        "stripe-signature": VALID_SIGNATURE,
+      },
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(JSON.parse(response.body)).toEqual({ received: true });
+    // No user row created
+    expect(prisma.user.update).not.toHaveBeenCalled();
+    expect(prisma.user.create).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,41 @@
+/**
+ * Webhooks route group.
+ *
+ * Routes:
+ *   POST /v1/webhooks/stripe — verify Stripe signature, dispatch event,
+ *                               fire telemetry, respond 200.
+ *
+ * Rate limit: 100 req/min/IP applied at the route level. Above Stripe's
+ * actual retry cadence (a healthy account sees a few events per hour) but
+ * tight enough to make replay-flood DoS unattractive. Encapsulated to the
+ * webhooks scope so the global content limit (60/min) doesn't bleed in.
+ */
+import rateLimit from "@fastify/rate-limit";
+import type { FastifyPluginAsync } from "fastify";
+
+import { stripeWebhookHandler } from "./stripe.js";
+
+export const STRIPE_WEBHOOK_RATE_LIMIT_PER_MIN = 100;
+
+export const webhooksRoutes: FastifyPluginAsync = async (fastify) => {
+  // Register rate-limit at this scope so the webhook gets its own bucket
+  // distinct from the public content API's global limiter.
+  await fastify.register(rateLimit, {
+    global: false,
+    max: STRIPE_WEBHOOK_RATE_LIMIT_PER_MIN,
+    timeWindow: "1 minute",
+  });
+
+  fastify.post(
+    "/v1/webhooks/stripe",
+    {
+      config: {
+        rateLimit: {
+          max: STRIPE_WEBHOOK_RATE_LIMIT_PER_MIN,
+          timeWindow: "1 minute",
+        },
+      },
+    },
+    stripeWebhookHandler,
+  );
+};