Merge pull request #20230 from mozilla/worktree-FXA-13069

feat(auth): Add passkey registration REST endpoints (FXA-13069)

Author: dschom

libs/accounts/passkey/src/lib/passkey.challenge.manager.in.spec.ts

@@ -50,10 +50,13 @@ async function clearChallengeKeys() {
 beforeAll(async () => {
   redis = new Redis({ host: 'localhost' });
 
-  config = new PasskeyConfig();
-  config.rpId = 'localhost';
-  config.allowedOrigins = ['http://localhost'];
-  config.challengeTimeout = 1000 * 60 * 5; // 5 minutes
+  config = new PasskeyConfig({
+    enabled: true,
+    rpId: 'localhost',
+    allowedOrigins: ['http://localhost'],
+    maxPasskeysPerUser: 10,
+    challengeTimeout: 1000 * 60 * 5,
+  });
 
   const moduleRef = await buildTestModule(redis, config, mockLogger);
 
@@ -136,10 +139,13 @@ describe('PasskeyChallengeManager (integration)', () => {
 
   describe('TTL expiry', () => {
     it('challenge is gone from Redis after the TTL elapses', async () => {
-      const shortConfig = new PasskeyConfig();
-      shortConfig.rpId = 'localhost';
-      shortConfig.allowedOrigins = ['http://localhost'];
-      shortConfig.challengeTimeout = 1000;
+      const shortConfig = new PasskeyConfig({
+        enabled: true,
+        rpId: 'localhost',
+        allowedOrigins: ['http://localhost'],
+        maxPasskeysPerUser: 10,
+        challengeTimeout: 1000,
+      });
 
       const moduleRef = await buildTestModule(redis, shortConfig, mockLogger);
 

libs/accounts/passkey/src/lib/passkey.challenge.manager.spec.ts

@@ -28,11 +28,16 @@ const MOCK_CHALLENGE = Buffer.alloc(32, 0xab).toString('base64url');
 const CHALLENGE_TIMEOUT_MS = 1000 * 60 * 5;
 
 function makeConfig(overrides: Partial<PasskeyConfig> = {}): PasskeyConfig {
-  const config = new PasskeyConfig();
-  config.rpId = 'accounts.firefox.com';
-  config.allowedOrigins = ['https://accounts.firefox.com'];
-  config.challengeTimeout = CHALLENGE_TIMEOUT_MS;
-  Object.assign(config, overrides);
+  const config = new PasskeyConfig({
+    allowedOrigins: ['https://accounts.firefox.com'],
+    challengeTimeout: CHALLENGE_TIMEOUT_MS,
+    enabled: true,
+    maxPasskeysPerUser: 6,
+    residentKey: 'required',
+    rpId: 'accounts.firefox.com',
+    ...overrides,
+  });
+
   return config;
 }
 

libs/accounts/passkey/src/lib/passkey.config.ts

@@ -5,6 +5,7 @@
 import {
   ArrayMinSize,
   IsArray,
+  IsBoolean,
   IsIn,
   IsNotEmpty,
   IsNumber,
@@ -31,6 +32,9 @@ export const MAX_PASSKEY_NAME_LENGTH = 255;
  * and passed to PasskeyService constructor.
  */
 export class PasskeyConfig {
+  @IsBoolean()
+  public enabled!: boolean;
+
   /**
    * WebAuthn Relying Party ID (must match the domain).
    * @example 'accounts.firefox.com'
@@ -99,4 +103,21 @@ export class PasskeyConfig {
   @IsOptional()
   @IsIn(['platform', 'cross-platform'])
   public authenticatorAttachment?: AuthenticatorAttachment | undefined;
+
+  /**
+   * Creates a new PasskeyConfig instance by copying all fields from the
+   * provided options object.
+   *
+   * @param opts - Source object whose properties are copied into this instance.
+   */
+  constructor(opts: PasskeyConfig) {
+    this.allowedOrigins = opts.allowedOrigins;
+    this.authenticatorAttachment = opts.authenticatorAttachment;
+    this.challengeTimeout = opts.challengeTimeout;
+    this.enabled = opts.enabled;
+    this.maxPasskeysPerUser = opts.maxPasskeysPerUser;
+    this.residentKey = opts.residentKey;
+    this.rpId = opts.rpId;
+    this.userVerification = opts.userVerification;
+  }
 }

libs/accounts/passkey/src/lib/passkey.manager.in.spec.ts

@@ -24,11 +24,12 @@ describe('PasskeyManager (Integration)', () => {
   let accountManager: AccountManager;
 
   // Use a small limit to make passkeyLimitReached error tests practical
-  const testConfig: PasskeyConfig = Object.assign(new PasskeyConfig(), {
+  const testConfig: PasskeyConfig = new PasskeyConfig({
+    enabled: true,
     rpId: 'accounts.example.com',
-    rpName: 'Example',
     allowedOrigins: ['https://accounts.example.com'],
     maxPasskeysPerUser: 2,
+    challengeTimeout: 30_000,
   });
 
   const mockMetrics = {

libs/accounts/passkey/src/lib/passkey.manager.spec.ts

@@ -32,11 +32,13 @@ jest.mock('./passkey.repository', () => ({
 
 const mockDb = {} as unknown as AccountDatabase;
 const MOCK_MAX_PASSKEYS_PER_USER = 3;
+const CHALLENGE_TIMEOUT_MS = 1000 * 60 * 5;
 
-const mockConfig: PasskeyConfig = Object.assign(new PasskeyConfig(), {
-  rpId: 'accounts.example.com',
-  rpName: 'Example',
+const mockConfig = new PasskeyConfig({
   allowedOrigins: ['https://accounts.example.com'],
+  enabled: true,
+  rpId: 'accounts.example.com',
+  challengeTimeout: CHALLENGE_TIMEOUT_MS,
   maxPasskeysPerUser: MOCK_MAX_PASSKEYS_PER_USER,
 });
 

libs/accounts/passkey/src/lib/passkey.provider.spec.ts

@@ -20,8 +20,8 @@ const VALID_RAW_CONFIG: RawPasskeyConfig = {
   enabled: true,
   rpId: 'accounts.firefox.com',
   allowedOrigins: ['https://accounts.firefox.com'],
-  challengeTimeout: 60000,
   maxPasskeysPerUser: 10,
+  challengeTimeout: 30_000,
   userVerification: 'required',
   residentKey: 'required',
   authenticatorAttachment: '',
@@ -90,13 +90,6 @@ describe('PasskeyChallengeRedisProvider', () => {
 });
 
 describe('PasskeyConfigProvider', () => {
-  describe('when passkeys.enabled is false', () => {
-    it('returns null without validation', async () => {
-      const { config } = await buildModule({ enabled: false });
-      expect(config).toBeNull();
-    });
-  });
-
   describe('when config is valid', () => {
     it('returns a PasskeyConfig instance', async () => {
       const { config } = await buildModule(VALID_RAW_CONFIG);
@@ -107,7 +100,7 @@ describe('PasskeyConfigProvider', () => {
       const { config } = await buildModule(VALID_RAW_CONFIG);
       expect(config!.rpId).toBe('accounts.firefox.com');
       expect(config!.allowedOrigins).toEqual(['https://accounts.firefox.com']);
-      expect(config!.challengeTimeout).toBe(60000);
+      expect(config!.challengeTimeout).toBe(30_000);
       expect(config!.maxPasskeysPerUser).toBe(10);
       expect(config!.userVerification).toBe('required');
       expect(config!.residentKey).toBe('required');
@@ -125,46 +118,46 @@ describe('PasskeyConfigProvider', () => {
   });
 
   describe('when config is invalid', () => {
-    it('returns null', async () => {
-      const { config } = await buildModule({
-        ...VALID_RAW_CONFIG,
-        rpId: '',
-        allowedOrigins: ['not-a-valid-origin'],
-      });
-      expect(config).toBeNull();
+    it('throws', async () => {
+      await expect(() =>
+        buildModule({
+          ...VALID_RAW_CONFIG,
+          rpId: '',
+        })
+      ).rejects.toThrow('property rpId has failed the following constraints');
     });
 
-    it('logs an error with the validation message', async () => {
-      const { logger } = await buildModule({
-        ...VALID_RAW_CONFIG,
-        allowedOrigins: ['not-a-valid-origin'],
-      });
-      expect(logger.error).toHaveBeenCalledWith(
-        'passkey.config.invalid',
-        expect.objectContaining({
-          message: expect.stringContaining(
-            'Passkeys disabled due to malformed config'
-          ),
+    it('rejects allowedOrigins with trailing path', async () => {
+      await expect(() =>
+        buildModule({
+          ...VALID_RAW_CONFIG,
+          allowedOrigins: 'not-a-valid-origin',
         })
+      ).rejects.toThrow(
+        'property allowedOrigins has failed the following constraints'
       );
     });
 
     it('rejects allowedOrigins with trailing path', async () => {
-      const { config, logger } = await buildModule({
-        ...VALID_RAW_CONFIG,
-        allowedOrigins: ['https://accounts.firefox.com/path'],
-      });
-      expect(config).toBeNull();
-      expect(logger.error).toHaveBeenCalled();
+      await expect(() =>
+        buildModule({
+          ...VALID_RAW_CONFIG,
+          allowedOrigins: ['https://accounts.firefox.com/path'],
+        })
+      ).rejects.toThrow(
+        'property allowedOrigins has failed the following constraints'
+      );
     });
 
     it('rejects empty allowedOrigins array', async () => {
-      const { config, logger } = await buildModule({
-        ...VALID_RAW_CONFIG,
-        allowedOrigins: [],
-      });
-      expect(config).toBeNull();
-      expect(logger.error).toHaveBeenCalled();
+      await expect(() =>
+        buildModule({
+          ...VALID_RAW_CONFIG,
+          allowedOrigins: [],
+        })
+      ).rejects.toThrow(
+        'property allowedOrigins has failed the following constraints'
+      );
     });
   });
 });

libs/accounts/passkey/src/lib/passkey.provider.ts

@@ -14,6 +14,14 @@ import type {
   UserVerificationRequirement,
 } from '@simplewebauthn/server';
 
+/**
+ * Raw passkey configuration.
+ *
+ * Mirrors the passkeys section of the for general configurations.
+ * An empty string for `authenticatorAttachment` is normalized to `undefined`
+ * by {@link buildPasskeyConfig} because Convict cannot represent `undefined`
+ * in JSON config files.
+ */
 export type RawPasskeyConfig = {
   enabled: boolean;
   rpId: string;
@@ -22,38 +30,46 @@ export type RawPasskeyConfig = {
   maxPasskeysPerUser: number;
   userVerification: UserVerificationRequirement;
   residentKey: ResidentKeyRequirement;
+  /** Empty string is treated as "no preference" and normalized to `undefined`. */
   authenticatorAttachment: AuthenticatorAttachment | '';
 };
 
-export function buildPasskeyConfig(
-  raw: RawPasskeyConfig,
-  log: LoggerService
-): PasskeyConfig | null {
-  if (!raw.enabled) {
-    return null;
-  }
-
-  const mapped = {
+/**
+ * Builds and validates a {@link PasskeyConfig} from raw Convict values.
+ *
+ * Normalizes `authenticatorAttachment`: an empty string (the Convict
+ * no-preference sentinel) is converted to `undefined` so that the
+ * WebAuthn library omits the field from registration options entirely.
+ *
+ * @param raw - Raw config values read from Convict.
+ * @returns A fully validated {@link PasskeyConfig} instance.
+ * @throws {Error} If any field fails class-validator constraints, with a
+ *   human-readable list of all validation errors.
+ */
+export function buildPasskeyConfig(raw: RawPasskeyConfig): PasskeyConfig {
+  const passkeyConfig = new PasskeyConfig({
     ...raw,
     authenticatorAttachment: raw.authenticatorAttachment || undefined,
-  };
+  });
 
-  const passkeyConfig = Object.assign(new PasskeyConfig(), mapped);
   const errors = validateSync(passkeyConfig, {
     skipMissingProperties: false,
   });
   if (errors.length > 0) {
     const message = errors.map((e) => e.toString()).join('\n');
-    log.error('passkey.config.invalid', {
-      message: `Passkeys disabled due to malformed config:\n${message}`,
-    });
-    return null;
+    throw new Error(`Malformed passkey config:\n${message}`);
   }
   return passkeyConfig;
 }
 
+/** NestJS injection token for the passkey-specific Redis client. */
 export const PASSKEY_CHALLENGE_REDIS = 'PasskeyChallengeRedis';
 
+/**
+ * NestJS provider that creates a dedicated Redis client for passkey challenge
+ * storage. The client is configured by merging the base `redis` config with
+ * the `redis.passkey` override, allowing a separate DB index or host.
+ */
 export const PasskeyChallengeRedisProvider = {
   provide: PASSKEY_CHALLENGE_REDIS,
   useFactory: (config: ConfigService) => {
@@ -67,6 +83,14 @@ export const PasskeyChallengeRedisProvider = {
   inject: [ConfigService],
 };
 
+/**
+ * NestJS provider that reads, validates, and exposes the {@link PasskeyConfig}
+ * for injection throughout the passkey module.
+ *
+ * Returns `null` (and logs an error) when the `passkeys` config key is absent,
+ * allowing dependent services to treat passkeys as disabled rather than
+ * throwing at startup.
+ */
 export const PasskeyConfigProvider = {
   provide: PasskeyConfig,
   useFactory: (config: ConfigService, log: LoggerService) => {
@@ -77,7 +101,7 @@ export const PasskeyConfigProvider = {
       });
       return null;
     }
-    return buildPasskeyConfig(rawConfig as RawPasskeyConfig, log);
+    return buildPasskeyConfig(rawConfig as RawPasskeyConfig);
   },
   inject: [ConfigService, LOGGER_PROVIDER],
 };

libs/accounts/passkey/src/lib/passkey.service.spec.ts

@@ -101,11 +101,12 @@ describe('PasskeyService', () => {
     warn: jest.fn(),
   };
 
-  const mockConfig = Object.assign(new PasskeyConfig(), {
+  const mockConfig = new PasskeyConfig({
+    enabled: true,
     rpId: 'accounts.firefox.com',
     allowedOrigins: ['https://accounts.firefox.com'],
-    challengeTimeout: 60000,
     maxPasskeysPerUser: 10,
+    challengeTimeout: 30_000,
     userVerification: 'required',
     residentKey: 'required',
   });

libs/accounts/passkey/src/lib/passkey.service.ts

@@ -75,6 +75,21 @@ const DISPLAY_SAFE_UNICODE_WITH_NON_BMP =
  */
 @Injectable()
 export class PasskeyService {
+  /**
+   * Indicates service is enabled.
+   */
+  get enabled(): boolean {
+    return this.config.enabled;
+  }
+
+  /**
+   * Creates new PasskeyService
+   * @param passkeyManager current passkey manager
+   * @param challengeManager current pass key challenge manager
+   * @param config config for passkeys
+   * @param metrics metrics for emitting raw metrics
+   * @param log logger for logging errors / warnings
+   */
   constructor(
     private readonly passkeyManager: PasskeyManager,
     private readonly challengeManager: PasskeyChallengeManager,
@@ -122,6 +137,11 @@ export class PasskeyService {
    * @param uid - User ID (16-byte Buffer)
    * @param response - Raw registration response from the browser
    * @param challenge - Challenge that was issued for this registration
+   * @returns The newly created passkey record as stored in the database.
+   * @throws {AppError} passkeyChallengeNotFound if the challenge has expired,
+   *   was already consumed, or never existed.
+   * @throws {AppError} passkeyRegistrationFailed if attestation verification
+   *   fails or the verified flag is false.
    */
   async createPasskeyFromRegistrationResponse(
     uid: Buffer,