index.ts

/*
 * @forgerock/javascript-sdk
 *
 * index.ts
 *
 * Copyright (c) 2024 - 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 { CallbackType } from '../auth/enums';
import type HiddenValueCallback from '../fr-auth/callbacks/hidden-value-callback';
import type MetadataCallback from '../fr-auth/callbacks/metadata-callback';
import type FRStep from '../fr-auth/fr-step';
import { FRLogger } from '../util/logger';
import { WebAuthnOutcome, WebAuthnOutcomeType, WebAuthnStepType } from './enums';
import {
  arrayBufferToString,
  parseCredentials,
  parsePubKeyArray,
  parseRelyingPartyId,
} from './helpers';
import type {
  AttestationType,
  RelyingParty,
  WebAuthnAuthenticationMetadata,
  WebAuthnCallbacks,
  WebAuthnRegistrationMetadata,
  WebAuthnTextOutputRegistration,
} from './interfaces';
import type TextOutputCallback from '../fr-auth/callbacks/text-output-callback';
import { parseWebAuthnAuthenticateText, parseWebAuthnRegisterText } from './script-parser';
import { withTimeout } from '../util/timeout';

// <clientdata>::<attestation>::<publickeyCredential>::<DeviceName>
type OutcomeWithName<
  ClientId extends string,
  Attestation extends AttestationType,
  PubKeyCred extends PublicKeyCredential,
  Name = '',
> = Name extends infer P extends string
  ? `${ClientId}::${Attestation}::${PubKeyCred['id']}${P extends '' ? '' : `::${P}`}`
  : never;
// JSON-based WebAuthn
type WebAuthnMetadata = WebAuthnAuthenticationMetadata | WebAuthnRegistrationMetadata;
// Script-based WebAuthn
type WebAuthnTextOutput = WebAuthnTextOutputRegistration;
const TWO_SECOND = 2000;

declare global {
  interface Window {
    PingWebAuthnAbortController: AbortController;
  }
}

/**
 * Utility for integrating a web browser's WebAuthn API.
 *
 * Example:
 *
 * ```js
 * // Determine if a step is a WebAuthn step
 * const stepType = FRWebAuthn.getWebAuthnStepType(step);
 * if (stepType === WebAuthnStepType.Registration) {
 *   // Register a new device
 *   await FRWebAuthn.register(step);
 * } else if (stepType === WebAuthnStepType.Authentication) {
 *   // Authenticate with a registered device
 *   await FRWebAuthn.authenticate(step);
 * }
 * ```
 *
 * Conditional mediation (Autofill) Support:
 *
 * ```js
 * // Check if browser supports conditional mediation
 * const supportsConditionalUI = await FRWebAuthn.isConditionalUISupported();
 *
 * if (supportsConditionalUI) {
 *   // The authenticate() method automatically handles conditional mediation
 *   // when the server indicates support via conditionalWebAuthn: true
 *   // in the metadata. No additional code changes needed.
 *   await FRWebAuthn.authenticate(step);
 *
 *   // For conditional mediation to work in the browser, add autocomplete="webauthn"
 *   // to your username input field:
 *   // <input type="text" name="username" autocomplete="webauthn" />
 * }
 * ```
 */
abstract class FRWebAuthn {
  /**
   * Determines if the given step is a WebAuthn step.
   *
   * @param step The step to evaluate
   * @return A WebAuthnStepType value
   */
  public static getWebAuthnStepType(step: FRStep): WebAuthnStepType {
    const outcomeCallback = this.getOutcomeCallback(step);
    const metadataCallback = this.getMetadataCallback(step);
    const textOutputCallback = this.getTextOutputCallback(step);

    if (outcomeCallback && metadataCallback) {
      const metadata = metadataCallback.getOutputValue('data') as {
        pubKeyCredParams?: [];
      };
      if (metadata?.pubKeyCredParams) {
        return WebAuthnStepType.Registration;
      }

      return WebAuthnStepType.Authentication;
    } else if (outcomeCallback && textOutputCallback) {
      const message = textOutputCallback.getMessage();
      if (message.includes('pubKeyCredParams')) {
        return WebAuthnStepType.Registration;
      }

      return WebAuthnStepType.Authentication;
    } else {
      return WebAuthnStepType.None;
    }
  }

  /**
   * Checks if the browser supports WebAuthn.
   *
   * @return boolean indicating if WebAuthn is available
   */
  public static isWebAuthnSupported(): boolean {
    return !!window.PublicKeyCredential;
  }

  /**
   * Checks if the browser supports conditional mediation (autofill) for WebAuthn.
   *
   * @return Promise<boolean> indicating if conditional mediation is available
   */
  public static async isConditionalMediationSupported(): Promise<boolean> {
    if (!this.isWebAuthnSupported()) {
      return false;
    }

    // Check if the browser supports conditional mediation
    try {
      return withTimeout(PublicKeyCredential.isConditionalMediationAvailable(), TWO_SECOND);
    } catch {
      FRLogger.warn('Conditional mediation check timed out');
    }

    return false;
  }

  /**
   * Populates the step with the necessary authentication outcome.
   * Automatically handles conditional mediation if indicated by the server metadata.
   *
   * @param step The step that contains WebAuthn authentication data
   * @param optionsTransformer Augments the derived options with custom behaviour
   * @return The populated step
   */
  public static async authenticate(
    step: FRStep,
    optionsTransformer: (options: CredentialRequestOptions) => CredentialRequestOptions = (
      options,
    ) => options,
  ): Promise<FRStep> {
    const { hiddenCallback, metadataCallback, textOutputCallback } = this.getCallbacks(step);
    if (hiddenCallback && (metadataCallback || textOutputCallback)) {
      const options: CredentialRequestOptions = {};

      try {
        if (metadataCallback) {
          const meta = metadataCallback.getOutputValue('data') as WebAuthnAuthenticationMetadata;
          const mediation = meta.mediation as CredentialMediationRequirement;

          if (mediation === 'conditional') {
            const isConditionalMediationSupported = await this.isConditionalMediationSupported();
            if (!isConditionalMediationSupported) {
              const e = new Error(
                'Conditional mediation was requested, but is not supported by this browser.',
              );
              e.name = WebAuthnOutcomeType.NotSupportedError;
              throw e;
            }
          }

          options.publicKey = this.createAuthenticationPublicKey(meta);
          options.mediation = mediation;
        } else if (textOutputCallback) {
          const metadata = this.extractMetadata(textOutputCallback.getMessage());
          if (metadata) {
            options.publicKey = this.createAuthenticationPublicKey(
              metadata as WebAuthnAuthenticationMetadata,
            );
          } else {
            options.publicKey = parseWebAuthnAuthenticateText(textOutputCallback.getMessage());
          }
        } else {
          throw new Error('No Credential found from Public Key');
        }
        const credential: PublicKeyCredential | null = await this.getAuthenticationCredential(
          optionsTransformer(options),
        );
        const outcome: ReturnType<typeof this.getAuthenticationOutcome> =
          this.getAuthenticationOutcome(credential);

        if (metadataCallback) {
          const meta = metadataCallback.getOutputValue('data') as WebAuthnAuthenticationMetadata;
          if (meta?.supportsJsonResponse && credential && 'authenticatorAttachment' in credential) {
            hiddenCallback.setInputValue(
              JSON.stringify({
                authenticatorAttachment: credential.authenticatorAttachment,
                legacyData: outcome,
              }),
            );
            return step;
          }
        }
        hiddenCallback.setInputValue(outcome);
        return step;
      } catch (error) {
        if (!(error instanceof Error)) throw error;
        // NotSupportedError is a special case
        if (error.name === WebAuthnOutcomeType.NotSupportedError) {
          hiddenCallback.setInputValue(WebAuthnOutcome.Unsupported);
          throw error;
        }
        hiddenCallback.setInputValue(`${WebAuthnOutcome.Error}::${error.name}:${error.message}`);
        throw error;
      }
    } else {
      const e = new Error('Incorrect callbacks for WebAuthn authentication');
      e.name = WebAuthnOutcomeType.DataError;
      hiddenCallback?.setInputValue(`${WebAuthnOutcome.Error}::${e.name}:${e.message}`);
      throw e;
    }
  }
  /**
   * Populates the step with the necessary registration outcome.
   *
   * @param step The step that contains WebAuthn registration data
   * @return The populated step
   */
  // Can make this generic const in Typescript 5.0 > and the name itself will
  // be inferred from the type so `typeof deviceName` will not just return string
  // but the actual name of the deviceName passed in as a generic.
  public static async register<T extends string = ''>(
    step: FRStep,
    deviceName?: T,
  ): Promise<FRStep> {
    const { hiddenCallback, metadataCallback, textOutputCallback } = this.getCallbacks(step);
    if (hiddenCallback && (metadataCallback || textOutputCallback)) {
      let outcome: OutcomeWithName<string, AttestationType, PublicKeyCredential>;
      let credential: PublicKeyCredential | null = null;

      try {
        let publicKey: PublicKeyCredentialRequestOptions;
        if (metadataCallback) {
          const meta = metadataCallback.getOutputValue('data') as WebAuthnRegistrationMetadata;
          publicKey = this.createRegistrationPublicKey(meta);
          credential = await this.getRegistrationCredential(
            publicKey as PublicKeyCredentialCreationOptions,
          );
          outcome = this.getRegistrationOutcome(credential);
        } else if (textOutputCallback) {
          const metadata = this.extractMetadata(textOutputCallback.getMessage());

          if (metadata) {
            publicKey = this.createRegistrationPublicKey(metadata as WebAuthnRegistrationMetadata);
          } else {
            publicKey = parseWebAuthnRegisterText(textOutputCallback.getMessage());
          }
          credential = await this.getRegistrationCredential(
            publicKey as PublicKeyCredentialCreationOptions,
          );
          outcome = this.getRegistrationOutcome(credential);
        } else {
          throw new Error('No Credential found from Public Key');
        }
      } catch (error) {
        if (!(error instanceof Error)) throw error;
        // NotSupportedError is a special case
        if (error.name === WebAuthnOutcomeType.NotSupportedError) {
          hiddenCallback.setInputValue(WebAuthnOutcome.Unsupported);
          throw error;
        }
        hiddenCallback.setInputValue(`${WebAuthnOutcome.Error}::${error.name}:${error.message}`);
        throw error;
      }

      if (metadataCallback) {
        const meta = metadataCallback.getOutputValue('data') as WebAuthnAuthenticationMetadata;
        if (meta?.supportsJsonResponse && credential && 'authenticatorAttachment' in credential) {
          hiddenCallback.setInputValue(
            JSON.stringify({
              authenticatorAttachment: credential.authenticatorAttachment,
              legacyData:
                deviceName && deviceName.length > 0 ? `${outcome}::${deviceName}` : outcome,
            }),
          );
          return step;
        }
      }

      hiddenCallback.setInputValue(
        deviceName && deviceName.length > 0 ? `${outcome}::${deviceName}` : outcome,
      );
      return step;
    } else {
      const e = new Error('Incorrect callbacks for WebAuthn registration');
      e.name = WebAuthnOutcomeType.DataError;
      hiddenCallback?.setInputValue(`${WebAuthnOutcome.Error}::${e.name}:${e.message}`);
      throw e;
    }
  }

  /**
   * Returns an object containing the two WebAuthn callbacks.
   *
   * @param step The step that contains WebAuthn callbacks
   * @return The WebAuthn callbacks
   */
  public static getCallbacks(step: FRStep): WebAuthnCallbacks {
    const hiddenCallback = this.getOutcomeCallback(step);
    const metadataCallback = this.getMetadataCallback(step);
    const textOutputCallback = this.getTextOutputCallback(step);

    const returnObj: WebAuthnCallbacks = {
      hiddenCallback,
    };
    if (metadataCallback) {
      returnObj.metadataCallback = metadataCallback;
    } else if (textOutputCallback) {
      returnObj.textOutputCallback = textOutputCallback;
    }
    return returnObj;
  }

  /**
   * Returns the WebAuthn metadata callback containing data to pass to the browser
   * Web Authentication API.
   *
   * @param step The step that contains WebAuthn callbacks
   * @return The metadata callback
   */
  public static getMetadataCallback(step: FRStep): MetadataCallback | undefined {
    return step.getCallbacksOfType<MetadataCallback>(CallbackType.MetadataCallback).find((x) => {
      const cb = x.getOutputByName<WebAuthnMetadata | undefined>('data', undefined);
      // eslint-disable-next-line no-prototype-builtins
      return cb && cb.hasOwnProperty('relyingPartyId');
    });
  }

  /**
   * Returns the WebAuthn hidden value callback where the outcome should be populated.
   *
   * @param step The step that contains WebAuthn callbacks
   * @return The hidden value callback
   */
  public static getOutcomeCallback(step: FRStep): HiddenValueCallback | undefined {
    return step
      .getCallbacksOfType<HiddenValueCallback>(CallbackType.HiddenValueCallback)
      .find((x) => x.getOutputByName<string>('id', '') === 'webAuthnOutcome');
  }

  /**
   * Returns the WebAuthn metadata callback containing data to pass to the browser
   * Web Authentication API.
   *
   * @param step The step that contains WebAuthn callbacks
   * @return The metadata callback
   */
  public static getTextOutputCallback(step: FRStep): TextOutputCallback | undefined {
    return step
      .getCallbacksOfType<TextOutputCallback>(CallbackType.TextOutputCallback)
      .find((x) => {
        const cb = x.getOutputByName<WebAuthnTextOutput | undefined>('message', undefined);
        return cb && cb.includes('webAuthnOutcome');
      });
  }

  /**
   * Retrieves the credential from the browser Web Authentication API.
   *
   * @param options The options associated with the request
   * @return The credential
   */
  public static async getAuthenticationCredential(
    options: CredentialRequestOptions,
  ): Promise<PublicKeyCredential | null> {
    // Feature check before we attempt authenticating
    if (!this.isWebAuthnSupported()) {
      const e = new Error('PublicKeyCredential not supported by this browser');
      e.name = WebAuthnOutcomeType.NotSupportedError;
      throw e;
    }

    const credential = await navigator.credentials.get({
      ...options,
      signal: this.createAbortController().signal,
    });
    return credential as PublicKeyCredential;
  }

  /**
   * Converts an authentication credential into the outcome expected by OpenAM.
   *
   * @param credential The credential to convert
   * @return The outcome string
   */
  public static getAuthenticationOutcome(
    credential: PublicKeyCredential | null,
  ):
    | OutcomeWithName<string, AttestationType, PublicKeyCredential>
    | OutcomeWithName<string, AttestationType, PublicKeyCredential, string> {
    if (credential === null) {
      const e = new Error('No credential generated from authentication');
      e.name = WebAuthnOutcomeType.UnknownError;
      throw e;
    }

    try {
      const clientDataJSON = arrayBufferToString(credential.response.clientDataJSON);
      const assertionResponse = credential.response as AuthenticatorAssertionResponse;
      const authenticatorData = new Int8Array(
        assertionResponse.authenticatorData,
      ).toString() as AttestationType;
      const signature = new Int8Array(assertionResponse.signature).toString();

      // Current native typing for PublicKeyCredential does not include `userHandle`
      // eslint-disable-next-line
      // @ts-ignore
      const userHandle = arrayBufferToString(credential.response.userHandle);

      let stringOutput =
        `${clientDataJSON}::${authenticatorData}::${signature}::${credential.id}` as OutcomeWithName<
          string,
          AttestationType,
          PublicKeyCredential
        >;
      // Check if Username is stored on device
      if (userHandle) {
        stringOutput = `${stringOutput}::${userHandle}`;
        return stringOutput as OutcomeWithName<
          string,
          AttestationType,
          PublicKeyCredential,
          string
        >;
      }

      return stringOutput;
    } catch (error) {
      const e = new Error('Transforming credential object to string failed');
      e.name = WebAuthnOutcomeType.EncodingError;
      throw e;
    }
  }

  /**
   * Retrieves the credential from the browser Web Authentication API.
   *
   * @param options The public key options associated with the request
   * @return The credential
   */
  public static async getRegistrationCredential(
    options: PublicKeyCredentialCreationOptions,
  ): Promise<PublicKeyCredential | null> {
    // Feature check before we attempt registering a device
    if (!this.isWebAuthnSupported()) {
      const e = new Error('PublicKeyCredential not supported by this browser');
      e.name = WebAuthnOutcomeType.NotSupportedError;
      throw e;
    }
    const credential = await navigator.credentials.create({
      publicKey: options,
    });
    return credential as PublicKeyCredential;
  }

  /**
   * Converts a registration credential into the outcome expected by OpenAM.
   *
   * @param credential The credential to convert
   * @return The outcome string
   */
  public static getRegistrationOutcome(
    credential: PublicKeyCredential | null,
  ): OutcomeWithName<string, AttestationType, PublicKeyCredential> {
    if (credential === null) {
      const e = new Error('No credential generated from registration');
      e.name = WebAuthnOutcomeType.UnknownError;
      throw e;
    }

    try {
      const clientDataJSON = arrayBufferToString(credential.response.clientDataJSON);
      const attestationResponse = credential.response as AuthenticatorAttestationResponse;
      const attestationObject = new Int8Array(
        attestationResponse.attestationObject,
      ).toString() as AttestationType.Direct;
      return `${clientDataJSON}::${attestationObject}::${credential.id}`;
    } catch (error) {
      const e = new Error('Transforming credential object to string failed');
      e.name = WebAuthnOutcomeType.EncodingError;
      throw e;
    }
  }

  /**
   * Converts authentication tree metadata into options required by the browser
   * Web Authentication API.
   *
   * @param metadata The metadata provided in the authentication tree MetadataCallback
   * @return The Web Authentication API request options
   */
  public static createAuthenticationPublicKey(
    metadata: WebAuthnAuthenticationMetadata,
  ): PublicKeyCredentialRequestOptions {
    const {
      acceptableCredentials,
      allowCredentials,
      _allowCredentials,
      challenge,
      relyingPartyId,
      _relyingPartyId,
      timeout,
      userVerification,
      extensions,
    } = metadata;

    // Use the structured _allowCredentials if available, otherwise parse the string format
    let allowCredentialsValue: PublicKeyCredentialDescriptor[] | undefined;
    if (_allowCredentials && Array.isArray(_allowCredentials)) {
      // The incoming _allowCredentials entries have an `id` property of type `Array`, which is rejected by `navigator.credentials.get()`.
      // Converting it to a TypedArray here to meet the spec (https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredentialRequestOptions#id).
      allowCredentialsValue = _allowCredentials.map((cred) => {
        return {
          ...cred,
          id: new Int8Array(cred.id as unknown as number[]),
        };
      });
    } else {
      allowCredentialsValue = parseCredentials(allowCredentials || acceptableCredentials || '');
    }

    // Use _relyingPartyId if available, otherwise parse the old format
    const rpId = _relyingPartyId || parseRelyingPartyId(relyingPartyId);

    const options: PublicKeyCredentialRequestOptions = {
      challenge: Uint8Array.from(atob(challenge), (c) => c.charCodeAt(0)).buffer,
      timeout,
    };
    // For conditional mediation, allowCredentials can be omitted.
    // For standard WebAuthn, it may or may not be present.
    // Only add the property if the array is not empty.
    if (allowCredentialsValue && allowCredentialsValue.length > 0) {
      options.allowCredentials = allowCredentialsValue;
    }

    // Add optional properties only if they have values
    if (userVerification) {
      options.userVerification = userVerification;
    }

    if (rpId) {
      options.rpId = rpId;
    }

    if (extensions && Object.keys(extensions).length > 0) {
      options.extensions = extensions;
    }

    return options;
  }

  /**
   * Converts authentication tree metadata into options required by the browser
   * Web Authentication API.
   *
   * @param metadata The metadata provided in the authentication tree MetadataCallback
   * @return The Web Authentication API request options
   */
  public static createRegistrationPublicKey(
    metadata: WebAuthnRegistrationMetadata,
  ): PublicKeyCredentialCreationOptions {
    const { pubKeyCredParams: pubKeyCredParamsString } = metadata;
    const pubKeyCredParams = parsePubKeyArray(pubKeyCredParamsString);
    if (!pubKeyCredParams) {
      const e = new Error('Missing pubKeyCredParams property from registration options');
      e.name = WebAuthnOutcomeType.DataError;
      throw e;
    }
    const excludeCredentials = parseCredentials(metadata.excludeCredentials);

    const {
      attestationPreference,
      authenticatorSelection,
      challenge,
      relyingPartyId,
      relyingPartyName,
      timeout,
      userId,
      userName,
      displayName,
    } = metadata;
    const rpId = parseRelyingPartyId(relyingPartyId);
    const rp: RelyingParty = {
      name: relyingPartyName,
      ...(rpId && { id: rpId }),
    };

    return {
      attestation: attestationPreference,
      authenticatorSelection: JSON.parse(authenticatorSelection),
      challenge: Uint8Array.from(atob(challenge), (c) => c.charCodeAt(0)).buffer,
      ...(excludeCredentials.length && { excludeCredentials }),
      pubKeyCredParams,
      rp,
      timeout,
      user: {
        displayName: displayName || userName,
        id: Int8Array.from(userId.split('').map((c: string) => c.charCodeAt(0))),
        name: displayName || userName,
      },
    };
  }

  private static createAbortController() {
    window.PingWebAuthnAbortController?.abort();

    const abortController = new AbortController();
    window.PingWebAuthnAbortController = abortController;
    return abortController;
  }

  private static extractMetadata(message: string): object | null {
    const contextMatch = message.match(/^var scriptContext = (.*);*$/m);
    const jsonString = contextMatch?.[1];

    if (jsonString) {
      return JSON.parse(jsonString);
    }

    return null;
  }
}

export default FRWebAuthn;
export type {
  RelyingParty,
  WebAuthnAuthenticationMetadata,
  WebAuthnCallbacks,
  WebAuthnRegistrationMetadata,
};
export { WebAuthnOutcome, WebAuthnOutcomeType, WebAuthnStepType };