create-ailk 0.21.0 → 0.22.0

package/templates/apps/api/src/lib/flow-completion-store.ts

@@ -0,0 +1,136 @@
+/**
+ * A magnet's completion setting — its data boundary (#8757, spec
+ * docs/specs/8757-a-per-magnet-completion-setting-spec.md D3).
+ *
+ * `flow_definitions.completion` / `checkout_offering` are new columns, and
+ * `lib/tenant-db.ts` — the magnet routes' only other data path — stays closed
+ * under the parallel contract with #8746 (D7), so the two columns get this
+ * named boundary of their own. Every statement is scoped by a server-resolved
+ * `workspaceId` (a tenant's, or the public lead route's resolved workspace):
+ *
+ *   - `completionsFor`       — one `findMany` by workspace AND id list;
+ *   - `setCompletion`        — one `updateMany` by id AND workspace, writing
+ *                              exactly the two columns;
+ *   - `liveCompletionBySlug` — one `findFirst` of a LIVE magnet by workspace
+ *                              AND slug (its pair, title and config — the
+ *                              config for a declared `completionEmail`);
+ *   - `inviteSendCounts`     — two `lead.count`s for the invite email's caps
+ *                              (D6), by workspace AND `flow:<slug>` source.
+ *
+ * No list without an id set, no other model, no read by any other key.
+ * Base tree (SEC-8757-D): no `oss: false` marker and no `MODULE_SLICES`
+ * entry, because the never-gate lead route imports it. `architecture.yaml`
+ * lists this file under the tenant-scope rule's `paths_scoped` with exactly
+ * these four call sites' counts, so a further access fails the lint.
+ */
+import {
+  FLOW_COMPLETION_DEFAULT,
+  flowCompletionSettingSchema,
+  type FlowCompletionSetting,
+} from "@working-theory/validation";
+
+import { prisma } from "./prisma.js";
+
+const DEFAULT_SETTING: FlowCompletionSetting = {
+  completion: FLOW_COMPLETION_DEFAULT,
+  checkoutOffering: null,
+};
+
+/**
+ * A stored pair as the vocabulary reads it. The database's CHECKs make every
+ * stored pair valid; a row that carries neither column (a test fixture, or a
+ * read before the migration) reads as the default, as `customersEnabled` does.
+ */
+function toSetting(row: { completion?: unknown; checkoutOffering?: unknown }) {
+  const parsed = flowCompletionSettingSchema.safeParse({
+    completion: row.completion,
+    checkoutOffering: row.checkoutOffering ?? null,
+  });
+  return parsed.success ? parsed.data : DEFAULT_SETTING;
+}
+
+/** The setting of each of `ids` in `workspaceId`. An id absent from the map reads as `lead`. */
+export async function completionsFor(
+  workspaceId: string,
+  ids: readonly string[],
+): Promise<Map<string, FlowCompletionSetting>> {
+  const out = new Map<string, FlowCompletionSetting>();
+  if (ids.length === 0) return out;
+  const rows = await prisma.flowDefinition.findMany({
+    where: { workspaceId, id: { in: [...ids] } },
+    select: { id: true, completion: true, checkoutOffering: true },
+  });
+  for (const row of rows) out.set(row.id, toSetting(row));
+  return out;
+}
+
+/** `completionsFor`'s answer for one id. */
+export function completionOf(
+  settings: Map<string, FlowCompletionSetting>,
+  id: string,
+): FlowCompletionSetting {
+  return settings.get(id) ?? DEFAULT_SETTING;
+}
+
+/** Write the pair onto magnet `id` of `workspaceId`; nothing else on the row. */
+export async function setCompletion(
+  workspaceId: string,
+  id: string,
+  setting: FlowCompletionSetting,
+): Promise<"set" | "not_found"> {
+  const result = await prisma.flowDefinition.updateMany({
+    where: { id, workspaceId },
+    data: { completion: setting.completion, checkoutOffering: setting.checkoutOffering },
+  });
+  return result.count > 0 ? "set" : "not_found";
+}
+
+export type LiveCompletion = FlowCompletionSetting & {
+  title: string;
+  /** The stored config, unparsed — the invite email reads its `completionEmail`. */
+  config: unknown;
+};
+
+/** The LIVE magnet at `slug` in `workspaceId`: its setting, title and config, or `null`. */
+export async function liveCompletionBySlug(
+  workspaceId: string,
+  slug: string,
+): Promise<LiveCompletion | null> {
+  const row = await prisma.flowDefinition.findFirst({
+    where: { workspaceId, slug, status: "live" },
+    select: { title: true, config: true, completion: true, checkoutOffering: true },
+  });
+  return row === null ? null : { ...toSetting(row), title: row.title, config: row.config };
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const HOUR_MS = 60 * 60 * 1000;
+
+/**
+ * D6's two caps, counted in the database so they hold across instances and
+ * against a spoofed `x-forwarded-for`: this magnet's leads for `email`
+ * (case-insensitively) over the last day, and all of its leads over the last
+ * hour. Both include the lead the caller just wrote.
+ */
+export async function inviteSendCounts(
+  workspaceId: string,
+  slug: string,
+  email: string,
+  now: Date,
+): Promise<{ recipientDay: number; siteHour: number }> {
+  const source = `flow:${slug}`;
+  const [recipientDay, siteHour] = await Promise.all([
+    prisma.lead.count({
+      where: {
+        workspaceId,
+        source,
+        email: { equals: email, mode: "insensitive" },
+        createdAt: { gte: new Date(now.getTime() - DAY_MS) },
+      },
+    }),
+    prisma.lead.count({
+      where: { workspaceId, source, createdAt: { gte: new Date(now.getTime() - HOUR_MS) } },
+    }),
+  ]);
+  return { recipientDay, siteHour };
+}

package/templates/apps/api/src/lib/hub-sign-in-store.ts

@@ -102,6 +102,38 @@ export async function findClientByClientId(
   });
 }
 
+/** What the hub's sign-in page may show about a spoke (#8790 D2). */
+export interface SignInClientInfo {
+  clientId: string;
+  /** The spoke's display name from the registry. */
+  name: string;
+  /** The origin of the client's first registered redirect URI. */
+  origin: string;
+}
+
+/**
+ * The public shape of one spoke's sign-in client, or `null` when the client
+ * is missing, disabled, or its spoke is revoked (#8790 D2). Only the
+ * registry decides what a sign-in page may name — never a query parameter.
+ */
+export async function findSignInClientInfo(
+  clientId: string,
+): Promise<SignInClientInfo | null> {
+  const client = await findClientByClientId(clientId);
+  if (client === null || !client.enabled) return null;
+  const spoke = await findSpokeById(clientId);
+  if (spoke === null || spoke.revokedAt !== null) return null;
+  const first = client.redirectUris[0];
+  if (first === undefined) return null;
+  let origin: string;
+  try {
+    origin = new URL(first).origin;
+  } catch {
+    return null;
+  }
+  return { clientId, name: spoke.name, origin };
+}
+
 /**
  * Create or update a spoke's sign-in client (the operator CLI). Re-running
  * rotates the secret: `clientSecret` is replaced by the new digest, so the
@@ -161,7 +193,10 @@ export function canonicalRedirectUri(raw: string): string | null {
 
 export type RegisterSignInClientResult =
   | { ok: true; spokeId: string; secret: string }
-  | { ok: false; reason: "invalid-redirect-uri" | "spoke-not-found" | "spoke-revoked" };
+  | {
+      ok: false;
+      reason: "invalid-redirect-uri" | "spoke-not-found" | "spoke-revoked";
+    };
 
 /**
  * The operator CLI's `sign-in-client` (D3): refuse an invalid callback, an
@@ -173,7 +208,8 @@ export async function registerSignInClient(params: {
   redirectUri: string;
 }): Promise<RegisterSignInClientResult> {
   const redirectUri = canonicalRedirectUri(params.redirectUri);
-  if (redirectUri === null) return { ok: false, reason: "invalid-redirect-uri" };
+  if (redirectUri === null)
+    return { ok: false, reason: "invalid-redirect-uri" };
 
   const spoke = await findSpokeById(params.spokeId);
   if (!spoke) return { ok: false, reason: "spoke-not-found" };

package/templates/apps/api/src/lib/proposal-paid-store.ts

@@ -8,13 +8,15 @@
  * every scaffold without the member slice (the #5677 failure). Its one piece
  * write therefore lives here, in the base tree, importing only `prisma.ts`.
  *
- * Two statements and no others, both scoped by a workspace id AND a piece id
+ * Three statements and no others, all scoped by a workspace id AND a piece id
  * taken from a Stripe-signed `checkout.session.completed` event's metadata —
  * written by this server when it opened the session (`ailk_proposal`,
  * `ailk_workspace`; `services/proposal-payments.ts`), never settable by the
- * payer: a guarded `updateMany` that stamps an unpaid proposal paid, and a
- * `findFirst` by the same pair reading back which session paid it. No list,
- * no other model, no read by any other key; never called by a route.
+ * payer: a guarded `updateMany` that stamps an unpaid proposal paid, a
+ * `findFirst` by the same pair reading back which session paid it, and a
+ * `findFirst` by the same pair reading the proposal's Person — the subject of
+ * the checkout's terms grant (#8765 D14). No list, no other model, no read by
+ * any other key; never called by a route.
  * `architecture.yaml` names this file as a tenant-scope exclusion with that
  * reason.
  */
@@ -47,3 +49,18 @@ export async function stampProposalPaid(
   if (row === null) return "not_found";
   return row.paidSessionId === sessionId ? "replay" : "already_paid";
 }
+
+/**
+ * The proposal's Person (#8765 D14), or `null` when no proposal of that id
+ * is in that workspace.
+ */
+export async function proposalPersonId(
+  workspaceId: string,
+  pieceId: string,
+): Promise<string | null> {
+  const row = await prisma.piece.findFirst({
+    where: { id: pieceId, workspaceId, kind: "proposal" },
+    select: { personId: true },
+  });
+  return row?.personId ?? null;
+}

package/templates/apps/api/src/middleware/__tests__/auth.hub-session-path.test.ts

@@ -53,7 +53,11 @@ let spokeA: SeededSpoke;
 let spokeB: SeededSpoke;
 let handlerRuns: string[];
 
-/** D1's 18 strings plus #8435's two contact routes and #8438's two consents routes (22), in the list's order. */
+/**
+ * D1's 18 strings plus #8435's two contact routes, #8438's two consents
+ * routes, #8765's account-agreements pair and #8515's onboarding pair (26),
+ * in the list's order.
+ */
 const ADMITTED = [
   "GET /v1/hub-sign-in/me",
   "GET /v1/member/pieces",
@@ -77,6 +81,9 @@ const ADMITTED = [
   "POST /v1/member/deletion-request",
   "GET /v1/member/consents",
   "POST /v1/member/consents",
+  // #8765 D5 — the caller's account-level sign-up agreements.
+  "GET /v1/consent/account",
+  "POST /v1/consent/account",
   // #8515 D13 — the client's onboarding read and write.
   "GET /v1/member/onboarding",
   "POST /v1/member/onboarding",
@@ -86,6 +93,8 @@ const ADMITTED = [
 const OFF_LIST = [
   "GET /v1/consent/platform",
   "POST /v1/consent/platform",
+  // #8765 D2 — the anonymous sign-up evidence is never a credential's route.
+  "GET /v1/consent/sign-up",
   "GET /v1/member/other",
   "GET /v1/member/messages/:id",
   "GET /v1/waitlist-signups/me",
@@ -177,9 +186,9 @@ afterEach(async () => {
 });
 
 describe("HUB_SESSION_ROUTES", () => {
-  it("is exactly the 24 entries, by method and registered URL — never a prefix (AC-1, #8515 AC-6)", () => {
+  it("is exactly the 26 entries, by method and registered URL — never a prefix (AC-1, #8515 AC-6, #8765 AC-6)", () => {
     expect([...HUB_SESSION_ROUTES]).toEqual(ADMITTED);
-    expect(HUB_SESSION_ROUTES.length).toBe(24);
+    expect(HUB_SESSION_ROUTES.length).toBe(26);
     for (const route of HUB_SESSION_ROUTES) {
       expect({
         route,
@@ -222,6 +231,8 @@ describe("hub credential — admitted routes", () => {
 
 describe("hub credential — every other route is 404 with no handler run (AC-7)", () => {
   it.each([
+    ["GET", "/v1/consent/sign-up"],
+    ["GET", "/v1/consent/platform"],
     ["GET", "/v1/member/other"],
     ["GET", "/v1/member/messages/lead_1"],
     ["GET", "/v1/waitlist-signups/me"],

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

@@ -34,9 +34,10 @@
  *      spoke's key (`x-ailk-spoke-key`), only while its grant is unrevoked and
  *      unexpired, its client enabled and its person's email verified, and only
  *      on `HUB_SESSION_ROUTES` — an exact list of METHOD + registered URL
- *      pairs — the credential's own `me` and the member routes, 24 in all
- *      (#8220, #8515); any other route is 404 (never 403, so the account area's
- *      `read()` loads "nothing for this caller"). It acts as its person
+ *      pairs — the credential's own `me`, the member routes and the
+ *      account-agreements pair, 26 in all (#8220, #8515, #8765); any other
+ *      route is 404 (never 403, so the account area's `read()` loads
+ *      "nothing for this caller"). It acts as its person
  *      (`request.userId`) and carries `request.hubSession` — never
  *      `request.sessionTenant` — and its request logger names the spoke
  *      (`spokeId`). Each person is limited, at each spoke, to 60 requests and
@@ -153,12 +154,14 @@ export type HubSession = {
  * The only routes a hub-issued credential reaches (#7894 D6, #8220 D1): an
  * EXACT list of method + registered URL, never a prefix and never computed,
  * so a route added later joins only by a reviewed edit of this list
- * (SEC-7894-3). Five groups, in this order: the credential's own `me` and
+ * (SEC-7894-3). Six groups, in this order: the credential's own `me` and
  * #7877's three member reads; #8169's eight member reads; #8170's six member
  * writes (roadmap §7.2 row order); #8438's member consents read and write;
- * #8515's onboarding read and write — 24 in all.
+ * #8765's account-agreements read and write; #8515's onboarding read and
+ * write — 26 in all.
  * `GET /v1/consent/platform` is not admitted — it is the Admin owner's own
- * consent to Working Theory, on the hub's cookie session. The member profile write IS admitted — it
+ * consent to Working Theory, on the hub's cookie session. Nor is the
+ * anonymous `GET /v1/consent/sign-up` (#8765 D2): it takes no credential. The member profile write IS admitted — it
  * is the person's own account, which roadmap D9 saves through it. Not
  * admitted, deliberately: `GET /v1/waitlist-signups/me`,
  * `GET /v1/flow-checkouts/me`, `GET /v1/subscription/me` and
@@ -191,6 +194,10 @@ export const HUB_SESSION_ROUTES: readonly string[] = Object.freeze([
   // admitted: those are the Admin owner's, on the hub's own cookie session.
   "GET /v1/member/consents",
   "POST /v1/member/consents",
+  // #8765 D5 — the caller's account-level sign-up agreements, so a spoke's
+  // account layout reads and accepts the one grant every site shares.
+  "GET /v1/consent/account",
+  "POST /v1/consent/account",
   // #8515 D13 — the client's onboarding read and write.
   "GET /v1/member/onboarding",
   "POST /v1/member/onboarding",

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

@@ -758,7 +758,12 @@ export function buildOpenApiSpec(
             "lead's id with a 201; with anything different it is a 422. Keys are " +
             "scoped per workspace, are first-write-wins, and should be unguessable " +
             "(a UUID, a Stripe Checkout Session id). Without a database there is no " +
-            "stored lead to match, so the key has no effect.",
+            "stored lead to match, so the key has no effect. A contact lead — " +
+            "`source` `contact-form`, `conversational-intake` or `flow:contact` — " +
+            "must carry `consent: true` (the visitor accepted the site's terms), " +
+            "else it is a 400 `consent_required`; the server then records " +
+            "`payload.consent` (`statement`, `acceptedAt`) itself, replacing any the " +
+            "caller sent. Other sources do not read `consent`.",
           parameters: [
             {
               name: "Idempotency-Key",
@@ -789,10 +794,17 @@ export function buildOpenApiSpec(
             },
             "400": {
               description:
-                "Validation error — invalid request body, or a malformed Idempotency-Key",
+                "Validation error — invalid request body, or a malformed " +
+                "Idempotency-Key; or `consent_required`, a contact lead without " +
+                "`consent: true`",
               content: {
                 "application/json": {
-                  schema: { $ref: "#/components/schemas/InvalidInputResponse" },
+                  schema: {
+                    oneOf: [
+                      { $ref: "#/components/schemas/InvalidInputResponse" },
+                      { $ref: "#/components/schemas/ConsentRequiredResponse" },
+                    ],
+                  },
                 },
               },
             },
@@ -1472,6 +1484,13 @@ export function buildOpenApiSpec(
                 "Free-form caller-set channel tag (e.g. `agent`); no CR/LF",
             },
             email: { type: "string", format: "email", maxLength: 254 },
+            consent: {
+              type: "boolean",
+              description:
+                "`true` when the visitor accepted the site's terms. Required (as " +
+                "`true`) for a contact lead; read for no other source, and never " +
+                "stored as sent — the server records `payload.consent` instead.",
+            },
             payload: {
               type: "object",
               maxProperties: 64,
@@ -1575,6 +1594,14 @@ export function buildOpenApiSpec(
             message: { type: "string" },
           },
         },
+        ConsentRequiredResponse: {
+          type: "object",
+          required: ["error", "message"],
+          properties: {
+            error: { type: "string", enum: ["consent_required"] },
+            message: { type: "string" },
+          },
+        },
         PersistFailedResponse: {
           type: "object",
           required: ["error"],

package/templates/apps/api/src/routes/auth/__tests__/hub-sign-in.test.ts

@@ -35,6 +35,7 @@ import { authPreHandlerPlugin } from "../../../middleware/auth.js";
 import { __resetHubSignInBuckets } from "../../../services/hub-sign-in.js";
 import {
   hubSignInClientRoutes,
+  hubSignInPublicRoutes,
   hubSignInSessionRoutes,
 } from "../hub-sign-in.js";
 
@@ -56,6 +57,7 @@ function buildApp(): FastifyInstance {
     await authScope.register(hubSignInSessionRoutes);
   });
   server.register(hubSignInClientRoutes);
+  server.register(hubSignInPublicRoutes);
   return server;
 }
 
@@ -481,3 +483,50 @@ describe("GET /v1/hub-sign-in/me", () => {
     expect(wrongKey.statusCode).toBe(401);
   });
 });
+
+describe("GET /v1/hub-sign-in/clients/:clientId (#8790 D2)", () => {
+  const read = (clientId: string) =>
+    app.inject({
+      method: "GET",
+      url: `/v1/hub-sign-in/clients/${encodeURIComponent(clientId)}`,
+    });
+
+  it("answers a live client's name and origin, and nothing else", async () => {
+    const res = await read(spoke.spoke.id);
+    expect(res.statusCode).toBe(200);
+    expect(res.headers["cache-control"]).toBe("no-store");
+    expect(res.json()).toEqual({
+      ok: true,
+      data: {
+        clientId: spoke.spoke.id,
+        name: spoke.spoke.name,
+        origin: new URL(spoke.client.redirectUris[0]!).origin,
+      },
+    });
+  });
+
+  it("is a 404 for an unknown client id", async () => {
+    const res = await read("spoke_nope");
+    expect(res.statusCode).toBe(404);
+    expect(res.json()).toEqual({
+      ok: false,
+      error: { code: "not_found", message: "Not found" },
+    });
+  });
+
+  it("is the same 404 for a disabled client", async () => {
+    spoke.client.enabled = false;
+    const res = await read(spoke.spoke.id);
+    expect(res.statusCode).toBe(404);
+    expect(res.json()).toEqual({
+      ok: false,
+      error: { code: "not_found", message: "Not found" },
+    });
+  });
+
+  it("is the same 404 for a revoked spoke", async () => {
+    spoke.spoke.revokedAt = new Date();
+    const res = await read(spoke.spoke.id);
+    expect(res.statusCode).toBe(404);
+  });
+});

package/templates/apps/api/src/routes/auth/hub-sign-in.ts

@@ -35,11 +35,13 @@
  * `/v1/auth/tokens`; recorded in apps/api/CLAUDE.md).
  */
 import { logger } from "@working-theory/observability";
+import { findSignInClientInfo } from "../../lib/hub-sign-in-store.js";
 import {
   hubSignInCodeResponseSchema,
   hubSignInMeResponseSchema,
   hubSignInRevokeResponseSchema,
   hubSignInTokenResponseSchema,
+  hubSignInClientInfoResponseSchema,
 } from "@working-theory/validation";
 import type { FastifyPluginAsync, FastifyReply, FastifyRequest } from "fastify";
 import type { ZodType } from "zod";
@@ -159,6 +161,45 @@ export const hubSignInSessionRoutes: FastifyPluginAsync = async (fastify) => {
   });
 };
 
+/**
+ * `clients/:clientId` — public, no auth (#8790 D2). The hub's own sign-in page
+ * asks what it may say about the spoke that sent a visitor: the spoke's name
+ * and origin, from the registry. A missing, disabled, or revoked client is
+ * a 404 with the same body as an unknown one, so the route confirms nothing
+ * about ids that are not live. Registered in `server.ts`'s public block.
+ */
+export const hubSignInPublicRoutes: FastifyPluginAsync = async (fastify) => {
+  fastify.get<{ Params: { clientId: string } }>(
+    "/v1/hub-sign-in/clients/:clientId",
+    async (request, reply) => {
+      const { clientId } = request.params;
+      reply.header("Cache-Control", "no-store");
+      if (clientId.length === 0 || clientId.length > 128) {
+        return notFound(reply);
+      }
+      const info = await findSignInClientInfo(clientId);
+      if (info === null) return notFound(reply);
+      const parsed = hubSignInClientInfoResponseSchema.safeParse(info);
+      if (!parsed.success) {
+        logger.error(
+          {
+            route: "hub-sign-in/clients",
+            issues: parsed.error.issues.map((i) => i.path.join(".")),
+          },
+          "[hub-sign-in] response failed its own contract schema",
+        );
+        return error(
+          reply,
+          500,
+          "internal_error",
+          "Response failed contract validation",
+        );
+      }
+      return reply.status(200).send({ ok: true, data: parsed.data });
+    },
+  );
+};
+
 /** `token` and `revoke` — registered in their own rate-limited scope. */
 export const hubSignInClientRoutes: FastifyPluginAsync = async (fastify) => {
   fastify.post(