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

package/src/v2/IAuthClient.interface.ts

@@ -0,0 +1,91 @@
+import type {
+  AuthenticationResult,
+  AccountInfo as AccountInfoBase,
+  IPublicClientApplication,
+} from '@azure/msal-browser';
+
+export type IdTokenClaims = {
+  aud: string;
+  exp: number;
+};
+
+export type AccountInfo = AccountInfoBase & {
+  idTokenClaims?: IdTokenClaims;
+};
+
+export type AuthBehavior = 'popup' | 'redirect';
+
+export type AuthRequest = {
+  scopes?: string[];
+  loginHint?: string;
+};
+
+/**
+ * Interface for MSAL v2 compatible authentication client.
+ *
+ * This interface defines the contract for authentication clients that maintain
+ * backward compatibility with MSAL v2 API while using MSAL v4 implementation
+ * under the hood. This is useful for gradual migration scenarios.
+ *
+ * @example
+ * ```typescript
+ * const client: IAuthClient_v2 = createProxyClient(baseClient);
+ *
+ * // Use v2 compatible API
+ * const account = client.account;
+ * const result = await client.login({ scopes: ['User.Read'] });
+ * ```
+ */
+export interface IAuthClient extends IPublicClientApplication {
+  /**
+   * Tenant ID for the client domain
+   */
+  readonly tenantId: string;
+
+  /**
+   * Returns account for client tenant that MSAL currently has data for.
+   * (the account object is created at the time of successful login)
+   */
+  get account(): AccountInfo | undefined;
+
+  /**
+   * Check if the current account has valid claims
+   */
+  get hasValidClaims(): boolean;
+
+  /**
+   * Configured client ID
+   */
+  get clientId(): string | undefined;
+
+  /**
+   * Request origin from browser storage
+   */
+  get requestOrigin(): string | null;
+
+  /**
+   * Login user with optional silent authentication fallback
+   * @param options - Optional authentication request options
+   * @param behavior - Authentication method: 'popup' or 'redirect'
+   * @param silent - Whether to attempt silent authentication first
+   * @returns Promise resolving to authentication result or void
+   */
+  login(
+    options?: AuthRequest,
+    behavior?: AuthBehavior,
+    silent?: boolean,
+  ): Promise<AuthenticationResult | void>;
+
+  /**
+   * Acquire access token with optional silent authentication fallback
+   * @param options - Authentication request options
+   * @param behavior - Authentication method: 'popup' or 'redirect'
+   * @param silent - Whether to attempt silent authentication first
+   * @returns Promise resolving to authentication result or void
+   */
+  acquireToken(
+    options?: AuthRequest,
+    behavior?: AuthBehavior,
+    silent?: boolean,
+  ): Promise<AuthenticationResult | void>;
+}

package/src/v2/IPublicClientApplication.interface.ts

@@ -0,0 +1,71 @@
+import type { AccountInfo, AuthenticationResult } from './types';
+
+/**
+ * MSAL v2 compatible PublicClientApplication interface.
+ *
+ * This interface defines the contract for MSAL v2 PublicClientApplication
+ * to maintain backward compatibility while using MSAL v4 implementation.
+ *
+ * @example
+ * ```typescript
+ * const v4Client = new PublicClientApplication(config);
+ * const v2Client = createProxyClient_v2(v4Client);
+ *
+ * // Use v2-compatible methods
+ * const accounts = v2Client.getAllAccounts();
+ * const token = await v2Client.acquireTokenSilent({ scopes: ['User.Read'], account });
+ * ```
+ */
+export interface IPublicClientApplication {
+  /**
+   * Get all cached accounts
+   * @returns Array of cached account information
+   */
+  getAllAccounts(): AccountInfo[];
+
+  /**
+   * Acquire token silently using cached credentials
+   * @param request - Token request parameters
+   * @returns Promise resolving to authentication result
+   */
+  acquireTokenSilent(request: {
+    scopes: string[];
+    account: AccountInfo;
+  }): Promise<AuthenticationResult>;
+
+  /**
+   * Login user via popup window
+   * @param request - Optional login request parameters
+   * @returns Promise resolving to authentication result
+   */
+  loginPopup(request?: { scopes?: string[] }): Promise<AuthenticationResult>;
+
+  /**
+   * Login user via redirect
+   * @param request - Optional login request parameters
+   * @returns Promise that resolves when redirect is initiated
+   */
+  loginRedirect(request?: { scopes?: string[] }): Promise<void>;
+
+  /**
+   * Logout user via redirect
+   * @param request - Optional logout request parameters
+   * @returns Promise that resolves when logout is complete
+   */
+  logoutRedirect(request?: {
+    postLogoutRedirectUri?: string;
+    account?: AccountInfo;
+  }): Promise<void>;
+
+  /**
+   * Handle authentication redirect after login/logout
+   * @returns Promise resolving to authentication result or null
+   */
+  handleRedirectPromise(): Promise<AuthenticationResult | null>;
+
+  /**
+   * Get the currently active account
+   * @returns Active account information or null
+   */
+  getActiveAccount(): AccountInfo | null;
+}

package/src/v2/MsalProvider.interface.ts

@@ -0,0 +1,92 @@
+import type { SemVer } from 'semver';
+import type { MsalModuleVersion } from '../static';
+import type { IPublicClientApplication } from './IPublicClientApplication.interface';
+import type { AccountInfo, AuthenticationResult } from './types';
+
+/**
+ * Interface for MSAL v2 compatible authentication provider.
+ *
+ * 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.
+ */
+export interface IMsalProvider {
+  /** Current version of the provider (MSAL module version) */
+  version: string | SemVer;
+
+  /** Current MSAL module version */
+  msalVersion: MsalModuleVersion;
+
+  /**
+   * The MSAL PublicClientApplication instance (v2 compatible)
+   */
+  readonly client: IPublicClientApplication;
+
+  /**
+   * The current authenticated account (v2 compatibility)
+   * @deprecated Use activeAccount instead
+   */
+  readonly defaultAccount: AccountInfo | undefined;
+
+  /**
+   * The client configuration used to initialize this provider
+   * @deprecated Configuration should not be exposed
+   */
+  readonly defaultConfig: unknown | undefined;
+
+  /**
+   * The MSAL client instance (v2 compatibility)
+   * @deprecated Use client instead
+   */
+  readonly defaultClient: IPublicClientApplication;
+
+  /**
+   * Create a new MSAL client instance
+   * @deprecated This method is deprecated in MSAL v4
+   */
+  createClient(): IPublicClientApplication;
+
+  /**
+   * Acquire an access token for the specified scopes
+   * @param req - Auth request options (v2 compatible)
+   */
+  acquireAccessToken(req: { scopes: string[]; account?: AccountInfo }): Promise<string | undefined>;
+
+  /**
+   * Acquire full authentication result
+   * @param req - Auth request options (v2 compatible)
+   */
+  acquireToken(req: {
+    scopes: string[];
+    account?: AccountInfo;
+  }): Promise<AuthenticationResult | undefined>;
+
+  /**
+   * Login user interactively
+   * @param options - Login options (v2 compatible)
+   */
+  login(options?: { onlyIfRequired?: boolean }): Promise<void>;
+
+  /**
+   * Logout user
+   * @param options - Logout options (v2 compatible)
+   */
+  logout(options?: { redirectUri?: string }): Promise<void>;
+
+  /**
+   * Handle authentication redirect
+   */
+  handleRedirect(): Promise<void | null>;
+
+  /**
+   * Create a proxy provider for version compatibility
+   * @param version - Version string
+   * @returns Proxy provider
+   */
+  createProxyProvider<T = IMsalProvider>(version: string): T;
+
+  /**
+   * Dispose of the provider and clean up resources
+   */
+  dispose(): void;
+}

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

@@ -0,0 +1,186 @@
+import type { IMsalClient } from '../MsalClient.interface';
+import type { IAuthClient } from './IAuthClient.interface';
+import { mapAccountInfo } from './map-account-info';
+import { mapAuthenticationResult } from './map-authentication-result';
+import type { AccountInfo } from './types';
+
+/**
+ * Creates a v2-compatible proxy for MSAL PublicClientApplication.
+ *
+ * This function creates a proxy that wraps the MSAL v4 PublicClientApplication
+ * and provides v2-compatible method signatures and return types.
+ *
+ * @param client - The MSAL v4 PublicClientApplication instance
+ * @returns A proxy client with v2-compatible interface
+ *
+ * @example
+ * ```typescript
+ * const v4Client = new PublicClientApplication(config);
+ * const v2Client = createProxyClient_v2(v4Client);
+ *
+ * // Use v2-compatible methods
+ * const accounts = v2Client.getAllAccounts();
+ * const token = await v2Client.acquireTokenSilent({ scopes: ['User.Read'], account });
+ * ```
+ */
+export function createProxyClient(client: IMsalClient): IAuthClient {
+  const proxy = new Proxy(client, {
+    get: (target: IMsalClient, prop: keyof IAuthClient) => {
+      switch (prop) {
+        case 'getAllAccounts': {
+          return () => {
+            return target.getAllAccounts().map(mapAccountInfo);
+          };
+        }
+
+        case 'acquireTokenSilent': {
+          return async (request: { scopes: string[]; account: AccountInfo }) => {
+            const result = await target.acquireTokenSilent({
+              scopes: request.scopes,
+              account: request.account, // AccountInfo is compatible between v2/v4
+            });
+
+            return mapAuthenticationResult(result);
+          };
+        }
+
+        case 'loginPopup': {
+          return async (request?: { scopes?: string[] }) => {
+            const result = await target.loginPopup({
+              scopes: request?.scopes || [],
+            });
+
+            return mapAuthenticationResult(result);
+          };
+        }
+
+        case 'logoutRedirect': {
+          return async (request?: { postLogoutRedirectUri?: string; account?: AccountInfo }) => {
+            await target.logoutRedirect({
+              postLogoutRedirectUri: request?.postLogoutRedirectUri,
+              account: request?.account,
+            });
+          };
+        }
+
+        case 'handleRedirectPromise': {
+          return async () => {
+            const result = await target.handleRedirectPromise();
+
+            if (!result) {
+              return null;
+            }
+
+            return mapAuthenticationResult(result);
+          };
+        }
+
+        case 'getActiveAccount': {
+          return () => {
+            const account = target.getActiveAccount();
+            if (!account) {
+              return null;
+            }
+
+            return mapAccountInfo(account);
+          };
+        }
+
+        case 'tenantId': {
+          return target.tenantId;
+        }
+
+        case 'account': {
+          const account = target.getActiveAccount();
+          return account ? mapAccountInfo(account) : undefined;
+        }
+
+        case 'hasValidClaims': {
+          return target.hasValidClaims;
+        }
+
+        case 'clientId': {
+          return target.getConfiguration().auth.clientId;
+        }
+
+        case 'requestOrigin': {
+          return target.getConfiguration().auth.redirectUri;
+        }
+
+        case 'login': {
+          return async (
+            options?: { scopes?: string[]; loginHint?: string },
+            behavior?: 'popup' | 'redirect',
+            silent?: boolean,
+          ) => {
+            return await target.login({
+              request: {
+                scopes: options?.scopes || [],
+                loginHint: options?.loginHint,
+              },
+              behavior: behavior,
+              silent: silent,
+            });
+          };
+        }
+
+        case 'acquireToken': {
+          return async (
+            options?: { scopes?: string[]; loginHint?: string },
+            behavior?: 'popup' | 'redirect',
+            silent?: boolean,
+          ) => {
+            return await target.acquireToken({
+              request: {
+                scopes: options?.scopes || [],
+                account: target.getActiveAccount() ?? undefined,
+                loginHint: options?.loginHint,
+              },
+              behavior: behavior,
+              silent: silent,
+            });
+          };
+        }
+
+        case 'initialize':
+        case 'acquireTokenPopup':
+        case 'acquireTokenRedirect':
+        case 'acquireTokenByCode':
+        case 'addEventCallback':
+        case 'removeEventCallback':
+        case 'addPerformanceCallback':
+        case 'removePerformanceCallback':
+        case 'enableAccountStorageEvents':
+        case 'disableAccountStorageEvents':
+        case 'getConfiguration':
+        case 'setActiveAccount':
+        case 'getAccountByHomeId':
+        case 'getAccountByLocalId':
+        case 'getAccountByUsername':
+        case 'loginRedirect':
+        case 'logout':
+        case 'logoutPopup':
+        case 'ssoSilent':
+        case 'getTokenCache':
+        case 'setLogger':
+        case 'getLogger':
+        case 'initializeWrapperLibrary':
+        case 'setNavigationClient':
+        case 'hydrateCache':
+        case 'getAccount':
+        case 'clearCache': {
+          return target[prop];
+        }
+
+        default: {
+          // TypeScript-only guard to catch missing properties at compile time
+          const _exhaustiveCheck: never = prop;
+          // For any other properties, return the original value
+          return (target as unknown as IAuthClient)[_exhaustiveCheck];
+        }
+      }
+    },
+  });
+
+  return proxy as unknown as IAuthClient;
+}

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

@@ -0,0 +1,156 @@
+import type { IMsalProvider } from '../MsalProvider.interface';
+import type { IMsalProvider as IMsalProvider_v2 } from './MsalProvider.interface';
+import type { AccountInfo as AccountInfo_v2 } from './types';
+import { createProxyClient } from './create-proxy-client';
+import { mapAccountInfo } from './map-account-info';
+import { MsalModuleVersion } from '../static';
+
+/**
+ * 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 function createProxyProvider(provider: IMsalProvider): IMsalProvider_v2 {
+  // Create a v2-compatible client wrapper using the new client proxy
+  const v2Client = createProxyClient(provider.client);
+
+  // Use Proxy to intercept property access and provide v2-compatible implementations
+  const proxy = new Proxy(provider, {
+    get: (target: IMsalProvider, prop: keyof IMsalProvider_v2) => {
+      switch (prop) {
+        case 'version': {
+          return provider.version;
+        }
+        case 'msalVersion': {
+          return MsalModuleVersion.V2;
+        }
+        case 'client': {
+          // Return the v2-compatible client wrapper
+          return v2Client as unknown as IMsalProvider_v2['client'];
+        }
+        case 'defaultClient': {
+          // Deprecated property - redirect to client with warning
+          console.warn('defaultClient is deprecated, use client instead');
+          return v2Client as unknown as IMsalProvider_v2['defaultClient'];
+        }
+        case 'defaultAccount': {
+          // Map v4 account to v2 format for backward compatibility
+          const account = target.account;
+          const defaultAccount: IMsalProvider_v2['defaultAccount'] = account
+            ? mapAccountInfo(account)
+            : undefined;
+          return defaultAccount;
+        }
+        case 'defaultConfig': {
+          // Deprecated property - not available in v4
+          console.warn('defaultConfig is deprecated and not available in v4');
+          return undefined;
+        }
+        case 'createClient': {
+          // Deprecated method - return function that returns v2 client
+          console.warn('createClient is deprecated in MSAL v4');
+          const createClient: IMsalProvider_v2['createClient'] = () => v2Client;
+          return createClient;
+        }
+        case 'acquireToken': {
+          // Adapt v4 acquireToken to v2 signature with proper type mapping
+          const acquireToken: IMsalProvider_v2['acquireToken'] = async (req: {
+            scopes: string[];
+            account?: AccountInfo_v2;
+          }) => {
+            const result = await target.acquireToken({
+              request: { scopes: req.scopes, account: req.account },
+            });
+
+            // Convert null to undefined for v2 compatibility
+            return result || undefined;
+          };
+          return acquireToken;
+        }
+        case 'acquireAccessToken': {
+          // Adapt v4 acquireAccessToken to v2 signature
+          const acquireAccessToken: IMsalProvider_v2['acquireAccessToken'] = async (req: {
+            scopes: string[];
+            account?: AccountInfo_v2;
+          }) => {
+            return await target.acquireAccessToken({
+              request: { scopes: req.scopes, account: req.account },
+            });
+          };
+          return acquireAccessToken;
+        }
+        case 'login': {
+          // Adapt v4 login to v2 signature with optional parameters
+          const login: IMsalProvider_v2['login'] = async (options?: {
+            onlyIfRequired?: boolean;
+          }) => {
+            // Skip login if already authenticated and onlyIfRequired is true
+            if (options?.onlyIfRequired && target.account) {
+              return;
+            }
+            // Call v4 login with empty scopes (v2 behavior)
+            await target.login({ request: { scopes: [] } });
+          };
+          return login;
+        }
+        case 'logout': {
+          // Adapt v4 logout to v2 signature
+          const logout: IMsalProvider_v2['logout'] = async (options?: { redirectUri?: string }) => {
+            await target.logout({ redirectUri: options?.redirectUri });
+          };
+          return logout;
+        }
+        case 'handleRedirect': {
+          // Adapt v4 handleRedirect to v2 signature
+          const handleRedirect: IMsalProvider_v2['handleRedirect'] = async () => {
+            await target.handleRedirect();
+            // v2 expects null after redirect handling
+            return null;
+          };
+          return handleRedirect;
+        }
+        case 'createProxyProvider': {
+          // Generic method to create proxy providers for different versions
+          const createProxyProvider: IMsalProvider_v2['createProxyProvider'] = <T = IMsalProvider>(
+            version: string,
+          ) => target.createProxyProvider(version as MsalModuleVersion) as T;
+          return createProxyProvider;
+        }
+        case 'dispose': {
+          // No-op dispose method for v2 compatibility
+          return () => {
+            /** noop */
+          };
+        }
+        default: {
+          if (prop === 'then') {
+            return undefined;
+          }
+          // Exhaustive check to ensure all v2 properties are handled
+          const exhaustiveCheck: never = prop;
+          // Fallback: return original property from target for any unhandled cases
+          return (target as IMsalProvider)[exhaustiveCheck];
+        }
+      }
+    },
+  });
+
+  // Return the proxy cast to v2 interface for type safety
+  return proxy as unknown as IMsalProvider_v2;
+}

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

@@ -0,0 +1,20 @@
+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 function mapAccountInfo(account: AccountInfo): AccountInfo_v2 {
+  return {
+    homeAccountId: account.homeAccountId,
+    environment: account.environment,
+    tenantId: account.tenantId,
+    username: account.username,
+    localAccountId: account.localAccountId,
+    name: account.name,
+    idTokenClaims: account.idTokenClaims,
+  };
+}

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

@@ -0,0 +1,24 @@
+import type { AuthenticationResult } from '@azure/msal-browser';
+import type { AuthenticationResult as AuthenticationResult_v2 } from './types';
+import { mapAccountInfo } from './map-account-info';
+
+/**
+ * Maps current AuthenticationResult to v2 AuthenticationResult format.
+ *
+ * @param result - The current AuthenticationResult to convert
+ * @returns The v2 AuthenticationResult format
+ */
+export function mapAuthenticationResult(result: AuthenticationResult): AuthenticationResult_v2 {
+  return {
+    authority: result.authority,
+    uniqueId: result.uniqueId,
+    tenantId: result.tenantId,
+    scopes: result.scopes,
+    account: result.account ? mapAccountInfo(result.account) : null,
+    idToken: result.idToken,
+    idTokenClaims: result.idTokenClaims,
+    accessToken: result.accessToken,
+    expiresOn: result.expiresOn,
+    tokenType: result.tokenType,
+  };
+}

package/src/v2/types.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;
@@ -10,6 +16,12 @@ export type AccountInfo = {
   };
 };
 
+/**
+ * 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/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '5.1.1';
+export const version = '6.0.0-next.0';