@forgerock/journey-client 0.0.0-beta-20251222204813

package/src/lib/webauthn/helpers.test.ts

@@ -0,0 +1,54 @@
+/*
+ * @forgerock/ping-javascript-sdk
+ *
+ * helpers.test.ts
+ *
+ * Copyright (c) 2020 - 2025 Ping Identity Corporation. All rights reserved.
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+import { parseCredentials, parsePubKeyArray } from './helpers.js';
+import {
+  allowCredentials70,
+  allowMultipleCredentials70,
+  acceptableCredentials653,
+  acceptableMultipleCredentials653,
+  pubKeyCredParamsStr,
+} from './helpers.mock.data.js';
+
+describe('Test WebAuthn helper functions', () => {
+  it('should parse the one credential in the MetadataCallback 7.0', () => {
+    const credentials = parseCredentials(allowCredentials70);
+    expect(credentials[0].id.toString()).toBe('[object ArrayBuffer]');
+    expect(credentials[0].type).toBe('public-key');
+  });
+
+  it('should parse the two credentials in the MetadataCallback 7.0', () => {
+    const credentials = parseCredentials(allowMultipleCredentials70);
+    expect(credentials[0].id.toString()).toBe('[object ArrayBuffer]');
+    expect(credentials[0].type).toBe('public-key');
+    expect(credentials[1].id.toString()).toBe('[object ArrayBuffer]');
+    expect(credentials[1].type).toBe('public-key');
+  });
+
+  it('should parse the one credential in the MetadataCallback 6.5', () => {
+    const credentials = parseCredentials(acceptableCredentials653);
+    expect(credentials[0].id.toString()).toBe('[object ArrayBuffer]');
+    expect(credentials[0].type).toBe('public-key');
+  });
+
+  it('should parse the two credentials in the MetadataCallback 6.5', () => {
+    const credentials = parseCredentials(acceptableMultipleCredentials653);
+    expect(credentials[0].id.toString()).toBe('[object ArrayBuffer]');
+    expect(credentials[0].type).toBe('public-key');
+    expect(credentials[1].id.toString()).toBe('[object ArrayBuffer]');
+    expect(credentials[1].type).toBe('public-key');
+  });
+
+  it('should parse the pubKeyCredParams in the MetadataCallback 7.0 & 6.5.3', () => {
+    const pubKeyCredParams = parsePubKeyArray(pubKeyCredParamsStr);
+    expect(pubKeyCredParams).toContainEqual({ type: 'public-key', alg: -7 });
+    expect(pubKeyCredParams).toContainEqual({ type: 'public-key', alg: -257 });
+  });
+});

package/src/lib/webauthn/helpers.ts

@@ -0,0 +1,124 @@
+/*
+ * @forgerock/ping-javascript-sdk
+ *
+ * helpers.ts
+ *
+ * Copyright (c) 2020 - 2025 Ping Identity Corporation. All rights reserved.
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+/**
+ * @module
+ * @ignore
+ * These are private utility functions for HttpClient
+ */
+import { WebAuthnOutcomeType } from './enums.js';
+import type { ParsedCredential } from './interfaces.js';
+
+function ensureArray(arr: RegExpMatchArray | null): string[] {
+  return arr || [];
+}
+
+function arrayBufferToString(arrayBuffer: ArrayBuffer): string {
+  // https://goo.gl/yabPex - To future-proof, we'll pass along whatever the browser
+  // gives us and let AM disregard randomly-injected properties
+  const uint8Array = new Uint8Array(arrayBuffer);
+  const txtDecoder = new TextDecoder();
+
+  const json = txtDecoder.decode(uint8Array);
+  return json;
+}
+
+function getIndexOne(arr: RegExpMatchArray | null): string {
+  return arr ? arr[1] : '';
+}
+
+// TODO: Remove this once AM is providing fully-serialized JSON
+function parseCredentials(value: string): ParsedCredential[] {
+  try {
+    const creds = value
+      .split('}')
+      .filter((x) => !!x && x !== ']')
+      .map((x) => {
+        // eslint-disable-next-line @typescript-eslint/no-use-before-define
+        const idArray = parseNumberArray(x);
+        return {
+          id: new Int8Array(idArray).buffer,
+          type: 'public-key' as PublicKeyCredentialType,
+        };
+      });
+    return creds;
+  } catch {
+    const e = new Error('Transforming credential object to string failed');
+    e.name = WebAuthnOutcomeType.EncodingError;
+    throw e;
+  }
+}
+
+function parseNumberArray(value: string): number[] {
+  const matches = /new Int8Array\((.+)\)/.exec(value);
+  if (matches === null || matches.length < 2) {
+    return [];
+  }
+  return JSON.parse(matches[1]);
+}
+
+function parsePubKeyArray(value: string | unknown[]): PublicKeyCredentialParameters[] | undefined {
+  if (Array.isArray(value)) {
+    return value as PublicKeyCredentialParameters[];
+  }
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+  if (value && value[0] === '[') {
+    return JSON.parse(value);
+  }
+  value = value.replace(/(\w+):/g, '"$1":');
+  return JSON.parse(`[${value}]`);
+}
+
+function parseAllowCredentialsArray(
+  value: string | unknown[],
+): PublicKeyCredentialDescriptor[] | undefined {
+  if (!value) {
+    return undefined;
+  }
+  if (Array.isArray(value)) {
+    return value as PublicKeyCredentialDescriptor[];
+  }
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+  if (value && value[0] === '[') {
+    return JSON.parse(value);
+  }
+  value = value.replace(/(\w+):/g, '"$1":');
+  return JSON.parse(`[${value}]`);
+}
+
+/**
+ * AM is currently serializing RP as one of the following formats, depending on
+ * whether RP ID has been configured:
+ *   "relyingPartyId":""
+ *   "relyingPartyId":"rpId: \"foo\","
+ * This regex handles both formats, but should be removed once AM is fixed.
+ */
+function parseRelyingPartyId(relyingPartyId: string): string {
+  if (relyingPartyId.includes('rpId')) {
+    return relyingPartyId.replace(/rpId: "(.+)",/, '$1');
+  } else {
+    return relyingPartyId.replace(/id: "(.+)",/, '$1');
+  }
+}
+
+export {
+  ensureArray,
+  arrayBufferToString,
+  getIndexOne,
+  parseCredentials,
+  parseNumberArray,
+  parseAllowCredentialsArray,
+  parsePubKeyArray,
+  parseRelyingPartyId,
+};

package/src/lib/webauthn/interfaces.ts

@@ -0,0 +1,112 @@
+/*
+ * @forgerock/ping-javascript-sdk
+ *
+ * interfaces.ts
+ *
+ * Copyright (c) 2020 - 2025 Ping Identity Corporation. All rights reserved.
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+import type { HiddenValueCallback } from '../callbacks/hidden-value-callback.js';
+import type { MetadataCallback } from '../callbacks/metadata-callback.js';
+import type { TextOutputCallback } from '../callbacks/text-output-callback.js';
+
+export enum AttestationType {
+  Direct = 'direct',
+  Indirect = 'indirect',
+  None = 'none',
+}
+
+export interface DeviceStepState extends StepState {
+  value1: number;
+  value2: number;
+}
+
+export enum UserVerificationType {
+  Discouraged = 'discouraged',
+  Preferred = 'preferred',
+  Required = 'required',
+}
+
+export interface RelyingParty {
+  name: string;
+  id?: string;
+}
+
+export interface ResponseCredential {
+  response: { clientDataJSON: ArrayBuffer };
+}
+
+export interface Step<TData, TState> {
+  data?: TData;
+  state: TState;
+  type: StepType;
+}
+
+export interface StepState {
+  authId: string;
+}
+
+export enum StepType {
+  DeviceAuthentication = 'DeviceAuthentication',
+  DeviceRegistration = 'DeviceRegistration',
+  DeviceRegistrationChoice = 'DeviceRegistrationChoice',
+  LoginFailure = 'LoginFailure',
+  LoginSuccess = 'LoginSuccess',
+  OneTimePassword = 'OneTimePassword',
+  SecondFactorChoice = 'SecondFactorChoice',
+  Username = 'Username',
+  UsernamePassword = 'UsernamePassword',
+  UserPassword = 'UserPassword',
+}
+
+export interface WebAuthnRegistrationMetadata {
+  attestationPreference: 'none' | 'indirect' | 'direct';
+  authenticatorSelection: string;
+  challenge: string;
+  excludeCredentials: string;
+  pubKeyCredParams: string;
+  relyingPartyId: string;
+  relyingPartyName: string;
+  timeout: number;
+  userId: string;
+  userName: string;
+  displayName?: string;
+  supportsJsonResponse?: boolean;
+}
+
+export interface WebAuthnAuthenticationMetadata {
+  acceptableCredentials?: string;
+  allowCredentials?: string;
+  challenge: string;
+  relyingPartyId: string;
+  timeout: number;
+  userVerification: UserVerificationType;
+  supportsJsonResponse?: boolean;
+}
+
+export interface WebAuthnCallbacks {
+  hiddenCallback?: HiddenValueCallback;
+  metadataCallback?: MetadataCallback;
+  textOutputCallback?: TextOutputCallback;
+}
+
+export type WebAuthnTextOutputRegistration = string;
+
+export interface ParsedCredential {
+  /**
+   * The WebAuthn API (specifically `PublicKeyCredentialDescriptor['id']`) expects a `BufferSource` type.
+   * In current TypeScript environments, `SharedArrayBuffer` is not directly assignable to `BufferSource`
+   * due to missing properties like `resizable`, `resize`, etc.
+   * Although `SharedArrayBuffer` might have been implicitly compatible in older environments,
+   * explicitly using `ArrayBuffer` ensures strict type compatibility with the WebAuthn API.
+   * The `script-parser.ts` already converts the ID to an `ArrayBuffer` before use.
+   *
+   * See:
+   * - W3C WebAuthn Level 3: https://www.w3.org/TR/webauthn-3/#dictdef-publickeycredentialdescriptor
+   * - MDN BufferSource: https://developer.mozilla.org/en-US/docs/Web/API/BufferSource
+   */
+  id: ArrayBuffer;
+  type: 'public-key';
+}