@open-everywhere/core 0.1.0

package/agent/credentials/kv-vault.ts

@@ -0,0 +1,180 @@
+// The ENCRYPTED KV VAULT (OPE-88) — a small, reusable read/write/lock surface over the `db`
+// broker's `stored_credential` machinery, for connector-plane adapters that must persist their
+// OWN secret material (an own-rolled OAuth adapter's DCR client registration + access/refresh
+// tokens) rather than resolve a single operator-set value like the read-only CredentialBroker.
+//
+// WHY THIS EXISTS. The db credential broker (credentials/db-broker.ts) exposes a READ-only
+// getSecret and a host-only storeDbSecret keyed to the intake webhook. The own-rolled OAuth
+// adapter needs a general per-(connector,subject) encrypted JSON store PLUS a single-flight lock
+// for rotation-safe token refresh. Rather than invent a second crypto path (the brief forbids
+// that) or a second table, this vault REUSES db-broker's AES-256-GCM encrypt/decrypt and the
+// `stored_credential` (org, ref) → ciphertext store verbatim — the value is just a JSON blob the
+// adapter stringifies. One crypto path, one at-rest store, one fail-closed key contract.
+//
+// BOUNDARY. This lives in CORE (it reaches core internals — the operational store, deploymentOrg,
+// the db-broker crypto — directly) and is re-exported through the adapter-api barrel so the
+// own-rolled OAuth adapter composes its OAuth-specific record shapes on top WITHOUT deep-importing
+// core. The adapter owns OAuth semantics; core owns crypto + persistence + the process lock.
+//
+// SINGLE-FLIGHT — TWO LAYERS.
+//
+//   1. `withLock` — a per-key in-process async mutex. It serialises the refreshers that pile up
+//      WITHIN a process (concurrent tool calls in one eve turn). Cheap first layer.
+//
+//   2. `claim`/`releaseClaim` (OPE-91) — a CROSS-PROCESS single-flight over the SAME row, because the
+//      mutex can't span instances (the callback-route process vs the eve-workflow process, or two
+//      concurrent Vercel invocations). A Postgres advisory lock is unusable here: the PgClient port is
+//      a single `query()` over a connection pool with NO transaction/session pinning, so a held
+//      `pg_advisory_*` lock could unlock on a different pooled connection (silently never releasing, or
+//      releasing another caller's lock). Instead we do an ATOMIC ROW CLAIM — a compare-and-set on
+//      dedicated claim columns of the vault row (claimStoredCredential): the winner refreshes, losers
+//      wait and adopt. A crashed winner never wedges the row — the claim is a lease (claimed_at) that a
+//      later claimant may steal once `leaseTtlMs` has elapsed. The claim state carries NO secret
+//      material (a random id + timestamps), and lives in its OWN columns precisely because the stored
+//      value is an OPAQUE ciphertext envelope that a CAS cannot reach inside. The adapter's
+//      rotation-aware re-read + invalid_grant recovery remains as the last-resort net.
+
+import { encryptCredential, decryptCredential, DB_BROKER } from "./db-broker.js";
+import { getOperationalStore } from "../operational/provider.js";
+import { deploymentOrg } from "../identity/binding.js";
+import type { StoredCredentialRow } from "../operational/store.js";
+
+/** The read/write/lock surface an encrypted-KV consumer (the OAuth adapter's token vault) rides. */
+export interface EncryptedKvVault {
+  /** Decrypted plaintext stored under `ref` for the deployment org, or null when none is stored. */
+  read(ref: string): Promise<string | null>;
+  /** Encrypt `plaintext` (AES-256-GCM, via the db broker's single crypto path) and upsert it under
+   *  `ref`. `labels` are display-only metadata (connector/domain/createdBy) — never the value. */
+  write(ref: string, plaintext: string, labels?: { connector?: string; domain?: string; createdBy?: string }): Promise<void>;
+  /**
+   * DESTROY whatever is stored under `ref` (OPE-287). Returns true iff a row went; idempotent.
+   *
+   * This is the at-rest half of a purge. Severing REACHABILITY (nothing derives the subject that
+   * keys the row any more) is not the same as the credential being DEAD — the ciphertext, and the
+   * refresh token inside it, survive a reachability fence. Only this makes it die locally; the
+   * VENDOR-side half (RFC 7009) is the adapter's job, because only the adapter knows the record's
+   * OAuth shape and which endpoint revokes it. Callers take {@link EncryptedKvVault.withLock} on the
+   * same key a refresh would, so a purge cannot interleave with a read-modify-write in this process.
+   */
+  delete(ref: string): Promise<boolean>;
+  /**
+   * Every ref stored under `refPrefix` for the deployment org, ref-ascending (OPE-1025). REFS
+   * ONLY — no ciphertext is read, so a caller that only wants to know WHICH rows exist never
+   * decrypts one.
+   *
+   * THE PREFIX IS REQUIRED, and that is the point. The port beneath allows an unfiltered walk for
+   * the out-of-band operator sweep, but a consumer riding this vault owns exactly one ref
+   * namespace and must never learn the names of credentials outside it. Demanding the prefix here
+   * makes that structural rather than a convention: there is no way to spell "list everything"
+   * through this interface. The prefix narrows in the SQL predicate (see
+   * `OperationalStore.listStoredCredentialRefs`), and it is matched LITERALLY — a `%` or `_` in it
+   * matches itself.
+   *
+   * WHY A CONSUMER NEEDS IT. Records this vault holds can become residue that no composed ref
+   * reaches: the OAuth adapter's pending-authorization rows are keyed by a RANDOM state, so once
+   * the consent window closes nothing can name them again. Enumerating its own namespace is the
+   * only way such a consumer can clean up after itself.
+   */
+  listRefs(refPrefix: string): Promise<readonly string[]>;
+  /** Run `fn` while holding a per-`key` exclusive in-process lock (single-flight token refresh). */
+  withLock<T>(key: string, fn: () => Promise<T>): Promise<T>;
+  /**
+   * CROSS-PROCESS single-flight: atomically claim `ref`'s row (compare-and-set on dedicated claim
+   * columns — the ciphertext payload is opaque, so the claim can't live inside it). Returns true IFF
+   * THIS caller won. `nowMs` stamps the claim AND sets the lease-expiry boundary — a claim older than
+   * `leaseTtlMs` is stealable, so a crashed winner never wedges the row. A missing row returns false.
+   */
+  claim(ref: string, claimId: string, nowMs: number, leaseTtlMs: number): Promise<boolean>;
+  /** Release a claim on `ref` IFF `claimId` still holds it (guarded — never clears a stealer's claim). */
+  releaseClaim(ref: string, claimId: string): Promise<void>;
+}
+
+/** Injectable seams — every live default reaches a core internal, so the adapter never does. Tests
+ *  substitute an in-memory store + fixed clock; the live default is the real sqlite/postgres store. */
+export interface EncryptedKvVaultDeps {
+  readonly getStore?: () => Pick<ReturnType<typeof getOperationalStore>, "getStoredCredential" | "putStoredCredential" | "deleteStoredCredential" | "listStoredCredentialRefs" | "claimStoredCredential" | "releaseStoredCredential">;
+  readonly org?: () => string;
+  readonly encrypt?: (plaintext: string) => string;
+  readonly decrypt?: (envelope: string) => string;
+}
+
+// A per-key async mutex, MODULE-level so single-flight holds across the process even if two vault
+// instances are constructed. `lockTails` maps a key to the tail of its promise chain; each caller
+// appends itself and awaits its predecessor, so callers for the same key run strictly one at a time.
+const lockTails = new Map<string, Promise<void>>();
+
+async function withKeyedLock<T>(key: string, fn: () => Promise<T>): Promise<T> {
+  const prev = lockTails.get(key) ?? Promise.resolve();
+  let release!: () => void;
+  const mine = new Promise<void>((r) => {
+    release = r;
+  });
+  const tail = prev.then(() => mine);
+  lockTails.set(key, tail);
+  await prev; // wait my turn — the predecessor's `mine` has resolved
+  try {
+    return await fn();
+  } finally {
+    release();
+    // GC: drop the entry iff I'm still the tail (no successor queued after me).
+    if (lockTails.get(key) === tail) lockTails.delete(key);
+  }
+}
+
+/**
+ * Build an {@link EncryptedKvVault} over the db broker's crypto + the operational `stored_credential`
+ * store. Fail-closed on a missing/bad AES key is INHERITED from encrypt/decrypt (they throw before
+ * any store touch). The plaintext leaves this module only as ciphertext; it is never logged.
+ */
+export function encryptedKvVault(deps: EncryptedKvVaultDeps = {}): EncryptedKvVault {
+  const store = deps.getStore ?? getOperationalStore;
+  const org = deps.org ?? deploymentOrg;
+  const encrypt = deps.encrypt ?? encryptCredential;
+  const decrypt = deps.decrypt ?? decryptCredential;
+  return {
+    async read(ref) {
+      const row = await store().getStoredCredential(org(), ref);
+      if (!row) return null;
+      return decrypt(row.ciphertext);
+    },
+    async write(ref, plaintext, labels) {
+      const ciphertext = encrypt(plaintext); // throws (fail closed) on a bad key BEFORE any store write
+      const rec: StoredCredentialRow = {
+        ref,
+        ciphertext,
+        ...(labels?.connector ? { connector: labels.connector } : {}),
+        ...(labels?.domain ? { domain: labels.domain } : {}),
+        createdBy: labels?.createdBy ?? DB_BROKER,
+        createdAt: new Date().toISOString(),
+      };
+      await store().putStoredCredential(org(), rec);
+    },
+    async delete(ref) {
+      // No crypto on this path by design: destroying the envelope must not depend on the AES key
+      // being present or valid. `write`/`read` fail closed on a bad key — a purge that inherited
+      // that would leave the very credential an operator is trying to destroy in place precisely
+      // when the key has been rotated out from under it.
+      return store().deleteStoredCredential(org(), ref);
+    },
+    async listRefs(refPrefix) {
+      // No crypto on this path either: the enumeration returns refs, and a caller that wanted a
+      // value would go through `read`. A caller must not be able to spell "everything", so an
+      // EMPTY prefix is refused rather than passed down as an unfiltered walk (the port reads an
+      // empty prefix as "no prefix", which is exactly the wrong default here).
+      if (!refPrefix) throw new Error("encryptedKvVault.listRefs: a non-empty ref prefix is required — this interface cannot enumerate the whole credential store.");
+      return store().listStoredCredentialRefs(org(), refPrefix);
+    },
+    withLock: withKeyedLock,
+    async claim(ref, claimId, nowMs, leaseTtlMs) {
+      // Derive the two ISO stamps the store CAS compares: the claim time, and the boundary before
+      // which an existing claim counts as an abandoned (stealable) lease. Kept here (not in the store)
+      // so the store stays a pure timestamp comparator with no clock/TTL policy of its own.
+      const claimedAtIso = new Date(nowMs).toISOString();
+      const staleBeforeIso = new Date(nowMs - leaseTtlMs).toISOString();
+      return store().claimStoredCredential(org(), ref, claimId, claimedAtIso, staleBeforeIso);
+    },
+    async releaseClaim(ref, claimId) {
+      await store().releaseStoredCredential(org(), ref, claimId);
+    },
+  };
+}

package/agent/credentials/operator-secrets.ts

@@ -0,0 +1,396 @@
+// OPERATOR-SIDE SECRETS INTAKE (OPE-408 phase 1) — the ONE implementation behind two skins:
+// the `oe secret` CLI (scripts/oe-secret.ts) and the `secret_set`/`secret_list`/`secret_rm` tools on
+// the ops MCP server (agent/ops/server.ts). Both run on the OPERATOR'S machine, both call the
+// functions below, and neither adds a second crypto path: every write goes through
+// `storeDbSecret` (db-broker.ts, AES-256-GCM, fail-closed) exactly like the chat-intake flow.
+//
+// WHY OPERATOR-SIDE AND DIRECT-TO-DB. Tommy's ruling (OPE-408, 2026-08-12): db-over-env is the
+// DEFAULT home for secrets, and the route in must work with ZERO channel env vars — no bootstrap
+// channel, no admin token to mint before the first surface exists, no deployed HTTP endpoint. The
+// trust root is therefore the env the operator ALREADY holds to run any of this: `DATABASE_URL` +
+// `OE_CREDENTIAL_ENCRYPTION_KEY`; the org keying the rows is tracked config, or the `org` argument.
+// Nothing here is reachable from the
+// deployed agent: these are plain exported functions, not tools, not control-plane verbs.
+//
+// 🔴 WRITE-ONLY IS ABSOLUTE. There is no `oe secret get`, no read-back tool, and no function here
+// that returns a stored VALUE to a caller outside the resolution seam:
+//   • `setOperatorSecret` takes a plaintext and returns only {name, bytes, at} — a byte COUNT, never
+//     a prefix, never a masked rendering (a prefix of an API key is a real disclosure).
+//   • `listOperatorSecrets` projects ref/setBy/setAt. The ciphertext column is read (the store has no
+//     metadata-only projection) and DROPPED inside this function — it never leaves.
+//   • `getOperatorSecret` is the RESOLUTION seam the runtime will use (step 4 of the OPE-408
+//     migration order), not an operator verb. No skin exposes it.
+//
+// AUDIT — DELIBERATELY NOT ON THE HASH CHAIN. `appendAudit` chains each row to its predecessor's sha
+// under an IN-PROCESS per-org lock (audit/chain.ts): "across SEPARATE serverless instances the lock
+// does not span processes, so two instances appending for the same org concurrently can still fork".
+// An operator CLI is by construction a separate process from the deployed agent, so appending here
+// would manufacture exactly the fork the verifier reports as a chain break — a self-inflicted
+// integrity alarm indistinguishable at a glance from tampering. So operator-side writes are recorded
+// UNCHAINED, on the row itself: `created_by` carries the provenance token (`operator:cli` /
+// `operator:ops-mcp`, plus an optional operator label) and `created_at` the write time, both surfaced
+// by `oe secret list`. The chat-intake path keeps its `credential.stored` audit row — it runs
+// in-process, inside the deployed agent, where the chain is sound.
+
+import { CredentialError } from "../access/credentials.js";
+import { deploymentOrg } from "../identity/binding.js";
+import { credentialKeyArmed, decryptCredential, storeDbSecret, CREDENTIAL_KEY_ENV } from "./db-broker.js";
+import { getOperationalStore } from "../operational/provider.js";
+import { reservedRefNamespace, reservedRefRefusal } from "./reserved-refs.js";
+
+/** Provenance token stamped into `created_by` by the `oe secret` CLI skin. */
+export const SET_BY_CLI = "operator:cli";
+/** Provenance token stamped into `created_by` by the ops-MCP skin. */
+export const SET_BY_OPS_MCP = "operator:ops-mcp";
+
+/** The env names an operator-side skin may lift out of a `.env` file into `process.env` — the
+ *  root-of-trust set and nothing else. A skin that copied the whole file would quietly re-create the
+ *  env-as-secret-home this ticket exists to delete (and could shadow a stored secret with a stale
+ *  env var mid-migration). Additive-only, and every addition must be a var the STORE needs to open. */
+// 🔴 THE ORG NAME LEFT THIS LIST WITH ITS READ (OPE-1545). The org is tracked config
+// (`agent/identity/surfaces.ts`), so no code reads it from the environment and lifting the name
+// would open nothing. A skin that must key rows under another org passes `--org` / the `org`
+// argument.
+export const SECRET_STORE_ENV_KEYS: readonly string[] = [
+  "DATABASE_URL",
+  "OE_CREDENTIAL_ENCRYPTION_KEY",
+  "OE_OPERATIONAL_PROVIDER",
+  "OE_PGLITE_DIR",
+  "OE_SQLITE_PATH",
+] as const;
+
+/** What a write reports back. `bytes` is a COUNT — the only fact about a value any skin may print. */
+export interface SecretWriteResult {
+  readonly name: string;
+  /** UTF-8 byte length of the stored value. Never a prefix, never a hash of the value. */
+  readonly bytes: number;
+  /** ISO-8601 write time (the row's `created_at`). */
+  readonly at: string;
+  /** True when a value was already stored under this name (this write replaced it). */
+  readonly replaced: boolean;
+}
+
+/** One row of `oe secret list` — names and provenance ONLY. */
+export interface SecretListEntry {
+  readonly name: string;
+  /** The row's `created_by`: an operator provenance token, or the principal id of a chat intake. */
+  readonly setBy: string;
+  /** ISO-8601 of the last write (the store upserts `created_at`, so this is "last set"). */
+  readonly setAt: string;
+  /** True for a HOST-MINTED internal ref (`hook:`, `oe-oauth:`, `notion-handshake:`) — shown only
+   *  under `--all`, never settable or removable through these functions. */
+  readonly internal: boolean;
+}
+
+/** Options every function here shares. `org` defaults to the declared deployment org. */
+export interface OperatorSecretOptions {
+  readonly org?: string;
+}
+
+const MAX_NAME_LENGTH = 200;
+
+/**
+ * Why `name` is not a usable credential ref, or undefined when it is fine. Refuses: empty, over-long,
+ * any whitespace or control character (a name that cannot be typed back is unmanageable, and a
+ * trailing space is the classic invisible mismatch), and the reserved host-minted namespaces — the
+ * same refusal the db broker applies at READ time, applied here at WRITE time so an operator cannot
+ * plant a row the resolver will forever refuse.
+ */
+export function secretNameRefusal(name: string): string | undefined {
+  if (typeof name !== "string" || name.length === 0) return "a secret name is required (the name a credential’s secretRef points at, e.g. ACME_API_TOKEN)";
+  if (name.length > MAX_NAME_LENGTH) return `secret name is ${name.length} characters — the limit is ${MAX_NAME_LENGTH}`;
+  // Whitespace (a trailing space is the classic invisible mismatch), C0/C1 controls, and the
+  // invisible separators this repo has been bitten by (U+2028/U+2029, U+FEFF) — spelled as escapes
+  // ON PURPOSE: a raw one of these in source is exactly the class `lint:invisible-bytes` fails on.
+  if (/[\s\u0000-\u001f\u007f-\u009f\u2028\u2029\ufeff]/.test(name)) {
+    return `secret name ${JSON.stringify(name)} contains whitespace or a control/invisible character`;
+  }
+  const reserved = reservedRefNamespace(name);
+  if (reserved) return reservedRefRefusal(name, reserved);
+  return undefined;
+}
+
+/** One parsed KEY=VALUE line. */
+export interface ParsedSecretEntry {
+  readonly name: string;
+  readonly value: string;
+}
+
+/** The result of parsing a batch file: what to write, and every line that could not be read. */
+export interface ParsedSecretFile {
+  readonly entries: readonly ParsedSecretEntry[];
+  readonly errors: readonly string[];
+}
+
+/**
+ * Parse a `.env`-shaped batch file — `KEY=VALUE` per line — for `oe secret set --from-file`. This is
+ * the 30-secrets case: an operator's existing `.env.local` is exactly this format, so migrating a
+ * deployment off channel env vars is one command.
+ *
+ * Tolerated: blank lines, `#` comments, a leading `export `, `KEY = value` spacing, single- or
+ * double-quoted values (double-quoted values unescape `\n`, `\r`, `\t`, `\\`, `\"` so a one-line PEM
+ * survives; single-quoted are literal). A bare value keeps its inner spaces and drops a trailing
+ * comment ONLY when the value is quoted — an unquoted `#` is part of the value, because secrets
+ * contain `#` far more often than an operator writes a trailing comment on a secret line.
+ *
+ * Pure: no I/O, no env, no store. Every unparseable line is reported with its 1-based number rather
+ * than skipped silently — a dropped line in a 30-secret migration is a channel that mysteriously
+ * fails to boot three deploys later.
+ */
+export function parseSecretEnvFile(text: string): ParsedSecretFile {
+  const entries: ParsedSecretEntry[] = [];
+  const errors: string[] = [];
+  const seen = new Set<string>();
+  const lines = text.split(/\r?\n/);
+  for (const [i, raw] of lines.entries()) {
+    const lineNo = i + 1;
+    const line = raw.trim();
+    if (line.length === 0 || line.startsWith("#")) continue;
+    const body = line.startsWith("export ") ? line.slice("export ".length).trim() : line;
+    const eq = body.indexOf("=");
+    if (eq <= 0) {
+      errors.push(`line ${lineNo}: not a KEY=VALUE line`);
+      continue;
+    }
+    const name = body.slice(0, eq).trim();
+    const refusal = secretNameRefusal(name);
+    if (refusal) {
+      errors.push(`line ${lineNo}: ${refusal}`);
+      continue;
+    }
+    const value = unquoteEnvValue(body.slice(eq + 1).trim());
+    if (value.length === 0) {
+      errors.push(`line ${lineNo}: ${name} has an empty value — refusing (delete the line, or use \`oe secret rm ${name}\`)`);
+      continue;
+    }
+    if (seen.has(name)) {
+      errors.push(`line ${lineNo}: ${name} appears more than once — refusing rather than guessing which wins`);
+      continue;
+    }
+    seen.add(name);
+    entries.push({ name, value });
+  }
+  return { entries, errors };
+}
+
+/** Strip one layer of matching quotes; unescape only inside double quotes (dotenv's rule). */
+function unquoteEnvValue(raw: string): string {
+  if (raw.length >= 2 && raw.startsWith("'") && raw.endsWith("'")) return raw.slice(1, -1);
+  if (raw.length >= 2 && raw.startsWith('"') && raw.endsWith('"')) {
+    return raw
+      .slice(1, -1)
+      .replace(/\\n/g, "\n")
+      .replace(/\\r/g, "\r")
+      .replace(/\\t/g, "\t")
+      .replace(/\\"/g, '"')
+      .replace(/\\\\/g, "\\");
+  }
+  return raw;
+}
+
+/** Input to {@link setOperatorSecret}. `value` is handed straight to the encrypt path. */
+export interface SetOperatorSecretInput extends OperatorSecretOptions {
+  readonly name: string;
+  /** The plaintext. Encrypted immediately; never logged, returned, or measured beyond its byte count. */
+  readonly value: string;
+  /** Provenance for the row's `created_by` — {@link SET_BY_CLI} / {@link SET_BY_OPS_MCP}, optionally
+   *  suffixed by an operator label (`operator:cli:tommy`). Never a secret. */
+  readonly setBy: string;
+  /** ISO-8601 override (tests). */
+  readonly at?: string;
+}
+
+/**
+ * Encrypt + upsert ONE secret through the db broker's write path. Refuses (before touching the store)
+ * an invalid/reserved name, an empty value, or an unarmed {@link CREDENTIAL_KEY_ENV} — `storeDbSecret`
+ * itself fails closed on the key, and the pre-check exists only to give the operator the fix sentence
+ * instead of a stack trace.
+ *
+ * The returned {@link SecretWriteResult} is everything a skin is allowed to print.
+ */
+export async function setOperatorSecret(input: SetOperatorSecretInput): Promise<SecretWriteResult> {
+  const refusal = secretNameRefusal(input.name);
+  if (refusal) throw new CredentialError(refusal);
+  if (typeof input.value !== "string" || input.value.length === 0) {
+    throw new CredentialError(`refusing to store an empty value for ${JSON.stringify(input.name)} (use \`oe secret rm\` to delete it)`);
+  }
+  requireArmedKey("store");
+
+  const org = input.org ?? deploymentOrg();
+  const at = input.at ?? new Date().toISOString();
+  const existing = await getOperationalStore().getStoredCredential(org, input.name);
+  await storeDbSecret({ org, ref: input.name, plaintext: input.value, createdBy: input.setBy, at });
+  return { name: input.name, bytes: Buffer.byteLength(input.value, "utf8"), at, replaced: existing !== null };
+}
+
+/**
+ * Every stored secret's NAME + provenance. NEVER a value and never part of one — the ciphertext this
+ * function reads (the store has no metadata-only projection, and adding one would mean a second
+ * migration in two backends for a display nicety) is dropped here and never returned.
+ *
+ * Host-minted internal refs are excluded unless `includeInternal` — they are not operator-managed,
+ * `secret_set`/`secret_rm` refuse them, and listing them by default would read as an invitation.
+ */
+export async function listOperatorSecrets(
+  opts: OperatorSecretOptions & { readonly includeInternal?: boolean } = {},
+): Promise<readonly SecretListEntry[]> {
+  const org = opts.org ?? deploymentOrg();
+  const store = getOperationalStore();
+  const refs = await store.listStoredCredentialRefs(org);
+  const out: SecretListEntry[] = [];
+  for (const ref of refs) {
+    const internal = reservedRefNamespace(ref) !== undefined;
+    if (internal && !opts.includeInternal) continue;
+    const row = await store.getStoredCredential(org, ref);
+    if (!row) continue; // deleted between the enumerate and the read — nothing to report
+    out.push({ name: ref, setBy: row.createdBy, setAt: row.createdAt, internal });
+  }
+  return out;
+}
+
+/**
+ * Delete one stored secret. Returns false when there was nothing to delete (the skin says so rather
+ * than claiming a removal). Refuses a reserved/internal ref: those are host-minted material the KV
+ * vault owns, and destroying one out of band breaks an inbound webhook or an OAuth grant with no
+ * trace of why. The row IS the secret, so this is a real DELETE (the store grants it for exactly
+ * this table — see operational/postgres.ts MUTABLE_TABLE_VERBS).
+ */
+export async function removeOperatorSecret(name: string, opts: OperatorSecretOptions = {}): Promise<boolean> {
+  const refusal = secretNameRefusal(name);
+  if (refusal) throw new CredentialError(refusal);
+  return await getOperationalStore().deleteStoredCredential(opts.org ?? deploymentOrg(), name);
+}
+
+/** Where {@link getOperatorSecret} found a value. */
+export type OperatorSecretSource = "db" | "env";
+
+/** A resolved secret. `value` is the plaintext — this type never crosses a skin boundary. */
+export interface ResolvedOperatorSecret {
+  readonly value: string;
+  readonly source: OperatorSecretSource;
+}
+
+/**
+ * {@link getOperatorSecret}'s "nobody configured this name" refusal — no row in the db credential
+ * store AND no environment variable of that name.
+ *
+ * 🔴 IT IS A CLASS BECAUSE THE MESSAGES ARE NOT DISTINGUISHABLE. This is the ORDINARY state for an
+ * OPTIONAL secret, and a caller that treats optional-and-absent as silence needs to tell it from a
+ * real fault (an unarmed `OE_CREDENTIAL_ENCRYPTION_KEY`, a store that will not open) — which does
+ * make every read of that name fail and MUST be reported. Both messages contain the words "is not
+ * set", so a substring test silently swallows the fault: the Notion ingress did exactly that, and a
+ * broken credential store 401'd every delivery in total silence. Test `err instanceof
+ * OperatorSecretNotSetError`, never the message text.
+ */
+export class OperatorSecretNotSetError extends CredentialError {}
+
+let envFallbackWarned = new Set<string>();
+
+/** Test seam: forget which names have already warned about the env fallback. */
+export function resetOperatorSecretWarnings(): void {
+  envFallbackWarned = new Set<string>();
+}
+
+/**
+ * THE RULED RESOLUTION ORDER (OPE-408): **a secret in the db store wins; env is the migration
+ * on-ramp, not a parallel home.** This is the seam the hardwired `process.env.<VENDOR>_TOKEN`-class
+ * reads move onto in step 4 of the migration order; it is pinned by tests now so the order cannot
+ * drift while those call sites are converted.
+ *
+ * 🔴 IT IS NOT A SILENT FALLBACK, AND IT IS NOT A SECOND BROKER. The credential plane's fail-closed
+ * rule — a credential naming a broker resolves through THAT broker or throws (access/credentials.ts)
+ * — is untouched: `getSecretVia("db", ref)` still refuses to consult env, and nothing here is
+ * registered as a broker. This function is the OPERATOR-VAR resolver: one name, two possible homes
+ * during the migration, with the ambiguity resolved loudly:
+ *
+ *   1. reserved namespace                      → refuse (same line the db broker draws at read time)
+ *   2. a stored row EXISTS + key armed         → the stored value WINS, env is not consulted
+ *   3. a stored row EXISTS + key NOT armed     → THROW naming OE_CREDENTIAL_ENCRYPTION_KEY. We do NOT
+ *      fall back to env here: the operator stored a value (possibly a rotation) that we cannot read,
+ *      and an env var of the same name may be the RETIRED one. Injecting a stale credential silently
+ *      is the exact failure the fail-closed doctrine exists to prevent.
+ *   4. no stored row + env set                 → the env value, with a ONE-TIME per-name notice that
+ *      it is the on-ramp. There is no ambiguity to fail closed on: nothing is stored.
+ *   5. neither                                 → throw, naming both homes and the `oe secret set` fix.
+ *
+ * A store that cannot be reached at all (no DB wired — a unit test, a not-yet-provisioned box) is
+ * NOT fatal: it degrades to the env arm with a one-time notice, because "there is no store" and
+ * "the store says nothing" are the same fact for this name.
+ */
+export async function getOperatorSecret(name: string, opts: OperatorSecretOptions = {}): Promise<ResolvedOperatorSecret> {
+  const reserved = reservedRefNamespace(name);
+  if (reserved) throw new CredentialError(reservedRefRefusal(name, reserved));
+
+  const org = opts.org ?? deploymentOrg();
+  let row: { ciphertext: string } | null = null;
+  try {
+    row = await getOperationalStore().getStoredCredential(org, name);
+  } catch (err) {
+    noticeOnce(name, `[open-everywhere:credentials] secret "${name}": the operational store is unreachable (${String(err instanceof Error ? err.message : err)}) — falling back to the env var if set.`);
+  }
+
+  if (row) {
+    if (!credentialKeyArmed()) {
+      throw new CredentialError(
+        `secret "${name}" is stored in the db credential store but ${CREDENTIAL_KEY_ENV} is not set (or is malformed) — refusing ` +
+          `to fall back to the environment variable of the same name, which may be a retired value (fail closed). Set ` +
+          `${CREDENTIAL_KEY_ENV} to the base64 32-byte key this deployment stored with.`,
+      );
+    }
+    return { value: decryptCredential(row.ciphertext), source: "db" };
+  }
+
+  const fromEnv = envFallbackValue(name, process.env);
+  if (fromEnv !== undefined) {
+    noticeOnce(
+      name,
+      `[open-everywhere:credentials] secret "${name}" resolved from the environment — the db credential store is its default home. ` +
+        `Move it with \`oe secret set ${name}\` (then the env var can be deleted).`,
+    );
+    return { value: fromEnv, source: "env" };
+  }
+
+  // The ONE arm callers may treat as silence — see {@link OperatorSecretNotSetError} for why the
+  // class, not the message, is the seam.
+  throw new OperatorSecretNotSetError(
+    `secret "${name}" is not set: no row in the db credential store for org "${org}", and no environment variable of that name. ` +
+      `Store it with \`oe secret set ${name}\` (value on stdin).`,
+  );
+}
+
+/** The env fallback's value for `name`, or `undefined` when the variable is unset or empty. The ONE
+ *  place that decides what "set" means for the fallback — {@link getOperatorSecret} and
+ *  {@link operatorSecretEnvFallbackPresent} both read it, so the two cannot drift. */
+function envFallbackValue(name: string, env: NodeJS.ProcessEnv): string | undefined {
+  const value = env[name];
+  return value !== undefined && value !== "" ? value : undefined;
+}
+
+/**
+ * Whether {@link getOperatorSecret} would still answer for `name` from the ENVIRONMENT once the
+ * stored row is gone — the one arm that makes a delete less than a retirement.
+ *
+ * 🔴 PRESENCE ONLY. It answers a boolean. It never returns the value, never logs it, and never
+ * reports a length or a prefix of it, so it is safe on the operator skins (`secret_rm` reports it).
+ * It shares {@link envFallbackValue} with the resolver, so a `false` here really does mean the name
+ * fails closed.
+ */
+export function operatorSecretEnvFallbackPresent(name: string, env: NodeJS.ProcessEnv = process.env): boolean {
+  return envFallbackValue(name, env) !== undefined;
+}
+
+function noticeOnce(name: string, message: string): void {
+  if (envFallbackWarned.has(name)) return;
+  envFallbackWarned.add(name);
+  console.warn(message);
+}
+
+/** Fail closed with the operator's fix sentence when the AES key is absent/malformed. */
+function requireArmedKey(what: "store"): void {
+  if (credentialKeyArmed()) return;
+  throw new CredentialError(
+    `${CREDENTIAL_KEY_ENV} is not set (or is not a base64-encoded 32-byte key) — refusing to ${what} a secret (fail closed). ` +
+      `It is one of this deployment's root-of-trust variables: set the SAME value the deployed instance holds, or nothing ` +
+      `written here will be readable there. Generate one with: node -e "console.log(require('node:crypto').randomBytes(32).toString('base64'))"`,
+  );
+}

package/agent/credentials/page-chrome.ts

@@ -0,0 +1,59 @@
+// THE SHARED CHROME FOR THE HOST-SERVED CAPABILITY PAGES — the HTML skeleton, the escape, and the
+// three response headers that are a SECURITY POSTURE rather than styling.
+//
+// Extracted from `webhooks/reveal-page.ts`, byte-for-byte, when a second page needed the same
+// skeleton. It is deliberately the chrome ONLY: no token verification, no grant lookup, no store
+// handle, no copy. Each page owns its own body text and — critically — its own generic-failure copy,
+// because "every failure on THIS route renders identically" is a per-route property and collapsing
+// the routes onto one 404 body would say nothing extra while making each page's copy less useful to
+// the human who legitimately hit it.
+//
+// 🔴 THE THREE HEADERS ARE NOT DECORATION.
+//
+//   • `cache-control: no-store` — these pages render one-shot capability material. A proxy or a
+//     browser cache holding one turns a burned single-use grant back into a readable artefact.
+//   • `referrer-policy: no-referrer` — the page's OWN URL carries a capability-bearing token, so a
+//     click on anything must not leak it in a `Referer` header. There are no outbound links on any
+//     page that uses this chrome, for the same reason; the header is the belt.
+//   • `noindex,nofollow` — a crawler that reached one of these URLs must not put it in an index.
+//
+// SELF-CONTAINED BY CONSTRUCTION: inline style, no external asset, no script. A page that fetched
+// anything would be a page whose rendering depends on a third party at the exact moment a secret is
+// on screen.
+
+/** Minimal HTML entity escape for every value interpolated into a page. */
+export function escapeHtml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+
+const PAGE_STYLE =
+  "font:16px/1.5 system-ui,-apple-system,sans-serif;max-width:34rem;margin:3rem auto;padding:0 1rem;color:#1a1a1a;background:#fff";
+
+/** The one submit button style, so the four pages cannot drift into looking like four products. */
+export const BUTTON_STYLE =
+  "margin-top:.5rem;padding:.6rem 1.2rem;font:inherit;font-weight:600;color:#fff;background:#1a56db;border:0;border-radius:.4rem;cursor:pointer";
+
+/** The one monospace block style — used wherever a value has to be copied by hand. */
+export const CODE_BLOCK_STYLE = "background:#f5f5f5;padding:.75rem;border-radius:.4rem;overflow-x:auto";
+
+/** Render one self-contained page with the full header posture. `inner` is trusted markup the
+ *  CALLER assembled; every interpolated VALUE inside it must already have gone through
+ *  {@link escapeHtml}. */
+export function securePageResponse(status: number, title: string, inner: string): Response {
+  const html =
+    `<!doctype html><html lang="en"><head><meta charset="utf-8">` +
+    `<meta name="viewport" content="width=device-width,initial-scale=1">` +
+    `<meta name="robots" content="noindex,nofollow">` +
+    `<meta name="referrer" content="no-referrer">` +
+    `<title>${escapeHtml(title)}</title></head>` +
+    `<body style="${PAGE_STYLE}"><h1 style="font-size:1.25rem">${escapeHtml(title)}</h1>${inner}</body></html>`;
+  return new Response(html, {
+    status,
+    headers: {
+      "content-type": "text/html; charset=utf-8",
+      "cache-control": "no-store",
+      // See the header: a page that renders capability material must never leak its own token.
+      "referrer-policy": "no-referrer",
+    },
+  });
+}