@moondeck/station 0.0.0-stage → 1.0.0

package/lib/mcp-connections.ts

@@ -0,0 +1,959 @@
+/**
+ * User-authed MCP connections (ADR-057) — the host side of the generic
+ * handshake. Everything secret happens here: OAuth discovery (RFC 9728
+ * protected-resource metadata → RFC 8414 AS metadata), dynamic client
+ * registration (RFC 7591), PKCE, the code exchange, token refresh, and the
+ * sealed secret store. The cloud only ever sees non-secret status/URLs.
+ *
+ * Auth kinds:
+ *   - "oauth" — discovered from a 401 + WWW-Authenticate chain.
+ *   - "token" — a static header the user pasted (write-only over the bridge).
+ *   - "none"  — the URL answered an unauthenticated initialize.
+ */
+
+import { createHash, randomBytes } from "node:crypto";
+import { eq } from "drizzle-orm";
+
+import { configuredCredentialStore, queueStoreWrite, userParameterName } from "./credential-store";
+import { LeftOwnCredentialsError, whileOnOwnCredentials } from "./cloud-credential-host";
+import { getDb, schema } from "./db";
+import { sealAesGcm, openAesGcm } from "./secrets";
+import { signInBoxMode } from "./signin-box";
+import type { McpOp } from "../src/protocol";
+
+const FETCH_TIMEOUT_MS = 10_000;
+// Refresh an access token this long before its recorded expiry.
+const REFRESH_LEAD_MS = 60_000;
+
+export interface McpAck {
+  status: "connected" | "auth_required" | "disconnected";
+  authorizeUrl?: string;
+  scopes?: string[];
+}
+
+interface OauthSecret {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt?: number; // epoch ms; absent = treat as non-expiring
+}
+
+interface HeaderSecret {
+  headerName: string;
+  headerValue: string;
+}
+
+// --- sealed single-column packing (same format as host-env.ts) --------------
+
+function pack(value: string): string {
+  const sealed = sealAesGcm(value);
+  return `${sealed.ct.toString("base64")}.${sealed.nonce.toString("base64")}`;
+}
+
+function unpack(enc: string): string {
+  const dot = enc.indexOf(".");
+  const ct = Buffer.from(enc.slice(0, dot), "base64");
+  const nonce = Buffer.from(enc.slice(dot + 1), "base64");
+  return openAesGcm(ct, nonce);
+}
+
+// --- fetch helpers -----------------------------------------------------------
+
+async function timedFetch(url: string, init?: RequestInit): Promise<Response> {
+  return fetch(url, {
+    ...init,
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    redirect: "follow",
+  });
+}
+
+async function fetchJson(url: string): Promise<Record<string, unknown> | null> {
+  try {
+    const res = await timedFetch(url, { headers: { accept: "application/json" } });
+    if (!res.ok) return null;
+    return (await res.json()) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+/** POST an MCP `initialize` (streamable HTTP). Returns the raw Response. */
+async function mcpInitialize(
+  url: string,
+  header?: HeaderSecret | null,
+): Promise<Response> {
+  return timedFetch(url, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      accept: "application/json, text/event-stream",
+      ...(header ? { [header.headerName]: header.headerValue } : {}),
+    },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: 0,
+      method: "initialize",
+      params: {
+        protocolVersion: "2025-06-18",
+        capabilities: {},
+        clientInfo: { name: "uai-host", version: "1.0" },
+      },
+    }),
+  });
+}
+
+/** Collapse whitespace and cap length — this text lands in the connect dialog. */
+function oneLine(s: string, max = 300): string {
+  const flat = s.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+
+/**
+ * The vendor's own explanation for a failed response, so the connect dialog
+ * can show it instead of a bare status code. Vendors bury it in one of a few
+ * shapes — RFC 6750's `error_description`, a bare `error`/`message`, or a
+ * GraphQL-style `errors[]` — so try each, then fall back to the raw body.
+ * Never throws: a missing or unparseable body just means no reason to add.
+ */
+async function failureReason(res: Response): Promise<string | null> {
+  const text = await res.text().catch(() => "");
+  if (!text.trim()) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return oneLine(text);
+  }
+  const body = (parsed ?? {}) as Record<string, unknown>;
+  const errors = body.errors;
+  const first = Array.isArray(errors)
+    ? (errors[0] as Record<string, unknown> | undefined)
+    : undefined;
+  // `error` is a string in some payloads and an object wrapping `message` in
+  // others — New Relic alone returns both shapes plus `errors[]`, depending
+  // on which of its tiers answers. Prefer the descriptive fields; the bare
+  // `error` string ("unauthorized") is the last resort.
+  const nested =
+    typeof body.error === "object" && body.error !== null
+      ? (body.error as Record<string, unknown>)
+      : undefined;
+  const reason = [
+    body.error_description,
+    body.message,
+    first?.message,
+    nested?.message,
+    body.error,
+  ].find((c): c is string => typeof c === "string" && c.trim().length > 0);
+  return oneLine(reason ?? text);
+}
+
+// --- OAuth discovery (RFC 9728 → RFC 8414) -----------------------------------
+
+/** Candidate well-known URLs, path-aware per spec, root fallback last. */
+function wellKnownCandidates(base: string, suffix: string): string[] {
+  const u = new URL(base);
+  const path = u.pathname.replace(/\/$/, "");
+  const out: string[] = [];
+  if (path && path !== "") {
+    out.push(`${u.origin}/.well-known/${suffix}${path}`);
+  }
+  out.push(`${u.origin}/.well-known/${suffix}`);
+  return out;
+}
+
+/** Parse `resource_metadata="…"` out of a WWW-Authenticate header. */
+function resourceMetadataUrl(wwwAuth: string | null): string | null {
+  if (!wwwAuth) return null;
+  const m = /resource_metadata="([^"]+)"/i.exec(wwwAuth);
+  return m?.[1] ?? null;
+}
+
+interface Discovered {
+  authorizationEndpoint: string;
+  tokenEndpoint: string;
+  registrationEndpoint?: string;
+  scopesSupported?: string[];
+}
+
+/**
+ * From the MCP URL + the 401's WWW-Authenticate, find the authorization
+ * server's metadata. Tolerates servers that skip RFC 9728 (falls back to
+ * treating the MCP origin as its own authorization server).
+ */
+async function discoverAuth(
+  mcpUrl: string,
+  wwwAuth: string | null,
+): Promise<Discovered> {
+  // 1. Protected-resource metadata → authorization_servers[0].
+  const prmCandidates = [
+    ...(resourceMetadataUrl(wwwAuth) ? [resourceMetadataUrl(wwwAuth)!] : []),
+    ...wellKnownCandidates(mcpUrl, "oauth-protected-resource"),
+  ];
+  let asBase: string | null = null;
+  let resourceScopes: string[] | undefined;
+  for (const url of prmCandidates) {
+    const prm = await fetchJson(url);
+    const servers = prm?.authorization_servers;
+    if (Array.isArray(servers) && typeof servers[0] === "string") {
+      asBase = servers[0];
+      if (Array.isArray(prm?.scopes_supported)) {
+        resourceScopes = prm.scopes_supported as string[];
+      }
+      break;
+    }
+  }
+  // Servers that skip RFC 9728 often ARE their own AS.
+  asBase ??= new URL(mcpUrl).origin;
+
+  // 2. AS metadata (RFC 8414, then OIDC discovery).
+  const asCandidates = [
+    ...wellKnownCandidates(asBase, "oauth-authorization-server"),
+    ...wellKnownCandidates(asBase, "openid-configuration"),
+  ];
+  for (const url of asCandidates) {
+    const meta = await fetchJson(url);
+    if (
+      typeof meta?.authorization_endpoint === "string" &&
+      typeof meta?.token_endpoint === "string"
+    ) {
+      return {
+        authorizationEndpoint: meta.authorization_endpoint,
+        tokenEndpoint: meta.token_endpoint,
+        registrationEndpoint:
+          typeof meta.registration_endpoint === "string"
+            ? meta.registration_endpoint
+            : undefined,
+        scopesSupported:
+          resourceScopes ??
+          (Array.isArray(meta.scopes_supported)
+            ? (meta.scopes_supported as string[])
+            : undefined),
+      };
+    }
+  }
+  throw new Error(
+    "the server requires auth but exposes no OAuth metadata (" +
+      "no /.well-known/oauth-protected-resource or …/oauth-authorization-server)",
+  );
+}
+
+/** RFC 7591 dynamic client registration. Returns client id (+secret). */
+async function registerClient(
+  registrationEndpoint: string,
+  redirectUri: string,
+): Promise<{ clientId: string; clientSecret?: string }> {
+  const res = await timedFetch(registrationEndpoint, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      client_name: "Moondeck",
+      redirect_uris: [redirectUri],
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      token_endpoint_auth_method: "none",
+    }),
+  });
+  if (!res.ok) {
+    throw new Error(`dynamic client registration failed (${res.status})`);
+  }
+  const json = (await res.json()) as Record<string, unknown>;
+  if (typeof json.client_id !== "string") {
+    throw new Error("registration response carried no client_id");
+  }
+  return {
+    clientId: json.client_id,
+    clientSecret:
+      typeof json.client_secret === "string" ? json.client_secret : undefined,
+  };
+}
+
+function b64url(buf: Buffer): string {
+  return buf.toString("base64url");
+}
+
+// --- op handlers --------------------------------------------------------------
+
+export async function handleMcpOp(op: McpOp): Promise<McpAck> {
+  switch (op.kind) {
+    case "probe":
+      return probe(op);
+    case "oauth.complete":
+      return oauthComplete(op.connectionId, op.code);
+    case "disconnect": {
+      deleteMcpConnectionLocal(op.connectionId);
+      return { status: "disconnected" };
+    }
+  }
+}
+
+async function probe(op: Extract<McpOp, { kind: "probe" }>): Promise<McpAck> {
+  const db = getDb();
+  const now = Date.now();
+
+  // Static-header connection: verify the header works, seal, done.
+  if (op.headerName && op.headerValue) {
+    const header = { headerName: op.headerName, headerValue: op.headerValue };
+    const res = await mcpInitialize(op.url, header);
+    if (res.status === 401 || res.status === 403) {
+      // 401 and 403 send you to different fixes, so don't collapse them into
+      // one "rejected" message. 401 is a credential the server did not
+      // recognise — re-check the key. 403 is one it DID recognise and then
+      // refused: the key is fine, but its user lacks permission or the
+      // account is not entitled to this server. Telling someone to re-paste
+      // a working key is the expensive failure here.
+      const lead =
+        res.status === 401
+          ? "the server rejected the token (401)"
+          : "the token was accepted but this server refused the request " +
+            "(403) — the key is likely valid but lacks permission for it";
+      const why = await failureReason(res);
+      throw new Error(why ? `${lead}: ${why}` : lead);
+    }
+    if (!res.ok) {
+      const why = await failureReason(res);
+      const lead = `unexpected response (${res.status})`;
+      throw new Error(why ? `${lead}: ${why}` : lead);
+    }
+    if (signInBoxMode()) {
+      // ADR-136 sign-in box: the store first, a row with no secret.
+      await putMcpConnectionStoreFirst({
+        v: 1,
+        kind: "mcp",
+        id: op.connectionId,
+        userId: op.userId,
+        url: op.url,
+        authKind: "token",
+        tokenEndpoint: null,
+        redirectUri: null,
+        clientId: null,
+        clientSecret: null,
+        pkceVerifier: null,
+        secret: JSON.stringify(header),
+        status: "connected",
+        scopes: null,
+        updatedAt: now,
+      });
+      return { status: "connected" };
+    }
+    db.insert(schema.mcpConnections)
+      .values({
+        id: op.connectionId,
+        userId: op.userId,
+        url: op.url,
+        authKind: "token",
+        secretEnc: pack(JSON.stringify(header)),
+        status: "connected",
+        updatedAt: now,
+      })
+      .onConflictDoUpdate({
+        target: schema.mcpConnections.id,
+        set: {
+          url: op.url,
+          authKind: "token",
+          secretEnc: pack(JSON.stringify(header)),
+          status: "connected",
+          updatedAt: now,
+        },
+      })
+      .run();
+    mirrorMcpConnectionToStore(op.connectionId);
+    return { status: "connected" };
+  }
+
+  // Bare probe.
+  const res = await mcpInitialize(op.url);
+  if (res.ok) {
+    if (signInBoxMode()) {
+      await putMcpConnectionStoreFirst({
+        v: 1,
+        kind: "mcp",
+        id: op.connectionId,
+        userId: op.userId,
+        url: op.url,
+        authKind: "none",
+        tokenEndpoint: null,
+        redirectUri: null,
+        clientId: null,
+        clientSecret: null,
+        pkceVerifier: null,
+        secret: null,
+        status: "connected",
+        scopes: null,
+        updatedAt: now,
+      });
+      return { status: "connected" };
+    }
+    db.insert(schema.mcpConnections)
+      .values({
+        id: op.connectionId,
+        userId: op.userId,
+        url: op.url,
+        authKind: "none",
+        status: "connected",
+        updatedAt: now,
+      })
+      .onConflictDoUpdate({
+        target: schema.mcpConnections.id,
+        set: { url: op.url, authKind: "none", status: "connected", updatedAt: now },
+      })
+      .run();
+    mirrorMcpConnectionToStore(op.connectionId);
+    return { status: "connected" };
+  }
+  if (res.status !== 401 && res.status !== 403) {
+    throw new Error(
+      `not an MCP server? initialize returned ${res.status} ${res.statusText}`,
+    );
+  }
+  if (!op.state || !op.redirectUri) {
+    throw new Error("server requires OAuth but no state/redirectUri provided");
+  }
+
+  // OAuth: discovery → client → PKCE → authorize URL.
+  const found = await discoverAuth(op.url, res.headers.get("www-authenticate"));
+  let clientId = op.clientId;
+  let clientSecret = op.clientSecret;
+  if (!clientId) {
+    if (!found.registrationEndpoint) {
+      throw new Error(
+        "the authorization server does not support dynamic client " +
+          "registration — enter a client id/secret manually",
+      );
+    }
+    const reg = await registerClient(found.registrationEndpoint, op.redirectUri);
+    clientId = reg.clientId;
+    clientSecret = reg.clientSecret;
+  }
+
+  const verifier = b64url(randomBytes(32));
+  const challenge = b64url(createHash("sha256").update(verifier).digest());
+  const authorize = new URL(found.authorizationEndpoint);
+  authorize.searchParams.set("response_type", "code");
+  authorize.searchParams.set("client_id", clientId);
+  authorize.searchParams.set("redirect_uri", op.redirectUri);
+  authorize.searchParams.set("state", op.state);
+  authorize.searchParams.set("code_challenge", challenge);
+  authorize.searchParams.set("code_challenge_method", "S256");
+  // RFC 8707 resource indicator — REQUIRED by the MCP auth spec.
+  authorize.searchParams.set("resource", op.url);
+  if (found.scopesSupported?.length) {
+    authorize.searchParams.set("scope", found.scopesSupported.join(" "));
+  }
+
+  if (signInBoxMode()) {
+    // ADR-136 sign-in box: the pending half-flow (verifier, client secret)
+    // lives in memory only until oauth.complete; nothing pending reaches the
+    // store or the row. A box restart mid-flow means "probe again".
+    boxPendingOauth.set(op.connectionId, { verifier, clientSecret: clientSecret ?? null });
+    upsertStoreHeldMcpConnectionRow(
+      {
+        id: op.connectionId,
+        userId: op.userId,
+        url: op.url,
+        authKind: "oauth",
+        tokenEndpoint: found.tokenEndpoint,
+        redirectUri: op.redirectUri,
+        clientId,
+        status: "pending",
+        scopes: found.scopesSupported?.join(" ") ?? null,
+        updatedAt: now,
+      },
+      null,
+    );
+    return { status: "auth_required", authorizeUrl: authorize.toString() };
+  }
+  const fields = {
+    userId: op.userId,
+    url: op.url,
+    authKind: "oauth",
+    tokenEndpoint: found.tokenEndpoint,
+    redirectUri: op.redirectUri,
+    clientId,
+    clientSecretEnc: clientSecret ? pack(clientSecret) : null,
+    pkceVerifierEnc: pack(verifier),
+    secretEnc: null,
+    status: "pending",
+    scopes: found.scopesSupported?.join(" ") ?? null,
+    updatedAt: now,
+  };
+  db.insert(schema.mcpConnections)
+    .values({ id: op.connectionId, ...fields })
+    .onConflictDoUpdate({ target: schema.mcpConnections.id, set: fields })
+    .run();
+  mirrorMcpConnectionToStore(op.connectionId);
+  return { status: "auth_required", authorizeUrl: authorize.toString() };
+}
+
+async function oauthComplete(connectionId: string, code: string): Promise<McpAck> {
+  const db = getDb();
+  const row = db
+    .select()
+    .from(schema.mcpConnections)
+    .where(eq(schema.mcpConnections.id, connectionId))
+    .get();
+  if (!row) throw new Error("unknown connection — probe first");
+  const pending = signInBoxMode() ? (boxPendingOauth.get(connectionId) ?? null) : null;
+  if (
+    !row.tokenEndpoint ||
+    !row.clientId ||
+    !row.redirectUri ||
+    (!pending && !row.pkceVerifierEnc)
+  ) {
+    throw new Error(
+      signInBoxMode() && !pending
+        ? "the sign-in box restarted during this OAuth flow — probe again"
+        : "connection has no pending OAuth flow",
+    );
+  }
+  const verifier = pending ? pending.verifier : unpack(row.pkceVerifierEnc!);
+  const clientSecret = pending
+    ? (pending.clientSecret ?? undefined)
+    : row.clientSecretEnc
+      ? unpack(row.clientSecretEnc)
+      : undefined;
+
+  const { ok, status, json } = await postTokenEndpoint(
+    row.tokenEndpoint,
+    {
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: row.redirectUri,
+      client_id: row.clientId,
+      code_verifier: verifier,
+      // RFC 8707, mirrored from the authorize request.
+      resource: row.url,
+    },
+    row.clientId,
+    clientSecret,
+  );
+  if (!ok || typeof json.access_token !== "string") {
+    const detail =
+      typeof json.error === "string" ? json.error : `status ${status}`;
+    throw new Error(`token exchange failed (${detail})`);
+  }
+
+  const secret: OauthSecret = {
+    accessToken: json.access_token,
+    refreshToken:
+      typeof json.refresh_token === "string" ? json.refresh_token : undefined,
+    expiresAt:
+      typeof json.expires_in === "number"
+        ? Date.now() + json.expires_in * 1000
+        : undefined,
+  };
+  const scopes =
+    typeof json.scope === "string" && json.scope.length > 0
+      ? json.scope
+      : row.scopes;
+  if (pending) {
+    await putMcpConnectionStoreFirst({
+      v: 1,
+      kind: "mcp",
+      id: connectionId,
+      userId: row.userId,
+      url: row.url,
+      authKind: "oauth",
+      tokenEndpoint: row.tokenEndpoint,
+      redirectUri: row.redirectUri,
+      clientId: row.clientId,
+      clientSecret: pending.clientSecret,
+      pkceVerifier: null,
+      secret: JSON.stringify(secret),
+      status: "connected",
+      scopes,
+      updatedAt: Date.now(),
+    });
+    boxPendingOauth.delete(connectionId);
+    return {
+      status: "connected",
+      scopes: scopes ? scopes.split(" ").filter(Boolean) : undefined,
+    };
+  }
+  db.update(schema.mcpConnections)
+    .set({
+      secretEnc: pack(JSON.stringify(secret)),
+      pkceVerifierEnc: null,
+      status: "connected",
+      scopes,
+      updatedAt: Date.now(),
+    })
+    .where(eq(schema.mcpConnections.id, connectionId))
+    .run();
+  mirrorMcpConnectionToStore(connectionId);
+  return {
+    status: "connected",
+    scopes: scopes ? scopes.split(" ").filter(Boolean) : undefined,
+  };
+}
+
+// --- gateway support ----------------------------------------------------------
+
+/** A connected row for `id`, or null. */
+export function getConnection(id: string): schema.McpConnection | null {
+  return (
+    getDb()
+      .select()
+      .from(schema.mcpConnections)
+      .where(eq(schema.mcpConnections.id, id))
+      .get() ?? null
+  );
+}
+
+/** All CONNECTED connections owned by `userId` (task-up + gateway ACL). */
+export function listConnectionsForUser(userId: string): schema.McpConnection[] {
+  return getDb()
+    .select()
+    .from(schema.mcpConnections)
+    .where(eq(schema.mcpConnections.userId, userId))
+    .all()
+    .filter((r) => r.status === "connected");
+}
+
+/**
+ * The Authorization (or custom) header for a connection, refreshing an
+ * expired OAuth access token first (rotating the stored refresh token when
+ * the server issues a new one). Null when the connection needs no header.
+ */
+export async function authHeaderFor(
+  row: schema.McpConnection,
+  forceRefresh = false,
+): Promise<{ name: string; value: string } | null> {
+  if (row.authKind === "none") return null;
+  if (!row.secretEnc) throw new Error("connection has no stored secret");
+  if (row.authKind === "token") {
+    const h = JSON.parse(unpack(row.secretEnc)) as HeaderSecret;
+    return { name: h.headerName, value: h.headerValue };
+  }
+  let secret = JSON.parse(unpack(row.secretEnc)) as OauthSecret;
+  if (
+    forceRefresh ||
+    (secret.expiresAt && secret.expiresAt - REFRESH_LEAD_MS < Date.now())
+  ) {
+    // ADR-154 §7: a refresh only while the runner is on its own
+    // credentials, counted whole (the rotated secret written, its store
+    // mirror queued): leaving them waits for it, and none begins after.
+    const current = secret;
+    const refreshing = whileOnOwnCredentials(() => refreshTokens(row, current));
+    if (refreshing === null) throw new LeftOwnCredentialsError();
+    secret = await refreshing;
+  }
+  return { name: "authorization", value: `Bearer ${secret.accessToken}` };
+}
+
+/**
+ * POST a token-endpoint request. A client secret rides HTTP Basic first
+ * (RFC 6749's MUST-support method, what DCR vendors expect); on failure it
+ * retries once with `client_secret` in the body (client_secret_post) —
+ * some manual-creds vendors (Slack's user-token endpoint) only read body
+ * credentials and answer Basic with bad_client_secret.
+ */
+async function postTokenEndpoint(
+  tokenEndpoint: string,
+  params: Record<string, string>,
+  clientId: string,
+  clientSecret: string | undefined,
+): Promise<{ ok: boolean; status: number; json: Record<string, unknown> }> {
+  const attempt = async (mode: "basic" | "post") => {
+    const body = new URLSearchParams(params);
+    const headers: Record<string, string> = {
+      "content-type": "application/x-www-form-urlencoded",
+      accept: "application/json",
+    };
+    if (clientSecret) {
+      if (mode === "basic") {
+        headers.authorization =
+          "Basic " +
+          Buffer.from(`${clientId}:${clientSecret}`).toString("base64");
+      } else {
+        body.set("client_secret", clientSecret);
+      }
+    }
+    const res = await timedFetch(tokenEndpoint, {
+      method: "POST",
+      headers,
+      body,
+    });
+    const json = (await res.json().catch(() => ({}))) as Record<
+      string,
+      unknown
+    >;
+    return {
+      ok: res.ok && typeof json.access_token === "string",
+      status: res.status,
+      json,
+    };
+  };
+  const basic = await attempt("basic");
+  if (basic.ok || !clientSecret) return basic;
+  return attempt("post");
+}
+
+async function refreshTokens(
+  row: schema.McpConnection,
+  secret: OauthSecret,
+): Promise<OauthSecret> {
+  if (!secret.refreshToken || !row.tokenEndpoint || !row.clientId) {
+    throw new Error("access token expired and no refresh token is stored");
+  }
+  const { ok, status, json } = await postTokenEndpoint(
+    row.tokenEndpoint,
+    {
+      grant_type: "refresh_token",
+      refresh_token: secret.refreshToken,
+      client_id: row.clientId,
+      resource: row.url,
+    },
+    row.clientId,
+    row.clientSecretEnc ? unpack(row.clientSecretEnc) : undefined,
+  );
+  if (!ok || typeof json.access_token !== "string") {
+    throw new Error(`token refresh failed (status ${status})`);
+  }
+  const next: OauthSecret = {
+    accessToken: json.access_token,
+    refreshToken:
+      typeof json.refresh_token === "string"
+        ? json.refresh_token
+        : secret.refreshToken,
+    expiresAt:
+      typeof json.expires_in === "number"
+        ? Date.now() + json.expires_in * 1000
+        : undefined,
+  };
+  getDb()
+    .update(schema.mcpConnections)
+    .set({ secretEnc: pack(JSON.stringify(next)), updatedAt: Date.now() })
+    .where(eq(schema.mcpConnections.id, row.id))
+    .run();
+  mirrorMcpConnectionToStore(row.id);
+  return next;
+}
+
+// ---------------------------------------------------------------------------
+// Credential store mirror (ADR-134 slice 2):
+// `<prefix>/users/<userId>/mcp/<connectionId>`. The connection id is the
+// cloud's, which is org-bound there; on the host the owner is the user.
+// Owned hosts: no-ops.
+// ---------------------------------------------------------------------------
+
+export interface StoredMcpConnection {
+  v: 1;
+  kind: "mcp";
+  id: string;
+  userId: string;
+  url: string;
+  authKind: string;
+  tokenEndpoint: string | null;
+  redirectUri: string | null;
+  clientId: string | null;
+  clientSecret: string | null;
+  pkceVerifier: string | null;
+  /** The sealed JSON, decrypted: header or OAuth tokens. */
+  secret: string | null;
+  status: string;
+  scopes: string | null;
+  updatedAt: number;
+}
+
+export function mcpConnectionParameterName(userId: string, id: string): string {
+  return userParameterName(userId, "mcp", id);
+}
+
+/** The row as it is mirrored (secrets decrypted). Never logged. */
+export function mcpConnectionStoreValue(id: string): StoredMcpConnection | null {
+  const row = getDb()
+    .select()
+    .from(schema.mcpConnections)
+    .where(eq(schema.mcpConnections.id, id))
+    .get();
+  if (!row) return null;
+  return {
+    v: 1,
+    kind: "mcp",
+    id: row.id,
+    userId: row.userId,
+    url: row.url,
+    authKind: row.authKind,
+    tokenEndpoint: row.tokenEndpoint,
+    redirectUri: row.redirectUri,
+    clientId: row.clientId,
+    clientSecret: row.clientSecretEnc ? unpack(row.clientSecretEnc) : null,
+    pkceVerifier: row.pkceVerifierEnc ? unpack(row.pkceVerifierEnc) : null,
+    secret: row.secretEnc ? unpack(row.secretEnc) : null,
+    status: row.status,
+    scopes: row.scopes,
+    updatedAt: row.updatedAt,
+  };
+}
+
+export function setMcpConnectionStoreRef(id: string, storeRef: string): void {
+  getDb()
+    .update(schema.mcpConnections)
+    .set({ storeRef })
+    .where(eq(schema.mcpConnections.id, id))
+    .run();
+}
+
+export function listMcpConnectionStoreRows(): Array<{
+  id: string;
+  userId: string;
+  storeRef: string | null;
+}> {
+  return getDb()
+    .select({
+      id: schema.mcpConnections.id,
+      userId: schema.mcpConnections.userId,
+      storeRef: schema.mcpConnections.storeRef,
+    })
+    .from(schema.mcpConnections)
+    .all();
+}
+
+export function mirrorMcpConnectionToStore(id: string): void {
+  // ADR-136 sign-in box: rows hold no secret; the store was written first,
+  // and a mirror of a secret-less row would overwrite the only copy.
+  if (signInBoxMode()) return;
+  queueStoreWrite(`mirror mcp connection ${id}`, async (store) => {
+    const value = mcpConnectionStoreValue(id);
+    if (!value) return;
+    const name = mcpConnectionParameterName(value.userId, id);
+    await store.put(name, JSON.stringify(value));
+    setMcpConnectionStoreRef(id, name);
+  });
+}
+
+/** Delete the row and its parameter (the disconnect op and reconcile). */
+export function deleteMcpConnectionLocal(id: string): void {
+  const row = getDb()
+    .select({ userId: schema.mcpConnections.userId, storeRef: schema.mcpConnections.storeRef })
+    .from(schema.mcpConnections)
+    .where(eq(schema.mcpConnections.id, id))
+    .get();
+  getDb().delete(schema.mcpConnections).where(eq(schema.mcpConnections.id, id)).run();
+  if (!row) return;
+  const name = row.storeRef ?? mcpConnectionParameterName(row.userId, id);
+  queueStoreWrite(`delete mcp connection ${id}`, (store) => store.delete(name));
+}
+
+// ---------------------------------------------------------------------------
+// ADR-136 sign-in box: connection rows here hold NO secret — the header or
+// OAuth tokens, the client secret and the PKCE verifier live in the store (or,
+// for a half-finished OAuth flow, in memory only). What the box lists (url,
+// auth kind, status, scopes) also rides as tags so a replacement box needs no
+// value read.
+// ---------------------------------------------------------------------------
+
+export const MCP_CONNECTION_TAGS = {
+  urlB64: "uai_url_b64",
+  authKind: "uai_auth_kind",
+  status: "uai_status",
+  scopesB64: "uai_scopes_b64",
+  updatedAt: "uai_updated_at",
+} as const;
+
+const boxPendingOauth = new Map<string, { verifier: string; clientSecret: string | null }>();
+
+/** Test seam. */
+export function pendingOauthForTesting(connectionId: string): boolean {
+  return boxPendingOauth.has(connectionId);
+}
+
+export type StoreHeldMcpConnectionRow = Pick<
+  StoredMcpConnection,
+  "id" | "userId" | "url" | "authKind" | "tokenEndpoint" | "redirectUri" | "clientId" | "status" | "scopes" | "updatedAt"
+>;
+
+export function mcpConnectionMetadataTags(value: {
+  url: string;
+  authKind: string;
+  status: string;
+  scopes: string | null;
+  updatedAt: number;
+}): Record<string, string> {
+  return {
+    [MCP_CONNECTION_TAGS.urlB64]: Buffer.from(value.url, "utf8").toString("base64url").slice(0, 256),
+    [MCP_CONNECTION_TAGS.authKind]: value.authKind,
+    [MCP_CONNECTION_TAGS.status]: value.status,
+    [MCP_CONNECTION_TAGS.scopesB64]: value.scopes
+      ? Buffer.from(value.scopes, "utf8").toString("base64url").slice(0, 256)
+      : "",
+    [MCP_CONNECTION_TAGS.updatedAt]: String(value.updatedAt),
+  };
+}
+
+/** Upsert a row with every secret column null. */
+export function upsertStoreHeldMcpConnectionRow(
+  value: StoreHeldMcpConnectionRow,
+  storeRef: string | null,
+): void {
+  const fields = {
+    userId: value.userId,
+    url: value.url,
+    authKind: value.authKind,
+    tokenEndpoint: value.tokenEndpoint,
+    redirectUri: value.redirectUri,
+    clientId: value.clientId,
+    clientSecretEnc: null,
+    pkceVerifierEnc: null,
+    secretEnc: null,
+    status: value.status,
+    scopes: value.scopes,
+    updatedAt: value.updatedAt,
+    storeRef,
+  };
+  getDb()
+    .insert(schema.mcpConnections)
+    .values({ id: value.id, ...fields })
+    .onConflictDoUpdate({ target: schema.mcpConnections.id, set: fields })
+    .run();
+}
+
+/** The store first, awaited (a refused put is the op's failure), then tags
+ *  and a secret-less row. */
+export async function putMcpConnectionStoreFirst(value: StoredMcpConnection): Promise<void> {
+  const store = configuredCredentialStore();
+  if (!store) throw new Error("the sign-in box has no credential store to hold the connection");
+  const name = mcpConnectionParameterName(value.userId, value.id);
+  await store.put(name, JSON.stringify(value));
+  try {
+    await store.tag(name, mcpConnectionMetadataTags(value));
+  } catch (err) {
+    console.warn(
+      `[mcp] connection ${value.id}: tagging ${name} failed (${err instanceof Error ? err.message : String(err)}) — a replacement box needs the transitional read to list it`,
+    );
+  }
+  upsertStoreHeldMcpConnectionRow(value, name);
+}
+
+/** Delete the row only (no store call). */
+export function deleteMcpConnectionRowLocal(id: string): void {
+  boxPendingOauth.delete(id);
+  getDb().delete(schema.mcpConnections).where(eq(schema.mcpConnections.id, id)).run();
+}
+
+/** Reconcile import: a connection this host lacks. Existing rows win. */
+export function importMcpConnectionFromStore(
+  value: StoredMcpConnection,
+  storeRef: string,
+): boolean {
+  const result = getDb()
+    .insert(schema.mcpConnections)
+    .values({
+      id: value.id,
+      userId: value.userId,
+      url: value.url,
+      authKind: value.authKind,
+      tokenEndpoint: value.tokenEndpoint,
+      redirectUri: value.redirectUri,
+      clientId: value.clientId,
+      clientSecretEnc: value.clientSecret === null ? null : pack(value.clientSecret),
+      pkceVerifierEnc: value.pkceVerifier === null ? null : pack(value.pkceVerifier),
+      secretEnc: value.secret === null ? null : pack(value.secret),
+      status: value.status,
+      scopes: value.scopes,
+      updatedAt: value.updatedAt,
+      storeRef,
+    })
+    .onConflictDoNothing({ target: schema.mcpConnections.id })
+    .run();
+  return result.changes > 0;
+}