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

package/docs/migration-v2-to-v4.md

@@ -0,0 +1,115 @@
+# Migration Guide
+
+## MSAL v2 to v4 Migration
+
+This package has been upgraded from MSAL Browser v2 to v4, providing the latest security improvements and features from Microsoft.
+
+### What Changed in v4
+
+**New MSAL Browser v4 Features:**
+- Enhanced security with improved token management
+- Better performance and memory usage
+- New authentication API structure with nested request objects
+- Improved error handling and retry mechanisms
+
+**Architecture Changes:**
+- **Module Hoisting**: The module uses module hoisting, meaning sub-module instances proxy the parent module instance
+- **Shared Authentication State**: Authentication state is shared across all module instances
+- **Async Initialization**: New `initialize()` method must be called before using the provider
+
+### Breaking Changes
+
+1. **Auto-initialization via Framework**
+   ```typescript
+   // The provider initializes automatically when framework loads
+   const framework = await initialize(configurator);
+   const auth = framework.auth; // Already initialized
+   
+   // Manual initialization is only needed for standalone usage
+   const provider = new MsalProvider(config);
+   await provider.initialize();
+   ```
+
+2. **API Method Signature Updates**
+   - `logout()` now returns `Promise<boolean>` instead of `Promise<void>`
+   - `handleRedirect()` now returns `Promise<AuthenticationResult | null>` instead of `Promise<void>`
+   - Methods now expect nested request objects (v4 format)
+
+3. **Account Property Changes**
+   - Use `account` property (returns `AccountInfo | null`) - v4 native
+   - `defaultAccount` is deprecated and only available via v2 proxy layer
+   - Migration: Replace `defaultAccount` with `account` throughout your code
+
+### Migration Steps
+
+1. **Update Token Acquisition** (Recommended)
+   ```typescript
+   // Before (v2 format - still works via proxy)
+   const token = await framework.auth.acquireAccessToken({ 
+     scopes: ['api.read'] 
+   });
+   
+   // After (v4 format - recommended)
+   const token = await framework.auth.acquireAccessToken({ 
+     request: { scopes: ['api.read'] } 
+   });
+   ```
+
+2. **Update Logout Handling**
+   ```typescript
+   // Before
+   await framework.auth.logout();
+   
+   // After (check return value)
+   const success = await framework.auth.logout();
+   if (success) {
+     // Handle successful logout
+   }
+   ```
+
+3. **Update Redirect Handling**
+   ```typescript
+   // Before
+   await framework.auth.handleRedirect();
+   
+   // After (handle result)
+   const result = await framework.auth.handleRedirect();
+   if (result?.account) {
+     // User authenticated successfully
+     console.log('Logged in as:', result.account.username);
+   }
+   ```
+
+4. **Update Configuration** (if needed)
+   ```typescript
+   // Ensure only the root module configures MSAL
+   enableMSAL(configurator, (builder) => {
+     builder.setClientConfig({
+       auth: {
+         clientId: 'your-client-id',
+         tenantId: 'your-tenant-id',
+         redirectUri: 'https://your-app.com/callback'
+       }
+     });
+     builder.setRequiresAuth(true);
+   });
+   ```
+
+5. **Remove Duplicate Configurations**: Remove MSAL configuration from child modules
+
+### Backward Compatibility
+
+The module includes a **v2 proxy layer** that automatically converts v2 API calls to v4 format. This means:
+- ✅ Existing code continues to work without changes
+- ✅ Legacy format `{ scopes: [] }` is still supported
+- ✅ Deprecated v2 properties like `defaultAccount` are available via v2 proxy (with deprecation warnings)
+- ⚠️ New v4 features require using v4 format
+
+### Benefits of Migration
+
+- **Better Security**: Latest MSAL v4 security improvements and token handling
+- **Improved Performance**: Faster token acquisition, better caching, reduced memory usage
+- **Enhanced Error Handling**: More robust error recovery and retry mechanisms
+- **Future-Proof**: Access to latest Microsoft authentication features and updates
+- **Shared State**: Improved authentication state management across app scopes via module hoisting
+- **Better Developer Experience**: Cleaner API, better TypeScript support, comprehensive documentation

package/docs/testing.md

@@ -0,0 +1,167 @@
+# MSAL — test double
+
+Authenticate in-process instead of against Entra ID.
+
+```typescript
+import { enableMsalMock } from '@equinor/fusion-framework-module-msal/mock';
+
+enableMsalMock(configurator);
+```
+
+Import path: `@equinor/fusion-framework-module-msal/mock`. The entry point has **no test-runner dependency**.
+
+## What is substituted
+
+> [!IMPORTANT]
+> Only `IMsalClient` — the object that would contact Entra ID. The real `MsalConfigurator`, the real `MsalProvider` and the real schema validation all still run.
+
+That distinction is the point. Scope resolution, silent-first token acquisition, account handling, proxy providers and telemetry stay on the production code path, so a test observes real provider behaviour:
+
+```typescript
+const fusion = await mockFramework((configurator) => {
+  // the client is configured with *what it talks to*, exactly as in production
+  configurator.msal.setClientConfig({ auth: { clientId: 'my-app', tenantId: 'my-tenant' } });
+});
+
+const token = await fusion.modules.auth.acquireAccessToken();
+// scope is 'my-app/.default' — resolved by the real provider, not by the test double
+```
+
+A double that replaced the provider would have skipped that logic and reported whatever it was told to.
+
+## Defaults
+
+A user named `Test User` is signed in. Tokens are real JWTs, minted in-process with a fixed issue time, so they are identical across runs and machines and can be compared or snapshotted directly.
+
+When no client configuration is declared, a stand-in one is used, so an application boots under test without credentials it does not have.
+
+## Choosing the signed-in user
+
+`MsalMockClient` takes the same `MsalClientConfig` the real `MsalClient` takes — a client configuration has no notion of who is signed in, so the user is declared separately and signed in on the client as it is built:
+
+```typescript
+import { enableMsalMock } from '@equinor/fusion-framework-module-msal/mock';
+
+enableMsalMock(configurator, (builder) => {
+  builder.setAccount({ name: 'Ada Lovelace', username: 'ada@equinor.com' });
+});
+```
+
+Pass `null` when nobody is signed in:
+
+```typescript
+enableMsalMock(configurator, (builder) => {
+  builder.setAccount(null);
+});
+```
+
+`setAccount` also takes an ordinary config-builder callback, resolved while the configuration is assembled and handed the same arguments every other builder callback receives:
+
+```typescript
+enableMsalMock(configurator, (builder) => {
+  builder.setAccount(async ({ hasModule }) => ({
+    name: hasModule('app') ? 'App User' : 'Portal User',
+  }));
+});
+```
+
+The user is in place **before** `MsalProvider.initialize()` runs, so the provider's own start-up path acts on it. Combined with `setRequiresAuth(true)`, a test observes the real automatic login rather than a state assigned after the fact.
+
+`setClient` replaces the client, but not the rule: the declared user is signed in on whichever client the module authenticates through, so a mock client supplied that way receives it too.
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `name` | `Test User` | Display name |
+| `username` | `test.user@equinor.com` | UPN / email |
+| `userId` | `fusion-mock-user` | Object ID |
+| `tenantId` | the client's configured tenant | Tenant |
+| `scopes` | `fusion-mock-scope` | Granted when a request specifies none |
+| `account` | derived | A preconfigured `AccountInfo` to use outright |
+| `signedOut` | `false` | Start without a signed-in user |
+
+The client tokens are issued for comes from the client configuration (`setClientConfig`), not from the user.
+
+### Why the user is signed in at construction
+
+The account is put in the client's cache as the client is built — before the provider exists. That reproduces the production shape of a returning user with a live session: the provider finds an account already there and takes the branch it takes in the browser.
+
+Assigning the account **after** `MsalProvider.initialize()` — from an `onInitialized` hook, say — looks equivalent but is not. `initialize()` exchanges an auth code, calls `handleRedirect()` and, when `requiresAuth` is set, performs an automatic login. A late assignment silently overwrites all of that, so a test asserting on the sign-in journey would be observing its own assignment rather than the framework.
+
+## Changing the user between tests
+
+When a suite shares one framework instance but needs a different user per test, set the active account directly:
+
+```typescript
+beforeEach(() => {
+  fusion.modules.auth.client.setActiveAccount(account);
+});
+```
+
+The mock keeps a real account cache, so this behaves the way MSAL does: `getActiveAccount`, `getAllAccounts` and `getAccount(filter)` all agree afterwards. Unlike real MSAL, an account that was never issued by a sign-in is accepted and added to the cache, which is what makes the one-liner above possible.
+
+Signing out (`logout`, `logoutPopup`, `logoutRedirect`) removes the account from the cache rather than merely deactivating it, as MSAL does.
+
+## Running inside a host application
+
+When the module is hoisted onto a host application's provider — an app inside a portal — no client is built. The app authenticates through the host's client, exactly as in production.
+
+A user declared with `setAccount` is still honoured: it is signed in on the **host's** client, because that is the client the app authenticates through. The alternative would be for `setAccount` to silently do nothing precisely when an app is being tested inside a portal.
+
+The session is shared, so this changes who the host sees signed in too — as it does in production. If the host does not authenticate through a mock client, `setAccount` throws rather than failing quietly.
+
+## Testing signed-out behaviour
+
+Both `null` and `signedOut: true` start without a session. Silent flows then resolve empty so the provider follows its unauthenticated path, while an explicit login still succeeds — which lets a test drive the sign-in journey rather than only its end state.
+
+They differ in what the login resolves to. `null` forgets the identity, so a login produces the default user:
+
+```typescript
+builder.setAccount(null);
+```
+
+`signedOut: true` keeps it, so a login produces the user the test named — which is what to reach for when the assertion is about *who* signed in:
+
+```typescript
+builder.setAccount({ name: 'Ada Lovelace', signedOut: true });
+```
+
+## Mocking an individual call
+
+> [!IMPORTANT]
+> That is your test runner's job. This module ships **no mocking API**.
+
+The mock client is a plain class with ordinary methods, so `vi.spyOn`, `bun:test`'s `spyOn` and Node's `t.mock.method` all work on it directly — with their own call assertions, argument matchers and reset semantics, which a framework-specific API would not give you.
+
+The provider exposes the client it authenticates through, so a spy has a stable target:
+
+```typescript
+vi.spyOn(fusion.modules.auth.client, 'acquireToken').mockResolvedValue(result);
+
+afterEach(() => vi.restoreAllMocks());
+```
+
+## Minting a token directly
+
+For code that only needs a token — an HTTP interceptor test, say — skip the client:
+
+```typescript
+import { createMockToken } from '@equinor/fusion-framework-module-msal/mock';
+
+const token = createMockToken({ oid: 'fusion-mock-user' });
+```
+
+## Exports
+
+| Export | Purpose |
+| --- | --- |
+| `enableMsalMock(configurator, configure?)` | Register the module with an in-process client |
+| `msalMockModule` | The module itself, for manual registration |
+| `MsalMockConfigurator` | The real configurator, backed by an in-process client |
+| `MsalMockClient(config)` | The in-process client, taking the same `MsalClientConfig` as `MsalClient` |
+| `createMsalMockClient(config, user?)` | Convenience alias for `new MsalMockClient(config)` |
+| `createMockToken(claims?)` | Mint a deterministic JWT |
+
+## Related
+
+- [Module README](../README.md) — production configuration
+- [`@equinor/fusion-framework/mock`](../../../framework/docs/testing.md) — mock every framework boundary at once

package/docs/troubleshooting.md

@@ -0,0 +1,17 @@
+# Troubleshooting
+
+## Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| **Authentication Loop** | Ensure redirect URIs match your application's routing |
+| **Token Acquisition Fails** | Check that required scopes are properly configured |
+| **Module Not Found** | Ensure the module is properly configured and framework is initialized |
+| **Multiple MSAL Instances** | Remove duplicate configurations from child modules |
+| **Redirect Returns Void** | For redirect flows, use `handleRedirect()` after navigation completes |
+| **Token Empty/Undefined** | Verify user is authenticated and scopes are correct |
+
+## Getting Help
+
+- 📖 [MSAL Cookbook](https://github.com/equinor/fusion-framework/tree/main/cookbooks/app-react-msal) - Complete working examples
+- 🐛 [Report Issues](https://github.com/equinor/fusion/issues) - Bug reports and feature requests

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.1",
+  "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"
       ]
     }
   },
@@ -48,18 +55,18 @@
   "devDependencies": {
     "@types/semver": "^7.7.1",
     "semver": "^7.7.4",
-    "typescript": "^6.0.3",
+    "typescript": "^7.0.2",
     "zod": "^4.4.3",
-    "@equinor/fusion-framework-module": "^6.1.0",
-    "@equinor/fusion-framework-module-telemetry": "^7.0.0"
+    "@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",
+    "typescript": ">=5.0.0",
     "zod": "^4.0.0",
-    "@equinor/fusion-framework-module": "^6.1.0",
-    "@equinor/fusion-framework-module-telemetry": "^7.0.0"
+    "@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/MsalClient.ts

@@ -145,11 +145,14 @@ export class MsalClient extends PublicClientApplication implements IMsalClient {
    * - **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.
+   *
+   * @throws {Error} If an invalid `options.behavior` value is provided.
    */
   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) {
+      // Warn early when neither an account nor login hint is available for silent SSO
       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',
@@ -216,6 +219,7 @@ export class MsalClient extends PublicClientApplication implements IMsalClient {
    * ```
    */
   async logout(options?: LogoutOptions): Promise<void> {
+    // Warn when no account was supplied since the active account will be used instead
     if (!options?.account) {
       this.getLogger().warning(
         'No account available for logout, please provide an account in the options',
@@ -253,14 +257,18 @@ export class MsalClient extends PublicClientApplication implements IMsalClient {
    *
    * The default silent behavior is determined by presence of account in the request.
    * This provides optimal UX by minimizing unnecessary user interactions.
+   *
+   * @throws {Error} If no `request` is provided in `options`.
    */
   async acquireToken(options: AcquireTokenOptions): Promise<AcquireTokenResult> {
     const { behavior = 'redirect', silent = !!options.request?.account, request } = options;
 
+    // A request is required to know which scopes/account to acquire a token for
     if (!request) {
       throw new Error('No request provided, please provide a request in the options');
     }
 
+    // Warn when no scopes are requested, since MSAL requires at least one scope
     if (request.scopes.length === 0) {
       this.getLogger().warning(
         'No scopes provided, please provide scopes in the request option, see options.request for more information.',
@@ -271,6 +279,7 @@ export class MsalClient extends PublicClientApplication implements IMsalClient {
     // Attempt silent token acquisition first
     // This fetches from cache or uses refresh token without user interaction
     if (silent) {
+      // Only silent-acquire when an account is available to look up cached tokens for
       if (request.account) {
         try {
           this.getLogger().verbose(