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

package/dist/types/mock/create-mock-token.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Claims that can be set on a generated mock token.
+ *
+ * @remarks
+ * Mirrors the subset of Entra ID claims that Fusion applications read. Any
+ * additional claims are passed through unchanged.
+ */
+export interface MockTokenClaims {
+    /** Object ID of the signed-in user. */
+    oid?: string;
+    /** Display name of the signed-in user. */
+    name?: string;
+    /** UPN / email of the signed-in user. */
+    preferred_username?: string;
+    /** Tenant the token was issued for. */
+    tid?: string;
+    /** Audience — normally the client or resource the token is intended for. */
+    aud?: string;
+    /** Issuer. */
+    iss?: string;
+    /** Scopes granted, space-separated as in a real Entra ID token. */
+    scp?: string;
+    /** Issued-at, seconds since epoch. */
+    iat?: number;
+    /** Not-before, seconds since epoch. */
+    nbf?: number;
+    /** Expiry, seconds since epoch. */
+    exp?: number;
+    [claim: string]: unknown;
+}
+/**
+ * Creates a structurally valid, unsigned JWT for use in tests.
+ *
+ * The token has three base64url segments and decodes to the supplied claims, so
+ * code that splits, decodes, or inspects token claims behaves exactly as it does
+ * in production. The signature segment is a fixed placeholder — the token is
+ * **not** cryptographically valid and will be rejected by any real service.
+ *
+ * @remarks
+ * Timestamps default to a fixed issue time and a one-hour lifetime so repeated
+ * runs produce byte-identical tokens. A test that needs an expired token can set
+ * `exp` in the past.
+ *
+ * @param claims - Claims to embed in the token payload.
+ * @returns An unsigned JWT string in `header.payload.signature` form.
+ *
+ * @example
+ * ```typescript
+ * const token = createMockToken({ name: 'Test User', scp: 'Files.Read' });
+ * const [, payload] = token.split('.');
+ * JSON.parse(decodeJwtSegment(payload)).name; // 'Test User'
+ * ```
+ */
+export declare const createMockToken: (claims?: MockTokenClaims) => string;

package/dist/types/mock/create-mock-user-from-token.d.ts

@@ -0,0 +1,25 @@
+import type { MsalMockUser } from './MsalMockClient';
+/**
+ * Derives a {@link MsalMockUser} from a JWT's payload claims, so a token minted
+ * outside this module (e.g. by a backend's own mock) can drive who the mock
+ * signs in as.
+ *
+ * @remarks
+ * Maps the standard Entra ID claims Fusion applications read — `name`,
+ * `preferred_username`, `oid`, `tid`, `scp` — onto the matching
+ * {@link MsalMockUser} fields. Identity only: it does not affect which token
+ * the client returns — use {@link MsalMockConfigurator.setToken} for that.
+ *
+ * @param token - A JWT (e.g. from {@link createMockToken}, or issued by an
+ * external mock) with a base64url-encoded payload segment.
+ * @returns A mock user built from the token's claims.
+ * @throws When the token has no payload segment (`header.payload.signature`).
+ *
+ * @example
+ * ```typescript
+ * enableMsalMock(configurator, (builder) => {
+ *   builder.setAccount(createMockUserFromToken(token));
+ * });
+ * ```
+ */
+export declare const createMockUserFromToken: (token: string) => MsalMockUser;

package/dist/types/mock/create-msal-mock-client.d.ts

@@ -0,0 +1,14 @@
+import type { IMsalClient } from '../MsalClient.interface';
+import type { MsalClientConfig } from '../MsalClient';
+import { type MsalMockUser } from './MsalMockClient';
+/**
+ * Convenience helper that creates a mock client instance.
+ *
+ * @remarks
+ * The class form is preferred for a more familiar configuration pattern.
+ *
+ * @param config - The same client configuration the real client is built from.
+ * @param user - Optional user to sign in, applied after construction.
+ * @returns A client that resolves tokens in-process.
+ */
+export declare const createMsalMockClient: (config: MsalClientConfig, user?: MsalMockUser) => IMsalClient;

package/dist/types/mock/decode-jwt-segment.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Decodes a base64url segment of a {@link createMockToken} JWT back to its JSON string.
+ *
+ * @remarks
+ * Plain `atob` alone mangles non-ASCII claims: it treats its output as latin1,
+ * while segments are UTF-8 encoded. This reverses that encoding and also
+ * restores the standard base64 alphabet/padding `atob` expects.
+ *
+ * @param segment - A base64url segment, e.g. from splitting a JWT on `.`.
+ * @returns The decoded UTF-8 string.
+ */
+export declare function decodeJwtSegment(segment: string): string;
+export default decodeJwtSegment;

package/dist/types/mock/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Mock MSAL for tests: real provider, real configurator, fake client.
+ *
+ * @remarks
+ * Substituting the client is the smallest change that removes Entra ID from a test.
+ * Everything above it — scope resolution, silent-first token acquisition, account
+ * handling, proxy providers, telemetry — is the production code path.
+ *
+ * @example
+ * ```typescript
+ * import { enableMsalMock } from '@equinor/fusion-framework-module-msal/mock';
+ *
+ * // default mock user
+ * enableMsalMock(configurator);
+ *
+ * // or a specific one
+ * enableMsalMock(configurator, (builder) => {
+ *   builder.setAccount({ name: 'Ada Lovelace', signedOut: true });
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { MsalMockClient, type MsalMockUser } from './MsalMockClient';
+export { createMsalMockClient } from './create-msal-mock-client';
+export { MsalMockConfigurator } from './MsalMockConfigurator';
+export { enableMsalMock, msalMockModule, type AuthConfigMockFn } from './module';
+export { createMockToken, type MockTokenClaims } from './create-mock-token';
+export { createMockUserFromToken } from './create-mock-user-from-token';
+export { decodeJwtSegment } from './decode-jwt-segment';

package/dist/types/mock/module.d.ts

@@ -0,0 +1,35 @@
+import type { IModulesConfigurator } from '@equinor/fusion-framework-module';
+import { type MsalModule } from '../module';
+import { MsalMockConfigurator } from './MsalMockConfigurator';
+/**
+ * The MSAL module with a mock client instead of a live connection to Entra ID.
+ *
+ * @remarks
+ * Only `configure` differs from the real module. `initialize` is the production
+ * one, untouched, so proxy providers, host-provider hoisting and provider
+ * initialization all behave exactly as they do in production — and a test
+ * observes the real start-up path rather than a rehearsal of it.
+ */
+export declare const msalMockModule: MsalModule;
+/**
+ * Configuration callback for {@link enableMsalMock}.
+ */
+export type AuthConfigMockFn<TRef = unknown> = (configurator: MsalMockConfigurator, ref?: TRef) => void;
+/**
+ * Enables MSAL against a mock client, so a test needs no credentials and no network.
+ *
+ * @remarks
+ * Registered last, this replaces whichever auth module the configurator already
+ * carries, so it works on a `FrameworkConfigurator` that pre-registers the real one.
+ *
+ * @param configurator - The modules configurator to register on.
+ * @param configure - Optional callback to override the default mock client.
+ *
+ * @example
+ * ```typescript
+ * enableMsalMock(configurator, (builder) => {
+ *   builder.setAccount({ name: 'Ada Lovelace' });
+ * });
+ * ```
+ */
+export declare const enableMsalMock: (configurator: IModulesConfigurator<any, any>, configure?: AuthConfigMockFn) => void;

package/dist/types/msal-config-schema.d.ts

@@ -0,0 +1,64 @@
+import z from 'zod';
+import { CacheLookupPolicy } from '@azure/msal-browser';
+import type { IMsalClient } from './MsalClient.interface';
+import type { IMsalProvider } from './MsalProvider.interface';
+export type { TelemetryConfig } from './telemetry-config-schema';
+/**
+ * Zod schema for MSAL module configuration validation.
+ *
+ * @remarks
+ * Kept in its own module so the configuration can be extended at its source.
+ * The schema itself describes what reaches `MsalProvider` and strips anything
+ * else; keys a variant of this module needs only while the configuration is
+ * being built are declared on {@link MsalConfigExtension} instead.
+ */
+export declare const MsalConfigSchema: z.ZodObject<{
+    client: z.ZodOptional<z.ZodCustom<IMsalClient, IMsalClient>>;
+    provider: z.ZodOptional<z.ZodCustom<IMsalProvider, IMsalProvider>>;
+    requiresAuth: z.ZodOptional<z.ZodBoolean>;
+    redirectUri: z.ZodOptional<z.ZodString>;
+    loginHint: z.ZodOptional<z.ZodString>;
+    authCode: z.ZodOptional<z.ZodString>;
+    cacheLookupPolicy: z.ZodOptional<z.ZodCustom<CacheLookupPolicy, CacheLookupPolicy>>;
+    version: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    telemetry: z.ZodObject<{
+        provider: z.ZodOptional<z.ZodCustom<import("@equinor/fusion-framework-module-telemetry").ITelemetryProvider, import("@equinor/fusion-framework-module-telemetry").ITelemetryProvider>>;
+        metadata: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        scope: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * Configuration a variant of this module adds to {@link MsalConfig}.
+ *
+ * @remarks
+ * Empty by design: production MSAL configuration is exactly the schema. This
+ * exists so a variant — the test double in `./mock`, for instance — can declare
+ * its own branch of the configuration through declaration merging:
+ *
+ * ```typescript
+ * declare module '@equinor/fusion-framework-module-msal' {
+ *   interface MsalConfigExtension {
+ *     mock?: { account?: MsalMockUser };
+ *   }
+ * }
+ * ```
+ *
+ * That is what keeps `BaseConfigBuilder._set` honest about the added key. Its
+ * target is a dot-path union derived from {@link MsalConfig}, so a key the type
+ * does not know about can only be set by casting past the builder — and a
+ * generic configurator cannot help, because a dot-path union over an unresolved
+ * type parameter defers, taking every existing literal path down with it.
+ *
+ * The key exists to carry a declaration across the builder, not to reach the
+ * provider: the schema strips it during validation, so it is readable from the
+ * raw configuration and absent from the validated one.
+ */
+export interface MsalConfigExtension {
+}
+/**
+ * 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> & MsalConfigExtension;

package/dist/types/telemetry-config-schema.d.ts

@@ -0,0 +1,8 @@
+import z from 'zod';
+/**
+ * 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>;

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "10.0.2";
+export declare const version = "11.0.0-next.1";

package/docs/api-reference.md

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

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

@@ -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