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

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-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,29 @@
+/**
+ * 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 { 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/static.d.ts

@@ -3,7 +3,7 @@
  *
  * This constant is used to register and identify the MSAL module within the Fusion Framework.
  */
-export declare const ModuleName: "msal";
+export declare const ModuleName: 'msal';
 /**
  * Enumeration of supported MSAL module versions.
  *

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/v2/IAuthClient.interface.d.ts

@@ -79,7 +79,7 @@ export interface IAuthClient extends IPublicClientApplication {
      * @param silent - Whether to attempt silent authentication first
      * @returns Promise resolving to authentication result or void
      */
-    login(options?: AuthRequest, behavior?: AuthBehavior, silent?: boolean): Promise<AuthenticationResult | void>;
+    login(options?: AuthRequest, behavior?: AuthBehavior, silent?: boolean): Promise<AuthenticationResult | undefined>;
     /**
      * Acquire access token with optional silent authentication fallback
      * @param options - Authentication request options
@@ -87,5 +87,5 @@ export interface IAuthClient extends IPublicClientApplication {
      * @param silent - Whether to attempt silent authentication first
      * @returns Promise resolving to authentication result or void
      */
-    acquireToken(options?: AuthRequest, behavior?: AuthBehavior, silent?: boolean): Promise<AuthenticationResult | void>;
+    acquireToken(options?: AuthRequest, behavior?: AuthBehavior, silent?: boolean): Promise<AuthenticationResult | undefined>;
 }

package/dist/types/v2/Logger.d.ts

@@ -0,0 +1,92 @@
+import { LogLevel, type LoggerOptions } from './types.js';
+/**
+ * Class which facilitates logging of messages to a specific place
+ */
+export declare class Logger {
+    private correlationId;
+    private level;
+    private piiLoggingEnabled;
+    private localCallback;
+    private packageName;
+    private packageVersion;
+    /**
+     * Creates a new `Logger`.
+     *
+     * @param loggerOptions - Logger configuration, including callback, PII, and log level settings.
+     * @param packageName - Name of the package implementing this logger.
+     * @param packageVersion - Version of the package implementing this logger.
+     */
+    constructor(loggerOptions: LoggerOptions, packageName?: string, packageVersion?: string);
+    /**
+     * Creates the default logger options used when none are provided.
+     *
+     * @returns Default logger options with a no-op callback, PII logging disabled, and Info level.
+     */
+    private static createDefaultLoggerOptions;
+    /**
+     * Create new Logger with existing configurations.
+     *
+     * @param packageName - Name of the package implementing this logger.
+     * @param packageVersion - Version of the package implementing this logger.
+     * @param correlationId - Correlation ID to use, falling back to this logger's own if omitted.
+     * @returns A new `Logger` instance cloned from this one.
+     */
+    clone(packageName: string, packageVersion: string, correlationId?: string): Logger;
+    /**
+     * Logs error messages.
+     *
+     * @param message - The message to log.
+     * @param correlationId - Correlation ID to attach to the log entry, if any.
+     */
+    error(message: string, correlationId?: string): void;
+    /**
+     * Logs warning messages.
+     *
+     * @param message - The message to log.
+     * @param correlationId - Correlation ID to attach to the log entry, if any.
+     */
+    warning(message: string, correlationId?: string): void;
+    /**
+     * Logs info messages.
+     *
+     * @param message - The message to log.
+     * @param correlationId - Correlation ID to attach to the log entry, if any.
+     */
+    info(message: string, correlationId?: string): void;
+    /**
+     * Logs verbose messages.
+     *
+     * @param message - The message to log.
+     * @param correlationId - Correlation ID to attach to the log entry, if any.
+     */
+    verbose(message: string, correlationId?: string): void;
+    /**
+     * Logs trace messages.
+     *
+     * @param message - The message to log.
+     * @param correlationId - Correlation ID to attach to the log entry, if any.
+     */
+    trace(message: string, correlationId?: string): void;
+    /**
+     * Returns whether PII Logging is enabled or not.
+     *
+     * @returns `true` when PII logging is enabled, otherwise `false`.
+     */
+    isPiiLoggingEnabled(): boolean;
+    /**
+     * Formats and dispatches a log message to the configured callback, unless it
+     * is below the configured log level or contains PII while PII logging is disabled.
+     *
+     * @param logMessage - The raw message to log.
+     * @param options - Log level, PII flag, and correlation ID for this message.
+     */
+    private logMessage;
+    /**
+     * Execute callback with message.
+     *
+     * @param level - The log level of the message.
+     * @param message - The formatted message to send to the callback.
+     * @param containsPii - Whether the message contains personally identifiable information.
+     */
+    executeCallback(level: LogLevel, message: string, containsPii: boolean): void;
+}

package/dist/types/v2/MsalProvider.interface.d.ts

@@ -81,7 +81,7 @@ export interface IMsalProvider {
     /**
      * Handle authentication redirect
      */
-    handleRedirect(): Promise<void | null>;
+    handleRedirect(): Promise<undefined | null>;
     /**
      * Create a proxy provider for version compatibility
      * @param version - Version string

package/dist/types/v2/types.d.ts

@@ -4,6 +4,7 @@
  * This file contains all types required to type IPublicClientApplication
  * from MSAL v2.38.4 to maintain backward compatibility while using MSAL v4 implementation.
  */
+import type { Logger } from './Logger.js';
 /**
  * Key-Value type to support queryParams, extraQueryParams and claims
  */
@@ -291,9 +292,7 @@ export declare enum LogLevel {
 /**
  * Callback to send the messages to
  */
-export interface ILoggerCallback {
-    (level: LogLevel, message: string, containsPii: boolean): void;
-}
+export type ILoggerCallback = (level: LogLevel, message: string, containsPii: boolean) => void;
 /**
  * Options for logger messages
  */
@@ -303,52 +302,7 @@ export type LoggerOptions = {
     logLevel?: LogLevel;
     correlationId?: string;
 };
-/**
- * Class which facilitates logging of messages to a specific place
- */
-export declare class Logger {
-    private correlationId;
-    private level;
-    private piiLoggingEnabled;
-    private localCallback;
-    private packageName;
-    private packageVersion;
-    constructor(loggerOptions: LoggerOptions, packageName?: string, packageVersion?: string);
-    private static createDefaultLoggerOptions;
-    /**
-     * Create new Logger with existing configurations.
-     */
-    clone(packageName: string, packageVersion: string, correlationId?: string): Logger;
-    /**
-     * Logs error messages.
-     */
-    error(message: string, correlationId?: string): void;
-    /**
-     * Logs warning messages.
-     */
-    warning(message: string, correlationId?: string): void;
-    /**
-     * Logs info messages.
-     */
-    info(message: string, correlationId?: string): void;
-    /**
-     * Logs verbose messages.
-     */
-    verbose(message: string, correlationId?: string): void;
-    /**
-     * Logs trace messages.
-     */
-    trace(message: string, correlationId?: string): void;
-    /**
-     * Returns whether PII Logging is enabled or not.
-     */
-    isPiiLoggingEnabled(): boolean;
-    private logMessage;
-    /**
-     * Execute callback with message.
-     */
-    executeCallback(level: LogLevel, message: string, containsPii: boolean): void;
-}
+export { Logger } from './Logger.js';
 /**
  * Performance event type
  */

package/dist/types/v4/types.d.ts

@@ -395,9 +395,7 @@ export declare enum LogLevel {
 /**
  * Callback to send the messages to
  */
-export interface ILoggerCallback {
-    (level: LogLevel, message: string, containsPii: boolean): void;
-}
+export type ILoggerCallback = (level: LogLevel, message: string, containsPii: boolean) => void;
 /**
  * Event callback function type
  */

package/dist/types/version.d.ts

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

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 |