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

package/docs/testing.md

@@ -0,0 +1,191 @@
+# 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.
+
+## Returning an exact token
+
+Most tests only care who is signed in and let the mock fabricate a token from that user's fields. When a backend mock validates the token itself — specific claims, an audience, or a signature — it needs to see the exact token it expects instead:
+
+```typescript
+enableMsalMock(configurator, (builder) => {
+  builder.setToken(token);
+});
+```
+
+`setToken` also signs in the user the token's claims describe, via `createMockUserFromToken` — so `acquireAccessToken` returns this token, and the account APIs agree with it. Pass `true` as the second argument to keep a separately declared account instead:
+
+```typescript
+enableMsalMock(configurator, (builder) => {
+  builder.setAccount({ name: 'Ada Lovelace' }).setToken(token, true);
+});
+```
+
+| 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' });
+```
+
+To use a generated token as the signed-in user for `ffc app dev --mock`, `ffc app serve --mock`,
+or a Vite SPA, see
+[Generate a mock user and update `.env`](../../../vite-plugins/spa/README.md#generate-a-mock-user-and-update-env).
+That workflow documents persistent mock-auth configuration, identity claims, and custom `scp`
+token scopes.
+
+## 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.2",
+  "version": "11.0.0-next.1",
   "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.1"
   },
   "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.1"
   },
   "peerDependenciesMeta": {
     "@equinor/fusion-framework-module-telemetry": {