@mcp-z/oauth 1.0.0

package/dist/esm/jwt-auth.js

@@ -0,0 +1,164 @@
+/**
+ * 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 { createRemoteJWKSet, importSPKI, jwtVerify } from 'jose';
+/**
+ * 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 class JWTUserAuth {
+    /**
+   * 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
+   */ async getUserId(req) {
+        var _httpReq_headers;
+        const httpReq = req;
+        // Extract Authorization header
+        const authHeader = (_httpReq_headers = httpReq.headers) === null || _httpReq_headers === void 0 ? void 0 : _httpReq_headers.authorization;
+        if (!authHeader) {
+            throw new Error('JWTUserAuth: No Authorization header found');
+        }
+        // Parse Bearer token
+        const match = /^Bearer\s+(.+)$/i.exec(authHeader.trim());
+        if (!match) {
+            throw new Error('JWTUserAuth: Invalid Authorization header format (expected "Bearer <token>")');
+        }
+        const token = match[1];
+        if (!token) {
+            throw new Error('JWTUserAuth: Empty JWT token');
+        }
+        // Verify JWT and extract payload
+        const payload = await this.verifyToken(token);
+        // Extract user ID from configured claim
+        const userId = payload[this.config.userIdClaim];
+        if (!userId || typeof userId !== 'string') {
+            throw new Error(`JWTUserAuth: JWT missing or invalid '${this.config.userIdClaim}' claim`);
+        }
+        return userId;
+    }
+    /**
+   * Verify JWT signature and claims
+   */ async verifyToken(token) {
+        try {
+            // Build verification options
+            const options = {
+                ...this.config.issuer && {
+                    issuer: this.config.issuer
+                },
+                ...this.config.audience && {
+                    audience: this.config.audience
+                },
+                ...this.config.clockTolerance && {
+                    clockTolerance: this.config.clockTolerance
+                }
+            };
+            // Verify with appropriate key type
+            let result;
+            if (this.config.secret) {
+                // HS256 verification with shared secret
+                const secret = new TextEncoder().encode(this.config.secret);
+                result = await jwtVerify(token, secret, {
+                    ...options,
+                    algorithms: this.config.algorithms.length > 0 ? this.config.algorithms : [
+                        'HS256'
+                    ]
+                });
+            } else if (this.remoteJWKSet) {
+                // RS256/ES256 verification with remote JWKS
+                result = await jwtVerify(token, this.remoteJWKSet, {
+                    ...options,
+                    algorithms: this.config.algorithms.length > 0 ? this.config.algorithms : [
+                        'RS256',
+                        'ES256'
+                    ]
+                });
+            } else if (this.config.publicKey) {
+                // RS256/ES256 verification with provided public key
+                // If string (PEM), import it first; if JWK, use directly
+                const key = typeof this.config.publicKey === 'string' ? await importSPKI(this.config.publicKey, 'RS256') : this.config.publicKey;
+                result = await jwtVerify(token, key, {
+                    ...options,
+                    algorithms: this.config.algorithms.length > 0 ? this.config.algorithms : [
+                        'RS256',
+                        'ES256'
+                    ]
+                });
+            } else {
+                throw new Error('JWTUserAuth: No verification key configured');
+            }
+            return result.payload;
+        } catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`JWTUserAuth: JWT verification failed: ${error.message}`);
+            }
+            throw new Error('JWTUserAuth: JWT verification failed');
+        }
+    }
+    constructor(config){
+        var _config_userIdClaim, _config_algorithms, _config_clockTolerance;
+        // Validate configuration
+        if (!config.secret && !config.publicKey && !config.jwksUrl) {
+            throw new Error('JWTUserAuth: Must provide one of: secret (HS256), publicKey (RS256/ES256), or jwksUrl');
+        }
+        if (config.secret && config.secret.length < 32) {
+            throw new Error('JWTUserAuth: secret must be at least 32 characters for HS256');
+        }
+        if ((config.secret ? 1 : 0) + (config.publicKey ? 1 : 0) + (config.jwksUrl ? 1 : 0) > 1) {
+            throw new Error('JWTUserAuth: Provide only one of: secret, publicKey, or jwksUrl');
+        }
+        // Store configuration with defaults
+        this.config = {
+            ...config.secret !== undefined && {
+                secret: config.secret
+            },
+            ...config.publicKey !== undefined && {
+                publicKey: config.publicKey
+            },
+            ...config.jwksUrl !== undefined && {
+                jwksUrl: config.jwksUrl
+            },
+            ...config.issuer !== undefined && {
+                issuer: config.issuer
+            },
+            ...config.audience !== undefined && {
+                audience: config.audience
+            },
+            userIdClaim: (_config_userIdClaim = config.userIdClaim) !== null && _config_userIdClaim !== void 0 ? _config_userIdClaim : 'sub',
+            algorithms: (_config_algorithms = config.algorithms) !== null && _config_algorithms !== void 0 ? _config_algorithms : [],
+            clockTolerance: (_config_clockTolerance = config.clockTolerance) !== null && _config_clockTolerance !== void 0 ? _config_clockTolerance : 0
+        };
+        // Create remote JWK set if using JWKS URL
+        if (config.jwksUrl) {
+            this.remoteJWKSet = createRemoteJWKSet(new URL(config.jwksUrl));
+        }
+    }
+}

package/dist/esm/jwt-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/oauth/oauth/src/jwt-auth.ts"],"sourcesContent":["/**\n * JWT-based user authentication for multi-tenant deployments\n *\n * Extracts user ID from JWT tokens with signature and claims verification.\n * Supports HS256, RS256, ES256 algorithms via JOSE library.\n */\n\nimport { createRemoteJWKSet, importSPKI, type JWK, type JWTPayload, type JWTVerifyOptions, type JWTVerifyResult, jwtVerify } from 'jose';\nimport type { JWTUserAuthConfig, UserAuthProvider } from './types.ts';\n\n/**\n * HTTP request interface (subset needed for JWT auth)\n */\ninterface HttpRequest {\n  headers?: {\n    authorization?: string;\n  };\n}\n\n/**\n * JWT-based user authentication provider\n *\n * Verifies JWT tokens and extracts user IDs from claims.\n * Use for multi-tenant deployments where users authenticate via JWT.\n *\n * @example\n * ```typescript\n * // HS256 with shared secret\n * const userAuth = new JWTUserAuth({\n *   secret: process.env.JWT_SECRET!,\n *   issuer: 'https://auth.example.com',\n *   audience: 'api.example.com',\n * });\n *\n * // RS256 with public key\n * const userAuth = new JWTUserAuth({\n *   publicKey: process.env.JWT_PUBLIC_KEY!,\n *   issuer: 'https://auth.example.com',\n * });\n *\n * // RS256 with JWKS URL (dynamic key rotation)\n * const userAuth = new JWTUserAuth({\n *   jwksUrl: 'https://auth.example.com/.well-known/jwks.json',\n *   issuer: 'https://auth.example.com',\n *   audience: 'api.example.com',\n * });\n * ```\n */\nexport class JWTUserAuth implements UserAuthProvider {\n  private readonly config: {\n    secret?: string;\n    publicKey?: string | JWK;\n    jwksUrl?: string;\n    issuer?: string | string[];\n    audience?: string | string[];\n    userIdClaim: string;\n    algorithms: string[];\n    clockTolerance: number;\n  };\n  private readonly remoteJWKSet?: ReturnType<typeof createRemoteJWKSet>;\n\n  constructor(config: JWTUserAuthConfig) {\n    // Validate configuration\n    if (!config.secret && !config.publicKey && !config.jwksUrl) {\n      throw new Error('JWTUserAuth: Must provide one of: secret (HS256), publicKey (RS256/ES256), or jwksUrl');\n    }\n\n    if (config.secret && config.secret.length < 32) {\n      throw new Error('JWTUserAuth: secret must be at least 32 characters for HS256');\n    }\n\n    if ((config.secret ? 1 : 0) + (config.publicKey ? 1 : 0) + (config.jwksUrl ? 1 : 0) > 1) {\n      throw new Error('JWTUserAuth: Provide only one of: secret, publicKey, or jwksUrl');\n    }\n\n    // Store configuration with defaults\n    this.config = {\n      ...(config.secret !== undefined && { secret: config.secret }),\n      ...(config.publicKey !== undefined && { publicKey: config.publicKey }),\n      ...(config.jwksUrl !== undefined && { jwksUrl: config.jwksUrl }),\n      ...(config.issuer !== undefined && { issuer: config.issuer }),\n      ...(config.audience !== undefined && { audience: config.audience }),\n      userIdClaim: config.userIdClaim ?? 'sub',\n      algorithms: config.algorithms ?? [],\n      clockTolerance: config.clockTolerance ?? 0,\n    };\n\n    // Create remote JWK set if using JWKS URL\n    if (config.jwksUrl) {\n      this.remoteJWKSet = createRemoteJWKSet(new URL(config.jwksUrl));\n    }\n  }\n\n  /**\n   * Extract and verify user ID from JWT token\n   *\n   * @param req - HTTP request object with Authorization header\n   * @returns User ID from verified JWT claims\n   * @throws Error if token missing, invalid, expired, or claims invalid\n   */\n  async getUserId(req: unknown): Promise<string> {\n    const httpReq = req as HttpRequest;\n\n    // Extract Authorization header\n    const authHeader = httpReq.headers?.authorization;\n    if (!authHeader) {\n      throw new Error('JWTUserAuth: No Authorization header found');\n    }\n\n    // Parse Bearer token\n    const match = /^Bearer\\s+(.+)$/i.exec(authHeader.trim());\n    if (!match) {\n      throw new Error('JWTUserAuth: Invalid Authorization header format (expected \"Bearer <token>\")');\n    }\n\n    const token = match[1];\n    if (!token) {\n      throw new Error('JWTUserAuth: Empty JWT token');\n    }\n\n    // Verify JWT and extract payload\n    const payload = await this.verifyToken(token);\n\n    // Extract user ID from configured claim\n    const userId = payload[this.config.userIdClaim];\n    if (!userId || typeof userId !== 'string') {\n      throw new Error(`JWTUserAuth: JWT missing or invalid '${this.config.userIdClaim}' claim`);\n    }\n\n    return userId;\n  }\n\n  /**\n   * Verify JWT signature and claims\n   */\n  private async verifyToken(token: string): Promise<JWTPayload> {\n    try {\n      // Build verification options\n      const options: JWTVerifyOptions = {\n        ...(this.config.issuer && { issuer: this.config.issuer }),\n        ...(this.config.audience && { audience: this.config.audience }),\n        ...(this.config.clockTolerance && { clockTolerance: this.config.clockTolerance }),\n      };\n\n      // Verify with appropriate key type\n      let result: JWTVerifyResult;\n\n      if (this.config.secret) {\n        // HS256 verification with shared secret\n        const secret = new TextEncoder().encode(this.config.secret);\n        result = await jwtVerify(token, secret, {\n          ...options,\n          algorithms: this.config.algorithms.length > 0 ? this.config.algorithms : ['HS256'],\n        });\n      } else if (this.remoteJWKSet) {\n        // RS256/ES256 verification with remote JWKS\n        result = await jwtVerify(token, this.remoteJWKSet, {\n          ...options,\n          algorithms: this.config.algorithms.length > 0 ? this.config.algorithms : ['RS256', 'ES256'],\n        });\n      } else if (this.config.publicKey) {\n        // RS256/ES256 verification with provided public key\n        // If string (PEM), import it first; if JWK, use directly\n        const key = typeof this.config.publicKey === 'string' ? await importSPKI(this.config.publicKey, 'RS256') : this.config.publicKey;\n\n        result = await jwtVerify(token, key, {\n          ...options,\n          algorithms: this.config.algorithms.length > 0 ? this.config.algorithms : ['RS256', 'ES256'],\n        });\n      } else {\n        throw new Error('JWTUserAuth: No verification key configured');\n      }\n\n      return result.payload;\n    } catch (error) {\n      if (error instanceof Error) {\n        throw new Error(`JWTUserAuth: JWT verification failed: ${error.message}`);\n      }\n      throw new Error('JWTUserAuth: JWT verification failed');\n    }\n  }\n}\n"],"names":["createRemoteJWKSet","importSPKI","jwtVerify","JWTUserAuth","getUserId","req","httpReq","authHeader","headers","authorization","Error","match","exec","trim","token","payload","verifyToken","userId","config","userIdClaim","options","issuer","audience","clockTolerance","result","secret","TextEncoder","encode","algorithms","length","remoteJWKSet","publicKey","key","error","message","jwksUrl","undefined","URL"],"mappings":"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"}

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

@@ -0,0 +1,131 @@
+/**
+ * Key generation utilities for consistent storage key format
+ *
+ * Key format: {accountId}:{service}:{type}
+ * Example: work@gmail.com:gmail:token
+ */
+import type { Keyv } from 'keyv';
+/**
+ * Key types for account-scoped data (requires accountId)
+ */
+export type AccountKeyType = 'token' | 'metadata' | 'dcr-client';
+/**
+ * Key types for service-scoped data (no accountId)
+ */
+export type ServiceKeyType = 'active' | 'linked';
+/**
+ * Parameters for account-scoped keys.
+ * All fields are required - no silent defaults.
+ */
+export interface AccountKeyParams {
+    /** Account identifier - typically an email address */
+    accountId: string;
+    /** Service name (e.g., 'gmail', 'sheets', 'drive', 'outlook') */
+    service: string;
+}
+/**
+ * Parameters for service-scoped keys.
+ * These keys don't include accountId.
+ */
+export interface ServiceKeyParams {
+    /** Service name */
+    service: string;
+}
+/**
+ * Create account-scoped storage key.
+ *
+ * These keys are scoped to a specific account (email address) and store
+ * account-specific data like OAuth tokens and account metadata.
+ *
+ * @param type - Key type ('token' for OAuth tokens, 'metadata' for account details, 'dcr-client' for DCR registration)
+ * @param params - Account key parameters with explicit field names
+ * @returns Storage key in format: "{accountId}:{service}:{type}"
+ *
+ * @example
+ * ```typescript
+ * // Store OAuth token
+ * const tokenKey = createAccountKey('token', {
+ *   accountId: 'alice@gmail.com',
+ *   service: 'gmail'
+ * });
+ * // Returns: "alice@gmail.com:gmail:token"
+ *
+ * // Store account metadata (alias, timestamps, profile)
+ * const metadataKey = createAccountKey('metadata', {
+ *   accountId: 'alice@gmail.com',
+ *   service: 'gmail'
+ * });
+ * // Returns: "alice@gmail.com:gmail:metadata"
+ *
+ * // Store DCR client registration info
+ * const dcrKey = createAccountKey('dcr-client', {
+ *   accountId: 'alice@outlook.com',
+ *   service: 'outlook'
+ * });
+ * // Returns: "alice@outlook.com:outlook:dcr-client"
+ * ```
+ */
+export declare function createAccountKey(type: AccountKeyType, params: AccountKeyParams): string;
+/**
+ * Create service-scoped storage key.
+ *
+ * These keys are scoped to a service (not a specific account) and store
+ * service-level data like which account is active or the list of linked accounts.
+ *
+ * @param type - Key type ('active' for active account, 'linked' for account list)
+ * @param params - Service key parameters
+ * @returns Storage key in format: "{service}:{type}"
+ *
+ * @example
+ * ```typescript
+ * // Track active account
+ * const activeKey = createServiceKey('active', {
+ *   service: 'gmail'
+ * });
+ * // Returns: "gmail:active"
+ *
+ * // Store list of linked accounts
+ * const linkedKey = createServiceKey('linked', {
+ *   service: 'gmail'
+ * });
+ * // Returns: "gmail:linked"
+ * ```
+ */
+export declare function createServiceKey(type: ServiceKeyType, params: ServiceKeyParams): string;
+/**
+ * Parse token key to extract components
+ *
+ * @param key - Storage key to parse
+ * @returns Object with accountId and service, or undefined if invalid format
+ *
+ * @example
+ * const parsed = parseTokenKey('user@gmail.com:gmail:token');
+ * // Returns: { accountId: 'user@gmail.com', service: 'gmail' }
+ *
+ * const invalid = parseTokenKey('invalid-key');
+ * // Returns: undefined
+ */
+export declare function parseTokenKey(key: string): {
+    accountId: string;
+    service: string;
+} | undefined;
+/**
+ * List all account IDs for a service
+ *
+ * Iterates token keys and returns all accountIds that match the service.
+ * Encapsulates key format details for forward compatibility.
+ *
+ * @param store - Keyv store to iterate
+ * @param service - Service name
+ * @returns Array of account IDs (e.g., email addresses)
+ *
+ * @example
+ * const accounts = await listAccountIds(store, 'gmail');
+ * // Returns: ['alice@gmail.com', 'bob@gmail.com']
+ *
+ * @example
+ * // Empty array if no accounts found
+ * const empty = await listAccountIds(store, 'unknown-service');
+ * // Returns: []
+ */
+export declare function listAccountIds(store: Keyv, service: string): Promise<string[]>;

package/dist/esm/key-utils.js

@@ -0,0 +1,143 @@
+/**
+ * Key generation utilities for consistent storage key format
+ *
+ * Key format: {accountId}:{service}:{type}
+ * Example: work@gmail.com:gmail:token
+ */ /**
+ * Validate key parameters don't contain colon delimiter
+ */ function validateKeyParams(params) {
+    for (const [key, value] of Object.entries(params)){
+        if (typeof value !== 'string') {
+            throw new Error(`Key parameter '${key}' must be a string, got: ${typeof value}`);
+        }
+        if (value.includes(':')) {
+            throw new Error(`Key parameter '${key}' cannot contain colon character: ${value}`);
+        }
+    }
+}
+/**
+ * Create account-scoped storage key.
+ *
+ * These keys are scoped to a specific account (email address) and store
+ * account-specific data like OAuth tokens and account metadata.
+ *
+ * @param type - Key type ('token' for OAuth tokens, 'metadata' for account details, 'dcr-client' for DCR registration)
+ * @param params - Account key parameters with explicit field names
+ * @returns Storage key in format: "{accountId}:{service}:{type}"
+ *
+ * @example
+ * ```typescript
+ * // Store OAuth token
+ * const tokenKey = createAccountKey('token', {
+ *   accountId: 'alice@gmail.com',
+ *   service: 'gmail'
+ * });
+ * // Returns: "alice@gmail.com:gmail:token"
+ *
+ * // Store account metadata (alias, timestamps, profile)
+ * const metadataKey = createAccountKey('metadata', {
+ *   accountId: 'alice@gmail.com',
+ *   service: 'gmail'
+ * });
+ * // Returns: "alice@gmail.com:gmail:metadata"
+ *
+ * // Store DCR client registration info
+ * const dcrKey = createAccountKey('dcr-client', {
+ *   accountId: 'alice@outlook.com',
+ *   service: 'outlook'
+ * });
+ * // Returns: "alice@outlook.com:outlook:dcr-client"
+ * ```
+ */ export function createAccountKey(type, params) {
+    validateKeyParams(params);
+    return `${params.accountId}:${params.service}:${type}`;
+}
+/**
+ * Create service-scoped storage key.
+ *
+ * These keys are scoped to a service (not a specific account) and store
+ * service-level data like which account is active or the list of linked accounts.
+ *
+ * @param type - Key type ('active' for active account, 'linked' for account list)
+ * @param params - Service key parameters
+ * @returns Storage key in format: "{service}:{type}"
+ *
+ * @example
+ * ```typescript
+ * // Track active account
+ * const activeKey = createServiceKey('active', {
+ *   service: 'gmail'
+ * });
+ * // Returns: "gmail:active"
+ *
+ * // Store list of linked accounts
+ * const linkedKey = createServiceKey('linked', {
+ *   service: 'gmail'
+ * });
+ * // Returns: "gmail:linked"
+ * ```
+ */ export function createServiceKey(type, params) {
+    validateKeyParams(params);
+    return `${params.service}:${type}`;
+}
+/**
+ * Parse token key to extract components
+ *
+ * @param key - Storage key to parse
+ * @returns Object with accountId and service, or undefined if invalid format
+ *
+ * @example
+ * const parsed = parseTokenKey('user@gmail.com:gmail:token');
+ * // Returns: { accountId: 'user@gmail.com', service: 'gmail' }
+ *
+ * const invalid = parseTokenKey('invalid-key');
+ * // Returns: undefined
+ */ export function parseTokenKey(key) {
+    const parts = key.split(':');
+    if (parts.length !== 3 || parts[2] !== 'token' || !parts[0] || !parts[1]) {
+        return undefined;
+    }
+    return {
+        accountId: parts[0],
+        service: parts[1]
+    };
+}
+/**
+ * List all account IDs for a service
+ *
+ * Iterates token keys and returns all accountIds that match the service.
+ * Encapsulates key format details for forward compatibility.
+ *
+ * @param store - Keyv store to iterate
+ * @param service - Service name
+ * @returns Array of account IDs (e.g., email addresses)
+ *
+ * @example
+ * const accounts = await listAccountIds(store, 'gmail');
+ * // Returns: ['alice@gmail.com', 'bob@gmail.com']
+ *
+ * @example
+ * // Empty array if no accounts found
+ * const empty = await listAccountIds(store, 'unknown-service');
+ * // Returns: []
+ */ export async function listAccountIds(store, service) {
+    const accountIds = [];
+    try {
+        var _store_iterator;
+        const iterator = (_store_iterator = store.iterator) === null || _store_iterator === void 0 ? void 0 : _store_iterator.call(store, undefined);
+        if (!iterator) {
+            return accountIds;
+        }
+        for await (const [key] of iterator){
+            const parsed = parseTokenKey(key);
+            if (parsed && parsed.service === service) {
+                accountIds.push(parsed.accountId);
+            }
+        }
+    } catch (_error) {
+        // If iteration fails, return empty array (fail gracefully)
+        // This handles stores that don't support iteration
+        return accountIds;
+    }
+    return accountIds;
+}

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

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/oauth/oauth/src/key-utils.ts"],"sourcesContent":["/**\n * Key generation utilities for consistent storage key format\n *\n * Key format: {accountId}:{service}:{type}\n * Example: work@gmail.com:gmail:token\n */\n\nimport type { Keyv } from 'keyv';\n\n/**\n * Key types for account-scoped data (requires accountId)\n */\nexport type AccountKeyType = 'token' | 'metadata' | 'dcr-client';\n\n/**\n * Key types for service-scoped data (no accountId)\n */\nexport type ServiceKeyType = 'active' | 'linked';\n\n/**\n * Parameters for account-scoped keys.\n * All fields are required - no silent defaults.\n */\nexport interface AccountKeyParams {\n  /** Account identifier - typically an email address */\n  accountId: string;\n\n  /** Service name (e.g., 'gmail', 'sheets', 'drive', 'outlook') */\n  service: string;\n}\n\n/**\n * Parameters for service-scoped keys.\n * These keys don't include accountId.\n */\nexport interface ServiceKeyParams {\n  /** Service name */\n  service: string;\n}\n\n/**\n * Validate key parameters don't contain colon delimiter\n */\nfunction validateKeyParams(params: AccountKeyParams | ServiceKeyParams): void {\n  for (const [key, value] of Object.entries(params)) {\n    if (typeof value !== 'string') {\n      throw new Error(`Key parameter '${key}' must be a string, got: ${typeof value}`);\n    }\n    if (value.includes(':')) {\n      throw new Error(`Key parameter '${key}' cannot contain colon character: ${value}`);\n    }\n  }\n}\n\n/**\n * Create account-scoped storage key.\n *\n * These keys are scoped to a specific account (email address) and store\n * account-specific data like OAuth tokens and account metadata.\n *\n * @param type - Key type ('token' for OAuth tokens, 'metadata' for account details, 'dcr-client' for DCR registration)\n * @param params - Account key parameters with explicit field names\n * @returns Storage key in format: \"{accountId}:{service}:{type}\"\n *\n * @example\n * ```typescript\n * // Store OAuth token\n * const tokenKey = createAccountKey('token', {\n *   accountId: 'alice@gmail.com',\n *   service: 'gmail'\n * });\n * // Returns: \"alice@gmail.com:gmail:token\"\n *\n * // Store account metadata (alias, timestamps, profile)\n * const metadataKey = createAccountKey('metadata', {\n *   accountId: 'alice@gmail.com',\n *   service: 'gmail'\n * });\n * // Returns: \"alice@gmail.com:gmail:metadata\"\n *\n * // Store DCR client registration info\n * const dcrKey = createAccountKey('dcr-client', {\n *   accountId: 'alice@outlook.com',\n *   service: 'outlook'\n * });\n * // Returns: \"alice@outlook.com:outlook:dcr-client\"\n * ```\n */\nexport function createAccountKey(type: AccountKeyType, params: AccountKeyParams): string {\n  validateKeyParams(params);\n  return `${params.accountId}:${params.service}:${type}`;\n}\n\n/**\n * Create service-scoped storage key.\n *\n * These keys are scoped to a service (not a specific account) and store\n * service-level data like which account is active or the list of linked accounts.\n *\n * @param type - Key type ('active' for active account, 'linked' for account list)\n * @param params - Service key parameters\n * @returns Storage key in format: \"{service}:{type}\"\n *\n * @example\n * ```typescript\n * // Track active account\n * const activeKey = createServiceKey('active', {\n *   service: 'gmail'\n * });\n * // Returns: \"gmail:active\"\n *\n * // Store list of linked accounts\n * const linkedKey = createServiceKey('linked', {\n *   service: 'gmail'\n * });\n * // Returns: \"gmail:linked\"\n * ```\n */\nexport function createServiceKey(type: ServiceKeyType, params: ServiceKeyParams): string {\n  validateKeyParams(params);\n  return `${params.service}:${type}`;\n}\n\n/**\n * Parse token key to extract components\n *\n * @param key - Storage key to parse\n * @returns Object with accountId and service, or undefined if invalid format\n *\n * @example\n * const parsed = parseTokenKey('user@gmail.com:gmail:token');\n * // Returns: { accountId: 'user@gmail.com', service: 'gmail' }\n *\n * const invalid = parseTokenKey('invalid-key');\n * // Returns: undefined\n */\nexport function parseTokenKey(key: string): { accountId: string; service: string } | undefined {\n  const parts = key.split(':');\n  if (parts.length !== 3 || parts[2] !== 'token' || !parts[0] || !parts[1]) {\n    return undefined;\n  }\n  return {\n    accountId: parts[0],\n    service: parts[1],\n  };\n}\n\n/**\n * List all account IDs for a service\n *\n * Iterates token keys and returns all accountIds that match the service.\n * Encapsulates key format details for forward compatibility.\n *\n * @param store - Keyv store to iterate\n * @param service - Service name\n * @returns Array of account IDs (e.g., email addresses)\n *\n * @example\n * const accounts = await listAccountIds(store, 'gmail');\n * // Returns: ['alice@gmail.com', 'bob@gmail.com']\n *\n * @example\n * // Empty array if no accounts found\n * const empty = await listAccountIds(store, 'unknown-service');\n * // Returns: []\n */\nexport async function listAccountIds(store: Keyv, service: string): Promise<string[]> {\n  const accountIds: string[] = [];\n\n  try {\n    const iterator = store.iterator?.(undefined);\n    if (!iterator) {\n      return accountIds;\n    }\n\n    for await (const [key] of iterator) {\n      const parsed = parseTokenKey(key);\n      if (parsed && parsed.service === service) {\n        accountIds.push(parsed.accountId);\n      }\n    }\n  } catch (_error) {\n    // If iteration fails, return empty array (fail gracefully)\n    // This handles stores that don't support iteration\n    return accountIds;\n  }\n\n  return accountIds;\n}\n"],"names":["validateKeyParams","params","key","value","Object","entries","Error","includes","createAccountKey","type","accountId","service","createServiceKey","parseTokenKey","parts","split","length","undefined","listAccountIds","store","accountIds","iterator","parsed","push","_error"],"mappings":"AAAA;;;;;CAKC,GAmCD;;CAEC,GACD,SAASA,kBAAkBC,MAA2C;IACpE,KAAK,MAAM,CAACC,KAAKC,MAAM,IAAIC,OAAOC,OAAO,CAACJ,QAAS;QACjD,IAAI,OAAOE,UAAU,UAAU;YAC7B,MAAM,IAAIG,MAAM,CAAC,eAAe,EAAEJ,IAAI,yBAAyB,EAAE,OAAOC,OAAO;QACjF;QACA,IAAIA,MAAMI,QAAQ,CAAC,MAAM;YACvB,MAAM,IAAID,MAAM,CAAC,eAAe,EAAEJ,IAAI,kCAAkC,EAAEC,OAAO;QACnF;IACF;AACF;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiCC,GACD,OAAO,SAASK,iBAAiBC,IAAoB,EAAER,MAAwB;IAC7ED,kBAAkBC;IAClB,OAAO,GAAGA,OAAOS,SAAS,CAAC,CAAC,EAAET,OAAOU,OAAO,CAAC,CAAC,EAAEF,MAAM;AACxD;AAEA;;;;;;;;;;;;;;;;;;;;;;;;CAwBC,GACD,OAAO,SAASG,iBAAiBH,IAAoB,EAAER,MAAwB;IAC7ED,kBAAkBC;IAClB,OAAO,GAAGA,OAAOU,OAAO,CAAC,CAAC,EAAEF,MAAM;AACpC;AAEA;;;;;;;;;;;;CAYC,GACD,OAAO,SAASI,cAAcX,GAAW;IACvC,MAAMY,QAAQZ,IAAIa,KAAK,CAAC;IACxB,IAAID,MAAME,MAAM,KAAK,KAAKF,KAAK,CAAC,EAAE,KAAK,WAAW,CAACA,KAAK,CAAC,EAAE,IAAI,CAACA,KAAK,CAAC,EAAE,EAAE;QACxE,OAAOG;IACT;IACA,OAAO;QACLP,WAAWI,KAAK,CAAC,EAAE;QACnBH,SAASG,KAAK,CAAC,EAAE;IACnB;AACF;AAEA;;;;;;;;;;;;;;;;;;CAkBC,GACD,OAAO,eAAeI,eAAeC,KAAW,EAAER,OAAe;IAC/D,MAAMS,aAAuB,EAAE;IAE/B,IAAI;YACeD;QAAjB,MAAME,YAAWF,kBAAAA,MAAME,QAAQ,cAAdF,sCAAAA,qBAAAA,OAAiBF;QAClC,IAAI,CAACI,UAAU;YACb,OAAOD;QACT;QAEA,WAAW,MAAM,CAAClB,IAAI,IAAImB,SAAU;YAClC,MAAMC,SAAST,cAAcX;YAC7B,IAAIoB,UAAUA,OAAOX,OAAO,KAAKA,SAAS;gBACxCS,WAAWG,IAAI,CAACD,OAAOZ,SAAS;YAClC;QACF;IACF,EAAE,OAAOc,QAAQ;QACf,2DAA2D;QAC3D,mDAAmD;QACnD,OAAOJ;IACT;IAEA,OAAOA;AACT"}

package/dist/esm/lib/account-server/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Unified account management API for MCP servers.
+ *
+ * Provides two account management modes:
+ * - Loopback: Server-managed multi-account OAuth (LoopbackOAuthProvider)
+ * - Stateless: MCP client-managed OAuth (read-only status)
+ *
+ * @example
+ * // Loopback OAuth account management
+ * const {tools, prompts} = AccountServer.createLoopback({
+ *   service: 'gmail',
+ *   store: tokenStore,
+ *   logger,
+ *   auth: authProvider
+ * });
+ *
+ * @example
+ * // Stateless mode (MCP OAuth)
+ * const {tools, prompts} = AccountServer.createStateless({
+ *   service: 'gmail'
+ * });
+ */
+import { createLoopback } from './loopback.js';
+import { createStateless } from './stateless.js';
+export declare const AccountServer: {
+    /**
+     * Create loopback OAuth account management tools.
+     * Server manages multiple accounts with stored tokens (LoopbackOAuthProvider).
+     * Returns 4 tools: account-me, account-switch, account-remove, account-list.
+     * No prompts.
+     */
+    createLoopback: typeof createLoopback;
+    /**
+     * Create stateless mode tools.
+     * MCP client manages authentication. Server extracts user identity from bearer token.
+     * Returns 1 tool: account-me.
+     * No prompts.
+     */
+    createStateless: typeof createStateless;
+};
+export { createLoopback } from './loopback.js';
+export { createAccountMe } from './me.js';
+export { findAccountByEmailOrAlias } from './shared-utils.js';
+export { createStateless } from './stateless.js';
+export type { AccountLoopbackConfig, AccountMeConfig, AccountStatelessConfig } from './types.js';

package/dist/esm/lib/account-server/index.js

@@ -0,0 +1,41 @@
+/**
+ * Unified account management API for MCP servers.
+ *
+ * Provides two account management modes:
+ * - Loopback: Server-managed multi-account OAuth (LoopbackOAuthProvider)
+ * - Stateless: MCP client-managed OAuth (read-only status)
+ *
+ * @example
+ * // Loopback OAuth account management
+ * const {tools, prompts} = AccountServer.createLoopback({
+ *   service: 'gmail',
+ *   store: tokenStore,
+ *   logger,
+ *   auth: authProvider
+ * });
+ *
+ * @example
+ * // Stateless mode (MCP OAuth)
+ * const {tools, prompts} = AccountServer.createStateless({
+ *   service: 'gmail'
+ * });
+ */ import { createLoopback } from './loopback.js';
+import { createStateless } from './stateless.js';
+export const AccountServer = {
+    /**
+   * Create loopback OAuth account management tools.
+   * Server manages multiple accounts with stored tokens (LoopbackOAuthProvider).
+   * Returns 4 tools: account-me, account-switch, account-remove, account-list.
+   * No prompts.
+   */ createLoopback,
+    /**
+   * Create stateless mode tools.
+   * MCP client manages authentication. Server extracts user identity from bearer token.
+   * Returns 1 tool: account-me.
+   * No prompts.
+   */ createStateless
+};
+export { createLoopback } from './loopback.js';
+export { createAccountMe } from './me.js';
+export { findAccountByEmailOrAlias } from './shared-utils.js';
+export { createStateless } from './stateless.js';

package/dist/esm/lib/account-server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/oauth/oauth/src/lib/account-server/index.ts"],"sourcesContent":["/**\n * Unified account management API for MCP servers.\n *\n * Provides two account management modes:\n * - Loopback: Server-managed multi-account OAuth (LoopbackOAuthProvider)\n * - Stateless: MCP client-managed OAuth (read-only status)\n *\n * @example\n * // Loopback OAuth account management\n * const {tools, prompts} = AccountServer.createLoopback({\n *   service: 'gmail',\n *   store: tokenStore,\n *   logger,\n *   auth: authProvider\n * });\n *\n * @example\n * // Stateless mode (MCP OAuth)\n * const {tools, prompts} = AccountServer.createStateless({\n *   service: 'gmail'\n * });\n */\n\nimport { createLoopback } from './loopback.ts';\nimport { createStateless } from './stateless.ts';\n\nexport const AccountServer = {\n  /**\n   * Create loopback OAuth account management tools.\n   * Server manages multiple accounts with stored tokens (LoopbackOAuthProvider).\n   * Returns 4 tools: account-me, account-switch, account-remove, account-list.\n   * No prompts.\n   */\n  createLoopback,\n\n  /**\n   * Create stateless mode tools.\n   * MCP client manages authentication. Server extracts user identity from bearer token.\n   * Returns 1 tool: account-me.\n   * No prompts.\n   */\n  createStateless,\n};\n\nexport { createLoopback } from './loopback.ts';\nexport { createAccountMe } from './me.ts';\nexport { findAccountByEmailOrAlias } from './shared-utils.ts';\nexport { createStateless } from './stateless.ts';\nexport type { AccountLoopbackConfig, AccountMeConfig, AccountStatelessConfig } from './types.ts';\n"],"names":["createLoopback","createStateless","AccountServer","createAccountMe","findAccountByEmailOrAlias"],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;CAqBC,GAED,SAASA,cAAc,QAAQ,gBAAgB;AAC/C,SAASC,eAAe,QAAQ,iBAAiB;AAEjD,OAAO,MAAMC,gBAAgB;IAC3B;;;;;GAKC,GACDF;IAEA;;;;;GAKC,GACDC;AACF,EAAE;AAEF,SAASD,cAAc,QAAQ,gBAAgB;AAC/C,SAASG,eAAe,QAAQ,UAAU;AAC1C,SAASC,yBAAyB,QAAQ,oBAAoB;AAC9D,SAASH,eAAe,QAAQ,iBAAiB"}

package/dist/esm/lib/account-server/loopback.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Loopback OAuth account management tools.
+ *
+ * Provides account management for LoopbackOAuthProvider (server-managed multi-account).
+ * Users can add multiple accounts, switch between them, and manage identities.
+ *
+ * Tools:
+ * - account-me: Show current user identity (email, alias, session expiry)
+ * - account-switch: Use account (add if needed, switch if already linked)
+ * - account-remove: Remove account and delete tokens
+ * - account-list: Show all linked accounts (returns empty array if none)
+ */
+import type { McpPrompt, McpTool } from '../../types.js';
+import type { AccountLoopbackConfig } from './types.js';
+/**
+ * Create loopback OAuth account management tools.
+ * Returns 4 tools: account-me, account-switch, account-remove, account-list.
+ */
+export declare function createLoopback(config: AccountLoopbackConfig): {
+    tools: McpTool[];
+    prompts: McpPrompt[];
+};