create-ailk 0.24.0 → 0.26.0

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

@@ -1,1083 +0,0 @@
-/**
- * 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 { isModuleEnabled } from "../../config/modules.js";
-import { prisma } from "../../lib/prisma.js";
-import {
-  classifyStripeKey,
-  getStripeClient,
-  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>;
-
-/**
- * The read-only source the GET answers when the Organization has NO stored
- * connection but OWNS the Stripe key in this API process's environment
- * (#9285 AC-3, AC-8): the deployment's own `STRIPE_SECRET_KEY`. It names the
- * mode the key's class implies and nothing else — never the key, its last
- * four or a webhook path — and a publishable or unrecognised value is no
- * source at all. A stored connection always wins; the caller decides that,
- * not this function.
- */
-export type StripeEnvironmentSource = { source: "environment"; mode: StripeConnectionMode };
-
-/** The mode the process's own Stripe key implies, or `null` for no usable class. */
-function environmentKeyMode(): StripeConnectionMode | null {
-  switch (classifyStripeKey(process.env["STRIPE_SECRET_KEY"])) {
-    case "restricted-test":
-    case "secret-test":
-      return "test";
-    case "restricted-live":
-    case "secret-live":
-      return "live";
-    default:
-      return null;
-  }
-}
-
-/**
- * Whether this Organization owns the environment key (#9285 AC-8). Without
- * the multi-tenant module a deployment has one Organization, and it owns the
- * key. With it, only the Organization named by `STRIPE_ENV_ORGANIZATION_ID`
- * does; unset, blank or naming no Organization, nobody does (fail closed), so
- * one tenant's Offerings can never sell through another's account.
- */
-export function organizationOwnsEnvironmentStripeKey(organizationId: string): boolean {
-  if (!isModuleEnabled("multi-tenant")) return true;
-  const owner = process.env["STRIPE_ENV_ORGANIZATION_ID"]?.trim();
-  return owner !== undefined && owner !== "" && owner === organizationId;
-}
-
-/** The environment source for this Organization, or `null` when it has none to see. */
-export function getEnvironmentStripeSource(organizationId: string): StripeEnvironmentSource | null {
-  if (!organizationOwnsEnvironmentStripeKey(organizationId)) return null;
-  const mode = environmentKeyMode();
-  return mode === null ? null : { source: "environment", mode };
-}
-
-/**
- * The connection state Offerings sells on (#9285 AC-9): the stored summary
- * first, else `"environment"` for an Organization that owns the environment
- * key, else `null`. `"unreadable"` stays a corrupt stored row. The one
- * "is this Organization connected" read every Offerings path shares.
- */
-export async function getOfferingsConnectionState(
-  organizationId: string,
-): Promise<StripeConnectionSummary | "unreadable" | "environment" | null> {
-  const stored = await getStripeConnectionSummary(organizationId);
-  if (stored !== null) return stored;
-  return getEnvironmentStripeSource(organizationId) === null ? null : "environment";
-}
-
-/** 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 };
-
-/**
- * The environment key's client for the Organization that owns it (#9285
- * AC-9), through `getStripeClient()` — the allow-list the env checkout path
- * already meets (a test key, or the restricted live key the process admitted
- * at boot). A key it refuses is `unusable`, not `none`: the Organization owns
- * a key it cannot sell through.
- */
-function environmentClientFor(organizationId: string): StripeConnectionClient {
-  const source = getEnvironmentStripeSource(organizationId);
-  if (source === null) return { kind: "none" };
-  try {
-    return { kind: "ok", client: getStripeClient(), mode: source.mode };
-  } catch {
-    return { kind: "unusable" };
-  }
-}
-
-/**
- * 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). With no stored row, an
- * Organization that owns the deployment's environment key (#9285 AC-8) is sold
- * through it, by the same chokepoint the env checkout path uses; no other
- * Organization ever falls back to it.
- */
-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 environmentClientFor(organizationId);
-  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}`;
-}