@open-everywhere/core 0.1.0

package/agent/credentials/page-token.ts

@@ -0,0 +1,219 @@
+// THE SIGNED PAGE-TOKEN CODEC — one HMAC grammar, serving TWO browser front doors:
+//
+//   • `aud: "intake"` — the WRITE-only credential-intake page (credentials/intake-page.ts). The
+//     holder may store one value for one intake row.
+//   • `aud: "reveal"` — the READ-once webhook-secret reveal page (webhooks/reveal-page.ts,
+//     OPE-150). The holder may read one host-minted signing secret, exactly once.
+//
+// (Two more audiences once existed — `webhook-collect` (WRITE-once, a vendor's own signing secret)
+// and `webhook-endpoint` (READ-once, a hook's ingress URL) — for setup pages nothing could ever issue
+// a link to. Deleted with those pages in OPE-207. Their sharpest pairing is recorded below because it
+// is the clearest illustration of why `aud` exists at all.)
+//
+// 🔴 WHY `aud` IS REQUIRED, AND WHY IT IS THE WHOLE REASON THIS MODULE EXISTS. Every route verifies
+// against the SAME deployment secret (`OE_INTAKE_PAGE_SIGNING_KEY`) and every claim set is
+// `{v, org, id, rb, exp}` — structurally identical. Without an audience claim, a token minted for
+// one route VERIFIES on the others, and no two of them are equivalent in any direction:
+//   • an intake token replayed at /reveal would turn a WRITE capability into a READ of whatever
+//     `hook:` ref that row's id happens to name;
+//   • a reveal token replayed at /intake would let a reveal holder WRITE a hook's signing secret;
+//   • 🔴 and the sharpest pairing, from a page that no longer exists: a REVEAL token replayed at a
+//     WRITE page over the SAME vault ref (`hook:<id>`) would have let whoever was handed a read-once
+//     link OVERWRITE that hook's signing key with a value of their choosing. Any future page that
+//     names an existing ref from the opposite direction reintroduces exactly that, and `aud` is what
+//     makes it a non-event.
+// A shared key across N routes with compatible claim sets is a cross-route replay waiting to
+// happen, and it is exactly the class of thing that is invisible until someone tries it. So `aud`
+// is REQUIRED (not defaulted) and CHECKED PER ROUTE, and the codec refuses a token whose audience
+// is not the one the caller asked for — the verifier takes the expected audience as an ARGUMENT so
+// a route physically cannot forget to check it.
+//
+// ⭐ BOTH ROUTES CARRY A SECOND WALL, AND IT PINS THE ROW RATHER THAN THE TOKEN (OPE-607). The two
+// front doors write their rows into ONE table (`credential_intake`), so the audience claim separates
+// the TOKENS and the `connector` label separates the ROWS. Reveal grants carry the reserved sentinel
+// {@link REVEAL_GRANT_CONNECTOR} and the reveal route pins it; an intake redemption refuses ANY
+// reserved label ({@link isReservedGrantConnector}) and the intake mint refuses to stamp one. So a
+// token whose audience check was somehow defeated still has to find a row of the matching class, in
+// EITHER direction. `scripts/webhook-reveal-test.ts` drives the full N×N matrix over
+// {@link PAGE_AUDIENCES} rather than a handful of interesting pairs, so a THIRD audience cannot be
+// added without the matrix growing to cover it, and drives the cross-CLASS pair on top of it.
+//
+// ONE KEY, NOT TWO, deliberately. A second env var would be a second thing to rotate, a second
+// fail-closed path, and a second way for a deployment to be half-armed (reveal works, intake 404s,
+// nobody notices). The audience claim gives the separation at zero operational cost, and the key
+// name is unchanged so an already-armed deployment needs no new secret.
+//
+// ⚠️ ROTATION-SHAPED BEHAVIOUR AT THE DEPLOY THAT LANDS THIS: pre-OPE-150 tokens carry no `aud` and
+// are therefore refused. Outstanding intake links die at that deploy. That is a ~15-minute blast
+// radius (the tokens' own TTL) and identical to what rotating the signing key does — which is the
+// documented, expected way to invalidate outstanding links. Ask for a fresh link.
+//
+// CAPABILITY-BEARING: whoever holds a token can perform its one act until `exp`. NEVER log one.
+
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+/** The env var holding the HMAC signing secret for BOTH page front doors. DELIBERATELY a DEDICATED
+ *  secret (not the db AES key): the pages are storage-home agnostic, so their token secret must not
+ *  be coupled to any one home's key. Rotate it like a credential; a captured token dies at `exp`
+ *  regardless, and rotating invalidates every outstanding link immediately. */
+export const PAGE_TOKEN_KEY_ENV = "OE_INTAKE_PAGE_SIGNING_KEY";
+
+/** Which front door a token is for. CLOSED — a new page adds a member here and a route that names
+ *  it, which is what makes "did anyone forget to check the audience" a compile-time question. */
+export type PageAudience = "intake" | "reveal";
+
+/**
+ * Every audience, as a VALUE — so the cross-audience replay matrix can be written as a loop over the
+ * union rather than as a hand-maintained list of interesting pairs.
+ *
+ * 🔴 THE TOTALITY CHECK BELOW IS THE POINT. `satisfies` alone would admit a SHORTER array (every
+ * member of a subset is still a `PageAudience`), so a third audience could be added to the type and
+ * silently miss the matrix — which is the exact drift this array exists to prevent. `_AudiencesAreTotal`
+ * resolves to `never` unless the array covers the union, so the omission is a COMPILE error.
+ */
+export const PAGE_AUDIENCES = ["intake", "reveal"] as const satisfies readonly PageAudience[];
+
+type _AudiencesAreTotal = Exclude<PageAudience, (typeof PAGE_AUDIENCES)[number]> extends never ? true : never;
+const _audiencesAreTotal: _AudiencesAreTotal = true;
+void _audiencesAreTotal;
+
+// --- the ROW-class vocabulary (the second wall) ----------------------------------------------------
+//
+// 🔴 WHY THIS LIVES HERE AND NOT ON EITHER ROUTE. The audience claim and the row class are ONE
+// separation done twice — once over tokens, once over rows — and they only work while both routes
+// agree on the same vocabulary. A sentinel declared on the reveal route and re-derived on the intake
+// route is two copies of one string, and the day they drift the wall opens silently in exactly one
+// direction. So the vocabulary is declared once, next to the audiences it mirrors, and each route
+// imports it.
+
+/** The `connector` label stamped on a webhook-REVEAL grant row (webhooks/reveal-page.ts stamps it,
+ *  and re-exports this constant). A reveal grant lives in `credential_intake` beside real intake
+ *  rows, so this label is what makes the two row classes tellable apart. */
+export const REVEAL_GRANT_CONNECTOR = "webhook-reveal";
+
+/**
+ * Every `connector` label RESERVED for a NON-intake grant row in `credential_intake`.
+ *
+ * A real intake row's `connector` is an open vocabulary — it is whatever connector the catalogue
+ * names ("notion", "github", …) — so an intake route cannot pin one positive value. It pins the
+ * complement instead: a row carrying ANY label on this list is not an intake row, and an intake
+ * front door must refuse it. Adding a grant class to the table means adding its label here.
+ */
+const RESERVED_GRANT_CONNECTORS: readonly string[] = [REVEAL_GRANT_CONNECTOR];
+
+/**
+ * Does this `connector` label mark a row as a GRANT of some other class — something an intake front
+ * door must never mint and never redeem?
+ *
+ * Used in BOTH directions (OPE-607): the intake mint refuses to stamp a reserved label (so no intake
+ * row can ever pose as a grant), and every intake redemption path refuses a row that carries one (so
+ * no grant row can ever be completed as an intake). The refusals are named — `wrong-class` on the
+ * finalize seam — but never surfaced: every page failure still renders the ONE generic 404.
+ */
+export function isReservedGrantConnector(connector: string): boolean {
+  return RESERVED_GRANT_CONNECTORS.includes(connector);
+}
+
+/** The signed claim set — bound to ONE row, for ONE audience. `rb` = the principal the row is bound
+ *  to (the identity the act is attributed to); `exp` = a hard epoch-ms wall equal to the row's own
+ *  expiry. `v` guards a future grammar change. */
+export interface PageTokenClaims {
+  readonly v: 1;
+  readonly aud: PageAudience;
+  readonly org: string;
+  /** The row id this token authorizes acting on. */
+  readonly id: string;
+  /** The principal the row is bound to (requestedBy). */
+  readonly rb: string;
+  /** Hard expiry, epoch ms. */
+  readonly exp: number;
+}
+
+/** The configured signing secret, or undefined (both page routes then 404 — disarmed). */
+export function pageTokenSigningKey(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const v = (env[PAGE_TOKEN_KEY_ENV] ?? "").trim();
+  return v.length > 0 ? v : undefined;
+}
+
+/**
+ * The deployment's OWN public base URL for a page link (the human opens it in a browser).
+ * Precedence mirrors the self-dispatch base-url resolver: `OE_PUBLIC_BASE_URL` (explicit operator
+ * override — scheme optional, trailing slash stripped) → `VERCEL_PROJECT_PRODUCTION_URL` (the
+ * stable production alias) → `VERCEL_URL` (this deployment's generated host — last resort; can sit
+ * behind deployment protection). Bare hosts get `https://`. Undefined when undiscoverable.
+ */
+export function pageBaseUrl(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const explicit = (env.OE_PUBLIC_BASE_URL ?? "").trim();
+  if (explicit.length > 0) {
+    const withScheme = /^https?:\/\//i.test(explicit) ? explicit : `https://${explicit}`;
+    return withScheme.replace(/\/+$/, "");
+  }
+  const host = (env.VERCEL_PROJECT_PRODUCTION_URL ?? "").trim() || (env.VERCEL_URL ?? "").trim();
+  return host.length > 0 ? `https://${host.replace(/\/+$/, "")}` : undefined;
+}
+
+function b64urlEncode(buf: Buffer): string {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function b64urlDecode(s: string): Buffer {
+  // Reject anything outside the base64url alphabet BEFORE decoding (Buffer is lax) — a malformed
+  // token must fail cleanly, never decode to attacker-shaped bytes.
+  if (!/^[A-Za-z0-9_-]*$/.test(s)) return Buffer.alloc(0);
+  return Buffer.from(s.replace(/-/g, "+").replace(/_/g, "/"), "base64");
+}
+
+function sign(secret: string, payloadB64: string): string {
+  return b64urlEncode(createHmac("sha256", secret).update(payloadB64, "utf8").digest());
+}
+
+/**
+ * Mint a signed, single-use page token. `<payloadB64>.<sigB64>` — the payload is the JSON claim
+ * set, the signature an HMAC-SHA256 over it. CAPABILITY-BEARING; NEVER log it.
+ */
+export function mintPageToken(claims: PageTokenClaims, secret: string): string {
+  const payloadB64 = b64urlEncode(Buffer.from(JSON.stringify(claims), "utf8"));
+  return `${payloadB64}.${sign(secret, payloadB64)}`;
+}
+
+/**
+ * Verify + decode a page token FOR ONE AUDIENCE. Constant-time signature compare, then structural,
+ * audience and expiry checks. Returns the claims for a valid, unexpired, well-formed token of the
+ * EXPECTED audience, or `null` for ANYTHING else (malformed, tampered, wrong version, wrong
+ * audience, expired) — the caller renders one generic failure, so a holder can't distinguish the
+ * reasons. `now` is injectable for tests.
+ *
+ * `expected` is a REQUIRED parameter rather than a field the caller compares afterwards: an
+ * afterwards-comparison is a line a route can omit, and this one is load-bearing (see the header).
+ */
+export function verifyPageToken(token: string, secret: string, expected: PageAudience, now: number = Date.now()): PageTokenClaims | null {
+  if (typeof token !== "string") return null;
+  const dot = token.indexOf(".");
+  if (dot <= 0 || dot === token.length - 1) return null;
+  const payloadB64 = token.slice(0, dot);
+  const sigB64 = token.slice(dot + 1);
+
+  const expectedSig = sign(secret, payloadB64);
+  const a = Buffer.from(sigB64);
+  const b = Buffer.from(expectedSig);
+  if (a.length !== b.length || !timingSafeEqual(a, b)) return null;
+
+  let parsed: unknown;
+  try {
+    const raw = b64urlDecode(payloadB64);
+    if (raw.length === 0) return null;
+    parsed = JSON.parse(raw.toString("utf8"));
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) return null;
+  const c = parsed as Record<string, unknown>;
+  if (c.v !== 1) return null;
+  if (c.aud !== expected) return null; // CROSS-ROUTE REPLAY WALL — see the header
+  if (typeof c.org !== "string" || !c.org) return null;
+  if (typeof c.id !== "string" || !c.id) return null;
+  if (typeof c.rb !== "string" || !c.rb) return null;
+  if (typeof c.exp !== "number" || !Number.isFinite(c.exp)) return null;
+  if (c.exp <= now) return null; // hard expiry wall
+  return { v: 1, aud: expected, org: c.org, id: c.id, rb: c.rb, exp: c.exp };
+}

package/agent/credentials/purge.ts

@@ -0,0 +1,113 @@
+// THE CREDENTIAL-PURGE HOOK (OPE-287) — the vendor-neutral seam core calls to make a subject's
+// stored credentials DIE, rather than merely stop being reachable.
+//
+// WHY A SEAM AND NOT A CALL. `revokeLinkSet` (identity/link-store.ts) is the offboarding lever and
+// lives in CORE. The credentials it has to destroy live in the OAuth adapter's vault, under keys
+// only that adapter composes (`oe-oauth:tok:<providerRef>:user:<subject>`), and their vendor-side
+// revocation needs the adapter's OAuth knowledge (which endpoint, which token-type hint). Core
+// importing the adapter to do that would invert the dependency the boundary test exists to hold
+// (packages/core never reaches packages/adapters). So the adapter REGISTERS, exactly like
+// registerEntityActionAdapter / registerUserAuthFlow, and core calls whatever is registered.
+//
+// 🔴 FAIL-OPEN ON PURGE, NEVER ON REVOKE. This is the one inversion of the fail-closed default that
+// runs everywhere else in this codebase, and it is deliberate. Offboarding is a NARROWING act: the
+// revoke itself (status flip + tombstoned ids) is what removes the person's standing, and it is
+// already durable before a purge is attempted. If the vault is down, the vendor is down, or no
+// adapter is registered at all, blocking the revoke would mean an outage in a credential store can
+// stop an org from offboarding somebody — strictly worse than an offboarding that completed with a
+// credential still to destroy. So {@link purgeSubjectCredentials} NEVER throws; it reports, and the
+// caller writes the outcome into the audit row (`credentialsPurged` / `purgeFailed: true`) so the
+// residue is VISIBLE and can be finished later with the `purge_link_set_credentials` control verb.
+// A silent best-effort would be the unacceptable version of this; an audited one is not.
+
+/** What an adapter that holds per-subject credentials must be able to do when a subject is
+ *  offboarded. One method, because a purge is all-or-nothing per subject — an adapter that holds
+ *  several providers' rows for one person sweeps them all (it is the only thing that knows how
+ *  many there are). */
+export interface CredentialPurgeHook {
+  /**
+   * Destroy every credential this adapter holds for `subjectId` — vendor-side revocation first
+   * (best effort), then the at-rest row — and return HOW MANY rows actually went. Must be
+   * idempotent: a second purge of the same subject legitimately returns 0.
+   *
+   * `subjectId` is the vault's USER-subject id: either the shared link-set subject
+   * (`ls:<org>/<setId>`) or a qualified RAW per-account subject (`p:<org>/<platform>/<id>`) — both
+   * from identity/oauth-vault-share.ts. There is no app-subject purge — the service identity is not
+   * a person and is not offboarded. An offboarding sweeps BOTH shapes (OPE-300 G3): the shared
+   * subject, and every tombstoned account's raw subject, because a per-person credential (an
+   * Identity Center SSO token) is never stored under the shared one.
+   */
+  purgeSubject(subjectId: string): Promise<number>;
+}
+
+// MORE THAN ONE ADAPTER HOLDS PER-SUBJECT CREDENTIALS (OPE-300 G3). The registry was a single slot
+// when the own-rolled OAuth vault was the only holder. It is not any more: the AWS Identity Center
+// adapter stores an SSO refresh token per person under `aws-sso:tok:<subject>`, in the same vault,
+// under a key only it composes. A last-wins slot would have made those two adapters silently
+// cancel each other at boot — whichever registered second would be the only one an offboarding
+// reached. So registration is KEYED, and a purge fans out to every registered holder.
+const registeredHooks = new Map<string, CredentialPurgeHook>();
+
+/** Register a credential-purge hook at boot (register-adapters.ts, alongside the adapter that owns
+ *  the rows). `name` identifies the HOLDER (e.g. "oe-oauth", "aws-sso"); re-registering the same
+ *  name is an idempotent overwrite, mirroring registerUserAuthFlow / registerBroker, while a
+ *  different name ADDS a holder rather than displacing one. */
+export function registerCredentialPurgeHook(name: string, hook: CredentialPurgeHook): void {
+  registeredHooks.set(name, hook);
+}
+
+/** Test seam / rollback: forget every registered hook (the "no credential adapter wired" path). */
+export function resetCredentialPurgeHook(): void {
+  registeredHooks.clear();
+}
+
+/** The outcome of a best-effort purge, shaped to go straight into an audit detail. `failed` is true
+ *  ONLY when a registered hook threw — no hook registered is not a failure (nothing to purge), and
+ *  says so by reporting `{ purged: 0, failed: false }`. */
+export interface CredentialPurgeOutcome {
+  readonly purged: number;
+  readonly failed: boolean;
+}
+
+/**
+ * Purge `subjectId`'s credentials through EVERY registered holder. NEVER THROWS — see this file's
+ * header for why the one fail-open in the codebase is here. An error is logged (message only:
+ * a purge error must never carry token material, and the adapters' errors are built not to) and
+ * reported through `failed` so the caller can audit it.
+ *
+ * ONE HOLDER'S FAILURE NEVER STOPS ANOTHER'S PURGE — the same per-source isolation the OAuth
+ * adapter already applies across providers, one level up. `purged` is the total across holders;
+ * `failed` is true if ANY of them threw, so an audit row can never read "everything went" when
+ * something is still stored.
+ */
+export async function purgeSubjectCredentials(subjectId: string): Promise<CredentialPurgeOutcome> {
+  let purged = 0;
+  let failed = false;
+  for (const [name, hook] of registeredHooks) {
+    try {
+      purged += await hook.purgeSubject(subjectId);
+    } catch (e) {
+      failed = true;
+      console.warn(`[credential-purge] purge for subject failed in "${name}" (offboarding still applied): ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+  return { purged, failed };
+}
+
+/**
+ * Purge SEVERAL subjects (OPE-300 G3) — the shape offboarding actually needs, because a link-set
+ * addresses credentials under more than one key: the set's SHARED subject, plus each member
+ * account's own RAW subject (`rawVaultSubject`), which is the only key an Identity Center SSO
+ * token is ever stored under. Duplicates are collapsed so a caller can pass a list built from rows
+ * without worrying about repeats. Same fail-open contract, totalled the same way.
+ */
+export async function purgeSubjectsCredentials(subjectIds: readonly string[]): Promise<CredentialPurgeOutcome> {
+  let purged = 0;
+  let failed = false;
+  for (const subjectId of new Set(subjectIds)) {
+    const outcome = await purgeSubjectCredentials(subjectId);
+    purged += outcome.purged;
+    failed ||= outcome.failed;
+  }
+  return { purged, failed };
+}

package/agent/credentials/ref.ts

@@ -0,0 +1,151 @@
+// Structured `db` credential refs (task #113, stage 5). A pasted-key credential stored via the db
+// broker needs a ref that is (a) unique per connector credential and (b) REVERSIBLE back to the
+// (connector, credentialId) pair that named it — so the credential-binding PR can re-stamp exactly
+// that credential env → db with no schema migration (the intake row carries only the ref string).
+//
+// GRAMMAR: `db:<connector>:<credentialId>`. Both segments are opaque operator-chosen ids that MUST
+// NOT contain a colon (the delimiter) — guarded at derive time so the ref round-trips. This is the
+// heavier-alternative-avoided: rather than add a `credential_intake.credential` column, the ref
+// itself carries the identity. `parseDbCredentialRef` is the inverse and returns null for anything
+// that isn't a well-formed db ref (an env-var-name ref, an OAuth credential, a hand-typed string) —
+// so a non-db ref simply routes NO binding PR (fail-safe skip), never a crash.
+
+/** The prefix every structured db credential ref carries. */
+export const DB_REF_PREFIX = "db:";
+
+/**
+ * Derive the reversible db ref for one connector credential: `db:<connector>:<credentialId>`. Throws
+ * if either id is empty or contains a `:` — a colon would make the ref ambiguous to
+ * {@link parseDbCredentialRef}, so we refuse at the derive point rather than store an unrecoverable
+ * ref. Ids are connector-config values (operator-authored), so this only fires on a malformed config.
+ */
+export function dbCredentialRef(connector: string, credentialId: string): string {
+  if (!connector || !credentialId) {
+    throw new Error(`dbCredentialRef needs a non-empty connector and credentialId (got "${connector}"/"${credentialId}")`);
+  }
+  if (connector.includes(":") || credentialId.includes(":")) {
+    throw new Error(`dbCredentialRef: neither connector ("${connector}") nor credentialId ("${credentialId}") may contain ":" — it is the ref delimiter`);
+  }
+  return `${DB_REF_PREFIX}${connector}:${credentialId}`;
+}
+
+/**
+ * The inverse of {@link dbCredentialRef}. Returns `{ connector, credentialId }` for a well-formed
+ * `db:<connector>:<credentialId>` ref, or `null` for anything else (missing prefix, wrong segment
+ * count, empty segment). Never throws — callers treat `null` as "not a db-stored credential, no
+ * binding PR" (the fail-safe path).
+ */
+export function parseDbCredentialRef(ref: string): { connector: string; credentialId: string } | null {
+  if (typeof ref !== "string" || !ref.startsWith(DB_REF_PREFIX)) return null;
+  const rest = ref.slice(DB_REF_PREFIX.length);
+  const idx = rest.indexOf(":");
+  if (idx <= 0) return null; // no connector/id delimiter, or an empty connector
+  const connector = rest.slice(0, idx);
+  const credentialId = rest.slice(idx + 1);
+  // credentialId must itself be colon-free (exactly three segments) or the ref wasn't ours to derive.
+  if (!connector || !credentialId || credentialId.includes(":")) return null;
+  return { connector, credentialId };
+}
+
+// --- RefCodec registry (R1 — vendor-agnostic credential HOMES) -----------------------------------
+//
+// A stored credential ref carries its HOME in a prefix (`db:`, or a future vendor's). Historically
+// every consumer hardcoded `parseDbCredentialRef` and branched on a closed set. A RefCodec instead
+// REGISTERS one grammar under a home name; `parseCredentialRef` walks the registry and returns
+// `{ home, ...fields }` for the first codec that recognises the ref — or `null` for a BARE secret-ref
+// (an env-var name whose home is the separate `broker: "env"` stamp, no prefix). A new vendor
+// (ToolHive-class) registers its own codec and every consumer routes it automatically — no core edit.
+
+/** The minimal credential facts a {@link RefCodec.derive} inspects to decide whether a credential is
+ *  homed by that codec, and to build its ref. Deliberately NOT the full ConnectorCredential (ref.ts is a
+ *  pure leaf that connector-credentials.ts must be free to import) — just the identity. */
+export interface CredentialRefDeriveInput {
+  /** The connector name (a `db:` ref segment). */
+  readonly connector: string;
+  /** The credential id within the connector (a `db:` ref segment). */
+  readonly credentialId: string;
+}
+
+/** One credential-ref grammar: the home it names + a pure inverse parser (+ an optional forward
+ *  derive). */
+export interface RefCodec {
+  /** The home name this codec owns (the `home` field {@link parseCredentialRef} stamps, e.g. "db"). */
+  readonly home: string;
+  /** Structured fields for a well-formed ref of THIS home, or null when the string isn't this
+   *  grammar (fail-safe skip — the next codec, or a bare ref). Never throws. */
+  parse(ref: string): Readonly<Record<string, string>> | null;
+  /** The FORWARD direction: the stored ref for a credential whose home is THIS codec, or null when the
+   *  credential is not homed here (the next codec, or the db default). {@link deriveCredentialRef} walks
+   *  the registry so a new vendor's intake ref derives without a hardcoded branch. May throw on a
+   *  MALFORMED credential (a colon in a segment) — same discipline as the derive functions. */
+  derive?(input: CredentialRefDeriveInput): string | null;
+}
+
+/** The core home name — also the RefCodec + CredentialHome registry key. */
+export const DB_HOME = "db";
+
+const REF_CODECS = new Map<string, RefCodec>();
+
+/**
+ * Register a credential-ref codec by home name. Idempotent overwrite (last wins), mirroring
+ * credentials.ts registerBroker. A vendor adapter registers its grammar this way — the consumers
+ * (intake storage dispatch, the binding-PR override) need no edit to route the new home.
+ */
+export function registerRefCodec(codec: RefCodec): void {
+  REF_CODECS.set(codec.home, codec);
+}
+
+/** Test seam: forget all registered codecs, then restore the core db codec. */
+export function resetRefCodecs(): void {
+  REF_CODECS.clear();
+  registerCoreRefCodecs();
+}
+
+/** A parsed credential ref: its home + the home's structured fields. */
+export type ParsedCredentialRef = { readonly home: string } & Readonly<Record<string, string>>;
+
+/**
+ * Parse a stored credential ref into `{ home, ...fields }` via the first registered codec that
+ * recognises it, or `null` for a bare secret-ref (no home prefix — an env-var name whose home is the
+ * `broker: "env"` stamp). This is the SINGLE discrimination point consumers route through instead of
+ * hand-enumerating the registered homes. Never throws.
+ */
+export function parseCredentialRef(ref: string): ParsedCredentialRef | null {
+  if (typeof ref !== "string") return null;
+  for (const codec of REF_CODECS.values()) {
+    const fields = codec.parse(ref);
+    if (fields) return { home: codec.home, ...fields };
+  }
+  return null;
+}
+
+/**
+ * The FORWARD dual of {@link parseCredentialRef}: the stored ref an intake writes for a credential,
+ * derived by the first registered codec whose {@link RefCodec.derive} claims it. The connector card's
+ * "Set API key" flow routes through this instead of a hardcoded branch, so a new vendor's home derives
+ * with no core edit. Today the core db codec claims every input; returns null only if none does.
+ * Propagates a malformed-segment throw from the underlying derive.
+ */
+export function deriveCredentialRef(input: CredentialRefDeriveInput): string | null {
+  for (const codec of REF_CODECS.values()) {
+    const ref = codec.derive?.(input);
+    if (ref !== null && ref !== undefined) return ref;
+  }
+  return null;
+}
+
+function registerCoreRefCodecs(): void {
+  // db is the DEFAULT home for an intake-able api-key: a chat-pasted key lives in the db broker under
+  // a reversible `db:<connector>:<cred>` ref. A future registered home vendor stands this down for a
+  // credential homed elsewhere.
+  registerRefCodec({
+    home: DB_HOME,
+    parse: parseDbCredentialRef,
+    derive: (input) => dbCredentialRef(input.connector, input.credentialId),
+  });
+}
+
+// The core codec self-registers at module load. ref.ts is a pure leaf that every credential-ref
+// consumer already imports, so this guarantees `parseCredentialRef` recognises db refs
+// UNCONDITIONALLY — the fail-closed invariant does not depend on any other module's load order.
+registerCoreRefCodecs();

package/agent/credentials/reserved-refs.ts

@@ -0,0 +1,76 @@
+// RESERVED CREDENTIAL-REF NAMESPACES (OPE-150) — the fail-closed line between the two things that
+// share the `stored_credential` table.
+//
+// THE PROBLEM THIS CLOSES. `stored_credential` is one table with two tenants:
+//
+//   1. OUTBOUND credentials an operator or a member deliberately handed us (an API key pasted into
+//      the intake modal). These are resolved by the EGRESS plane through
+//      `getSecretVia("db", ref)` — a read-only CredentialBroker whose whole job is "give the
+//      outbound call its bearer token".
+//   2. INTERNAL secret material the HOST minted for ITSELF and stores through the encrypted KV
+//      vault (`credentials/kv-vault.ts`): the own-rolled OAuth adapter's tokens (`oe-oauth:*`),
+//      the `hook:*` namespace a since-deleted chat-created webhook class minted into (retained: see
+//      below), and since OPE-195
+//      a VENDOR-issued handshake key we merely captured rather than minted (`notion-handshake:*`).
+//
+// Class 2 must never be resolvable as class 1. A webhook signing secret is an INBOUND
+// authentication key: routing it through the outbound resolver would make it something the egress
+// plane can fetch and send to a third party. Today the only way to ask for that is a config
+// credential declaring `broker: "db", secretRef: "hook:…"` — which needs a merged PR, so it is
+// not a live hole. It is also a free guard that costs one map lookup on a path that already does a
+// database read, and it closes the identical residual `oe-oauth:` already carried.
+//
+// 🔴 NOT A DEAD GUARD — the triggering condition is a real, expressible config today. Both
+// `access/bundle.ts`'s `Connection.secretRef` and `webhooks/config.ts`'s `WebhookHook.secretRef`
+// are free-form strings resolved through `getSecretVia`, and neither validator has ever inspected
+// the namespace. `scripts/webhook-runtime-test.ts` drives the guard through the REAL broker.
+//
+// WHY A GUARD AND NOT "PUT THEM IN A DIFFERENT TABLE". A second table is a second migration, a
+// second RLS policy, a second backend triple to keep in sync, and a second crypto path — the exact
+// drift this tree's "one mechanism per concern" rule exists to prevent. The vault ALREADY reads and
+// writes these refs directly (it holds the store handle itself, credentials/kv-vault.ts), so the
+// namespaces are separated where the separation actually has to hold: at the RESOLVER.
+
+/**
+ * A VENDOR-ISSUED handshake secret captured at subscription time (OPE-195) — today, Notion's
+ * `verification_token`, which is the HMAC key for every subsequent delivery on that subscription.
+ * Same class as `hook:` (an INBOUND authentication key the egress plane must never fetch), and
+ * captured by the one function that mints it, `webhooks/handshake-capture.ts`.
+ *
+ * ⚠️ DELIBERATELY NOT UNDER `hook:`. These are not runtime hooks, and `revealEndpointUrl` renders
+ * `<base>/webhooks/<rest>` for ANY `hook:` ref with no second colon — so a `hook:`-namespaced
+ * handshake ref would print a bogus ingress URL beside the secret on the reveal page. A separate
+ * namespace keeps the endpoint render honest AND still earns the resolver refusal below.
+ */
+export const NOTION_HANDSHAKE_REF_NAMESPACE = "notion-handshake:";
+
+/**
+ * A SELF-SHARED secret this deployment mints for and verifies against ITSELF — no external
+ * counterparty ever holds or presents the value (OPE-408 step 3: `OE_INTAKE_PAGE_SIGNING_KEY`,
+ * `OE_SPAWN_DISPATCH_SECRET`, `OE_TRANSCRIPT_RELAY_SECRET`). Same class as `hook:`/`oe-oauth:`: read
+ * and written directly by {@link import("./self-secrets.js").getOrMintSelfSecret}, never through the
+ * outbound resolver. See `self-secrets.ts` for the mint-on-first-use resolution order.
+ */
+export const SELF_SECRET_REF_NAMESPACE = "self:";
+
+/** Ref prefixes that name HOST-MINTED internal secret material. Never resolvable as an outbound
+ *  credential. Additive-only: adding a prefix here can only ever make the resolver refuse MORE. */
+export const RESERVED_REF_NAMESPACES: readonly string[] = ["hook:", "oe-oauth:", NOTION_HANDSHAKE_REF_NAMESPACE, SELF_SECRET_REF_NAMESPACE] as const;
+
+/** The reserved namespace `ref` sits in, or undefined. Case-sensitive on purpose: the refs are
+ *  host-minted with exact spelling, and a case-insensitive test would refuse an operator's
+ *  legitimately-named `Hook:` key for no reason. */
+export function reservedRefNamespace(ref: string): string | undefined {
+  return RESERVED_REF_NAMESPACES.find((ns) => ref.startsWith(ns));
+}
+
+/** The operator-facing refusal sentence. Names the ref (a POINTER — the class of information every
+ *  other credential error already carries) and never a value. */
+export function reservedRefRefusal(ref: string, ns: string): string {
+  return (
+    `credential ref ${JSON.stringify(ref)} is in the reserved "${ns}" namespace — refusing to resolve it as an ` +
+    `outbound credential (fail closed). Refs in that namespace hold secret material this deployment minted for ` +
+    `ITSELF (an inbound webhook signing secret, an OAuth token the adapter rotates); they are read internally by ` +
+    `the encrypted KV vault, never handed to an outbound call. Pick a different ref.`
+  );
+}