@mcp-z/oauth-microsoft 1.0.1 → 1.0.3

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

@@ -13,6 +13,16 @@
  * 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 CachedToken, type LoopbackOAuthConfig } from '../types.js';
@@ -27,6 +37,7 @@ import { type CachedToken, 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
@@ -61,7 +72,73 @@ 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;
     /**

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

@@ -13,6 +13,16 @@
  * 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 CachedToken, type LoopbackOAuthConfig } from '../types.js';
@@ -27,6 +37,7 @@ import { type CachedToken, 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
@@ -61,7 +72,73 @@ 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;
     /**