@runuai/host 0.9.150 → 0.9.152

package/lib/mcp-capture.ts

@@ -0,0 +1,860 @@
+/**
+ * ADR-154 §11 on the sign-in box: an MCP connection's handshake — probe,
+ * discovery (RFC 9728 → RFC 8414), dynamic registration (RFC 7591), PKCE and
+ * the code exchange — every request through the SSRF rule (safe-http.ts),
+ * written as one immutable revision exactly where the cloud's flow says, and
+ * never into this box's own store.
+ *
+ * - A static header the server accepts is the lease-readable part.
+ * - An OAuth sign-in writes the broker-only part first (the refresh token,
+ *   the client and the token endpoint, which only the broker reads), then
+ *   the lease-readable part (the access token and its expiry).
+ * - A server that wants nothing is a `none` connection: nothing is written.
+ *
+ * Between the probe and the callback, the PKCE verifier and client secret
+ * wait in this process's memory, bound to the exact flow and the
+ * authorization server's issuer, for ten minutes at most (or until the cloud
+ * cancels the flow), and are taken once. A box restarted meanwhile says so:
+ * the person connects again.
+ *
+ * The server and everything it names are untrusted:
+ * - discovery takes protected-resource metadata only for this resource
+ *   (RFC 9728) and authorization-server metadata only from its own issuer
+ *   (RFC 8414); a callback must name that issuer when the server supports it
+ *   (RFC 9207), and otherwise the server's endpoints must sit on its own
+ *   origin, so a code meant for one server never reaches another (RFC 9700
+ *   §4.4, mix-up);
+ * - nothing a server says is relayed to the cloud: answers carry fixed
+ *   messages, OAuth error codes from the standard list, and scopes only as a
+ *   subset of those asked for;
+ * - the sign-in page handed to the browser obeys the same public-address
+ *   rule as every request;
+ * - each step, its credential writes included, finishes inside the cloud's
+ *   answer deadline, and the cloud's cancel stops a step where it is (HTTP,
+ *   registration, the code exchange or a write), so nothing the cloud gave
+ *   up on keeps running.
+ */
+
+import { createHash, randomBytes } from "node:crypto";
+
+import {
+  isScopeList,
+  serializeLeasedValue,
+  type CaptureFlowWire,
+  type CaptureResultWire,
+  type CredentialLocation,
+  type McpCaptureAckFrame,
+  type McpCaptureCancelFrame,
+  type McpCaptureCompleteFrame,
+  type McpCaptureProbeFrame,
+} from "../src/cloud-credentials";
+import { parseCaptureFlow, writeCapture, type ParsedCaptureFlow } from "./capture-flow";
+import type { CredentialStore } from "./credential-store";
+import {
+  SafeHttpRefusal,
+  parseSafeUrl,
+  safeJson,
+  safeRequest,
+  vetPublicUrl,
+  type SafeHttpDeps,
+  type SafeHttpLimits,
+} from "./safe-http";
+import { emptyRefreshMeta, refreshMetaFrom, type RefreshMeta } from "./token-lanes/types";
+
+export const MCP_OAUTH_LANE = "mcp-oauth";
+
+/** What only the broker reads for an MCP OAuth connection. */
+export interface BrokerMcpValue {
+  v: 1;
+  part: "broker";
+  location: CredentialLocation;
+  class: "mcp";
+  lane: typeof MCP_OAUTH_LANE;
+  tokenEndpoint: string;
+  clientId: string;
+  clientSecret: string | null;
+  /** The MCP server URL, sent as RFC 8707 `resource` on every grant. */
+  resource: string;
+  accessToken: string;
+  /** Null when the server gave none: the sign-in lapses with its token. */
+  refreshToken: string | null;
+  scopes: string | null;
+  refresh: RefreshMeta;
+}
+
+type AckBody = Omit<McpCaptureAckFrame, "kind" | "opId">;
+
+const PENDING_TTL_MS = 10 * 60_000;
+/** The most sign-ins waiting at once; the oldest goes first past it. */
+export const MAX_PENDING_SIGN_INS = 256;
+/** One step's whole budget, inside the bridge's 45-second answer deadline. */
+export const OPERATION_DEADLINE_MS = 40_000;
+const DISCOVERY_MAX_BYTES = 256 * 1024;
+
+/** The OAuth error codes an answer may name (RFC 6749, 7591, 8707). */
+const OAUTH_ERROR_CODES = new Set([
+  "invalid_request",
+  "invalid_client",
+  "invalid_grant",
+  "unauthorized_client",
+  "unsupported_grant_type",
+  "invalid_scope",
+  "access_denied",
+  "server_error",
+  "temporarily_unavailable",
+  "invalid_target",
+  "invalid_redirect_uri",
+  "invalid_client_metadata",
+]);
+
+/** A token or registration endpoint's failure, never in its own words. */
+export function oauthFailure(json: Record<string, unknown>, status: number): string {
+  return typeof json.error === "string" && OAUTH_ERROR_CODES.has(json.error) ? json.error : `HTTP ${status}`;
+}
+
+interface PendingSignIn {
+  /** The exact flow the probe was for: completion uses this, not the frame's. */
+  flow: CaptureFlowWire;
+  state: string;
+  verifier: string;
+  clientId: string;
+  clientSecret: string | null;
+  issuer: string;
+  /** The server sends RFC 9207 `iss`; a callback without it is refused. */
+  issRequired: boolean;
+  tokenEndpoint: string;
+  redirectUri: string;
+  resource: string;
+  /** What was asked for, space-separated, or null for the default. */
+  scopes: string | null;
+  expiresAt: number;
+  timer: NodeJS.Timeout;
+}
+
+const pendingSignIns = new Map<string, PendingSignIn>();
+
+function flowKey(flow: { credentialId: string; revision: string }): string {
+  return `${flow.credentialId}\u0000${flow.revision}`;
+}
+
+function sameFlow(a: CaptureFlowWire, b: CaptureFlowWire): boolean {
+  return (
+    a.credentialId === b.credentialId &&
+    a.revision === b.revision &&
+    a.leaseParameter === b.leaseParameter &&
+    a.brokerParameter === b.brokerParameter &&
+    a.orgId === b.orgId &&
+    a.userId === b.userId
+  );
+}
+
+function forgetPending(key: string, entry?: PendingSignIn): void {
+  const current = pendingSignIns.get(key);
+  if (!current || (entry && current !== entry)) return;
+  clearTimeout(current.timer);
+  pendingSignIns.delete(key);
+}
+
+function rememberPending(key: string, entry: Omit<PendingSignIn, "timer">): void {
+  forgetPending(key);
+  while (pendingSignIns.size >= MAX_PENDING_SIGN_INS) {
+    const oldest = pendingSignIns.keys().next().value;
+    if (oldest === undefined) break;
+    forgetPending(oldest);
+  }
+  const pending = { ...entry } as PendingSignIn;
+  pending.timer = setTimeout(() => forgetPending(key, pending), Math.max(0, entry.expiresAt - Date.now()));
+  pending.timer.unref();
+  pendingSignIns.set(key, pending);
+}
+
+/** A probe or completion under way, stoppable by the cloud's cancel. */
+interface Step {
+  key: string;
+  state: string;
+  flow: CaptureFlowWire;
+  controller: AbortController;
+}
+
+const steps = new Set<Step>();
+
+/**
+ * Flows the cloud cancelled, so a step for one never begins (or installs a
+ * sign-in) afterwards: by flow and state, until it would have expired. A
+ * marker is never dropped while it lasts, and the table never grows past
+ * MAX_CANCELLED_FLOWS: a cancel that finds it full is kept as one overflow
+ * horizon instead, and until that passes no new step begins at all (fail
+ * closed, in bounded memory).
+ */
+const cancelledFlows = new Map<string, number>();
+export const MAX_CANCELLED_FLOWS = 4096;
+let maxCancelledFlows = MAX_CANCELLED_FLOWS;
+/** Until when a cancel the table had no room for may still apply to any
+ *  flow; 0 when none. */
+let overflowUntil = 0;
+
+/** Tests only. */
+export function setMaxCancelledFlowsForTesting(limit: number | null): void {
+  maxCancelledFlows = limit ?? MAX_CANCELLED_FLOWS;
+}
+
+/** Drop the markers that ran out: all lasting the same time, the oldest
+ *  inserted runs out first. */
+function pruneCancelled(now: number): void {
+  for (const [key, until] of cancelledFlows) {
+    if (until > now) return;
+    cancelledFlows.delete(key);
+  }
+}
+
+function cancelledKey(key: string, state: string): string {
+  return `${key}\u0000${state}`;
+}
+
+function isCancelled(key: string, state: string, now: number): boolean {
+  const until = cancelledFlows.get(cancelledKey(key, state));
+  if (until === undefined) return false;
+  if (until > now) return true;
+  cancelledFlows.delete(cancelledKey(key, state));
+  return false;
+}
+
+/** Remember a cancel, never at the cost of another live marker: exactly
+ *  while the table has room, else as the overflow horizon. */
+function rememberCancelled(key: string, state: string, now: number): void {
+  pruneCancelled(now);
+  const marker = cancelledKey(key, state);
+  if (cancelledFlows.has(marker) || cancelledFlows.size < maxCancelledFlows) {
+    cancelledFlows.delete(marker);
+    cancelledFlows.set(marker, now + PENDING_TTL_MS);
+    return;
+  }
+  overflowUntil = Math.max(overflowUntil, now + PENDING_TTL_MS);
+}
+
+type BeganStep = { signal: AbortSignal; end: () => void };
+
+/** Begin a step for this flow: refused when the cloud already cancelled it,
+ *  or when too many cancels are live to tell. Its signal ends at the step's
+ *  deadline or at the cloud's cancel. */
+function beginStep(
+  flow: CaptureFlowWire,
+  state: string,
+  deadlineMs: number,
+  now: number,
+): BeganStep | "cancelled" | "busy" {
+  const key = flowKey(flow);
+  if (isCancelled(key, state, now)) return "cancelled";
+  // A cancel recorded only as the overflow horizon could be this flow's.
+  if (overflowUntil > now) return "busy";
+  const step: Step = { key, state, flow: { ...flow }, controller: new AbortController() };
+  steps.add(step);
+  return {
+    signal: AbortSignal.any([step.controller.signal, AbortSignal.timeout(deadlineMs)]),
+    end: () => steps.delete(step),
+  };
+}
+
+function refusedStep(outcome: "cancelled" | "busy"): AckBody {
+  return error(outcome === "busy" ? "the sign-in box is busy; try again shortly" : "cancelled");
+}
+
+/** Test seam. */
+export function pendingSignInForTesting(flow: { credentialId: string; revision: string }): boolean {
+  return pendingSignIns.has(flowKey(flow));
+}
+
+/** Tests only. */
+export function pendingSignInCountForTesting(): number {
+  return pendingSignIns.size;
+}
+
+/** Tests only. */
+export function stepsUnderWayForTesting(): number {
+  return steps.size;
+}
+
+/** Tests only: forget every cancelled flow. */
+export function resetCancelledFlowsForTesting(): void {
+  cancelledFlows.clear();
+  overflowUntil = 0;
+}
+
+/** Tests only. */
+export function cancelledFlowCountForTesting(): number {
+  return cancelledFlows.size;
+}
+
+/**
+ * The cloud ended this flow: a step under way for it stops where it is, its
+ * verifier and secret are forgotten now, and a step for it that has not
+ * begun yet never will.
+ */
+export function cancelMcpCapture(frame: McpCaptureCancelFrame, now: number = Date.now()): void {
+  const key = flowKey(frame.flow);
+  for (const step of steps) {
+    if (step.key === key && step.state === frame.state && sameFlow(step.flow, frame.flow)) step.controller.abort();
+  }
+  const pending = pendingSignIns.get(key);
+  if (pending && pending.state === frame.state && sameFlow(pending.flow, frame.flow)) forgetPending(key);
+  rememberCancelled(key, frame.state, now);
+}
+
+export interface McpCaptureDeps {
+  store: CredentialStore;
+  http?: SafeHttpDeps;
+  limits?: SafeHttpLimits;
+  now?: () => number;
+  /** Tests only: a step's whole budget. */
+  deadlineMs?: number;
+}
+
+function error(message: string): AckBody {
+  return { outcome: "error", capture: null, authorizeUrl: null, scopes: null, error: message.slice(0, 500) };
+}
+
+function b64url(buf: Buffer): string {
+  return buf.toString("base64url");
+}
+
+/** POST an MCP `initialize` (streamable HTTP): the status and the auth
+ *  challenge only. The body is never read, so nothing in it travels on. */
+async function initialize(
+  url: string,
+  header: { name: string; value: string } | null,
+  signal: AbortSignal,
+  deps: McpCaptureDeps,
+): Promise<{ status: number; wwwAuthenticate: string | null }> {
+  const response = await safeRequest(
+    {
+      url,
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        accept: "application/json, text/event-stream",
+        ...(header ? { [header.name]: header.value } : {}),
+      },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 0,
+        method: "initialize",
+        params: { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "uai", version: "1.0" } },
+      }),
+      signal,
+    },
+    deps.limits,
+    deps.http,
+  );
+  response.body.destroy();
+  const wwwAuthenticate = response.headers["www-authenticate"];
+  return { status: response.status, wwwAuthenticate: typeof wwwAuthenticate === "string" ? wwwAuthenticate : null };
+}
+
+async function fetchMetadata(
+  url: string,
+  signal: AbortSignal,
+  deps: McpCaptureDeps,
+): Promise<Record<string, unknown> | null> {
+  try {
+    const { status, json } = await safeJson(
+      { url, signal },
+      { maxResponseBytes: DISCOVERY_MAX_BYTES, limits: deps.limits, deps: deps.http },
+    );
+    return status >= 200 && status < 300 && json && typeof json === "object" && !Array.isArray(json)
+      ? (json as Record<string, unknown>)
+      : null;
+  } catch (thrown) {
+    // The step's deadline ends discovery, not just this candidate.
+    if (signal.aborted) throw thrown;
+    return null;
+  }
+}
+
+/**
+ * Identifiers are parsed only to be validated, and compared as the strings
+ * they are: RFC 9728 §6 and RFC 8414 §4 compare code point by code point,
+ * with no normalization (a `/a/../mcp` path, an explicit `:443` or another
+ * case is another identifier).
+ *
+ * A resource identifier (RFC 9728 §1.2) is an https URL with no userinfo and
+ * no fragment; a query may be part of it.
+ */
+function isResourceIdentifier(raw: string): boolean {
+  return !raw.includes("#") && parseSafeUrl(raw) !== null;
+}
+
+/** An issuer identifier (RFC 8414 §2) is an https URL with no userinfo, no
+ *  query and no fragment. */
+function isIssuerIdentifier(raw: string): boolean {
+  return !raw.includes("?") && !raw.includes("#") && parseSafeUrl(raw) !== null;
+}
+
+/** An identifier's authority, path and query as spelled: well-known URLs are
+ *  built from these, never from a re-serialization. */
+function spelling(raw: string): { origin: string; path: string; query: string } {
+  const match = /^(https:\/\/[^/?#]+)([^?#]*)(\?[^#]*)?$/i.exec(raw);
+  if (!match) throw new McpCaptureError("the server's address is not an https URL");
+  return { origin: match[1]!, path: match[2] ?? "", query: match[3] ?? "" };
+}
+
+/**
+ * RFC 9728 §3.1: `/.well-known/oauth-protected-resource` between the host
+ * and the resource's own path and query, as spelled (a lone slash after the
+ * host dropped). Only there: the host's root document describes the host,
+ * and §3.3 lets metadata speak only for the identifier its URL was built
+ * from.
+ */
+function protectedResourceMetadataUrl(resource: string): string {
+  const parts = spelling(resource);
+  const path = parts.path === "/" ? "" : parts.path;
+  return `${parts.origin}/.well-known/oauth-protected-resource${path}${parts.query}`;
+}
+
+/**
+ * RFC 8414 §3.1, in the order the MCP authorization spec asks: the
+ * well-known string between the host and the issuer's path (its terminating
+ * slash dropped), then OpenID Connect's places for it.
+ */
+function authorizationServerCandidates(issuer: string): string[] {
+  const parts = spelling(issuer);
+  const path = parts.path.replace(/\/$/, "");
+  if (!path) {
+    return [
+      `${parts.origin}/.well-known/oauth-authorization-server`,
+      `${parts.origin}/.well-known/openid-configuration`,
+    ];
+  }
+  return [
+    `${parts.origin}/.well-known/oauth-authorization-server${path}`,
+    `${parts.origin}/.well-known/openid-configuration${path}`,
+    `${parts.origin}${path}/.well-known/openid-configuration`,
+  ];
+}
+
+function originOf(raw: string): string | null {
+  return parseSafeUrl(raw)?.origin ?? null;
+}
+
+interface Discovered {
+  issuer: string;
+  issRequired: boolean;
+  authorizationEndpoint: string;
+  tokenEndpoint: string;
+  registrationEndpoint: string | null;
+}
+
+async function discover(
+  mcpUrl: string,
+  wwwAuthenticate: string | null,
+  signal: AbortSignal,
+  deps: McpCaptureDeps,
+): Promise<Discovered> {
+  if (!isResourceIdentifier(mcpUrl)) throw new McpCaptureError("the server's address is not an https URL");
+  const hinted = wwwAuthenticate ? (/resource_metadata="([^"]+)"/i.exec(wwwAuthenticate)?.[1] ?? null) : null;
+  // The issuer identifiers the authorization server's metadata may name.
+  let issuers: string[] | null = null;
+  // The 401's `resource_metadata` (§5.1), then the location §3.1 derives.
+  for (const url of [...(hinted ? [hinted] : []), protectedResourceMetadataUrl(mcpUrl)]) {
+    const metadata = await fetchMetadata(url, signal, deps);
+    // RFC 9728 §3.3: identical, as strings, or another resource's metadata.
+    if (!metadata || metadata.resource !== mcpUrl) continue;
+    const servers = metadata.authorization_servers;
+    if (!Array.isArray(servers) || typeof servers[0] !== "string") continue;
+    if (!isIssuerIdentifier(servers[0])) {
+      throw new McpCaptureError("the server names an authorization server that is not an issuer identifier");
+    }
+    issuers = [servers[0]];
+    break;
+  }
+  // A server from before RFC 9728 is its own authorization server: the
+  // identifier the metadata URL is built from is its origin, and only that,
+  // exactly, may come back as its issuer (RFC 8414 §3.3).
+  issuers ??= [new URL(mcpUrl).origin];
+  for (const url of authorizationServerCandidates(issuers[0]!)) {
+    const metadata = await fetchMetadata(url, signal, deps);
+    // RFC 8414 §3.3: identical, as strings, or another server's metadata.
+    if (!metadata || typeof metadata.issuer !== "string" || !issuers.includes(metadata.issuer)) continue;
+    if (typeof metadata.authorization_endpoint !== "string" || typeof metadata.token_endpoint !== "string") continue;
+    const issRequired = metadata.authorization_response_iss_parameter_supported === true;
+    const own = originOf(metadata.issuer);
+    if (
+      !issRequired &&
+      (originOf(metadata.authorization_endpoint) !== own || originOf(metadata.token_endpoint) !== own)
+    ) {
+      // Without RFC 9207's `iss` a code could be sent to another server's
+      // token endpoint than the one that issued it.
+      throw new McpCaptureError("the authorization server's endpoints are not on its own address");
+    }
+    return {
+      issuer: metadata.issuer,
+      issRequired,
+      authorizationEndpoint: metadata.authorization_endpoint,
+      tokenEndpoint: metadata.token_endpoint,
+      registrationEndpoint: typeof metadata.registration_endpoint === "string" ? metadata.registration_endpoint : null,
+    };
+  }
+  throw new McpCaptureError("the server asks for a sign-in but publishes no usable OAuth metadata");
+}
+
+/** Our own failure, safe to show: never a server's words. */
+class McpCaptureError extends Error {}
+
+async function register(
+  registrationEndpoint: string,
+  redirectUri: string,
+  signal: AbortSignal,
+  deps: McpCaptureDeps,
+): Promise<{ clientId: string; clientSecret: string | null }> {
+  const { status, json } = await safeJson(
+    {
+      url: registrationEndpoint,
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        client_name: "Uai",
+        redirect_uris: [redirectUri],
+        grant_types: ["authorization_code", "refresh_token"],
+        response_types: ["code"],
+        token_endpoint_auth_method: "none",
+      }),
+      signal,
+    },
+    { maxResponseBytes: DISCOVERY_MAX_BYTES, limits: deps.limits, deps: deps.http },
+  );
+  const body = json && typeof json === "object" && !Array.isArray(json) ? (json as Record<string, unknown>) : {};
+  if (status < 200 || status >= 300 || typeof body.client_id !== "string" || body.client_id.length > 512) {
+    throw new McpCaptureError(`dynamic client registration failed (${oauthFailure(body, status)})`);
+  }
+  return {
+    clientId: body.client_id,
+    clientSecret: typeof body.client_secret === "string" ? body.client_secret : null,
+  };
+}
+
+/**
+ * A token-endpoint request: a client secret rides HTTP Basic first, then once
+ * more in the body for vendors that only read that (as today's runners do).
+ */
+export async function postTokenEndpoint(
+  tokenEndpoint: string,
+  params: Record<string, string>,
+  client: { clientId: string; clientSecret: string | null },
+  deps: Pick<McpCaptureDeps, "http" | "limits"> & { signal?: AbortSignal },
+): Promise<{ status: number; json: Record<string, unknown> }> {
+  const signal = deps.signal ?? AbortSignal.timeout(OPERATION_DEADLINE_MS);
+  const attempt = async (mode: "basic" | "post") => {
+    const form = new URLSearchParams(params);
+    const headers: Record<string, string> = { "content-type": "application/x-www-form-urlencoded" };
+    if (client.clientSecret) {
+      if (mode === "basic") {
+        headers.authorization = `Basic ${Buffer.from(`${client.clientId}:${client.clientSecret}`).toString("base64")}`;
+      } else {
+        form.set("client_secret", client.clientSecret);
+      }
+    }
+    const { status, json } = await safeJson(
+      { url: tokenEndpoint, method: "POST", headers, body: form.toString(), signal },
+      { maxResponseBytes: 64 * 1024, limits: deps.limits, deps: deps.http },
+    );
+    const body = json && typeof json === "object" && !Array.isArray(json) ? (json as Record<string, unknown>) : {};
+    return { status, json: body };
+  };
+  const basic = await attempt("basic");
+  const ok = basic.status >= 200 && basic.status < 300 && typeof basic.json.access_token === "string";
+  if (ok || !client.clientSecret) return basic;
+  return attempt("post");
+}
+
+/** The scopes a 401's Bearer challenge asks for (RFC 6750 §3), if any. */
+function challengeScopes(wwwAuthenticate: string | null): string[] | null {
+  const raw = wwwAuthenticate ? (/\bscope="([^"]*)"/i.exec(wwwAuthenticate)?.[1] ?? null) : null;
+  if (raw === null) return null;
+  const scopes = raw.split(" ").filter(Boolean);
+  return scopes.length > 0 && isScopeList(scopes) ? scopes : null;
+}
+
+/** What a token response granted, only as far as it was asked for: a server
+ *  cannot put anything else into an answer this way. */
+function grantedScopes(raw: unknown, requested: string | null): string[] | null {
+  if (requested === null) return null;
+  const asked = new Set(requested.split(" "));
+  if (typeof raw !== "string") return [...asked];
+  return raw.split(" ").filter((scope) => asked.has(scope));
+}
+
+/** A step its signal ended: the cloud's cancel, or the step's deadline. */
+function stopped(signal: AbortSignal): AckBody {
+  const reason: unknown = signal.reason;
+  const timedOut = reason instanceof DOMException && reason.name === "TimeoutError";
+  return error(timedOut ? "the connection took too long to set up" : "cancelled");
+}
+
+function failed(thrown: unknown): AckBody {
+  if (thrown instanceof SafeHttpRefusal) return error(`refused: ${thrown.message}`);
+  if (thrown instanceof McpCaptureError) return error(thrown.message);
+  // Anything else may carry text from elsewhere: say only that it failed.
+  return error("the connection could not be completed");
+}
+
+function mcpFlow(raw: unknown): ParsedCaptureFlow | null {
+  const flow = parseCaptureFlow(raw);
+  return flow && flow.location.class === "mcp" ? flow : null;
+}
+
+/** Probe an MCP server for a connection being added. */
+export async function probeMcpCapture(frame: McpCaptureProbeFrame, deps: McpCaptureDeps): Promise<AckBody> {
+  const flow = mcpFlow(frame.flow);
+  if (!flow) return error("this capture is not an MCP connection's");
+  const now = deps.now ?? Date.now;
+  const step = beginStep(frame.flow, frame.state, deps.deadlineMs ?? OPERATION_DEADLINE_MS, now());
+  if (typeof step === "string") return refusedStep(step);
+  const { signal } = step;
+  try {
+    if (frame.header) {
+      if (flow.brokerParameter !== null) return error("a static header does not rotate; it has no broker part");
+      const answer = await initialize(frame.url, frame.header, signal, deps);
+      if (answer.status === 401) return error("the server rejected the header (401)");
+      if (answer.status === 403) {
+        return error("the server accepted the header but refused the request (403): it likely lacks permission");
+      }
+      if (answer.status < 200 || answer.status >= 300) return error(`unexpected response (${answer.status})`);
+      if (signal.aborted) return stopped(signal);
+      const capture = await writeCapture(
+        deps.store,
+        flow,
+        {
+          lease: serializeLeasedValue({
+            v: 1,
+            part: "lease",
+            location: flow.location,
+            class: "mcp",
+            authKind: "token",
+            header: frame.header,
+          }),
+          broker: null,
+          expiresAt: null,
+        },
+        { signal },
+      );
+      return { outcome: "token", capture, authorizeUrl: null, scopes: null, error: null };
+    }
+
+    const answer = await initialize(frame.url, null, signal, deps);
+    if (answer.status >= 200 && answer.status < 300) {
+      return { outcome: "none", capture: null, authorizeUrl: null, scopes: null, error: null };
+    }
+    if (answer.status !== 401 && answer.status !== 403) {
+      return error(`not an MCP server? initialize answered ${answer.status}`);
+    }
+    if (flow.brokerParameter === null) return error("an OAuth sign-in needs a broker part to keep its refresh token");
+    const found = await discover(frame.url, answer.wwwAuthenticate, signal, deps);
+    let client = { clientId: frame.clientId, clientSecret: frame.clientSecret };
+    if (!client.clientId) {
+      if (!found.registrationEndpoint) {
+        return error("the authorization server cannot register a client: enter a client id and secret");
+      }
+      if (originOf(found.registrationEndpoint) !== originOf(found.issuer) && !found.issRequired) {
+        return error("the authorization server's endpoints are not on its own address");
+      }
+      const registered = await register(found.registrationEndpoint, frame.redirectUri, signal, deps);
+      client = { clientId: registered.clientId, clientSecret: registered.clientSecret };
+    }
+    let authorize: URL;
+    try {
+      authorize = new URL(found.authorizationEndpoint);
+    } catch {
+      return error("the server's sign-in page is not an address");
+    }
+    // Only an https page on a public address is ever handed to the browser:
+    // a `javascript:` one would run in Uai's origin, a private one would aim
+    // the person's browser at their own network.
+    if (authorize.protocol !== "https:" || authorize.username !== "" || authorize.password !== "") {
+      return error("the server's sign-in page is not an https address");
+    }
+    try {
+      await vetPublicUrl(authorize.toString(), deps.limits, deps.http, signal);
+    } catch {
+      if (signal.aborted) return stopped(signal);
+      return error("the server's sign-in page is not on a public address");
+    }
+    // The connection's own needs, never the server's whole capability list.
+    const scopes = frame.scopes ?? challengeScopes(answer.wwwAuthenticate);
+    const verifier = b64url(randomBytes(32));
+    const challenge = b64url(createHash("sha256").update(verifier).digest());
+    authorize.searchParams.set("response_type", "code");
+    authorize.searchParams.set("client_id", client.clientId!);
+    authorize.searchParams.set("redirect_uri", frame.redirectUri);
+    authorize.searchParams.set("state", frame.state);
+    authorize.searchParams.set("code_challenge", challenge);
+    authorize.searchParams.set("code_challenge_method", "S256");
+    authorize.searchParams.set("resource", frame.url);
+    if (scopes?.length) authorize.searchParams.set("scope", scopes.join(" "));
+    // A cancel that came while this step ran leaves nothing waiting.
+    if (signal.aborted) return stopped(signal);
+    rememberPending(flowKey(flow), {
+      flow: { ...frame.flow },
+      state: frame.state,
+      verifier,
+      clientId: client.clientId!,
+      clientSecret: client.clientSecret,
+      issuer: found.issuer,
+      issRequired: found.issRequired,
+      tokenEndpoint: found.tokenEndpoint,
+      redirectUri: frame.redirectUri,
+      resource: frame.url,
+      scopes: scopes?.length ? scopes.join(" ") : null,
+      expiresAt: now() + PENDING_TTL_MS,
+    });
+    return {
+      outcome: "auth_required",
+      capture: null,
+      authorizeUrl: authorize.toString(),
+      scopes: scopes?.length ? scopes : null,
+      error: null,
+    };
+  } catch (thrown) {
+    return signal.aborted ? stopped(signal) : failed(thrown);
+  } finally {
+    step.end();
+  }
+}
+
+/** The authorization server redirected back: exchange the code and write
+ *  the revision, broker-only part first. */
+export async function completeMcpCapture(frame: McpCaptureCompleteFrame, deps: McpCaptureDeps): Promise<AckBody> {
+  const key = flowKey(frame.flow);
+  const pending = pendingSignIns.get(key);
+  // Taken once, whatever happens next.
+  forgetPending(key);
+  const now = deps.now ?? Date.now;
+  if (!pending || pending.expiresAt <= now()) {
+    return error("the sign-in box lost this sign-in (it restarted, or it took too long): connect again");
+  }
+  if (pending.state !== frame.state || !sameFlow(pending.flow, frame.flow)) {
+    return error("this callback is not the sign-in that was started");
+  }
+  // RFC 9207 §2.4: `iss` is compared to the issuer as a simple string; a
+  // redirect naming another issuer is another server's code.
+  if ((frame.iss !== null || pending.issRequired) && frame.iss !== pending.issuer) {
+    return error("this callback came from another authorization server than the sign-in's");
+  }
+  const flow = mcpFlow(pending.flow);
+  if (!flow || flow.brokerParameter === null) return error("this capture is not an MCP sign-in's");
+  const step = beginStep(pending.flow, pending.state, deps.deadlineMs ?? OPERATION_DEADLINE_MS, now());
+  if (typeof step === "string") return refusedStep(step);
+  const { signal } = step;
+  try {
+    const { status, json } = await postTokenEndpoint(
+      pending.tokenEndpoint,
+      {
+        grant_type: "authorization_code",
+        code: frame.code,
+        redirect_uri: pending.redirectUri,
+        client_id: pending.clientId,
+        code_verifier: pending.verifier,
+        resource: pending.resource,
+      },
+      { clientId: pending.clientId, clientSecret: pending.clientSecret },
+      { ...deps, signal },
+    );
+    if (status < 200 || status >= 300 || typeof json.access_token !== "string" || json.access_token.length > 4096) {
+      return error(`the token exchange failed (${oauthFailure(json, status)})`);
+    }
+    const expiresAt = typeof json.expires_in === "number" ? now() + json.expires_in * 1000 : null;
+    const scopes = grantedScopes(json.scope, pending.scopes);
+    const broker: BrokerMcpValue = {
+      v: 1,
+      part: "broker",
+      location: flow.location,
+      class: "mcp",
+      lane: MCP_OAUTH_LANE,
+      tokenEndpoint: pending.tokenEndpoint,
+      clientId: pending.clientId,
+      clientSecret: pending.clientSecret,
+      resource: pending.resource,
+      accessToken: json.access_token,
+      refreshToken: typeof json.refresh_token === "string" ? json.refresh_token : null,
+      scopes: pending.scopes,
+      refresh: { ...emptyRefreshMeta(MCP_OAUTH_LANE), expiresAt, refreshedAt: now() },
+    };
+    if (signal.aborted) return stopped(signal);
+    const capture: CaptureResultWire = await writeCapture(
+      deps.store,
+      flow,
+      {
+        broker: JSON.stringify(broker),
+        lease: serializeLeasedValue({
+          v: 1,
+          part: "lease",
+          location: flow.location,
+          class: "mcp",
+          authKind: "oauth",
+          accessToken: json.access_token,
+          tokenType: "Bearer",
+          expiresAt,
+        }),
+        expiresAt,
+      },
+      { signal },
+    );
+    return { outcome: "connected", capture, authorizeUrl: null, scopes, error: null };
+  } catch (thrown) {
+    return signal.aborted ? stopped(signal) : failed(thrown);
+  } finally {
+    step.end();
+  }
+}
+
+/** A stored MCP broker part, exactly, for the revision at `expected`. */
+export function parseBrokerMcpValue(raw: string, expected: CredentialLocation): BrokerMcpValue | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  const o = parsed as Record<string, unknown>;
+  const location = o.location as Record<string, unknown> | null;
+  const refresh = refreshMetaFrom(o.refresh);
+  if (
+    o.v !== 1 ||
+    o.part !== "broker" ||
+    o.class !== "mcp" ||
+    o.lane !== MCP_OAUTH_LANE ||
+    expected.class !== "mcp" ||
+    !location ||
+    typeof location !== "object" ||
+    location.class !== expected.class ||
+    location.scope !== expected.scope ||
+    location.ownerId !== expected.ownerId ||
+    location.credentialId !== expected.credentialId ||
+    location.revision !== expected.revision ||
+    typeof o.tokenEndpoint !== "string" ||
+    typeof o.clientId !== "string" ||
+    !(o.clientSecret === null || typeof o.clientSecret === "string") ||
+    typeof o.resource !== "string" ||
+    typeof o.accessToken !== "string" ||
+    !(o.refreshToken === null || typeof o.refreshToken === "string") ||
+    !(o.scopes === null || typeof o.scopes === "string") ||
+    !refresh ||
+    refresh.lane !== MCP_OAUTH_LANE
+  ) {
+    return null;
+  }
+  return {
+    v: 1,
+    part: "broker",
+    location: expected,
+    class: "mcp",
+    lane: MCP_OAUTH_LANE,
+    tokenEndpoint: o.tokenEndpoint,
+    clientId: o.clientId,
+    clientSecret: o.clientSecret,
+    resource: o.resource,
+    accessToken: o.accessToken,
+    refreshToken: o.refreshToken,
+    scopes: o.scopes,
+    refresh,
+  };
+}