feat(journey-client): automatic server based mediation and abort controller

Author: vatsalparikh

.changeset/ready-snakes-sell.md

@@ -4,7 +4,7 @@
 
 Add WebAuthn conditional mediation (passkey autofill) support.
 
-- `WebAuthn.authenticate(step, mediation?, signal?)` forwards `mediation` and `signal` to `navigator.credentials.get`.
-- When `mediation` is `'conditional'`, an `AbortSignal` is required.
+- `WebAuthn.authenticate(step, signal?)` derives mediation from WebAuthn metadata (`meta.mediation`).
+- When `meta.mediation` is `'conditional'`, an `AbortSignal` is used (caller-provided if present, otherwise created by the SDK).
 - If conditional mediation is requested but not supported, `authenticate()` throws `NotSupportedError` (and the existing error handling sets the hidden outcome to `unsupported`).
 - Adds `WebAuthn.isConditionalMediationSupported()` helper, docs, and unit tests.

e2e/journey-app/components/webauthn-step.ts

@@ -66,9 +66,17 @@ export async function handleWebAuthnStep(
     conditionalInput?.focus();
 
     const isConditionalSupported = await WebAuthn.isConditionalMediationSupported();
-    if (isConditionalSupported && conditionalInput) {
+
+    const metadataCallback = WebAuthn.getMetadataCallback(step);
+    const meta = metadataCallback?.getData<{
+      mediation?: CredentialMediationRequirement;
+      conditional?: boolean;
+    }>();
+    const isConditionalMediation = meta?.mediation === 'conditional' || meta?.conditional === true;
+
+    if (isConditionalSupported && conditionalInput && isConditionalMediation) {
       const controller = new AbortController();
-      void WebAuthn.authenticate(step, 'conditional', controller.signal)
+      void WebAuthn.authenticate(step, controller.signal)
         .then(() => submitForm())
         .catch(() => {
           setError('WebAuthn failed or was cancelled. Please try again or use a different method.');

packages/journey-client/api-report/journey-client.webauthn.api.md

@@ -92,7 +92,7 @@ export enum UserVerificationType {
 
 // @public
 export abstract class WebAuthn {
-    static authenticate(step: JourneyStep, mediation?: CredentialMediationRequirement, signal?: AbortSignal): Promise<JourneyStep>;
+    static authenticate(step: JourneyStep, signal?: AbortSignal): Promise<JourneyStep>;
     static createAuthenticationPublicKey(metadata: WebAuthnAuthenticationMetadata): PublicKeyCredentialRequestOptions;
     static createRegistrationPublicKey(metadata: WebAuthnRegistrationMetadata): PublicKeyCredentialCreationOptions;
     static getAuthenticationCredential(options: PublicKeyCredentialRequestOptions, mediation?: CredentialMediationRequirement, signal?: AbortSignal): Promise<PublicKeyCredential | null>;
@@ -117,6 +117,8 @@ export interface WebAuthnAuthenticationMetadata {
     // (undocumented)
     challenge: string;
     // (undocumented)
+    mediation?: CredentialMediationRequirement;
+    // (undocumented)
     relyingPartyId: string;
     // (undocumented)
     supportsJsonResponse?: boolean;

packages/journey-client/src/lib/webauthn/interfaces.ts

@@ -80,6 +80,7 @@ export interface WebAuthnAuthenticationMetadata {
   acceptableCredentials?: string;
   allowCredentials?: string;
   challenge: string;
+  mediation?: CredentialMediationRequirement;
   relyingPartyId: string;
   timeout: number;
   userVerification: UserVerificationType;

packages/journey-client/src/lib/webauthn/webauthn.test.ts

@@ -138,43 +138,61 @@ describe('WebAuthn conditional mediation', () => {
     vi.restoreAllMocks();
   });
 
-  it('requires an AbortSignal when mediation is conditional', async () => {
+  it('uses an internal AbortSignal when mediation is conditional and caller provides none', async () => {
+    const metaDriven = JSON.parse(JSON.stringify(webAuthnAuthMetaCallback70)) as any;
+    metaDriven.callbacks[0].output[0].value.mediation = 'conditional';
+
     // eslint-disable-next-line
-    const step = createJourneyStep(webAuthnAuthMetaCallback70 as any);
+    const step = createJourneyStep(metaDriven as any);
     const hiddenCallback = WebAuthn.getOutcomeCallback(step);
     if (!hiddenCallback) throw new Error('Missing hidden callback for test');
 
-    await expect(WebAuthn.authenticate(step, 'conditional')).rejects.toThrow(
-      'AbortSignal is required for conditional mediation WebAuthn requests',
+    const credentialsGet = vi
+      .spyOn(navigator.credentials, 'get')
+      .mockResolvedValue({} as unknown as Credential);
+
+    vi.spyOn(WebAuthn, 'getAuthenticationOutcome').mockReturnValue(
+      'ok' as unknown as ReturnType<typeof WebAuthn.getAuthenticationOutcome>,
     );
 
-    expect(hiddenCallback.getInputValue()).toContain(
-      'AbortSignal is required for conditional mediation WebAuthn requests',
+    await WebAuthn.authenticate(step);
+
+    expect(credentialsGet).toHaveBeenCalledWith(
+      expect.objectContaining({
+        mediation: 'conditional',
+        signal: expect.any(Object),
+        publicKey: expect.any(Object),
+      }),
     );
+    expect(hiddenCallback.getInputValue()).toBe('ok');
   });
 
   it('throws NotSupportedError when conditional mediation is not supported by the browser', async () => {
+    const metaDriven = JSON.parse(JSON.stringify(webAuthnAuthMetaCallback70)) as any;
+    metaDriven.callbacks[0].output[0].value.mediation = 'conditional';
+
     // eslint-disable-next-line
-    const step = createJourneyStep(webAuthnAuthMetaCallback70 as any);
+    const step = createJourneyStep(metaDriven as any);
     const hiddenCallback = WebAuthn.getOutcomeCallback(step);
     if (!hiddenCallback) throw new Error('Missing hidden callback for test');
 
     const conditionalSupportSpy = vi
       .spyOn(WebAuthn, 'isConditionalMediationSupported')
       .mockResolvedValue(false);
 
-    await expect(
-      WebAuthn.authenticate(step, 'conditional', new AbortController().signal),
-    ).rejects.toMatchObject({ name: 'NotSupportedError' });
+    await expect(WebAuthn.authenticate(step)).rejects.toMatchObject({ name: 'NotSupportedError' });
 
     expect(conditionalSupportSpy).toHaveBeenCalledTimes(1);
     expect(hiddenCallback.getInputValue()).toBe('unsupported');
     expect(navigator.credentials.get as unknown as ReturnType<typeof vi.fn>).not.toHaveBeenCalled();
   });
 
   it('passes mediation + signal through to navigator.credentials.get when supported', async () => {
+    const metaDriven = JSON.parse(JSON.stringify(webAuthnAuthMetaCallback70)) as any;
+    metaDriven.callbacks[0].output[0].value.mediation = 'conditional';
+
     // eslint-disable-next-line
-    const step = createJourneyStep(webAuthnAuthMetaCallback70 as any);
+    const step = createJourneyStep(metaDriven as any);
     const hiddenCallback = WebAuthn.getOutcomeCallback(step);
     if (!hiddenCallback) throw new Error('Missing hidden callback for test');
 
@@ -187,7 +205,7 @@ describe('WebAuthn conditional mediation', () => {
       .spyOn(WebAuthn, 'getAuthenticationOutcome')
       .mockReturnValue('ok' as unknown as ReturnType<typeof WebAuthn.getAuthenticationOutcome>);
 
-    await WebAuthn.authenticate(step, 'conditional', abortController.signal);
+    await WebAuthn.authenticate(step, abortController.signal);
 
     expect(outcomeSpy).toHaveBeenCalledTimes(1);
     expect(credentialsGet).toHaveBeenCalledWith(

packages/journey-client/src/lib/webauthn/webauthn.ts

@@ -63,7 +63,7 @@ type WebAuthnMetadata = WebAuthnAuthenticationMetadata | WebAuthnRegistrationMet
  *
  * Conditional mediation (passkey autofill) support:
  *
- * Conditional mediation is **opt-in** in this SDK via the `authenticate()` parameters.
+ * Conditional mediation is **server-driven** in this SDK via WebAuthn metadata (`meta.mediation`).
  *
  * ```js
  * // Optional: feature-detect conditional UI before attempting
@@ -72,18 +72,29 @@ type WebAuthnMetadata = WebAuthnAuthenticationMetadata | WebAuthnRegistrationMet
  * if (supportsConditionalUI) {
  *   const controller = new AbortController();
  *
- *   await WebAuthn.authenticate(step, 'conditional', controller.signal);
+ *   // Optional: provide a signal to cancel an in-flight request
+ *   await WebAuthn.authenticate(step, controller.signal);
  * }
  * ```
  *
  * Notes:
- * - When `mediation` is `'conditional'`, an `AbortSignal` is required.
+ * - When server-driven mediation is `'conditional'`, an `AbortSignal` will be used.
+ *   If you don't provide one, the SDK will create one.
  * - If conditional mediation is requested but not supported by the browser,
  *   `authenticate()` throws a `NotSupportedError` and sets the hidden WebAuthn outcome to `unsupported`.
  * - To enable passkey autofill, add `autocomplete="webauthn"` to your username field:
  *   `<input type="text" name="username" autocomplete="webauthn" />`
  */
 export abstract class WebAuthn {
+  private static conditionalAbortController?: AbortController;
+
+  private static createAbortController(): AbortController {
+    this.conditionalAbortController?.abort();
+    const abortController = new AbortController();
+    this.conditionalAbortController = abortController;
+    return abortController;
+  }
+
   /**
    * Determines if the given step is a WebAuthn step.
    *
@@ -123,32 +134,29 @@ export abstract class WebAuthn {
    * Populates the step with the necessary authentication outcome.
    *
    * @param step The step that contains WebAuthn authentication data
-   * @param mediation Optional mediation requirement passed through to `navigator.credentials.get()`
-   * @param signal Optional AbortSignal passed through to `navigator.credentials.get()` (required when `mediation` is `'conditional'`)
+   * @param signal Optional AbortSignal passed through to `navigator.credentials.get()`
    * @return The populated step
    */
-  public static async authenticate(
-    step: JourneyStep,
-    mediation?: CredentialMediationRequirement,
-    signal?: AbortSignal,
-  ): Promise<JourneyStep> {
+  public static async authenticate(step: JourneyStep, signal?: AbortSignal): Promise<JourneyStep> {
     const { hiddenCallback, metadataCallback, textOutputCallback } = this.getCallbacks(step);
     if (hiddenCallback && (metadataCallback || textOutputCallback)) {
       let outcome: ReturnType<typeof this.getAuthenticationOutcome>;
       let credential: PublicKeyCredential | null = null;
+      let mediation: CredentialMediationRequirement | undefined;
 
       try {
         let publicKey: PublicKeyCredentialRequestOptions;
         if (metadataCallback) {
           const meta = metadataCallback.getOutputValue('data') as WebAuthnAuthenticationMetadata;
+          mediation = meta.mediation;
           publicKey = this.createAuthenticationPublicKey(meta);
 
           if (mediation === 'conditional') {
-            if (!signal) {
-              throw new Error(
-                'AbortSignal is required for conditional mediation WebAuthn requests',
-              );
-            }
+            // Abort any prior conditional request started by the SDK.
+            // (If the caller provides their own signal, we still abort the prior SDK-owned one.)
+            this.conditionalAbortController?.abort();
+
+            const abortSignal = signal ?? this.createAbortController().signal;
 
             const isConditionalMediationSupported = await this.isConditionalMediationSupported();
             if (!isConditionalMediationSupported) {
@@ -158,14 +166,21 @@ export abstract class WebAuthn {
               e.name = WebAuthnOutcomeType.NotSupportedError;
               throw e;
             }
-          }
 
-          credential = await this.getAuthenticationCredential(
-            publicKey as PublicKeyCredentialRequestOptions,
-            mediation,
-            signal,
-          );
-          outcome = this.getAuthenticationOutcome(credential);
+            credential = await this.getAuthenticationCredential(
+              publicKey as PublicKeyCredentialRequestOptions,
+              mediation,
+              abortSignal,
+            );
+            outcome = this.getAuthenticationOutcome(credential);
+          } else {
+            credential = await this.getAuthenticationCredential(
+              publicKey as PublicKeyCredentialRequestOptions,
+              mediation,
+              signal,
+            );
+            outcome = this.getAuthenticationOutcome(credential);
+          }
         } else {
           throw new Error(
             'No metadata callback found for WebAuthn authentication. Please disable JavaScript in server node.',
@@ -511,14 +526,27 @@ export abstract class WebAuthn {
     const rpId = parseRelyingPartyId(relyingPartyId);
     const allowCredentialsValue = parseCredentials(allowCredentials || acceptableCredentials || '');
 
-    return {
+    const options: PublicKeyCredentialRequestOptions = {
       challenge: Uint8Array.from(atob(challenge), (c) => c.charCodeAt(0)).buffer,
       timeout,
-      // only add key-value pair if proper value is provided
-      ...(allowCredentialsValue && { allowCredentials: allowCredentialsValue }),
-      ...(userVerification && { userVerification }),
-      ...(rpId && { rpId }),
     };
+
+    // 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;
+    }
+
+    if (userVerification) {
+      options.userVerification = userVerification;
+    }
+
+    if (rpId) {
+      options.rpId = rpId;
+    }
+
+    return options;
   }
 
   /**