create-ailk 0.1.0

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

@@ -0,0 +1,253 @@
+/**
+ * POST /api/webhooks/stripe
+ *
+ * Receives Stripe webhook events. Verifies the signature on the raw
+ * request body using the secret from STRIPE_WEBHOOK_SECRET. Dispatches
+ * verified events through a `switch (event.type)` statement.
+ *
+ * Error mapping (in priority order):
+ *   1. STRIPE_WEBHOOK_SECRET missing      → 503 webhook-not-configured
+ *   2. Body is not a Buffer (parser miss) → 400 invalid-request
+ *   3. Stripe-Signature header missing    → 400 signature-missing
+ *   4. Signature verification fails       → 400 signature-invalid
+ *
+ * Successful dispatch always 200s — including unknown event types.
+ * Telemetry failures are caught, logged, and do NOT change the response.
+ *
+ * Billing upsert (customer.created / checkout.session.completed):
+ *   Lookup priority:
+ *     1. Typed composite match: (billingProvider="stripe", billingCustomerId=customer)
+ *     2. Email fallback: User.findUnique({ where: { email } }) → update billing fields
+ *     3. No match → 200 + warn log; no User row created (pre-signup state)
+ */
+import { track } from "@working-theory/analytics/server";
+import type { FastifyReply, FastifyRequest } from "fastify";
+
+import { config } from "../../config/index.js";
+import { prisma } from "../../lib/prisma.js";
+import {
+  StripeWebhookSignatureError,
+  verifyWebhookSignature,
+} from "../../lib/stripe.js";
+import { hasSeen, markSeen } from "../../lib/webhook-idempotency.js";
+
+const TELEMETRY_TIMEOUT_MS = 2000;
+
+export const stripeWebhookHandler = async (
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> => {
+  const secret = config.STRIPE_WEBHOOK_SECRET;
+  if (!secret) {
+    request.log.warn("stripe webhook hit but STRIPE_WEBHOOK_SECRET is not set");
+    await reply.code(503).send({ error: "webhook-not-configured" });
+    return;
+  }
+
+  const rawBody = request.body;
+  if (!Buffer.isBuffer(rawBody)) {
+    request.log.error(
+      "stripe webhook body is not a Buffer — content-type parser misconfigured",
+    );
+    await reply.code(400).send({ error: "invalid-request" });
+    return;
+  }
+
+  const signature = request.headers["stripe-signature"];
+  if (typeof signature !== "string" || signature.length === 0) {
+    await reply.code(400).send({ error: "signature-missing" });
+    return;
+  }
+
+  let event;
+  try {
+    event = verifyWebhookSignature(rawBody, signature, secret);
+  } catch (err) {
+    if (err instanceof StripeWebhookSignatureError) {
+      request.log.warn(
+        { reason: err.message },
+        "stripe webhook signature verification failed",
+      );
+      await reply.code(400).send({ error: "signature-invalid" });
+      return;
+    }
+    throw err;
+  }
+
+  const eventIdPrefix = event.id.substring(0, 8);
+  request.log.info(
+    { eventType: event.type, eventIdPrefix },
+    "stripe webhook event received",
+  );
+
+  // AILK-layer idempotency. Stripe guarantees at-least-once delivery and
+  // dashboard "resend" replays a previously-delivered event verbatim. Skip
+  // side effects on the second arrival; still 200 so Stripe stops retrying.
+  if (hasSeen(event.id)) {
+    request.log.info(
+      { eventType: event.type, eventIdPrefix },
+      "duplicate stripe webhook event — idempotent short-circuit",
+    );
+    await reply.code(200).send({ received: true });
+    return;
+  }
+  markSeen(event.id);
+
+  switch (event.type) {
+    case "customer.created": {
+      const customer = event.data.object as {
+        id: string;
+        email?: string | null;
+      };
+      await upsertBillingIdentity(request, {
+        customerId: customer.id,
+        email: customer.email ?? null,
+        eventIdPrefix,
+      });
+      break;
+    }
+    case "checkout.session.completed": {
+      const session = event.data.object as {
+        amount_total?: number | null;
+        currency?: string | null;
+        customer?: string | null;
+        customer_details?: { email?: string | null } | null;
+        metadata?: Record<string, string> | null;
+      };
+      const props = {
+        amount: session.amount_total ?? undefined,
+        currency: session.currency ?? undefined,
+        productId:
+          session.metadata?.["productId"] ??
+          session.metadata?.["product_id"] ??
+          undefined,
+        eventType: event.type,
+        eventIdPrefix,
+      };
+
+      // Telemetry and billing upsert are independent — run in parallel.
+      await Promise.all([
+        fireTelemetryWithTimeout(request, "purchase-completed", props),
+        session.customer
+          ? upsertBillingIdentity(request, {
+              customerId: session.customer,
+              email: session.customer_details?.email ?? null,
+              eventIdPrefix,
+            })
+          : Promise.resolve(),
+      ]);
+      break;
+    }
+    default:
+      request.log.info(
+        { eventType: event.type, eventIdPrefix },
+        "unhandled webhook event",
+      );
+      break;
+  }
+
+  await reply.code(200).send({ received: true });
+};
+
+/**
+ * Link User.billingProvider + User.billingCustomerId for a Stripe customer.
+ *
+ * Lookup priority:
+ *   1. Typed composite match: (billingProvider="stripe", billingCustomerId=customerId)
+ *      → already linked; no-op (idempotent)
+ *   2. Email fallback: User.findUnique({ where: { email } }) → update billing fields
+ *   3. No match → warn; do NOT create a User row (pre-signup state preserved for Phase B #852)
+ *
+ * DB failures are caught and logged — a broken DB link should not cause Stripe to retry
+ * the event (which would fire analytics + billing again on eventual success).
+ */
+async function upsertBillingIdentity(
+  request: FastifyRequest,
+  {
+    customerId,
+    email,
+    eventIdPrefix,
+  }: { customerId: string; email: string | null; eventIdPrefix: string },
+): Promise<void> {
+  try {
+    const existingByBilling = await prisma.user.findFirst({
+      where: {
+        billingProvider: "stripe",
+        billingCustomerId: customerId,
+      },
+    });
+
+    if (existingByBilling) {
+      request.log.info(
+        { eventIdPrefix },
+        "billing identity already linked — idempotent no-op",
+      );
+      return;
+    }
+
+    if (email) {
+      const existingByEmail = await prisma.user.findUnique({
+        where: { email },
+      });
+
+      if (existingByEmail) {
+        await prisma.user.update({
+          where: { id: existingByEmail.id },
+          data: {
+            billingProvider: "stripe",
+            billingCustomerId: customerId,
+          },
+        });
+        request.log.info(
+          { eventIdPrefix },
+          "billing identity linked via email fallback",
+        );
+        return;
+      }
+    }
+
+    request.log.warn(
+      { eventIdPrefix },
+      "stripe webhook: no User match for billing identity — pre-signup state preserved",
+    );
+  } catch (err) {
+    request.log.error(
+      {
+        eventIdPrefix,
+        error: err instanceof Error ? err.message : String(err),
+      },
+      "billing identity upsert failed — continuing",
+    );
+  }
+}
+
+async function fireTelemetryWithTimeout(
+  request: FastifyRequest,
+  name: string,
+  props: Record<string, unknown>,
+): Promise<void> {
+  let timeoutId!: ReturnType<typeof setTimeout>;
+  const timeout = new Promise<void>((resolve) => {
+    timeoutId = setTimeout(() => {
+      request.log.warn(
+        { telemetryEvent: name },
+        "telemetry call exceeded timeout; continuing",
+      );
+      resolve();
+    }, TELEMETRY_TIMEOUT_MS);
+  });
+
+  try {
+    await Promise.race([track(name, props), timeout]);
+  } catch (err) {
+    request.log.error(
+      {
+        telemetryEvent: name,
+        error: err instanceof Error ? err.message : String(err),
+      },
+      "telemetry call threw",
+    );
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}

package/templates/apps/api/src/server.ts

@@ -0,0 +1,157 @@
+/**
+ * AI Launch Kit API Server
+ *
+ * Local-only backend for auth (sessions, API tokens) stored in the customer DB.
+ * Business-data proxying has been removed; AILK-native routes will be added
+ * in subsequent issues.
+ *
+ * This file exports a build() function for both:
+ * - Vercel serverless deployment (api/index.ts)
+ * - Local development (src/index.ts)
+ */
+import cors from '@fastify/cors';
+import rateLimit from '@fastify/rate-limit';
+import Fastify from 'fastify';
+
+import { config } from './config/index.js';
+import { registerErrorSerializer } from './lib/error-serializer.js';
+import { validateLeadCaptureDir } from './lib/lead-capture-store.js';
+import { assertSandboxKey } from './lib/stripe.js';
+import { authPreHandlerPlugin } from './middleware/auth.js';
+import { rateLimitMiddleware } from './middleware/rate-limit.js';
+import { openapiRoutes } from './openapi/index.js';
+import { tokenRoutes } from './routes/auth/tokens.js';
+import { userRoutes } from './routes/auth/user.js';
+import { checkoutRoutes } from './routes/checkout/index.js';
+import { contentRoutes } from './routes/content/index.js';
+import {
+  CONTENT_RATE_LIMIT_UNAUTH,
+  CONTENT_RATE_LIMIT_WINDOW,
+} from './routes/content/rate-limit.js';
+import {
+  leadCallbackRoute,
+  leadSubmitRoute,
+  leadSubscribeRoute,
+} from './routes/leads/index.js';
+import { registerTestAuthRoute, shouldMountTestAuth } from './routes/test/auth/session.js';
+import { webhooksRoutes } from './routes/webhooks/index.js';
+
+/**
+ * Build Fastify server instance (for serverless or standalone)
+ * @returns Configured Fastify instance ready for requests
+ */
+export async function build() {
+  // Startup-time validation: fail fast if LEAD_CAPTURE_FILE points at a missing directory.
+  await validateLeadCaptureDir();
+
+  // Runtime sandbox-mode guard: reject live-mode Stripe keys before any
+  // webhook or checkout call can exercise them. Idempotent — safe even if
+  // assertSandboxKey is called again inside a route handler.
+  if (config.STRIPE_SECRET_KEY) {
+    assertSandboxKey(config.STRIPE_SECRET_KEY);
+  }
+
+  const server = Fastify({
+    logger: true,
+  });
+
+  // Register error serializer — maps internal exceptions to generic strings
+  // so connection strings, hostnames, stack traces, and SDK error details
+  // never reach the client. Full detail still goes to pino at error level.
+  registerErrorSerializer(server);
+
+  // Register CORS — public read API + same-origin auth callers
+  await server.register(cors, {
+    origin: config.FRONTEND_URL || true,
+    credentials: true,
+  });
+
+  // Register rate limiting — applied globally with the unauth ceiling. The
+  // limiter is in-memory by default, which suits a single Vercel function /
+  // single-process dev server; multi-instance deployments will need a
+  // Redis store, swappable here without changing route code.
+  await server.register(rateLimit, {
+    max: CONTENT_RATE_LIMIT_UNAUTH,
+    timeWindow: CONTENT_RATE_LIMIT_WINDOW,
+  });
+
+  // Health check
+  server.get('/health', async () => ({
+    status: 'healthy',
+    timestamp: new Date().toISOString(),
+  }));
+
+  // Root endpoint
+  server.get('/', async () => {
+    return {
+      name: 'AI Launch Kit API',
+      version: '1.0.0',
+      description: 'Local auth + session backend + public content API',
+      endpoints: {
+        health: 'GET /health',
+        openapi: 'GET /v1/openapi.json',
+        // Auth (local)
+        tokens: 'POST/GET/DELETE /v1/auth/tokens',
+        profile: 'GET/PATCH /v1/user/profile',
+        userData: 'GET/PUT/DELETE /v1/user/data/:key',
+        // Public content (read-only)
+        contentTypes: 'GET /v1/content/types',
+        contentList: 'GET /v1/content/:type',
+        contentPage: 'GET /v1/content/:type/:slug',
+        checkoutSessions: 'POST /v1/checkout/sessions',
+      },
+    };
+  });
+
+  // Register authenticated routes — the dual-mode preHandler (#587) runs in
+  // this sub-scope so unauthenticated callers never reach token / user data
+  // handlers. Cookie-first, Bearer-fallback; see middleware/auth.ts.
+  await server.register(async (authScope) => {
+    await authScope.register(authPreHandlerPlugin, {
+      frontendOrigin: config.FRONTEND_URL,
+    });
+    await authScope.register(tokenRoutes);
+    await authScope.register(userRoutes);
+  });
+
+  // Public routes — no auth required.
+  await server.register(contentRoutes);
+  await server.register(checkoutRoutes);
+
+  // Webhooks routes — raw-body parser scoped to this sub-router only so the
+  // global JSON parser on all other routes is unaffected.
+  await server.register(async (webhooksScope) => {
+    webhooksScope.addContentTypeParser(
+      'application/json',
+      { parseAs: 'buffer' },
+      (_req, body, done) => {
+        done(null, body);
+      },
+    );
+    await webhooksScope.register(webhooksRoutes);
+  });
+
+  // Leads routes — rate-limit middleware scoped to this sub-router
+  await server.register(async (leadsScope) => {
+    leadsScope.register(rateLimitMiddleware);
+    await leadsScope.register(leadSubmitRoute);
+    await leadsScope.register(leadSubscribeRoute);
+    await leadsScope.register(leadCallbackRoute);
+  });
+
+  // Test-auth route — triple-gated (NODE_ENV !== production AND
+  // AILK_TEST_AUTH_ENABLED === 'true' AND AILK_TEST_AUTH_USER_ALLOWLIST
+  // non-empty). When any gate fails, the route is never registered and
+  // Fastify returns its default 404 — the surface NEVER advertises itself
+  // in production. See #517 / docs/internal/roadmaps/e2e-testing-roadmap.md.
+  if (shouldMountTestAuth()) {
+    await server.register(registerTestAuthRoute);
+    server.log.warn(
+      'test-auth route MOUNTED — only safe in dev/test environments',
+    );
+  }
+
+  await server.register(openapiRoutes);
+
+  return server;
+}