@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/codeAgent/tools/McpOAuth.ts

@@ -0,0 +1,233 @@
+import { createHash, randomBytes } from "node:crypto";
+import type { CodeAgentMcpServerRef } from "akanjs/common";
+import type { McpStoredAuth } from "./McpTokenStore";
+
+export interface McpOAuthServer {
+  issuer: string;
+  authorizationEndpoint: string;
+  tokenEndpoint: string;
+  registrationEndpoint?: string;
+  scopesSupported?: string[];
+  /** RFC 8707: what the token is minted for, which is the MCP endpoint and not the authorization server. */
+  resource: string;
+  /** Scopes the resource asked for in its own metadata, which are the ones to request. */
+  resourceScopes?: string[];
+}
+
+export interface McpOAuthTokens {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt?: number;
+  scope?: string;
+}
+
+interface TokenResponse {
+  access_token?: string;
+  refresh_token?: string;
+  expires_in?: number;
+  scope?: string;
+  error?: string;
+  error_description?: string;
+}
+
+// Every endpoint is discovered from the 401 challenge; `pkgs/akanjs/server/mcp/McpAuth.ts` is the server half.
+export class McpOAuth {
+  /** RFC 9728. A client tries the path-inserted spelling first and the bare one second. */
+  static readonly resourceWellKnown = "/.well-known/oauth-protected-resource";
+  static readonly serverWellKnown = "/.well-known/oauth-authorization-server";
+  static readonly openidWellKnown = "/.well-known/openid-configuration";
+  /** A fixed list, not an ephemeral port: a registered client is bound to its exact `redirect_uri`. */
+  static readonly ports = [33418, 33419, 33420, 33421, 33422];
+  static readonly callbackPath = "/callback";
+  /** How long the browser half may take before the loopback server gives the port back. */
+  static readonly timeoutMs = 300_000;
+
+  static #json(response: Response) {
+    return response.json() as Promise<Record<string, unknown>>;
+  }
+
+  /** The challenge's `resource_metadata` wins over derived urls: only the server knows which spelling it published. */
+  static resourceMetadataUrls(serverUrl: string, challenge?: string | null) {
+    const named = challenge ? /resource_metadata="([^"]+)"/.exec(challenge)?.[1] : undefined;
+    if (named) return [named];
+    const url = new URL(serverUrl);
+    const withPath = url.pathname === "/" ? "" : url.pathname.replace(/\/$/, "");
+    return [
+      new URL(`${McpOAuth.resourceWellKnown}${withPath}`, url.origin).href,
+      new URL(McpOAuth.resourceWellKnown, url.origin).href,
+    ];
+  }
+
+  /** RFC 8414 §3.1 inserts the issuer's path after the suffix; OpenID appends it. Both are tried. */
+  static serverMetadataUrls(issuer: string) {
+    const url = new URL(issuer);
+    const withPath = url.pathname === "/" ? "" : url.pathname.replace(/\/$/, "");
+    return [
+      new URL(`${McpOAuth.serverWellKnown}${withPath}`, url.origin).href,
+      new URL(`${withPath}${McpOAuth.openidWellKnown}`, url.origin).href,
+      new URL(McpOAuth.serverWellKnown, url.origin).href,
+    ];
+  }
+
+  /** A resource with no metadata falls back to its own origin as issuer: many servers skip the discovery half. */
+  static async discover(serverUrl: string, challenge?: string | null): Promise<McpOAuthServer> {
+    const resourceDoc = await McpOAuth.#first(McpOAuth.resourceMetadataUrls(serverUrl, challenge));
+    const resource = typeof resourceDoc?.resource === "string" ? resourceDoc.resource : serverUrl;
+    const resourceScopes = McpOAuth.#strings(resourceDoc?.scopes_supported);
+    const issuers = McpOAuth.#strings(resourceDoc?.authorization_servers);
+    const candidates = issuers.length ? issuers : [new URL(serverUrl).origin];
+    for (const issuer of candidates) {
+      const doc = await McpOAuth.#first(McpOAuth.serverMetadataUrls(issuer));
+      if (!doc) continue;
+      const methods = McpOAuth.#strings(doc.code_challenge_methods_supported);
+      // Refuse rather than downgrade (OAuth 2.1): a document without S256 is too old or rewritten by an attacker.
+      if (methods.length && !methods.includes("S256"))
+        throw new Error(`${issuer} does not offer PKCE S256, which is the only method this client will use.`);
+      const authorizationEndpoint = typeof doc.authorization_endpoint === "string" ? doc.authorization_endpoint : "";
+      const tokenEndpoint = typeof doc.token_endpoint === "string" ? doc.token_endpoint : "";
+      if (!authorizationEndpoint || !tokenEndpoint) continue;
+      return {
+        issuer: typeof doc.issuer === "string" ? doc.issuer : issuer,
+        authorizationEndpoint,
+        tokenEndpoint,
+        ...(typeof doc.registration_endpoint === "string" ? { registrationEndpoint: doc.registration_endpoint } : {}),
+        ...(McpOAuth.#strings(doc.scopes_supported).length
+          ? { scopesSupported: McpOAuth.#strings(doc.scopes_supported) }
+          : {}),
+        resource,
+        ...(resourceScopes.length ? { resourceScopes } : {}),
+      };
+    }
+    throw new Error(`No OAuth metadata was found for ${serverUrl}. Declare "oauth" for it in mcp.json.`);
+  }
+
+  /** RFC 7591. What lets a hosted server be reached with nothing declared but its url. */
+  static async register(server: McpOAuthServer, redirectUri: string, name: string) {
+    if (!server.registrationEndpoint)
+      throw new Error(
+        `${server.issuer} registers no clients on demand. Put its "oauth": { "clientId": "…" } in mcp.json.`,
+      );
+    const response = await fetch(server.registrationEndpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        client_name: `akan code (${name})`,
+        redirect_uris: [redirectUri],
+        grant_types: ["authorization_code", "refresh_token"],
+        response_types: ["code"],
+        // A CLI cannot keep a secret, so it says so and the server issues a public client.
+        token_endpoint_auth_method: "none",
+        application_type: "native",
+      }),
+      signal: AbortSignal.timeout(30_000),
+    });
+    const body = (await McpOAuth.#json(response)) as { client_id?: string; client_secret?: string; error?: string };
+    if (!response.ok || !body.client_id)
+      throw new Error(`${server.issuer} refused the client registration: ${body.error ?? response.status}`);
+    return { clientId: body.client_id, ...(body.client_secret ? { clientSecret: body.client_secret } : {}) };
+  }
+
+  static async authorize(options: {
+    server: McpOAuthServer;
+    clientId: string;
+    clientSecret?: string;
+    redirectUri: string;
+    scope?: string;
+    /** Receives the url to open. Nothing happens until somebody visits it. */
+    open: (url: string) => void;
+    /** The already-bound loopback that answers the redirect. */
+    wait: () => Promise<URLSearchParams>;
+  }): Promise<McpOAuthTokens> {
+    const verifier = randomBytes(32).toString("base64url");
+    const state = randomBytes(16).toString("base64url");
+    const scope =
+      options.scope ?? options.server.resourceScopes?.join(" ") ?? options.server.scopesSupported?.join(" ");
+    const authorize = new URL(options.server.authorizationEndpoint);
+    for (const [key, value] of Object.entries({
+      response_type: "code",
+      client_id: options.clientId,
+      redirect_uri: options.redirectUri,
+      code_challenge: createHash("sha256").update(verifier).digest("base64url"),
+      code_challenge_method: "S256",
+      state,
+      resource: options.server.resource,
+      ...(scope ? { scope } : {}),
+    }))
+      authorize.searchParams.set(key, value);
+    options.open(authorize.href);
+    const params = await options.wait();
+    const error = params.get("error");
+    if (error) throw new Error(`${error}: ${params.get("error_description") ?? "the authorization was refused"}`);
+    if (params.get("state") !== state) throw new Error("The authorization response carried the wrong state.");
+    const iss = params.get("iss");
+    // Without the iss check a response from one authorization server can be replayed at another.
+    if (iss && iss !== options.server.issuer)
+      throw new Error(`The authorization response came from ${iss}, not ${options.server.issuer}.`);
+    const code = params.get("code");
+    if (!code) throw new Error("The authorization response carried no code.");
+    return await McpOAuth.#token(options.server, {
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: options.redirectUri,
+      client_id: options.clientId,
+      code_verifier: verifier,
+      resource: options.server.resource,
+      ...(options.clientSecret ? { client_secret: options.clientSecret } : {}),
+    });
+  }
+
+  static async refresh(server: McpOAuthServer, auth: McpStoredAuth) {
+    if (!auth.refreshToken) throw new Error("There is no refresh token for this server.");
+    return await McpOAuth.#token(server, {
+      grant_type: "refresh_token",
+      refresh_token: auth.refreshToken,
+      client_id: auth.clientId,
+      resource: server.resource,
+      ...(auth.clientSecret ? { client_secret: auth.clientSecret } : {}),
+      ...(auth.scope ? { scope: auth.scope } : {}),
+    });
+  }
+
+  /** The scope a server was signed in with, or what its metadata asks for, for a refresh that must restate it. */
+  static scopeOf(ref: CodeAgentMcpServerRef, server: McpOAuthServer) {
+    return ref.oauth?.scope ?? server.resourceScopes?.join(" ") ?? server.scopesSupported?.join(" ");
+  }
+
+  static async #token(server: McpOAuthServer, form: Record<string, string>): Promise<McpOAuthTokens> {
+    const response = await fetch(server.tokenEndpoint, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+      body: new URLSearchParams(form).toString(),
+      signal: AbortSignal.timeout(30_000),
+    });
+    const body = (await McpOAuth.#json(response)) as TokenResponse;
+    if (!response.ok || !body.access_token)
+      throw new Error(`${server.tokenEndpoint} refused the token request: ${body.error ?? response.status}`);
+    return {
+      accessToken: body.access_token,
+      ...(body.refresh_token ? { refreshToken: body.refresh_token } : {}),
+      ...(body.expires_in ? { expiresAt: Date.now() + body.expires_in * 1_000 } : {}),
+      ...(body.scope ? { scope: body.scope } : {}),
+    };
+  }
+
+  static async #first(urls: string[]) {
+    for (const url of urls) {
+      try {
+        const response = await fetch(url, {
+          headers: { accept: "application/json", "mcp-protocol-version": "2025-06-18" },
+          signal: AbortSignal.timeout(15_000),
+        });
+        if (!response.ok) continue;
+        return await McpOAuth.#json(response);
+      } catch {
+        // A metadata url that does not resolve is one spelling out of several; the caller tries the next.
+      }
+    }
+    return undefined;
+  }
+
+  static #strings(value: unknown) {
+    return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string") : [];
+  }
+}

package/codeAgent/tools/McpOAuthLoopback.ts

@@ -0,0 +1,64 @@
+import { McpOAuth } from "./McpOAuth";
+
+export class McpOAuthLoopback {
+  readonly #server: ReturnType<typeof Bun.serve>;
+  readonly #port: number;
+  #resolve: ((params: URLSearchParams) => void) | undefined;
+  readonly #answer: Promise<URLSearchParams>;
+
+  private constructor(port: number) {
+    this.#port = port;
+    this.#answer = new Promise<URLSearchParams>((resolve) => {
+      this.#resolve = resolve;
+    });
+    this.#server = Bun.serve({
+      port,
+      // Never 0.0.0.0: the redirect carries a credential that anything on the network could race the browser for.
+      hostname: "127.0.0.1",
+      fetch: (request) => this.#handle(request),
+    });
+  }
+
+  /** The registered port first, else the first free one; a caller that lost its port registers again. */
+  static bind(preferred?: number) {
+    const ports = preferred ? [preferred, ...McpOAuth.ports.filter((port) => port !== preferred)] : McpOAuth.ports;
+    const failures: string[] = [];
+    for (const port of ports) {
+      try {
+        return new McpOAuthLoopback(port);
+      } catch (error) {
+        failures.push(`${port}: ${String(error)}`);
+      }
+    }
+    throw new Error(`No loopback port was free for the sign-in — ${failures.join(", ")}`);
+  }
+
+  get redirectUri() {
+    return `http://127.0.0.1:${this.#port}${McpOAuth.callbackPath}`;
+  }
+
+  /** The query the browser came back with, or a timeout — a sign-in nobody finishes must give the port back. */
+  async wait() {
+    const timeout = new Promise<never>((_, reject) =>
+      setTimeout(() => reject(new Error("The sign-in was not completed in time.")), McpOAuth.timeoutMs).unref?.(),
+    );
+    return await Promise.race([this.#answer, timeout]);
+  }
+
+  close() {
+    this.#server.stop(true);
+  }
+
+  #handle(request: Request) {
+    const url = new URL(request.url);
+    if (url.pathname !== McpOAuth.callbackPath) return new Response("Not found", { status: 404 });
+    this.#resolve?.(url.searchParams);
+    const failed = url.searchParams.get("error");
+    return new Response(
+      `<!doctype html><meta charset="utf-8"><title>akan code</title><body style="font:16px system-ui;padding:3rem">
+<h1>${failed ? "Sign-in failed" : "Signed in"}</h1>
+<p>${failed ? `The authorization server said: ${Bun.escapeHTML(failed)}` : "You can close this tab and go back to the terminal."}</p>`,
+      { status: failed ? 400 : 200, headers: { "content-type": "text/html; charset=utf-8" } },
+    );
+  }
+}

package/codeAgent/tools/McpServerConfig.ts

@@ -0,0 +1,129 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import type { CodeAgentMcpServerRef } from "akanjs/common";
+import { akanCodePaths } from "../agent/akanCodePaths";
+
+export type McpServerScope = "global" | "workspace";
+
+export interface McpDeclaredServer {
+  ref: CodeAgentMcpServerRef;
+  disabled: boolean;
+  scope: McpServerScope;
+}
+
+interface ServerFileEntry {
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  url?: string;
+  type?: string;
+  disabled?: boolean;
+  headers?: Record<string, string>;
+  oauth?: { clientId?: string; clientSecret?: string; scope?: string };
+}
+
+interface ServerFile {
+  mcpServers?: Record<string, ServerFileEntry>;
+  servers?: Record<string, ServerFileEntry>;
+}
+
+// Global is the default home: a server's token already lives there, so one declaration serves every checkout.
+// VS Code spells the key `servers`; a write keeps the file's own key, or it breaks the editor sharing the file.
+export class McpServerConfig {
+  static file(workspaceRoot: string, scope: McpServerScope = "workspace") {
+    return scope === "global" ? akanCodePaths.globalMcpFile() : akanCodePaths.mcpFile(workspaceRoot);
+  }
+
+  /** Both files, in the order they are merged — global first, so the workspace's entry lands on top of it. */
+  static files(workspaceRoot: string): { scope: McpServerScope; file: string }[] {
+    return [
+      { scope: "global", file: McpServerConfig.file(workspaceRoot, "global") },
+      { scope: "workspace", file: McpServerConfig.file(workspaceRoot, "workspace") },
+    ];
+  }
+
+  static read(workspaceRoot: string): CodeAgentMcpServerRef[] {
+    return McpServerConfig.declared(workspaceRoot)
+      .filter((entry) => !entry.disabled)
+      .map((entry) => entry.ref);
+  }
+
+  /** Every declared server including the disabled ones, which is what a listing has to show. */
+  static declared(workspaceRoot: string): McpDeclaredServer[] {
+    const byName = new Map<string, McpDeclaredServer>();
+    for (const { scope } of McpServerConfig.files(workspaceRoot))
+      for (const [name, entry] of Object.entries(McpServerConfig.#parse(workspaceRoot, scope).map))
+        byName.set(name, { ref: McpServerConfig.#refOf(name, entry), disabled: !!entry.disabled, scope });
+    return [...byName.values()];
+  }
+
+  /** Replaces a same-name entry in the target file; a url is an http server, anything else a command and argv. */
+  static add(workspaceRoot: string, name: string, target: string[], scope: McpServerScope = "global") {
+    const [head, ...rest] = target;
+    if (!head) throw new Error("Give the server a command to run, or a url to reach.");
+    const entry: ServerFileEntry = /^https?:\/\//.test(head) ? { url: head } : { command: head, args: rest };
+    const { file, key, map } = McpServerConfig.#parse(workspaceRoot, scope);
+    const next = { ...map, [name]: entry };
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify({ [key]: next }, null, 2)}\n`);
+    return McpServerConfig.#refOf(name, entry);
+  }
+
+  /** Removes it from the file `only` names, else the workspace file and then the global one; false when none has it. */
+  static remove(workspaceRoot: string, name: string, only?: McpServerScope): McpServerScope | false {
+    const candidates = McpServerConfig.files(workspaceRoot).filter(({ scope }) => !only || scope === only);
+    for (const { scope } of candidates.reverse()) {
+      const { file, key, map } = McpServerConfig.#parse(workspaceRoot, scope);
+      if (!(name in map)) continue;
+      const next = { ...map };
+      delete next[name];
+      writeFileSync(file, `${JSON.stringify({ [key]: next }, null, 2)}\n`);
+      return scope;
+    }
+    return false;
+  }
+
+  static #refOf(name: string, entry: ServerFileEntry): CodeAgentMcpServerRef {
+    return {
+      name,
+      transport: entry.url ? "http" : "stdio",
+      ...(entry.command ? { command: entry.command } : {}),
+      ...(entry.args ? { args: entry.args } : {}),
+      ...(entry.url ? { url: entry.url } : {}),
+      ...(entry.env ? { env: entry.env } : {}),
+      ...(entry.headers ? { headers: entry.headers } : {}),
+      ...(entry.oauth ? { oauth: entry.oauth } : {}),
+    };
+  }
+
+  static targetOf(ref: CodeAgentMcpServerRef) {
+    return ref.url ?? [ref.command, ...(ref.args ?? [])].filter(Boolean).join(" ");
+  }
+
+  /** Why a file yielded nothing, when it exists and yielded nothing — a listing has to say which. */
+  static problem(workspaceRoot: string) {
+    for (const { file } of McpServerConfig.files(workspaceRoot)) {
+      if (!existsSync(file)) continue;
+      try {
+        JSON.parse(readFileSync(file, "utf8"));
+      } catch (error) {
+        return `${file} is not valid JSON — ${String(error)}`;
+      }
+    }
+    return undefined;
+  }
+
+  static #parse(workspaceRoot: string, scope: McpServerScope) {
+    const file = McpServerConfig.file(workspaceRoot, scope);
+    const empty = { file, key: "mcpServers" as const, map: {} as Record<string, ServerFileEntry> };
+    if (!existsSync(file)) return empty;
+    try {
+      const parsed = JSON.parse(readFileSync(file, "utf8")) as ServerFile;
+      if (parsed.servers && !parsed.mcpServers) return { file, key: "servers" as const, map: parsed.servers };
+      return { ...empty, map: parsed.mcpServers ?? {} };
+    } catch {
+      // A malformed file costs its servers, not the session; `problem` is what says so on the listing.
+      return empty;
+    }
+  }
+}

package/codeAgent/tools/McpSignIn.ts

@@ -0,0 +1,158 @@
+import type { CodeAgentMcpServerRef } from "akanjs/common";
+import { ConfigLock } from "../../cloud/configLock";
+import { McpOAuth, type McpOAuthServer } from "./McpOAuth";
+import { McpOAuthLoopback } from "./McpOAuthLoopback";
+import { type McpStoredAuth, McpTokenStore } from "./McpTokenStore";
+
+export interface McpSignInOptions {
+  /** How the host reaches a browser. A host with none must not call {@link McpSignIn.run}. */
+  open: (url: string) => void;
+  onNotice?: (message: string) => void;
+}
+
+export class McpSignIn {
+  // A server that rotates refresh tokens may revoke the whole grant when one is presented twice.
+  static readonly #refreshing = new Map<string, Promise<string | undefined>>();
+
+  /** The token to connect with, or undefined when none is had without asking; a failed refresh is not a throw. */
+  static async token(ref: CodeAgentMcpServerRef, onNotice?: (message: string) => void) {
+    const stored = McpTokenStore.read(ref.name);
+    if (!stored) return undefined;
+    if (!McpTokenStore.isExpired(stored)) return stored.accessToken;
+    return await McpSignIn.#refreshOnce(ref, stored, onNotice);
+  }
+
+  /** After a server answered `refused` with 401: a token another session stored since, else one refresh. */
+  static async retryToken(ref: CodeAgentMcpServerRef, refused: string, onNotice?: (message: string) => void) {
+    const stored = McpTokenStore.read(ref.name);
+    if (!stored) return undefined;
+    if (stored.accessToken !== refused && !McpTokenStore.isExpired(stored)) return stored.accessToken;
+    return await McpSignIn.#refreshOnce(ref, stored, onNotice);
+  }
+
+  static async #refreshOnce(ref: CodeAgentMcpServerRef, stored: McpStoredAuth, onNotice?: (message: string) => void) {
+    const key = `${ref.name}\n${stored.refreshToken}`;
+    let pending = McpSignIn.#refreshing.get(key);
+    if (!pending) {
+      pending = McpSignIn.#refreshed(ref, stored, onNotice).finally(() => McpSignIn.#refreshing.delete(key));
+      McpSignIn.#refreshing.set(key, pending);
+    }
+    return await pending;
+  }
+
+  static async #refreshed(ref: CodeAgentMcpServerRef, stored: McpStoredAuth, onNotice?: (message: string) => void) {
+    if (!stored.refreshToken) return undefined;
+    try {
+      return await ConfigLock.run(McpTokenStore.lockFile(), async () => {
+        // Another `akan code` may have refreshed while this one waited: take its token, never its spent refresh token.
+        const current = McpTokenStore.read(ref.name);
+        if (!current) return undefined;
+        if (current.accessToken !== stored.accessToken && !McpTokenStore.isExpired(current)) return current.accessToken;
+        const server: McpOAuthServer = {
+          issuer: current.issuer,
+          authorizationEndpoint: "",
+          tokenEndpoint: current.tokenEndpoint,
+          resource: current.resource,
+        };
+        const tokens = await McpOAuth.refresh(server, current);
+        // `expires_in` is optional (RFC 6749 §5.1): the spent token's expiry must not outlive it on the new one.
+        const { expiresAt: _spent, ...grant } = current;
+        // A server that rotates refresh tokens invalidates the old one, so keeping it would sign us out.
+        McpTokenStore.write(ref.name, { ...grant, ...tokens });
+        return tokens.accessToken;
+      });
+    } catch (error) {
+      onNotice?.(`MCP server "${ref.name}" needs signing in again — ${String(error)}`);
+      return undefined;
+    }
+  }
+
+  /** Interactive: discover, register unless the stored client is reusable, open a browser, store the token. */
+  static async run(ref: CodeAgentMcpServerRef, options: McpSignInOptions): Promise<McpStoredAuth> {
+    if (!ref.url) throw new Error(`"${ref.name}" is a stdio server: give it its credential through "env".`);
+    const challenge = await McpSignIn.challenge(ref);
+    const server = await McpOAuth.discover(ref.url, challenge);
+    const stored = McpTokenStore.read(ref.name);
+    const reusable = stored && stored.issuer === server.issuer && !ref.oauth?.clientId ? stored : undefined;
+    const loopback = McpOAuthLoopback.bind(McpSignIn.#portOf(reusable?.redirectUri));
+    try {
+      const redirectUri = loopback.redirectUri;
+      const client = await McpSignIn.#client(ref, server, redirectUri, reusable);
+      options.onNotice?.(`Opening a browser to sign in to "${ref.name}"…`);
+      const scope = McpOAuth.scopeOf(ref, server);
+      const tokens = await McpOAuth.authorize({
+        server,
+        clientId: client.clientId,
+        ...(client.clientSecret ? { clientSecret: client.clientSecret } : {}),
+        redirectUri,
+        ...(scope ? { scope } : {}),
+        open: options.open,
+        wait: () => loopback.wait(),
+      });
+      const auth: McpStoredAuth = {
+        issuer: server.issuer,
+        tokenEndpoint: server.tokenEndpoint,
+        resource: server.resource,
+        clientId: client.clientId,
+        ...(client.clientSecret ? { clientSecret: client.clientSecret } : {}),
+        redirectUri,
+        ...tokens,
+      };
+      McpTokenStore.write(ref.name, auth);
+      return auth;
+    } finally {
+      loopback.close();
+    }
+  }
+
+  /** The `WWW-Authenticate` of an unauthenticated `initialize`, or null when the server answers anything but 401. */
+  static async challenge(ref: CodeAgentMcpServerRef) {
+    if (!ref.url) return null;
+    try {
+      const response = await fetch(ref.url, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          accept: "application/json, text/event-stream",
+          ...ref.headers,
+        },
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: 0,
+          method: "initialize",
+          params: { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "akan-code", version: "1" } },
+        }),
+        signal: AbortSignal.timeout(15_000),
+      });
+      return response.status === 401 ? (response.headers.get("www-authenticate") ?? "") : null;
+    } catch {
+      // Unreachable is not unauthenticated. Discovery will try the well-known urls and report its own failure.
+      return null;
+    }
+  }
+
+  static async #client(
+    ref: CodeAgentMcpServerRef,
+    server: McpOAuthServer,
+    redirectUri: string,
+    reusable: McpStoredAuth | undefined,
+  ) {
+    if (ref.oauth?.clientId)
+      return {
+        clientId: ref.oauth.clientId,
+        ...(ref.oauth.clientSecret ? { clientSecret: ref.oauth.clientSecret } : {}),
+      };
+    if (reusable && reusable.redirectUri === redirectUri)
+      return {
+        clientId: reusable.clientId,
+        ...(reusable.clientSecret ? { clientSecret: reusable.clientSecret } : {}),
+      };
+    return await McpOAuth.register(server, redirectUri, ref.name);
+  }
+
+  static #portOf(redirectUri: string | undefined) {
+    if (!redirectUri) return undefined;
+    const port = Number(new URL(redirectUri).port);
+    return Number.isFinite(port) && port > 0 ? port : undefined;
+  }
+}

package/codeAgent/tools/McpTokenStore.ts

@@ -0,0 +1,81 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { akanCodePaths } from "../agent/akanCodePaths";
+
+export interface McpStoredAuth {
+  /** The authorization server that minted it, so a server that moves issuer invalidates rather than misuses it. */
+  issuer: string;
+  /** Kept with the token so a refresh at connect costs no discovery round trip before the first tool call. */
+  tokenEndpoint: string;
+  /** RFC 8707: what the token was minted for, which a refresh has to restate. */
+  resource: string;
+  clientId: string;
+  clientSecret?: string;
+  /** Registered with the client, so a later sign-in binds the same loopback port or registers again. */
+  redirectUri: string;
+  accessToken: string;
+  refreshToken?: string;
+  /** Epoch ms. Absent when the server issued no lifetime, which the spec allows and means "until refused". */
+  expiresAt?: number;
+  scope?: string;
+}
+
+// Home directory only, mode 0600: `.akan/code/mcp.json` is shared with the editors and routinely committed.
+export class McpTokenStore {
+  static file() {
+    return akanCodePaths.mcpAuthFile();
+  }
+
+  static lockFile() {
+    return `${McpTokenStore.file()}.lock`;
+  }
+
+  static read(name: string): McpStoredAuth | undefined {
+    return McpTokenStore.#all()[name];
+  }
+
+  static names() {
+    return Object.keys(McpTokenStore.#all());
+  }
+
+  /** Re-reads right before writing, or two concurrent sign-ins each drop the other's token. */
+  static write(name: string, auth: McpStoredAuth) {
+    McpTokenStore.#save({ ...McpTokenStore.#all(), [name]: auth });
+  }
+
+  static clear(name: string) {
+    const all = McpTokenStore.#all();
+    if (!(name in all)) return false;
+    delete all[name];
+    McpTokenStore.#save(all);
+    return true;
+  }
+
+  static isExpired(auth: McpStoredAuth) {
+    return auth.expiresAt !== undefined && auth.expiresAt <= Date.now() + McpTokenStore.skewMs;
+  }
+
+  /** A token is treated as spent this long before it actually is, so a call never races its own expiry. */
+  static readonly skewMs = 60_000;
+
+  static #all(): Record<string, McpStoredAuth> {
+    const file = McpTokenStore.file();
+    if (!existsSync(file)) return {};
+    try {
+      const parsed = JSON.parse(readFileSync(file, "utf8")) as { servers?: Record<string, McpStoredAuth> };
+      return parsed.servers ?? {};
+    } catch {
+      return {};
+    }
+  }
+
+  static #save(servers: Record<string, McpStoredAuth>) {
+    const file = McpTokenStore.file();
+    mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temp = `${file}.${process.pid}.tmp`;
+    writeFileSync(temp, `${JSON.stringify({ servers }, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temp, file);
+    // `rename` keeps the temp file's mode, but an existing target written by an older build may be looser.
+    chmodSync(file, 0o600);
+  }
+}