create-ailk 0.21.0 → 0.23.0

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

@@ -48,12 +48,17 @@
  *
  * Billing upsert (customer.created / checkout.session.completed):
  *   Billing-entity routing (org-scoped billing, #3601, spec D2): a checkout
- *   carrying metadata.organizationId links the Organization (multi-tenant
+ *   carrying metadata.organizationId takes the Organization path (multi-tenant
  *   module); absent → the User path (single-tenant).
  *
- *   Organization path (metadata.organizationId present):
+ *   Organization path (metadata.organizationId present) — proof-based since
+ *   #9067 D13: the metadata names the target, the recorded session proves it.
  *     1. Typed composite match already pointing at this org → idempotent no-op
- *     2. Else link the target Organization (by id) billing fields
+ *     2. A checkout.session.completed binds only when the Organization's
+ *        `planCheckoutSessionId` is this session's id and no customer is
+ *        bound yet (one guarded updateMany, which also clears the session)
+ *     3. Anything else — an unrecorded session, a bound customer, any
+ *        customer.created — logs org_bind_unproven and writes nothing
  *
  *   User path (no organizationId):
  *     1. Typed composite match: (billingProvider="stripe", billingCustomerId=customer)
@@ -96,6 +101,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 +123,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 +153,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 +164,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;
@@ -314,6 +336,23 @@ export const stripeWebhookHandler = async (
     return;
   }
 
+  // #8932 D9 (contract W8) — an Offerings-stamped event belongs to the
+  // per-Organization endpoint, which must still be able to act on it, so it
+  // is acked here BEFORE `markSeen` and nothing is written. Presence decides,
+  // whatever the value; any other event takes the path below unchanged.
+  if (
+    offeringsStampSourcesOf(event).some((source) =>
+      Object.hasOwn(source, OFFERINGS_STAMP_KEY),
+    )
+  ) {
+    request.log.info(
+      { eventType: event.type, eventIdPrefix, outcome: "offerings_path" },
+      "stripe webhook event left to the per-Organization endpoint",
+    );
+    await reply.code(200).send({ received: true });
+    return;
+  }
+
   request.log.info(
     { eventType: event.type, eventIdPrefix },
     "stripe webhook event received",
@@ -353,15 +392,16 @@ export const stripeWebhookHandler = async (
         email?: string | null;
         metadata?: Record<string, string> | null;
       };
-      // Billing-entity routing (spec D2): a multi-tenant checkout stamps the
-      // target Organization id in metadata.organizationId (an individual → their
-      // sentinel default org). Present → link the Organization; absent → the
-      // User path (single-tenant, degrade-clean).
+      // Billing-entity routing (spec D2): metadata.organizationId present →
+      // the Organization path, which a customer's own metadata can never
+      // prove (#9067 D13: only a recorded plan session binds), so it writes
+      // nothing; absent → the User path (single-tenant, degrade-clean).
       const organizationId = customer.metadata?.["organizationId"] ?? null;
       if (organizationId) {
         await upsertOrgBillingIdentity(request, {
           organizationId,
           customerId: customer.id,
+          sessionId: null,
           eventIdPrefix,
         });
       } else {
@@ -404,6 +444,7 @@ export const stripeWebhookHandler = async (
           ? upsertOrgBillingIdentity(request, {
               organizationId,
               customerId: session.customer,
+              sessionId: session.id ?? null,
               eventIdPrefix,
             })
           : upsertBillingIdentity(request, {
@@ -429,13 +470,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 +583,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;
 };
 
@@ -616,6 +670,28 @@ function siteStampSourcesOf(event: {
     .filter((source) => source !== null) as Record<string, string>[];
 }
 
+/** The metadata key the hub's Offerings checkout stamps on its sessions (contract A6, #8932 D9). */
+const OFFERINGS_STAMP_KEY = "ailk_offering";
+
+/**
+ * Where an Offerings stamp may sit (#8932 D9): every site-stamp source
+ * (`siteStampSourcesOf` — the Subscription, the Customer and an invoice's
+ * three) plus, for a `checkout.session.*` event whose object is a session,
+ * the session's own metadata.
+ */
+function offeringsStampSourcesOf(event: {
+  type: string;
+  data?: unknown;
+}): Record<string, string>[] {
+  const sources = siteStampSourcesOf(event);
+  const object = objectOrNull(objectOrNull(event.data)?.["object"]);
+  if (event.type.startsWith("checkout.session.") && object?.["object"] === "checkout.session") {
+    const metadata = objectOrNull(object["metadata"]);
+    if (metadata !== null) sources.push(metadata as Record<string, string>);
+  }
+  return sources;
+}
+
 /**
  * Minimal projected shape of a Stripe Invoice object for the dunning arms
  * (#6034 FR-1). `subscription` and `customer` are EXPANDABLE Stripe fields —
@@ -750,7 +826,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 +834,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 +848,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",
+    );
+  }
 }
 
 /**
@@ -1196,14 +1377,19 @@ async function upsertBillingIdentity(
 
 /**
  * Link Organization.billingProvider + billingCustomerId for a Stripe customer
- * (org-scoped billing, #3601, spec D2/D3). Called when a checkout carries
- * metadata.organizationId — for a real org, or an individual's sentinel default
- * Organization (orgs-of-one; AC2 — ONE billing path inside the module).
+ * (org-scoped billing, #3601, spec D2/D3), only on proof (#9067 D13,
+ * SEC-9067-1 to -3). `metadata.organizationId` names the target; the proof
+ * is the session id POST /v1/billing/plan-checkout recorded on that
+ * Organization. The bind is one guarded `updateMany` on `{ id,
+ * planCheckoutSessionId: sessionId, billingCustomerId: null }`, which also
+ * clears the recorded session — so a session no route recorded, a session
+ * recorded by another deployment's database, a re-point of a bound customer
+ * and a `customer.created` (`sessionId` null: a customer's metadata proves
+ * nothing) all bind nothing and log `org_bind_unproven`.
  *
  * Idempotent: a typed-composite match (billingProvider="stripe",
  * billingCustomerId=customerId) already pointing at THIS org is a no-op on
- * replay. Otherwise the target Organization (by id from checkout metadata) is
- * linked.
+ * replay.
  *
  * DB failures are caught and logged (never re-thrown) — a broken link must not
  * make Stripe retry (which would re-fire analytics + billing on eventual
@@ -1214,9 +1400,24 @@ async function upsertOrgBillingIdentity(
   {
     organizationId,
     customerId,
+    sessionId,
     eventIdPrefix,
-  }: { organizationId: string; customerId: string; eventIdPrefix: string },
+  }: {
+    organizationId: string;
+    customerId: string;
+    sessionId: string | null;
+    eventIdPrefix: string;
+  },
 ): Promise<void> {
+  const unproven = () =>
+    request.log.warn(
+      { eventIdPrefix, outcome: "org_bind_unproven" },
+      "org billing identity not linked — no recorded plan checkout proves it",
+    );
+  if (sessionId === null) {
+    unproven();
+    return;
+  }
   try {
     const existingByBilling = await prisma.organization.findFirst({
       where: {
@@ -1233,22 +1434,30 @@ async function upsertOrgBillingIdentity(
       return;
     }
 
-    await prisma.organization.update({
-      where: { id: organizationId },
+    const { count } = await prisma.organization.updateMany({
+      where: { id: organizationId, planCheckoutSessionId: sessionId, billingCustomerId: null },
       data: {
         billingProvider: "stripe",
         billingCustomerId: customerId,
+        planCheckoutSessionId: null,
       },
     });
+    if (count !== 1) {
+      unproven();
+      return;
+    }
     request.log.info(
       { eventIdPrefix },
-      "org billing identity linked from checkout metadata.organizationId",
+      "org billing identity linked from the recorded plan checkout",
     );
   } catch (err) {
+    // #9067 FR-6 — the name and Prisma code only: some Prisma messages
+    // print the call's arguments, which here carry the session and customer ids.
     request.log.error(
       {
         eventIdPrefix,
-        error: err instanceof Error ? err.message : String(err),
+        errName: err instanceof Error ? err.name : "unknown",
+        code: (err as { code?: unknown } | null)?.code,
       },
       "org billing identity upsert failed — continuing",
     );