@aiwerk/mcp-bridge 2.5.2 → 2.6.0

package/README.md

@@ -400,7 +400,7 @@ OAuth2 features: automatic token acquisition, caching with expiry-aware refresh,
 
 **OAuth2 Authorization Code + PKCE** (interactive browser login):
 
-For MCP servers behind enterprise SSO or user-level OAuth2 that require browser-based login:
+For MCP servers behind enterprise SSO or user-level OAuth2 that require browser-based login (desktop/laptop):
 
 ```json
 {
@@ -429,6 +429,40 @@ Features:
 - **Automatic refresh** — tokens refreshed transparently via `refresh_token` grant
 - **Actionable errors** — expired tokens return error with exact CLI command to re-authenticate
 
+**OAuth2 Device Code** (headless environments — VPS, Docker, SSH, CI):
+
+For environments without a browser. You authenticate on a separate device using a short code:
+
+```json
+{
+  "auth": {
+    "type": "oauth2",
+    "grantType": "device_code",
+    "deviceAuthorizationUrl": "https://github.com/login/device/code",
+    "tokenUrl": "https://github.com/login/oauth/access_token",
+    "clientId": "your-app-id",
+    "scopes": ["repo", "read:org"]
+  }
+}
+```
+
+```bash
+mcp-bridge auth login my-server
+# ──────────────────────────────────────────
+#  Device authentication for "my-server"
+#
+#  1. Open: https://github.com/login/device
+#  2. Enter code: ABCD-1234
+# ──────────────────────────────────────────
+# Waiting for authorization...
+```
+
+Features:
+- **RFC 8628 compliant** — works with GitHub, Google, Microsoft, Auth0, Okta
+- **No local browser needed** — authenticate from phone/laptop, token received on server
+- **Automatic polling** — respects `interval` and `slow_down` responses
+- **Same token persistence** — stored in `~/.mcp-bridge/tokens/` with auto-refresh
+
 ### Environment variables
 
 Secrets go in `~/.mcp-bridge/.env` (chmod 600 on init):
@@ -556,7 +590,7 @@ For production deployments with high security requirements, consider adding an e
 | ✅ | Configurable retries + graceful shutdown | 2.0.0 |
 | ✅ | OAuth2 Client Credentials | 2.1.0 |
 | ✅ | OAuth2 Authorization Code + PKCE | 2.5.0 |
-| 🔜 | OAuth2 Device Code flow (headless) | planned |
+| ✅ | OAuth2 Device Code flow (headless) | 2.6.0 |
 | 🔜 | Hosted bridge (bridge.aiwerk.ch) | planned |
 | 🔜 | Remote catalog integration | planned |
 | 🔜 | OpenTelemetry / Prometheus metrics | planned |

package/dist/bin/mcp-bridge.js

@@ -8,6 +8,8 @@ import { loadConfig, initConfigDir } from "../src/config.js";
 import { StandaloneServer } from "../src/standalone-server.js";
 import { PACKAGE_VERSION } from "../src/protocol.js";
 import { checkForUpdate, runUpdate } from "../src/update-checker.js";
+import { FileTokenStore } from "../src/token-store.js";
+import { performAuthCodeLogin, performDeviceCodeLogin } from "../src/cli-auth.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // After tsc, this file lives at dist/bin/mcp-bridge.js.
@@ -111,6 +113,17 @@ function parseArgs(argv) {
             case "update":
                 args.command = "update";
                 break;
+            case "auth":
+                args.command = "auth";
+                // Consume subcommand
+                if (i + 1 < argv.length) {
+                    const sub = argv[i + 1];
+                    if (sub === "login" || sub === "logout" || sub === "status") {
+                        args.authSubcommand = sub;
+                        i++;
+                    }
+                }
+                break;
             default:
                 if (!arg.startsWith("-")) {
                     args.positional.push(arg);
@@ -139,6 +152,9 @@ Usage:
   mcp-bridge servers                List configured servers
   mcp-bridge search <query>         Search catalog by keyword
   mcp-bridge update [--check]       Check for / install updates
+  mcp-bridge auth login <server>    Authenticate with an OAuth2 server
+  mcp-bridge auth logout <server>   Remove stored token for a server
+  mcp-bridge auth status            Show auth status for all servers
 
 Options:
   --config PATH     Custom config file (default: ~/.mcp-bridge/config.json)
@@ -257,6 +273,132 @@ async function cmdUpdate(logger, checkOnly) {
     const result = await runUpdate(logger);
     process.stdout.write(result + "\n");
 }
+async function cmdAuth(args, logger) {
+    const sub = args.authSubcommand;
+    if (!sub) {
+        process.stderr.write("Usage: mcp-bridge auth <login|logout|status> [server-name]\n");
+        process.exit(1);
+    }
+    const tokenStore = new FileTokenStore();
+    if (sub === "status") {
+        let config;
+        try {
+            config = loadConfig({ configPath: args.configPath, logger });
+        }
+        catch {
+            config = null;
+        }
+        const stored = tokenStore.list();
+        if (stored.length === 0 && !config) {
+            process.stdout.write("No stored tokens.\n");
+            return;
+        }
+        process.stdout.write("\nAuth status:\n\n");
+        process.stdout.write("  Server          Auth Type              Token Status\n");
+        process.stdout.write("  " + "\u2500".repeat(60) + "\n");
+        // Show configured servers
+        const shown = new Set();
+        if (config) {
+            for (const [name, serverConfig] of Object.entries(config.servers)) {
+                const authType = serverConfig.auth?.type ?? "none";
+                const grantType = serverConfig.auth?.type === "oauth2" && "grantType" in serverConfig.auth
+                    ? serverConfig.auth.grantType
+                    : serverConfig.auth?.type === "oauth2" ? "client_credentials" : "";
+                const label = authType === "oauth2" ? `oauth2 (${grantType})` : authType;
+                const token = tokenStore.load(name);
+                let status;
+                if (token) {
+                    const now = Date.now();
+                    if (token.expiresAt > now) {
+                        const mins = Math.round((token.expiresAt - now) / 60000);
+                        status = `valid (expires in ${mins}m)`;
+                    }
+                    else {
+                        status = token.refreshToken ? "expired (refresh available)" : "expired";
+                    }
+                }
+                else if (grantType === "authorization_code" || grantType === "device_code") {
+                    status = "not authenticated";
+                }
+                else {
+                    status = "-";
+                }
+                process.stdout.write(`  ${name.padEnd(16)}${label.padEnd(23)}${status}\n`);
+                shown.add(name);
+            }
+        }
+        // Show stored tokens not in config
+        for (const { serverName, token } of stored) {
+            if (shown.has(serverName))
+                continue;
+            const now = Date.now();
+            const status = token.expiresAt > now
+                ? `valid (expires in ${Math.round((token.expiresAt - now) / 60000)}m)`
+                : "expired";
+            process.stdout.write(`  ${serverName.padEnd(16)}${"oauth2 (stored)".padEnd(23)}${status}\n`);
+        }
+        process.stdout.write("\n");
+        return;
+    }
+    // login / logout need a server name
+    const serverName = args.positional[0];
+    if (!serverName) {
+        process.stderr.write(`Usage: mcp-bridge auth ${sub} <server-name>\n`);
+        process.exit(1);
+    }
+    if (sub === "logout") {
+        tokenStore.remove(serverName);
+        process.stdout.write(`Removed stored token for ${serverName}\n`);
+        return;
+    }
+    // login
+    let config;
+    try {
+        config = loadConfig({ configPath: args.configPath, logger });
+    }
+    catch (err) {
+        logger.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+    const serverConfig = config.servers[serverName];
+    if (!serverConfig) {
+        logger.error(`Server "${serverName}" not found in config`);
+        process.exit(1);
+    }
+    const auth = serverConfig.auth;
+    if (!auth || auth.type !== "oauth2" || !("grantType" in auth)) {
+        logger.error(`Server "${serverName}" is not configured for an interactive OAuth2 flow (authorization_code or device_code)`);
+        process.exit(1);
+    }
+    const grantType = auth.grantType;
+    let token;
+    if (grantType === "device_code") {
+        const deviceAuth = auth;
+        token = await performDeviceCodeLogin(serverName, {
+            deviceAuthorizationUrl: deviceAuth.deviceAuthorizationUrl,
+            tokenUrl: deviceAuth.tokenUrl,
+            clientId: deviceAuth.clientId,
+            scopes: deviceAuth.scopes,
+        }, logger);
+    }
+    else if (grantType === "authorization_code") {
+        const authCodeAuth = auth;
+        token = await performAuthCodeLogin(serverName, {
+            authorizationUrl: authCodeAuth.authorizationUrl,
+            tokenUrl: authCodeAuth.tokenUrl,
+            clientId: authCodeAuth.clientId,
+            clientSecret: authCodeAuth.clientSecret,
+            scopes: authCodeAuth.scopes,
+            callbackPort: authCodeAuth.callbackPort,
+        }, logger);
+    }
+    else {
+        logger.error(`Server "${serverName}" uses grant type "${grantType}" which does not support interactive login`);
+        process.exit(1);
+    }
+    tokenStore.save(serverName, token);
+    process.stdout.write(`Authentication successful for ${serverName}. Token stored.\n`);
+}
 async function cmdServe(args, logger) {
     let config;
     try {
@@ -325,6 +467,9 @@ async function main() {
         case "update":
             await cmdUpdate(logger, args.checkOnly);
             break;
+        case "auth":
+            await cmdAuth(args, logger);
+            break;
         case "serve":
             await cmdServe(args, logger);
             break;

package/dist/src/cli-auth.d.ts

@@ -0,0 +1,41 @@
+import type { Logger } from "./types.js";
+import type { StoredToken } from "./token-store.js";
+export interface AuthCodeConfig {
+    authorizationUrl: string;
+    tokenUrl: string;
+    clientId?: string;
+    clientSecret?: string;
+    scopes?: string[];
+    callbackPort?: number;
+}
+/**
+ * Generate a PKCE code_verifier: 43-128 URL-safe characters.
+ */
+export declare function generateCodeVerifier(length?: number): string;
+/**
+ * Compute S256 code_challenge from code_verifier.
+ */
+export declare function computeCodeChallenge(verifier: string): string;
+/**
+ * Perform the full OAuth2 Authorization Code flow with PKCE.
+ *
+ * 1. Start local HTTP server on callbackPort
+ * 2. Open browser to authorization URL
+ * 3. Receive callback with authorization code
+ * 4. Exchange code for tokens
+ */
+export declare function performAuthCodeLogin(serverName: string, authConfig: AuthCodeConfig, logger: Logger): Promise<StoredToken>;
+export interface DeviceCodeConfig {
+    deviceAuthorizationUrl: string;
+    tokenUrl: string;
+    clientId: string;
+    scopes?: string[];
+}
+/**
+ * Perform the OAuth2 Device Authorization Grant (RFC 8628).
+ *
+ * 1. POST to deviceAuthorizationUrl to obtain device_code + user_code
+ * 2. Display user_code and verification_uri to the user
+ * 3. Poll tokenUrl until the user authorizes or the code expires
+ */
+export declare function performDeviceCodeLogin(serverName: string, config: DeviceCodeConfig, logger: Logger): Promise<StoredToken>;

package/dist/src/cli-auth.js

@@ -0,0 +1,300 @@
+import { createServer } from "http";
+import { randomBytes, createHash } from "crypto";
+import { exec } from "child_process";
+import { platform } from "os";
+/** Escape HTML special characters to prevent XSS in callback responses. */
+function escapeHtml(str) {
+    return str
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+const LOGIN_TIMEOUT_MS = 120_000;
+/**
+ * Generate a PKCE code_verifier: 43-128 URL-safe characters.
+ */
+export function generateCodeVerifier(length = 64) {
+    const charset = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~";
+    const bytes = randomBytes(length);
+    let result = "";
+    for (let i = 0; i < length; i++) {
+        result += charset[bytes[i] % charset.length];
+    }
+    return result;
+}
+/**
+ * Compute S256 code_challenge from code_verifier.
+ */
+export function computeCodeChallenge(verifier) {
+    return createHash("sha256")
+        .update(verifier, "ascii")
+        .digest("base64url");
+}
+/**
+ * Open a URL in the default browser using platform-specific commands.
+ */
+function openBrowser(url, logger) {
+    const os = platform();
+    let cmd;
+    if (os === "darwin") {
+        cmd = `open "${url}"`;
+    }
+    else if (os === "win32") {
+        cmd = `start "" "${url}"`;
+    }
+    else {
+        cmd = `xdg-open "${url}"`;
+    }
+    exec(cmd, (err) => {
+        if (err) {
+            logger.warn(`[mcp-bridge] Could not open browser automatically. Please visit:\n${url}`);
+        }
+    });
+}
+const DEFAULT_EXPIRES_IN = 3600;
+const EXPIRY_BUFFER_SECONDS = 60;
+/**
+ * Perform the full OAuth2 Authorization Code flow with PKCE.
+ *
+ * 1. Start local HTTP server on callbackPort
+ * 2. Open browser to authorization URL
+ * 3. Receive callback with authorization code
+ * 4. Exchange code for tokens
+ */
+export async function performAuthCodeLogin(serverName, authConfig, logger) {
+    const port = authConfig.callbackPort ?? 9876;
+    const redirectUri = `http://localhost:${port}/callback`;
+    const codeVerifier = generateCodeVerifier();
+    const codeChallenge = computeCodeChallenge(codeVerifier);
+    const state = randomBytes(16).toString("hex");
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const timeout = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                server.close();
+                reject(new Error("Authentication timed out after 120 seconds"));
+            }
+        }, LOGIN_TIMEOUT_MS);
+        const server = createServer((req, res) => {
+            if (!req.url?.startsWith("/callback")) {
+                res.writeHead(404);
+                res.end("Not found");
+                return;
+            }
+            const url = new URL(req.url, `http://localhost:${port}`);
+            const error = url.searchParams.get("error");
+            if (error) {
+                res.writeHead(200, { "Content-Type": "text/html" });
+                res.end(`<html><body><h2>Authentication failed</h2><p>${escapeHtml(error)}: ${escapeHtml(url.searchParams.get("error_description") || "")}</p></body></html>`);
+                if (!settled) {
+                    settled = true;
+                    clearTimeout(timeout);
+                    server.close();
+                    reject(new Error(`Authorization failed: ${error}`));
+                }
+                return;
+            }
+            const returnedState = url.searchParams.get("state");
+            if (returnedState !== state) {
+                res.writeHead(400, { "Content-Type": "text/html" });
+                res.end("<html><body><h2>Invalid state parameter</h2></body></html>");
+                if (!settled) {
+                    settled = true;
+                    clearTimeout(timeout);
+                    server.close();
+                    reject(new Error("OAuth2 state mismatch — possible CSRF attack"));
+                }
+                return;
+            }
+            const code = url.searchParams.get("code");
+            if (!code) {
+                res.writeHead(400, { "Content-Type": "text/html" });
+                res.end("<html><body><h2>Missing authorization code</h2></body></html>");
+                if (!settled) {
+                    settled = true;
+                    clearTimeout(timeout);
+                    server.close();
+                    reject(new Error("No authorization code in callback"));
+                }
+                return;
+            }
+            res.writeHead(200, { "Content-Type": "text/html" });
+            res.end(`<html><body><h2>Authentication successful!</h2><p>You can close this window and return to the terminal.</p></body></html>`);
+            if (!settled) {
+                settled = true;
+                clearTimeout(timeout);
+                server.close();
+                exchangeCodeForToken(authConfig, code, redirectUri, codeVerifier, logger)
+                    .then(resolve)
+                    .catch(reject);
+            }
+        });
+        server.listen(port, () => {
+            const params = new URLSearchParams();
+            params.set("response_type", "code");
+            if (authConfig.clientId)
+                params.set("client_id", authConfig.clientId);
+            params.set("redirect_uri", redirectUri);
+            if (authConfig.scopes?.length)
+                params.set("scope", authConfig.scopes.join(" "));
+            params.set("state", state);
+            params.set("code_challenge", codeChallenge);
+            params.set("code_challenge_method", "S256");
+            const authUrl = `${authConfig.authorizationUrl}?${params.toString()}`;
+            logger.info(`[mcp-bridge] Opening browser for ${serverName} authentication...`);
+            logger.info(`[mcp-bridge] If the browser doesn't open, visit: ${authUrl}`);
+            openBrowser(authUrl, logger);
+        });
+        server.on("error", (err) => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timeout);
+                reject(new Error(`Failed to start callback server on port ${port}: ${err.message}`));
+            }
+        });
+    });
+}
+const DEFAULT_POLL_INTERVAL_S = 5;
+const SLOW_DOWN_INCREMENT_S = 5;
+/**
+ * Perform the OAuth2 Device Authorization Grant (RFC 8628).
+ *
+ * 1. POST to deviceAuthorizationUrl to obtain device_code + user_code
+ * 2. Display user_code and verification_uri to the user
+ * 3. Poll tokenUrl until the user authorizes or the code expires
+ */
+export async function performDeviceCodeLogin(serverName, config, logger) {
+    // Step 1: Request device code
+    const formData = new URLSearchParams();
+    formData.set("client_id", config.clientId);
+    if (config.scopes?.length)
+        formData.set("scope", config.scopes.join(" "));
+    const deviceResponse = await fetch(config.deviceAuthorizationUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: formData.toString(),
+    });
+    if (!deviceResponse.ok) {
+        const text = await deviceResponse.text().catch(() => "");
+        throw new Error(`Device authorization request failed: HTTP ${deviceResponse.status} ${text}`);
+    }
+    const devicePayload = (await deviceResponse.json());
+    if (devicePayload.error) {
+        throw new Error(`Device authorization error: ${devicePayload.error} — ${devicePayload.error_description || ""}`);
+    }
+    if (!devicePayload.device_code || !devicePayload.user_code || !devicePayload.verification_uri) {
+        throw new Error("Device authorization response missing required fields (device_code, user_code, verification_uri)");
+    }
+    const deviceCode = devicePayload.device_code;
+    const userCode = devicePayload.user_code;
+    const verificationUri = devicePayload.verification_uri;
+    const verificationUriComplete = devicePayload.verification_uri_complete;
+    const expiresInS = devicePayload.expires_in ?? 900;
+    let intervalS = devicePayload.interval ?? DEFAULT_POLL_INTERVAL_S;
+    // Step 2: Display instructions to the user
+    logger.info(`[mcp-bridge] ──────────────────────────────────────────`);
+    logger.info(`[mcp-bridge]  Device authentication for "${serverName}"`);
+    logger.info(`[mcp-bridge]`);
+    logger.info(`[mcp-bridge]  1. Open: ${verificationUri}`);
+    logger.info(`[mcp-bridge]  2. Enter code: ${userCode}`);
+    logger.info(`[mcp-bridge] ──────────────────────────────────────────`);
+    if (verificationUriComplete) {
+        logger.info(`[mcp-bridge] Or open this URL directly: ${verificationUriComplete}`);
+        openBrowser(verificationUriComplete, logger);
+    }
+    logger.info(`[mcp-bridge] Waiting for authorization (expires in ${expiresInS}s)...`);
+    // Step 3: Poll for token
+    const deadline = Date.now() + expiresInS * 1000;
+    while (Date.now() < deadline) {
+        await sleep(intervalS * 1000);
+        const tokenForm = new URLSearchParams();
+        tokenForm.set("grant_type", "urn:ietf:params:oauth:grant-type:device_code");
+        tokenForm.set("device_code", deviceCode);
+        tokenForm.set("client_id", config.clientId);
+        const tokenResponse = await fetch(config.tokenUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: tokenForm.toString(),
+        });
+        const tokenPayload = (await tokenResponse.json());
+        if (tokenPayload.error) {
+            if (tokenPayload.error === "authorization_pending") {
+                continue;
+            }
+            if (tokenPayload.error === "slow_down") {
+                intervalS += SLOW_DOWN_INCREMENT_S;
+                continue;
+            }
+            if (tokenPayload.error === "expired_token") {
+                throw new Error("Device code expired. Please try again.");
+            }
+            if (tokenPayload.error === "access_denied") {
+                throw new Error("Authorization denied by user.");
+            }
+            throw new Error(`Device code token error: ${tokenPayload.error} — ${tokenPayload.error_description || ""}`);
+        }
+        if (!tokenPayload.access_token) {
+            throw new Error("Device code token response missing access_token");
+        }
+        const expiresIn = Number.isFinite(tokenPayload.expires_in)
+            ? Number(tokenPayload.expires_in)
+            : DEFAULT_EXPIRES_IN;
+        const expiresAt = Date.now() + Math.max(0, expiresIn - EXPIRY_BUFFER_SECONDS) * 1000;
+        logger.info(`[mcp-bridge] Authentication successful. Token expires in ${expiresIn}s.`);
+        return {
+            accessToken: tokenPayload.access_token,
+            refreshToken: tokenPayload.refresh_token,
+            expiresAt,
+            tokenUrl: config.tokenUrl,
+            clientId: config.clientId,
+            scopes: config.scopes,
+        };
+    }
+    throw new Error("Device code expired (timeout). Please try again.");
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function exchangeCodeForToken(config, code, redirectUri, codeVerifier, logger) {
+    const formData = new URLSearchParams();
+    formData.set("grant_type", "authorization_code");
+    formData.set("code", code);
+    formData.set("redirect_uri", redirectUri);
+    formData.set("code_verifier", codeVerifier);
+    if (config.clientId)
+        formData.set("client_id", config.clientId);
+    if (config.clientSecret)
+        formData.set("client_secret", config.clientSecret);
+    const response = await fetch(config.tokenUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: formData.toString(),
+    });
+    if (!response.ok) {
+        const text = await response.text().catch(() => "");
+        throw new Error(`Token exchange failed: HTTP ${response.status} ${text}`);
+    }
+    const payload = (await response.json());
+    if (payload.error) {
+        throw new Error(`Token exchange error: ${payload.error} — ${payload.error_description || ""}`);
+    }
+    if (!payload.access_token) {
+        throw new Error("Token exchange response missing access_token");
+    }
+    const expiresIn = Number.isFinite(payload.expires_in)
+        ? Number(payload.expires_in)
+        : DEFAULT_EXPIRES_IN;
+    const expiresAt = Date.now() + Math.max(0, expiresIn - EXPIRY_BUFFER_SECONDS) * 1000;
+    logger.info(`[mcp-bridge] Authentication successful. Token expires in ${expiresIn}s.`);
+    return {
+        accessToken: payload.access_token,
+        refreshToken: payload.refresh_token,
+        expiresAt,
+        tokenUrl: config.tokenUrl,
+        clientId: config.clientId,
+        scopes: config.scopes,
+    };
+}

package/dist/src/config.js

@@ -49,10 +49,15 @@ export function parseEnvFile(content) {
             continue;
         const key = trimmed.substring(0, eqIdx).trim();
         let value = trimmed.substring(eqIdx + 1).trim();
-        // Strip surrounding quotes
+        // Strip surrounding quotes and handle escaped quotes within
         if ((value.startsWith('"') && value.endsWith('"')) ||
             (value.startsWith("'") && value.endsWith("'"))) {
+            const quote = value[0];
             value = value.slice(1, -1);
+            // Unescape escaped quotes: \" → " or \' → '
+            value = value.replace(new RegExp(`\\\\${quote}`, "g"), quote);
+            // Unescape escaped backslashes: \\ → \
+            value = value.replace(/\\\\/g, "\\");
         }
         if (key)
             env[key] = value;
@@ -100,7 +105,10 @@ export function loadConfig(options = {}) {
             options.logger?.warn(`[mcp-bridge] Failed to parse .env file: ${err instanceof Error ? err.message : err}`);
         }
     }
-    // Merge .env into process.env (don't overwrite existing)
+    // Populate process.env with .env values for child processes (don't overwrite
+    // existing env vars — this matches dotenv's default behavior). This is separate
+    // from the config resolution below, which uses a different merge order where
+    // .env values win over process.env.
     for (const [key, value] of Object.entries(dotEnv)) {
         if (process.env[key] === undefined) {
             process.env[key] = value;

package/dist/src/index.d.ts

@@ -1,9 +1,13 @@
-export { BaseTransport, resolveEnvVars, resolveEnvRecord, resolveArgs, resolveAuthHeaders, resolveAuthHeadersAsync, resolveOAuth2Config, resolveServerHeaders, resolveServerHeadersAsync, warnIfNonTlsRemoteUrl, } from "./transport-base.js";
+export { BaseTransport, resolveEnvVars, resolveEnvRecord, resolveArgs, resolveAuthHeaders, resolveAuthHeadersAsync, isAuthCodeOAuth2, resolveOAuth2Config, resolveAuthCodeOAuth2Config, resolveServerHeaders, resolveServerHeadersAsync, warnIfNonTlsRemoteUrl, } from "./transport-base.js";
 export { StdioTransport } from "./transport-stdio.js";
 export { SseTransport } from "./transport-sse.js";
 export { StreamableHttpTransport } from "./transport-streamable-http.js";
 export { OAuth2TokenManager } from "./oauth2-token-manager.js";
-export type { OAuth2Config } from "./oauth2-token-manager.js";
+export type { OAuth2Config, AuthCodeOAuth2Config } from "./oauth2-token-manager.js";
+export { FileTokenStore } from "./token-store.js";
+export type { TokenStore, StoredToken } from "./token-store.js";
+export { performAuthCodeLogin, generateCodeVerifier, computeCodeChallenge } from "./cli-auth.js";
+export type { AuthCodeConfig } from "./cli-auth.js";
 export { McpRouter } from "./mcp-router.js";
 export type { RouterToolHint, RouterServerStatus, RouterDispatchResponse, RouterTransportRefs } from "./mcp-router.js";
 export { ResultCache, createResultCacheKey, stableStringify } from "./result-cache.js";

package/dist/src/index.js

@@ -1,10 +1,14 @@
 // Core exports for @aiwerk/mcp-bridge
 // Transport classes
-export { BaseTransport, resolveEnvVars, resolveEnvRecord, resolveArgs, resolveAuthHeaders, resolveAuthHeadersAsync, resolveOAuth2Config, resolveServerHeaders, resolveServerHeadersAsync, warnIfNonTlsRemoteUrl, } from "./transport-base.js";
+export { BaseTransport, resolveEnvVars, resolveEnvRecord, resolveArgs, resolveAuthHeaders, resolveAuthHeadersAsync, isAuthCodeOAuth2, resolveOAuth2Config, resolveAuthCodeOAuth2Config, resolveServerHeaders, resolveServerHeadersAsync, warnIfNonTlsRemoteUrl, } from "./transport-base.js";
 export { StdioTransport } from "./transport-stdio.js";
 export { SseTransport } from "./transport-sse.js";
 export { StreamableHttpTransport } from "./transport-streamable-http.js";
 export { OAuth2TokenManager } from "./oauth2-token-manager.js";
+// Token store
+export { FileTokenStore } from "./token-store.js";
+// CLI auth
+export { performAuthCodeLogin, generateCodeVerifier, computeCodeChallenge } from "./cli-auth.js";
 // Router
 export { McpRouter } from "./mcp-router.js";
 // Result cache

package/dist/src/mcp-router.d.ts

@@ -93,9 +93,9 @@ export type RouterDispatchResponse = {
     code?: number;
 };
 export interface RouterTransportRefs {
-    sse: new (config: McpServerConfig, clientConfig: McpClientConfig, logger: Logger, onReconnected?: () => Promise<void>, tokenManager?: OAuth2TokenManager, requestIdGenerator?: () => number) => McpTransport;
+    sse: new (config: McpServerConfig, clientConfig: McpClientConfig, logger: Logger, onReconnected?: () => Promise<void>, tokenManager?: OAuth2TokenManager, requestIdGenerator?: () => number, serverName?: string) => McpTransport;
     stdio: new (config: McpServerConfig, clientConfig: McpClientConfig, logger: Logger, onReconnected?: () => Promise<void>, requestIdGenerator?: () => number) => McpTransport;
-    streamableHttp: new (config: McpServerConfig, clientConfig: McpClientConfig, logger: Logger, onReconnected?: () => Promise<void>, tokenManager?: OAuth2TokenManager, requestIdGenerator?: () => number) => McpTransport;
+    streamableHttp: new (config: McpServerConfig, clientConfig: McpClientConfig, logger: Logger, onReconnected?: () => Promise<void>, tokenManager?: OAuth2TokenManager, requestIdGenerator?: () => number, serverName?: string) => McpTransport;
 }
 export declare class McpRouter {
     private readonly servers;
@@ -129,6 +129,15 @@ export declare class McpRouter {
     private getPromotionStats;
     private getRetryPolicy;
     private classifyTransientError;
+    /**
+     * Call a tool with automatic retry on transient transport errors.
+     *
+     * NOTE: Only transport-level errors (timeout, connection_error) are retried.
+     * MCP protocol errors (valid JSON-RPC responses with error fields) are NOT
+     * retried, because they typically indicate non-transient issues (unknown tool,
+     * invalid params, server-side validation failures). The retryOn config
+     * intentionally only accepts "timeout" | "connection_error" categories.
+     */
     private callToolWithRetry;
     disconnectAll(): Promise<void>;
     shutdown(timeoutMs?: number): Promise<void>;