create-ailk 0.21.0 → 0.23.0

package/templates/apps/api/src/services/offerings/connection.ts

@@ -0,0 +1,1003 @@
+/**
+ * An Organization's Stripe connection (#8876, spec
+ * docs/specs/8876-the-offerings-data-model-typed-spec.md D6; #8907, spec
+ * docs/specs/8907-the-organization-stripe-connection-custody-spec.md D2–D6,
+ * D11–D13; contract docs/specs/8879-the-offerings-security-contract-key-spec.md
+ * C1–C11, K3–K9, P2) — the ONE file that reads or writes the StripeConnection
+ * model, and the one that encrypts or decrypts its key and webhook secret.
+ *
+ * WRITE-ONLY TO EVERY READER. No function here returns the key, the webhook
+ * secret, the routing token's row or a ciphertext to a route: the summary
+ * and the view select no ciphertext (the view reads only whether a secret is
+ * set), and a write answers `Saved`, which carries no `last4` and no token
+ * (SEC-8907-10). Only `stripeClientForOrganization` and the token lookup
+ * decrypt, for their server-side callers (#8054, #8861).
+ *
+ * ENCRYPTION AT REST (D2, C2, C10). `v1.<iv>.<tag>.<ciphertext>`, each part
+ * base64url: AES-256-GCM under `config.STRIPE_CONNECTION_KEY`, a fresh 12-byte
+ * IV, a 16-byte tag (enforced on decrypt), and
+ * `stripe-connection:v1:<organizationId>:<field>` as additional data, so a
+ * value copied to another Organization, into the other column or under the
+ * other mode fails authentication. Decryption tries the current key, then
+ * `STRIPE_CONNECTION_KEY_PREVIOUS`; encryption always uses the current key.
+ * A copy of the scheduling envelope, not an import: that file is a slice file
+ * and this one is base tree (D2).
+ *
+ * DATA ACCESS (D6, C11). Ten delegate calls, each keyed on an
+ * `organizationId` the server resolved (the tenant, or the row a token
+ * named), pinned by `architecture.yaml`'s `paths_scoped` count. Only the
+ * rekey walk lists rows, and only the bin calls it. Every call is wrapped so
+ * a Prisma error leaves as a `StripeConnectionStoreError` with a fixed
+ * message and no cause — a CHECK violation's text names the row's values
+ * (SEC-8907-9).
+ *
+ * `null` means no row and nothing else. A row that fails its schema is
+ * `"unreadable"`, so no caller mistakes a corrupt connection for an absent
+ * one and falls back to the deployment's env key (contract A2, NFR2).
+ *
+ * LOGGING (D15, C5). Only `organizationId`, `mode`, a fixed `outcome` or
+ * `reason`, and an error's class name. Never the key or any part of it,
+ * `last4`, the secret, the token, a ciphertext or Stripe error text.
+ */
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+
+import { logger } from "@working-theory/observability";
+import {
+  stripeConnectionSummarySchema,
+  type StripeConnectionSummary,
+} from "@working-theory/validation";
+import { z } from "zod";
+
+import { config } from "../../config/index.js";
+import { prisma } from "../../lib/prisma.js";
+import {
+  classifyStripeKey,
+  isProductionBuild,
+  stripeClientForConnection,
+  type StripeConnectionMode,
+  type StripeKeyClass,
+} from "../../lib/stripe.js";
+
+/** The connection's summary, `"unreadable"` for a corrupt row, `null` for none. */
+export async function getStripeConnectionSummary(
+  organizationId: string,
+): Promise<StripeConnectionSummary | "unreadable" | null> {
+  const row = await store(() =>
+    prisma.stripeConnection.findUnique({
+      where: { organizationId },
+      select: { mode: true, keyLast4: true, liveAt: true, createdAt: true, updatedAt: true },
+    }),
+  );
+  if (row === null) return null;
+  const summary = stripeConnectionSummarySchema.safeParse({
+    mode: row.mode,
+    last4: row.keyLast4,
+    connectedAt: isoOf(row.createdAt),
+    liveAt: row.liveAt === null ? null : isoOf(row.liveAt),
+    updatedAt: isoOf(row.updatedAt),
+  });
+  if (summary.success) return summary.data;
+  logUnreadableRow(organizationId);
+  return "unreadable";
+}
+
+/** An ISO string, or `null` for a value that is not a valid Date. */
+function isoOf(value: unknown): string | null {
+  return value instanceof Date && !Number.isNaN(value.getTime()) ? value.toISOString() : null;
+}
+
+function logUnreadableRow(organizationId: string): void {
+  logger.error(
+    { organizationId, reason: "connection_unreadable" },
+    "[offerings] stripe connection row is unreadable",
+  );
+}
+
+function logUnreadableValue(organizationId: string): void {
+  logger.error(
+    { organizationId, reason: "credential_unreadable" },
+    "[offerings] stripe connection value could not be decrypted",
+  );
+}
+
+// ─── The store boundary ─────────────────────────────────────────────────────
+
+/** Every store failure, with a fixed message and no cause (SEC-8907-9). */
+export class StripeConnectionStoreError extends Error {
+  readonly uniqueViolation: boolean;
+  constructor(uniqueViolation: boolean) {
+    super("stripe connection store call failed");
+    this.name = "StripeConnectionStoreError";
+    this.uniqueViolation = uniqueViolation;
+  }
+}
+
+async function store<T>(call: () => Promise<T>): Promise<T> {
+  try {
+    return await call();
+  } catch (err) {
+    const code = (err as { code?: unknown } | null)?.code;
+    throw new StripeConnectionStoreError(code === "P2002");
+  }
+}
+
+// ─── The cipher (D2) ────────────────────────────────────────────────────────
+
+/** The three encrypted values; each binds its own additional data. */
+export type StripeConnectionField = "credential" | "webhook-secret:test" | "webhook-secret:live";
+
+const FORMAT_VERSION = "v1";
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+const KEY_BYTES = 32;
+
+function additionalData(organizationId: string, field: StripeConnectionField): Buffer {
+  return Buffer.from(`stripe-connection:${FORMAT_VERSION}:${organizationId}:${field}`, "utf8");
+}
+
+function secretField(mode: StripeConnectionMode): StripeConnectionField {
+  return mode === "live" ? "webhook-secret:live" : "webhook-secret:test";
+}
+
+/** Encrypt one value for one Organization's field (D2). */
+export function encryptStripeConnectionValue(
+  plaintext: string,
+  organizationId: string,
+  field: StripeConnectionField,
+  key: Buffer,
+): string {
+  const iv = randomBytes(IV_BYTES);
+  const cipher = createCipheriv("aes-256-gcm", key, iv, { authTagLength: TAG_BYTES });
+  cipher.setAAD(additionalData(organizationId, field));
+  const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+  return [
+    FORMAT_VERSION,
+    iv.toString("base64url"),
+    cipher.getAuthTag().toString("base64url"),
+    ciphertext.toString("base64url"),
+  ].join(".");
+}
+
+/** One key's attempt: `null` for any failure, never a throw. */
+function decryptUnder(
+  stored: string,
+  organizationId: string,
+  field: StripeConnectionField,
+  key: Buffer | undefined,
+): string | null {
+  if (!key || key.length !== KEY_BYTES) return null;
+  const parts = stored.split(".");
+  if (parts.length !== 4 || parts[0] !== FORMAT_VERSION) return null;
+  const iv = Buffer.from(parts[1] ?? "", "base64url");
+  const tag = Buffer.from(parts[2] ?? "", "base64url");
+  const ciphertext = Buffer.from(parts[3] ?? "", "base64url");
+  if (iv.length !== IV_BYTES || tag.length !== TAG_BYTES) return null;
+  try {
+    const decipher = createDecipheriv("aes-256-gcm", key, iv, { authTagLength: TAG_BYTES });
+    decipher.setAAD(additionalData(organizationId, field));
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Decrypt one value under the current key, then the previous one (C10), or
+ * `null` when it is unreadable for ANY reason — no key, a wrong key, another
+ * Organization's value, the other field or mode, a part of the wrong length.
+ */
+export function decryptStripeConnectionValue(
+  stored: string,
+  organizationId: string,
+  field: StripeConnectionField,
+): string | null {
+  return (
+    decryptUnder(stored, organizationId, field, config.STRIPE_CONNECTION_KEY) ??
+    decryptUnder(stored, organizationId, field, config.STRIPE_CONNECTION_KEY_PREVIOUS)
+  );
+}
+
+/** Whether the writes can run: `STRIPE_CONNECTION_KEY` is set (C3). */
+export function stripeConnectionKeyConfigured(): boolean {
+  return config.STRIPE_CONNECTION_KEY !== undefined;
+}
+
+/** A routing token: 256 random bits, 43 base64url characters (W1). */
+function mintWebhookToken(): string {
+  return randomBytes(32).toString("base64url");
+}
+
+const WEBHOOK_TOKEN_RE = /^[A-Za-z0-9_-]{43}$/;
+const LAST4_RE = /^[A-Za-z0-9]{4}$/;
+const MODES = new Set<unknown>(["test", "live"]);
+
+function isMode(value: unknown): value is StripeConnectionMode {
+  return MODES.has(value);
+}
+
+// ─── Admission by class (D4) ────────────────────────────────────────────────
+
+export type StripeKeyRefusalReason =
+  | "key_not_live"
+  | "key_unrestricted"
+  | "live_key_needs_go_live"
+  | "key_publishable"
+  | "key_unrecognized"
+  | "key_not_usable";
+
+export type StripeKeyColumn = "connect" | "go-live";
+
+type Admission = "admit" | Exclude<StripeKeyRefusalReason, "key_not_usable">;
+
+/** One row per class, so a seventh class fails the type check (K3, K4, K5). */
+const ADMISSION: Record<StripeKeyColumn, Record<StripeKeyClass, Admission>> = {
+  connect: {
+    "restricted-test": "admit",
+    "secret-test": "key_unrestricted",
+    "restricted-live": "live_key_needs_go_live",
+    "secret-live": "key_unrestricted",
+    publishable: "key_publishable",
+    unknown: "key_unrecognized",
+  },
+  "go-live": {
+    "restricted-test": "key_not_live",
+    "secret-test": "key_unrestricted",
+    "restricted-live": "admit",
+    "secret-live": "key_unrestricted",
+    publishable: "key_publishable",
+    unknown: "key_unrecognized",
+  },
+};
+
+/**
+ * The class table's answer for one submitted key (D4). On admit, the key is
+ * `raw.trim()` — the string the classifier decided on — and `keyLast4` its
+ * last four characters; a key whose last four are not alphanumeric (a body
+ * under four characters, which no Stripe key has) is `key_not_usable` with no
+ * probe, so the database's CHECK is never what refuses.
+ */
+export function admitConnectionKey(
+  raw: string,
+  column: StripeKeyColumn,
+):
+  | { ok: true; key: string; keyLast4: string }
+  | { ok: false; reason: StripeKeyRefusalReason } {
+  const admission = ADMISSION[column][classifyStripeKey(raw)];
+  if (admission !== "admit") return { ok: false, reason: admission };
+  const key = raw.trim();
+  const keyLast4 = key.slice(-4);
+  if (!LAST4_RE.test(keyLast4)) return { ok: false, reason: "key_not_usable" };
+  return { ok: true, key, keyLast4 };
+}
+
+// ─── The probes (D5, K9, P2) ────────────────────────────────────────────────
+
+/** The longest the three probes may take together before the answer is `unavailable`. */
+export const PROBE_TIMEOUT_MS = 10_000;
+
+export type ProbeOutcome = "usable" | "not_usable" | "unavailable";
+
+const NOT_USABLE_TYPES = new Set(["StripeAuthenticationError", "StripePermissionError"]);
+
+function refusesTheKey(reason: unknown): boolean {
+  const { type, statusCode } = (reason ?? {}) as { type?: unknown; statusCode?: unknown };
+  return (
+    (typeof type === "string" && NOT_USABLE_TYPES.has(type)) ||
+    statusCode === 401 ||
+    statusCode === 403
+  );
+}
+
+function errNameOf(reason: unknown): string {
+  if (reason instanceof Error) return reason.name;
+  const type = (reason as { type?: unknown } | null)?.type;
+  return typeof type === "string" ? type : "unknown";
+}
+
+/**
+ * The three read probes (D5): `products.list`, `prices.list` and
+ * `checkout.sessions.list`, each `{ limit: 1 }`, started together and decided
+ * from all three settled results, so a refused key costs the same one round
+ * whichever probe refused it (SEC-8907-4). One answer covers an invalid key
+ * and a valid key missing a permission. The client lives only inside the
+ * call (C8).
+ */
+export async function probeStripeKey(input: {
+  organizationId: string;
+  key: string;
+  mode: StripeConnectionMode;
+  liveAt: Date | null;
+}): Promise<ProbeOutcome> {
+  const { organizationId } = input;
+  const client = stripeClientForConnection(input);
+  if (client === null) return logProbe(organizationId, "not_usable");
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timedOut = new Promise<"timeout">((resolve) => {
+    timer = setTimeout(() => resolve("timeout"), PROBE_TIMEOUT_MS);
+  });
+  const settled = Promise.allSettled([
+    client.products.list({ limit: 1 }),
+    client.prices.list({ limit: 1 }),
+    client.checkout.sessions.list({ limit: 1 }),
+  ]);
+  const results = await Promise.race([settled, timedOut]).finally(() => clearTimeout(timer));
+  if (results === "timeout") return logProbe(organizationId, "unavailable", "timeout");
+
+  const rejected = results.flatMap((r) => (r.status === "rejected" ? [r.reason as unknown] : []));
+  if (rejected.length === 0) return logProbe(organizationId, "usable");
+  if (rejected.some(refusesTheKey)) return logProbe(organizationId, "not_usable");
+  return logProbe(organizationId, "unavailable", undefined, errNameOf(rejected[0]));
+}
+
+function logProbe(
+  organizationId: string,
+  outcome: ProbeOutcome,
+  reason?: "timeout",
+  errName?: string,
+): ProbeOutcome {
+  const line = {
+    organizationId,
+    outcome,
+    ...(reason && { reason }),
+    ...(errName && { errName }),
+  };
+  if (outcome === "unavailable") logger.warn(line, "[offerings] stripe key probe");
+  else logger.info(line, "[offerings] stripe key probe");
+  return outcome;
+}
+
+// ─── The reads ──────────────────────────────────────────────────────────────
+
+/** C4's GET body: no key, no secret, no ciphertext — and no plaintext token outside the path. */
+const viewSchema = z
+  .object({
+    mode: z.enum(["test", "live"]),
+    last4: z.string().regex(LAST4_RE),
+    webhookPath: z.string().regex(/^\/v1\/webhooks\/stripe\/[A-Za-z0-9_-]{43}$/),
+    webhookSecretSet: z.boolean(),
+    connectedAt: z.iso.datetime(),
+    liveAt: z.iso.datetime().nullable(),
+    updatedAt: z.iso.datetime(),
+  })
+  .strict()
+  .refine((view) => (view.mode === "live") === (view.liveAt !== null), { path: ["liveAt"] });
+export type StripeConnectionView = z.infer<typeof viewSchema>;
+
+/** What a write answers (D7): no `last4`, no `webhookPath` (SEC-8907-10). */
+export type StripeConnectionSaved = {
+  mode: StripeConnectionMode;
+  webhookSecretSet: boolean;
+  liveAt: string | null;
+  updatedAt: string;
+};
+
+/**
+ * C4's GET (D7): the view, `"unreadable"` for a row that fails its schema,
+ * `null` for none. `webhookSecretSet` is decided from presence, never by
+ * decrypting.
+ */
+export async function getStripeConnectionView(
+  organizationId: string,
+): Promise<StripeConnectionView | "unreadable" | null> {
+  const row = await store(() =>
+    prisma.stripeConnection.findUnique({
+      where: { organizationId },
+      select: {
+        mode: true,
+        keyLast4: true,
+        webhookToken: true,
+        webhookSecretCiphertext: true,
+        liveAt: true,
+        createdAt: true,
+        updatedAt: true,
+      },
+    }),
+  );
+  if (row === null) return null;
+  const view = viewSchema.safeParse({
+    mode: row.mode,
+    last4: row.keyLast4,
+    webhookPath: `/v1/webhooks/stripe/${row.webhookToken}`,
+    webhookSecretSet: row.webhookSecretCiphertext !== null,
+    connectedAt: isoOf(row.createdAt),
+    liveAt: row.liveAt === null ? null : isoOf(row.liveAt),
+    updatedAt: isoOf(row.updatedAt),
+  });
+  if (view.success) return view.data;
+  logUnreadableRow(organizationId);
+  return "unreadable";
+}
+
+/** The row every write starts from (D6 call 3, D8 step 12). */
+export type StripeConnectionWriteRow = {
+  mode: StripeConnectionMode;
+  keyLast4: string;
+  webhookSecretSet: boolean;
+  liveAt: Date | null;
+  updatedAt: Date;
+};
+
+/**
+ * The read every write starts with (D6 call 3): the mode, last four and
+ * `updatedAt` the compare-and-swap keys on, plus whether a secret is set and
+ * the go-live time, so a write can answer `Saved` without a second read. The
+ * secret's presence is read, never its value.
+ */
+export async function readConnectionForWrite(
+  organizationId: string,
+): Promise<StripeConnectionWriteRow | "unreadable" | null> {
+  const row = await store(() =>
+    prisma.stripeConnection.findUnique({
+      where: { organizationId },
+      select: {
+        mode: true,
+        keyLast4: true,
+        webhookSecretCiphertext: true,
+        liveAt: true,
+        updatedAt: true,
+      },
+    }),
+  );
+  if (row === null) return null;
+  if (!isMode(row.mode) || !LAST4_RE.test(row.keyLast4)) {
+    logUnreadableRow(organizationId);
+    return "unreadable";
+  }
+  return {
+    mode: row.mode,
+    keyLast4: row.keyLast4,
+    webhookSecretSet: row.webhookSecretCiphertext !== null,
+    liveAt: row.liveAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+function savedOf(
+  mode: StripeConnectionMode,
+  webhookSecretSet: boolean,
+  liveAt: Date | null,
+  updatedAt: Date,
+): StripeConnectionSaved {
+  return {
+    mode,
+    webhookSecretSet,
+    liveAt: liveAt === null ? null : liveAt.toISOString(),
+    updatedAt: updatedAt.toISOString(),
+  };
+}
+
+// ─── The writes (D6) ────────────────────────────────────────────────────────
+
+type StoredFields = {
+  mode?: StripeConnectionMode;
+  keyLast4?: string;
+  credentialCiphertext?: string;
+  webhookSecretCiphertext?: string | null;
+  liveAt?: Date | null;
+  updatedAt: Date;
+};
+
+/**
+ * The compare-and-swap replace, go-live, secret set and rekey share (D6 call
+ * 5): it writes only when the row still carries the `updatedAt` its caller
+ * read, so a write in between is never lost or overwritten.
+ */
+async function writeIfUnchanged(
+  organizationId: string,
+  updatedAt: Date,
+  data: StoredFields,
+): Promise<boolean> {
+  const { count } = await store(() =>
+    prisma.stripeConnection.updateMany({ where: { organizationId, updatedAt }, data }),
+  );
+  return count > 0;
+}
+
+/** A write that did not happen, and why — the route maps each to its answer. */
+export type StripeConnectionWriteRefusal = {
+  kind: "connection_changed" | "connection_required" | "key_not_configured" | "live_mode_unavailable";
+};
+
+/** What the audit row and the owners' email name: the row as this write left it (C7). */
+export type StripeConnectionAudit = { mode: StripeConnectionMode; last4: string };
+
+export type StripeConnectionWrite<Kind extends string> =
+  | { kind: Kind; saved: StripeConnectionSaved; audit: StripeConnectionAudit }
+  | StripeConnectionWriteRefusal;
+
+const CHANGED = { kind: "connection_changed" } as const;
+const REQUIRED = { kind: "connection_required" } as const;
+const NO_KEY = { kind: "key_not_configured" } as const;
+const LIVE_UNAVAILABLE = { kind: "live_mode_unavailable" } as const;
+
+/**
+ * Re-read for a retry, re-applying every precondition the route's first read
+ * enforced: a row that became unreadable is a change, and a row that went
+ * live in between is never written from a build that is not production (D3,
+ * SEC-8907-3) — a preview sharing production's database must not reach it
+ * through the retry either.
+ */
+async function reread(
+  organizationId: string,
+): Promise<StripeConnectionWriteRow | null | "changed" | "live"> {
+  const row = await readConnectionForWrite(organizationId);
+  if (row === "unreadable") return "changed";
+  if (row?.mode === "live" && !isProductionBuild()) return "live";
+  return row;
+}
+
+/**
+ * A retry acts only on a row in the mode the request was made against: a
+ * replace never silently undoes a go-live that committed while its probe
+ * ran, and a secret entered for one mode is never bound to the other
+ * (C9, W2, SEC-8879-3).
+ */
+function modeMoved(
+  row: StripeConnectionWriteRow,
+  observed: StripeConnectionWriteRow | null,
+): boolean {
+  return row.mode !== (observed?.mode ?? "test");
+}
+
+/**
+ * Connect or replace (C9). `observed` is the route's D8 step 12 read: only a
+ * request that found no row there may create, so a replace whose row a
+ * disconnect removed in between answers `connection_changed` and never brings
+ * the connection back (SEC-8907-6). A replace keeps the token, sets the mode
+ * to test and clears the secret when the row was live — the secret is bound
+ * to the mode. One retry from a fresh read, then `connection_changed`. Two
+ * first connects that race are last-writer-wins: the loser's create collides,
+ * its retry finds the winner's row and replaces it, and both writes are
+ * audited and emailed (D6, "retried once from the read").
+ */
+export async function putStripeConnectionKey(
+  organizationId: string,
+  key: string,
+  keyLast4: string,
+  observed: StripeConnectionWriteRow | null,
+): Promise<StripeConnectionWrite<"connect" | "replace">> {
+  const cipherKey = config.STRIPE_CONNECTION_KEY;
+  if (!cipherKey) return NO_KEY;
+  const credentialCiphertext = encryptStripeConnectionValue(key, organizationId, "credential", cipherKey);
+  const mayCreate = observed === null;
+
+  let row: StripeConnectionWriteRow | null | "changed" | "live" = observed;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    if (attempt > 0) row = await reread(organizationId);
+    if (row === "changed") return CHANGED;
+    if (row === "live") return LIVE_UNAVAILABLE;
+    const now = new Date();
+    if (row === null) {
+      if (!mayCreate) return CHANGED;
+      try {
+        await store(() =>
+          prisma.stripeConnection.create({
+            data: {
+              organizationId,
+              mode: "test",
+              keyLast4,
+              credentialCiphertext,
+              webhookToken: mintWebhookToken(),
+              webhookSecretCiphertext: null,
+              liveAt: null,
+              updatedAt: now,
+            },
+            select: { id: true },
+          }),
+        );
+        return {
+          kind: "connect",
+          saved: savedOf("test", false, null, now),
+          audit: { mode: "test", last4: keyLast4 },
+        };
+      } catch (err) {
+        if (err instanceof StripeConnectionStoreError && err.uniqueViolation) continue;
+        throw err;
+      }
+    }
+    if (attempt > 0 && modeMoved(row, observed)) return CHANGED;
+    const clearsSecret = row.mode === "live";
+    const written = await writeIfUnchanged(organizationId, row.updatedAt, {
+      mode: "test",
+      keyLast4,
+      credentialCiphertext,
+      liveAt: null,
+      ...(clearsSecret && { webhookSecretCiphertext: null }),
+      updatedAt: now,
+    });
+    if (written) {
+      return {
+        kind: "replace",
+        saved: savedOf("test", clearsSecret ? false : row.webhookSecretSet, null, now),
+        audit: { mode: "test", last4: keyLast4 },
+      };
+    }
+  }
+  return CHANGED;
+}
+
+/**
+ * Go live (K5): the restricted live key, the mode, the go-live time and the
+ * secret bound to `webhook-secret:live`, in one compare-and-swap. A row
+ * already live takes the same write, which is how a live key is rotated
+ * without returning to test.
+ */
+export async function goLiveStripeConnection(
+  organizationId: string,
+  key: string,
+  keyLast4: string,
+  webhookSecret: string,
+  now: Date,
+  observed: StripeConnectionWriteRow | null,
+): Promise<StripeConnectionWrite<"go_live">> {
+  const cipherKey = config.STRIPE_CONNECTION_KEY;
+  if (!cipherKey) return NO_KEY;
+  if (observed === null) return REQUIRED;
+  const data: StoredFields = {
+    mode: "live",
+    keyLast4,
+    credentialCiphertext: encryptStripeConnectionValue(key, organizationId, "credential", cipherKey),
+    webhookSecretCiphertext: encryptStripeConnectionValue(
+      webhookSecret,
+      organizationId,
+      "webhook-secret:live",
+      cipherKey,
+    ),
+    liveAt: now,
+    updatedAt: now,
+  };
+
+  let row: StripeConnectionWriteRow | null | "changed" | "live" = observed;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    if (attempt > 0) row = await reread(organizationId);
+    if (row === null || row === "changed") return CHANGED;
+    if (row === "live") return LIVE_UNAVAILABLE;
+    // Each attempt writes its own `updatedAt`, so the swap's version key only
+    // moves forward even when the probe ran long; `liveAt` is the caller's.
+    const updatedAt = new Date();
+    if (await writeIfUnchanged(organizationId, row.updatedAt, { ...data, updatedAt })) {
+      return {
+        kind: "go_live",
+        saved: savedOf("live", true, now, updatedAt),
+        audit: { mode: "live", last4: keyLast4 },
+      };
+    }
+  }
+  return CHANGED;
+}
+
+/**
+ * Set the webhook secret, bound to the row's own mode. The compare-and-swap
+ * and the retry's mode check mean a mode change in between answers
+ * `connection_changed` and never binds the secret to the other mode.
+ */
+export async function setStripeWebhookSecret(
+  organizationId: string,
+  webhookSecret: string,
+  observed: StripeConnectionWriteRow | null,
+): Promise<StripeConnectionWrite<"webhook_secret">> {
+  const cipherKey = config.STRIPE_CONNECTION_KEY;
+  if (!cipherKey) return NO_KEY;
+  if (observed === null) return REQUIRED;
+
+  let row: StripeConnectionWriteRow | null | "changed" | "live" = observed;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    if (attempt > 0) row = await reread(organizationId);
+    if (row === null || row === "changed") return CHANGED;
+    if (row === "live") return LIVE_UNAVAILABLE;
+    if (modeMoved(row, observed)) return CHANGED;
+    const now = new Date();
+    const written = await writeIfUnchanged(organizationId, row.updatedAt, {
+      webhookSecretCiphertext: encryptStripeConnectionValue(
+        webhookSecret,
+        organizationId,
+        secretField(row.mode),
+        cipherKey,
+      ),
+      updatedAt: now,
+    });
+    if (written) {
+      return {
+        kind: "webhook_secret",
+        saved: savedOf(row.mode, true, row.liveAt, now),
+        audit: { mode: row.mode, last4: row.keyLast4 },
+      };
+    }
+  }
+  return CHANGED;
+}
+
+/**
+ * Reset the webhook (D6 call 6): a new token and no secret, so the previous
+ * URL is `not-found` from this moment. Needs no deployment key — it only
+ * takes exposure away. Keyed on the `updatedAt` the caller read, so the mode
+ * it answers and audits is the mode it reset, and a row that went live in
+ * between is never reset from a build that is not production (D3); a miss is
+ * re-read and retried once. A token collision is retried with a new token.
+ */
+export async function resetStripeWebhook(
+  organizationId: string,
+  observed: StripeConnectionWriteRow,
+): Promise<StripeConnectionWrite<"webhook_reset">> {
+  let row: StripeConnectionWriteRow | null | "changed" | "live" = observed;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    if (attempt > 0) row = await reread(organizationId);
+    if (row === null) return REQUIRED;
+    if (row === "changed") return CHANGED;
+    if (row === "live") return LIVE_UNAVAILABLE;
+    const current = row;
+    const now = new Date();
+    try {
+      const { count } = await store(() =>
+        prisma.stripeConnection.updateMany({
+          where: { organizationId, updatedAt: current.updatedAt },
+          data: { webhookToken: mintWebhookToken(), webhookSecretCiphertext: null, updatedAt: now },
+        }),
+      );
+      if (count > 0) {
+        return {
+          kind: "webhook_reset",
+          saved: savedOf(current.mode, false, current.liveAt, now),
+          audit: { mode: current.mode, last4: current.keyLast4 },
+        };
+      }
+    } catch (err) {
+      if (!(err instanceof StripeConnectionStoreError && err.uniqueViolation)) throw err;
+    }
+  }
+  return CHANGED;
+}
+
+/**
+ * Disconnect (D6 call 7, C8): the row and its token are gone at once. The
+ * Organization's enabled set and its workspaces' shown sets stay. Keyed on
+ * the `updatedAt` the caller read, so the `remove` audit row and email name
+ * the mode and last four of the row actually deleted, and a row that went
+ * live in between is never deleted from a build that is not production (D3);
+ * a miss is re-read and retried once.
+ */
+export async function deleteStripeConnection(
+  organizationId: string,
+  observed: StripeConnectionWriteRow,
+): Promise<
+  | { kind: "removed"; audit: StripeConnectionAudit }
+  | { kind: "absent" }
+  | { kind: "connection_changed" | "live_mode_unavailable" }
+> {
+  let row: StripeConnectionWriteRow | null | "changed" | "live" = observed;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    if (attempt > 0) row = await reread(organizationId);
+    if (row === null) return { kind: "absent" };
+    if (row === "changed") return CHANGED;
+    if (row === "live" || (row.mode === "live" && !isProductionBuild())) return LIVE_UNAVAILABLE;
+    const current = row;
+    const { count } = await store(() =>
+      prisma.stripeConnection.deleteMany({ where: { organizationId, updatedAt: current.updatedAt } }),
+    );
+    if (count > 0) return { kind: "removed", audit: { mode: current.mode, last4: current.keyLast4 } };
+  }
+  return CHANGED;
+}
+
+// ─── The token lookup (D11, W1, W2) ─────────────────────────────────────────
+
+export type StripeWebhookConnection =
+  | { kind: "not-found" }
+  | { kind: "not-configured"; organizationId: string; mode: StripeConnectionMode }
+  | { kind: "unreadable"; organizationId: string }
+  | { kind: "ok"; organizationId: string; mode: StripeConnectionMode; webhookSecret: string };
+
+/**
+ * The lookup #8861's receiver calls with the token from its path. A token
+ * that is not a minted shape is `not-found` with no read; a deleted row's or
+ * a reset row's old token is `not-found` from the moment the write commits.
+ * A live row on a non-production build is `unreadable` without decrypting
+ * (D3, SEC-8907-3).
+ */
+export async function findStripeConnectionByWebhookToken(
+  token: string,
+): Promise<StripeWebhookConnection> {
+  if (!WEBHOOK_TOKEN_RE.test(token)) return { kind: "not-found" };
+  const row = await store(() =>
+    prisma.stripeConnection.findUnique({
+      where: { webhookToken: token },
+      select: { organizationId: true, mode: true, webhookSecretCiphertext: true },
+    }),
+  );
+  if (row === null) return { kind: "not-found" };
+  const { organizationId } = row;
+  if (!isMode(row.mode)) {
+    logUnreadableRow(organizationId);
+    return { kind: "unreadable", organizationId };
+  }
+  if (row.webhookSecretCiphertext === null) {
+    return { kind: "not-configured", organizationId, mode: row.mode };
+  }
+  if (row.mode === "live" && !isProductionBuild()) return { kind: "unreadable", organizationId };
+  const webhookSecret = decryptStripeConnectionValue(
+    row.webhookSecretCiphertext,
+    organizationId,
+    secretField(row.mode),
+  );
+  if (webhookSecret === null) {
+    logUnreadableValue(organizationId);
+    return { kind: "unreadable", organizationId };
+  }
+  return { kind: "ok", organizationId, mode: row.mode, webhookSecret };
+}
+
+// ─── The use-time client (D12, K6, K7) ──────────────────────────────────────
+
+type ConnectionClient = NonNullable<ReturnType<typeof stripeClientForConnection>>;
+
+export type StripeConnectionClient =
+  | { kind: "none" }
+  | { kind: "unusable" }
+  | { kind: "ok"; client: ConnectionClient; mode: StripeConnectionMode };
+
+/**
+ * A client built from the Organization's own key, in its own mode — what
+ * #8054's catalog source and #8861's checkout call. A live row on a
+ * non-production build is `unusable` before any decrypt (D3); so is a key
+ * that does not decrypt and one the factory refuses for the row's mode.
+ * Nothing is cached beyond the call (C8), and there is never a fallback to
+ * the deployment's env key.
+ */
+export async function stripeClientForOrganization(
+  organizationId: string,
+): Promise<StripeConnectionClient> {
+  const row = await store(() =>
+    prisma.stripeConnection.findUnique({
+      where: { organizationId },
+      select: { credentialCiphertext: true, mode: true, liveAt: true },
+    }),
+  );
+  if (row === null) return { kind: "none" };
+  if (!isMode(row.mode)) {
+    logUnreadableRow(organizationId);
+    return { kind: "unusable" };
+  }
+  if (row.mode === "live" && !isProductionBuild()) return { kind: "unusable" };
+  const key = decryptStripeConnectionValue(row.credentialCiphertext, organizationId, "credential");
+  if (key === null) {
+    logUnreadableValue(organizationId);
+    return { kind: "unusable" };
+  }
+  const client = stripeClientForConnection({ organizationId, key, mode: row.mode, liveAt: row.liveAt });
+  if (client === null) return { kind: "unusable" };
+  return { kind: "ok", client, mode: row.mode };
+}
+
+// ─── The rekey walk (D13, C10) ──────────────────────────────────────────────
+
+export type StripeConnectionsRekeyResult =
+  | {
+      ok: true;
+      scanned: number;
+      current: number;
+      rekeyed: number;
+      changed: number;
+      unreadable: number;
+      remaining: number;
+    }
+  | { ok: false; reason: "key_not_configured" | "not_production" };
+
+type FieldState = { ok: "current" } | { ok: "previous"; plaintext: string } | { ok: false };
+
+function fieldState(stored: string, organizationId: string, field: StripeConnectionField): FieldState {
+  if (decryptUnder(stored, organizationId, field, config.STRIPE_CONNECTION_KEY) !== null) {
+    return { ok: "current" };
+  }
+  const plaintext = decryptUnder(stored, organizationId, field, config.STRIPE_CONNECTION_KEY_PREVIOUS);
+  return plaintext === null ? { ok: false } : { ok: "previous", plaintext };
+}
+
+/**
+ * Re-encrypt every row still under the previous key with the current one.
+ * A row whose every value is current is untouched; a rekeyed row keeps the
+ * `updatedAt` it had, so an owner's "updated" date never moves for a
+ * rotation; a row an owner wrote in between is left alone (`changed`); a
+ * value under neither key is `unreadable` and untouched. Idempotent: a second
+ * run rekeys nothing. `remaining` counts only what another run could rekey.
+ *
+ * It runs on a production build only (`not_production` otherwise, nothing
+ * read): a walk from a preview or a development machine pointed at
+ * production's database with another key would re-encrypt every connection
+ * under a key production lacks (D3), and one that skipped live rows would
+ * report `remaining=0` while they were still under the previous key.
+ */
+export async function rekeyStripeConnections(
+  { pageSize = 100 }: { pageSize?: number } = {},
+): Promise<StripeConnectionsRekeyResult> {
+  const take = Math.max(1, Math.floor(pageSize));
+  const cipherKey = config.STRIPE_CONNECTION_KEY;
+  if (!cipherKey) return { ok: false, reason: "key_not_configured" };
+  if (!isProductionBuild()) return { ok: false, reason: "not_production" };
+  const counts = { scanned: 0, current: 0, rekeyed: 0, changed: 0, unreadable: 0 };
+
+  let lastId: string | undefined;
+  for (;;) {
+    const after = lastId;
+    const page = await store(() =>
+      prisma.stripeConnection.findMany({
+        where: after === undefined ? {} : { id: { gt: after } },
+        orderBy: { id: "asc" },
+        take,
+        select: {
+          id: true,
+          organizationId: true,
+          mode: true,
+          credentialCiphertext: true,
+          webhookSecretCiphertext: true,
+          updatedAt: true,
+        },
+      }),
+    );
+    for (const row of page) {
+      counts.scanned += 1;
+      const outcome = await rekeyRow(row, cipherKey);
+      counts[outcome] += 1;
+    }
+    if (page.length < take) break;
+    lastId = page[page.length - 1]!.id;
+  }
+  return { ok: true, ...counts, remaining: counts.changed };
+}
+
+async function rekeyRow(
+  row: {
+    organizationId: string;
+    mode: string;
+    credentialCiphertext: string;
+    webhookSecretCiphertext: string | null;
+    updatedAt: Date;
+  },
+  cipherKey: Buffer,
+): Promise<"current" | "rekeyed" | "changed" | "unreadable"> {
+  const { organizationId } = row;
+  if (!isMode(row.mode)) {
+    logUnreadableRow(organizationId);
+    return "unreadable";
+  }
+  const secret = secretField(row.mode);
+  const credential = fieldState(row.credentialCiphertext, organizationId, "credential");
+  const webhook =
+    row.webhookSecretCiphertext === null
+      ? ({ ok: "current" } as const)
+      : fieldState(row.webhookSecretCiphertext, organizationId, secret);
+  if (credential.ok === false || webhook.ok === false) {
+    logUnreadableValue(organizationId);
+    return "unreadable";
+  }
+  if (credential.ok === "current" && webhook.ok === "current") return "current";
+
+  const written = await writeIfUnchanged(organizationId, row.updatedAt, {
+    ...(credential.ok === "previous" && {
+      credentialCiphertext: encryptStripeConnectionValue(
+        credential.plaintext,
+        organizationId,
+        "credential",
+        cipherKey,
+      ),
+    }),
+    ...(webhook.ok === "previous" && {
+      webhookSecretCiphertext: encryptStripeConnectionValue(
+        webhook.plaintext,
+        organizationId,
+        secret,
+        cipherKey,
+      ),
+    }),
+    updatedAt: row.updatedAt,
+  });
+  return written ? "rekeyed" : "changed";
+}
+
+/** The bin's one output line: counts only, never a key or a row id. */
+export function formatRekeyReport(result: StripeConnectionsRekeyResult): string {
+  if (!result.ok) return `[stripe-connections-rekey] ${result.reason}`;
+  const { scanned, current, rekeyed, changed, unreadable, remaining } = result;
+  return `[stripe-connections-rekey] scanned=${scanned} current=${current} rekeyed=${rekeyed} changed=${changed} unreadable=${unreadable} remaining=${remaining}`;
+}