@equinor/fusion-framework-module-msal 5.1.2 → 6.0.0-next.1

package/src/__tests__/versioning/resolve-version.test.ts

@@ -1,17 +1,12 @@
 import { describe, it, expect, vi } from 'vitest';
 import { SemVer } from 'semver';
-import { resolveVersion } from '../../versioning/resolve-version';
 
-// Mock the static module to avoid test failures when package version changes
-// This ensures tests remain stable regardless of package.json version bumps
-vi.mock('../../static', () => ({
-  MsalModuleVersion: {
-    V2: 'v2',
-    Latest: '4.0.9', // Fixed version for consistent testing
-  },
+// Mock the version first (hoisted)
+vi.mock('../../version', () => ({
+  version: '6.1.2-next.0+1493919587',
 }));
 
-// Import the mocked version
+import { resolveVersion } from '../../versioning/resolve-version';
 import { MsalModuleVersion } from '../../static';
 
 describe('resolveVersion', () => {
@@ -23,12 +18,12 @@ describe('resolveVersion', () => {
         wantedVersion: expect.any(SemVer),
         latestVersion: expect.any(SemVer),
         isLatest: false,
-        satisfiesLatest: false, // 2.x is not compatible with 4.x
+        satisfiesLatest: false, // 2.x is not compatible with 5.x
         enumVersion: MsalModuleVersion.V2,
       });
 
       expect(result.wantedVersion.version).toBe('2.1.0');
-      expect(result.latestVersion.version).toBe('4.0.9');
+      expect(result.latestVersion.version).toBe('6.1.2');
     });
 
     it('should resolve with SemVer object', () => {
@@ -36,14 +31,14 @@ describe('resolveVersion', () => {
       const result = resolveVersion(semver);
 
       expect(result.wantedVersion).toBe(semver);
-      expect(result.satisfiesLatest).toBe(false); // 2.x is not compatible with 4.x
+      expect(result.satisfiesLatest).toBe(false); // 2.x is not compatible with 5.x
     });
 
     it('should resolve latest version when no version provided', () => {
       const result = resolveVersion();
 
-      expect(result.wantedVersion.version).toBe('4.0.9');
-      expect(result.latestVersion.version).toBe('4.0.9');
+      expect(result.wantedVersion.version).toBe('6.1.2');
+      expect(result.latestVersion.version).toBe('6.1.2');
       expect(result.isLatest).toBe(true);
       expect(result.satisfiesLatest).toBe(true);
     });
@@ -51,7 +46,7 @@ describe('resolveVersion', () => {
     it('should resolve latest version when empty string provided', () => {
       const result = resolveVersion('');
 
-      expect(result.wantedVersion.version).toBe('4.0.9');
+      expect(result.wantedVersion.version).toBe('6.1.2');
       expect(result.isLatest).toBe(true);
     });
 
@@ -59,54 +54,46 @@ describe('resolveVersion', () => {
       const result = resolveVersion('2.5.0');
 
       expect(result.enumVersion).toBe(MsalModuleVersion.V2);
-      expect(result.satisfiesLatest).toBe(false); // 2.x is not compatible with 4.x
+      expect(result.satisfiesLatest).toBe(false); // 2.x is not compatible with 5.x
     });
   });
 
   describe('version comparison and warnings', () => {
     it('should identify version states correctly', () => {
       // Exact latest version
-      expect(resolveVersion('4.0.9').isLatest).toBe(true);
+      expect(resolveVersion('6.1.2-next.0+1493919587').isLatest).toBe(true);
 
       // Patch difference (satisfies but not latest)
-      const patchResult = resolveVersion('4.0.8');
+      const patchResult = resolveVersion('6.1.1');
       expect(patchResult.isLatest).toBe(false);
       expect(patchResult.satisfiesLatest).toBe(true);
       expect(patchResult.warnings).toBeUndefined();
 
-      // Minor difference (satisfies with warning)
-      const minorResult = resolveVersion('4.1.0');
+      // Minor difference (satisfies)
+      const minorResult = resolveVersion('6.0.0');
       expect(minorResult.isLatest).toBe(false);
       expect(minorResult.satisfiesLatest).toBe(true);
-      expect(minorResult.warnings).toBeDefined();
-      expect(minorResult.warnings?.[0]).toContain(
-        'Requested minor version 1 is different from the latest minor version 0',
-      );
 
-      // Major difference (doesn't satisfy with warning)
-      const majorResult = resolveVersion('5.0.0');
+      // Major difference (doesn't satisfy)
+      const majorResult = resolveVersion('7.0.0');
       expect(majorResult.satisfiesLatest).toBe(false);
-      expect(majorResult.warnings).toBeDefined();
-      expect(majorResult.warnings?.[0]).toContain(
-        'Requested major version 5 is greater than the latest major version 4',
-      );
     });
 
     it('should handle versions without matching enum with warnings', () => {
-      // Lower major version
+      // Lower major version - should map to V2
       const lowerResult = resolveVersion('3.0.0');
-      expect(lowerResult.enumVersion).toBe('4.0.9'); // Falls back to latest
+      expect(lowerResult.enumVersion).toBe(MsalModuleVersion.V2);
       expect(lowerResult.warnings).toBeDefined();
       expect(lowerResult.warnings?.[0]).toContain(
-        'Requested major version 3 is behind the latest major version 4',
+        'Requested major version 3 is behind the latest major version 6',
       );
 
-      // Zero version
+      // Zero version - should map to V2
       const zeroResult = resolveVersion('0.0.0');
-      expect(zeroResult.enumVersion).toBe('4.0.9'); // Falls back to latest
+      expect(zeroResult.enumVersion).toBe(MsalModuleVersion.V2);
       expect(zeroResult.warnings).toBeDefined();
       expect(zeroResult.warnings?.[0]).toContain(
-        'Requested major version 0 is behind the latest major version 4',
+        'Requested major version 0 is behind the latest major version 6',
       );
     });
   });
@@ -122,8 +109,8 @@ describe('resolveVersion', () => {
         expect(result.warnings?.[0]).toContain(
           `Failed to parse requested version "${invalidVersion}"`,
         );
-        // Should fall back to latest version
-        expect(result.wantedVersion.version).toBe('4.0.9');
+        // Should fall back to latest version (coerced)
+        expect(result.wantedVersion.version).toBe('6.1.2');
       });
     });
 
@@ -137,9 +124,9 @@ describe('resolveVersion', () => {
   describe('edge cases', () => {
     it('should handle complex version strings with pre-release and build metadata', () => {
       const testCases = [
-        { input: '4.0.9-beta.1', expected: '4.0.9' },
-        { input: '4.0.9+build.123', expected: '4.0.9' },
-        { input: '4.0.9-beta.1.alpha.2+build.123.456', expected: '4.0.9' },
+        { input: '6.1.2-next.0+1493919587-beta.1', expected: '6.1.2' },
+        { input: '6.1.2-next.0+1493919587+build.123', expected: '6.1.2' },
+        { input: '6.1.2-next.0+1493919587-beta.1.alpha.2+build.123.456', expected: '6.1.2' },
       ];
 
       testCases.forEach(({ input, expected }) => {
@@ -155,7 +142,7 @@ describe('resolveVersion', () => {
 
       // Latest version should be consistent
       expect(result1.latestVersion.version).toBe(result2.latestVersion.version);
-      expect(result1.latestVersion.version).toBe('4.0.9');
+      expect(result1.latestVersion.version).toBe('6.1.2');
 
       // Structure should be consistent
       expect(result1).toHaveProperty('wantedVersion');

package/src/create-client-log-callback.ts

@@ -0,0 +1,101 @@
+import { type ILoggerCallback, LogLevel } from '@azure/msal-browser';
+import {
+  type ITelemetryProvider,
+  TelemetryLevel,
+} from '@equinor/fusion-framework-module-telemetry';
+
+/**
+ * Maps MSAL log levels to corresponding telemetry levels.
+ *
+ * This mapping ensures consistent log level translation between MSAL's logging
+ * system and the framework's telemetry system.
+ */
+const levelMap: Partial<Record<LogLevel, TelemetryLevel>> = {
+  [LogLevel.Verbose]: TelemetryLevel.Debug,
+  [LogLevel.Info]: TelemetryLevel.Information,
+  [LogLevel.Warning]: TelemetryLevel.Warning,
+  [LogLevel.Error]: TelemetryLevel.Error,
+};
+
+/**
+ * Parses MSAL log message into structured components.
+ *
+ * MSAL log messages follow the format:
+ * [timestamp] : [correlationId] : [package] : [level] - [component] - [message]
+ *
+ * @param message - Raw MSAL log message
+ * @returns Parsed message components
+ */
+const parseMsalMessage = (message: string) => {
+  // Match the structured format: [timestamp] : [correlationId] : [package] : [level] - [component] - [message]
+  const match = message.match(
+    /^\[([^\]]+)\]\s*:\s*\[([^\]]*)\]\s*:\s*([^:]+)\s*:\s*(\w+)\s*-\s*([^-]+)\s*-\s*(.*)$/,
+  );
+
+  if (match) {
+    const [, _timestamp, _correlationId, packageInfo, _logLevel, component, logMessage] = match;
+    return {
+      package: packageInfo.trim() ?? undefined,
+      component: component.trim() ?? undefined,
+      message: logMessage.trim() ?? undefined,
+    };
+  }
+
+  // Fallback for non-structured messages
+  return { message: message.trim() };
+};
+
+/**
+ * Creates a telemetry callback function for MSAL logging integration.
+ *
+ * This function bridges MSAL's internal logging system with the framework's
+ * telemetry infrastructure. It maps MSAL log levels to telemetry levels and
+ * forwards log events to the provided telemetry provider with structured metadata.
+ *
+ * The callback function returned by this method will be called by MSAL whenever
+ * a log event occurs, allowing for centralized logging and monitoring of
+ * authentication-related events.
+ *
+ * @param provider - Telemetry provider instance to receive log events
+ * @param metadata - Additional metadata to include with each telemetry event (e.g., module version, environment)
+ * @param scope - Telemetry scope identifiers for categorization and filtering
+ * @returns Logger callback function for MSAL that forwards events to telemetry provider
+ *
+ * @example
+ * ```typescript
+ * const callback = createClientLogCallback(
+ *   telemetryProvider,
+ *   { module: 'msal', version: '4.0.0' },
+ *   ['framework', 'authentication']
+ * );
+ *
+ * // Use with MSAL configuration
+ * const config = {
+ *   system: {
+ *     loggerOptions: {
+ *       loggerCallback: callback,
+ *       piiLoggingEnabled: false
+ *     }
+ *   }
+ * };
+ * ```
+ */
+export const createClientLogCallback = (
+  provider: ITelemetryProvider,
+  metadata: Record<string, unknown>,
+  scope: string[],
+): ILoggerCallback | undefined => {
+  return (level: LogLevel, message: string, _containsPii: boolean) => {
+    const parsedMessage = parseMsalMessage(message);
+
+    provider.trackEvent({
+      name: 'MsalClient',
+      level: levelMap[level] ?? TelemetryLevel.Information,
+      scope,
+      metadata,
+      properties: {
+        ...parsedMessage,
+      },
+    });
+  };
+};

package/src/create-proxy-provider.ts

@@ -0,0 +1,89 @@
+import type { IMsalProvider } from './MsalProvider.interface';
+import { MsalModuleVersion } from './static';
+import { resolveVersion } from './versioning/resolve-version';
+import { createProxyProvider as createProxyProvider_v2 } from './v2/create-proxy-provider';
+
+/**
+ * Creates a proxy provider for version compatibility.
+ *
+ * This function handles the creation of proxy providers that maintain
+ * backward compatibility with different MSAL versions while using the
+ * latest MSAL v4 implementation under the hood.
+ *
+ * @param provider - The base MSAL provider instance
+ * @param version - The target version string (e.g., '2.0.0', '4.0.0')
+ * @returns A proxy provider compatible with the specified version
+ *
+ * @example
+ * ```typescript
+ * const baseProvider = new MsalProvider(config);
+ * const v2Proxy = createProxyProvider(baseProvider, '2.0.0');
+ * ```
+ */
+export function createProxyProvider<T = IMsalProvider>(
+  provider: IMsalProvider,
+  version: string,
+): T {
+  // Resolve the requested version to determine which proxy to create
+  const { enumVersion } = resolveVersion(version);
+
+  switch (enumVersion) {
+    case MsalModuleVersion.V2:
+      // Create v2-compatible proxy with legacy API adapters
+      return createProxyProvider_v2(provider) as T;
+    case MsalModuleVersion.V4:
+      // Create transparent proxy for v4 - passes through to original provider
+      // This allows v4 code to be used where any version is expected
+      return new Proxy(provider, {
+        get: (target: IMsalProvider, prop: keyof IMsalProvider) => {
+          switch (prop) {
+            case 'version': {
+              return target.version;
+            }
+            case 'msalVersion': {
+              return enumVersion;
+            }
+            case 'client': {
+              return target.client;
+            }
+            case 'account': {
+              return target.account;
+            }
+            case 'acquireAccessToken': {
+              return target.acquireAccessToken.bind(target);
+            }
+            case 'acquireToken': {
+              return target.acquireToken.bind(target);
+            }
+            case 'login': {
+              return target.login.bind(target);
+            }
+            case 'logout': {
+              return target.logout.bind(target);
+            }
+            case 'handleRedirect': {
+              return target.handleRedirect.bind(target);
+            }
+            case 'createProxyProvider': {
+              return target.createProxyProvider.bind(target);
+            }
+            case 'initialize': {
+              return () => {
+                // noop - initialize is handled by the provider, not the proxy
+              };
+            }
+            default: {
+              // backstop to prevent then from being called - this is not an async operation
+              if (prop === 'then') return undefined;
+
+              // Exhaustive check: TypeScript-only guard to ensure all IMsalProvider keys are handled
+              const exhausted: never = prop;
+              return (target as IMsalProvider)[exhausted];
+            }
+          }
+        },
+      }) as T;
+    default:
+      throw new Error(`Version ${version} is not supported`);
+  }
+}

package/src/index.ts

@@ -2,15 +2,14 @@ export {
   module,
   configureMsal,
   enableMSAL,
-  type AuthConfigurator as IAppConfigurator,
-  type AuthConfigFn,
-  type IAuthProvider,
   type MsalModule,
+  type AuthConfigFn,
 } from './module';
 
-export { MsalModuleVersion } from './static';
+export type { IMsalProvider } from './MsalProvider.interface';
+export type { IMsalClient } from './MsalClient.interface';
+export { MsalClient, type MsalClientConfig } from './MsalClient';
 
-export { default } from './module';
+export type { AccountInfo, AuthenticationResult } from './types';
 
-export type { AccountInfo, AuthenticationResult } from './v2/types';
-export type { AuthClientConfig } from './v2/configurator';
+export { default } from './module';

package/src/module.ts

@@ -4,62 +4,116 @@ import {
   SemanticVersion,
 } from '@equinor/fusion-framework-module';
 
-import { MsalModuleVersion } from './static';
+import { MsalConfigurator } from './MsalConfigurator';
+import { MsalProvider, type IMsalProvider } from './MsalProvider';
+import type { MsalClientConfig } from './MsalClient';
 
-import { AuthConfigurator, AuthProvider, type AuthClientConfig, type IAuthProvider } from './v2';
+import { version } from './version';
 
-export type MsalModule = Module<'auth', IAuthProvider, AuthConfigurator, [MsalModule]>;
-export type { AuthConfigurator, IAuthProvider };
+/**
+ * MSAL authentication module configuration.
+ *
+ * This module provides Microsoft Authentication Library (MSAL) integration for the
+ * Fusion Framework, supporting MSAL v4 with backward compatibility for v2 applications.
+ */
+export type MsalModule = Module<'auth', IMsalProvider, MsalConfigurator, [MsalModule]>;
 
+/**
+ * MSAL authentication module definition.
+ *
+ * This module manages authentication providers with the following initialization flow:
+ * 1. Check for custom provider configuration
+ * 2. Check for existing provider in parent module (for proxy compatibility)
+ * 3. Create new provider with client configuration
+ *
+ * @remarks
+ * The module supports proxy providers for version compatibility, allowing v4 implementations
+ * to work with v2-compatible code during migration periods.
+ */
 export const module: MsalModule = {
   name: 'auth',
-  version: new SemanticVersion(MsalModuleVersion.Latest),
-  configure: () => new AuthConfigurator(),
+  version: new SemanticVersion(version),
+  configure: () => new MsalConfigurator(),
   initialize: async (init) => {
     const config = await init.config.createConfigAsync(init);
 
-    // configured to use a custom provider
+    // Priority 1: Use custom provider if explicitly configured
     if (config.provider) {
       return config.provider;
     }
 
-    // check if the provider is defined in the parent module
-    const hostProvider = init.ref?.auth as AuthProvider;
+    // Priority 2: Check if provider exists in parent module (proxy compatibility)
+    // This allows child applications to reuse parent's authentication provider
+    const hostProvider = init.ref?.auth;
     if (hostProvider) {
       try {
-        return hostProvider.createProxyProvider(config.version);
+        const proxyProvider = hostProvider.createProxyProvider(config.version);
+        return proxyProvider;
       } catch (error) {
         console.error('MsalModule::Failed to create proxy provider', error);
-        // just to make sure during migration that the provider is not set
+        // Fallback to host provider to prevent app breakage during migration
+        // TODO: Consider throwing error instead once all apps are migrated to v4
         return hostProvider;
       }
     }
 
+    // Priority 3: Validate client configuration is provided
     if (!config.client) {
       throw new Error(
         'Client configuration is required when provider is not in the parent module nor defined',
       );
     }
 
-    // create a new provider
-    const authProvider = new AuthProvider(config.client);
+    // Create new MSAL provider instance
+    const provider = new MsalProvider(config);
 
-    if (config.requiresAuth) {
-      await authProvider.handleRedirect();
-      await authProvider.login({ onlyIfRequired: true });
-    }
+    // Initialize the provider (handles redirect callbacks, SSO, etc.)
+    await provider.initialize();
 
-    return authProvider;
+    return provider;
   },
 };
 
+/**
+ * Configuration function type for MSAL module setup.
+ *
+ * This function receives a builder object with methods to configure the MSAL client
+ * and authentication requirements.
+ */
 export type AuthConfigFn = (builder: {
-  setClientConfig: (config: AuthClientConfig) => void;
+  /**
+   * Set MSAL client configuration
+   * @param config - Client configuration with tenant ID, client ID, etc.
+   */
+  setClientConfig: (config: MsalClientConfig) => void;
+  /**
+   * Set whether authentication is required for the application
+   * @param requiresAuth - If true, app will attempt automatic login on initialization
+   */
   setRequiresAuth: (requiresAuth: boolean) => void;
 }) => void;
 
+/**
+ * Enables MSAL authentication module in the framework.
+ *
+ * This is a convenience function that adds the MSAL module configuration to the
+ * framework configurator with optional configuration callback.
+ *
+ * @param configurator - The framework modules configurator instance
+ * @param configure - Optional configuration callback for MSAL setup
+ *
+ * @example
+ * ```typescript
+ * enableMSAL(frameworkConfigurator, (builder) => {
+ *   builder.setClientConfig({
+ *     auth: { clientId: 'your-client-id', tenantId: 'your-tenant-id' }
+ *   });
+ *   builder.setRequiresAuth(true);
+ * });
+ * ```
+ */
 export const enableMSAL = (
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  // @biome-ignore lint/suspicious/noExplicitAny: must be any to support all module types
   configurator: IModulesConfigurator<any, any>,
   configure?: AuthConfigFn,
 ): void => {
@@ -67,6 +121,20 @@ export const enableMSAL = (
   configurator.addConfig(config);
 };
 
+/**
+ * Creates MSAL module configuration with custom setup.
+ *
+ * @param configure - Configuration callback function
+ * @returns Module configuration object ready for framework integration
+ *
+ * @example
+ * ```typescript
+ * const msalConfig = configureMsal((builder) => {
+ *   builder.setClientConfig(msalClientConfig);
+ *   builder.setRequiresAuth(true);
+ * });
+ * ```
+ */
 export const configureMsal = (configure: AuthConfigFn) => ({
   module,
   configure,

package/src/static.ts

@@ -1,8 +1,37 @@
-import { version } from './version';
-
+/**
+ * Module identifier for the MSAL authentication module.
+ *
+ * This constant is used to register and identify the MSAL module within the Fusion Framework.
+ */
 export const ModuleName = 'msal' as const;
 
+/**
+ * Enumeration of supported MSAL module versions.
+ *
+ * This enum defines the available MSAL versions and provides type-safe access to version identifiers.
+ * The `Latest` value is automatically set to the current module version at build time.
+ *
+ * @remarks
+ * - `V2`: MSAL v2 compatibility (legacy support)
+ * - `V4`: MSAL v4 (current major version)
+ * - `Latest`: Always points to the current module version (5.1.0)
+ *
+ * @example
+ * ```typescript
+ * import { MsalModuleVersion } from '@equinor/fusion-framework-module-msal';
+ *
+ * // Check version
+ * if (version === MsalModuleVersion.Latest) {
+ *   console.log('Using latest MSAL version');
+ * }
+ *
+ * // Create version-specific proxy
+ * const proxy = provider.createProxyProvider(MsalModuleVersion.V2);
+ * ```
+ */
 export enum MsalModuleVersion {
+  /** MSAL v2 compatibility version */
   V2 = 'v2',
-  Latest = version,
+  /** MSAL v4 (current major version) */
+  V4 = 'v4',
 }

package/src/types.ts

@@ -1,8 +1,16 @@
-import type { SemVer } from 'semver';
-import type { MsalModuleVersion } from './static';
+/**
+ * Re-exports of core MSAL types from @azure/msal-browser.
+ *
+ * This module provides convenient access to commonly used MSAL types without
+ * requiring direct imports from @azure/msal-browser. These types represent
+ * fundamental authentication entities used throughout the MSAL module.
+ *
+ * @module
+ */
 
-// this should be defined the @equinor/fusion-framework-module package
-export interface IProxyProvider {
-  version: string | SemVer;
-  createProxyProvider<T>(version: MsalModuleVersion): T;
-}
+export {
+  /** Represents account information for an authenticated user */
+  AccountInfo,
+  /** Represents the result of an authentication operation including tokens and account */
+  AuthenticationResult,
+} from '@azure/msal-browser';

package/src/util/compare-origin.ts

@@ -0,0 +1,11 @@
+import { normalizeUri } from './normalize-uri';
+
+/**
+ * Compares normalized version of urls
+ *
+ * @internal
+ */
+export const compareOrigin = (a: string, b: string): boolean => {
+  const url = { a: normalizeUri(a), b: normalizeUri(b) };
+  return url.a === url.b;
+};

package/src/{v2/client/util/url.ts → util/normalize-uri.ts}

@@ -12,13 +12,3 @@ export const normalizeUri = (uri: string, home: string = window.location.origin)
   const { origin, pathname } = new URL(uri);
   return origin + pathname.replace(/([^:]\/)\/+/g, '$1');
 };
-
-/**
- * Compares normalized version of urls
- *
- * @internal
- */
-export const compareOrigin = (a: string, b: string): boolean => {
-  const url = { a: normalizeUri(a), b: normalizeUri(b) };
-  return url.a === url.b;
-};