mcp-compose 0.3.0 → 0.4.0

package/dist/src/oauth.js

@@ -3,11 +3,13 @@ import { createHash, randomBytes } from 'node:crypto';
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
-import { exec } from 'node:child_process';
+import { spawn } from 'node:child_process';
 // --- Constants ---
 const CONFIG_DIR = join(homedir(), '.mcp-auth', 'mcp-compose');
 const DEFAULT_AUTH_TIMEOUT = 120_000;
-const MCP_PROTOCOL_VERSION = '2025-03-26';
+const MCP_PROTOCOL_VERSION = '2026-07-28';
+/** OAuth metadata and token endpoints are remote input. Never buffer them without a limit. */
+const MAX_OAUTH_RESPONSE_BODY_BYTES = 1024 * 1024;
 const CLIENT_NAME = 'mcp-compose';
 // --- Helpers ---
 function serverHash(url) {
@@ -16,27 +18,242 @@ function serverHash(url) {
 function generateCodeVerifier() {
     return randomBytes(32).toString('base64url');
 }
+function generateState() {
+    return randomBytes(32).toString('base64url');
+}
 function generateCodeChallenge(verifier) {
     return createHash('sha256').update(verifier).digest('base64url');
 }
+function normalizeResourceUrl(serverUrl) {
+    const url = new URL(serverUrl);
+    url.search = '';
+    url.hash = '';
+    return url.toString();
+}
+function validateAuthorizationServerIssuer(value) {
+    if (typeof value !== 'string')
+        throw new Error('OAuth protected-resource metadata has an invalid authorization server');
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error('OAuth protected-resource metadata has an invalid authorization server');
+    }
+    if (!['http:', 'https:'].includes(url.protocol)
+        || url.username || url.password || url.hash || url.search) {
+        throw new Error('OAuth protected-resource metadata has an invalid authorization server');
+    }
+    if (url.protocol === 'http:' && !isLiteralLoopbackHost(url.hostname)) {
+        throw new Error('OAuth authorization server must use HTTPS outside loopback');
+    }
+    return value;
+}
+function isLiteralLoopbackHost(hostname) {
+    const host = hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    return host === 'localhost' || host === '::1' || /^127(?:\.\d{1,3}){3}$/.test(host);
+}
+function validateOAuthEndpoint(value, label) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`OAuth ${label} endpoint is invalid`);
+    }
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.hash
+        || (url.protocol === 'http:' && !isLiteralLoopbackHost(url.hostname))) {
+        throw new Error(`OAuth ${label} endpoint must use HTTPS outside loopback`);
+    }
+    return url.toString();
+}
 async function ensureConfigDir() {
     await mkdir(CONFIG_DIR, { recursive: true, mode: 0o700 });
 }
-function openBrowser(url) {
-    const cmd = process.platform === 'darwin' ? 'open'
-        : process.platform === 'win32' ? 'start ""'
-            : 'xdg-open';
-    exec(`${cmd} "${url}"`, (err) => {
-        if (err) {
-            process.stderr.write(`Please open this URL in your browser:\n${url}\n`);
-        }
+const defaultBrowserLauncher = (command, args, options) => spawn(command, args, options);
+/** Opens an authorization URL as a literal process argument, never through a shell. */
+export function openBrowser(url, launchBrowser = defaultBrowserLauncher) {
+    let command;
+    let args;
+    if (process.platform === 'darwin') {
+        command = 'open';
+        args = [url];
+    }
+    else if (process.platform === 'win32') {
+        // `start` is a cmd.exe built-in. rundll32 accepts the URL as a direct
+        // argument, so URL syntax cannot become shell syntax on Windows.
+        command = 'rundll32.exe';
+        args = ['url.dll,FileProtocolHandler', url];
+    }
+    else {
+        command = 'xdg-open';
+        args = [url];
+    }
+    const child = launchBrowser(command, args, { detached: true, stdio: 'ignore', windowsHide: true });
+    child.once('error', () => {
+        process.stderr.write(`Please open this URL in your browser:\n${url}\n`);
     });
+    child.unref();
 }
-function parseWwwAuthenticateScope(header) {
+function normalizeScope(scope) {
+    if (!scope)
+        return undefined;
+    const tokens = scope.trim().split(/\s+/);
+    return tokens.length > 0 && tokens.every((token) => /^[\x21\x23-\x5B\x5D-\x7E]+$/.test(token))
+        ? tokens.join(' ')
+        : undefined;
+}
+function scopeTokens(scope) {
+    return new Set(normalizeScope(scope)?.split(' ') ?? []);
+}
+function isScopeSubset(scope, allowedScope) {
+    const requested = scopeTokens(scope);
+    const allowed = scopeTokens(allowedScope);
+    return requested.size === 0 || (allowed.size > 0 && [...requested].every((token) => allowed.has(token)));
+}
+function unionScopes(...scopes) {
+    const tokens = new Set();
+    for (const scope of scopes) {
+        for (const token of scopeTokens(scope))
+            tokens.add(token);
+    }
+    return tokens.size > 0 ? [...tokens].join(' ') : undefined;
+}
+function metadataScopes(scope) {
+    return Array.isArray(scope) ? normalizeScope(scope.filter((value) => typeof value === 'string').join(' ')) : undefined;
+}
+/** Parse Bearer auth-params without mistaking quoted commas or escaped quotes for challenge boundaries. */
+function parseBearerChallenge(header) {
     if (!header)
         return undefined;
-    const match = /scope="([^"]+)"/.exec(header);
-    return match?.[1];
+    let position = 0;
+    let firstBearer;
+    const readToken = () => {
+        const start = position;
+        while (position < header.length && /[!#$%&'*+.^_`|~0-9A-Za-z-]/.test(header[position] ?? ''))
+            position += 1;
+        return position > start ? header.slice(start, position) : undefined;
+    };
+    const skipWhitespace = () => {
+        while (position < header.length && /[ \t]/.test(header[position] ?? ''))
+            position += 1;
+    };
+    const readValue = () => {
+        if (header[position] !== '"')
+            return readToken();
+        position += 1;
+        let value = '';
+        while (position < header.length) {
+            const char = header[position++] ?? '';
+            if (char === '"')
+                return value;
+            if (char === '\\' && position < header.length)
+                value += header[position++] ?? '';
+            else
+                value += char;
+        }
+        return undefined;
+    };
+    while (position < header.length) {
+        while (header[position] === ',' || /[ \t]/.test(header[position] ?? ''))
+            position += 1;
+        const scheme = readToken();
+        if (!scheme)
+            break;
+        skipWhitespace();
+        const params = new Map();
+        while (position < header.length) {
+            const saved = position;
+            const name = readToken();
+            skipWhitespace();
+            if (!name || header[position] !== '=') {
+                position = saved;
+                break;
+            }
+            position += 1;
+            skipWhitespace();
+            const value = readValue();
+            if (value === undefined)
+                break;
+            params.set(name.toLowerCase(), value);
+            skipWhitespace();
+            if (header[position] !== ',')
+                break;
+            position += 1;
+            const afterComma = position;
+            skipWhitespace();
+            readToken();
+            skipWhitespace();
+            const isNextParam = header[position] === '=';
+            position = afterComma;
+            if (!isNextParam)
+                break;
+            skipWhitespace();
+        }
+        if (scheme.toLowerCase() === 'bearer') {
+            firstBearer ??= params;
+            if (params.has('scope') || params.has('resource_metadata'))
+                return params;
+        }
+    }
+    return firstBearer;
+}
+function parseWwwAuthenticateScope(header) {
+    return normalizeScope(parseBearerChallenge(header)?.get('scope'));
+}
+function challengeMetadataUrl(header, serverUrl) {
+    const raw = parseBearerChallenge(header)?.get('resource_metadata');
+    if (!raw)
+        return undefined;
+    try {
+        const expected = new URL(serverUrl);
+        const metadata = new URL(raw);
+        if (metadata.origin !== expected.origin
+            || !['http:', 'https:'].includes(metadata.protocol)
+            || metadata.username || metadata.password || metadata.hash)
+            return undefined;
+        return metadata.toString();
+    }
+    catch {
+        return undefined;
+    }
+}
+function abortError(signal) {
+    return signal.reason instanceof Error ? signal.reason : new Error('OAuth operation aborted');
+}
+function throwIfAborted(signal) {
+    if (signal.aborted)
+        throw abortError(signal);
+}
+/**
+ * Use one deadline for the whole operation, rather than giving each fallback
+ * endpoint a fresh timeout. This prevents a discovery chain from exceeding
+ * the lifetime of its gateway request.
+ */
+function createBoundedOperation(timeout, callerSignal) {
+    const controller = new AbortController();
+    const abortFromCaller = () => { controller.abort(callerSignal?.reason); };
+    if (callerSignal?.aborted)
+        abortFromCaller();
+    else
+        callerSignal?.addEventListener('abort', abortFromCaller, { once: true });
+    const timer = setTimeout(() => { controller.abort(new Error('OAuth operation timed out')); }, timeout);
+    timer.unref();
+    return {
+        signal: controller.signal,
+        dispose: () => {
+            clearTimeout(timer);
+            callerSignal?.removeEventListener('abort', abortFromCaller);
+        },
+    };
+}
+async function awaitWithSignal(promise, signal) {
+    throwIfAborted(signal);
+    return await new Promise((resolve, reject) => {
+        const onAbort = () => { reject(abortError(signal)); };
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then(resolve, reject).finally(() => { signal.removeEventListener('abort', onAbort); });
+    });
 }
 function listenOnRandomPort(server) {
     return new Promise((resolve) => {
@@ -60,24 +277,132 @@ async function saveStoredAuth(hash, auth) {
     await writeFile(join(CONFIG_DIR, `${hash}.json`), JSON.stringify(auth, null, 2), { mode: 0o600 });
 }
 // --- Discovery ---
-async function fetchJson(url, headers) {
+class OAuthResponseTooLargeError extends Error {
+    constructor() {
+        super(`OAuth response body exceeds ${String(MAX_OAUTH_RESPONSE_BODY_BYTES)} bytes`);
+    }
+}
+async function readBoundedResponseText(res) {
+    const body = res.body;
+    if (!body)
+        return '';
+    const contentLength = res.headers.get('content-length');
+    if (contentLength && /^\d+$/.test(contentLength) && Number(contentLength) > MAX_OAUTH_RESPONSE_BODY_BYTES) {
+        await body.cancel();
+        throw new OAuthResponseTooLargeError();
+    }
+    const reader = body.getReader();
+    const chunks = [];
+    let byteLength = 0;
     try {
-        const res = headers ? await fetch(url, { headers }) : await fetch(url);
+        for (;;) {
+            const result = await reader.read();
+            if (result.done)
+                break;
+            const value = result.value;
+            byteLength += value.byteLength;
+            if (byteLength > MAX_OAUTH_RESPONSE_BODY_BYTES) {
+                await reader.cancel();
+                throw new OAuthResponseTooLargeError();
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+async function readBoundedJson(res) {
+    return JSON.parse(await readBoundedResponseText(res));
+}
+/** Consume an ignored error response up to the same limit, then release its socket. */
+async function discardBoundedResponseBody(res) {
+    const body = res.body;
+    if (!body)
+        return;
+    const contentLength = res.headers.get('content-length');
+    if (contentLength && /^\d+$/.test(contentLength) && Number(contentLength) > MAX_OAUTH_RESPONSE_BODY_BYTES) {
+        await body.cancel();
+        return;
+    }
+    const reader = body.getReader();
+    let byteLength = 0;
+    try {
+        for (;;) {
+            const result = await reader.read();
+            if (result.done)
+                return;
+            byteLength += result.value.byteLength;
+            if (byteLength > MAX_OAUTH_RESPONSE_BODY_BYTES) {
+                await reader.cancel();
+                return;
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+async function fetchJson(url, signal, headers) {
+    try {
+        throwIfAborted(signal);
+        const res = headers
+            ? await fetch(url, { headers, signal, redirect: 'error' })
+            : await fetch(url, { signal, redirect: 'error' });
         if (res.ok)
-            return await res.json();
+            return await readBoundedJson(res);
+        await discardBoundedResponseBody(res);
     }
-    catch {
+    catch (error) {
+        throwIfAborted(signal);
+        if (error instanceof OAuthResponseTooLargeError)
+            throw error;
         // ignore network errors, continue
     }
     return undefined;
 }
-async function discoverProtectedResource(serverUrl, headers) {
-    const url = new URL(serverUrl);
-    const fetchHeaders = { 'MCP-Protocol-Version': MCP_PROTOCOL_VERSION, ...headers };
-    // Path-aware URL first, then root fallback (RFC 9728)
-    return await fetchJson(new URL(`/.well-known/oauth-protected-resource${url.pathname}`, url.origin).toString(), fetchHeaders) ?? await fetchJson(new URL('/.well-known/oauth-protected-resource', url.origin).toString(), fetchHeaders);
+async function discoverProtectedResource(serverUrl, signal, headers, challengedMetadataUrl) {
+    const resource = normalizeResourceUrl(serverUrl);
+    const fetchHeaders = Object.fromEntries(Object.entries(headers ?? {})
+        .filter(([name]) => name.toLowerCase() !== 'mcp-protocol-version'));
+    // Headers are case-insensitive on the wire. Set this after user headers so
+    // discovery always carries the protocol version this client implements.
+    fetchHeaders['MCP-Protocol-Version'] = MCP_PROTOCOL_VERSION;
+    if (challengedMetadataUrl) {
+        const metadata = await fetchJson(challengedMetadataUrl, signal, fetchHeaders);
+        if (metadata)
+            return validateProtectedResourceMetadata(metadata, resource, challengedMetadataUrl, 'resource_metadata');
+    }
+    // Path-aware URL first, then root fallback (RFC 9728).
+    for (const metadataUrl of protectedResourceMetadataUrls(resource)) {
+        const metadata = await fetchJson(metadataUrl, signal, fetchHeaders);
+        if (metadata)
+            return validateProtectedResourceMetadata(metadata, resource, metadataUrl, 'discovery');
+    }
+    return undefined;
+}
+function protectedResourceMetadataUrl(resource) {
+    const url = new URL(resource);
+    return new URL(`/.well-known/oauth-protected-resource${url.pathname}`, url.origin).toString();
+}
+function protectedResourceMetadataUrls(resource) {
+    const url = new URL(resource);
+    return [...new Set([
+            protectedResourceMetadataUrl(resource),
+            new URL('/.well-known/oauth-protected-resource', url.origin).toString(),
+        ])];
 }
-async function discoverAuthServer(authServerUrl) {
+/** RFC 9728 §3.3 requires exact string identity, after JSON decoding, not URL normalization. */
+function validateProtectedResourceMetadata(metadata, resource, metadataUrl, source) {
+    if (metadata.resource !== resource
+        || (source === 'discovery' && !protectedResourceMetadataUrls(resource).includes(metadataUrl))) {
+        const label = source === 'resource_metadata' ? 'resource_metadata' : 'protected-resource metadata';
+        throw new Error(`OAuth ${label} does not bind to its protected resource`);
+    }
+    return metadata;
+}
+async function discoverAuthServer(authServerUrl, signal) {
     const url = new URL(authServerUrl);
     const hasPath = url.pathname !== '/' && url.pathname !== '';
     // RFC 8414 + OIDC Discovery URLs in priority order
@@ -90,16 +415,20 @@ async function discoverAuthServer(authServerUrl) {
         new URL('/.well-known/openid-configuration', url.origin),
     ];
     for (const discoveryUrl of urls) {
-        const meta = await fetchJson(discoveryUrl.toString());
-        if (meta)
+        const meta = await fetchJson(discoveryUrl.toString(), signal);
+        if (meta) {
+            if (typeof meta.issuer !== 'string' || meta.issuer !== authServerUrl) {
+                throw new Error('OAuth authorization-server metadata issuer is not bound to its server');
+            }
             return meta;
+        }
     }
     return undefined;
 }
 // --- Registration (RFC 7591) ---
-async function registerClient(authServerUrl, metadata, redirectUri) {
-    const endpoint = metadata?.registration_endpoint
-        ?? new URL('/register', authServerUrl).toString();
+async function registerClient(authServerUrl, metadata, redirectUri, signal) {
+    const endpoint = validateOAuthEndpoint(metadata?.registration_endpoint
+        ?? new URL('/register', authServerUrl).toString(), 'registration');
     const res = await fetch(endpoint, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
@@ -109,12 +438,16 @@ async function registerClient(authServerUrl, metadata, redirectUri) {
             grant_types: ['authorization_code', 'refresh_token'],
             response_types: ['code'],
             token_endpoint_auth_method: 'none',
+            application_type: 'native',
         }),
+        signal,
+        redirect: 'error',
     });
     if (!res.ok) {
-        throw new Error(`Client registration failed: ${String(res.status)} ${await res.text()}`);
+        await readBoundedResponseText(res);
+        throw new Error(`Client registration failed with HTTP ${String(res.status)}`);
     }
-    const info = await res.json();
+    const info = await readBoundedJson(res);
     info.redirect_uris = [redirectUri];
     return info;
 }
@@ -129,56 +462,92 @@ function buildClientAuthHeaders(clientInfo) {
     }
     return headers;
 }
-async function exchangeCodeForTokens(authServerUrl, metadata, clientInfo, code, codeVerifier, redirectUri) {
-    const tokenUrl = metadata?.token_endpoint ?? new URL('/token', authServerUrl).toString();
+function requireBearerToken(tokens) {
+    if (tokens.token_type.toLowerCase() !== 'bearer') {
+        throw new Error(`Unsupported OAuth token type: ${tokens.token_type}`);
+    }
+    return tokens;
+}
+async function exchangeCodeForTokens(authServerUrl, metadata, clientInfo, code, codeVerifier, redirectUri, resource, signal) {
+    const tokenUrl = validateOAuthEndpoint(metadata?.token_endpoint ?? new URL('/token', authServerUrl).toString(), 'token');
     const params = new URLSearchParams({
         grant_type: 'authorization_code',
         code,
         code_verifier: codeVerifier,
         redirect_uri: redirectUri,
         client_id: clientInfo.client_id,
+        resource,
     });
     const res = await fetch(tokenUrl, {
         method: 'POST',
         headers: buildClientAuthHeaders(clientInfo),
         body: params.toString(),
+        signal,
+        redirect: 'error',
     });
     if (!res.ok) {
-        throw new Error(`Token exchange failed: ${String(res.status)} ${await res.text()}`);
+        await readBoundedResponseText(res);
+        throw new Error(`Token exchange failed with HTTP ${String(res.status)}`);
     }
-    return await res.json();
+    return requireBearerToken(await readBoundedJson(res));
 }
-async function refreshAccessToken(authServerUrl, metadata, clientInfo, refreshToken) {
-    const tokenUrl = metadata?.token_endpoint ?? new URL('/token', authServerUrl).toString();
+async function refreshAccessToken(authServerUrl, metadata, clientInfo, refreshToken, resource, scope, originalScope, signal) {
+    const tokenUrl = validateOAuthEndpoint(metadata?.token_endpoint ?? new URL('/token', authServerUrl).toString(), 'token');
     const params = new URLSearchParams({
         grant_type: 'refresh_token',
         refresh_token: refreshToken,
         client_id: clientInfo.client_id,
+        resource,
     });
+    if (scope)
+        params.set('scope', scope);
     try {
         const res = await fetch(tokenUrl, {
             method: 'POST',
             headers: buildClientAuthHeaders(clientInfo),
             body: params.toString(),
+            signal,
+            redirect: 'error',
         });
-        if (!res.ok)
+        if (!res.ok) {
+            await discardBoundedResponseBody(res);
+            return undefined;
+        }
+        const tokens = requireBearerToken(await readBoundedJson(res));
+        // RFC 6749 permits scope omission on refresh. Keep the known grant, and
+        // reject a response that claims a broader grant than the original token.
+        if (tokens.scope && originalScope && !isScopeSubset(tokens.scope, originalScope))
             return undefined;
-        const tokens = await res.json();
+        const effectiveScope = scope ?? originalScope;
+        if (!tokens.scope && effectiveScope)
+            tokens.scope = effectiveScope;
         // Preserve original refresh token if server doesn't return a new one
         tokens.refresh_token ??= refreshToken;
         return tokens;
     }
     catch {
+        throwIfAborted(signal);
         return undefined;
     }
 }
 // --- Callback Server ---
-function waitForOAuthCallback(server, port, timeout) {
+function waitForOAuthCallback(server, port, expectedState, expectedIssuer, issuerRequired, signal) {
     return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => {
+        let settled = false;
+        const finish = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener('abort', onAbort);
             server.close();
-            reject(new Error('OAuth authorization timed out'));
-        }, timeout);
+            callback();
+        };
+        const onAbort = () => { finish(() => { reject(abortError(signal)); }); };
+        if (signal.aborted) {
+            onAbort();
+            return;
+        }
+        signal.addEventListener('abort', onAbort, { once: true });
         server.on('request', (req, res) => {
             const reqUrl = new URL(req.url ?? '/', `http://127.0.0.1:${String(port)}`);
             if (reqUrl.pathname !== '/oauth/callback') {
@@ -188,21 +557,39 @@ function waitForOAuthCallback(server, port, timeout) {
             }
             const code = reqUrl.searchParams.get('code');
             const error = reqUrl.searchParams.get('error');
+            const state = reqUrl.searchParams.get('state');
+            const issuer = reqUrl.searchParams.get('iss');
+            if (state !== expectedState) {
+                finish(() => {
+                    res.writeHead(400, { 'Content-Type': 'text/html' });
+                    res.end('<html><body><h1>Authorization failed</h1><p>Invalid state</p></body></html>');
+                    reject(new Error('OAuth state validation failed'));
+                });
+                return;
+            }
+            if ((issuer === null && issuerRequired) || (issuer !== null && issuer !== expectedIssuer)) {
+                finish(() => {
+                    res.writeHead(400, { 'Content-Type': 'text/html' });
+                    res.end('<html><body><h1>Authorization failed</h1><p>Invalid issuer</p></body></html>');
+                    reject(new Error('OAuth issuer validation failed'));
+                });
+                return;
+            }
             if (code) {
-                clearTimeout(timer);
-                res.writeHead(200, { 'Content-Type': 'text/html' });
-                res.end('<html><body><h1>Authorization successful</h1><p>You can close this tab.</p></body></html>');
-                server.close();
-                resolve(code);
+                finish(() => {
+                    res.writeHead(200, { 'Content-Type': 'text/html' });
+                    res.end('<html><body><h1>Authorization successful</h1><p>You can close this tab.</p></body></html>');
+                    resolve(code);
+                });
             }
             else {
-                clearTimeout(timer);
                 const msg = (error ?? reqUrl.searchParams.get('error_description') ?? 'Unknown error')
                     .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-                res.writeHead(400, { 'Content-Type': 'text/html' });
-                res.end(`<html><body><h1>Authorization failed</h1><p>${msg}</p></body></html>`);
-                server.close();
-                reject(new Error(`OAuth error: ${msg}`));
+                finish(() => {
+                    res.writeHead(400, { 'Content-Type': 'text/html' });
+                    res.end(`<html><body><h1>Authorization failed</h1><p>${msg}</p></body></html>`);
+                    reject(new Error(`OAuth error: ${msg}`));
+                });
             }
         });
     });
@@ -216,31 +603,55 @@ export class OAuthClient {
     stored;
     authServerUrl;
     authServerMetadata;
+    resource;
+    protectedResourceScope;
     /** Deduplicates concurrent handleUnauthorized() calls into a single auth flow. */
     pendingAuth = null;
     constructor(options) {
         this.serverUrl = options.serverUrl;
         this.headers = options.headers ?? {};
         this.authTimeout = options.authTimeout ?? DEFAULT_AUTH_TIMEOUT;
+        if (!Number.isFinite(this.authTimeout) || this.authTimeout <= 0) {
+            throw new Error('OAuth authTimeout must be a positive finite number');
+        }
         this.hash = serverHash(options.serverUrl);
     }
+    async runOperation(options, operation) {
+        const bounded = createBoundedOperation(this.authTimeout, options?.signal);
+        try {
+            return await operation(bounded.signal);
+        }
+        finally {
+            bounded.dispose();
+        }
+    }
     /**
-     * Get a valid access token, loading from disk cache if available.
+     * Get a cached access token only after binding it to the authorization
+     * server currently discovered for this protected resource.
      */
-    async getAccessToken() {
-        this.stored ??= await loadStoredAuth(this.hash);
-        return this.stored?.tokens?.access_token;
+    async getAccessToken(options) {
+        return await this.runOperation(options, async (signal) => {
+            this.stored ??= await loadStoredAuth(this.hash);
+            const storedTokens = this.stored?.tokens;
+            if (!storedTokens?.access_token || typeof storedTokens.token_type !== 'string'
+                || storedTokens.token_type.toLowerCase() !== 'bearer')
+                return undefined;
+            await this.discover(signal);
+            const issuer = this.authServerMetadata?.issuer;
+            return issuer !== undefined && this.stored?.issuer === issuer ? storedTokens.access_token : undefined;
+        });
     }
     /**
      * Handle a 401 response from the remote server.
      * Deduplicates concurrent calls — only one auth flow runs at a time;
      * subsequent callers wait for the same result.
      */
-    async handleUnauthorized(wwwAuthenticate) {
-        if (this.pendingAuth) {
-            return this.pendingAuth;
+    async handleUnauthorized(wwwAuthenticate, options) {
+        const pendingAuth = this.pendingAuth;
+        if (pendingAuth) {
+            return await this.runOperation(options, async (signal) => await awaitWithSignal(pendingAuth, signal));
         }
-        this.pendingAuth = this.executeAuthFlow(wwwAuthenticate);
+        this.pendingAuth = this.runOperation(options, async (signal) => await this.executeAuthFlow(wwwAuthenticate, signal));
         try {
             return await this.pendingAuth;
         }
@@ -248,14 +659,26 @@ export class OAuthClient {
             this.pendingAuth = null;
         }
     }
-    async executeAuthFlow(wwwAuthenticate) {
-        const scope = parseWwwAuthenticateScope(wwwAuthenticate);
-        this.stored ??= await loadStoredAuth(this.hash) ?? {};
+    async executeAuthFlow(wwwAuthenticate, signal) {
+        const challengedScope = parseWwwAuthenticateScope(wwwAuthenticate);
+        const challengedMetadataUrl = challengeMetadataUrl(wwwAuthenticate, this.serverUrl);
+        this.stored ??= await loadStoredAuth(this.hash);
+        this.stored ??= {};
         // Discover auth server
-        await this.discover();
+        await this.discover(signal, challengedMetadataUrl);
+        const issuer = this.getAuthServerIssuer();
+        const scope = this.effectiveScope(challengedScope, issuer);
         // Try refresh first
-        if (this.stored.tokens?.refresh_token && this.stored.clientInfo && this.authServerUrl) {
-            const refreshed = await refreshAccessToken(this.authServerUrl, this.authServerMetadata, this.stored.clientInfo, this.stored.tokens.refresh_token);
+        if (this.stored.tokens?.refresh_token
+            && this.stored.clientInfo
+            && this.authServerUrl
+            && this.stored.issuer === issuer
+            && this.resource
+            && (!challengedScope || isScopeSubset(challengedScope, this.stored.tokens.scope))) {
+            const refreshScope = challengedScope && isScopeSubset(challengedScope, this.stored.tokens.scope)
+                ? challengedScope
+                : undefined;
+            const refreshed = await refreshAccessToken(this.authServerUrl, this.authServerMetadata, this.stored.clientInfo, this.stored.tokens.refresh_token, this.resource, refreshScope, this.stored.tokens.scope, signal);
             if (refreshed) {
                 this.stored.tokens = refreshed;
                 this.stored.tokenSavedAt = new Date().toISOString();
@@ -267,36 +690,56 @@ export class OAuthClient {
         if (!this.authServerUrl) {
             throw new Error('Failed to discover authorization server');
         }
+        if (!this.authServerMetadata?.code_challenge_methods_supported?.includes('S256')) {
+            throw new Error('OAuth authorization server does not advertise PKCE S256 support');
+        }
         // Start callback server on a random port
         const callbackHttpServer = createHttpServer();
         const callbackPort = await listenOnRandomPort(callbackHttpServer);
         const redirectUri = `http://127.0.0.1:${String(callbackPort)}/oauth/callback`;
         try {
-            // Register client (or re-register if redirect_uri changed)
-            if (!this.stored.clientInfo?.redirect_uris?.includes(redirectUri)) {
-                this.stored.clientInfo = await registerClient(this.authServerUrl, this.authServerMetadata, redirectUri);
+            // Do not reuse a registration that was issued by a different authorization server.
+            if (this.stored.issuer !== issuer
+                || !this.stored.clientInfo?.redirect_uris?.includes(redirectUri)) {
+                this.stored.clientInfo = await registerClient(this.authServerUrl, this.authServerMetadata, redirectUri, signal);
             }
             // PKCE
             const codeVerifier = generateCodeVerifier();
             const codeChallenge = generateCodeChallenge(codeVerifier);
+            const state = generateState();
             // Build authorization URL
-            const authEndpoint = this.authServerMetadata?.authorization_endpoint
-                ?? new URL('/authorize', this.authServerUrl).toString();
+            const authEndpoint = validateOAuthEndpoint(this.authServerMetadata.authorization_endpoint
+                ?? new URL('/authorize', this.authServerUrl).toString(), 'authorization');
             const authUrl = new URL(authEndpoint);
             authUrl.searchParams.set('response_type', 'code');
             authUrl.searchParams.set('client_id', this.stored.clientInfo.client_id);
             authUrl.searchParams.set('redirect_uri', redirectUri);
             authUrl.searchParams.set('code_challenge', codeChallenge);
             authUrl.searchParams.set('code_challenge_method', 'S256');
+            authUrl.searchParams.set('state', state);
+            authUrl.searchParams.set('resource', this.resource ?? normalizeResourceUrl(this.serverUrl));
             if (scope)
                 authUrl.searchParams.set('scope', scope);
             // Open browser and wait for callback
             process.stderr.write(`Opening browser for authorization...\n`);
+            const callback = waitForOAuthCallback(callbackHttpServer, callbackPort, state, issuer, this.authServerMetadata.authorization_response_iss_parameter_supported === true, signal);
             openBrowser(authUrl.toString());
-            const code = await waitForOAuthCallback(callbackHttpServer, callbackPort, this.authTimeout);
+            const code = await callback;
             // Exchange code for tokens
-            const tokens = await exchangeCodeForTokens(this.authServerUrl, this.authServerMetadata, this.stored.clientInfo, code, codeVerifier, redirectUri);
+            const tokens = await exchangeCodeForTokens(this.authServerUrl, this.authServerMetadata, this.stored.clientInfo, code, codeVerifier, redirectUri, this.resource ?? normalizeResourceUrl(this.serverUrl), signal);
+            // The token response may omit scope when it matches the authorization
+            // request. Persist that effective grant rather than losing it.
+            if (!tokens.scope && scope)
+                tokens.scope = scope;
+            if (tokens.scope && scope && !isScopeSubset(tokens.scope, scope)) {
+                throw new Error('OAuth token response scope exceeds the authorization request');
+            }
             this.stored.tokens = tokens;
+            this.stored.issuer = issuer;
+            if (scope)
+                this.stored.requestedScope = scope;
+            else
+                delete this.stored.requestedScope;
             this.stored.tokenSavedAt = new Date().toISOString();
             await saveStoredAuth(this.hash, this.stored);
             return tokens.access_token;
@@ -305,13 +748,49 @@ export class OAuthClient {
             callbackHttpServer.close();
         }
     }
-    async discover() {
-        if (this.authServerUrl)
+    async discover(signal, challengedMetadataUrl) {
+        // A 401 challenge can name a current protected-resource metadata document
+        // after an earlier cached-token lookup populated discovery state. Re-read
+        // and validate it so its authorization server and scopes govern this flow.
+        if (this.authServerUrl && !challengedMetadataUrl)
             return;
-        const resourceMeta = await discoverProtectedResource(this.serverUrl, this.headers);
+        const resourceMeta = await discoverProtectedResource(this.serverUrl, signal, this.headers, challengedMetadataUrl);
         const firstServer = resourceMeta?.authorization_servers?.[0];
-        this.authServerUrl = firstServer ?? new URL('/', this.serverUrl).toString();
-        this.authServerMetadata = await discoverAuthServer(this.authServerUrl);
+        const authServerUrl = firstServer === undefined
+            ? validateAuthorizationServerIssuer(new URL(this.serverUrl).origin)
+            : validateAuthorizationServerIssuer(firstServer);
+        const resource = resourceMeta?.resource ?? normalizeResourceUrl(this.serverUrl);
+        const authServerMetadata = await discoverAuthServer(authServerUrl, signal);
+        throwIfAborted(signal);
+        this.authServerUrl = authServerUrl;
+        this.resource = resource;
+        this.protectedResourceScope = metadataScopes(resourceMeta?.scopes_supported);
+        this.authServerMetadata = authServerMetadata;
+    }
+    /**
+     * A Bearer challenge is authoritative. For a step-up request retain the
+     * existing grant/request and add the challenged scopes. On the first flow,
+     * protected-resource metadata supplies the only discovery fallback.
+     */
+    effectiveScope(challengedScope, issuer) {
+        const sameIssuer = this.stored?.issuer === issuer;
+        if (challengedScope) {
+            return sameIssuer
+                ? unionScopes(this.stored?.tokens?.scope, this.stored?.requestedScope, challengedScope)
+                : challengedScope;
+        }
+        return sameIssuer
+            ? unionScopes(this.stored?.tokens?.scope, this.stored?.requestedScope)
+            : this.protectedResourceScope;
+    }
+    getAuthServerIssuer() {
+        if (!this.authServerUrl) {
+            throw new Error('Failed to discover authorization server');
+        }
+        if (!this.authServerMetadata?.issuer) {
+            throw new Error('OAuth authorization-server metadata has no issuer');
+        }
+        return this.authServerMetadata.issuer;
     }
 }
 //# sourceMappingURL=oauth.js.map