create-ailk 0.22.0 → 0.23.0

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

@@ -0,0 +1,384 @@
+/**
+ * POST /v1/webhooks/stripe/:connectionToken — the per-Organization Stripe
+ * webhook (#8932; 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 token names ONE StripeConnection row (#8907 D11): that row's decrypted
+ * secret verifies the signature, with no env key (W3, the key-less verify),
+ * and its `organizationId` is the only Organization the event can act for —
+ * nothing in the body, query or headers changes it. The event acts only for a
+ * Checkout Session the hub's own checkout recorded (#8930's record, A11) for
+ * that Organization, whose signed `metadata.site` is the record's workspace
+ * (W5), whose paid line item is the record's Price (W6), once per session, as
+ * one lead whose offering is the record's FULL lookup key (G5) and which — for
+ * a live session — carries the held-plan marker #8793's release reads (W7).
+ *
+ * THE LADDER (D2). One handler; the first step that answers ends the request:
+ *
+ *    1  token lookup `not-found` (or a non-string param) → 404, no line
+ *   1a  token lookup rejects                → 503 webhook-unavailable
+ *    2  `not-configured` / `unreadable`     → 503 webhook-not-configured
+ *    3  settle the signature (held as a value, as the legacy route does)
+ *    4  commerce claim `undetermined`       → 503 + Retry-After
+ *    5  `unclaimed`: signed → 200 dropped; unsigned → the module-disabled 404
+ *    6  the held rejection                  → 400
+ *    7  W4 livemode ≠ the row's mode        → 200 livemode_mismatch
+ *    8  W5 not a completed / async-paid session → 200 ignored_type
+ *  9–11 W5 the record: rejects → 503, `"unreadable"` → 500, none → 200 unrecorded
+ *   12  another Organization's record, or `metadata.site` ≠ the record's
+ *       workspace                          → 200 foreign_organization
+ *   13  the record's mode ≠ the row's      → 200 livemode_mismatch
+ *   14  W10 seen for this Organization     → 200 duplicate
+ *   15  W6 a completed session not paid   → 200 unpaid (seen)
+ *   16  W6 the line items cannot be read   → 503 stripe-unavailable
+ *   17  W6 not exactly the record's Price  → 200 offering_mismatch (seen)
+ *   18  W7 fulfil through `routeLead`      → 200 fulfilled / already_fulfilled /
+ *       unfulfillable (seen), else 503 fulfilment-unavailable
+ *
+ * Every 200 body is `{ received: true }` — the outcome is the log line's,
+ * never the body's, because Stripe shows the seller every response body
+ * (C1, SEC-8932-13). No non-2xx answer is ever marked seen, so Stripe's retry
+ * reaches a corrected deployment (SEC-8930-1). Dedup is this endpoint's own
+ * per-Organization store (D8), checked after attribution, so a foreign or
+ * unrecorded event is in no store at all (W10).
+ *
+ * LOGGING (W9, C6). Each line carries exactly the keys D2 names for its step:
+ * `organizationId`, `eventType`, an 8-character `eventIdPrefix` and `outcome`
+ * — never the token, the secret, a full Stripe id, the buyer's email, the
+ * lookup key, a metadata value, line-item text or an error message. Every
+ * rejection the handler awaits is caught here, so none reaches Fastify's
+ * error handler. The token never reaches a request line either: the shared
+ * path redactor (`lib/error-serializer.ts`'s `redactLogPath`, D10) replaces
+ * it whole.
+ *
+ * W11. No billing identity is bound from a connection's event: this file
+ * imports none of the legacy route's billing functions and its only write is
+ * the one lead.
+ */
+import type { FastifyReply, FastifyRequest } from "fastify";
+
+import {
+  commerceDisabledResponse,
+  LICENSE_UNDETERMINED_BODY,
+  LICENSE_UNDETERMINED_RETRY_AFTER_SECONDS,
+  LICENSE_UNDETERMINED_STATUS,
+  resolveCommerceClaim,
+} from "../../lib/require-commerce-claim.js";
+import {
+  StripeWebhookSignatureError,
+  verifyWebhookSignatureKeyless,
+} from "../../lib/stripe.js";
+import {
+  hasSeenForOrganization,
+  markSeenForOrganization,
+} from "../../lib/webhook-idempotency.js";
+import { routeLead, type RouteLeadResult } from "../../services/lead-routing.js";
+import {
+  readCheckoutSessionRecord,
+  type CheckoutSessionRecord,
+} from "../../services/offerings/checkout-session-record.js";
+import {
+  findStripeConnectionByWebhookToken,
+  stripeClientForOrganization,
+  type StripeWebhookConnection,
+} from "../../services/offerings/connection.js";
+
+/** A space: no `Idempotency-Key` header can carry one, so no request can pre-seed this key (NFR6). */
+const OFFERINGS_LEAD_KEY_PREFIX = "stripe-offerings ";
+
+/** The two session events that can fulfil (W5). */
+const FULFILLING_EVENT_TYPES = new Set([
+  "checkout.session.completed",
+  "checkout.session.async_payment_succeeded",
+]);
+
+/** The server-written terms stamp the hub's checkout puts in `metadata` (#8765 D14). */
+const TERMS_STAMP_KEY = "ailk_terms";
+
+type VerifiedEvent = ReturnType<typeof verifyWebhookSignatureKeyless>;
+type Connection = Extract<StripeWebhookConnection, { kind: "ok" }>;
+
+type SettledSignature =
+  | { ok: true; event: VerifiedEvent }
+  | { ok: false; status: number; body: { error: string }; verifyThrew: boolean };
+
+/** The fields of a signed Checkout Session this route reads — read, never trusted beyond the signature. */
+type SessionObject = {
+  object?: unknown;
+  id?: unknown;
+  payment_status?: unknown;
+  amount_total?: unknown;
+  currency?: unknown;
+  customer_details?: { email?: unknown } | null;
+  consent?: { terms_of_service?: unknown } | null;
+  metadata?: Record<string, unknown> | null;
+};
+
+/** Step 3: the signature as a value, so the claim can be read before any rejection is sent (D-64). */
+function settleSignature(request: FastifyRequest, secret: string): SettledSignature {
+  const rawBody = request.body;
+  if (!Buffer.isBuffer(rawBody)) {
+    return { ok: false, status: 400, body: { error: "invalid-request" }, verifyThrew: false };
+  }
+  const signature = request.headers["stripe-signature"];
+  if (typeof signature !== "string" || signature.length === 0) {
+    return { ok: false, status: 400, body: { error: "signature-missing" }, verifyThrew: false };
+  }
+  try {
+    return { ok: true, event: verifyWebhookSignatureKeyless(rawBody, signature, secret) };
+  } catch (err) {
+    if (err instanceof StripeWebhookSignatureError) {
+      return { ok: false, status: 400, body: { error: "signature-invalid" }, verifyThrew: true };
+    }
+    throw err;
+  }
+}
+
+/** The event keys every line from step 7 on carries (W9). */
+function eventKeys(organizationId: string, event: VerifiedEvent) {
+  return {
+    organizationId,
+    eventType: event.type,
+    eventIdPrefix: event.id.slice(0, 8),
+  };
+}
+
+function objectOf(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+export const stripeOfferingsWebhookHandler = async (
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> => {
+  // ── Steps 1, 1a, 2 — the token selects the connection (W1, W2) ───────────
+  const token = (request.params as { connectionToken?: unknown } | undefined)
+    ?.connectionToken;
+  let connection: StripeWebhookConnection;
+  try {
+    connection =
+      typeof token === "string"
+        ? await findStripeConnectionByWebhookToken(token)
+        : { kind: "not-found" };
+  } catch {
+    request.log.error(
+      { outcome: "connection_unavailable" },
+      "stripe offerings webhook: the connection store could not be read",
+    );
+    await reply.code(503).send({ error: "webhook-unavailable" });
+    return;
+  }
+  if (connection.kind === "not-found") {
+    await reply.code(404).send({ error: "not-found" });
+    return;
+  }
+  if (connection.kind !== "ok") {
+    request.log.warn(
+      { organizationId: connection.organizationId, outcome: "webhook_not_configured" },
+      "stripe offerings webhook: the connection has no usable webhook secret",
+    );
+    await reply.code(503).send({ error: "webhook-not-configured" });
+    return;
+  }
+  const { organizationId } = connection;
+
+  // ── Steps 3–6 — signature first, claim second (D-64) ─────────────────────
+  const settled = settleSignature(request, connection.webhookSecret);
+  const claim = await resolveCommerceClaim();
+
+  if (claim === "undetermined") {
+    request.log.warn(
+      settled.ok
+        ? { ...eventKeys(organizationId, settled.event), outcome: "license_undetermined" }
+        : { organizationId, outcome: "license_undetermined" },
+      "stripe offerings webhook held: the commerce licence could not be read",
+    );
+    await reply
+      .code(LICENSE_UNDETERMINED_STATUS)
+      .header("Retry-After", String(LICENSE_UNDETERMINED_RETRY_AFTER_SECONDS))
+      .send(LICENSE_UNDETERMINED_BODY);
+    return;
+  }
+
+  if (claim === "unclaimed") {
+    if (settled.ok) {
+      request.log.warn(
+        { ...eventKeys(organizationId, settled.event), outcome: "dropped_no_commerce_claim" },
+        "stripe offerings webhook event dropped: no commerce claim",
+      );
+      await reply.code(200).send({ received: true });
+      return;
+    }
+    const err = commerceDisabledResponse();
+    await reply.code(err.status).send(err.body);
+    return;
+  }
+
+  if (!settled.ok) {
+    if (settled.verifyThrew) {
+      request.log.warn(
+        { organizationId, outcome: "signature_invalid" },
+        "stripe offerings webhook signature verification failed",
+      );
+    }
+    await reply.code(settled.status).send(settled.body);
+    return;
+  }
+
+  await processVerifiedEvent(request, reply, connection, settled.event);
+};
+
+/** Steps 7–18, for an event signed with the connection's own secret. */
+async function processVerifiedEvent(
+  request: FastifyRequest,
+  reply: FastifyReply,
+  connection: Connection,
+  event: VerifiedEvent,
+): Promise<void> {
+  const { organizationId } = connection;
+  const keys = eventKeys(organizationId, event);
+  const ack = async (
+    level: "info" | "warn",
+    outcome: string,
+    message: string,
+    seen: boolean,
+  ): Promise<void> => {
+    if (seen) markSeenForOrganization(organizationId, event.id);
+    request.log[level]({ ...keys, outcome }, message);
+    await reply.code(200).send({ received: true });
+  };
+  const fail = async (status: number, error: string, outcome: string, message: string) => {
+    request.log.error({ ...keys, outcome }, message);
+    await reply.code(status).send({ error });
+  };
+
+  // ── Step 7 — W4 ──────────────────────────────────────────────────────────
+  if ((event.livemode === true) !== (connection.mode === "live")) {
+    await ack("warn", "livemode_mismatch", "stripe offerings webhook event dropped: livemode differs from the connection", false);
+    return;
+  }
+
+  // ── Step 8 — W5, the type ────────────────────────────────────────────────
+  const session = objectOf(objectOf(event.data)?.["object"]) as SessionObject | null;
+  if (!FULFILLING_EVENT_TYPES.has(event.type) || session?.object !== "checkout.session") {
+    await ack("info", "ignored_type", "stripe offerings webhook event ignored", false);
+    return;
+  }
+
+  // ── Steps 9–11 — W5, the hub's own record (A11) ──────────────────────────
+  let record: CheckoutSessionRecord | "unreadable" | null;
+  try {
+    record = await readCheckoutSessionRecord(session.id);
+  } catch {
+    await fail(503, "record-unavailable", "record_unavailable", "stripe offerings webhook: the session record could not be read");
+    return;
+  }
+  if (record === "unreadable") {
+    await fail(500, "record-unreadable", "record_unreadable", "stripe offerings webhook: the session record is unreadable");
+    return;
+  }
+  if (record === null) {
+    await ack("info", "unrecorded", "stripe offerings webhook: no hub record for the session", false);
+    return;
+  }
+
+  // ── Step 12 — W5, this Organization and this workspace (C2) ──────────────
+  const site = session.metadata?.["site"];
+  if (record.organizationId !== organizationId || typeof site !== "string" || site !== record.workspaceId) {
+    await ack("warn", "foreign_organization", "stripe offerings webhook: the session is not this Organization's", false);
+    return;
+  }
+
+  // ── Step 13 — the record's mode ──────────────────────────────────────────
+  if (record.mode !== connection.mode) {
+    await ack("warn", "livemode_mismatch", "stripe offerings webhook event dropped: the record's mode differs from the connection", false);
+    return;
+  }
+
+  // ── Step 14 — W10, per-Organization dedup ────────────────────────────────
+  if (hasSeenForOrganization(organizationId, event.id)) {
+    await ack("info", "duplicate", "stripe offerings webhook: duplicate event", false);
+    return;
+  }
+
+  // ── Step 15 — W6, payment ────────────────────────────────────────────────
+  if (
+    event.type === "checkout.session.completed" &&
+    session.payment_status !== "paid" &&
+    session.payment_status !== "no_payment_required"
+  ) {
+    await ack("info", "unpaid", "stripe offerings webhook: the session is not paid", true);
+    return;
+  }
+
+  // ── Steps 16–17 — W6, the paid Price is the record's (D5) ────────────────
+  let paidPriceIds: unknown[];
+  try {
+    const resolved = await stripeClientForOrganization(organizationId);
+    if (resolved.kind !== "ok") throw new Error("connection unusable");
+    const items = await resolved.client.checkout.sessions.listLineItems(record.sessionId, { limit: 2 });
+    paidPriceIds = items.data.map((item) => item.price?.id);
+  } catch {
+    await fail(503, "stripe-unavailable", "stripe_unavailable", "stripe offerings webhook: the line items could not be read");
+    return;
+  }
+  if (paidPriceIds.length !== 1 || paidPriceIds[0] !== record.priceId) {
+    await ack("warn", "offering_mismatch", "stripe offerings webhook: the paid Price is not the recorded one", true);
+    return;
+  }
+
+  // ── Step 18 — W7, one held lead per session (D6) ─────────────────────────
+  const metadata = session.metadata ?? {};
+  const terms = metadata[TERMS_STAMP_KEY];
+  let result: RouteLeadResult;
+  try {
+    result = await routeLead(
+      {
+        kind: "submit",
+        siteId: record.workspaceId,
+        source: "web",
+        email: typeof session.customer_details?.email === "string" ? session.customer_details.email : "",
+        payload: {
+          page: "checkout",
+          // The record's full key (G5) — never `metadata.ailk_offering`.
+          offering: record.lookupKey,
+          site: record.workspaceId,
+          amountTotal: typeof session.amount_total === "number" ? session.amount_total : null,
+          currency: typeof session.currency === "string" ? session.currency : null,
+          termsAccepted:
+            session.consent?.terms_of_service === "accepted" && typeof terms === "string" ? terms : null,
+        },
+      },
+      {
+        ip: request.ip,
+        userAgent: request.headers["user-agent"],
+        receivedAt: new Date().toISOString(),
+      },
+      { idempotencyKey: OFFERINGS_LEAD_KEY_PREFIX + record.sessionId, offeringsCheckout: true },
+    );
+  } catch {
+    await fail(503, "fulfilment-unavailable", "fulfilment_unavailable", "stripe offerings webhook: the lead could not be written");
+    return;
+  }
+
+  if (result.ok && result.persisted === "db") {
+    if (result.replayed === true) {
+      await ack("info", "already_fulfilled", "stripe offerings webhook: the session was already fulfilled", true);
+    } else {
+      await ack("info", "fulfilled", "stripe offerings webhook: the session was fulfilled", true);
+    }
+    return;
+  }
+  if (!result.ok && result.error.kind === "idempotency_conflict") {
+    await ack("info", "already_fulfilled", "stripe offerings webhook: the session was already fulfilled", true);
+    return;
+  }
+  if (!result.ok && result.error.kind === "invalid_input") {
+    await ack("warn", "unfulfillable", "stripe offerings webhook: the session has no storable email", true);
+    return;
+  }
+  await fail(503, "fulfilment-unavailable", "fulfilment_unavailable", "stripe offerings webhook: the lead could not be written");
+}

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)
@@ -331,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",
@@ -370,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 {
@@ -421,6 +444,7 @@ export const stripeWebhookHandler = async (
           ? upsertOrgBillingIdentity(request, {
               organizationId,
               customerId: session.customer,
+              sessionId: session.id ?? null,
               eventIdPrefix,
             })
           : upsertBillingIdentity(request, {
@@ -646,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 —
@@ -1331,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
@@ -1349,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: {
@@ -1368,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",
     );