@equinor/fusion-framework-module-msal 10.0.2 → 11.0.0-next.0

package/docs/version-management.md

@@ -0,0 +1,67 @@
+# Version Management
+
+The MSAL module includes built-in version checking to ensure compatibility between different MSAL library versions.
+
+## Version Resolution
+
+```typescript
+import { resolveVersion, VersionError } from '@equinor/fusion-framework-module-msal/versioning';
+
+// Resolve and validate a version
+const result = resolveVersion('2.0.0');
+console.log(result.isLatest); // false
+console.log(result.satisfiesLatest); // true
+console.log(result.enumVersion); // MsalModuleVersion.V2
+```
+
+## Version Checking Behavior
+
+- **Major Version Incompatibility**: Throws `VersionError` if requested major version is greater than latest
+- **Minor Version Mismatch**: Logs warning but allows execution
+- **Patch Differences**: Ignored for compatibility
+- **Invalid Versions**: Throws `VersionError` with descriptive message
+
+## API Reference
+
+### `resolveVersion(version: string | SemVer): ResolvedVersion`
+
+Resolves and validates a version string against the latest available MSAL version.
+
+**Parameters:**
+- `version` - Version string or SemVer object to resolve
+
+**Returns:** `ResolvedVersion` object containing:
+- `wantedVersion: SemVer` - The parsed requested version
+- `latestVersion: SemVer` - The latest available version
+- `isLatest: boolean` - Whether the version is exactly the latest
+- `satisfiesLatest: boolean` - Whether the major version matches latest
+- `enumVersion: MsalModuleVersion` - Corresponding enum version
+
+**Throws:** `VersionError` for invalid or incompatible versions
+
+### `VersionError`
+
+Error class for version-related issues with the following types:
+- `InvalidVersion` - Requested version is not a valid semver
+- `InvalidLatestVersion` - Latest version parsing failed (build issue)
+- `MajorIncompatibility` - Major version is greater than latest
+- `MinorMismatch` - Minor version differs (warning only)
+- `PatchDifference` - Patch version differs (info only)
+- `IncompatibleVersion` - General incompatibility
+
+## Error Handling
+
+```typescript
+import { resolveVersion, VersionError } from '@equinor/fusion-framework-module-msal/versioning';
+
+try {
+  const result = resolveVersion('3.0.0'); // Assuming latest is 2.x
+} catch (error) {
+  if (error instanceof VersionError) {
+    console.error('Version error:', error.message);
+    console.error('Requested:', error.requestedVersion);
+    console.error('Latest:', error.latestVersion);
+    console.error('Type:', error.type);
+  }
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-msal",
-  "version": "10.0.2",
+  "version": "11.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",
@@ -16,6 +16,10 @@
     "./v4": {
       "import": "./dist/esm/v4/index.js",
       "types": "./dist/types/v4/index.d.ts"
+    },
+    "./mock": {
+      "import": "./dist/esm/mock/index.js",
+      "types": "./dist/types/mock/index.d.ts"
     }
   },
   "typesVersions": {
@@ -28,6 +32,9 @@
       ],
       "v4": [
         "dist/types/v4/index.d.ts"
+      ],
+      "mock": [
+        "dist/types/mock/index.d.ts"
       ]
     }
   },
@@ -50,16 +57,16 @@
     "semver": "^7.7.4",
     "typescript": "^7.0.2",
     "zod": "^4.4.3",
-    "@equinor/fusion-framework-module": "^6.1.1",
-    "@equinor/fusion-framework-module-telemetry": "^7.0.1"
+    "@equinor/fusion-framework-module": "^6.1.3-next.0",
+    "@equinor/fusion-framework-module-telemetry": "^8.0.0-next.0"
   },
   "peerDependencies": {
     "@types/semver": "^7.0.0",
     "semver": "^7.0.0",
     "typescript": ">=5.0.0",
     "zod": "^4.0.0",
-    "@equinor/fusion-framework-module": "^6.1.1",
-    "@equinor/fusion-framework-module-telemetry": "^7.0.1"
+    "@equinor/fusion-framework-module": "^6.1.3-next.0",
+    "@equinor/fusion-framework-module-telemetry": "^8.0.0-next.0"
   },
   "peerDependenciesMeta": {
     "@equinor/fusion-framework-module-telemetry": {

package/src/MsalConfigurator.ts

@@ -1,68 +1,23 @@
-import z from 'zod';
-import { BaseConfigBuilder } from '@equinor/fusion-framework-module';
-import semver from 'semver';
-import type { IMsalProvider } from './MsalProvider.interface';
 import {
-  TelemetryLevel,
-  type ITelemetryProvider,
-} from '@equinor/fusion-framework-module-telemetry';
+  BaseConfigBuilder,
+  type ConfigBuilderCallbackArgs,
+} from '@equinor/fusion-framework-module';
+import { TelemetryLevel } from '@equinor/fusion-framework-module-telemetry';
+import { CacheLookupPolicy, LogLevel } from '@azure/msal-browser';
+
+import type { ITelemetryProvider } from '@equinor/fusion-framework-module-telemetry';
+import type { IMsalProvider } from './MsalProvider.interface';
 import { MsalClient, type MsalClientConfig, type IMsalClient } from './MsalClient';
 import { createClientLogCallback } from './create-client-log-callback';
-import { CacheLookupPolicy, LogLevel } from '@azure/msal-browser';
 import { version } from './version';
+import { MsalConfigSchema, type MsalConfig } from './msal-config-schema';
 
-/**
- * Zod schema for telemetry configuration validation.
- *
- * @internal
- */
-const TelemetryConfigSchema = z.object({
-  provider: z.custom<ITelemetryProvider>().optional(),
-  metadata: z.record(z.string(), z.unknown()).optional().default({
-    module: 'msal',
-    version,
-  }),
-  scope: z.array(z.string()).optional().default(['framework', 'authentication']),
-});
-
-/**
- * Telemetry configuration for MSAL module.
- *
- * This configuration controls how authentication events are tracked and logged
- * through the framework's telemetry system.
- */
-export type TelemetryConfig = z.infer<typeof TelemetryConfigSchema>;
-
-/**
- * Zod schema for MSAL module configuration validation.
- *
- * @internal
- */
-const MsalConfigSchema = z.object({
-  client: z.custom<IMsalClient>().optional(),
-  provider: z.custom<IMsalProvider>().optional(),
-  requiresAuth: z.boolean().optional(),
-  redirectUri: z.string().optional(),
-  loginHint: z.string().optional(),
-  authCode: z.string().optional(),
-  cacheLookupPolicy: z
-    .custom<CacheLookupPolicy>(
-      (val) =>
-        typeof val === 'number' &&
-        Object.values(CacheLookupPolicy).includes(val as CacheLookupPolicy),
-    )
-    .optional(),
-  version: z.string().transform((x: string) => String(semver.coerce(x))),
-  telemetry: TelemetryConfigSchema,
-});
-
-/**
- * Complete configuration object for MSAL authentication module.
- *
- * This type represents the full configuration including client setup, authentication
- * requirements, telemetry, and version information.
- */
-export type MsalConfig = z.infer<typeof MsalConfigSchema>;
+export {
+  MsalConfigSchema,
+  type MsalConfig,
+  type MsalConfigExtension,
+} from './msal-config-schema';
+export { TelemetryConfigSchema, type TelemetryConfig } from './telemetry-config-schema';
 
 /**
  * Configuration builder for MSAL v4 authentication module.
@@ -79,6 +34,7 @@ export type MsalConfig = z.infer<typeof MsalConfigSchema>;
  */
 export class MsalConfigurator extends BaseConfigBuilder<MsalConfig> {
   #msalConfig?: MsalClientConfig;
+  #client?: IMsalClient;
 
   /**
    * The MSAL module version being configured.
@@ -107,6 +63,9 @@ export class MsalConfigurator extends BaseConfigBuilder<MsalConfig> {
         return telemetry;
       }
     });
+    // Always resolve the configured client instance through the builder.
+    // This keeps the client getter live and avoids re-registering the same config key.
+    this._set('client', async () => this.#client);
     // Default cache lookup policy to AccessTokenAndRefreshToken to avoid iframe fallback delays
     this._set('cacheLookupPolicy', async () => CacheLookupPolicy.AccessTokenAndRefreshToken);
   }
@@ -136,6 +95,23 @@ export class MsalConfigurator extends BaseConfigBuilder<MsalConfig> {
     return this;
   }
 
+  /**
+   * Returns the client configuration declared through
+   * {@link MsalConfigurator.setClientConfig | setClientConfig}, if any.
+   *
+   * @remarks
+   * This is the configuration as declared, not the resolved one a client is
+   * built from — see
+   * {@link MsalConfigurator._createClientConfig | _createClientConfig} for that.
+   * Reading it is how a subclass can tell "nothing was declared" apart from
+   * "declared, and here it is", without re-deriving that from a resolved value.
+   *
+   * @returns The declared client configuration, or `undefined` when none was declared.
+   */
+  public getClientConfig(): MsalClientConfig | undefined {
+    return this.#msalConfig;
+  }
+
   /**
    * Sets the cache lookup policy used for every silent token acquisition.
    *
@@ -274,10 +250,23 @@ export class MsalConfigurator extends BaseConfigBuilder<MsalConfig> {
    * ```
    */
   setClient(client: IMsalClient): this {
-    this._set('client', async () => client);
+    this.#client = client;
     return this;
   }
 
+  /**
+   * Returns the currently configured MSAL client, if one has been set.
+   *
+   * @remarks
+   * This is useful in tests when a mock client has been provided and the test
+   * wants to adjust its state after it has been assigned to the configurator.
+   *
+   * @returns The configured client, or `undefined` when none has been set.
+   */
+  public getClient(): IMsalClient | undefined {
+    return this.#client;
+  }
+
   /**
    * Sets telemetry provider for MSAL authentication events.
    *
@@ -328,72 +317,170 @@ export class MsalConfigurator extends BaseConfigBuilder<MsalConfig> {
   /**
    * Processes and validates the configuration.
    *
-   * @param config - Raw configuration object
+   * @param rawConfig - Raw configuration object
+   * @param init - The builder arguments, carrying the host reference when hoisted
    * @returns Processed and validated configuration
    */
-  async _processConfig(rawConfig: MsalConfig): Promise<MsalConfig> {
+  async _processConfig(
+    rawConfig: MsalConfig,
+    init?: ConfigBuilderCallbackArgs,
+  ): Promise<MsalConfig> {
     // Validate and coerce configuration using Zod schema
     const config = await MsalConfigSchema.parseAsync(rawConfig);
 
-    // Auto-create client if config provided but no client instance
+    // Auto-create client if no client instance was supplied
     // This allows users to provide configuration without manually instantiating the client
-    if (!config.client && this.#msalConfig) {
-      const clientConfig = this.#msalConfig;
+    // A hoisted module authenticates through the host's provider, so any client built here
+    // would be discarded — gate it here rather than in `_createClient`, so a substituted
+    // client (see `MsalMockConfigurator`) cannot shadow the host's signed-in user
+    if (!config.client && !this._isHoisted(init)) {
+      config.client = await this._createClient(config, init);
+    }
 
-      config.telemetry.provider?.trackEvent({
-        name: 'module-msal.configurator._processConfig.creating-client',
-        level: TelemetryLevel.Debug,
-        scope: config.telemetry.scope,
-        metadata: { ...config.telemetry.metadata, clientConfig },
-      });
+    return config;
+  }
 
-      // Auto-generate authority URL from tenant ID if not explicitly provided
-      // This simplifies configuration for most common cases
-      if (!clientConfig.auth.authority && clientConfig.auth.tenantId) {
-        clientConfig.auth.authority = `https://login.microsoftonline.com/${clientConfig.auth.tenantId}`;
-      }
+  /**
+   * Creates the client to authenticate through, when none was supplied.
+   *
+   * @remarks
+   * Called by {@link MsalConfigurator._processConfig | _processConfig} only when
+   * no client was set, so a client supplied through
+   * {@link MsalConfigurator.setClient | setClient} always wins. It is likewise
+   * not called when the module is hoisted onto a host application's provider —
+   * see {@link MsalConfigurator._isHoisted | _isHoisted}.
+   *
+   * This is the seam for authenticating through something other than Entra ID.
+   * Overriding it replaces only the client, leaving the builder, the schema
+   * validation and `MsalProvider` untouched — which is how
+   * `MsalMockConfigurator` substitutes an in-process client for tests.
+   *
+   * An override normally builds from
+   * {@link MsalConfigurator._createClientConfig | _createClientConfig}, so it
+   * receives the same fully-resolved {@link MsalClientConfig} the real client is
+   * built from rather than re-deriving it.
+   *
+   * Returning `undefined` is legitimate and means "there is nothing to build a
+   * client from", which leaves the module without one.
+   *
+   * @param config - The validated configuration the client is built from.
+   * @param init - The builder arguments, carrying the host reference when hoisted.
+   * @returns The client, or `undefined` when there is nothing to build one from.
+   */
+  protected async _createClient(
+    config: MsalConfig,
+    _init?: ConfigBuilderCallbackArgs,
+  ): Promise<IMsalClient | undefined> {
+    const clientConfig = this._createClientConfig(config);
+    // A client can be omitted for a hoisted module or an intentionally incomplete setup.
+    if (!clientConfig) {
+      return undefined;
+    }
 
-      // Set default cache location to localStorage for browser environments
-      // MSAL supports sessionStorage as well, but localStorage is the standard for persistent auth
-      if (!clientConfig.cache) {
-        clientConfig.cache = { cacheLocation: 'localStorage' };
-      }
+    // Instantiate MSAL client with fully configured options
+    return new MsalClient(clientConfig);
+  }
 
-      // Integrate framework telemetry with MSAL logging system
-      // This allows MSAL events to flow through the framework's telemetry pipeline
-      if (!clientConfig.system?.loggerOptions && config.telemetry?.provider) {
-        const { provider, metadata, scope } = config.telemetry;
-
-        provider.trackEvent({
-          name: 'module-msal.configurator._processConfig.client-telemetry-connected',
-          level: TelemetryLevel.Debug,
-          scope,
-          metadata,
-        });
-
-        clientConfig.system = {
-          ...clientConfig.system,
-          loggerOptions: {
-            // Only log PII in development to protect user privacy in production
-            piiLoggingEnabled: process.env.NODE_ENV === 'development',
-            // Bridge MSAL log events to framework telemetry system
-            loggerCallback: createClientLogCallback(provider, metadata, [...scope, '3rd-party']),
-            // Use Warning level by default - captures errors and warnings without being verbose
-            logLevel: LogLevel.Warning,
-            // Preserve any user-provided logger options (allows customization)
-            ...clientConfig.system?.loggerOptions,
-          },
-        };
-      }
-      // Apply silent cache lookup policy if configured
-      if (config.cacheLookupPolicy !== undefined) {
-        clientConfig.cacheLookupPolicy = config.cacheLookupPolicy;
-      }
+  /**
+   * Whether this module is hoisted onto a host application's authentication.
+   *
+   * @remarks
+   * When an application runs inside a host — a portal loading an app, or an app
+   * loading a widget — the module initializer returns a proxy of the host's
+   * provider instead of building its own (see the host-provider branch of the
+   * module initializer). A client built during configuration would therefore be
+   * constructed and immediately discarded.
+   *
+   * Detecting this during configuration lets the configurator skip building a
+   * client entirely, which matters most for substituted clients: a mock client
+   * built here would otherwise silently shadow the host's real signed-in user.
+   *
+   * @param init - The builder arguments, carrying the host reference when hoisted.
+   * @returns `true` when a host provider will be used instead of a locally built client.
+   */
+  protected _isHoisted(init?: ConfigBuilderCallbackArgs): boolean {
+    return !!(init?.ref as { auth?: IMsalProvider } | undefined)?.auth;
+  }
 
-      // Instantiate MSAL client with fully configured options
-      config.client = new MsalClient(clientConfig);
+  /**
+   * Resolves the full MSAL client configuration to build a client from.
+   *
+   * @remarks
+   * Applies the defaults a client is expected to be built with — authority
+   * derived from the tenant, cache location, telemetry-backed logging and the
+   * configured cache lookup policy.
+   *
+   * Kept separate from {@link MsalConfigurator._createClient | _createClient} so
+   * that substituting the client does not also mean re-implementing this
+   * resolution. `MsalMockConfigurator` relies on it to hand its mock client the
+   * very same configuration the real client would have received.
+   *
+   * @param config - The validated configuration.
+   * @returns The client configuration, or `undefined` when none was declared.
+   */
+  protected _createClientConfig(config: MsalConfig): MsalClientConfig | undefined {
+    const declared = this.#msalConfig;
+    // Do not construct a client when configuration has not supplied client settings.
+    if (!declared) {
+      return undefined;
     }
 
-    return config;
+    config.telemetry.provider?.trackEvent({
+      name: 'module-msal.configurator._processConfig.creating-client',
+      level: TelemetryLevel.Debug,
+      scope: config.telemetry.scope,
+      metadata: { ...config.telemetry.metadata, clientConfig: declared },
+    });
+
+    // Copied rather than enriched in place, so the object a caller passed to
+    // `setClientConfig` is never rewritten behind its back — a caller may well
+    // be reusing or asserting on it
+    const clientConfig: MsalClientConfig = {
+      ...declared,
+      auth: { ...declared.auth },
+      // Default to localStorage: MSAL supports sessionStorage too, but
+      // localStorage is the standard for persistent auth in browsers
+      cache: declared.cache ?? { cacheLocation: 'localStorage' },
+    };
+
+    // Auto-generate authority URL from tenant ID if not explicitly provided
+    // This simplifies configuration for most common cases
+    if (!clientConfig.auth.authority && clientConfig.auth.tenantId) {
+      clientConfig.auth.authority = `https://login.microsoftonline.com/${clientConfig.auth.tenantId}`;
+    }
+
+    // Integrate framework telemetry with MSAL logging system
+    // This allows MSAL events to flow through the framework's telemetry pipeline
+    if (!clientConfig.system?.loggerOptions && config.telemetry?.provider) {
+      const { provider, metadata, scope } = config.telemetry;
+
+      provider.trackEvent({
+        name: 'module-msal.configurator._processConfig.client-telemetry-connected',
+        level: TelemetryLevel.Debug,
+        scope,
+        metadata,
+      });
+
+      clientConfig.system = {
+        ...clientConfig.system,
+        loggerOptions: {
+          // Only log PII in development to protect user privacy in production
+          piiLoggingEnabled: process.env.NODE_ENV === 'development',
+          // Bridge MSAL log events to framework telemetry system
+          loggerCallback: createClientLogCallback(provider, metadata, [...scope, '3rd-party']),
+          // Use Warning level by default - captures errors and warnings without being verbose
+          logLevel: LogLevel.Warning,
+          // Preserve any user-provided logger options (allows customization)
+          ...clientConfig.system?.loggerOptions,
+        },
+      };
+    }
+
+    // Apply silent cache lookup policy if configured
+    if (config.cacheLookupPolicy !== undefined) {
+      clientConfig.cacheLookupPolicy = config.cacheLookupPolicy;
+    }
+
+    return clientConfig;
   }
 }

package/src/__tests__/MsalConfigurator.test.ts

@@ -20,6 +20,23 @@ const createInitialConfig = (): Pick<MsalConfig, 'telemetry'> => ({
 });
 
 describe('MsalConfigurator', () => {
+  it('enriches a copy, leaving the declared client configuration untouched', async () => {
+    // A caller may reuse or assert on the object it passed, and the defaults
+    // applied here are derived — rewriting it behind their back is not ours to do
+    const declared = { auth: { clientId: 'my-app', tenantId: 'my-tenant' } };
+    const configurator = new MsalConfigurator();
+
+    configurator.setClientConfig(declared);
+
+    const config = await configurator.createConfigAsync(
+      createConfigCallbackArgs(),
+      createInitialConfig(),
+    );
+
+    expect(declared).toEqual({ auth: { clientId: 'my-app', tenantId: 'my-tenant' } });
+    expect(config.client?.tenantId).toBe('my-tenant');
+  });
+
   it('setAuthCode should normalize surrounding whitespace', async () => {
     const configurator = new MsalConfigurator();
 
@@ -74,6 +91,95 @@ describe('MsalConfigurator', () => {
     expect(config.client).toBeUndefined();
   });
 
+  describe('_createClient', () => {
+    it('builds from the same resolved client config the real client would get', async () => {
+      // The mock relies on this: substituting the client must not also mean
+      // re-implementing authority, cache and telemetry resolution
+      const received: unknown[] = [];
+      class CustomConfigurator extends MsalConfigurator {
+        protected override async _createClient(config: MsalConfig): Promise<IMsalClient> {
+          received.push(this._createClientConfig(config));
+          return createClient();
+        }
+      }
+
+      const configurator = new CustomConfigurator();
+      configurator.setClientConfig({ auth: { clientId: 'client-id', tenantId: 'tenant-id' } });
+
+      await configurator.createConfigAsync(createConfigCallbackArgs(), createInitialConfig());
+
+      expect(received).toEqual([
+        expect.objectContaining({
+          auth: expect.objectContaining({
+            clientId: 'client-id',
+            // derived by the configurator, not by the caller
+            authority: 'https://login.microsoftonline.com/tenant-id',
+          }),
+          cache: { cacheLocation: 'localStorage' },
+        }),
+      ]);
+    });
+
+    it('supplies the client when none was set', async () => {
+      const client = createClient();
+      class CustomConfigurator extends MsalConfigurator {
+        protected override async _createClient(): Promise<IMsalClient> {
+          return client;
+        }
+      }
+
+      const config = await new CustomConfigurator().createConfigAsync(
+        createConfigCallbackArgs(),
+        createInitialConfig(),
+      );
+
+      expect(config.client).toBe(client);
+    });
+
+    it('is not consulted when a client was set, so setClient always wins', async () => {
+      const own = createClient();
+      const createOther = vi.fn().mockResolvedValue(createClient());
+      class CustomConfigurator extends MsalConfigurator {
+        protected override _createClient(): Promise<IMsalClient> {
+          return createOther();
+        }
+      }
+
+      const configurator = new CustomConfigurator();
+      configurator.setClient(own);
+
+      const config = await configurator.createConfigAsync(
+        createConfigCallbackArgs(),
+        createInitialConfig(),
+      );
+
+      expect(config.client).toBe(own);
+      expect(createOther).not.toHaveBeenCalled();
+    });
+
+    it('is not consulted when hoisted, so a host provider is never shadowed', async () => {
+      // A hoisted module authenticates through the host's provider, so anything
+      // built here would be discarded — or worse, shadow the host's user
+      const createOther = vi.fn().mockResolvedValue(createClient());
+      class CustomConfigurator extends MsalConfigurator {
+        protected override _createClient(): Promise<IMsalClient> {
+          return createOther();
+        }
+      }
+
+      const configurator = new CustomConfigurator();
+      configurator.setClientConfig({ auth: { clientId: 'client-id', tenantId: 'tenant-id' } });
+
+      const config = await configurator.createConfigAsync(
+        { ...createConfigCallbackArgs(), ref: { auth: {} } },
+        createInitialConfig(),
+      );
+
+      expect(config.client).toBeUndefined();
+      expect(createOther).not.toHaveBeenCalled();
+    });
+  });
+
   describe('cacheLookupPolicy', () => {
     it('defaults to CacheLookupPolicy.AccessTokenAndRefreshToken', async () => {
       const configurator = new MsalConfigurator();