@mcp-z/client 1.0.0

package/dist/cjs/auth/rfc9728-discovery.js

@@ -0,0 +1,436 @@
+/**
+ * RFC 9728 Protected Resource Metadata Discovery
+ * Probes .well-known/oauth-protected-resource endpoint
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get discoverAuthorizationServerMetadata () {
+        return discoverAuthorizationServerMetadata;
+    },
+    get discoverProtectedResourceMetadata () {
+        return discoverProtectedResourceMetadata;
+    }
+});
+function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) {
+    try {
+        var info = gen[key](arg);
+        var value = info.value;
+    } catch (error) {
+        reject(error);
+        return;
+    }
+    if (info.done) {
+        resolve(value);
+    } else {
+        Promise.resolve(value).then(_next, _throw);
+    }
+}
+function _async_to_generator(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
+function _ts_generator(thisArg, body) {
+    var f, y, t, _ = {
+        label: 0,
+        sent: function() {
+            if (t[0] & 1) throw t[1];
+            return t[1];
+        },
+        trys: [],
+        ops: []
+    }, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype), d = Object.defineProperty;
+    return d(g, "next", {
+        value: verb(0)
+    }), d(g, "throw", {
+        value: verb(1)
+    }), d(g, "return", {
+        value: verb(2)
+    }), typeof Symbol === "function" && d(g, Symbol.iterator, {
+        value: function() {
+            return this;
+        }
+    }), g;
+    function verb(n) {
+        return function(v) {
+            return step([
+                n,
+                v
+            ]);
+        };
+    }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while(g && (g = 0, op[0] && (_ = 0)), _)try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [
+                op[0] & 2,
+                t.value
+            ];
+            switch(op[0]){
+                case 0:
+                case 1:
+                    t = op;
+                    break;
+                case 4:
+                    _.label++;
+                    return {
+                        value: op[1],
+                        done: false
+                    };
+                case 5:
+                    _.label++;
+                    y = op[1];
+                    op = [
+                        0
+                    ];
+                    continue;
+                case 7:
+                    op = _.ops.pop();
+                    _.trys.pop();
+                    continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) {
+                        _ = 0;
+                        continue;
+                    }
+                    if (op[0] === 3 && (!t || op[1] > t[0] && op[1] < t[3])) {
+                        _.label = op[1];
+                        break;
+                    }
+                    if (op[0] === 6 && _.label < t[1]) {
+                        _.label = t[1];
+                        t = op;
+                        break;
+                    }
+                    if (t && _.label < t[2]) {
+                        _.label = t[2];
+                        _.ops.push(op);
+                        break;
+                    }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop();
+                    continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) {
+            op = [
+                6,
+                e
+            ];
+            y = 0;
+        } finally{
+            f = t = 0;
+        }
+        if (op[0] & 5) throw op[1];
+        return {
+            value: op[0] ? op[1] : void 0,
+            done: true
+        };
+    }
+}
+/**
+ * Extract origin (protocol + host) from a URL
+ * @param url - Full URL that may include a path
+ * @returns Origin (e.g., "https://example.com") or original string if invalid URL
+ *
+ * @example
+ * getOrigin('https://example.com/mcp') // → 'https://example.com'
+ * getOrigin('http://localhost:9999/api/v1/mcp') // → 'http://localhost:9999'
+ */ function getOrigin(url) {
+    try {
+        return new URL(url).origin;
+    } catch (unused) {
+        // Invalid URL - return as-is for graceful degradation
+        return url;
+    }
+}
+/**
+ * Extract path from a URL (without origin)
+ * @param url - Full URL
+ * @returns Path component (e.g., "/mcp", "/api/v1/mcp") or empty string if no path
+ */ function getPath(url) {
+    try {
+        var parsed = new URL(url);
+        // pathname includes leading slash, e.g., "/mcp"
+        return parsed.pathname === '/' ? '' : parsed.pathname;
+    } catch (unused) {
+        return '';
+    }
+}
+function discoverProtectedResourceMetadata(resourceUrl) {
+    return _async_to_generator(function() {
+        var origin, path, rootUrl, response, metadata, rootMetadata, subPathUrl, subPathResponse, unused, unused1, subPathUrl1, response1, unused2, _error;
+        return _ts_generator(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    _state.trys.push([
+                        0,
+                        19,
+                        ,
+                        20
+                    ]);
+                    origin = getOrigin(resourceUrl);
+                    path = getPath(resourceUrl);
+                    // Strategy 1: Try root location (REQUIRED by RFC 9728)
+                    rootUrl = "".concat(origin, "/.well-known/oauth-protected-resource");
+                    _state.label = 1;
+                case 1:
+                    _state.trys.push([
+                        1,
+                        11,
+                        ,
+                        12
+                    ]);
+                    return [
+                        4,
+                        fetch(rootUrl, {
+                            method: 'GET',
+                            headers: {
+                                Accept: 'application/json',
+                                Connection: 'close'
+                            }
+                        })
+                    ];
+                case 2:
+                    response = _state.sent();
+                    if (!response.ok) return [
+                        3,
+                        10
+                    ];
+                    return [
+                        4,
+                        response.json()
+                    ];
+                case 3:
+                    metadata = _state.sent();
+                    // Check if the discovered resource matches what we're looking for
+                    if (metadata.resource === resourceUrl) {
+                        return [
+                            2,
+                            metadata
+                        ];
+                    }
+                    // If there's no path component, return root metadata
+                    // (e.g., looking for http://example.com and found it)
+                    if (!path) {
+                        return [
+                            2,
+                            metadata
+                        ];
+                    }
+                    if (!resourceUrl.startsWith(metadata.resource)) return [
+                        3,
+                        10
+                    ];
+                    // Still try sub-path location to see if there's more specific metadata
+                    // But save root metadata as fallback
+                    rootMetadata = metadata;
+                    // Try sub-path location for more specific metadata
+                    subPathUrl = "".concat(origin, "/.well-known/oauth-protected-resource").concat(path);
+                    _state.label = 4;
+                case 4:
+                    _state.trys.push([
+                        4,
+                        8,
+                        ,
+                        9
+                    ]);
+                    return [
+                        4,
+                        fetch(subPathUrl, {
+                            method: 'GET',
+                            headers: {
+                                Accept: 'application/json',
+                                Connection: 'close'
+                            }
+                        })
+                    ];
+                case 5:
+                    subPathResponse = _state.sent();
+                    if (!subPathResponse.ok) return [
+                        3,
+                        7
+                    ];
+                    return [
+                        4,
+                        subPathResponse.json()
+                    ];
+                case 6:
+                    return [
+                        2,
+                        _state.sent()
+                    ];
+                case 7:
+                    return [
+                        3,
+                        9
+                    ];
+                case 8:
+                    unused = _state.sent();
+                    return [
+                        3,
+                        9
+                    ];
+                case 9:
+                    // Return root metadata as it applies to this resource
+                    return [
+                        2,
+                        rootMetadata
+                    ];
+                case 10:
+                    return [
+                        3,
+                        12
+                    ];
+                case 11:
+                    unused1 = _state.sent();
+                    return [
+                        3,
+                        12
+                    ];
+                case 12:
+                    if (!path) return [
+                        3,
+                        18
+                    ];
+                    subPathUrl1 = "".concat(origin, "/.well-known/oauth-protected-resource").concat(path);
+                    _state.label = 13;
+                case 13:
+                    _state.trys.push([
+                        13,
+                        17,
+                        ,
+                        18
+                    ]);
+                    return [
+                        4,
+                        fetch(subPathUrl1, {
+                            method: 'GET',
+                            headers: {
+                                Accept: 'application/json',
+                                Connection: 'close'
+                            }
+                        })
+                    ];
+                case 14:
+                    response1 = _state.sent();
+                    if (!response1.ok) return [
+                        3,
+                        16
+                    ];
+                    return [
+                        4,
+                        response1.json()
+                    ];
+                case 15:
+                    return [
+                        2,
+                        _state.sent()
+                    ];
+                case 16:
+                    return [
+                        3,
+                        18
+                    ];
+                case 17:
+                    unused2 = _state.sent();
+                    return [
+                        3,
+                        18
+                    ];
+                case 18:
+                    // Neither location found or resource didn't match
+                    return [
+                        2,
+                        null
+                    ];
+                case 19:
+                    _error = _state.sent();
+                    // Network error, invalid URL, or other failure
+                    return [
+                        2,
+                        null
+                    ];
+                case 20:
+                    return [
+                        2
+                    ];
+            }
+        });
+    })();
+}
+function discoverAuthorizationServerMetadata(authServerUrl) {
+    return _async_to_generator(function() {
+        var origin, wellKnownUrl, response, _error;
+        return _ts_generator(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    _state.trys.push([
+                        0,
+                        3,
+                        ,
+                        4
+                    ]);
+                    origin = getOrigin(authServerUrl);
+                    wellKnownUrl = "".concat(origin, "/.well-known/oauth-authorization-server");
+                    return [
+                        4,
+                        fetch(wellKnownUrl, {
+                            method: 'GET',
+                            headers: {
+                                Accept: 'application/json',
+                                Connection: 'close'
+                            }
+                        })
+                    ];
+                case 1:
+                    response = _state.sent();
+                    if (!response.ok) {
+                        return [
+                            2,
+                            null
+                        ];
+                    }
+                    return [
+                        4,
+                        response.json()
+                    ];
+                case 2:
+                    return [
+                        2,
+                        _state.sent()
+                    ];
+                case 3:
+                    _error = _state.sent();
+                    return [
+                        2,
+                        null
+                    ];
+                case 4:
+                    return [
+                        2
+                    ];
+            }
+        });
+    })();
+}
+/* CJS INTEROP */ if (exports.__esModule && exports.default) { try { Object.defineProperty(exports.default, '__esModule', { value: true }); for (var key in exports) { exports.default[key] = exports[key]; } } catch (_) {}; module.exports = exports.default; }

package/dist/cjs/auth/rfc9728-discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/libs/client/src/auth/rfc9728-discovery.ts"],"sourcesContent":["/**\n * RFC 9728 Protected Resource Metadata Discovery\n * Probes .well-known/oauth-protected-resource endpoint\n */\n\nimport type { AuthorizationServerMetadata, ProtectedResourceMetadata } from './types.ts';\n\n/**\n * Extract origin (protocol + host) from a URL\n * @param url - Full URL that may include a path\n * @returns Origin (e.g., \"https://example.com\") or original string if invalid URL\n *\n * @example\n * getOrigin('https://example.com/mcp') // → 'https://example.com'\n * getOrigin('http://localhost:9999/api/v1/mcp') // → 'http://localhost:9999'\n */\nfunction getOrigin(url: string): string {\n  try {\n    return new URL(url).origin;\n  } catch {\n    // Invalid URL - return as-is for graceful degradation\n    return url;\n  }\n}\n\n/**\n * Extract path from a URL (without origin)\n * @param url - Full URL\n * @returns Path component (e.g., \"/mcp\", \"/api/v1/mcp\") or empty string if no path\n */\nfunction getPath(url: string): string {\n  try {\n    const parsed = new URL(url);\n    // pathname includes leading slash, e.g., \"/mcp\"\n    return parsed.pathname === '/' ? '' : parsed.pathname;\n  } catch {\n    return '';\n  }\n}\n\n/**\n * Discover OAuth 2.0 Protected Resource Metadata (RFC 9728)\n * Probes .well-known/oauth-protected-resource endpoint\n *\n * Discovery Strategy:\n * 1. Try origin root: {origin}/.well-known/oauth-protected-resource\n * 2. If 404, try sub-path: {origin}/.well-known/oauth-protected-resource{path}\n *\n * @param resourceUrl - URL of the protected resource (e.g., https://ai.todoist.net/mcp)\n * @returns ProtectedResourceMetadata if discovered, null otherwise\n *\n * @example\n * // Todoist case: MCP at ai.todoist.net/mcp, OAuth at todoist.com\n * const metadata = await discoverProtectedResourceMetadata('https://ai.todoist.net/mcp');\n * // Returns: { resource: \"https://ai.todoist.net/mcp\", authorization_servers: [\"https://todoist.com\"] }\n */\nexport async function discoverProtectedResourceMetadata(resourceUrl: string): Promise<ProtectedResourceMetadata | null> {\n  try {\n    const origin = getOrigin(resourceUrl);\n    const path = getPath(resourceUrl);\n\n    // Strategy 1: Try root location (REQUIRED by RFC 9728)\n    const rootUrl = `${origin}/.well-known/oauth-protected-resource`;\n\n    try {\n      const response = await fetch(rootUrl, {\n        method: 'GET',\n        headers: { Accept: 'application/json', Connection: 'close' },\n      });\n\n      if (response.ok) {\n        const metadata = (await response.json()) as ProtectedResourceMetadata;\n        // Check if the discovered resource matches what we're looking for\n        if (metadata.resource === resourceUrl) {\n          return metadata;\n        }\n        // If there's no path component, return root metadata\n        // (e.g., looking for http://example.com and found it)\n        if (!path) {\n          return metadata;\n        }\n        // If requested URL starts with metadata.resource, the root metadata applies to sub-paths\n        // (e.g., looking for http://example.com/api/v1/mcp, found http://example.com)\n        if (resourceUrl.startsWith(metadata.resource)) {\n          // Still try sub-path location to see if there's more specific metadata\n          // But save root metadata as fallback\n          const rootMetadata = metadata;\n\n          // Try sub-path location for more specific metadata\n          const subPathUrl = `${origin}/.well-known/oauth-protected-resource${path}`;\n          try {\n            const subPathResponse = await fetch(subPathUrl, {\n              method: 'GET',\n              headers: { Accept: 'application/json', Connection: 'close' },\n            });\n            if (subPathResponse.ok) {\n              return (await subPathResponse.json()) as ProtectedResourceMetadata;\n            }\n          } catch {\n            // Sub-path failed, use root metadata\n          }\n\n          // Return root metadata as it applies to this resource\n          return rootMetadata;\n        }\n        // Otherwise, try sub-path location before giving up\n      }\n    } catch {\n      // Continue to sub-path location\n    }\n\n    // Strategy 2: Try sub-path location (MCP spec extension)\n    // Only try if there's a path component\n    if (path) {\n      const subPathUrl = `${origin}/.well-known/oauth-protected-resource${path}`;\n\n      try {\n        const response = await fetch(subPathUrl, {\n          method: 'GET',\n          headers: { Accept: 'application/json', Connection: 'close' },\n        });\n\n        if (response.ok) {\n          return (await response.json()) as ProtectedResourceMetadata;\n        }\n      } catch {\n        // Fall through to return null\n      }\n    }\n\n    // Neither location found or resource didn't match\n    return null;\n  } catch (_error) {\n    // Network error, invalid URL, or other failure\n    return null;\n  }\n}\n\n/**\n * Discover OAuth 2.0 Authorization Server Metadata (RFC 8414)\n * Probes .well-known/oauth-authorization-server endpoint\n *\n * @param authServerUrl - URL of the authorization server (typically from RFC 9728 discovery)\n * @returns AuthorizationServerMetadata if discovered, null otherwise\n *\n * @example\n * const metadata = await discoverAuthorizationServerMetadata('https://todoist.com');\n * // Returns: { issuer: \"https://todoist.com\", authorization_endpoint: \"...\", ... }\n */\nexport async function discoverAuthorizationServerMetadata(authServerUrl: string): Promise<AuthorizationServerMetadata | null> {\n  try {\n    const origin = getOrigin(authServerUrl);\n    const wellKnownUrl = `${origin}/.well-known/oauth-authorization-server`;\n\n    const response = await fetch(wellKnownUrl, {\n      method: 'GET',\n      headers: { Accept: 'application/json', Connection: 'close' },\n    });\n\n    if (!response.ok) {\n      return null;\n    }\n\n    return (await response.json()) as AuthorizationServerMetadata;\n  } catch (_error) {\n    return null;\n  }\n}\n"],"names":["discoverAuthorizationServerMetadata","discoverProtectedResourceMetadata","getOrigin","url","URL","origin","getPath","parsed","pathname","resourceUrl","path","rootUrl","response","metadata","rootMetadata","subPathUrl","subPathResponse","_error","fetch","method","headers","Accept","Connection","ok","json","resource","startsWith","authServerUrl","wellKnownUrl"],"mappings":"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"}

package/dist/cjs/auth/types.d.cts

@@ -0,0 +1,137 @@
+/**
+ * Shared types for OAuth and DCR authentication
+ */
+/**
+ * OAuth callback result from authorization server
+ */
+export interface CallbackResult {
+    /** Authorization code from OAuth server */
+    code: string;
+    /** State parameter for CSRF protection */
+    state?: string;
+}
+/**
+ * PKCE (Proof Key for Code Exchange) parameters (RFC 7636)
+ * Used to secure OAuth 2.0 authorization code flow for public clients
+ */
+export interface PkceParams {
+    /** Code verifier - cryptographically random string (43-128 characters) */
+    codeVerifier: string;
+    /** Code challenge - derived from code verifier using challenge method */
+    codeChallenge: string;
+    /** Code challenge method - S256 (SHA-256) or plain */
+    codeChallengeMethod: 'S256' | 'plain';
+}
+/**
+ * OAuth token set with access and refresh tokens
+ */
+export interface TokenSet {
+    /** Access token for API requests */
+    accessToken: string;
+    /** Refresh token for obtaining new access tokens */
+    refreshToken: string;
+    /** Timestamp when access token expires (milliseconds since epoch) */
+    expiresAt: number;
+    /** Scopes granted for this token set */
+    scopes?: string[];
+    /** Client ID used for DCR registration (stored for future use) */
+    clientId?: string;
+    /** Client secret used for DCR registration (stored for future use) */
+    clientSecret?: string;
+}
+/**
+ * OAuth 2.0 Protected Resource Metadata (RFC 9728)
+ * Response from .well-known/oauth-protected-resource endpoint
+ */
+export interface ProtectedResourceMetadata {
+    /** The protected resource identifier */
+    resource: string;
+    /** List of authorization server URLs that can issue tokens for this resource */
+    authorization_servers: string[];
+    /** Optional list of scopes supported by this resource */
+    scopes_supported?: string[];
+    /** Optional list of bearer token methods supported (header, query, body) */
+    bearer_methods_supported?: string[];
+}
+/**
+ * OAuth 2.0 Authorization Server Metadata (RFC 8414)
+ * Response from .well-known/oauth-authorization-server endpoint
+ */
+export interface AuthorizationServerMetadata {
+    /** The authorization server's issuer identifier */
+    issuer?: string;
+    /** URL of the authorization endpoint */
+    authorization_endpoint?: string;
+    /** URL of the token endpoint */
+    token_endpoint?: string;
+    /** URL of the client registration endpoint (DCR - RFC 7591) */
+    registration_endpoint?: string;
+    /** URL of the token introspection endpoint */
+    introspection_endpoint?: string;
+    /** List of OAuth scopes supported by the authorization server */
+    scopes_supported?: string[];
+    /** Response types supported (code, token, etc.) */
+    response_types_supported?: string[];
+    /** Grant types supported (authorization_code, refresh_token, etc.) */
+    grant_types_supported?: string[];
+    /** Token endpoint authentication methods supported */
+    token_endpoint_auth_methods_supported?: string[];
+}
+/**
+ * OAuth server capabilities discovered from .well-known endpoint
+ */
+export interface AuthCapabilities {
+    /** Whether the server supports Dynamic Client Registration (RFC 7591) */
+    supportsDcr: boolean;
+    /** DCR client registration endpoint */
+    registrationEndpoint?: string;
+    /** OAuth authorization endpoint */
+    authorizationEndpoint?: string;
+    /** OAuth token endpoint */
+    tokenEndpoint?: string;
+    /** Token introspection endpoint */
+    introspectionEndpoint?: string;
+    /** Supported OAuth scopes */
+    scopes?: string[];
+}
+/**
+ * Client credentials from DCR registration
+ */
+export interface ClientCredentials {
+    /** OAuth client ID */
+    clientId: string;
+    /** OAuth client secret */
+    clientSecret: string;
+    /** Timestamp when client was registered */
+    issuedAt?: number;
+}
+/**
+ * Options for DCR client registration
+ */
+export interface DcrRegistrationOptions {
+    /** Client name to register */
+    clientName?: string;
+    /** Redirect URI for OAuth callback */
+    redirectUri?: string;
+}
+/**
+ * Options for OAuth authorization flow
+ */
+export interface OAuthFlowOptions {
+    /** Port for OAuth callback listener (required - use get-port to find available port) */
+    port: number;
+    /** Redirect URI for OAuth callback (optional - will be built from port if not provided) */
+    redirectUri?: string;
+    /** OAuth scopes to request */
+    scopes?: string[];
+    /** Resource parameter (RFC 8707) - target resource server identifier */
+    resource?: string;
+    /** Enable PKCE (RFC 7636) - recommended for all clients, required for public clients */
+    pkce?: boolean;
+    /** Headless mode (don't open browser) */
+    headless?: boolean;
+    /** Timeout for callback (milliseconds) */
+    timeout?: number;
+    /** Optional logger for debug output (defaults to singleton logger) */
+    logger?: import('../utils/logger.js').Logger;
+}