@mcp-z/client 1.0.0

package/dist/cjs/auth/pkce.js

@@ -0,0 +1,192 @@
+/**
+ * PKCE (Proof Key for Code Exchange) utilities
+ * Implements RFC 7636 for OAuth 2.0 public client security
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "generatePkce", {
+    enumerable: true,
+    get: function() {
+        return generatePkce;
+    }
+});
+var _nodecrypto = require("node:crypto");
+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
+        };
+    }
+}
+/**
+ * Generate random code verifier for PKCE (RFC 7636 Section 4.1)
+ * Returns cryptographically random string of 43-128 characters using base64url encoding
+ */ function generateRandomCodeVerifier() {
+    // RFC 7636 recommends 43-128 characters
+    // Using 32 random bytes -> 43 base64url characters
+    return (0, _nodecrypto.randomBytes)(32).toString('base64url');
+}
+/**
+ * Calculate PKCE code challenge from code verifier (RFC 7636 Section 4.2)
+ * Uses S256 method: BASE64URL(SHA256(ASCII(code_verifier)))
+ */ function calculatePKCECodeChallenge(codeVerifier) {
+    return _async_to_generator(function() {
+        var hash;
+        return _ts_generator(this, function(_state) {
+            hash = (0, _nodecrypto.createHash)('sha256').update(codeVerifier, 'ascii').digest();
+            return [
+                2,
+                Buffer.from(hash).toString('base64url')
+            ];
+        });
+    })();
+}
+function generatePkce() {
+    return _async_to_generator(function() {
+        var codeVerifier, codeChallenge;
+        return _ts_generator(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    // Generate cryptographically random code verifier (RFC 7636 § 4.1)
+                    codeVerifier = generateRandomCodeVerifier();
+                    return [
+                        4,
+                        calculatePKCECodeChallenge(codeVerifier)
+                    ];
+                case 1:
+                    codeChallenge = _state.sent();
+                    return [
+                        2,
+                        {
+                            codeVerifier: codeVerifier,
+                            codeChallenge: codeChallenge,
+                            codeChallengeMethod: 'S256'
+                        }
+                    ];
+            }
+        });
+    })();
+}
+/* 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/pkce.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/libs/client/src/auth/pkce.ts"],"sourcesContent":["/**\n * PKCE (Proof Key for Code Exchange) utilities\n * Implements RFC 7636 for OAuth 2.0 public client security\n */\n\nimport { createHash, randomBytes } from 'node:crypto';\nimport type { PkceParams } from './types.ts';\n\n/**\n * Generate random code verifier for PKCE (RFC 7636 Section 4.1)\n * Returns cryptographically random string of 43-128 characters using base64url encoding\n */\nfunction generateRandomCodeVerifier(): string {\n  // RFC 7636 recommends 43-128 characters\n  // Using 32 random bytes -> 43 base64url characters\n  return randomBytes(32).toString('base64url');\n}\n\n/**\n * Calculate PKCE code challenge from code verifier (RFC 7636 Section 4.2)\n * Uses S256 method: BASE64URL(SHA256(ASCII(code_verifier)))\n */\nasync function calculatePKCECodeChallenge(codeVerifier: string): Promise<string> {\n  const hash = createHash('sha256').update(codeVerifier, 'ascii').digest();\n  return Buffer.from(hash).toString('base64url');\n}\n\n/**\n * Generate PKCE parameters for OAuth 2.0 authorization code flow\n * Uses S256 method (SHA-256 hash) as recommended by RFC 7636\n *\n * @returns PkceParams with code verifier, challenge, and method\n *\n * @example\n * const pkce = await generatePkce();\n * // Use pkce.codeChallenge and pkce.codeChallengeMethod in authorization URL\n * // Store pkce.codeVerifier for token exchange\n */\nexport async function generatePkce(): Promise<PkceParams> {\n  // Generate cryptographically random code verifier (RFC 7636 § 4.1)\n  const codeVerifier = generateRandomCodeVerifier();\n\n  // Generate code challenge using S256 method (RFC 7636 § 4.2)\n  // S256: BASE64URL(SHA256(ASCII(code_verifier)))\n  const codeChallenge = await calculatePKCECodeChallenge(codeVerifier);\n\n  return {\n    codeVerifier,\n    codeChallenge,\n    codeChallengeMethod: 'S256',\n  };\n}\n"],"names":["generatePkce","generateRandomCodeVerifier","randomBytes","toString","calculatePKCECodeChallenge","codeVerifier","hash","createHash","update","digest","Buffer","from","codeChallenge","codeChallengeMethod"],"mappings":"AAAA;;;CAGC;;;;+BAmCqBA;;;eAAAA;;;0BAjCkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGxC;;;CAGC,GACD,SAASC;IACP,wCAAwC;IACxC,mDAAmD;IACnD,OAAOC,IAAAA,uBAAW,EAAC,IAAIC,QAAQ,CAAC;AAClC;AAEA;;;CAGC,GACD,SAAeC,2BAA2BC,YAAoB;;YACtDC;;YAAAA,OAAOC,IAAAA,sBAAU,EAAC,UAAUC,MAAM,CAACH,cAAc,SAASI,MAAM;YACtE;;gBAAOC,OAAOC,IAAI,CAACL,MAAMH,QAAQ,CAAC;;;IACpC;;AAaO,SAAeH;;YAEdK,cAIAO;;;;oBALN,mEAAmE;oBAC7DP,eAAeJ;oBAIC;;wBAAMG,2BAA2BC;;;oBAAjDO,gBAAgB;oBAEtB;;wBAAO;4BACLP,cAAAA;4BACAO,eAAAA;4BACAC,qBAAqB;wBACvB;;;;IACF"}

package/dist/cjs/auth/rfc9728-discovery.d.cts

@@ -0,0 +1,34 @@
+/**
+ * RFC 9728 Protected Resource Metadata Discovery
+ * Probes .well-known/oauth-protected-resource endpoint
+ */
+import type { AuthorizationServerMetadata, ProtectedResourceMetadata } from './types.js';
+/**
+ * Discover OAuth 2.0 Protected Resource Metadata (RFC 9728)
+ * Probes .well-known/oauth-protected-resource endpoint
+ *
+ * Discovery Strategy:
+ * 1. Try origin root: {origin}/.well-known/oauth-protected-resource
+ * 2. If 404, try sub-path: {origin}/.well-known/oauth-protected-resource{path}
+ *
+ * @param resourceUrl - URL of the protected resource (e.g., https://ai.todoist.net/mcp)
+ * @returns ProtectedResourceMetadata if discovered, null otherwise
+ *
+ * @example
+ * // Todoist case: MCP at ai.todoist.net/mcp, OAuth at todoist.com
+ * const metadata = await discoverProtectedResourceMetadata('https://ai.todoist.net/mcp');
+ * // Returns: { resource: "https://ai.todoist.net/mcp", authorization_servers: ["https://todoist.com"] }
+ */
+export declare function discoverProtectedResourceMetadata(resourceUrl: string): Promise<ProtectedResourceMetadata | null>;
+/**
+ * Discover OAuth 2.0 Authorization Server Metadata (RFC 8414)
+ * Probes .well-known/oauth-authorization-server endpoint
+ *
+ * @param authServerUrl - URL of the authorization server (typically from RFC 9728 discovery)
+ * @returns AuthorizationServerMetadata if discovered, null otherwise
+ *
+ * @example
+ * const metadata = await discoverAuthorizationServerMetadata('https://todoist.com');
+ * // Returns: { issuer: "https://todoist.com", authorization_endpoint: "...", ... }
+ */
+export declare function discoverAuthorizationServerMetadata(authServerUrl: string): Promise<AuthorizationServerMetadata | null>;

package/dist/cjs/auth/rfc9728-discovery.d.ts

@@ -0,0 +1,34 @@
+/**
+ * RFC 9728 Protected Resource Metadata Discovery
+ * Probes .well-known/oauth-protected-resource endpoint
+ */
+import type { AuthorizationServerMetadata, ProtectedResourceMetadata } from './types.js';
+/**
+ * Discover OAuth 2.0 Protected Resource Metadata (RFC 9728)
+ * Probes .well-known/oauth-protected-resource endpoint
+ *
+ * Discovery Strategy:
+ * 1. Try origin root: {origin}/.well-known/oauth-protected-resource
+ * 2. If 404, try sub-path: {origin}/.well-known/oauth-protected-resource{path}
+ *
+ * @param resourceUrl - URL of the protected resource (e.g., https://ai.todoist.net/mcp)
+ * @returns ProtectedResourceMetadata if discovered, null otherwise
+ *
+ * @example
+ * // Todoist case: MCP at ai.todoist.net/mcp, OAuth at todoist.com
+ * const metadata = await discoverProtectedResourceMetadata('https://ai.todoist.net/mcp');
+ * // Returns: { resource: "https://ai.todoist.net/mcp", authorization_servers: ["https://todoist.com"] }
+ */
+export declare function discoverProtectedResourceMetadata(resourceUrl: string): Promise<ProtectedResourceMetadata | null>;
+/**
+ * Discover OAuth 2.0 Authorization Server Metadata (RFC 8414)
+ * Probes .well-known/oauth-authorization-server endpoint
+ *
+ * @param authServerUrl - URL of the authorization server (typically from RFC 9728 discovery)
+ * @returns AuthorizationServerMetadata if discovered, null otherwise
+ *
+ * @example
+ * const metadata = await discoverAuthorizationServerMetadata('https://todoist.com');
+ * // Returns: { issuer: "https://todoist.com", authorization_endpoint: "...", ... }
+ */
+export declare function discoverAuthorizationServerMetadata(authServerUrl: string): Promise<AuthorizationServerMetadata | null>;