create-ailk 0.20.0 → 0.22.0

package/templates/apps/api/src/routes/webhooks/stripe.ts

@@ -96,6 +96,16 @@
  *   `stripeSessionId`), with `session.customer` as the customer id only on a
  *   live-mode event. Logs an outcome kind only; never fails the 200.
  *
+ * Checkout terms grant (checkout.session.completed, #8765 D14):
+ *   Chained after the Person step, `recordCheckoutTermsGrant` records the
+ *   buyer's acceptance of the session's terms box as one `checkout` row of
+ *   the consent ledger — only for a session whose `consent.terms_of_service`
+ *   is `accepted` and whose server-written `metadata.ailk_terms` names
+ *   `account_terms` at its current version (a Payment Link, invoice or older
+ *   session carries none), for the Person `checkoutBuyerPerson` resolves.
+ *   Logs `{ event: "checkout-consent", outcome, eventIdPrefix }` only; never
+ *   fails the 200.
+ *
  * Dunning (invoice.payment_failed / customer.subscription.updated, #6034):
  *   Records a per-subscriber lifecycle state in a `UserData` row behind a
  *   reserved-key guard (routes/auth/user.ts). `invoice.payment_failed` arms
@@ -108,6 +118,11 @@
 import { track } from "@working-theory/analytics/server";
 import type { Prisma } from "@working-theory/database";
 import { isId } from "@working-theory/ids";
+import {
+  ACCOUNT_TERMS_PURPOSE_ID,
+  consentPurposeById,
+  SITE_CONSENT_CONFIG_DEFAULTS,
+} from "@working-theory/validation";
 import type { FastifyReply, FastifyRequest } from "fastify";
 
 import { config } from "../../config/index.js";
@@ -133,6 +148,8 @@ import {
 } from "../../lib/stripe.js";
 import { hasSeen, markSeen } from "../../lib/webhook-idempotency.js";
 import { recordWorkspaceAuditAction } from "../../services/audit-log.js";
+import { checkoutBuyerPerson } from "../../services/checkout-buyer.js";
+import { recordCheckoutConsent } from "../../services/consent.js";
 import { isUniqueViolation } from "../../services/default-tenant.js";
 import {
   DUNNING_MAX_SUBSCRIPTIONS,
@@ -142,8 +159,8 @@ import {
   type DunningRecord,
 } from "../../services/dunning-policy.js";
 import {
-  recordCheckoutPerson,
-  type CheckoutPersonOutcome,
+  resolveCheckoutPerson,
+  type CheckoutPersonResult,
 } from "../../services/person.js";
 
 const TELEMETRY_TIMEOUT_MS = 2000;
@@ -429,13 +446,24 @@ export const stripeWebhookHandler = async (
           session,
           eventIdPrefix,
           outcome: "completed",
-        }).then(() =>
-          recordFlowCheckoutPerson(request, {
-            session,
-            livemode: event.livemode === true,
-            eventIdPrefix,
-          }),
-        ),
+        })
+          .then(() =>
+            recordFlowCheckoutPerson(request, {
+              session,
+              livemode: event.livemode === true,
+              eventIdPrefix,
+            }),
+          )
+          // #8765 D14 — after the Person step, whose Person is a flow
+          // checkout's grant subject.
+          .then((flowPerson) =>
+            recordCheckoutTermsGrant(request, {
+              session,
+              livemode: event.livemode === true,
+              eventIdPrefix,
+              flowPerson,
+            }),
+          ),
         stampRequestPaid(request, { session, eventIdPrefix }),
         stampProposalPaid(request, { session, eventId: event.id, eventIdPrefix }),
       ]);
@@ -531,6 +559,8 @@ type CheckoutSessionObject = {
   currency?: string | null;
   customer?: string | null;
   customer_details?: { email?: string | null } | null;
+  /** The terms box's answer (#8765 D14): `accepted` when the buyer ticked it. */
+  consent?: { terms_of_service?: string | null } | null;
   metadata?: Record<string, string> | null;
 };
 
@@ -750,7 +780,7 @@ async function stampFlowCheckout(
 /**
  * The hub checkout's Person (#852 D6): after `stampFlowCheckout`, find or
  * create the Person of the completed checkout's lead
- * (`services/person.ts`'s `recordCheckoutPerson`). Runs only for a paid (or
+ * (`services/person.ts`'s `resolveCheckoutPerson`). Runs only for a paid (or
  * nothing-due) session of THIS site — the foreign-site filter has already
  * returned — that carries `metadata.flowCheckoutId`. The customer id's ONE
  * source is `session.customer`, written onto the Person only for a
@@ -758,7 +788,8 @@ async function stampFlowCheckout(
  * delivery whose Person step failed is repaired by the next one.
  *
  * Logs `{ eventIdPrefix, flowCheckoutIdPrefix, outcome }` only — never the
- * email or the customer id. Never throws: the response stays 200.
+ * email or the customer id. Answers the Person, or `null` when the step did
+ * not run or found none (#8765 D14). Never throws: the response stays 200.
  */
 async function recordFlowCheckoutPerson(
   request: FastifyRequest,
@@ -771,33 +802,137 @@ async function recordFlowCheckoutPerson(
     livemode: boolean;
     eventIdPrefix: string;
   },
-): Promise<void> {
+): Promise<CheckoutPersonResult["person"]> {
   const flowCheckoutId = session.metadata?.["flowCheckoutId"];
-  if (!flowCheckoutId) return;
+  if (!flowCheckoutId) return null;
   if (
     session.payment_status !== "paid" &&
     session.payment_status !== "no_payment_required"
   ) {
-    return;
+    return null;
   }
   const flowCheckoutIdPrefix = flowCheckoutId.substring(0, 8);
-  let outcome: CheckoutPersonOutcome;
+  let result: CheckoutPersonResult;
   try {
-    outcome = await recordCheckoutPerson({
+    result = await resolveCheckoutPerson({
       flowCheckoutId,
       stripeSessionId: session.id,
       customer: session.customer,
       livemode,
     });
   } catch {
-    outcome = "person_failed";
+    result = { outcome: "person_failed", person: null };
   }
-  const line = { eventIdPrefix, flowCheckoutIdPrefix, outcome };
-  if (outcome === "person_failed") {
+  const line = { eventIdPrefix, flowCheckoutIdPrefix, outcome: result.outcome };
+  if (result.outcome === "person_failed") {
     request.log.error(line, "flow checkout person failed — continuing");
   } else {
     request.log.info(line, "flow checkout person");
   }
+  return result.person;
+}
+
+/** The metadata key the Checkout creators stamp with the terms the box showed (#8765 D12). */
+const TERMS_STAMP_KEY = "ailk_terms";
+
+/**
+ * `<purposeId>@<policyVersion>` of the account terms as the registry reads
+ * them now — the only stamp a grant is recorded for (SEC-8765-E) — and that
+ * version, which `recordCheckoutConsent` checks against the site's registry.
+ * Derived, never written down, so a version bump retires every older stamp.
+ */
+function currentTermsStamp(): { stamp: string; policyVersion: number } | null {
+  const purpose = consentPurposeById(
+    SITE_CONSENT_CONFIG_DEFAULTS,
+    ACCOUNT_TERMS_PURPOSE_ID,
+  );
+  return purpose
+    ? {
+        stamp: `${purpose.id}@${purpose.policyVersion}`,
+        policyVersion: purpose.policyVersion,
+      }
+    : null;
+}
+
+/**
+ * The buyer's terms grant (#8765 D14). Writes nothing — and logs why — for a
+ * session whose box was not accepted (`consent_absent`: Stripe enforced the
+ * box, so the order completes regardless), one that does not carry the
+ * current `ailk_terms` stamp (`terms_unstamped`: a Payment Link, an invoice,
+ * an older session or other terms), or one whose buyer has no Person
+ * (`person_unresolved`). Otherwise `recordCheckoutConsent` writes at most one
+ * row per Person and session (`recorded` / `unchanged`), or none when the
+ * site's registry has moved past the stamped version (`version_changed`).
+ *
+ * Logs `{ event, outcome, eventIdPrefix }` only (plus `errName` on `failed`)
+ * — never an email or a Person id. Never throws: the response stays 200.
+ */
+async function recordCheckoutTermsGrant(
+  request: FastifyRequest,
+  {
+    session,
+    livemode,
+    eventIdPrefix,
+    flowPerson,
+  }: {
+    session: CheckoutSessionObject;
+    livemode: boolean;
+    eventIdPrefix: string;
+    /** A flow checkout's Person, from `recordFlowCheckoutPerson`. */
+    flowPerson: CheckoutPersonResult["person"];
+  },
+): Promise<void> {
+  const line = (outcome: string) => ({
+    event: "checkout-consent",
+    outcome,
+    eventIdPrefix,
+  });
+  try {
+    if (session.consent?.terms_of_service !== "accepted") {
+      request.log.info(
+        line("consent_absent"),
+        "checkout terms grant: box not accepted",
+      );
+      return;
+    }
+    const stamp: unknown = session.metadata?.[TERMS_STAMP_KEY];
+    const expected = currentTermsStamp();
+    if (expected === null || stamp !== expected.stamp) {
+      request.log.info(
+        line("terms_unstamped"),
+        "checkout terms grant: session carries no current terms stamp",
+      );
+      return;
+    }
+    const sessionId = session.id;
+    const buyer =
+      typeof sessionId === "string" && sessionId !== ""
+        ? await checkoutBuyerPerson(session, livemode, flowPerson)
+        : null;
+    if (buyer === null || typeof sessionId !== "string") {
+      request.log.info(
+        line("person_unresolved"),
+        "checkout terms grant: no Person for this buyer",
+      );
+      return;
+    }
+    const outcome = await recordCheckoutConsent({
+      workspaceId: buyer.workspaceId,
+      personId: buyer.personId,
+      sessionId,
+      policyVersion: expected.policyVersion,
+    });
+    request.log.info(line(outcome), "checkout terms grant");
+  } catch (err) {
+    // The error's class only (a Prisma error's message can carry values).
+    request.log.error(
+      {
+        ...line("failed"),
+        errName: err instanceof Error ? err.name : "UnknownError",
+      },
+      "checkout terms grant failed — continuing",
+    );
+  }
 }
 
 /**

package/templates/apps/api/src/server.ts

@@ -50,13 +50,16 @@ import type { RegisteredRoute } from "./openapi/surface-drift.js";
 import { exampleAeoRoute, scoreAeoRoute } from "./routes/aeo/index.js";
 import {
   hubSignInClientRoutes,
+  hubSignInPublicRoutes,
   hubSignInSessionRoutes,
 } from "./routes/auth/hub-sign-in.js";
 import { tokenRoutes } from "./routes/auth/tokens.js";
 import { transactionalEmailRoute } from "./routes/auth/transactional-email.js";
 import { userRoutes } from "./routes/auth/user.js";
 import {
+  consentAccountRoutes,
   consentCookieRoute,
+  consentSignUpRoute,
   consentUnsubscribeRoute,
 } from "./routes/consent/index.js";
 import { getPageRoute } from "./routes/content/get-page.js";
@@ -980,6 +983,14 @@ export async function build() {
     // preHandler's hub-credential branch (D6).
     await authScope.register(hubSignInSessionRoutes);
 
+    // #8765 D5 — the caller's account-level sign-up agreements. Auth only,
+    // NOT tenant-guarded: the agreement is about the `User` row, read and
+    // written in the deployment's own site workspace whatever site asks.
+    // Unconditional — auth and consent are never-gate surfaces — and both
+    // are in `HUB_SESSION_ROUTES`, so a spoke reaches them with its member's
+    // credential (the account layout's interstitial, D7).
+    await authScope.register(consentAccountRoutes);
+
     // Tenant-context routes (multi-tenant module) — auth only. They
     // establish/inspect the active workspace, so the tenant guard does not
     // apply to them; each enforces membership in the service layer.
@@ -1378,6 +1389,10 @@ export async function build() {
   await server.register(searchContentRoute);
   await server.register(listPagesRoute);
   await server.register(getPageRoute);
+  // The hub's sign-in page names the spoke that sent a visitor (#8790 D2):
+  // a public read of one client's name + origin from the registry. No auth —
+  // the visitor is signed out by definition when the page asks.
+  await server.register(hubSignInPublicRoutes);
   // Checkout launcher + reader — commerce PRIMITIVES (D-64, #5796; the GET
   // added by #6084). Registered UNCONDITIONALLY and gated at CALL time on
   // the JWT `commerce` claim, the same posture content-write has
@@ -1570,6 +1585,19 @@ export async function build() {
     });
     await unsubscribeScope.register(consentUnsubscribeRoute);
   });
+  // #8765 D2 — the sign-up agreements' evidence, beside the consent floor:
+  // anonymous, keyless, outside every module gate (sign-up and consent are
+  // never-gate surfaces). Its own scope, `signupevidence`, so an anonymous
+  // burst never shares a bucket with the cookie banner's log (SEC-8765-D).
+  // Its main caller is the web's own server, whose cache keeps it to one call
+  // a minute per enabled locale per instance.
+  await server.register(async (signUpEvidenceScope) => {
+    signUpEvidenceScope.register(rateLimitMiddleware, {
+      perIpPerMinute: DEFAULT_PER_IP_PER_MINUTE_STRICT,
+      scope: "signupevidence",
+    });
+    await signUpEvidenceScope.register(consentSignUpRoute);
+  });
 
   // Leads routes — rate-limit middleware scoped to this sub-router. Own
   // default (10/min, pre-#4730) rather than inheriting the wider