@mcp-z/oauth-microsoft 1.0.0 → 1.0.2

package/dist/esm/providers/device-code.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/oauth/oauth-microsoft/src/providers/device-code.ts"],"sourcesContent":["/**\n * Device Code OAuth Implementation for Microsoft\n *\n * Implements OAuth 2.0 Device Authorization Grant (RFC 8628) for headless/limited-input devices.\n * Designed for scenarios where interactive browser flows are impractical (SSH sessions, CI/CD, etc.).\n *\n * Flow:\n * 1. Request device code from Microsoft endpoint\n * 2. Display user_code and verification_uri to user\n * 3. Poll token endpoint until user completes authentication\n * 4. Cache access token + refresh token to storage\n * 5. Refresh tokens when expired\n *\n * Similar to service accounts in usage pattern: single static identity, minimal account management.\n */\n\nimport { getToken, type OAuth2TokenStorageProvider, setToken } from '@mcp-z/oauth';\nimport type { Keyv } from 'keyv';\nimport open from 'open';\nimport { fetchWithTimeout } from '../lib/fetch-with-timeout.ts';\nimport type { AuthContext, CachedToken, EnrichedExtra, Logger, MicrosoftAuthProvider, MicrosoftService } from '../types.ts';\n\n/**\n * Device Code Flow Response\n * Response from Microsoft device authorization endpoint\n */\ninterface DeviceCodeResponse {\n  device_code: string;\n  user_code: string;\n  verification_uri: string;\n  verification_uri_complete?: string;\n  expires_in: number;\n  interval: number;\n  message?: string;\n}\n\n/**\n * Token Response from Microsoft OAuth endpoint\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 * Device Code Provider Configuration\n */\nexport interface DeviceCodeConfig {\n  /** Microsoft service type (e.g., 'outlook') */\n  service: MicrosoftService;\n  /** Azure AD client ID */\n  clientId: string;\n  /** Azure AD tenant ID */\n  tenantId: string;\n  /** OAuth scopes to request (space-separated string or array) */\n  scope: string;\n  /** Logger instance */\n  logger: Logger;\n  /** Token storage for caching */\n  tokenStore: Keyv<unknown>;\n  /** Headless mode - print device code instead of opening browser */\n  headless: boolean;\n}\n\n/**\n * DeviceCodeProvider implements OAuth2TokenStorageProvider using Microsoft Device Code Flow\n *\n * This provider:\n * - Initiates device code flow with Microsoft endpoint\n * - Displays user_code and verification_uri for manual authentication\n * - Polls token endpoint until user completes auth\n * - Stores access tokens + refresh tokens in Keyv storage\n * - Refreshes tokens when expired\n * - Provides single static identity (minimal account management like service accounts)\n *\n * @example\n * ```typescript\n * const provider = new DeviceCodeProvider({\n *   service: 'outlook',\n *   clientId: 'your-client-id',\n *   tenantId: 'common',\n *   scope: 'https://graph.microsoft.com/Mail.Read',\n *   logger: console,\n *   tokenStore: new Keyv(),\n *   headless: true,\n * });\n *\n * // Get authenticated Microsoft Graph client\n * const token = await provider.getAccessToken('default');\n * ```\n */\nexport class DeviceCodeProvider implements OAuth2TokenStorageProvider {\n  private config: DeviceCodeConfig;\n\n  constructor(config: DeviceCodeConfig) {\n    this.config = config;\n  }\n\n  /**\n   * Start device code flow and poll for token\n   *\n   * 1. POST to /devicecode endpoint to get device_code and user_code\n   * 2. Display verification instructions to user\n   * 3. Poll /token endpoint every interval seconds\n   * 4. Handle authorization_pending, slow_down, expired_token errors\n   * 5. Return token when user completes authentication\n   */\n  private async startDeviceCodeFlow(accountId: string): Promise<CachedToken> {\n    const { clientId, tenantId, scope, logger, headless } = this.config;\n\n    // Step 1: Request device code\n    const deviceCodeEndpoint = `https://login.microsoftonline.com/${tenantId}/oauth2/v2.0/devicecode`;\n    logger.debug('Requesting device code', { endpoint: deviceCodeEndpoint });\n\n    const deviceCodeResponse = await fetchWithTimeout(deviceCodeEndpoint, {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },\n      body: new URLSearchParams({\n        client_id: clientId,\n        scope: scope,\n      }),\n    });\n\n    if (!deviceCodeResponse.ok) {\n      const errorText = await deviceCodeResponse.text();\n      throw new Error(`Device code request failed (HTTP ${deviceCodeResponse.status}): ${errorText}`);\n    }\n\n    const deviceCodeData = (await deviceCodeResponse.json()) as DeviceCodeResponse;\n    const { device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval } = deviceCodeData;\n\n    // Step 2: Display instructions to user\n    logger.info('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');\n    logger.info('Device code authentication required');\n    logger.info('');\n    logger.info(`Please visit: ${verification_uri_complete || verification_uri}`);\n    logger.info(`And enter code: ${user_code}`);\n    logger.info('');\n    logger.info(`Code expires in ${expires_in} seconds`);\n    logger.info('Waiting for authentication...');\n    logger.info('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');\n\n    // Optional: Open browser in non-headless mode\n    if (!headless) {\n      const urlToOpen = verification_uri_complete || verification_uri;\n      try {\n        await open(urlToOpen);\n        logger.debug('Opened browser to verification URL', { url: urlToOpen });\n      } catch (error) {\n        logger.debug('Failed to open browser', { error: error instanceof Error ? error.message : String(error) });\n      }\n    }\n\n    // Step 3: Poll token endpoint\n    return await this.pollForToken(device_code, interval || 5, accountId);\n  }\n\n  /**\n   * Poll Microsoft token endpoint until user completes authentication\n   *\n   * Handles Microsoft-specific error codes:\n   * - authorization_pending: User hasn't completed auth yet, keep polling\n   * - slow_down: Increase polling interval by 5 seconds\n   * - authorization_declined: User denied authorization\n   * - expired_token: Device code expired (typically after 15 minutes)\n   */\n  private async pollForToken(deviceCode: string, intervalSeconds: number, accountId: string): Promise<CachedToken> {\n    const { clientId, tenantId, logger, service, tokenStore } = this.config;\n    const tokenEndpoint = `https://login.microsoftonline.com/${tenantId}/oauth2/v2.0/token`;\n\n    let currentInterval = intervalSeconds;\n    const startTime = Date.now();\n\n    while (true) {\n      // Wait for polling interval\n      await new Promise((resolve) => setTimeout(resolve, currentInterval * 1000));\n\n      logger.debug('Polling for token', { elapsed: Math.floor((Date.now() - startTime) / 1000), interval: currentInterval });\n\n      const response = await fetchWithTimeout(tokenEndpoint, {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },\n        body: new URLSearchParams({\n          grant_type: 'urn:ietf:params:oauth:grant-type:device_code',\n          client_id: clientId,\n          device_code: deviceCode,\n        }),\n      });\n\n      const responseData = (await response.json()) as TokenResponse & { error?: string; error_description?: string };\n\n      if (response.ok) {\n        // Success! Convert to CachedToken and store\n        const tokenData = responseData as TokenResponse;\n        const token: CachedToken = {\n          accessToken: tokenData.access_token,\n          ...(tokenData.refresh_token && { refreshToken: tokenData.refresh_token }),\n          expiresAt: Date.now() + (tokenData.expires_in - 60) * 1000, // 60s safety margin\n          ...(tokenData.scope && { scope: tokenData.scope }),\n        };\n\n        // Cache token to storage\n        await setToken(tokenStore, { accountId, service }, token);\n        logger.info('Device code authentication successful', { accountId });\n\n        return token;\n      }\n\n      // Handle error responses\n      const error = responseData.error;\n      const errorDescription = responseData.error_description || '';\n\n      if (error === 'authorization_pending') {\n        // User hasn't completed auth yet - continue polling\n        logger.debug('Authorization pending, waiting for user...');\n        continue;\n      }\n\n      if (error === 'slow_down') {\n        // Microsoft wants us to slow down polling\n        currentInterval += 5;\n        logger.debug('Received slow_down, increasing interval', { newInterval: currentInterval });\n        continue;\n      }\n\n      if (error === 'authorization_declined') {\n        throw new Error('User declined authorization. Please restart the authentication flow.');\n      }\n\n      if (error === 'expired_token') {\n        throw new Error('Device code expired. Please restart the authentication flow.');\n      }\n\n      // Unknown error\n      throw new Error(`Device code flow failed: ${error} - ${errorDescription}`);\n    }\n  }\n\n  /**\n   * Refresh expired access token using refresh token\n   *\n   * @param refreshToken - Refresh token from previous authentication\n   * @returns New cached token with fresh access token\n   */\n  private async refreshAccessToken(refreshToken: string): Promise<CachedToken> {\n    const { clientId, tenantId, scope, logger } = this.config;\n    const tokenEndpoint = `https://login.microsoftonline.com/${tenantId}/oauth2/v2.0/token`;\n\n    logger.debug('Refreshing access token');\n\n    const response = await fetchWithTimeout(tokenEndpoint, {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },\n      body: new URLSearchParams({\n        grant_type: 'refresh_token',\n        client_id: clientId,\n        refresh_token: refreshToken,\n        scope: scope,\n      }),\n    });\n\n    if (!response.ok) {\n      const errorText = await response.text();\n      throw new Error(`Token refresh failed (HTTP ${response.status}): ${errorText}`);\n    }\n\n    const tokenData = (await response.json()) as TokenResponse;\n\n    return {\n      accessToken: tokenData.access_token,\n      refreshToken: tokenData.refresh_token || refreshToken, // Some responses may not include new refresh token\n      expiresAt: Date.now() + (tokenData.expires_in - 60) * 1000, // 60s safety margin\n      scope: tokenData.scope || scope,\n    };\n  }\n\n  /**\n   * Check if token is still valid (not expired)\n   */\n  private isTokenValid(token: CachedToken): boolean {\n    return token.expiresAt !== undefined && token.expiresAt > Date.now();\n  }\n\n  /**\n   * Get access token for Microsoft Graph API\n   *\n   * Flow:\n   * 1. Check token storage\n   * 2. If valid token exists, return it\n   * 3. If expired but has refresh token, try refresh\n   * 4. Otherwise, start new device code flow\n   *\n   * @param accountId - Account identifier. Defaults to 'device-code' (fixed identifier for device code flow).\n   * @returns Access token for API requests\n   */\n  async getAccessToken(accountId?: string): Promise<string> {\n    const { logger, service, tokenStore } = this.config;\n    const effectiveAccountId = accountId ?? 'device-code';\n\n    logger.debug('Getting access token', { service, accountId: effectiveAccountId });\n\n    // Check storage for cached token\n    const storedToken = await getToken<CachedToken>(tokenStore, { accountId: effectiveAccountId, service });\n\n    if (storedToken && this.isTokenValid(storedToken)) {\n      logger.debug('Using stored access token', { accountId: effectiveAccountId });\n      return storedToken.accessToken;\n    }\n\n    // If stored token expired but has refresh token, try refresh\n    if (storedToken?.refreshToken) {\n      try {\n        logger.info('Refreshing expired access token', { accountId: effectiveAccountId });\n        const refreshedToken = await this.refreshAccessToken(storedToken.refreshToken);\n        await setToken(tokenStore, { accountId: effectiveAccountId, service }, refreshedToken);\n        return refreshedToken.accessToken;\n      } catch (error) {\n        logger.info('Token refresh failed', {\n          accountId: effectiveAccountId,\n          error: error instanceof Error ? error.message : String(error),\n        });\n        // In headless mode, cannot start interactive device code flow\n        if (this.config.headless) {\n          throw new Error(`Token refresh failed in headless mode. Cannot start interactive device code flow. Error: ${error instanceof Error ? error.message : String(error)}`);\n        }\n        // Fall through to new device code flow (interactive mode only)\n      }\n    }\n\n    // No valid token - check if we can start device code flow\n    if (this.config.headless) {\n      throw new Error('No valid token available in headless mode. Device code flow requires user interaction. ' + 'Please run authentication flow interactively first or provide valid tokens.');\n    }\n\n    // Interactive mode - start device code flow\n    logger.info('Starting device code flow', { accountId: effectiveAccountId });\n    const token = await this.startDeviceCodeFlow(effectiveAccountId);\n    return token.accessToken;\n  }\n\n  /**\n   * Get user email from Microsoft Graph /me endpoint (pure query)\n   *\n   * @param accountId - Account identifier\n   * @returns User's email address (userPrincipalName or mail field)\n   */\n  async getUserEmail(accountId?: string): Promise<string> {\n    const { logger } = this.config;\n    // Device code is single-account mode\n    const token = await this.getAccessToken(accountId);\n\n    logger.debug('Fetching user email from Microsoft Graph');\n\n    const response = await fetchWithTimeout('https://graph.microsoft.com/v1.0/me', {\n      headers: { Authorization: `Bearer ${token}` },\n    });\n\n    if (!response.ok) {\n      const errorText = await response.text();\n      throw new Error(`Failed to get user email (HTTP ${response.status}): ${errorText}`);\n    }\n\n    const userData = (await response.json()) as { userPrincipalName?: string; mail?: string };\n    const email = userData.userPrincipalName || userData.mail;\n\n    if (!email) {\n      throw new Error('User email not found in Microsoft Graph response');\n    }\n\n    return email;\n  }\n\n  /**\n   * Create auth provider for Microsoft Graph SDK integration\n   *\n   * Device code provider ALWAYS uses fixed accountId='device-code'\n   * This is by design - device code is a single static identity pattern\n   *\n   * @param accountId - Account identifier (must be 'device-code' or undefined, otherwise throws error)\n   * @returns Auth provider with getAccessToken method\n   */\n  toAuthProvider(accountId?: string): { getAccessToken: () => Promise<string> } {\n    // Device code ONLY works with 'device-code' account ID\n    if (accountId !== undefined && accountId !== 'device-code') {\n      throw new Error(`DeviceCodeProvider only supports accountId='device-code', got '${accountId}'. Device code uses a single static identity pattern.`);\n    }\n\n    // ALWAYS use fixed 'device-code' account ID\n    const getToken = () => this.getAccessToken('device-code');\n\n    return {\n      getAccessToken: getToken,\n    };\n  }\n\n  /**\n   * Create Microsoft Graph AuthenticationProvider for SDK usage\n   *\n   * @param accountId - Account identifier\n   * @returns AuthenticationProvider that provides access tokens\n   */\n  private createAuthProvider(accountId?: string): MicrosoftAuthProvider {\n    return {\n      getAccessToken: async () => {\n        return await this.getAccessToken(accountId);\n      },\n    };\n  }\n\n  /**\n   * Create middleware wrapper for single-user authentication\n   *\n   * Middleware wraps tool, resource, and prompt handlers and injects authContext into extra parameter.\n   * Handlers receive MicrosoftAuthProvider via extra.authContext.auth for API calls.\n   *\n   * @returns Object with withToolAuth, withResourceAuth, withPromptAuth methods\n   *\n   * @example\n   * ```typescript\n   * // Server registration\n   * const middleware = provider.authMiddleware();\n   * const tools = toolFactories.map(f => f()).map(middleware.withToolAuth);\n   * const resources = resourceFactories.map(f => f()).map(middleware.withResourceAuth);\n   * const prompts = promptFactories.map(f => f()).map(middleware.withPromptAuth);\n   *\n   * // Tool handler receives auth\n   * async function handler({ id }: In, extra: EnrichedExtra) {\n   *   // extra.authContext.auth is MicrosoftAuthProvider (from middleware)\n   *   const graph = Client.initWithMiddleware({ authProvider: extra.authContext.auth });\n   * }\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 (defensive: handle arg-less tool pattern)\n        // If called with fewer args than expected, use first arg as both args and extra\n        let extra: EnrichedExtra;\n        if (allArgs.length <= extraPosition) {\n          // Arg-less tool pattern: single argument is both args and extra\n          extra = (allArgs[0] || {}) as EnrichedExtra;\n          allArgs[0] = extra;\n          allArgs[extraPosition] = extra;\n        } else {\n          extra = (allArgs[extraPosition] || {}) as EnrichedExtra;\n          allArgs[extraPosition] = extra;\n        }\n\n        try {\n          // Use fixed accountId for storage isolation (like service-account pattern)\n          const accountId = 'device-code';\n\n          // Create Microsoft Graph authentication provider\n          const auth = this.createAuthProvider(accountId);\n\n          // Inject authContext and logger into extra parameter\n          (extra as { authContext?: AuthContext }).authContext = {\n            auth, // MicrosoftAuthProvider for Graph SDK\n            accountId, // Account identifier\n          };\n          (extra as { logger?: unknown }).logger = this.config.logger;\n\n          // Call original handler with all args\n          return await originalHandler(...allArgs);\n        } catch (error) {\n          // Wrap auth errors with helpful context\n          throw new Error(`Device code authentication failed: ${error instanceof Error ? error.message : String(error)}`);\n        }\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":["getToken","setToken","open","fetchWithTimeout","DeviceCodeProvider","startDeviceCodeFlow","accountId","clientId","tenantId","scope","logger","headless","config","deviceCodeEndpoint","debug","endpoint","deviceCodeResponse","method","headers","body","URLSearchParams","client_id","ok","errorText","text","Error","status","deviceCodeData","json","device_code","user_code","verification_uri","verification_uri_complete","expires_in","interval","info","urlToOpen","url","error","message","String","pollForToken","deviceCode","intervalSeconds","service","tokenStore","tokenEndpoint","currentInterval","startTime","Date","now","Promise","resolve","setTimeout","elapsed","Math","floor","response","grant_type","responseData","tokenData","token","accessToken","access_token","refresh_token","refreshToken","expiresAt","errorDescription","error_description","newInterval","refreshAccessToken","isTokenValid","undefined","getAccessToken","effectiveAccountId","storedToken","refreshedToken","getUserEmail","Authorization","userData","email","userPrincipalName","mail","toAuthProvider","createAuthProvider","authMiddleware","wrapAtPosition","module","extraPosition","originalHandler","handler","wrappedHandler","allArgs","extra","length","auth","authContext","withToolAuth","withResourceAuth","withPromptAuth"],"mappings":"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"}
+{"version":3,"sources":["/Users/kevin/Dev/Projects/mcp-z/oauth-microsoft/src/providers/device-code.ts"],"sourcesContent":["/**\n * Device Code OAuth Implementation for Microsoft\n *\n * Implements OAuth 2.0 Device Authorization Grant (RFC 8628) for headless/limited-input devices.\n * Designed for scenarios where interactive browser flows are impractical (SSH sessions, CI/CD, etc.).\n *\n * Flow:\n * 1. Request device code from Microsoft endpoint\n * 2. Display user_code and verification_uri to user\n * 3. Poll token endpoint until user completes authentication\n * 4. Cache access token + refresh token to storage\n * 5. Refresh tokens when expired\n *\n * Similar to service accounts in usage pattern: single static identity, minimal account management.\n */\n\nimport { getToken, type OAuth2TokenStorageProvider, setToken } from '@mcp-z/oauth';\nimport type { Keyv } from 'keyv';\nimport open from 'open';\nimport { fetchWithTimeout } from '../lib/fetch-with-timeout.ts';\nimport type { AuthContext, CachedToken, EnrichedExtra, Logger, MicrosoftAuthProvider, MicrosoftService } from '../types.ts';\n\n/**\n * Device Code Flow Response\n * Response from Microsoft device authorization endpoint\n */\ninterface DeviceCodeResponse {\n  device_code: string;\n  user_code: string;\n  verification_uri: string;\n  verification_uri_complete?: string;\n  expires_in: number;\n  interval: number;\n  message?: string;\n}\n\n/**\n * Token Response from Microsoft OAuth endpoint\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 * Device Code Provider Configuration\n */\nexport interface DeviceCodeConfig {\n  /** Microsoft service type (e.g., 'outlook') */\n  service: MicrosoftService;\n  /** Azure AD client ID */\n  clientId: string;\n  /** Azure AD tenant ID */\n  tenantId: string;\n  /** OAuth scopes to request (space-separated string or array) */\n  scope: string;\n  /** Logger instance */\n  logger: Logger;\n  /** Token storage for caching */\n  tokenStore: Keyv<unknown>;\n  /** Headless mode - print device code instead of opening browser */\n  headless: boolean;\n}\n\n/**\n * DeviceCodeProvider implements OAuth2TokenStorageProvider using Microsoft Device Code Flow\n *\n * This provider:\n * - Initiates device code flow with Microsoft endpoint\n * - Displays user_code and verification_uri for manual authentication\n * - Polls token endpoint until user completes auth\n * - Stores access tokens + refresh tokens in Keyv storage\n * - Refreshes tokens when expired\n * - Provides single static identity (minimal account management like service accounts)\n *\n * @example\n * ```typescript\n * const provider = new DeviceCodeProvider({\n *   service: 'outlook',\n *   clientId: 'your-client-id',\n *   tenantId: 'common',\n *   scope: 'https://graph.microsoft.com/Mail.Read',\n *   logger: console,\n *   tokenStore: new Keyv(),\n *   headless: true,\n * });\n *\n * // Get authenticated Microsoft Graph client\n * const token = await provider.getAccessToken('default');\n * ```\n */\nexport class DeviceCodeProvider implements OAuth2TokenStorageProvider {\n  private config: DeviceCodeConfig;\n\n  constructor(config: DeviceCodeConfig) {\n    this.config = config;\n  }\n\n  /**\n   * Start device code flow and poll for token\n   *\n   * 1. POST to /devicecode endpoint to get device_code and user_code\n   * 2. Display verification instructions to user\n   * 3. Poll /token endpoint every interval seconds\n   * 4. Handle authorization_pending, slow_down, expired_token errors\n   * 5. Return token when user completes authentication\n   */\n  private async startDeviceCodeFlow(accountId: string): Promise<CachedToken> {\n    const { clientId, tenantId, scope, logger, headless } = this.config;\n\n    // Step 1: Request device code\n    const deviceCodeEndpoint = `https://login.microsoftonline.com/${tenantId}/oauth2/v2.0/devicecode`;\n    logger.debug('Requesting device code', { endpoint: deviceCodeEndpoint });\n\n    const deviceCodeResponse = await fetchWithTimeout(deviceCodeEndpoint, {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },\n      body: new URLSearchParams({\n        client_id: clientId,\n        scope,\n      }),\n    });\n\n    if (!deviceCodeResponse.ok) {\n      const errorText = await deviceCodeResponse.text();\n      throw new Error(`Device code request failed (HTTP ${deviceCodeResponse.status}): ${errorText}`);\n    }\n\n    const deviceCodeData = (await deviceCodeResponse.json()) as DeviceCodeResponse;\n    const { device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval } = deviceCodeData;\n\n    // Step 2: Display instructions to user\n    logger.info('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');\n    logger.info('Device code authentication required');\n    logger.info('');\n    logger.info(`Please visit: ${verification_uri_complete || verification_uri}`);\n    logger.info(`And enter code: ${user_code}`);\n    logger.info('');\n    logger.info(`Code expires in ${expires_in} seconds`);\n    logger.info('Waiting for authentication...');\n    logger.info('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');\n\n    // Optional: Open browser in non-headless mode\n    if (!headless) {\n      const urlToOpen = verification_uri_complete || verification_uri;\n      try {\n        await open(urlToOpen);\n        logger.debug('Opened browser to verification URL', { url: urlToOpen });\n      } catch (error) {\n        logger.debug('Failed to open browser', { error: error instanceof Error ? error.message : String(error) });\n      }\n    }\n\n    // Step 3: Poll token endpoint\n    return await this.pollForToken(device_code, interval || 5, accountId);\n  }\n\n  /**\n   * Poll Microsoft token endpoint until user completes authentication\n   *\n   * Handles Microsoft-specific error codes:\n   * - authorization_pending: User hasn't completed auth yet, keep polling\n   * - slow_down: Increase polling interval by 5 seconds\n   * - authorization_declined: User denied authorization\n   * - expired_token: Device code expired (typically after 15 minutes)\n   */\n  private async pollForToken(deviceCode: string, intervalSeconds: number, accountId: string): Promise<CachedToken> {\n    const { clientId, tenantId, logger, service, tokenStore } = this.config;\n    const tokenEndpoint = `https://login.microsoftonline.com/${tenantId}/oauth2/v2.0/token`;\n\n    let currentInterval = intervalSeconds;\n    const startTime = Date.now();\n\n    while (true) {\n      // Wait for polling interval\n      await new Promise((resolve) => setTimeout(resolve, currentInterval * 1000));\n\n      logger.debug('Polling for token', { elapsed: Math.floor((Date.now() - startTime) / 1000), interval: currentInterval });\n\n      const response = await fetchWithTimeout(tokenEndpoint, {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },\n        body: new URLSearchParams({\n          grant_type: 'urn:ietf:params:oauth:grant-type:device_code',\n          client_id: clientId,\n          device_code: deviceCode,\n        }),\n      });\n\n      const responseData = (await response.json()) as TokenResponse & { error?: string; error_description?: string };\n\n      if (response.ok) {\n        // Success! Convert to CachedToken and store\n        const tokenData = responseData as TokenResponse;\n        const token: CachedToken = {\n          accessToken: tokenData.access_token,\n          ...(tokenData.refresh_token && { refreshToken: tokenData.refresh_token }),\n          expiresAt: Date.now() + (tokenData.expires_in - 60) * 1000, // 60s safety margin\n          ...(tokenData.scope && { scope: tokenData.scope }),\n        };\n\n        // Cache token to storage\n        await setToken(tokenStore, { accountId, service }, token);\n        logger.info('Device code authentication successful', { accountId });\n\n        return token;\n      }\n\n      // Handle error responses\n      const error = responseData.error;\n      const errorDescription = responseData.error_description || '';\n\n      if (error === 'authorization_pending') {\n        // User hasn't completed auth yet - continue polling\n        logger.debug('Authorization pending, waiting for user...');\n        continue;\n      }\n\n      if (error === 'slow_down') {\n        // Microsoft wants us to slow down polling\n        currentInterval += 5;\n        logger.debug('Received slow_down, increasing interval', { newInterval: currentInterval });\n        continue;\n      }\n\n      if (error === 'authorization_declined') {\n        throw new Error('User declined authorization. Please restart the authentication flow.');\n      }\n\n      if (error === 'expired_token') {\n        throw new Error('Device code expired. Please restart the authentication flow.');\n      }\n\n      // Unknown error\n      throw new Error(`Device code flow failed: ${error} - ${errorDescription}`);\n    }\n  }\n\n  /**\n   * Refresh expired access token using refresh token\n   *\n   * @param refreshToken - Refresh token from previous authentication\n   * @returns New cached token with fresh access token\n   */\n  private async refreshAccessToken(refreshToken: string): Promise<CachedToken> {\n    const { clientId, tenantId, scope, logger } = this.config;\n    const tokenEndpoint = `https://login.microsoftonline.com/${tenantId}/oauth2/v2.0/token`;\n\n    logger.debug('Refreshing access token');\n\n    const response = await fetchWithTimeout(tokenEndpoint, {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },\n      body: new URLSearchParams({\n        grant_type: 'refresh_token',\n        client_id: clientId,\n        refresh_token: refreshToken,\n        scope,\n      }),\n    });\n\n    if (!response.ok) {\n      const errorText = await response.text();\n      throw new Error(`Token refresh failed (HTTP ${response.status}): ${errorText}`);\n    }\n\n    const tokenData = (await response.json()) as TokenResponse;\n\n    return {\n      accessToken: tokenData.access_token,\n      refreshToken: tokenData.refresh_token || refreshToken, // Some responses may not include new refresh token\n      expiresAt: Date.now() + (tokenData.expires_in - 60) * 1000, // 60s safety margin\n      scope: tokenData.scope || scope,\n    };\n  }\n\n  /**\n   * Check if token is still valid (not expired)\n   */\n  private isTokenValid(token: CachedToken): boolean {\n    return token.expiresAt !== undefined && token.expiresAt > Date.now();\n  }\n\n  /**\n   * Get access token for Microsoft Graph API\n   *\n   * Flow:\n   * 1. Check token storage\n   * 2. If valid token exists, return it\n   * 3. If expired but has refresh token, try refresh\n   * 4. Otherwise, start new device code flow\n   *\n   * @param accountId - Account identifier. Defaults to 'device-code' (fixed identifier for device code flow).\n   * @returns Access token for API requests\n   */\n  async getAccessToken(accountId?: string): Promise<string> {\n    const { logger, service, tokenStore } = this.config;\n    const effectiveAccountId = accountId ?? 'device-code';\n\n    logger.debug('Getting access token', { service, accountId: effectiveAccountId });\n\n    // Check storage for cached token\n    const storedToken = await getToken<CachedToken>(tokenStore, { accountId: effectiveAccountId, service });\n\n    if (storedToken && this.isTokenValid(storedToken)) {\n      logger.debug('Using stored access token', { accountId: effectiveAccountId });\n      return storedToken.accessToken;\n    }\n\n    // If stored token expired but has refresh token, try refresh\n    if (storedToken?.refreshToken) {\n      try {\n        logger.info('Refreshing expired access token', { accountId: effectiveAccountId });\n        const refreshedToken = await this.refreshAccessToken(storedToken.refreshToken);\n        await setToken(tokenStore, { accountId: effectiveAccountId, service }, refreshedToken);\n        return refreshedToken.accessToken;\n      } catch (error) {\n        logger.info('Token refresh failed', {\n          accountId: effectiveAccountId,\n          error: error instanceof Error ? error.message : String(error),\n        });\n        // In headless mode, cannot start interactive device code flow\n        if (this.config.headless) {\n          throw new Error(`Token refresh failed in headless mode. Cannot start interactive device code flow. Error: ${error instanceof Error ? error.message : String(error)}`);\n        }\n        // Fall through to new device code flow (interactive mode only)\n      }\n    }\n\n    // No valid token - check if we can start device code flow\n    if (this.config.headless) {\n      throw new Error('No valid token available in headless mode. Device code flow requires user interaction. ' + 'Please run authentication flow interactively first or provide valid tokens.');\n    }\n\n    // Interactive mode - start device code flow\n    logger.info('Starting device code flow', { accountId: effectiveAccountId });\n    const token = await this.startDeviceCodeFlow(effectiveAccountId);\n    return token.accessToken;\n  }\n\n  /**\n   * Get user email from Microsoft Graph /me endpoint (pure query)\n   *\n   * @param accountId - Account identifier\n   * @returns User's email address (userPrincipalName or mail field)\n   */\n  async getUserEmail(accountId?: string): Promise<string> {\n    const { logger } = this.config;\n    // Device code is single-account mode\n    const token = await this.getAccessToken(accountId);\n\n    logger.debug('Fetching user email from Microsoft Graph');\n\n    const response = await fetchWithTimeout('https://graph.microsoft.com/v1.0/me', {\n      headers: { Authorization: `Bearer ${token}` },\n    });\n\n    if (!response.ok) {\n      const errorText = await response.text();\n      throw new Error(`Failed to get user email (HTTP ${response.status}): ${errorText}`);\n    }\n\n    const userData = (await response.json()) as { userPrincipalName?: string; mail?: string };\n    const email = userData.userPrincipalName || userData.mail;\n\n    if (!email) {\n      throw new Error('User email not found in Microsoft Graph response');\n    }\n\n    return email;\n  }\n\n  /**\n   * Create auth provider for Microsoft Graph SDK integration\n   *\n   * Device code provider ALWAYS uses fixed accountId='device-code'\n   * This is by design - device code is a single static identity pattern\n   *\n   * @param accountId - Account identifier (must be 'device-code' or undefined, otherwise throws error)\n   * @returns Auth provider with getAccessToken method\n   */\n  toAuthProvider(accountId?: string): { getAccessToken: () => Promise<string> } {\n    // Device code ONLY works with 'device-code' account ID\n    if (accountId !== undefined && accountId !== 'device-code') {\n      throw new Error(`DeviceCodeProvider only supports accountId='device-code', got '${accountId}'. Device code uses a single static identity pattern.`);\n    }\n\n    // ALWAYS use fixed 'device-code' account ID\n    const getToken = () => this.getAccessToken('device-code');\n\n    return {\n      getAccessToken: getToken,\n    };\n  }\n\n  /**\n   * Create Microsoft Graph AuthenticationProvider for SDK usage\n   *\n   * @param accountId - Account identifier\n   * @returns AuthenticationProvider that provides access tokens\n   */\n  private createAuthProvider(accountId?: string): MicrosoftAuthProvider {\n    return {\n      getAccessToken: async () => {\n        return await this.getAccessToken(accountId);\n      },\n    };\n  }\n\n  /**\n   * Create middleware wrapper for single-user authentication\n   *\n   * Middleware wraps tool, resource, and prompt handlers and injects authContext into extra parameter.\n   * Handlers receive MicrosoftAuthProvider via extra.authContext.auth for API calls.\n   *\n   * @returns Object with withToolAuth, withResourceAuth, withPromptAuth methods\n   *\n   * @example\n   * ```typescript\n   * // Server registration\n   * const middleware = provider.authMiddleware();\n   * const tools = toolFactories.map(f => f()).map(middleware.withToolAuth);\n   * const resources = resourceFactories.map(f => f()).map(middleware.withResourceAuth);\n   * const prompts = promptFactories.map(f => f()).map(middleware.withPromptAuth);\n   *\n   * // Tool handler receives auth\n   * async function handler({ id }: In, extra: EnrichedExtra) {\n   *   // extra.authContext.auth is MicrosoftAuthProvider (from middleware)\n   *   const graph = Client.initWithMiddleware({ authProvider: extra.authContext.auth });\n   * }\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 (defensive: handle arg-less tool pattern)\n        // If called with fewer args than expected, use first arg as both args and extra\n        let extra: EnrichedExtra;\n        if (allArgs.length <= extraPosition) {\n          // Arg-less tool pattern: single argument is both args and extra\n          extra = (allArgs[0] || {}) as EnrichedExtra;\n          allArgs[0] = extra;\n          allArgs[extraPosition] = extra;\n        } else {\n          extra = (allArgs[extraPosition] || {}) as EnrichedExtra;\n          allArgs[extraPosition] = extra;\n        }\n\n        try {\n          // Use fixed accountId for storage isolation (like service-account pattern)\n          const accountId = 'device-code';\n\n          // Create Microsoft Graph authentication provider\n          const auth = this.createAuthProvider(accountId);\n\n          // Inject authContext and logger into extra parameter\n          (extra as { authContext?: AuthContext }).authContext = {\n            auth, // MicrosoftAuthProvider for Graph SDK\n            accountId, // Account identifier\n          };\n          (extra as { logger?: unknown }).logger = this.config.logger;\n\n          // Call original handler with all args\n          return await originalHandler(...allArgs);\n        } catch (error) {\n          // Wrap auth errors with helpful context\n          throw new Error(`Device code authentication failed: ${error instanceof Error ? error.message : String(error)}`);\n        }\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":["getToken","setToken","open","fetchWithTimeout","DeviceCodeProvider","startDeviceCodeFlow","accountId","clientId","tenantId","scope","logger","headless","config","deviceCodeEndpoint","debug","endpoint","deviceCodeResponse","method","headers","body","URLSearchParams","client_id","ok","errorText","text","Error","status","deviceCodeData","json","device_code","user_code","verification_uri","verification_uri_complete","expires_in","interval","info","urlToOpen","url","error","message","String","pollForToken","deviceCode","intervalSeconds","service","tokenStore","tokenEndpoint","currentInterval","startTime","Date","now","Promise","resolve","setTimeout","elapsed","Math","floor","response","grant_type","responseData","tokenData","token","accessToken","access_token","refresh_token","refreshToken","expiresAt","errorDescription","error_description","newInterval","refreshAccessToken","isTokenValid","undefined","getAccessToken","effectiveAccountId","storedToken","refreshedToken","getUserEmail","Authorization","userData","email","userPrincipalName","mail","toAuthProvider","createAuthProvider","authMiddleware","wrapAtPosition","module","extraPosition","originalHandler","handler","wrappedHandler","allArgs","extra","length","auth","authContext","withToolAuth","withResourceAuth","withPromptAuth"],"mappings":"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"}

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

@@ -13,9 +13,19 @@
  * 5. Handle callback, exchange code for token
  * 6. Cache token to storage
  * 7. Close ephemeral server
+ *
+ * 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 { type LoopbackOAuthConfig } from '../types.js';
+import { type CachedToken, type LoopbackOAuthConfig } from '../types.js';
 /**
  * Loopback OAuth Client (RFC 8252 Section 7.3)
  *
@@ -27,6 +37,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
@@ -44,14 +55,6 @@ export declare class LoopbackOAuthProvider implements OAuth2TokenStorageProvider
     toAuthProvider(accountId?: string): {
         getAccessToken: () => Promise<string>;
     };
-    /**
-     * 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 Microsoft Graph API (pure query)
      * Used to query email for existing authenticated account
@@ -60,14 +63,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 Microsoft Graph using access token
@@ -77,9 +72,89 @@ export declare class LoopbackOAuthProvider implements OAuth2TokenStorageProvider
      * @returns User's email address (mail field or userPrincipalName fallback)
      */
     private fetchUserEmailFromToken;
-    private performEphemeralOAuthFlow;
+    /**
+     * Build Microsoft 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.
+     */
+    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 auth middleware for single-user context (single active account per service)
      *