mixdog 1.2.1 → 1.2.2

package/src/runtime/agent/orchestrator/mcp/client.mjs

@@ -24,13 +24,22 @@ import { currentToolExecutionOwner } from '../../../shared/tool-execution-owner.
 import { positiveInt } from '../../../shared/numbers.mjs';
 import {
   providerSafeMcpToolName,
+  resolveMcpOAuthUrl,
   resolveMcpRequestTimeouts,
   resolveMcpTransportKind,
   scrubMcpConnectionMessage,
+  scrubMcpSecrets,
 } from './client-config.mjs';
 import { createLazyOutputValidator } from './lazy-output-validator.mjs';
-import { appendMcpStderrTail, createMcpTransport } from './client-transport.mjs';
-import { listAllMcpTools, runBoundedHandshake } from './client-handshake.mjs';
+import { appendMcpStderrTail, createMcpTransport, hasConfiguredMcpAuth } from './client-transport.mjs';
+import { listAllMcpTools, MCP_CONNECT_CANCELLED, runBoundedHandshake } from './client-handshake.mjs';
+import {
+  clearMcpOAuth,
+  hasStoredMcpOAuthTokens,
+  isMcpOAuthReauthenticationRequired,
+  MCP_OAUTH_CALLBACK_NOT_PENDING,
+} from './oauth.mjs';
+export { probeMcpServerAuth } from './oauth-probe.mjs';
 
 // Config interpretation (transport kind, URL policy, env expansion, headers,
 // timeouts, log scrubbing) lives in client-config.mjs; re-exported so every
@@ -103,6 +112,20 @@ function mcpLog(line) {
   if (process.env.MIXDOG_QUIET_MCP_LOG) return;
   process.stderr.write(line);
 }
+// OAuth tokens belong to the live connection, not to its config: a server may
+// echo the request (Authorization included) into an error body or result.
+function oauthSecrets(...transports) {
+  return transports.flatMap((transport) => transport?.oauth?.secrets() || []);
+}
+function scrubMcpOAuthError(error, cfg, secrets) {
+  if (secrets.length === 0) return error;
+  if (!(error instanceof Error)) return new Error(scrubMcpConnectionMessage(String(error), cfg, secrets));
+  error.message = scrubMcpConnectionMessage(error.message, cfg, secrets);
+  if (typeof error.stack === 'string') error.stack = scrubMcpConnectionMessage(error.stack, cfg, secrets);
+  // A JSON-RPC error carries the server's own payload (McpError.data).
+  if (error.data !== undefined) error.data = scrubMcpSecrets(error.data, secrets);
+  return error;
+}
 
 async function loadMcpSdk() {
   mcpSdkPromise ??= Promise.all([
@@ -148,14 +171,16 @@ export async function connectMcpServers(config, options = {}) {
   });
   // Connect all servers in PARALLEL: a slow/hung server (bounded by its
   // per-server startup timeout) must never delay the others' handshakes.
-  const settled = await Promise.allSettled(entries.map(([name, cfg]) => connectServer(name, cfg, scopeId, genAtStart)));
+  const settled = await Promise.allSettled(
+    entries.map(([name, cfg]) => connectServer(name, cfg, scopeId, genAtStart, options))
+  );
   settled.forEach((res, i) => {
     if (res.status !== 'rejected') return;
     const [name, cfg] = entries[i];
     const rawMessage = res.reason instanceof Error ? res.reason.message : String(res.reason);
     const msg = scrubMcpConnectionMessage(rawMessage, cfg);
     mcpLog(`[mcp-client] Failed to connect "${name}": ${msg}\n`);
-    failures.push({ name, msg });
+    failures.push({ name, msg, ...(res.reason?.authRequired ? { authRequired: true } : {}) });
   });
   if (failures.length > 0) {
     const detail = failures.map((f) => `${f.name}: ${f.msg}`).join('; ');
@@ -330,7 +355,7 @@ export function getMcpServerInstructionsMap(scopeId = DEFAULT_MCP_SCOPE_ID) {
 // shutdown generation captured BEFORE the caller queued/closed anything: a
 // disconnectAll() landing during the close (or the connect) bumps it, and the
 // replacement must then never register (no resurrection after shutdown).
-async function replaceServerConnection(scopeId, name, current, cfg, genAtStart) {
+async function replaceServerConnection(scopeId, name, current, cfg, genAtStart, options = {}) {
   const registryKey = mcpServerRegistryKey(scopeId, name);
   if (current) {
     await _closeServer(current);
@@ -343,10 +368,12 @@ async function replaceServerConnection(scopeId, name, current, cfg, genAtStart)
   try {
     // connectServer re-checks the same generation after loading the SDK and
     // again right before registering, so a shutdown mid-handshake also aborts.
-    await connectServer(name, cfg, scopeId, genAtStart);
+    await connectServer(name, cfg, scopeId, genAtStart, options);
   } catch (reason) {
     const rawMessage = reason instanceof Error ? reason.message : String(reason);
-    throw new Error(scrubMcpConnectionMessage(rawMessage, cfg));
+    const error = new Error(scrubMcpConnectionMessage(rawMessage, cfg));
+    if (reason?.authRequired) error.authRequired = true;
+    throw error;
   }
 }
 
@@ -356,6 +383,7 @@ async function replaceServerConnection(scopeId, name, current, cfg, genAtStart)
 // connect per server is ever running (no doubly registered transports).
 async function runExclusiveServerOp(registryKey, task) {
   for (let pending = reconnects.wait(registryKey); pending; pending = reconnects.wait(registryKey)) {
+    // Only waiting for the reconnect to settle; its failure belongs to its caller.
     await pending.catch(() => {});
   }
   return reconnects.run(registryKey, task);
@@ -396,7 +424,7 @@ async function reconnectMcpServer(scopeId, serverName, failedServer) {
  * rejects (credential-scrubbed message) when the connect fails, leaving the
  * server unregistered.
  */
-export async function reconnectSingleMcpServer(scopeId, name, cfg = undefined) {
+export async function reconnectSingleMcpServer(scopeId, name, cfg = undefined, options = {}) {
   const normalized = normalizeMcpScopeId(scopeId);
   _knownMcpScopes.add(normalized);
   const registryKey = mcpServerRegistryKey(normalized, name);
@@ -415,7 +443,7 @@ export async function reconnectSingleMcpServer(scopeId, name, cfg = undefined) {
       closeCallAdmission(normalized, name, `MCP ${name} disabled`);
       return false;
     }
-    await replaceServerConnection(normalized, name, current, nextCfg, genAtStart);
+    await replaceServerConnection(normalized, name, current, nextCfg, genAtStart, options);
     return true;
   });
 }
@@ -438,96 +466,101 @@ export async function executeMcpTool(name, args, options = {}) {
     definition?.mcpOperation
       ? _callMcpFeatureWithTimeout(target, definition.mcpOperation, args, callSignal)
       : _callToolWithTimeout(target, toolName, args, callSignal);
+  let retryServer = null;
+  const secrets = () => oauthSecrets(server.transport, retryServer?.transport);
   const gate = callAdmissionFor(server);
-  return gate.run(
-    options?.ownerKey || currentToolExecutionOwner(),
-    async () => {
-      // The gate stops forwarding the caller's abort once this task is
-      // admitted, so the task itself observes the signal for its whole run.
-      if (callSignal?.aborted) {
-        throw mcpAbortError(
-          callSignal,
-          `MCP tool call aborted before dispatch (server="${serverName}", tool="${toolName}")`
-        );
-      }
-      let result;
-      try {
-        result = await dispatch(server);
-      } catch (firstErr) {
-        const firstMsg = firstErr instanceof Error ? firstErr.message : String(firstErr);
-        if (isMcpCallAbortError(firstErr) || callSignal?.aborted) {
-          // A cancelled call is not a transport failure: reconnecting and
-          // replaying it would duplicate the side effect the caller just
-          // walked away from.
-          mcpLog(`[mcp-client] Tool call aborted by caller for "${serverName}/${toolName}".\n`);
-          throw firstErr;
-        }
-        if (isMcpToolCallTimeoutError(firstErr)) {
-          mcpLog(`[mcp-client] Tool call timed out; skipping reconnect retry for "${serverName}/${toolName}".\n`);
-          throw firstErr;
-        }
-        const serverDead = server.liveness?.alive === false;
-        if (!serverDead && isMcpServerResponseError(firstErr)) {
-          // The server answered (JSON-RPC error): it is alive — nothing to
-          // reconnect, and the call already ran its course.
-          throw firstErr;
-        }
-        // Only a failure that proves the request never left this process
-        // may be replayed; anything else may already have run server-side.
-        const undelivered = isMcpUndeliveredError(firstErr);
-        const deadTail = serverDead ? server.stderrTail?.() : '';
-        mcpLog(`[mcp-client] Tool call failed, attempting shared reconnect...\n`);
-        let retryServer;
-        try {
-          // The reconnect is SHARED (singleflight): the race only stops
-          // THIS caller from waiting on it — the reconnect keeps running
-          // for its other waiters. Without this, an abort mid-reconnect
-          // could not settle the call and the admission slot stayed held
-          // until the reconnect finished, or forever if it hung.
-          retryServer = await raceMcpAbort(
-            reconnectMcpServer(scopeId, serverName, server),
-            callSignal,
-            `MCP tool call aborted during reconnect (server="${serverName}", tool="${toolName}")`
-          );
-        } catch (reconnectErr) {
-          if (isMcpCallAbortError(reconnectErr) || callSignal?.aborted) throw reconnectErr;
-          const reconnectMsg = reconnectErr instanceof Error ? reconnectErr.message : String(reconnectErr);
-          throw new Error(
-            appendMcpStderrTail(`Tool call failed: ${firstMsg}; reconnect also failed: ${reconnectMsg}`, deadTail)
-          );
-        }
-        if (!undelivered) {
-          throw new Error(
-            appendMcpStderrTail(
-              `Tool call failed: ${firstMsg}; MCP server "${serverName}" was reconnected for the next call, but this call was not replayed because the request may already have reached the server`,
-              deadTail
-            )
-          );
-        }
-        // A reconnect that outlived the caller's abort must not dispatch the
-        // retry: that would run the side effect after cancellation.
+  return gate
+    .run(
+      options?.ownerKey || currentToolExecutionOwner(),
+      async () => {
+        // The gate stops forwarding the caller's abort once this task is
+        // admitted, so the task itself observes the signal for its whole run.
         if (callSignal?.aborted) {
           throw mcpAbortError(
             callSignal,
-            `MCP tool call aborted after reconnect (server="${serverName}", tool="${toolName}")`
+            `MCP tool call aborted before dispatch (server="${serverName}", tool="${toolName}")`
           );
         }
+        let result;
         try {
-          result = await dispatch(retryServer);
-        } catch (retryErr) {
-          if (isMcpCallAbortError(retryErr) || callSignal?.aborted) throw retryErr;
-          const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
-          throw new Error(`Tool call failed: ${firstMsg}; retry after reconnect also failed: ${retryMsg}`);
+          result = await dispatch(server);
+        } catch (firstErr) {
+          const firstMsg = firstErr instanceof Error ? firstErr.message : String(firstErr);
+          if (isMcpCallAbortError(firstErr) || callSignal?.aborted) {
+            // A cancelled call is not a transport failure: reconnecting and
+            // replaying it would duplicate the side effect the caller just
+            // walked away from.
+            mcpLog(`[mcp-client] Tool call aborted by caller for "${serverName}/${toolName}".\n`);
+            throw firstErr;
+          }
+          if (isMcpToolCallTimeoutError(firstErr)) {
+            mcpLog(`[mcp-client] Tool call timed out; skipping reconnect retry for "${serverName}/${toolName}".\n`);
+            throw firstErr;
+          }
+          const serverDead = server.liveness?.alive === false;
+          if (!serverDead && isMcpServerResponseError(firstErr)) {
+            // The server answered (JSON-RPC error): it is alive — nothing to
+            // reconnect, and the call already ran its course.
+            throw firstErr;
+          }
+          // Only a failure that proves the request never left this process
+          // may be replayed; anything else may already have run server-side.
+          const undelivered = isMcpUndeliveredError(firstErr);
+          const deadTail = serverDead ? server.stderrTail?.() : '';
+          mcpLog(`[mcp-client] Tool call failed, attempting shared reconnect...\n`);
+          try {
+            // The reconnect is SHARED (singleflight): the race only stops
+            // THIS caller from waiting on it — the reconnect keeps running
+            // for its other waiters. Without this, an abort mid-reconnect
+            // could not settle the call and the admission slot stayed held
+            // until the reconnect finished, or forever if it hung.
+            retryServer = await raceMcpAbort(
+              reconnectMcpServer(scopeId, serverName, server),
+              callSignal,
+              `MCP tool call aborted during reconnect (server="${serverName}", tool="${toolName}")`
+            );
+          } catch (reconnectErr) {
+            if (isMcpCallAbortError(reconnectErr) || callSignal?.aborted) throw reconnectErr;
+            const reconnectMsg = reconnectErr instanceof Error ? reconnectErr.message : String(reconnectErr);
+            throw new Error(
+              appendMcpStderrTail(`Tool call failed: ${firstMsg}; reconnect also failed: ${reconnectMsg}`, deadTail)
+            );
+          }
+          if (!undelivered) {
+            throw new Error(
+              appendMcpStderrTail(
+                `Tool call failed: ${firstMsg}; MCP server "${serverName}" was reconnected for the next call, but this call was not replayed because the request may already have reached the server`,
+                deadTail
+              )
+            );
+          }
+          // A reconnect that outlived the caller's abort must not dispatch the
+          // retry: that would run the side effect after cancellation.
+          if (callSignal?.aborted) {
+            throw mcpAbortError(
+              callSignal,
+              `MCP tool call aborted after reconnect (server="${serverName}", tool="${toolName}")`
+            );
+          }
+          try {
+            result = await dispatch(retryServer);
+          } catch (retryErr) {
+            if (isMcpCallAbortError(retryErr) || callSignal?.aborted) throw retryErr;
+            const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
+            throw new Error(`Tool call failed: ${firstMsg}; retry after reconnect also failed: ${retryMsg}`);
+          }
         }
+        const normalized = normalizeToolEnvelope(await normalizeMcpToolResult(scrubMcpSecrets(result, secrets())));
+        const text = capMcpResult(normalized.result);
+        return normalized.explicitSuccess ? makeToolEnvelope(text, [], { explicitSuccess: true }) : text;
+      },
+      {
+        signal: callSignal,
       }
-      const normalized = normalizeToolEnvelope(await normalizeMcpToolResult(result));
-      const text = capMcpResult(normalized.result);
-      return normalized.explicitSuccess ? makeToolEnvelope(text, [], { explicitSuccess: true }) : text;
-    },
-    {
-      signal: callSignal,
-    }
-  );
+    )
+    .catch((error) => {
+      throw scrubMcpOAuthError(error, server.cfg, secrets());
+    });
 }
 
 const MCP_FEATURE_REQUESTS = {
@@ -903,6 +936,7 @@ export function raceMcpAbort(promise, signal, message) {
   if (!signal) return promise;
   allowConcurrentAbortListeners(signal);
   if (signal.aborted) {
+    // The abort wins; the abandoned promise's late rejection must not go unhandled.
     void Promise.resolve(promise).catch(() => {});
     return Promise.reject(mcpAbortError(signal, message));
   }
@@ -1090,6 +1124,7 @@ export async function disconnectAll(options = undefined) {
       /* ignore */
     }
     try {
+      entry.transport.oauth?.close();
       void entry.client.close().catch(() => {
         /* ignore */
       });
@@ -1118,6 +1153,9 @@ export async function disconnectAll(options = undefined) {
 export async function disconnectMcpServer(name, options = {}) {
   const scopeId = normalizeMcpScopeId(options);
   const registryKey = mcpServerRegistryKey(scopeId, name);
+  // An exclusive reconnect may currently be waiting for human authorization.
+  // Cancel before queueing the disconnect behind that operation.
+  cancelMcpLogin(name, options);
   return runExclusiveServerOp(registryKey, async () => {
     const server = servers.get(registryKey);
     if (!server) return false;
@@ -1132,6 +1170,73 @@ export async function disconnectMcpServer(name, options = {}) {
     return true;
   });
 }
+/**
+ * Cancel the interactive OAuth login of a connect of `name` still in its
+ * handshake; that connect then fails. Callers that queue behind the connect
+ * (disable, remove) call this first so they never wait out the login.
+ */
+export function cancelMcpLogin(name, options = {}) {
+  const scopeId = normalizeMcpScopeId(options);
+  for (const entry of _pendingConnects) {
+    if (entry.scopeId === scopeId && entry.name === name) entry.transport.oauth?.close();
+  }
+}
+/**
+ * Answer the interactive OAuth login of a connect of `name` still in its
+ * handshake with the redirect URL pasted from the browser (remote / headless
+ * sign-in); that connect then proceeds as after the loopback callback. Throws
+ * a fixed message, never the pasted URL, for an invalid paste (the login stays
+ * pending) or when no login is waiting.
+ */
+export function completeMcpLogin(name, callbackUrl, options = {}) {
+  const scopeId = normalizeMcpScopeId(options);
+  for (const entry of _pendingConnects) {
+    if (entry.scopeId === scopeId && entry.name === name && entry.transport.oauth?.loginStarted) {
+      entry.transport.oauth.completeCallback(callbackUrl);
+      return;
+    }
+  }
+  throw new Error(MCP_OAUTH_CALLBACK_NOT_PENDING);
+}
+/** Whether a connect of `name` still in its handshake is waiting for an
+ *  interactive (browser) OAuth login. */
+export function isMcpLoginPending(name, options = {}) {
+  const scopeId = normalizeMcpScopeId(options);
+  for (const entry of _pendingConnects) {
+    if (entry.scopeId === scopeId && entry.name === name && entry.transport.oauth?.loginStarted) return true;
+  }
+  return false;
+}
+/**
+ * Stored OAuth sign-in state of an HTTP/SSE server without configured
+ * authentication: `{ signedIn }` (tokens stored for its exact URL), or null
+ * for servers that never use MCP OAuth.
+ */
+export function getMcpServerOAuthState(cfg) {
+  let url;
+  try {
+    url = resolveMcpOAuthUrl(cfg);
+  } catch {
+    return null;
+  }
+  if (!url || hasConfiguredMcpAuth(cfg)) return null;
+  return { signedIn: hasStoredMcpOAuthTokens(url) };
+}
+/**
+ * Log out of an HTTP/SSE server URL: delete the OAuth tokens and client
+ * registration stored for it, shared by every server configured with that
+ * exact URL, and drop them from live connections.
+ */
+export async function clearMcpServerOAuth(cfg) {
+  let url;
+  try {
+    url = resolveMcpOAuthUrl(cfg);
+  } catch {
+    // A config without a valid remote URL never connected, so never logged in.
+    return;
+  }
+  if (url) await clearMcpOAuth({ url });
+}
 /**
  * Close a single server: for stdio transports first shut down the full child
  * process tree (close stdin -> grace -> tree kill) so wrapper chains such as
@@ -1143,6 +1248,7 @@ async function _closeServer(server) {
   // A deliberate close is not a crash: suppress the unexpected-close report.
   if (server?.liveness) server.liveness.closing = true;
   const transport = server?.transport;
+  transport?.oauth?.close();
   // Live stdio transports expose the spawned ChildProcess on _process.
   if (transport?._process) {
     try {
@@ -1165,7 +1271,8 @@ async function connectServer(
   name,
   cfg,
   scopeId = DEFAULT_MCP_SCOPE_ID,
-  genAtStart = currentConnectAbortGeneration(scopeId)
+  genAtStart = currentConnectAbortGeneration(scopeId),
+  options = {}
 ) {
   scopeId = normalizeMcpScopeId(scopeId);
   _knownMcpScopes.add(scopeId);
@@ -1182,8 +1289,14 @@ async function connectServer(
     sdk,
     log: mcpLog,
     strictEnv: cfg?._mixdogStrictEnv === true,
+    // Only an explicit sign-in (beginMcpOAuthLogin) is interactive; it may
+    // supply its own browser launcher to capture the authorization URL.
+    oauthOptions: {
+      interactive: options.interactive === true,
+      ...(typeof options.openBrowser === 'function' ? { openBrowser: options.openBrowser } : {}),
+    },
   });
-  const liveness = trackMcpLiveness(client, name, cfg, stderrTail);
+  const liveness = trackMcpLiveness(client, name, cfg, stderrTail, transport);
   const pending = { scopeId, name, client, transport };
   _pendingConnects.add(pending);
   try {
@@ -1237,6 +1350,22 @@ async function connectServer(
     }
     _invalidateMcpToolFieldMemo();
     mcpLog(`[mcp] connected: ${tools.length} tools — ${tools.map((t) => t.name).join(', ')}\n`);
+  } catch (error) {
+    await _closeServer({ client, transport, liveness });
+    const scrubbed = scrubMcpOAuthError(error, cfg, oauthSecrets(transport));
+    // A server that only needs an OAuth sign-in is not a broken server: the
+    // sign-in was required, or an explicit one did not complete (cancelled,
+    // denied, timed out or a failed exchange after it started, or cancelled
+    // before it could). A failure after the sign-in obtained tokens is real.
+    const signInIncomplete =
+      transport.oauth &&
+      (isMcpOAuthReauthenticationRequired(error) ||
+        (transport.oauth.loginStarted && !transport.oauth.loginCompleted) ||
+        (transport.oauth.interactive && error?.code === MCP_CONNECT_CANCELLED));
+    if (signInIncomplete && scrubbed && typeof scrubbed === 'object') {
+      scrubbed.authRequired = true;
+    }
+    throw scrubbed;
   } finally {
     _pendingConnects.delete(pending);
   }
@@ -1249,7 +1378,7 @@ async function connectServer(
  * records the last error (parse/send hiccups do not mean the server died).
  * Handlers already installed on the client are chained, not replaced.
  */
-function trackMcpLiveness(client, name, cfg, stderrTail) {
+function trackMcpLiveness(client, name, cfg, stderrTail, transport) {
   const liveness = { alive: true, closing: false, closedAt: 0, lastError: '' };
   const priorClose = client.onclose;
   const priorError = client.onerror;
@@ -1263,7 +1392,11 @@ function trackMcpLiveness(client, name, cfg, stderrTail) {
     if (typeof priorClose === 'function') priorClose.apply(client, args);
   };
   client.onerror = (error, ...rest) => {
-    liveness.lastError = scrubMcpConnectionMessage(error instanceof Error ? error.message : String(error), cfg);
+    liveness.lastError = scrubMcpConnectionMessage(
+      error instanceof Error ? error.message : String(error),
+      cfg,
+      oauthSecrets(transport)
+    );
     if (typeof priorError === 'function') priorError.call(client, error, ...rest);
   };
   return liveness;
@@ -1316,6 +1449,7 @@ export function setMcpScopeRoot(scopeId, root) {
     if (server.cfg?._mixdogRootsFollowScope !== true) continue;
     Promise.resolve()
       .then(() => server.client?.sendRootsListChanged?.())
+      // A server that rejects the roots notification keeps its previous roots.
       .catch(() => {});
   }
 }
@@ -1383,7 +1517,7 @@ async function runToolRefresh(registryKey, live, name, cfg, capabilities) {
     _invalidateMcpToolFieldMemo();
   } catch (error) {
     mcpLog(
-      `[mcp-client] Failed to refresh tools for "${name}": ${scrubMcpConnectionMessage(error?.message || error, cfg)}\n`
+      `[mcp-client] Failed to refresh tools for "${name}": ${scrubMcpConnectionMessage(error?.message || error, cfg, oauthSecrets(live.transport))}\n`
     );
   }
 }
@@ -1419,7 +1553,7 @@ export function _registerMcpServerForTest(scopeId, name, rawTools = [], options
     capabilities,
     liveness: { alive: true, closing: false, closedAt: 0, lastError: '' },
     stderrTail: typeof options.stderrTail === 'function' ? options.stderrTail : () => '',
-    transport: null,
+    transport: options.transport || null,
     client: {
       callTool:
         typeof options.callTool === 'function'

package/src/runtime/agent/orchestrator/mcp/oauth-callback.mjs

@@ -0,0 +1,103 @@
+import { timingSafeEqual } from 'node:crypto';
+import { OAUTH_PAGE_CONTENT_TYPE, oauthErrorHtml, oauthSuccessHtml } from '../providers/lib/oauth-page.mjs';
+
+/** Upper bound of a pasted redirect URL (`completeMcpLogin`). */
+export const MCP_OAUTH_CALLBACK_MAX_BYTES = 64 * 1024;
+// Fixed messages: a pasted URL carries the authorization code and is never
+// echoed into an error, a log or a status.
+const INVALID_CALLBACK_PASTE =
+  'The pasted sign-in URL is invalid. Paste the full address the browser was redirected to after signing in.';
+export const MCP_OAUTH_CALLBACK_NOT_PENDING = 'MCP OAuth sign-in is not waiting for a callback';
+const sameState = (supplied, expected) => {
+  const a = Buffer.from(supplied || '');
+  const b = Buffer.from(expected || '');
+  return b.length > 0 && a.length === b.length && timingSafeEqual(a, b);
+};
+
+/**
+ * The outcome of a redirect URL pasted from the browser for a pending login
+ * whose redirect URI is `redirectUrl` and state `state`: `{ code }`, or
+ * `{ denied: true }` for an authorization error. Throws a fixed message (never
+ * the pasted text) for anything that is not exactly that login's callback.
+ */
+export function parsePastedMcpOAuthCallback(pasted, { redirectUrl, state }) {
+  const invalid = () => new Error(INVALID_CALLBACK_PASTE);
+  if (typeof pasted !== 'string' || Buffer.byteLength(pasted) > MCP_OAUTH_CALLBACK_MAX_BYTES) throw invalid();
+  const raw = pasted.trim();
+  let target;
+  let expected;
+  try {
+    target = new URL(raw);
+    expected = new URL(redirectUrl);
+  } catch {
+    throw invalid();
+  }
+  if (
+    raw.includes('#') ||
+    target.username ||
+    target.password ||
+    target.origin !== expected.origin ||
+    target.pathname !== expected.pathname
+  )
+    throw invalid();
+  const seen = new Set();
+  for (const [key, value] of target.searchParams) {
+    if (seen.has(key)) throw invalid();
+    seen.add(key);
+    // The redirect URI's own parameters come back unchanged; any others an
+    // authorization server adds (e.g. Google's scope/authuser/prompt) are
+    // ignored, as in Codex's parse_callback_url.
+    if (expected.searchParams.has(key) && expected.searchParams.get(key) !== value) throw invalid();
+  }
+  for (const key of expected.searchParams.keys()) if (!seen.has(key)) throw invalid();
+  if (!sameState(target.searchParams.get('state'), state)) throw invalid();
+  if (seen.has('code') === seen.has('error')) throw invalid();
+  if (seen.has('error')) return { denied: true };
+  const code = target.searchParams.get('code');
+  if (!code) throw invalid();
+  return { code };
+}
+
+// Answers a request to the loopback redirect URI: only a GET of the exact
+// callback path and host, carrying exactly the pending state (compared in
+// constant time) and either one code or an error, finishes the login.
+export function answerOAuthCallback(req, res, { redirectUrl, state, finish, serverName }) {
+  const page = (status, html) => {
+    res.writeHead(status, {
+      'Content-Type': OAUTH_PAGE_CONTENT_TYPE,
+      'Cache-Control': 'no-store',
+      'Referrer-Policy': 'no-referrer',
+    });
+    res.end(html);
+  };
+  const invalid = () =>
+    page(400, oauthErrorHtml('This sign-in link is invalid or has expired.', 'Start the sign-in again from Mixdog.'));
+  let target;
+  try {
+    target = new URL(req.url || '/', redirectUrl);
+  } catch {
+    invalid();
+    return;
+  }
+  // `finish` is absent once the login was answered (e.g. by a pasted URL).
+  const valid =
+    typeof finish === 'function' &&
+    req.method === 'GET' &&
+    req.headers.host === new URL(redirectUrl).host &&
+    target.pathname === '/oauth/callback' &&
+    target.searchParams.getAll('state').length === 1 &&
+    sameState(target.searchParams.get('state'), state);
+  if (!valid || (!target.searchParams.has('error') && target.searchParams.getAll('code').length !== 1)) {
+    invalid();
+    return;
+  }
+  const server = serverName || 'the MCP server';
+  if (target.searchParams.has('error')) {
+    // The authorization server's error text is never reflected.
+    page(400, oauthErrorHtml(`Sign-in to ${server} was not completed.`, 'Start the sign-in again from Mixdog.'));
+    finish(undefined);
+    return;
+  }
+  page(200, oauthSuccessHtml(server));
+  finish(target.searchParams.get('code'));
+}