@equinor/fusion-framework-module-msal-node 0.1.0

package/src/AuthConfigurator.interface.ts

@@ -0,0 +1,163 @@
+import type { PublicClientApplication } from '@azure/msal-node';
+
+import type { IAuthProvider } from './AuthProvider.interface.js';
+
+/**
+ * Represents the configuration for authentication in "token only" mode.
+ *
+ * @property mode - Specifies the authentication mode as 'token_only'.
+ * @property accessToken - The authentication token to be used.
+ * @property parent - An optional reference to a parent authentication provider.
+ */
+type AuthConfigTokenMode = {
+  mode: 'token_only';
+  accessToken: string;
+  client?: never;
+  server?: never;
+  parent?: IAuthProvider;
+};
+
+/**
+ * Configuration type for silent authentication mode.
+ *
+ * @property mode - Specifies the authentication mode as 'silent'.
+ * @property client - An instance of `PublicClientApplication` used for authentication.
+ * @property parent - An optional parent `IAuthProvider` instance for delegation.
+ */
+type AuthConfigSilentMode = {
+  mode: 'silent';
+  client: PublicClientApplication;
+  server?: never;
+  accessToken?: never;
+  parent?: IAuthProvider;
+};
+
+/**
+ * Configuration type for the interactive authentication mode.
+ *
+ * @property mode - Specifies the authentication mode as 'interactive'.
+ * @property client - An instance of `PublicClientApplication` used for authentication.
+ * @property server - Configuration for the local server used during the interactive authentication process.
+ * @property server.port - The port number on which the local server will run.
+ * @property server.onOpen - An optional callback function that is invoked with the authentication URL when the server starts.
+ * @property parent - An optional parent `IAuthProvider` instance for delegation or chaining of authentication providers.
+ */
+type AuthConfigInteractiveMode = {
+  mode: 'interactive';
+  client: PublicClientApplication;
+  server: {
+    port: number;
+    onOpen?: (url: string) => void;
+  };
+  accessToken?: never;
+  parent?: IAuthProvider;
+};
+
+/**
+ * Represents the configuration options for authentication.
+ *
+ * This type is a union of three different authentication modes:
+ * - `AuthConfigInteractiveMode`: Configuration for interactive authentication.
+ * - `AuthConfigSilentMode`: Configuration for silent authentication.
+ * - `AuthConfigTokenMode`: Configuration for token-based authentication.
+ */
+export type AuthConfig = AuthConfigInteractiveMode | AuthConfigSilentMode | AuthConfigTokenMode;
+
+/**
+ * Interface for configuring authentication settings for the MSAL Node module.
+ *
+ * This interface is intended for both consumers (users integrating authentication into their Fusion Framework Node.js applications)
+ * and future maintainers or developers extending or refactoring the module.
+ *
+ * Each method allows for fine-grained control over the authentication setup, supporting multiple authentication modes:
+ * - `token_only`: Use a pre-obtained access token (e.g., for CI/CD or automation).
+ * - `silent`: Use MSAL's silent authentication with a configured client (for background services or cached tokens).
+ * - `interactive`: Use MSAL's interactive authentication, typically for CLI tools or development, with a local server for browser-based login.
+ *
+ * Consumers should use the provided methods to configure the module according to their use case.
+ * Maintainers should ensure that new authentication flows or configuration options are exposed via this interface for consistency.
+ *
+ * @example
+ * // --- Interactive mode (browser login, local server) ---
+ * ```ts
+ * builder.setMode('interactive');
+ * builder.setClientConfig('your-tenant-id', 'your-client-id');
+ * builder.setServerPort(3000);
+ * builder.setServerOnOpen((url) => {
+ *   console.log(`Please navigate to: ${url}`);
+ * });
+ * ```
+ *
+ * // --- Silent mode (background, cached/refresh tokens) ---
+ * ```ts
+ * builder.setMode('silent');
+ * builder.setClientConfig('your-tenant-id', 'your-client-id');
+ * ```
+ *
+ * // --- Token only mode (pre-obtained token, CI/CD) ---
+ * ```ts
+ * builder.setMode('token_only');
+ * builder.setAccessToken('your-access-token');
+ */
+export interface IAuthConfigurator {
+  /**
+   * Sets the authentication mode for the module.
+   *
+   * @param mode - The authentication mode to use: 'token_only', 'silent', or 'interactive'.
+   *
+   * Consumers: Call this first to define the overall authentication strategy.
+   * Maintainers: Add new modes here if supporting additional auth flows.
+   */
+  setMode(mode: AuthConfig['mode']): void;
+
+  /**
+   * Sets the MSAL client instance for authentication.
+   *
+   * @param client - The MSAL PublicClientApplication instance to use for authentication.
+   *
+   * Consumers: Use this to provide a custom MSAL client if needed.
+   * Maintainers: Ensure compatibility with MSAL updates and custom client options.
+   */
+  setClient(client: AuthConfig['client']): void;
+
+  /**
+   * Configures the MSAL client using tenant and client IDs.
+   *
+   * @param tenantId - Azure AD tenant ID.
+   * @param clientId - Azure AD client/application ID.
+   *
+   * Consumers: Use this for quick setup without manually creating a client instance.
+   * Maintainers: Update this if the client configuration contract changes.
+   */
+  setClientConfig(tenantId: string, clientId: string): void;
+
+  /**
+   * Sets the port for the local server (used in interactive mode for auth callbacks).
+   *
+   * @param port - The port number for the local HTTP server.
+   *
+   * Consumers: Use this to avoid port conflicts or customize the callback endpoint.
+   * Maintainers: Ensure this is respected in server setup logic.
+   */
+  setServerPort(port: number): void;
+
+  /**
+   * Sets a callback to be invoked when the local server opens (interactive mode).
+   *
+   * @param onOpen - Callback receiving the server URL when ready, or undefined to disable.
+   *
+   * Consumers: Use this to display or log the login URL for users.
+   * Maintainers: Update this if the server startup flow changes.
+   */
+  setServerOnOpen(onOpen: ((url: string) => void) | undefined): void;
+
+  /**
+   * Sets a pre-obtained access token for token_only mode.
+   *
+   * @param token - The access token to use for authentication.
+   *
+   * Consumers: Use this for automation or CI/CD scenarios.
+   * Maintainers: Ensure this is securely handled and not mixed with other modes.
+   */
+  setAccessToken(token: string): void;
+}

package/src/AuthConfigurator.ts

@@ -0,0 +1,131 @@
+import { PublicClientApplication } from '@azure/msal-node';
+import {
+  BaseConfigBuilder,
+  type ConfigBuilderCallbackArgs,
+  type ModulesInstance,
+} from '@equinor/fusion-framework-module';
+
+import { createAuthClient } from './create-auth-client';
+
+import type { MsalNodeModule } from './module.js';
+import type { AuthConfig } from './AuthConfigurator.interface.js';
+
+/**
+ * Internal builder for MSAL Node authentication configuration.
+ *
+ * This class provides the implementation for the fluent API exposed via the public interface.
+ * Most consumer-facing documentation is in the interface; see {@link IAuthConfigurator} for usage details.
+ *
+ * @see IAuthConfigurator
+ * @extends BaseConfigBuilder
+ *
+ * Maintainers: Extend or refactor this class to support new authentication modes or configuration options.
+ * Ensure changes are reflected in the interface and validated in `_processConfig`.
+ */
+export class AuthConfigurator extends BaseConfigBuilder<AuthConfig> {
+  constructor() {
+    super();
+    this.setMode('interactive');
+  }
+
+  setMode(mode: AuthConfig['mode']) {
+    this._set('mode', mode);
+  }
+
+  setClient(client: AuthConfig['client']) {
+    this._set('client', client);
+  }
+
+  setClientConfig(tenantId: string, clientId: string): void {
+    this._set('client', () => createAuthClient(tenantId, clientId));
+  }
+
+  setServerPort(port: number) {
+    this._set('server.port', port);
+  }
+
+  setServerOnOpen(onOpen: ((url: string) => void) | undefined) {
+    this._set('server.onOpen', onOpen);
+  }
+
+  setAccessToken(token: string) {
+    this._set('accessToken', token);
+  }
+
+  /**
+   * Prepares and finalizes the authentication configuration before validation and use.
+   *
+   * This method injects the parent authentication provider reference (if available)
+   * into the configuration. It is called before `_processConfig` and allows for
+   * dynamic or contextual configuration adjustments based on the current module instance.
+   *
+   * Future maintainers: If additional contextual setup is needed (e.g., injecting
+   * dependencies, environment-specific values, or chaining providers), extend this method.
+   *
+   * @inheritdoc
+   * @param init - Initialization arguments, including module references.
+   * @param initial - Optional initial configuration values.
+   * @returns The prepared configuration object, ready for validation.
+   */
+  protected _buildConfig(
+    init: ConfigBuilderCallbackArgs,
+    initial?: Partial<AuthConfig> | undefined,
+  ) {
+    // Inject the parent auth provider from the current module instance, if present
+    this._set('parent', (init.ref as ModulesInstance<[MsalNodeModule]>)?.auth);
+    // Call the base builder to finalize the config
+    return super._buildConfig(init, initial);
+  }
+
+  /**
+   * Validates and processes the authentication configuration before use.
+   *
+   * This method ensures that all required properties are present and correctly typed
+   * for the selected authentication mode. Throws descriptive errors if configuration
+   * is incomplete or invalid, helping catch misconfigurations early.
+   *
+   * Future maintainers: Update this logic if new authentication modes or required
+   * properties are introduced. Keep error messages clear to aid debugging.
+   *
+   * @inheritdoc
+   * @param config - The authentication configuration object to validate.
+   * @returns The validated configuration object.
+   * @throws Error if required properties are missing or invalid for the selected mode.
+   */
+  async _processConfig(config: AuthConfig): Promise<AuthConfig> {
+    switch (config.mode) {
+      case 'interactive': {
+        // Interactive mode requires a valid MSAL client instance
+        if (config.client instanceof PublicClientApplication === false) {
+          throw new Error('Client is required when mode is interactive');
+        }
+        // Server configuration must be present
+        if (!config.server) {
+          throw new Error('Server is required when mode is interactive');
+        }
+        // Server port must be a number
+        if (typeof config.server.port !== 'number') {
+          throw new Error('Server port must be a number when mode is interactive');
+        }
+        break;
+      }
+      case 'silent': {
+        // Silent mode requires a valid MSAL client instance
+        if (config.client instanceof PublicClientApplication === false) {
+          throw new Error('Client is required when mode is silent');
+        }
+        break;
+      }
+      case 'token_only': {
+        // Token only mode requires a string access token
+        if (typeof config.accessToken !== 'string') {
+          throw new Error('Access token is required when mode is token_only');
+        }
+        break;
+      }
+      // If new modes are added, ensure validation is implemented here
+    }
+    // Return the validated config for use by the module
+    return config;
+  }
+}

package/src/AuthProvider.interface.ts

@@ -0,0 +1,53 @@
+import type { AuthenticationResult } from '@azure/msal-node';
+
+/**
+ * Interface for authentication providers in the Fusion MSAL Node module.
+ *
+ * Provides a unified API for authentication operations, including acquiring access tokens.
+ * The actual behavior of each method depends on the configured authentication mode (interactive, silent, or token-only).
+ *
+ * When accessing `appModules.msal.auth`, you will interact with this interface to:
+ * - Acquire Azure AD access tokens for specified scopes
+ *
+ * All methods are asynchronous and return Promises. See method documentation for details.
+ *
+ * @remarks
+ * This provider assumes the user is already logged in. To support login and logout operations, the module must be configured in interactive mode. In other modes, `login` and `logout` are present for compatibility but will be no-ops or throw if called.
+ *
+ * @see IAuthProviderInteractive for interactive login/logout support
+ */
+export interface IAuthProvider {
+  /**
+   * This method is present for compatibility but will never trigger a user login flow unless interactive mode is configured.
+   *
+   * @param options - An object specifying the required scopes for authentication.
+   * @returns A Promise that will always reject or be a no-op, depending on implementation.
+   *
+   * @remarks
+   * This method is not supported and should not be used to initiate login unless interactive mode is enabled.
+   */
+  login(options: { scopes: string[] }): Promise<AuthenticationResult>;
+
+  /**
+   * This method is present for compatibility but will never trigger a user logout flow unless interactive mode is configured.
+   *
+   * @returns A Promise that will always resolve immediately or be a no-op, depending on implementation.
+   *
+   * @remarks
+   * This method is not supported and should not be used to initiate logout unless interactive mode is enabled.
+   */
+  logout(): Promise<void>;
+
+  /**
+   * Acquires an access token for the specified scopes.
+   *
+   * @param options - An object specifying the required scopes and an optional `interactive` flag.
+   *   - `scopes`: The scopes for which the token is requested.
+   *   - `interactive`: If true, may trigger an interactive login if silent acquisition fails (not supported unless interactive mode is enabled).
+   * @returns A Promise that resolves to a string representing the acquired access token.
+   *
+   * @remarks
+   * This is the primary method for obtaining tokens for API calls or resource access.
+   */
+  acquireAccessToken(options: { scopes: string[]; interactive?: boolean }): Promise<string>;
+}

package/src/AuthProvider.ts

@@ -0,0 +1,119 @@
+import type { AccountInfo, AuthenticationResult, PublicClientApplication } from '@azure/msal-node';
+
+import { AuthServerError, NoAccountsError, SilentTokenAcquisitionError } from './error.js';
+
+import type { IAuthProvider } from './AuthProvider.interface.js';
+
+/**
+ * Implementation of the authentication provider for the Fusion MSAL Node module.
+ *
+ * Implements {@link IAuthProvider} and provides methods for managing authentication
+ * and token acquisition using the MSAL (Microsoft Authentication Library) for Node.js.
+ *
+ * This implementation assumes the user is already logged in and does not support
+ * triggering interactive login or logout flows. The `login` method will always throw, and `logout`
+ * only clears the token cache.
+ *
+ * @see AuthProviderInteractive For interactive login/logout support (user-driven authentication flows).
+ * @see AuthProviderTokenOnly For scenarios where a pre-obtained token is used (automation, CI/CD, etc).
+ *
+ * Developers extending this class can add support for additional authentication flows or modify token
+ * acquisition logic. Ensure that any changes remain consistent with the interface contract.
+ */
+export class AuthProvider implements IAuthProvider {
+  constructor(protected _client: PublicClientApplication) {}
+
+  /**
+   * Retrieves the first account from the list of all accounts available in the MSAL client.
+   *
+   * @returns A promise that resolves to the first `AccountInfo` object if available, or `null` if no accounts exist.
+   */
+  public async getAccount(): Promise<AccountInfo | null> {
+    const accounts = await this._client.getAllAccounts();
+    return accounts[0] ?? null;
+  }
+
+  /**
+   * Acquires an access token for the specified scopes.
+   *
+   * @param options - An object containing the options for acquiring the token.
+   * @param options.scopes - An array of strings representing the scopes for which the access token is requested.
+   * @returns A promise that resolves to the acquired access token as a string.
+   * @throws An error if the token acquisition process fails.
+   */
+  public async acquireAccessToken(options: {
+    scopes: string[];
+  }): Promise<string> {
+    const { accessToken } = await this.acquireToken(options);
+    return accessToken;
+  }
+
+  /**
+   * Initiates the login process with the specified options.
+   *
+   * @param _options - An object containing the scopes required for authentication.
+   * @returns A promise that resolves to an `AuthenticationResult` upon successful login.
+   * @throws `AuthServerError` - Always throws this error as login is not supported in this implementation.
+   *
+   * @remarks
+   * This method is not supported and is intended to be overridden by `AuthProviderInteractive`.
+   */
+  public async login(_options: { scopes: string[] }): Promise<AuthenticationResult> {
+    throw new AuthServerError('Login not supported, use AuthProviderInteractive instead');
+  }
+
+  /**
+   * Logs out the user by clearing the token cache and removing all accounts.
+   *
+   * This method retrieves all accounts from the token cache and removes them
+   * individually. Afterward, it clears the entire cache to ensure no residual
+   * authentication data remains.
+   *
+   * @returns A promise that resolves when the logout process is complete.
+   */
+  public async logout() {
+    const cache = this._client.getTokenCache();
+    const accounts = await cache.getAllAccounts();
+    for (const account of accounts) {
+      await cache.removeAccount(account);
+    }
+    this._client.clearCache();
+  }
+
+  /**
+   * Acquires an authentication token for the specified scopes.
+   *
+   * This method first attempts to acquire a token silently using the accounts
+   * available in the token cache. If no accounts are found and interactive login
+   * is allowed, it initiates an interactive login flow. If interactive login is
+   * not allowed and no accounts are found, an error is thrown.
+   *
+   * @param scopes - An array of strings representing the scopes for which the token is requested.
+   * @param options - Optional parameters for token acquisition.
+   * @param options.interactive - A boolean indicating whether interactive login is allowed
+   *                               if no accounts are found in the cache. Defaults to `false`.
+   * @returns A promise that resolves to an `AuthenticationResult` containing the acquired token.
+   * @throws {@link NoAccountsError} If no accounts are found in the cache and interactive login is not allowed.
+   * @throws {@link SilentTokenAcquisitionError} If an error occurs during silent token acquisition.
+   */
+  public async acquireToken(options: {
+    scopes: string[];
+  }): Promise<AuthenticationResult> {
+    const account = await this.getAccount();
+    if (!account) {
+      throw new NoAccountsError('No accounts found in cache');
+    }
+
+    try {
+      const tokenResponse = await this._client.acquireTokenSilent({
+        scopes: options.scopes,
+        account,
+      });
+      return tokenResponse;
+    } catch (error) {
+      throw new SilentTokenAcquisitionError('Error acquiring token', {
+        cause: error,
+      });
+    }
+  }
+}

package/src/AuthProviderInteractive.ts

@@ -0,0 +1,117 @@
+import {
+  CryptoProvider,
+  type AuthenticationResult,
+  type PublicClientApplication,
+} from '@azure/msal-node';
+
+import openBrowser from 'open';
+import { createAuthServer } from './create-auth-server.js';
+import { AuthProvider } from './AuthProvider.js';
+
+/**
+ * Options for configuring the interactive authentication provider.
+ *
+ * @property server - Configuration for the local server used to handle authentication callbacks.
+ *   @property port - The port number on which the local server will listen for authentication responses.
+ *   @property onOpen - Optional callback invoked with the authentication URL when the server is ready (e.g., to display or log the URL).
+ *
+ * Used when constructing an instance of {@link AuthProviderInteractive} to enable browser-based login flows.
+ */
+type AuthProviderOptions = {
+  server: {
+    port: number;
+    onOpen?: (url: string) => void;
+  };
+};
+
+/**
+ * Implementation of an interactive authentication provider for the Fusion MSAL Node module.
+ *
+ * Extends {@link AuthProvider} to support user-driven authentication flows using the authorization code flow with PKCE.
+ * This class opens the user's default browser for authentication and handles the response via a local server.
+ *
+ * This implementation is intended for scenarios where interactive login is required, such as CLI tools or development utilities.
+ *
+ * Developers extending this provider can customize the interactive flow, server handling, or PKCE logic as needed.
+ * Ensure that any changes remain consistent with the expected interface and security best practices.
+ *
+ * @see AuthProvider for non-interactive (silent) authentication flows.
+ * @see AuthProviderTokenOnly for token-only scenarios.
+ */
+export class AuthProviderInteractive extends AuthProvider {
+  #options: AuthProviderOptions;
+
+  constructor(client: PublicClientApplication, options: AuthProviderOptions) {
+    super(client);
+    this.#options = options;
+  }
+
+  /**
+   * Initiates the login process using the authorization code flow with PKCE.
+   *
+   * This method generates a PKCE code verifier and challenge to enhance security
+   * and prevent authorization code interception attacks. It constructs an
+   * authorization code URL, opens the default browser for user authentication,
+   * and starts a local server to handle the authentication response.
+   *
+   * @param scopes - An array of scopes that specify the permissions being requested.
+   * @returns A promise that resolves to an `AuthenticationResult` containing the
+   *          authentication details upon successful login.
+   *
+   * @throws Will throw an error if the PKCE code generation, browser opening, or
+   *         authentication server setup fails.
+   */
+  public async login(options: { scopes: string[] }): Promise<AuthenticationResult> {
+    const { scopes } = options;
+    const { port, onOpen } = this.#options.server;
+
+    // Generate a new PKCE code verifier and challenge
+    // This is used to enhance security in the authorization code flow
+    // by preventing authorization code interception attacks.
+    const cryptoProvider = new CryptoProvider();
+    const { verifier, challenge } = await cryptoProvider.generatePkceCodes();
+    const authCodeUrl = await this._client.getAuthCodeUrl({
+      scopes,
+      redirectUri: `http://localhost:${port}`,
+      codeChallenge: challenge,
+      codeChallengeMethod: 'S256',
+    });
+
+    // open default browser to authenticate
+    await openBrowser(authCodeUrl);
+
+    // callback to open the auth code url
+    if (onOpen) onOpen(authCodeUrl);
+
+    return createAuthServer(this._client, scopes, {
+      codeVerifier: verifier,
+      port,
+    });
+  }
+
+  /**
+   * Acquires an authentication token for the specified scopes.
+   *
+   * This method first attempts to acquire a token silently using the accounts
+   * available in the token cache. If no accounts are found and interactive login
+   * is allowed, it initiates an interactive login flow. If interactive login is
+   * not allowed and no accounts are found, an error is thrown.
+   *
+   * @param scopes - An array of strings representing the scopes for which the token is requested.
+   * @param options - Optional parameters for token acquisition.
+   * @param options.interactive - A boolean indicating whether interactive login is allowed
+   *                               if no accounts are found in the cache. Defaults to `false`.
+   * @returns A promise that resolves to an `AuthenticationResult` containing the acquired token.
+   * @throws {@link NoAccountsError} If no accounts are found in the cache and interactive login is not allowed.
+   * @throws {@link SilentTokenAcquisitionError} If an error occurs during silent token acquisition.
+   */
+  public async acquireToken(options: {
+    scopes: string[];
+  }): Promise<AuthenticationResult> {
+    const { scopes } = options ?? { scopes: [] };
+    if ((await this.getAccount()) === null) {
+      return this.login({ scopes });
+    }
+    return super.acquireToken(options);
+  }
+}

package/src/AuthTokenProvider.ts

@@ -0,0 +1,56 @@
+import type { AuthenticationResult } from '@azure/msal-node';
+import type { IAuthProvider } from './AuthProvider.interface.js';
+
+/**
+ * Implementation of an authentication provider that supplies a static, pre-obtained access token.
+ *
+ * This class implements {@link IAuthProvider} and is intended for scenarios where authentication
+ * is handled externally and a token is provided directly (e.g., CI/CD pipelines, automation, or service accounts).
+ *
+ * Login and logout operations are not supported and will always throw errors if called.
+ *
+ * @see AuthProvider for silent authentication using cached accounts and MSAL flows.
+ * @see AuthProviderInteractive for interactive, user-driven authentication flows.
+ */
+export class AuthTokenProvider implements IAuthProvider {
+  #accessToken: string;
+  constructor(token: string) {
+    this.#accessToken = token;
+  }
+
+  /**
+   * Not supported in token-only mode. Always throws an error if called.
+   *
+   * This provider is designed for scenarios where authentication is handled externally
+   * and a static token is supplied. Login flows are not possible in this context.
+   *
+   * @throws Error Always throws to indicate login is not supported.
+   */
+  login(): Promise<AuthenticationResult> {
+    throw new Error('Method not supported in token mode');
+  }
+
+  /**
+   * Not supported in token-only mode. Always throws an error if called.
+   *
+   * Since this provider does not manage user sessions or accounts, logout is not applicable.
+   *
+   * @throws Error Always throws to indicate logout is not supported.
+   */
+  logout(): Promise<void> {
+    throw new Error('Method not supported in token mode');
+  }
+
+  /**
+   * Returns the pre-obtained access token supplied to the provider.
+   *
+   * This is the only supported operation for this provider. No token refresh or acquisition logic is performed.
+   *
+   * @returns The static access token as a string.
+   */
+  async acquireAccessToken(): Promise<string> {
+    return this.#accessToken;
+  }
+}
+
+export default AuthTokenProvider;