create-ailk 0.21.0 → 0.23.0

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

@@ -57,6 +57,48 @@
  * file leaves nothing to find, and its retry writes again. `subscribe` and
  * `callback` never read the header. The key is never logged or echoed.
  *
+ * CONTACT TERMS ACCEPTANCE (#8730). A `submit` whose `source` is a
+ * consent-bearing source (`isConsentLeadSource` in @working-theory/validation:
+ * the contact sources `contact-form`, `conversational-intake`, `flow:contact`,
+ * and since #9130 the Free apply page's `flow:job-application`) must carry a
+ * top-level `consent: true` — the boolean, nothing else — or it is
+ * `400 consent_required` before the tenant read or any write. An accepted one
+ * gets `payload.consent = { statement, acceptedAt }` written HERE, replacing
+ * any `payload.consent` the client sent: `statement` is the platform's
+ * contact terms statement (`CONTACT_FORM_TERMS_STATEMENT`) and `acceptedAt`
+ * this request's receive time. The `consent` flag itself is never stored. A
+ * lead with any other source, `subscribe` and `callback` are unchanged. A
+ * 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.
+ *
+ * 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
+ * completion setting. On `invite` the 201 gains `next: { completion:
+ * "invite" }` and — on a first write, never a replay — the submitter is sent
+ * one confirmation email whose link starts sign-in with their address
+ * prefilled (capped per recipient and per magnet, counted in the database);
+ * on `checkout`, re-checked against the `commerce` claim and the published
+ * offerings, it gains `next: { completion: "checkout", checkoutOffering }`.
+ * `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).
+ *
+ * A CHECKOUT'S ACCOUNT LINK (#8757 D14). A checkout fulfilment's submit
+ * (`source: "web"`, `payload.page: "checkout"`) carries the caller's account
+ * origin into `routeLead` as `accountOrigin`, resolved exactly as the invite
+ * link's (`accountTargetFor`): the spoke's enabled sign-in client's callback
+ * origin, or `FRONTEND_URL`'s on a keyless build with an account area. With
+ * none, or a failed read, it is left out and the buyer's purchase email goes
+ * without the link. No other submit makes this read, and the 201 is unchanged.
+ *
  * 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
@@ -67,6 +109,11 @@
  */
 
 import { track } from "@working-theory/analytics/server";
+import {
+  CONTACT_FORM_TERMS_STATEMENT,
+  isConsentLeadSource,
+  type LeadSubmitNext,
+} from "@working-theory/validation";
 import type { FastifyPluginAsync } from "fastify";
 
 import { acceptsKind, resolveLeadDelivery } from "../../lib/lead-delivery.js";
@@ -81,6 +128,11 @@ import {
   routeLead,
   type SourceMeta,
 } from "../../services/lead-routing.js";
+import {
+  accountTargetFor,
+  magnetCompletionWithinBudget,
+  sendInviteConfirmation,
+} from "../../services/magnet-completion.js";
 import { resolveCallerSite } from "../../services/public-site-resolver.js";
 import { sendRequestConfirmLink } from "../../services/request-confirm.js";
 
@@ -105,6 +157,29 @@ function liftString(
   return (typeof fromPayload === "string" ? fromPayload : topLevel) as string;
 }
 
+/** #8730, #9130 — the refusal a consent-bearing lead without terms acceptance gets. */
+const CONSENT_REQUIRED_BODY = {
+  error: "consent_required",
+  message: "Accept the terms to send this form.",
+} as const;
+
+/**
+ * #8730 D3, #9130 — the accepted terms, recorded by the server on a
+ * consent-bearing lead's payload, replacing any `consent` the client wrote
+ * there. Only a plain object payload is stamped: anything else is left for
+ * `routeLead`'s schema to refuse, never spread into an object that would then
+ * pass it.
+ */
+function withConsentRecord(payload: unknown, acceptedAt: string): unknown {
+  if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+    return payload;
+  }
+  return {
+    ...(payload as Record<string, unknown>),
+    consent: { statement: CONTACT_FORM_TERMS_STATEMENT, acceptedAt },
+  };
+}
+
 /**
  * Build a typed RouteLeadInput from the raw request body for a given kind.
  * Explicit destructure per kind prevents unknown fields (e.g. attacker-supplied
@@ -122,6 +197,7 @@ function buildInput(
   kind: LeadKind,
   body: Record<string, unknown>,
   workspaceId: string,
+  receivedAt: string,
 ): RouteLeadInput {
   const payload = (body["payload"] ?? {}) as Record<string, unknown>;
 
@@ -131,7 +207,9 @@ function buildInput(
       siteId: workspaceId,
       source: body["source"] as string,
       email: liftString(body, payload, "email"),
-      payload,
+      payload: isConsentLeadSource(body["source"])
+        ? (withConsentRecord(payload, receivedAt) as Record<string, unknown>)
+        : payload,
     };
   }
   if (kind === "subscribe") {
@@ -154,10 +232,32 @@ function buildInput(
   };
 }
 
+/** A spoke checkout fulfilment's submit (#8757 D14): `source: "web"`, `payload.page: "checkout"`. */
+function isCheckoutSubmit(body: Record<string, unknown>): boolean {
+  const payload = body["payload"];
+  return (
+    body["source"] === "web" &&
+    typeof payload === "object" &&
+    payload !== null &&
+    (payload as Record<string, unknown>)["page"] === "checkout"
+  );
+}
+
 function makeLeadsRoute(kind: LeadKind): FastifyPluginAsync {
   return async (fastify) => {
     fastify.post(`/v1/leads/${kind}`, async (request, reply) => {
       const body = request.body as Record<string, unknown>;
+
+      // #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
@@ -264,10 +364,20 @@ function makeLeadsRoute(kind: LeadKind): FastifyPluginAsync {
         sourceMeta.consentVisitorId = consentVisitorId;
       }
 
+      // #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),
+        buildInput(kind, body, workspaceId, sourceMeta.receivedAt),
         sourceMeta,
-        idempotencyKey === undefined ? {} : { idempotencyKey },
+        {
+          ...(idempotencyKey !== undefined && { idempotencyKey }),
+          ...(accountOrigin !== undefined && { accountOrigin }),
+        },
       );
 
       if (!result.ok) {
@@ -357,10 +467,12 @@ function makeLeadsRoute(kind: LeadKind): FastifyPluginAsync {
         result.persisted === "db" &&
         caller.kind !== "spoke"
       ) {
-        const callbackInput = buildInput(kind, body, workspaceId) as Extract<
-          RouteLeadInput,
-          { kind: "callback" }
-        >;
+        const callbackInput = buildInput(
+          kind,
+          body,
+          workspaceId,
+          sourceMeta.receivedAt,
+        ) as Extract<RouteLeadInput, { kind: "callback" }>;
         sendRequestConfirmLink(result.id, {
           name: callbackInput.name,
           phone: callbackInput.phone,
@@ -370,6 +482,50 @@ function makeLeadsRoute(kind: LeadKind): FastifyPluginAsync {
         });
       }
 
+      // #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",
+          );
+        }
+      }
+
       // 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) {
@@ -385,6 +541,7 @@ function makeLeadsRoute(kind: LeadKind): FastifyPluginAsync {
         id: result.id,
         persisted: result.persisted,
         email: result.email,
+        ...(next === undefined ? {} : { next }),
       });
     });
   };

package/templates/apps/api/src/routes/webhooks/README.md

@@ -199,6 +199,72 @@ through `metadata.site`.
   site, which silences the hub's dunning record for that subscription — the
   same key can already cancel or re-price it outright.
 
+## Per-Organization endpoint (#8932)
+
+`POST /v1/webhooks/stripe/:connectionToken` (`stripe-offerings.ts`) is the
+receiver for one Organization's own Stripe connection — the Offerings money
+path (spec `docs/specs/8932-the-per-organization-stripe-webhook-spec.md`,
+contract `docs/specs/8879-the-offerings-security-contract-key-spec.md` W1,
+W3–W11, G5, T8). The 43-character token selects one `StripeConnection` row
+(`findStripeConnectionByWebhookToken`, #8907); that row's decrypted secret
+verifies the signature through `verifyWebhookSignatureKeyless` (no env key),
+and its `organizationId` is the only Organization the event can act for.
+Registered beside the legacy route on every build, with its own 100/min
+per-IP bucket; the commerce claim is read at call time.
+
+**The ladder** — the first step that answers ends the request; every `200`
+body is `{ received: true }` and the outcome is the log line's only:
+
+| #    | Step                                                                                                                                                                                                                | Answer                                                                                     | Seen     |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | -------- |
+| 1    | the token resolves to no row (or is malformed)                                                                                                                                                                      | `404 not-found`, logs nothing                                                              | no       |
+| 1a   | the token lookup rejects                                                                                                                                                                                            | `503 webhook-unavailable`                                                                  | no       |
+| 2    | the row has no usable secret                                                                                                                                                                                        | `503 webhook-not-configured`                                                               | no       |
+| 3–6  | signature settled, then the claim (as the legacy route): `undetermined` → `503` + `Retry-After: 300`; `unclaimed` → signed `200 dropped_no_commerce_claim`, unsigned the module-disabled `404`; then the held `400` | as stated                                                                                  | no       |
+| 7    | `event.livemode` is not the row's mode                                                                                                                                                                              | `200 livemode_mismatch`                                                                    | no       |
+| 8    | not `checkout.session.completed` / `.async_payment_succeeded` on a session object                                                                                                                                   | `200 ignored_type`                                                                         | no       |
+| 9–11 | the hub's session record (#8930): rejects / unreadable / none                                                                                                                                                       | `503 record-unavailable` / `500 record-unreadable` / `200 unrecorded`                      | no       |
+| 12   | another Organization's record, or `metadata.site` is not the record's workspace                                                                                                                                     | `200 foreign_organization`                                                                 | no       |
+| 13   | the record's mode is not the row's                                                                                                                                                                                  | `200 livemode_mismatch`                                                                    | no       |
+| 14   | already seen for this Organization                                                                                                                                                                                  | `200 duplicate`                                                                            | —        |
+| 15   | a `completed` session neither `paid` nor `no_payment_required`                                                                                                                                                      | `200 unpaid`                                                                               | yes      |
+| 16   | the connection's client or its `listLineItems` call fails                                                                                                                                                           | `503 stripe-unavailable` (never the env key)                                               | no       |
+| 17   | not exactly one line item whose Price id is the record's                                                                                                                                                            | `200 offering_mismatch`                                                                    | yes      |
+| 18   | `routeLead` (below)                                                                                                                                                                                                 | `200 fulfilled` / `already_fulfilled` / `unfulfillable`, else `503 fulfilment-unavailable` | yes / no |
+
+**The lead.** One per session: `routeLead` with the idempotency key
+`"stripe-offerings " + sessionId` — a space, which no `Idempotency-Key`
+header can carry, so no anonymous lead can take the key first — and
+`offeringsCheckout: true`. Its offering is the record's FULL lookup key,
+never `metadata.ailk_offering`. A live session's lead is marked
+`spokeCheckout`, the hold #8793's `releaseHeldCheckoutPlan` releases at the
+buyer's verified first link; no path here writes `Person.planOffering`. A
+test-mode session's lead is written unmarked: no hold, purchase message,
+email or consent grant. A replay or a conflict on that key is
+`already_fulfilled`; a lead the database did not take is a `503`, so Stripe
+retries.
+
+**The legacy endpoint steps aside (W8).** `POST /v1/webhooks/stripe` acks
+any event carrying an `ailk_offering` key — in a session's metadata or any
+site-stamp source above — with `200 { received: true }` and
+`outcome: "offerings_path"`, **before** `markSeen`, and writes nothing.
+Every event without the key takes the legacy path unchanged.
+
+**Two dedup stores.** The legacy route keeps `hasSeen` / `markSeen`; the
+per-Organization route uses its own `hasSeenForOrganization` /
+`markSeenForOrganization`, keyed `<organizationId>:<eventId>`. Neither
+endpoint's store can swallow the other's event. Both are in-memory per
+instance; the per-Organization route's correctness rests on the lead's
+database key.
+
+**Logs.** Each line carries `organizationId`, `eventType`, an 8-character
+`eventIdPrefix` and `outcome` (fewer before an event is verified) — never
+the token, the secret, a full Stripe id, an email, a lookup key, a metadata
+value or Stripe product text. Request and error lines log the path with
+the token replaced whole by `:connectionToken` (`redactLogPath`).
+
+**W11.** No billing identity is bound from a connection's event.
+
 ## Dunning (#6034)
 
 Two arms record a per-subscriber lifecycle state so a failed renewal is no