@mcp-z/oauth-microsoft 1.0.0

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

@@ -0,0 +1,125 @@
+/**
+ * Loopback OAuth Implementation for Microsoft (RFC 8252)
+ *
+ * Implements OAuth 2.0 Authorization Code Flow with PKCE using loopback interface redirection.
+ * Uses ephemeral local server with OS-assigned port (RFC 8252 Section 8.3).
+ * Eliminates port conflicts by using port 0, allowing unlimited concurrent servers.
+ *
+ * Flow:
+ * 1. Check token cache (memory + storage)
+ * 2. If cache miss: Start ephemeral server on port 0
+ * 3. Generate auth URL with dynamic redirect (localhost:{assigned-port})
+ * 4. Open browser or print URL (headless flag controls behavior)
+ * 5. Handle callback, exchange code for token
+ * 6. Cache token to storage
+ * 7. Close ephemeral server
+ */
+import { type OAuth2TokenStorageProvider } from '@mcp-z/oauth';
+import { type LoopbackOAuthConfig } from '../types.js';
+/**
+ * Loopback OAuth Client (RFC 8252 Section 7.3)
+ *
+ * Implements OAuth 2.0 Authorization Code Flow with PKCE for native applications
+ * using loopback interface redirection. Manages ephemeral OAuth flows and token persistence
+ * with Keyv for key-based token storage using compound keys.
+ *
+ * Token key format: {accountId}:{service}:token (e.g., "user@example.com:outlook:token")
+ */
+export declare class LoopbackOAuthProvider implements OAuth2TokenStorageProvider {
+    private config;
+    constructor(config: LoopbackOAuthConfig);
+    /**
+     * Get access token from Keyv using compound key
+     *
+     * @param accountId - Account identifier (email address). Required for loopback OAuth.
+     * @returns Access token for API requests
+     */
+    getAccessToken(accountId?: string): Promise<string>;
+    /**
+     * Convert to Microsoft Graph-compatible auth provider
+     *
+     * @param accountId - Account identifier for multi-account support (e.g., 'user@example.com')
+     * @returns Auth provider configured for the specified account
+     */
+    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
+     *
+     * @param accountId - Account identifier to get email for
+     * @returns User's email address
+     */
+    getUserEmail(accountId?: string): Promise<string>;
+    /**
+     * Check for existing accounts in token storage (incremental OAuth detection)
+     *
+     * Uses key-utils helper for forward compatibility with key format changes.
+     *
+     * @returns Array of account IDs that have tokens for this service
+     */
+    private getExistingAccounts;
+    private isTokenValid;
+    /**
+     * Fetch user email from Microsoft Graph using access token
+     * Called during OAuth flow to get email for accountId
+     *
+     * @param accessToken - Fresh access token from OAuth exchange
+     * @returns User's email address (mail field or userPrincipalName fallback)
+     */
+    private fetchUserEmailFromToken;
+    private performEphemeralOAuthFlow;
+    private exchangeCodeForToken;
+    private refreshAccessToken;
+    /**
+     * Create auth middleware for single-user context (single active account per service)
+     *
+     * Single-user mode:
+     * - Maintains per-service active accounts in storage
+     * - Supports backchannel account override via extra._meta.accountId
+     * - Automatically enhances output schemas with auth_required branch
+     *
+     * Example:
+     * ```typescript
+     * const loopback = new LoopbackOAuthProvider({ service: 'outlook', ... });
+     * const middleware = loopback.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);
+     * ```
+     *
+     * @returns Object with withToolAuth, withResourceAuth, withPromptAuth methods
+     */
+    authMiddleware(): {
+        withToolAuth: <T extends {
+            name: string;
+            config: unknown;
+            handler: unknown;
+        }>(module: T) => T;
+        withResourceAuth: <T extends {
+            name: string;
+            template?: unknown;
+            config?: unknown;
+            handler: unknown;
+        }>(module: T) => T;
+        withPromptAuth: <T extends {
+            name: string;
+            config: unknown;
+            handler: unknown;
+        }>(module: T) => T;
+    };
+}
+/**
+ * Create a loopback OAuth client for Microsoft services
+ * Works for both stdio and HTTP transports
+ */
+export declare function createMicrosoftFileAuth(config: LoopbackOAuthConfig): OAuth2TokenStorageProvider;