@equinor/fusion-framework-module-msal 10.0.0 → 10.0.2

package/src/v2/Logger.ts

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

package/src/v2/MsalProvider.interface.ts

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

package/src/v2/create-proxy-client.ts

@@ -28,9 +28,11 @@ import type { AccountInfo } from './types';
 export function createProxyClient(client: IMsalClient): IAuthClient {
   const proxy = new Proxy(client, {
     get: (target: IMsalClient, prop: keyof IAuthClient) => {
+      // Adapt each v4 client member to the v2-compatible shape expected by callers
       switch (prop) {
         case 'getAllAccounts': {
           return () => {
+            // Map each v4 account shape to its v2-compatible equivalent
             return target.getAllAccounts().map(mapAccountInfo);
           };
         }
@@ -69,6 +71,7 @@ export function createProxyClient(client: IMsalClient): IAuthClient {
           return async () => {
             const result = await target.handleRedirectPromise();
 
+            // No redirect result means there's nothing pending to map
             if (!result) {
               return null;
             }
@@ -80,6 +83,7 @@ export function createProxyClient(client: IMsalClient): IAuthClient {
         case 'getActiveAccount': {
           return () => {
             const account = target.getActiveAccount();
+            // No active account means there's nothing to map
             if (!account) {
               return null;
             }
@@ -185,5 +189,7 @@ export function createProxyClient(client: IMsalClient): IAuthClient {
     },
   });
 
+  // The Proxy handler above implements every member of `IAuthClient` at runtime via its `get`
+  // trap, but TypeScript can't verify a `Proxy<T>` satisfies `T` structurally.
   return proxy as unknown as IAuthClient;
 }

package/src/v2/create-proxy-provider.ts

@@ -13,6 +13,7 @@ import { MsalModuleVersion } from '../static';
  * @returns True if the request is in v4 format (has a `request` property with `scopes` and `account`)
  */
 function isRequestV4(req: unknown): req is AcquireTokenOptions {
+  // Non-object/null values can never match the v4 request shape
   if (typeof req !== 'object' || req === null) {
     return false;
   }
@@ -48,6 +49,7 @@ export function createProxyProvider(provider: IMsalProvider): IMsalProvider_v2 {
   // Use Proxy to intercept property access and provide v2-compatible implementations
   const proxy = new Proxy(provider, {
     get: (target: IMsalProvider, prop: keyof IMsalProvider_v2) => {
+      // Adapt each v4 provider member to the v2-compatible shape expected by callers
       switch (prop) {
         case 'version': {
           return provider.version;
@@ -62,6 +64,7 @@ export function createProxyProvider(provider: IMsalProvider): IMsalProvider_v2 {
         case 'defaultClient': {
           // Deprecated property - redirect to client with warning
           console.warn('defaultClient is deprecated, use client instead');
+          // Same v2-compatible client wrapper as the `client` case above.
           return v2Client as unknown as IMsalProvider_v2['defaultClient'];
         }
         case 'defaultAccount': {
@@ -156,6 +159,7 @@ export function createProxyProvider(provider: IMsalProvider): IMsalProvider_v2 {
           };
         }
         default: {
+          // The proxy is awaited in some contexts, so `then` must resolve to undefined
           if (prop === 'then') {
             return undefined;
           }

package/src/v2/types.ts

@@ -5,6 +5,8 @@
  * from MSAL v2.38.4 to maintain backward compatibility while using MSAL v4 implementation.
  */
 
+import type { Logger } from './Logger.js';
+
 // ============================================================================
 // Basic Types
 // ============================================================================
@@ -287,6 +289,7 @@ export type RedirectRequest = Partial<
 > & {
   scopes: Array<string>;
   redirectStartPage?: string;
+  // biome-ignore lint/suspicious/noConfusingVoidType: `void` here relies on TypeScript's special-cased "void-returning callback accepts any return value" behavior — `undefined` would break assignability of navigate functions that return a value/promise
   onRedirectNavigate?: (url: string) => boolean | void;
   tokenBodyParameters?: StringDict;
 };
@@ -334,6 +337,7 @@ export type SsoSilentRequest = Partial<
  */
 export type EndSessionRequest = Partial<Omit<CommonEndSessionRequest, 'tokenQueryParameters'>> & {
   authority?: string;
+  // biome-ignore lint/suspicious/noConfusingVoidType: `void` here relies on TypeScript's special-cased "void-returning callback accepts any return value" behavior — `undefined` would break assignability of navigate functions that return a value/promise
   onRedirectNavigate?: (url: string) => boolean | void;
 };
 
@@ -390,9 +394,7 @@ export 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
@@ -404,161 +406,9 @@ export type LoggerOptions = {
   correlationId?: string;
 };
 
-/**
- * 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;
-
-  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 || '';
-  }
-
-  private static createDefaultLoggerOptions(): LoggerOptions {
-    return {
-      loggerCallback: () => {
-        // allow users to not set loggerCallback
-      },
-      piiLoggingEnabled: false,
-      logLevel: LogLevel.Info,
-    };
-  }
-
-  /**
-   * Create new Logger with existing configurations.
-   */
-  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.
-   */
-  error(message: string, correlationId?: string): void {
-    this.logMessage(message, {
-      logLevel: LogLevel.Error,
-      containsPii: false,
-      correlationId: correlationId || '',
-    });
-  }
-
-  /**
-   * Logs warning messages.
-   */
-  warning(message: string, correlationId?: string): void {
-    this.logMessage(message, {
-      logLevel: LogLevel.Warning,
-      containsPii: false,
-      correlationId: correlationId || '',
-    });
-  }
-
-  /**
-   * Logs info messages.
-   */
-  info(message: string, correlationId?: string): void {
-    this.logMessage(message, {
-      logLevel: LogLevel.Info,
-      containsPii: false,
-      correlationId: correlationId || '',
-    });
-  }
-
-  /**
-   * Logs verbose messages.
-   */
-  verbose(message: string, correlationId?: string): void {
-    this.logMessage(message, {
-      logLevel: LogLevel.Verbose,
-      containsPii: false,
-      correlationId: correlationId || '',
-    });
-  }
-
-  /**
-   * Logs trace messages.
-   */
-  trace(message: string, correlationId?: string): void {
-    this.logMessage(message, {
-      logLevel: LogLevel.Trace,
-      containsPii: false,
-      correlationId: correlationId || '',
-    });
-  }
-
-  /**
-   * Returns whether PII Logging is enabled or not.
-   */
-  isPiiLoggingEnabled(): boolean {
-    return this.piiLoggingEnabled || false;
-  }
-
-  private logMessage(
-    logMessage: string,
-    options: {
-      logLevel: LogLevel;
-      containsPii: boolean;
-      correlationId: string;
-    },
-  ): void {
-    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.
-   */
-  executeCallback(level: LogLevel, message: string, containsPii: boolean): void {
-    if (this.localCallback) {
-      this.localCallback(level, message, containsPii);
-    }
-  }
-}
+// Re-exported from its own file to satisfy single-export-per-file while
+// preserving this file's existing public export surface.
+export { Logger } from './Logger.js';
 
 // ============================================================================
 // Performance Types

package/src/v4/create-proxy-provider.ts

@@ -23,6 +23,7 @@ export function createProxyProvider(provider: IMsalProvider): IMsalProvider {
   // Create passthrough proxy that only overrides msalVersion
   return new Proxy(provider, {
     get: (target: IMsalProvider, prop: keyof IMsalProvider) => {
+      // Passthrough every property except msalVersion, which reports V4 compatibility
       switch (prop) {
         case 'msalVersion': {
           // Report as V4 for compatibility tracking

package/src/v4/types.ts

@@ -317,6 +317,7 @@ export type RedirectRequest = {
   sid?: string;
   account?: AccountInfo;
   redirectStartPage?: string;
+  // biome-ignore lint/suspicious/noConfusingVoidType: `void` here relies on TypeScript's special-cased "void-returning callback accepts any return value" behavior — `undefined` would break assignability of navigate functions that return a value/promise
   onRedirectNavigate?: (url: string) => boolean | void;
   authenticationScheme?: AuthenticationScheme;
   resourceRequestMethod?: string;
@@ -393,6 +394,7 @@ export type EndSessionRequest = {
   state?: string;
   logoutHint?: string;
   extraQueryParameters?: StringDict;
+  // biome-ignore lint/suspicious/noConfusingVoidType: `void` here relies on TypeScript's special-cased "void-returning callback accepts any return value" behavior — `undefined` would break assignability of navigate functions that return a value/promise
   onRedirectNavigate?: (url: string) => boolean | void;
 };
 
@@ -468,9 +470,7 @@ export 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 Types

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '10.0.0';
+export const version = '10.0.2';

package/src/versioning/resolve-version.ts

@@ -31,12 +31,15 @@ import { version as latestVersionString } from '../version';
 function mapVersionToEnumVersion(version: string | SemVer): MsalModuleVersion {
   console.log('Resolving version:', version);
   const coercedVersion = semver.coerce(version);
+  // An uncoercible version string cannot be mapped to a module version
   if (!coercedVersion) {
     throw new Error(`Invalid version: ${version}`);
   }
+  // Versions before 4.0.0 (including 2.x) map to the v2-compatible module version
   if (semver.satisfies(coercedVersion, '<4.0.0')) {
     return MsalModuleVersion.V2;
   }
+  // Versions before 7.0.0 (4.x and 5.x/6.x) map to the v4-compatible module version
   if (semver.satisfies(coercedVersion, '<7.0.0')) {
     return MsalModuleVersion.V4;
   }
@@ -113,6 +116,7 @@ export function resolveVersion(version?: string | SemVer): ResolvedVersion {
     wantedVersion = latestVersion;
   }
 
+  // Warn when the requested major version trails the latest major version
   if (wantedVersion.major < latestVersion.major) {
     const majorBehindVersionWarning = new VersionError(
       `Requested major version ${wantedVersion.major} is behind the latest major version ${latestVersion.major}`,