@aiwerk/mcp-bridge 2.5.3 → 2.6.1

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

@@ -9,7 +9,7 @@ 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 } from "../src/cli-auth.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.
@@ -317,7 +317,7 @@ async function cmdAuth(args, logger) {
                         status = token.refreshToken ? "expired (refresh available)" : "expired";
                     }
                 }
-                else if (grantType === "authorization_code") {
+                else if (grantType === "authorization_code" || grantType === "device_code") {
                     status = "not authenticated";
                 }
                 else {
@@ -366,19 +366,36 @@ async function cmdAuth(args, logger) {
         process.exit(1);
     }
     const auth = serverConfig.auth;
-    if (!auth || auth.type !== "oauth2" || !("grantType" in auth) || auth.grantType !== "authorization_code") {
-        logger.error(`Server "${serverName}" is not configured for OAuth2 authorization_code flow`);
+    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);
     }
-    const authCodeAuth = auth;
-    const token = await performAuthCodeLogin(serverName, {
-        authorizationUrl: authCodeAuth.authorizationUrl,
-        tokenUrl: authCodeAuth.tokenUrl,
-        clientId: authCodeAuth.clientId,
-        clientSecret: authCodeAuth.clientSecret,
-        scopes: authCodeAuth.scopes,
-        callbackPort: authCodeAuth.callbackPort,
-    }, logger);
     tokenStore.save(serverName, token);
     process.stdout.write(`Authentication successful for ${serverName}. Token stored.\n`);
 }

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

@@ -25,3 +25,19 @@ export declare function computeCodeChallenge(verifier: string): string;
  * 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[];
+    /** Skip opening browser (for tests). */
+    skipBrowser?: boolean;
+}
+/**
+ * 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

@@ -157,6 +157,109 @@ export async function performAuthCodeLogin(serverName, authConfig, logger) {
         });
     });
 }
+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}`);
+        if (!config.skipBrowser) {
+            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");

package/dist/src/oauth2-token-manager.d.ts

@@ -14,6 +14,12 @@ export interface AuthCodeOAuth2Config {
     clientSecret?: string;
     scopes?: string[];
 }
+export interface DeviceCodeOAuth2Config {
+    grantType: "device_code";
+    tokenUrl: string;
+    clientId: string;
+    scopes?: string[];
+}
 export declare class OAuth2TokenManager {
     private readonly logger;
     private readonly tokenCache;
@@ -29,6 +35,13 @@ export declare class OAuth2TokenManager {
      * Checks TokenStore, refreshes if expired, throws if unavailable.
      */
     getTokenForAuthCode(serverName: string, config: AuthCodeOAuth2Config): Promise<string>;
+    /**
+     * Get a token for a device_code flow server.
+     * Checks TokenStore, refreshes if expired, throws if unavailable.
+     */
+    getTokenForDeviceCode(serverName: string, config: DeviceCodeOAuth2Config): Promise<string>;
+    private doDeviceCodeRefresh;
+    private refreshDeviceCodeToken;
     private doAuthCodeRefresh;
     private refreshAuthCodeToken;
     private makeKey;

package/dist/src/oauth2-token-manager.js

@@ -75,6 +75,87 @@ export class OAuth2TokenManager {
             this.authCodeInflight.delete(serverName);
         }
     }
+    /**
+     * Get a token for a device_code flow server.
+     * Checks TokenStore, refreshes if expired, throws if unavailable.
+     */
+    async getTokenForDeviceCode(serverName, config) {
+        if (!this.tokenStore) {
+            throw new Error(`Authentication required for server "${serverName}". Run: mcp-bridge auth login ${serverName}`);
+        }
+        const stored = this.tokenStore.load(serverName);
+        if (!stored) {
+            const err = new Error(`Authentication required for server "${serverName}". Run: mcp-bridge auth login ${serverName}`);
+            err.code = -32007;
+            throw err;
+        }
+        const now = Date.now();
+        if (stored.expiresAt > now) {
+            return stored.accessToken;
+        }
+        // Token expired — try refresh with inflight dedup
+        const existingInflight = this.authCodeInflight.get(serverName);
+        if (existingInflight) {
+            return existingInflight;
+        }
+        const refreshPromise = this.doDeviceCodeRefresh(serverName, stored, config);
+        this.authCodeInflight.set(serverName, refreshPromise);
+        try {
+            return await refreshPromise;
+        }
+        finally {
+            this.authCodeInflight.delete(serverName);
+        }
+    }
+    async doDeviceCodeRefresh(serverName, stored, config) {
+        if (stored.refreshToken) {
+            try {
+                const refreshed = await this.refreshDeviceCodeToken(stored, config);
+                this.tokenStore.save(serverName, refreshed);
+                return refreshed.accessToken;
+            }
+            catch (err) {
+                this.logger.warn("[mcp-bridge] Device code token refresh failed:", err);
+            }
+        }
+        // Refresh failed or no refresh token
+        this.tokenStore.remove(serverName);
+        const error = new Error(`Authentication expired for server "${serverName}". Run: mcp-bridge auth login ${serverName}`);
+        error.code = -32006;
+        throw error;
+    }
+    async refreshDeviceCodeToken(stored, config) {
+        const formData = new URLSearchParams();
+        formData.set("grant_type", "refresh_token");
+        formData.set("refresh_token", stored.refreshToken);
+        formData.set("client_id", config.clientId);
+        if (config.scopes?.length)
+            formData.set("scope", config.scopes.join(" "));
+        const response = await fetch(stored.tokenUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: formData.toString(),
+        });
+        if (!response.ok) {
+            throw new Error(`OAuth2 refresh token exchange failed: HTTP ${response.status}`);
+        }
+        const payload = (await response.json());
+        if (!payload.access_token) {
+            throw new Error("OAuth2 refresh response missing access_token");
+        }
+        const expiresIn = Number.isFinite(payload.expires_in)
+            ? Number(payload.expires_in)
+            : DEFAULT_EXPIRES_IN_SECONDS;
+        const expiresAt = Date.now() + Math.max(0, expiresIn - EXPIRY_BUFFER_SECONDS) * 1000;
+        return {
+            accessToken: payload.access_token,
+            refreshToken: payload.refresh_token ?? stored.refreshToken,
+            expiresAt,
+            tokenUrl: stored.tokenUrl,
+            clientId: config.clientId,
+            scopes: config.scopes,
+        };
+    }
     async doAuthCodeRefresh(serverName, stored, config) {
         if (stored.refreshToken) {
             try {

package/dist/src/transport-base.d.ts

@@ -1,5 +1,5 @@
 import { McpTransport, McpRequest, McpResponse, McpServerConfig, McpClientConfig, Logger, JsonRpcMessage, RequestIdGenerator } from "./types.js";
-import type { OAuth2Config, AuthCodeOAuth2Config, OAuth2TokenManager } from "./oauth2-token-manager.js";
+import type { OAuth2Config, AuthCodeOAuth2Config, DeviceCodeOAuth2Config, OAuth2TokenManager } from "./oauth2-token-manager.js";
 export type PendingRequest = {
     resolve: (value: McpResponse) => void;
     reject: (reason: Error) => void;
@@ -83,8 +83,14 @@ export declare function isAuthCodeOAuth2(auth: {
     type: "oauth2";
     grantType?: string;
 }): boolean;
+/** Check whether an oauth2 auth config uses the device_code grant type. */
+export declare function isDeviceCodeOAuth2(auth: {
+    type: "oauth2";
+    grantType?: string;
+}): boolean;
 export declare function resolveOAuth2Config(config: McpServerConfig, extraEnv?: Record<string, string | undefined>, envFallback?: () => Record<string, string>): OAuth2Config;
 export declare function resolveAuthCodeOAuth2Config(config: McpServerConfig, extraEnv?: Record<string, string | undefined>, envFallback?: () => Record<string, string>): AuthCodeOAuth2Config;
+export declare function resolveDeviceCodeOAuth2Config(config: McpServerConfig, extraEnv?: Record<string, string | undefined>, envFallback?: () => Record<string, string>): DeviceCodeOAuth2Config;
 export declare function resolveAuthHeadersAsync(config: McpServerConfig, tokenManager: OAuth2TokenManager, extraEnv?: Record<string, string | undefined>, envFallback?: () => Record<string, string>, serverName?: string): Promise<Record<string, string>>;
 /**
  * Resolve server headers and merge auth headers (auth takes precedence).

package/dist/src/transport-base.js

@@ -185,6 +185,10 @@ export function resolveAuthHeaders(config, extraEnv, envFallback) {
 export function isAuthCodeOAuth2(auth) {
     return auth.grantType === "authorization_code";
 }
+/** Check whether an oauth2 auth config uses the device_code grant type. */
+export function isDeviceCodeOAuth2(auth) {
+    return auth.grantType === "device_code";
+}
 export function resolveOAuth2Config(config, extraEnv, envFallback) {
     if (!config.auth || config.auth.type !== "oauth2") {
         throw new Error("[mcp-bridge] resolveOAuth2Config called for non-oauth2 auth config");
@@ -192,14 +196,18 @@ export function resolveOAuth2Config(config, extraEnv, envFallback) {
     if (isAuthCodeOAuth2(config.auth)) {
         throw new Error("[mcp-bridge] resolveOAuth2Config called for authorization_code config — use resolveAuthCodeOAuth2Config instead");
     }
-    const scopes = config.auth.scopes?.map((scope, index) => resolveEnvVars(scope, `oauth2 scope[${index}]`, extraEnv, envFallback));
+    if (isDeviceCodeOAuth2(config.auth)) {
+        throw new Error("[mcp-bridge] resolveOAuth2Config called for device_code config — use resolveDeviceCodeOAuth2Config instead");
+    }
+    const auth = config.auth;
+    const scopes = auth.scopes?.map((scope, index) => resolveEnvVars(scope, `oauth2 scope[${index}]`, extraEnv, envFallback));
     return {
-        clientId: resolveEnvVars(config.auth.clientId, "oauth2 clientId", extraEnv, envFallback),
-        clientSecret: resolveEnvVars(config.auth.clientSecret, "oauth2 clientSecret", extraEnv, envFallback),
-        tokenUrl: resolveEnvVars(config.auth.tokenUrl, "oauth2 tokenUrl", extraEnv, envFallback),
+        clientId: resolveEnvVars(auth.clientId, "oauth2 clientId", extraEnv, envFallback),
+        clientSecret: resolveEnvVars(auth.clientSecret, "oauth2 clientSecret", extraEnv, envFallback),
+        tokenUrl: resolveEnvVars(auth.tokenUrl, "oauth2 tokenUrl", extraEnv, envFallback),
         ...(scopes && scopes.length > 0 ? { scopes } : {}),
-        ...("audience" in config.auth && config.auth.audience
-            ? { audience: resolveEnvVars(config.auth.audience, "oauth2 audience", extraEnv, envFallback) }
+        ...(auth.audience
+            ? { audience: resolveEnvVars(auth.audience, "oauth2 audience", extraEnv, envFallback) }
             : {}),
     };
 }
@@ -217,6 +225,19 @@ export function resolveAuthCodeOAuth2Config(config, extraEnv, envFallback) {
         ...(scopes && scopes.length > 0 ? { scopes } : {}),
     };
 }
+export function resolveDeviceCodeOAuth2Config(config, extraEnv, envFallback) {
+    if (!config.auth || config.auth.type !== "oauth2" || !isDeviceCodeOAuth2(config.auth)) {
+        throw new Error("[mcp-bridge] resolveDeviceCodeOAuth2Config called for non-device_code auth config");
+    }
+    const auth = config.auth;
+    const scopes = auth.scopes?.map((scope, index) => resolveEnvVars(scope, `oauth2 scope[${index}]`, extraEnv, envFallback));
+    return {
+        grantType: "device_code",
+        tokenUrl: resolveEnvVars(auth.tokenUrl, "oauth2 tokenUrl", extraEnv, envFallback),
+        clientId: resolveEnvVars(auth.clientId, "oauth2 clientId", extraEnv, envFallback),
+        ...(scopes && scopes.length > 0 ? { scopes } : {}),
+    };
+}
 export async function resolveAuthHeadersAsync(config, tokenManager, extraEnv, envFallback, serverName) {
     if (!config.auth)
         return {};
@@ -229,6 +250,14 @@ export async function resolveAuthHeadersAsync(config, tokenManager, extraEnv, en
             const token = await tokenManager.getTokenForAuthCode(serverName, authCodeConfig);
             return { Authorization: `Bearer ${token}` };
         }
+        if (isDeviceCodeOAuth2(config.auth)) {
+            if (!serverName) {
+                throw new Error("[mcp-bridge] serverName is required for device_code OAuth2 flow");
+            }
+            const deviceCodeConfig = resolveDeviceCodeOAuth2Config(config, extraEnv, envFallback);
+            const token = await tokenManager.getTokenForDeviceCode(serverName, deviceCodeConfig);
+            return { Authorization: `Bearer ${token}` };
+        }
         const oauth2Config = resolveOAuth2Config(config, extraEnv, envFallback);
         const token = await tokenManager.getToken(oauth2Config);
         return { Authorization: `Bearer ${token}` };

package/dist/src/types.d.ts

@@ -26,6 +26,13 @@ export type HttpAuthConfig = {
     clientSecret?: string;
     scopes?: string[];
     callbackPort?: number;
+} | {
+    type: "oauth2";
+    grantType: "device_code";
+    deviceAuthorizationUrl: string;
+    tokenUrl: string;
+    clientId: string;
+    scopes?: string[];
 };
 export interface RetryConfig {
     maxAttempts?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwerk/mcp-bridge",
-  "version": "2.5.3",
+  "version": "2.6.1",
   "description": "Standalone MCP server that multiplexes multiple MCP servers into one interface",
   "type": "module",
   "main": "./dist/src/index.js",