@equinor/fusion-framework-module-msal 7.3.1 → 8.0.0

package/dist/types/MsalConfigurator.d.ts

@@ -133,7 +133,12 @@ export declare class MsalConfigurator extends BaseConfigBuilder<MsalConfig> {
      */
     setLoginHint(loginHint?: string): this;
     /**
-     * @deprecated - since version 5.1.0, use setClient instead
+     * Sets a pre-configured MSAL provider instance directly.
+     *
+     * @deprecated Since version 5.1.0. Use {@link MsalConfigurator.setClient | setClient} instead.
+     *
+     * @param provider - Pre-configured provider instance, or undefined to clear
+     * @returns The configurator instance for method chaining
      */
     setProvider(provider?: IMsalProvider): this;
     /**
@@ -166,7 +171,11 @@ export declare class MsalConfigurator extends BaseConfigBuilder<MsalConfig> {
     setTelemetry(telemetry: ITelemetryProvider | undefined): this;
     /**
      * Sets optional metadata to be included on all MSAL telemetry events.
-     * @deprecated Use setTelemetry({ metadata }) instead
+     *
+     * @deprecated Use {@link MsalConfigurator.setTelemetry | setTelemetry} instead.
+     *
+     * @param metadata - Key-value metadata to attach to telemetry events, or undefined to clear
+     * @returns The configurator instance for method chaining
      */
     setTelemetryMetadata(metadata: Record<string, unknown> | undefined): this;
     /**

package/dist/types/index.d.ts

@@ -1,3 +1,29 @@
+/**
+ * @packageDocumentation
+ *
+ * MSAL authentication module for Fusion Framework.
+ *
+ * Provides Microsoft Authentication Library (MSAL) integration with support for:
+ * - Azure AD / Entra ID authentication (SSO, popup, redirect)
+ * - Automatic token management with silent refresh
+ * - Module hoisting for shared auth state across application scopes
+ * - Backward-compatible v2 proxy layer alongside native MSAL v4/v5 API
+ * - Backend-issued SPA authorization code exchange
+ *
+ * @example
+ * ```typescript
+ * import { enableMSAL } from '@equinor/fusion-framework-module-msal';
+ *
+ * enableMSAL(configurator, (builder) => {
+ *   builder.setClientConfig({
+ *     auth: { clientId: 'your-client-id', tenantId: 'your-tenant-id' },
+ *   });
+ *   builder.setRequiresAuth(true);
+ * });
+ * ```
+ *
+ * @module @equinor/fusion-framework-module-msal
+ */
 export { module, configureMsal, enableMSAL, type MsalModule, type AuthConfigFn, } from './module';
 export type { IMsalProvider } from './MsalProvider.interface';
 export type { IMsalClient } from './MsalClient.interface';

package/dist/types/v2/IAuthClient.interface.d.ts

@@ -1,12 +1,35 @@
 import type { AccountInfo as AccountInfoBase, AuthenticationResult, IPublicClientApplication } from './types';
+/**
+ * Simplified ID token claims used by the v2 compatibility layer.
+ *
+ * @property aud - Token audience (application ID)
+ * @property exp - Token expiration time (seconds since epoch)
+ */
 export type IdTokenClaims = {
     aud: string;
     exp: number;
 };
+/**
+ * Extended account information for v2 compatibility.
+ *
+ * Augments the base v2 `AccountInfo` with typed ID token claims.
+ */
 export type AccountInfo = AccountInfoBase & {
     idTokenClaims?: IdTokenClaims;
 };
+/**
+ * Authentication behavior type for v2-compatible login and token flows.
+ *
+ * - `'popup'` — Opens a popup window for authentication
+ * - `'redirect'` — Navigates the browser to the Microsoft login page
+ */
 export type AuthBehavior = 'popup' | 'redirect';
+/**
+ * Simplified authentication request for v2-compatible methods.
+ *
+ * @property scopes - Optional OAuth scopes to request (e.g. `['User.Read']`)
+ * @property loginHint - Optional username hint to pre-fill the login form
+ */
 export type AuthRequest = {
     scopes?: string[];
     loginHint?: string;

package/dist/types/v2/MsalProvider.interface.d.ts

@@ -7,7 +7,17 @@ import type { IAuthClient } from './IAuthClient.interface';
  *
  * This interface defines the contract for authentication providers that maintain
  * backward compatibility with MSAL v2 API while using MSAL v4 implementation
- * under the hood. This is useful for gradual migration scenarios.
+ * under the hood. Used by the v2 proxy layer during gradual migration scenarios.
+ *
+ * @example
+ * ```typescript
+ * // Obtain a v2 proxy from the current provider
+ * const v2Provider: IMsalProvider = provider.createProxyProvider('2.0.0');
+ *
+ * // Use v2-style API
+ * await v2Provider.login();
+ * const token = await v2Provider.acquireAccessToken({ scopes: ['User.Read'] });
+ * ```
  */
 export interface IMsalProvider {
     /** Current version of the provider (MSAL module version) */

package/dist/types/v2/create-proxy-client.d.ts

@@ -1,22 +1,24 @@
 import type { IMsalClient } from '../MsalClient.interface';
 import type { IAuthClient } from './IAuthClient.interface';
 /**
- * Creates a v2-compatible proxy for MSAL PublicClientApplication.
+ * Creates a v2-compatible proxy wrapper around an MSAL v4 client.
  *
- * This function creates a proxy that wraps the MSAL v4 PublicClientApplication
- * and provides v2-compatible method signatures and return types.
+ * The proxy intercepts property access on the v4 `IMsalClient` and adapts method
+ * signatures, return types, and account data to match the v2 `IAuthClient` interface.
+ * This allows consumer code written against MSAL v2 to continue working unchanged
+ * while the underlying implementation uses MSAL v4/v5.
  *
- * @param client - The MSAL v4 PublicClientApplication instance
- * @returns A proxy client with v2-compatible interface
+ * @param client - The MSAL v4 `IMsalClient` instance to wrap
+ * @returns A proxy implementing the v2-compatible `IAuthClient` interface
  *
  * @example
  * ```typescript
- * const v4Client = new PublicClientApplication(config);
- * const v2Client = createProxyClient_v2(v4Client);
+ * const v4Client = new MsalClient(config);
+ * const v2Client = createProxyClient(v4Client);
  *
  * // Use v2-compatible methods
  * const accounts = v2Client.getAllAccounts();
- * const token = await v2Client.acquireTokenSilent({ scopes: ['User.Read'], account });
+ * const result = await v2Client.acquireTokenSilent({ scopes: ['User.Read'], account });
  * ```
  */
 export declare function createProxyClient(client: IMsalClient): IAuthClient;

package/dist/types/v2/map-account-info.d.ts

@@ -1,9 +1,12 @@
 import type { AccountInfo } from '@azure/msal-browser';
 import type { AccountInfo as AccountInfo_v2 } from './types';
 /**
- * Maps current AccountInfo to v2 AccountInfo format.
+ * Maps a current (v4/v5) `AccountInfo` object to the v2-compatible `AccountInfo` format.
  *
- * @param account - The current AccountInfo to convert
- * @returns The v2 AccountInfo format
+ * Strips properties that don't exist in v2, ensuring backward-compatible serialization
+ * and type safety when passing account data through the v2 proxy layer.
+ *
+ * @param account - The current MSAL v4/v5 `AccountInfo` to convert
+ * @returns A v2-compatible `AccountInfo` containing only fields recognised by MSAL v2 consumers
  */
 export declare function mapAccountInfo(account: AccountInfo): AccountInfo_v2;

package/dist/types/v2/map-authentication-result.d.ts

@@ -1,9 +1,13 @@
 import type { AuthenticationResult } from '@azure/msal-browser';
 import type { AuthenticationResult as AuthenticationResult_v2 } from './types';
 /**
- * Maps current AuthenticationResult to v2 AuthenticationResult format.
+ * Maps a current (v4/v5) `AuthenticationResult` to the v2-compatible format.
  *
- * @param result - The current AuthenticationResult to convert
- * @returns The v2 AuthenticationResult format
+ * Converts the full authentication result — including the nested account object —
+ * to the subset of fields that MSAL v2 consumers expect. This enables the v2 proxy
+ * layer to return type-safe results without exposing v4/v5-only properties.
+ *
+ * @param result - The current MSAL v4/v5 `AuthenticationResult` to convert
+ * @returns A v2-compatible `AuthenticationResult` with mapped account and token fields
  */
 export declare function mapAuthenticationResult(result: AuthenticationResult): AuthenticationResult_v2;

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "7.3.1";
+export declare const version = "8.0.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-msal",
-  "version": "7.3.1",
+  "version": "8.0.0",
   "description": "Microsoft Authentication Library (MSAL) integration module for Fusion Framework",
   "main": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",
@@ -46,20 +46,20 @@
     "@azure/msal-browser": "^5.0.2"
   },
   "devDependencies": {
-    "@types/semver": "^7.5.0",
-    "semver": "^7.5.4",
-    "typescript": "^5.8.2",
-    "zod": "^4.1.8",
-    "@equinor/fusion-framework-module": "^5.0.6",
-    "@equinor/fusion-framework-module-telemetry": "^4.6.4"
+    "@types/semver": "^7.7.1",
+    "semver": "^7.7.4",
+    "typescript": "^5.9.3",
+    "zod": "^4.3.6",
+    "@equinor/fusion-framework-module": "^6.0.0",
+    "@equinor/fusion-framework-module-telemetry": "^5.0.0"
   },
   "peerDependencies": {
-    "@types/semver": "^7.5.0",
-    "semver": "^7.5.4",
-    "typescript": "^5.8.2",
-    "zod": "^4.1.8",
-    "@equinor/fusion-framework-module": "^5.0.6",
-    "@equinor/fusion-framework-module-telemetry": "^4.6.4"
+    "@types/semver": "^7.0.0",
+    "semver": "^7.0.0",
+    "typescript": "^5.0.0",
+    "zod": "^4.0.0",
+    "@equinor/fusion-framework-module": "^6.0.0",
+    "@equinor/fusion-framework-module-telemetry": "^5.0.0"
   },
   "peerDependenciesMeta": {
     "@equinor/fusion-framework-module-telemetry": {

package/src/MsalConfigurator.ts

@@ -206,7 +206,12 @@ export class MsalConfigurator extends BaseConfigBuilder<MsalConfig> {
   }
 
   /**
-   * @deprecated - since version 5.1.0, use setClient instead
+   * Sets a pre-configured MSAL provider instance directly.
+   *
+   * @deprecated Since version 5.1.0. Use {@link MsalConfigurator.setClient | setClient} instead.
+   *
+   * @param provider - Pre-configured provider instance, or undefined to clear
+   * @returns The configurator instance for method chaining
    */
   setProvider(provider?: IMsalProvider): this {
     this._set('provider', async () => provider);
@@ -251,7 +256,11 @@ export class MsalConfigurator extends BaseConfigBuilder<MsalConfig> {
 
   /**
    * Sets optional metadata to be included on all MSAL telemetry events.
-   * @deprecated Use setTelemetry({ metadata }) instead
+   *
+   * @deprecated Use {@link MsalConfigurator.setTelemetry | setTelemetry} instead.
+   *
+   * @param metadata - Key-value metadata to attach to telemetry events, or undefined to clear
+   * @returns The configurator instance for method chaining
    */
   setTelemetryMetadata(metadata: Record<string, unknown> | undefined): this {
     this._set('telemetry.metadata', async () => metadata);

package/src/MsalProvider.ts

@@ -177,6 +177,20 @@ export class MsalProvider extends BaseModuleProvider<MsalConfig> implements IMsa
    * Apps should call acquireToken with actual scopes after initialization completes.
    */
   async initialize(): Promise<void> {
+    // Guard: skip authentication when running inside MSAL's hidden iframe.
+    // MSAL uses a hidden iframe for silent token renewal (acquireTokenSilent).
+    // The iframe loads the app URL, which would re-initialize MSAL and attempt
+    // loginRedirect(), causing the "block_iframe_reload" error.  Detect this
+    // by checking if we're in an iframe and the URL contains MSAL's hash params.
+    if (typeof window !== 'undefined' && window !== window.parent) {
+      // Running inside an iframe — let the parent handle authentication.
+      // Still initialize the client so handleRedirectPromise can process
+      // the auth response and post it back to the parent frame.
+      await this.#client.initialize();
+      await this.#client.handleRedirectPromise();
+      return;
+    }
+
     const measurement = this._trackMeasurement('initialize', TelemetryLevel.Debug);
     // Initialize the underlying MSAL client first
     await this.#client.initialize();
@@ -320,11 +334,16 @@ export class MsalProvider extends BaseModuleProvider<MsalConfig> implements IMsa
   async acquireToken(
     options?: AcquireTokenOptions | AcquireTokenOptionsLegacy,
   ): Promise<AcquireTokenResult> {
+    // Guard: when running inside MSAL's hidden iframe, only attempt silent
+    // acquisition.  Interactive flows (redirect/popup) must never be triggered
+    // from an iframe — MSAL will throw "block_iframe_reload".
+    const inIframe = typeof window !== 'undefined' && window !== window.parent;
+
     // Determine behavior and silent options, with defaults (redirect and true respectively)
-    const behavior = options?.behavior ?? 'redirect';
+    const behavior = inIframe ? 'redirect' : (options?.behavior ?? 'redirect');
 
-    // Silent mode defaults to true, meaning the provider will attempt silent token acquisition first
-    const silent = options?.silent ?? true;
+    // When in an iframe, force silent-only to prevent interactive fallback
+    const silent = inIframe ? true : (options?.silent ?? true);
 
     const defaultScopes = this.defaultScopes;
 
@@ -383,6 +402,15 @@ export class MsalProvider extends BaseModuleProvider<MsalConfig> implements IMsa
       measurement?.measure();
       return result;
     } catch (error) {
+      // Inside MSAL's hidden iframe, silent acquisition may fail and the client
+      // would fall back to acquireTokenRedirect which throws "block_iframe_reload".
+      // Suppress this — the parent frame handles interactive auth.
+      if (inIframe) {
+        this._trackEvent('acquireToken.suppressed-in-iframe', TelemetryLevel.Debug, {
+          properties: telemetryProperties,
+        });
+        return undefined;
+      }
       this._trackException('acquireToken-failed', TelemetryLevel.Error, {
         exception: error as Error,
         properties: telemetryProperties,
@@ -439,6 +467,11 @@ export class MsalProvider extends BaseModuleProvider<MsalConfig> implements IMsa
    * ```
    */
   async login(options: LoginOptions): Promise<LoginResult> {
+    // Guard: never attempt interactive login inside MSAL's hidden iframe.
+    if (typeof window !== 'undefined' && window !== window.parent) {
+      return undefined;
+    }
+
     const { behavior = 'redirect', silent = true, request } = options;
 
     request.loginHint ??=

package/src/index.ts

@@ -1,3 +1,30 @@
+/**
+ * @packageDocumentation
+ *
+ * MSAL authentication module for Fusion Framework.
+ *
+ * Provides Microsoft Authentication Library (MSAL) integration with support for:
+ * - Azure AD / Entra ID authentication (SSO, popup, redirect)
+ * - Automatic token management with silent refresh
+ * - Module hoisting for shared auth state across application scopes
+ * - Backward-compatible v2 proxy layer alongside native MSAL v4/v5 API
+ * - Backend-issued SPA authorization code exchange
+ *
+ * @example
+ * ```typescript
+ * import { enableMSAL } from '@equinor/fusion-framework-module-msal';
+ *
+ * enableMSAL(configurator, (builder) => {
+ *   builder.setClientConfig({
+ *     auth: { clientId: 'your-client-id', tenantId: 'your-tenant-id' },
+ *   });
+ *   builder.setRequiresAuth(true);
+ * });
+ * ```
+ *
+ * @module @equinor/fusion-framework-module-msal
+ */
+
 export {
   module,
   configureMsal,

package/src/util/compare-origin.ts

@@ -1,9 +1,16 @@
 import { normalizeUri } from './normalize-uri';
 
 /**
- * Compares normalized version of urls
+ * Compares two URIs after normalizing them to their canonical form.
+ *
+ * Both values are passed through {@link normalizeUri} before comparison, so relative
+ * paths, double slashes, and trailing slashes are handled transparently.
  *
  * @internal
+ *
+ * @param a - First URI or relative path
+ * @param b - Second URI or relative path
+ * @returns `true` when both URIs resolve to the same normalized string
  */
 export const compareOrigin = (a: string, b: string): boolean => {
   const url = { a: normalizeUri(a), b: normalizeUri(b) };

package/src/util/normalize-uri.ts

@@ -1,11 +1,21 @@
 /**
- * Creates and normalizes redirect uri.
- * Strips double and trailing slashes
+ * Creates and normalizes a redirect URI.
+ *
+ * Resolves relative paths against the provided base URL and strips double and trailing slashes
+ * from the resulting pathname. Used internally to sanitize redirect URIs before passing them
+ * to MSAL authentication flows.
  *
  * @internal
  *
- * @param uri - relative path or full url
- * @param home - base url for relative urls
+ * @param uri - Relative path (e.g. `/callback`) or absolute URL (e.g. `https://app.com/callback`)
+ * @param home - Base URL for resolving relative paths. Defaults to `window.location.origin`.
+ * @returns Fully-qualified, normalized URI string
+ *
+ * @example
+ * ```typescript
+ * normalizeUri('/callback');                  // https://current-origin.com/callback
+ * normalizeUri('https://app.com//callback/'); // https://app.com/callback
+ * ```
  */
 export const normalizeUri = (uri: string, home: string = window.location.origin): string => {
   uri = uri.match(/^http[s]?/) ? uri : home + uri;

package/src/util/redirect.ts

@@ -1,12 +1,17 @@
 /**
- * Redirects browser to provided location
- * If not redirected by provided timeout, promise is rejected
+ * Redirects the browser to the specified URL.
+ *
+ * If the browser has not navigated away within the given timeout, the returned
+ * promise is rejected. This acts as a safeguard against redirect failures.
  *
  * @internal
  *
- * @param url - endpoint to navigate to
- * @param timeout - max wait before redirect
- * @param history - append navigation to history
+ * @param url - Endpoint to navigate to
+ * @param timeout - Maximum milliseconds to wait before considering the redirect failed. Defaults to `3000`.
+ * @param history - When `true`, uses `location.assign()` so the current page is kept in browser history.
+ *   Otherwise uses `location.replace()` which replaces the current history entry.
+ * @returns A promise that rejects after the timeout (it never resolves because a successful redirect
+ *   causes the page to unload)
  */
 export const redirect = (url: string, timeout = 3000, history?: boolean): Promise<void> => {
   history ? window.location.assign(url) : window.location.replace(url);

package/src/v2/IAuthClient.interface.ts

@@ -4,17 +4,40 @@ import type {
   IPublicClientApplication,
 } from './types';
 
+/**
+ * Simplified ID token claims used by the v2 compatibility layer.
+ *
+ * @property aud - Token audience (application ID)
+ * @property exp - Token expiration time (seconds since epoch)
+ */
 export type IdTokenClaims = {
   aud: string;
   exp: number;
 };
 
+/**
+ * Extended account information for v2 compatibility.
+ *
+ * Augments the base v2 `AccountInfo` with typed ID token claims.
+ */
 export type AccountInfo = AccountInfoBase & {
   idTokenClaims?: IdTokenClaims;
 };
 
+/**
+ * Authentication behavior type for v2-compatible login and token flows.
+ *
+ * - `'popup'` — Opens a popup window for authentication
+ * - `'redirect'` — Navigates the browser to the Microsoft login page
+ */
 export type AuthBehavior = 'popup' | 'redirect';
 
+/**
+ * Simplified authentication request for v2-compatible methods.
+ *
+ * @property scopes - Optional OAuth scopes to request (e.g. `['User.Read']`)
+ * @property loginHint - Optional username hint to pre-fill the login form
+ */
 export type AuthRequest = {
   scopes?: string[];
   loginHint?: string;

package/src/v2/MsalProvider.interface.ts

@@ -8,7 +8,17 @@ import type { IAuthClient } from './IAuthClient.interface';
  *
  * This interface defines the contract for authentication providers that maintain
  * backward compatibility with MSAL v2 API while using MSAL v4 implementation
- * under the hood. This is useful for gradual migration scenarios.
+ * under the hood. Used by the v2 proxy layer during gradual migration scenarios.
+ *
+ * @example
+ * ```typescript
+ * // Obtain a v2 proxy from the current provider
+ * const v2Provider: IMsalProvider = provider.createProxyProvider('2.0.0');
+ *
+ * // Use v2-style API
+ * await v2Provider.login();
+ * const token = await v2Provider.acquireAccessToken({ scopes: ['User.Read'] });
+ * ```
  */
 export interface IMsalProvider {
   /** Current version of the provider (MSAL module version) */

package/src/v2/create-proxy-client.ts

@@ -5,22 +5,24 @@ import { mapAuthenticationResult } from './map-authentication-result';
 import type { AccountInfo } from './types';
 
 /**
- * Creates a v2-compatible proxy for MSAL PublicClientApplication.
+ * Creates a v2-compatible proxy wrapper around an MSAL v4 client.
  *
- * This function creates a proxy that wraps the MSAL v4 PublicClientApplication
- * and provides v2-compatible method signatures and return types.
+ * The proxy intercepts property access on the v4 `IMsalClient` and adapts method
+ * signatures, return types, and account data to match the v2 `IAuthClient` interface.
+ * This allows consumer code written against MSAL v2 to continue working unchanged
+ * while the underlying implementation uses MSAL v4/v5.
  *
- * @param client - The MSAL v4 PublicClientApplication instance
- * @returns A proxy client with v2-compatible interface
+ * @param client - The MSAL v4 `IMsalClient` instance to wrap
+ * @returns A proxy implementing the v2-compatible `IAuthClient` interface
  *
  * @example
  * ```typescript
- * const v4Client = new PublicClientApplication(config);
- * const v2Client = createProxyClient_v2(v4Client);
+ * const v4Client = new MsalClient(config);
+ * const v2Client = createProxyClient(v4Client);
  *
  * // Use v2-compatible methods
  * const accounts = v2Client.getAllAccounts();
- * const token = await v2Client.acquireTokenSilent({ scopes: ['User.Read'], account });
+ * const result = await v2Client.acquireTokenSilent({ scopes: ['User.Read'], account });
  * ```
  */
 export function createProxyClient(client: IMsalClient): IAuthClient {

package/src/v2/map-account-info.ts

@@ -2,10 +2,13 @@ import type { AccountInfo } from '@azure/msal-browser';
 import type { AccountInfo as AccountInfo_v2 } from './types';
 
 /**
- * Maps current AccountInfo to v2 AccountInfo format.
+ * Maps a current (v4/v5) `AccountInfo` object to the v2-compatible `AccountInfo` format.
  *
- * @param account - The current AccountInfo to convert
- * @returns The v2 AccountInfo format
+ * Strips properties that don't exist in v2, ensuring backward-compatible serialization
+ * and type safety when passing account data through the v2 proxy layer.
+ *
+ * @param account - The current MSAL v4/v5 `AccountInfo` to convert
+ * @returns A v2-compatible `AccountInfo` containing only fields recognised by MSAL v2 consumers
  */
 export function mapAccountInfo(account: AccountInfo): AccountInfo_v2 {
   return {

package/src/v2/map-authentication-result.ts

@@ -3,10 +3,14 @@ import type { AuthenticationResult as AuthenticationResult_v2 } from './types';
 import { mapAccountInfo } from './map-account-info';
 
 /**
- * Maps current AuthenticationResult to v2 AuthenticationResult format.
+ * Maps a current (v4/v5) `AuthenticationResult` to the v2-compatible format.
  *
- * @param result - The current AuthenticationResult to convert
- * @returns The v2 AuthenticationResult format
+ * Converts the full authentication result — including the nested account object —
+ * to the subset of fields that MSAL v2 consumers expect. This enables the v2 proxy
+ * layer to return type-safe results without exposing v4/v5-only properties.
+ *
+ * @param result - The current MSAL v4/v5 `AuthenticationResult` to convert
+ * @returns A v2-compatible `AuthenticationResult` with mapped account and token fields
  */
 export function mapAuthenticationResult(result: AuthenticationResult): AuthenticationResult_v2 {
   return {

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '7.3.1';
+export const version = '8.0.0';