@pi-archimedes/mcp 2.3.0

package/src/auth-storage.ts

@@ -0,0 +1,330 @@
+/**
+ * OAuth credential storage backed by the OS keyring.
+ *
+ * Tokens are persisted via @napi-rs/keyring (macOS Keychain, Windows
+ * Credential Manager, or the Linux Secret Service). Storage is fail-closed:
+ * when the credential store is unavailable (no libsecret, headless session,
+ * revoked keyring) every operation throws a clear error — there is never a
+ * plaintext fallback.
+ *
+ * Windows Credential Manager caps each value at 1280 characters, so payloads
+ * over {@link AUTH_SECRET_CHUNK_SIZE} are split into 1000-char chunks:
+ *   - chunk i → account `<account>.chunk.<digest>.<i>`
+ *   - main account → manifest `{ __chunks: 1, chunkCount, chunkDigest }`
+ * where `digest` is the first 16 hex chars of sha256(payload). Overwrites and
+ * deletes remove stale chunks from the previous group (known from the
+ * previous manifest, or defensibly from the previous plain payload's own
+ * digest when no manifest is present).
+ */
+
+import { createHash } from "node:crypto";
+
+import { Entry } from "@napi-rs/keyring";
+
+import type { AuthEntry } from "./oauth-types.js";
+
+/**
+ * Service name for all auth entries. Deliberately different from the
+ * reference adapter's `pi-mcp-adapter.oauth` so both adapters can coexist
+ * on the same machine.
+ */
+const AUTH_SECRET_SERVICE = "pi-archimedes-mcp.oauth";
+
+/** Windows Credential Manager value cap is 1280 chars; keep headroom. */
+const AUTH_SECRET_CHUNK_SIZE = 1000;
+
+/** Marker on the manifest JSON stored at the main account for chunked payloads. */
+const AUTH_CHUNK_MANIFEST_KEY = "__chunks";
+
+const UNAVAILABLE_MESSAGE =
+  "OS credential store unavailable — cannot store OAuth tokens securely";
+
+interface ChunkManifest {
+  __chunks: 1;
+  chunkCount: number;
+  chunkDigest: string;
+}
+
+/** A group of chunk accounts that a main-account payload may reference. */
+interface ChunkGroup {
+  digest: string;
+  count: number;
+}
+
+// In-memory cache keyed by server name. Caches both presence and absence so
+// the SDK's per-request token reads don't hammer the credential daemon.
+// save/delete update it explicitly; out-of-process changes are not observed
+// until the process restarts.
+const authEntryCache = new Map<string, AuthEntry | undefined>();
+
+function cloneAuthEntry(entry: AuthEntry | undefined): AuthEntry | undefined {
+  return entry === undefined ? undefined : structuredClone(entry);
+}
+
+/** Deterministic per-server account: `sha256-<hex sha256 of serverName>`. */
+function getAuthEntryAccount(serverName: string): string {
+  return `sha256-${createHash("sha256").update(serverName, "utf8").digest("hex")}`;
+}
+
+function getChunkAccount(account: string, chunkDigest: string, index: number): string {
+  return `${account}.chunk.${chunkDigest}.${index}`;
+}
+
+/** First 16 hex chars of sha256(payload) — identifies a chunk group. */
+function digestPayload(payload: string): string {
+  return createHash("sha256").update(payload, "utf8").digest("hex").slice(0, 16);
+}
+
+function chunkCountForPayload(payload: string): number {
+  return Math.ceil(payload.length / AUTH_SECRET_CHUNK_SIZE);
+}
+
+/**
+ * A main-account payload's chunk group. A manifest references its own
+ * chunkDigest/count; a plain payload references no chunks of its own, but
+ * grouping it under (its own digest, ceil(len/CHUNK_SIZE)) lets overwrites
+ * and deletes defensively sweep orphans when no manifest is present.
+ */
+function chunkGroupForPayload(payload: string): ChunkGroup {
+  const manifest = parseManifest(payload);
+  if (manifest) {
+    return { digest: manifest.chunkDigest, count: manifest.chunkCount };
+  }
+  return { digest: digestPayload(payload), count: chunkCountForPayload(payload) };
+}
+
+function removeChunkGroup(account: string, group: ChunkGroup): void {
+  for (let i = 0; i < group.count; i++) {
+    removeSecret(getChunkAccount(account, group.digest, i));
+  }
+}
+
+/**
+ * Classify an error thrown by Entry.getPassword() as "entry absent".
+ *
+ * @napi-rs/keyring v1.3.0 never throws from the read path — its Rust
+ * `get_password()` is `inner.get_password().ok()`, so a missing entry is
+ * the `null` return handled in {@link readSecret}. This is therefore a
+ * DEFENSIVE fallback for backends (or future versions) that throw on miss.
+ *
+ * The patterns are the specific "item absent" phrasings of this stack —
+ * keyring-core's canonical `NoEntry` message ("No matching credential
+ * found"), plus narrow legacy equivalents. Deliberately EXCLUDED because
+ * they appear in genuine store failures that must stay fail-closed:
+ * bare "no such" ("No such file or directory (os error 2)"), bare
+ * "not found" (D-Bus "Match rule not found"), and generic "missing".
+ *
+ * Accepted false-positive tradeoff: if a genuine store failure on the READ
+ * path coincidentally contains one of these phrasings, it is misclassified
+ * as "no entry" — getAuthEntry returns undefined and the user re-auths
+ * (fail-open on read only). The write and delete paths never run this
+ * classification and remain fail-closed (removeSecret is deliberately
+ * best-effort by design).
+ */
+function isMissingEntryError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return /no matching credential found|does not exist|no such entry|no entry/i.test(message);
+}
+
+function unavailableError(cause?: unknown): Error {
+  return new Error(UNAVAILABLE_MESSAGE, cause ? { cause } : undefined);
+}
+
+/**
+ * Read a secret. Returns undefined when the entry does not exist. Throws
+ * {@link UNAVAILABLE_MESSAGE} when the keyring itself is inaccessible.
+ */
+function readSecret(account: string): string | undefined {
+  let entry: Entry;
+  try {
+    entry = new Entry(AUTH_SECRET_SERVICE, account);
+  } catch (error) {
+    throw unavailableError(error);
+  }
+  try {
+    // @napi-rs/keyring v1.3.0 returns null for a missing entry and never
+    // throws from the read path — the catch below is a defensive fallback
+    // for backends that do throw on miss (see isMissingEntryError).
+    const password = entry.getPassword();
+    return password === null || password === undefined ? undefined : password;
+  } catch (error) {
+    if (isMissingEntryError(error)) return undefined;
+    throw unavailableError(error);
+  }
+}
+
+function writeSecret(account: string, password: string): void {
+  let entry: Entry;
+  try {
+    entry = new Entry(AUTH_SECRET_SERVICE, account);
+  } catch (error) {
+    throw unavailableError(error);
+  }
+  try {
+    entry.setPassword(password);
+  } catch (error) {
+    throw unavailableError(error);
+  }
+}
+
+/** Best-effort delete for stale chunks: a missing entry must not fail the caller. */
+function removeSecret(account: string): void {
+  try {
+    new Entry(AUTH_SECRET_SERVICE, account).deletePassword();
+  } catch {
+    // Missing entry (or transiently unavailable store) — best-effort cleanup.
+  }
+}
+
+/** Parse a main-account payload as a chunk manifest, if it is one. */
+function parseManifest(payload: string): ChunkManifest | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(payload);
+  } catch {
+    return undefined;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return undefined;
+  }
+  const candidate = parsed as Partial<ChunkManifest> & Record<string, unknown>;
+  if (candidate[AUTH_CHUNK_MANIFEST_KEY] !== 1) return undefined;
+  if (
+    typeof candidate.chunkCount !== "number" ||
+    !Number.isInteger(candidate.chunkCount) ||
+    candidate.chunkCount <= 0
+  ) {
+    return undefined;
+  }
+  if (typeof candidate.chunkDigest !== "string" || candidate.chunkDigest.length === 0) {
+    return undefined;
+  }
+  return candidate as ChunkManifest;
+}
+
+function parseAuthEntry(payload: string): AuthEntry {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(payload);
+  } catch {
+    throw new Error(`Corrupt OAuth entry in the OS credential store: payload is not valid JSON`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`Corrupt OAuth entry in the OS credential store: payload is not a JSON object`);
+  }
+  return parsed as AuthEntry;
+}
+
+/** Read every chunk of a manifest group and reassemble the payload in order. */
+function readChunkedEntry(account: string, manifest: ChunkManifest): AuthEntry {
+  let payload = "";
+  for (let i = 0; i < manifest.chunkCount; i++) {
+    const chunk = readSecret(getChunkAccount(account, manifest.chunkDigest, i));
+    if (chunk === undefined) {
+      throw new Error(
+        `Corrupt OAuth entry in the OS credential store: missing chunk ${i} of ${manifest.chunkCount}`,
+      );
+    }
+    payload += chunk;
+  }
+  return parseAuthEntry(payload);
+}
+
+/**
+ * Read the stored auth entry for a server. Returns undefined when the server
+ * has no stored entry. Throws when the credential store is unavailable
+ * (fail-closed) or the stored payload is corrupt.
+ */
+export function getAuthEntry(serverName: string): AuthEntry | undefined {
+  if (authEntryCache.has(serverName)) {
+    return cloneAuthEntry(authEntryCache.get(serverName));
+  }
+
+  const account = getAuthEntryAccount(serverName);
+  const payload = readSecret(account);
+  let entry: AuthEntry | undefined;
+  if (payload !== undefined) {
+    const manifest = parseManifest(payload);
+    entry = manifest
+      ? readChunkedEntry(account, manifest)
+      : parseAuthEntry(payload);
+  }
+
+  // Cache the result — presence AND absence — to short-circuit later reads.
+  authEntryCache.set(serverName, entry);
+  return cloneAuthEntry(entry);
+}
+
+/**
+ * Persist the auth entry for a server, chunking large payloads. Replaces any
+ * previously stored entry and removes its stale chunks. Throws when the
+ * credential store is unavailable (fail-closed, no plaintext fallback).
+ */
+export function saveAuthEntry(serverName: string, entry: AuthEntry, serverUrl?: string): void {
+  if (serverUrl) entry.serverUrl = serverUrl;
+
+  const account = getAuthEntryAccount(serverName);
+  const payload = JSON.stringify(entry);
+
+  // Read the previous state before overwriting: a newer smaller payload
+  // replaces the manifest, so the old chunk group must be learned from the
+  // previous main-account content while it is still readable.
+  const previousPayload = readSecret(account);
+  const previousGroup =
+    previousPayload !== undefined ? chunkGroupForPayload(previousPayload) : undefined;
+
+  const newGroup: ChunkGroup | undefined =
+    payload.length > AUTH_SECRET_CHUNK_SIZE
+      ? { digest: digestPayload(payload), count: chunkCountForPayload(payload) }
+      : undefined;
+
+  try {
+    if (newGroup) {
+      const manifest: ChunkManifest = {
+        __chunks: 1,
+        chunkCount: newGroup.count,
+        chunkDigest: newGroup.digest,
+      };
+      for (let i = 0; i < newGroup.count; i++) {
+        writeSecret(
+          getChunkAccount(account, newGroup.digest, i),
+          payload.slice(i * AUTH_SECRET_CHUNK_SIZE, (i + 1) * AUTH_SECRET_CHUNK_SIZE),
+        );
+      }
+      // Manifest last: a crash mid-write leaves the previous consistent state.
+      writeSecret(account, JSON.stringify(manifest));
+    } else {
+      writeSecret(account, payload);
+    }
+  } catch (error) {
+    // Incomplete write: clean up any chunks of the new group already written.
+    if (newGroup) removeChunkGroup(account, newGroup);
+    throw error;
+  }
+
+  // Stale-chunk cleanup: only when the chunk group changed. Equal digests
+  // mean an identical payload, whose chunks, if any, were just rewritten.
+  const newDigest = newGroup ? newGroup.digest : digestPayload(payload);
+  if (previousGroup && previousGroup.digest !== newDigest) {
+    removeChunkGroup(account, previousGroup);
+  }
+
+  authEntryCache.set(serverName, cloneAuthEntry(entry));
+}
+
+/**
+ * Delete the stored auth entry for a server: manifest, all of its chunks,
+ * and the main account. Idempotent for servers that were never saved.
+ * Throws when the credential store is unavailable (fail-closed).
+ */
+export function deleteAuthEntry(serverName: string): void {
+  const account = getAuthEntryAccount(serverName);
+
+  const payload = readSecret(account);
+  if (payload !== undefined) {
+    removeChunkGroup(account, chunkGroupForPayload(payload));
+  }
+  removeSecret(account);
+
+  authEntryCache.delete(serverName);
+}

package/src/auto-auth.test.ts

@@ -0,0 +1,231 @@
+import { describe, expect, it, vi } from "vitest";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import open from "open";
+import { autoAuthenticate, needsAuthToolResult } from "./auto-auth.js";
+import type { ServerClient } from "./server-client.js";
+
+// The real BorderedLoader needs a live TUI; a stub with the same surface
+// (constructor message + onAbort) is enough to drive the auto-auth flow.
+vi.mock("@earendil-works/pi-coding-agent", () => ({
+  BorderedLoader: class {
+    message: string;
+    onAbort?: () => void;
+    constructor(_tui: unknown, _theme: unknown, message: string) {
+      this.message = message;
+    }
+    dispose() {}
+  },
+}));
+vi.mock("open", () => ({ default: vi.fn().mockResolvedValue({}) }));
+
+const AUTH_URL = "https://as.example/authorize?state=xyz";
+
+// ── fakes ────────────────────────────────────────────────────────────────────
+
+interface FakeClientOpts {
+  /** success: resolves; wait: hangs until the signal aborts; throw: rejects with `error`. */
+  outcome?: "success" | "wait" | "throw";
+  error?: string;
+  /** Status the client reports after close()+connect() (default: "connected"). */
+  statusAfterReconnect?: string;
+}
+
+interface FakeClient {
+  name: string;
+  status: string;
+  error: string | null;
+  tools: never[];
+  close: ReturnType<typeof vi.fn>;
+  connect: ReturnType<typeof vi.fn>;
+  authenticate: ReturnType<typeof vi.fn>;
+}
+
+/** Minimal needs-auth ServerClient fake — authenticate/close/connect are scripted. */
+function makeFakeClient(opts: FakeClientOpts = {}): FakeClient {
+  const client: FakeClient = {
+    name: "srv",
+    status: "needs-auth",
+    error: "authentication required or token rejected",
+    tools: [],
+    close: vi.fn(async () => {}),
+    connect: vi.fn(async () => {
+      client.status = opts.statusAfterReconnect ?? "connected";
+    }),
+    authenticate: vi.fn(),
+  };
+  client.authenticate.mockImplementation(
+    (options?: { signal?: AbortSignal; onAuthorizationUrl?: (u: URL) => void | Promise<void> }) => {
+      if (options?.signal?.aborted) return Promise.reject(new Error("OAuth cancelled"));
+      switch (opts.outcome ?? "success") {
+        case "wait":
+          // Hangs until the signal aborts — like a browser flow awaiting a callback.
+          return new Promise<void>((_resolve, reject) => {
+            options?.signal?.addEventListener(
+              "abort",
+              () => reject(new Error("OAuth cancelled")),
+              { once: true },
+            );
+          });
+        case "throw":
+          return Promise.reject(new Error(opts.error ?? "boom"));
+        default:
+          return Promise.resolve();
+      }
+    },
+  );
+  return client;
+}
+
+interface CtxState {
+  notify: ReturnType<typeof vi.fn>;
+  custom: ReturnType<typeof vi.fn>;
+  lastLoader: () => { message: string; onAbort?: () => void } | null;
+}
+
+/** Fake ExtensionContext: custom() runs the factory synchronously and
+ *  resolves when done() is first called; the loader is captured. */
+function makeCtx(hasUI: boolean): { ctx: ExtensionContext; state: CtxState } {
+  const state: Omit<CtxState, "lastLoader"> = { notify: vi.fn(), custom: vi.fn() };
+  let lastLoader: { message: string; onAbort?: () => void } | null = null;
+  state.custom.mockImplementation(
+    (factory: (
+      tui: unknown,
+      theme: unknown,
+      keybindings: unknown,
+      done: (result: unknown) => void,
+    ) => unknown) => {
+      let resolve!: (result: unknown) => void;
+      const pending = new Promise<unknown>((r) => (resolve = r));
+      let settled = false;
+      const done = (result: unknown) => {
+        if (!settled) {
+          settled = true;
+          resolve(result);
+        }
+      };
+      lastLoader = factory({}, {}, {}, done) as { message: string; onAbort?: () => void } | null;
+      return pending;
+    },
+  );
+  const ctx = {
+    hasUI,
+    signal: new AbortController().signal,
+    ui: { notify: state.notify, custom: state.custom },
+  } as unknown as ExtensionContext;
+  return { ctx, state: { ...state, lastLoader: () => lastLoader } };
+}
+
+// ── needsAuthToolResult ──────────────────────────────────────────────────────
+
+describe("needsAuthToolResult", () => {
+  it("is guidance (isError false) pointing at /mcp auth <server>", () => {
+    const r = needsAuthToolResult("auth-srv");
+    expect(r.isError).toBe(false);
+    expect(r.details).toEqual({ server: "auth-srv", status: "needs-auth" });
+    const text = r.content[0]!.text;
+    expect(text).toContain("requires authentication");
+    expect(text).toContain("/mcp auth auth-srv");
+    expect(text).not.toContain("Auto-auth failed");
+  });
+
+  it("includes the auto-auth error when provided", () => {
+    const r = needsAuthToolResult("auth-srv", "OAuth cancelled");
+    const text = r.content[0]!.text;
+    expect(text).toContain("OAuth cancelled");
+    expect(text).toContain("/mcp auth auth-srv");
+    expect(r.isError).toBe(false);
+  });
+});
+
+// ── autoAuthenticate ─────────────────────────────────────────────────────────
+
+describe("autoAuthenticate", () => {
+  it("runs the flow through a BorderedLoader, opens the URL, and reconnects on success", async () => {
+    const client = makeFakeClient();
+    const { ctx, state } = makeCtx(true);
+    const outcome = await autoAuthenticate(ctx, client as unknown as ServerClient);
+
+    expect(outcome.proceed).toBe(true);
+    expect(outcome.error).toBeUndefined();
+    expect(state.custom).toHaveBeenCalledTimes(1);
+    expect(state.lastLoader()!.message).toContain("srv");
+    expect(client.authenticate).toHaveBeenCalledTimes(1);
+    const opts = client.authenticate.mock.calls[0]![0] as {
+      signal: AbortSignal;
+      onAuthorizationUrl: (u: URL) => Promise<void>;
+    };
+    expect(opts.signal.aborted).toBe(false);
+    // Authorization URL: open the browser and notify the user of it
+    await opts.onAuthorizationUrl(new URL(AUTH_URL));
+    expect(open).toHaveBeenCalledWith(AUTH_URL);
+    expect(state.notify).toHaveBeenCalledWith(expect.stringContaining(AUTH_URL), "info");
+    // Reconnect to pick up the freshly stored token (mirrors /mcp auth)
+    expect(client.close).toHaveBeenCalledTimes(1);
+    expect(client.connect).toHaveBeenCalledTimes(1);
+  });
+
+  it("esc aborts the flow, reports cancellation, and does not reconnect", async () => {
+    const client = makeFakeClient({ outcome: "wait" });
+    const { ctx, state } = makeCtx(true);
+    const running = autoAuthenticate(ctx, client as unknown as ServerClient);
+    await vi.waitFor(() => expect(client.authenticate).toHaveBeenCalledTimes(1));
+    const opts = client.authenticate.mock.calls[0]![0] as { signal: AbortSignal };
+    expect(opts.signal.aborted).toBe(false);
+
+    // Simulate Esc in the loader
+    state.lastLoader()!.onAbort!();
+    const outcome = await running;
+
+    expect(opts.signal.aborted).toBe(true);
+    expect(outcome.proceed).toBe(false);
+    expect(outcome.error).toBe("OAuth cancelled");
+    expect(client.close).not.toHaveBeenCalled();
+    expect(client.connect).not.toHaveBeenCalled();
+  });
+
+  it("surfaces flow failures without throwing and without reconnecting", async () => {
+    const client = makeFakeClient({ outcome: "throw", error: "token endpoint refused" });
+    const { ctx } = makeCtx(true);
+    const outcome = await autoAuthenticate(ctx, client as unknown as ServerClient);
+    expect(outcome.proceed).toBe(false);
+    expect(outcome.error).toBe("token endpoint refused");
+    expect(client.close).not.toHaveBeenCalled();
+    expect(client.connect).not.toHaveBeenCalled();
+  });
+
+  it("runs headless (no loader) when the context has no UI", async () => {
+    const client = makeFakeClient();
+    const { ctx, state } = makeCtx(false);
+    const outcome = await autoAuthenticate(ctx, client as unknown as ServerClient);
+    expect(outcome.proceed).toBe(true);
+    expect(state.custom).not.toHaveBeenCalled();
+    expect(client.authenticate).toHaveBeenCalledTimes(1);
+    expect(client.close).toHaveBeenCalledTimes(1);
+    expect(client.connect).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns the error headless when the flow fails", async () => {
+    const client = makeFakeClient({ outcome: "throw", error: "keyring unavailable" });
+    const { ctx } = makeCtx(false);
+    const outcome = await autoAuthenticate(ctx, client as unknown as ServerClient);
+    expect(outcome).toEqual({ proceed: false, error: "keyring unavailable" });
+    expect(client.close).not.toHaveBeenCalled();
+  });
+
+  it("reports when the reconnected server still needs auth (ADR 0001 re-auth loop)", async () => {
+    const client = makeFakeClient({ statusAfterReconnect: "needs-auth" });
+    const { ctx } = makeCtx(false);
+    const outcome = await autoAuthenticate(ctx, client as unknown as ServerClient);
+    expect(outcome.proceed).toBe(false);
+    expect(outcome.error).toMatch(/still/i);
+  });
+
+  it("reports a failed reconnect after successful authentication", async () => {
+    const client = makeFakeClient();
+    client.connect.mockRejectedValue(new Error("connection refused"));
+    const { ctx } = makeCtx(false);
+    const outcome = await autoAuthenticate(ctx, client as unknown as ServerClient);
+    expect(outcome.proceed).toBe(false);
+    expect(outcome.error).toContain("connection refused");
+  });
+});

package/src/auto-auth.ts

@@ -0,0 +1,135 @@
+/**
+ * Tool-call-time `needs-auth` handling, shared by the `mcp` proxy's call
+ * action and the direct-tool executor (plan-026, Task 7).
+ *
+ * When the owning server's client is in the `needs-auth` state at call time:
+ *
+ * - autoAuth disabled (default): no authentication is initiated; the caller
+ *   returns guidance content (`isError: false` — guidance, not a crash)
+ *   telling the user to run `/mcp auth <server>`.
+ * - autoAuth enabled: `ServerClient.authenticate` (the SINGLE auth entry
+ *   point — never `auth-flow.authenticate` directly) is called inline and the
+ *   caller retries the tool call once. A `BorderedLoader` (tui.md Pattern 2,
+ *   same pattern as `/mcp auth`) shows progress when the execute context has
+ *   UI; esc aborts the flow. Headless contexts run the flow plainly and the
+ *   authorization URL is opened directly.
+ *
+ * The loader/cancel/reconnect machinery is shared with `/mcp auth` in
+ * `auth-run.ts`; this module maps the structured outcome onto the tool's
+ * `{ proceed, error }` guidance result.
+ */
+import { type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  openAuthUrl,
+  reconnectAfterAuth,
+  runAuthWithLoader,
+  type AuthRunOutcome,
+} from "./auth-run.js";
+import type { AuthenticateOptions } from "./auth-flow.js";
+import type { ServerClient } from "./server-client.js";
+
+/** Tool result for a needs-auth server: guidance, not a crash. */
+export interface NeedsAuthToolResult {
+  content: Array<{ type: "text"; text: string }>;
+  details: { server: string; status: "needs-auth" };
+  isError: false;
+}
+
+/**
+ * Guidance result for a needs-auth server. `autoAuthError` is only set when
+ * autoAuth was enabled but the inline flow was cancelled or failed.
+ */
+export function needsAuthToolResult(
+  serverName: string,
+  autoAuthError?: string,
+): NeedsAuthToolResult {
+  const lines = [`MCP server "${serverName}" requires authentication.`];
+  if (autoAuthError !== undefined) lines.push(`Auto-auth failed: ${autoAuthError}`);
+  lines.push(`Run /mcp auth ${serverName} to authenticate, then retry this call.`);
+  return {
+    content: [{ type: "text" as const, text: lines.join("\n") }],
+    details: { server: serverName, status: "needs-auth" },
+    isError: false,
+  };
+}
+
+/** Outcome of an inline auto-auth attempt. */
+export interface AutoAuthOutcome {
+  /** True when the flow succeeded AND the client was reconnected — the caller should retry the call once. */
+  proceed: boolean;
+  /** Error text for the guidance result when proceed is false. */
+  error?: string;
+}
+
+function toMessage(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}
+
+/** Map the shared auth-run outcome onto the tool's guidance result. */
+function toAutoAuthOutcome(outcome: AuthRunOutcome, serverName: string): AutoAuthOutcome {
+  switch (outcome.kind) {
+    case "cancelled":
+      return { proceed: false, error: "OAuth cancelled" };
+    case "flow-error":
+      return { proceed: false, error: outcome.error };
+    case "reconnect-failed":
+      return {
+        proceed: false,
+        error: `authenticated, but reconnecting ${serverName} failed: ${outcome.error}`,
+      };
+    case "reconnected":
+      if (outcome.status === "needs-auth") {
+        // The freshly stored token was rejected immediately — e.g. a
+        // pre-registered public client whose session needs interactive
+        // re-auth (ADR 0001). Guidance points back at /mcp auth.
+        return {
+          proceed: false,
+          error: "auth succeeded, but the server still requires authentication",
+        };
+      }
+      return { proceed: true };
+  }
+}
+
+/**
+ * Run `ServerClient.authenticate` inline.
+ *
+ * With a UI context the flow is wrapped in a `BorderedLoader` (same pattern
+ * as `/mcp auth`): esc aborts the flow and the cancellation is reported as
+ * "OAuth cancelled". Without one (print/RPC mode) the flow runs plainly,
+ * tied to the agent's abort signal when streaming.
+ *
+ * On success the client is closed and reconnected so the freshly stored
+ * token is re-read into the Bearer header (mirrors `/mcp auth`). Cancellation,
+ * flow failure, and reconnect failure are returned as errors rather than
+ * thrown into the tool call.
+ */
+export async function autoAuthenticate(
+  ctx: ExtensionContext | undefined,
+  client: ServerClient,
+): Promise<AutoAuthOutcome> {
+  if (ctx?.hasUI) {
+    return toAutoAuthOutcome(
+      await runAuthWithLoader(ctx, client, {
+        loaderLabel: `Authenticating ${client.name}… (esc to cancel)`,
+      }),
+      client.name,
+    );
+  }
+
+  try {
+    // Headless: no loader to cancel with — when the agent is streaming,
+    // tie the flow to its abort signal instead.
+    const opts: AuthenticateOptions = {
+      onAuthorizationUrl: (url: URL) => openAuthUrl(url.toString()),
+    };
+    if (ctx?.signal) opts.signal = ctx.signal;
+    await client.authenticate(opts);
+  } catch (e) {
+    return { proceed: false, error: toMessage(e) };
+  }
+
+  // Success: close + reconnect so the fresh token is used immediately
+  // (connect re-reads the keyring for the Bearer header — mirrors /mcp auth)
+  return toAutoAuthOutcome(await reconnectAfterAuth(client), client.name);
+}