@agent-deck/backend 1.1.4 → 1.1.6

package/dist/lib/mcp-oauth-discovery.js

@@ -0,0 +1,161 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoverMcpOAuthRequirements = discoverMcpOAuthRequirements;
+const oauth_provider_guides_1 = require("../data/oauth-provider-guides");
+function finalizeOAuthDiscovery(serviceUrl, oauth, authServers = []) {
+    const provider = oauth.provider ?? (0, oauth_provider_guides_1.inferOAuthProvider)(serviceUrl, authServers);
+    const setupMode = (0, oauth_provider_guides_1.resolveOAuthSetupMode)(provider, oauth.supportsDynamicRegistration);
+    return {
+        ...oauth,
+        provider,
+        setupMode,
+        supportsDynamicRegistration: setupMode === 'dynamic' ? true : oauth.supportsDynamicRegistration ?? false,
+    };
+}
+function protectedResourceCandidates(serviceUrl) {
+    const parsed = new URL(serviceUrl);
+    const path = parsed.pathname.replace(/\/$/, '');
+    const candidates = new Set([
+        `${parsed.origin}/.well-known/oauth-protected-resource`,
+    ]);
+    if (path && path !== '/') {
+        candidates.add(`${parsed.origin}/.well-known/oauth-protected-resource${path}`);
+        candidates.add(`${parsed.origin}/.well-known/oauth-protected-resource${path}/`);
+    }
+    return [...candidates];
+}
+async function fetchJson(url) {
+    try {
+        const response = await fetch(url, {
+            headers: { Accept: 'application/json' },
+        });
+        if (!response.ok) {
+            return null;
+        }
+        return response.json();
+    }
+    catch {
+        return null;
+    }
+}
+async function fetchAuthorizationServerMetadata(issuerOrAsUrl) {
+    const trimmed = issuerOrAsUrl.replace(/\/$/, '');
+    const candidates = trimmed.includes('/.well-known/')
+        ? [trimmed]
+        : [
+            `${trimmed}/.well-known/oauth-authorization-server`,
+            `${trimmed}/.well-known/openid-configuration`,
+        ];
+    for (const candidate of candidates) {
+        const data = await fetchJson(candidate);
+        if (data && typeof data === 'object') {
+            return data;
+        }
+    }
+    return null;
+}
+function applyKnownProviderFallbacks(serviceUrl, authServers, oauth) {
+    if (authServers.some((server) => server.includes('github.com/login/oauth'))) {
+        return finalizeOAuthDiscovery(serviceUrl, {
+            ...oauth,
+            required: true,
+            provider: 'github',
+            authorizationUrl: 'https://github.com/login/oauth/authorize',
+            tokenUrl: 'https://github.com/login/oauth/access_token',
+            supportsDynamicRegistration: false,
+        }, authServers);
+    }
+    return finalizeOAuthDiscovery(serviceUrl, oauth, authServers);
+}
+async function resolveFromProtectedResource(serviceUrl, metadata) {
+    const oauth = {
+        required: true,
+        resourceName: metadata.resource_name ?? metadata.resource,
+        scopesSupported: metadata.scopes_supported ?? [],
+        bearerMethodsSupported: metadata.bearer_methods_supported ?? [],
+    };
+    const authServers = metadata.authorization_servers ?? [];
+    if (authServers.length === 0) {
+        return finalizeOAuthDiscovery(serviceUrl, oauth, authServers);
+    }
+    const asMeta = await fetchAuthorizationServerMetadata(authServers[0]);
+    if (asMeta) {
+        oauth.issuer = asMeta.issuer;
+        oauth.authorizationUrl = asMeta.authorization_endpoint;
+        oauth.tokenUrl = asMeta.token_endpoint;
+        oauth.scopesSupported = asMeta.scopes_supported ?? oauth.scopesSupported;
+        oauth.supportsDynamicRegistration = Boolean(asMeta.registration_endpoint);
+    }
+    return applyKnownProviderFallbacks(serviceUrl, authServers, oauth);
+}
+async function probeWwwAuthenticate(serviceUrl) {
+    const headers = {
+        Accept: 'application/json, text/event-stream',
+        'Content-Type': 'application/json',
+    };
+    for (const method of ['GET', 'POST']) {
+        try {
+            const init = method === 'GET'
+                ? { method, headers: { Accept: headers.Accept } }
+                : {
+                    method,
+                    headers,
+                    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list', params: {} }),
+                };
+            const response = await fetch(serviceUrl, init);
+            const wwwAuth = response.headers.get('www-authenticate');
+            if (wwwAuth) {
+                return wwwAuth;
+            }
+        }
+        catch {
+            // try next method
+        }
+    }
+    return null;
+}
+function parseResourceMetadataUrl(wwwAuthenticate) {
+    const match = wwwAuthenticate.match(/resource_metadata="([^"]+)"/i);
+    return match?.[1] ?? null;
+}
+async function discoverMcpOAuthRequirements(serviceUrl) {
+    const oauth = { required: false };
+    try {
+        for (const candidate of protectedResourceCandidates(serviceUrl)) {
+            const data = await fetchJson(candidate);
+            if (data && typeof data === 'object') {
+                return resolveFromProtectedResource(serviceUrl, data);
+            }
+        }
+        const parsed = new URL(serviceUrl);
+        const asData = await fetchAuthorizationServerMetadata(parsed.origin);
+        if (asData?.authorization_endpoint) {
+            return finalizeOAuthDiscovery(serviceUrl, {
+                required: true,
+                issuer: asData.issuer,
+                authorizationUrl: asData.authorization_endpoint,
+                tokenUrl: asData.token_endpoint,
+                scopesSupported: asData.scopes_supported ?? [],
+                supportsDynamicRegistration: Boolean(asData.registration_endpoint),
+            });
+        }
+        const wwwAuth = await probeWwwAuthenticate(serviceUrl);
+        if (wwwAuth) {
+            const resourceMetadataUrl = parseResourceMetadataUrl(wwwAuth);
+            if (resourceMetadataUrl) {
+                const data = await fetchJson(resourceMetadataUrl);
+                if (data && typeof data === 'object') {
+                    return resolveFromProtectedResource(serviceUrl, data);
+                }
+            }
+            if (wwwAuth.toLowerCase().includes('oauth') || wwwAuth.toLowerCase().includes('bearer')) {
+                return finalizeOAuthDiscovery(serviceUrl, { required: true });
+            }
+        }
+    }
+    catch (error) {
+        oauth.error = error instanceof Error ? error.message : 'OAuth detection failed';
+    }
+    return oauth;
+}
+//# sourceMappingURL=mcp-oauth-discovery.js.map

package/dist/lib/mcp-oauth-discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-oauth-discovery.js","sourceRoot":"","sources":["../../src/lib/mcp-oauth-discovery.ts"],"names":[],"mappings":";;AAuLA,oEA2CC;AAlOD,yEAIuC;AAgCvC,SAAS,sBAAsB,CAC7B,UAAkB,EAClB,KAAwB,EACxB,cAAwB,EAAE;IAE1B,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,IAAA,0CAAkB,EAAC,UAAU,EAAE,WAAW,CAAC,CAAC;IAC/E,MAAM,SAAS,GAAG,IAAA,6CAAqB,EAAC,QAAQ,EAAE,KAAK,CAAC,2BAA2B,CAAC,CAAC;IACrF,OAAO;QACL,GAAG,KAAK;QACR,QAAQ;QACR,SAAS;QACT,2BAA2B,EACzB,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,2BAA2B,IAAI,KAAK;KAC9E,CAAC;AACJ,CAAC;AAED,SAAS,2BAA2B,CAAC,UAAkB;IACrD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAChD,MAAM,UAAU,GAAG,IAAI,GAAG,CAAS;QACjC,GAAG,MAAM,CAAC,MAAM,uCAAuC;KACxD,CAAC,CAAC;IAEH,IAAI,IAAI,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;QACzB,UAAU,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,wCAAwC,IAAI,EAAE,CAAC,CAAC;QAC/E,UAAU,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,wCAAwC,IAAI,GAAG,CAAC,CAAC;IAClF,CAAC;IAED,OAAO,CAAC,GAAG,UAAU,CAAC,CAAC;AACzB,CAAC;AAED,KAAK,UAAU,SAAS,CAAC,GAAW;IAClC,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAChC,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE;SACxC,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,KAAK,UAAU,gCAAgC,CAC7C,aAAqB;IAErB,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACjD,MAAM,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC;QAClD,CAAC,CAAC,CAAC,OAAO,CAAC;QACX,CAAC,CAAC;YACE,GAAG,OAAO,yCAAyC;YACnD,GAAG,OAAO,mCAAmC;SAC9C,CAAC;IAEN,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,SAAS,CAAC,CAAC;QACxC,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YACrC,OAAO,IAAmC,CAAC;QAC7C,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,2BAA2B,CAClC,UAAkB,EAClB,WAAqB,EACrB,KAAwB;IAExB,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,wBAAwB,CAAC,CAAC,EAAE,CAAC;QAC5E,OAAO,sBAAsB,CAAC,UAAU,EAAE;YACxC,GAAG,KAAK;YACR,QAAQ,EAAE,IAAI;YACd,QAAQ,EAAE,QAAQ;YAClB,gBAAgB,EAAE,0CAA0C;YAC5D,QAAQ,EAAE,6CAA6C;YACvD,2BAA2B,EAAE,KAAK;SACnC,EAAE,WAAW,CAAC,CAAC;IAClB,CAAC;IAED,OAAO,sBAAsB,CAAC,UAAU,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;AAChE,CAAC;AAED,KAAK,UAAU,4BAA4B,CACzC,UAAkB,EAClB,QAAmC;IAEnC,MAAM,KAAK,GAAsB;QAC/B,QAAQ,EAAE,IAAI;QACd,YAAY,EAAE,QAAQ,CAAC,aAAa,IAAI,QAAQ,CAAC,QAAQ;QACzD,eAAe,EAAE,QAAQ,CAAC,gBAAgB,IAAI,EAAE;QAChD,sBAAsB,EAAE,QAAQ,CAAC,wBAAwB,IAAI,EAAE;KAChE,CAAC;IAEF,MAAM,WAAW,GAAG,QAAQ,CAAC,qBAAqB,IAAI,EAAE,CAAC;IACzD,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,sBAAsB,CAAC,UAAU,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;IAChE,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,gCAAgC,CAAC,WAAW,CAAC,CAAC,CAAE,CAAC,CAAC;IACvE,IAAI,MAAM,EAAE,CAAC;QACX,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC7B,KAAK,CAAC,gBAAgB,GAAG,MAAM,CAAC,sBAAsB,CAAC;QACvD,KAAK,CAAC,QAAQ,GAAG,MAAM,CAAC,cAAc,CAAC;QACvC,KAAK,CAAC,eAAe,GAAG,MAAM,CAAC,gBAAgB,IAAI,KAAK,CAAC,eAAe,CAAC;QACzE,KAAK,CAAC,2BAA2B,GAAG,OAAO,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC;IAC5E,CAAC;IAED,OAAO,2BAA2B,CAAC,UAAU,EAAE,WAAW,EAAE,KAAK,CAAC,CAAC;AACrE,CAAC;AAED,KAAK,UAAU,oBAAoB,CAAC,UAAkB;IACpD,MAAM,OAAO,GAAG;QACd,MAAM,EAAE,qCAAqC;QAC7C,cAAc,EAAE,kBAAkB;KACnC,CAAC;IAEF,KAAK,MAAM,MAAM,IAAI,CAAC,KAAK,EAAE,MAAM,CAAU,EAAE,CAAC;QAC9C,IAAI,CAAC;YACH,MAAM,IAAI,GACR,MAAM,KAAK,KAAK;gBACd,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,EAAE;gBACjD,CAAC,CAAC;oBACE,MAAM;oBACN,OAAO;oBACP,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;iBAClF,CAAC;YACR,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;YAC/C,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;YACzD,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO,OAAO,CAAC;YACjB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,kBAAkB;QACpB,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,wBAAwB,CAAC,eAAuB;IACvD,MAAM,KAAK,GAAG,eAAe,CAAC,KAAK,CAAC,8BAA8B,CAAC,CAAC;IACpE,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;AAC5B,CAAC;AAEM,KAAK,UAAU,4BAA4B,CAAC,UAAkB;IACnE,MAAM,KAAK,GAAsB,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IAErD,IAAI,CAAC;QACH,KAAK,MAAM,SAAS,IAAI,2BAA2B,CAAC,UAAU,CAAC,EAAE,CAAC;YAChE,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,SAAS,CAAC,CAAC;YACxC,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACrC,OAAO,4BAA4B,CAAC,UAAU,EAAE,IAAiC,CAAC,CAAC;YACrF,CAAC;QACH,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;QACnC,MAAM,MAAM,GAAG,MAAM,gCAAgC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACrE,IAAI,MAAM,EAAE,sBAAsB,EAAE,CAAC;YACnC,OAAO,sBAAsB,CAAC,UAAU,EAAE;gBACxC,QAAQ,EAAE,IAAI;gBACd,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,gBAAgB,EAAE,MAAM,CAAC,sBAAsB;gBAC/C,QAAQ,EAAE,MAAM,CAAC,cAAc;gBAC/B,eAAe,EAAE,MAAM,CAAC,gBAAgB,IAAI,EAAE;gBAC9C,2BAA2B,EAAE,OAAO,CAAC,MAAM,CAAC,qBAAqB,CAAC;aACnE,CAAC,CAAC;QACL,CAAC;QAED,MAAM,OAAO,GAAG,MAAM,oBAAoB,CAAC,UAAU,CAAC,CAAC;QACvD,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,mBAAmB,GAAG,wBAAwB,CAAC,OAAO,CAAC,CAAC;YAC9D,IAAI,mBAAmB,EAAE,CAAC;gBACxB,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,mBAAmB,CAAC,CAAC;gBAClD,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;oBACrC,OAAO,4BAA4B,CAAC,UAAU,EAAE,IAAiC,CAAC,CAAC;gBACrF,CAAC;YACH,CAAC;YAED,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACxF,OAAO,sBAAsB,CAAC,UAAU,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;YAChE,CAAC;QACH,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,KAAK,CAAC,KAAK,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,wBAAwB,CAAC;IAClF,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/lib/oauth-token-response.d.ts

@@ -0,0 +1,11 @@
+export type OAuthTokenResponseBody = {
+    access_token: string;
+    refresh_token?: string;
+    expires_in?: number;
+    token_type?: string;
+    scope?: string;
+};
+/** Parse OAuth token endpoint body (JSON or application/x-www-form-urlencoded). */
+export declare function parseOAuthTokenResponse(response: Response): Promise<OAuthTokenResponseBody>;
+export declare function oauthTokenRequestHeaders(): Record<string, string>;
+//# sourceMappingURL=oauth-token-response.d.ts.map

package/dist/lib/oauth-token-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-token-response.d.ts","sourceRoot":"","sources":["../../src/lib/oauth-token-response.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,sBAAsB,GAAG;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,mFAAmF;AACnF,wBAAsB,uBAAuB,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,sBAAsB,CAAC,CA0CjG;AAED,wBAAgB,wBAAwB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKjE"}

package/dist/lib/oauth-token-response.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseOAuthTokenResponse = parseOAuthTokenResponse;
+exports.oauthTokenRequestHeaders = oauthTokenRequestHeaders;
+/** Parse OAuth token endpoint body (JSON or application/x-www-form-urlencoded). */
+async function parseOAuthTokenResponse(response) {
+    const contentType = response.headers.get('content-type') ?? '';
+    const text = await response.text();
+    const trimmed = text.trim();
+    if (!trimmed) {
+        throw new Error('OAuth token response was empty');
+    }
+    if (contentType.includes('application/json') || trimmed.startsWith('{')) {
+        const data = JSON.parse(trimmed);
+        if (data.error) {
+            throw new Error(`OAuth token error: ${data.error}${data.error_description ? ` — ${data.error_description}` : ''}`);
+        }
+        if (!data.access_token) {
+            throw new Error('OAuth token JSON response missing access_token');
+        }
+        return data;
+    }
+    const params = new URLSearchParams(trimmed);
+    const oauthError = params.get('error');
+    if (oauthError) {
+        const description = params.get('error_description');
+        throw new Error(`OAuth token error: ${oauthError}${description ? ` — ${description}` : ''}`);
+    }
+    const accessToken = params.get('access_token');
+    if (!accessToken) {
+        throw new Error(`OAuth token response missing access_token: ${trimmed.slice(0, 200)}`);
+    }
+    const expiresIn = params.get('expires_in');
+    return {
+        access_token: accessToken,
+        refresh_token: params.get('refresh_token') ?? undefined,
+        expires_in: expiresIn ? Number(expiresIn) : undefined,
+        token_type: params.get('token_type') ?? undefined,
+        scope: params.get('scope') ?? undefined,
+    };
+}
+function oauthTokenRequestHeaders() {
+    return {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Accept: 'application/json',
+    };
+}
+//# sourceMappingURL=oauth-token-response.js.map

package/dist/lib/oauth-token-response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-token-response.js","sourceRoot":"","sources":["../../src/lib/oauth-token-response.ts"],"names":[],"mappings":";;AASA,0DA0CC;AAED,4DAKC;AAlDD,mFAAmF;AAC5E,KAAK,UAAU,uBAAuB,CAAC,QAAkB;IAC9D,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;IAC/D,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAE5B,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IAED,IAAI,WAAW,CAAC,QAAQ,CAAC,kBAAkB,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACxE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAA4E,CAAC;QAC5G,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACb,sBAAsB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAClG,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACpE,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACvC,IAAI,UAAU,EAAE,CAAC;QACf,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,sBAAsB,UAAU,GAAG,WAAW,CAAC,CAAC,CAAC,MAAM,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC/F,CAAC;IAED,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAC/C,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,8CAA8C,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;IACzF,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC3C,OAAO;QACL,YAAY,EAAE,WAAW;QACzB,aAAa,EAAE,MAAM,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,SAAS;QACvD,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS;QACrD,UAAU,EAAE,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,SAAS;QACjD,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,SAAS;KACxC,CAAC;AACJ,CAAC;AAED,SAAgB,wBAAwB;IACtC,OAAO;QACL,cAAc,EAAE,mCAAmC;QACnD,MAAM,EAAE,kBAAkB;KAC3B,CAAC;AACJ,CAAC"}

package/dist/lib/pkce.d.ts

@@ -0,0 +1,7 @@
+export interface PkcePair {
+    codeVerifier: string;
+    codeChallenge: string;
+}
+/** RFC 7636 PKCE with S256 code challenge. */
+export declare function generatePkcePair(): PkcePair;
+//# sourceMappingURL=pkce.d.ts.map

package/dist/lib/pkce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.d.ts","sourceRoot":"","sources":["../../src/lib/pkce.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,QAAQ;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,8CAA8C;AAC9C,wBAAgB,gBAAgB,IAAI,QAAQ,CAI3C"}

package/dist/lib/pkce.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generatePkcePair = generatePkcePair;
+const crypto_1 = require("crypto");
+/** RFC 7636 PKCE with S256 code challenge. */
+function generatePkcePair() {
+    const codeVerifier = (0, crypto_1.randomBytes)(32).toString('base64url');
+    const codeChallenge = (0, crypto_1.createHash)('sha256').update(codeVerifier).digest('base64url');
+    return { codeVerifier, codeChallenge };
+}
+//# sourceMappingURL=pkce.js.map

package/dist/lib/pkce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.js","sourceRoot":"","sources":["../../src/lib/pkce.ts"],"names":[],"mappings":";;AAQA,4CAIC;AAZD,mCAAiD;AAOjD,8CAA8C;AAC9C,SAAgB,gBAAgB;IAC9B,MAAM,YAAY,GAAG,IAAA,oBAAW,EAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC3D,MAAM,aAAa,GAAG,IAAA,mBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IACpF,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,CAAC;AACzC,CAAC"}

package/dist/mcp-server.d.ts

@@ -6,15 +6,16 @@ export declare class AgentDeckMCPServer {
     private sessions;
     /** Set only while registerTools/registerResources run for a new session server. */
     private mcpServerForRegistration;
-    /** Workspace root per MCP session → resolves `.agent-deck/deck.yaml`. */
-    private workspaceBySession;
+    /** Per-session workspace + optional deck override (see mcp-session-binding.ts). */
+    private sessionBinding;
     private activeSessionId;
     private get server();
     constructor(port?: number, backendUrl?: string);
     private createMcpServer;
     private getSessionId;
-    private getBoundWorkspace;
     private getAgentHeaders;
+    private fetchDeck;
+    private buildBindingPayload;
     private callBackendAPI;
     private getBoundDeckId;
     private toolResult;

package/dist/mcp-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"AAQA,OAAO,OAA8B,MAAM,SAAS,CAAC;AAuBrD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,GAAG,CAAsB;IACjC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAiC;IACjD,mFAAmF;IACnF,OAAO,CAAC,wBAAwB,CAAwB;IACxD,yEAAyE;IACzE,OAAO,CAAC,kBAAkB,CAA6B;IACvD,OAAO,CAAC,eAAe,CAAqB;IAE5C,OAAO,KAAK,MAAM,GAKjB;gBAEW,IAAI,GAAE,MAAa,EAAE,UAAU,GAAE,MAAgC;IAc7E,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,iBAAiB;IAKzB,OAAO,CAAC,eAAe;YAQT,cAAc;YAwCd,cAAc;IAQ5B,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,UAAU;IA8wBlB,OAAO,CAAC,cAAc;IA2LtB,OAAO,CAAC,WAAW;IA2CnB,OAAO,CAAC,kBAAkB;YAKZ,aAAa;YAuDb,uBAAuB;IAiB/B,KAAK;IAiCL,IAAI;CAeX"}
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"AAQA,OAAO,OAA8B,MAAM,SAAS,CAAC;AA0BrD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,GAAG,CAAsB;IACjC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAiC;IACjD,mFAAmF;IACnF,OAAO,CAAC,wBAAwB,CAAwB;IACxD,mFAAmF;IACnF,OAAO,CAAC,cAAc,CAAyB;IAC/C,OAAO,CAAC,eAAe,CAAqB;IAE5C,OAAO,KAAK,MAAM,GAKjB;gBAEW,IAAI,GAAE,MAAa,EAAE,UAAU,GAAE,MAAgC;IAc7E,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,eAAe;YAIT,SAAS;YAkBT,mBAAmB;YAYnB,cAAc;YAwCd,cAAc;IAQ5B,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,UAAU;IAm2BlB,OAAO,CAAC,cAAc;IA2LtB,OAAO,CAAC,WAAW;IA2CnB,OAAO,CAAC,kBAAkB;YAKZ,aAAa;YAuDb,uBAAuB;IAiB/B,KAAK;IAmCL,IAAI;CAeX"}

package/dist/mcp-server.js

@@ -14,8 +14,8 @@ const promises_1 = __importDefault(require("node:fs/promises"));
 const node_path_1 = __importDefault(require("node:path"));
 const zod_1 = require("zod");
 const repo_deck_1 = require("./scope/repo-deck");
-const shared_2 = require("@agent-deck/shared");
 const version_1 = require("./lib/version");
+const mcp_session_binding_1 = require("./mcp-session-binding");
 const agentClientHeaders = {
     [shared_1.AGENT_DECK_CLIENT_HEADER]: shared_1.AGENT_DECK_AGENT_CLIENT,
     Accept: 'application/json',
@@ -27,8 +27,8 @@ class AgentDeckMCPServer {
     sessions = new Map();
     /** Set only while registerTools/registerResources run for a new session server. */
     mcpServerForRegistration;
-    /** Workspace root per MCP session → resolves `.agent-deck/deck.yaml`. */
-    workspaceBySession = new Map();
+    /** Per-session workspace + optional deck override (see mcp-session-binding.ts). */
+    sessionBinding;
     activeSessionId;
     get server() {
         if (!this.mcpServerForRegistration) {
@@ -42,10 +42,10 @@ class AgentDeckMCPServer {
         this.app = (0, express_1.default)();
         this.app.use(express_1.default.json());
         this.setupRoutes();
-        const envWorkspace = process.env.AGENT_DECK_WORKSPACE?.trim();
-        if (envWorkspace) {
-            this.workspaceBySession.set('default', envWorkspace);
-        }
+        this.sessionBinding = new mcp_session_binding_1.McpSessionBindingStore({
+            workspace: process.env.AGENT_DECK_WORKSPACE,
+            deckId: process.env.AGENT_DECK_DECK_ID,
+        });
     }
     createMcpServer() {
         this.mcpServerForRegistration = new mcp_js_1.McpServer({
@@ -61,15 +61,31 @@ class AgentDeckMCPServer {
     getSessionId() {
         return this.activeSessionId ?? 'default';
     }
-    getBoundWorkspace() {
-        const sessionId = this.getSessionId();
-        return this.workspaceBySession.get(sessionId) ?? process.env.AGENT_DECK_WORKSPACE?.trim();
-    }
     getAgentHeaders() {
-        const workspace = this.getBoundWorkspace();
+        return this.sessionBinding.getAgentHeaders(this.getSessionId());
+    }
+    async fetchDeck(deckId) {
+        const deck = await fetch(`${this.backendUrl}/api/decks/${deckId}`, {
+            headers: {
+                ...agentClientHeaders,
+                Accept: 'application/json',
+            },
+        });
+        const body = (await deck.json());
+        if (!deck.ok || !body.success || !body.data?.id) {
+            throw new Error(body.error ?? `Deck not found: ${deckId}`);
+        }
+        return body.data;
+    }
+    async buildBindingPayload(sessionId, manifestDeckId) {
+        const snapshot = this.sessionBinding.getBinding(sessionId);
+        const deck = await this.callBackendAPI('/api/scope/deck');
         return {
-            ...agentClientHeaders,
-            ...(workspace ? { [shared_1.AGENT_DECK_WORKSPACE_HEADER]: workspace } : {}),
+            workspaceRoot: snapshot.workspaceRoot,
+            deck_id: deck?.id,
+            deck_name: deck?.name,
+            deck_source: (0, mcp_session_binding_1.resolveDeckBindingSource)(snapshot, manifestDeckId),
+            session_deck_override: this.sessionBinding.hasSessionDeckOverride(sessionId),
         };
     }
     async callBackendAPI(endpoint, init = {}) {
@@ -116,7 +132,7 @@ class AgentDeckMCPServer {
     async getBoundDeckId() {
         const deck = await this.callBackendAPI('/api/scope/deck');
         if (!deck?.id) {
-            throw new Error('No bound deck — call bind_workspace or setup_repo_deck first');
+            throw new Error('No bound deck — call bind_workspace (optionally with deckId) or switch_bound_deck first');
         }
         return deck.id;
     }
@@ -129,12 +145,31 @@ class AgentDeckMCPServer {
     setupTools() {
         this.server.registerTool("bind_workspace", {
             title: "Bind Workspace",
-            description: "Bind an MCP session to a repo workspace root. Reads .agent-deck/deck.yaml to resolve the deck for this project.",
-            inputSchema: { workspaceRoot: zod_1.z.string() },
-        }, async ({ workspaceRoot }) => {
+            description: "Bind this MCP session to a workspace root. Pass deckId for a session-only deck override (same path, different concurrent agents). Without deckId, uses .agent-deck/deck.yaml when present.",
+            inputSchema: {
+                workspaceRoot: zod_1.z.string(),
+                deckId: zod_1.z.string().uuid().optional(),
+            },
+        }, async ({ workspaceRoot, deckId }) => {
             try {
                 const sessionId = this.getSessionId();
-                this.workspaceBySession.set(sessionId, workspaceRoot);
+                this.sessionBinding.setWorkspace(sessionId, workspaceRoot);
+                if (deckId) {
+                    const deck = await this.fetchDeck(deckId);
+                    this.sessionBinding.setDeckId(sessionId, deckId);
+                    const payload = await this.buildBindingPayload(sessionId);
+                    return {
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify({
+                                    ...payload,
+                                    deck_name: deck.name,
+                                    message: 'Session bound with deck override. .agent-deck/deck.yaml is unchanged; other MCP sessions can use a different deck at the same path.',
+                                }, null, 2),
+                            }],
+                    };
+                }
+                this.sessionBinding.clearDeckId(sessionId);
                 const resolved = await fetch(`${this.backendUrl}/api/scope/resolve`, {
                     method: 'POST',
                     headers: { ...agentClientHeaders, 'Content-Type': 'application/json' },
@@ -142,31 +177,90 @@ class AgentDeckMCPServer {
                 });
                 const body = (await resolved.json());
                 if (!body.success || !body.data) {
-                    throw new Error(body.error ?? 'Failed to resolve workspace deck');
+                    throw new Error(body.error ??
+                        'Failed to resolve workspace deck. Pass deckId to bind without deck.yaml, or call setup_repo_deck.');
                 }
                 const { data } = body;
+                const payload = await this.buildBindingPayload(sessionId, data.manifest.deck_id);
                 return {
                     content: [{
                             type: "text",
                             text: JSON.stringify({
-                                workspaceRoot,
+                                ...payload,
                                 manifestPath: data.manifestPath,
-                                deck_id: data.manifest.deck_id,
-                                deck_name: data.deck.name,
+                                message: 'Session bound via .agent-deck/deck.yaml.',
                             }, null, 2),
                         }],
                 };
             }
             catch (error) {
                 const message = String(error);
-                const hint = message.includes('deck.yaml')
-                    ? ' Call setup_repo_deck with workspaceRoot and deckId to create .agent-deck/deck.yaml, or get_repo_deck_status to diagnose.'
+                const hint = message.includes('deck.yaml') || message.includes('No .agent-deck')
+                    ? ' Pass deckId on bind_workspace, call setup_repo_deck, or get_repo_deck_status to diagnose.'
                     : '';
                 return {
                     content: [{ type: "text", text: JSON.stringify({ error: message + hint }, null, 2) }],
                 };
             }
         });
+        this.server.registerTool("switch_bound_deck", {
+            title: "Switch Bound Deck",
+            description: "Switch the deck for this MCP session only. Does not modify .agent-deck/deck.yaml. Use when multiple agent sessions share the same workspace path.",
+            inputSchema: { deckId: zod_1.z.string().uuid() },
+        }, async ({ deckId }) => {
+            try {
+                const sessionId = this.getSessionId();
+                const deck = await this.fetchDeck(deckId);
+                this.sessionBinding.setDeckId(sessionId, deckId);
+                const payload = await this.buildBindingPayload(sessionId);
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                ...payload,
+                                deck_name: deck.name,
+                                message: 'Session deck switched. Other sessions and deck.yaml are unchanged.',
+                            }, null, 2),
+                        }],
+                };
+            }
+            catch (error) {
+                return this.toolError(error);
+            }
+        });
+        this.server.registerTool("get_session_binding", {
+            title: "Get Session Binding",
+            description: "Show workspace and effective deck for this MCP session, including whether the deck comes from a session override or repo deck.yaml.",
+            inputSchema: {},
+        }, async () => {
+            try {
+                const sessionId = this.getSessionId();
+                const snapshot = this.sessionBinding.getBinding(sessionId);
+                let manifestDeckId;
+                if (snapshot.workspaceRoot && !snapshot.deckSource) {
+                    const manifest = await (0, repo_deck_1.loadRepoDeckManifest)(snapshot.workspaceRoot);
+                    manifestDeckId = manifest?.deck_id;
+                }
+                const deck = await this.callBackendAPI('/api/scope/deck');
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                workspaceRoot: snapshot.workspaceRoot,
+                                session_deck_override: snapshot.deckId,
+                                session_deck_source: snapshot.deckSource,
+                                repo_manifest_deck_id: manifestDeckId,
+                                effective_deck_id: deck?.id,
+                                effective_deck_name: deck?.name,
+                                effective_deck_source: (0, mcp_session_binding_1.resolveDeckBindingSource)(snapshot, manifestDeckId),
+                            }, null, 2),
+                        }],
+                };
+            }
+            catch (error) {
+                return this.toolError(error);
+            }
+        });
         this.server.registerTool("get_repo_deck_status", {
             title: "Get Repo Deck Status",
             description: "Check whether .agent-deck/deck.yaml exists in a workspace and whether it links to a valid deck",
@@ -183,7 +277,7 @@ class AgentDeckMCPServer {
                                 text: JSON.stringify({
                                     status: 'missing',
                                     workspaceRoot,
-                                    expectedPath: shared_2.REPO_DECK_MANIFEST_PATH,
+                                    expectedPath: shared_1.REPO_DECK_MANIFEST_PATH,
                                     message: 'No .agent-deck/deck.yaml found. Use setup_repo_deck to create one.',
                                     availableDecks: Array.isArray(decks)
                                         ? decks.map((d) => ({ id: d.id, name: d.name }))
@@ -232,7 +326,7 @@ class AgentDeckMCPServer {
                 const sessionId = this.getSessionId();
                 const existing = await (0, repo_deck_1.loadRepoDeckManifest)(workspaceRoot);
                 if (existing) {
-                    this.workspaceBySession.set(sessionId, workspaceRoot);
+                    this.sessionBinding.setWorkspace(sessionId, workspaceRoot);
                     const resolved = await fetch(`${this.backendUrl}/api/scope/resolve`, {
                         method: 'POST',
                         headers: { ...agentClientHeaders, 'Content-Type': 'application/json' },
@@ -264,7 +358,7 @@ class AgentDeckMCPServer {
                                 text: JSON.stringify({
                                     status: 'needs_deck_id',
                                     workspaceRoot,
-                                    expectedPath: shared_2.REPO_DECK_MANIFEST_PATH,
+                                    expectedPath: shared_1.REPO_DECK_MANIFEST_PATH,
                                     message: 'Pick a deck id from the dashboard (My Decks → copy icon) and call setup_repo_deck again with deckId.',
                                     availableDecks: Array.isArray(decks)
                                         ? decks.map((d) => ({ id: d.id, name: d.name }))
@@ -284,7 +378,7 @@ class AgentDeckMCPServer {
                     await promises_1.default.mkdir(dirPath, { recursive: true });
                     await promises_1.default.writeFile(filePath, content, 'utf8');
                 }
-                this.workspaceBySession.set(sessionId, workspaceRoot);
+                this.sessionBinding.setWorkspace(sessionId, workspaceRoot);
                 return {
                     content: [{
                             type: "text",
@@ -328,7 +422,7 @@ class AgentDeckMCPServer {
         });
         this.server.registerTool("get_bound_deck", {
             title: "Get Bound Deck",
-            description: "Get the deck bound to this session via bind_workspace or AGENT_DECK_WORKSPACE (.agent-deck/deck.yaml)",
+            description: "Get the deck bound to this session (session deckId override, env, or .agent-deck/deck.yaml)",
             inputSchema: {},
         }, async () => {
             try {
@@ -1121,7 +1215,7 @@ class AgentDeckMCPServer {
             const sessionId = transport.sessionId;
             if (sessionId) {
                 this.sessions.delete(sessionId);
-                this.workspaceBySession.delete(sessionId);
+                this.sessionBinding.clearSession(sessionId);
             }
         };
         await server.connect(transport);
@@ -1152,7 +1246,9 @@ class AgentDeckMCPServer {
             this.app.listen(this.port, () => {
                 console.log(`✅ Agent Deck MCP Server is ready to accept connections`);
                 console.log(`📋 Available tools:`);
-                console.log(`   - bind_workspace: Bind session to repo via .agent-deck/deck.yaml`);
+                console.log(`   - bind_workspace: Bind session to workspace; optional deckId override`);
+                console.log(`   - switch_bound_deck: Switch deck for this session only`);
+                console.log(`   - get_session_binding: Show session workspace + effective deck`);
                 console.log(`   - get_repo_deck_status: Check repo deck manifest`);
                 console.log(`   - setup_repo_deck: Create .agent-deck/deck.yaml for a repo`);
                 console.log(`   - get_bound_deck: Get workspace-bound deck`);