@mcp-z/oauth-microsoft 1.0.0 → 1.0.2

package/dist/cjs/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)
      *