create-ailk 0.19.0 → 0.20.0

package/templates/apps/api/src/services/default-tenant.ts

@@ -74,6 +74,13 @@ export interface TenantContext {
    * `@working-theory/validation`'s `allows`.
    */
   grants?: readonly AgentGrantablePermission[];
+  /**
+   * Set ONLY by `agentTenant` (#8514 D4); a person's tenant never carries it.
+   * `@working-theory/validation`'s `roleAllows` / `allows` read it to withhold
+   * `AGENT_WITHHELD_PERMISSIONS` from an agent's role, and both tenant guards
+   * refuse an agent request whose tenant lacks it (fail closed).
+   */
+  agent?: true;
 }
 
 export type TenantErrorKind = "forbidden" | "not_found" | "conflict";
@@ -222,7 +229,9 @@ export async function resolveDefaultTenantForOperator(
  * An agent's tenant (#3591 D5, #7864): its person's tenant with the role
  * clamped to the agent's ceiling and, when any survive, the agent's grants
  * that its person's own role holds. `grants` is omitted when none survive,
- * so an agent with no effective grant is the same shape as before.
+ * so an agent with no effective grant is the same shape as before. It always
+ * carries `agent: true` (#8514 D4), which withholds the client-keeping rows a
+ * member holds by role.
  *
  * The one clamp both tenant guards apply — `resolveAgentTenant` (multi-tenant)
  * and `resolveDefaultTenantForAgent` (base build) — so the two builds cannot
@@ -238,8 +247,8 @@ export function agentTenant(
     (p) => agent.grants.includes(p) && can(personTenant.role, p),
   );
   return grants.length > 0
-    ? { ...personTenant, role, grants }
-    : { ...personTenant, role };
+    ? { ...personTenant, role, agent: true, grants }
+    : { ...personTenant, role, agent: true };
 }
 
 /**

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

@@ -114,7 +114,8 @@ function refuse<T = never>(
 // keyed on an identity the request has already proved (the user the cookie
 // session resolved to; the client that passed secret AND spoke key), so an
 // invented key never gets one (SEC-7894-8). The shape of `middleware/auth.ts`'s
-// per-agent limiter. SINGLE-REPLICA, like every limiter in this app.
+// per-agent limiter. SINGLE-REPLICA, like the in-process limiters in this
+// app (the per-IP middleware shares a database store, #5040).
 
 interface Bucket {
   windowStartMs: number;

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

@@ -48,8 +48,16 @@
  * throws, never refuses the lead and never changes `routeLead`'s result: an
  * unstorable address or a failed step writes the lead with `personId: null`
  * and logs one bare line (`person-skipped` / `person-failed`, never the
- * email). `subscribe` and `callback` create no Person; the `email`, `local`
- * and `none` deliveries never reach `persistToDb`.
+ * email). The `email`, `local` and `none` deliveries never reach
+ * `persistToDb`.
+ *
+ * CONTACT AND LINKS (#8435 D5). A `submit` may carry `options.contact` (the
+ * magnet's tagged answers): `findOrCreatePerson` fills the Person's BLANK
+ * contact fields from it while the Person is uncurated, and the lead's own
+ * `payload` is unchanged. A `subscribe` and a `callback` with a storable email
+ * (a callback's is `payload.email`) now also resolve a Person and stamp its id
+ * as `personId`; a callback with no email makes no Person call and writes no
+ * `personId`. Every one of these steps is best-effort exactly like the lead's.
  *
  * CHECKOUT PLAN (#7877 D10). A spoke's checkout fulfilment posts one
  * `submit` with the Checkout Session id as its `Idempotency-Key`. When that
@@ -72,6 +80,15 @@
  * an update; an unmarked create carries no `spokeCheckout` key at all and
  * relies on the column default. The plan rule above is unchanged: it still
  * runs after the write, from the same candidate.
+ *
+ * VISITOR LINK (#8438 D11). When the request carried a valid consent visitor
+ * id (`SourceMeta.consentVisitorId`, set by the leads and flows routes from
+ * `x-ailk-consent-visitor` only when it is a v4 UUID) and the submit resolved
+ * a Person, `linkConsentVisitor` joins the two — source `magnet` for a
+ * `flow:` source, else `api`. A link never fails a lead and is never
+ * returned: `RouteLeadResult.personId` is internal, for the flow engine's
+ * consent write. A subscribe or callback resolves no Person, so it links
+ * nothing. The header is never echoed and never logged.
  */
 
 import { randomUUID } from "node:crypto";
@@ -91,8 +108,15 @@ import { appendLeadRecord } from "../lib/lead-capture-store.js";
 import { acceptsKind, resolveLeadDelivery } from "../lib/lead-delivery.js";
 import { prisma } from "../lib/prisma.js";
 
+import { linkConsentVisitor } from "./consent.js";
 import { enrichLead } from "./enrichment-shim.js";
-import { findOrCreatePerson, setPersonPlanOffering } from "./person.js";
+import {
+  findOrCreatePerson,
+  normalizeCapturedContact,
+  normalizeTelephone,
+  setPersonPlanOffering,
+} from "./person.js";
+import type { LeadContact, PersonContact } from "./person.js";
 import { requestConfirmSupersedesNotification } from "./request-confirm.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
@@ -133,6 +157,12 @@ export type SourceMeta = {
    * never grant it.
    */
   relayed?: boolean;
+  /**
+   * The cookie banner's visitor id from the request's `x-ailk-consent-visitor`
+   * header, set only when it is a v4 UUID (#8438 D11). Used to link the
+   * visitor to the lead's Person; never persisted, echoed or logged.
+   */
+  consentVisitorId?: string;
 };
 
 /** Where the lead landed: a database row, the local file fallback, or the owner's inbox by email (#6730). */
@@ -142,6 +172,12 @@ export type Persisted = "db" | "file" | "email";
 export type RouteLeadOptions = {
   /** The caller's validated `Idempotency-Key`; honoured for `submit` only. */
   idempotencyKey?: string;
+  /**
+   * The contact the capture offers (#8435 D5) — the magnet's tagged answers —
+   * honoured for `submit` only and never persisted as such: the lead's
+   * `payload` stays the raw answers.
+   */
+  contact?: LeadContact;
 };
 
 export type RouteLeadResult =
@@ -154,6 +190,12 @@ export type RouteLeadResult =
        */
       replayed?: true;
       id: string;
+      /**
+       * The Person a `submit` resolved (#8438 D11), `null`/absent when none.
+       * Internal only — the route builds its 201 body from `id`, `persisted`
+       * and `email`, so this never reaches a wire.
+       */
+      personId?: string | null;
       persisted: Persisted;
       email:
         | { ok: true; messageId: string }
@@ -256,6 +298,8 @@ type PersistResult =
       source: "db";
       skipEmail: boolean;
       skipReason?: string;
+      /** The Person a `submit` resolved (#8438 D11). */
+      personId?: string | null;
     }
   // #7869 D5 — a keyed create lost a race to a row it now answers with.
   | { ok: "keyed"; outcome: KeyedOutcome }
@@ -267,25 +311,41 @@ type PersistResult =
  * must never refuse, lose or delay a lead. Logs the outcome kind and the
  * site only.
  */
-async function resolveLeadPersonId(input: SubmitInput): Promise<string | null> {
+async function resolveCapturePersonId(
+  siteId: string,
+  capture: { email: string; name?: string | null; contact?: Partial<PersonContact> },
+): Promise<string | null> {
   try {
-    const name = typeof input.payload["name"] === "string" ? input.payload["name"] : null;
-    const person = await findOrCreatePerson(input.siteId, { email: input.email, name });
+    const person = await findOrCreatePerson(siteId, capture);
     if (person.ok) return person.value.personId;
     if (person.error.kind === "invalid_email") {
       logger.warn(
-        { event: "person-skipped", kind: person.error.kind, siteId: input.siteId },
+        { event: "person-skipped", kind: person.error.kind, siteId },
         "lead person skipped",
       );
     } else {
-      logger.error({ event: "person-failed", siteId: input.siteId }, "lead person failed");
+      logger.error({ event: "person-failed", siteId }, "lead person failed");
     }
   } catch {
-    logger.error({ event: "person-failed", siteId: input.siteId }, "lead person failed");
+    logger.error({ event: "person-failed", siteId }, "lead person failed");
   }
   return null;
 }
 
+async function resolveLeadPersonId(input: SubmitInput, contact?: LeadContact): Promise<string | null> {
+  const payloadName = typeof input.payload["name"] === "string" ? input.payload["name"] : null;
+  if (contact === undefined) {
+    return resolveCapturePersonId(input.siteId, { email: input.email, name: payloadName });
+  }
+  // #8435 D5 — an explicit contact name wins over the payload's.
+  const name = typeof contact.name === "string" ? contact.name : payloadName;
+  return resolveCapturePersonId(input.siteId, {
+    email: input.email,
+    name,
+    contact: normalizeCapturedContact(contact),
+  });
+}
+
 /** A LIVE-mode Checkout Session id (#7877 D10, SEC-7877-C). */
 const LIVE_CHECKOUT_SESSION_KEY = /^cs_live_[A-Za-z0-9]{1,250}$/;
 const SITE_SLUG = /^[a-z0-9][a-z0-9-]{0,39}$/;
@@ -357,9 +417,10 @@ async function persistToDb(
   idempotencyKey?: string,
   viaSpoke = false,
   relayed = false,
+  contact?: LeadContact,
 ): Promise<PersistResult> {
   if (input.kind === "submit") {
-    const personId = await resolveLeadPersonId(input);
+    const personId = await resolveLeadPersonId(input, contact);
     // #8185 D2 — the plan rule's own predicate (pure: input, key, flag),
     // evaluated before the create so its result can be stored. A relayed
     // request is never a spoke's server call (D3).
@@ -413,10 +474,12 @@ async function persistToDb(
     if (candidate !== null && personId !== null) {
       await applyCheckoutPlan(input, personId, candidate);
     }
-    return { ok: true, id: row.id, source: "db", skipEmail: false };
+    return { ok: true, id: row.id, source: "db", skipEmail: false, personId };
   }
 
   if (input.kind === "subscribe") {
+    // #8435 D5 — the subscriber's Person; `null` when the step skips or fails.
+    const personId = await resolveCapturePersonId(input.siteId, { email: input.email });
     try {
       const row = (await prisma.subscriber.create({
         data: {
@@ -430,6 +493,7 @@ async function persistToDb(
           workspaceId: input.siteId,
           email: input.email,
           source: input.source,
+          personId,
         },
         select: { id: true },
       })) as DbRow;
@@ -467,6 +531,18 @@ async function persistToDb(
   }
 
   // kind === "callback"
+  // #8435 D5 — a callback with a string `payload.email` resolves a Person; one
+  // without makes no call and writes no `personId`.
+  const callbackEmail = input.payload["email"];
+  const telephone = normalizeTelephone(input.phone);
+  const callbackPersonId =
+    typeof callbackEmail === "string"
+      ? await resolveCapturePersonId(input.siteId, {
+          email: callbackEmail,
+          name: input.name,
+          contact: telephone === null ? {} : { telephone },
+        })
+      : undefined;
   const row = (await prisma.callback.create({
     data: {
       siteId: input.siteId,
@@ -480,6 +556,7 @@ async function persistToDb(
         preferredTime: input.preferredTime,
       }),
       payload: input.payload as Prisma.InputJsonValue,
+      ...(callbackPersonId !== undefined && { personId: callbackPersonId }),
     },
     select: { id: true },
   })) as DbRow;
@@ -750,6 +827,7 @@ export async function routeLead(
   let persisted: Persisted;
   let skipEmail = false;
   let skipReason: string | undefined;
+  let personId: string | null = null;
 
   try {
     const dbResult = await persistToDb(
@@ -757,6 +835,7 @@ export async function routeLead(
       idempotencyKey,
       sourceMeta.viaSpoke === true,
       sourceMeta.relayed === true,
+      input.kind === "submit" ? options.contact : undefined,
     );
     // #7869 D5 — a lost race answers like the lookup above: no capture
     // record, no notification.
@@ -772,6 +851,20 @@ export async function routeLead(
     persisted = "db";
     skipEmail = dbResult.skipEmail;
     skipReason = dbResult.skipReason;
+    personId = dbResult.personId ?? null;
+    // #8438 D11 — only after THIS request's own write (a keyed replay
+    // returned above), and only when a Person was resolved.
+    if (sourceMeta.consentVisitorId !== undefined && personId !== null) {
+      await linkConsentVisitor({
+        workspaceId: input.siteId,
+        visitorId: sourceMeta.consentVisitorId,
+        personId,
+        source:
+          input.kind === "submit" && input.source.startsWith("flow:")
+            ? "magnet"
+            : "api",
+      });
+    }
   } catch (dbErr) {
     // #6254 AC-11 (spec D6, SEC-02) — a constraint violation is OUR OWN
     // derivation producing a row Postgres itself refuses (an unresolved
@@ -891,5 +984,5 @@ export async function routeLead(
     emailResult = await sendEmail(input, id!, persisted!, sourceMeta.viaSpoke);
   }
 
-  return { ok: true, id: id!, persisted, email: emailResult };
+  return { ok: true, id: id!, personId, persisted, email: emailResult };
 }