@mcp-z/oauth 1.0.0

package/dist/cjs/types.js

@@ -0,0 +1,210 @@
+/**
+ * Type definitions for multi-account management and OAuth integration
+ */ "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 AccountManagerError () {
+        return AccountManagerError;
+    },
+    get AccountNotFoundError () {
+        return AccountNotFoundError;
+    },
+    get AuthRequiredError () {
+        return AuthRequiredError;
+    },
+    get ConfigurationError () {
+        return ConfigurationError;
+    },
+    get RequiresAuthenticationError () {
+        return RequiresAuthenticationError;
+    }
+});
+function _assert_this_initialized(self) {
+    if (self === void 0) {
+        throw new ReferenceError("this hasn't been initialised - super() hasn't been called");
+    }
+    return self;
+}
+function _call_super(_this, derived, args) {
+    derived = _get_prototype_of(derived);
+    return _possible_constructor_return(_this, _is_native_reflect_construct() ? Reflect.construct(derived, args || [], _get_prototype_of(_this).constructor) : derived.apply(_this, args));
+}
+function _class_call_check(instance, Constructor) {
+    if (!(instance instanceof Constructor)) {
+        throw new TypeError("Cannot call a class as a function");
+    }
+}
+function _construct(Parent, args, Class) {
+    if (_is_native_reflect_construct()) {
+        _construct = Reflect.construct;
+    } else {
+        _construct = function construct(Parent, args, Class) {
+            var a = [
+                null
+            ];
+            a.push.apply(a, args);
+            var Constructor = Function.bind.apply(Parent, a);
+            var instance = new Constructor();
+            if (Class) _set_prototype_of(instance, Class.prototype);
+            return instance;
+        };
+    }
+    return _construct.apply(null, arguments);
+}
+function _get_prototype_of(o) {
+    _get_prototype_of = Object.setPrototypeOf ? Object.getPrototypeOf : function getPrototypeOf(o) {
+        return o.__proto__ || Object.getPrototypeOf(o);
+    };
+    return _get_prototype_of(o);
+}
+function _inherits(subClass, superClass) {
+    if (typeof superClass !== "function" && superClass !== null) {
+        throw new TypeError("Super expression must either be null or a function");
+    }
+    subClass.prototype = Object.create(superClass && superClass.prototype, {
+        constructor: {
+            value: subClass,
+            writable: true,
+            configurable: true
+        }
+    });
+    if (superClass) _set_prototype_of(subClass, superClass);
+}
+function _is_native_function(fn) {
+    return Function.toString.call(fn).indexOf("[native code]") !== -1;
+}
+function _possible_constructor_return(self, call) {
+    if (call && (_type_of(call) === "object" || typeof call === "function")) {
+        return call;
+    }
+    return _assert_this_initialized(self);
+}
+function _set_prototype_of(o, p) {
+    _set_prototype_of = Object.setPrototypeOf || function setPrototypeOf(o, p) {
+        o.__proto__ = p;
+        return o;
+    };
+    return _set_prototype_of(o, p);
+}
+function _type_of(obj) {
+    "@swc/helpers - typeof";
+    return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
+}
+function _wrap_native_super(Class) {
+    var _cache = typeof Map === "function" ? new Map() : undefined;
+    _wrap_native_super = function wrapNativeSuper(Class) {
+        if (Class === null || !_is_native_function(Class)) return Class;
+        if (typeof Class !== "function") {
+            throw new TypeError("Super expression must either be null or a function");
+        }
+        if (typeof _cache !== "undefined") {
+            if (_cache.has(Class)) return _cache.get(Class);
+            _cache.set(Class, Wrapper);
+        }
+        function Wrapper() {
+            return _construct(Class, arguments, _get_prototype_of(this).constructor);
+        }
+        Wrapper.prototype = Object.create(Class.prototype, {
+            constructor: {
+                value: Wrapper,
+                enumerable: false,
+                writable: true,
+                configurable: true
+            }
+        });
+        return _set_prototype_of(Wrapper, Class);
+    };
+    return _wrap_native_super(Class);
+}
+function _is_native_reflect_construct() {
+    try {
+        var result = !Boolean.prototype.valueOf.call(Reflect.construct(Boolean, [], function() {}));
+    } catch (_) {}
+    return (_is_native_reflect_construct = function() {
+        return !!result;
+    })();
+}
+var AccountManagerError = /*#__PURE__*/ function(Error1) {
+    "use strict";
+    _inherits(AccountManagerError, Error1);
+    function AccountManagerError(message, code) {
+        var retryable = arguments.length > 2 && arguments[2] !== void 0 ? arguments[2] : false;
+        _class_call_check(this, AccountManagerError);
+        var _this;
+        _this = _call_super(this, AccountManagerError, [
+            message
+        ]);
+        _this.name = 'AccountManagerError';
+        _this.code = code;
+        _this.retryable = retryable;
+        return _this;
+    }
+    return AccountManagerError;
+}(_wrap_native_super(Error));
+var AccountNotFoundError = /*#__PURE__*/ function(AccountManagerError) {
+    "use strict";
+    _inherits(AccountNotFoundError, AccountManagerError);
+    function AccountNotFoundError(accountRef) {
+        _class_call_check(this, AccountNotFoundError);
+        return _call_super(this, AccountNotFoundError, [
+            "Account '".concat(accountRef, "' not found"),
+            'ACCOUNT_NOT_FOUND',
+            false
+        ]);
+    }
+    return AccountNotFoundError;
+}(AccountManagerError);
+var ConfigurationError = /*#__PURE__*/ function(AccountManagerError) {
+    "use strict";
+    _inherits(ConfigurationError, AccountManagerError);
+    function ConfigurationError(message) {
+        _class_call_check(this, ConfigurationError);
+        return _call_super(this, ConfigurationError, [
+            "Configuration error: ".concat(message),
+            'CONFIGURATION_ERROR',
+            false
+        ]);
+    }
+    return ConfigurationError;
+}(AccountManagerError);
+var RequiresAuthenticationError = /*#__PURE__*/ function(AccountManagerError) {
+    "use strict";
+    _inherits(RequiresAuthenticationError, AccountManagerError);
+    function RequiresAuthenticationError(service, accountId) {
+        _class_call_check(this, RequiresAuthenticationError);
+        var _this;
+        var message = accountId ? "No account found for ".concat(service, " (account: ").concat(accountId, "). Use account-add to connect one.") : "No account found for ".concat(service, ". Use account-add to connect one.");
+        _this = _call_super(this, RequiresAuthenticationError, [
+            message,
+            'REQUIRES_AUTHENTICATION',
+            false
+        ]);
+        _this.accountId = accountId;
+        return _this;
+    }
+    return RequiresAuthenticationError;
+}(AccountManagerError);
+var AuthRequiredError = /*#__PURE__*/ function(Error1) {
+    "use strict";
+    _inherits(AuthRequiredError, Error1);
+    function AuthRequiredError(descriptor, message) {
+        _class_call_check(this, AuthRequiredError);
+        var _this;
+        _this = _call_super(this, AuthRequiredError, [
+            message || "Authentication required: ".concat(descriptor.kind)
+        ]);
+        _this.name = 'AuthRequiredError';
+        _this.descriptor = descriptor;
+        return _this;
+    }
+    return AuthRequiredError;
+}(_wrap_native_super(Error));
+/* 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/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/oauth/oauth/src/types.ts"],"sourcesContent":["/**\n * Type definitions for multi-account management and OAuth integration\n */\n\nimport type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport type { AnySchema, ZodRawShapeCompat } from '@modelcontextprotocol/sdk/server/zod-compat.js';\nimport type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';\nimport type { CallToolResult, GetPromptResult, ServerNotification, ServerRequest, ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';\n\nexport type Logger = Pick<Console, 'info' | 'error' | 'warn' | 'debug'>;\n\nexport interface AccountInfo {\n  email: string;\n  alias?: string;\n  addedAt: string;\n  lastUsed?: string;\n  metadata?: {\n    name?: string;\n    picture?: string;\n    [key: string]: unknown;\n  };\n}\n\n/**\n * MCP tool module definition with configuration and handler function.\n *\n * Represents a registered tool in the Model Context Protocol server that can be\n * invoked by MCP clients. Tools are the primary mechanism for executing operations\n * in response to client requests.\n *\n * @property name - Unique tool identifier (e.g., \"gmail-message-send\", \"sheets-values-get\")\n * @property config - Tool configuration including description and schemas\n * @property config.description - Human-readable description shown to MCP clients\n * @property config.inputSchema - Zod schema defining tool arguments (JSON-serializable)\n * @property config.outputSchema - Zod schema defining tool response structure\n * @property handler - Async function that executes the tool operation\n *\n * @remarks\n * This is the runtime representation of an MCP tool after registration. The handler\n * receives JSON-serializable arguments validated against inputSchema and returns\n * a CallToolResult validated against outputSchema.\n *\n * Tools are typically created using tool factory functions and registered with the\n * MCP server during initialization.\n *\n * @example\n * ```typescript\n * const tool: McpTool = {\n *   name: \"gmail-message-send\",\n *   config: {\n *     description: \"Send an email message\",\n *     inputSchema: { to: { type: \"string\" }, subject: { type: \"string\" } },\n *     outputSchema: { result: { type: \"object\" } }\n *   },\n *   handler: async (args, context) => {\n *     // Implementation\n *     return { content: [{ type: \"text\", text: \"Message sent\" }] };\n *   }\n * };\n * ```\n *\n * @see {@link McpPrompt} for prompt module definition\n */\nexport interface McpTool {\n  name: string;\n  config: {\n    description: string;\n    inputSchema: Record<string, unknown>;\n    outputSchema: Record<string, unknown>;\n  };\n  handler: (args: unknown, context?: unknown) => Promise<CallToolResult>;\n}\n\n/**\n * MCP prompt module definition with configuration and handler function.\n *\n * Represents a registered prompt template in the Model Context Protocol server that\n * can be retrieved and rendered by MCP clients. Prompts provide reusable templates\n * for common interaction patterns.\n *\n * @property name - Unique prompt identifier (e.g., \"draft-email\", \"summarize-thread\")\n * @property config - Prompt configuration (schema and metadata are prompt-specific)\n * @property handler - Async function that generates the prompt content\n *\n * @remarks\n * This is the runtime representation of an MCP prompt after registration. Unlike\n * {@link McpTool} which executes operations, prompts generate templated content\n * that clients can use to structure interactions.\n *\n * The handler receives optional arguments and returns a GetPromptResult containing\n * the rendered prompt messages.\n *\n * @example\n * ```typescript\n * const prompt: McpPrompt = {\n *   name: \"draft-email\",\n *   config: {\n *     description: \"Generate email draft from key points\",\n *     arguments: [{ name: \"points\", description: \"Key points to include\" }]\n *   },\n *   handler: async (args) => {\n *     const points = args?.points || [];\n *     return {\n *       messages: [{\n *         role: \"user\",\n *         content: { type: \"text\", text: `Draft email covering: ${points.join(\", \")}` }\n *       }]\n *     };\n *   }\n * };\n * ```\n *\n * @see {@link McpTool} for tool module definition\n */\nexport interface McpPrompt {\n  name: string;\n  config: unknown;\n  handler: (args: unknown) => Promise<GetPromptResult>;\n}\n\nexport class AccountManagerError extends Error {\n  public code: string;\n  public retryable: boolean;\n\n  constructor(message: string, code: string, retryable = false) {\n    super(message);\n    this.name = 'AccountManagerError';\n    this.code = code;\n    this.retryable = retryable;\n  }\n}\n\nexport class AccountNotFoundError extends AccountManagerError {\n  constructor(accountRef: string) {\n    super(`Account '${accountRef}' not found`, 'ACCOUNT_NOT_FOUND', false);\n  }\n}\n\nexport class ConfigurationError extends AccountManagerError {\n  constructor(message: string) {\n    super(`Configuration error: ${message}`, 'CONFIGURATION_ERROR', false);\n  }\n}\n\nexport class RequiresAuthenticationError extends AccountManagerError {\n  public accountId: string | undefined;\n\n  constructor(service: string, accountId?: string) {\n    const message = accountId ? `No account found for ${service} (account: ${accountId}). Use account-add to connect one.` : `No account found for ${service}. Use account-add to connect one.`;\n    super(message, 'REQUIRES_AUTHENTICATION', false);\n    this.accountId = accountId;\n  }\n}\n\nexport interface AuthEmailProvider {\n  getUserEmail(accountId?: string): Promise<string>;\n  authenticateNewAccount?(): Promise<string>;\n}\n\nexport interface UserAuthProvider {\n  getUserId(req: unknown): Promise<string>; // Throws if auth invalid\n}\n\nexport interface JWTUserAuthConfig {\n  secret?: string; // HS256 - MUST be at least 32 characters\n  publicKey?: string | object; // RS256/ES256 - PEM string, JWK object, or JWKS URL\n  jwksUrl?: string; // Alternative to publicKey\n  issuer?: string | string[];\n  audience?: string | string[];\n  userIdClaim?: string; // Default: 'sub'\n  algorithms?: string[]; // Default: auto-detect\n  clockTolerance?: number; // Default: 0\n}\n\nexport interface SessionUserAuthConfig {\n  sessionSecret: string; // MUST be at least 32 characters\n  cookieName?: string; // Default: 'session'\n  algorithm?: 'sha256' | 'sha512'; // Default: 'sha256'\n}\n\nexport interface Credentials {\n  accessToken: string;\n  expiresAt?: number;\n  refreshToken?: string;\n  scope?: string;\n  tokenType?: string;\n  idToken?: string;\n}\n\nexport type AuthFlowDescriptor =\n  | { kind: 'credentials'; connection?: string; provider?: string; credentials: Credentials }\n  | { kind: 'auth_url'; connection?: string; provider?: string; url: string; txn?: string; state?: string; codeVerifier?: string; poll?: { statusUrl: string; interval?: number }; hint?: string }\n  | { kind: 'device_code'; connection?: string; provider?: string; txn?: string; device: { userCode: string; verificationUri: string; verificationUriComplete?: string; expiresIn: number; interval: number }; poll?: { statusUrl: string; interval?: number }; hint?: string }\n  | { kind: 'error'; error: string; code?: number };\n\nexport class AuthRequiredError extends Error {\n  public descriptor: AuthFlowDescriptor;\n\n  constructor(descriptor: AuthFlowDescriptor, message?: string) {\n    super(message || `Authentication required: ${descriptor.kind}`);\n    this.name = 'AuthRequiredError';\n    this.descriptor = descriptor;\n  }\n}\n\nexport interface CachedToken {\n  accessToken: string;\n  refreshToken?: string;\n  expiresAt?: number;\n  scope?: string;\n}\n\n/**\n * Tool config signature - explicit structural type mirroring SDK registerTool config\n *\n * Uses explicit structure instead of Parameters<> extraction to avoid TypeScript inference\n * collapse to 'never' when using ToolModule[] arrays. The deep conditional types from\n * Parameters<> cannot be unified across array elements.\n *\n * Validated against SDK signature for compatibility - compile errors if SDK changes.\n *\n * NOTE: This type is duplicated in @mcp-z/server for architectural independence.\n * Keep these definitions synchronized manually when updating.\n */\nexport type ToolConfig = {\n  title?: string;\n  description?: string;\n  inputSchema?: ZodRawShapeCompat | AnySchema;\n  outputSchema?: ZodRawShapeCompat | AnySchema;\n  annotations?: ToolAnnotations;\n  _meta?: Record<string, unknown>;\n};\n\n// Compile-time validation that ToolConfig is compatible with SDK\ntype _ValidateToolConfigAssignable = ToolConfig extends Parameters<McpServer['registerTool']>[1] ? true : never;\ntype _ValidateToolConfigReceivable = Parameters<McpServer['registerTool']>[1] extends ToolConfig ? true : never;\n\n/**\n * Tool handler signature with generic support for middleware.\n *\n * @template TArgs - Tool arguments type (default: unknown for SDK compatibility)\n * @template TExtra - Request handler extra type (default: RequestHandlerExtra from SDK)\n *\n * Defaults provide SDK-extracted types for compatibility with MCP SDK.\n * Generic parameters enable type-safe middleware transformation.\n *\n * NOTE: This interface is duplicated in @mcp-z/server for architectural independence.\n * Keep these definitions synchronized manually when updating.\n */\nexport type ToolHandler<TArgs = unknown, TExtra = RequestHandlerExtra<ServerRequest, ServerNotification>> = (args: TArgs, extra: TExtra) => Promise<CallToolResult>;\n\n/**\n * Tool module interface with bounded generics.\n *\n * @template TConfig - Tool config type (default: SDK ToolConfig)\n * @template THandler - Handler function type (default: SDK ToolHandler)\n *\n * Use without generics for SDK-typed tools:\n * - Business tool factories: `ToolModule`\n * - Tool registration: `ToolModule[]`\n *\n * Use with generics for middleware transformation:\n * - Auth middleware: `ToolModule<ToolConfig, ToolHandler<TArgs, EnrichedExtra>>`\n *\n * The bounds ensure compatibility with SDK registration.\n *\n * NOTE: This interface is duplicated in @mcp-z/server for architectural independence.\n * Keep these definitions synchronized manually when updating.\n *\n * @see {@link ToolHandler} for handler function signature\n * @see {@link AuthMiddlewareWrapper} for middleware wrapper pattern\n */\nexport interface ToolModule<TConfig = ToolConfig, THandler = unknown> {\n  name: string;\n  config: TConfig;\n  handler: THandler;\n}\n\n/**\n * Middleware wrapper that enriches tool modules with authentication context.\n *\n * Wraps plain tool modules to inject authentication, logging, and request metadata.\n * The wrapper pattern allows separation of business logic from cross-cutting concerns.\n *\n * @template TArgs - Tool arguments type (inferred from tool module)\n * @template TExtra - Enriched extra type with auth context and logger\n *\n * @param toolModule - Plain tool module to wrap with auth middleware\n * @returns Wrapped tool module with enriched handler signature\n *\n * @remarks\n * Auth middleware wrappers typically:\n * - Extract auth context from MCP request or OAuth provider\n * - Inject logger instance for structured logging\n * - Handle authentication errors with proper MCP error responses\n * - Preserve tool configuration and metadata\n *\n * @example\n * ```typescript\n * // Actual usage pattern from OAuth providers (LoopbackOAuthProvider, ServiceAccountProvider, DcrOAuthProvider)\n * const provider = new LoopbackOAuthProvider({ service: 'gmail', ... });\n * const authMiddleware = provider.authMiddleware();\n *\n * // Apply middleware to tools (handlers receive enriched extra with authContext)\n * const tools = toolFactories.map(f => f()).map(authMiddleware.withToolAuth);\n * const resources = resourceFactories.map(f => f()).map(authMiddleware.withResourceAuth);\n * const prompts = promptFactories.map(f => f()).map(authMiddleware.withPromptAuth);\n *\n * // Tool handler receives enriched extra with guaranteed authContext\n * async function handler({ id }: In, extra: EnrichedExtra) {\n *   // extra.authContext.auth is OAuth2Client (from middleware)\n *   const gmail = google.gmail({ version: 'v1', auth: extra.authContext.auth });\n *   // ... business logic with authenticated context\n * }\n * ```\n *\n * @see {@link ToolModule} for base tool interface\n * @see {@link ToolHandler} for handler function signature\n */\nexport type AuthMiddlewareWrapper<TArgs = unknown, TExtra = RequestHandlerExtra<ServerRequest, ServerNotification>> = (toolModule: ToolModule) => ToolModule<ToolConfig, ToolHandler<TArgs, TExtra>>;\n\n/**\n * Base interface for stateful OAuth adapters (LoopbackOAuthProvider pattern)\n *\n * Stateful adapters manage token storage, refresh, and multi-account state.\n * Used for local development, test setup, and CI/CD workflows.\n *\n * Key characteristics:\n * - Token storage and retrieval via tokenStore\n * - Automatic token refresh with provider\n * - Interactive OAuth flows (browser, ephemeral server)\n * - Multi-account management\n *\n * Parameter usage:\n * - accountId: Account identifier (email address for token storage)\n */\nexport interface OAuth2TokenStorageProvider {\n  /**\n   * Get access token for the specified account.\n   * If token is expired, automatically refreshes it.\n   * If token is missing, triggers OAuth flow (interactive) or throws AuthRequired (headless).\n   *\n   * @param accountId - Account identifier for multi-account support\n   * @returns Access token string\n   */\n  getAccessToken(accountId?: string): Promise<string>;\n\n  /**\n   * Get email address for the specified account.\n   * Used during account registration to verify identity with provider.\n   *\n   * @param accountId - Account identifier\n   * @returns Email address from provider verification\n   */\n  getUserEmail(accountId?: string): Promise<string>;\n}\n"],"names":["AccountManagerError","AccountNotFoundError","AuthRequiredError","ConfigurationError","RequiresAuthenticationError","message","code","retryable","name","Error","accountRef","service","accountId","descriptor","kind"],"mappings":"AAAA;;CAEC;;;;;;;;;;;QAsHYA;eAAAA;;QAYAC;eAAAA;;QA+DAC;eAAAA;;QAzDAC;eAAAA;;QAMAC;eAAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAxBN,IAAA,AAAMJ,oCAAN;;cAAMA;aAAAA,oBAICK,OAAe,EAAEC,IAAY;YAAEC,YAAAA,iEAAY;gCAJ5CP;;gBAKT,kBALSA;YAKHK;;QACN,MAAKG,IAAI,GAAG;QACZ,MAAKF,IAAI,GAAGA;QACZ,MAAKC,SAAS,GAAGA;;;WARRP;qBAA4BS;AAYlC,IAAA,AAAMR,qCAAN;;cAAMA;aAAAA,qBACCS,UAAkB;gCADnBT;QAET,OAAA,kBAFSA;YAEF,YAAsB,OAAXS,YAAW;YAAc;YAAqB;;;WAFvDT;EAA6BD;AAMnC,IAAA,AAAMG,mCAAN;;cAAMA;aAAAA,mBACCE,OAAe;gCADhBF;QAET,OAAA,kBAFSA;YAEF,wBAA+B,OAARE;YAAW;YAAuB;;;WAFvDF;EAA2BH;AAMjC,IAAA,AAAMI,4CAAN;;cAAMA;aAAAA,4BAGCO,OAAe,EAAEC,SAAkB;gCAHpCR;;QAIT,IAAMC,UAAUO,YAAY,AAAC,wBAA4CA,OAArBD,SAAQ,eAAuB,OAAVC,WAAU,wCAAsC,AAAC,wBAA+B,OAARD,SAAQ;gBACzJ,kBALSP;YAKHC;YAAS;YAA2B;;QAC1C,MAAKO,SAAS,GAAGA;;;WANRR;EAAoCJ;AAmD1C,IAAA,AAAME,kCAAN;;cAAMA;aAAAA,kBAGCW,UAA8B,EAAER,OAAgB;gCAHjDH;;gBAIT,kBAJSA;YAIHG,WAAW,AAAC,4BAA2C,OAAhBQ,WAAWC,IAAI;;QAC5D,MAAKN,IAAI,GAAG;QACZ,MAAKK,UAAU,GAAGA;;;WANTX;qBAA0BO"}

package/dist/esm/account-utils.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Account management utilities for OAuth token storage
+ *
+ * Provides account lifecycle operations (add, remove, activate) and account data
+ * access (tokens, metadata). Uses named parameters consistent with key-utils.ts.
+ */
+import type { Keyv } from 'keyv';
+import { type AccountKeyParams, type ServiceKeyParams } from './key-utils.js';
+import type { AccountInfo } from './types.js';
+/**
+ * Add account to linked accounts list and set as active if first account.
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (service, accountId)
+ *
+ * @example
+ * await addAccount(tokenStore, {
+ *   service: 'gmail',
+ *   accountId: 'alice@gmail.com'
+ * });
+ */
+export declare function addAccount(store: Keyv, params: AccountKeyParams): Promise<void>;
+/**
+ * Remove account: delete token, metadata, update linked list, and active account.
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (service, accountId)
+ *
+ * @example
+ * await removeAccount(tokenStore, {
+ *   service: 'gmail',
+ *   accountId: 'alice@gmail.com'
+ * });
+ */
+export declare function removeAccount(store: Keyv, params: AccountKeyParams): Promise<void>;
+/**
+ * Get active account ID for a service.
+ *
+ * Key: {service}:active
+ *
+ * @param store - Keyv storage instance
+ * @param params - Service identification (service)
+ * @returns Active account ID or undefined if none set
+ */
+export declare function getActiveAccount(store: Keyv, params: ServiceKeyParams): Promise<string | undefined>;
+/**
+ * Set active account ID for a service.
+ * Pass null as accountId to deactivate (clear active account).
+ *
+ * Key: {service}:active
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (service, accountId). Pass accountId: null to deactivate.
+ */
+export declare function setActiveAccount(store: Keyv, params: AccountKeyParams | (ServiceKeyParams & {
+    accountId: null;
+})): Promise<void>;
+/**
+ * Get list of linked account IDs for a service.
+ *
+ * Key: {service}:linked
+ *
+ * @param store - Keyv storage instance
+ * @param params - Service identification (service)
+ * @returns Array of account IDs (empty array if none)
+ */
+export declare function getLinkedAccounts(store: Keyv, params: ServiceKeyParams): Promise<string[]>;
+/**
+ * Get account metadata (alias, lastUsed, etc).
+ *
+ * Key: {accountId}:{service}:metadata
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (accountId, service)
+ * @returns Account info or undefined if not found
+ */
+export declare function getAccountInfo(store: Keyv, params: AccountKeyParams): Promise<AccountInfo | undefined>;
+/**
+ * Set account metadata (alias, lastUsed, etc).
+ *
+ * Key: {accountId}:{service}:metadata
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (accountId, service)
+ * @param info - Account metadata to store
+ */
+export declare function setAccountInfo(store: Keyv, params: AccountKeyParams, info: AccountInfo): Promise<void>;
+/**
+ * Get OAuth token for an account.
+ *
+ * Key: {accountId}:{service}:token
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (accountId, service)
+ * @returns Token or undefined if not found
+ */
+export declare function getToken<T>(store: Keyv, params: AccountKeyParams): Promise<T | undefined>;
+/**
+ * Set OAuth token for an account.
+ *
+ * Key: {accountId}:{service}:token
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (accountId, service)
+ * @param token - OAuth token data to store
+ */
+export declare function setToken<T>(store: Keyv, params: AccountKeyParams, token: T): Promise<void>;

package/dist/esm/account-utils.js

@@ -0,0 +1,179 @@
+/**
+ * Account management utilities for OAuth token storage
+ *
+ * Provides account lifecycle operations (add, remove, activate) and account data
+ * access (tokens, metadata). Uses named parameters consistent with key-utils.ts.
+ */ import { createAccountKey, createServiceKey } from './key-utils.js';
+// ============================================================================
+// Account Lifecycle Operations
+// ============================================================================
+/**
+ * Add account to linked accounts list and set as active if first account.
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (service, accountId)
+ *
+ * @example
+ * await addAccount(tokenStore, {
+ *   service: 'gmail',
+ *   accountId: 'alice@gmail.com'
+ * });
+ */ export async function addAccount(store, params) {
+    const linked = await getLinkedAccounts(store, {
+        service: params.service
+    });
+    if (!linked.includes(params.accountId)) {
+        linked.push(params.accountId);
+        const linkedKey = createServiceKey('linked', {
+            service: params.service
+        });
+        await store.set(linkedKey, linked);
+    }
+    const active = await getActiveAccount(store, {
+        service: params.service
+    });
+    if (!active) {
+        await setActiveAccount(store, params);
+    }
+}
+/**
+ * Remove account: delete token, metadata, update linked list, and active account.
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (service, accountId)
+ *
+ * @example
+ * await removeAccount(tokenStore, {
+ *   service: 'gmail',
+ *   accountId: 'alice@gmail.com'
+ * });
+ */ export async function removeAccount(store, params) {
+    const tokenKey = createAccountKey('token', params);
+    await store.delete(tokenKey);
+    const infoKey = createAccountKey('metadata', params);
+    await store.delete(infoKey);
+    const linked = await getLinkedAccounts(store, {
+        service: params.service
+    });
+    const filtered = linked.filter((id)=>id !== params.accountId);
+    const linkedKey = createServiceKey('linked', {
+        service: params.service
+    });
+    await store.set(linkedKey, filtered);
+    // Set new active account if we're removing the currently active one
+    const active = await getActiveAccount(store, {
+        service: params.service
+    });
+    if (active === params.accountId) {
+        const newActive = filtered[0];
+        if (newActive) {
+            await setActiveAccount(store, {
+                service: params.service,
+                accountId: newActive
+            });
+        } else {
+            const activeKey = createServiceKey('active', {
+                service: params.service
+            });
+            await store.delete(activeKey);
+        }
+    }
+}
+// ============================================================================
+// Service-Scoped Account Operations
+// ============================================================================
+/**
+ * Get active account ID for a service.
+ *
+ * Key: {service}:active
+ *
+ * @param store - Keyv storage instance
+ * @param params - Service identification (service)
+ * @returns Active account ID or undefined if none set
+ */ export async function getActiveAccount(store, params) {
+    const key = createServiceKey('active', params);
+    return await store.get(key);
+}
+/**
+ * Set active account ID for a service.
+ * Pass null as accountId to deactivate (clear active account).
+ *
+ * Key: {service}:active
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (service, accountId). Pass accountId: null to deactivate.
+ */ export async function setActiveAccount(store, params) {
+    const key = createServiceKey('active', {
+        service: params.service
+    });
+    if ('accountId' in params && params.accountId === null) {
+        // accountId: null signals deactivation per API contract
+        await store.delete(key);
+    } else {
+        await store.set(key, params.accountId);
+    }
+}
+/**
+ * Get list of linked account IDs for a service.
+ *
+ * Key: {service}:linked
+ *
+ * @param store - Keyv storage instance
+ * @param params - Service identification (service)
+ * @returns Array of account IDs (empty array if none)
+ */ export async function getLinkedAccounts(store, params) {
+    const key = createServiceKey('linked', params);
+    const accounts = await store.get(key);
+    return accounts || [];
+}
+// ============================================================================
+// Account Data Operations
+// ============================================================================
+/**
+ * Get account metadata (alias, lastUsed, etc).
+ *
+ * Key: {accountId}:{service}:metadata
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (accountId, service)
+ * @returns Account info or undefined if not found
+ */ export async function getAccountInfo(store, params) {
+    const key = createAccountKey('metadata', params);
+    return await store.get(key);
+}
+/**
+ * Set account metadata (alias, lastUsed, etc).
+ *
+ * Key: {accountId}:{service}:metadata
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (accountId, service)
+ * @param info - Account metadata to store
+ */ export async function setAccountInfo(store, params, info) {
+    const key = createAccountKey('metadata', params);
+    await store.set(key, info);
+}
+/**
+ * Get OAuth token for an account.
+ *
+ * Key: {accountId}:{service}:token
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (accountId, service)
+ * @returns Token or undefined if not found
+ */ export async function getToken(store, params) {
+    const key = createAccountKey('token', params);
+    return await store.get(key);
+}
+/**
+ * Set OAuth token for an account.
+ *
+ * Key: {accountId}:{service}:token
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (accountId, service)
+ * @param token - OAuth token data to store
+ */ export async function setToken(store, params, token) {
+    const key = createAccountKey('token', params);
+    await store.set(key, token);
+}

package/dist/esm/account-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/oauth/oauth/src/account-utils.ts"],"sourcesContent":["/**\n * Account management utilities for OAuth token storage\n *\n * Provides account lifecycle operations (add, remove, activate) and account data\n * access (tokens, metadata). Uses named parameters consistent with key-utils.ts.\n */\n\nimport type { Keyv } from 'keyv';\nimport { type AccountKeyParams, createAccountKey, createServiceKey, type ServiceKeyParams } from './key-utils.ts';\nimport type { AccountInfo } from './types.ts';\n\n// ============================================================================\n// Account Lifecycle Operations\n// ============================================================================\n\n/**\n * Add account to linked accounts list and set as active if first account.\n *\n * @param store - Keyv storage instance\n * @param params - Account identification (service, accountId)\n *\n * @example\n * await addAccount(tokenStore, {\n *   service: 'gmail',\n *   accountId: 'alice@gmail.com'\n * });\n */\nexport async function addAccount(store: Keyv, params: AccountKeyParams): Promise<void> {\n  const linked = await getLinkedAccounts(store, { service: params.service });\n\n  if (!linked.includes(params.accountId)) {\n    linked.push(params.accountId);\n    const linkedKey = createServiceKey('linked', { service: params.service });\n    await store.set(linkedKey, linked);\n  }\n\n  const active = await getActiveAccount(store, { service: params.service });\n  if (!active) {\n    await setActiveAccount(store, params);\n  }\n}\n\n/**\n * Remove account: delete token, metadata, update linked list, and active account.\n *\n * @param store - Keyv storage instance\n * @param params - Account identification (service, accountId)\n *\n * @example\n * await removeAccount(tokenStore, {\n *   service: 'gmail',\n *   accountId: 'alice@gmail.com'\n * });\n */\nexport async function removeAccount(store: Keyv, params: AccountKeyParams): Promise<void> {\n  const tokenKey = createAccountKey('token', params);\n  await store.delete(tokenKey);\n\n  const infoKey = createAccountKey('metadata', params);\n  await store.delete(infoKey);\n\n  const linked = await getLinkedAccounts(store, { service: params.service });\n  const filtered = linked.filter((id) => id !== params.accountId);\n  const linkedKey = createServiceKey('linked', { service: params.service });\n  await store.set(linkedKey, filtered);\n\n  // Set new active account if we're removing the currently active one\n  const active = await getActiveAccount(store, { service: params.service });\n  if (active === params.accountId) {\n    const newActive = filtered[0];\n    if (newActive) {\n      await setActiveAccount(store, { service: params.service, accountId: newActive });\n    } else {\n      const activeKey = createServiceKey('active', { service: params.service });\n      await store.delete(activeKey);\n    }\n  }\n}\n\n// ============================================================================\n// Service-Scoped Account Operations\n// ============================================================================\n\n/**\n * Get active account ID for a service.\n *\n * Key: {service}:active\n *\n * @param store - Keyv storage instance\n * @param params - Service identification (service)\n * @returns Active account ID or undefined if none set\n */\nexport async function getActiveAccount(store: Keyv, params: ServiceKeyParams): Promise<string | undefined> {\n  const key = createServiceKey('active', params);\n  return await store.get(key);\n}\n\n/**\n * Set active account ID for a service.\n * Pass null as accountId to deactivate (clear active account).\n *\n * Key: {service}:active\n *\n * @param store - Keyv storage instance\n * @param params - Account identification (service, accountId). Pass accountId: null to deactivate.\n */\nexport async function setActiveAccount(store: Keyv, params: AccountKeyParams | (ServiceKeyParams & { accountId: null })): Promise<void> {\n  const key = createServiceKey('active', { service: params.service });\n  if ('accountId' in params && params.accountId === null) {\n    // accountId: null signals deactivation per API contract\n    await store.delete(key);\n  } else {\n    await store.set(key, (params as AccountKeyParams).accountId);\n  }\n}\n\n/**\n * Get list of linked account IDs for a service.\n *\n * Key: {service}:linked\n *\n * @param store - Keyv storage instance\n * @param params - Service identification (service)\n * @returns Array of account IDs (empty array if none)\n */\nexport async function getLinkedAccounts(store: Keyv, params: ServiceKeyParams): Promise<string[]> {\n  const key = createServiceKey('linked', params);\n  const accounts = await store.get(key);\n  return accounts || [];\n}\n\n// ============================================================================\n// Account Data Operations\n// ============================================================================\n\n/**\n * Get account metadata (alias, lastUsed, etc).\n *\n * Key: {accountId}:{service}:metadata\n *\n * @param store - Keyv storage instance\n * @param params - Account identification (accountId, service)\n * @returns Account info or undefined if not found\n */\nexport async function getAccountInfo(store: Keyv, params: AccountKeyParams): Promise<AccountInfo | undefined> {\n  const key = createAccountKey('metadata', params);\n  return await store.get(key);\n}\n\n/**\n * Set account metadata (alias, lastUsed, etc).\n *\n * Key: {accountId}:{service}:metadata\n *\n * @param store - Keyv storage instance\n * @param params - Account identification (accountId, service)\n * @param info - Account metadata to store\n */\nexport async function setAccountInfo(store: Keyv, params: AccountKeyParams, info: AccountInfo): Promise<void> {\n  const key = createAccountKey('metadata', params);\n  await store.set(key, info);\n}\n\n/**\n * Get OAuth token for an account.\n *\n * Key: {accountId}:{service}:token\n *\n * @param store - Keyv storage instance\n * @param params - Account identification (accountId, service)\n * @returns Token or undefined if not found\n */\nexport async function getToken<T>(store: Keyv, params: AccountKeyParams): Promise<T | undefined> {\n  const key = createAccountKey('token', params);\n  return await store.get(key);\n}\n\n/**\n * Set OAuth token for an account.\n *\n * Key: {accountId}:{service}:token\n *\n * @param store - Keyv storage instance\n * @param params - Account identification (accountId, service)\n * @param token - OAuth token data to store\n */\nexport async function setToken<T>(store: Keyv, params: AccountKeyParams, token: T): Promise<void> {\n  const key = createAccountKey('token', params);\n  await store.set(key, token);\n}\n"],"names":["createAccountKey","createServiceKey","addAccount","store","params","linked","getLinkedAccounts","service","includes","accountId","push","linkedKey","set","active","getActiveAccount","setActiveAccount","removeAccount","tokenKey","delete","infoKey","filtered","filter","id","newActive","activeKey","key","get","accounts","getAccountInfo","setAccountInfo","info","getToken","setToken","token"],"mappings":"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"}

package/dist/esm/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @mcp-z/oauth - Multi-account OAuth orchestration and secure token storage for MCP servers
+ *
+ * Provides account management functions, account tools generation, and secure logging utilities.
+ * Designed to work with any storage backend (file, Redis, DuckDB) via Keyv interface.
+ */
+export { addAccount, getActiveAccount, getToken, removeAccount, setAccountInfo, setActiveAccount, setToken } from './account-utils.js';
+export { JWTUserAuth } from './jwt-auth.js';
+export { type AccountKeyParams, type AccountKeyType, createAccountKey, createServiceKey, listAccountIds, type ServiceKeyParams, type ServiceKeyType } from './key-utils.js';
+export { type AccountLoopbackConfig, AccountServer, type AccountStatelessConfig, createLoopback, createStateless } from './lib/account-server/index.js';
+export type { DcrClientInformation, DcrClientMetadata, DcrConfig, DcrErrorResponse, ProviderTokens } from './lib/dcr-types.js';
+export type { RFC8414Metadata, RFC9728Metadata } from './lib/rfc-metadata-types.js';
+export { generatePKCE, type PKCEPair } from './pkce.js';
+export { sanitizeForLogging, sanitizeForLoggingFormatter } from './sanitizer.js';
+export * as schemas from './schemas/index.js';
+export { SessionUserAuth } from './session-auth.js';
+export { getErrorTemplate, getSuccessTemplate } from './templates.js';
+export type { AccountInfo, AuthEmailProvider, AuthFlowDescriptor, AuthMiddlewareWrapper, CachedToken, Credentials, JWTUserAuthConfig, Logger, McpPrompt, McpTool, OAuth2TokenStorageProvider, SessionUserAuthConfig, ToolConfig, ToolHandler, ToolModule, UserAuthProvider, } from './types.js';
+export { AccountManagerError, AccountNotFoundError, AuthRequiredError, ConfigurationError, RequiresAuthenticationError } from './types.js';

package/dist/esm/index.js

@@ -0,0 +1,23 @@
+/**
+ * @mcp-z/oauth - Multi-account OAuth orchestration and secure token storage for MCP servers
+ *
+ * Provides account management functions, account tools generation, and secure logging utilities.
+ * Designed to work with any storage backend (file, Redis, DuckDB) via Keyv interface.
+ */ // Core account management - Public API
+// Internal functions - For provider implementations and testing
+export { addAccount, getActiveAccount, getToken, removeAccount, setAccountInfo, setActiveAccount, setToken } from './account-utils.js';
+// Auth classes - For multi-tenant testing
+export { JWTUserAuth } from './jwt-auth.js';
+export { createAccountKey, createServiceKey, listAccountIds } from './key-utils.js';
+// Account server and factory functions - Public API
+export { AccountServer, createLoopback, createStateless } from './lib/account-server/index.js';
+export { generatePKCE } from './pkce.js';
+// Logging utilities - Public API
+export { sanitizeForLogging, sanitizeForLoggingFormatter } from './sanitizer.js';
+// Schemas
+import * as _schemas from './schemas/index.js';
+export { _schemas as schemas };
+export { SessionUserAuth } from './session-auth.js';
+export { getErrorTemplate, getSuccessTemplate } from './templates.js';
+// Public error classes
+export { AccountManagerError, AccountNotFoundError, AuthRequiredError, ConfigurationError, RequiresAuthenticationError } from './types.js';

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/oauth/oauth/src/index.ts"],"sourcesContent":["/**\n * @mcp-z/oauth - Multi-account OAuth orchestration and secure token storage for MCP servers\n *\n * Provides account management functions, account tools generation, and secure logging utilities.\n * Designed to work with any storage backend (file, Redis, DuckDB) via Keyv interface.\n */\n\n// Core account management - Public API\n// Internal functions - For provider implementations and testing\nexport { addAccount, getActiveAccount, getToken, removeAccount, setAccountInfo, setActiveAccount, setToken } from './account-utils.ts';\n// Auth classes - For multi-tenant testing\nexport { JWTUserAuth } from './jwt-auth.ts';\nexport { type AccountKeyParams, type AccountKeyType, createAccountKey, createServiceKey, listAccountIds, type ServiceKeyParams, type ServiceKeyType } from './key-utils.ts';\n// Account server and factory functions - Public API\nexport { type AccountLoopbackConfig, AccountServer, type AccountStatelessConfig, createLoopback, createStateless } from './lib/account-server/index.ts';\n// DCR types - Public API\nexport type { DcrClientInformation, DcrClientMetadata, DcrConfig, DcrErrorResponse, ProviderTokens } from './lib/dcr-types.ts';\n// RFC Metadata Types - Public API\nexport type { RFC8414Metadata, RFC9728Metadata } from './lib/rfc-metadata-types.ts';\nexport { generatePKCE, type PKCEPair } from './pkce.ts';\n// Logging utilities - Public API\nexport { sanitizeForLogging, sanitizeForLoggingFormatter } from './sanitizer.ts';\n// Schemas\nexport * as schemas from './schemas/index.ts';\nexport { SessionUserAuth } from './session-auth.ts';\nexport { getErrorTemplate, getSuccessTemplate } from './templates.ts';\n\n// Public types - core interfaces that consumers use\nexport type {\n  // Account management types\n  AccountInfo,\n  // Provider interfaces\n  AuthEmailProvider,\n  AuthFlowDescriptor,\n  AuthMiddlewareWrapper,\n  CachedToken,\n  Credentials,\n  // Auth config types\n  JWTUserAuthConfig,\n  // Utility types\n  Logger,\n  McpPrompt,\n  McpTool,\n  OAuth2TokenStorageProvider,\n  SessionUserAuthConfig,\n  ToolConfig,\n  ToolHandler,\n  ToolModule,\n  UserAuthProvider,\n} from './types.ts';\n\n// Public error classes\nexport { AccountManagerError, AccountNotFoundError, AuthRequiredError, ConfigurationError, RequiresAuthenticationError } from './types.ts';\n"],"names":["addAccount","getActiveAccount","getToken","removeAccount","setAccountInfo","setActiveAccount","setToken","JWTUserAuth","createAccountKey","createServiceKey","listAccountIds","AccountServer","createLoopback","createStateless","generatePKCE","sanitizeForLogging","sanitizeForLoggingFormatter","schemas","SessionUserAuth","getErrorTemplate","getSuccessTemplate","AccountManagerError","AccountNotFoundError","AuthRequiredError","ConfigurationError","RequiresAuthenticationError"],"mappings":"AAAA;;;;;CAKC,GAED,uCAAuC;AACvC,gEAAgE;AAChE,SAASA,UAAU,EAAEC,gBAAgB,EAAEC,QAAQ,EAAEC,aAAa,EAAEC,cAAc,EAAEC,gBAAgB,EAAEC,QAAQ,QAAQ,qBAAqB;AACvI,0CAA0C;AAC1C,SAASC,WAAW,QAAQ,gBAAgB;AAC5C,SAAqDC,gBAAgB,EAAEC,gBAAgB,EAAEC,cAAc,QAAoD,iBAAiB;AAC5K,oDAAoD;AACpD,SAAqCC,aAAa,EAA+BC,cAAc,EAAEC,eAAe,QAAQ,gCAAgC;AAKxJ,SAASC,YAAY,QAAuB,YAAY;AACxD,iCAAiC;AACjC,SAASC,kBAAkB,EAAEC,2BAA2B,QAAQ,iBAAiB;AACjF,UAAU;AACV,0BAAyB,qBAAqB;AAA9C,SAAO,YAAKC,OAAO,GAA2B;AAC9C,SAASC,eAAe,QAAQ,oBAAoB;AACpD,SAASC,gBAAgB,EAAEC,kBAAkB,QAAQ,iBAAiB;AA0BtE,uBAAuB;AACvB,SAASC,mBAAmB,EAAEC,oBAAoB,EAAEC,iBAAiB,EAAEC,kBAAkB,EAAEC,2BAA2B,QAAQ,aAAa"}

package/dist/esm/jwt-auth.d.ts

@@ -0,0 +1,53 @@
+/**
+ * JWT-based user authentication for multi-tenant deployments
+ *
+ * Extracts user ID from JWT tokens with signature and claims verification.
+ * Supports HS256, RS256, ES256 algorithms via JOSE library.
+ */
+import type { JWTUserAuthConfig, UserAuthProvider } from './types.js';
+/**
+ * JWT-based user authentication provider
+ *
+ * Verifies JWT tokens and extracts user IDs from claims.
+ * Use for multi-tenant deployments where users authenticate via JWT.
+ *
+ * @example
+ * ```typescript
+ * // HS256 with shared secret
+ * const userAuth = new JWTUserAuth({
+ *   secret: process.env.JWT_SECRET!,
+ *   issuer: 'https://auth.example.com',
+ *   audience: 'api.example.com',
+ * });
+ *
+ * // RS256 with public key
+ * const userAuth = new JWTUserAuth({
+ *   publicKey: process.env.JWT_PUBLIC_KEY!,
+ *   issuer: 'https://auth.example.com',
+ * });
+ *
+ * // RS256 with JWKS URL (dynamic key rotation)
+ * const userAuth = new JWTUserAuth({
+ *   jwksUrl: 'https://auth.example.com/.well-known/jwks.json',
+ *   issuer: 'https://auth.example.com',
+ *   audience: 'api.example.com',
+ * });
+ * ```
+ */
+export declare class JWTUserAuth implements UserAuthProvider {
+    private readonly config;
+    private readonly remoteJWKSet?;
+    constructor(config: JWTUserAuthConfig);
+    /**
+     * Extract and verify user ID from JWT token
+     *
+     * @param req - HTTP request object with Authorization header
+     * @returns User ID from verified JWT claims
+     * @throws Error if token missing, invalid, expired, or claims invalid
+     */
+    getUserId(req: unknown): Promise<string>;
+    /**
+     * Verify JWT signature and claims
+     */
+    private verifyToken;
+}