apex-code 0.0.1-alpha.8 → 0.0.4

package/dist/core/mcp/metadata-cache.js

@@ -0,0 +1,99 @@
+/**
+ * Persistent MCP tool metadata, so search and describe answer without a running
+ * server. Everything the cache holds is producible from a past connection, which is
+ * what makes "no server needed to search" a property rather than a convention.
+ *
+ * One file for every server, not one per server: the whole cache is read once at
+ * session start and written whole, and a handful of servers never makes that costly.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "../../config.js";
+const EMPTY = { version: 1, servers: {} };
+const SEPARATOR = "|";
+export function mcpCachePath() {
+    return join(getAgentDir(), "mcp", "metadata.json");
+}
+/**
+ * Everything that can change which tools a server publishes, and nothing that cannot.
+ * A version bump in `args` produces a new key and therefore reads no stale entries,
+ * while `capabilities` or `idleTimeoutMinutes` leave the key alone.
+ */
+function transportIdentity(transport) {
+    if (transport.kind === "stdio") {
+        // Env values, not just keys: a server that switches which token or mode it runs
+        // under can publish a different tool list under the same command line.
+        const env = Object.entries(transport.env)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, value]) => `${key}=${value}`)
+            .join(",");
+        return ["stdio", transport.command, transport.args.join(" "), env, transport.cwd ?? ""].join(SEPARATOR);
+    }
+    const headers = Object.entries(transport.headers)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, value]) => `${key}=${value}`)
+        .join(",");
+    return ["http", transport.url, headers, transport.bearerTokenEnv ?? ""].join(SEPARATOR);
+}
+/**
+ * The name is part of the key, not only the launch spec. Two servers can share a
+ * command (the same binary run twice under different names) and would otherwise
+ * collide, the second silently overwriting the first's cached tools.
+ */
+export function serverCacheKey(server) {
+    const identity = [server.name, transportIdentity(server.transport)].join(SEPARATOR);
+    return createHash("sha256").update(identity).digest("hex").slice(0, 32);
+}
+export class McpMetadataCache {
+    file;
+    path;
+    constructor(path = mcpCachePath()) {
+        this.path = path;
+        this.file = McpMetadataCache.read(path);
+    }
+    static read(path) {
+        if (!existsSync(path))
+            return structuredClone(EMPTY);
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf-8"));
+            if (parsed?.version !== 1 || typeof parsed.servers !== "object" || parsed.servers === null) {
+                return structuredClone(EMPTY);
+            }
+            return parsed;
+        }
+        catch {
+            return structuredClone(EMPTY);
+        }
+    }
+    get(server) {
+        return this.file.servers[serverCacheKey(server)]?.tools ?? [];
+    }
+    all() {
+        return Object.values(this.file.servers).flatMap((entry) => entry.tools);
+    }
+    set(server, tools) {
+        this.file.servers[serverCacheKey(server)] = { name: server.name, tools: [...tools] };
+    }
+    /** Forget every server absent from `configured`, so a removed server stops appearing in search. */
+    prune(configured) {
+        const live = new Set(configured.map(serverCacheKey));
+        for (const key of Object.keys(this.file.servers)) {
+            if (!live.has(key))
+                delete this.file.servers[key];
+        }
+    }
+    save() {
+        const directory = dirname(this.path);
+        mkdirSync(directory, { recursive: true });
+        const temporary = join(directory, `.metadata.${process.pid}.tmp`);
+        try {
+            writeFileSync(temporary, JSON.stringify(this.file));
+            renameSync(temporary, this.path);
+        }
+        catch {
+            rmSync(temporary, { force: true });
+        }
+    }
+}
+//# sourceMappingURL=metadata-cache.js.map

package/dist/core/mcp/metadata-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-cache.js","sourceRoot":"","sources":["../../../src/core/mcp/metadata-cache.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Persistent MCP tool metadata, so search and describe answer without a running\n * server. Everything the cache holds is producible from a past connection, which is\n * what makes \"no server needed to search\" a property rather than a convention.\n *\n * One file for every server, not one per server: the whole cache is read once at\n * session start and written whole, and a handful of servers never makes that costly.\n */\n\nimport { createHash } from \"node:crypto\";\nimport { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport { getAgentDir } from \"../../config.ts\";\nimport type { CachedTool, McpServerConfig, McpTransport } from \"./types.ts\";\n\ninterface CacheFile {\n\tversion: 1;\n\tservers: Record<string, { name: string; tools: CachedTool[] }>;\n}\n\nconst EMPTY: CacheFile = { version: 1, servers: {} };\n\nconst SEPARATOR = \"|\";\n\nexport function mcpCachePath(): string {\n\treturn join(getAgentDir(), \"mcp\", \"metadata.json\");\n}\n\n/**\n * Everything that can change which tools a server publishes, and nothing that cannot.\n * A version bump in `args` produces a new key and therefore reads no stale entries,\n * while `capabilities` or `idleTimeoutMinutes` leave the key alone.\n */\nfunction transportIdentity(transport: McpTransport): string {\n\tif (transport.kind === \"stdio\") {\n\t\t// Env values, not just keys: a server that switches which token or mode it runs\n\t\t// under can publish a different tool list under the same command line.\n\t\tconst env = Object.entries(transport.env)\n\t\t\t.sort(([a], [b]) => a.localeCompare(b))\n\t\t\t.map(([key, value]) => `${key}=${value}`)\n\t\t\t.join(\",\");\n\t\treturn [\"stdio\", transport.command, transport.args.join(\" \"), env, transport.cwd ?? \"\"].join(SEPARATOR);\n\t}\n\tconst headers = Object.entries(transport.headers)\n\t\t.sort(([a], [b]) => a.localeCompare(b))\n\t\t.map(([key, value]) => `${key}=${value}`)\n\t\t.join(\",\");\n\treturn [\"http\", transport.url, headers, transport.bearerTokenEnv ?? \"\"].join(SEPARATOR);\n}\n\n/**\n * The name is part of the key, not only the launch spec. Two servers can share a\n * command (the same binary run twice under different names) and would otherwise\n * collide, the second silently overwriting the first's cached tools.\n */\nexport function serverCacheKey(server: McpServerConfig): string {\n\tconst identity = [server.name, transportIdentity(server.transport)].join(SEPARATOR);\n\treturn createHash(\"sha256\").update(identity).digest(\"hex\").slice(0, 32);\n}\n\nexport class McpMetadataCache {\n\tprivate file: CacheFile;\n\tprivate readonly path: string;\n\n\tconstructor(path: string = mcpCachePath()) {\n\t\tthis.path = path;\n\t\tthis.file = McpMetadataCache.read(path);\n\t}\n\n\tprivate static read(path: string): CacheFile {\n\t\tif (!existsSync(path)) return structuredClone(EMPTY);\n\t\ttry {\n\t\t\tconst parsed = JSON.parse(readFileSync(path, \"utf-8\")) as CacheFile;\n\t\t\tif (parsed?.version !== 1 || typeof parsed.servers !== \"object\" || parsed.servers === null) {\n\t\t\t\treturn structuredClone(EMPTY);\n\t\t\t}\n\t\t\treturn parsed;\n\t\t} catch {\n\t\t\treturn structuredClone(EMPTY);\n\t\t}\n\t}\n\n\tget(server: McpServerConfig): CachedTool[] {\n\t\treturn this.file.servers[serverCacheKey(server)]?.tools ?? [];\n\t}\n\n\tall(): CachedTool[] {\n\t\treturn Object.values(this.file.servers).flatMap((entry) => entry.tools);\n\t}\n\n\tset(server: McpServerConfig, tools: readonly CachedTool[]): void {\n\t\tthis.file.servers[serverCacheKey(server)] = { name: server.name, tools: [...tools] };\n\t}\n\n\t/** Forget every server absent from `configured`, so a removed server stops appearing in search. */\n\tprune(configured: readonly McpServerConfig[]): void {\n\t\tconst live = new Set(configured.map(serverCacheKey));\n\t\tfor (const key of Object.keys(this.file.servers)) {\n\t\t\tif (!live.has(key)) delete this.file.servers[key];\n\t\t}\n\t}\n\n\tsave(): void {\n\t\tconst directory = dirname(this.path);\n\t\tmkdirSync(directory, { recursive: true });\n\t\tconst temporary = join(directory, `.metadata.${process.pid}.tmp`);\n\t\ttry {\n\t\t\twriteFileSync(temporary, JSON.stringify(this.file));\n\t\t\trenameSync(temporary, this.path);\n\t\t} catch {\n\t\t\trmSync(temporary, { force: true });\n\t\t}\n\t}\n}\n"]}

package/dist/core/mcp/oauth/authorize.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared entry point for `apex-code mcp auth <server>` and the TUI `/mcp auth`
+ * command. Resolves the named server from the merged MCP config, checks it is an
+ * OAuth-configured HTTP server, and runs the flow. UI-agnostic: callers supply the
+ * line printer and the browser opener.
+ */
+import type { CredentialStore } from "@earendil-works/pi-ai";
+import { runMcpOAuthFlow } from "./flow.ts";
+export interface AuthorizeServerOptions {
+    serverName: string;
+    /** Project root for `.mcp.json` discovery. Default: process.cwd(). */
+    cwd?: string;
+    /** Credential sink. Default: the host store (`AuthStorage.create()`). */
+    credentials?: CredentialStore;
+    openBrowser?: (url: string) => void;
+    /** Injectable flow, for tests. */
+    flow?: typeof runMcpOAuthFlow;
+    log: (line: string) => void;
+}
+export declare function authorizeConfiguredServer(options: AuthorizeServerOptions): Promise<void>;
+//# sourceMappingURL=authorize.d.ts.map

package/dist/core/mcp/oauth/authorize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorize.d.ts","sourceRoot":"","sources":["../../../../src/core/mcp/oauth/authorize.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAG7D,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,MAAM,WAAW,sBAAsB;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,kCAAkC;IAClC,IAAI,CAAC,EAAE,OAAO,eAAe,CAAC;IAC9B,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5B;AAED,wBAAsB,yBAAyB,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0B9F","sourcesContent":["/**\n * Shared entry point for `apex-code mcp auth <server>` and the TUI `/mcp auth`\n * command. Resolves the named server from the merged MCP config, checks it is an\n * OAuth-configured HTTP server, and runs the flow. UI-agnostic: callers supply the\n * line printer and the browser opener.\n */\n\nimport { join } from \"node:path\";\nimport type { CredentialStore } from \"@earendil-works/pi-ai\";\nimport { AuthStorage } from \"../../auth-storage.ts\";\nimport { loadMcpConfig, PROJECT_CONFIG_FILENAME } from \"../config.ts\";\nimport { runMcpOAuthFlow } from \"./flow.ts\";\n\nexport interface AuthorizeServerOptions {\n\tserverName: string;\n\t/** Project root for `.mcp.json` discovery. Default: process.cwd(). */\n\tcwd?: string;\n\t/** Credential sink. Default: the host store (`AuthStorage.create()`). */\n\tcredentials?: CredentialStore;\n\topenBrowser?: (url: string) => void;\n\t/** Injectable flow, for tests. */\n\tflow?: typeof runMcpOAuthFlow;\n\tlog: (line: string) => void;\n}\n\nexport async function authorizeConfiguredServer(options: AuthorizeServerOptions): Promise<void> {\n\tconst { servers } = loadMcpConfig({ projectPath: join(options.cwd ?? process.cwd(), PROJECT_CONFIG_FILENAME) });\n\tconst server = servers.get(options.serverName);\n\tif (!server) {\n\t\tconst names = [...servers.keys()];\n\t\tthrow new Error(\n\t\t\t`MCP server \"${options.serverName}\" is not configured. Configured servers: ${names.join(\", \") || \"none\"}. Add it to .mcp.json first.`,\n\t\t);\n\t}\n\tif (server.transport.kind !== \"http\") {\n\t\tthrow new Error(`MCP server \"${options.serverName}\" is a stdio server; OAuth applies to HTTP servers only.`);\n\t}\n\tif (server.auth !== \"oauth\") {\n\t\tthrow new Error(\n\t\t\t`MCP server \"${options.serverName}\" is not configured for OAuth. Add \"auth\": \"oauth\" to its entry.`,\n\t\t);\n\t}\n\tconst result = await (options.flow ?? runMcpOAuthFlow)({\n\t\tserverName: options.serverName,\n\t\tserverUrl: server.transport.url,\n\t\tcredentials: options.credentials ?? AuthStorage.create(),\n\t\tdeps: { print: options.log, openBrowser: options.openBrowser ?? (() => {}) },\n\t});\n\toptions.log(\n\t\t`Authorized \"${options.serverName}\". Token stored; expires ${new Date(result.expiresAt).toISOString()}.`,\n\t);\n}\n"]}

package/dist/core/mcp/oauth/authorize.js

@@ -0,0 +1,32 @@
+/**
+ * Shared entry point for `apex-code mcp auth <server>` and the TUI `/mcp auth`
+ * command. Resolves the named server from the merged MCP config, checks it is an
+ * OAuth-configured HTTP server, and runs the flow. UI-agnostic: callers supply the
+ * line printer and the browser opener.
+ */
+import { join } from "node:path";
+import { AuthStorage } from "../../auth-storage.js";
+import { loadMcpConfig, PROJECT_CONFIG_FILENAME } from "../config.js";
+import { runMcpOAuthFlow } from "./flow.js";
+export async function authorizeConfiguredServer(options) {
+    const { servers } = loadMcpConfig({ projectPath: join(options.cwd ?? process.cwd(), PROJECT_CONFIG_FILENAME) });
+    const server = servers.get(options.serverName);
+    if (!server) {
+        const names = [...servers.keys()];
+        throw new Error(`MCP server "${options.serverName}" is not configured. Configured servers: ${names.join(", ") || "none"}. Add it to .mcp.json first.`);
+    }
+    if (server.transport.kind !== "http") {
+        throw new Error(`MCP server "${options.serverName}" is a stdio server; OAuth applies to HTTP servers only.`);
+    }
+    if (server.auth !== "oauth") {
+        throw new Error(`MCP server "${options.serverName}" is not configured for OAuth. Add "auth": "oauth" to its entry.`);
+    }
+    const result = await (options.flow ?? runMcpOAuthFlow)({
+        serverName: options.serverName,
+        serverUrl: server.transport.url,
+        credentials: options.credentials ?? AuthStorage.create(),
+        deps: { print: options.log, openBrowser: options.openBrowser ?? (() => { }) },
+    });
+    options.log(`Authorized "${options.serverName}". Token stored; expires ${new Date(result.expiresAt).toISOString()}.`);
+}
+//# sourceMappingURL=authorize.js.map

package/dist/core/mcp/oauth/authorize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorize.js","sourceRoot":"","sources":["../../../../src/core/mcp/oauth/authorize.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAc5C,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,OAA+B,EAAiB;IAC/F,MAAM,EAAE,OAAO,EAAE,GAAG,aAAa,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE,uBAAuB,CAAC,EAAE,CAAC,CAAC;IAChH,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/C,IAAI,CAAC,MAAM,EAAE,CAAC;QACb,MAAM,KAAK,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QAClC,MAAM,IAAI,KAAK,CACd,eAAe,OAAO,CAAC,UAAU,4CAA4C,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,8BAA8B,CACrI,CAAC;IACH,CAAC;IACD,IAAI,MAAM,CAAC,SAAS,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,eAAe,OAAO,CAAC,UAAU,0DAA0D,CAAC,CAAC;IAC9G,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACd,eAAe,OAAO,CAAC,UAAU,kEAAkE,CACnG,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,eAAe,CAAC,CAAC;QACtD,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,GAAG;QAC/B,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,WAAW,CAAC,MAAM,EAAE;QACxD,IAAI,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,CAAC,GAAG,EAAE,CAAC,EAAC,CAAC,CAAC,EAAE;KAC5E,CAAC,CAAC;IACH,OAAO,CAAC,GAAG,CACV,eAAe,OAAO,CAAC,UAAU,4BAA4B,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,GAAG,CACxG,CAAC;AAAA,CACF","sourcesContent":["/**\n * Shared entry point for `apex-code mcp auth <server>` and the TUI `/mcp auth`\n * command. Resolves the named server from the merged MCP config, checks it is an\n * OAuth-configured HTTP server, and runs the flow. UI-agnostic: callers supply the\n * line printer and the browser opener.\n */\n\nimport { join } from \"node:path\";\nimport type { CredentialStore } from \"@earendil-works/pi-ai\";\nimport { AuthStorage } from \"../../auth-storage.ts\";\nimport { loadMcpConfig, PROJECT_CONFIG_FILENAME } from \"../config.ts\";\nimport { runMcpOAuthFlow } from \"./flow.ts\";\n\nexport interface AuthorizeServerOptions {\n\tserverName: string;\n\t/** Project root for `.mcp.json` discovery. Default: process.cwd(). */\n\tcwd?: string;\n\t/** Credential sink. Default: the host store (`AuthStorage.create()`). */\n\tcredentials?: CredentialStore;\n\topenBrowser?: (url: string) => void;\n\t/** Injectable flow, for tests. */\n\tflow?: typeof runMcpOAuthFlow;\n\tlog: (line: string) => void;\n}\n\nexport async function authorizeConfiguredServer(options: AuthorizeServerOptions): Promise<void> {\n\tconst { servers } = loadMcpConfig({ projectPath: join(options.cwd ?? process.cwd(), PROJECT_CONFIG_FILENAME) });\n\tconst server = servers.get(options.serverName);\n\tif (!server) {\n\t\tconst names = [...servers.keys()];\n\t\tthrow new Error(\n\t\t\t`MCP server \"${options.serverName}\" is not configured. Configured servers: ${names.join(\", \") || \"none\"}. Add it to .mcp.json first.`,\n\t\t);\n\t}\n\tif (server.transport.kind !== \"http\") {\n\t\tthrow new Error(`MCP server \"${options.serverName}\" is a stdio server; OAuth applies to HTTP servers only.`);\n\t}\n\tif (server.auth !== \"oauth\") {\n\t\tthrow new Error(\n\t\t\t`MCP server \"${options.serverName}\" is not configured for OAuth. Add \"auth\": \"oauth\" to its entry.`,\n\t\t);\n\t}\n\tconst result = await (options.flow ?? runMcpOAuthFlow)({\n\t\tserverName: options.serverName,\n\t\tserverUrl: server.transport.url,\n\t\tcredentials: options.credentials ?? AuthStorage.create(),\n\t\tdeps: { print: options.log, openBrowser: options.openBrowser ?? (() => {}) },\n\t});\n\toptions.log(\n\t\t`Authorized \"${options.serverName}\". Token stored; expires ${new Date(result.expiresAt).toISOString()}.`,\n\t);\n}\n"]}

package/dist/core/mcp/oauth/discover.d.ts

@@ -0,0 +1,27 @@
+/**
+ * OAuth discovery for MCP servers: the `WWW-Authenticate` challenge, protected-resource
+ * metadata (RFC 9728), and authorization-server metadata (RFC 8414), in the order the
+ * MCP authorization spec expects.
+ *
+ * Metadata URLs must be https. The one exception is loopback, because the authorization
+ * code flow itself speaks loopback http and local development servers ride on it.
+ */
+export type FetchLike = typeof fetch;
+export declare class OAuthDiscoveryError extends Error {
+}
+export interface AuthorizationServerMetadata {
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    registrationEndpoint: string | undefined;
+}
+export declare function oauthErrorMessage(error: unknown): string;
+/** Pulls `resource_metadata` out of a `WWW-Authenticate: Bearer …` challenge, if present. */
+export declare function parseWwwAuthenticate(value: string | undefined): {
+    resourceMetadata?: string;
+};
+export declare function discoverAuthorizationServer(options: {
+    serverUrl: string;
+    wwwAuthenticate?: string;
+    fetch?: FetchLike;
+}): Promise<AuthorizationServerMetadata>;
+//# sourceMappingURL=discover.d.ts.map

package/dist/core/mcp/oauth/discover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../../../src/core/mcp/oauth/discover.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,SAAS,GAAG,OAAO,KAAK,CAAC;AAErC,qBAAa,mBAAoB,SAAQ,KAAK;CAAG;AAEjD,MAAM,WAAW,2BAA2B;IAC3C,qBAAqB,EAAE,MAAM,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,oBAAoB,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC;AAKD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAExD;AAMD,+FAA6F;AAC7F,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG;IAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAE,CAM7F;AAkDD,wBAAsB,2BAA2B,CAAC,OAAO,EAAE;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,SAAS,CAAC;CAClB,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAsCvC","sourcesContent":["/**\n * OAuth discovery for MCP servers: the `WWW-Authenticate` challenge, protected-resource\n * metadata (RFC 9728), and authorization-server metadata (RFC 8414), in the order the\n * MCP authorization spec expects.\n *\n * Metadata URLs must be https. The one exception is loopback, because the authorization\n * code flow itself speaks loopback http and local development servers ride on it.\n */\n\nexport type FetchLike = typeof fetch;\n\nexport class OAuthDiscoveryError extends Error {}\n\nexport interface AuthorizationServerMetadata {\n\tauthorizationEndpoint: string;\n\ttokenEndpoint: string;\n\tregistrationEndpoint: string | undefined;\n}\n\nconst PRM_WELL_KNOWN = \".well-known/oauth-protected-resource\";\nconst AS_WELL_KNOWN = \".well-known/oauth-authorization-server\";\n\nexport function oauthErrorMessage(error: unknown): string {\n\treturn error instanceof Error ? error.message : String(error);\n}\n\nfunction isLoopback(url: URL): boolean {\n\treturn url.hostname === \"127.0.0.1\" || url.hostname === \"localhost\" || url.hostname === \"::1\";\n}\n\n/** Pulls `resource_metadata` out of a `WWW-Authenticate: Bearer …` challenge, if present. */\nexport function parseWwwAuthenticate(value: string | undefined): { resourceMetadata?: string } {\n\tif (!value) return {};\n\tconst challenge = /^Bearer\\s+(.*)$/i.exec(value.trim());\n\tif (!challenge) return {};\n\tconst resourceMetadata = /resource_metadata\\s*=\\s*\"([^\"]+)\"/i.exec(challenge[1])?.[1];\n\treturn resourceMetadata ? { resourceMetadata } : {};\n}\n\n/** RFC 9728: the well-known URI is inserted before the path, with the bare origin as fallback. */\nfunction wellKnownUrls(resource: URL, suffix: string): URL[] {\n\tconst pathAware = new URL(resource);\n\tpathAware.pathname = `/${suffix}${resource.pathname === \"/\" ? \"\" : resource.pathname}`;\n\tconst origin = new URL(resource);\n\torigin.pathname = `/${suffix}`;\n\treturn [pathAware, origin];\n}\n\nasync function fetchJson(url: URL, fetch: FetchLike): Promise<Record<string, unknown>> {\n\tif (url.protocol !== \"https:\" && !isLoopback(url)) {\n\t\tthrow new OAuthDiscoveryError(`OAuth metadata URLs must be https (loopback excepted): ${url}`);\n\t}\n\tlet response: Response;\n\ttry {\n\t\tresponse = await fetch(url, { redirect: \"error\" });\n\t} catch (error) {\n\t\tthrow new OAuthDiscoveryError(`could not fetch OAuth metadata from ${url}: ${oauthErrorMessage(error)}`);\n\t}\n\tif (!response.ok) throw new OAuthDiscoveryError(`OAuth metadata at ${url} answered HTTP ${response.status}`);\n\ttry {\n\t\tconst parsed: unknown = await response.json();\n\t\tif (typeof parsed !== \"object\" || parsed === null) throw new Error(\"not an object\");\n\t\treturn parsed as Record<string, unknown>;\n\t} catch {\n\t\tthrow new OAuthDiscoveryError(`OAuth metadata at ${url} is not a JSON object`);\n\t}\n}\n\nfunction requireEndpoint(metadata: Record<string, unknown>, key: string, label: string): string {\n\tconst value = metadata[key];\n\tif (typeof value !== \"string\" || value === \"\") {\n\t\tthrow new OAuthDiscoveryError(`authorization server metadata is missing ${label}`);\n\t}\n\treturn value;\n}\n\nfunction toAuthorizationServerMetadata(raw: Record<string, unknown>): AuthorizationServerMetadata {\n\treturn {\n\t\tauthorizationEndpoint: requireEndpoint(raw, \"authorization_endpoint\", \"an authorization endpoint\"),\n\t\ttokenEndpoint: requireEndpoint(raw, \"token_endpoint\", \"a token endpoint\"),\n\t\tregistrationEndpoint:\n\t\t\ttypeof raw.registration_endpoint === \"string\" && raw.registration_endpoint !== \"\"\n\t\t\t\t? raw.registration_endpoint\n\t\t\t\t: undefined,\n\t};\n}\n\nexport async function discoverAuthorizationServer(options: {\n\tserverUrl: string;\n\twwwAuthenticate?: string;\n\tfetch?: FetchLike;\n}): Promise<AuthorizationServerMetadata> {\n\tconst fetch = options.fetch ?? globalThis.fetch;\n\tconst serverUrl = new URL(options.serverUrl);\n\tif (serverUrl.protocol !== \"https:\" && !isLoopback(serverUrl)) {\n\t\tthrow new OAuthDiscoveryError(`an OAuth-protected MCP server must be https or loopback: ${options.serverUrl}`);\n\t}\n\n\tlet authorizationServers: URL[] = [];\n\tconst fromChallenge = parseWwwAuthenticate(options.wwwAuthenticate).resourceMetadata;\n\tconst prmCandidates = fromChallenge ? [new URL(fromChallenge)] : wellKnownUrls(serverUrl, PRM_WELL_KNOWN);\n\tfor (const candidate of prmCandidates) {\n\t\ttry {\n\t\t\tconst prm = await fetchJson(candidate, fetch);\n\t\t\tif (Array.isArray(prm.authorization_servers)) {\n\t\t\t\tauthorizationServers = prm.authorization_servers\n\t\t\t\t\t.filter((entry): entry is string => typeof entry === \"string\")\n\t\t\t\t\t.map((entry) => new URL(entry));\n\t\t\t\tbreak;\n\t\t\t}\n\t\t} catch (error) {\n\t\t\t// An explicit challenge URL is the server speaking; do not silently skip it.\n\t\t\tif (fromChallenge !== undefined && candidate.href === fromChallenge) throw error;\n\t\t}\n\t}\n\n\tconst asCandidates = authorizationServers.length > 0 ? authorizationServers : [serverUrl];\n\tlet lastError: unknown;\n\tfor (const candidate of asCandidates) {\n\t\ttry {\n\t\t\tconst wellKnown = new URL(`/${AS_WELL_KNOWN}`, candidate.origin);\n\t\t\treturn toAuthorizationServerMetadata(await fetchJson(wellKnown, fetch));\n\t\t} catch (error) {\n\t\t\tlastError = error;\n\t\t}\n\t}\n\tthrow lastError instanceof OAuthDiscoveryError\n\t\t? lastError\n\t\t: new OAuthDiscoveryError(`no authorization server metadata found for ${options.serverUrl}`);\n}\n"]}

package/dist/core/mcp/oauth/discover.js

@@ -0,0 +1,116 @@
+/**
+ * OAuth discovery for MCP servers: the `WWW-Authenticate` challenge, protected-resource
+ * metadata (RFC 9728), and authorization-server metadata (RFC 8414), in the order the
+ * MCP authorization spec expects.
+ *
+ * Metadata URLs must be https. The one exception is loopback, because the authorization
+ * code flow itself speaks loopback http and local development servers ride on it.
+ */
+export class OAuthDiscoveryError extends Error {
+}
+const PRM_WELL_KNOWN = ".well-known/oauth-protected-resource";
+const AS_WELL_KNOWN = ".well-known/oauth-authorization-server";
+export function oauthErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isLoopback(url) {
+    return url.hostname === "127.0.0.1" || url.hostname === "localhost" || url.hostname === "::1";
+}
+/** Pulls `resource_metadata` out of a `WWW-Authenticate: Bearer …` challenge, if present. */
+export function parseWwwAuthenticate(value) {
+    if (!value)
+        return {};
+    const challenge = /^Bearer\s+(.*)$/i.exec(value.trim());
+    if (!challenge)
+        return {};
+    const resourceMetadata = /resource_metadata\s*=\s*"([^"]+)"/i.exec(challenge[1])?.[1];
+    return resourceMetadata ? { resourceMetadata } : {};
+}
+/** RFC 9728: the well-known URI is inserted before the path, with the bare origin as fallback. */
+function wellKnownUrls(resource, suffix) {
+    const pathAware = new URL(resource);
+    pathAware.pathname = `/${suffix}${resource.pathname === "/" ? "" : resource.pathname}`;
+    const origin = new URL(resource);
+    origin.pathname = `/${suffix}`;
+    return [pathAware, origin];
+}
+async function fetchJson(url, fetch) {
+    if (url.protocol !== "https:" && !isLoopback(url)) {
+        throw new OAuthDiscoveryError(`OAuth metadata URLs must be https (loopback excepted): ${url}`);
+    }
+    let response;
+    try {
+        response = await fetch(url, { redirect: "error" });
+    }
+    catch (error) {
+        throw new OAuthDiscoveryError(`could not fetch OAuth metadata from ${url}: ${oauthErrorMessage(error)}`);
+    }
+    if (!response.ok)
+        throw new OAuthDiscoveryError(`OAuth metadata at ${url} answered HTTP ${response.status}`);
+    try {
+        const parsed = await response.json();
+        if (typeof parsed !== "object" || parsed === null)
+            throw new Error("not an object");
+        return parsed;
+    }
+    catch {
+        throw new OAuthDiscoveryError(`OAuth metadata at ${url} is not a JSON object`);
+    }
+}
+function requireEndpoint(metadata, key, label) {
+    const value = metadata[key];
+    if (typeof value !== "string" || value === "") {
+        throw new OAuthDiscoveryError(`authorization server metadata is missing ${label}`);
+    }
+    return value;
+}
+function toAuthorizationServerMetadata(raw) {
+    return {
+        authorizationEndpoint: requireEndpoint(raw, "authorization_endpoint", "an authorization endpoint"),
+        tokenEndpoint: requireEndpoint(raw, "token_endpoint", "a token endpoint"),
+        registrationEndpoint: typeof raw.registration_endpoint === "string" && raw.registration_endpoint !== ""
+            ? raw.registration_endpoint
+            : undefined,
+    };
+}
+export async function discoverAuthorizationServer(options) {
+    const fetch = options.fetch ?? globalThis.fetch;
+    const serverUrl = new URL(options.serverUrl);
+    if (serverUrl.protocol !== "https:" && !isLoopback(serverUrl)) {
+        throw new OAuthDiscoveryError(`an OAuth-protected MCP server must be https or loopback: ${options.serverUrl}`);
+    }
+    let authorizationServers = [];
+    const fromChallenge = parseWwwAuthenticate(options.wwwAuthenticate).resourceMetadata;
+    const prmCandidates = fromChallenge ? [new URL(fromChallenge)] : wellKnownUrls(serverUrl, PRM_WELL_KNOWN);
+    for (const candidate of prmCandidates) {
+        try {
+            const prm = await fetchJson(candidate, fetch);
+            if (Array.isArray(prm.authorization_servers)) {
+                authorizationServers = prm.authorization_servers
+                    .filter((entry) => typeof entry === "string")
+                    .map((entry) => new URL(entry));
+                break;
+            }
+        }
+        catch (error) {
+            // An explicit challenge URL is the server speaking; do not silently skip it.
+            if (fromChallenge !== undefined && candidate.href === fromChallenge)
+                throw error;
+        }
+    }
+    const asCandidates = authorizationServers.length > 0 ? authorizationServers : [serverUrl];
+    let lastError;
+    for (const candidate of asCandidates) {
+        try {
+            const wellKnown = new URL(`/${AS_WELL_KNOWN}`, candidate.origin);
+            return toAuthorizationServerMetadata(await fetchJson(wellKnown, fetch));
+        }
+        catch (error) {
+            lastError = error;
+        }
+    }
+    throw lastError instanceof OAuthDiscoveryError
+        ? lastError
+        : new OAuthDiscoveryError(`no authorization server metadata found for ${options.serverUrl}`);
+}
+//# sourceMappingURL=discover.js.map

package/dist/core/mcp/oauth/discover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.js","sourceRoot":"","sources":["../../../../src/core/mcp/oauth/discover.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * OAuth discovery for MCP servers: the `WWW-Authenticate` challenge, protected-resource\n * metadata (RFC 9728), and authorization-server metadata (RFC 8414), in the order the\n * MCP authorization spec expects.\n *\n * Metadata URLs must be https. The one exception is loopback, because the authorization\n * code flow itself speaks loopback http and local development servers ride on it.\n */\n\nexport type FetchLike = typeof fetch;\n\nexport class OAuthDiscoveryError extends Error {}\n\nexport interface AuthorizationServerMetadata {\n\tauthorizationEndpoint: string;\n\ttokenEndpoint: string;\n\tregistrationEndpoint: string | undefined;\n}\n\nconst PRM_WELL_KNOWN = \".well-known/oauth-protected-resource\";\nconst AS_WELL_KNOWN = \".well-known/oauth-authorization-server\";\n\nexport function oauthErrorMessage(error: unknown): string {\n\treturn error instanceof Error ? error.message : String(error);\n}\n\nfunction isLoopback(url: URL): boolean {\n\treturn url.hostname === \"127.0.0.1\" || url.hostname === \"localhost\" || url.hostname === \"::1\";\n}\n\n/** Pulls `resource_metadata` out of a `WWW-Authenticate: Bearer …` challenge, if present. */\nexport function parseWwwAuthenticate(value: string | undefined): { resourceMetadata?: string } {\n\tif (!value) return {};\n\tconst challenge = /^Bearer\\s+(.*)$/i.exec(value.trim());\n\tif (!challenge) return {};\n\tconst resourceMetadata = /resource_metadata\\s*=\\s*\"([^\"]+)\"/i.exec(challenge[1])?.[1];\n\treturn resourceMetadata ? { resourceMetadata } : {};\n}\n\n/** RFC 9728: the well-known URI is inserted before the path, with the bare origin as fallback. */\nfunction wellKnownUrls(resource: URL, suffix: string): URL[] {\n\tconst pathAware = new URL(resource);\n\tpathAware.pathname = `/${suffix}${resource.pathname === \"/\" ? \"\" : resource.pathname}`;\n\tconst origin = new URL(resource);\n\torigin.pathname = `/${suffix}`;\n\treturn [pathAware, origin];\n}\n\nasync function fetchJson(url: URL, fetch: FetchLike): Promise<Record<string, unknown>> {\n\tif (url.protocol !== \"https:\" && !isLoopback(url)) {\n\t\tthrow new OAuthDiscoveryError(`OAuth metadata URLs must be https (loopback excepted): ${url}`);\n\t}\n\tlet response: Response;\n\ttry {\n\t\tresponse = await fetch(url, { redirect: \"error\" });\n\t} catch (error) {\n\t\tthrow new OAuthDiscoveryError(`could not fetch OAuth metadata from ${url}: ${oauthErrorMessage(error)}`);\n\t}\n\tif (!response.ok) throw new OAuthDiscoveryError(`OAuth metadata at ${url} answered HTTP ${response.status}`);\n\ttry {\n\t\tconst parsed: unknown = await response.json();\n\t\tif (typeof parsed !== \"object\" || parsed === null) throw new Error(\"not an object\");\n\t\treturn parsed as Record<string, unknown>;\n\t} catch {\n\t\tthrow new OAuthDiscoveryError(`OAuth metadata at ${url} is not a JSON object`);\n\t}\n}\n\nfunction requireEndpoint(metadata: Record<string, unknown>, key: string, label: string): string {\n\tconst value = metadata[key];\n\tif (typeof value !== \"string\" || value === \"\") {\n\t\tthrow new OAuthDiscoveryError(`authorization server metadata is missing ${label}`);\n\t}\n\treturn value;\n}\n\nfunction toAuthorizationServerMetadata(raw: Record<string, unknown>): AuthorizationServerMetadata {\n\treturn {\n\t\tauthorizationEndpoint: requireEndpoint(raw, \"authorization_endpoint\", \"an authorization endpoint\"),\n\t\ttokenEndpoint: requireEndpoint(raw, \"token_endpoint\", \"a token endpoint\"),\n\t\tregistrationEndpoint:\n\t\t\ttypeof raw.registration_endpoint === \"string\" && raw.registration_endpoint !== \"\"\n\t\t\t\t? raw.registration_endpoint\n\t\t\t\t: undefined,\n\t};\n}\n\nexport async function discoverAuthorizationServer(options: {\n\tserverUrl: string;\n\twwwAuthenticate?: string;\n\tfetch?: FetchLike;\n}): Promise<AuthorizationServerMetadata> {\n\tconst fetch = options.fetch ?? globalThis.fetch;\n\tconst serverUrl = new URL(options.serverUrl);\n\tif (serverUrl.protocol !== \"https:\" && !isLoopback(serverUrl)) {\n\t\tthrow new OAuthDiscoveryError(`an OAuth-protected MCP server must be https or loopback: ${options.serverUrl}`);\n\t}\n\n\tlet authorizationServers: URL[] = [];\n\tconst fromChallenge = parseWwwAuthenticate(options.wwwAuthenticate).resourceMetadata;\n\tconst prmCandidates = fromChallenge ? [new URL(fromChallenge)] : wellKnownUrls(serverUrl, PRM_WELL_KNOWN);\n\tfor (const candidate of prmCandidates) {\n\t\ttry {\n\t\t\tconst prm = await fetchJson(candidate, fetch);\n\t\t\tif (Array.isArray(prm.authorization_servers)) {\n\t\t\t\tauthorizationServers = prm.authorization_servers\n\t\t\t\t\t.filter((entry): entry is string => typeof entry === \"string\")\n\t\t\t\t\t.map((entry) => new URL(entry));\n\t\t\t\tbreak;\n\t\t\t}\n\t\t} catch (error) {\n\t\t\t// An explicit challenge URL is the server speaking; do not silently skip it.\n\t\t\tif (fromChallenge !== undefined && candidate.href === fromChallenge) throw error;\n\t\t}\n\t}\n\n\tconst asCandidates = authorizationServers.length > 0 ? authorizationServers : [serverUrl];\n\tlet lastError: unknown;\n\tfor (const candidate of asCandidates) {\n\t\ttry {\n\t\t\tconst wellKnown = new URL(`/${AS_WELL_KNOWN}`, candidate.origin);\n\t\t\treturn toAuthorizationServerMetadata(await fetchJson(wellKnown, fetch));\n\t\t} catch (error) {\n\t\t\tlastError = error;\n\t\t}\n\t}\n\tthrow lastError instanceof OAuthDiscoveryError\n\t\t? lastError\n\t\t: new OAuthDiscoveryError(`no authorization server metadata found for ${options.serverUrl}`);\n}\n"]}

package/dist/core/mcp/oauth/flow.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The user-initiated OAuth authorization flow for one MCP server: authorization-code
+ * with PKCE against a loopback callback listener that exists only for the duration of
+ * the flow. Per ADR 0023's posture, nothing here is reachable from a tool call — the
+ * command is the only entry point.
+ */
+import type { CredentialStore } from "@earendil-works/pi-ai";
+import { type FetchLike } from "./discover.ts";
+export declare class OAuthFlowError extends Error {
+}
+export interface McpOAuthFlowDeps {
+    print: (line: string) => void;
+    openBrowser: (url: string) => void;
+    fetch: FetchLike;
+    now: () => number;
+    timeoutMs: number;
+}
+export interface McpOAuthFlowOptions {
+    serverName: string;
+    serverUrl: string;
+    credentials: CredentialStore;
+    /** A manually registered client id; skips dynamic registration when present. */
+    clientId?: string;
+    clientSecret?: string;
+    deps?: Partial<McpOAuthFlowDeps>;
+}
+export interface McpOAuthFlowResult {
+    expiresAt: number;
+}
+export declare function runMcpOAuthFlow(options: McpOAuthFlowOptions): Promise<McpOAuthFlowResult>;
+//# sourceMappingURL=flow.d.ts.map

package/dist/core/mcp/oauth/flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.d.ts","sourceRoot":"","sources":["../../../../src/core/mcp/oauth/flow.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAc,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAA+B,KAAK,SAAS,EAA0C,MAAM,eAAe,CAAC;AAMpH,qBAAa,cAAe,SAAQ,KAAK;CAAG;AAE5C,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,KAAK,EAAE,SAAS,CAAC;IACjB,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CAClB;AAOD,MAAM,WAAW,mBAAmB;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,eAAe,CAAC;IAC7B,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,kBAAkB;IAClC,SAAS,EAAE,MAAM,CAAC;CAClB;AAuED,wBAAsB,eAAe,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA+F/F","sourcesContent":["/**\n * The user-initiated OAuth authorization flow for one MCP server: authorization-code\n * with PKCE against a loopback callback listener that exists only for the duration of\n * the flow. Per ADR 0023's posture, nothing here is reachable from a tool call — the\n * command is the only entry point.\n */\n\nimport { randomBytes } from \"node:crypto\";\nimport { createServer, type IncomingMessage, type Server, type ServerResponse } from \"node:http\";\nimport type { Credential, CredentialStore } from \"@earendil-works/pi-ai\";\nimport { discoverAuthorizationServer, type FetchLike, OAuthDiscoveryError, oauthErrorMessage } from \"./discover.ts\";\nimport { mcpCredentialKey } from \"./mcp-token.ts\";\nimport { createPkcePair } from \"./pkce.ts\";\nimport { registerClient } from \"./register.ts\";\nimport { exchangeAuthorizationCode, TokenEndpointError } from \"./token-client.ts\";\n\nexport class OAuthFlowError extends Error {}\n\nexport interface McpOAuthFlowDeps {\n\tprint: (line: string) => void;\n\topenBrowser: (url: string) => void;\n\tfetch: FetchLike;\n\tnow: () => number;\n\ttimeoutMs: number;\n}\n\nconst DEFAULT_TIMEOUT_MS = 5 * 60_000;\n/** Store the token as expiring a minute early, so in-flight calls never ride it to death. */\nconst EXPIRY_SKEW_MS = 60_000;\nconst CALLBACK_PATH = \"/callback\";\n\nexport interface McpOAuthFlowOptions {\n\tserverName: string;\n\tserverUrl: string;\n\tcredentials: CredentialStore;\n\t/** A manually registered client id; skips dynamic registration when present. */\n\tclientId?: string;\n\tclientSecret?: string;\n\tdeps?: Partial<McpOAuthFlowDeps>;\n}\n\nexport interface McpOAuthFlowResult {\n\texpiresAt: number;\n}\n\n/**\n * Accepts exactly one callback carrying the issued `state`, then stops. A request with\n * the wrong state is answered 400 and the listener stays available for the real one;\n * after the right one, the socket is closed before the flow proceeds to the exchange.\n */\nclass LoopbackCallback {\n\treadonly state = randomBytes(16).toString(\"base64url\");\n\tredirectUri = \"\";\n\tprivate server: Server | undefined;\n\tprivate resolveCode: ((code: string) => void) | undefined;\n\n\tasync start(): Promise<void> {\n\t\tconst server = createServer((request, response) => this.handle(request, response));\n\t\tawait new Promise<void>((resolve) => server.listen(0, \"127.0.0.1\", resolve));\n\t\tconst address = server.address();\n\t\tif (address === null || typeof address === \"string\") {\n\t\t\tthrow new OAuthFlowError(\"could not bind the loopback callback listener\");\n\t\t}\n\t\tthis.server = server;\n\t\tthis.redirectUri = `http://127.0.0.1:${address.port}${CALLBACK_PATH}`;\n\t}\n\n\tprivate handle(request: IncomingMessage, response: ServerResponse): void {\n\t\tconst respond = (status: number, body: string) => {\n\t\t\tresponse.writeHead(status, { \"content-type\": \"text/plain\" });\n\t\t\tresponse.end(body);\n\t\t};\n\t\tconst port = this.server?.address();\n\t\tconst origin = `http://127.0.0.1:${port !== null && typeof port === \"object\" ? port.port : 0}`;\n\t\tconst url = new URL(String(request.url), origin);\n\t\tif (url.pathname !== CALLBACK_PATH) {\n\t\t\trespond(404, \"not found\");\n\t\t\treturn;\n\t\t}\n\t\tif (url.searchParams.get(\"state\") !== this.state) {\n\t\t\trespond(400, \"invalid state\");\n\t\t\treturn;\n\t\t}\n\t\tconst code = url.searchParams.get(\"code\");\n\t\tif (!code) {\n\t\t\trespond(400, \"missing code\");\n\t\t\treturn;\n\t\t}\n\t\trespond(200, \"Authorization complete. You can close this tab.\");\n\t\tconst resolve = this.resolveCode;\n\t\tthis.resolveCode = undefined;\n\t\tresolve?.(code);\n\t}\n\n\t/** Resolves with the authorization code, or rejects when the flow times out. */\n\tcode(timeoutMs: number): Promise<string> {\n\t\treturn new Promise<string>((resolve, reject) => {\n\t\t\tconst timer = setTimeout(() => {\n\t\t\t\treject(new OAuthFlowError(`timed out after ${timeoutMs} ms waiting for authorization to complete`));\n\t\t\t}, timeoutMs);\n\t\t\tthis.resolveCode = (code) => {\n\t\t\t\tclearTimeout(timer);\n\t\t\t\tresolve(code);\n\t\t\t};\n\t\t});\n\t}\n\n\tclose(): Promise<void> {\n\t\tconst server = this.server;\n\t\tif (!server) return Promise.resolve();\n\t\treturn new Promise((resolve) => server.close(() => resolve()));\n\t}\n}\n\nexport async function runMcpOAuthFlow(options: McpOAuthFlowOptions): Promise<McpOAuthFlowResult> {\n\tconst deps: McpOAuthFlowDeps = {\n\t\tprint: options.deps?.print ?? ((line: string) => console.log(line)),\n\t\topenBrowser: options.deps?.openBrowser ?? (() => {}),\n\t\tfetch: options.deps?.fetch ?? globalThis.fetch,\n\t\tnow: options.deps?.now ?? Date.now,\n\t\ttimeoutMs: options.deps?.timeoutMs ?? DEFAULT_TIMEOUT_MS,\n\t};\n\tconst callback = new LoopbackCallback();\n\ttry {\n\t\tawait callback.start();\n\n\t\tlet wwwAuthenticate: string | undefined;\n\t\ttry {\n\t\t\tconst probe = await deps.fetch(new URL(options.serverUrl), { redirect: \"error\" });\n\t\t\twwwAuthenticate = probe.headers.get(\"www-authenticate\") ?? undefined;\n\t\t} catch {\n\t\t\t// The probe is advisory; discovery falls back to well-known URIs.\n\t\t}\n\t\tconst metadata = await discoverAuthorizationServer({\n\t\t\tserverUrl: options.serverUrl,\n\t\t\twwwAuthenticate,\n\t\t\tfetch: deps.fetch,\n\t\t});\n\n\t\tlet clientId = options.clientId;\n\t\tif (!clientId) {\n\t\t\tif (!metadata.registrationEndpoint) {\n\t\t\t\tthrow new OAuthFlowError(\n\t\t\t\t\t`The authorization server for \"${options.serverName}\" supports no dynamic client registration, so this needs manual client registration: register a client with redirect URI ${callback.redirectUri} and pass its client id.`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst registered = await registerClient({\n\t\t\t\tregistrationEndpoint: new URL(metadata.registrationEndpoint),\n\t\t\t\tclientName: `Apex Code — MCP server \"${options.serverName}\"`,\n\t\t\t\tredirectUris: [callback.redirectUri],\n\t\t\t\tfetch: deps.fetch,\n\t\t\t});\n\t\t\tclientId = registered.clientId;\n\t\t}\n\n\t\tconst pkce = createPkcePair();\n\t\tconst authorizeUrl = new URL(metadata.authorizationEndpoint);\n\t\tauthorizeUrl.searchParams.set(\"response_type\", \"code\");\n\t\tauthorizeUrl.searchParams.set(\"client_id\", clientId);\n\t\tauthorizeUrl.searchParams.set(\"redirect_uri\", callback.redirectUri);\n\t\tauthorizeUrl.searchParams.set(\"code_challenge\", pkce.challenge);\n\t\tauthorizeUrl.searchParams.set(\"code_challenge_method\", \"S256\");\n\t\tauthorizeUrl.searchParams.set(\"state\", callback.state);\n\t\tauthorizeUrl.searchParams.set(\"resource\", options.serverUrl);\n\n\t\tdeps.print(`Authorize \"${options.serverName}\" by opening: ${authorizeUrl}`);\n\t\ttry {\n\t\t\tdeps.openBrowser(authorizeUrl.toString());\n\t\t} catch {\n\t\t\t// The URL is printed either way; opening a browser is best-effort.\n\t\t}\n\n\t\tconst code = await callback.code(deps.timeoutMs);\n\t\tconst token = await exchangeAuthorizationCode({\n\t\t\ttokenEndpoint: new URL(metadata.tokenEndpoint),\n\t\t\tcode,\n\t\t\tverifier: pkce.verifier,\n\t\t\tredirectUri: callback.redirectUri,\n\t\t\tclientId,\n\t\t\tclientSecret: options.clientSecret,\n\t\t\tresource: options.serverUrl,\n\t\t\tfetch: deps.fetch,\n\t\t});\n\n\t\tconst expiresAt = deps.now() + token.expiresInSeconds * 1000 - EXPIRY_SKEW_MS;\n\t\tconst credential: Credential = {\n\t\t\ttype: \"oauth\",\n\t\t\taccess: token.accessToken,\n\t\t\t// An absent rotation keeps the refresh token the server still honors.\n\t\t\trefresh: token.refreshToken ?? \"\",\n\t\t\texpires: expiresAt,\n\t\t\ttokenEndpoint: metadata.tokenEndpoint,\n\t\t\tresource: options.serverUrl,\n\t\t\tclientId,\n\t\t};\n\t\tawait options.credentials.modify(mcpCredentialKey(options.serverName), async () => credential);\n\t\treturn { expiresAt };\n\t} catch (error) {\n\t\tif (\n\t\t\terror instanceof OAuthFlowError ||\n\t\t\terror instanceof OAuthDiscoveryError ||\n\t\t\terror instanceof TokenEndpointError\n\t\t) {\n\t\t\tthrow error;\n\t\t}\n\t\tthrow new OAuthFlowError(`OAuth flow for \"${options.serverName}\" failed: ${oauthErrorMessage(error)}`);\n\t} finally {\n\t\tawait callback.close();\n\t}\n}\n"]}

package/dist/core/mcp/oauth/flow.js

@@ -0,0 +1,175 @@
+/**
+ * The user-initiated OAuth authorization flow for one MCP server: authorization-code
+ * with PKCE against a loopback callback listener that exists only for the duration of
+ * the flow. Per ADR 0023's posture, nothing here is reachable from a tool call — the
+ * command is the only entry point.
+ */
+import { randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { discoverAuthorizationServer, OAuthDiscoveryError, oauthErrorMessage } from "./discover.js";
+import { mcpCredentialKey } from "./mcp-token.js";
+import { createPkcePair } from "./pkce.js";
+import { registerClient } from "./register.js";
+import { exchangeAuthorizationCode, TokenEndpointError } from "./token-client.js";
+export class OAuthFlowError extends Error {
+}
+const DEFAULT_TIMEOUT_MS = 5 * 60_000;
+/** Store the token as expiring a minute early, so in-flight calls never ride it to death. */
+const EXPIRY_SKEW_MS = 60_000;
+const CALLBACK_PATH = "/callback";
+/**
+ * Accepts exactly one callback carrying the issued `state`, then stops. A request with
+ * the wrong state is answered 400 and the listener stays available for the real one;
+ * after the right one, the socket is closed before the flow proceeds to the exchange.
+ */
+class LoopbackCallback {
+    state = randomBytes(16).toString("base64url");
+    redirectUri = "";
+    server;
+    resolveCode;
+    async start() {
+        const server = createServer((request, response) => this.handle(request, response));
+        await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+        const address = server.address();
+        if (address === null || typeof address === "string") {
+            throw new OAuthFlowError("could not bind the loopback callback listener");
+        }
+        this.server = server;
+        this.redirectUri = `http://127.0.0.1:${address.port}${CALLBACK_PATH}`;
+    }
+    handle(request, response) {
+        const respond = (status, body) => {
+            response.writeHead(status, { "content-type": "text/plain" });
+            response.end(body);
+        };
+        const port = this.server?.address();
+        const origin = `http://127.0.0.1:${port !== null && typeof port === "object" ? port.port : 0}`;
+        const url = new URL(String(request.url), origin);
+        if (url.pathname !== CALLBACK_PATH) {
+            respond(404, "not found");
+            return;
+        }
+        if (url.searchParams.get("state") !== this.state) {
+            respond(400, "invalid state");
+            return;
+        }
+        const code = url.searchParams.get("code");
+        if (!code) {
+            respond(400, "missing code");
+            return;
+        }
+        respond(200, "Authorization complete. You can close this tab.");
+        const resolve = this.resolveCode;
+        this.resolveCode = undefined;
+        resolve?.(code);
+    }
+    /** Resolves with the authorization code, or rejects when the flow times out. */
+    code(timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new OAuthFlowError(`timed out after ${timeoutMs} ms waiting for authorization to complete`));
+            }, timeoutMs);
+            this.resolveCode = (code) => {
+                clearTimeout(timer);
+                resolve(code);
+            };
+        });
+    }
+    close() {
+        const server = this.server;
+        if (!server)
+            return Promise.resolve();
+        return new Promise((resolve) => server.close(() => resolve()));
+    }
+}
+export async function runMcpOAuthFlow(options) {
+    const deps = {
+        print: options.deps?.print ?? ((line) => console.log(line)),
+        openBrowser: options.deps?.openBrowser ?? (() => { }),
+        fetch: options.deps?.fetch ?? globalThis.fetch,
+        now: options.deps?.now ?? Date.now,
+        timeoutMs: options.deps?.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    };
+    const callback = new LoopbackCallback();
+    try {
+        await callback.start();
+        let wwwAuthenticate;
+        try {
+            const probe = await deps.fetch(new URL(options.serverUrl), { redirect: "error" });
+            wwwAuthenticate = probe.headers.get("www-authenticate") ?? undefined;
+        }
+        catch {
+            // The probe is advisory; discovery falls back to well-known URIs.
+        }
+        const metadata = await discoverAuthorizationServer({
+            serverUrl: options.serverUrl,
+            wwwAuthenticate,
+            fetch: deps.fetch,
+        });
+        let clientId = options.clientId;
+        if (!clientId) {
+            if (!metadata.registrationEndpoint) {
+                throw new OAuthFlowError(`The authorization server for "${options.serverName}" supports no dynamic client registration, so this needs manual client registration: register a client with redirect URI ${callback.redirectUri} and pass its client id.`);
+            }
+            const registered = await registerClient({
+                registrationEndpoint: new URL(metadata.registrationEndpoint),
+                clientName: `Apex Code — MCP server "${options.serverName}"`,
+                redirectUris: [callback.redirectUri],
+                fetch: deps.fetch,
+            });
+            clientId = registered.clientId;
+        }
+        const pkce = createPkcePair();
+        const authorizeUrl = new URL(metadata.authorizationEndpoint);
+        authorizeUrl.searchParams.set("response_type", "code");
+        authorizeUrl.searchParams.set("client_id", clientId);
+        authorizeUrl.searchParams.set("redirect_uri", callback.redirectUri);
+        authorizeUrl.searchParams.set("code_challenge", pkce.challenge);
+        authorizeUrl.searchParams.set("code_challenge_method", "S256");
+        authorizeUrl.searchParams.set("state", callback.state);
+        authorizeUrl.searchParams.set("resource", options.serverUrl);
+        deps.print(`Authorize "${options.serverName}" by opening: ${authorizeUrl}`);
+        try {
+            deps.openBrowser(authorizeUrl.toString());
+        }
+        catch {
+            // The URL is printed either way; opening a browser is best-effort.
+        }
+        const code = await callback.code(deps.timeoutMs);
+        const token = await exchangeAuthorizationCode({
+            tokenEndpoint: new URL(metadata.tokenEndpoint),
+            code,
+            verifier: pkce.verifier,
+            redirectUri: callback.redirectUri,
+            clientId,
+            clientSecret: options.clientSecret,
+            resource: options.serverUrl,
+            fetch: deps.fetch,
+        });
+        const expiresAt = deps.now() + token.expiresInSeconds * 1000 - EXPIRY_SKEW_MS;
+        const credential = {
+            type: "oauth",
+            access: token.accessToken,
+            // An absent rotation keeps the refresh token the server still honors.
+            refresh: token.refreshToken ?? "",
+            expires: expiresAt,
+            tokenEndpoint: metadata.tokenEndpoint,
+            resource: options.serverUrl,
+            clientId,
+        };
+        await options.credentials.modify(mcpCredentialKey(options.serverName), async () => credential);
+        return { expiresAt };
+    }
+    catch (error) {
+        if (error instanceof OAuthFlowError ||
+            error instanceof OAuthDiscoveryError ||
+            error instanceof TokenEndpointError) {
+            throw error;
+        }
+        throw new OAuthFlowError(`OAuth flow for "${options.serverName}" failed: ${oauthErrorMessage(error)}`);
+    }
+    finally {
+        await callback.close();
+    }
+}
+//# sourceMappingURL=flow.js.map