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

package/dist/types/__tests__/mock/create-mock-user-from-token.test.d.ts

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

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

@@ -267,4 +267,16 @@ export declare class MsalMockClient implements IMsalClient {
      * @param user - The user to sign in, or `null` when nobody is.
      */
     setUser(user: MsalMockUser | null): void;
+    /**
+     * Overrides the token returned by future results, independent of who is signed in.
+     *
+     * @remarks
+     * Use this when a backend mock validates its own tokens (specific claims, an
+     * audience, or a signature) — supplying the exact token here means that
+     * backend sees the token it issued, rather than a mock-shaped substitute this
+     * client would otherwise fabricate from the signed-in user's fields.
+     *
+     * @param token - The token to return verbatim, or `null` to resume generating one.
+     */
+    setToken(token: string | null): void;
 }

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

@@ -23,6 +23,11 @@ declare module '../msal-config-schema' {
              * `null` when nobody is signed in.
              */
             account?: MsalMockUser | null;
+            /**
+             * The token to return verbatim instead of one generated from the
+             * signed-in user's fields.
+             */
+            token?: string;
         };
     }
 }
@@ -105,6 +110,31 @@ export declare class MsalMockConfigurator extends MsalConfigurator {
      * ```
      */
     setAccount(account: MsalMockUser | null | ConfigBuilderCallback<MsalMockUser | null>): this;
+    /**
+     * Declares the token to return, independent of who is signed in.
+     *
+     * @remarks
+     * Use this when a backend mock validates its own tokens (specific claims, an
+     * audience, or a signature) — the client then returns this token verbatim
+     * instead of fabricating one from the signed-in user's fields.
+     *
+     * @param token - A JWT (e.g. from `createMockToken`, or issued by an external mock).
+     * @param skipResolve - When `true`, override only the token and leave an account
+     * declared through {@link setAccount} untouched. Defaults to `false`, which also signs
+     * in the user described by the token's claims, via {@link createMockUserFromToken}.
+     * @returns The builder, for chaining.
+     *
+     * @example Sign in as whoever the token names
+     * ```typescript
+     * builder.setToken(token);
+     * ```
+     *
+     * @example Keep a separately declared account, but return this exact token
+     * ```typescript
+     * builder.setAccount({ name: 'Ada Lovelace' }).setToken(token, true);
+     * ```
+     */
+    setToken(token: string, skipResolve?: boolean): this;
     /**
      * Assembles the configuration, then signs the declared user in.
      *

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

@@ -0,0 +1,25 @@
+import type { MsalMockUser } from './MsalMockClient';
+/**
+ * Derives a {@link MsalMockUser} from a JWT's payload claims, so a token minted
+ * outside this module (e.g. by a backend's own mock) can drive who the mock
+ * signs in as.
+ *
+ * @remarks
+ * Maps the standard Entra ID claims Fusion applications read — `name`,
+ * `preferred_username`, `oid`, `tid`, `scp` — onto the matching
+ * {@link MsalMockUser} fields. Identity only: it does not affect which token
+ * the client returns — use {@link MsalMockConfigurator.setToken} for that.
+ *
+ * @param token - A JWT (e.g. from {@link createMockToken}, or issued by an
+ * external mock) with a base64url-encoded payload segment.
+ * @returns A mock user built from the token's claims.
+ * @throws When the token has no payload segment (`header.payload.signature`).
+ *
+ * @example
+ * ```typescript
+ * enableMsalMock(configurator, (builder) => {
+ *   builder.setAccount(createMockUserFromToken(token));
+ * });
+ * ```
+ */
+export declare const createMockUserFromToken: (token: string) => MsalMockUser;

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

@@ -26,4 +26,5 @@ 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 { createMockUserFromToken } from './create-mock-user-from-token';
 export { decodeJwtSegment } from './decode-jwt-segment';

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "11.0.0-next.0";
+export declare const version = "11.0.0";

package/docs/testing.md

@@ -69,6 +69,24 @@ The user is in place **before** `MsalProvider.initialize()` runs, so the provide
 
 `setClient` replaces the client, but not the rule: the declared user is signed in on whichever client the module authenticates through, so a mock client supplied that way receives it too.
 
+## Returning an exact token
+
+Most tests only care who is signed in and let the mock fabricate a token from that user's fields. When a backend mock validates the token itself — specific claims, an audience, or a signature — it needs to see the exact token it expects instead:
+
+```typescript
+enableMsalMock(configurator, (builder) => {
+  builder.setToken(token);
+});
+```
+
+`setToken` also signs in the user the token's claims describe, via `createMockUserFromToken` — so `acquireAccessToken` returns this token, and the account APIs agree with it. Pass `true` as the second argument to keep a separately declared account instead:
+
+```typescript
+enableMsalMock(configurator, (builder) => {
+  builder.setAccount({ name: 'Ada Lovelace' }).setToken(token, true);
+});
+```
+
 | Option | Default | Purpose |
 | --- | --- | --- |
 | `name` | `Test User` | Display name |
@@ -150,6 +168,12 @@ import { createMockToken } from '@equinor/fusion-framework-module-msal/mock';
 const token = createMockToken({ oid: 'fusion-mock-user' });
 ```
 
+To use a generated token as the signed-in user for `ffc app dev --mock`, `ffc app serve --mock`,
+or a Vite SPA, see
+[Generate a mock user and update `.env`](../../../vite-plugins/spa/README.md#generate-a-mock-user-and-update-env).
+That workflow documents persistent mock-auth configuration, identity claims, and custom `scp`
+token scopes.
+
 ## Exports
 
 | Export | Purpose |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-msal",
-  "version": "11.0.0-next.0",
+  "version": "11.0.0",
   "description": "Microsoft Authentication Library (MSAL) integration module for Fusion Framework",
   "main": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",
@@ -57,16 +57,16 @@
     "semver": "^7.7.4",
     "typescript": "^7.0.2",
     "zod": "^4.4.3",
-    "@equinor/fusion-framework-module": "^6.1.3-next.0",
-    "@equinor/fusion-framework-module-telemetry": "^8.0.0-next.0"
+    "@equinor/fusion-framework-module": "^6.1.3",
+    "@equinor/fusion-framework-module-telemetry": "^7.1.0"
   },
   "peerDependencies": {
     "@types/semver": "^7.0.0",
     "semver": "^7.0.0",
     "typescript": ">=5.0.0",
     "zod": "^4.0.0",
-    "@equinor/fusion-framework-module": "^6.1.3-next.0",
-    "@equinor/fusion-framework-module-telemetry": "^8.0.0-next.0"
+    "@equinor/fusion-framework-module": "^6.1.3",
+    "@equinor/fusion-framework-module-telemetry": "^7.1.0"
   },
   "peerDependenciesMeta": {
     "@equinor/fusion-framework-module-telemetry": {

package/src/__tests__/mock/create-mock-user-from-token.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+
+import { createMockToken } from '../../mock/create-mock-token';
+import { createMockUserFromToken } from '../../mock/create-mock-user-from-token';
+
+describe('createMockUserFromToken', () => {
+  it('maps identity claims onto the matching MsalMockUser fields', () => {
+    const token = createMockToken({
+      name: 'Ada Lovelace',
+      preferred_username: 'ada@equinor.com',
+      oid: 'ada-object-id',
+      tid: 'ada-tenant-id',
+      scp: 'User.Read Files.Read',
+    });
+
+    expect(createMockUserFromToken(token)).toEqual({
+      name: 'Ada Lovelace',
+      username: 'ada@equinor.com',
+      userId: 'ada-object-id',
+      tenantId: 'ada-tenant-id',
+      scopes: ['User.Read', 'Files.Read'],
+    });
+  });
+
+  it('leaves a field undefined rather than fabricating one, when a claim is absent', () => {
+    const token = createMockToken({
+      name: undefined,
+      preferred_username: undefined,
+      scp: undefined,
+    });
+
+    const user = createMockUserFromToken(token);
+
+    expect(user.name).toBeUndefined();
+    expect(user.username).toBeUndefined();
+    expect(user.scopes).toBeUndefined();
+  });
+
+  it('throws for a token with no payload segment', () => {
+    expect(() => createMockUserFromToken('not-a-jwt')).toThrow(/payload segment/);
+  });
+
+  it('throws for an empty string', () => {
+    expect(() => createMockUserFromToken('')).toThrow(/payload segment/);
+  });
+});

package/src/__tests__/mock/msal-mock.test.ts

@@ -12,6 +12,7 @@ import type { IMsalProvider } from '../../MsalProvider.interface';
 import { enableMSAL, module as realModule } from '../../module';
 import {
   MsalMockClient,
+  createMockToken,
   createMsalMockClient,
   enableMsalMock,
   msalMockModule,
@@ -425,6 +426,74 @@ describe('MsalMockClient', () => {
 
     expect(result?.accessToken).toBe('mock-token');
   });
+
+  it('returns a token set directly on the client verbatim', async () => {
+    const client = new MsalMockClient(clientConfig());
+    const token = createMockToken({ name: 'Direct Token' });
+
+    client.setToken(token);
+    const result = await client.acquireToken({ request: { scopes: ['X'] } });
+
+    expect(result?.accessToken).toBe(token);
+    expect(result?.idToken).toBe(token);
+  });
+
+  it('resumes generating tokens once setToken(null) clears the override', async () => {
+    const client = new MsalMockClient(clientConfig());
+    const token = createMockToken({ name: 'Direct Token' });
+    client.setToken(token);
+
+    client.setToken(null);
+    const result = await client.acquireToken({ request: { scopes: ['X'] } });
+
+    expect(result?.accessToken).not.toBe(token);
+  });
+});
+
+describe('MsalMockConfigurator.setToken', () => {
+  it('returns the exact token instead of one generated from the account', async () => {
+    const token = createMockToken({ name: 'Token User' });
+    const provider = await initializeMockWith((builder) => builder.setToken(token));
+
+    const result = await provider.client.acquireToken({ request: { scopes: ['X'] } });
+
+    expect(result?.accessToken).toBe(token);
+    expect(result?.idToken).toBe(token);
+  });
+
+  it('signs in the account named by the token claims by default', async () => {
+    const token = createMockToken({
+      name: 'Token User',
+      preferred_username: 'token.user@equinor.com',
+    });
+    const provider = await initializeMockWith((builder) => builder.setToken(token));
+
+    expect(provider.account?.name).toBe('Token User');
+    expect(provider.account?.username).toBe('token.user@equinor.com');
+  });
+
+  it('keeps a separately declared account when skipResolve is true', async () => {
+    // skipResolve overrides only the returned token, leaving setAccount's declaration alone
+    const token = createMockToken({ name: 'Token User' });
+    const provider = await initializeMockWith((builder) => {
+      builder.setAccount({ name: 'Ada Lovelace' });
+      builder.setToken(token, true);
+    });
+
+    expect(provider.account?.name).toBe('Ada Lovelace');
+    const result = await provider.client.acquireToken({ request: { scopes: ['X'] } });
+    expect(result?.accessToken).toBe(token);
+  });
+
+  it('resumes generating tokens once setToken(null) is called on the client', async () => {
+    const token = createMockToken({ name: 'Token User' });
+    const provider = await initializeMockWith((builder) => builder.setToken(token));
+
+    (provider.client as MsalMockClient).setToken(null);
+    const result = await provider.client.acquireToken({ request: { scopes: ['X'] } });
+
+    expect(result?.accessToken).not.toBe(token);
+  });
 });
 
 describe('setAccount(null)', () => {

package/src/mock/MsalMockClient.ts

@@ -88,6 +88,7 @@ export class MsalMockClient implements IMsalClient {
   };
   #cache = new Map<string, AccountInfo>();
   #activeAccountId: string | null = null;
+  #token: string | null = null;
 
   /**
    * The account currently signed in, or `null`.
@@ -549,6 +550,21 @@ export class MsalMockClient implements IMsalClient {
     this.#signIn(account ?? this.#createAccount());
   }
 
+  /**
+   * Overrides the token returned by future results, independent of who is signed in.
+   *
+   * @remarks
+   * Use this when a backend mock validates its own tokens (specific claims, an
+   * audience, or a signature) — supplying the exact token here means that
+   * backend sees the token it issued, rather than a mock-shaped substitute this
+   * client would otherwise fabricate from the signed-in user's fields.
+   *
+   * @param token - The token to return verbatim, or `null` to resume generating one.
+   */
+  public setToken(token: string | null): void {
+    this.#token = token;
+  }
+
   /**
    * Creates the one account represented by this mock's configured identity.
    * @returns An MSAL-shaped account for the configured user.
@@ -571,14 +587,17 @@ export class MsalMockClient implements IMsalClient {
    */
   #createResult(scopes?: string[]): AuthenticationResult {
     const granted = scopes?.length ? scopes : this.#user.scopes;
-    const token = createMockToken({
-      name: this.#user.name,
-      preferred_username: this.#user.username,
-      oid: this.#user.userId,
-      tid: this.#user.tenantId,
-      aud: this.#user.clientId,
-      scp: granted.join(' '),
-    });
+    // a caller-supplied token is sent verbatim so a backend mock validating it sees what it expects
+    const token =
+      this.#token ??
+      createMockToken({
+        name: this.#user.name,
+        preferred_username: this.#user.username,
+        oid: this.#user.userId,
+        tid: this.#user.tenantId,
+        aud: this.#user.clientId,
+        scp: granted.join(' '),
+      });
 
     // Object shape matches AuthenticationResult's fields consumers rely on; the real
     // type also carries browser-only fields (e.g. `familyId`) this mock intentionally omits

package/src/mock/MsalMockConfigurator.ts

@@ -9,6 +9,7 @@ import type { MsalClientConfig } from '../MsalClient';
 import { MsalConfigurator, type MsalConfig } from '../MsalConfigurator';
 
 import { MsalMockClient, type MsalMockUser } from './MsalMockClient';
+import { createMockUserFromToken } from './create-mock-user-from-token';
 
 /**
  * Declares the mock's own branch of the MSAL configuration.
@@ -31,6 +32,11 @@ declare module '../msal-config-schema' {
        * `null` when nobody is signed in.
        */
       account?: MsalMockUser | null;
+      /**
+       * The token to return verbatim instead of one generated from the
+       * signed-in user's fields.
+       */
+      token?: string;
     };
   }
 }
@@ -135,36 +141,86 @@ export class MsalMockConfigurator extends MsalConfigurator {
   }
 
   /**
-   * Signs the declared user in on the client the module authenticates through.
+   * Declares the token to return, independent of who is signed in.
    *
    * @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.
+   * Use this when a backend mock validates its own tokens (specific claims, an
+   * audience, or a signature) — the client then returns this token verbatim
+   * instead of fabricating one from the signed-in user's fields.
+   *
+   * @param token - A JWT (e.g. from `createMockToken`, or issued by an external mock).
+   * @param skipResolve - When `true`, override only the token and leave an account
+   * declared through {@link setAccount} untouched. Defaults to `false`, which also signs
+   * in the user described by the token's claims, via {@link createMockUserFromToken}.
+   * @returns The builder, for chaining.
+   *
+   * @example Sign in as whoever the token names
+   * ```typescript
+   * builder.setToken(token);
+   * ```
+   *
+   * @example Keep a separately declared account, but return this exact token
+   * ```typescript
+   * builder.setAccount({ name: 'Ada Lovelace' }).setToken(token, true);
+   * ```
+   */
+  public setToken(token: string, skipResolve = false): this {
+    this._set('mock.token', token);
+    // skipResolve defaults to false - most callers want the token's claims to name who is signed in
+    if (!skipResolve) {
+      this.setAccount(createMockUserFromToken(token));
+    }
+    return this;
+  }
+
+  /**
+   * Resolves the client the module authenticates through, wherever it was built.
+   *
+   * @remarks
+   * Shared by {@link setAccount} and {@link setToken} application: neither can
+   * assume the scope declaring mock state is the scope that built 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.
+   * @param action - Describes what could not be applied, for the thrown error.
+   * @returns The resolved mock client.
    * @throws When the resolved client is not a {@link MsalMockClient}.
    */
-  #signIn(
-    account: MsalMockUser | null,
+  #getClient(
     config: MsalConfig,
-    init?: ConfigBuilderCallbackArgs,
-  ): void {
+    init: ConfigBuilderCallbackArgs | undefined,
+    action: string,
+  ): MsalMockClient {
     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.
+    // Reject a real client because mock 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.',
+        `MsalMockConfigurator: cannot ${action}, because this module does not authenticate through a mock client. Declare it where that client is configured instead.`,
       );
     }
 
-    client.setUser(account);
+    return client;
+  }
+
+  /**
+   * Signs the declared user in on the client the module authenticates through.
+   *
+   * @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 {
+    this.#getClient(config, init, 'sign a user in').setUser(account);
   }
 
   /**
@@ -211,6 +267,14 @@ export class MsalMockConfigurator extends MsalConfigurator {
       this.#signIn(account, config, init);
     }
 
+    // Applied after the account so a token declared alongside `skipResolve: true`
+    // overrides whatever `setUser` above just fabricated.
+    const token = rawConfig.mock?.token;
+    // absent means the test declared no token override; leave the client generating its own
+    if (token !== undefined) {
+      this.#getClient(config, init, 'set a token').setToken(token);
+    }
+
     return config;
   }
 

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

@@ -0,0 +1,46 @@
+import type { MsalMockUser } from './MsalMockClient';
+import { decodeJwtSegment } from './decode-jwt-segment';
+import type { MockTokenClaims } from './create-mock-token';
+
+/**
+ * Derives a {@link MsalMockUser} from a JWT's payload claims, so a token minted
+ * outside this module (e.g. by a backend's own mock) can drive who the mock
+ * signs in as.
+ *
+ * @remarks
+ * Maps the standard Entra ID claims Fusion applications read — `name`,
+ * `preferred_username`, `oid`, `tid`, `scp` — onto the matching
+ * {@link MsalMockUser} fields. Identity only: it does not affect which token
+ * the client returns — use {@link MsalMockConfigurator.setToken} for that.
+ *
+ * @param token - A JWT (e.g. from {@link createMockToken}, or issued by an
+ * external mock) with a base64url-encoded payload segment.
+ * @returns A mock user built from the token's claims.
+ * @throws When the token has no payload segment (`header.payload.signature`).
+ *
+ * @example
+ * ```typescript
+ * enableMsalMock(configurator, (builder) => {
+ *   builder.setAccount(createMockUserFromToken(token));
+ * });
+ * ```
+ */
+export const createMockUserFromToken = (token: string): MsalMockUser => {
+  const [, payload] = token.split('.');
+  // fail loudly rather than signing in an empty/garbage user from a malformed token
+  if (!payload) {
+    throw new Error(
+      'createMockUserFromToken: expected a JWT with a payload segment (header.payload.signature)',
+    );
+  }
+
+  const claims: MockTokenClaims = JSON.parse(decodeJwtSegment(payload));
+
+  return {
+    name: claims.name,
+    username: claims.preferred_username,
+    userId: claims.oid,
+    tenantId: claims.tid,
+    scopes: claims.scp?.split(' '),
+  };
+};

package/src/mock/index.ts

@@ -26,4 +26,5 @@ 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 { createMockUserFromToken } from './create-mock-user-from-token';
 export { decodeJwtSegment } from './decode-jwt-segment';

package/src/version.ts

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

package/.changeset/msal-auth-provider-fix.md

@@ -1,7 +0,0 @@
----
-"@equinor/fusion-framework-module-msal": patch
----
-
-Fixed AuthProvider to properly extend BaseModuleProvider, eliminating module initialization warnings about provider inheritance.
-
-The AuthProvider class now inherits the standard version property and dispose method from BaseModuleProvider, ensuring proper integration with the Fusion Framework's module system.