@open-everywhere/core 0.1.0

package/agent/credentials/db-broker.ts

@@ -0,0 +1,270 @@
+// The `db` credential broker (task #113) — a core, vendor-SDK-free CredentialBroker whose secret
+// store is our own operational DB (stored_credential). It is the self-host path between the env
+// broker (a secret per env var, set by the operator) and a managed vault (KMS/Vault): an org
+// member pastes an API key into a native Slack modal, the webhook encrypts it here, and egress
+// resolves it later through the SAME getSecretVia("db", ref) seam as every other broker — zero
+// resolver changes. It is REGISTERED (available) when its AES key is armed (register-adapters.ts);
+// a credential reaches it by naming `broker: "db"` — there is no global selection.
+//
+// SECURITY CONTRACT (the whole point):
+//   • The value is stored ENCRYPTED at rest — AES-256-GCM, node:crypto, key from
+//     OE_CREDENTIAL_ENCRYPTION_KEY (32-byte, base64). Random IV per record, auth tag stored.
+//   • FAIL CLOSED: with the key env absent or malformed, the broker refuses BOTH store and read —
+//     it never falls back to storing plaintext, and never returns a value it cannot authenticate.
+//   • The plaintext NEVER touches the model, a log, or audit detail. `encryptCredential` /
+//     `decryptCredential` are the only two functions that see it, and neither logs. The stored
+//     ciphertext is opaque even to the operational store (it holds a base64 blob).
+//   • The WRITE path (`storeDbSecret`) is a plain exported function, NOT on the CredentialBroker
+//     interface (which is read-only by design) — only the credential-intake webhook handler calls
+//     it. The model-facing egress plane only ever calls getSecret (read).
+
+import { randomBytes, createCipheriv, createDecipheriv } from "node:crypto";
+import {
+  CredentialError,
+  registerBroker,
+  registeredBrokerNames,
+  CREDENTIAL_UNRESOLVED,
+  type CredentialBroker,
+  type UnresolvedReason,
+} from "../access/credentials.js";
+import { getOperationalStore } from "../operational/provider.js";
+import { appendAudit } from "../audit/audit.js";
+import { deploymentOrg } from "../identity/binding.js";
+import { registerCredentialHome } from "./home.js";
+import { reservedRefNamespace, reservedRefRefusal } from "./reserved-refs.js";
+
+/** The registry name this broker registers under; a credential names it via `broker: "db"`. */
+export const DB_BROKER = "db";
+
+/** The env var holding the base64-encoded 32-byte AES-256-GCM key. Named in every fail-closed error. */
+export const CREDENTIAL_KEY_ENV = "OE_CREDENTIAL_ENCRYPTION_KEY";
+
+const KEY_BYTES = 32; // AES-256
+const IV_BYTES = 12; // GCM standard nonce length
+const TAG_BYTES = 16; // GCM auth tag length
+
+/**
+ * Load + validate the AES-256-GCM key from {@link CREDENTIAL_KEY_ENV}. FAIL CLOSED: an absent or
+ * non-32-byte key throws a CredentialError that NAMES the env (operator-facing) — the broker never
+ * proceeds to store plaintext or read an un-authenticatable value. Read fresh each call (cheap; no
+ * process-lifetime caching of key material beyond the env itself). The key VALUE is never logged.
+ */
+function loadKey(): Buffer {
+  const raw = process.env[CREDENTIAL_KEY_ENV];
+  if (!raw) {
+    throw new CredentialError(
+      `db credential broker: ${CREDENTIAL_KEY_ENV} is not set — refusing to store or read credentials ` +
+        `(fail closed). Set it to a base64-encoded 32-byte key.`,
+    );
+  }
+  let key: Buffer;
+  try {
+    key = Buffer.from(raw, "base64");
+  } catch {
+    throw new CredentialError(`db credential broker: ${CREDENTIAL_KEY_ENV} is not valid base64 — refusing (fail closed).`);
+  }
+  if (key.length !== KEY_BYTES) {
+    throw new CredentialError(
+      `db credential broker: ${CREDENTIAL_KEY_ENV} decodes to ${key.length} bytes, need ${KEY_BYTES} ` +
+        `(a base64-encoded 32-byte AES-256 key) — refusing (fail closed).`,
+    );
+  }
+  return key;
+}
+
+/**
+ * Is the AES key armed and well-formed? A pure PREDICATE over the same {@link loadKey} the crypto
+ * uses — so there is still exactly one place that decides what a valid key is. It exists so a caller
+ * can give the operator the fix sentence BEFORE attempting a store (operator-secrets.ts), and so the
+ * env-vs-db resolution order can refuse to fall back to an env var when a stored row exists but is
+ * unreadable. Never returns or logs the key.
+ */
+export function credentialKeyArmed(): boolean {
+  try {
+    loadKey();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Encrypt one plaintext secret into the opaque envelope `base64(iv ‖ tag ‖ ciphertext)`. A fresh
+ * random IV per call means the same plaintext stored twice produces different ciphertext (no
+ * equality leak). Never logs the plaintext OR the ciphertext.
+ */
+export function encryptCredential(plaintext: string): string {
+  const key = loadKey();
+  const iv = randomBytes(IV_BYTES);
+  const cipher = createCipheriv("aes-256-gcm", key, iv);
+  const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return Buffer.concat([iv, tag, ct]).toString("base64");
+}
+
+/**
+ * Decrypt an envelope produced by {@link encryptCredential}. Throws CredentialError on a malformed
+ * or tampered blob (GCM auth-tag mismatch → the value is NOT returned — fail closed). Never logs
+ * either the ciphertext or the recovered plaintext.
+ */
+export function decryptCredential(envelope: string): string {
+  const key = loadKey();
+  let buf: Buffer;
+  try {
+    buf = Buffer.from(envelope, "base64");
+  } catch {
+    throw new CredentialError("db credential broker: stored ciphertext is not valid base64 — refusing (fail closed).");
+  }
+  if (buf.length < IV_BYTES + TAG_BYTES) {
+    throw new CredentialError("db credential broker: stored ciphertext is truncated — refusing (fail closed).");
+  }
+  const iv = buf.subarray(0, IV_BYTES);
+  const tag = buf.subarray(IV_BYTES, IV_BYTES + TAG_BYTES);
+  const ct = buf.subarray(IV_BYTES + TAG_BYTES);
+  const decipher = createDecipheriv("aes-256-gcm", key, iv);
+  decipher.setAuthTag(tag);
+  try {
+    return Buffer.concat([decipher.update(ct), decipher.final()]).toString("utf8");
+  } catch {
+    // GCM final() throws on an auth-tag mismatch (wrong key, or tampered ciphertext) — surface it as
+    // a CredentialError, never the raw crypto error (which could hint at internals), and NEVER the value.
+    throw new CredentialError("db credential broker: ciphertext failed authentication (wrong key or tampered) — refusing (fail closed).");
+  }
+}
+
+/** Input to the host-side write path — the ONLY way a value enters the store. */
+export interface StoreDbSecretInput {
+  /** The tenant the credential belongs to (the intake's org). */
+  readonly org: string;
+  /** The lookup key egress resolves through getSecret, e.g. `db:notion-<domain>-key`. */
+  readonly ref: string;
+  /** The plaintext value — encrypted immediately, never persisted or logged raw. */
+  readonly plaintext: string;
+  /** Connector label (audit/admin views only). */
+  readonly connector?: string;
+  /** Domain label (audit/admin views only). */
+  readonly domain?: string;
+  /** The storing principal (the intake requester). */
+  readonly createdBy: string;
+  /** ISO-8601 store time (defaults to now). */
+  readonly at?: string;
+}
+
+/**
+ * Host-side WRITE path — encrypt `plaintext` and upsert it under (org, ref). Called ONLY by the
+ * credential-intake webhook handler (agent/credentials/intake.ts), never exposed as an agent tool
+ * and never placed on the read-only CredentialBroker interface. FAIL CLOSED via {@link loadKey}: a
+ * missing/malformed key throws BEFORE anything is stored. The plaintext leaves this function only as
+ * ciphertext; it is never logged.
+ */
+export async function storeDbSecret(input: StoreDbSecretInput): Promise<void> {
+  const ciphertext = encryptCredential(input.plaintext); // throws (fail closed) if the key env is bad — before any store write
+  await getOperationalStore().putStoredCredential(input.org, {
+    ref: input.ref,
+    ciphertext,
+    ...(input.connector ? { connector: input.connector } : {}),
+    ...(input.domain ? { domain: input.domain } : {}),
+    createdBy: input.createdBy,
+    createdAt: input.at ?? new Date().toISOString(),
+  });
+}
+
+/**
+ * The read broker. `getSecret(ref)` resolves a stored credential for the deployment org (the egress
+ * plane carries no org — it serves the single service identity, same posture as the env
+ * broker). Missing ref → a CredentialError matching the env broker's shape ("secret not found for
+ * ref ..."). FAIL CLOSED on a bad key (loadKey throws in decryptCredential). Never logs the value.
+ *
+ * RESERVED NAMESPACES ARE REFUSED FIRST (OPE-150), BEFORE ANY STORE READ. `stored_credential` holds
+ * two disjoint tenants — outbound credentials a human handed us, and secret material the HOST
+ * minted for itself (`hook:` inbound webhook signing secrets, `oe-oauth:` adapter tokens). The
+ * second class is read by the encrypted KV vault directly (credentials/kv-vault.ts, which holds the
+ * store handle and never comes through here); this broker is the OUTBOUND resolver, so a config
+ * declaring `broker:"db", secretRef:"hook:…"` must not be able to turn an INBOUND authentication
+ * key into something the egress plane can send to a third party. See credentials/reserved-refs.ts.
+ *
+ * 🔴 EVERY REFUSAL AUDITS ITSELF (OPE-639). The throw below is correct, but on its own it was
+ * INVISIBLE: consumers catch `CredentialError` and degrade quietly, which is the right availability
+ * posture and the wrong observability one. Notion's channel path is the measured case —
+ * `resolveNotionCredential` (notion-api.ts) turns the throw into `undefined`, the webhook acks 200
+ * with `action: "no-api-key"`, and the deployment says nothing at all. That is how the Notion path
+ * stayed dead for weeks. `deploy:census` proves a row EXISTS; nothing proved the deployment REACTS
+ * when one does not. So this broker writes {@link CREDENTIAL_UNRESOLVED} before it throws.
+ *
+ * THE VERDICT DOES NOT CHANGE — availability over integrity still holds. The row is an observation,
+ * the throw is the behaviour, and the audit write is best-effort: it can never be the reason a
+ * resolution fails differently than it did before.
+ */
+export function makeDbCredentialBroker(): CredentialBroker {
+  return {
+    async getSecret(ref) {
+      const reserved = reservedRefNamespace(ref);
+      if (reserved) {
+        await auditUnresolved(ref, "reserved-namespace");
+        throw new CredentialError(reservedRefRefusal(ref, reserved));
+      }
+      const row = await getOperationalStore().getStoredCredential(deploymentOrg(), ref);
+      if (!row) {
+        await auditUnresolved(ref, "no-stored-row");
+        throw new CredentialError(`secret not found for ref "${ref}" (no stored credential — store one via the "Set API key" flow)`);
+      }
+      return decryptCredential(row.ciphertext);
+    },
+  };
+}
+
+// The audit action and the reason vocabulary are the BROKER SEAM's (access/credentials.ts), not this
+// broker's: OPE-776 added two more refusal classes one layer up, and one census / forensic read /
+// test must be able to ask for the same string whichever layer refused. Re-exported here so every
+// importer that already reads them from this module is unchanged.
+export { CREDENTIAL_UNRESOLVED };
+export type { UnresolvedReason };
+
+/**
+ * Record ONE unresolvable db credential ref. Best-effort and silent on failure — an audit write must
+ * never turn a clean refusal into a different one.
+ *
+ * 🔴 THE DETAIL CARRIES POINTERS, NEVER MATERIAL: the broker name, the ref, and a fixed reason
+ * string. No value, no length, no prefix, no hash, and no caught error text — a broker error is not
+ * ours to trust into an audit row. The ref is the whole point: it is what an operator needs to act
+ * ("store a row for db:notion:channel-key"), and it is a NAME, not a secret.
+ *
+ * `platform: "credential"` follows approvals/actions.ts `whereFromScope`: the platform column says
+ * what KIND of thing a row is about when no surface owns it, and `workspace` carries the identifier
+ * — here the broker. A ref that stays unresolvable writes a row per attempt on purpose. A repeated
+ * refusal is the signal, and its rate is what tells a dead path from a one-off.
+ */
+async function auditUnresolved(ref: string, reason: UnresolvedReason): Promise<void> {
+  await appendAudit({
+    org: deploymentOrg(),
+    platform: "credential",
+    workspace: DB_BROKER,
+    action: CREDENTIAL_UNRESOLVED,
+    detail: { broker: DB_BROKER, ref, reason },
+  }).catch(() => undefined);
+}
+
+/** Register the `db` broker under its canonical name. Call once at startup (register-adapters.ts). */
+export function registerDbCredentialBroker(): void {
+  registerBroker(DB_BROKER, makeDbCredentialBroker());
+}
+
+// The `db` CredentialHome (R1) — the WRITE target the intake resolves for a `db:` ref. Registered at
+// module load (this module is value-imported wherever a db ref is stored), INDEPENDENT of the db
+// broker's registration: `store` writes via storeDbSecret (which needs only the AES key, not the
+// registered read broker), while `hostWriteAvailable` separately reflects whether the read broker is
+// armed — so the connector offer only advertises "Set API key" once the db broker is registered.
+registerCredentialHome({
+  name: DB_BROKER,
+  hostWriteAvailable: () => registeredBrokerNames().includes(DB_BROKER),
+  async store(input) {
+    await storeDbSecret({
+      org: input.org,
+      ref: input.ref,
+      plaintext: input.plaintext,
+      ...(input.connector ? { connector: input.connector } : {}),
+      ...(input.domain ? { domain: input.domain } : {}),
+      createdBy: input.createdBy,
+    });
+  },
+});

package/agent/credentials/home.ts

@@ -0,0 +1,83 @@
+// The CredentialHome registry (R1 — provider-agnostic credential homes) — WHERE a pasted work-surface
+// secret is WRITTEN, host-side, and whether ANY home can take one right now.
+//
+// The credential-intake webhook (credentials/intake.ts) used to hand-enumerate write homes by a closed
+// vendor branch, and the connector offer keyed its "Set API key" option off a per-vendor "armed"
+// signal. A CredentialHome instead REGISTERS one write target under a home name (the same name the
+// RefCodec stamps, credentials/ref.ts). Intake resolves `credentialHome(parsedRef.home).store(...)`;
+// the offer asks `hostWriteHomeAvailable(registeredCredentialHomes())`. A new vendor (ToolHive-class)
+// registers its home and BOTH paths route it — no edit to intake or the offer.
+//
+// This module is a PURE registry leaf: it holds no vendor logic and imports nothing. The core db home
+// registers from its OWN module (credentials/db-broker.ts), so a home's backing (the db AES key) lives
+// with the home.
+
+/** The context a home's write needs. Vendor-neutral: `parsed` carries the RefCodec's structured
+ *  fields (parseCredentialRef result — e.g. a db home reads none) and `deps` is an opaque per-call DI
+ *  bag (the intake test seam) each home narrows for the one key it understands. */
+export interface CredentialHomeStoreInput {
+  /** The tenant the credential belongs to (the intake's org). */
+  readonly org: string;
+  /** The full stored ref (db:… / a vendor's) — the lookup key egress later resolves. */
+  readonly ref: string;
+  /** The pasted value — handed straight to the home's write path, NEVER logged/audited/held. */
+  readonly plaintext: string;
+  /** Connector label (audit/admin views only). */
+  readonly connector?: string;
+  /** Domain label (audit/admin views only). */
+  readonly domain?: string;
+  /** The storing principal (the intake requester). */
+  readonly createdBy: string;
+  /** The RefCodec's structured fields for `ref` (parseCredentialRef result, minus `home`). */
+  readonly parsed: Readonly<Record<string, string>>;
+  /** Per-call DI overrides (the intake test seam). Structurally typed so this module stays vendor-free;
+   *  each home narrows the one key it understands. */
+  readonly deps?: Readonly<Record<string, unknown>>;
+}
+
+/** A place a pasted work-surface secret can live, host-side. */
+export interface CredentialHome {
+  /** The home name — the RefCodec home the ref stamps (credentials/ref.ts DB_HOME, or a registered
+   *  vendor home). */
+  readonly name: string;
+  /** Can a pasted key be WRITTEN to this home host-side right now? Registration-gated: the connector
+   *  offer keys the "Set API key" option off ANY registered home returning true. (db: its broker is
+   *  registered; env: false — operator-only.) */
+  hostWriteAvailable(): boolean;
+  /** Store a pasted secret under this home. FAIL CLOSED (throw) if the home's backing layer is not
+   *  configured — NEVER silently redirect to another home (a value in the wrong custody home is the bug). */
+  store(input: CredentialHomeStoreInput): Promise<void>;
+}
+
+const HOMES = new Map<string, CredentialHome>();
+
+/** Register a credential home by name. Idempotent overwrite (last wins), mirroring registerBroker. */
+export function registerCredentialHome(home: CredentialHome): void {
+  HOMES.set(home.name, home);
+}
+
+/** The registered home for `name`, or undefined when none is registered (the caller fails closed —
+ *  never a silent fallback to another home). */
+export function credentialHome(name: string): CredentialHome | undefined {
+  return HOMES.get(name);
+}
+
+/** Every registered home (the connector offer passes this to {@link hostWriteHomeAvailable}). */
+export function registeredCredentialHomes(): readonly CredentialHome[] {
+  return [...HOMES.values()];
+}
+
+/** Test seam: forget all registered homes. (No auto-restore — the core homes re-register on their
+ *  modules' next load; a single test file runs in its own process.) */
+export function resetCredentialHomes(): void {
+  HOMES.clear();
+}
+
+/** Is a host-write-capable HOME available among `homes` — can a pasted key be stored somewhere
+ *  host-side? True iff any home reports {@link CredentialHome.hostWriteAvailable}. The connector offer
+ *  passes {@link registeredCredentialHomes}; a bounded set is passed in tests. Fail closed (false) on
+ *  an empty set. */
+export function hostWriteHomeAvailable(homes: Iterable<CredentialHome>): boolean {
+  for (const h of homes) if (h.hostWriteAvailable()) return true;
+  return false;
+}

package/agent/credentials/intake-page.ts

@@ -0,0 +1,302 @@
+// The one-shot credential-intake PAGE front door (task #113, stage 6) — the UNIVERSAL bottom rung of
+// the intake preference ladder (modal → button+URL → the page). Slack has a native secret modal
+// (credentials/intake.ts); Discord/Teams and the modal-less surfaces (Notion/GitHub/Linear) get a
+// LINK instead: a signed, single-use, ~15-minute URL the requester opens in a browser to enter the
+// key on a minimal self-contained HTML form. The value is POSTed straight to THIS host and stored
+// through the EXACT same seam the Slack modal uses (completeCredentialIntake) — same validation
+// ordering, same single-use CAS, same CredentialHome write, same `credential.stored` audit (value
+// NEVER touched). The agent/model is never in the loop: it couriers the link, never the secret.
+//
+// THE TOKEN is a WRITE-ONLY capability bound to ONE intake row:
+//   • HMAC-SHA256 over a compact JSON claim set — `{ v, org, id, rb, exp }` — with the deployment
+//     secret OE_INTAKE_PAGE_SIGNING_KEY. `id` binds the specific intake request row; `rb` pins the
+//     requester identity; `exp` is a hard ~15-min wall (equal to the intake row's own expiry).
+//   • SINGLE-USE via the intake row's compare-and-set consume (consumeCredentialIntake) — the SAME
+//     row the Slack modal consumes, so an intake can be completed through the modal OR the page but
+//     never both. Consumed ⇒ every later POST is refused.
+//   • WRITE-ONLY: the page can ONLY store. It never reads back a stored value, never lists anything,
+//     never returns a token/secret. The GET renders a form; there is no read endpoint.
+//
+// FAIL CLOSED on every axis (no oracle about what exists):
+//   • No signing key configured ⇒ BOTH routes 404 — the endpoint effectively does not exist (the
+//     same posture as oe-oauth-callback with no completer / self-dispatch with no secret).
+//   • A malformed / mis-signed / expired token, an unknown / consumed / expired intake row, or any
+//     store failure ⇒ ONE generic 404 page with identical copy — a holder learns nothing about which
+//     of those it hit. The only 200 is a successful store (or the form for a still-valid token).
+//   • An EMPTY submit re-renders the form (a genuine mistake, pre-consume — never burns the row),
+//     exactly the Slack modal's "Enter the API key" behaviour. The single-attempt guarantee is the
+//     row's CAS consume: the value is stored at most once per token.
+//
+// DELIVERY / ATTRIBUTION — the deliberate trade, worth understanding before changing it. The link is
+// HOST-POSTED into the conversation the admin asked from, so on a channel everyone who can read that
+// channel can see the URL, and the page has NO login — the signed token IS the identity assertion. A
+// different channel member could therefore open it and submit a value, which the audit would attribute
+// to the bound requester (`rb`). That is ACCEPTED because the capability is strictly WRITE-ONLY: the
+// worst outcome is storing a credential (a witnessed, audited act carrying the ref + the bound
+// requester), never reading or listing one — so channel delivery is the witnessed FLOOR, with DM
+// delivery preferred where the surface offers it. Only an ADMIN's turn can mint a link at all (the
+// offer resolver omits the org-level api-key option for a non-admin), and the token binds that one
+// requester. What would change this: making the page identity-bearing (an OAuth'd session, or a
+// per-user nonce confirmed out of band) — which is the right move the moment the page ever grows a
+// READ affordance, because the write-only property is exactly what makes this trade sound.
+//
+// ⭐ THE FLIP CONDITION FIRED (OPE-150) — AND THE ANSWER WAS A SEPARATE ROUTE, NOT A WIDER ONE.
+// A READ affordance now exists: the webhook-secret REVEAL page (webhooks/reveal-page.ts), where the
+// host MINTS a signing secret and a human must read it exactly once. Rather than growing this page
+// a read mode and inheriting a delivery trade that is only sound while it is write-only, the read
+// lives on its OWN path with its OWN, strictly stronger rules — no channel posting AT ALL (private
+// delivery is a propose-time precondition and the tool refuses on surfaces without one), a GET that
+// has zero side effects so an unfurler cannot burn it, and a POST that consumes the grant BEFORE it
+// decrypts anything. The two routes share this file's TOKEN CODEC (credentials/page-token.ts) and
+// the `credential_intake` TABLE, and nothing else. TWO walls keep them from replaying onto each
+// other, and they are what make "a separate route" more than a naming convention:
+//   1. a REQUIRED audience claim on the token (`aud`), checked per route;
+//   2. a ROW CLASS (OPE-607) — reveal grants carry a reserved `connector` sentinel, this route
+//      refuses any row that carries one, and it refuses to MINT one. The second wall stands even
+//      when the first is defeated, and it stands in both directions.
+
+import { createCredentialIntake, completeCredentialIntake, type RequestCredentialIntakeInput, type CredentialIntakeDeps } from "./intake.js";
+import { getOperationalStore } from "../operational/provider.js";
+import { mintPageToken, pageBaseUrl, verifyPageToken, isReservedGrantConnector, PAGE_TOKEN_KEY_ENV, type PageTokenClaims } from "./page-token.js";
+import { getOrMintSelfSecret, selfSecretsArmed } from "./self-secrets.js";
+import type { CredentialIntakeRow } from "../operational/store.js";
+
+/** The mounted route path — GET renders the form, POST stores the value. Same path for both. */
+export const INTAKE_PAGE_PATH = "/connect/v1/intake";
+
+/** The form field the token rides in (hidden input) and the field the pasted value lands in. */
+const TOKEN_FIELD = "t";
+const VALUE_FIELD = "k";
+
+/** The signing secret, minting it on first use (OPE-408 step 3 — credentials/self-secrets.ts). */
+async function intakePageSigningKey(env: NodeJS.ProcessEnv = process.env): Promise<string> {
+  return getOrMintSelfSecret(PAGE_TOKEN_KEY_ENV, { env });
+}
+
+/** The deployment's OWN public base URL for the intake link — see credentials/page-token.ts. */
+function intakePageBaseUrl(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  return pageBaseUrl(env);
+}
+
+/** Can this deployment mint + serve intake-page links? (the vault armed AND a resolvable base URL —
+ *  the delivery precondition; the connector card keys its `page` route off this.) SYNC: minting
+ *  never fails once the vault is armed, so "available" reduces to "can I mint" + "do I know my URL". */
+export function intakePageAvailable(env: NodeJS.ProcessEnv = process.env): boolean {
+  return selfSecretsArmed() && intakePageBaseUrl(env) !== undefined;
+}
+
+// --- token codec (the shared one, pinned to this route's AUDIENCE) --------------------------------
+//
+// OPE-150 moved the codec to credentials/page-token.ts and added a REQUIRED `aud` claim, because a
+// SECOND front door now verifies against the same key (the webhook-secret reveal page). These two
+// wrappers are the intake route's audience pin: nothing in this file can mint or accept a token for
+// the other audience, because neither wrapper takes the audience as an argument.
+
+/** This route's claim set — the shared claims with `aud` fixed to `"intake"`. */
+export type IntakePageClaims = Omit<PageTokenClaims, "aud">;
+
+/** Mint an intake-page token (audience `"intake"`). CAPABILITY-BEARING; NEVER log it. */
+export function mintIntakePageToken(claims: IntakePageClaims, secret: string): string {
+  return mintPageToken({ ...claims, aud: "intake" }, secret);
+}
+
+/** Verify + decode an INTAKE token. `null` for anything invalid, expired — or minted for the OTHER
+ *  audience (a reveal token is refused here, and vice versa). */
+export function verifyIntakePageToken(token: string, secret: string, now: number = Date.now()): IntakePageClaims | null {
+  const c = verifyPageToken(token, secret, "intake", now);
+  return c ? { v: c.v, org: c.org, id: c.id, rb: c.rb, exp: c.exp } : null;
+}
+
+// --- link issuance (the non-Slack delivery path) --------------------------------------------------
+
+/** Deps for {@link issueIntakePageLink} — env override + the createCredentialIntake DI seam. */
+export interface IssueIntakePageLinkDeps extends CredentialIntakeDeps {
+  readonly env?: NodeJS.ProcessEnv;
+}
+
+/**
+ * Create ONE intake row (surface-neutral — no chat post) and return the browser link the requester
+ * opens to enter the key. The token's expiry equals the row's expiry, so link + row age out together.
+ * Returns `undefined` when the page is not available on this deployment (no signing key / no base URL)
+ * — the caller then degrades to honest text, never a dead link. The URL is CAPABILITY-BEARING; the
+ * caller delivers it into the (witnessed) conversation and NEVER logs/audits it.
+ */
+export async function issueIntakePageLink(
+  input: RequestCredentialIntakeInput,
+  deps: IssueIntakePageLinkDeps = {},
+): Promise<{ id: string; url: string } | undefined> {
+  const env = deps.env ?? process.env;
+  const base = intakePageBaseUrl(env);
+  if (!base || !selfSecretsArmed()) return undefined;
+  const secret = await intakePageSigningKey(env);
+
+  const { id, expiresAt } = await createCredentialIntake(input, deps);
+  const token = mintIntakePageToken(
+    { v: 1, org: input.org, id, rb: input.requestedBy, exp: Date.parse(expiresAt) },
+    secret,
+  );
+  const url = `${base}${INTAKE_PAGE_PATH}?${TOKEN_FIELD}=${encodeURIComponent(token)}`;
+  return { id, url };
+}
+
+// --- page rendering (self-contained, no external assets) ------------------------------------------
+
+/** Minimal HTML entity escape for the few values interpolated into the page. */
+function esc(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:30rem;margin:3rem auto;padding:0 1rem;color:#1a1a1a;background:#fff";
+
+function htmlResponse(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">` +
+    `<title>${esc(title)}</title></head>` +
+    `<body style="${PAGE_STYLE}"><h1 style="font-size:1.25rem">${esc(title)}</h1>${inner}</body></html>`;
+  return new Response(html, { status, headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" } });
+}
+
+/** THE ONE generic failure — identical for a bad/expired/consumed/unknown token or row, so a holder
+ *  learns nothing about what exists (no oracle). Always 404. */
+function invalidPage(): Response {
+  return htmlResponse(
+    404,
+    "This link is not valid",
+    `<p>This credential link is not valid, or it has already been used or expired. Ask for a fresh one where you were given it.</p>`,
+  );
+}
+
+/** The intake form. `connector`/`domain` are shown to help the (token-holding) requester know what to
+ *  enter — visible only to someone holding a valid unconsumed token. `notice` is an optional inline
+ *  message (an empty-submit retry). The token rides a hidden field; the value posts to the same path. */
+function formPage(token: string, connector: string, domain: string | undefined, notice?: string): Response {
+  const forWhom = domain ? `${esc(connector)} key for ${esc(domain)}` : `${esc(connector)} key`;
+  const noticeHtml = notice ? `<p style="color:#b00020">${esc(notice)}</p>` : "";
+  const inner =
+    `<p>Enter the <strong>${forWhom}</strong>. It is stored encrypted on this deployment; the agent never sees it, and this link works only once.</p>` +
+    noticeHtml +
+    `<form method="post" action="${esc(INTAKE_PAGE_PATH)}" autocomplete="off">` +
+    `<input type="hidden" name="${TOKEN_FIELD}" value="${esc(token)}">` +
+    `<label for="k" style="display:block;font-weight:600;margin:.75rem 0 .25rem">API key</label>` +
+    `<input id="k" name="${VALUE_FIELD}" type="password" autocomplete="off" spellcheck="false" ` +
+    `style="width:100%;box-sizing:border-box;padding:.6rem;font:inherit;border:1px solid #ccc;border-radius:.4rem">` +
+    `<button type="submit" style="margin-top:1rem;padding:.6rem 1.2rem;font:inherit;font-weight:600;color:#fff;background:#1a56db;border:0;border-radius:.4rem;cursor:pointer">Store securely</button>` +
+    `</form>`;
+  return htmlResponse(200, "Enter an API key", inner);
+}
+
+// --- route handlers -------------------------------------------------------------------------------
+
+/** Injectable deps for the handlers (env + the store-side DI seam). */
+export interface IntakePageHandlerDeps extends CredentialIntakeDeps {
+  readonly env?: NodeJS.ProcessEnv;
+}
+
+/**
+ * Is this row an INTAKE row this token may still act on — present, of the intake CLASS, unconsumed,
+ * owned by the token's bound principal, and unexpired?
+ *
+ * 🔴 THE CLASS TEST IS THE SECOND WALL (OPE-607), and it is the mirror of the reveal route's
+ * `grantOpen`. `credential_intake` holds grant rows of other classes too — a webhook-reveal grant
+ * carries a reserved `connector` sentinel — and a token whose `aud:"intake"` check was somehow
+ * defeated would otherwise reach one. Every path in this file that reads a row goes through here, so
+ * the form cannot render for a grant row and the POST cannot complete one. The finalize seam
+ * (`completeCredentialIntake`) re-checks it, because this page is not its only front door.
+ */
+function intakeRowOpen(row: CredentialIntakeRow | null, boundTo: string, nowMs: number): row is CredentialIntakeRow {
+  return (
+    row !== null &&
+    !row.usedAt &&
+    !isReservedGrantConnector(row.connector) &&
+    row.requestedBy === boundTo &&
+    Date.parse(row.expiresAt) > nowMs
+  );
+}
+
+/**
+ * GET {@link INTAKE_PAGE_PATH}?t=<token> — render the entry form for a valid, unconsumed token, else
+ * the generic 404. Fail closed: no signing key ⇒ 404 (route absent). Verifies the token, then confirms
+ * the bound intake row is still present, owned by the token's requester, and unexpired/unconsumed —
+ * else the same generic 404 (no oracle). NEVER an open redirect: only inline HTML is returned.
+ */
+export async function handleIntakePageGet(req: Request, deps: IntakePageHandlerDeps = {}): Promise<Response> {
+  const env = deps.env ?? process.env;
+  if (!selfSecretsArmed()) return new Response("not found", { status: 404 });
+  const secret = await intakePageSigningKey(env);
+
+  const now = (deps.now ?? (() => new Date()))().getTime();
+  const token = new URL(req.url).searchParams.get(TOKEN_FIELD) ?? "";
+  const claims = verifyIntakePageToken(token, secret, now);
+  if (!claims) return invalidPage();
+
+  // The token is authentic; confirm the row it names is still completable (present, of the INTAKE
+  // class, owned, unexpired, unconsumed). Any miss ⇒ the same generic 404 — a valid-but-spent token
+  // reveals nothing, and neither does one that names a grant row of another class.
+  const intake = await getOperationalStore().getCredentialIntake(claims.org, claims.id);
+  if (!intakeRowOpen(intake, claims.rb, now)) return invalidPage();
+  return formPage(token, intake.connector, intake.domain);
+}
+
+/**
+ * POST {@link INTAKE_PAGE_PATH} (form-encoded `t`=token, `k`=value) — verify the token, then store the
+ * value through the SHARED completeCredentialIntake seam (single-use CAS, CredentialHome write,
+ * `credential.stored` audit, stage-5 binding PR). Fail closed: no signing key ⇒ 404. A bad/expired
+ * token, or any completion failure other than an empty value, ⇒ the generic 404 (no oracle). An empty
+ * value re-renders the form (pre-consume; never burns the token). On success ⇒ a plain 200 confirmation.
+ *
+ * The submitting identity is the token's `rb` (the requester the intake was bound to) — the page has
+ * no login, so the signed token IS the identity assertion. completeCredentialIntake re-checks it equals
+ * the row's requestedBy (defence in depth against a row mutated after mint).
+ */
+export async function handleIntakePagePost(req: Request, deps: IntakePageHandlerDeps = {}): Promise<Response> {
+  const env = deps.env ?? process.env;
+  if (!selfSecretsArmed()) return new Response("not found", { status: 404 });
+  const secret = await intakePageSigningKey(env);
+
+  const now = (deps.now ?? (() => new Date()))().getTime();
+
+  let form: FormData;
+  try {
+    form = await req.formData();
+  } catch {
+    return invalidPage();
+  }
+  const token = typeof form.get(TOKEN_FIELD) === "string" ? (form.get(TOKEN_FIELD) as string) : "";
+  // The pasted value — read then handed straight to completeCredentialIntake; never logged/echoed here.
+  const value = typeof form.get(VALUE_FIELD) === "string" ? (form.get(VALUE_FIELD) as string) : "";
+
+  const claims = verifyIntakePageToken(token, secret, now);
+  if (!claims) return invalidPage();
+
+  // A pre-consume empty check so a genuine blank submit re-renders the form (matching the Slack modal)
+  // rather than routing to the generic 404 — but ONLY once we've confirmed the row is still showable.
+  if (!value.trim()) {
+    const intake = await getOperationalStore().getCredentialIntake(claims.org, claims.id);
+    if (!intakeRowOpen(intake, claims.rb, now)) return invalidPage();
+    return formPage(token, intake.connector, intake.domain, "Enter the API key.");
+  }
+
+  const result = await completeCredentialIntake(
+    { org: claims.org, id: claims.id, value, submittedBy: claims.rb, audit: { platform: "web", workspace: "intake-page", surface: INTAKE_PAGE_PATH } },
+    deps,
+  );
+  if (!result.ok) {
+    if (result.code === "empty") {
+      // Raced to empty after the trim check — re-render rather than 404 (still pre-consume). The
+      // same open test as every other arm: a row of the wrong class never renders a form.
+      const intake = await getOperationalStore().getCredentialIntake(claims.org, claims.id);
+      if (intakeRowOpen(intake, claims.rb, now)) return formPage(token, intake.connector, intake.domain, "Enter the API key.");
+    }
+    return invalidPage(); // every other failure collapses to one generic page — no oracle
+  }
+
+  const forWhom = result.domain ? `${esc(result.connector)} key for ${esc(result.domain)}` : `${esc(result.connector)} key`;
+  return htmlResponse(
+    200,
+    "API key stored",
+    `<p>Your <strong>${forWhom}</strong> was stored securely. The agent never saw the value, and this link is now used up. You can close this tab.</p>`,
+  );
+}