@ikarmic/forge-core 4.5.0 → 5.1.0

package/dist/mcp/manager.d.ts

@@ -1,8 +1,9 @@
 import type { ToolDefinition } from '../types.js';
-import { type ConnectedMcpServer } from './mcp-client.js';
+import { type ConnectOptions, type ConnectedMcpServer } from './mcp-client.js';
+import type { McpOAuthOptions } from './oauth.js';
 import type { McpServerSpec } from './mcp-config.js';
 import { type OrgPolicy } from '../policy/policy.js';
-export type McpServerState = 'connected' | 'failed' | 'disabled';
+export type McpServerState = 'connected' | 'failed' | 'disabled' | 'needs-auth';
 export interface McpServerStatus {
     name: string;
     state: McpServerState;
@@ -24,8 +25,13 @@ export interface McpManagerOptions {
     connectTimeoutMs?: number;
     /** Organization policy for the MCP allowlist. Unset = the managed policy file; null = none. */
     policy?: OrgPolicy | null;
+    /**
+     * OAuth sign-in for HTTP servers that want it. Without it such a server is simply "failed" (401). With it, saved
+     * tokens are used and a server without them is listed as "needs-auth" until {@link McpManager.signIn} runs.
+     */
+    oauth?: Omit<McpOAuthOptions, 'interactive'>;
     /** Test seam. */
-    connect?: (name: string, spec: McpServerSpec) => Promise<ConnectedMcpServer>;
+    connect?: (name: string, spec: McpServerSpec, options?: ConnectOptions) => Promise<ConnectedMcpServer>;
 }
 /** Replace `${workspaceFolder}` in args, env values, url and headers. */
 export declare function expandSpec(spec: McpServerSpec, cwd: string): McpServerSpec;
@@ -41,11 +47,18 @@ export declare class McpManager {
     ensureConnected(): Promise<void>;
     /** Tools from all connected servers (call {@link ensureConnected} first). */
     tools(): ToolDefinition[];
+    /** The servers that are connected right now (call {@link ensureConnected} first). */
+    servers(): readonly ConnectedMcpServer[];
     status(): McpServerStatus[];
     /** Drop connections and re-read the config files. */
+    private readonly specs;
+    /**
+     * Sign in to a server listed as `needs-auth`: opens the user's browser, waits for them to finish (up to the sign-in
+     * timeout), saves the tokens, then reconnects everything so the server's tools appear.
+     */
+    signIn(name: string): Promise<void>;
     reload(): Promise<void>;
     dispose(): Promise<void>;
     private readScope;
     private load;
 }
-//# sourceMappingURL=manager.d.ts.map

package/dist/mcp/manager.js

@@ -5,7 +5,7 @@
  * reported in `status()` instead of only written to stderr.
  */
 import path from 'node:path';
-import { closeAll, connectOne } from './mcp-client.js';
+import { McpAuthRequiredError, closeAll, connectOne } from './mcp-client.js';
 import { loadMcpConfig } from './mcp-config.js';
 import { defaultUserMcpPath } from './marketplace.js';
 import { filterMcpServers, getOrgPolicy } from '../policy/policy.js';
@@ -50,10 +50,32 @@ export class McpManager {
     tools() {
         return this.connected.flatMap((s) => s.tools);
     }
+    /** The servers that are connected right now (call {@link ensureConnected} first). */
+    servers() {
+        return this.connected;
+    }
     status() {
         return [...this.statuses];
     }
     /** Drop connections and re-read the config files. */
+    specs = new Map();
+    /**
+     * Sign in to a server listed as `needs-auth`: opens the user's browser, waits for them to finish (up to the sign-in
+     * timeout), saves the tokens, then reconnects everything so the server's tools appear.
+     */
+    async signIn(name) {
+        const oauth = this.options.oauth;
+        const spec = this.specs.get(name);
+        if (!oauth)
+            throw new Error('sign-in is not available here');
+        if (!spec)
+            throw new Error(`no MCP server named "${name}"`);
+        const connect = this.options.connect ?? connectOne;
+        const wait = oauth.signInTimeoutMs ?? 5 * 60_000;
+        const server = await withTimeout(connect(name, expandSpec(spec, this.options.cwd), { oauth: { ...oauth, interactive: true } }), wait + (this.options.connectTimeoutMs ?? 30_000), `Signing in to MCP server "${name}"`);
+        await closeAll([server]);
+        await this.reload();
+    }
     async reload() {
         await this.dispose();
         await this.ensureConnected();
@@ -110,10 +132,13 @@ export class McpManager {
             if (spec.disabled)
                 return { status: { name, state: 'disabled', scope, toolCount: 0 } };
             try {
-                const server = await withTimeout(connect(name, expandSpec(spec, cwd)), timeoutMs, `MCP server "${name}"`);
+                this.specs.set(name, spec);
+                const server = await withTimeout(connect(name, expandSpec(spec, cwd), this.options.oauth ? { oauth: { ...this.options.oauth, interactive: false } } : undefined), timeoutMs, `MCP server "${name}"`);
                 return { server, status: { name, state: 'connected', scope, toolCount: server.tools.length } };
             }
             catch (err) {
+                if (err instanceof McpAuthRequiredError)
+                    return { status: { name, state: 'needs-auth', scope, toolCount: 0, error: err.message } };
                 return { status: { name, state: 'failed', scope, toolCount: 0, error: err.message } };
             }
         }));
@@ -121,4 +146,3 @@ export class McpManager {
         this.statuses = [...statuses, ...results.map((r) => r.status)];
     }
 }
-//# sourceMappingURL=manager.js.map

package/dist/mcp/marketplace-types.d.ts

@@ -80,4 +80,3 @@ export interface InstalledServerMetadata {
     installedAt: string;
     displayName?: string;
 }
-//# sourceMappingURL=marketplace-types.d.ts.map

package/dist/mcp/marketplace-types.js

@@ -10,4 +10,3 @@
  */
 /** Version of the catalog JSON format. Bumped on backwards-incompatible changes. */
 export const MARKETPLACE_CATALOG_VERSION = 1;
-//# sourceMappingURL=marketplace-types.js.map

package/dist/mcp/marketplace.d.ts

@@ -55,6 +55,8 @@ export declare function installDirNameFor(source: {
  * server" message instead of silently registering nothing.
  */
 export declare function probeRepoForServer(repoPath: string, subdir?: string): Promise<McpServerSpec>;
+/** `--` ends git's option parsing: a source that starts with `-` (`--upload-pack=…`) must never be read as an option. */
+export declare function gitCloneArgs(url: string, target: string): string[];
 /**
  * Install an MCP server from a catalog entry or a raw GitHub URL.
  * Returns the {@link InstalledMcpServer} describing what was installed.
@@ -95,4 +97,3 @@ export declare function listInstalledServers(params?: {
     cacheRoot?: string;
     userMcpPath?: string;
 }): Promise<InstalledMcpServer[]>;
-//# sourceMappingURL=marketplace.d.ts.map

package/dist/mcp/marketplace.js

@@ -27,6 +27,8 @@ import { homedir } from 'node:os';
 import path from 'node:path';
 import { promisify } from 'node:util';
 import { parseMcpConfig } from './mcp-config.js';
+import { isOutsideRel } from '../tools/shared.js';
+import { updateJsonFile } from '../config-file.js';
 const execFileP = promisify(execFile);
 /** Path to the cache root (caller-controlled so tests can inject a temp dir). */
 export function defaultCacheRoot() {
@@ -152,10 +154,14 @@ export async function probeRepoForServer(repoPath, subdir) {
 }
 /** Side-effect: clone the source into the cache dir. */
 async function gitClone(url, target) {
-    await execFileP('git', ['clone', '--depth', '1', '--quiet', url, target], {
+    await execFileP('git', gitCloneArgs(url, target), {
         windowsHide: true,
     });
 }
+/** `--` ends git's option parsing: a source that starts with `-` (`--upload-pack=…`) must never be read as an option. */
+export function gitCloneArgs(url, target) {
+    return ['clone', '--depth', '1', '--quiet', '--', url, target];
+}
 /**
  * Install an MCP server from a catalog entry or a raw GitHub URL.
  * Returns the {@link InstalledMcpServer} describing what was installed.
@@ -197,7 +203,7 @@ export async function installMcpServer(params) {
     // consequences of a bypass (arbitrary recursive delete) are severe.
     const installPath = path.join(cacheRoot, name);
     const relInstall = path.relative(cacheRoot, installPath);
-    if (relInstall.startsWith('..') || path.isAbsolute(relInstall)) {
+    if (isOutsideRel(relInstall)) {
         throw new Error(`Refusing to install "${name}": resolved path escapes the cache root.`);
     }
     if (existsSync(installPath)) {
@@ -260,8 +266,8 @@ export async function readUserMcpRegistry(userMcpPath) {
 }
 /** Write the user's MCP registry, creating parent directories as needed. */
 export async function writeUserMcpRegistry(userMcpPath, config) {
-    await mkdir(path.dirname(userMcpPath), { recursive: true });
-    await writeFile(userMcpPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+    // Atomic, and one writer at a time (see updateJsonFile).
+    await updateJsonFile(userMcpPath, () => config);
 }
 /** Remove an installed MCP server by name. Idempotent: succeeds even when absent. */
 export async function uninstallMcpServer(params) {
@@ -319,4 +325,3 @@ export async function listInstalledServers(params) {
     }
     return out;
 }
-//# sourceMappingURL=marketplace.js.map

package/dist/mcp/mcp-client.d.ts

@@ -1,4 +1,5 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { type McpOAuthOptions } from './oauth.js';
 import type { McpConfigFile, McpServerSpec } from './mcp-config.js';
 import type { ToolDefinition } from '../types.js';
 /**
@@ -9,11 +10,20 @@ export interface ConnectedMcpServer {
     name: string;
     client: Client;
     tools: ToolDefinition[];
+    /** What the server says about using it (from `initialize`); shown to the model next to its tools. */
+    instructions?: string | undefined;
 }
 /** Connect to every server in a parsed MCP config. Failed connections are skipped with a warning. */
-export declare function connectAll(config: McpConfigFile): Promise<ConnectedMcpServer[]>;
+export declare function connectAll(config: McpConfigFile, options?: ConnectOptions): Promise<ConnectedMcpServer[]>;
+export { McpAuthRequiredError } from './oauth.js';
+export interface ConnectOptions {
+    /** Let an HTTP server that wants OAuth sign-in use saved tokens, and (with `interactive`) ask the user to sign in. */
+    oauth?: McpOAuthOptions;
+}
 /** Connect to a single server and pull its tools. */
-export declare function connectOne(name: string, spec: McpServerSpec): Promise<ConnectedMcpServer>;
+export declare function connectOne(name: string, spec: McpServerSpec, options?: ConnectOptions): Promise<ConnectedMcpServer>;
+/** The instructions servers sent with `initialize`, as one prompt block (empty when none sent any). */
+export declare function mcpInstructionsBlock(servers: readonly ConnectedMcpServer[]): string;
 /** Close all clients and their underlying transports. */
 export declare function closeAll(servers: ConnectedMcpServer[]): Promise<void>;
 /**
@@ -24,4 +34,3 @@ export declare function closeAll(servers: ConnectedMcpServer[]): Promise<void>;
  * single string and keep the structured content for any embedded resources.
  */
 export declare function mcpResultToValue(result: unknown): unknown;
-//# sourceMappingURL=mcp-client.d.ts.map

package/dist/mcp/mcp-client.js

@@ -24,12 +24,14 @@
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { UnauthorizedError } from '@modelcontextprotocol/sdk/client/auth.js';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 import { filterMcpServers, getOrgPolicy } from '../policy/policy.js';
 import { jsonSchemaToZod } from './json-schema-to-zod.js';
+import { ForgeOAuthProvider, McpAuthRequiredError, defaultMcpAuthDir, readSavedAuth } from './oauth.js';
 /**
  * Self-identifying info we send to every MCP server during the `initialize`
  * handshake. Version is read from our own package.json so it stays in sync
@@ -53,7 +55,7 @@ function readPackageVersion() {
     }
 }
 /** Connect to every server in a parsed MCP config. Failed connections are skipped with a warning. */
-export async function connectAll(config) {
+export async function connectAll(config, options = {}) {
     const { allowed, blocked } = filterMcpServers(config.mcpServers, getOrgPolicy()?.policy);
     for (const name of blocked) {
         process.stderr.write(`forge: MCP server "${name}" is blocked by organization policy
@@ -65,10 +67,14 @@ export async function connectAll(config) {
         if (spec.disabled)
             continue;
         try {
-            const server = await connectOne(name, spec);
+            const server = await connectOne(name, spec, options);
             results.push(server);
         }
         catch (err) {
+            if (err instanceof McpAuthRequiredError) {
+                process.stderr.write(`forge: MCP server "${name}" needs you to sign in. Run: forge mcp login ${name}\n`);
+                continue;
+            }
             // Skip failed servers so one bad entry doesn't take down the whole
             // session; surface the error so the caller can log it.
             process.stderr.write(`forge: MCP server "${name}" failed to connect: ${err.message}\n`);
@@ -76,21 +82,68 @@ export async function connectAll(config) {
     }
     return results;
 }
+export { McpAuthRequiredError } from './oauth.js';
+/** A 401 from a server we connected to without credentials. */
+function isUnauthorized(err) {
+    const e = err;
+    return err instanceof UnauthorizedError || e?.code === 401 || (typeof e?.message === 'string' && /\b401\b/.test(e.message));
+}
 /** Connect to a single server and pull its tools. */
-export async function connectOne(name, spec) {
-    const transport = buildTransport(spec);
-    const client = new Client(CLIENT_INFO, { capabilities: {} });
-    await client.connect(transport);
-    const { tools: mcpTools } = await client.listTools();
-    const tools = mcpTools.map((t) => mcpToolToForgeTool(name, t, client));
-    return { name, client, tools };
+export async function connectOne(name, spec, options = {}) {
+    const timeout = spec.timeout ? { timeout: spec.timeout } : undefined;
+    let client = new Client(CLIENT_INFO, { capabilities: {} });
+    const oauth = options.oauth;
+    // A static Authorization header is the user's own choice of credentials: leave OAuth out of it.
+    const hasStaticAuth = Object.keys(spec.headers ?? {}).some((h) => h.toLowerCase() === 'authorization');
+    const wantsOAuth = Boolean(oauth && spec.url && !spec.command && !hasStaticAuth);
+    if (!wantsOAuth) {
+        await client.connect(buildTransport(spec), timeout);
+    }
+    else {
+        const url = spec.url;
+        const haveTokens = Boolean((await readSavedAuth(oauth.storeDir ?? defaultMcpAuthDir(), url))?.tokens);
+        let provider;
+        if (haveTokens || oauth.interactive) {
+            provider = await ForgeOAuthProvider.create(name, url, oauth);
+        }
+        let transport = buildTransport(spec, provider);
+        try {
+            await client.connect(transport, timeout);
+        }
+        catch (err) {
+            if (!provider) {
+                // Tried without credentials and the server refused: it needs a sign-in the user has not done yet.
+                if (isUnauthorized(err))
+                    throw new McpAuthRequiredError(name);
+                throw err;
+            }
+            if (!(err instanceof UnauthorizedError))
+                throw err;
+            // The SDK started the sign-in (the browser is open); wait for the user, then connect again with the tokens.
+            try {
+                const code = await provider.waitForCode();
+                await transport.finishAuth(code);
+            }
+            catch (signInErr) {
+                provider.cancel();
+                throw signInErr;
+            }
+            await client.close().catch(() => undefined);
+            client = new Client(CLIENT_INFO, { capabilities: {} });
+            transport = buildTransport(spec, provider);
+            await client.connect(transport, timeout);
+        }
+    }
+    const { tools: mcpTools } = await client.listTools(undefined, spec.timeout ? { timeout: spec.timeout } : undefined);
+    const tools = mcpTools.map((t) => mcpToolToForgeTool(name, t, client, spec.timeout));
+    return { name, client, tools, instructions: client.getInstructions()?.trim() || undefined };
 }
 /**
  * Pick the right SDK transport for the server spec. The transport type is
  * either explicit (`type: 'sse'` etc.) or inferred from the shape of the
  * spec: `command` present ⇒ stdio, `url` present ⇒ SSE.
  */
-function buildTransport(spec) {
+function buildTransport(spec, authProvider) {
     const explicit = spec.type;
     const isStdio = explicit === 'stdio' || (!explicit && Boolean(spec.command));
     const isSse = explicit === 'sse' || (!explicit && Boolean(spec.url) && !explicit);
@@ -118,10 +171,17 @@ function buildTransport(spec) {
     const headers = spec.headers ?? {};
     const requestInit = headers ? { headers } : {};
     if (explicit === 'streamable-http') {
-        return new StreamableHTTPClientTransport(new URL(spec.url), { requestInit });
+        return new StreamableHTTPClientTransport(new URL(spec.url), { requestInit, ...(authProvider ? { authProvider } : {}) });
     }
     // Default for HTTP-transport specs: SSE (preserves prior behavior).
-    return new SSEClientTransport(new URL(spec.url), { requestInit });
+    return new SSEClientTransport(new URL(spec.url), { requestInit, ...(authProvider ? { authProvider } : {}) });
+}
+/** The instructions servers sent with `initialize`, as one prompt block (empty when none sent any). */
+export function mcpInstructionsBlock(servers) {
+    return servers
+        .filter((s) => s.instructions)
+        .map((s) => `<mcp-server-instructions server="${s.name.replace(/"/g, '')}">\n${s.instructions}\n</mcp-server-instructions>`)
+        .join('\n\n');
 }
 /** Close all clients and their underlying transports. */
 export async function closeAll(servers) {
@@ -133,7 +193,7 @@ export async function closeAll(servers) {
  * namespace of the built-in tools and tells the model which server a tool
  * came from at a glance.
  */
-function mcpToolToForgeTool(serverName, mcpTool, client) {
+function mcpToolToForgeTool(serverName, mcpTool, client, timeout) {
     const fullName = `mcp__${serverName}__${mcpTool.name}`;
     const description = [
         mcpTool.description ?? '',
@@ -150,10 +210,7 @@ function mcpToolToForgeTool(serverName, mcpTool, client) {
         // destructive so the user gets a confirmation prompt unless --auto.
         destructive: true,
         execute: async (args) => {
-            const result = await client.callTool({
-                name: mcpTool.name,
-                arguments: args,
-            });
+            const result = await client.callTool({ name: mcpTool.name, arguments: args }, undefined, timeout ? { timeout } : undefined);
             return mcpResultToValue(result);
         },
     };
@@ -185,4 +242,3 @@ export function mcpResultToValue(result) {
     }
     return { text, content: r.content, isError: r.isError };
 }
-//# sourceMappingURL=mcp-client.js.map

package/dist/mcp/mcp-config.d.ts

@@ -45,6 +45,8 @@ export interface McpServerSpec {
     headers?: Record<string, string>;
     /** Keep the entry but do not connect it. */
     disabled?: boolean;
+    /** Milliseconds to wait for a connection or a tool call before giving up (default: the SDK's 60 s). */
+    timeout?: number;
 }
 /**
  * Load and validate a `forge.mcp.json` file. Throws if the file is missing,
@@ -56,4 +58,3 @@ export declare function loadMcpConfig(configPath: string): Promise<McpConfigFile
  * that already have the file contents (e.g. embedded configs).
  */
 export declare function parseMcpConfig(raw: string, sourcePath?: string): McpConfigFile;
-//# sourceMappingURL=mcp-config.d.ts.map

package/dist/mcp/mcp-config.js

@@ -9,6 +9,7 @@ const serverSchema = z
     url: z.string().optional(),
     headers: z.record(z.string(), z.string()).optional(),
     disabled: z.boolean().optional(),
+    timeout: z.number().int().positive().max(3_600_000).optional(),
 })
     .refine((s) => Boolean(s.command) || Boolean(s.url), {
     message: 'Each MCP server must have either `command` (stdio) or `url` (sse/streamable-http).',
@@ -60,4 +61,3 @@ export function parseMcpConfig(raw, sourcePath = '<inline>') {
     }
     return result.data;
 }
-//# sourceMappingURL=mcp-config.js.map

package/dist/mcp/oauth.d.ts

@@ -0,0 +1,55 @@
+import type { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
+import type { OAuthClientInformationMixed, OAuthClientMetadata, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
+export interface McpOAuthOptions {
+    /** Defaults to `~/.forge/mcp-auth`. */
+    storeDir?: string;
+    /** Show the authorization page to the user (their browser). Throw to refuse. */
+    openUrl: (url: string) => void | Promise<void>;
+    /** True: may open the browser and wait for the user. False: only use tokens already saved. */
+    interactive?: boolean;
+    /** How long to wait for the user to finish in the browser. Default five minutes. */
+    signInTimeoutMs?: number;
+}
+/** The server needs the user to sign in, and this connection was not allowed to ask. */
+export declare class McpAuthRequiredError extends Error {
+    readonly server: string;
+    constructor(server: string);
+}
+interface SavedAuth {
+    url: string;
+    port?: number;
+    clientInformation?: OAuthClientInformationMixed;
+    tokens?: OAuthTokens;
+}
+export declare function defaultMcpAuthDir(): string;
+export declare function readSavedAuth(dir: string, serverUrl: string): Promise<SavedAuth | undefined>;
+export declare function forgetSavedAuth(dir: string, serverUrl: string): Promise<void>;
+export declare class ForgeOAuthProvider implements OAuthClientProvider {
+    readonly serverName: string;
+    private readonly serverUrl;
+    private readonly dir;
+    private readonly port;
+    private readonly options;
+    private verifier;
+    private expectedState;
+    private receiver;
+    private constructor();
+    static create(serverName: string, serverUrl: string, options: McpOAuthOptions): Promise<ForgeOAuthProvider>;
+    get redirectUrl(): string;
+    get clientMetadata(): OAuthClientMetadata;
+    state(): string;
+    private saved;
+    clientInformation(): Promise<OAuthClientInformationMixed | undefined>;
+    saveClientInformation(info: OAuthClientInformationMixed): Promise<void>;
+    tokens(): Promise<OAuthTokens | undefined>;
+    saveTokens(tokens: OAuthTokens): Promise<void>;
+    saveCodeVerifier(v: string): void;
+    codeVerifier(): string;
+    invalidateCredentials(scope: 'all' | 'client' | 'tokens' | 'verifier' | 'discovery'): Promise<void>;
+    /** Called by the SDK once it has the authorization URL. Without `interactive` this is where the connection stops. */
+    redirectToAuthorization(url: URL): Promise<void>;
+    /** After the SDK reported the sign-in as started: the code the browser brings back. */
+    waitForCode(): Promise<string>;
+    cancel(): void;
+}
+export {};

package/dist/mcp/oauth.js

@@ -0,0 +1,197 @@
+/**
+ * OAuth sign-in for MCP servers behind it (authorization code with PKCE, dynamic client registration).
+ * The SDK does the protocol; this file supplies what it leaves to the application: where tokens are kept,
+ * where the browser returns to (a one-shot page on 127.0.0.1), and a state value that must come back unchanged.
+ *
+ * Tokens live in `~/.forge/mcp-auth/<server>.json`, readable by the user only, one file per server URL.
+ * Signing in is always the user's act: a server that needs it is reported as such, and the browser opens only
+ * when `interactive` is set. A URL that is not http or https is never opened.
+ */
+import { randomBytes, createHash } from 'node:crypto';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import http from 'node:http';
+import { homedir } from 'node:os';
+import path from 'node:path';
+/** The server needs the user to sign in, and this connection was not allowed to ask. */
+export class McpAuthRequiredError extends Error {
+    server;
+    constructor(server) {
+        super(`MCP server "${server}" needs you to sign in`);
+        this.server = server;
+        this.name = 'McpAuthRequiredError';
+    }
+}
+export function defaultMcpAuthDir() {
+    return path.join(homedir(), '.forge', 'mcp-auth');
+}
+function fileFor(dir, serverUrl) {
+    return path.join(dir, `${createHash('sha256').update(serverUrl).digest('hex').slice(0, 32)}.json`);
+}
+export async function readSavedAuth(dir, serverUrl) {
+    try {
+        return JSON.parse(await readFile(fileFor(dir, serverUrl), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeSavedAuth(dir, auth) {
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await writeFile(fileFor(dir, auth.url), JSON.stringify(auth, null, 2), { encoding: 'utf8', mode: 0o600 });
+}
+export async function forgetSavedAuth(dir, serverUrl) {
+    await rm(fileFor(dir, serverUrl), { force: true });
+}
+/** A port on 127.0.0.1: the one used last time if it is free (so a registered redirect URL keeps working), else any. */
+async function freePort(preferred) {
+    const tryListen = (port) => new Promise((resolve) => {
+        const s = http.createServer();
+        s.once('error', () => resolve(undefined));
+        s.listen(port, '127.0.0.1', () => {
+            const got = s.address().port;
+            s.close(() => resolve(got));
+        });
+    });
+    return (preferred ? await tryListen(preferred) : undefined) ?? (await tryListen(0)) ?? 0;
+}
+/** A one-shot page the browser returns to. Resolves with the code; a wrong `state` is ignored, an `error` rejects. */
+async function receiveCode(port, expectedState, timeoutMs) {
+    let resolveCode;
+    let rejectCode;
+    const code = new Promise((resolve, reject) => {
+        resolveCode = resolve;
+        rejectCode = reject;
+    });
+    const page = (title) => `<!doctype html><meta charset="utf-8"><title>${title}</title><body style="font-family:sans-serif;margin:3em"><h2>${title}</h2><p>You can close this tab and go back to your editor.</p>`;
+    const server = http.createServer((req, res) => {
+        const url = new URL(req.url ?? '/', `http://127.0.0.1:${port}`);
+        if (url.pathname !== '/callback') {
+            res.writeHead(404).end();
+            return;
+        }
+        if (url.searchParams.get('state') !== expectedState) {
+            res.writeHead(400, { 'content-type': 'text/html' }).end(page('This sign-in link is not for this session'));
+            return;
+        }
+        const error = url.searchParams.get('error');
+        const got = url.searchParams.get('code');
+        if (error || !got) {
+            res.writeHead(400, { 'content-type': 'text/html' }).end(page('Sign-in was not completed'));
+            rejectCode(new Error(`sign-in failed: ${error ?? 'no code returned'}`));
+            return;
+        }
+        res.writeHead(200, { 'content-type': 'text/html' }).end(page('Signed in to Forge'));
+        resolveCode(got);
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, '127.0.0.1', resolve);
+    });
+    const timer = setTimeout(() => rejectCode(new Error('sign-in timed out')), timeoutMs);
+    const close = () => {
+        clearTimeout(timer);
+        server.closeAllConnections();
+        server.close();
+    };
+    code.then(close, close);
+    return { code, close };
+}
+export class ForgeOAuthProvider {
+    serverName;
+    serverUrl;
+    dir;
+    port;
+    options;
+    verifier = '';
+    expectedState = '';
+    receiver;
+    constructor(serverName, serverUrl, dir, port, options) {
+        this.serverName = serverName;
+        this.serverUrl = serverUrl;
+        this.dir = dir;
+        this.port = port;
+        this.options = options;
+    }
+    static async create(serverName, serverUrl, options) {
+        const dir = options.storeDir ?? defaultMcpAuthDir();
+        const saved = await readSavedAuth(dir, serverUrl);
+        const port = await freePort(saved?.port);
+        await writeSavedAuth(dir, { ...(saved ?? { url: serverUrl }), url: serverUrl, port });
+        return new ForgeOAuthProvider(serverName, serverUrl, dir, port, options);
+    }
+    get redirectUrl() {
+        return `http://127.0.0.1:${this.port}/callback`;
+    }
+    get clientMetadata() {
+        return {
+            client_name: 'Ikarmic Forge',
+            redirect_uris: [this.redirectUrl],
+            grant_types: ['authorization_code', 'refresh_token'],
+            response_types: ['code'],
+            token_endpoint_auth_method: 'none',
+        };
+    }
+    state() {
+        this.expectedState = randomBytes(16).toString('hex');
+        return this.expectedState;
+    }
+    async saved() {
+        return (await readSavedAuth(this.dir, this.serverUrl)) ?? { url: this.serverUrl };
+    }
+    async clientInformation() {
+        const info = (await this.saved()).clientInformation;
+        // A registration made for another redirect URL cannot be used here: register again.
+        if (info?.redirect_uris && !info.redirect_uris.includes(this.redirectUrl))
+            return undefined;
+        return info;
+    }
+    async saveClientInformation(info) {
+        await writeSavedAuth(this.dir, { ...(await this.saved()), clientInformation: info });
+    }
+    async tokens() {
+        return (await this.saved()).tokens;
+    }
+    async saveTokens(tokens) {
+        await writeSavedAuth(this.dir, { ...(await this.saved()), tokens });
+    }
+    saveCodeVerifier(v) {
+        this.verifier = v;
+    }
+    codeVerifier() {
+        return this.verifier;
+    }
+    async invalidateCredentials(scope) {
+        const s = await this.saved();
+        if (scope === 'all' || scope === 'tokens')
+            delete s.tokens;
+        if (scope === 'all' || scope === 'client')
+            delete s.clientInformation;
+        await writeSavedAuth(this.dir, s);
+    }
+    /** Called by the SDK once it has the authorization URL. Without `interactive` this is where the connection stops. */
+    async redirectToAuthorization(url) {
+        if (!this.options.interactive)
+            throw new McpAuthRequiredError(this.serverName);
+        if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+            throw new Error(`MCP server "${this.serverName}" gave a sign-in address that is not a web page (${url.protocol}); refused`);
+        }
+        this.receiver?.close();
+        this.receiver = await receiveCode(this.port, this.expectedState, this.options.signInTimeoutMs ?? 5 * 60_000);
+        await this.options.openUrl(url.href);
+    }
+    /** After the SDK reported the sign-in as started: the code the browser brings back. */
+    async waitForCode() {
+        if (!this.receiver)
+            throw new Error('no sign-in is waiting');
+        try {
+            return await this.receiver.code;
+        }
+        finally {
+            this.receiver = undefined;
+        }
+    }
+    cancel() {
+        this.receiver?.close();
+        this.receiver = undefined;
+    }
+}