create-ailk 0.1.0

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

@@ -0,0 +1,130 @@
+/**
+ * Leads route group.
+ *
+ * Routes:
+ *   POST /v1/leads/submit    — lead submission (contact form / inquiry)
+ *   POST /v1/leads/subscribe — newsletter subscription
+ *   POST /v1/leads/callback  — callback request (phone-back)
+ */
+
+import { track } from "@working-theory/analytics/server";
+import type { FastifyPluginAsync } from "fastify";
+
+import {
+  type LeadKind,
+  type RouteLeadInput,
+  routeLead,
+} from "../../services/lead-routing.js";
+
+/**
+ * Build a typed RouteLeadInput from the raw request body for a given kind.
+ * Explicit destructure per kind prevents unknown fields (e.g. attacker-supplied
+ * `id`) from reaching the service — the service's .strict() Zod schemas provide
+ * a second layer, but we also keep the handler clean at the boundary.
+ */
+function buildInput(
+  kind: LeadKind,
+  body: Record<string, unknown>,
+): RouteLeadInput {
+  if (kind === "lead") {
+    return {
+      kind,
+      siteId: body["siteId"] as string,
+      source: body["source"] as string,
+      email: body["email"] as string,
+      payload: (body["payload"] ?? {}) as Record<string, unknown>,
+    };
+  }
+  if (kind === "subscribe") {
+    return {
+      kind,
+      siteId: body["siteId"] as string,
+      email: body["email"] as string,
+      source: body["source"] as string,
+    };
+  }
+  return {
+    kind,
+    siteId: body["siteId"] as string,
+    name: body["name"] as string,
+    phone: body["phone"] as string,
+    ...(body["preferredTime"] !== undefined && {
+      preferredTime: body["preferredTime"] as string,
+    }),
+    payload: (body["payload"] ?? {}) as Record<string, unknown>,
+  };
+}
+
+function makeLeadsRoute(kind: LeadKind): FastifyPluginAsync {
+  return async (fastify) => {
+    fastify.post(`/v1/leads/${kind}`, async (request, reply) => {
+      const body = request.body as Record<string, unknown>;
+      const sourceMeta = {
+        ip: request.ip,
+        userAgent: request.headers["user-agent"],
+        receivedAt: new Date().toISOString(),
+      };
+
+      const result = await routeLead(buildInput(kind, body), sourceMeta);
+
+      if (!result.ok) {
+        if (result.error.kind === "invalid_input") {
+          return reply
+            .status(400)
+            .send({ error: "invalid_input", message: result.error.message });
+        }
+        if (result.error.kind === "persist_failed") {
+          // Do not surface internal error detail — log it server-side only
+          request.log.error(
+            { kind, siteId: body["siteId"], error: result.error.message },
+            "lead persist_failed",
+          );
+          return reply.status(503).send({ error: "persist_failed" });
+        }
+        // config_missing — lead capture not configured (file disabled + no DB)
+        return reply.status(503).send({
+          error: "lead_capture_not_configured",
+          message: "Lead capture is not configured.",
+        });
+      }
+
+      // PII-safe structured log: only routing metadata, no email/phone/name/payload
+      const emailKind =
+        "skipped" in result.email
+          ? "skipped"
+          : result.email.ok
+            ? "ok"
+            : "error";
+      request.log.info(
+        {
+          siteId: body["siteId"],
+          kind,
+          ip: sourceMeta.ip,
+          persisted: result.persisted,
+          emailKind,
+        },
+        "lead routed",
+      );
+
+      // Fire-and-forget: track() never throws; no need to hold the response.
+      void track("lead-captured", {
+        source: body["source"] as string | undefined,
+        locale: (body["payload"] as Record<string, unknown> | undefined)?.[
+          "locale"
+        ] as string | undefined,
+      });
+
+      return reply
+        .status(201)
+        .send({
+          id: result.id,
+          persisted: result.persisted,
+          email: result.email,
+        });
+    });
+  };
+}
+
+export const leadSubmitRoute = makeLeadsRoute("lead");
+export const leadSubscribeRoute = makeLeadsRoute("subscribe");
+export const leadCallbackRoute = makeLeadsRoute("callback");

package/templates/apps/api/src/routes/test/auth/__tests__/session.test.ts

@@ -0,0 +1,296 @@
+/**
+ * @file session.test.ts
+ *
+ * Integration tests for the triple-gated test-auth route (#517).
+ *
+ * The route is mounted only when all three gates pass:
+ *   1. NODE_ENV !== 'production'
+ *   2. AILK_TEST_AUTH_ENABLED === 'true'
+ *   3. AILK_TEST_AUTH_USER_ALLOWLIST is non-empty
+ *
+ * If any gate fails, the route returns 404 — NEVER 401 or 403 — so the surface
+ * stays hidden in production. The single exception is allowlist-mismatch when
+ * the route IS mounted: that returns 403 (the surface is intentionally exposed
+ * in non-prod test-auth mode; rejecting a non-allowlisted userId with 403 is
+ * the documented behaviour).
+ */
+
+import Fastify from "fastify";
+import type { FastifyInstance } from "fastify";
+
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted; mirrors auth.cookie-path.test.ts pattern
+jest.mock("../../../../lib/prisma.js", () => ({
+  prisma: {
+    user: {
+      findUnique: jest.fn(),
+    },
+    session: {
+      create: jest.fn(),
+    },
+  },
+}));
+
+import { prisma } from "../../../../lib/prisma.js";
+import { registerTestAuthRoute, shouldMountTestAuth } from "../session.js";
+
+const ALLOWLISTED_USER_ID = "test-user-id-001";
+const NON_ALLOWLISTED_USER_ID = "user-not-in-allowlist";
+
+/** Build a Fastify instance with the test-auth route registered unconditionally. */
+function buildAppWithRoute(): FastifyInstance {
+  const app = Fastify({ logger: false });
+  app.register(registerTestAuthRoute);
+  return app;
+}
+
+/** Build a Fastify instance with NO test-auth route registered (gate-failed path). */
+function buildAppWithoutRoute(): FastifyInstance {
+  const app = Fastify({ logger: false });
+  return app;
+}
+
+describe("test-auth route — triple gate (shouldMountTestAuth)", () => {
+  const originalEnv = { ...process.env };
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  it("returns false when AILK_TEST_AUTH_ENABLED is unset (even with NODE_ENV=test)", () => {
+    process.env.NODE_ENV = "test";
+    delete process.env.AILK_TEST_AUTH_ENABLED;
+    process.env.AILK_TEST_AUTH_USER_ALLOWLIST = ALLOWLISTED_USER_ID;
+    expect(shouldMountTestAuth()).toBe(false);
+  });
+
+  it("returns false when NODE_ENV=production (even with flag + allowlist set)", () => {
+    process.env.NODE_ENV = "production";
+    process.env.AILK_TEST_AUTH_ENABLED = "true";
+    process.env.AILK_TEST_AUTH_USER_ALLOWLIST = ALLOWLISTED_USER_ID;
+    expect(shouldMountTestAuth()).toBe(false);
+  });
+
+  it("returns false when AILK_TEST_AUTH_USER_ALLOWLIST is empty", () => {
+    process.env.NODE_ENV = "test";
+    process.env.AILK_TEST_AUTH_ENABLED = "true";
+    process.env.AILK_TEST_AUTH_USER_ALLOWLIST = "";
+    expect(shouldMountTestAuth()).toBe(false);
+  });
+
+  it("returns false when AILK_TEST_AUTH_ENABLED is 'false' (not the literal string 'true')", () => {
+    process.env.NODE_ENV = "test";
+    process.env.AILK_TEST_AUTH_ENABLED = "false";
+    process.env.AILK_TEST_AUTH_USER_ALLOWLIST = ALLOWLISTED_USER_ID;
+    expect(shouldMountTestAuth()).toBe(false);
+  });
+
+  it("returns true when all three gates pass", () => {
+    process.env.NODE_ENV = "test";
+    process.env.AILK_TEST_AUTH_ENABLED = "true";
+    process.env.AILK_TEST_AUTH_USER_ALLOWLIST = ALLOWLISTED_USER_ID;
+    expect(shouldMountTestAuth()).toBe(true);
+  });
+});
+
+describe("test-auth route — POST /api/test/auth/session", () => {
+  let app: FastifyInstance;
+  const originalEnv = { ...process.env };
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  afterEach(async () => {
+    if (app) {
+      await app.close();
+    }
+    process.env = { ...originalEnv };
+  });
+
+  it("returns 404 when route is NOT mounted (gate failed — AILK_TEST_AUTH_ENABLED unset)", async () => {
+    // Simulate the gate-failed registration: route plugin is simply not called.
+    process.env.NODE_ENV = "test";
+    delete process.env.AILK_TEST_AUTH_ENABLED;
+    process.env.AILK_TEST_AUTH_USER_ALLOWLIST = ALLOWLISTED_USER_ID;
+
+    app = buildAppWithoutRoute();
+    await app.ready();
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/test/auth/session",
+      payload: { userId: ALLOWLISTED_USER_ID },
+      headers: { "content-type": "application/json" },
+    });
+
+    // Fastify's default for unregistered routes is 404 — the contract this AC enforces.
+    expect(res.statusCode).toBe(404);
+  });
+
+  it("returns 404 when NODE_ENV=production (route is NOT mounted)", async () => {
+    process.env.NODE_ENV = "production";
+    process.env.AILK_TEST_AUTH_ENABLED = "true";
+    process.env.AILK_TEST_AUTH_USER_ALLOWLIST = ALLOWLISTED_USER_ID;
+
+    // server.ts gates registration on shouldMountTestAuth(); production should
+    // skip the registration and the route should not exist.
+    app = buildAppWithoutRoute();
+    await app.ready();
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/test/auth/session",
+      payload: { userId: ALLOWLISTED_USER_ID },
+      headers: { "content-type": "application/json" },
+    });
+
+    expect(res.statusCode).toBe(404);
+  });
+
+  it("returns 200 with { token, expiresAt, user } for an allowlisted user", async () => {
+    process.env.NODE_ENV = "test";
+    process.env.AILK_TEST_AUTH_ENABLED = "true";
+    process.env.AILK_TEST_AUTH_USER_ALLOWLIST = ALLOWLISTED_USER_ID;
+
+    const userRow = {
+      id: ALLOWLISTED_USER_ID,
+      email: "test-user@example.com",
+      name: "Test User",
+      role: "user",
+    };
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(userRow);
+    (prisma.session.create as jest.Mock).mockImplementation(
+      ({ data }: { data: Record<string, unknown> }) =>
+        Promise.resolve({
+          id: data.id,
+          token: data.token,
+          userId: data.userId,
+          expiresAt: data.expiresAt,
+        }),
+    );
+
+    app = buildAppWithRoute();
+    await app.ready();
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/test/auth/session",
+      payload: { userId: ALLOWLISTED_USER_ID },
+      headers: { "content-type": "application/json" },
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = JSON.parse(res.body);
+    expect(typeof body.token).toBe("string");
+    expect(body.token.length).toBeGreaterThanOrEqual(32); // sufficient entropy
+    expect(body.expiresAt).toBeDefined();
+    expect(new Date(body.expiresAt).getTime()).toBeGreaterThan(Date.now());
+    expect(body.user).toEqual(userRow);
+
+    // Session.create was called with the correct shape
+    expect(prisma.session.create).toHaveBeenCalledWith({
+      data: expect.objectContaining({
+        userId: ALLOWLISTED_USER_ID,
+        token: expect.any(String),
+        expiresAt: expect.any(Date),
+        id: expect.any(String),
+      }),
+    });
+  });
+
+  it("returns 403 when user is not in allowlist", async () => {
+    process.env.NODE_ENV = "test";
+    process.env.AILK_TEST_AUTH_ENABLED = "true";
+    // Allowlist contains only ALLOWLISTED_USER_ID
+    process.env.AILK_TEST_AUTH_USER_ALLOWLIST = ALLOWLISTED_USER_ID;
+
+    app = buildAppWithRoute();
+    await app.ready();
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/test/auth/session",
+      payload: { userId: NON_ALLOWLISTED_USER_ID },
+      headers: { "content-type": "application/json" },
+    });
+
+    expect(res.statusCode).toBe(403);
+    // Session.create MUST NOT have been called for a non-allowlisted user
+    expect(prisma.session.create).not.toHaveBeenCalled();
+  });
+
+  it("returns 404 when user is missing in DB (even if allowlisted)", async () => {
+    process.env.NODE_ENV = "test";
+    process.env.AILK_TEST_AUTH_ENABLED = "true";
+    process.env.AILK_TEST_AUTH_USER_ALLOWLIST = ALLOWLISTED_USER_ID;
+
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(null);
+
+    app = buildAppWithRoute();
+    await app.ready();
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/test/auth/session",
+      payload: { userId: ALLOWLISTED_USER_ID },
+      headers: { "content-type": "application/json" },
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(prisma.session.create).not.toHaveBeenCalled();
+  });
+
+  it("supports CSV-formatted allowlist (multiple userIds)", async () => {
+    process.env.NODE_ENV = "test";
+    process.env.AILK_TEST_AUTH_ENABLED = "true";
+    process.env.AILK_TEST_AUTH_USER_ALLOWLIST = `${ALLOWLISTED_USER_ID},another-user,third-user`;
+
+    const userRow = {
+      id: "another-user",
+      email: "another@example.com",
+      name: "Another User",
+      role: "admin",
+    };
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(userRow);
+    (prisma.session.create as jest.Mock).mockImplementation(
+      ({ data }: { data: Record<string, unknown> }) =>
+        Promise.resolve({
+          id: data.id,
+          token: data.token,
+          userId: data.userId,
+          expiresAt: data.expiresAt,
+        }),
+    );
+
+    app = buildAppWithRoute();
+    await app.ready();
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/test/auth/session",
+      payload: { userId: "another-user" },
+      headers: { "content-type": "application/json" },
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(JSON.parse(res.body).user).toEqual(userRow);
+  });
+
+  it("returns 400 for invalid request body (missing userId)", async () => {
+    process.env.NODE_ENV = "test";
+    process.env.AILK_TEST_AUTH_ENABLED = "true";
+    process.env.AILK_TEST_AUTH_USER_ALLOWLIST = ALLOWLISTED_USER_ID;
+
+    app = buildAppWithRoute();
+    await app.ready();
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/test/auth/session",
+      payload: {},
+      headers: { "content-type": "application/json" },
+    });
+
+    expect(res.statusCode).toBe(400);
+  });
+});

package/templates/apps/api/src/routes/test/auth/session.ts

@@ -0,0 +1,141 @@
+/**
+ * Test-auth session minting route (#517 — pre-OSS e2e seam §3.1, §5.1).
+ *
+ * POST /v1/test/auth/session — mints a real Better Auth Session row for an
+ * allowlisted user, returning { token, expiresAt, user }. The caller is
+ * expected to set the cookie under one of Better Auth's session-cookie names
+ * (`better-auth.session_token` on HTTP/dev, `__Secure-better-auth.session_token`
+ * on HTTPS/prod) so the dual-mode preHandler (apps/api/src/middleware/auth.ts)
+ * reads the row on subsequent requests.
+ *
+ * SECURITY — TRIPLE GATE:
+ *   The route is mounted ONLY when shouldMountTestAuth() returns true. All
+ *   three of these must hold:
+ *     1. NODE_ENV !== 'production'
+ *     2. AILK_TEST_AUTH_ENABLED === 'true' (literal string match)
+ *     3. AILK_TEST_AUTH_USER_ALLOWLIST is a non-empty CSV string
+ *   If any gate fails, the route is never registered. Fastify returns its
+ *   default 404 for unknown routes, which is the documented behaviour — the
+ *   surface NEVER advertises itself in production. The route handler itself
+ *   does NOT re-check the gates; gating is registration-time, not request-time.
+ *
+ * ALLOWLIST FORMAT — comma-separated values (CSV), exact-match strings. No
+ * regex or wildcard. Empty entries (between commas) are trimmed and ignored.
+ */
+import { randomBytes, randomUUID } from "node:crypto";
+
+import { logger } from "@working-theory/observability";
+import type { FastifyPluginAsync } from "fastify";
+import { z } from "zod";
+
+import { prisma } from "../../../lib/prisma.js";
+
+/**
+ * Default session lifetime — matches Better Auth's session.expiresIn config
+ * in apps/web/auth.ts (60 * 60 * 24 * 7 seconds = 7 days). Kept in sync by
+ * convention; the dual-mode preHandler only reads expiresAt, so a small drift
+ * is harmless.
+ */
+const SESSION_LIFETIME_MS = 7 * 24 * 60 * 60 * 1000;
+
+const sessionRequestSchema = z.object({
+  userId: z.string().min(1),
+});
+
+/**
+ * Pure triple-gate predicate. Exported so server.ts and tests can both check
+ * the gate state without duplicating the env-var contract.
+ */
+export function shouldMountTestAuth(): boolean {
+  if (process.env.NODE_ENV === "production") return false;
+  if (process.env.AILK_TEST_AUTH_ENABLED !== "true") return false;
+  const allowlist = process.env.AILK_TEST_AUTH_USER_ALLOWLIST ?? "";
+  if (parseAllowlist(allowlist).length === 0) return false;
+  return true;
+}
+
+/**
+ * Parse the CSV allowlist into a normalized array of trimmed, non-empty
+ * strings. Centralised so route-handler matching and gate-check agree on the
+ * same parse semantics.
+ */
+function parseAllowlist(raw: string): string[] {
+  return raw
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+/**
+ * Generate an opaque session token with at least 256 bits of entropy. Matches
+ * the format Better Auth's own session-token generator uses (hex-encoded
+ * random bytes); the dual-mode preHandler treats this as opaque so the exact
+ * encoding is not load-bearing — but the entropy ceiling matters.
+ *
+ * Uses crypto.randomBytes directly (not @working-theory/common's getRandomness) because
+ * session tokens are security-critical and must not be seedable in e2e mode.
+ */
+function generateSessionToken(): string {
+  return randomBytes(32).toString("hex");
+}
+
+/**
+ * Fastify plugin that registers POST /v1/test/auth/session. Caller MUST gate
+ * registration on shouldMountTestAuth() — the plugin itself trusts that gate
+ * decision and does not re-check at request time.
+ */
+export const registerTestAuthRoute: FastifyPluginAsync = async (fastify) => {
+  fastify.post("/v1/test/auth/session", async (request, reply) => {
+    // ── Parse + validate body ──────────────────────────────────────────────
+    const parsed = sessionRequestSchema.safeParse(request.body);
+    if (!parsed.success) {
+      return reply.code(400).send({
+        error: "invalid_request",
+        details: parsed.error.issues,
+      });
+    }
+
+    const { userId } = parsed.data;
+
+    // ── Allowlist check — 403 (not 404) when route is mounted ──────────────
+    // The gate to hide the surface is registration-time. Once the route is
+    // mounted (non-prod, flag on, allowlist non-empty), a non-allowlisted
+    // userId is a normal authorization failure → 403.
+    const allowlist = parseAllowlist(
+      process.env.AILK_TEST_AUTH_USER_ALLOWLIST ?? "",
+    );
+    if (!allowlist.includes(userId)) {
+      return reply.code(403).send({ error: "forbidden" });
+    }
+
+    // ── User existence check — 404 if the seeded user is missing ───────────
+    const user = await prisma.user.findUnique({
+      where: { id: userId },
+      select: { id: true, email: true, name: true, role: true },
+    });
+    if (!user) {
+      return reply.code(404).send({ error: "user_not_found" });
+    }
+
+    // ── Mint the Session row ───────────────────────────────────────────────
+    const token = generateSessionToken();
+    const expiresAt = new Date(Date.now() + SESSION_LIFETIME_MS);
+    const sessionId = randomUUID();
+
+    await prisma.session.create({
+      data: {
+        id: sessionId,
+        token,
+        userId: user.id,
+        expiresAt,
+      },
+    });
+
+    logger.info(
+      { userId: user.id, sessionId },
+      "[test-auth] minted session for e2e harness",
+    );
+
+    return reply.code(200).send({ token, expiresAt, user });
+  });
+};

package/templates/apps/api/src/routes/webhooks/README.md

@@ -0,0 +1,57 @@
+# Webhooks — `apps/api/src/routes/webhooks/`
+
+Stripe webhook receiver at `POST /v1/webhooks/stripe`. Verifies
+signatures, dispatches events via a `switch`, and fires server-side
+telemetry. v1 handles `checkout.session.completed` only.
+
+## How to add a new event handler
+
+Add a `case` arm to the `switch` in `stripe.ts`:
+
+```ts
+case "invoice.payment_succeeded": {
+  const invoice = event.data.object as { ... };
+  await fireTelemetryWithTimeout(request, "invoice-paid", { ... });
+  break;
+}
+```
+
+Customer forks edit `stripe.ts` directly. v1 ships no pluggable handler
+registry — if multiple forks request one, file an issue.
+
+## Idempotency caveat (load-bearing)
+
+Stripe uses **at-least-once delivery semantics** and occasionally
+double-delivers events. v1 has no idempotency store. Telemetry-only side
+effects make this an acceptable counting drift.
+
+**The day a side effect with write semantics is added** (DB persistence,
+confirmation email, refund processing), an idempotency layer must be added
+first. Suggested pattern: a `webhook_events` table keyed on `event.id`
+with an early-return for already-seen IDs.
+
+## Env contract
+
+Both vars are **server-only** — never use a `NEXT_PUBLIC_` prefix.
+
+| Var                     | Required                     | Notes                                                                                               |
+| ----------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------- |
+| `STRIPE_WEBHOOK_SECRET` | For the route to do anything | `whsec_*` from Stripe Dashboard                                                                     |
+| `STRIPE_SECRET_KEY`     | For checkout + sandbox check | Must be `sk_test_*`; live keys are hook-blocked at commit and runtime-blocked by `assertSandboxKey` |
+
+Without `STRIPE_WEBHOOK_SECRET`, the route returns 503 on every request.
+
+## Deployment note
+
+Customer forks must:
+
+1. Configure a Stripe Dashboard webhook endpoint pointing at
+   `https://<your-host>/v1/webhooks/stripe`.
+2. Copy the endpoint's **Signing secret** (`whsec_*`) into
+   `STRIPE_WEBHOOK_SECRET` in their environment.
+
+Without both, telemetry will not fire and 503s will be logged.
+
+## Brief
+
+`docs/internal/decisions/ailk-stripe-webhook-receiver.md`