@mcp-z/oauth-google 1.0.0

package/dist/esm/lib/token-verifier.d.ts

@@ -0,0 +1,44 @@
+/**
+ * DCR Token Verifier
+ *
+ * Validates bearer tokens by calling Authorization Server's verification endpoint.
+ * Implements proper AS/RS separation - Resource Server doesn't access token storage.
+ */
+import type { ProviderTokens } from '@mcp-z/oauth';
+/**
+ * Authentication information from token verification
+ */
+export interface AuthInfo {
+    /** Bearer access token */
+    token: string;
+    /** Client ID that owns the token */
+    clientId: string;
+    /** Granted scopes */
+    scopes: string[];
+    /** Token expiration timestamp (milliseconds since epoch) */
+    expiresAt: number;
+    /** Google provider tokens (if available) */
+    providerTokens?: ProviderTokens;
+}
+/**
+ * DCR Token Verifier validates access tokens via Authorization Server
+ *
+ * This implements proper OAuth 2.0 architecture where the Resource Server
+ * (MCP server) validates tokens by calling the Authorization Server's
+ * verification endpoint rather than accessing token storage directly.
+ */
+export declare class DcrTokenVerifier {
+    private verifyUrl;
+    /**
+     * @param verifyUrl - Authorization Server's /oauth/verify endpoint URL
+     */
+    constructor(verifyUrl: string);
+    /**
+     * Verify an access token by calling the Authorization Server
+     *
+     * @param token - Bearer access token to validate
+     * @returns AuthInfo with token metadata and provider tokens
+     * @throws Error if token is invalid or verification fails
+     */
+    verifyAccessToken(token: string): Promise<AuthInfo>;
+}

package/dist/esm/lib/token-verifier.js

@@ -0,0 +1,53 @@
+/**
+ * DCR Token Verifier
+ *
+ * Validates bearer tokens by calling Authorization Server's verification endpoint.
+ * Implements proper AS/RS separation - Resource Server doesn't access token storage.
+ */ /**
+ * DCR Token Verifier validates access tokens via Authorization Server
+ *
+ * This implements proper OAuth 2.0 architecture where the Resource Server
+ * (MCP server) validates tokens by calling the Authorization Server's
+ * verification endpoint rather than accessing token storage directly.
+ */ export class DcrTokenVerifier {
+    /**
+   * Verify an access token by calling the Authorization Server
+   *
+   * @param token - Bearer access token to validate
+   * @returns AuthInfo with token metadata and provider tokens
+   * @throws Error if token is invalid or verification fails
+   */ async verifyAccessToken(token) {
+        try {
+            const response = await fetch(this.verifyUrl, {
+                method: 'GET',
+                headers: {
+                    Authorization: `Bearer ${token}`
+                }
+            });
+            if (!response.ok) {
+                let errorMessage = 'Unknown error';
+                try {
+                    var _ref, _error_error_description;
+                    const error = await response.json();
+                    errorMessage = (_ref = (_error_error_description = error.error_description) !== null && _error_error_description !== void 0 ? _error_error_description : error.error) !== null && _ref !== void 0 ? _ref : errorMessage;
+                } catch  {
+                    // Failed to parse error JSON, use status text
+                    errorMessage = response.statusText;
+                }
+                throw new Error(`Token verification failed: ${errorMessage}`);
+            }
+            const authInfo = await response.json();
+            return authInfo;
+        } catch (error) {
+            if (error instanceof Error) {
+                throw error;
+            }
+            throw new Error(`Token verification failed: ${String(error)}`);
+        }
+    }
+    /**
+   * @param verifyUrl - Authorization Server's /oauth/verify endpoint URL
+   */ constructor(verifyUrl){
+        this.verifyUrl = verifyUrl;
+    }
+}

package/dist/esm/lib/token-verifier.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/oauth/oauth-google/src/lib/token-verifier.ts"],"sourcesContent":["/**\n * DCR Token Verifier\n *\n * Validates bearer tokens by calling Authorization Server's verification endpoint.\n * Implements proper AS/RS separation - Resource Server doesn't access token storage.\n */\n\nimport type { ProviderTokens } from '@mcp-z/oauth';\n\n/**\n * Authentication information from token verification\n */\nexport interface AuthInfo {\n  /** Bearer access token */\n  token: string;\n\n  /** Client ID that owns the token */\n  clientId: string;\n\n  /** Granted scopes */\n  scopes: string[];\n\n  /** Token expiration timestamp (milliseconds since epoch) */\n  expiresAt: number;\n\n  /** Google provider tokens (if available) */\n  providerTokens?: ProviderTokens;\n}\n\n/**\n * DCR Token Verifier validates access tokens via Authorization Server\n *\n * This implements proper OAuth 2.0 architecture where the Resource Server\n * (MCP server) validates tokens by calling the Authorization Server's\n * verification endpoint rather than accessing token storage directly.\n */\nexport class DcrTokenVerifier {\n  private verifyUrl: string;\n\n  /**\n   * @param verifyUrl - Authorization Server's /oauth/verify endpoint URL\n   */\n  constructor(verifyUrl: string) {\n    this.verifyUrl = verifyUrl;\n  }\n\n  /**\n   * Verify an access token by calling the Authorization Server\n   *\n   * @param token - Bearer access token to validate\n   * @returns AuthInfo with token metadata and provider tokens\n   * @throws Error if token is invalid or verification fails\n   */\n  async verifyAccessToken(token: string): Promise<AuthInfo> {\n    try {\n      const response = await fetch(this.verifyUrl, {\n        method: 'GET',\n        headers: {\n          Authorization: `Bearer ${token}`,\n        },\n      });\n\n      if (!response.ok) {\n        let errorMessage = 'Unknown error';\n        try {\n          const error = await response.json();\n          errorMessage = (error as { error_description?: string; error?: string }).error_description ?? (error as { error?: string }).error ?? errorMessage;\n        } catch {\n          // Failed to parse error JSON, use status text\n          errorMessage = response.statusText;\n        }\n        throw new Error(`Token verification failed: ${errorMessage}`);\n      }\n\n      const authInfo = (await response.json()) as AuthInfo;\n      return authInfo;\n    } catch (error) {\n      if (error instanceof Error) {\n        throw error;\n      }\n      throw new Error(`Token verification failed: ${String(error)}`);\n    }\n  }\n}\n"],"names":["DcrTokenVerifier","verifyAccessToken","token","response","fetch","verifyUrl","method","headers","Authorization","ok","errorMessage","error","json","error_description","statusText","Error","authInfo","String"],"mappings":"AAAA;;;;;CAKC,GAwBD;;;;;;CAMC,GACD,OAAO,MAAMA;IAUX;;;;;;GAMC,GACD,MAAMC,kBAAkBC,KAAa,EAAqB;QACxD,IAAI;YACF,MAAMC,WAAW,MAAMC,MAAM,IAAI,CAACC,SAAS,EAAE;gBAC3CC,QAAQ;gBACRC,SAAS;oBACPC,eAAe,CAAC,OAAO,EAAEN,OAAO;gBAClC;YACF;YAEA,IAAI,CAACC,SAASM,EAAE,EAAE;gBAChB,IAAIC,eAAe;gBACnB,IAAI;wBAEa,MAAA;oBADf,MAAMC,QAAQ,MAAMR,SAASS,IAAI;oBACjCF,gBAAe,QAAA,2BAAA,AAACC,MAAyDE,iBAAiB,cAA3E,sCAAA,2BAA+E,AAACF,MAA6BA,KAAK,cAAlH,kBAAA,OAAsHD;gBACvI,EAAE,OAAM;oBACN,8CAA8C;oBAC9CA,eAAeP,SAASW,UAAU;gBACpC;gBACA,MAAM,IAAIC,MAAM,CAAC,2BAA2B,EAAEL,cAAc;YAC9D;YAEA,MAAMM,WAAY,MAAMb,SAASS,IAAI;YACrC,OAAOI;QACT,EAAE,OAAOL,OAAO;YACd,IAAIA,iBAAiBI,OAAO;gBAC1B,MAAMJ;YACR;YACA,MAAM,IAAII,MAAM,CAAC,2BAA2B,EAAEE,OAAON,QAAQ;QAC/D;IACF;IA3CA;;GAEC,GACD,YAAYN,SAAiB,CAAE;QAC7B,IAAI,CAACA,SAAS,GAAGA;IACnB;AAuCF"}

package/dist/esm/package.json

@@ -0,0 +1 @@
+{ "type": "module" }

package/dist/esm/providers/dcr.d.ts

@@ -0,0 +1,107 @@
+/**
+ * DCR Provider - Stateless Dynamic Client Registration Provider
+ *
+ * Implements stateless provider pattern where provider tokens are received from
+ * token verification context rather than managed by the provider itself.
+ *
+ * Use case: MCP HTTP servers with DCR authentication where client manages tokens
+ * and provider only handles Google API calls with provided credentials.
+ */
+import type { ProviderTokens } from '@mcp-z/oauth';
+import { OAuth2Client } from 'google-auth-library';
+import type { Logger } from '../types.js';
+/**
+ * DCR Provider configuration
+ */
+export interface DcrOAuthProviderConfig {
+    /** Google application client ID */
+    clientId: string;
+    /** Google application client secret (optional for public clients) */
+    clientSecret?: string;
+    /** OAuth scopes */
+    scope: string;
+    /** DCR token verification endpoint URL (e.g., http://localhost:3000/oauth/verify) */
+    verifyEndpoint: string;
+    /** Logger for auth operations */
+    logger: Logger;
+}
+/**
+ * DCR Provider - Stateless OAuth provider for Dynamic Client Registration
+ *
+ * Unlike LoopbackOAuthProvider which manages token storage, DcrOAuthProvider is stateless:
+ * - Receives provider tokens from verification context (HTTP bearer auth)
+ * - Creates auth providers on-demand from tokens
+ * - Handles token refresh using Google OAuth 2.0
+ * - No token storage dependency
+ *
+ * Pattern:
+ * ```typescript
+ * const provider = new DcrOAuthProvider(config);
+ * const auth = provider.toAuth(providerTokens);
+ * const accessToken = await getAccessToken(auth);
+ * ```
+ */
+export declare class DcrOAuthProvider {
+    private config;
+    private emailCache;
+    constructor(config: DcrOAuthProviderConfig);
+    /**
+     * Create Google OAuth2Client from provider tokens
+     *
+     * This is the core stateless pattern - provider receives tokens from context
+     * (token verification, HTTP request) and creates OAuth2Client on-demand.
+     *
+     * @param tokens - Provider tokens (Google access/refresh tokens)
+     * @returns Google OAuth2Client configured with credentials
+     */
+    toAuth(tokens: ProviderTokens): OAuth2Client;
+    /**
+     * Check if token needs refresh (with 1 minute buffer)
+     */
+    private needsRefresh;
+    /**
+     * Refresh Google access token using refresh token
+     *
+     * @param refreshToken - Google refresh token
+     * @returns New provider tokens
+     */
+    refreshAccessToken(refreshToken: string): Promise<ProviderTokens>;
+    /**
+     * Get user email from Google userinfo API (with caching)
+     *
+     * @param tokens - Provider tokens to use for API call
+     * @returns User's email address
+     */
+    getUserEmail(tokens: ProviderTokens): Promise<string>;
+    /**
+     * Auth middleware for HTTP servers with DCR bearer auth
+     * Validates bearer tokens and enriches extra with provider tokens
+     *
+     * Pattern:
+     * ```typescript
+     * const provider = new DcrOAuthProvider({ ..., verifyEndpoint: 'http://localhost:3000/oauth/verify' });
+     * const authMiddleware = provider.authMiddleware();
+     * const tools = toolFactories.map(f => f()).map(authMiddleware.withToolAuth);
+     * const resources = resourceFactories.map(f => f()).map(authMiddleware.withResourceAuth);
+     * const prompts = promptFactories.map(f => f()).map(authMiddleware.withPromptAuth);
+     * ```
+     */
+    authMiddleware(): {
+        withToolAuth: <T extends {
+            name: string;
+            config: unknown;
+            handler: unknown;
+        }>(module: T) => T;
+        withResourceAuth: <T extends {
+            name: string;
+            template?: unknown;
+            config?: unknown;
+            handler: unknown;
+        }>(module: T) => T;
+        withPromptAuth: <T extends {
+            name: string;
+            config: unknown;
+            handler: unknown;
+        }>(module: T) => T;
+    };
+}

package/dist/esm/providers/dcr.js

@@ -0,0 +1,242 @@
+/**
+ * DCR Provider - Stateless Dynamic Client Registration Provider
+ *
+ * Implements stateless provider pattern where provider tokens are received from
+ * token verification context rather than managed by the provider itself.
+ *
+ * Use case: MCP HTTP servers with DCR authentication where client manages tokens
+ * and provider only handles Google API calls with provided credentials.
+ */ import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { OAuth2Client } from 'google-auth-library';
+/**
+ * DCR Provider - Stateless OAuth provider for Dynamic Client Registration
+ *
+ * Unlike LoopbackOAuthProvider which manages token storage, DcrOAuthProvider is stateless:
+ * - Receives provider tokens from verification context (HTTP bearer auth)
+ * - Creates auth providers on-demand from tokens
+ * - Handles token refresh using Google OAuth 2.0
+ * - No token storage dependency
+ *
+ * Pattern:
+ * ```typescript
+ * const provider = new DcrOAuthProvider(config);
+ * const auth = provider.toAuth(providerTokens);
+ * const accessToken = await getAccessToken(auth);
+ * ```
+ */ export class DcrOAuthProvider {
+    /**
+   * Create Google OAuth2Client from provider tokens
+   *
+   * This is the core stateless pattern - provider receives tokens from context
+   * (token verification, HTTP request) and creates OAuth2Client on-demand.
+   *
+   * @param tokens - Provider tokens (Google access/refresh tokens)
+   * @returns Google OAuth2Client configured with credentials
+   */ toAuth(tokens) {
+        var _tokens_refreshToken, _tokens_expiresAt;
+        const { clientId, clientSecret } = this.config;
+        // Create OAuth2Client with credentials
+        const client = new OAuth2Client({
+            clientId,
+            ...clientSecret && {
+                clientSecret
+            }
+        });
+        // Set initial credentials (convert undefined to null for Google's Credentials type)
+        client.credentials = {
+            access_token: tokens.accessToken,
+            refresh_token: (_tokens_refreshToken = tokens.refreshToken) !== null && _tokens_refreshToken !== void 0 ? _tokens_refreshToken : null,
+            expiry_date: (_tokens_expiresAt = tokens.expiresAt) !== null && _tokens_expiresAt !== void 0 ? _tokens_expiresAt : null,
+            token_type: 'Bearer'
+        };
+        // Override getRequestMetadataAsync to handle token refresh
+        // @ts-expect-error - Access protected method for token refresh
+        const originalGetMetadata = client.getRequestMetadataAsync.bind(client);
+        // @ts-expect-error - Override protected method for token refresh
+        client.getRequestMetadataAsync = async (url)=>{
+            // Check if token needs refresh
+            if (this.needsRefresh(client.credentials.expiry_date)) {
+                try {
+                    // Use built-in refresh mechanism
+                    const refreshedTokens = await client.refreshAccessToken();
+                    client.credentials = refreshedTokens.credentials;
+                } catch (error) {
+                    throw new Error(`Token refresh failed: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            return originalGetMetadata(url);
+        };
+        return client;
+    }
+    /**
+   * Check if token needs refresh (with 1 minute buffer)
+   */ needsRefresh(expiryDate) {
+        if (!expiryDate) return false; // No expiry = no refresh needed
+        return Date.now() >= expiryDate - 60000; // 1 minute buffer
+    }
+    /**
+   * Refresh Google access token using refresh token
+   *
+   * @param refreshToken - Google refresh token
+   * @returns New provider tokens
+   */ async refreshAccessToken(refreshToken) {
+        const { clientId, clientSecret } = this.config;
+        const tokenUrl = 'https://oauth2.googleapis.com/token';
+        const params = {
+            refresh_token: refreshToken,
+            client_id: clientId,
+            grant_type: 'refresh_token'
+        };
+        // Only include client_secret for confidential clients
+        if (clientSecret) {
+            params.client_secret = clientSecret;
+        }
+        const body = new URLSearchParams(params);
+        const response = await fetch(tokenUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded'
+            },
+            body: body.toString()
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Token refresh failed: ${response.status} ${errorText}`);
+        }
+        const tokenResponse = await response.json();
+        const result = {
+            accessToken: tokenResponse.access_token,
+            refreshToken: refreshToken
+        };
+        // Only add optional fields if they have values
+        if (tokenResponse.expires_in !== undefined) {
+            result.expiresAt = Date.now() + tokenResponse.expires_in * 1000;
+        }
+        if (tokenResponse.scope !== undefined) {
+            result.scope = tokenResponse.scope;
+        }
+        return result;
+    }
+    /**
+   * Get user email from Google userinfo API (with caching)
+   *
+   * @param tokens - Provider tokens to use for API call
+   * @returns User's email address
+   */ async getUserEmail(tokens) {
+        var _tokens_expiresAt;
+        const cacheKey = tokens.accessToken;
+        const cached = this.emailCache.get(cacheKey);
+        // Check cache (with same expiry as access token)
+        if (cached && Date.now() < cached.expiresAt) {
+            return cached.email;
+        }
+        const auth = this.toAuth(tokens);
+        // Use OAuth2Client to make authenticated request
+        const response = await auth.request({
+            url: 'https://www.googleapis.com/oauth2/v2/userinfo',
+            method: 'GET'
+        });
+        const userInfo = response.data;
+        const email = userInfo.email;
+        // Cache with token expiration (default 1 hour if not specified)
+        this.emailCache.set(cacheKey, {
+            email,
+            expiresAt: (_tokens_expiresAt = tokens.expiresAt) !== null && _tokens_expiresAt !== void 0 ? _tokens_expiresAt : Date.now() + 3600000
+        });
+        return email;
+    }
+    /**
+   * Auth middleware for HTTP servers with DCR bearer auth
+   * Validates bearer tokens and enriches extra with provider tokens
+   *
+   * Pattern:
+   * ```typescript
+   * const provider = new DcrOAuthProvider({ ..., verifyEndpoint: 'http://localhost:3000/oauth/verify' });
+   * const authMiddleware = provider.authMiddleware();
+   * const tools = toolFactories.map(f => f()).map(authMiddleware.withToolAuth);
+   * const resources = resourceFactories.map(f => f()).map(authMiddleware.withResourceAuth);
+   * const prompts = promptFactories.map(f => f()).map(authMiddleware.withPromptAuth);
+   * ```
+   */ authMiddleware() {
+        // Shared wrapper logic - extracts extra parameter from specified position
+        // Generic T captures the actual module type; handler is cast from unknown to callable
+        const wrapAtPosition = (module, extraPosition)=>{
+            const originalHandler = module.handler;
+            const wrappedHandler = async (...allArgs)=>{
+                var _extra_requestInfo;
+                // Extract extra from the correct position
+                const extra = allArgs[extraPosition];
+                // Extract DCR bearer token from SDK's authInfo (if present) or request headers
+                let bearerToken;
+                // Option 1: Token already verified by SDK's bearerAuth middleware
+                if (extra.authInfo && typeof extra.authInfo === 'object') {
+                    var _ref;
+                    // authInfo contains the validated token - extract it
+                    // The SDK's bearerAuth middleware already validated it, but we need the raw token for /oauth/verify
+                    // Check if authInfo has the token directly, otherwise extract from headers
+                    const authInfo = extra.authInfo;
+                    bearerToken = (_ref = typeof authInfo.accessToken === 'string' ? authInfo.accessToken : undefined) !== null && _ref !== void 0 ? _ref : typeof authInfo.token === 'string' ? authInfo.token : undefined;
+                }
+                // Option 2: Extract from Authorization header
+                if (!bearerToken && ((_extra_requestInfo = extra.requestInfo) === null || _extra_requestInfo === void 0 ? void 0 : _extra_requestInfo.headers)) {
+                    const authHeader = extra.requestInfo.headers.authorization || extra.requestInfo.headers.Authorization;
+                    if (authHeader) {
+                        // Handle both string and string[] types
+                        const headerValue = Array.isArray(authHeader) ? authHeader[0] : authHeader;
+                        if (headerValue) {
+                            const match = /^Bearer\s+(.+)$/i.exec(headerValue);
+                            if (match) {
+                                bearerToken = match[1];
+                            }
+                        }
+                    }
+                }
+                if (!bearerToken) {
+                    throw new McpError(ErrorCode.InvalidRequest, 'Missing Authorization header. DCR mode requires bearer token.');
+                }
+                // Call /oauth/verify to validate DCR token and get provider tokens
+                const verifyResponse = await fetch(this.config.verifyEndpoint, {
+                    headers: {
+                        Authorization: `Bearer ${bearerToken}`
+                    }
+                });
+                if (!verifyResponse.ok) {
+                    throw new McpError(ErrorCode.InvalidRequest, `Token verification failed: ${verifyResponse.status}`);
+                }
+                const verifyData = await verifyResponse.json();
+                // Fetch user email to use as accountId (with caching)
+                let accountId;
+                try {
+                    accountId = await this.getUserEmail(verifyData.providerTokens);
+                } catch (error) {
+                    throw new McpError(ErrorCode.InternalError, `Failed to get user email for DCR authentication: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                // Create auth client from provider tokens
+                const auth = this.toAuth(verifyData.providerTokens);
+                // Inject authContext and logger into extra
+                extra.authContext = {
+                    auth,
+                    accountId
+                };
+                extra.logger = this.config.logger;
+                // Call original handler with all args
+                return await originalHandler(...allArgs);
+            };
+            return {
+                ...module,
+                handler: wrappedHandler
+            };
+        };
+        return {
+            // Use structural constraints to avoid contravariance check on handler type.
+            // wrapAtPosition is now generic and returns T directly.
+            withToolAuth: (module)=>wrapAtPosition(module, 1),
+            withResourceAuth: (module)=>wrapAtPosition(module, 2),
+            withPromptAuth: (module)=>wrapAtPosition(module, 0)
+        };
+    }
+    constructor(config){
+        this.emailCache = new Map();
+        this.config = config;
+    }
+}

package/dist/esm/providers/dcr.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/oauth/oauth-google/src/providers/dcr.ts"],"sourcesContent":["/**\n * DCR Provider - Stateless Dynamic Client Registration Provider\n *\n * Implements stateless provider pattern where provider tokens are received from\n * token verification context rather than managed by the provider itself.\n *\n * Use case: MCP HTTP servers with DCR authentication where client manages tokens\n * and provider only handles Google API calls with provided credentials.\n */\n\nimport type { ProviderTokens } from '@mcp-z/oauth';\nimport { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';\nimport { OAuth2Client } from 'google-auth-library';\nimport type { AuthContext, EnrichedExtra, Logger } from '../types.ts';\n\n/**\n * DCR Provider configuration\n */\nexport interface DcrOAuthProviderConfig {\n  /** Google application client ID */\n  clientId: string;\n\n  /** Google application client secret (optional for public clients) */\n  clientSecret?: string;\n\n  /** OAuth scopes */\n  scope: string;\n\n  /** DCR token verification endpoint URL (e.g., http://localhost:3000/oauth/verify) */\n  verifyEndpoint: string;\n\n  /** Logger for auth operations */\n  logger: Logger;\n}\n\n/**\n * Google TokenResponse\n */\ninterface TokenResponse {\n  access_token: string;\n  refresh_token?: string;\n  expires_in?: number;\n  scope?: string;\n  token_type?: string;\n}\n\n/**\n * DCR Provider - Stateless OAuth provider for Dynamic Client Registration\n *\n * Unlike LoopbackOAuthProvider which manages token storage, DcrOAuthProvider is stateless:\n * - Receives provider tokens from verification context (HTTP bearer auth)\n * - Creates auth providers on-demand from tokens\n * - Handles token refresh using Google OAuth 2.0\n * - No token storage dependency\n *\n * Pattern:\n * ```typescript\n * const provider = new DcrOAuthProvider(config);\n * const auth = provider.toAuth(providerTokens);\n * const accessToken = await getAccessToken(auth);\n * ```\n */\nexport class DcrOAuthProvider {\n  private config: DcrOAuthProviderConfig;\n  private emailCache = new Map<string, { email: string; expiresAt: number }>();\n\n  constructor(config: DcrOAuthProviderConfig) {\n    this.config = config;\n  }\n\n  /**\n   * Create Google OAuth2Client from provider tokens\n   *\n   * This is the core stateless pattern - provider receives tokens from context\n   * (token verification, HTTP request) and creates OAuth2Client on-demand.\n   *\n   * @param tokens - Provider tokens (Google access/refresh tokens)\n   * @returns Google OAuth2Client configured with credentials\n   */\n  toAuth(tokens: ProviderTokens): OAuth2Client {\n    const { clientId, clientSecret } = this.config;\n\n    // Create OAuth2Client with credentials\n    const client = new OAuth2Client({\n      clientId,\n      ...(clientSecret && { clientSecret }),\n    });\n\n    // Set initial credentials (convert undefined to null for Google's Credentials type)\n    client.credentials = {\n      access_token: tokens.accessToken,\n      refresh_token: tokens.refreshToken ?? null,\n      expiry_date: tokens.expiresAt ?? null,\n      token_type: 'Bearer',\n    };\n\n    // Override getRequestMetadataAsync to handle token refresh\n    // @ts-expect-error - Access protected method for token refresh\n    const originalGetMetadata = client.getRequestMetadataAsync.bind(client);\n\n    // @ts-expect-error - Override protected method for token refresh\n    client.getRequestMetadataAsync = async (url?: string) => {\n      // Check if token needs refresh\n      if (this.needsRefresh(client.credentials.expiry_date)) {\n        try {\n          // Use built-in refresh mechanism\n          const refreshedTokens = await client.refreshAccessToken();\n          client.credentials = refreshedTokens.credentials;\n        } catch (error) {\n          throw new Error(`Token refresh failed: ${error instanceof Error ? error.message : String(error)}`);\n        }\n      }\n\n      return originalGetMetadata(url);\n    };\n\n    return client;\n  }\n\n  /**\n   * Check if token needs refresh (with 1 minute buffer)\n   */\n  private needsRefresh(expiryDate: number | null | undefined): boolean {\n    if (!expiryDate) return false; // No expiry = no refresh needed\n    return Date.now() >= expiryDate - 60000; // 1 minute buffer\n  }\n\n  /**\n   * Refresh Google access token using refresh token\n   *\n   * @param refreshToken - Google refresh token\n   * @returns New provider tokens\n   */\n  async refreshAccessToken(refreshToken: string): Promise<ProviderTokens> {\n    const { clientId, clientSecret } = this.config;\n\n    const tokenUrl = 'https://oauth2.googleapis.com/token';\n    const params: Record<string, string> = {\n      refresh_token: refreshToken,\n      client_id: clientId,\n      grant_type: 'refresh_token',\n    };\n\n    // Only include client_secret for confidential clients\n    if (clientSecret) {\n      params.client_secret = clientSecret;\n    }\n\n    const body = new URLSearchParams(params);\n\n    const response = await fetch(tokenUrl, {\n      method: 'POST',\n      headers: {\n        'Content-Type': 'application/x-www-form-urlencoded',\n      },\n      body: body.toString(),\n    });\n\n    if (!response.ok) {\n      const errorText = await response.text();\n      throw new Error(`Token refresh failed: ${response.status} ${errorText}`);\n    }\n\n    const tokenResponse = (await response.json()) as TokenResponse;\n\n    const result: ProviderTokens = {\n      accessToken: tokenResponse.access_token,\n      refreshToken: refreshToken, // Keep original refresh token\n    };\n\n    // Only add optional fields if they have values\n    if (tokenResponse.expires_in !== undefined) {\n      result.expiresAt = Date.now() + tokenResponse.expires_in * 1000;\n    }\n    if (tokenResponse.scope !== undefined) {\n      result.scope = tokenResponse.scope;\n    }\n\n    return result;\n  }\n\n  /**\n   * Get user email from Google userinfo API (with caching)\n   *\n   * @param tokens - Provider tokens to use for API call\n   * @returns User's email address\n   */\n  async getUserEmail(tokens: ProviderTokens): Promise<string> {\n    const cacheKey = tokens.accessToken;\n    const cached = this.emailCache.get(cacheKey);\n\n    // Check cache (with same expiry as access token)\n    if (cached && Date.now() < cached.expiresAt) {\n      return cached.email;\n    }\n\n    const auth = this.toAuth(tokens);\n\n    // Use OAuth2Client to make authenticated request\n    const response = await auth.request({\n      url: 'https://www.googleapis.com/oauth2/v2/userinfo',\n      method: 'GET',\n    });\n\n    const userInfo = response.data as { email: string };\n    const email = userInfo.email;\n\n    // Cache with token expiration (default 1 hour if not specified)\n    this.emailCache.set(cacheKey, {\n      email,\n      expiresAt: tokens.expiresAt ?? Date.now() + 3600000,\n    });\n\n    return email;\n  }\n\n  /**\n   * Auth middleware for HTTP servers with DCR bearer auth\n   * Validates bearer tokens and enriches extra with provider tokens\n   *\n   * Pattern:\n   * ```typescript\n   * const provider = new DcrOAuthProvider({ ..., verifyEndpoint: 'http://localhost:3000/oauth/verify' });\n   * const authMiddleware = provider.authMiddleware();\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   */\n  authMiddleware() {\n    // Shared wrapper logic - extracts extra parameter from specified position\n    // Generic T captures the actual module type; handler is cast from unknown to callable\n    const wrapAtPosition = <T extends { name: string; handler: unknown; [key: string]: unknown }>(module: T, extraPosition: number): T => {\n      const originalHandler = module.handler as (...args: unknown[]) => Promise<unknown>;\n\n      const wrappedHandler = async (...allArgs: unknown[]) => {\n        // Extract extra from the correct position\n        const extra = allArgs[extraPosition] as EnrichedExtra;\n\n        // Extract DCR bearer token from SDK's authInfo (if present) or request headers\n        let bearerToken: string | undefined;\n\n        // Option 1: Token already verified by SDK's bearerAuth middleware\n        if (extra.authInfo && typeof extra.authInfo === 'object') {\n          // authInfo contains the validated token - extract it\n          // The SDK's bearerAuth middleware already validated it, but we need the raw token for /oauth/verify\n          // Check if authInfo has the token directly, otherwise extract from headers\n          const authInfo = extra.authInfo as unknown as Record<string, unknown>;\n          bearerToken = (typeof authInfo.accessToken === 'string' ? authInfo.accessToken : undefined) ?? (typeof authInfo.token === 'string' ? authInfo.token : undefined);\n        }\n\n        // Option 2: Extract from Authorization header\n        if (!bearerToken && extra.requestInfo?.headers) {\n          const authHeader = extra.requestInfo.headers.authorization || extra.requestInfo.headers.Authorization;\n          if (authHeader) {\n            // Handle both string and string[] types\n            const headerValue = Array.isArray(authHeader) ? authHeader[0] : authHeader;\n            if (headerValue) {\n              const match = /^Bearer\\s+(.+)$/i.exec(headerValue);\n              if (match) {\n                bearerToken = match[1];\n              }\n            }\n          }\n        }\n\n        if (!bearerToken) {\n          throw new McpError(ErrorCode.InvalidRequest, 'Missing Authorization header. DCR mode requires bearer token.');\n        }\n\n        // Call /oauth/verify to validate DCR token and get provider tokens\n        const verifyResponse = await fetch(this.config.verifyEndpoint, {\n          headers: { Authorization: `Bearer ${bearerToken}` },\n        });\n\n        if (!verifyResponse.ok) {\n          throw new McpError(ErrorCode.InvalidRequest, `Token verification failed: ${verifyResponse.status}`);\n        }\n\n        const verifyData = (await verifyResponse.json()) as {\n          providerTokens: ProviderTokens;\n        };\n\n        // Fetch user email to use as accountId (with caching)\n        let accountId: string;\n        try {\n          accountId = await this.getUserEmail(verifyData.providerTokens);\n        } catch (error) {\n          throw new McpError(ErrorCode.InternalError, `Failed to get user email for DCR authentication: ${error instanceof Error ? error.message : String(error)}`);\n        }\n\n        // Create auth client from provider tokens\n        const auth = this.toAuth(verifyData.providerTokens);\n\n        // Inject authContext and logger into extra\n        (extra as { authContext?: AuthContext }).authContext = {\n          auth,\n          accountId, // User's email address\n        };\n        (extra as { logger?: unknown }).logger = this.config.logger;\n\n        // Call original handler with all args\n        return await originalHandler(...allArgs);\n      };\n\n      return {\n        ...module,\n        handler: wrappedHandler,\n      } as T;\n    };\n\n    return {\n      // Use structural constraints to avoid contravariance check on handler type.\n      // wrapAtPosition is now generic and returns T directly.\n      withToolAuth: <T extends { name: string; config: unknown; handler: unknown }>(module: T) => wrapAtPosition(module, 1),\n      withResourceAuth: <T extends { name: string; template?: unknown; config?: unknown; handler: unknown }>(module: T) => wrapAtPosition(module, 2),\n      withPromptAuth: <T extends { name: string; config: unknown; handler: unknown }>(module: T) => wrapAtPosition(module, 0),\n    };\n  }\n}\n"],"names":["ErrorCode","McpError","OAuth2Client","DcrOAuthProvider","toAuth","tokens","clientId","clientSecret","config","client","credentials","access_token","accessToken","refresh_token","refreshToken","expiry_date","expiresAt","token_type","originalGetMetadata","getRequestMetadataAsync","bind","url","needsRefresh","refreshedTokens","refreshAccessToken","error","Error","message","String","expiryDate","Date","now","tokenUrl","params","client_id","grant_type","client_secret","body","URLSearchParams","response","fetch","method","headers","toString","ok","errorText","text","status","tokenResponse","json","result","expires_in","undefined","scope","getUserEmail","cacheKey","cached","emailCache","get","email","auth","request","userInfo","data","set","authMiddleware","wrapAtPosition","module","extraPosition","originalHandler","handler","wrappedHandler","allArgs","extra","bearerToken","authInfo","token","requestInfo","authHeader","authorization","Authorization","headerValue","Array","isArray","match","exec","InvalidRequest","verifyResponse","verifyEndpoint","verifyData","accountId","providerTokens","InternalError","authContext","logger","withToolAuth","withResourceAuth","withPromptAuth","Map"],"mappings":"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"}

package/dist/esm/providers/loopback-oauth.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Loopback OAuth Implementation (RFC 8252)
+ *
+ * Implements OAuth 2.0 Authorization Code Flow with PKCE using loopback interface redirection.
+ * Uses ephemeral local server with OS-assigned port (RFC 8252 Section 8.3).
+ */
+import { type OAuth2TokenStorageProvider } from '@mcp-z/oauth';
+import { OAuth2Client } from 'google-auth-library';
+import { type LoopbackOAuthConfig } from '../types.js';
+/**
+ * Loopback OAuth Client (RFC 8252 Section 7.3)
+ *
+ * Implements OAuth 2.0 Authorization Code Flow with PKCE for native applications
+ * using loopback interface redirection. Manages ephemeral OAuth flows and token persistence
+ * with Keyv for key-based token storage using compound keys.
+ *
+ * Token key format: {accountId}:{service}:token (e.g., "user@example.com:gmail:token")
+ */
+export declare class LoopbackOAuthProvider implements OAuth2TokenStorageProvider {
+    private config;
+    constructor(config: LoopbackOAuthConfig);
+    /**
+     * Get access token from Keyv using compound key
+     *
+     * @param accountId - Account identifier (email address). Required for loopback OAuth.
+     * @returns Access token for API requests
+     */
+    getAccessToken(accountId?: string): Promise<string>;
+    /**
+     * Convert to googleapis-compatible OAuth2Client
+     *
+     * @param accountId - Account identifier for multi-account support (e.g., 'user@example.com')
+     * @returns OAuth2Client configured for the specified account
+     */
+    toAuth(accountId?: string): OAuth2Client;
+    /**
+     * Authenticate new account with OAuth flow
+     * Triggers account selection, stores token, registers account
+     *
+     * @returns Email address of newly authenticated account
+     * @throws Error in headless mode (cannot open browser for OAuth)
+     */
+    authenticateNewAccount(): Promise<string>;
+    /**
+     * Get user email from Google's userinfo endpoint (pure query)
+     * Used to query email for existing authenticated account
+     *
+     * @param accountId - Account identifier to get email for
+     * @returns User's email address
+     */
+    getUserEmail(accountId?: string): Promise<string>;
+    /**
+     * Check for existing accounts in token storage (incremental OAuth detection)
+     *
+     * Uses key-utils helper for forward compatibility with key format changes.
+     *
+     * @returns Array of account IDs that have tokens for this service
+     */
+    private getExistingAccounts;
+    private isTokenValid;
+    /**
+     * Fetch user email from Google OAuth2 userinfo endpoint
+     * Called during OAuth flow to get email for accountId
+     *
+     * @param accessToken - Fresh access token from OAuth exchange
+     * @returns User's email address
+     */
+    private fetchUserEmailFromToken;
+    private performEphemeralOAuthFlow;
+    private exchangeCodeForToken;
+    private refreshAccessToken;
+    /**
+     * Create authentication middleware for MCP tools, resources, and prompts
+     *
+     * Returns position-aware middleware wrappers that enrich handlers with authentication context.
+     * The middleware handles token retrieval, refresh, and AuthRequiredError automatically.
+     *
+     * Single-user middleware for desktop/CLI apps where ONE user runs the entire process:
+     * - Desktop applications (Claude Desktop)
+     * - CLI tools (Gmail CLI)
+     * - Personal automation scripts
+     *
+     * All requests use token lookups based on the active account or account override.
+     *
+     * @returns Object with withToolAuth, withResourceAuth, withPromptAuth methods
+     *
+     * @example
+     * ```typescript
+     * const loopback = new LoopbackOAuthProvider({ service: 'gmail', ... });
+     * const authMiddleware = loopback.authMiddleware();
+     * const tools = toolFactories.map(f => f()).map(authMiddleware.withToolAuth);
+     * const resources = resourceFactories.map(f => f()).map(authMiddleware.withResourceAuth);
+     * const prompts = promptFactories.map(f => f()).map(authMiddleware.withPromptAuth);
+     * ```
+     */
+    authMiddleware(): {
+        withToolAuth: <T extends {
+            name: string;
+            config: unknown;
+            handler: unknown;
+        }>(module: T) => T;
+        withResourceAuth: <T extends {
+            name: string;
+            template?: unknown;
+            config?: unknown;
+            handler: unknown;
+        }>(module: T) => T;
+        withPromptAuth: <T extends {
+            name: string;
+            config: unknown;
+            handler: unknown;
+        }>(module: T) => T;
+    };
+}
+/**
+ * Create a loopback OAuth client for Google services
+ * Works for both stdio and HTTP transports
+ */
+export declare function createGoogleFileAuth(config: LoopbackOAuthConfig): OAuth2TokenStorageProvider;