@microsoft/rayfin-auth-provider-fabric 1.20.0 → 1.22.0

package/dist/PostMessageAuthTransport.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Handoff result returned by the host extension's `AuthPlugin`.
+ */
+export interface PostMessageHandoffResult {
+    /** Single-use handoff code to exchange for tokens. */
+    handoffCode: string;
+    /** Opaque nonce echoed back for correlation. */
+    state: string;
+}
+/**
+ * PostMessage transport for embedded (iframe) auth.
+ *
+ * Sends a `fabric-auth` / `auth.requestHandoff` message to the parent
+ * window and waits for a correlated response carrying the handoff code.
+ *
+ * Delegates the low-level postMessage send/receive/correlate to
+ * `sendBridgeRequest` from `@microsoft/fabric-embedded-host`.
+ *
+ * @param params.callbackUrl  The callback origin where the SPA is hosted.
+ * @param params.codeChallenge  PKCE S256 code challenge.
+ * @param params.codeChallengeMethod  Always `"S256"`.
+ * @param params.state  Opaque nonce for CSRF/correlation.
+ * @param params.timeoutMs  Response timeout in milliseconds (default 30 000).
+ * @returns Promise resolving with the handoff code and state.
+ * @throws {AuthError} On timeout, error response, or missing parent.
+ */
+export declare function requestHandoff(params: {
+    callbackUrl: string;
+    codeChallenge: string;
+    codeChallengeMethod: string;
+    state: string;
+    timeoutMs?: number;
+}): Promise<PostMessageHandoffResult>;
+//# sourceMappingURL=PostMessageAuthTransport.d.ts.map

package/dist/PostMessageAuthTransport.js

@@ -0,0 +1,44 @@
+import { sendBridgeRequest, BridgeError, } from '@microsoft/fabric-embedded-host';
+import { AuthError } from '@microsoft/rayfin-lib';
+/**
+ * PostMessage transport for embedded (iframe) auth.
+ *
+ * Sends a `fabric-auth` / `auth.requestHandoff` message to the parent
+ * window and waits for a correlated response carrying the handoff code.
+ *
+ * Delegates the low-level postMessage send/receive/correlate to
+ * `sendBridgeRequest` from `@microsoft/fabric-embedded-host`.
+ *
+ * @param params.callbackUrl  The callback origin where the SPA is hosted.
+ * @param params.codeChallenge  PKCE S256 code challenge.
+ * @param params.codeChallengeMethod  Always `"S256"`.
+ * @param params.state  Opaque nonce for CSRF/correlation.
+ * @param params.timeoutMs  Response timeout in milliseconds (default 30 000).
+ * @returns Promise resolving with the handoff code and state.
+ * @throws {AuthError} On timeout, error response, or missing parent.
+ */
+export function requestHandoff(params) {
+    const { callbackUrl, codeChallenge, codeChallengeMethod, state, timeoutMs } = params;
+    if (!window.parent || window.parent === window) {
+        return Promise.reject(new AuthError('No parent window — embedded auth requires an iframe host.', 'NO_PARENT_WINDOW'));
+    }
+    return sendBridgeRequest({
+        target: window.parent,
+        channel: 'fabric-auth',
+        kind: 'auth.requestHandoff',
+        payload: {
+            callbackUrl,
+            codeChallenge,
+            codeChallengeMethod,
+            state,
+        },
+        timeoutMs,
+    }).catch((err) => {
+        // Re-wrap BridgeError as AuthError for backward compatibility
+        if (err instanceof BridgeError) {
+            throw new AuthError(err.message, err.code);
+        }
+        throw err;
+    });
+}
+//# sourceMappingURL=PostMessageAuthTransport.js.map

package/dist/embeddedFabricLogin.d.ts

@@ -0,0 +1,20 @@
+import type { Auth } from '@microsoft/rayfin-auth';
+import type { FabricAuthOptions } from './types';
+/**
+ * Embedded-mode Fabric login — acquires a session via postMessage to the
+ * parent Fabric Extension Host without opening a popup.
+ *
+ * 1. Generates PKCE parameters in local variables (no `localStorage`).
+ * 2. Sends `auth.requestHandoff` to the parent via {@link requestHandoff}.
+ * 3. Receives the handoff code from the host's `AuthPlugin`.
+ * 4. Exchanges the handoff code for tokens via `exchangeVerificationCode`.
+ * 5. Creates a session via `createSessionFromTokenResponse`.
+ *
+ * The session is stored in the iframe's own `localStorage`.
+ *
+ * @param auth Auth instance for token exchange and session management.
+ * @param options Fabric auth options (`returnOrigin` required).
+ * @throws {AuthError} On missing options, transport failure, or token exchange error.
+ */
+export declare function embeddedFabricLogin(auth: Auth, options: FabricAuthOptions): Promise<void>;
+//# sourceMappingURL=embeddedFabricLogin.d.ts.map

package/dist/embeddedFabricLogin.js

@@ -0,0 +1,55 @@
+import { generateCodeVerifier, generateCodeChallenge, generateState, } from '@microsoft/rayfin-auth';
+import { AuthError } from '@microsoft/rayfin-lib';
+import { requestHandoff } from './PostMessageAuthTransport';
+/**
+ * Embedded-mode Fabric login — acquires a session via postMessage to the
+ * parent Fabric Extension Host without opening a popup.
+ *
+ * 1. Generates PKCE parameters in local variables (no `localStorage`).
+ * 2. Sends `auth.requestHandoff` to the parent via {@link requestHandoff}.
+ * 3. Receives the handoff code from the host's `AuthPlugin`.
+ * 4. Exchanges the handoff code for tokens via `exchangeVerificationCode`.
+ * 5. Creates a session via `createSessionFromTokenResponse`.
+ *
+ * The session is stored in the iframe's own `localStorage`.
+ *
+ * @param auth Auth instance for token exchange and session management.
+ * @param options Fabric auth options (`returnOrigin` required).
+ * @throws {AuthError} On missing options, transport failure, or token exchange error.
+ */
+export async function embeddedFabricLogin(auth, options) {
+    if (!options.returnOrigin) {
+        throw new AuthError('returnOrigin is required for embedded Fabric authentication.', 'MISSING_RETURN_ORIGIN');
+    }
+    // PKCE in local variables only — not persisted to localStorage.
+    const codeVerifier = generateCodeVerifier();
+    const codeChallenge = await generateCodeChallenge(codeVerifier);
+    const state = generateState();
+    console.debug('[FabricAuth:embedded] Requesting handoff from host via postMessage');
+    // NOTE: We intentionally do NOT pass fabricPortalUrl as the targetOrigin.
+    // The SPA's window.parent is the Fabric *extension* iframe (AppViewMode),
+    // not the portal itself.  The extension runs at a different origin than
+    // fabricPortalUrl, and the child iframe cannot read window.parent.origin.
+    // Security relies on UUID v4 requestId correlation + PKCE.
+    const result = await requestHandoff({
+        callbackUrl: options.returnOrigin,
+        codeChallenge,
+        codeChallengeMethod: 'S256',
+        state,
+    });
+    // Validate state to prevent replay attacks.
+    if (result.state !== state) {
+        throw new AuthError('State mismatch in embedded auth handoff response.', 'STATE_MISMATCH');
+    }
+    console.debug('[FabricAuth:embedded] Handoff received, exchanging code for tokens');
+    const redirectUri = options.returnOrigin;
+    const tokenResponse = await auth.getAuthApi().exchangeVerificationCode({
+        verificationCode: result.handoffCode,
+        codeVerifier,
+        codeType: 'fabric_handoff',
+        redirectUri,
+    });
+    auth.createSessionFromTokenResponse(tokenResponse);
+    console.debug('[FabricAuth:embedded] Session established');
+}
+//# sourceMappingURL=embeddedFabricLogin.js.map

package/dist/ensureSignedInWithFabric.d.ts

@@ -3,20 +3,22 @@ import type { FabricAuthOptions } from './types';
 /**
  * Ensures the user is signed in via Fabric brokered authentication.
  *
- * Implements a 3-step waterfall — the first step that succeeds short-circuits the rest:
+ * Implements a multi-step waterfall — the first step that succeeds short-circuits the rest:
  *
  * 1. **Already authenticated** — if `auth.getSession().isAuthenticated` is true,
  *    return the existing session immediately.
  * 2. **Refresh token** — if a refresh token is available, attempt `auth.refreshSession()`.
  *    Return the refreshed session on success; continue on failure.
- * 3. **Open Fabric broker** — no existing auth path available. Open the Fabric Portal
+ * 3. **Embedded mode** — if running inside a Fabric iframe (`fabricEmbedded=true`),
+ *    use `embeddedFabricLogin()` to acquire a session via `postMessage` handoff.
+ * 4. **Open Fabric broker** — no existing auth path available. Open the Fabric Portal
  *    in a new tab via `initiateFabricLogin()` and wait for the Fabric extension to post
  *    the handoff code via `postMessage`. The function exchanges the code internally
  *    and creates the session. Once the promise resolves, return the new session.
  *
- * **Step 3 calls `window.open()`** — to avoid popup/tab blockers, call this function
+ * **Step 4 calls `window.open()`** — to avoid popup/tab blockers, call this function
  * from inside a synchronous user-gesture handler (e.g., a button click).
- * Steps 1–2 do not open windows and are safe to call on page load.
+ * Steps 1–3 do not open windows and are safe to call on page load.
  *
  * @param auth The Auth instance.
  * @param options Fabric authentication options (workspaceId, projectId, returnOrigin).

package/dist/ensureSignedInWithFabric.js

@@ -1,22 +1,26 @@
 import { AuthError } from '@microsoft/rayfin-lib';
+import { embeddedFabricLogin } from './embeddedFabricLogin';
+import { isEmbeddedMode, tryResumeSession } from './fabricAuthHelpers';
 import { initiateFabricLogin } from './initiateFabricLogin';
 /**
  * Ensures the user is signed in via Fabric brokered authentication.
  *
- * Implements a 3-step waterfall — the first step that succeeds short-circuits the rest:
+ * Implements a multi-step waterfall — the first step that succeeds short-circuits the rest:
  *
  * 1. **Already authenticated** — if `auth.getSession().isAuthenticated` is true,
  *    return the existing session immediately.
  * 2. **Refresh token** — if a refresh token is available, attempt `auth.refreshSession()`.
  *    Return the refreshed session on success; continue on failure.
- * 3. **Open Fabric broker** — no existing auth path available. Open the Fabric Portal
+ * 3. **Embedded mode** — if running inside a Fabric iframe (`fabricEmbedded=true`),
+ *    use `embeddedFabricLogin()` to acquire a session via `postMessage` handoff.
+ * 4. **Open Fabric broker** — no existing auth path available. Open the Fabric Portal
  *    in a new tab via `initiateFabricLogin()` and wait for the Fabric extension to post
  *    the handoff code via `postMessage`. The function exchanges the code internally
  *    and creates the session. Once the promise resolves, return the new session.
  *
- * **Step 3 calls `window.open()`** — to avoid popup/tab blockers, call this function
+ * **Step 4 calls `window.open()`** — to avoid popup/tab blockers, call this function
  * from inside a synchronous user-gesture handler (e.g., a button click).
- * Steps 1–2 do not open windows and are safe to call on page load.
+ * Steps 1–3 do not open windows and are safe to call on page load.
  *
  * @param auth The Auth instance.
  * @param options Fabric authentication options (workspaceId, projectId, returnOrigin).
@@ -24,42 +28,44 @@ import { initiateFabricLogin } from './initiateFabricLogin';
  * @throws {AuthError} If all steps fail or the broker tab is blocked.
  */
 export async function ensureSignedInWithFabric(auth, options) {
-    // Step 1: Already authenticated
-    console.debug('[FabricAuth] Step 1: checking for existing session');
-    const currentSession = auth.getSession();
-    if (currentSession.isAuthenticated) {
-        console.debug('[FabricAuth] Step 1: existing session found, skipping remaining steps');
-        return currentSession;
+    // Steps 1-2: existing session or refresh
+    const resumed = await tryResumeSession(auth);
+    if (resumed) {
+        return resumed;
     }
-    // Step 2: Try refresh token
-    console.debug('[FabricAuth] Step 2: checking for refresh token');
-    if (auth.hasRefreshToken()) {
+    // Step 3: Embedded mode — postMessage auth via parent iframe host
+    if (isEmbeddedMode(options)) {
+        console.debug('[FabricAuth] Embedded mode detected, using postMessage auth');
         try {
-            await auth.refreshSession();
-            const refreshedSession = auth.getSession();
-            if (refreshedSession.isAuthenticated) {
-                console.debug('[FabricAuth] Step 2: session refreshed successfully');
-                return refreshedSession;
+            await embeddedFabricLogin(auth, options);
+            const embeddedSession = auth.getSession();
+            if (embeddedSession.isAuthenticated) {
+                console.debug('[FabricAuth] Embedded auth succeeded');
+                return embeddedSession;
             }
+            throw new AuthError('Fabric embedded authentication completed but no session was established.', 'SESSION_NOT_ESTABLISHED');
         }
-        catch {
-            console.warn('[FabricAuth] Step 2: session refresh failed, continuing to step 3');
+        catch (err) {
+            // If there's no parent window the embedded flag is stale (e.g.
+            // leftover sessionStorage or URL param without an actual iframe).
+            // Fall through to the popup path instead of failing outright.
+            if (err instanceof AuthError && err.code === 'NO_PARENT_WINDOW') {
+                console.debug('[FabricAuth] No parent window — falling back to popup auth');
+            }
+            else {
+                throw err;
+            }
         }
     }
-    else {
-        console.debug('[FabricAuth] Step 2: no refresh token available, skipping to step 3');
-    }
-    // Step 3: Open Fabric broker in a new tab
+    // Step 4: Open Fabric broker in a new tab (popup flow)
     // WARNING: This calls window.open() — must be in a user-gesture context
-    console.debug('[FabricAuth] Step 3: initiating Fabric broker login');
+    console.debug('[FabricAuth] Initiating Fabric broker login');
     await initiateFabricLogin(auth, options);
-    // Session was created inside initiateFabricLogin via createSessionFromTokenResponse
     const newSession = auth.getSession();
     if (newSession.isAuthenticated) {
-        console.debug('[FabricAuth] Step 3: Fabric broker login succeeded, session established');
+        console.debug('[FabricAuth] Fabric broker login succeeded');
         return newSession;
     }
-    console.warn('[FabricAuth] Step 3: Fabric broker login completed but no session was established');
     throw new AuthError('Fabric authentication completed but no session was established.', 'SESSION_NOT_ESTABLISHED');
 }
 //# sourceMappingURL=ensureSignedInWithFabric.js.map

package/dist/fabricAuthHelpers.d.ts

@@ -0,0 +1,25 @@
+import type { Auth, OpaqueSession } from '@microsoft/rayfin-auth';
+import type { FabricAuthOptions } from './types';
+/**
+ * Detects embedded mode from the `fabricEmbedded` option, the
+ * `?fabricEmbedded=true` URL query parameter, or a previously stored
+ * `sessionStorage` flag.
+ *
+ * Delegates to `@microsoft/fabric-embedded-host` for the actual
+ * detection logic.  `FabricAuthOptions` satisfies the shared
+ * `EmbeddedModeOptions` interface.
+ */
+export declare function isEmbeddedMode(options: FabricAuthOptions): boolean;
+/**
+ * Attempts to resume an existing session without any user interaction.
+ *
+ * 1. Returns the current session if already authenticated.
+ * 2. If a refresh token is available, tries `auth.refreshSession()` and
+ *    returns the refreshed session on success.
+ * 3. Returns `null` when neither path produces an authenticated session.
+ *
+ * This helper never opens windows, popups, or postMessage channels —
+ * it is always safe to call on page load.
+ */
+export declare function tryResumeSession(auth: Auth): Promise<OpaqueSession | null>;
+//# sourceMappingURL=fabricAuthHelpers.d.ts.map

package/dist/fabricAuthHelpers.js

@@ -0,0 +1,48 @@
+import { isEmbeddedMode as sharedIsEmbeddedMode } from '@microsoft/fabric-embedded-host';
+/**
+ * Detects embedded mode from the `fabricEmbedded` option, the
+ * `?fabricEmbedded=true` URL query parameter, or a previously stored
+ * `sessionStorage` flag.
+ *
+ * Delegates to `@microsoft/fabric-embedded-host` for the actual
+ * detection logic.  `FabricAuthOptions` satisfies the shared
+ * `EmbeddedModeOptions` interface.
+ */
+export function isEmbeddedMode(options) {
+    return sharedIsEmbeddedMode(options);
+}
+/**
+ * Attempts to resume an existing session without any user interaction.
+ *
+ * 1. Returns the current session if already authenticated.
+ * 2. If a refresh token is available, tries `auth.refreshSession()` and
+ *    returns the refreshed session on success.
+ * 3. Returns `null` when neither path produces an authenticated session.
+ *
+ * This helper never opens windows, popups, or postMessage channels —
+ * it is always safe to call on page load.
+ */
+export async function tryResumeSession(auth) {
+    // Step 1: Already authenticated
+    const currentSession = auth.getSession();
+    if (currentSession.isAuthenticated) {
+        console.debug('[FabricAuth] Existing session found');
+        return currentSession;
+    }
+    // Step 2: Try refresh token
+    if (auth.hasRefreshToken()) {
+        try {
+            await auth.refreshSession();
+            const refreshedSession = auth.getSession();
+            if (refreshedSession.isAuthenticated) {
+                console.debug('[FabricAuth] Session refreshed successfully');
+                return refreshedSession;
+            }
+        }
+        catch {
+            console.warn('[FabricAuth] Session refresh failed, continuing');
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=fabricAuthHelpers.js.map

package/dist/index.d.ts

@@ -1,5 +1,9 @@
 export type { FabricAuthOptions } from './types';
 export { bridgeFabricCallback } from './bridgeFabricCallback';
+export { embeddedFabricLogin } from './embeddedFabricLogin';
 export { ensureSignedInWithFabric } from './ensureSignedInWithFabric';
+export { initEmbeddedAuth } from './initEmbeddedAuth';
 export { initiateFabricLogin } from './initiateFabricLogin';
+export { requestHandoff } from './PostMessageAuthTransport';
+export type { PostMessageHandoffResult } from './PostMessageAuthTransport';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,5 +1,8 @@
 // Functions
 export { bridgeFabricCallback } from './bridgeFabricCallback';
+export { embeddedFabricLogin } from './embeddedFabricLogin';
 export { ensureSignedInWithFabric } from './ensureSignedInWithFabric';
+export { initEmbeddedAuth } from './initEmbeddedAuth';
 export { initiateFabricLogin } from './initiateFabricLogin';
+export { requestHandoff } from './PostMessageAuthTransport';
 //# sourceMappingURL=index.js.map

package/dist/initEmbeddedAuth.d.ts

@@ -0,0 +1,29 @@
+import type { Auth, OpaqueSession } from '@microsoft/rayfin-auth';
+import type { FabricAuthOptions } from './types';
+/**
+ * Initializes embedded Fabric authentication if running inside an iframe
+ * with `?fabricEmbedded=true`.
+ *
+ * Call this once at app startup (e.g., in a `useEffect` or initialization
+ * routine). It is safe to call on page load — it never opens a popup or
+ * new tab.
+ *
+ * **Behaviour:**
+ * - If `fabricEmbedded=true` is **not** in the URL and `options.fabricEmbedded`
+ *   is not `true`, returns `null` immediately (no-op).
+ * - If embedded mode is detected, runs a 3-step waterfall:
+ *   1. Return existing session if already authenticated.
+ *   2. Attempt refresh via refresh token.
+ *   3. Request a handoff code from the parent host via `postMessage`
+ *      and exchange it for a session (PKCE, no popup).
+ *
+ * Apps that also support the popup flow should continue to call
+ * {@link ensureSignedInWithFabric} from a user-gesture handler for the
+ * non-embedded case.
+ *
+ * @param auth  The Auth instance.
+ * @param options  Fabric authentication options.
+ * @returns The authenticated session, or `null` if not in embedded mode.
+ */
+export declare function initEmbeddedAuth(auth: Auth, options: FabricAuthOptions): Promise<OpaqueSession | null>;
+//# sourceMappingURL=initEmbeddedAuth.d.ts.map

package/dist/initEmbeddedAuth.js

@@ -0,0 +1,54 @@
+import { embeddedFabricLogin } from './embeddedFabricLogin';
+import { isEmbeddedMode, tryResumeSession } from './fabricAuthHelpers';
+/**
+ * Initializes embedded Fabric authentication if running inside an iframe
+ * with `?fabricEmbedded=true`.
+ *
+ * Call this once at app startup (e.g., in a `useEffect` or initialization
+ * routine). It is safe to call on page load — it never opens a popup or
+ * new tab.
+ *
+ * **Behaviour:**
+ * - If `fabricEmbedded=true` is **not** in the URL and `options.fabricEmbedded`
+ *   is not `true`, returns `null` immediately (no-op).
+ * - If embedded mode is detected, runs a 3-step waterfall:
+ *   1. Return existing session if already authenticated.
+ *   2. Attempt refresh via refresh token.
+ *   3. Request a handoff code from the parent host via `postMessage`
+ *      and exchange it for a session (PKCE, no popup).
+ *
+ * Apps that also support the popup flow should continue to call
+ * {@link ensureSignedInWithFabric} from a user-gesture handler for the
+ * non-embedded case.
+ *
+ * @param auth  The Auth instance.
+ * @param options  Fabric authentication options.
+ * @returns The authenticated session, or `null` if not in embedded mode.
+ */
+export async function initEmbeddedAuth(auth, options) {
+    if (!isEmbeddedMode(options)) {
+        return null;
+    }
+    // Steps 1-2: existing session or refresh
+    const resumed = await tryResumeSession(auth);
+    if (resumed) {
+        return resumed;
+    }
+    // Step 3: postMessage handoff (no popup, no window.open)
+    console.debug('[FabricAuth:initEmbedded] Starting postMessage handoff flow');
+    try {
+        await embeddedFabricLogin(auth, options);
+    }
+    catch (err) {
+        console.warn('[FabricAuth:initEmbedded] Embedded login failed', err);
+        return null;
+    }
+    const newSession = auth.getSession();
+    if (newSession.isAuthenticated) {
+        console.debug('[FabricAuth:initEmbedded] Session established');
+        return newSession;
+    }
+    console.warn('[FabricAuth:initEmbedded] Handoff completed but no session was established');
+    return null;
+}
+//# sourceMappingURL=initEmbeddedAuth.js.map

package/dist/initiateFabricLogin.js

@@ -41,8 +41,11 @@ export async function initiateFabricLogin(auth, options) {
         let channel = null;
         // 5-minute timeout — matches the backend's handoff code TTL.
         const TIMEOUT_MS = 5 * 60 * 1000;
+        /** Whether the brokeredAuth.ready signal has been handled. */
+        let readyHandled = false;
         function cleanup() {
             window.removeEventListener('message', handleMessage);
+            window.removeEventListener('message', handleReady);
             channel?.close();
             channel = null;
             clearTimeout(timeoutId);
@@ -54,7 +57,7 @@ export async function initiateFabricLogin(auth, options) {
         function handleMessage(event) {
             // Origin check is advisory — state + PKCE provide the real security.
             if (event.origin !== expectedBrokerOrigin) {
-                console.warn(`[FabricAuth] postMessage origin mismatch (expected="${expectedBrokerOrigin}", actual="${event.origin}") — continuing (secured by state + PKCE)`);
+                console.info(`[FabricAuth] postMessage from origin="${event.origin}" (expected portal="${expectedBrokerOrigin}") — continuing (secured by state + PKCE)`);
             }
             if (!event.data || typeof event.data !== 'object') {
                 console.debug('[FabricAuth] postMessage ignored: non-object payload');
@@ -101,6 +104,53 @@ export async function initiateFabricLogin(auth, options) {
             cleanup();
             reject(new AuthError('Fabric authentication timed out after 5 minutes. Please try again.', 'FABRIC_AUTH_TIMEOUT'));
         }, TIMEOUT_MS);
+        /**
+         * Handles `brokeredAuth.ready` from the broker extension.
+         *
+         * When the broker extension sends a ready signal the SDK responds with a
+         * `brokeredAuth.challenge` containing the PKCE parameters.  Only the
+         * first ready signal is handled — subsequent signals are ignored.
+         *
+         * The challenge is sent to `event.source` (the window that sent the ready
+         * signal) rather than `fabricWindow`.  In Fabric the extension runs in a
+         * cross-origin iframe inside the popup — `postMessage` sent to the
+         * popup's top-level window does not propagate to child iframes.
+         */
+        function handleReady(event) {
+            if (readyHandled)
+                return;
+            if (!event.data || typeof event.data !== 'object')
+                return;
+            if (event.data.type !== 'brokeredAuth.ready')
+                return;
+            // Origin check is advisory — the extension iframe runs at a different
+            // origin than the Fabric portal.  PKCE + state provide the real security.
+            if (event.origin !== expectedBrokerOrigin) {
+                console.info(`[FabricAuth] brokeredAuth.ready from origin="${event.origin}" (expected portal="${expectedBrokerOrigin}") — continuing (secured by state + PKCE)`);
+            }
+            readyHandled = true;
+            window.removeEventListener('message', handleReady);
+            const challengePayload = {
+                type: 'brokeredAuth.challenge',
+                returnOrigin: options.returnOrigin,
+                codeChallenge,
+                codeChallengeMethod: 'S256',
+                state,
+            };
+            // Reply to the window that sent the ready signal (the extension iframe).
+            const source = event.source;
+            if (source) {
+                source.postMessage(challengePayload, event.origin || '*');
+                console.debug(`[FabricAuth] Sent brokeredAuth.challenge to event.source (origin=${event.origin || '*'})`);
+            }
+            else if (fabricWindow && !fabricWindow.closed) {
+                // Fallback: if event.source is unavailable, try the popup directly.
+                fabricWindow.postMessage(challengePayload, expectedBrokerOrigin);
+                console.debug('[FabricAuth] Sent brokeredAuth.challenge to fabricWindow (event.source unavailable)');
+            }
+        }
+        // Listen for brokeredAuth.ready from the popup (postMessage PKCE).
+        window.addEventListener('message', handleReady);
         // Listen for handoff via postMessage and BroadcastChannel (legacy bridge).
         console.debug('[FabricAuth] Registering postMessage listener for broker handoff');
         window.addEventListener('message', handleMessage);

package/dist/types.d.ts

@@ -34,5 +34,13 @@ export interface FabricAuthOptions {
      * @deprecated Backward-compat only — will be removed once postMessage rollout is complete.
      */
     callbackUrl?: string;
+    /**
+     * When `true`, use embedded (iframe) authentication via postMessage instead
+     * of the popup flow. The SDK also auto-detects embedded mode when
+     * `?fabricEmbedded=true` is present in `window.location.search`.
+     *
+     * Set explicitly to override URL-based detection.
+     */
+    fabricEmbedded?: boolean;
 }
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/rayfin-auth-provider-fabric",
-  "version": "1.20.0",
+  "version": "1.22.0",
   "description": "Fabric brokered authentication provider for Rayfin SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,8 +12,9 @@
   ],
   "type": "module",
   "dependencies": {
-    "@microsoft/rayfin-lib": "1.20.0",
-    "@microsoft/rayfin-auth": "1.20.0"
+    "@microsoft/rayfin-auth": "1.22.0",
+    "@microsoft/fabric-embedded-host": "1.22.0",
+    "@microsoft/rayfin-lib": "1.22.0"
   },
   "devDependencies": {
     "typescript": "^5.8.3",