@mcp-z/oauth-microsoft 1.0.0

package/dist/cjs/providers/device-code.d.cts

@@ -0,0 +1,179 @@
+/**
+ * Device Code OAuth Implementation for Microsoft
+ *
+ * Implements OAuth 2.0 Device Authorization Grant (RFC 8628) for headless/limited-input devices.
+ * Designed for scenarios where interactive browser flows are impractical (SSH sessions, CI/CD, etc.).
+ *
+ * Flow:
+ * 1. Request device code from Microsoft endpoint
+ * 2. Display user_code and verification_uri to user
+ * 3. Poll token endpoint until user completes authentication
+ * 4. Cache access token + refresh token to storage
+ * 5. Refresh tokens when expired
+ *
+ * Similar to service accounts in usage pattern: single static identity, minimal account management.
+ */
+import { type OAuth2TokenStorageProvider } from '@mcp-z/oauth';
+import type { Keyv } from 'keyv';
+import type { Logger, MicrosoftService } from '../types.js';
+/**
+ * Device Code Provider Configuration
+ */
+export interface DeviceCodeConfig {
+    /** Microsoft service type (e.g., 'outlook') */
+    service: MicrosoftService;
+    /** Azure AD client ID */
+    clientId: string;
+    /** Azure AD tenant ID */
+    tenantId: string;
+    /** OAuth scopes to request (space-separated string or array) */
+    scope: string;
+    /** Logger instance */
+    logger: Logger;
+    /** Token storage for caching */
+    tokenStore: Keyv<unknown>;
+    /** Headless mode - print device code instead of opening browser */
+    headless: boolean;
+}
+/**
+ * DeviceCodeProvider implements OAuth2TokenStorageProvider using Microsoft Device Code Flow
+ *
+ * This provider:
+ * - Initiates device code flow with Microsoft endpoint
+ * - Displays user_code and verification_uri for manual authentication
+ * - Polls token endpoint until user completes auth
+ * - Stores access tokens + refresh tokens in Keyv storage
+ * - Refreshes tokens when expired
+ * - Provides single static identity (minimal account management like service accounts)
+ *
+ * @example
+ * ```typescript
+ * const provider = new DeviceCodeProvider({
+ *   service: 'outlook',
+ *   clientId: 'your-client-id',
+ *   tenantId: 'common',
+ *   scope: 'https://graph.microsoft.com/Mail.Read',
+ *   logger: console,
+ *   tokenStore: new Keyv(),
+ *   headless: true,
+ * });
+ *
+ * // Get authenticated Microsoft Graph client
+ * const token = await provider.getAccessToken('default');
+ * ```
+ */
+export declare class DeviceCodeProvider implements OAuth2TokenStorageProvider {
+    private config;
+    constructor(config: DeviceCodeConfig);
+    /**
+     * Start device code flow and poll for token
+     *
+     * 1. POST to /devicecode endpoint to get device_code and user_code
+     * 2. Display verification instructions to user
+     * 3. Poll /token endpoint every interval seconds
+     * 4. Handle authorization_pending, slow_down, expired_token errors
+     * 5. Return token when user completes authentication
+     */
+    private startDeviceCodeFlow;
+    /**
+     * Poll Microsoft token endpoint until user completes authentication
+     *
+     * Handles Microsoft-specific error codes:
+     * - authorization_pending: User hasn't completed auth yet, keep polling
+     * - slow_down: Increase polling interval by 5 seconds
+     * - authorization_declined: User denied authorization
+     * - expired_token: Device code expired (typically after 15 minutes)
+     */
+    private pollForToken;
+    /**
+     * Refresh expired access token using refresh token
+     *
+     * @param refreshToken - Refresh token from previous authentication
+     * @returns New cached token with fresh access token
+     */
+    private refreshAccessToken;
+    /**
+     * Check if token is still valid (not expired)
+     */
+    private isTokenValid;
+    /**
+     * Get access token for Microsoft Graph API
+     *
+     * Flow:
+     * 1. Check token storage
+     * 2. If valid token exists, return it
+     * 3. If expired but has refresh token, try refresh
+     * 4. Otherwise, start new device code flow
+     *
+     * @param accountId - Account identifier. Defaults to 'device-code' (fixed identifier for device code flow).
+     * @returns Access token for API requests
+     */
+    getAccessToken(accountId?: string): Promise<string>;
+    /**
+     * Get user email from Microsoft Graph /me endpoint (pure query)
+     *
+     * @param accountId - Account identifier
+     * @returns User's email address (userPrincipalName or mail field)
+     */
+    getUserEmail(accountId?: string): Promise<string>;
+    /**
+     * Create auth provider for Microsoft Graph SDK integration
+     *
+     * Device code provider ALWAYS uses fixed accountId='device-code'
+     * This is by design - device code is a single static identity pattern
+     *
+     * @param accountId - Account identifier (must be 'device-code' or undefined, otherwise throws error)
+     * @returns Auth provider with getAccessToken method
+     */
+    toAuthProvider(accountId?: string): {
+        getAccessToken: () => Promise<string>;
+    };
+    /**
+     * Create Microsoft Graph AuthenticationProvider for SDK usage
+     *
+     * @param accountId - Account identifier
+     * @returns AuthenticationProvider that provides access tokens
+     */
+    private createAuthProvider;
+    /**
+     * Create middleware wrapper for single-user authentication
+     *
+     * Middleware wraps tool, resource, and prompt handlers and injects authContext into extra parameter.
+     * Handlers receive MicrosoftAuthProvider via extra.authContext.auth for API calls.
+     *
+     * @returns Object with withToolAuth, withResourceAuth, withPromptAuth methods
+     *
+     * @example
+     * ```typescript
+     * // Server registration
+     * const middleware = provider.authMiddleware();
+     * const tools = toolFactories.map(f => f()).map(middleware.withToolAuth);
+     * const resources = resourceFactories.map(f => f()).map(middleware.withResourceAuth);
+     * const prompts = promptFactories.map(f => f()).map(middleware.withPromptAuth);
+     *
+     * // Tool handler receives auth
+     * async function handler({ id }: In, extra: EnrichedExtra) {
+     *   // extra.authContext.auth is MicrosoftAuthProvider (from middleware)
+     *   const graph = Client.initWithMiddleware({ authProvider: extra.authContext.auth });
+     * }
+     * ```
+     */
+    authMiddleware(): {
+        withToolAuth: <T extends {
+            name: string;
+            config: unknown;
+            handler: unknown;
+        }>(module: T) => T;
+        withResourceAuth: <T extends {
+            name: string;
+            template?: unknown;
+            config?: unknown;
+            handler: unknown;
+        }>(module: T) => T;
+        withPromptAuth: <T extends {
+            name: string;
+            config: unknown;
+            handler: unknown;
+        }>(module: T) => T;
+    };
+}

package/dist/cjs/providers/device-code.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Device Code OAuth Implementation for Microsoft
+ *
+ * Implements OAuth 2.0 Device Authorization Grant (RFC 8628) for headless/limited-input devices.
+ * Designed for scenarios where interactive browser flows are impractical (SSH sessions, CI/CD, etc.).
+ *
+ * Flow:
+ * 1. Request device code from Microsoft endpoint
+ * 2. Display user_code and verification_uri to user
+ * 3. Poll token endpoint until user completes authentication
+ * 4. Cache access token + refresh token to storage
+ * 5. Refresh tokens when expired
+ *
+ * Similar to service accounts in usage pattern: single static identity, minimal account management.
+ */
+import { type OAuth2TokenStorageProvider } from '@mcp-z/oauth';
+import type { Keyv } from 'keyv';
+import type { Logger, MicrosoftService } from '../types.js';
+/**
+ * Device Code Provider Configuration
+ */
+export interface DeviceCodeConfig {
+    /** Microsoft service type (e.g., 'outlook') */
+    service: MicrosoftService;
+    /** Azure AD client ID */
+    clientId: string;
+    /** Azure AD tenant ID */
+    tenantId: string;
+    /** OAuth scopes to request (space-separated string or array) */
+    scope: string;
+    /** Logger instance */
+    logger: Logger;
+    /** Token storage for caching */
+    tokenStore: Keyv<unknown>;
+    /** Headless mode - print device code instead of opening browser */
+    headless: boolean;
+}
+/**
+ * DeviceCodeProvider implements OAuth2TokenStorageProvider using Microsoft Device Code Flow
+ *
+ * This provider:
+ * - Initiates device code flow with Microsoft endpoint
+ * - Displays user_code and verification_uri for manual authentication
+ * - Polls token endpoint until user completes auth
+ * - Stores access tokens + refresh tokens in Keyv storage
+ * - Refreshes tokens when expired
+ * - Provides single static identity (minimal account management like service accounts)
+ *
+ * @example
+ * ```typescript
+ * const provider = new DeviceCodeProvider({
+ *   service: 'outlook',
+ *   clientId: 'your-client-id',
+ *   tenantId: 'common',
+ *   scope: 'https://graph.microsoft.com/Mail.Read',
+ *   logger: console,
+ *   tokenStore: new Keyv(),
+ *   headless: true,
+ * });
+ *
+ * // Get authenticated Microsoft Graph client
+ * const token = await provider.getAccessToken('default');
+ * ```
+ */
+export declare class DeviceCodeProvider implements OAuth2TokenStorageProvider {
+    private config;
+    constructor(config: DeviceCodeConfig);
+    /**
+     * Start device code flow and poll for token
+     *
+     * 1. POST to /devicecode endpoint to get device_code and user_code
+     * 2. Display verification instructions to user
+     * 3. Poll /token endpoint every interval seconds
+     * 4. Handle authorization_pending, slow_down, expired_token errors
+     * 5. Return token when user completes authentication
+     */
+    private startDeviceCodeFlow;
+    /**
+     * Poll Microsoft token endpoint until user completes authentication
+     *
+     * Handles Microsoft-specific error codes:
+     * - authorization_pending: User hasn't completed auth yet, keep polling
+     * - slow_down: Increase polling interval by 5 seconds
+     * - authorization_declined: User denied authorization
+     * - expired_token: Device code expired (typically after 15 minutes)
+     */
+    private pollForToken;
+    /**
+     * Refresh expired access token using refresh token
+     *
+     * @param refreshToken - Refresh token from previous authentication
+     * @returns New cached token with fresh access token
+     */
+    private refreshAccessToken;
+    /**
+     * Check if token is still valid (not expired)
+     */
+    private isTokenValid;
+    /**
+     * Get access token for Microsoft Graph API
+     *
+     * Flow:
+     * 1. Check token storage
+     * 2. If valid token exists, return it
+     * 3. If expired but has refresh token, try refresh
+     * 4. Otherwise, start new device code flow
+     *
+     * @param accountId - Account identifier. Defaults to 'device-code' (fixed identifier for device code flow).
+     * @returns Access token for API requests
+     */
+    getAccessToken(accountId?: string): Promise<string>;
+    /**
+     * Get user email from Microsoft Graph /me endpoint (pure query)
+     *
+     * @param accountId - Account identifier
+     * @returns User's email address (userPrincipalName or mail field)
+     */
+    getUserEmail(accountId?: string): Promise<string>;
+    /**
+     * Create auth provider for Microsoft Graph SDK integration
+     *
+     * Device code provider ALWAYS uses fixed accountId='device-code'
+     * This is by design - device code is a single static identity pattern
+     *
+     * @param accountId - Account identifier (must be 'device-code' or undefined, otherwise throws error)
+     * @returns Auth provider with getAccessToken method
+     */
+    toAuthProvider(accountId?: string): {
+        getAccessToken: () => Promise<string>;
+    };
+    /**
+     * Create Microsoft Graph AuthenticationProvider for SDK usage
+     *
+     * @param accountId - Account identifier
+     * @returns AuthenticationProvider that provides access tokens
+     */
+    private createAuthProvider;
+    /**
+     * Create middleware wrapper for single-user authentication
+     *
+     * Middleware wraps tool, resource, and prompt handlers and injects authContext into extra parameter.
+     * Handlers receive MicrosoftAuthProvider via extra.authContext.auth for API calls.
+     *
+     * @returns Object with withToolAuth, withResourceAuth, withPromptAuth methods
+     *
+     * @example
+     * ```typescript
+     * // Server registration
+     * const middleware = provider.authMiddleware();
+     * const tools = toolFactories.map(f => f()).map(middleware.withToolAuth);
+     * const resources = resourceFactories.map(f => f()).map(middleware.withResourceAuth);
+     * const prompts = promptFactories.map(f => f()).map(middleware.withPromptAuth);
+     *
+     * // Tool handler receives auth
+     * async function handler({ id }: In, extra: EnrichedExtra) {
+     *   // extra.authContext.auth is MicrosoftAuthProvider (from middleware)
+     *   const graph = Client.initWithMiddleware({ authProvider: extra.authContext.auth });
+     * }
+     * ```
+     */
+    authMiddleware(): {
+        withToolAuth: <T extends {
+            name: string;
+            config: unknown;
+            handler: unknown;
+        }>(module: T) => T;
+        withResourceAuth: <T extends {
+            name: string;
+            template?: unknown;
+            config?: unknown;
+            handler: unknown;
+        }>(module: T) => T;
+        withPromptAuth: <T extends {
+            name: string;
+            config: unknown;
+            handler: unknown;
+        }>(module: T) => T;
+    };
+}