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

package/src/module.ts

@@ -1,142 +0,0 @@
-import {
-  type Module,
-  type IModulesConfigurator,
-  type ModuleConfigType,
-  SemanticVersion,
-} from '@equinor/fusion-framework-module';
-
-import { MsalConfigurator } from './MsalConfigurator';
-import { MsalProvider, type IMsalProvider } from './MsalProvider';
-
-import { version } from './version';
-
-/**
- * MSAL authentication module configuration.
- *
- * This module provides Microsoft Authentication Library (MSAL) integration for the
- * Fusion Framework, supporting MSAL v4 with backward compatibility for v2 applications.
- */
-export type MsalModule = Module<'auth', IMsalProvider, MsalConfigurator, [MsalModule]>;
-
-/**
- * MSAL authentication module definition.
- *
- * This module manages authentication providers with the following initialization flow:
- * 1. Check for custom provider configuration
- * 2. Check for existing provider in parent module (for proxy compatibility)
- * 3. Create new provider with client configuration
- *
- * @remarks
- * The module supports proxy providers for version compatibility, allowing v4 implementations
- * to work with v2-compatible code during migration periods.
- */
-export const module: MsalModule = {
-  name: 'auth',
-  version: new SemanticVersion(version),
-  configure: () => new MsalConfigurator(),
-  initialize: async (init) => {
-    const config = await init.config.createConfigAsync(init);
-
-    // Priority 1: Use custom provider if explicitly configured
-    if (config.provider) {
-      return config.provider;
-    }
-
-    // Priority 2: Check if provider exists in parent module (proxy compatibility)
-    // This allows child applications to reuse parent's authentication provider
-    const hostProvider = init.ref?.auth;
-    // Reuse the parent's provider (via a version-compatible proxy) when available
-    if (hostProvider) {
-      try {
-        const proxyProvider = hostProvider.createProxyProvider(config.version);
-        return proxyProvider;
-      } catch (error) {
-        console.error('MsalModule::Failed to create proxy provider', error);
-        // Fallback to host provider to prevent app breakage during migration
-        // TODO(#5114): Consider throwing error instead once all apps are migrated to v4
-        return hostProvider;
-      }
-    }
-
-    // Priority 3: Validate client configuration is provided
-    if (!config.client) {
-      throw new Error(
-        'Client configuration is required when provider is not in the parent module nor defined',
-      );
-    }
-
-    // Create new MSAL provider instance
-    const provider = new MsalProvider(config);
-
-    // Initialize the provider (handles redirect callbacks, SSO, etc.)
-    await provider.initialize();
-
-    return provider;
-  },
-};
-
-/**
- * Configuration function type for MSAL module setup.
- *
- * This function receives a builder object with methods to configure the MSAL client
- * and authentication requirements.
- */
-export type AuthConfigFn<TRef = unknown> = (
-  configurator: ModuleConfigType<MsalModule>,
-  ref?: TRef,
-) => void;
-
-/**
- * Enables MSAL authentication module in the framework.
- *
- * This is a convenience function that adds the MSAL module configuration to the
- * framework configurator with optional configuration callback.
- *
- * @param configurator - The framework modules configurator instance
- * @param configure - Optional configuration callback for MSAL setup
- *
- * @example
- * ```typescript
- * enableMSAL(frameworkConfigurator, (builder) => {
- *   builder.setClientConfig({
- *     auth: { clientId: 'your-client-id', tenantId: 'your-tenant-id' }
- *   });
- *   builder.setRequiresAuth(true);
- * });
- * ```
- */
-export const enableMSAL = (
-  // biome-ignore lint/suspicious/noExplicitAny: must be any to support all module types
-  configurator: IModulesConfigurator<any, any>,
-  configure?: AuthConfigFn,
-): void => {
-  const config = configure ? configureMsal(configure) : { module };
-  configurator.addConfig(config);
-};
-
-/**
- * Creates MSAL module configuration with custom setup.
- *
- * @param configure - Configuration callback function
- * @returns Module configuration object ready for framework integration
- *
- * @example
- * ```typescript
- * const msalConfig = configureMsal((builder) => {
- *   builder.setClientConfig(msalClientConfig);
- *   builder.setRequiresAuth(true);
- * });
- * ```
- */
-export const configureMsal = (configure: AuthConfigFn) => ({
-  module,
-  configure,
-});
-
-declare module '@equinor/fusion-framework-module' {
-  interface Modules {
-    auth: MsalModule;
-  }
-}
-
-export default module;

package/src/msal-config-schema.ts

@@ -1,81 +0,0 @@
-import z from 'zod';
-import semver from 'semver';
-import { CacheLookupPolicy } from '@azure/msal-browser';
-
-import type { IMsalClient } from './MsalClient.interface';
-import type { IMsalProvider } from './MsalProvider.interface';
-import { TelemetryConfigSchema } from './telemetry-config-schema';
-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 const MsalConfigSchema = z.object({
-  client: z.custom<IMsalClient>().optional(),
-  provider: z.custom<IMsalProvider>().optional(),
-  requiresAuth: z.boolean().optional(),
-  redirectUri: z.string().optional(),
-  loginHint: z.string().optional(),
-  authCode: z.string().optional(),
-  cacheLookupPolicy: z
-    .custom<CacheLookupPolicy>(
-      (val) =>
-        typeof val === 'number' &&
-        Object.values(CacheLookupPolicy).includes(val as CacheLookupPolicy),
-    )
-    .optional(),
-  version: z.string().transform((value, ctx) => {
-    const coerced = semver.coerce(value);
-    // `semver.coerce` returns `null` for an unparseable version; without this guard it
-    // would silently become the literal string "null" instead of failing validation.
-    if (!coerced) {
-      ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Invalid MSAL module version' });
-      return z.NEVER;
-    }
-    return coerced.version;
-  }),
-  telemetry: TelemetryConfigSchema,
-});
-
-/**
- * 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.
- */
-// biome-ignore lint/suspicious/noEmptyInterface: the extension point is the point
-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/src/static.ts

@@ -1,38 +0,0 @@
-/**
- * Module identifier for the MSAL authentication module.
- *
- * This constant is used to register and identify the MSAL module within the Fusion Framework.
- */
-export const ModuleName = 'msal' as const;
-
-/**
- * Enumeration of supported MSAL module versions.
- *
- * This enum defines the available MSAL versions and provides type-safe access to version identifiers.
- *
- * @remarks
- * - `V2`: MSAL v2 compatibility (legacy support)
- * - `V4`: MSAL v4 compatibility (supports @azure/msal-browser 4.x)
- * - `V5`: MSAL v5 compatibility (supports @azure/msal-browser 5.x)
- *
- * @example
- * ```typescript
- * import { MsalModuleVersion } from '@equinor/fusion-framework-module-msal';
- *
- * // Check version
- * if (version === MsalModuleVersion.V5) {
- *   console.log('Using MSAL v5 compatible version');
- * }
- *
- * // Create version-specific proxy
- * const proxy = provider.createProxyProvider(MsalModuleVersion.V2);
- * ```
- */
-export enum MsalModuleVersion {
-  /** MSAL v2 compatibility version (legacy support) */
-  V2 = 'v2',
-  /** MSAL v4 compatibility version (supports @azure/msal-browser 4.x) */
-  V4 = 'v4',
-  /** MSAL v5 compatibility version (supports @azure/msal-browser 5.x) */
-  V5 = 'v5',
-}

package/src/telemetry-config-schema.ts

@@ -1,25 +0,0 @@
-import z from 'zod';
-import type { ITelemetryProvider } from '@equinor/fusion-framework-module-telemetry';
-import { version } from './version';
-
-/**
- * Zod schema for telemetry configuration validation.
- *
- * @internal
- */
-export const TelemetryConfigSchema = z.object({
-  provider: z.custom<ITelemetryProvider>().optional(),
-  metadata: z.record(z.string(), z.unknown()).optional().default({
-    module: 'msal',
-    version,
-  }),
-  scope: z.array(z.string()).optional().default(['framework', 'authentication']),
-});
-
-/**
- * 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/src/types.ts

@@ -1,16 +0,0 @@
-/**
- * Re-exports of core MSAL types from @azure/msal-browser.
- *
- * This module provides convenient access to commonly used MSAL types without
- * requiring direct imports from @azure/msal-browser. These types represent
- * fundamental authentication entities used throughout the MSAL module.
- *
- * @module
- */
-
-export {
-  /** Represents account information for an authenticated user */
-  AccountInfo,
-  /** Represents the result of an authentication operation including tokens and account */
-  AuthenticationResult,
-} from '@azure/msal-browser';

package/src/util/compare-origin.ts

@@ -1,18 +0,0 @@
-import { normalizeUri } from './normalize-uri';
-
-/**
- * Compares two URIs after normalizing them to their canonical form.
- *
- * Both values are passed through {@link normalizeUri} before comparison, so relative
- * paths, double slashes, and trailing slashes are handled transparently.
- *
- * @internal
- *
- * @param a - First URI or relative path
- * @param b - Second URI or relative path
- * @returns `true` when both URIs resolve to the same normalized string
- */
-export const compareOrigin = (a: string, b: string): boolean => {
-  const url = { a: normalizeUri(a), b: normalizeUri(b) };
-  return url.a === url.b;
-};

package/src/util/normalize-uri.ts

@@ -1,24 +0,0 @@
-/**
- * Creates and normalizes a redirect URI.
- *
- * Resolves relative paths against the provided base URL and strips double and trailing slashes
- * from the resulting pathname. Used internally to sanitize redirect URIs before passing them
- * to MSAL authentication flows.
- *
- * @internal
- *
- * @param uri - Relative path (e.g. `/callback`) or absolute URL (e.g. `https://app.com/callback`)
- * @param home - Base URL for resolving relative paths. Defaults to `window.location.origin`.
- * @returns Fully-qualified, normalized URI string
- *
- * @example
- * ```typescript
- * normalizeUri('/callback');                  // https://current-origin.com/callback
- * normalizeUri('https://app.com//callback/'); // https://app.com/callback
- * ```
- */
-export const normalizeUri = (uri: string, home: string = window.location.origin): string => {
-  uri = uri.match(/^http[s]?/) ? uri : home + uri;
-  const { origin, pathname } = new URL(uri);
-  return origin + pathname.replace(/([^:]\/)\/+/g, '$1');
-};

package/src/util/redirect.ts

@@ -1,19 +0,0 @@
-/**
- * Redirects the browser to the specified URL.
- *
- * If the browser has not navigated away within the given timeout, the returned
- * promise is rejected. This acts as a safeguard against redirect failures.
- *
- * @internal
- *
- * @param url - Endpoint to navigate to
- * @param timeout - Maximum milliseconds to wait before considering the redirect failed. Defaults to `3000`.
- * @param history - When `true`, uses `location.assign()` so the current page is kept in browser history.
- *   Otherwise uses `location.replace()` which replaces the current history entry.
- * @returns A promise that rejects after the timeout (it never resolves because a successful redirect
- *   causes the page to unload)
- */
-export const redirect = (url: string, timeout = 3000, history?: boolean): Promise<void> => {
-  history ? window.location.assign(url) : window.location.replace(url);
-  return new Promise((_, reject) => setTimeout(reject, timeout));
-};

package/src/v2/IAuthClient.interface.ts

@@ -1,114 +0,0 @@
-import type {
-  AccountInfo as AccountInfoBase,
-  AuthenticationResult,
-  IPublicClientApplication,
-} from './types';
-
-/**
- * Simplified ID token claims used by the v2 compatibility layer.
- *
- * @property aud - Token audience (application ID)
- * @property exp - Token expiration time (seconds since epoch)
- */
-export type IdTokenClaims = {
-  aud: string;
-  exp: number;
-};
-
-/**
- * Extended account information for v2 compatibility.
- *
- * Augments the base v2 `AccountInfo` with typed ID token claims.
- */
-export type AccountInfo = AccountInfoBase & {
-  idTokenClaims?: IdTokenClaims;
-};
-
-/**
- * Authentication behavior type for v2-compatible login and token flows.
- *
- * - `'popup'` — Opens a popup window for authentication
- * - `'redirect'` — Navigates the browser to the Microsoft login page
- */
-export type AuthBehavior = 'popup' | 'redirect';
-
-/**
- * Simplified authentication request for v2-compatible methods.
- *
- * @property scopes - Optional OAuth scopes to request (e.g. `['User.Read']`)
- * @property loginHint - Optional username hint to pre-fill the login form
- */
-export type AuthRequest = {
-  scopes?: string[];
-  loginHint?: string;
-};
-
-/**
- * Interface for MSAL v2 compatible authentication client.
- *
- * This interface defines the contract for authentication clients that maintain
- * backward compatibility with MSAL v2 API while using MSAL v4 implementation
- * under the hood. This is useful for gradual migration scenarios.
- *
- * @example
- * ```typescript
- * const client: IAuthClient_v2 = createProxyClient(baseClient);
- *
- * // Use v2 compatible API
- * const account = client.account;
- * const result = await client.login({ scopes: ['User.Read'] });
- * ```
- */
-export interface IAuthClient extends IPublicClientApplication {
-  /**
-   * Tenant ID for the client domain
-   */
-  readonly tenantId: string;
-
-  /**
-   * Returns account for client tenant that MSAL currently has data for.
-   * (the account object is created at the time of successful login)
-   */
-  get account(): AccountInfo | undefined;
-
-  /**
-   * Check if the current account has valid claims
-   */
-  get hasValidClaims(): boolean;
-
-  /**
-   * Configured client ID
-   */
-  get clientId(): string | undefined;
-
-  /**
-   * Request origin from browser storage
-   */
-  get requestOrigin(): string | null;
-
-  /**
-   * Login user with optional silent authentication fallback
-   * @param options - Optional authentication request options
-   * @param behavior - Authentication method: 'popup' or 'redirect'
-   * @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 | undefined>;
-
-  /**
-   * Acquire access token with optional silent authentication fallback
-   * @param options - Authentication request options
-   * @param behavior - Authentication method: 'popup' or 'redirect'
-   * @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 | undefined>;
-}

package/src/v2/Logger.ts

@@ -1,204 +0,0 @@
-import { LogLevel, type ILoggerCallback, type LoggerOptions } from './types.js';
-
-/**
- * Class which facilitates logging of messages to a specific place
- */
-export class Logger {
-  // Correlation ID for request, usually set by user.
-  private correlationId: string;
-
-  // Current log level, defaults to info.
-  private level: LogLevel = LogLevel.Info;
-
-  // Boolean describing whether PII logging is allowed.
-  private piiLoggingEnabled: boolean;
-
-  // Callback to send messages to.
-  private localCallback: ILoggerCallback;
-
-  // Package name implementing this logger
-  private packageName: string;
-
-  // Package version implementing this logger
-  private packageVersion: string;
-
-  /**
-   * 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) {
-    const defaultLoggerCallback = () => {
-      return;
-    };
-    const setLoggerOptions = loggerOptions || Logger.createDefaultLoggerOptions();
-    this.localCallback = setLoggerOptions.loggerCallback || defaultLoggerCallback;
-    this.piiLoggingEnabled = setLoggerOptions.piiLoggingEnabled || false;
-    this.level =
-      typeof setLoggerOptions.logLevel === 'number' ? setLoggerOptions.logLevel : LogLevel.Info;
-    this.correlationId = setLoggerOptions.correlationId || '';
-    this.packageName = packageName || '';
-    this.packageVersion = packageVersion || '';
-  }
-
-  /**
-   * 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(): LoggerOptions {
-    return {
-      loggerCallback: () => {
-        // allow users to not set loggerCallback
-      },
-      piiLoggingEnabled: false,
-      logLevel: LogLevel.Info,
-    };
-  }
-
-  /**
-   * 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.
-   */
-  public clone(packageName: string, packageVersion: string, correlationId?: string): Logger {
-    return new Logger(
-      {
-        loggerCallback: this.localCallback,
-        piiLoggingEnabled: this.piiLoggingEnabled,
-        logLevel: this.level,
-        correlationId: correlationId || this.correlationId,
-      },
-      packageName,
-      packageVersion,
-    );
-  }
-
-  /**
-   * 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 {
-    this.logMessage(message, {
-      logLevel: LogLevel.Error,
-      containsPii: false,
-      correlationId: correlationId || '',
-    });
-  }
-
-  /**
-   * 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 {
-    this.logMessage(message, {
-      logLevel: LogLevel.Warning,
-      containsPii: false,
-      correlationId: correlationId || '',
-    });
-  }
-
-  /**
-   * 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 {
-    this.logMessage(message, {
-      logLevel: LogLevel.Info,
-      containsPii: false,
-      correlationId: correlationId || '',
-    });
-  }
-
-  /**
-   * 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 {
-    this.logMessage(message, {
-      logLevel: LogLevel.Verbose,
-      containsPii: false,
-      correlationId: correlationId || '',
-    });
-  }
-
-  /**
-   * 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 {
-    this.logMessage(message, {
-      logLevel: LogLevel.Trace,
-      containsPii: false,
-      correlationId: correlationId || '',
-    });
-  }
-
-  /**
-   * Returns whether PII Logging is enabled or not.
-   *
-   * @returns `true` when PII logging is enabled, otherwise `false`.
-   */
-  isPiiLoggingEnabled(): boolean {
-    return this.piiLoggingEnabled || false;
-  }
-
-  /**
-   * 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(
-    logMessage: string,
-    options: {
-      logLevel: LogLevel;
-      containsPii: boolean;
-      correlationId: string;
-    },
-  ): void {
-    // Skip messages below the configured level or containing PII when PII logging is disabled
-    if (options.logLevel > this.level || (!this.piiLoggingEnabled && options.containsPii)) {
-      return;
-    }
-    const timestamp = new Date().toUTCString();
-
-    // Add correlationId to logs if set, correlationId provided on log messages take precedence
-    const logHeader = `[${timestamp}] : [${options.correlationId || this.correlationId || ''}]`;
-
-    const log = `${logHeader} : ${this.packageName}@${
-      this.packageVersion
-    } : ${LogLevel[options.logLevel]} - ${logMessage}`;
-    this.executeCallback(options.logLevel, log, options.containsPii || false);
-  }
-
-  /**
-   * 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 {
-    // Only invoke the callback when one has been configured
-    if (this.localCallback) {
-      this.localCallback(level, message, containsPii);
-    }
-  }
-}