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

package/src/mock/MsalMockConfigurator.ts

@@ -0,0 +1,241 @@
+import type {
+  ConfigBuilderCallback,
+  ConfigBuilderCallbackArgs,
+} from '@equinor/fusion-framework-module';
+
+import type { IMsalClient } from '../MsalClient.interface';
+import type { IMsalProvider } from '../MsalProvider.interface';
+import type { MsalClientConfig } from '../MsalClient';
+import { MsalConfigurator, type MsalConfig } from '../MsalConfigurator';
+
+import { MsalMockClient, type MsalMockUser } from './MsalMockClient';
+
+/**
+ * Declares the mock's own branch of the MSAL configuration.
+ *
+ * @remarks
+ * Merging into `MsalConfigExtension` is what lets `setAccount` record the
+ * user through the ordinary builder — `_set` derives its target from
+ * {@link MsalConfig}, so a key the type does not know about could only be set by
+ * casting past it.
+ *
+ * The schema strips `mock` when it validates, so a declaration made here travels
+ * the builder and stops there: it is readable from the raw configuration and
+ * absent from the one `MsalProvider` receives.
+ */
+declare module '../msal-config-schema' {
+  interface MsalConfigExtension {
+    mock?: {
+      /**
+       * The user to sign in, resolved if it was declared as a callback, or
+       * `null` when nobody is signed in.
+       */
+      account?: MsalMockUser | null;
+    };
+  }
+}
+
+/**
+ * The client configuration used when a test declares none.
+ *
+ * @remarks
+ * `MsalClientConfig.auth.clientId` is required, so a mock still needs a client
+ * configuration to exist. Supplying a default is what lets an application boot
+ * under test without declaring credentials it does not have.
+ */
+const defaultMockClientConfig: MsalClientConfig = {
+  auth: {
+    clientId: 'fusion-mock-client',
+    tenantId: 'fusion-mock-tenant',
+  },
+};
+
+/**
+ * The real MSAL configurator, backed by an in-process client.
+ *
+ * @remarks
+ * Nothing else changes: the same builder API, the same validation and the same
+ * `MsalProvider` are used. Only the boundary that would contact Entra ID is
+ * substituted, through the same
+ * {@link MsalConfigurator._createClient | _createClient} seam the real
+ * configurator builds its own client from — and from the same
+ * {@link MsalConfigurator._createClientConfig | _createClientConfig}, so
+ * `setClientConfig` means exactly what it means in production.
+ *
+ * A user named `Test User` is signed in by default, so an application boots
+ * without declaring anything.
+ *
+ * @example Name the signed-in user
+ * ```typescript
+ * enableMsalMock(configurator, (builder) => {
+ *   builder.setAccount({ name: 'Ada Lovelace', username: 'ada@equinor.com' });
+ * });
+ * ```
+ *
+ * @example Configure the client exactly as in production
+ * ```typescript
+ * enableMsalMock(configurator, (builder) => {
+ *   builder.setClientConfig({ auth: { clientId: 'my-app', tenantId: 'my-tenant' } });
+ * });
+ * ```
+ *
+ * @example Take full control of authentication
+ * ```typescript
+ * enableMsalMock(configurator, (builder) => {
+ *   builder.setClient(new MyOwnMsalClient());
+ * });
+ * ```
+ */
+export class MsalMockConfigurator extends MsalConfigurator {
+  /**
+   * Declares the user to sign in.
+   *
+   * @remarks
+   * Who is signed in is session state, not client configuration — which is what
+   * lets {@link MsalMockClient} take the same argument the real client takes: a
+   * client is configured with *what it talks to*, never with *who is signed in*.
+   *
+   * The user is therefore recorded on the configuration as `mock.account`, not
+   * on this builder, and is signed in on whichever client the module ends up
+   * authenticating through — wherever that client was built:
+   *
+   * - The client this builder builds, normally. The user is in place before
+   *   `MsalProvider.initialize` runs, which is what makes the provider's own
+   *   start-up path observable: with `signedOut` and `setRequiresAuth(true)`, a
+   *   test sees the real automatic login run.
+   * - The **host's** client when the module is hoisted onto a host
+   *   application's provider, because none is built here. An application inside
+   *   a portal shares the portal's session, so this changes who the host sees
+   *   signed in too, as it would in production.
+   * - A client supplied through {@link MsalConfigurator.setClient | setClient},
+   *   when that client is a {@link MsalMockClient}.
+   *
+   * Throws when that client cannot represent a declared user, rather than
+   * failing quietly — a silent no-op is the whole failure mode this exists to
+   * prevent.
+   *
+   * Pass `null` when nobody is signed in, or `{ signedOut: true }` to keep an
+   * identity without a session — a later login then resolves as that user.
+   *
+   * @param account - The user, or an ordinary config-builder callback resolving it.
+   * @returns The builder, for chaining.
+   *
+   * @example Derive the user from the modules in scope
+   * ```typescript
+   * builder.setAccount(async ({ hasModule }) => ({
+   *   name: hasModule('app') ? 'App User' : 'Portal User',
+   * }));
+   * ```
+   */
+  public setAccount(
+    account: MsalMockUser | null | ConfigBuilderCallback<MsalMockUser | null>,
+  ): this {
+    this._set('mock.account', account);
+    return this;
+  }
+
+  /**
+   * Signs the declared user in on the client the module authenticates through.
+   *
+   * @remarks
+   * Deliberately not done while the client is built: that would assume the scope
+   * declaring the user is the scope building the client, which is exactly what
+   * is not true when an application is tested inside a portal. The host built
+   * that client, in a scope this builder never sees, so the client has to be
+   * located rather than assumed.
+   *
+   * @param account - The user to sign in, or `null` when nobody is.
+   * @param config - The validated configuration, carrying the client when one was built.
+   * @param init - The builder arguments, carrying the host reference when hoisted.
+   * @throws When the resolved client is not a {@link MsalMockClient}.
+   */
+  #signIn(
+    account: MsalMockUser | null,
+    config: MsalConfig,
+    init?: ConfigBuilderCallbackArgs,
+  ): void {
+    const host = (init?.ref as { auth?: IMsalProvider } | undefined)?.auth;
+    const client = config.client ?? host?.client;
+
+    // Reject a real client because mock account state cannot be applied to it.
+    if (!(client instanceof MsalMockClient)) {
+      throw new Error(
+        'MsalMockConfigurator: cannot sign a user in, because this module does not authenticate through a mock client. Declare the user where that client is configured instead.',
+      );
+    }
+
+    client.setUser(account);
+  }
+
+  /**
+   * Assembles the configuration, then signs the declared user in.
+   *
+   * @remarks
+   * Stands a client configuration in first when this builder is the one that
+   * will build a client: `MsalClientConfig.auth.clientId` is required to build
+   * any client at all and a test has no real credentials to declare. It then
+   * flows through the very same
+   * {@link MsalConfigurator._createClientConfig | _createClientConfig}
+   * enrichment the real client is built from, and anything declared through
+   * {@link MsalConfigurator.setClientConfig | setClientConfig} wins — exactly as
+   * in production.
+   *
+   * Doing that here rather than in the constructor is deliberate: a hoisted
+   * module authenticates through the host and builds no client, so it must not
+   * look configured either.
+   *
+   * The user is read from `rawConfig`, because the schema strips `mock` when it
+   * validates — the key exists to carry a test's declaration through the
+   * builder, never to reach the provider.
+   *
+   * @param rawConfig - The raw configuration to process.
+   * @param init - The builder arguments, carrying the host reference when hoisted.
+   * @returns The processed and validated configuration.
+   */
+  override async _processConfig(
+    rawConfig: MsalConfig,
+    init?: ConfigBuilderCallbackArgs,
+  ): Promise<MsalConfig> {
+    // Supply mock credentials only when this builder owns client construction.
+    if (!this._isHoisted(init) && !this.getClientConfig()) {
+      this.setClientConfig(defaultMockClientConfig);
+    }
+
+    const config = await super._processConfig(rawConfig, init);
+
+    // `null` is a declaration in its own right — nobody is signed in — so only
+    // an absent one means the test said nothing about the user
+    const account = rawConfig.mock?.account;
+    // Apply even null because null explicitly requests a signed-out mock state.
+    if (account !== undefined) {
+      this.#signIn(account, config, init);
+    }
+
+    return config;
+  }
+
+  /**
+   * Builds an in-process client.
+   *
+   * @remarks
+   * Called only when no client was set, so
+   * {@link MsalConfigurator.setClient | setClient} still replaces authentication
+   * outright.
+   *
+   * Deliberately does not delegate to `super`, which would build a real
+   * `MsalClient` and contact Entra ID. It is never reached when the module is
+   * hoisted onto a host application's provider, because the base configurator
+   * gates client creation on {@link MsalConfigurator._isHoisted | _isHoisted} —
+   * a mock client built there would shadow the host's client, the exact scenario
+   * an application-inside-a-portal test exists to cover.
+   *
+   * Knows nothing about who is signed in: a client is built from what it talks
+   * to, and the declared user is applied to it afterwards.
+   *
+   * @param config - The validated configuration the client is built from.
+   * @returns A client resolving tokens in-process.
+   */
+  protected override async _createClient(config: MsalConfig): Promise<IMsalClient> {
+    return new MsalMockClient(this._createClientConfig(config) ?? defaultMockClientConfig);
+  }
+}

package/src/mock/create-mock-token.ts

@@ -0,0 +1,92 @@
+/**
+ * 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;
+}
+
+/**
+ * Encodes a value as base64url without padding, as used in JWT segments.
+ *
+ * @param value - Raw string to encode.
+ * @returns The base64url representation.
+ */
+const base64Url = (value: string): string => {
+  // btoa operates on latin1; encodeURIComponent round-trip keeps non-ASCII names intact
+  const bytes = new TextEncoder().encode(value);
+  let binary = '';
+  // Iterate over encoded bytes so Unicode claims are preserved before base64url encoding.
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+};
+
+/**
+ * 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 const createMockToken = (claims: MockTokenClaims = {}): string => {
+  const header = { alg: 'none', typ: 'JWT' };
+  // Fixed default clock keeps generated tokens byte-identical between runs
+  const issuedAt = claims.iat ?? 1_700_000_000;
+  const payload: MockTokenClaims = {
+    iss: 'https://login.microsoftonline.com/fusion-test-tenant/v2.0',
+    aud: 'fusion-test-client',
+    tid: 'fusion-test-tenant',
+    oid: 'fusion-test-user',
+    iat: issuedAt,
+    nbf: issuedAt,
+    exp: issuedAt + 3600,
+    ...claims,
+  };
+
+  return [
+    base64Url(JSON.stringify(header)),
+    base64Url(JSON.stringify(payload)),
+    'fusion-test-signature',
+  ].join('.');
+};

package/src/mock/create-msal-mock-client.ts

@@ -0,0 +1,25 @@
+import type { IMsalClient } from '../MsalClient.interface';
+import type { MsalClientConfig } from '../MsalClient';
+import { MsalMockClient, 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 const createMsalMockClient = (
+  config: MsalClientConfig,
+  user?: MsalMockUser,
+): IMsalClient => {
+  const client = new MsalMockClient(config);
+  // Apply the optional identity after construction so the helper matches setUser semantics.
+  if (user) {
+    client.setUser(user);
+  }
+  return client;
+};

package/src/mock/decode-jwt-segment.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 function decodeJwtSegment(segment: string): string {
+  const base64 = segment
+    .replace(/-/g, '+')
+    .replace(/_/g, '/')
+    .padEnd(segment.length + ((4 - (segment.length % 4)) % 4), '=');
+  const binary = atob(base64);
+  const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+  return new TextDecoder().decode(bytes);
+}
+
+export default decodeJwtSegment;

package/src/mock/index.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/src/mock/module.ts

@@ -0,0 +1,54 @@
+import type { IModulesConfigurator } from '@equinor/fusion-framework-module';
+
+import { module, 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 const msalMockModule: MsalModule = {
+  ...module,
+  configure: () => new MsalMockConfigurator(),
+};
+
+/**
+ * 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 const enableMsalMock = (
+  // biome-ignore lint/suspicious/noExplicitAny: must be any to support all module types
+  configurator: IModulesConfigurator<any, any>,
+  configure?: AuthConfigMockFn,
+): void => {
+  configurator.addConfig({ module: msalMockModule, configure } as {
+    module: MsalModule;
+  });
+};

package/src/msal-config-schema.ts

@@ -0,0 +1,81 @@
+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/telemetry-config-schema.ts

@@ -0,0 +1,25 @@
+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/version.ts

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

package/src/versioning/resolve-version.ts

@@ -29,7 +29,6 @@ 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) {

package/vitest.config.ts

@@ -1,6 +1,6 @@
 import { defineProject } from 'vitest/config';
 
-import { name, version } from './package.json';
+import { name, version } from './package.json' with { type: 'json' };
 
 export default defineProject({
   test: {