@mcp-z/oauth-google 1.0.0 → 1.0.2

package/dist/cjs/lib/loopback-router.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/mcp-z/oauth-google/src/lib/loopback-router.ts"],"sourcesContent":["/**\n * Loopback OAuth callback router\n *\n * Handles GET /oauth/callback for persistent redirectUri deployments.\n */\n\nimport { getErrorTemplate, getSuccessTemplate } from '@mcp-z/oauth';\nimport type { Request, Response } from 'express';\nimport express from 'express';\nimport type { LoopbackOAuthProvider } from '../providers/loopback-oauth.ts';\n\nexport function createLoopbackCallbackRouter(provider: LoopbackOAuthProvider): express.Router {\n  const router = express.Router();\n\n  router.get('/oauth/callback', async (req: Request, res: Response) => {\n    const code = typeof req.query.code === 'string' ? req.query.code : undefined;\n    const state = typeof req.query.state === 'string' ? req.query.state : undefined;\n    const error = typeof req.query.error === 'string' ? req.query.error : undefined;\n\n    if (error) {\n      res.status(400).send(getErrorTemplate(error));\n      return;\n    }\n\n    if (!code) {\n      res.status(400).send(getErrorTemplate('No authorization code received'));\n      return;\n    }\n\n    try {\n      await provider.handleOAuthCallback({ code, state });\n      res.status(200).send(getSuccessTemplate());\n    } catch (callbackError) {\n      res.status(500).send(getErrorTemplate(callbackError instanceof Error ? callbackError.message : 'Token exchange failed'));\n    }\n  });\n\n  return router;\n}\n"],"names":["createLoopbackCallbackRouter","provider","router","express","Router","get","req","res","code","state","error","callbackError","query","undefined","status","send","getErrorTemplate","handleOAuthCallback","getSuccessTemplate","Error","message"],"mappings":"AAAA;;;;CAIC;;;;+BAOeA;;;eAAAA;;;qBALqC;8DAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGb,SAASA,6BAA6BC,QAA+B;IAC1E,IAAMC,SAASC,gBAAO,CAACC,MAAM;IAE7BF,OAAOG,GAAG,CAAC,mBAAmB,SAAOC,KAAcC;;gBAC3CC,MACAC,OACAC,OAeGC;;;;wBAjBHH,OAAO,OAAOF,IAAIM,KAAK,CAACJ,IAAI,KAAK,WAAWF,IAAIM,KAAK,CAACJ,IAAI,GAAGK;wBAC7DJ,QAAQ,OAAOH,IAAIM,KAAK,CAACH,KAAK,KAAK,WAAWH,IAAIM,KAAK,CAACH,KAAK,GAAGI;wBAChEH,QAAQ,OAAOJ,IAAIM,KAAK,CAACF,KAAK,KAAK,WAAWJ,IAAIM,KAAK,CAACF,KAAK,GAAGG;wBAEtE,IAAIH,OAAO;4BACTH,IAAIO,MAAM,CAAC,KAAKC,IAAI,CAACC,IAAAA,uBAAgB,EAACN;4BACtC;;;wBACF;wBAEA,IAAI,CAACF,MAAM;4BACTD,IAAIO,MAAM,CAAC,KAAKC,IAAI,CAACC,IAAAA,uBAAgB,EAAC;4BACtC;;;wBACF;;;;;;;;;wBAGE;;4BAAMf,SAASgB,mBAAmB,CAAC;gCAAET,MAAAA;gCAAMC,OAAAA;4BAAM;;;wBAAjD;wBACAF,IAAIO,MAAM,CAAC,KAAKC,IAAI,CAACG,IAAAA,yBAAkB;;;;;;wBAChCP;wBACPJ,IAAIO,MAAM,CAAC,KAAKC,IAAI,CAACC,IAAAA,uBAAgB,EAACL,AAAa,YAAbA,eAAyBQ,SAAQR,cAAcS,OAAO,GAAG;;;;;;;;;;;QAEnG;;IAEA,OAAOlB;AACT"}

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

@@ -1 +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","verifyUrl","verifyAccessToken","token","response","errorMessage","error","authInfo","fetch","method","headers","Authorization","ok","json","error_description","statusText","Error","String"],"mappings":"AAAA;;;;;CAKC;;;;+BA+BYA;;;eAAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAN,IAAA,AAAMA,iCAAN;;aAAMA,iBAMCC,SAAiB;gCANlBD;QAOT,IAAI,CAACC,SAAS,GAAGA;;iBAPRD;IAUX;;;;;;GAMC,GACD,OAAME,iBA6BL,GA7BD,SAAMA,kBAAkBC,KAAa;;gBAE3BC,UAQAC,cAGa,MAAA,0BADTC,iBASJC,UAECD;;;;;;;;;;wBArBU;;4BAAME,MAAM,IAAI,CAACP,SAAS,EAAE;gCAC3CQ,QAAQ;gCACRC,SAAS;oCACPC,eAAe,AAAC,UAAe,OAANR;gCAC3B;4BACF;;;wBALMC,WAAW;6BAOb,CAACA,SAASQ,EAAE,EAAZ;;;;wBACEP,eAAe;;;;;;;;;wBAEH;;4BAAMD,SAASS,IAAI;;;wBAA3BP,UAAQ;wBACdD,gBAAe,QAAA,2BAAA,AAACC,QAAyDQ,iBAAiB,cAA3E,sCAAA,2BAA+E,AAACR,QAA6BA,KAAK,cAAlH,kBAAA,OAAsHD;;;;;;;wBAErI,8CAA8C;wBAC9CA,eAAeD,SAASW,UAAU;;;;;;wBAEpC,MAAM,IAAIC,MAAM,AAAC,8BAA0C,OAAbX;;wBAG9B;;4BAAMD,SAASS,IAAI;;;wBAA/BN,WAAY;wBAClB;;4BAAOA;;;wBACAD;wBACP,IAAIA,AAAK,YAALA,OAAiBU,QAAO;4BAC1B,MAAMV;wBACR;wBACA,MAAM,IAAIU,MAAM,AAAC,8BAA2C,OAAdC,OAAOX;;;;;;;QAEzD;;WA9CWN"}
+{"version":3,"sources":["/Users/kevin/Dev/Projects/mcp-z/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","verifyUrl","verifyAccessToken","token","response","errorMessage","error","authInfo","fetch","method","headers","Authorization","ok","json","error_description","statusText","Error","String"],"mappings":"AAAA;;;;;CAKC;;;;+BA+BYA;;;eAAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAN,IAAA,AAAMA,iCAAN;;aAAMA,iBAMCC,SAAiB;gCANlBD;QAOT,IAAI,CAACC,SAAS,GAAGA;;iBAPRD;IAUX;;;;;;GAMC,GACD,OAAME,iBA6BL,GA7BD,SAAMA,kBAAkBC,KAAa;;gBAE3BC,UAQAC,cAGa,MAAA,0BADTC,iBASJC,UAECD;;;;;;;;;;wBArBU;;4BAAME,MAAM,IAAI,CAACP,SAAS,EAAE;gCAC3CQ,QAAQ;gCACRC,SAAS;oCACPC,eAAe,AAAC,UAAe,OAANR;gCAC3B;4BACF;;;wBALMC,WAAW;6BAOb,CAACA,SAASQ,EAAE,EAAZ;;;;wBACEP,eAAe;;;;;;;;;wBAEH;;4BAAMD,SAASS,IAAI;;;wBAA3BP,UAAQ;wBACdD,gBAAe,QAAA,2BAAA,AAACC,QAAyDQ,iBAAiB,cAA3E,sCAAA,2BAA+E,AAACR,QAA6BA,KAAK,cAAlH,kBAAA,OAAsHD;;;;;;;wBAErI,8CAA8C;wBAC9CA,eAAeD,SAASW,UAAU;;;;;;wBAEpC,MAAM,IAAIC,MAAM,AAAC,8BAA0C,OAAbX;;wBAG9B;;4BAAMD,SAASS,IAAI;;;wBAA/BN,WAAY;wBAClB;;4BAAOA;;;wBACAD;wBACP,IAAIA,AAAK,YAALA,OAAiBU,QAAO;4BAC1B,MAAMV;wBACR;wBACA,MAAM,IAAIU,MAAM,AAAC,8BAA2C,OAAdC,OAAOX;;;;;;;QAEzD;;WA9CWN"}

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

@@ -1 +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":["DcrOAuthProvider","config","emailCache","Map","toAuth","tokens","clientId","clientSecret","client","OAuth2Client","credentials","access_token","accessToken","refresh_token","refreshToken","expiry_date","expiresAt","token_type","originalGetMetadata","getRequestMetadataAsync","bind","url","refreshedTokens","error","needsRefresh","refreshAccessToken","Error","message","String","expiryDate","Date","now","tokenUrl","params","body","response","errorText","tokenResponse","result","client_id","grant_type","client_secret","URLSearchParams","fetch","method","headers","toString","ok","text","status","json","expires_in","undefined","scope","getUserEmail","cacheKey","cached","auth","userInfo","email","get","request","data","set","authMiddleware","wrapAtPosition","module","extraPosition","originalHandler","handler","wrappedHandler","allArgs","extra","bearerToken","authInfo","authHeader","headerValue","match","verifyResponse","verifyData","accountId","token","requestInfo","authorization","Authorization","Array","isArray","exec","McpError","ErrorCode","InvalidRequest","verifyEndpoint","providerTokens","InternalError","authContext","logger","withToolAuth","withResourceAuth","withPromptAuth"],"mappings":"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"}
+{"version":3,"sources":["/Users/kevin/Dev/Projects/mcp-z/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":["DcrOAuthProvider","config","emailCache","Map","toAuth","tokens","clientId","clientSecret","client","OAuth2Client","credentials","access_token","accessToken","refresh_token","refreshToken","expiry_date","expiresAt","token_type","originalGetMetadata","getRequestMetadataAsync","bind","url","refreshedTokens","error","needsRefresh","refreshAccessToken","Error","message","String","expiryDate","Date","now","tokenUrl","params","body","response","errorText","tokenResponse","result","client_id","grant_type","client_secret","URLSearchParams","fetch","method","headers","toString","ok","text","status","json","expires_in","undefined","scope","getUserEmail","cacheKey","cached","auth","userInfo","email","get","request","data","set","authMiddleware","wrapAtPosition","module","extraPosition","originalHandler","handler","wrappedHandler","allArgs","extra","bearerToken","authInfo","authHeader","headerValue","match","verifyResponse","verifyData","accountId","token","requestInfo","authorization","Authorization","Array","isArray","exec","McpError","ErrorCode","InvalidRequest","verifyEndpoint","providerTokens","InternalError","authContext","logger","withToolAuth","withResourceAuth","withPromptAuth"],"mappings":"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"}

package/dist/cjs/providers/loopback-oauth.d.cts

@@ -3,10 +3,20 @@
  *
  * 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).
+ *
+ * CHANGE (2026-01-03):
+ * - Non-headless mode now opens the auth URL AND blocks (polls) until tokens are available,
+ *   for BOTH redirectUri (persistent) and ephemeral (loopback) modes.
+ * - Ephemeral flow no longer calls `open()` itself. Instead it:
+ *   1) starts the loopback callback server
+ *   2) throws AuthRequiredError(auth_url)
+ * - Middleware catches AuthRequiredError(auth_url):
+ *   - if not headless: open(url) once + poll pending state until callback completes (or timeout)
+ *   - then retries token acquisition and injects authContext in the SAME tool call.
  */
 import { type OAuth2TokenStorageProvider } from '@mcp-z/oauth';
 import { OAuth2Client } from 'google-auth-library';
-import { type LoopbackOAuthConfig } from '../types.js';
+import { type CachedToken, type LoopbackOAuthConfig } from '../types.js';
 /**
  * Loopback OAuth Client (RFC 8252 Section 7.3)
  *
@@ -18,6 +28,7 @@ import { type LoopbackOAuthConfig } from '../types.js';
  */
 export declare class LoopbackOAuthProvider implements OAuth2TokenStorageProvider {
     private config;
+    private openedStates;
     constructor(config: LoopbackOAuthConfig);
     /**
      * Get access token from Keyv using compound key
@@ -33,14 +44,6 @@ export declare class LoopbackOAuthProvider implements OAuth2TokenStorageProvider
      * @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
@@ -49,14 +52,6 @@ export declare class LoopbackOAuthProvider implements OAuth2TokenStorageProvider
      * @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
@@ -66,9 +61,90 @@ export declare class LoopbackOAuthProvider implements OAuth2TokenStorageProvider
      * @returns User's email address
      */
     private fetchUserEmailFromToken;
-    private performEphemeralOAuthFlow;
+    /**
+     * Build OAuth authorization URL with the "most parameters" baseline.
+     * This is shared by BOTH persistent (redirectUri) and ephemeral (loopback) modes.
+     */
+    private buildAuthUrl;
+    /**
+     * Create a cached token + email from an authorization code.
+     * This is the shared callback handler for BOTH persistent and ephemeral modes.
+     */
+    private handleAuthorizationCode;
+    /**
+     * Store token + account metadata. Shared by BOTH persistent and ephemeral modes.
+     */
+    private persistAuthResult;
+    /**
+     * Pending auth (PKCE verifier) key format.
+     * Keep as-is (confirmed), even though it's not a public contract.
+     */
+    private pendingKey;
+    /**
+     * Store PKCE verifier for callback (5 minute TTL).
+     * Shared by BOTH persistent and ephemeral modes.
+     */
+    private createPendingAuth;
+    /**
+     * Load and validate pending auth state (5 minute TTL).
+     * Shared by BOTH persistent and ephemeral modes.
+     */
+    private readAndValidatePendingAuth;
+    /**
+     * Mark pending auth as completed (used by middleware polling).
+     */
+    private markPendingComplete;
+    /**
+     * Clean up pending auth state.
+     */
+    private deletePendingAuth;
+    /**
+     * Wait until pending auth is marked completed (or timeout).
+     * Used by middleware after opening auth URL in non-headless mode.
+     */
+    private waitForOAuthCompletion;
+    /**
+     * Process an OAuth callback using shared state validation + token exchange + persistence.
+     * Used by BOTH:
+     * - ephemeral loopback server callback handler
+     * - persistent redirectUri callback handler
+     *
+     * IMPORTANT CHANGE:
+     * - We do NOT delete pending state here anymore.
+     * - We mark it completed so middleware can poll and then clean it up.
+     */
+    private processOAuthCallback;
+    /**
+     * Loopback OAuth server helper (RFC 8252 Section 7.3)
+     *
+     * Implements ephemeral local server with OS-assigned port (RFC 8252 Section 8.3).
+     * Shared callback handling uses:
+     * - the same authUrl builder as redirectUri mode
+     * - the same pending PKCE verifier storage as redirectUri mode
+     * - the same callback processor as redirectUri mode
+     */
+    private createOAuthCallbackServer;
+    /**
+     * Starts the ephemeral loopback server and returns an AuthRequiredError(auth_url).
+     * Middleware will open+poll and then retry in the same call.
+     */
+    private startEphemeralOAuthFlow;
     private exchangeCodeForToken;
     private refreshAccessToken;
+    /**
+     * Handle OAuth callback from persistent endpoint.
+     * Used by HTTP servers with configured redirectUri.
+     *
+     * @param params - OAuth callback parameters
+     * @returns Email and cached token
+     */
+    handleOAuthCallback(params: {
+        code: string;
+        state?: string;
+    }): Promise<{
+        email: string;
+        token: CachedToken;
+    }>;
     /**
      * Create authentication middleware for MCP tools, resources, and prompts
      *
@@ -83,15 +159,6 @@ export declare class LoopbackOAuthProvider implements OAuth2TokenStorageProvider
      * 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 {

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

@@ -3,10 +3,20 @@
  *
  * 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).
+ *
+ * CHANGE (2026-01-03):
+ * - Non-headless mode now opens the auth URL AND blocks (polls) until tokens are available,
+ *   for BOTH redirectUri (persistent) and ephemeral (loopback) modes.
+ * - Ephemeral flow no longer calls `open()` itself. Instead it:
+ *   1) starts the loopback callback server
+ *   2) throws AuthRequiredError(auth_url)
+ * - Middleware catches AuthRequiredError(auth_url):
+ *   - if not headless: open(url) once + poll pending state until callback completes (or timeout)
+ *   - then retries token acquisition and injects authContext in the SAME tool call.
  */
 import { type OAuth2TokenStorageProvider } from '@mcp-z/oauth';
 import { OAuth2Client } from 'google-auth-library';
-import { type LoopbackOAuthConfig } from '../types.js';
+import { type CachedToken, type LoopbackOAuthConfig } from '../types.js';
 /**
  * Loopback OAuth Client (RFC 8252 Section 7.3)
  *
@@ -18,6 +28,7 @@ import { type LoopbackOAuthConfig } from '../types.js';
  */
 export declare class LoopbackOAuthProvider implements OAuth2TokenStorageProvider {
     private config;
+    private openedStates;
     constructor(config: LoopbackOAuthConfig);
     /**
      * Get access token from Keyv using compound key
@@ -33,14 +44,6 @@ export declare class LoopbackOAuthProvider implements OAuth2TokenStorageProvider
      * @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
@@ -49,14 +52,6 @@ export declare class LoopbackOAuthProvider implements OAuth2TokenStorageProvider
      * @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
@@ -66,9 +61,90 @@ export declare class LoopbackOAuthProvider implements OAuth2TokenStorageProvider
      * @returns User's email address
      */
     private fetchUserEmailFromToken;
-    private performEphemeralOAuthFlow;
+    /**
+     * Build OAuth authorization URL with the "most parameters" baseline.
+     * This is shared by BOTH persistent (redirectUri) and ephemeral (loopback) modes.
+     */
+    private buildAuthUrl;
+    /**
+     * Create a cached token + email from an authorization code.
+     * This is the shared callback handler for BOTH persistent and ephemeral modes.
+     */
+    private handleAuthorizationCode;
+    /**
+     * Store token + account metadata. Shared by BOTH persistent and ephemeral modes.
+     */
+    private persistAuthResult;
+    /**
+     * Pending auth (PKCE verifier) key format.
+     * Keep as-is (confirmed), even though it's not a public contract.
+     */
+    private pendingKey;
+    /**
+     * Store PKCE verifier for callback (5 minute TTL).
+     * Shared by BOTH persistent and ephemeral modes.
+     */
+    private createPendingAuth;
+    /**
+     * Load and validate pending auth state (5 minute TTL).
+     * Shared by BOTH persistent and ephemeral modes.
+     */
+    private readAndValidatePendingAuth;
+    /**
+     * Mark pending auth as completed (used by middleware polling).
+     */
+    private markPendingComplete;
+    /**
+     * Clean up pending auth state.
+     */
+    private deletePendingAuth;
+    /**
+     * Wait until pending auth is marked completed (or timeout).
+     * Used by middleware after opening auth URL in non-headless mode.
+     */
+    private waitForOAuthCompletion;
+    /**
+     * Process an OAuth callback using shared state validation + token exchange + persistence.
+     * Used by BOTH:
+     * - ephemeral loopback server callback handler
+     * - persistent redirectUri callback handler
+     *
+     * IMPORTANT CHANGE:
+     * - We do NOT delete pending state here anymore.
+     * - We mark it completed so middleware can poll and then clean it up.
+     */
+    private processOAuthCallback;
+    /**
+     * Loopback OAuth server helper (RFC 8252 Section 7.3)
+     *
+     * Implements ephemeral local server with OS-assigned port (RFC 8252 Section 8.3).
+     * Shared callback handling uses:
+     * - the same authUrl builder as redirectUri mode
+     * - the same pending PKCE verifier storage as redirectUri mode
+     * - the same callback processor as redirectUri mode
+     */
+    private createOAuthCallbackServer;
+    /**
+     * Starts the ephemeral loopback server and returns an AuthRequiredError(auth_url).
+     * Middleware will open+poll and then retry in the same call.
+     */
+    private startEphemeralOAuthFlow;
     private exchangeCodeForToken;
     private refreshAccessToken;
+    /**
+     * Handle OAuth callback from persistent endpoint.
+     * Used by HTTP servers with configured redirectUri.
+     *
+     * @param params - OAuth callback parameters
+     * @returns Email and cached token
+     */
+    handleOAuthCallback(params: {
+        code: string;
+        state?: string;
+    }): Promise<{
+        email: string;
+        token: CachedToken;
+    }>;
     /**
      * Create authentication middleware for MCP tools, resources, and prompts
      *
@@ -83,15 +159,6 @@ export declare class LoopbackOAuthProvider implements OAuth2TokenStorageProvider
      * 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 {