create-ailk 0.23.0 → 0.24.0

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

@@ -71,10 +71,30 @@
  * direct caller can still send `consent: true`; the gate makes acceptance an
  * explicit, recorded assertion, not proof that a person read the terms.
  *
- * API↔MCP PARITY for `consent` (#8730): no guard entry, for the reason the
- * Idempotency-Key paragraph below gives — this route parses no validation
- * export, so it binds as `api-args-unbound`. `capture_lead` stamps `mcp`, a
- * source this check never reads, so the tool is unchanged.
+ * THE BODY GATE (#7171, #7172, #7173 — the operator's decision of
+ * 2026-10-19: the MCP tool adopts the API, arguments and results). Each of
+ * the three writes is its own registration, and each parses `request.body`
+ * with one exported `@working-theory/validation` schema —
+ * `leadSubmitBodySchema`, `leadSubscribeBodySchema`, `leadCallbackBodySchema`
+ * — answering `400 invalid_input` (the first issue's message) when the body
+ * is not admitted; `capture_lead`, `subscribe_newsletter` and
+ * `request_callback` take exactly those exports and return the 201 below
+ * unchanged, so the parity guard holds the three pairs as `twin`s. The
+ * schemas are plain objects, never `.strict()`: every body a site form sends
+ * today — `siteId` beside the fields, the StepFlow envelope with `email`
+ * inside `payload`, no `payload` at all — still passes, an unknown key is
+ * stripped from the parsed copy and never refused. The parsed value is a
+ * gate only: `captureLead` reads the RAW `request.body`, so what `routeLead`
+ * validates and persists is byte-identical to before (#5732 — the payload
+ * walk sees the object that is stored). The one new refusal beyond the
+ * schema's own is a malformed or `null` body, which threw before.
+ *
+ * API↔MCP PARITY for `consent` (#8730): `leadSubmitBodySchema` declares it
+ * as an optional boolean, so the guard sees the same argument on both sides.
+ * The REQUIREMENT — `true` on a consent-bearing source — is the handler's
+ * own check below, which the guard does not model; `capture_lead` sends the
+ * agent's own `source`, so an agent naming a consent source needs
+ * `consent: true` exactly as a form does.
  *
  * A MAGNET'S COMPLETION (#8757 D6). After a `flow:<slug>` submit is written
  * to the database, `services/magnet-completion.ts` reads that LIVE magnet's
@@ -87,9 +107,10 @@
  * `lead`, a draft or missing magnet, or a caller with nowhere to sign in
  * leaves the 201 as it was. A failed read or send never changes the 201,
  * and the completion read has a time budget (`MAGNET_COMPLETION_BUDGET_MS`).
- * `next` is reachable only through a `flow:` source: `capture_lead` posts
- * `source: "mcp"`, so the tool's arguments get the same answer as before and
- * no parity guard row changes (NFR5).
+ * `next` is reachable only through a `flow:` source, which the parity guard's
+ * own argument fixture for `capture_lead` never sends, so the guard's
+ * observation never carries it and `leadWriteResultSchema` does not declare
+ * it (NFR5).
  *
  * A CHECKOUT'S ACCOUNT LINK (#8757 D14). A checkout fulfilment's submit
  * (`source: "web"`, `payload.page: "checkout"`) carries the caller's account
@@ -101,20 +122,23 @@
  *
  * API↔MCP PARITY for the header (#7869 D9, roadmap §12 Q5): NO guard entry.
  * The guard binds a route's arguments to the validation export its handler
- * `.safeParse`s on `request.params|query|body`; the header check below is a
- * regex test, not such a parse, so this route still binds as
- * `api-args-unbound` and the `capture_lead` row is unchanged. The 201 body's
- * field set is unchanged too, and `capture_lead` sends no header. If the
- * guard ever models headers, this becomes an API-side `arg-only-in`.
+ * `.safeParse`s on `request.params|query|body` — here `leadSubmitBodySchema`
+ * — and models no header; the header check below is a regex test, not such a
+ * parse, so the key is outside the compared contract. The 201 body's field
+ * set is unchanged too, and `capture_lead` sends no header. If the guard
+ * ever models headers, this becomes an API-side `arg-only-in`.
  */
 
 import { track } from "@working-theory/analytics/server";
 import {
   CONTACT_FORM_TERMS_STATEMENT,
   isConsentLeadSource,
+  leadCallbackBodySchema,
+  leadSubmitBodySchema,
+  leadSubscribeBodySchema,
   type LeadSubmitNext,
 } from "@working-theory/validation";
-import type { FastifyPluginAsync } from "fastify";
+import type { FastifyPluginAsync, FastifyReply, FastifyRequest } from "fastify";
 
 import { acceptsKind, resolveLeadDelivery } from "../../lib/lead-delivery.js";
 import { currentSiteId, resolveSiteWorkspaceId } from "../../lib/site.js";
@@ -243,313 +267,355 @@ function isCheckoutSubmit(body: Record<string, unknown>): boolean {
   );
 }
 
-function makeLeadsRoute(kind: LeadKind): FastifyPluginAsync {
-  return async (fastify) => {
-    fastify.post(`/v1/leads/${kind}`, async (request, reply) => {
-      const body = request.body as Record<string, unknown>;
+/**
+ * The refusal a body the route's own export does not admit gets (#7171,
+ * #7172, #7173): the shape and the first-issue message `routeLead`'s
+ * `invalid_input` branch already answers. Logs nothing.
+ */
+function refuseBody(
+  reply: FastifyReply,
+  issues: readonly { message: string }[],
+) {
+  return reply.status(400).send({
+    error: "invalid_input",
+    message: issues[0]?.message ?? "invalid input",
+  });
+}
 
-      // #8730 D1, #9130 — a contact lead or a job application carries the
-      // visitor's terms acceptance, or it is refused before the tenant read
-      // and any write.
-      if (
-        kind === "submit" &&
-        isConsentLeadSource(body?.["source"]) &&
-        body?.["consent"] !== true
-      ) {
-        return reply.status(400).send(CONSENT_REQUIRED_BODY);
-      }
-      // request.ip became attacker-influenceable when trustProxy: true went
-      // instance-wide (server.ts, #4730/#4778) — leads/index.ts was never
-      // itself touched by that PR. Traced every consumer of this value
-      // (#5112, DEF-004): lead-routing.ts's structured log field and its
-      // opt-in (LEAD_CAPTURE_INCLUDE_IP) persisted metadata.ip both RECORD
-      // the value; neither branches routing, persistence, or dedup on it.
-      // The best-effort/record-only posture is judged sufficient — the same
-      // trade-off server.ts's own trustProxy comment already accepts. The
-      // private @working-theory/lead-routing package (not present in this
-      // repo, not inspectable) is the one consumer this trace could not
-      // complete; see docs/specs/5112-leads-ip-trace-spec.md §8.
-      const sourceMeta: SourceMeta = {
-        ip: request.ip,
-        userAgent: request.headers["user-agent"],
-        receivedAt: new Date().toISOString(),
-      };
+/**
+ * The shared capture, after a kind's own gates: tenant resolution, the
+ * idempotency key, `buildInput` over the RAW body, `routeLead`, the confirm
+ * link, `next`, `track` and the 201. Reads `request.body` itself — never the
+ * body export's parsed copy — so what `routeLead` validates and persists is
+ * the object the client sent (the #5732 property: `boundedLeadPayload` walks
+ * exactly what is persisted, an own `__proto__` key included, where a
+ * `z.record` copy would have dropped it).
+ */
+async function captureLead(
+  kind: LeadKind,
+  request: FastifyRequest,
+  reply: FastifyReply,
+) {
+  const body = request.body as Record<string, unknown>;
 
-      // #7532 D4 — a registered spoke resolves first, to its own workspace; a
-      // refused key never falls through to the alias below. A keyless lead
-      // whose hub-status read fails on a cold start proceeds as on a non-hub,
-      // so routeLead's outage fallback captures it (#7633 amendment).
-      const caller = await resolveCallerSite(request, {
-        keylessOnRegistryFailure: "anonymous",
+  // request.ip became attacker-influenceable when trustProxy: true went
+  // instance-wide (server.ts, #4730/#4778) — leads/index.ts was never
+  // itself touched by that PR. Traced every consumer of this value
+  // (#5112, DEF-004): lead-routing.ts's structured log field and its
+  // opt-in (LEAD_CAPTURE_INCLUDE_IP) persisted metadata.ip both RECORD
+  // the value; neither branches routing, persistence, or dedup on it.
+  // The best-effort/record-only posture is judged sufficient — the same
+  // trade-off server.ts's own trustProxy comment already accepts. The
+  // private @working-theory/lead-routing package (not present in this
+  // repo, not inspectable) is the one consumer this trace could not
+  // complete; see docs/specs/5112-leads-ip-trace-spec.md §8.
+  const sourceMeta: SourceMeta = {
+    ip: request.ip,
+    userAgent: request.headers["user-agent"],
+    receivedAt: new Date().toISOString(),
+  };
+
+  // #7532 D4 — a registered spoke resolves first, to its own workspace; a
+  // refused key never falls through to the alias below. A keyless lead
+  // whose hub-status read fails on a cold start proceeds as on a non-hub,
+  // so routeLead's outage fallback captures it (#7633 amendment).
+  const caller = await resolveCallerSite(request, {
+    keylessOnRegistryFailure: "anonymous",
+  });
+  if (caller.kind === "refused") {
+    return reply.status(503).send({
+      error: "tenant_unresolved",
+      message: "This site is not configured to accept submissions.",
+    });
+  }
+
+  // #6203 — resolve the tenant SERVER-SIDE before any write is
+  // attempted. Two branches, deliberately different:
+  //
+  //  - No DATABASE_URL: the zero-config OSS file-fallback deployment.
+  //    There is no `workspaces` table to resolve against (and
+  //    `assertSiteAliasResolves()` already skips its own boot check for
+  //    exactly this reason), so the "resolved" value here is the site
+  //    ALIAS itself (`currentSiteId()`) — the same value the file
+  //    fallback would have carried before this unit. Never a rejection:
+  //    that would break lead capture for every zero-config scaffold.
+  //  - DATABASE_URL set: resolve via `resolveSiteWorkspaceId()`, the
+  //    SAME alias -> workspace resolution `currentSiteId()` already
+  //    drives everywhere else in this app. `null` here is a genuine
+  //    misconfiguration `build()` already refuses to boot past
+  //    (`assertSiteAliasResolves()`) — reaching it at request time is
+  //    the residual case that startup check cannot catch (a workspace
+  //    deleted after boot, a transient read), and it fails closed the
+  //    same way: reject, never guess (spec AC-4).
+  let workspaceId: string;
+  if (caller.kind === "spoke") {
+    workspaceId = caller.workspaceId;
+    sourceMeta.viaSpoke = true;
+  } else if (!process.env.DATABASE_URL) {
+    workspaceId = currentSiteId();
+  } else {
+    const resolved = await resolveSiteWorkspaceId();
+    if (resolved === null) {
+      request.log.error(
+        { kind },
+        "lead capture: DATABASE_URL is set but the site alias resolves to no workspace",
+      );
+      return reply.status(503).send({
+        error: "tenant_unresolved",
+        message: "This site is not configured to accept submissions.",
       });
-      if (caller.kind === "refused") {
-        return reply.status(503).send({
-          error: "tenant_unresolved",
-          message: "This site is not configured to accept submissions.",
+    }
+    workspaceId = resolved;
+  }
+
+  // #7869 D1 — after the tenant gate, before any read or write. Node
+  // lower-cases header names, and joins a duplicated header with ", ",
+  // which the pattern refuses.
+  let idempotencyKey: string | undefined;
+  if (kind === "submit") {
+    const rawKey = request.headers["idempotency-key"];
+    if (rawKey !== undefined) {
+      if (
+        typeof rawKey !== "string" ||
+        !IDEMPOTENCY_KEY_PATTERN.test(rawKey)
+      ) {
+        return reply.status(400).send({
+          error: "invalid_input",
+          message:
+            "Idempotency-Key must be 16 to 255 visible ASCII characters.",
         });
       }
+      idempotencyKey = rawKey;
+    }
+  }
 
-      // #6203 — resolve the tenant SERVER-SIDE before any write is
-      // attempted. Two branches, deliberately different:
-      //
-      //  - No DATABASE_URL: the zero-config OSS file-fallback deployment.
-      //    There is no `workspaces` table to resolve against (and
-      //    `assertSiteAliasResolves()` already skips its own boot check for
-      //    exactly this reason), so the "resolved" value here is the site
-      //    ALIAS itself (`currentSiteId()`) — the same value the file
-      //    fallback would have carried before this unit. Never a rejection:
-      //    that would break lead capture for every zero-config scaffold.
-      //  - DATABASE_URL set: resolve via `resolveSiteWorkspaceId()`, the
-      //    SAME alias -> workspace resolution `currentSiteId()` already
-      //    drives everywhere else in this app. `null` here is a genuine
-      //    misconfiguration `build()` already refuses to boot past
-      //    (`assertSiteAliasResolves()`) — reaching it at request time is
-      //    the residual case that startup check cannot catch (a workspace
-      //    deleted after boot, a transient read), and it fails closed the
-      //    same way: reject, never guess (spec AC-4).
-      let workspaceId: string;
-      if (caller.kind === "spoke") {
-        workspaceId = caller.workspaceId;
-        sourceMeta.viaSpoke = true;
-      } else if (!process.env.DATABASE_URL) {
-        workspaceId = currentSiteId();
-      } else {
-        const resolved = await resolveSiteWorkspaceId();
-        if (resolved === null) {
-          request.log.error(
-            { kind },
-            "lead capture: DATABASE_URL is set but the site alias resolves to no workspace",
-          );
-          return reply.status(503).send({
-            error: "tenant_unresolved",
-            message: "This site is not configured to accept submissions.",
-          });
-        }
-        workspaceId = resolved;
-      }
+  // #8185 D3 — a spoke's same-origin relay marks every forwarded call.
+  // The mark can only remove the spoke-checkout marker, never grant it.
+  sourceMeta.relayed = request.headers["x-ailk-relayed"] !== undefined;
 
-      // #7869 D1 — after the tenant gate, before any read or write. Node
-      // lower-cases header names, and joins a duplicated header with ", ",
-      // which the pattern refuses.
-      let idempotencyKey: string | undefined;
-      if (kind === "submit") {
-        const rawKey = request.headers["idempotency-key"];
-        if (rawKey !== undefined) {
-          if (
-            typeof rawKey !== "string" ||
-            !IDEMPOTENCY_KEY_PATTERN.test(rawKey)
-          ) {
-            return reply.status(400).send({
-              error: "invalid_input",
-              message:
-                "Idempotency-Key must be 16 to 255 visible ASCII characters.",
-            });
-          }
-          idempotencyKey = rawKey;
-        }
-      }
+  // #8438 D11 — the cookie banner's visitor id, forwarded by the site's
+  // own server from its first-party cookie. Only a v4 UUID counts; the
+  // header is never echoed or logged. It links the visitor to the
+  // lead's Person after the write, and changes nothing about the answer.
+  const consentVisitorId = consentVisitorFromHeader(
+    request.headers[CONSENT_VISITOR_HEADER],
+  );
+  if (consentVisitorId !== undefined) {
+    sourceMeta.consentVisitorId = consentVisitorId;
+  }
 
-      // #8185 D3 — a spoke's same-origin relay marks every forwarded call.
-      // The mark can only remove the spoke-checkout marker, never grant it.
-      sourceMeta.relayed = request.headers["x-ailk-relayed"] !== undefined;
+  // #8757 D14 — where a buyer's account lives, for the purchase email.
+  let accountOrigin: string | undefined;
+  if (kind === "submit" && isCheckoutSubmit(body)) {
+    const target = await accountTargetFor(caller).catch(() => null);
+    accountOrigin = target?.origin;
+  }
+
+  const result = await routeLead(
+    buildInput(kind, body, workspaceId, sourceMeta.receivedAt),
+    sourceMeta,
+    {
+      ...(idempotencyKey !== undefined && { idempotencyKey }),
+      ...(accountOrigin !== undefined && { accountOrigin }),
+    },
+  );
 
-      // #8438 D11 — the cookie banner's visitor id, forwarded by the site's
-      // own server from its first-party cookie. Only a v4 UUID counts; the
-      // header is never echoed or logged. It links the visitor to the
-      // lead's Person after the write, and changes nothing about the answer.
-      const consentVisitorId = consentVisitorFromHeader(
-        request.headers[CONSENT_VISITOR_HEADER],
+  if (!result.ok) {
+    if (result.error.kind === "idempotency_conflict") {
+      // #7869 D6 — the operator's signal that a keyed lead was refused.
+      // Never the key, the email or the payload.
+      request.log.warn(
+        { kind, siteId: workspaceId, outcome: "idempotency_conflict" },
+        "lead idempotency_conflict",
       );
-      if (consentVisitorId !== undefined) {
-        sourceMeta.consentVisitorId = consentVisitorId;
-      }
+      return reply.status(422).send({
+        error: "idempotency_key_reused",
+        message: "This Idempotency-Key was used for a different lead.",
+      });
+    }
+    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: workspaceId, error: result.error.message },
+        "lead persist_failed",
+      );
+      return reply.status(503).send({ error: "persist_failed" });
+    }
+    if (result.error.kind === "delivery_failed") {
+      // Email was the delivery and the provider did not accept it —
+      // never reported as sent (#6730 D5). Detail stays server-side.
+      // `{ kind, siteId }` only (spec D5): provider error text can echo
+      // an address.
+      request.log.error({ kind, siteId: workspaceId }, "lead delivery_failed");
+      return reply.status(503).send({
+        error: "delivery_failed",
+        message: "The message could not be delivered.",
+      });
+    }
+    // config_missing — this deployment has nowhere to put this kind of
+    // lead (#6730 D1: production with neither a database nor the email
+    // vars, or a newsletter signup with no database).
+    return reply.status(503).send({
+      error: "lead_capture_not_configured",
+      message: "Lead capture is not configured.",
+    });
+  }
 
-      // #8757 D14 — where a buyer's account lives, for the purchase email.
-      let accountOrigin: string | undefined;
-      if (kind === "submit" && isCheckoutSubmit(body)) {
-        const target = await accountTargetFor(caller).catch(() => null);
-        accountOrigin = target?.origin;
-      }
+  // 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: workspaceId,
+      kind,
+      ip: sourceMeta.ip,
+      persisted: result.persisted,
+      emailKind,
+      replayed: result.replayed === true,
+    },
+    "lead routed",
+  );
 
-      const result = await routeLead(
-        buildInput(kind, body, workspaceId, sourceMeta.receivedAt),
-        sourceMeta,
-        {
-          ...(idempotencyKey !== undefined && { idempotencyKey }),
-          ...(accountOrigin !== undefined && { accountOrigin }),
-        },
-      );
+  // Request-and-confirm (#5970): mint the tenant's one-time confirm
+  // credential and email them the link. Fire-and-forget and `void`-
+  // returning, so the 201 below stays independent of both Resend and that
+  // write — the request is already persisted by this point, and a send
+  // that fails must never turn a captured lead into an error.
+  //
+  // Callback only: `submit` and `subscribe` have no confirm step. The
+  // service itself no-ops (with a logged reason) when the feature is not
+  // configured, which is the default.
+  // `result.persisted === "db"` for the same reason `lead-routing.ts`
+  // consults it (#5970 security review round 3, M1): the credential is
+  // minted by an update on the `callbacks` row, so a FILE-FALLBACK id
+  // would match nothing and the operator would be left with no email at
+  // all. On that path the generic notification is sent instead, which is
+  // what keeps "exactly one" true in both directions.
+  // A spoke's callback never takes this path (#7532 D4, SEC-7532-2): the
+  // link is minted on the deployment's one Stripe account.
+  if (
+    kind === "callback" &&
+    result.persisted === "db" &&
+    caller.kind !== "spoke"
+  ) {
+    const callbackInput = buildInput(
+      kind,
+      body,
+      workspaceId,
+      sourceMeta.receivedAt,
+    ) as Extract<RouteLeadInput, { kind: "callback" }>;
+    sendRequestConfirmLink(result.id, {
+      name: callbackInput.name,
+      phone: callbackInput.phone,
+      ...(callbackInput.preferredTime !== undefined && {
+        preferredTime: callbackInput.preferredTime,
+      }),
+    });
+  }
 
-      if (!result.ok) {
-        if (result.error.kind === "idempotency_conflict") {
-          // #7869 D6 — the operator's signal that a keyed lead was refused.
-          // Never the key, the email or the payload.
-          request.log.warn(
-            { kind, siteId: workspaceId, outcome: "idempotency_conflict" },
-            "lead idempotency_conflict",
-          );
-          return reply.status(422).send({
-            error: "idempotency_key_reused",
-            message: "This Idempotency-Key was used for a different lead.",
-          });
-        }
-        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: workspaceId, error: result.error.message },
-            "lead persist_failed",
-          );
-          return reply.status(503).send({ error: "persist_failed" });
-        }
-        if (result.error.kind === "delivery_failed") {
-          // Email was the delivery and the provider did not accept it —
-          // never reported as sent (#6730 D5). Detail stays server-side.
-          // `{ kind, siteId }` only (spec D5): provider error text can echo
-          // an address.
-          request.log.error({ kind, siteId: workspaceId }, "lead delivery_failed");
-          return reply.status(503).send({
-            error: "delivery_failed",
-            message: "The message could not be delivered.",
+  // #8757 D6 — a written `flow:<slug>` submit answers its magnet's
+  // completion. A read that fails, or outlasts its budget, leaves the 201
+  // as it was: the lead is saved.
+  let next: LeadSubmitNext | undefined;
+  const source = body["source"];
+  if (
+    kind === "submit" &&
+    result.persisted === "db" &&
+    typeof source === "string" &&
+    source.startsWith("flow:")
+  ) {
+    const slug = source.slice("flow:".length);
+    try {
+      const completion = await magnetCompletionWithinBudget(workspaceId, slug, () =>
+        accountTargetFor(caller),
+      );
+      if (completion !== null) {
+        next = completion.next;
+        if (completion.next.completion === "invite" && !result.replayed) {
+          const submitInput = buildInput(
+            kind,
+            body,
+            workspaceId,
+            sourceMeta.receivedAt,
+          ) as Extract<RouteLeadInput, { kind: "submit" }>;
+          const locale = submitInput.payload["locale"];
+          void sendInviteConfirmation({
+            workspaceId,
+            slug,
+            email: submitInput.email,
+            locale: typeof locale === "string" ? locale : undefined,
+            completion,
+            now: new Date(),
           });
         }
-        // config_missing — this deployment has nowhere to put this kind of
-        // lead (#6730 D1: production with neither a database nor the email
-        // vars, or a newsletter signup with no database).
-        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: workspaceId,
-          kind,
-          ip: sourceMeta.ip,
-          persisted: result.persisted,
-          emailKind,
-          replayed: result.replayed === true,
-        },
-        "lead routed",
+    } catch (error) {
+      request.log.error(
+        { event: "magnet-completion", error: error instanceof Error ? error.name : "unknown" },
+        "lead magnet completion read failed",
       );
+    }
+  }
 
-      // Request-and-confirm (#5970): mint the tenant's one-time confirm
-      // credential and email them the link. Fire-and-forget and `void`-
-      // returning, so the 201 below stays independent of both Resend and that
-      // write — the request is already persisted by this point, and a send
-      // that fails must never turn a captured lead into an error.
-      //
-      // Callback only: `submit` and `subscribe` have no confirm step. The
-      // service itself no-ops (with a logged reason) when the feature is not
-      // configured, which is the default.
-      // `result.persisted === "db"` for the same reason `lead-routing.ts`
-      // consults it (#5970 security review round 3, M1): the credential is
-      // minted by an update on the `callbacks` row, so a FILE-FALLBACK id
-      // would match nothing and the operator would be left with no email at
-      // all. On that path the generic notification is sent instead, which is
-      // what keeps "exactly one" true in both directions.
-      // A spoke's callback never takes this path (#7532 D4, SEC-7532-2): the
-      // link is minted on the deployment's one Stripe account.
-      if (
-        kind === "callback" &&
-        result.persisted === "db" &&
-        caller.kind !== "spoke"
-      ) {
-        const callbackInput = buildInput(
-          kind,
-          body,
-          workspaceId,
-          sourceMeta.receivedAt,
-        ) as Extract<RouteLeadInput, { kind: "callback" }>;
-        sendRequestConfirmLink(result.id, {
-          name: callbackInput.name,
-          phone: callbackInput.phone,
-          ...(callbackInput.preferredTime !== undefined && {
-            preferredTime: callbackInput.preferredTime,
-          }),
-        });
-      }
+  // Fire-and-forget: track() never throws; no need to hold the response.
+  // #7869 D6 — a replay records nothing new: the first write counted it.
+  if (!result.replayed) {
+    void track("lead-captured", {
+      source: body["source"] as string | undefined,
+      locale: (body["payload"] as Record<string, unknown> | undefined)?.[
+        "locale"
+      ] as string | undefined,
+    });
+  }
 
-      // #8757 D6 — a written `flow:<slug>` submit answers its magnet's
-      // completion. A read that fails, or outlasts its budget, leaves the 201
-      // as it was: the lead is saved.
-      let next: LeadSubmitNext | undefined;
-      const source = body["source"];
-      if (
-        kind === "submit" &&
-        result.persisted === "db" &&
-        typeof source === "string" &&
-        source.startsWith("flow:")
-      ) {
-        const slug = source.slice("flow:".length);
-        try {
-          const completion = await magnetCompletionWithinBudget(workspaceId, slug, () =>
-            accountTargetFor(caller),
-          );
-          if (completion !== null) {
-            next = completion.next;
-            if (completion.next.completion === "invite" && !result.replayed) {
-              const submitInput = buildInput(
-                kind,
-                body,
-                workspaceId,
-                sourceMeta.receivedAt,
-              ) as Extract<RouteLeadInput, { kind: "submit" }>;
-              const locale = submitInput.payload["locale"];
-              void sendInviteConfirmation({
-                workspaceId,
-                slug,
-                email: submitInput.email,
-                locale: typeof locale === "string" ? locale : undefined,
-                completion,
-                now: new Date(),
-              });
-            }
-          }
-        } catch (error) {
-          request.log.error(
-            { event: "magnet-completion", error: error instanceof Error ? error.name : "unknown" },
-            "lead magnet completion read failed",
-          );
-        }
-      }
+  return reply.status(201).send({
+    id: result.id,
+    persisted: result.persisted,
+    email: result.email,
+    ...(next === undefined ? {} : { next }),
+  });
+}
 
-      // Fire-and-forget: track() never throws; no need to hold the response.
-      // #7869 D6 — a replay records nothing new: the first write counted it.
-      if (!result.replayed) {
-        void track("lead-captured", {
-          source: body["source"] as string | undefined,
-          locale: (body["payload"] as Record<string, unknown> | undefined)?.[
-            "locale"
-          ] as string | undefined,
-        });
-      }
+export const leadSubmitRoute: FastifyPluginAsync = async (fastify) => {
+  fastify.post("/v1/leads/submit", async (request, reply) => {
+    const body = request.body as Record<string, unknown>;
 
-      return reply.status(201).send({
-        id: result.id,
-        persisted: result.persisted,
-        email: result.email,
-        ...(next === undefined ? {} : { next }),
-      });
-    });
-  };
-}
+    // #8730 D1, #9130 — a contact lead or a job application carries the
+    // visitor's terms acceptance, or it is refused before the body gate, the
+    // tenant read and any write.
+    if (isConsentLeadSource(body?.["source"]) && body?.["consent"] !== true) {
+      return reply.status(400).send(CONSENT_REQUIRED_BODY);
+    }
+    const parsed = leadSubmitBodySchema.safeParse(request.body);
+    if (!parsed.success) return refuseBody(reply, parsed.error.issues);
+    return captureLead("submit", request, reply);
+  });
+};
 
-export const leadSubmitRoute = makeLeadsRoute("submit");
-export const leadSubscribeRoute = makeLeadsRoute("subscribe");
-export const leadCallbackRoute = makeLeadsRoute("callback");
+export const leadSubscribeRoute: FastifyPluginAsync = async (fastify) => {
+  fastify.post("/v1/leads/subscribe", async (request, reply) => {
+    const parsed = leadSubscribeBodySchema.safeParse(request.body);
+    if (!parsed.success) return refuseBody(reply, parsed.error.issues);
+    return captureLead("subscribe", request, reply);
+  });
+};
+
+export const leadCallbackRoute: FastifyPluginAsync = async (fastify) => {
+  fastify.post("/v1/leads/callback", async (request, reply) => {
+    const parsed = leadCallbackBodySchema.safeParse(request.body);
+    if (!parsed.success) return refuseBody(reply, parsed.error.issues);
+    return captureLead("callback", request, reply);
+  });
+};
 
 /**
  * `GET /v1/leads/capture` (#6730 D4) — two booleans and nothing else: never