@equinor/fusion-framework-module-msal 5.1.1 → 6.0.0-next.0

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

@@ -0,0 +1,24 @@
+import type { IMsalProvider } from '../MsalProvider.interface';
+import type { IMsalProvider as IMsalProvider_v2 } from './MsalProvider.interface';
+/**
+ * Creates a proxy provider for MSAL v2 compatibility.
+ *
+ * This function creates a Proxy that wraps the MSAL v4 provider and provides
+ * v2-compatible method signatures and return types while using the latest
+ * MSAL v4 implementation under the hood. The proxy handles type conversions
+ * and method adaptations to maintain backward compatibility.
+ *
+ * @param provider - The base MSAL v4 provider instance to wrap
+ * @returns A proxy provider implementing the v2-compatible interface
+ *
+ * @example
+ * ```typescript
+ * const baseProvider = new MsalProvider(config);
+ * const v2Proxy = createProxyProvider(baseProvider);
+ *
+ * // Use v2-compatible API
+ * await v2Proxy.login();
+ * const token = await v2Proxy.acquireAccessToken({ scopes: ['User.Read'] });
+ * ```
+ */
+export declare function createProxyProvider(provider: IMsalProvider): IMsalProvider_v2;

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

@@ -0,0 +1,9 @@
+import type { AccountInfo } from '@azure/msal-browser';
+import type { AccountInfo as AccountInfo_v2 } from './types';
+/**
+ * Maps current AccountInfo to v2 AccountInfo format.
+ *
+ * @param account - The current AccountInfo to convert
+ * @returns The v2 AccountInfo format
+ */
+export declare function mapAccountInfo(account: AccountInfo): AccountInfo_v2;

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

@@ -0,0 +1,9 @@
+import type { AuthenticationResult } from '@azure/msal-browser';
+import type { AuthenticationResult as AuthenticationResult_v2 } from './types';
+/**
+ * Maps current AuthenticationResult to v2 AuthenticationResult format.
+ *
+ * @param result - The current AuthenticationResult to convert
+ * @returns The v2 AuthenticationResult format
+ */
+export declare function mapAuthenticationResult(result: AuthenticationResult): AuthenticationResult_v2;

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

@@ -1,3 +1,9 @@
+/**
+ * MSAL v2 compatible AccountInfo type.
+ *
+ * This type represents account information in MSAL v2 format
+ * to maintain backward compatibility while using MSAL v4 implementation.
+ */
 export type AccountInfo = {
     homeAccountId: string;
     environment: string;
@@ -9,6 +15,12 @@ export type AccountInfo = {
         [key: string]: string | number | string[] | object | undefined | unknown;
     };
 };
+/**
+ * MSAL v2 compatible AuthenticationResult type.
+ *
+ * This type represents authentication results in MSAL v2 format
+ * to maintain backward compatibility while using MSAL v4 implementation.
+ */
 export type AuthenticationResult = {
     authority: string;
     uniqueId: string;

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "5.1.1";
+export declare const version = "6.0.0-next.0";

package/dist/types/versioning/resolve-version.d.ts

@@ -1,4 +1,4 @@
-import { type SemVer } from 'semver';
+import { SemVer } from 'semver';
 import type { ResolvedVersion } from './types';
 /**
  * Resolves and validates a version string against the latest available MSAL version.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-msal",
-  "version": "5.1.1",
+  "version": "6.0.0-next.0",
   "description": "Microsoft Authentication Library (MSAL) integration module for Fusion Framework",
   "main": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",
@@ -36,14 +36,19 @@
     "directory": "packages/modules/msal"
   },
   "dependencies": {
-    "@azure/msal-browser": "^2.21.0",
-    "@types/semver": "^7.5.0",
+    "@azure/msal-browser": "^4.25.0",
     "semver": "^7.5.4",
-    "zod": "^4.1.8",
-    "@equinor/fusion-framework-module": "^5.0.4"
+    "zod": "^4.1.8"
   },
   "devDependencies": {
-    "typescript": "^5.8.2"
+    "@types/semver": "^7.5.0",
+    "typescript": "^5.8.2",
+    "@equinor/fusion-framework-module": "^5.0.5",
+    "@equinor/fusion-framework-module-telemetry": "4.4.0-next.0"
+  },
+  "peerDependencies": {
+    "@equinor/fusion-framework-module-telemetry": "^4.4.0-next.0",
+    "@equinor/fusion-framework-module": "^5.0.5"
   },
   "scripts": {
     "build": "tsc -b",

package/src/MsalClient.interface.ts

@@ -0,0 +1,121 @@
+import type {
+  IPublicClientApplication,
+  AccountInfo,
+  AuthenticationResult,
+  PopupRequest,
+  RedirectRequest,
+} from '@azure/msal-browser';
+
+/**
+ * Authentication behavior type determining the interaction method.
+ *
+ * - 'popup': Opens authentication in a popup window (returns result immediately)
+ * - 'redirect': Navigates browser to authentication page (returns void, result via handleRedirectPromise)
+ */
+export type AuthBehavior = 'popup' | 'redirect';
+
+/**
+ * Options for acquiring an access token.
+ *
+ * This type ensures either the legacy or modern approach is used by requiring
+ * the request parameter while allowing optional configuration for behavior and silent mode.
+ *
+ * @property request - MSAL request object for popup or redirect authentication
+ * @property behavior - Optional authentication method (popup or redirect). Defaults to 'redirect'
+ * @property silent - Optional flag to attempt silent token acquisition first. Defaults to true if account is available
+ */
+export type AcquireTokenOptions = {
+  request: PopupRequest | RedirectRequest;
+  behavior?: AuthBehavior;
+  silent?: boolean;
+};
+
+/**
+ * Result type for token acquisition operations.
+ *
+ * Returns the authentication result on success, or null/undefined on failure or redirect.
+ * For redirect flows, returns undefined (void) because browser navigation interrupts execution.
+ */
+export type AcquireTokenResult = AuthenticationResult | null | undefined;
+
+/**
+ * Options for user login/authentication.
+ *
+ * @property request - MSAL request object for popup or redirect authentication
+ * @property behavior - Optional authentication method (popup or redirect). Defaults to 'redirect'
+ * @property silent - Optional flag to attempt silent SSO authentication first. Defaults to true
+ */
+export type LoginOptions = {
+  request: PopupRequest | RedirectRequest;
+  behavior?: AuthBehavior;
+  silent?: boolean;
+};
+
+/**
+ * Options for user logout.
+ *
+ * @property redirectUri - Optional URI to redirect to after logout completes
+ * @property account - Optional account to log out (defaults to active account if not provided)
+ */
+export type LogoutOptions = {
+  redirectUri?: string;
+  account?: AccountInfo;
+};
+
+/**
+ * Result type for login operations.
+ *
+ * Returns the authentication result on success, or undefined on redirect-based flows
+ * (where the browser navigates away). For redirect flows, result is available via handleRedirectPromise.
+ */
+export type LoginResult = AuthenticationResult | undefined;
+
+/**
+ * Interface for MSAL v4 client with additional properties and methods.
+ *
+ * This interface extends the standard MSAL v4 PublicClientApplication
+ * with additional properties and methods needed for the framework.
+ *
+ * @example
+ * ```typescript
+ * const client: IMsalClient = new MsalClient(config);
+ *
+ * // Access additional properties
+ * const tenantId = client.tenantId;
+ * const hasValidClaims = client.hasValidClaims;
+ *
+ * // Use enhanced methods
+ * const result = await client.login({ request: { scopes: ['User.Read'] } });
+ * ```
+ */
+export interface IMsalClient extends IPublicClientApplication {
+  /** Configured client ID */
+  clientId: string | undefined;
+
+  /** Tenant ID for the client domain */
+  tenantId: string | undefined;
+
+  /** Check if the current account has valid claims */
+  hasValidClaims: boolean;
+
+  /**
+   * Login user with enhanced options
+   * @param options - Login configuration options
+   * @returns Promise resolving to authentication result or undefined
+   */
+  login(options: LoginOptions): Promise<LoginResult>;
+
+  /**
+   * Logout user with enhanced options
+   * @param options - Logout configuration options
+   * @returns Promise resolving to void
+   */
+  logout(options: LogoutOptions): Promise<void>;
+
+  /**
+   * Acquire access token with enhanced options
+   * @param options - Token acquisition configuration options
+   * @returns Promise resolving to authentication result or null/undefined
+   */
+  acquireToken(options: AcquireTokenOptions): Promise<AcquireTokenResult>;
+}

package/src/MsalClient.ts

@@ -0,0 +1,274 @@
+import {
+  PublicClientApplication,
+  type SilentRequest,
+  type Configuration,
+  type EndSessionRequest,
+  type PopupRequest,
+  type RedirectRequest,
+} from '@azure/msal-browser';
+
+import type {
+  IMsalClient,
+  AcquireTokenResult,
+  LoginOptions,
+  LogoutOptions,
+  LoginResult,
+  AcquireTokenOptions,
+} from './MsalClient.interface';
+
+export type { IMsalClient };
+
+/**
+ * MSAL client configuration extending the standard MSAL Configuration.
+ *
+ * This type adds tenant-specific configuration options while maintaining
+ * full compatibility with the base MSAL Configuration type.
+ *
+ * @remarks
+ * The `tenantId` in the auth configuration is optional but recommended for
+ * multi-tenant applications. When provided, it's used for better tenant isolation
+ * and can be accessed via the client's `tenantId` property.
+ */
+export type MsalClientConfig = Configuration & {
+  auth: {
+    /** Optional tenant identifier for Azure AD tenant */
+    tenantId?: string;
+  };
+};
+
+/**
+ * MSAL v4 client implementation with extended properties and methods.
+ *
+ * This class extends the standard MSAL PublicClientApplication to provide
+ * additional properties (tenantId, clientId, hasValidClaims) and enhanced
+ * authentication methods with better options for behavior and silent flows.
+ *
+ * @example
+ * ```typescript
+ * const config: MsalClientConfig = {
+ *   auth: {
+ *     clientId: 'your-client-id',
+ *     authority: 'https://login.microsoftonline.com/your-tenant-id',
+ *     tenantId: 'your-tenant-id'
+ *   }
+ * };
+ * const client = new MsalClient(config);
+ * await client.initialize();
+ * ```
+ */
+export class MsalClient extends PublicClientApplication implements IMsalClient {
+  #tenantId?: string;
+  #clientId?: string;
+
+  /**
+   * Creates a new MSAL client instance.
+   *
+   * @param config - MSAL client configuration including auth settings
+   */
+  constructor(config: MsalClientConfig) {
+    super(config);
+    this.#tenantId = config.auth?.tenantId;
+    this.#clientId = config.auth?.clientId;
+  }
+
+  /**
+   * Tenant identifier for the configured Azure AD tenant.
+   *
+   * @returns The tenant ID string if configured, undefined otherwise
+   */
+  get tenantId(): string | undefined {
+    return this.#tenantId;
+  }
+
+  /**
+   * Client identifier (application ID) for the configured Azure AD application.
+   *
+   * @returns The client ID string if configured, undefined otherwise
+   */
+  get clientId(): string | undefined {
+    return this.#clientId;
+  }
+
+  /**
+   * Checks if the currently active account has valid ID token claims.
+   *
+   * This property validates that the ID token's expiration claim (exp) is in the future,
+   * indicating the account is still authenticated and the session is valid.
+   *
+   * @returns True if the account has unexpired token claims, false otherwise
+   */
+  get hasValidClaims(): boolean {
+    const idTokenClaims = this.getActiveAccount()?.idTokenClaims;
+    // Compare token expiration time (seconds since epoch) with current time
+    return Number(idTokenClaims?.exp) > Number(Math.ceil(Date.now() / 1000));
+  }
+
+  /**
+   * Authenticates user with support for silent SSO, popup, and redirect flows.
+   *
+   * @param options - Login configuration with request, behavior, and silent flag
+   * @returns Promise resolving to authentication result
+   *
+   * @remarks
+   * Authentication flow priority:
+   * 1. Silent SSO (if enabled and account/loginHint provided)
+   * 2. Interactive method based on behavior (popup or redirect)
+   *
+   * **Behavior differences:**
+   * - **Popup**: Opens authentication popup window and returns authentication result immediately
+   * - **Redirect**: Navigates browser to Microsoft login page. Returns `void` because the browser
+   *   navigates to a new page. After redirect completes, the result will be available via
+   *   `handleRedirectPromise()` when the app loads on the new page.
+   */
+  async login(options: Required<LoginOptions>): Promise<LoginResult> {
+    // Attempt silent authentication first if enabled
+    // This provides better UX by avoiding unnecessary popups/redirects
+    if (options.silent) {
+      if (!options.request.account && !options.request.loginHint) {
+        this.getLogger().warning(
+          'No account or login hint provided, please provide an account or login hint in the request',
+        );
+      }
+      try {
+        return await this.ssoSilent(options.request as SilentRequest);
+      } catch {
+        // Silent login failed - continue to interactive flow
+        this.getLogger().warning('Silent login failed, falling back to interactive');
+      }
+    }
+
+    // Perform interactive authentication based on specified behavior
+    switch (options.behavior) {
+      case 'popup':
+        // Popup flow - returns result immediately after user completes authentication
+        return await this.loginPopup(options.request as PopupRequest);
+      case 'redirect':
+        // Redirect flow - browser navigates to Microsoft login page
+        // Returns void because browser navigation interrupts execution on current page
+        // Result will be available via handleRedirectPromise() after app loads on new page
+        await this.loginRedirect(options.request as RedirectRequest);
+        break;
+      default:
+        throw new Error(
+          `Invalid behavior provided: ${options.behavior}, please provide a valid behavior, see options.behavior for more information.`,
+        );
+    }
+  }
+
+  /**
+   * Logs out the current user and clears authentication state.
+   *
+   * This method initiates a logout flow using the redirect mechanism, which navigates
+   * the user to the Microsoft logout endpoint to clear session cookies and tokens.
+   *
+   * @param options - Logout configuration options
+   * @param options.account - Account to log out (defaults to active account if not provided)
+   * @param options.redirectUri - URI to redirect to after logout completes
+   * @returns Promise that resolves when logout redirect is initiated
+   *
+   * @remarks
+   * - This method always uses redirect flow for logout (more reliable than popup)
+   * - **Returns `void`**: The browser navigates to Microsoft's logout page, which interrupts
+   *   execution on the current page. This is expected behavior for redirect-based logout.
+   * - If no account is provided, uses the currently active account
+   * - After redirect, user will be logged out at Microsoft's identity provider
+   * - Application state and local tokens are cleared during this process
+   *
+   * @example
+   * ```typescript
+   * // Basic logout with active account
+   * await client.logout();
+   *
+   * // Logout with custom redirect URI
+   * await client.logout({
+   *   redirectUri: 'https://app.com/logged-out'
+   * });
+   * ```
+   */
+  async logout(options?: LogoutOptions): Promise<void> {
+    if (!options?.account) {
+      this.getLogger().warning(
+        'No account available for logout, please provide an account in the options',
+      );
+    }
+
+    const logoutRequest: EndSessionRequest = {
+      account: options?.account,
+      postLogoutRedirectUri: options?.redirectUri,
+    };
+
+    // Browser will navigate to Microsoft logout page
+    // Returns void because navigation interrupts execution on current page
+    await this.logoutRedirect(logoutRequest);
+  }
+
+  /**
+   * Acquires an access token with smart silent/interactive fallback.
+   *
+   * @param options - Token acquisition configuration
+   * @returns Promise resolving to authentication result or null/undefined
+   *
+   * @remarks
+   * Token acquisition flow:
+   * 1. If silent=true and account available, attempt silent token acquisition from cache
+   * 2. On silent failure (or not attempted), use interactive method based on behavior
+   * 3. Interactive method based on behavior (popup or redirect)
+   *
+   * **Behavior differences:**
+   * - **Popup**: Opens authentication popup window and returns token result immediately
+   * - **Redirect**: Navigates browser to Microsoft login page. Returns `void` because the browser
+   *   navigates to a new page. After redirect completes, handle the result via
+   *   `handleRedirectPromise()` when the app loads on the new page.
+   *
+   * The default silent behavior is determined by presence of account in the request.
+   * This provides optimal UX by minimizing unnecessary user interactions.
+   */
+  async acquireToken(options: AcquireTokenOptions): Promise<AcquireTokenResult> {
+    const { behavior = 'redirect', silent = !!options.request?.account, request } = options;
+
+    if (!request) {
+      throw new Error('No request provided, please provide a request in the options');
+    }
+
+    if (request.scopes.length === 0) {
+      this.getLogger().warning(
+        'No scopes provided, please provide scopes in the request option, see options.request for more information.',
+      );
+    }
+
+    // Attempt silent token acquisition first
+    // This fetches from cache or uses refresh token without user interaction
+    if (silent) {
+      if (request.account) {
+        try {
+          this.getLogger().verbose('Attempting to acquire token silently');
+          return await this.acquireTokenSilent(request as SilentRequest);
+        } catch {
+          // Silent acquisition failed - fall back to interactive
+          this.getLogger().warning('Silent token acquisition failed, falling back to interactive');
+        }
+      } else {
+        this.getLogger().warning(
+          'Cannot acquire token silently, no account provided, falling back to interactive.',
+        );
+      }
+    }
+
+    // Perform interactive token acquisition
+    switch (behavior) {
+      case 'popup':
+        // Popup flow - returns token immediately after user grants permission
+        return await this.acquireTokenPopup(request);
+      case 'redirect':
+        // Redirect flow - browser navigates to Microsoft login page
+        // Returns void because browser navigation interrupts execution on current page
+        // Token will be available via handleRedirectPromise() after app loads on new page
+        await this.acquireTokenRedirect(request);
+        break;
+      default:
+        throw new Error(
+          `Invalid behavior provided: ${behavior}, please provide a valid behavior, see options.behavior for more information.`,
+        );
+    }
+  }
+}