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

package/src/create-auth-cache.ts

@@ -0,0 +1,85 @@
+import {
+  DataProtectionScope,
+  Environment,
+  PersistenceCreator,
+  PersistenceCachePlugin,
+  type IPersistence,
+} from '@azure/msal-node-extensions';
+
+import { tmpdir } from 'node:os';
+
+import path from 'node:path';
+
+/**
+ * Resolves the directory path for storing the authentication cache.
+ *
+ * Uses the user's root directory if available, otherwise falls back to the OS temp directory.
+ *
+ * @returns The resolved cache directory path as a string.
+ */
+const resolveCachePath = () => {
+  return Environment?.getUserRootDirectory() ?? tmpdir();
+};
+
+/**
+ * Resolves the file path for the authentication cache based on tenant and client IDs.
+ *
+ * @param tenantId - The Azure AD tenant ID.
+ * @param clientId - The Azure AD client/application ID.
+ * @returns The full file path for the cache file.
+ */
+const resolveCacheFilePath = (tenantId: string, clientId: string) => {
+  return path.join(resolveCachePath(), `.token-cache-${tenantId}_${clientId}`);
+};
+
+/**
+ * Creates a persistence cache for storing authentication data securely on disk.
+ *
+ * The cache is encrypted and scoped to the current user for security. It is uniquely identified
+ * by the provided tenant and client IDs, and is associated with the 'fusion-framework' service.
+ *
+ * @param tenantId - The Azure AD tenant ID used to identify the cache.
+ * @param clientId - The Azure AD client/application ID used to identify the cache.
+ * @returns A promise that resolves to the created persistence cache instance.
+ */
+export const createPersistenceCache = async (
+  tenantId: string,
+  clientId: string,
+): Promise<IPersistence> => {
+  return PersistenceCreator.createPersistence({
+    cachePath: resolveCacheFilePath(tenantId, clientId),
+    serviceName: 'fusion-framework',
+    accountName: [tenantId, clientId].join('_'),
+    dataProtectionScope: DataProtectionScope.CurrentUser,
+  });
+};
+
+/**
+ * Clears the persistence cache for a specific tenant and client.
+ *
+ * Deletes the cache file and all associated authentication data for the given tenant and client IDs.
+ *
+ * @param tenantId - The Azure AD tenant ID.
+ * @param clientId - The Azure AD client/application ID.
+ * @returns A promise that resolves when the cache has been successfully cleared.
+ */
+export const clearPersistenceCache = async (tenantId: string, clientId: string): Promise<void> => {
+  const cache = await createPersistenceCache(tenantId, clientId);
+  await cache.delete();
+};
+
+/**
+ * Creates a `PersistenceCachePlugin` instance for use with MSAL, using the provided tenant and client IDs.
+ *
+ * This plugin enables MSAL to use the secure persistence cache for token storage.
+ *
+ * @param tenantId - The Azure AD tenant ID.
+ * @param clientId - The Azure AD client/application ID.
+ * @returns A promise that resolves to an instance of `PersistenceCachePlugin`.
+ */
+export const createPersistenceCachePlugin = async (
+  tenantId: string,
+  clientId: string,
+): Promise<PersistenceCachePlugin> => {
+  return new PersistenceCachePlugin(await createPersistenceCache(tenantId, clientId));
+};

package/src/create-auth-client.ts

@@ -0,0 +1,40 @@
+import { PublicClientApplication } from '@azure/msal-node';
+
+import { createPersistenceCachePlugin } from './create-auth-cache.js';
+
+/**
+ * Creates and configures a new MSAL PublicClientApplication instance for Azure AD authentication.
+ *
+ * This function sets up the client with the specified tenant and client IDs, and attaches a secure
+ * persistence cache plugin for storing authentication tokens on disk. The resulting client can be used
+ * for both silent and interactive authentication flows, depending on how it is integrated.
+ *
+ * @param tenantId - The Azure Active Directory tenant ID (directory identifier).
+ * @param clientId - The client/application ID registered in Azure AD.
+ * @returns A Promise that resolves to a configured instance of `PublicClientApplication`.
+ *
+ * @remarks
+ * The returned client uses a secure, user-scoped cache for token storage. This is recommended for CLI tools,
+ * background services, and other Node.js applications that require persistent authentication.
+ *
+ * @example
+ * ```typescript
+ * const client = await createAuthClient('your-tenant-id', 'your-client-id');
+ * // Use the client with MSAL APIs for authentication flows
+ * ```
+ */
+export const createAuthClient = async (
+  tenantId: string,
+  clientId: string,
+): Promise<PublicClientApplication> => {
+  const cachePlugin = await createPersistenceCachePlugin(tenantId, clientId);
+  return new PublicClientApplication({
+    auth: {
+      clientId: clientId,
+      authority: `https://login.microsoftonline.com/${tenantId}`,
+    },
+    cache: { cachePlugin },
+  });
+};
+
+export default createAuthClient;

package/src/create-auth-server.ts

@@ -0,0 +1,93 @@
+import type { AuthenticationResult, PublicClientApplication } from '@azure/msal-node';
+import { createServer } from 'node:http';
+import URL from 'node:url';
+
+import { AuthServerError, AuthServerTimeoutError } from './error.js';
+
+const DEFAULT_SERVER_TIMEOUT = 300000 as const; // 5 minutes
+
+/**
+ * Creates a temporary HTTP server to handle the OAuth 2.0 authorization code flow for interactive authentication.
+ *
+ * This function is used in interactive authentication scenarios to listen for the authorization code
+ * returned by Azure AD after the user authenticates in the browser. It exchanges the code for an access token
+ * using the provided `PublicClientApplication` instance. The server automatically shuts down after a successful
+ * authentication, error, or timeout.
+ *
+ * @param client - The MSAL `PublicClientApplication` instance used to acquire tokens.
+ * @param scopes - An array of scopes for which the token is requested.
+ * @param options - Configuration for the authentication server.
+ *   @param options.port - The port on which the server will listen for the authentication response.
+ *   @param options.codeVerifier - The PKCE code verifier used for enhanced security (optional).
+ *   @param options.timeout - Timeout in milliseconds before the server shuts down if no response is received (default: 5 minutes).
+ *
+ * @returns A promise that resolves with the `AuthenticationResult` upon successful authentication,
+ * or rejects with an error if authentication fails or times out.
+ *
+ * @throws {@link AuthServerError} If no authorization code is received or if token acquisition fails.
+ * @throws {@link AuthServerTimeoutError} If the server times out before receiving a response.
+ *
+ * @example
+ * ```typescript
+ * const result = await createAuthServer(client, ['user.read'], { port: 3000, codeVerifier });
+ * console.log(result.accessToken);
+ * ```
+ */
+export const createAuthServer = (
+  client: PublicClientApplication,
+  scopes: string[],
+  options: {
+    port: number;
+    codeVerifier?: string;
+    timeout?: number;
+  },
+): Promise<AuthenticationResult> => {
+  const { port, timeout = DEFAULT_SERVER_TIMEOUT } = options;
+  return new Promise<AuthenticationResult>((resolve, reject) => {
+    // Set a timeout for the server to close if no response is received in time
+    const timeoutId = setTimeout(() => {
+      server.close();
+      reject(new AuthServerTimeoutError('Authentication server timed out'));
+    }, timeout);
+
+    // Create a temporary HTTP server to listen for the OAuth 2.0 redirect
+    const server = createServer(async (req, res) => {
+      // Parse the URL and extract the query parameters from the redirect
+      const query = URL.parse(req.url ?? '', true).query;
+      if (!query.code) {
+        // If no authorization code is present, return an error to the browser and reject the promise
+        const error = new AuthServerError('No authorization code received');
+        res.writeHead(400, { 'Content-Type': 'text/html' });
+        res.end(error.message);
+        server.close();
+        return reject(error);
+      }
+
+      try {
+        // Attempt to exchange the authorization code for an access token
+        const tokenResponse = await client.acquireTokenByCode({
+          code: Array.isArray(query.code) ? query.code[0] : query.code,
+          scopes: scopes,
+          codeVerifier: options?.codeVerifier,
+          redirectUri: `http://localhost:${port}`,
+        });
+        // On success, notify the user in the browser and resolve the promise
+        res.writeHead(200, { 'Content-Type': 'text/html' });
+        res.end('Authentication successful! You can close this window.');
+        resolve(tokenResponse);
+      } catch (err) {
+        // If token acquisition fails, return an error to the browser and reject the promise
+        const error = new AuthServerError('Authentication failed', { cause: err as Error });
+        res.writeHead(500, { 'Content-Type': 'text/html' });
+        res.end(`<b>${error.message}</b><br>${(err as Error).message}`);
+        reject(error);
+      } finally {
+        // Always clean up: close the server and clear the timeout
+        server.close();
+        clearTimeout(timeoutId);
+      }
+    }).listen(port);
+  });
+};
+
+export default createAuthServer;

package/src/enable-module.ts

@@ -0,0 +1,35 @@
+import type { IModuleConfigurator, IModulesConfigurator } from '@equinor/fusion-framework-module';
+import { module, type MsalNodeModule } from './module';
+
+/**
+ * Enables the MSAL Node module by registering its configuration with the provided modules configurator.
+ *
+ * This function should be called to add the MSAL Node authentication module to a Fusion Framework application.
+ * It accepts a configurator instance and a configuration function, which is used to define the module's behavior and settings.
+ *
+ * @param configurator - The modules configurator instance used to register the MSAL Node module.
+ * @param configure - A configuration function for customizing the module (e.g., setting client ID, tenant ID, mode).
+ *
+ * @see IAuthProvider for the authentication provider interface exposed by the module.
+ * @see IAuthConfigurator for the configuration builder interface used in the configure callback.
+ *
+ * @example
+ * ```typescript
+ * enableModule(configurator, (builder) => {
+ *   builder.setMode('interactive');
+ *   builder.setClientConfig('your-tenant-id', 'your-client-id');
+ * });
+ * ```
+ */
+export const enableModule = (
+  // biome-ignore lint/suspicious/noExplicitAny: @todo -remove when types sorted in provider interface
+  configurator: IModulesConfigurator<any, any>,
+  configure: IModuleConfigurator<MsalNodeModule>['configure'],
+) => {
+  configurator.addConfig({
+    module,
+    configure,
+  });
+};
+
+export default enableModule;

package/src/error.ts

@@ -0,0 +1,66 @@
+/**
+ * Error thrown when no accounts are available for an operation that requires one.
+ *
+ * Typically used when attempting to acquire a token or perform an action that requires
+ * a user account, but none are found in the MSAL cache.
+ *
+ * @param message - Description of the error.
+ * @param options - Optional error options, including a cause for error chaining.
+ */
+export class NoAccountsError extends Error {
+  static readonly Name: string = 'NoAccountsError';
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = NoAccountsError.Name;
+  }
+}
+
+/**
+ * Error thrown when silent token acquisition fails.
+ *
+ * This error is used when MSAL cannot acquire a token silently, often due to missing
+ * credentials, expired tokens, or lack of a valid session.
+ *
+ * @param message - Description of the error.
+ * @param options - Optional error options, including a cause for error chaining.
+ */
+export class SilentTokenAcquisitionError extends Error {
+  static readonly Name: string = 'SilentTokenAcquisitionError';
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = SilentTokenAcquisitionError.Name;
+  }
+}
+
+/**
+ * Error representing a failure or issue in the authentication server flow.
+ *
+ * Used to signal problems during the OAuth 2.0 authorization code flow, such as
+ * missing codes, invalid requests, or token exchange failures. Supports error chaining.
+ *
+ * @param message - Description of the error.
+ * @param options - Optional error options, including a cause for error chaining.
+ */
+export class AuthServerError extends Error {
+  static readonly Name: string = 'AuthServerError';
+  constructor(message: string, options?: { cause?: Error }) {
+    super(message, options);
+    this.name = AuthServerError.Name;
+  }
+}
+
+/**
+ * Error thrown when the authentication server times out waiting for a response.
+ *
+ * Extends {@link AuthServerError} to provide additional context for timeout scenarios.
+ *
+ * @param message - Description of the error.
+ * @param options - Optional error options, including a cause for error chaining.
+ */
+export class AuthServerTimeoutError extends AuthServerError {
+  static readonly Name: string = 'AuthServerTimeoutError';
+  constructor(message: string, options?: { cause?: Error }) {
+    super(message, options);
+    this.name = AuthServerTimeoutError.Name;
+  }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export { AuthProvider } from './AuthProvider.js';
+
+export type { IAuthProvider } from './AuthProvider.interface.js';
+
+export type { IAuthConfigurator, AuthConfig } from './AuthConfigurator.interface.js';
+
+export { module as authModule, type MsalNodeModule } from './module.js';
+
+export { enableModule as enableAuthModule } from './enable-module.js';

package/src/module.ts

@@ -0,0 +1,52 @@
+import type { Module } from '@equinor/fusion-framework-module';
+import { AuthConfigurator } from './AuthConfigurator';
+import { AuthProvider } from './AuthProvider';
+import { AuthTokenProvider } from './AuthTokenProvider';
+import { AuthProviderInteractive } from './AuthProviderInteractive';
+import type { IAuthProvider } from './AuthProvider.interface';
+
+/**
+ * MSAL Node authentication module for the Fusion Framework.
+ *
+ * This module provides authentication capabilities for Node.js applications using Microsoft's MSAL library.
+ * It supports multiple authentication modes: token-only, interactive (browser-based), and silent (cached credentials).
+ *
+ * The module exposes a unified provider interface for acquiring tokens and managing authentication state.
+ *
+ * - In `token_only` mode, a static access token is used (see {@link AuthTokenProvider}).
+ * - In `interactive` mode, the user is prompted via a local server and browser (see {@link AuthProviderInteractive}).
+ * - In all other cases, silent authentication is attempted using cached credentials (see {@link AuthProvider}).
+ *
+ * @see AuthProvider
+ * @see AuthProviderInteractive
+ * @see AuthTokenProvider
+ * @see IAuthProvider
+ * @see AuthConfigurator
+ */
+export type MsalNodeModule = Module<'auth', IAuthProvider, AuthConfigurator>;
+
+export const module: MsalNodeModule = {
+  name: 'auth',
+  configure: () => new AuthConfigurator(),
+  initialize: async (args) => {
+    const config = await args.config.createConfigAsync(args);
+
+    switch (config.mode) {
+      case 'token_only':
+        return new AuthTokenProvider(config.accessToken);
+
+      case 'interactive': {
+        const { client, server } = config;
+        if (!server) {
+          throw new Error('Server configuration is required for interactive mode');
+        }
+        return new AuthProviderInteractive(client, { server });
+      }
+
+      default:
+        return new AuthProvider(config.client);
+    }
+  },
+};
+
+export default module;

package/src/version.ts

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

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist/esm",
+    "rootDir": "src",
+    "declarationDir": "./dist/types"
+  },
+  "references": [
+    {
+      "path": "../module"
+    }
+  ],
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "lib"]
+}