create-ailk 0.21.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");
+}