@microsoft/fabric-embedded-host 1.19.0

package/dist/MessageProtocol.d.ts

@@ -0,0 +1,63 @@
+/**
+ * MessageProtocol — type definitions for the postMessage bridge
+ * between a hosted Rayfin SPA (inside an iframe) and the Fabric
+ * extension host (EmbeddedAppHost).
+ *
+ * All messages flowing through the bridge conform to the
+ * {@link MessageEnvelope} shape, which carries a `channel` for
+ * plugin routing, a monotonic `version`, a `kind` discriminator,
+ * and a `requestId` for response correlation.
+ */
+/**
+ * Base envelope for every message exchanged over the postMessage bridge.
+ *
+ * The iframe sends requests and the host replies with responses that
+ * echo the same `channel`, `version`, and `requestId`.
+ */
+export interface MessageEnvelope {
+    /** Plugin channel identifier (e.g. `"fabric-auth"`). */
+    channel: string;
+    /** Protocol version — currently `1`. */
+    version: number;
+    /** Discriminator for the message type (e.g. `"auth.requestHandoff"`, `"response"`). */
+    kind: string;
+    /** Unique identifier for request/response correlation. */
+    requestId: string;
+}
+/**
+ * Error detail included in an {@link ErrorResponse}.
+ */
+export interface ResponseError {
+    /** Machine-readable error code (e.g. `"UNKNOWN_CHANNEL"`, `"PLUGIN_ERROR"`). */
+    code: string;
+    /** Human-readable error description. */
+    message: string;
+}
+/**
+ * Success response sent from the host back to the iframe.
+ */
+export interface SuccessResponse<T = unknown> extends MessageEnvelope {
+    kind: 'response';
+    success: true;
+    /** Plugin-specific result payload. */
+    result: T;
+}
+/**
+ * Error response sent from the host back to the iframe.
+ */
+export interface ErrorResponse extends MessageEnvelope {
+    kind: 'response';
+    success: false;
+    /** Structured error detail. */
+    error: ResponseError;
+}
+/**
+ * Union of all possible response shapes sent from the host.
+ */
+export type BridgeResponse<T = unknown> = SuccessResponse<T> | ErrorResponse;
+/**
+ * Type guard that validates whether a value conforms to the
+ * {@link MessageEnvelope} shape.
+ */
+export declare function isMessageEnvelope(data: unknown): data is MessageEnvelope;
+//# sourceMappingURL=MessageProtocol.d.ts.map

package/dist/MessageProtocol.js

@@ -0,0 +1,25 @@
+/**
+ * MessageProtocol — type definitions for the postMessage bridge
+ * between a hosted Rayfin SPA (inside an iframe) and the Fabric
+ * extension host (EmbeddedAppHost).
+ *
+ * All messages flowing through the bridge conform to the
+ * {@link MessageEnvelope} shape, which carries a `channel` for
+ * plugin routing, a monotonic `version`, a `kind` discriminator,
+ * and a `requestId` for response correlation.
+ */
+// ── Envelope validation ──────────────────────────────────────
+/**
+ * Type guard that validates whether a value conforms to the
+ * {@link MessageEnvelope} shape.
+ */
+export function isMessageEnvelope(data) {
+    if (typeof data !== 'object' || data === null)
+        return false;
+    const obj = data;
+    return (typeof obj.channel === 'string' &&
+        typeof obj.version === 'number' &&
+        typeof obj.kind === 'string' &&
+        typeof obj.requestId === 'string');
+}
+//# sourceMappingURL=MessageProtocol.js.map

package/dist/embeddedMode.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Embedded-mode detection utilities.
+ *
+ * An app is considered "embedded" when it runs inside a Fabric extension
+ * iframe rather than as a standalone page.  Detection uses a priority
+ * waterfall:
+ *
+ * 1. An explicit `fabricEmbedded` boolean option (highest priority).
+ * 2. A `?fabricEmbedded=true` query parameter in the current URL —
+ *    set by the Fabric Portal when it loads the SPA in an iframe.
+ * 3. A `sessionStorage` flag persisted after step 2, so that
+ *    client-side navigations that strip query params keep working.
+ */
+/**
+ * Options accepted by {@link isEmbeddedMode}.
+ *
+ * Both the Rayfin auth SDK (`FabricAuthOptions`) and the Fabric SDK
+ * can satisfy this interface — only the `fabricEmbedded` flag matters.
+ */
+export interface EmbeddedModeOptions {
+    /**
+     * When `true`, force embedded mode regardless of the URL or
+     * sessionStorage.  When `undefined` or `false`, fall through to
+     * URL / sessionStorage detection.
+     */
+    fabricEmbedded?: boolean;
+}
+/**
+ * Detects whether the app is running in embedded mode.
+ *
+ * Priority:
+ * 1. `options.fabricEmbedded === true` — explicit opt-in.
+ * 2. `?fabricEmbedded=true` in `window.location.search` — set by
+ *    the Fabric Portal; persisted to sessionStorage on first hit.
+ * 3. `sessionStorage` flag from a previous URL detection.
+ *
+ * @returns `true` when the app should use the embedded postMessage
+ *          auth flow instead of the popup/redirect flow.
+ */
+export declare function isEmbeddedMode(options: EmbeddedModeOptions): boolean;
+/**
+ * Clears the persisted embedded-mode flag from sessionStorage.
+ *
+ * Useful in testing or when the app explicitly exits embedded mode.
+ */
+export declare function clearEmbeddedMode(): void;
+//# sourceMappingURL=embeddedMode.d.ts.map

package/dist/embeddedMode.js

@@ -0,0 +1,65 @@
+/**
+ * Embedded-mode detection utilities.
+ *
+ * An app is considered "embedded" when it runs inside a Fabric extension
+ * iframe rather than as a standalone page.  Detection uses a priority
+ * waterfall:
+ *
+ * 1. An explicit `fabricEmbedded` boolean option (highest priority).
+ * 2. A `?fabricEmbedded=true` query parameter in the current URL —
+ *    set by the Fabric Portal when it loads the SPA in an iframe.
+ * 3. A `sessionStorage` flag persisted after step 2, so that
+ *    client-side navigations that strip query params keep working.
+ */
+const EMBEDDED_QUERY_PARAM = 'fabricEmbedded';
+const EMBEDDED_STORAGE_KEY = 'fabricEmbedded';
+/**
+ * Detects whether the app is running in embedded mode.
+ *
+ * Priority:
+ * 1. `options.fabricEmbedded === true` — explicit opt-in.
+ * 2. `?fabricEmbedded=true` in `window.location.search` — set by
+ *    the Fabric Portal; persisted to sessionStorage on first hit.
+ * 3. `sessionStorage` flag from a previous URL detection.
+ *
+ * @returns `true` when the app should use the embedded postMessage
+ *          auth flow instead of the popup/redirect flow.
+ */
+export function isEmbeddedMode(options) {
+    if (options.fabricEmbedded === true) {
+        return true;
+    }
+    if (new URLSearchParams(window.location.search).get(EMBEDDED_QUERY_PARAM) ===
+        'true') {
+        try {
+            sessionStorage.setItem(EMBEDDED_STORAGE_KEY, 'true');
+        }
+        catch {
+            // sessionStorage may be unavailable in sandboxed iframes
+        }
+        return true;
+    }
+    try {
+        if (sessionStorage.getItem(EMBEDDED_STORAGE_KEY) === 'true') {
+            return true;
+        }
+    }
+    catch {
+        // sessionStorage unavailable
+    }
+    return false;
+}
+/**
+ * Clears the persisted embedded-mode flag from sessionStorage.
+ *
+ * Useful in testing or when the app explicitly exits embedded mode.
+ */
+export function clearEmbeddedMode() {
+    try {
+        sessionStorage.removeItem(EMBEDDED_STORAGE_KEY);
+    }
+    catch {
+        // sessionStorage unavailable
+    }
+}
+//# sourceMappingURL=embeddedMode.js.map

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { MessageEnvelope, ResponseError, SuccessResponse, ErrorResponse, BridgeResponse, } from './MessageProtocol';
+export { isMessageEnvelope } from './MessageProtocol';
+export type { EmbeddedModeOptions } from './embeddedMode';
+export { isEmbeddedMode, clearEmbeddedMode } from './embeddedMode';
+export type { BridgeRequestOptions } from './postMessageBridge';
+export { BridgeError, sendBridgeRequest } from './postMessageBridge';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,4 @@
+export { isMessageEnvelope } from './MessageProtocol';
+export { isEmbeddedMode, clearEmbeddedMode } from './embeddedMode';
+export { BridgeError, sendBridgeRequest } from './postMessageBridge';
+//# sourceMappingURL=index.js.map

package/dist/postMessageBridge.d.ts

@@ -0,0 +1,51 @@
+import { SdkError } from '@microsoft/rayfin-lib';
+/**
+ * Options for {@link sendBridgeRequest}.
+ */
+export interface BridgeRequestOptions<TPayload> {
+    /** Target window to post the message to (typically `window.parent`). */
+    target: Window;
+    /** Channel identifier routed by the host's plugin registry. */
+    channel: string;
+    /** Message kind discriminator (e.g. `"auth.requestHandoff"`). */
+    kind: string;
+    /** Arbitrary payload attached to the message envelope. */
+    payload: TPayload;
+    /**
+     * `targetOrigin` passed to `postMessage`.
+     *
+     * When set to a specific origin (e.g. `"https://app.fabric.microsoft.com"`),
+     * the browser restricts delivery to that origin **and** the response handler
+     * validates `event.origin` on incoming messages.
+     *
+     * Defaults to `"*"` — acceptable only when the payload contains no secrets
+     * and the iframe cannot determine `window.parent.origin` at runtime.
+     */
+    targetOrigin?: string;
+    /** Response timeout in milliseconds. Defaults to 30 000. */
+    timeoutMs?: number;
+}
+/**
+ * Error thrown when a bridge request fails or times out.
+ */
+export declare class BridgeError extends SdkError {
+    name: string;
+    constructor(message: string, code?: string);
+}
+/**
+ * Send a request through the postMessage bridge and wait for a
+ * correlated response.
+ *
+ * The function:
+ * 1. Generates a unique `requestId` (UUID v4).
+ * 2. Posts a {@link MessageEnvelope}-shaped message to `target`.
+ * 3. Listens for a response whose `requestId` matches and
+ *    `kind === "response"`.
+ * 4. Resolves with the `result` on success or rejects with a
+ *    {@link BridgeError} on error/timeout.
+ *
+ * @typeParam TPayload  Shape of the request payload.
+ * @typeParam TResult   Shape of the successful response result.
+ */
+export declare function sendBridgeRequest<TPayload, TResult>(options: BridgeRequestOptions<TPayload>): Promise<TResult>;
+//# sourceMappingURL=postMessageBridge.d.ts.map

package/dist/postMessageBridge.js

@@ -0,0 +1,95 @@
+import { SdkError } from '@microsoft/rayfin-lib';
+/**
+ * Default response timeout in milliseconds (30 seconds).
+ */
+const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * Error thrown when a bridge request fails or times out.
+ */
+export class BridgeError extends SdkError {
+    name = 'BridgeError';
+    constructor(message, code) {
+        super(message, code);
+        Object.setPrototypeOf(this, BridgeError.prototype);
+    }
+}
+/**
+ * Send a request through the postMessage bridge and wait for a
+ * correlated response.
+ *
+ * The function:
+ * 1. Generates a unique `requestId` (UUID v4).
+ * 2. Posts a {@link MessageEnvelope}-shaped message to `target`.
+ * 3. Listens for a response whose `requestId` matches and
+ *    `kind === "response"`.
+ * 4. Resolves with the `result` on success or rejects with a
+ *    {@link BridgeError} on error/timeout.
+ *
+ * @typeParam TPayload  Shape of the request payload.
+ * @typeParam TResult   Shape of the successful response result.
+ */
+export function sendBridgeRequest(options) {
+    const { target, channel, kind, payload, targetOrigin = '*', timeoutMs = DEFAULT_TIMEOUT_MS, } = options;
+    if (!target || target === window) {
+        return Promise.reject(new BridgeError('No host window — embedded mode requires an iframe host.', 'NO_HOST_WINDOW'));
+    }
+    const requestId = crypto.randomUUID();
+    const request = {
+        channel,
+        version: 1,
+        kind,
+        requestId,
+        payload,
+    };
+    return new Promise((resolve, reject) => {
+        // eslint-disable-next-line prefer-const -- timeoutId must be declared before cleanup references it
+        let timeoutId;
+        function cleanup() {
+            window.removeEventListener('message', handleResponse);
+            clearTimeout(timeoutId);
+        }
+        function handleResponse(event) {
+            if (!event.data || typeof event.data !== 'object')
+                return;
+            if (event.data.requestId !== requestId)
+                return;
+            if (event.data.kind !== 'response')
+                return;
+            console.debug(`[PostMessageBridge] Response received from origin="${event.origin}", channel="${event.data.channel ?? '?'}"`);
+            // Validate that the response came from the window we sent the
+            // request to (window.parent).  This prevents other iframes or
+            // windows from spoofing correlated responses.
+            if (event.source !== target) {
+                console.warn('[PostMessageBridge] Ignoring response: event.source does not match target window');
+                return;
+            }
+            // When a specific targetOrigin was provided, validate the response
+            // origin to ensure we only accept messages from the expected host.
+            if (targetOrigin !== '*' && event.origin !== targetOrigin) {
+                console.warn(`[PostMessageBridge] Ignoring response from origin="${event.origin}" (expected "${targetOrigin}")`);
+                return;
+            }
+            if (event.data.version !== undefined && event.data.version !== 1) {
+                console.warn(`[PostMessageBridge] Unexpected protocol version: ${event.data.version}`);
+            }
+            cleanup();
+            if (event.data.success === true) {
+                resolve(event.data.result);
+            }
+            else {
+                const error = event.data.error ?? {
+                    code: 'UNKNOWN_ERROR',
+                    message: 'Unknown error from host.',
+                };
+                reject(new BridgeError(error.message, error.code));
+            }
+        }
+        window.addEventListener('message', handleResponse);
+        timeoutId = setTimeout(() => {
+            cleanup();
+            reject(new BridgeError(`Bridge request timed out after ${timeoutMs}ms. The host did not respond.`, 'BRIDGE_TIMEOUT'));
+        }, timeoutMs);
+        target.postMessage(request, targetOrigin);
+    });
+}
+//# sourceMappingURL=postMessageBridge.js.map

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@microsoft/fabric-embedded-host",
+  "version": "1.19.0",
+  "description": "Shared postMessage bridge protocol and embedded mode detection for Rayfin SDKs hosted inside Fabric iframes",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "!dist/**/__tests__/**",
+    "LICENSE"
+  ],
+  "type": "module",
+  "dependencies": {
+    "@microsoft/rayfin-lib": "1.21.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.3",
+    "@vitest/coverage-v8": "~3.2.4",
+    "rimraf": "~6.0.1"
+  },
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com",
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/project-rayfin.git",
+    "directory": "packages/typescript-sdk/fabric-embedded-host"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "build:watch": "tsc --watch",
+    "clean": "rimraf dist && rimraf .tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}