create-ailk 0.7.0 → 0.9.0

package/templates/apps/api/src/services/__tests__/revalidation.test.ts

@@ -4,9 +4,10 @@
  * loopback HTTP server (spec D11), not a `global.fetch` double: the contract
  * under test is the wire format, and only a real server proves that the bytes
  * on the wire are the bytes the signature covers. The server recomputes the
- * HMAC inside its own handler — the receiver's verification, performed for
- * real — and compares with `timingSafeEqual`, exactly as a Phase-3 receiver
- * will (spec FR7).
+ * HMAC inside its own handler over the D1 base string
+ * `v0:{timestamp}:{event}:{rawBody}` (#5902) — the receiver's verification,
+ * performed for real — and compares with `timingSafeEqual`, exactly as the
+ * receiver does (spec FR7).
  *
  * The server binds 127.0.0.1, which `ssrfBlocked` rejects; D7's
  * `allowPrivate: true` is what makes this substrate runnable at all.
@@ -23,10 +24,13 @@ import type { AddressInfo } from "node:net";
 const TEST_SECRET = "not-a-real-secret-fixture-value";
 const SIGNATURE_HEADER = "x-ailk-revalidate-signature";
 const EVENT_HEADER = "x-ailk-revalidate-event";
+const TIMESTAMP_HEADER = "x-ailk-revalidate-timestamp";
 
+// `type` must be a registered page type and `slug` a SLUG_PATTERN value — the
+// sender validates both before signing (#5902).
 const TARGET = {
   workspaceId: "ws_test_0001",
-  type: "page",
+  type: "Service",
   slug: "pricing",
   locale: "en",
 };
@@ -63,8 +67,11 @@ jest.mock("@working-theory/observability", () => ({
 interface Recorded {
   rawBody: string;
   signatureValid: boolean;
+  /** Whether the signature is HMAC over the raw body ALONE (the pre-#5902 wire). */
+  bodyOnlySignatureValid: boolean;
   signatureHeader: string;
   eventHeader: string;
+  timestampHeader: string;
   contentType: string;
   receivedAt: number;
 }
@@ -81,26 +88,40 @@ beforeAll(async () => {
     req.on("data", (c: Buffer) => void chunks.push(c));
     req.on("end", () => {
       const raw = Buffer.concat(chunks);
-
-      // The receiver's own verification (FR7): recompute HMAC-SHA256 over the
-      // RAW request body bytes and compare in constant time.
-      const expected = Buffer.from(
-        createHmac("sha256", TEST_SECRET).update(raw).digest("hex"),
-        "utf8",
-      );
+      const timestampHeader = String(req.headers[TIMESTAMP_HEADER] ?? "");
+      const eventHeader = String(req.headers[EVENT_HEADER] ?? "");
       const received = Buffer.from(
         String(req.headers[SIGNATURE_HEADER] ?? "").replace(/^sha256=/, ""),
         "utf8",
       );
-      const signatureValid =
-        expected.length === received.length &&
-        timingSafeEqual(expected, received);
+      const matches = (material: Buffer): boolean => {
+        const expected = Buffer.from(
+          createHmac("sha256", TEST_SECRET).update(material).digest("hex"),
+          "utf8",
+        );
+        return (
+          expected.length === received.length &&
+          timingSafeEqual(expected, received)
+        );
+      };
+
+      // The receiver's own verification (FR7, D1 as amended by #5902):
+      // recompute HMAC-SHA256 over `v0:{timestamp}:{event}:` followed by the
+      // RAW request body bytes, and compare in constant time.
+      const signatureValid = matches(
+        Buffer.concat([
+          Buffer.from(`v0:${timestampHeader}:${eventHeader}:`, "utf8"),
+          raw,
+        ]),
+      );
 
       recorded.push({
         rawBody: raw.toString("utf8"),
         signatureValid,
+        bodyOnlySignatureValid: matches(raw),
         signatureHeader: String(req.headers[SIGNATURE_HEADER] ?? ""),
-        eventHeader: String(req.headers[EVENT_HEADER] ?? ""),
+        eventHeader,
+        timestampHeader,
         contentType: String(req.headers["content-type"] ?? ""),
         receivedAt: Date.now(),
       });
@@ -219,6 +240,60 @@ describe("notifyRevalidate", () => {
     });
   }, 20_000);
 
+  it("signs v0:{timestamp}:{event}:{body} and sends the timestamp header (#5902)", async () => {
+    responseStatuses = [200];
+    const before = Math.floor(Date.now() / 1000);
+
+    await loadService().notifyRevalidate(TARGET, { event: "unpublish" });
+
+    const after = Math.floor(Date.now() / 1000);
+    expect(recorded).toHaveLength(1);
+    const [req] = recorded;
+
+    // Unix seconds, digits only, taken at send time — what the receiver checks
+    // its 5-minute tolerance against.
+    expect(req.timestampHeader).toMatch(/^[0-9]+$/);
+    const ts = Number(req.timestampHeader);
+    expect(ts).toBeGreaterThanOrEqual(before);
+    expect(ts).toBeLessThanOrEqual(after);
+
+    // The base-string shape, recomputed independently here: the timestamp and
+    // the event are inside the MAC, so neither can be altered in flight.
+    const expected = createHmac("sha256", TEST_SECRET)
+      .update(`v0:${req.timestampHeader}:unpublish:${req.rawBody}`, "utf8")
+      .digest("hex");
+    expect(req.signatureHeader).toBe(`sha256=${expected}`);
+    expect(req.signatureValid).toBe(true);
+    // And the body-alone signature of the pre-#5902 wire no longer verifies.
+    expect(req.bodyOnlySignatureValid).toBe(false);
+  });
+
+  it.each([
+    ["type", "page"], // not a registered page type
+    ["type", "Service:some-slug:en"], // the tag-collision shape (#6005 M3)
+    ["type", "S".repeat(300)],
+    ["slug", "Bad Slug"],
+    ["slug", "a:b"],
+    ["slug", ""],
+    ["locale", "english"],
+    ["locale", "en:x"],
+    ["locale", ""],
+  ])(
+    "throws before any outbound call on an invalid %s (%j) (#5902)",
+    async (field, value) => {
+      responseStatuses = [200];
+
+      await expect(
+        loadService().notifyRevalidate(
+          { ...TARGET, [field]: value },
+          { event: "publish" },
+        ),
+      ).rejects.toThrow();
+
+      expect(recorded).toHaveLength(0);
+    },
+  );
+
   it("is a single-warning no-op with CONTENT_REVALIDATE_URL unset", async () => {
     delete process.env.CONTENT_REVALIDATE_URL;
     delete process.env.CONTENT_REVALIDATE_SECRET;

package/templates/apps/api/src/services/checkout-buyer.ts

@@ -0,0 +1,72 @@
+/**
+ * @file checkout-buyer.ts
+ * @description Resolves a signed-in user into the Checkout buyer
+ * `POST /v1/checkout/sessions` pins and stamps (#6866 D3).
+ *
+ * A buyer is a user whose email is VERIFIED — the customer created for them
+ * carries the account email, and it must never carry an unproven one — and
+ * whose billing binding, if any, is a Stripe customer. The binding decides
+ * whether the library reuses a customer (`customerId`) or creates one
+ * (`null`). A row bound under any other provider is not a buyer: the webhook
+ * never re-points a non-null `billingCustomerId` (#6113), so a new stamped
+ * customer could only be an orphan.
+ *
+ * Base tree (N4): imports only `verified-email.ts` and `lib/prisma.ts`, never
+ * the commerce overlay's `services/subscription.ts`. The billing read selects
+ * no email, so `tools/lint-email-authz.ts` has nothing to flag.
+ */
+
+import { prisma } from "../lib/prisma.js";
+
+import { findVerifiedEmail } from "./verified-email.js";
+
+export type CheckoutBuyer = {
+  userId: string;
+  email: string;
+  /** The user's bound Stripe customer, or `null` when one is to be created. */
+  customerId: string | null;
+};
+
+export type CheckoutBuyerResult =
+  | { ok: true; buyer: CheckoutBuyer }
+  | {
+      ok: false;
+      reason: "user_not_found" | "email_unverified" | "foreign_provider";
+    };
+
+/**
+ * @param userId the id resolved from the authenticated session cookie — never
+ *        a request-supplied value.
+ * @throws whatever Prisma throws; the caller degrades that to anonymous (F7).
+ */
+export async function resolveCheckoutBuyer(
+  userId: string,
+): Promise<CheckoutBuyerResult> {
+  const verified = await findVerifiedEmail(userId);
+  if (!verified.ok) return { ok: false, reason: verified.reason };
+
+  const billing = await prisma.user.findUnique({
+    where: { id: userId },
+    select: { billingProvider: true, billingCustomerId: true },
+  });
+  if (!billing) return { ok: false, reason: "user_not_found" };
+
+  if (billing.billingCustomerId === null) {
+    return {
+      ok: true,
+      buyer: { userId, email: verified.value.email, customerId: null },
+    };
+  }
+  // The same provider predicate `resolveBillingCustomer` applies.
+  if (billing.billingProvider !== "stripe") {
+    return { ok: false, reason: "foreign_provider" };
+  }
+  return {
+    ok: true,
+    buyer: {
+      userId,
+      email: verified.value.email,
+      customerId: billing.billingCustomerId,
+    },
+  };
+}

package/templates/apps/api/src/services/lead-routing.ts

@@ -2,7 +2,12 @@
  * @file lead-routing.ts
  * @description Cross-namespace lead orchestration service (ADR 0009 D3).
  *
- * Pipeline: validate → enrich → persist (DB with file fallback) → email.
+ * Pipeline: validate → delivery guard → enrich → persist (DB with file
+ * fallback) → email. Where a lead may go is `resolveLeadDelivery()`
+ * (`lib/lead-delivery.ts`, #6730 D1): with no database but the email vars set,
+ * the owner email IS the delivery; in production with neither, nothing is
+ * accepted. A lead is reported sent only for a durable row or an email the
+ * provider accepted — never for the non-durable file fallback in production.
  * This is the first implementation of ADR 0009 D3's service-layer pattern.
  * Future cross-namespace orchestrators in apps/api/src/services/ should mirror
  * this shape: type-result returns, mocked-dep tests, non-transactional secondary
@@ -32,6 +37,7 @@ import { leadInputSchema } from "@working-theory/validation";
 
 import { writeLeadFallback } from "../lib/file-fallback.js";
 import { appendLeadRecord } from "../lib/lead-capture-store.js";
+import { acceptsKind, resolveLeadDelivery } from "../lib/lead-delivery.js";
 import { prisma } from "../lib/prisma.js";
 
 import { enrichLead } from "./enrichment-shim.js";
@@ -65,11 +71,14 @@ export type SourceMeta = {
   receivedAt: string; // ISO
 };
 
+/** Where the lead landed: a database row, the local file fallback, or the owner's inbox by email (#6730). */
+export type Persisted = "db" | "file" | "email";
+
 export type RouteLeadResult =
   | {
       ok: true;
       id: string;
-      persisted: "db" | "file";
+      persisted: Persisted;
       email:
         | { ok: true; messageId: string }
         | { ok: false; error: string }
@@ -78,7 +87,11 @@ export type RouteLeadResult =
   | {
       ok: false;
       error: {
-        kind: "invalid_input" | "persist_failed" | "config_missing";
+        kind:
+          | "invalid_input"
+          | "persist_failed"
+          | "config_missing"
+          | "delivery_failed";
         message: string;
       };
     };
@@ -272,7 +285,7 @@ type EmailResult =
 async function sendEmail(
   input: RouteLeadInput,
   id: string,
-  persisted: "db" | "file",
+  persisted: Persisted,
 ): Promise<EmailResult> {
   // Request-and-confirm SUPERSEDES this notification for a callback (#5970
   // D6). AC-1 requires the tenant to receive exactly one email, and the
@@ -316,7 +329,22 @@ async function sendEmail(
     siteId: input.siteId,
     source: input.kind === "callback" ? "callback" : input.source,
     email: input.kind === "callback" ? "" : input.email,
-    payload: input.kind === "subscribe" ? {} : input.payload,
+    // A callback's contact details are top-level fields, not payload keys
+    // (#6730): with no database the email is the only record of the
+    // request, so it must carry the name and number to call back.
+    payload:
+      input.kind === "subscribe"
+        ? {}
+        : input.kind === "callback"
+          ? {
+              ...input.payload,
+              name: input.name,
+              phone: input.phone,
+              ...(input.preferredTime !== undefined && {
+                preferredTime: input.preferredTime,
+              }),
+            }
+          : input.payload,
     createdAt: new Date().toISOString(),
   };
 
@@ -324,6 +352,9 @@ async function sendEmail(
     lead: leadForEmail,
     recipientEmail: to,
     fromAddress: from,
+    // A callback has no visitor address to reply to; an empty Reply-To is
+    // not a valid header, so reply to the owner instead.
+    ...(input.kind === "callback" && { replyToOverride: to }),
   });
 
   if (emailResult.ok) {
@@ -337,6 +368,47 @@ async function sendEmail(
   return { ok: false, error: `${kind}: ${message}` };
 }
 
+// ─── Email delivery (#6730 D2) ────────────────────────────────────────────────
+
+type EmailDelivery =
+  | { ok: true; id: string; email: { ok: true; messageId: string } }
+  | { ok: false; message: string };
+
+/**
+ * Deliver a lead as the owner email alone — success only when the provider
+ * accepted it. The id matches the file-fallback id format
+ * (`/^[a-z0-9_-]{8,64}$/i`).
+ */
+async function deliverByEmail(input: RouteLeadInput): Promise<EmailDelivery> {
+  const id = `email-${Date.now()}-${randomUUID().slice(0, 8)}`;
+  const result = await sendEmail(input, id, "email");
+  if ("ok" in result && result.ok) return { ok: true, id, email: result };
+  return {
+    ok: false,
+    message: "error" in result ? result.error : `email skipped: ${result.reason}`,
+  };
+}
+
+// ─── Lead-capture record ─────────────────────────────────────────────────────
+
+function captureRecordFor(input: RouteLeadInput, id: string, sourceMeta: SourceMeta) {
+  return {
+    id,
+    createdAt: sourceMeta.receivedAt,
+    source: input.kind === "callback" ? "callback" : input.source,
+    data:
+      input.kind === "callback"
+        ? { name: input.name, phone: input.phone, ...(input.payload ?? {}) }
+        : input.kind === "subscribe"
+          ? { email: input.email }
+          : { email: input.email, ...(input.payload ?? {}) },
+    metadata: {
+      ip: sourceMeta.ip,
+      userAgent: sourceMeta.userAgent,
+    },
+  };
+}
+
 // ─── Main export ──────────────────────────────────────────────────────────────
 
 export async function routeLead(
@@ -352,13 +424,13 @@ export async function routeLead(
     };
   }
 
-  // 2. Guard: if file capture is disabled AND no DB is configured, bail early.
-  // Both paths are unavailable — returning a clear error is better than a
-  // misleading 201 or a stack trace from Prisma on a missing DATABASE_URL.
-  if (
-    process.env.LEAD_CAPTURE_FILE_DISABLED === "true" &&
-    !process.env.DATABASE_URL
-  ) {
+  // 2. Guard: where can this lead go (#6730 D1)? A kind the configured
+  // delivery cannot take — anything in production with neither a database
+  // nor the email vars, a newsletter signup with no database — is refused
+  // before any write, so no visitor is told a message was sent when it
+  // reached nobody.
+  const delivery = resolveLeadDelivery();
+  if (!acceptsKind(delivery, input.kind)) {
     return {
       ok: false,
       error: {
@@ -374,9 +446,28 @@ export async function routeLead(
   // the real enrichment call with proper type alignment.
   await enrichLead(input as unknown as Parameters<typeof enrichLead>[0]);
 
+  // Email delivery — no database: the owner email is the delivery, so skip
+  // the DB and the (non-durable) file fallback entirely.
+  if (delivery === "email") {
+    const emailed = await deliverByEmail(input);
+    if (!emailed.ok) {
+      return {
+        ok: false,
+        error: { kind: "delivery_failed", message: emailed.message },
+      };
+    }
+    await appendLeadRecord(captureRecordFor(input, emailed.id, sourceMeta));
+    return {
+      ok: true,
+      id: emailed.id,
+      persisted: "email",
+      email: emailed.email,
+    };
+  }
+
   // 4. Persist primary (DB), fallback to file on error
   let id: string;
-  let persisted: "db" | "file";
+  let persisted: Persisted;
   let skipEmail = false;
   let skipReason: string | undefined;
 
@@ -424,7 +515,41 @@ export async function routeLead(
       };
     }
 
-    // 5. File fallback
+    // In production the file fallback is not durable (a serverless instance
+    // does not outlive the request), so reporting it as success would lose
+    // the lead silently. Deliver by email when that is configured; otherwise
+    // fail loudly (#6730 D2). A newsletter signup is never emailed — one
+    // owner email per address is not a list (`acceptsKind`).
+    if (process.env.NODE_ENV === "production") {
+      const dbMsg = dbErr instanceof Error ? dbErr.message : String(dbErr);
+      if (input.kind === "subscribe") {
+        return {
+          ok: false,
+          error: { kind: "persist_failed", message: `db: ${dbMsg}` },
+        };
+      }
+      const emailed = await deliverByEmail(input);
+      if (!emailed.ok) {
+        return {
+          ok: false,
+          error: {
+            kind: "persist_failed",
+            // Not the provider's text: it can echo an address, and this
+            // message is logged (spec D5).
+            message: `db: ${dbMsg}; email delivery failed`,
+          },
+        };
+      }
+      await appendLeadRecord(captureRecordFor(input, emailed.id, sourceMeta));
+      return {
+        ok: true,
+        id: emailed.id,
+        persisted: "email",
+        email: emailed.email,
+      };
+    }
+
+    // 5. File fallback (outside production only)
     // Include a UUID suffix so concurrent fallbacks produce unique IDs even
     // within the same millisecond. Format still matches /^[a-z0-9_-]{8,64}$/i.
     const fallbackLead = {
@@ -468,22 +593,7 @@ export async function routeLead(
   // 6. Write to lead-capture JSONL (always-on canonical AX surface).
   // Best-effort — a write failure does NOT roll back persistence or block email.
   // The file is the agent-readable surface; DB is the transactional record.
-  const captureRecord = {
-    id: id!,
-    createdAt: sourceMeta.receivedAt,
-    source: input.kind === "callback" ? "callback" : input.source,
-    data:
-      input.kind === "callback"
-        ? { name: input.name, phone: input.phone, ...(input.payload ?? {}) }
-        : input.kind === "subscribe"
-          ? { email: input.email }
-          : { email: input.email, ...(input.payload ?? {}) },
-    metadata: {
-      ip: sourceMeta.ip,
-      userAgent: sourceMeta.userAgent,
-    },
-  };
-  await appendLeadRecord(captureRecord);
+  await appendLeadRecord(captureRecordFor(input, id!, sourceMeta));
 
   // 7. Email notification (best-effort — never rolls back persistence)
   let emailResult: EmailResult;

package/templates/apps/api/src/services/leads-inbox.ts

@@ -25,10 +25,14 @@
  *
  * Two preconditions, neither of which this file can assert:
  *
- *   1. `resolveOwnerWorkspaces` must yield a workspace. On a build with no
- *      `multi-tenant` module it yields none — see its own header, and #5677,
- *      which made that a deliberate scope limit rather than a statement that
- *      there is nothing to resolve.
+ *   1. The caller's scope must resolve to a workspace. With the
+ *      `multi-tenant` module that is `resolveOwnerWorkspaces`. Without it
+ *      (#6730 D7) — Free and Pro — that resolver yields none by design (its
+ *      own header, #5677), so the scope is instead the default workspace,
+ *      granted ONLY through `resolveDefaultTenantForOperator`
+ *      (`default-tenant.ts`): `AILK_OPERATOR_EMAIL` set, the caller's
+ *      VERIFIED email equal to it, and the deployment unambiguously
+ *      one-workspace. Any other caller gets the empty page, never a wider one.
  *   2. The `siteId` the leads were WRITTEN under must equal a workspace id,
  *      and there are TWO independent sources of it — both must agree with the
  *      workspace, and neither is `currentSiteId()` on the primary path:
@@ -67,8 +71,10 @@
 import type { Prisma } from "@working-theory/database";
 import type { Id } from "@working-theory/ids";
 
+import { isModuleEnabled } from "../config/modules.js";
 import { prisma } from "../lib/prisma.js";
 
+import { resolveDefaultTenantForOperator } from "./default-tenant.js";
 import { resolveOwnerWorkspaces } from "./owner-workspaces.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
@@ -178,6 +184,40 @@ export function readName(payload: Prisma.JsonValue): string | null {
   return typeof name === "string" ? name.slice(0, MAX_NAME_LENGTH) : null;
 }
 
+// ─── Scope ────────────────────────────────────────────────────────────────────
+
+/**
+ * The workspace ids whose leads the caller may read. With `multi-tenant`,
+ * every workspace they own or administer (`resolveOwnerWorkspaces`,
+ * unchanged). Without it (#6730 D7), the default workspace — only for the
+ * pinned, verified operator on a one-workspace deployment; `null` from the
+ * resolver means no scope at all.
+ */
+async function resolveInboxSiteIds(
+  userId: Id<"user">,
+): Promise<{ ok: true; siteIds: string[] } | { ok: false; message: string }> {
+  if (!isModuleEnabled("multi-tenant")) {
+    try {
+      const tenant = await resolveDefaultTenantForOperator(userId);
+      return {
+        ok: true,
+        siteIds: tenant && LEAD_INBOX_ROLES.has(tenant.role) ? [tenant.workspaceId] : [],
+      };
+    } catch (err) {
+      return { ok: false, message: err instanceof Error ? err.message : String(err) };
+    }
+  }
+
+  const workspaces = await resolveOwnerWorkspaces(userId);
+  if (!workspaces.ok) return { ok: false, message: workspaces.error.message };
+  return {
+    ok: true,
+    siteIds: workspaces.value
+      .filter((workspace) => LEAD_INBOX_ROLES.has(workspace.role))
+      .map((workspace) => workspace.id),
+  };
+}
+
 // ─── Main export ──────────────────────────────────────────────────────────────
 
 /**
@@ -199,17 +239,14 @@ export async function listOwnedLeads(params: {
   cursor?: string | undefined;
   limit: number;
 }): Promise<ListLeadsResult> {
-  const workspaces = await resolveOwnerWorkspaces(params.userId);
-  if (!workspaces.ok) {
+  const scope = await resolveInboxSiteIds(params.userId);
+  if (!scope.ok) {
     return {
       ok: false,
-      error: { kind: "internal_error", message: workspaces.error.message },
+      error: { kind: "internal_error", message: scope.message },
     };
   }
-
-  const siteIds = workspaces.value
-    .filter((workspace) => LEAD_INBOX_ROLES.has(workspace.role))
-    .map((workspace) => workspace.id);
+  const siteIds = scope.siteIds;
 
   // No workspace the caller owns or administers means no lead can match, so
   // there is nothing to query. An empty page is the honest answer — the same