@microsoft/rayfin-auth-provider-fabric 1.36.0-alpha.1601 → 1.36.0-alpha.1663

package/README.md

@@ -8,6 +8,22 @@ npm create @microsoft/rayfin@latest
 
 For more details, [visit our docs](https://aka.ms/rayfin/docs).
 
+## Direct Entra token sign-in
+
+Already have a delegated Entra access token?
+Use `signInWithEntraToken` to establish a Rayfin session on an existing `Auth` instance without a popup or iframe.
+The helper supports browsers and Node.js.
+
+```typescript
+import { signInWithEntraToken } from '@microsoft/rayfin-auth-provider-fabric';
+
+const session = await signInWithEntraToken(client.auth, { entraToken });
+```
+
+Configure the client with the target AppBackend's workload API base URL.
+The helper derives the direct token-exchange endpoint and makes the resulting Rayfin session available to attached SDK clients.
+See [direct sign-in setup and usage](./assets/docs/index.md#direct-entra-token-sign-in) for token requirements, Node.js usage, and session handling.
+
 ## Security
 
 Microsoft takes the security of our software products and services seriously, which

package/assets/docs/index.md

@@ -1,10 +1,11 @@
 # Fabric auth provider
 
-Fabric brokered authentication helpers for Rayfin browser applications.
+Fabric brokered authentication helpers for Rayfin applications.
 
-Use `@microsoft/rayfin-auth-provider-fabric` when your application needs to authenticate through a Fabric-hosted broker experience instead of calling the standard Rayfin auth flows directly.
+Use `@microsoft/rayfin-auth-provider-fabric` to sign in through a Fabric-hosted browser experience or exchange an existing delegated Entra token directly for a Rayfin session.
 
-The package is designed for browser applications that already use `@microsoft/rayfin-auth` and need to reuse an existing session, refresh an expired session, or open the Fabric broker when no session can be restored silently.
+Popup and iframe helpers require a browser.
+`signInWithEntraToken()` supports browsers and Node.js and installs the exchanged session on your existing `Auth` instance.
 
 ## Installation
 
@@ -12,9 +13,71 @@ The package is designed for browser applications that already use `@microsoft/ra
 npm install @microsoft/rayfin-auth-provider-fabric @microsoft/rayfin-auth @microsoft/rayfin-lib
 ```
 
-## Quick start
+## Direct Entra token sign-in
 
-The recommended entry point is `ensureSignedInWithFabric()`.
+Use this flow when your app already obtains a delegated Entra token through MSAL, Azure CLI, or another identity library.
+Token acquisition remains your responsibility.
+The token must target the Fabric/Power BI resource accepted by your deployment, contain delegated `Item.Execute.All`, and belong to the target item's owning tenant.
+The user must also have Execute permission on that item; app-only tokens are not supported.
+The app must have external Entra exchange enabled.
+
+```typescript
+import { Auth } from '@microsoft/rayfin-auth';
+import { ApiClient } from '@microsoft/rayfin-lib';
+import { signInWithEntraToken } from '@microsoft/rayfin-auth-provider-fabric';
+
+const apiClient = new ApiClient({
+  baseUrl: rayfinEndpoint,
+  publishableKey,
+});
+const auth = new Auth(apiClient, { storage: false });
+auth.attachToClient(apiClient);
+
+try {
+  const session = await signInWithEntraToken(auth, { entraToken });
+  console.log('Authenticated', session.isAuthenticated);
+  // Use SDK clients attached to apiClient here.
+} finally {
+  auth.destroy();
+}
+```
+
+This example works in Node.js without browser globals.
+`rayfinEndpoint` is the trusted HTTPS AppBackend workload API base URL, including its existing path, not the app's static-hosting URL or a full token endpoint.
+Use an absolute HTTPS URL, including for localhost, with no credentials, query string, or fragment; relative proxy bases are not supported.
+`entraToken` is the raw token string, without the `Bearer` scheme prefix.
+The SDK resolves `/api/auth/v1/brokered/token` against the configured base.
+No `FabricAuthOptions`, popup, iframe, PKCE, or return origin is needed.
+
+```typescript
+function signInWithEntraToken(
+  auth: Auth,
+  options: EntraTokenSignInOptions
+): Promise<OpaqueSession>;
+
+interface EntraTokenSignInOptions {
+  entraToken: string;
+}
+```
+
+For a `RayfinClient`, pass `client.auth`; it is already attached to the client's HTTP transport.
+The returned `OpaqueSession` exposes session metadata, not tokens.
+Subsequent authenticated requests and refresh use the Rayfin session, not the Entra token.
+The supplied `Auth` instance controls persistence; `storage: false` keeps the session in memory.
+Use a separate instance per user on a server and call `auth.destroy()` when it is no longer needed.
+`RayfinServerClient` does not expose `auth`; this helper expects a standalone `Auth` or `RayfinClient.auth`, not an access-token callback.
+
+Each explicit call attempts an exchange rather than silently returning a previous session.
+Concurrent direct calls on the same `Auth` instance run in invocation order and coordinate with its refresh operations.
+Success persists and replaces the session before emitting the login event; failure preserves an existing unexpired in-memory session without treating it as a successful new sign-in.
+The helper does not revoke the previous server session.
+Failures reject with `AuthError`; do not treat a failed sign-in as authentication of the requested identity.
+Browser callers need the service's CORS policy to permit the calling origin and authorization header.
+The helper does not acquire Entra tokens, follow exchange redirects, or automatically retry a rejected exchange.
+
+## Browser quick start
+
+For the browser broker experience, the recommended entry point is `ensureSignedInWithFabric()`.
 
 It performs a three-step waterfall:
 
@@ -73,6 +136,8 @@ This supports production and development portal URLs such as `https://app.fabric
 
 ## Supported flows
 
+Use `signInWithEntraToken()` when your app already has a delegated Entra token and wants to sign in without a browser broker.
+
 Use `ensureSignedInWithFabric()` when you want silent-session and refresh-token fallback behavior before opening the broker UI.
 
 Use `initiateFabricLogin()` when you only want the broker step and do not need the session and refresh pre-checks.
@@ -114,7 +179,7 @@ The bridge returns `true` when it handled a Fabric handoff and `false` when the
 
 ## Behavior notes
 
-- The broker URL is built with PKCE using the `S256` challenge method.
+- The browser broker URL is built with PKCE using the `S256` challenge method; direct token sign-in does not use PKCE.
 - Existing query parameters on `fabricPortalUrl` are preserved.
 - `callbackUrl` defaults to `${returnOrigin}/auth/callback` when omitted.
 - The broker handoff waits up to five minutes before timing out.
@@ -126,6 +191,10 @@ The package throws `AuthError` values from `@microsoft/rayfin-lib` for validatio
 
 Common cases include missing required options, blocked popups, explicit broker errors, and handoff timeout.
 
+Direct token sign-in reports `INVALID_REQUEST` for invalid local inputs, `EXCHANGE_NOT_ENABLED` for a disabled exchange, `AUTH_FAILED` for token rejection, `INSUFFICIENT_PERMISSIONS` for missing Execute access, and `NOT_AVAILABLE` for an unavailable endpoint.
+Transport or other HTTP failures use `TOKEN_EXCHANGE_FAILED`; malformed successful responses use `INVALID_TOKEN_RESPONSE`.
+Errors do not include the supplied token or raw server response.
+
 ```typescript
 import { AuthError } from '@microsoft/rayfin-lib';
 
@@ -138,8 +207,10 @@ try {
 }
 ```
 
-## Browser requirements
+## Runtime requirements
 
-This package is intended for browser environments.
+The public package entry point and `signInWithEntraToken()` can be imported and used in Node.js without browser globals.
+Use memory-only or appropriate custom `Auth` storage outside a browser.
 
-It depends on browser APIs such as `window.open()`, `postMessage`, `BroadcastChannel`, and `window.location`.
+The popup, iframe, and legacy callback helpers remain browser-only.
+They depend on browser APIs such as `window.open()`, `postMessage`, `BroadcastChannel`, and `window.location`.

package/dist/PostMessageAuthTransport.d.ts

@@ -35,5 +35,14 @@ export declare function requestHandoff(params: {
     codeChallengeMethod: string;
     state: string;
     timeoutMs?: number;
+    /** externalEmbed only: the app's brokered-authorize endpoint URL. */
+    brokeredAuthorizeUrl?: string;
+    /** externalEmbed only: the app's Fabric artifact identifier. */
+    artifactId?: string;
+    /**
+     * externalEmbed only: the pinned parent origin. When set, the request is
+     * delivered to (and the response accepted only from) this origin.
+     */
+    targetOrigin?: string;
 }): Promise<PostMessageHandoffResult>;
 //# sourceMappingURL=PostMessageAuthTransport.d.ts.map

package/dist/PostMessageAuthTransport.js

@@ -21,21 +21,31 @@ import { AuthError } from '@microsoft/rayfin-lib';
  * supported public API.
  */
 export function requestHandoff(params) {
-    const { callbackUrl, codeChallenge, codeChallengeMethod, state, timeoutMs } = params;
+    const { callbackUrl, codeChallenge, codeChallengeMethod, state, timeoutMs, brokeredAuthorizeUrl, artifactId, targetOrigin, } = params;
     if (!window.parent || window.parent === window) {
         return Promise.reject(new AuthError('No parent window — embedded auth requires an iframe host.', 'NO_PARENT_WINDOW'));
     }
+    // Normal Fabric payload is left byte-for-byte unchanged; the externalEmbed
+    // fields are added only when supplied.
+    const payload = {
+        callbackUrl,
+        codeChallenge,
+        codeChallengeMethod,
+        state,
+    };
+    if (brokeredAuthorizeUrl !== undefined) {
+        payload.brokeredAuthorizeUrl = brokeredAuthorizeUrl;
+    }
+    if (artifactId !== undefined) {
+        payload.artifactId = artifactId;
+    }
     return sendBridgeRequest({
         target: window.parent,
         channel: 'fabric-auth',
         kind: 'auth.requestHandoff',
-        payload: {
-            callbackUrl,
-            codeChallenge,
-            codeChallengeMethod,
-            state,
-        },
+        payload,
         timeoutMs,
+        ...(targetOrigin !== undefined ? { targetOrigin } : {}),
     }).catch((err) => {
         // Re-wrap BridgeError as AuthError for backward compatibility
         if (err instanceof BridgeError) {

package/dist/embeddedFabricLogin.js

@@ -2,6 +2,7 @@ import { generateCodeVerifier, generateCodeChallenge, generateState, } from '@mi
 import { createSessionFromTokenResponse } from '@microsoft/rayfin-auth/_internal';
 import { AuthError, assertBrowser } from '@microsoft/rayfin-lib';
 import { requestHandoff } from './PostMessageAuthTransport.js';
+import { getPinnedParentOrigin, isExternalEmbedScenario, } from './externalEmbedClassification.js';
 import { markEmbeddedHandoffCompleted } from './fabricAuthHelpers.js';
 import { hasFabricUserHint } from './fabricUserHint.js';
 /**
@@ -33,10 +34,15 @@ export async function embeddedFabricLogin(auth, options) {
     if (!options.returnOrigin) {
         throw new AuthError('returnOrigin is required for embedded Fabric authentication.', 'MISSING_RETURN_ORIGIN');
     }
-    if (!hasFabricUserHint()) {
-        // Legacy host: nothing server-side is comparing identities, so fall back to discarding any prior
-        // session before the handoff. Errors are swallowed — the stale token may already be invalid
-        // server-side, and the local clear that signOut performs in its own catch is what matters.
+    // In the acked externalEmbed scenario there is no server-side serve-cookie
+    // identity gate, so a `?_fu=` hint carries no comparison and is ignored: the
+    // SDK always signs out before the handoff. On the normal Fabric path the
+    // hint-gated sign-out below is unchanged.
+    const externalEmbed = isExternalEmbedScenario();
+    if (externalEmbed || !hasFabricUserHint()) {
+        // Discard any prior session before the handoff. Errors are swallowed — the
+        // stale token may already be invalid server-side, and the local clear that
+        // signOut performs in its own catch is what matters.
         try {
             await auth.signOut();
         }
@@ -54,11 +60,26 @@ export async function embeddedFabricLogin(auth, options) {
     // 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.
+    // In the externalEmbed scenario the parent host has no per-app config, so it
+    // is told which endpoint to broker against (`brokeredAuthorizeUrl`, derived
+    // from the SDK's own Fabric capacity URL) and which artifact the token is for
+    // (`artifactId`). The request is also pinned to the parent origin
+    // acknowledged during classification. On the normal Fabric path all three are
+    // omitted and the payload/target are unchanged.
     const result = await requestHandoff({
         callbackUrl: options.returnOrigin,
         codeChallenge,
         codeChallengeMethod: 'S256',
         state,
+        ...(externalEmbed
+            ? {
+                brokeredAuthorizeUrl: auth
+                    .getAuthApi()
+                    .getBrokeredAuthorizeExternalUrl(),
+                artifactId: options.projectId,
+                targetOrigin: getPinnedParentOrigin(),
+            }
+            : {}),
     });
     // Validate state to prevent replay attacks.
     if (result.state !== state) {

package/dist/ensureSignedInWithFabric.d.ts

@@ -12,8 +12,11 @@ import type { FabricAuthOptions } from './types.js';
  * 2. **Refresh token** — if a refresh token is available, attempt `auth.refreshSession()`.
  *    Return the refreshed session on success; continue on failure.
  *    Subject to the same skip.
- * 3. **Embedded mode** — if running inside a Fabric iframe (`fabricEmbedded=true`),
- *    use `embeddedFabricLogin()` to acquire a session via `postMessage` handoff.
+ * 3. **Embedded mode** — if running inside a Fabric iframe (`fabricEmbedded=true`)
+ *    or a third-party portal that acknowledges the externalEmbed classification
+ *    handshake, use `embeddedFabricLogin()` to acquire a session via `postMessage`
+ *    handoff. The externalEmbed scenario is detected from the handshake alone and
+ *    does not require the Fabric `fabricEmbedded` flag.
  * 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

package/dist/ensureSignedInWithFabric.js

@@ -1,5 +1,6 @@
 import { AuthError, assertBrowser } from '@microsoft/rayfin-lib';
 import { embeddedFabricLogin } from './embeddedFabricLogin.js';
+import { classifyExternalEmbed, isExternalEmbedScenario, } from './externalEmbedClassification.js';
 import { hasEmbeddedHandoffCompleted, isEmbeddedMode, tryResumeSession, } from './fabricAuthHelpers.js';
 import { hasFabricUserHint } from './fabricUserHint.js';
 import { initiateFabricLogin } from './initiateFabricLogin.js';
@@ -15,8 +16,11 @@ import { initiateFabricLogin } from './initiateFabricLogin.js';
  * 2. **Refresh token** — if a refresh token is available, attempt `auth.refreshSession()`.
  *    Return the refreshed session on success; continue on failure.
  *    Subject to the same skip.
- * 3. **Embedded mode** — if running inside a Fabric iframe (`fabricEmbedded=true`),
- *    use `embeddedFabricLogin()` to acquire a session via `postMessage` handoff.
+ * 3. **Embedded mode** — if running inside a Fabric iframe (`fabricEmbedded=true`)
+ *    or a third-party portal that acknowledges the externalEmbed classification
+ *    handshake, use `embeddedFabricLogin()` to acquire a session via `postMessage`
+ *    handoff. The externalEmbed scenario is detected from the handshake alone and
+ *    does not require the Fabric `fabricEmbedded` flag.
  * 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
@@ -66,6 +70,19 @@ import { initiateFabricLogin } from './initiateFabricLogin.js';
 export async function ensureSignedInWithFabric(auth, options) {
     assertBrowser('ensureSignedInWithFabric');
     const inEmbeddedMode = isEmbeddedMode(options);
+    // Run the one-shot externalEmbed classification handshake before any resume
+    // decision — and independently of Fabric's `fabricEmbedded` flag. The
+    // handshake self-gates on the presence of a parent frame (no parent → instant
+    // no-op), so a standalone tab pays nothing. A third-party parent that brokers
+    // external Entra acknowledges here; a normal Fabric host does not (the short
+    // timeout then classifies as normal). A successful acknowledgement — not the
+    // Fabric-UX `fabricEmbedded` hint — is what defines the externalEmbed
+    // scenario, so a portal embedding the app need stamp no Fabric-specific flag.
+    await classifyExternalEmbed();
+    const externalEmbed = isExternalEmbedScenario();
+    // The postMessage handoff path applies whenever the app is embedded — either
+    // Fabric embedded mode (`fabricEmbedded`) or a classified externalEmbed parent.
+    const embedded = inEmbeddedMode || externalEmbed;
     // Steps 1-2: existing session or refresh.
     //
     // A host that stamps `?_fu=` has already had its cookie identity-checked by the workload gate
@@ -75,9 +92,13 @@ export async function ensureSignedInWithFabric(auth, options) {
     // A host that stamps no hint is indistinguishable from the pre-feature world: nothing compared the
     // identities, so the persisted session may belong to a previously signed-in Fabric user. There we
     // keep the original behaviour and skip resume until a handoff has run this page load.
-    const skipResume = inEmbeddedMode && !hasFabricUserHint() && !hasEmbeddedHandoffCompleted();
+    //
+    // The externalEmbed scenario always skips resume: there is no serve-cookie identity gate and the
+    // parent brokers a fresh delegated handoff, so any persisted session must be discarded.
+    const skipResume = externalEmbed ||
+        (inEmbeddedMode && !hasFabricUserHint() && !hasEmbeddedHandoffCompleted());
     if (skipResume) {
-        console.debug('[FabricAuth] Embedded host stamped no user hint — skipping session resume to avoid a stale cross-user session');
+        console.debug('[FabricAuth] Skipping session resume (externalEmbed scenario or embedded host stamped no user hint) to avoid reusing a stale session');
     }
     else {
         const resumed = await tryResumeSession(auth);
@@ -86,7 +107,7 @@ export async function ensureSignedInWithFabric(auth, options) {
         }
     }
     // Step 3: Embedded mode — postMessage auth via parent iframe host
-    if (inEmbeddedMode) {
+    if (embedded) {
         console.debug('[FabricAuth] Embedded mode detected, using postMessage auth');
         try {
             await embeddedFabricLogin(auth, options);

package/dist/externalEmbedClassification.d.ts

@@ -0,0 +1,49 @@
+/**
+ * externalEmbed scenario classification.
+ *
+ * In embedded mode a third-party parent page may broker external-Entra
+ * authentication for this app. The app cannot tell such a host apart from the
+ * normal Fabric extension host by inspection, so on load it announces readiness
+ * once and treats a scenario acknowledgement as the classifier.
+ *
+ * The result is held in module state — like the Fabric user hint — so that
+ * every entry point (`ensureSignedInWithFabric`, `initEmbeddedAuth`) triggers
+ * the same one-shot classification and `embeddedFabricLogin` can read it to
+ * decide sign-out and payload shape without re-running the handshake.
+ *
+ * @internal Not exported from the package barrel.
+ */
+/**
+ * Short classification timeout (ms), deliberately distinct from the handoff
+ * request timeout. A normal Fabric host never acknowledges, so this bound is
+ * added to a normal embedded login in full; it is kept small so that path
+ * incurs no material delay. An externalEmbed parent acknowledges synchronously,
+ * well within the bound.
+ */
+export declare const EXTERNAL_EMBED_CLASSIFY_TIMEOUT_MS = 300;
+/**
+ * Runs the one-shot externalEmbed handshake if it has not run this page load.
+ *
+ * Posts a single readiness message to the parent and waits up to
+ * {@link EXTERNAL_EMBED_CLASSIFY_TIMEOUT_MS} for an acknowledgement declaring
+ * the externalEmbed scenario. Idempotent: subsequent calls are no-ops.
+ */
+export declare function classifyExternalEmbed(timeoutMs?: number): Promise<void>;
+/**
+ * Whether the current load was classified as the externalEmbed scenario.
+ * Returns `false` until {@link classifyExternalEmbed} has resolved.
+ */
+export declare function isExternalEmbedScenario(): boolean;
+/**
+ * The parent origin pinned during the handshake, or `undefined` when not in the
+ * externalEmbed scenario. Used as the `postMessage` target for the handoff so
+ * the request goes only to the acknowledged parent.
+ */
+export declare function getPinnedParentOrigin(): string | undefined;
+/**
+ * Resets classification state.
+ *
+ * @internal Test helper.
+ */
+export declare function resetExternalEmbedClassificationForTests(): void;
+//# sourceMappingURL=externalEmbedClassification.d.ts.map

package/dist/externalEmbedClassification.js

@@ -0,0 +1,107 @@
+import { assertBrowser } from '@microsoft/rayfin-lib';
+import { EXTERNAL_EMBED_ACK_KIND, EXTERNAL_EMBED_AUTH_CHANNEL, EXTERNAL_EMBED_READY_KIND, EXTERNAL_EMBED_SCENARIO, } from './externalEmbedProtocol.js';
+/**
+ * externalEmbed scenario classification.
+ *
+ * In embedded mode a third-party parent page may broker external-Entra
+ * authentication for this app. The app cannot tell such a host apart from the
+ * normal Fabric extension host by inspection, so on load it announces readiness
+ * once and treats a scenario acknowledgement as the classifier.
+ *
+ * The result is held in module state — like the Fabric user hint — so that
+ * every entry point (`ensureSignedInWithFabric`, `initEmbeddedAuth`) triggers
+ * the same one-shot classification and `embeddedFabricLogin` can read it to
+ * decide sign-out and payload shape without re-running the handshake.
+ *
+ * @internal Not exported from the package barrel.
+ */
+/**
+ * Short classification timeout (ms), deliberately distinct from the handoff
+ * request timeout. A normal Fabric host never acknowledges, so this bound is
+ * added to a normal embedded login in full; it is kept small so that path
+ * incurs no material delay. An externalEmbed parent acknowledges synchronously,
+ * well within the bound.
+ */
+export const EXTERNAL_EMBED_CLASSIFY_TIMEOUT_MS = 300;
+// `undefined` = not classified yet; `null` = normal Fabric; object = externalEmbed (pinned parent).
+let classification;
+/**
+ * Runs the one-shot externalEmbed handshake if it has not run this page load.
+ *
+ * Posts a single readiness message to the parent and waits up to
+ * {@link EXTERNAL_EMBED_CLASSIFY_TIMEOUT_MS} for an acknowledgement declaring
+ * the externalEmbed scenario. Idempotent: subsequent calls are no-ops.
+ */
+export async function classifyExternalEmbed(timeoutMs = EXTERNAL_EMBED_CLASSIFY_TIMEOUT_MS) {
+    assertBrowser('classifyExternalEmbed');
+    if (classification !== undefined) {
+        return;
+    }
+    const parent = window.parent;
+    if (!parent || parent === window) {
+        classification = null;
+        return;
+    }
+    classification = await new Promise((resolve) => {
+        let settled = false;
+        const requestId = crypto.randomUUID();
+        function finish(result) {
+            if (settled)
+                return;
+            settled = true;
+            window.removeEventListener('message', onMessage);
+            clearTimeout(timer);
+            resolve(result);
+        }
+        function onMessage(event) {
+            const data = event.data;
+            if (!data || typeof data !== 'object')
+                return;
+            if (event.source !== parent)
+                return;
+            if (data.channel !== EXTERNAL_EMBED_AUTH_CHANNEL)
+                return;
+            if (data.kind !== EXTERNAL_EMBED_ACK_KIND)
+                return;
+            if (data.scenario !== EXTERNAL_EMBED_SCENARIO)
+                return;
+            // Pin the parent's origin from the acknowledgement for the later handoff.
+            finish({ source: parent, origin: event.origin });
+        }
+        window.addEventListener('message', onMessage);
+        const timer = setTimeout(() => finish(null), timeoutMs);
+        // The iframe cannot know the parent's origin a priori and the readiness
+        // signal carries no secret, so it is posted with a wildcard target; the
+        // acknowledgement pins the origin for everything that follows.
+        parent.postMessage({
+            channel: EXTERNAL_EMBED_AUTH_CHANNEL,
+            version: 1,
+            kind: EXTERNAL_EMBED_READY_KIND,
+            requestId,
+        }, '*');
+    });
+}
+/**
+ * Whether the current load was classified as the externalEmbed scenario.
+ * Returns `false` until {@link classifyExternalEmbed} has resolved.
+ */
+export function isExternalEmbedScenario() {
+    return Boolean(classification);
+}
+/**
+ * The parent origin pinned during the handshake, or `undefined` when not in the
+ * externalEmbed scenario. Used as the `postMessage` target for the handoff so
+ * the request goes only to the acknowledged parent.
+ */
+export function getPinnedParentOrigin() {
+    return classification ? classification.origin : undefined;
+}
+/**
+ * Resets classification state.
+ *
+ * @internal Test helper.
+ */
+export function resetExternalEmbedClassificationForTests() {
+    classification = undefined;
+}
+//# sourceMappingURL=externalEmbedClassification.js.map

package/dist/externalEmbedProtocol.d.ts

@@ -0,0 +1,9 @@
+/** Bridge channel carrying Fabric brokered-auth messages. */
+export declare const EXTERNAL_EMBED_AUTH_CHANNEL = "fabric-auth";
+/** `kind` of the iframe's one-shot readiness announcement. */
+export declare const EXTERNAL_EMBED_READY_KIND = "externalEmbed.ready";
+/** `kind` of the parent's scenario acknowledgement. */
+export declare const EXTERNAL_EMBED_ACK_KIND = "externalEmbed.ack";
+/** Scenario tag declared by the acknowledgement. */
+export declare const EXTERNAL_EMBED_SCENARIO = "externalEmbed";
+//# sourceMappingURL=externalEmbedProtocol.d.ts.map

package/dist/externalEmbedProtocol.js

@@ -0,0 +1,27 @@
+/*
+ * externalEmbed wire protocol — iframe (embedded app) side.
+ *
+ * These `channel`/`kind`/scenario literals are the wire contract shared with
+ * the parent embed host (`@microsoft/rayfin-embed-host`). They are owned in the
+ * auth layer — the same layer that already owns the `fabric-auth` channel and
+ * the `auth.requestHandoff` kind — rather than in the transport package, which
+ * stays plugin-agnostic (it defines only the generic envelope; callers supply
+ * `channel` and `kind`). The peer package declares the same literals; a
+ * contract test in each package pins them to these canonical values so the two
+ * ends cannot drift.
+ *
+ * Canonical values (see docs/rfc/external-entra-embed-host-sdk.md):
+ *   channel = "fabric-auth", ready = "externalEmbed.ready",
+ *   ack = "externalEmbed.ack", scenario = "externalEmbed".
+ *
+ * @internal Not exported from the package barrel.
+ */
+/** Bridge channel carrying Fabric brokered-auth messages. */
+export const EXTERNAL_EMBED_AUTH_CHANNEL = 'fabric-auth';
+/** `kind` of the iframe's one-shot readiness announcement. */
+export const EXTERNAL_EMBED_READY_KIND = 'externalEmbed.ready';
+/** `kind` of the parent's scenario acknowledgement. */
+export const EXTERNAL_EMBED_ACK_KIND = 'externalEmbed.ack';
+/** Scenario tag declared by the acknowledgement. */
+export const EXTERNAL_EMBED_SCENARIO = 'externalEmbed';
+//# sourceMappingURL=externalEmbedProtocol.js.map

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export type { FabricAuthOptions } from './types.js';
+export type { EntraTokenSignInOptions } from './signInWithEntraToken.js';
+export { signInWithEntraToken } from './signInWithEntraToken.js';
 export { bridgeFabricCallback } from './bridgeFabricCallback.js';
 export { embeddedFabricLogin } from './embeddedFabricLogin.js';
 export { ensureSignedInWithFabric } from './ensureSignedInWithFabric.js';

package/dist/index.js

@@ -1,3 +1,4 @@
+export { signInWithEntraToken } from './signInWithEntraToken.js';
 // Functions
 export { bridgeFabricCallback } from './bridgeFabricCallback.js';
 export { embeddedFabricLogin } from './embeddedFabricLogin.js';

package/dist/initEmbeddedAuth.d.ts

@@ -9,13 +9,17 @@ import type { FabricAuthOptions } from './types.js';
  * new tab.
  *
  * **Behaviour:**
- * - If `fabricEmbedded=true` is **not** in the URL and `options.fabricEmbedded`
- *   is not `true`, returns `null` immediately (no-op).
+ * - Runs the one-shot externalEmbed classification handshake first. If a
+ *   third-party parent acknowledges it, the externalEmbed flow proceeds even
+ *   when the Fabric `fabricEmbedded` flag is absent.
+ * - If neither the handshake is acknowledged **nor** `fabricEmbedded` is set
+ *   (option or `?fabricEmbedded=true`), returns `null` (no-op). A standalone
+ *   page with no parent frame reaches this immediately.
  * - When the host stamps a `?_fu=` hint, runs the standard resume waterfall
  *   (existing session → refresh token → handoff).
- * - When it does not, skips resume on the first call per page load and goes
- *   straight to the handoff, preserving the pre-hint protection against reusing
- *   a previously signed-in Fabric user's session.
+ * - When it does not (or in the externalEmbed scenario), skips resume on the
+ *   first call per page load and goes straight to the handoff, preserving the
+ *   protection against reusing a previously signed-in user's session.
  *
  * Apps that also support the popup flow should continue to call
  * {@link ensureSignedInWithFabric} from a user-gesture handler for the

package/dist/initEmbeddedAuth.js

@@ -1,4 +1,5 @@
 import { embeddedFabricLogin } from './embeddedFabricLogin.js';
+import { classifyExternalEmbed, isExternalEmbedScenario, } from './externalEmbedClassification.js';
 import { hasEmbeddedHandoffCompleted, isEmbeddedMode, tryResumeSession, } from './fabricAuthHelpers.js';
 import { hasFabricUserHint } from './fabricUserHint.js';
 /**
@@ -10,13 +11,17 @@ import { hasFabricUserHint } from './fabricUserHint.js';
  * new tab.
  *
  * **Behaviour:**
- * - If `fabricEmbedded=true` is **not** in the URL and `options.fabricEmbedded`
- *   is not `true`, returns `null` immediately (no-op).
+ * - Runs the one-shot externalEmbed classification handshake first. If a
+ *   third-party parent acknowledges it, the externalEmbed flow proceeds even
+ *   when the Fabric `fabricEmbedded` flag is absent.
+ * - If neither the handshake is acknowledged **nor** `fabricEmbedded` is set
+ *   (option or `?fabricEmbedded=true`), returns `null` (no-op). A standalone
+ *   page with no parent frame reaches this immediately.
  * - When the host stamps a `?_fu=` hint, runs the standard resume waterfall
  *   (existing session → refresh token → handoff).
- * - When it does not, skips resume on the first call per page load and goes
- *   straight to the handoff, preserving the pre-hint protection against reusing
- *   a previously signed-in Fabric user's session.
+ * - When it does not (or in the externalEmbed scenario), skips resume on the
+ *   first call per page load and goes straight to the handoff, preserving the
+ *   protection against reusing a previously signed-in user's session.
  *
  * Apps that also support the popup flow should continue to call
  * {@link ensureSignedInWithFabric} from a user-gesture handler for the
@@ -27,20 +32,32 @@ import { hasFabricUserHint } from './fabricUserHint.js';
  * @returns The authenticated session, or `null` if not in embedded mode.
  */
 export async function initEmbeddedAuth(auth, options) {
-    if (!isEmbeddedMode(options)) {
+    const inEmbeddedMode = isEmbeddedMode(options);
+    // One-shot externalEmbed classification handshake before any resume or
+    // early-return decision. A successful acknowledgement means a third-party
+    // parent is brokering external Entra — detected from the handshake alone,
+    // independently of Fabric's `fabricEmbedded` flag. The handshake self-gates on
+    // a parent frame, so a standalone page is an instant no-op and still returns
+    // `null` below without opening anything.
+    await classifyExternalEmbed();
+    const externalEmbed = isExternalEmbedScenario();
+    // Not embedded by either signal → nothing to do on page load.
+    if (!externalEmbed && !inEmbeddedMode) {
         return null;
     }
     // Steps 1-2: existing session or refresh. Skipped on a legacy host (no `?_fu=` hint) until a
     // handoff has run this page load, because nothing server-side compared the session's identity
-    // against the current Fabric user. See ensureSignedInWithFabric for the full reasoning.
-    if (hasFabricUserHint() || hasEmbeddedHandoffCompleted()) {
+    // against the current Fabric user. The externalEmbed scenario always skips resume — the parent
+    // brokers a fresh delegated handoff. See ensureSignedInWithFabric for the full reasoning.
+    if (!externalEmbed &&
+        (hasFabricUserHint() || hasEmbeddedHandoffCompleted())) {
         const resumed = await tryResumeSession(auth);
         if (resumed) {
             return resumed;
         }
     }
     else {
-        console.debug('[FabricAuth:initEmbedded] Embedded host stamped no user hint — skipping session resume to avoid a stale cross-user session');
+        console.debug('[FabricAuth:initEmbedded] Skipping session resume (externalEmbed scenario or no user hint) to avoid a stale cross-user session');
     }
     // Step 3: postMessage handoff (no popup, no window.open)
     console.debug('[FabricAuth:initEmbedded] Starting postMessage handoff flow');

package/dist/signInWithEntraToken.d.ts

@@ -0,0 +1,28 @@
+import type { Auth, OpaqueSession } from '@microsoft/rayfin-auth';
+/** Options for signing in to a Fabric AppBackend with an existing Entra token. */
+export interface EntraTokenSignInOptions {
+    /** Already-acquired delegated Entra access token, without a Bearer prefix. */
+    entraToken: string;
+}
+/**
+ * Signs in to the AppBackend configured on `auth` using a delegated Entra token.
+ * Works in browsers and Node.js; no popup or iframe is required.
+ *
+ * The configured backend must be an absolute HTTPS workload URL, including its
+ * capacity/workspace/artifact path, not a static-hosting URL. The token is used
+ * only for this request; subsequent refresh uses the Rayfin refresh token.
+ * Success replaces the session on this Auth instance. Failures reject without
+ * returning a prior session. Concurrent calls on the same instance run in call
+ * order, after any active refresh; refresh waits until these calls settle.
+ *
+ * @param auth - The Auth instance used by your SDK clients.
+ * @param options - The already-acquired Entra credential.
+ * @returns The installed session metadata, without access or refresh tokens.
+ * @throws `AuthError` with a stable code and a credential-free message.
+ * @example
+ * ```typescript
+ * const session = await signInWithEntraToken(client.auth, { entraToken });
+ * ```
+ */
+export declare function signInWithEntraToken(auth: Auth, options: EntraTokenSignInOptions): Promise<OpaqueSession>;
+//# sourceMappingURL=signInWithEntraToken.d.ts.map

package/dist/signInWithEntraToken.js

@@ -0,0 +1,165 @@
+import { createSessionFromTokenResponse, getAuthProviderClient, runProviderSignIn, } from '@microsoft/rayfin-auth/_internal';
+import { AuthError } from '@microsoft/rayfin-lib';
+const TOKEN_PATH = '/api/auth/v1/brokered/token';
+function invalidResponse() {
+    return new AuthError('The token exchange returned an invalid token response.', 'INVALID_TOKEN_RESPONSE');
+}
+async function readTokenResponse(response) {
+    try {
+        return await response.json();
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+function validateTokenResponse(value) {
+    if (!value || typeof value !== 'object') {
+        throw invalidResponse();
+    }
+    if (!('accessToken' in value) ||
+        typeof value.accessToken !== 'string' ||
+        !value.accessToken.trim() ||
+        /\s/.test(value.accessToken) ||
+        !('tokenType' in value) ||
+        typeof value.tokenType !== 'string' ||
+        value.tokenType.toLowerCase() !== 'bearer' ||
+        !('expiresIn' in value) ||
+        typeof value.expiresIn !== 'number' ||
+        !Number.isFinite(value.expiresIn) ||
+        value.expiresIn <= 0) {
+        throw invalidResponse();
+    }
+    const now = Date.now();
+    const expiry = new Date(now + value.expiresIn * 1000).getTime();
+    if (!Number.isFinite(expiry) || expiry <= now) {
+        throw invalidResponse();
+    }
+    const refreshToken = 'refreshToken' in value ? value.refreshToken : undefined;
+    const scope = 'scope' in value ? value.scope : undefined;
+    if ((refreshToken != null && typeof refreshToken !== 'string') ||
+        (scope != null && typeof scope !== 'string')) {
+        throw invalidResponse();
+    }
+    return {
+        accessToken: value.accessToken,
+        tokenType: value.tokenType,
+        expiresIn: value.expiresIn,
+        refreshToken,
+        scope,
+    };
+}
+function exchangeError(status) {
+    switch (status) {
+        case 400:
+            return new AuthError('External Entra exchange is not enabled.', 'EXCHANGE_NOT_ENABLED');
+        case 401:
+            return new AuthError('Entra authentication failed.', 'AUTH_FAILED');
+        case 403:
+            return new AuthError('Item Execute permission is required.', 'INSUFFICIENT_PERMISSIONS');
+        case 404:
+            return new AuthError('External Entra exchange is not available.', 'NOT_AVAILABLE');
+        default:
+            return new AuthError('Entra token exchange failed.', 'TOKEN_EXCHANGE_FAILED');
+    }
+}
+function sanitizeSignInFailure(error) {
+    if (error instanceof AuthError) {
+        switch (error.code) {
+            case 'INVALID_TOKEN_RESPONSE':
+                throw invalidResponse();
+            case 'EXCHANGE_NOT_ENABLED':
+                throw exchangeError(400);
+            case 'AUTH_FAILED':
+                throw exchangeError(401);
+            case 'INSUFFICIENT_PERMISSIONS':
+                throw exchangeError(403);
+            case 'NOT_AVAILABLE':
+                throw exchangeError(404);
+        }
+    }
+    // Initialization and custom storage can also fail, outside the HTTP path.
+    throw exchangeError();
+}
+/**
+ * Signs in to the AppBackend configured on `auth` using a delegated Entra token.
+ * Works in browsers and Node.js; no popup or iframe is required.
+ *
+ * The configured backend must be an absolute HTTPS workload URL, including its
+ * capacity/workspace/artifact path, not a static-hosting URL. The token is used
+ * only for this request; subsequent refresh uses the Rayfin refresh token.
+ * Success replaces the session on this Auth instance. Failures reject without
+ * returning a prior session. Concurrent calls on the same instance run in call
+ * order, after any active refresh; refresh waits until these calls settle.
+ *
+ * @param auth - The Auth instance used by your SDK clients.
+ * @param options - The already-acquired Entra credential.
+ * @returns The installed session metadata, without access or refresh tokens.
+ * @throws `AuthError` with a stable code and a credential-free message.
+ * @example
+ * ```typescript
+ * const session = await signInWithEntraToken(client.auth, { entraToken });
+ * ```
+ */
+export async function signInWithEntraToken(auth, options) {
+    const token = options?.entraToken;
+    if (typeof token !== 'string' ||
+        !token ||
+        /\s/.test(token) ||
+        /^bearer$/i.test(token)) {
+        throw new AuthError('A raw Entra access token is required.', 'INVALID_REQUEST');
+    }
+    const client = getAuthProviderClient(auth);
+    const endpoint = client.resolveUrl(TOKEN_PATH);
+    try {
+        const url = new URL(endpoint);
+        if (url.protocol !== 'https:' ||
+            url.username ||
+            url.password ||
+            url.search ||
+            url.hash ||
+            /[\s\\]/.test(endpoint) ||
+            !url.pathname.endsWith(TOKEN_PATH)) {
+            throw new Error();
+        }
+    }
+    catch {
+        throw new AuthError('An absolute HTTPS backend URL is required.', 'INVALID_REQUEST');
+    }
+    return runProviderSignIn(auth, async () => {
+        let result;
+        try {
+            result = await client.requestIsolated(TOKEN_PATH, { Authorization: `Bearer ${token}` }, async (response) => {
+                const rejected = !response.ok || response.redirected;
+                if (rejected) {
+                    // Release unread streams without inspecting credential-bearing
+                    // error bodies. Cancellation failures follow the sanitized
+                    // transport-failure path, while the request timeout is still active.
+                    await response.body?.cancel();
+                }
+                return {
+                    status: response.status,
+                    ok: response.ok,
+                    redirected: response.redirected,
+                    value: rejected ? undefined : await readTokenResponse(response),
+                };
+            });
+        }
+        catch {
+            throw exchangeError();
+        }
+        if (result.redirected) {
+            throw exchangeError();
+        }
+        if (!result.ok) {
+            throw exchangeError(result.status);
+        }
+        const response = validateTokenResponse(result.value);
+        return createSessionFromTokenResponse(auth, response, {
+            persistBeforeCommit: true,
+        });
+    }).catch(sanitizeSignInFailure);
+}
+//# sourceMappingURL=signInWithEntraToken.js.map

package/package.json

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