@open-everywhere/core 0.1.0

package/agent/connections/grant-mcp-borrow.ts

@@ -0,0 +1,334 @@
+// THE BORROW DIAL: one resolution for both callers — the spend path and the approve-time catalogue read.
+// 🔴 The fence is not optional on either: {@link withBorrowClient} wraps the caller's BASE fetch itself.
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { FetchLike } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { findConnectorCredential, vercelConnectorOf } from "../access/connector-credentials.js";
+import { assertCredentialEndpointHostAllowed } from "../access/credential-endpoints.js";
+import { CREDENTIAL_GRANT_ROLES } from "../access/credential-grant.js";
+import { fenceMcpBorrowFetch } from "../access/mcp-call-fence.js";
+import { withRetryAfter, type RetryPolicy } from "../channels/rate-limit-retry.js";
+import type { GrantJsonObject } from "../operational/credential-grant-rows.js";
+import { connectorTransportSpec, type ConnectorTransportSpec } from "./connector-transport.js";
+import { requireUserAuthFlow, userAuthFlowProvider, type UserAuthSubject } from "./user-auth-flow.js";
+
+/**
+ * How long the WHOLE approve-time read may take — probe, mint, handshake and `tools/list` on ONE clock, not
+ * one timeout each. Both interactive doors acknowledge before the read: Discord defers and edits its
+ * interaction response, while Slack holds the work under the route's `waitUntil`. The bound therefore
+ * protects the host hold and the owner's retry path rather than serving as the surface acknowledgement
+ * deadline. Five seconds admits a healthy cold catalogue without turning a vendor stall into an unbounded
+ * invocation.
+ */
+export const BORROW_APPROVE_READ_BUDGET_MS = 5_000;
+
+/**
+ * One shared budget. 🔴 It is STATE, not only a clock reading: Node fires a timer up to 1 ms EARLY against
+ * `Date.now()`, so a refused leg could be followed by a read that still answered 1. `markSpent` closes that.
+ */
+export interface BorrowDeadline {
+  remainingMs(): number;
+  /** Record that the budget is gone. `remainingMs` answers 0 from here on, clock or no clock. */
+  markSpent(): void;
+}
+
+/** Start the shared budget. Threaded through the probe, the mint and the catalogue read so all of
+ *  them spend ONE budget rather than one each. */
+export function borrowDeadline(budgetMs: number = BORROW_APPROVE_READ_BUDGET_MS, nowMs: number = Date.now()): BorrowDeadline {
+  const endsAt = nowMs + budgetMs;
+  let spent = false;
+  return {
+    remainingMs: () => (spent ? 0 : Math.max(0, endsAt - Date.now())),
+    markSpent: () => {
+      spent = true;
+    },
+  };
+}
+
+/**
+ * Run `leg` against the shared deadline, or throw naming what ran out of time. 🔴 It does NOT cancel the leg
+ * — what the race buys is that the owner's tap is answered, with the ask still pending for a second press.
+ */
+export async function withinBorrowDeadline<T>(deadline: BorrowDeadline, what: string, leg: () => Promise<T>): Promise<T> {
+  const left = deadline.remainingMs();
+  if (left <= 0) throw new Error(`granted call: the approve-time budget was spent before ${what} could run (connections/grant-mcp-borrow.ts).`);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      leg(),
+      new Promise<never>((_resolve, reject) => {
+        timer = setTimeout(() => {
+          // 🔴 MARK BEFORE REJECTING (OPE-1309). The rejection refuses THIS leg; the mark is what
+          // stops the NEXT leg from running on a budget the clock has not quite finished spending.
+          // Node's timer can fire 1 ms early against `Date.now()`, so the mark — not the reading —
+          // is what makes the bound end-to-end.
+          deadline.markSpent();
+          reject(new Error(`granted call: ${what} did not answer within the approve-time budget (connections/grant-mcp-borrow.ts).`));
+        }, left);
+      }),
+    ]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
+
+/** How this client names itself in the MCP handshake. Host-authored, and it names no person. */
+const BORROW_CLIENT_INFO = { name: "open-everywhere-grant-borrow", version: "1.0.0" } as const;
+
+/** Injection seam for the tier-1 tests: the connection lookup, the mint and the wire. Production
+ *  passes none of them, so it takes the real registry, the real user-auth flow and the real
+ *  `fetch`. */
+export interface GrantBorrowDeps {
+  /** Resolve what a connection declared. Defaults to the connector-transport registry. */
+  readonly connectorSpec?: (connector: string) => ConnectorTransportSpec | undefined;
+  /** Mint the owner's access token for one OAuth vault subject. Defaults to the registered
+   *  user-auth flow, which is the only production path. */
+  readonly mintOwnerToken?: (provider: string, providerRef: string, vaultSubject: string) => Promise<string>;
+  /** The BASE fetch the fence wraps — never the fenced one. A test that injected an already-fenced
+   *  fetch would prove nothing about whether this module fences. */
+  readonly fetch?: FetchLike;
+  /** The 429 backoff policy {@link borrowRetryFetch} applies (OPE-1338). A test injects a stub sleep
+   *  and clock here; production passes nothing and takes the shared defaults. */
+  readonly retry?: RetryPolicy;
+}
+
+/** One resolved borrow connection: where it is dialled, and which OAuth home mints for it. */
+export interface BorrowConnection {
+  readonly connector: string;
+  readonly directUrl: string;
+  readonly url: URL;
+  /** The provider whose catalogue holds the personal credential. */
+  readonly provider: string;
+  /** The opaque per-provider OAuth connector id the owner's token is minted against. */
+  readonly providerRef: string;
+}
+
+/** The personal-credential id the grant plane spends for `connector`, or `undefined` when the plane
+ *  admits no grant for it at all. `CREDENTIAL_GRANT_ROLES` is the single reviewed list, so this
+ *  never guesses a credential id from a connector name. */
+function grantRoleCredential(connector: string): string | undefined {
+  return CREDENTIAL_GRANT_ROLES.find((r) => r.connector === connector)?.role;
+}
+
+/**
+ * Resolve the connection one borrow dials, or throw naming the boundary. The ORDER is the contract: the
+ * connection, then the admitted credential, then the credential's declared reach — all of it before any mint.
+ */
+export function resolveBorrowConnection(connector: string, deps: GrantBorrowDeps = {}): BorrowConnection {
+  const spec = (deps.connectorSpec ?? connectorTransportSpec)(connector);
+  if (spec === undefined) {
+    throw new Error(
+      `granted call: this deployment carries no "${connector}" connection, so there is no MCP server to borrow the ` +
+        "tool from (connections/grant-mcp-borrow.ts).",
+    );
+  }
+  let url: URL;
+  try {
+    url = new URL(spec.directUrl);
+  } catch {
+    throw new Error(`granted call: the "${connector}" connection's URL does not parse, so the borrow cannot be dialled (connections/grant-mcp-borrow.ts).`);
+  }
+  // The PROVIDER whose catalogue holds the personal credential. A connection that declares one says
+  // so; otherwise the connector's own name is the provider, which is the shape every grant-admitting
+  // connection in this tree has.
+  const provider = spec.provider ?? connector;
+  const credentialId = grantRoleCredential(connector);
+  if (credentialId === undefined) {
+    throw new Error(
+      `granted call: "${connector}" is not in CREDENTIAL_GRANT_ROLES, so no personal credential is admitted for it ` +
+        "(access/credential-grant.ts).",
+    );
+  }
+  const cred = findConnectorCredential(provider, credentialId);
+  if (cred === undefined) {
+    throw new Error(
+      `granted call: this deployment configures no "${credentialId}" ${provider} credential, so there is no per-user ` +
+        "credential to spend. Declare one in agent/access/connector-credentials.ts (connections/grant-mcp-borrow.ts).",
+    );
+  }
+  const providerRef = vercelConnectorOf(cred);
+  if (providerRef === undefined) {
+    throw new Error(
+      `granted call: the "${credentialId}" ${provider} credential declares no OAuth home, so no per-user token can be ` +
+        "minted from it (connections/grant-mcp-borrow.ts).",
+    );
+  }
+  assertCredentialEndpointHostAllowed(cred.endpoints, spec.directUrl, `granted ${provider} credential "${credentialId}"`);
+  return { connector, directUrl: spec.directUrl, provider, providerRef, url };
+}
+
+/** Mint the OWNER's access token for one resolved connection. 🔴 THE OWNER'S SUBJECT, NEVER THE
+ *  REQUESTER'S — see `access/credential-grant-owner.ts` for why that one line is the whole
+ *  difference between the member plane and a grant. */
+export async function mintBorrowToken(conn: BorrowConnection, vaultSubject: string, deps: GrantBorrowDeps = {}): Promise<string> {
+  const mint =
+    deps.mintOwnerToken ??
+    (async (label: string, ref: string, subject: string): Promise<string> =>
+      (await requireUserAuthFlow(label).mintUserToken(ref, { subject: { id: subject, type: "user" } })).token);
+  return await mint(conn.provider, conn.providerRef, vaultSubject);
+}
+
+/**
+ * The FENCED fetch one borrow may send through. 🔴 The pin is built from the ROW — the connection's host,
+ * `row.mcpTool` in the vendor's exact bytes, and the row's frozen arguments. Exported to test this seam.
+ */
+export function grantBorrowFetch(row: { readonly mcpTool?: string; readonly frozenArgs?: GrantJsonObject }, directUrl: string, base: FetchLike): FetchLike {
+  const url = new URL(directUrl);
+  // `?? ""` reaches the fence, which refuses to BUILD on an empty tool. A row with no vendor tool is
+  // not a borrow, and a fence it could not pin must never be a fence that admits everything.
+  return fenceMcpBorrowFetch({ frozenArgs: row.frozenArgs ?? {}, host: url.host, tool: row.mcpTool ?? "" }, base);
+}
+
+/**
+ * The BASE fetch with the shared 429 backoff, installed BELOW the grant burn — a retry re-sends under the one
+ * burn already taken, and an exhausted retry keeps it. It wraps the BASE, so the fence still runs once.
+ */
+export function borrowRetryFetch(connector: string, base: FetchLike, deps: GrantBorrowDeps = {}, deadline?: BorrowDeadline): FetchLike {
+  return (url, init) => {
+    // 🔴 THE SESSION TEARDOWN IS NEVER RETRIED. `withBorrowClient` calls `terminateSession` in a
+    // `finally`, AFTER the borrow has its result, and swallows whatever it raises — the session ages
+    // out at the vendor when the DELETE does not land, which is why that failure is not the caller's.
+    // Waiting out a rate limit on it would therefore buy nothing and cost the turn up to the whole
+    // budget in a block the caller is already past. Sending it once is the honest shape.
+    if ((init?.method ?? "GET").toUpperCase() === "DELETE") return base(url, init);
+    // Read what is LEFT of the shared budget NOW, not when this wrapper was built — see the note
+    // above. An earlier request that already spent some of it leaves a smaller bound for this one.
+    const budget = deadline?.remainingMs();
+    return withRetryAfter(async () => await base(url, init), {
+      surface: "grant-borrow",
+      // The id-free route SHAPE. The connector is a deployment-level name (`notion`), never a person,
+      // an org or a grant id — so every field on the NAMED failure stays safe to log.
+      operation: `POST /mcp (${connector})`,
+      ...deps.retry,
+      ...(budget === undefined ? {} : { totalBudgetMs: budget }),
+    });
+  };
+}
+
+/**
+ * Open a fenced MCP client, run `body`, tear the session down. 🔴 The caller never sees the transport, so it
+ * cannot bypass the fence. NO client capabilities: the vendor may not ask this client to sample or elicit.
+ */
+export async function withBorrowClient<T>(
+  conn: BorrowConnection,
+  pin: { readonly mcpTool: string; readonly frozenArgs?: GrantJsonObject },
+  token: string,
+  deps: GrantBorrowDeps,
+  body: (client: Client) => Promise<T>,
+  /** The SHARED approve-time clock. Omitted on the SPEND path, which is an ordinary tool call in a
+   *  turn and takes the SDK's own default; passed on the approve-time read, which runs inside a
+   *  button press. The handshake takes its slice off it and `body` takes what is left. */
+  deadline?: BorrowDeadline,
+): Promise<T> {
+  // 🔴 THE ORDER IS THE CONTRACT. The backoff wraps the BASE, then the fence wraps THAT — so the pin
+  // check runs once per logical request and a 429 retry re-sends the bytes it already approved
+  // (OPE-1338). Reversing the two would re-run the fence per attempt.
+  const base = borrowRetryFetch(conn.connector, deps.fetch ?? (globalThis.fetch as FetchLike), deps, deadline);
+  const fenced = grantBorrowFetch(pin, conn.directUrl, base);
+  const transport = new StreamableHTTPClientTransport(conn.url, {
+    fetch: fenced,
+    // 🔴 THE TOKEN RIDES `requestInit`, WHICH THE HOST BUILDS AND THE MODEL NEVER TOUCHES. It is
+    // also why the fence checks the BODY and not the headers — a header is not a channel the model
+    // can reach. No `authProvider` is passed: this transport must never negotiate its own
+    // authorization, only spend the token core resolved.
+    requestInit: { headers: { authorization: `Bearer ${token}` } },
+  });
+  const client = new Client(BORROW_CLIENT_INFO, { capabilities: {} });
+  try {
+    await client.connect(transport, deadline === undefined ? undefined : { timeout: deadline.remainingMs() });
+    return await body(client);
+  } finally {
+    // TEARDOWN IS BEST-EFFORT AND NEVER CHANGES THE RESULT. `terminateSession` is the DELETE the
+    // fence admits; a server that answers 405 (no explicit teardown) is the normal case. Both calls
+    // swallow their own failures, because a throw raised in a `finally` REPLACES the value or the
+    // error the borrow actually produced — a completed read must not surface as a teardown error,
+    // and a fence refusal must not be hidden behind one.
+    try {
+      await transport.terminateSession();
+    } catch {
+      /* the session ages out at the vendor instead — a teardown failure is not the caller's */
+    }
+    try {
+      await client.close();
+    } catch {
+      /* the client is discarded with this call either way */
+    }
+  }
+}
+
+/** What the approve-time catalogue read found. `found: false` carries the tool names the connection
+ *  DID publish, so the refusal can name near misses instead of a bare "no". */
+export type BorrowCatalogueEntry =
+  | { readonly found: true; readonly inputSchema: GrantJsonObject }
+  | { readonly found: false; readonly published: readonly string[] };
+
+/**
+ * Read the vendor's live catalogue under the OWNER's token: a server may publish a different tool list per
+ * account. A tool with no object `inputSchema` reads as ABSENT — there would be nothing to pin.
+ */
+export async function readBorrowToolSchema(
+  conn: BorrowConnection,
+  mcpTool: string,
+  frozenArgs: GrantJsonObject,
+  token: string,
+  deps: GrantBorrowDeps = {},
+  deadline: BorrowDeadline = borrowDeadline(),
+): Promise<BorrowCatalogueEntry> {
+  return await withBorrowClient(
+    conn,
+    { frozenArgs, mcpTool },
+    token,
+    deps,
+    async (client) => {
+      // WHAT THE HANDSHAKE LEFT, not a fresh budget — the two legs share one clock.
+      const listed = await client.listTools(undefined, { timeout: deadline.remainingMs() });
+      const published: string[] = [];
+      let schema: GrantJsonObject | undefined;
+      for (const tool of listed.tools) {
+        published.push(tool.name);
+        // BYTE-EQUAL, never a case-folded or trimmed match. The row dials these exact bytes and the
+        // fence pins them, so a tool this read accepted under a looser comparison would be a tool
+        // the fence refuses on every call.
+        if (tool.name !== mcpTool) continue;
+        const declared: unknown = tool.inputSchema;
+        if (typeof declared === "object" && declared !== null && !Array.isArray(declared)) schema = declared as GrantJsonObject;
+      }
+      return schema === undefined ? { found: false, published: published.sort() } : { found: true, inputSchema: schema };
+    },
+    deadline,
+  );
+}
+
+/**
+ * Has the OWNER connected their own account yet? `undefined` means UNKNOWN and is not a yes — the probe is
+ * optional on the port, so the caller reaches the catalogue read instead of approving on silence.
+ */
+export async function ownerHasConnectorConsent(conn: BorrowConnection, vaultSubject: string): Promise<boolean | undefined> {
+  const flow = userAuthFlowProvider();
+  const probe = flow?.hasFreshGrant;
+  if (flow === undefined || probe === undefined) return undefined;
+  try {
+    return await probe.call(flow, conn.providerRef, ownerSubject(vaultSubject));
+  } catch {
+    // A probe that threw has told us nothing. Reading that as "not connected" would post a connect
+    // link at an owner who is already connected, every time the vault hiccuped.
+    return undefined;
+  }
+}
+
+/**
+ * A CAPABILITY-BEARING URL the OWNER opens to connect their own account. 🔴 The subject is the owner's own
+ * vault subject, so the row it writes is the row a later borrow mints against. Never logged, never echoed.
+ */
+export async function startOwnerConnectorAuthorization(conn: BorrowConnection, vaultSubject: string, expiresInMs: number): Promise<string> {
+  const flow = requireUserAuthFlow(conn.connector);
+  const { url } = await flow.startAuthorization(conn.providerRef, { subject: ownerSubject(vaultSubject) }, { expiresInMs });
+  return url;
+}
+
+/** The owner's OAuth subject, spelled once so the probe and the authorization link can never key on
+ *  two different subjects for one person. */
+function ownerSubject(vaultSubject: string): UserAuthSubject {
+  return { id: vaultSubject, type: "user" };
+}

package/agent/connections/grant-mcp-transport.ts

@@ -0,0 +1,64 @@
+// THE GENERIC MCP BORROW TRANSPORT — one transport, no vendor names, and it may never widen a call, retry
+// under another credential, or fall back to a shared key. A vendor `isError` is vendor bytes, not a refusal.
+
+import type { GrantBorrowCall, GrantBorrowTransport } from "../access/credential-grant-broker.js";
+import {
+  foreignGrantBorrowRegistrant,
+  GrantBorrowTransportAlreadyRegisteredError,
+  registerCoreGrantBorrowTransport,
+} from "../access/grant-borrow-transport-registry.internal.js";
+import type { GrantOwnerSubject } from "../access/credential-grant-owner.js";
+import { CREDENTIAL_GRANT_ROLES } from "../access/credential-grant.js";
+import { asGrantUndispatched, GrantUndispatchedError, type CredentialGrantRow } from "../operational/credential-grant-rows.js";
+import { mintBorrowToken, resolveBorrowConnection, withBorrowClient, type BorrowConnection, type GrantBorrowDeps } from "./grant-mcp-borrow.js";
+
+/** Injection seam for the tier-1 tests — the shared borrow dial's own seam, re-exported under this
+ *  module's name so the transport's callers keep one import. */
+export type GrantMcpTransportDeps = GrantBorrowDeps;
+
+/** The generic borrow transport. One instance serves every connector the grant plane admits. */
+export function grantMcpTransport(deps: GrantMcpTransportDeps = {}): GrantBorrowTransport {
+  return async (call: GrantBorrowCall, grant: CredentialGrantRow, owner: GrantOwnerSubject): Promise<unknown> => {
+    // 🔴 The ROW is the authority on which tool is lent, and the call is not. Pinning the fence to the caller's
+    // value would make its tool check compare a value with itself, so the two are checked against each other.
+    const lentTool = grant.mcpTool;
+    if (lentTool === undefined) {
+      throw new GrantUndispatchedError("granted call: this grant row names no vendor tool, so there is nothing to borrow (connections/grant-mcp-transport.ts).");
+    }
+    if (lentTool !== call.mcpTool) {
+      throw new GrantUndispatchedError(
+        "granted call: the call names a different vendor tool than the grant row lends — refusing rather than dialling either (connections/grant-mcp-transport.ts).",
+      );
+    }
+
+    // 🔴 Every refusal in this block runs BEFORE the borrowed `tools/call` is sent, so each is marked
+    // undispatched. `withBorrowClient` sits outside the `try`: past it, a throw cannot claim the call was not sent.
+    let conn: BorrowConnection;
+    let token: string;
+    try {
+      conn = resolveBorrowConnection(grant.connector, deps);
+      // THE OWNER'S SUBJECT, NEVER THE REQUESTER'S.
+      token = await mintBorrowToken(conn, owner.vaultSubject, deps);
+    } catch (err) {
+      throw asGrantUndispatched(err);
+    }
+    // 🔴 `call.input` GOES OUT UNCHANGED. The granted arguments are `const`-pinned in the tool definition the model reads, so the model supplies them,
+    // and the fence inside `withBorrowClient` compares the outgoing bytes against the ROW. Merging the row's frozen arguments in here would be the transport answering its own fence.
+    return await withBorrowClient(conn, { frozenArgs: grant.frozenArgs, mcpTool: lentTool }, token, deps, async (client) =>
+      await client.callTool({ arguments: { ...call.input }, name: lentTool }),
+    );
+  };
+}
+
+/**
+ * Register the generic borrow transport for every admitted connector, from where the granted tools mount.
+ * Each connector registers ONCE; a connector another registrant holds THROWS, and the set is checked first.
+ */
+export function installGrantBorrowTransports(deps: GrantMcpTransportDeps = {}): void {
+  for (const role of CREDENTIAL_GRANT_ROLES) {
+    const foreign = foreignGrantBorrowRegistrant(role.connector);
+    if (foreign !== undefined) throw new GrantBorrowTransportAlreadyRegisteredError(role.connector, foreign);
+  }
+  const transport = grantMcpTransport(deps);
+  for (const role of CREDENTIAL_GRANT_ROLES) registerCoreGrantBorrowTransport(role.connector, transport);
+}

package/agent/connections/notion.ts

@@ -0,0 +1,42 @@
+// An eve *connection* — the host-side connector plane. The token is attached host-side and the call never
+// enters the sandbox, so the egress firewall does not gate it. The connection's runtime name is this slug.
+
+import { defineMcpClientConnection } from "eve/connections";
+import { connectorApprovalPolicy } from "./connector-auth.js";
+import { selectConnectorTransport } from "./connector-transport.js";
+
+// ⚠ LIVE (2026-07-21): hosted mcp.notion.com accepts tokens from its OWN MCP-OAuth flow only — it 401s
+// integration secrets and public OAuth tokens alike. Only the own-rolled oe-oauth flow arms this — the user
+// subject in a DM (`user-oauth`), and since OPE-1914 the app subject for the org credential (`workspace-oauth`).
+const NOTION_MCP_URL = "https://mcp.notion.com/mcp";
+
+// Transport selection runs ONCE at module load; the settings it depends on are read PER CALL, because this
+// module is scan-mounted and can evaluate before `registerSettings()`. Recording the SPEC here is deliberate.
+const transport = selectConnectorTransport({
+  connector: "notion",
+  provider: "notion",
+  directUrl: NOTION_MCP_URL,
+  fallbackSecretRef: "NOTION_API_KEY",
+  fallbackBroker: "env",
+});
+
+export default defineMcpClientConnection({
+  url: transport.url,
+  description:
+    "Notion workspace (MCP): search and read pages/databases, AND — when the connected " +
+    "integration has edit access — create/update pages and append blocks. This is the team's " +
+    "read/WRITE knowledge base: answer questions grounded in it, and record durable notes back " +
+    "into the page/database a channel points you at. Append under the right heading; don't " +
+    "rewrite whole pages. Notion's API owns the block model, so there's no markdown round-trip.",
+
+  // The provider-routed builder: the per-surface HARD GATE runs first, then it resolves WHICH credential this
+  // surface is bound to, so ten domains can use ten keys. The per-user arm changes the SUBJECT, never the gate.
+  auth: transport.auth,
+
+  // Defence in depth over the hard gates. Armed, it gates per op — reads never prompt, a write prompts once
+  // per session; off, it keeps eve's blanket `once()`.
+  approval: connectorApprovalPolicy(),
+});
+
+// The bound credential's `type` selects the OAuth path, and core carries no OAuth-vendor SDK import.
+// ENFORCEMENT: eve has no per-surface connection filter — `assertConnectorGranted` in getToken is the gate.

package/agent/connections/oe-oauth-callback.ts

@@ -0,0 +1,207 @@
+// Port half of the eve-mounted `GET /oauth/v1/callback`: the adapter's completer runs the code→token
+// exchange. No completer ⇒ 404, so the route is inert until the adapter arms. `state` is opaque, never logged.
+// A successful completion leaves a `connector.credential_bound` audit row (OPE-1937) — see
+// `auditCredentialBound` for what it carries and why it names no principal at all.
+
+import { asConsentResumeRecord, resumeAfterConsent, type ConsentResumeOutcome } from "./consent-resume.js";
+import type { ConsentCarriage } from "./user-auth-flow.js";
+import { appendAudit } from "../audit/audit.js";
+import { deploymentOrg } from "../identity/binding.js";
+
+/** The mounted route path — GET ?state=<opaque>&code=<code> (or &error=…). */
+export const OE_OAUTH_CALLBACK_PATH = "/oauth/v1/callback";
+
+/** The verbatim `state` (opaque single-use id the adapter minted at startAuthorization) + provider
+ *  `code`. Never carries a secret. */
+export interface OeOauthCallbackArgs {
+  readonly state: string;
+  readonly code: string;
+}
+
+/** The completer's outcome — `ok` gates success vs failure rendering; `connectionName` + `detail`
+ *  are shown to the human. NEVER carries a secret (no token transits the callback page). */
+export interface OeOauthCallbackResult {
+  readonly ok: boolean;
+  readonly connectionName?: string;
+  readonly detail?: string;
+  /**
+   * WHICH vault subject the completed consent bound — `app` is the deployment-wide org row every granting
+   * domain spends, `user` is one person's row. Only the TYPE is audited, never the id (see
+   * {@link auditCredentialBound}), and it is never rendered (OPE-1937).
+   */
+  readonly subject?: { readonly type: "app" } | { readonly type: "user"; readonly id: string };
+  /**
+   * Did the bind REPLACE an existing row for that subject? `storeToken` is last-write-wins, so a second
+   * admin's consent silently swaps the credential; this is the flag that puts the swap in the ledger.
+   */
+  readonly rebound?: boolean;
+  /**
+   * The consent carriage the pending row was minted with, handed straight back by the adapter. Present only
+   * when the authorization started from a detour that had a conversation to return to.
+   */
+  readonly consent?: ConsentCarriage;
+}
+
+/** The injected exchange step (the adapter's code→token + vault store). */
+export type OeOauthCallbackCompleter = (args: OeOauthCallbackArgs) => Promise<OeOauthCallbackResult>;
+
+let registered: OeOauthCallbackCompleter | undefined;
+
+/** Called at boot by the adapter's registerOeOauth, only when the OE_OAUTH master flag is armed. */
+export function registerOeOauthCallbackCompleter(fn: OeOauthCallbackCompleter): void {
+  registered = fn;
+}
+
+/** Test seam / rollback: forget the registered completer (the fail-closed 404 path). */
+export function resetOeOauthCallbackCompleter(): void {
+  registered = undefined;
+}
+
+/** The registered completer, or null when the own-rolled OAuth adapter is not armed. */
+export function resolveOeOauthCallbackCompleter(): OeOauthCallbackCompleter | null {
+  return registered ?? null;
+}
+
+function esc(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+function page(status: number, title: string, body: string): Response {
+  const html =
+    `<!doctype html><html lang="en"><head><meta charset="utf-8">` +
+    `<meta name="viewport" content="width=device-width,initial-scale=1">` +
+    `<title>${esc(title)}</title></head><body style="font:16px/1.5 system-ui,sans-serif;max-width:32rem;margin:4rem auto;padding:0 1rem">` +
+    `<h1 style="font-size:1.25rem">${esc(title)}</h1><p>${body}</p></body></html>`;
+  return new Response(html, { status, headers: { "content-type": "text/html; charset=utf-8" } });
+}
+
+/**
+ * Handles the callback: 404 not armed, 400 declined or missing param, 502 exchange rejected, 200 authorized.
+ * It only ever returns an inline page, so a crafted query cannot bounce the browser — never an open redirect.
+ */
+export async function handleOeOauthCallback(
+  req: Request,
+  complete: OeOauthCallbackCompleter | null,
+  deps: OeOauthCallbackDeps = {},
+): Promise<Response> {
+  // Fail closed: no completer ⇒ the own-rolled OAuth layer is not armed ⇒ the route does not exist.
+  if (!complete) return new Response("not found", { status: 404 });
+
+  const url = new URL(req.url);
+  const q = (name: string): string | undefined => {
+    const v = (url.searchParams.get(name) ?? "").trim();
+    return v.length > 0 ? v : undefined;
+  };
+
+  const state = q("state");
+  const code = q("code");
+  const error = q("error");
+
+  if (error) {
+    const desc = q("error_description");
+    return page(
+      400,
+      "Authorization was not granted",
+      `The provider returned <code>${esc(error)}</code>${desc ? `: ${esc(desc)}` : ""}. You can close this tab and try again.`,
+    );
+  }
+  if (!state) return page(400, "Missing authorization state", "This link is missing its <code>state</code> parameter and cannot be completed.");
+  if (!code) return page(400, "Missing authorization code", "This link is missing its <code>code</code> parameter and cannot be completed.");
+
+  let result: OeOauthCallbackResult;
+  try {
+    result = await complete({ state, code });
+  } catch (err) {
+    return page(502, "Could not complete the connection", `The authorization exchange failed: ${esc(err instanceof Error ? err.message : String(err))}.`);
+  }
+  if (!result.ok) {
+    return page(502, "Could not complete the connection", `The authorization exchange was rejected${result.detail ? `: ${esc(result.detail)}` : ""}.`);
+  }
+  await auditCredentialBound(result, deps);
+  const resumed = await runConsentResume(result, deps);
+  return page(
+    200,
+    "Connection authorized",
+    `The connection${result.connectionName ? ` <strong>${esc(result.connectionName)}</strong>` : ""} is now authorized. ` +
+      `${resumeClause(resumed)} You can close this tab.`,
+  );
+}
+
+/** The injected resume seam (OPE-1619). Absent ⇒ the live consent-resume plane. */
+export interface OeOauthCallbackDeps {
+  readonly resume?: typeof resumeAfterConsent;
+  /** The audit sink (OPE-1937). Absent ⇒ the live ledger. */
+  readonly audit?: typeof appendAudit;
+  /** The deployment's org for the audited row. Absent ⇒ the live deployment identity. */
+  readonly org?: () => string;
+}
+
+/**
+ * Record the bind (OPE-1937). A consent completion is where a credential STARTS EXISTING — and, because
+ * `storeToken` is last-write-wins, where one may silently REPLACE another. Before this row the only trace
+ * was `connector.oauth_url_issued` from the click, which says a URL was issued and nothing about what the
+ * URL went on to bind.
+ *
+ * 🔴 WHAT THE ROW CARRIES, AND WHAT IT CANNOT. The connector, the subject type and the rebind flag. NEVER
+ * token material — no token transits this route at all.
+ * 🔴 AND IT NAMES NO PRINCIPAL, ON EITHER SUBJECT TYPE. On an APP subject the route genuinely has none:
+ * the callback authenticates nobody, so whoever opens the URL binds the row, and naming the clicker would
+ * be a guess. On a USER subject the only id in reach is the VAULT SUBJECT — `p:<org>/<platform>/<tenant>/
+ * <id>` (identity/oauth-vault-share.ts), or an `ls:` link-set id that names no person at all. The ledger's
+ * `principal_id` holds the BARE vendor id with the platform in its own column, so writing a vault subject
+ * there would bucket the row away from every other row that person produced. Who ASKED is already on the
+ * record: the click writes `connector.oauth_url_issued` naming the clicker. Naming who COMPLETED would
+ * take the subject decomposed against this row's platform/workspace columns, which this change does not do.
+ * Best-effort, like every audit write: the page still renders if it fails.
+ */
+async function auditCredentialBound(result: OeOauthCallbackResult, deps: OeOauthCallbackDeps): Promise<void> {
+  const subject = result.subject;
+  if (!subject) return; // a completer that reports no subject has nothing to declare — never a guessed row
+  try {
+    await (deps.audit ?? appendAudit)({
+      org: (deps.org ?? deploymentOrg)(),
+      platform: "oauth",
+      workspace: "callback",
+      action: "connector.credential_bound",
+      detail: {
+        connector: result.connectionName ?? "unknown",
+        subject: subject.type,
+        rebound: result.rebound === true,
+      },
+    });
+  } catch {
+    /* the ledger write is best-effort — the human's page must render whatever the store does */
+  }
+}
+
+/**
+ * Resume the request this consent interrupted, if there was one. NEVER throws: the page must render whatever
+ * happens, so a resume failure is a page that says less, not a 502.
+ */
+async function runConsentResume(
+  result: OeOauthCallbackResult,
+  deps: OeOauthCallbackDeps,
+): Promise<ConsentResumeOutcome | undefined> {
+  const record = asConsentResumeRecord(result.consent);
+  if (!record) return undefined;
+  try {
+    return await (deps.resume ?? resumeAfterConsent)(record);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * What the landing page says about the conversation the person came FROM. It states only what actually
+ * happened — the page is the one place a person can check whether their request survived.
+ */
+function resumeClause(outcome: ConsentResumeOutcome | undefined): string {
+  if (!outcome) return "";
+  if (!outcome.delivered) return "Go back to your conversation and ask again — I could not reach it from here.";
+  switch (outcome.verdict) {
+    case "offer":
+      return "I've said so in your conversation — tell me there to carry on with the request you paused.";
+    case "expired":
+      return "The request you paused is too old to pick up on its own; ask me again in your conversation.";
+  }
+}