Merge pull request #20089 from mozilla/FXA-12912

task(passkeys): Add WebAuthn error categorization utility

Author: vbudhram

packages/fxa-settings/src/lib/passkeys/en.ftl

@@ -0,0 +1,51 @@
+## Passkey error messages
+## Surfaced when a WebAuthn ceremony (registration or sign-in) fails.
+
+# Registration errors
+
+# User cancelled or dismissed the browser prompt, or the authenticator could not satisfy the options
+passkey-registration-error-not-allowed = Passkey setup failed or is unavailable. Try again or choose another method.
+
+# The ceremony timed out before the user responded
+passkey-registration-error-timeout = Passkey setup was canceled. Try again.
+
+# Browser or platform does not support passkeys or the requested options (e.g., UV, discoverable credential)
+passkey-registration-error-not-supported = Passkeys aren’t supported here. Try another method or device.
+
+# RP ID / origin mismatch, or insecure context (e.g., embedded iframe, wrong domain)
+passkey-registration-error-security = Passkeys can’t be set up on this page. Use the secure site and try again.
+
+# A credential for this RP already exists on the authenticator (excludeCredentials match)
+passkey-registration-error-invalid-state = This passkey is already registered. Use it to sign in or add a different passkey.
+
+# Authenticator I/O failure (e.g., security key disconnected mid-ceremony)
+passkey-registration-error-not-readable = We couldn’t access the authenticator. Try again or choose another method.
+
+# Attestation constraints or device-specific restrictions can't be met
+passkey-registration-error-constraint = Passkey setup isn’t available with this device. Try another method or device.
+
+# Catch-all for unexpected errors during registration (TypeError, DataError, EncodingError, OperationError, UnknownError)
+passkey-registration-error-unexpected = Passkey setup failed. Try again or choose another method.
+
+# Authentication errors
+
+# User cancelled or dismissed the browser prompt, or no passkey is available / verification failed
+passkey-authentication-error-not-allowed = Sign-in with passkey failed or is unavailable. Try again or choose another method.
+
+# The ceremony timed out before the user responded
+passkey-authentication-error-timeout = Passkey request timed out. Please try again.
+
+# Browser or platform does not support passkeys
+passkey-authentication-error-not-supported = Passkeys aren’t supported. Try another method or device.
+
+# RP ID / origin mismatch, or insecure context (e.g., embedded iframe)
+passkey-authentication-error-security = Passkeys can’t be used on this page. Check you’re on the correct secure site and try again.
+
+# Unexpected credential state during authentication
+passkey-authentication-error-invalid-state = Something went wrong with your passkey. Try again or use another sign-in method.
+
+# Authenticator I/O failure (e.g., security key disconnected mid-ceremony)
+passkey-authentication-error-not-readable = We couldn’t access the authenticator. Try again or use another sign-in method.
+
+# Catch-all for unexpected errors during authentication (TypeError, DataError, EncodingError, ConstraintError, OperationError, UnknownError)
+passkey-authentication-error-unexpected = Something went wrong. Try again or choose another sign-in method.

packages/fxa-settings/src/lib/passkeys/index.ts

@@ -0,0 +1,6 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+export * from './webauthn';
+export * from './webauthn-errors';

packages/fxa-settings/src/lib/passkeys/webauthn-errors.test.ts

@@ -0,0 +1,199 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+import {
+  categorizeWebAuthnError,
+  handleWebAuthnError,
+  WebAuthnErrorCategory,
+  WebAuthnErrorType,
+  WebAuthnOperation,
+} from './webauthn-errors';
+
+function dom(name: string): DOMException {
+  return new DOMException('test', name);
+}
+
+const OPERATIONS: WebAuthnOperation[] = ['registration', 'authentication'];
+
+describe('categorizeWebAuthnError — user-action errors (no Sentry)', () => {
+  const cases: [string, WebAuthnErrorType][] = [
+    ['NotAllowedError', WebAuthnErrorType.NotAllowed],
+    ['TimeoutError', WebAuthnErrorType.Timeout],
+  ];
+
+  describe.each(OPERATIONS)('operation: %s', (operation) => {
+    test.each(cases)(
+      '%s → UserAction, logToSentry false',
+      (name, errorType) => {
+        const result = categorizeWebAuthnError(dom(name), operation);
+        expect(result.category).toBe(WebAuthnErrorCategory.UserAction);
+        expect(result.errorType).toBe(errorType);
+        expect(result.logToSentry).toBe(false);
+        expect(result.userMessageKey).toContain(operation);
+        expect(result.userMessageKey).toMatch(/passkey-.+-error-.+/);
+      }
+    );
+  });
+
+  it('returns distinct keys for registration vs authentication', () => {
+    const reg = categorizeWebAuthnError(dom('NotAllowedError'), 'registration');
+    const auth = categorizeWebAuthnError(
+      dom('NotAllowedError'),
+      'authentication'
+    );
+    expect(reg.userMessageKey).not.toBe(auth.userMessageKey);
+    expect(reg.userMessageKey).toContain('registration');
+    expect(auth.userMessageKey).toContain('authentication');
+  });
+});
+
+describe('categorizeWebAuthnError — device/platform errors (no Sentry)', () => {
+  const cases: [string, WebAuthnErrorType][] = [
+    ['NotSupportedError', WebAuthnErrorType.NotSupported],
+    ['SecurityError', WebAuthnErrorType.Security],
+    ['InvalidStateError', WebAuthnErrorType.InvalidState],
+    ['NotReadableError', WebAuthnErrorType.NotReadable],
+  ];
+
+  describe.each(OPERATIONS)('operation: %s', (operation) => {
+    test.each(cases)(
+      '%s → DevicePlatform, logToSentry false',
+      (name, errorType) => {
+        const result = categorizeWebAuthnError(dom(name), operation);
+        expect(result.category).toBe(WebAuthnErrorCategory.DevicePlatform);
+        expect(result.errorType).toBe(errorType);
+        expect(result.logToSentry).toBe(false);
+      }
+    );
+  });
+
+  it('InvalidStateError has distinct registration key (credential already exists)', () => {
+    const reg = categorizeWebAuthnError(
+      dom('InvalidStateError'),
+      'registration'
+    );
+    const auth = categorizeWebAuthnError(
+      dom('InvalidStateError'),
+      'authentication'
+    );
+    expect(reg.userMessageKey).toContain('registration');
+    expect(auth.userMessageKey).toContain('authentication');
+  });
+});
+
+describe('categorizeWebAuthnError — unexpected errors (Sentry enabled)', () => {
+  const domCases: [string, WebAuthnErrorType][] = [
+    ['ConstraintError', WebAuthnErrorType.Constraint],
+    ['DataError', WebAuthnErrorType.Data],
+    ['EncodingError', WebAuthnErrorType.Encoding],
+    ['OperationError', WebAuthnErrorType.Operation],
+    ['UnknownError', WebAuthnErrorType.Unknown],
+  ];
+
+  describe.each(OPERATIONS)('operation: %s', (operation) => {
+    test.each(domCases)(
+      '%s → Unexpected, logToSentry true',
+      (name, errorType) => {
+        const result = categorizeWebAuthnError(dom(name), operation);
+        expect(result.category).toBe(WebAuthnErrorCategory.Unexpected);
+        expect(result.errorType).toBe(errorType);
+        expect(result.logToSentry).toBe(true);
+      }
+    );
+  });
+
+  test.each(OPERATIONS)('TypeError → Unexpected on %s', (operation) => {
+    const result = categorizeWebAuthnError(
+      new TypeError('bad options'),
+      operation
+    );
+    expect(result.category).toBe(WebAuthnErrorCategory.Unexpected);
+    expect(result.errorType).toBe(WebAuthnErrorType.Type);
+    expect(result.logToSentry).toBe(true);
+  });
+
+  test.each(OPERATIONS)(
+    'unrecognized DOMException → Unexpected on %s',
+    (operation) => {
+      const result = categorizeWebAuthnError(
+        dom('SomeNewBrowserError'),
+        operation
+      );
+      expect(result.category).toBe(WebAuthnErrorCategory.Unexpected);
+      expect(result.errorType).toBe(WebAuthnErrorType.Unknown);
+      expect(result.logToSentry).toBe(true);
+      expect(result.userMessageKey).toContain(operation);
+    }
+  );
+
+  it('ConstraintError has distinct registration key', () => {
+    const reg = categorizeWebAuthnError(dom('ConstraintError'), 'registration');
+    const auth = categorizeWebAuthnError(
+      dom('ConstraintError'),
+      'authentication'
+    );
+    expect(reg.userMessageKey).toContain('registration');
+    expect(reg.userMessageKey).toContain('constraint');
+    expect(auth.userMessageKey).toContain('unexpected');
+  });
+});
+
+describe('categorizeWebAuthnError — non-DOMException inputs default to unexpected', () => {
+  const inputs: unknown[] = [
+    null,
+    undefined,
+    0,
+    '',
+    {},
+    [],
+    new Error('plain error'),
+  ];
+
+  test.each(inputs.map((v) => [String(v), v]))(
+    '%s → Unexpected, logToSentry true',
+    (_, input) => {
+      expect(() =>
+        categorizeWebAuthnError(input, 'authentication')
+      ).not.toThrow();
+      const result = categorizeWebAuthnError(input, 'authentication');
+      expect(result.category).toBe(WebAuthnErrorCategory.Unexpected);
+      expect(result.logToSentry).toBe(true);
+    }
+  );
+});
+
+describe('handleWebAuthnError', () => {
+  it('calls captureException for unexpected errors', () => {
+    const captureException = jest.fn();
+    handleWebAuthnError(new TypeError('bad'), 'registration', captureException);
+    expect(captureException).toHaveBeenCalledWith(expect.any(TypeError));
+  });
+
+  it('does not call captureException for user-action errors', () => {
+    const captureException = jest.fn();
+    handleWebAuthnError(
+      dom('NotAllowedError'),
+      'authentication',
+      captureException
+    );
+    expect(captureException).not.toHaveBeenCalled();
+  });
+
+  it('does not call captureException for device/platform errors', () => {
+    const captureException = jest.fn();
+    handleWebAuthnError(
+      dom('NotSupportedError'),
+      'registration',
+      captureException
+    );
+    expect(captureException).not.toHaveBeenCalled();
+  });
+
+  it('passes the original error to captureException, not the categorized result', () => {
+    const captureException = jest.fn();
+    const error = dom('ConstraintError');
+    handleWebAuthnError(error, 'registration', captureException);
+    expect(captureException).toHaveBeenCalledWith(error);
+  });
+});