create-ailk 0.7.0 → 0.9.0

package/templates/apps/api/src/lib/__tests__/lead-capture-store.test.ts

@@ -96,6 +96,36 @@ describe("appendLeadRecord", () => {
     expect(filePath).toMatch(/leads\.jsonl$/);
   });
 
+  // #6730 D3 — the default file is local-only: in production it does not
+  // outlive a serverless instance, so it is skipped unless explicitly pointed
+  // at a durable path.
+  describe("in production (#6730 D3)", () => {
+    const savedNodeEnv = process.env.NODE_ENV;
+    afterEach(() => {
+      process.env.NODE_ENV = savedNodeEnv;
+    });
+
+    it("skips the write when LEAD_CAPTURE_FILE is unset", async () => {
+      process.env.NODE_ENV = "production";
+
+      const result = await appendLeadRecord(record);
+
+      expect(result).toEqual({ ok: true, skipped: true });
+      expect(mockAppendFile).not.toHaveBeenCalled();
+    });
+
+    it("writes when LEAD_CAPTURE_FILE is set explicitly", async () => {
+      process.env.NODE_ENV = "production";
+      process.env.LEAD_CAPTURE_FILE = "/data/leads.jsonl";
+
+      const result = await appendLeadRecord(record);
+
+      expect(result).toEqual({ ok: true });
+      expect(mockAppendFile).toHaveBeenCalledTimes(1);
+      expect(mockAppendFile.mock.calls[0][0]).toBe("/data/leads.jsonl");
+    });
+  });
+
   // AC4 — LEAD_CAPTURE_FILE_DISABLED=true skips the write
   it("short-circuits write when LEAD_CAPTURE_FILE_DISABLED=true", async () => {
     process.env.LEAD_CAPTURE_FILE_DISABLED = "true";

package/templates/apps/api/src/lib/__tests__/lead-delivery.test.ts

@@ -0,0 +1,96 @@
+/**
+ * @file lead-delivery.test.ts
+ * @description The #6730 D1 delivery table, row by row.
+ */
+
+import { acceptsKind, resolveLeadDelivery } from "../lead-delivery";
+
+const EMAIL = {
+  RESEND_API_KEY: "re_test",
+  AILK_LEAD_NOTIFICATION_TO: "owner@example.com",
+  AILK_LEAD_NOTIFICATION_FROM: "noreply@example.com",
+};
+
+describe("resolveLeadDelivery", () => {
+  it("DATABASE_URL alone → inbox", () => {
+    expect(resolveLeadDelivery({ DATABASE_URL: "postgres://x", NODE_ENV: "production" })).toBe(
+      "inbox",
+    );
+  });
+
+  it("DATABASE_URL wins over the email vars", () => {
+    expect(resolveLeadDelivery({ DATABASE_URL: "postgres://x", ...EMAIL })).toBe("inbox");
+  });
+
+  it("the three email vars, no database → email", () => {
+    expect(resolveLeadDelivery({ ...EMAIL, NODE_ENV: "production" })).toBe("email");
+    expect(resolveLeadDelivery({ ...EMAIL, NODE_ENV: "development" })).toBe("email");
+  });
+
+  it("a bare RESEND_API_KEY is not email delivery — local in dev, none in production", () => {
+    expect(resolveLeadDelivery({ RESEND_API_KEY: "re_test", NODE_ENV: "development" })).toBe(
+      "local",
+    );
+    expect(resolveLeadDelivery({ RESEND_API_KEY: "re_test", NODE_ENV: "production" })).toBe(
+      "none",
+    );
+  });
+
+  it("the key and one address only → not email", () => {
+    expect(
+      resolveLeadDelivery({
+        RESEND_API_KEY: "re_test",
+        AILK_LEAD_NOTIFICATION_TO: "owner@example.com",
+        NODE_ENV: "production",
+      }),
+    ).toBe("none");
+  });
+
+  it("nothing configured in production → none", () => {
+    expect(resolveLeadDelivery({ NODE_ENV: "production" })).toBe("none");
+  });
+
+  it("nothing configured outside production → local", () => {
+    expect(resolveLeadDelivery({ NODE_ENV: "test" })).toBe("local");
+    expect(resolveLeadDelivery({})).toBe("local");
+  });
+
+  it("LEAD_CAPTURE_FILE_DISABLED=true removes the local path → none", () => {
+    expect(
+      resolveLeadDelivery({ NODE_ENV: "development", LEAD_CAPTURE_FILE_DISABLED: "true" }),
+    ).toBe("none");
+  });
+
+  it("reads process.env by default", () => {
+    const saved = process.env.DATABASE_URL;
+    process.env.DATABASE_URL = "postgres://x";
+    try {
+      expect(resolveLeadDelivery()).toBe("inbox");
+    } finally {
+      if (saved === undefined) delete process.env.DATABASE_URL;
+      else process.env.DATABASE_URL = saved;
+    }
+  });
+});
+
+describe("acceptsKind", () => {
+  it("none accepts nothing", () => {
+    expect(acceptsKind("none", "submit")).toBe(false);
+    expect(acceptsKind("none", "subscribe")).toBe(false);
+    expect(acceptsKind("none", "callback")).toBe(false);
+  });
+
+  it("email accepts submit and callback, never subscribe", () => {
+    expect(acceptsKind("email", "submit")).toBe(true);
+    expect(acceptsKind("email", "callback")).toBe(true);
+    expect(acceptsKind("email", "subscribe")).toBe(false);
+  });
+
+  it("inbox and local accept every kind", () => {
+    for (const d of ["inbox", "local"] as const) {
+      expect(acceptsKind(d, "submit")).toBe(true);
+      expect(acceptsKind(d, "subscribe")).toBe(true);
+      expect(acceptsKind(d, "callback")).toBe(true);
+    }
+  });
+});

package/templates/apps/api/src/lib/lead-capture-store.ts

@@ -12,6 +12,15 @@
  *
  * Env vars (all read inside function bodies — module is import-side-effect-free):
  *   LEAD_CAPTURE_FILE            — output path (default: apps/api/leads.jsonl relative to cwd)
+ *
+ * The default path is LOCAL-ONLY (#6730 D3). In production
+ * (`NODE_ENV=production`) with `LEAD_CAPTURE_FILE` unset, the write is skipped:
+ * on serverless hosting a file under the process cwd does not outlive the
+ * instance, so it is not a record of anything. An operator with a durable
+ * volume can keep a side copy by setting `LEAD_CAPTURE_FILE` explicitly —
+ * a copy only: in production it never makes a lead count as delivered
+ * (`lib/lead-delivery.ts` needs a database or the email vars).
+ *
  *   LEAD_CAPTURE_FILE_DISABLED   — set to "true" to skip writes (opt-out)
  *   LEAD_CAPTURE_INCLUDE_IP      — set to "true" to include metadata.ip in the record
  *
@@ -47,6 +56,9 @@ export async function appendLeadRecord(
   if (disabled) {
     return { ok: true, skipped: true };
   }
+  if (process.env.NODE_ENV === "production" && !process.env.LEAD_CAPTURE_FILE) {
+    return { ok: true, skipped: true };
+  }
 
   const includeIp = process.env.LEAD_CAPTURE_INCLUDE_IP === "true";
   const outputPath = resolveOutputPath();

package/templates/apps/api/src/lib/lead-delivery.ts

@@ -0,0 +1,52 @@
+/**
+ * @file lead-delivery.ts
+ * @description Where a captured lead goes, resolved from the environment (#6730 D1).
+ *
+ *   inbox — `DATABASE_URL` is set: the database is the destination (the lead
+ *           inbox at `/leads`); the owner email is still sent best-effort.
+ *   email — no database, but `RESEND_API_KEY` plus both notification
+ *           addresses are set: the owner email IS the delivery.
+ *   local — neither, outside production (`pnpm dev`, tests): the local file
+ *           fallback + `leads.jsonl`, so local work needs nothing configured.
+ *   none  — neither, in production: nothing is accepted, so no visitor is
+ *           ever told a message was sent when it reached nobody.
+ *
+ * A key alone delivers nothing (`sendEmail()` also needs both addresses), so
+ * it is not counted as configured. `LEAD_CAPTURE_FILE_DISABLED=true` removes
+ * the local file path, so outside production it resolves to `none` too.
+ *
+ * Import-side-effect-free; the environment is read at call time.
+ */
+
+export type LeadDelivery = "inbox" | "email" | "local" | "none";
+
+export type LeadDeliveryKind = "submit" | "subscribe" | "callback";
+
+export function resolveLeadDelivery(
+  env: NodeJS.ProcessEnv = process.env,
+): LeadDelivery {
+  if (env.DATABASE_URL) return "inbox";
+  if (
+    env.RESEND_API_KEY &&
+    env.AILK_LEAD_NOTIFICATION_TO &&
+    env.AILK_LEAD_NOTIFICATION_FROM
+  ) {
+    return "email";
+  }
+  if (env.NODE_ENV !== "production" && env.LEAD_CAPTURE_FILE_DISABLED !== "true") {
+    return "local";
+  }
+  return "none";
+}
+
+/**
+ * Whether a delivery mode accepts a lead of this kind. A newsletter
+ * subscription is a list entry, not a message — emailing the owner one
+ * address per signup is not a list — so `subscribe` needs somewhere to keep
+ * it (the database, or the local file in development).
+ */
+export function acceptsKind(d: LeadDelivery, kind: LeadDeliveryKind): boolean {
+  if (d === "none") return false;
+  if (kind === "subscribe") return d === "inbox" || d === "local";
+  return true;
+}

package/templates/apps/api/src/lib/stripe.ts

@@ -11,6 +11,13 @@
 import { getStripeClient } from "@working-theory/stripe-client";
 
 export {
+  // PRECONDITION (#6113): do not narrow or bypass this sandbox-only guard for a
+  // production key class until #6113's no-overwrite guard in
+  // routes/webhooks/stripe.ts upsertBillingIdentity is on main — an unverified
+  // Checkout email must never re-point an already-bound User.billingCustomerId.
+  // Widened by #6852 (the #6113 follow-up): the same function must bind only
+  // on a server-stamped metadata.ailk_user_id — an unverified Checkout email
+  // never makes a FIRST binding either.
   assertSandboxKey,
   createAdHocPrice,
   createBillingPortalSession,
@@ -25,6 +32,8 @@ export {
   StripeConfigError,
   StripeWebhookSignatureError,
   toSubscriptionLifecycleStatus,
+  // Signed-in Checkout (#6866 D8) — a pinned customer Stripe rejects.
+  UnknownCustomerError,
   UnknownProductCodeError,
   UnknownSessionError,
   verifyWebhookSignature,

package/templates/apps/api/src/middleware/__tests__/auth.optional-cookie.test.ts

@@ -0,0 +1,140 @@
+/**
+ * @file auth.optional-cookie.test.ts
+ *
+ * The non-rejecting cookie resolver `resolveOptionalCookieUser` (#6866 D2).
+ *
+ * Asserts each `none` reason (A1–A6), a `user` for a valid same-origin cookie
+ * (A7), and that the resolver never writes a reply and never throws.
+ */
+
+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
+jest.mock("../../lib/prisma.js", () => ({
+  prisma: {
+    session: { findUnique: jest.fn() },
+    apiToken: { findUnique: jest.fn(), update: jest.fn() },
+  },
+}));
+
+import { prisma } from "../../lib/prisma.js";
+import { resolveOptionalCookieUser } from "../auth.js";
+
+const FRONTEND = "https://app.example.com";
+const COOKIE = "better-auth.session_token=sess_tok_abc.signature";
+
+/** Echoes the resolver's result; the reply is only ever written here. */
+function buildApp(): FastifyInstance {
+  const app = Fastify();
+  app.post("/resolve", async (req) =>
+    resolveOptionalCookieUser(req, { frontendOrigin: FRONTEND }),
+  );
+  return app;
+}
+
+function validSession(overrides: Record<string, unknown> = {}) {
+  return {
+    id: "ses_1",
+    userId: "usr_buyer",
+    expiresAt: new Date(Date.now() + 60_000),
+    activeOrganizationId: null,
+    activeWorkspaceId: null,
+    ...overrides,
+  };
+}
+
+describe("resolveOptionalCookieUser (#6866 D2)", () => {
+  const originalDatabaseUrl = process.env.DATABASE_URL;
+  let app: FastifyInstance;
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+    process.env.DATABASE_URL = "postgresql://test:test@localhost/test";
+    app = buildApp();
+    await app.ready();
+  });
+
+  afterEach(async () => {
+    await app.close();
+    if (originalDatabaseUrl === undefined) delete process.env.DATABASE_URL;
+    else process.env.DATABASE_URL = originalDatabaseUrl;
+  });
+
+  async function resolve(headers: Record<string, string>) {
+    const res = await app.inject({ method: "POST", url: "/resolve", headers });
+    // The route's own handler wrote the only reply — the resolver wrote none.
+    expect(res.statusCode).toBe(200);
+    return JSON.parse(res.body) as unknown;
+  }
+
+  it("A1: no cookie → none/no_cookie, with no database read", async () => {
+    expect(await resolve({ origin: FRONTEND })).toEqual({
+      kind: "none",
+      reason: "no_cookie",
+    });
+    expect(prisma.session.findUnique).not.toHaveBeenCalled();
+  });
+
+  it("A1b: a bearer header alone is ignored — none/no_cookie, apiToken never read (F8)", async () => {
+    expect(
+      await resolve({ origin: FRONTEND, authorization: "Bearer tok_valid" }),
+    ).toEqual({ kind: "none", reason: "no_cookie" });
+    expect(prisma.apiToken.findUnique).not.toHaveBeenCalled();
+  });
+
+  it("A2: DATABASE_URL unset with a cookie → none/no_database", async () => {
+    delete process.env.DATABASE_URL;
+    expect(await resolve({ origin: FRONTEND, cookie: COOKIE })).toEqual({
+      kind: "none",
+      reason: "no_database",
+    });
+    expect(prisma.session.findUnique).not.toHaveBeenCalled();
+  });
+
+  it("A3: unknown token → none/unknown_session", async () => {
+    (prisma.session.findUnique as jest.Mock).mockResolvedValue(null);
+    expect(await resolve({ origin: FRONTEND, cookie: COOKIE })).toEqual({
+      kind: "none",
+      reason: "unknown_session",
+    });
+  });
+
+  it("A4: expired session → none/expired", async () => {
+    (prisma.session.findUnique as jest.Mock).mockResolvedValue(
+      validSession({ expiresAt: new Date(Date.now() - 1_000) }),
+    );
+    expect(await resolve({ origin: FRONTEND, cookie: COOKIE })).toEqual({
+      kind: "none",
+      reason: "expired",
+    });
+  });
+
+  it("A5: POST with a foreign Origin → none/cross_origin", async () => {
+    (prisma.session.findUnique as jest.Mock).mockResolvedValue(validSession());
+    expect(
+      await resolve({ origin: "https://evil.example.com", cookie: COOKIE }),
+    ).toEqual({ kind: "none", reason: "cross_origin" });
+  });
+
+  it("A6: the session lookup rejects → none/lookup_failed, never a throw", async () => {
+    (prisma.session.findUnique as jest.Mock).mockRejectedValue(
+      new Error("db down"),
+    );
+    expect(await resolve({ origin: FRONTEND, cookie: COOKIE })).toEqual({
+      kind: "none",
+      reason: "lookup_failed",
+    });
+  });
+
+  it("A7: a valid same-origin cookie → user, looked up by the unsigned token", async () => {
+    (prisma.session.findUnique as jest.Mock).mockResolvedValue(validSession());
+    expect(await resolve({ origin: FRONTEND, cookie: COOKIE })).toEqual({
+      kind: "user",
+      userId: "usr_buyer",
+    });
+    expect(prisma.session.findUnique).toHaveBeenCalledWith(
+      expect.objectContaining({ where: { token: "sess_tok_abc" } }),
+    );
+  });
+});

package/templates/apps/api/src/middleware/auth.ts

@@ -191,6 +191,60 @@ export type AuthPreHandlerOptions = {
   frontendOrigin?: string | undefined;
 };
 
+/**
+ * The result of `resolveOptionalCookieUser` — a signed-in user, or the reason
+ * there is none (#6866 D2).
+ */
+export type OptionalCookieUser =
+  | { kind: "user"; userId: Id<"user"> }
+  | {
+      kind: "none";
+      reason:
+        | "no_cookie"
+        | "no_database"
+        | "unknown_session"
+        | "expired"
+        | "cross_origin"
+        | "lookup_failed";
+    };
+
+/**
+ * Non-rejecting cookie resolver for routes that stay open to anonymous callers
+ * but act on a signed-in user when there is one (#6866 D2 — the checkout
+ * route's buyer stamp).
+ *
+ * Applies the cookie path's own rules — the same private cookie reader,
+ * Session lookup, expiry comparison and same-origin check as
+ * `makeAuthPreHandler` — so the two paths cannot drift. Reads the COOKIE only:
+ * a bearer `ApiToken` never identifies a user here. Never writes a reply and
+ * never throws; every failure is a `none` with its reason. The cookie is
+ * checked first, so an anonymous call on a database-less boot is `no_cookie`.
+ */
+export async function resolveOptionalCookieUser(
+  request: FastifyRequest,
+  opts: AuthPreHandlerOptions,
+): Promise<OptionalCookieUser> {
+  const cookieToken = readSessionCookie(request);
+  if (!cookieToken) return { kind: "none", reason: "no_cookie" };
+  if (!process.env.DATABASE_URL) return { kind: "none", reason: "no_database" };
+
+  let session: SessionRow | undefined;
+  try {
+    session = await resolveCookieSession(cookieToken);
+  } catch {
+    return { kind: "none", reason: "lookup_failed" };
+  }
+  if (!session) return { kind: "none", reason: "unknown_session" };
+  if (session.expiresAt.getTime() <= getClock().now()) {
+    return { kind: "none", reason: "expired" };
+  }
+  if (!isOriginAllowed(request, opts.frontendOrigin)) {
+    return { kind: "none", reason: "cross_origin" };
+  }
+  // Brand assertion at the Prisma read edge (ADR-0031 rule 5), as above.
+  return { kind: "user", userId: session.userId as Id<"user"> };
+}
+
 /**
  * Fastify preHandler implementing the dual-mode contract.
  *

package/templates/apps/api/src/openapi/spec.ts

@@ -747,9 +747,11 @@ export function buildOpenApiSpec(
             "form fields — for the given siteId. `source` is a free-form tag the caller " +
             "sets to identify the channel (for example `agent`); it is stored as-is and " +
             "not checked against a fixed vocabulary. A 201 response means the lead " +
-            "landed, in the database or (if the database is unavailable) a file " +
-            "fallback; the response's `email` field reports, best-effort, whether the " +
-            "site operator was notified.",
+            "landed — in the database, a local file fallback (outside production " +
+            "only), or, on a deployment with no database, the site operator's inbox " +
+            "by email (`persisted: \"email\"`); with a database, the response's " +
+            "`email` field reports, best-effort, whether the operator was notified. " +
+            "A lead is never reported captured when nothing stored or delivered it.",
           requestBody: {
             required: true,
             content: {
@@ -777,8 +779,8 @@ export function buildOpenApiSpec(
             },
             "503": {
               description:
-                "Lead capture unavailable — persistence failed, or neither file " +
-                "capture nor a database is configured",
+                "Lead capture unavailable — persistence failed, delivery failed, or " +
+                "this deployment has nowhere to put the lead",
               content: {
                 "application/json": {
                   schema: {
@@ -787,6 +789,7 @@ export function buildOpenApiSpec(
                       {
                         $ref: "#/components/schemas/LeadCaptureNotConfiguredResponse",
                       },
+                      { $ref: "#/components/schemas/DeliveryFailedResponse" },
                     ],
                   },
                 },
@@ -795,6 +798,36 @@ export function buildOpenApiSpec(
           },
         },
       },
+      "/v1/leads/capture": {
+        get: {
+          operationId: "getLeadCaptureStatus",
+          summary: "Whether this site accepts a contact message or a signup",
+          description:
+            "Two booleans: `contact` — a `POST /v1/leads/submit` would be accepted; " +
+            "`newsletter` — a `POST /v1/leads/subscribe` would be. A web page reads " +
+            "it to show the contact form or the site's contact email. It never says " +
+            "how a lead is delivered. No MCP twin (recorded parity exception): the " +
+            "three lead-write tools already answer the same question with a 503.",
+          responses: {
+            "200": {
+              description: "Lead-capture status",
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    required: ["ok", "data"],
+                    properties: {
+                      ok: { type: "boolean", enum: [true] },
+                      data: { $ref: "#/components/schemas/LeadCaptureStatus" },
+                    },
+                  },
+                },
+              },
+            },
+            "429": { $ref: "#/components/responses/RateLimited" },
+          },
+        },
+      },
       "/v1/leads/subscribe": {
         post: {
           operationId: "subscribeLead",
@@ -833,8 +866,8 @@ export function buildOpenApiSpec(
             },
             "503": {
               description:
-                "Lead capture unavailable — persistence failed, or neither file " +
-                "capture nor a database is configured",
+                "Lead capture unavailable — persistence failed, delivery failed, or " +
+                "this deployment has nowhere to put the lead",
               content: {
                 "application/json": {
                   schema: {
@@ -1033,8 +1066,8 @@ export function buildOpenApiSpec(
             },
             "503": {
               description:
-                "Lead capture unavailable — persistence failed, or neither file " +
-                "capture nor a database is configured",
+                "Lead capture unavailable — persistence failed, delivery failed, or " +
+                "this deployment has nowhere to put the lead",
               content: {
                 "application/json": {
                   schema: {
@@ -1043,6 +1076,7 @@ export function buildOpenApiSpec(
                       {
                         $ref: "#/components/schemas/LeadCaptureNotConfiguredResponse",
                       },
+                      { $ref: "#/components/schemas/DeliveryFailedResponse" },
                     ],
                   },
                 },
@@ -1489,10 +1523,11 @@ export function buildOpenApiSpec(
               type: "string",
               description:
                 "Server-assigned record id — a DB-prefixed entity id when " +
-                'persisted is "db", or a `fallback-<ts>-<rand>` file id when ' +
-                'persisted is "file"',
+                'persisted is "db", a `fallback-<ts>-<rand>` file id when ' +
+                'persisted is "file", or an `email-<ts>-<rand>` id when persisted ' +
+                'is "email" (no database; the operator email was the delivery)',
             },
-            persisted: { type: "string", enum: ["db", "file"] },
+            persisted: { type: "string", enum: ["db", "file", "email"] },
             email: { $ref: "#/components/schemas/LeadEmailResult" },
           },
         },
@@ -1511,6 +1546,22 @@ export function buildOpenApiSpec(
             error: { type: "string", enum: ["persist_failed"] },
           },
         },
+        DeliveryFailedResponse: {
+          type: "object",
+          required: ["error", "message"],
+          properties: {
+            error: { type: "string", enum: ["delivery_failed"] },
+            message: { type: "string" },
+          },
+        },
+        LeadCaptureStatus: {
+          type: "object",
+          required: ["contact", "newsletter"],
+          properties: {
+            contact: { type: "boolean" },
+            newsletter: { type: "boolean" },
+          },
+        },
         LeadCaptureNotConfiguredResponse: {
           type: "object",
           required: ["error", "message"],

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

@@ -44,6 +44,8 @@ jest.mock("@working-theory/stripe-client", () => ({
       this.name = "UnknownSessionError";
     }
   },
+  // #6866 — sessions.ts tests `instanceof UnknownCustomerError`.
+  UnknownCustomerError: class UnknownCustomerError extends Error {},
   UnknownProductCodeError: class UnknownProductCodeError extends Error {
     constructor(productCode: string) {
       super(`No active price found for lookup_key: ${productCode}`);
@@ -59,6 +61,7 @@ jest.mock("@working-theory/stripe-client", () => ({
 }));
 
 // Import after mock setup
+import { config } from "../../../config/index.js";
 import { checkoutRoutes } from "../index";
 import { __resetBuckets } from "../../../middleware/rate-limit.js";
 
@@ -370,8 +373,8 @@ describe("GET /v1/checkout/sessions/:id", () => {
       url: "/v1/checkout/sessions",
       payload: {
         productCode: "ailk-pro",
-        successUrl: "https://example.com/success",
-        cancelUrl: "https://example.com/cancel",
+        successUrl: `${config.FRONTEND_URL}/success`,
+        cancelUrl: `${config.FRONTEND_URL}/cancel`,
       },
     });