@equinor/fusion-framework-module-msal 11.0.0 → 11.0.1

package/docs/api-reference.md

@@ -1,85 +0,0 @@
-# MSAL API Reference
-
-## `enableMSAL(configurator, configure?)`
-
-Enables the MSAL module in your Fusion Framework application.
-
-**Parameters:**
-- `configurator`: `IModulesConfigurator` - The modules configurator instance
-- `configure?`: `(builder: { setClientConfig, setRequiresAuth }) => void` - Optional configuration function
-
-**Returns:** `void`
-
-**Example:**
-```typescript
-enableMSAL(configurator, (builder) => {
-  builder.setClientConfig({ auth: { clientId: '...', tenantId: '...' } });
-  builder.setRequiresAuth(true);
-});
-```
-
-## Type Definitions
-
-### `LoginOptions`
-
-```typescript
-type LoginOptions = {
-  request: PopupRequest | RedirectRequest;  // MSAL request object
-  behavior?: 'popup' | 'redirect';          // Auth method (default: 'redirect')
-  silent?: boolean;                         // Attempt silent auth first (default: true)
-};
-```
-
-### `LogoutOptions`
-
-```typescript
-type LogoutOptions = {
-  redirectUri?: string;                     // Redirect after logout
-  account?: AccountInfo;                    // Account to logout (defaults to active)
-};
-```
-
-### `AcquireTokenOptions`
-
-```typescript
-type AcquireTokenOptions = {
-  request: PopupRequest | RedirectRequest;  // MSAL request with scopes
-  behavior?: 'popup' | 'redirect';          // Auth method (default: 'redirect')
-  silent?: boolean;                         // Attempt silent first (default: true if account available)
-};
-```
-
-## `IMsalProvider`
-
-The authentication provider interface available at `framework.auth`:
-
-```typescript
-interface IMsalProvider {
-  // The MSAL PublicClientApplication instance
-  readonly client: IMsalClient;
-  
-  // Current user account information
-  readonly account: AccountInfo | null;
-  
-  // Initialize the MSAL provider
-  initialize(): Promise<void>;
-  
-  // Acquire an access token for the specified scopes
-  acquireAccessToken(options: AcquireTokenOptionsLegacy): Promise<string | undefined>;
-  
-  // Acquire full authentication result
-  acquireToken(options: AcquireTokenOptionsLegacy): Promise<AcquireTokenResult>;
-  
-  // Login user interactively
-  login(options: LoginOptions): Promise<LoginResult>;
-  
-  // Logout user (returns boolean)
-  logout(options?: LogoutOptions): Promise<boolean>;
-  
-  // Handle authentication redirect (returns AuthenticationResult | null)
-  handleRedirect(): Promise<AuthenticationResult | null>;
-}
-
-// Note: defaultAccount and other deprecated v2 properties are available only
-//       when using a v2-compatible proxy via createProxyProvider()
-```

package/docs/auth-code-flow.md

@@ -1,86 +0,0 @@
-# Backend-Issued Auth Code Flow
-
-Enable automatic sign-in using a backend-issued authorization code without interactive login prompts.
-
-## Overview
-
-When your backend authenticates a user and generates a short-lived SPA auth code, the MSAL module can exchange it for tokens during initialization, eliminating double-login issues and providing seamless authentication.
-
-## Usage
-
-```typescript
-import { enableMSAL } from '@equinor/fusion-framework-module-msal';
-
-enableMSAL(configurator, (builder) => {
-  builder.setClientConfig({
-    auth: {
-      clientId: 'your-client-id',
-      tenantId: 'your-tenant-id'
-    }
-  });
-
-  // Backend injects auth code as window.MSAL_AUTH_CODE during initial first page load
-  // This is the most secure approach - only available on first render, cleared after use
-  if (typeof window !== 'undefined' && window.MSAL_AUTH_CODE) {
-    builder.setAuthCode(window.MSAL_AUTH_CODE);
-    delete (window as any).MSAL_AUTH_CODE; // Clear after consuming
-  }
-
-  builder.setRequiresAuth(true);
-});
-```
-
-## How It Works
-
-1. Backend authenticates user and generates short-lived auth code
-2. Frontend passes auth code to MSAL: `builder.setAuthCode(authCode)`
-3. During `initialize()`: auth code exchanged for tokens (before `requiresAuth` check)
-4. Tokens cached by MSAL → user automatically signed in
-5. Falls back to standard MSAL flows on exchange failure
-
-## API: `setAuthCode(authCode?: string)`
-
-Sets backend-issued auth code for token exchange during initialization.
-
-Pass `undefined` to clear/reset a previously configured auth code.
-
-**Returns:** configurator instance (chainable)
-
-**Behavior:**
-- Exchange happens before `requiresAuth` check
-- On success: user auto-authenticated, no login prompt
-- On failure: falls back to standard MSAL login
-- Auth code cleared after exchange (no reuse)
-- `setAuthCode(undefined)` clears configured auth code
-- `setAuthCode('')` is treated as absent auth code
-- `setAuthCode('   ')` is trimmed and treated as absent auth code
-- No auth-code exchange is attempted when auth code is absent/cleared
-
-**Example:**
-
-```typescript
-// Best practice: Backend injects auth code on initial page load as window.MSAL_AUTH_CODE
-if (typeof window !== 'undefined' && window.MSAL_AUTH_CODE) {
-  builder.setAuthCode(window.MSAL_AUTH_CODE);
-  delete (window as any).MSAL_AUTH_CODE; // Clear after consuming to prevent reuse
-}
-
-// Clear/reset auth code when input is missing
-builder.setAuthCode(undefined);
-```
-
-## Security
-
-- ✅ Auth codes: single-use, short-lived (5-10 min)
-- ✅ MSAL validates tokens from Microsoft authority
-- ✅ Tokens stored securely, refresh tokens auto-managed
-- ⚠️ Pass codes securely: HTTPS, HTTP-only cookies, or encrypted channels
-
-## Troubleshooting
-
-| Issue | Solution |
-|-------|----------|
-| Auth code not exchanged | Verify `setAuthCode()` called before init |
-| Invalid auth code error | Confirm backend `WithSpaAuthCode` enabled, code is fresh |
-| Still shows login prompt | Check auth code exchange completes before `requiresAuth` check |
-| Exchange fails | Auth code may have expired; backend should generate fresh code per load |

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

@@ -1,115 +0,0 @@
-# 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

@@ -1,191 +0,0 @@
-# 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

@@ -1,17 +0,0 @@
-# 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

@@ -1,67 +0,0 @@
-# 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);
-  }
-}
-```