@axa-fr/oidc-client 7.27.11 → 7.27.12

package/src/oidcClient.ts

@@ -1,4 +1,9 @@
 import { fetchWithTokens } from './fetch';
+import {
+  ServiceWorkerSignalMessage,
+  ServiceWorkerSignalOptions,
+  signalServiceWorkerAsync,
+} from './initWorker.js';
 import { ILOidcLocation, OidcLocation } from './location';
 import { LoginCallback, Oidc } from './oidc.js';
 import { getValidTokenAsync, OidcToken, Tokens, ValidToken } from './parseTokens.js';
@@ -130,6 +135,30 @@ export class OidcClient {
   userInfo<T extends OidcUserInfo = OidcUserInfo>(): T {
     return this._oidc.userInfo;
   }
+
+  /**
+   * High-level helper to send a message to the OIDC service worker.
+   *
+   * Wraps the low-level `postMessage` + `MessageChannel` plumbing and
+   * returns the response posted back by the worker. Use the typed message
+   * symbols exported from `@axa-fr/oidc-client-service-worker/protocol`
+   * (`ServiceWorkerMessageType`) to build messages.
+   *
+   * @throws if no service worker is registered for the current
+   * configuration, or if the worker does not respond before the timeout
+   * elapses.
+   */
+  async signalServiceWorker<TResponse = unknown>(
+    message: ServiceWorkerSignalMessage,
+    options?: ServiceWorkerSignalOptions,
+  ): Promise<TResponse> {
+    return signalServiceWorkerAsync(
+      this._oidc.configuration,
+      this._oidc.configurationName,
+      message,
+      options,
+    ) as Promise<TResponse>;
+  }
 }
 
 export interface OidcUserInfo {

package/src/protocol.spec.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  buildDpopSecuredPlaceholder,
+  buildSecuredTokenPlaceholder,
+  buildStorageKey,
+  DPOP_TOKEN_PLACEHOLDER_PREFIX,
+  isServiceWorkerMessageType,
+  PROTOCOL_VERSION,
+  ServiceWorkerMessageType,
+  STORAGE_KEY_PREFIX,
+  SW_CONTROLLER_CHANGE_RELOAD_COUNT_KEY,
+  TOKEN_PLACEHOLDERS,
+} from './protocol';
+
+describe('public oidc-client protocol surface', () => {
+  it('exposes a stable PROTOCOL_VERSION', () => {
+    expect(PROTOCOL_VERSION).toMatch(/^\d+\.\d+\.\d+$/);
+  });
+
+  it('matches the wire-level message types documented in PROTOCOL.md', () => {
+    expect(ServiceWorkerMessageType).toEqual({
+      SKIP_WAITING: 'SKIP_WAITING',
+      CLAIM: 'claim',
+      CLEAR: 'clear',
+      INIT: 'init',
+      SET_STATE: 'setState',
+      GET_STATE: 'getState',
+      SET_CODE_VERIFIER: 'setCodeVerifier',
+      GET_CODE_VERIFIER: 'getCodeVerifier',
+      SET_SESSION_STATE: 'setSessionState',
+      GET_SESSION_STATE: 'getSessionState',
+      SET_NONCE: 'setNonce',
+      GET_NONCE: 'getNonce',
+      SET_DPOP_NONCE: 'setDemonstratingProofOfPossessionNonce',
+      GET_DPOP_NONCE: 'getDemonstratingProofOfPossessionNonce',
+      SET_DPOP_JWK: 'setDemonstratingProofOfPossessionJwk',
+      GET_DPOP_JWK: 'getDemonstratingProofOfPossessionJwk',
+    });
+  });
+
+  it('exposes the token placeholders the service worker emits', () => {
+    expect(TOKEN_PLACEHOLDERS).toEqual({
+      ACCESS_TOKEN: 'ACCESS_TOKEN_SECURED_BY_OIDC_SERVICE_WORKER',
+      REFRESH_TOKEN: 'REFRESH_TOKEN_SECURED_BY_OIDC_SERVICE_WORKER',
+      NONCE_TOKEN: 'NONCE_SECURED_BY_OIDC_SERVICE_WORKER',
+      CODE_VERIFIER: 'CODE_VERIFIER_SECURED_BY_OIDC_SERVICE_WORKER',
+    });
+    expect(DPOP_TOKEN_PLACEHOLDER_PREFIX).toBe('DPOP_SECURED_BY_OIDC_SERVICE_WORKER');
+  });
+});
+
+describe('protocol helpers', () => {
+  it('builds secured token placeholders that match the SW output', () => {
+    expect(buildSecuredTokenPlaceholder(TOKEN_PLACEHOLDERS.ACCESS_TOKEN, 'demo', 'tab-1')).toBe(
+      'ACCESS_TOKEN_SECURED_BY_OIDC_SERVICE_WORKER_demo#tabId=tab-1',
+    );
+    expect(buildSecuredTokenPlaceholder(TOKEN_PLACEHOLDERS.NONCE_TOKEN, 'demo')).toBe(
+      'NONCE_SECURED_BY_OIDC_SERVICE_WORKER_demo#tabId=default',
+    );
+  });
+
+  it('builds DPoP placeholders that match the SW output', () => {
+    expect(buildDpopSecuredPlaceholder('demo', 'tab-2')).toBe(
+      `${DPOP_TOKEN_PLACEHOLDER_PREFIX}_demo#tabId=tab-2`,
+    );
+  });
+
+  it.each([
+    [STORAGE_KEY_PREFIX.STATE, 'demo', 'oidc.state.demo'],
+    [STORAGE_KEY_PREFIX.NONCE, 'demo', 'oidc.nonce.demo'],
+    [STORAGE_KEY_PREFIX.CODE_VERIFIER, 'demo', 'oidc.code_verifier.demo'],
+    [STORAGE_KEY_PREFIX.LOGIN_PARAMS, 'demo', 'oidc.login.demo'],
+    [STORAGE_KEY_PREFIX.TAB_ID, 'demo', 'oidc.tabId.demo'],
+  ])('combines storage prefix %s + %s into %s', (prefix, configurationName, expected) => {
+    expect(buildStorageKey(prefix, configurationName)).toBe(expected);
+  });
+
+  it('exposes the SW controllerchange reload counter key', () => {
+    expect(SW_CONTROLLER_CHANGE_RELOAD_COUNT_KEY).toBe('oidc.sw.controllerchange_reload_count');
+  });
+
+  it.each(Object.values(ServiceWorkerMessageType))(
+    'recognises "%s" as a known message type',
+    type => {
+      expect(isServiceWorkerMessageType(type)).toBe(true);
+    },
+  );
+
+  it.each(['unknown', '', 42, null, undefined, {}])(
+    'rejects %p as not a known message type',
+    value => {
+      expect(isServiceWorkerMessageType(value)).toBe(false);
+    },
+  );
+});

package/src/protocol.ts

@@ -0,0 +1,106 @@
+/**
+ * Public, supported entry point for the OIDC service worker `postMessage`
+ * protocol, available directly from `@axa-fr/oidc-client`.
+ *
+ * The same exports are also published from
+ * `@axa-fr/oidc-client-service-worker/protocol`. The two modules are kept
+ * deliberately in sync (and verified by a unit test) so applications that
+ * depend only on `@axa-fr/oidc-client` can interact with the service worker
+ * without adding a transitive dependency.
+ *
+ * See `packages/oidc-client-service-worker/PROTOCOL.md` for the full
+ * specification.
+ */
+
+/**
+ * Semver-protected version of the service worker `postMessage` protocol.
+ */
+export const PROTOCOL_VERSION = '1.0.0' as const;
+
+/**
+ * Every supported service worker message type. The values are also the
+ * literal strings used on the wire as `MessageEventData.type` and must
+ * remain stable across patch and minor versions of the protocol.
+ */
+export const ServiceWorkerMessageType = {
+  SKIP_WAITING: 'SKIP_WAITING',
+  CLAIM: 'claim',
+  CLEAR: 'clear',
+  INIT: 'init',
+  SET_STATE: 'setState',
+  GET_STATE: 'getState',
+  SET_CODE_VERIFIER: 'setCodeVerifier',
+  GET_CODE_VERIFIER: 'getCodeVerifier',
+  SET_SESSION_STATE: 'setSessionState',
+  GET_SESSION_STATE: 'getSessionState',
+  SET_NONCE: 'setNonce',
+  GET_NONCE: 'getNonce',
+  SET_DPOP_NONCE: 'setDemonstratingProofOfPossessionNonce',
+  GET_DPOP_NONCE: 'getDemonstratingProofOfPossessionNonce',
+  SET_DPOP_JWK: 'setDemonstratingProofOfPossessionJwk',
+  GET_DPOP_JWK: 'getDemonstratingProofOfPossessionJwk',
+} as const;
+
+export type ServiceWorkerMessageTypeKey = keyof typeof ServiceWorkerMessageType;
+export type ServiceWorkerMessageTypeValue =
+  (typeof ServiceWorkerMessageType)[ServiceWorkerMessageTypeKey];
+
+export interface ServiceWorkerMessage<TData = unknown> {
+  type: ServiceWorkerMessageTypeValue | 'SKIP_WAITING' | 'claim';
+  configurationName: string;
+  data: TData;
+  tabId?: string;
+}
+
+export interface ServiceWorkerResponse {
+  configurationName?: string;
+  error?: unknown;
+  [key: string]: unknown;
+}
+
+/** Stable internal token placeholders – matched by the SW request handler. */
+export const TOKEN_PLACEHOLDERS = {
+  ACCESS_TOKEN: 'ACCESS_TOKEN_SECURED_BY_OIDC_SERVICE_WORKER',
+  REFRESH_TOKEN: 'REFRESH_TOKEN_SECURED_BY_OIDC_SERVICE_WORKER',
+  NONCE_TOKEN: 'NONCE_SECURED_BY_OIDC_SERVICE_WORKER',
+  CODE_VERIFIER: 'CODE_VERIFIER_SECURED_BY_OIDC_SERVICE_WORKER',
+} as const;
+
+export const DPOP_TOKEN_PLACEHOLDER_PREFIX = 'DPOP_SECURED_BY_OIDC_SERVICE_WORKER' as const;
+
+export const STORAGE_KEY_PREFIX = {
+  TAB_ID: 'oidc.tabId.',
+  STATE: 'oidc.state.',
+  NONCE: 'oidc.nonce.',
+  CODE_VERIFIER: 'oidc.code_verifier.',
+  LOGIN_PARAMS: 'oidc.login.',
+  SW_VERSION_MISMATCH_RELOAD: 'oidc.sw.version_mismatch_reload.',
+} as const;
+
+export const SW_CONTROLLER_CHANGE_RELOAD_COUNT_KEY =
+  'oidc.sw.controllerchange_reload_count' as const;
+
+export const buildStorageKey = (
+  prefix: (typeof STORAGE_KEY_PREFIX)[keyof typeof STORAGE_KEY_PREFIX],
+  configurationName: string,
+): string => `${prefix}${configurationName}`;
+
+export const buildSecuredTokenPlaceholder = (
+  placeholder: (typeof TOKEN_PLACEHOLDERS)[keyof typeof TOKEN_PLACEHOLDERS],
+  configurationName: string,
+  tabId: string = 'default',
+): string => `${placeholder}_${configurationName}#tabId=${tabId}`;
+
+export const buildDpopSecuredPlaceholder = (
+  configurationName: string,
+  tabId: string = 'default',
+): string => `${DPOP_TOKEN_PLACEHOLDER_PREFIX}_${configurationName}#tabId=${tabId}`;
+
+export const isServiceWorkerMessageType = (
+  value: unknown,
+): value is ServiceWorkerMessageTypeValue => {
+  if (typeof value !== 'string') {
+    return false;
+  }
+  return Object.values(ServiceWorkerMessageType).includes(value as ServiceWorkerMessageTypeValue);
+};

package/src/signalServiceWorker.spec.ts

@@ -0,0 +1,77 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import * as initWorker from './initWorker';
+import { OidcClient } from './oidcClient';
+import { ServiceWorkerMessageType } from './protocol';
+
+const buildClient = (overrides: Partial<{ configurationName: string }> = {}) => {
+  const oidc = {
+    configuration: { client_id: 'demo-client' },
+    configurationName: overrides.configurationName ?? 'demo',
+  };
+  return new OidcClient(oidc as never);
+};
+
+describe('OidcClient.signalServiceWorker', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('forwards the typed message to signalServiceWorkerAsync with the OIDC config', async () => {
+    const expected = { configurationName: 'demo', state: 'restored-state' };
+    const spy = vi
+      .spyOn(initWorker, 'signalServiceWorkerAsync')
+      .mockResolvedValue(expected as never);
+
+    const client = buildClient();
+    const response = await client.signalServiceWorker<{ state: string }>({
+      type: ServiceWorkerMessageType.GET_STATE,
+      configurationName: 'demo',
+      data: null,
+    });
+
+    expect(response).toEqual(expected);
+    expect(spy).toHaveBeenCalledOnce();
+    expect(spy).toHaveBeenCalledWith(
+      { client_id: 'demo-client' },
+      'demo',
+      expect.objectContaining({
+        type: 'getState',
+        data: null,
+      }),
+      undefined,
+    );
+  });
+
+  it('propagates a custom timeout option', async () => {
+    const spy = vi.spyOn(initWorker, 'signalServiceWorkerAsync').mockResolvedValue({} as never);
+
+    const client = buildClient();
+    await client.signalServiceWorker(
+      { type: ServiceWorkerMessageType.CLEAR, configurationName: 'demo', data: { status: null } },
+      { timeoutMs: 9000 },
+    );
+
+    expect(spy).toHaveBeenCalledWith(
+      expect.anything(),
+      'demo',
+      expect.objectContaining({ type: 'clear' }),
+      { timeoutMs: 9000 },
+    );
+  });
+
+  it('rejects when the underlying helper rejects', async () => {
+    const error = new Error('no SW');
+    vi.spyOn(initWorker, 'signalServiceWorkerAsync').mockRejectedValue(error);
+
+    const client = buildClient();
+
+    await expect(
+      client.signalServiceWorker({
+        type: ServiceWorkerMessageType.GET_STATE,
+        configurationName: 'demo',
+        data: null,
+      }),
+    ).rejects.toBe(error);
+  });
+});

package/src/version.ts

@@ -1 +1 @@
-export default '7.27.11';
+export default '7.27.12';