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

package/dist/types/MsalConfigurator.d.ts

@@ -1,23 +1,11 @@
-import z from 'zod';
-import { BaseConfigBuilder } from '@equinor/fusion-framework-module';
+import { BaseConfigBuilder, type ConfigBuilderCallbackArgs } from '@equinor/fusion-framework-module';
+import { CacheLookupPolicy } from '@azure/msal-browser';
+import type { ITelemetryProvider } from '@equinor/fusion-framework-module-telemetry';
 import type { IMsalProvider } from './MsalProvider.interface';
-import { type ITelemetryProvider } from '@equinor/fusion-framework-module-telemetry';
 import { type MsalClientConfig, type IMsalClient } from './MsalClient';
-import { CacheLookupPolicy } from '@azure/msal-browser';
-/**
- * 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>;
-/**
- * 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>;
+import { type MsalConfig } from './msal-config-schema';
+export { MsalConfigSchema, type MsalConfig, type MsalConfigExtension, } from './msal-config-schema';
+export { TelemetryConfigSchema, type TelemetryConfig } from './telemetry-config-schema';
 /**
  * Configuration builder for MSAL v4 authentication module.
  *
@@ -67,6 +55,20 @@ export declare class MsalConfigurator extends BaseConfigBuilder<MsalConfig> {
      * ```
      */
     setClientConfig(config?: MsalClientConfig): this;
+    /**
+     * Returns the client configuration declared through
+     * {@link MsalConfigurator.setClientConfig | setClientConfig}, if any.
+     *
+     * @remarks
+     * This is the configuration as declared, not the resolved one a client is
+     * built from — see
+     * {@link MsalConfigurator._createClientConfig | _createClientConfig} for that.
+     * Reading it is how a subclass can tell "nothing was declared" apart from
+     * "declared, and here it is", without re-deriving that from a resolved value.
+     *
+     * @returns The declared client configuration, or `undefined` when none was declared.
+     */
+    getClientConfig(): MsalClientConfig | undefined;
     /**
      * Sets the cache lookup policy used for every silent token acquisition.
      *
@@ -184,6 +186,16 @@ export declare class MsalConfigurator extends BaseConfigBuilder<MsalConfig> {
      * ```
      */
     setClient(client: IMsalClient): this;
+    /**
+     * Returns the currently configured MSAL client, if one has been set.
+     *
+     * @remarks
+     * This is useful in tests when a mock client has been provided and the test
+     * wants to adjust its state after it has been assigned to the configurator.
+     *
+     * @returns The configured client, or `undefined` when none has been set.
+     */
+    getClient(): IMsalClient | undefined;
     /**
      * Sets telemetry provider for MSAL authentication events.
      *
@@ -222,8 +234,72 @@ export declare class MsalConfigurator extends BaseConfigBuilder<MsalConfig> {
     /**
      * Processes and validates the configuration.
      *
-     * @param config - Raw configuration object
+     * @param rawConfig - Raw configuration object
+     * @param init - The builder arguments, carrying the host reference when hoisted
      * @returns Processed and validated configuration
      */
-    _processConfig(rawConfig: MsalConfig): Promise<MsalConfig>;
+    _processConfig(rawConfig: MsalConfig, init?: ConfigBuilderCallbackArgs): Promise<MsalConfig>;
+    /**
+     * Creates the client to authenticate through, when none was supplied.
+     *
+     * @remarks
+     * Called by {@link MsalConfigurator._processConfig | _processConfig} only when
+     * no client was set, so a client supplied through
+     * {@link MsalConfigurator.setClient | setClient} always wins. It is likewise
+     * not called when the module is hoisted onto a host application's provider —
+     * see {@link MsalConfigurator._isHoisted | _isHoisted}.
+     *
+     * This is the seam for authenticating through something other than Entra ID.
+     * Overriding it replaces only the client, leaving the builder, the schema
+     * validation and `MsalProvider` untouched — which is how
+     * `MsalMockConfigurator` substitutes an in-process client for tests.
+     *
+     * An override normally builds from
+     * {@link MsalConfigurator._createClientConfig | _createClientConfig}, so it
+     * receives the same fully-resolved {@link MsalClientConfig} the real client is
+     * built from rather than re-deriving it.
+     *
+     * Returning `undefined` is legitimate and means "there is nothing to build a
+     * client from", which leaves the module without one.
+     *
+     * @param config - The validated configuration the client is built from.
+     * @param init - The builder arguments, carrying the host reference when hoisted.
+     * @returns The client, or `undefined` when there is nothing to build one from.
+     */
+    protected _createClient(config: MsalConfig, _init?: ConfigBuilderCallbackArgs): Promise<IMsalClient | undefined>;
+    /**
+     * Whether this module is hoisted onto a host application's authentication.
+     *
+     * @remarks
+     * When an application runs inside a host — a portal loading an app, or an app
+     * loading a widget — the module initializer returns a proxy of the host's
+     * provider instead of building its own (see the host-provider branch of the
+     * module initializer). A client built during configuration would therefore be
+     * constructed and immediately discarded.
+     *
+     * Detecting this during configuration lets the configurator skip building a
+     * client entirely, which matters most for substituted clients: a mock client
+     * built here would otherwise silently shadow the host's real signed-in user.
+     *
+     * @param init - The builder arguments, carrying the host reference when hoisted.
+     * @returns `true` when a host provider will be used instead of a locally built client.
+     */
+    protected _isHoisted(init?: ConfigBuilderCallbackArgs): boolean;
+    /**
+     * Resolves the full MSAL client configuration to build a client from.
+     *
+     * @remarks
+     * Applies the defaults a client is expected to be built with — authority
+     * derived from the tenant, cache location, telemetry-backed logging and the
+     * configured cache lookup policy.
+     *
+     * Kept separate from {@link MsalConfigurator._createClient | _createClient} so
+     * that substituting the client does not also mean re-implementing this
+     * resolution. `MsalMockConfigurator` relies on it to hand its mock client the
+     * very same configuration the real client would have received.
+     *
+     * @param config - The validated configuration.
+     * @returns The client configuration, or `undefined` when none was declared.
+     */
+    protected _createClientConfig(config: MsalConfig): MsalClientConfig | undefined;
 }

package/dist/types/__tests__/create-proxy-provider.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/__tests__/mock/msal-mock.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/index.d.ts

@@ -28,5 +28,10 @@ export { module, configureMsal, enableMSAL, type MsalModule, type AuthConfigFn,
 export type { IMsalProvider } from './MsalProvider.interface';
 export type { IMsalClient } from './MsalClient.interface';
 export { MsalClient, type MsalClientConfig } from './MsalClient';
+/**
+ * Required to implement {@link IMsalProvider}, whose `msalVersion` member is
+ * typed as this enum.
+ */
+export { MsalModuleVersion } from './static';
 export type { AccountInfo, AuthenticationResult } from './types';
 export { default } from './module';

package/dist/types/mock/MsalMockClient.d.ts

@@ -0,0 +1,270 @@
+import type { AccountInfo, AuthenticationResult, AuthorizationCodeRequest, PopupRequest, RedirectRequest, SilentRequest, SsoSilentRequest, EndSessionRequest, EndSessionPopupRequest, InitializeApplicationRequest, WrapperSKU, INavigationClient, BrowserConfiguration, Logger, PerformanceCallbackFunction, EventCallbackFunction, EventType, ClearCacheRequest } from '@azure/msal-browser';
+import type { AcquireTokenOptions, AcquireTokenResult, IMsalClient, LoginOptions, LoginResult } from '../MsalClient.interface';
+import type { MsalClientConfig } from '../MsalClient';
+/**
+ * The user a mock MSAL client signs in.
+ *
+ * @remarks
+ * Deliberately separate from {@link MsalClientConfig}: a client is configured
+ * with *what it talks to*, never with *who is signed in*. The real client learns
+ * the user from Entra ID, so the mock is told after it is constructed — see
+ * {@link MsalMockClient.setUser | setUser}.
+ */
+export interface MsalMockUser {
+    /** Display name of the signed-in user. Defaults to `Test User`. */
+    name?: string;
+    /** UPN / email of the signed-in user. Defaults to `test.user@equinor.com`. */
+    username?: string;
+    /** Object ID of the signed-in user. Defaults to `fusion-mock-user`. */
+    userId?: string;
+    /** Tenant the user belongs to. Defaults to the client's configured tenant. */
+    tenantId?: string;
+    /** Scopes granted when a request does not specify its own. */
+    scopes?: string[];
+    /** Preconfigured account to use for signed-in state. */
+    account?: AccountInfo;
+    /**
+     * Start without a signed-in user, while keeping this identity.
+     *
+     * @remarks
+     * Silent flows then resolve empty so the provider follows its unauthenticated
+     * path, while an explicit login still succeeds *as this user*. That lets a
+     * test drive the sign-in journey and assert on who it ends up as, rather than
+     * only on its end state.
+     *
+     * Pass `null` instead of a user when the identity does not matter.
+     */
+    signedOut?: boolean;
+}
+/**
+ * A stand-in for the MSAL client that resolves tokens in-process.
+ *
+ * @remarks
+ * Constructed from {@link MsalClientConfig} — the very same argument
+ * {@link MsalClient} takes — so it is a drop-in substitute rather than a second
+ * API to learn. `setClientConfig` therefore means the same thing whether a test
+ * runs against Entra ID or against this client.
+ *
+ * Only the boundary that would contact Entra ID is replaced. The real
+ * `MsalProvider` runs on top of it unchanged, so account handling, silent-token
+ * preference, scope resolution, proxy providers and telemetry behave as they do in
+ * production — the test exercises the framework rather than the mock.
+ *
+ * Tokens are structurally valid, unsigned JWTs and are byte-identical between runs.
+ * They are **not** cryptographically valid and are rejected by any real service.
+ */
+export declare class MsalMockClient implements IMsalClient {
+    #private;
+    /**
+     * Mirrors MSAL's redirect completion, which is a no-op for this in-process mock.
+     * @returns Always `null`, because the mock performs no redirect.
+     */
+    handleRedirectPromise(): Promise<AuthenticationResult | null>;
+    /**
+     * Mirrors silent SSO and returns a token for the cached mock account.
+     * @param request - Silent SSO options and requested scopes.
+     * @returns A mock authentication result.
+     * @throws When no account is cached.
+     */
+    ssoSilent(request: SsoSilentRequest): Promise<AuthenticationResult>;
+    /**
+     * Mirrors popup login by signing in the configured mock user immediately.
+     * @param request - Optional popup options and requested scopes.
+     * @returns A mock authentication result.
+     */
+    loginPopup(request?: PopupRequest): Promise<AuthenticationResult>;
+    /**
+     * Mirrors redirect login without navigating, because the mock has no browser boundary.
+     * @param _request - Redirect options, accepted for interface compatibility.
+     */
+    loginRedirect(_request?: RedirectRequest): Promise<void>;
+    /**
+     * Mirrors the framework login entry point with an immediate mock sign-in.
+     * @param options - Login options including the requested scopes.
+     * @returns A mock login result.
+     */
+    login(options: LoginOptions): Promise<LoginResult>;
+    /** Mirrors logout by removing the active mock account from the cache. */
+    logout(): Promise<void>;
+    /**
+     * Mirrors MSAL initialization without performing a network handshake.
+     * @param _request - Initialization options, accepted for interface compatibility.
+     */
+    initialize(_request?: InitializeApplicationRequest): Promise<void>;
+    /**
+     * Mirrors popup token acquisition using the mock login flow.
+     * @param request - Popup token request.
+     * @returns A mock authentication result.
+     */
+    acquireTokenPopup(request: PopupRequest): Promise<AuthenticationResult>;
+    /**
+     * Mirrors redirect token acquisition without browser navigation.
+     * @param request - Redirect token request.
+     */
+    acquireTokenRedirect(request: RedirectRequest): Promise<void>;
+    /**
+     * Mirrors silent token acquisition for the cached mock account.
+     * @param request - Silent token request.
+     * @returns A mock authentication result.
+     * @throws When no account is cached.
+     */
+    acquireTokenSilent(request: SilentRequest): Promise<AuthenticationResult>;
+    /**
+     * Mirrors MSAL event registration; events are intentionally not emitted by the mock.
+     * @param _callback - Event handler, accepted for interface compatibility.
+     * @param _eventTypes - Event types, accepted for interface compatibility.
+     * @returns Always `null`, because the mock registers no callback.
+     */
+    addEventCallback(_callback: EventCallbackFunction, _eventTypes?: EventType[]): string | null;
+    /**
+     * Mirrors event removal as a no-op because this mock registers no callbacks.
+     * @param _callbackId - Callback identifier, accepted for interface compatibility.
+     */
+    removeEventCallback(_callbackId: string): void;
+    /**
+     * Mirrors performance callback registration with a stable mock identifier.
+     * @param _callback - Performance handler, accepted for interface compatibility.
+     * @returns A stable mock callback identifier.
+     */
+    addPerformanceCallback(_callback: PerformanceCallbackFunction): string;
+    /**
+     * Mirrors performance callback removal and reports successful mock removal.
+     * @param _callbackId - Callback identifier, accepted for interface compatibility.
+     * @returns Always `true` because no callback state is retained.
+     */
+    removePerformanceCallback(_callbackId: string): boolean;
+    /**
+     * Mirrors MSAL account lookup against the mock cache.
+     * @param accountFilter - Account fields to match.
+     * @returns The first matching account, or `null`.
+     */
+    getAccount(accountFilter: unknown): AccountInfo | null;
+    /**
+     * Mirrors MSAL account enumeration using the mock cache.
+     * @param _accountFilter - Account filter, accepted for interface compatibility.
+     * @returns All accounts currently in the mock cache.
+     */
+    getAllAccounts(_accountFilter?: unknown): AccountInfo[];
+    /**
+     * Mirrors redirect logout without navigating in the mock environment.
+     * @param _request - Logout options, accepted for interface compatibility.
+     */
+    logoutRedirect(_request?: EndSessionRequest): Promise<void>;
+    /**
+     * Mirrors popup logout without opening a browser window.
+     * @param _request - Logout options, accepted for interface compatibility.
+     */
+    logoutPopup(_request?: EndSessionPopupRequest): Promise<void>;
+    /**
+     * Mirrors MSAL logger access; the mock does not retain a logger.
+     * @returns An interface-compatible empty logger value.
+     */
+    getLogger(): Logger;
+    /**
+     * Mirrors logger configuration as a no-op for the mock.
+     * @param _logger - Logger, accepted for interface compatibility.
+     */
+    setLogger(_logger: unknown): void;
+    /**
+     * Mirrors wrapper metadata initialization as a no-op for the mock.
+     * @param _sku - Wrapper identifier, accepted for interface compatibility.
+     * @param _version - Wrapper version, accepted for interface compatibility.
+     */
+    initializeWrapperLibrary(_sku: WrapperSKU, _version: string): void;
+    /**
+     * Mirrors navigation-client configuration as a no-op because no navigation occurs.
+     * @param _navigationClient - Navigation client, accepted for interface compatibility.
+     */
+    setNavigationClient(_navigationClient: INavigationClient): void;
+    /**
+     * Mirrors configuration access and rejects it because the mock has no browser config.
+     * @returns Never; this mock does not expose browser configuration.
+     * @throws Always, because browser configuration is unsupported.
+     */
+    getConfiguration(): BrowserConfiguration;
+    /**
+     * Mirrors cache hydration as a no-op because mock tokens are created in-process.
+     * @param _result - Authentication result, accepted for interface compatibility.
+     * @param _request - Original token request, accepted for interface compatibility.
+     */
+    hydrateCache(_result: AuthenticationResult, _request: SilentRequest | SsoSilentRequest | RedirectRequest | PopupRequest): Promise<void>;
+    /**
+     * Mirrors MSAL cache clearing by removing every mock account.
+     * @param _request - Cache-clear options, accepted for interface compatibility.
+     */
+    clearCache(_request?: ClearCacheRequest): Promise<void>;
+    /**
+     * Mirrors the generic token acquisition entry point for the active mock account.
+     * @param options - Token acquisition options.
+     * @returns A mock result, or `null` without an active account.
+     */
+    acquireToken(options: AcquireTokenOptions): Promise<AcquireTokenResult>;
+    /**
+     * Mirrors authorization-code exchange by signing in and returning a mock result.
+     * @param request - Authorization-code request.
+     * @returns A mock authentication result.
+     */
+    acquireTokenByCode(request: AuthorizationCodeRequest): Promise<AuthenticationResult>;
+    /**
+     * Creates a mock client for the services the given configuration points at.
+     *
+     * @remarks
+     * Takes the same argument as {@link MsalClient}. A user named `Test User` is
+     * already in the account cache, so a provider built on this client boots the
+     * way one does for a returning user with a live session — no sign-in runs, and
+     * the provider's start-up path sees the state it would see in production. Use
+     * {@link MsalMockClient.setUser | setUser} to say who that user is.
+     *
+     * @param config - The same client configuration the real client is built from.
+     */
+    constructor(config: MsalClientConfig);
+    /**
+     * Returns the client identifier used by tokens minted by this mock.
+     * @returns The configured client identifier.
+     */
+    get clientId(): string | undefined;
+    /**
+     * Returns the tenant identifier used by tokens minted by this mock.
+     * @returns The configured tenant identifier.
+     */
+    get tenantId(): string | undefined;
+    /**
+     * Reports whether the mock currently has an active account.
+     * @returns Whether an account is active.
+     */
+    get hasValidClaims(): boolean;
+    /**
+     * Mirrors MSAL active-account access using the mock's single active account.
+     * @returns The active account, or `null`.
+     */
+    getActiveAccount(): AccountInfo | null;
+    /**
+     * Makes an account the active one, adding it to the cache if it is unknown.
+     *
+     * @remarks
+     * Real MSAL requires the account to already be cached. Accepting an unknown
+     * one is a deliberate concession to tests: it is the shortest way to swap the
+     * signed-in user between runs, without reconstructing the framework.
+     *
+     * @param next - The account to make active, or `null` to sign out.
+     */
+    setActiveAccount(next: AccountInfo | null): void;
+    /**
+     * Declares who is signed in, replacing whoever was.
+     *
+     * @remarks
+     * This is the counterpart to a real sign-in: the client is configured with
+     * what it talks to, and learns the user separately. `MsalMockConfigurator`
+     * applies it as the configuration is assembled, so the account is in the cache
+     * before `MsalProvider.initialize` runs — the provider then behaves as it does
+     * for a returning user with a live session.
+     *
+     * Values left out keep whatever they were. Passing `null` signs out and
+     * forgets the identity, so the provider follows its unauthenticated path;
+     * `{ signedOut: true }` does the same but keeps the identity, so a later login
+     * resolves as that user.
+     *
+     * @param user - The user to sign in, or `null` when nobody is.
+     */
+    setUser(user: MsalMockUser | null): void;
+}

package/dist/types/mock/MsalMockConfigurator.d.ts

@@ -0,0 +1,156 @@
+import type { ConfigBuilderCallback, ConfigBuilderCallbackArgs } from '@equinor/fusion-framework-module';
+import type { IMsalClient } from '../MsalClient.interface';
+import { MsalConfigurator, type MsalConfig } from '../MsalConfigurator';
+import { 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 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 declare class MsalMockConfigurator extends MsalConfigurator {
+    #private;
+    /**
+     * 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',
+     * }));
+     * ```
+     */
+    setAccount(account: MsalMockUser | null | ConfigBuilderCallback<MsalMockUser | null>): this;
+    /**
+     * 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.
+     */
+    _processConfig(rawConfig: MsalConfig, init?: ConfigBuilderCallbackArgs): Promise<MsalConfig>;
+    /**
+     * 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 _createClient(config: MsalConfig): Promise<IMsalClient>;
+}

package/dist/types/mock/create-mock-token.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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;
+}
+/**
+ * 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 declare const createMockToken: (claims?: MockTokenClaims) => string;

package/dist/types/mock/create-msal-mock-client.d.ts

@@ -0,0 +1,14 @@
+import type { IMsalClient } from '../MsalClient.interface';
+import type { MsalClientConfig } from '../MsalClient';
+import { 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 declare const createMsalMockClient: (config: MsalClientConfig, user?: MsalMockUser) => IMsalClient;

package/dist/types/mock/decode-jwt-segment.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 declare function decodeJwtSegment(segment: string): string;
+export default decodeJwtSegment;