Merge pull request #19984 from mozilla/FXA-12900

feat(libs): Create scaffolding for passkeys library

Author: vpomerleau

libs/accounts/passkey/.eslintrc.json

@@ -0,0 +1,18 @@
+{
+  "extends": ["../../../.eslintrc.json"],
+  "ignorePatterns": ["!**/*"],
+  "overrides": [
+    {
+      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.ts", "*.tsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.js", "*.jsx"],
+      "rules": {}
+    }
+  ]
+}

libs/accounts/passkey/README.md

@@ -0,0 +1,84 @@
+# accounts-passkey
+
+Passkey (WebAuthn) authentication library for Firefox Accounts.
+
+This library was generated with [Nx](https://nx.dev).
+
+## Building
+
+Run `nx run accounts-passkey:build` to build the library.
+
+## Running unit tests
+
+Run `nx run accounts-passkey:test-unit` to execute the unit tests via [Jest](https://jestjs.io).
+
+## Running integration tests
+
+Make sure local infrastructure (databases) are running. Check status with `yarn pm2 status` - you should see redis and mysql instances running. If not, run `yarn start infrastructure`.
+
+Run `nx run accounts-passkey:test-integration` to execute the integration tests via [Jest](https://jestjs.io).
+
+## Architecture
+
+This library follows the layered architecture pattern used across `libs/accounts/*`:
+
+### Layers
+
+1. **Service Layer** (`passkey.service.ts`)
+   - High-level business logic and orchestration
+   - Validates input, coordinates operations
+   - Handles metrics and logging
+   - Called by route handlers in auth-server/admin-server
+
+2. **Manager Layer** (`passkey.manager.ts`)
+   - Injectable class that wraps database operations
+   - Coordinates repository function calls
+   - Handles transactions and business logic related to data
+   - Injected into Service layer
+
+3. **Repository Layer** (`passkey.repository.ts`)
+   - Pure functions that accept `AccountDatabase` as first parameter
+   - Direct SQL queries using Kysely query builder
+   - No business logic, just data access
+   - Called by Manager layer
+
+4. **Error Layer** (`passkey.errors.ts`)
+   - Domain-specific error classes
+   - Structured error information for logging
+   - HTTP status code mapping
+
+5. **Configuration** (`passkey.config.ts`)
+   - Type-safe configuration interface
+   - Validated with class-validator decorators
+   - Loaded from Convict config in consuming applications
+
+### Pattern: No Module Export
+
+Unlike `libs/shared/nestjs/*`, this library **does not export a NestJS module**. This is intentional:
+
+- **auth-server** (Hapi + TypeDI): Uses `Container.get(PasskeyService)`
+- **admin-server** (NestJS): Manually wires providers in their modules
+
+This pattern gives consuming applications full control over DI setup.
+
+## WebAuthn / Passkey Background
+
+Passkeys are a WebAuthn-based authentication method that replaces passwords:
+
+- **Registration (Attestation)**: Create a new passkey credential
+- **Authentication (Assertion)**: Verify using existing passkey
+- **Challenge-Response**: Server generates challenge, client signs it
+- **Public Key Cryptography**: Private key stays on device, public key stored in DB
+
+Key WebAuthn concepts:
+
+- **Relying Party (RP)**: Our service (accounts.firefox.com)
+- **Authenticator**: User's device (phone, laptop, security key)
+- **Credential ID**: Unique identifier for each passkey
+- **Counter**: Signature counter for replay attack prevention
+- **User Verification (UV)**: Biometric or PIN on the device
+
+### Resources
+
+- [WebAuthn Spec](https://www.w3.org/TR/webauthn-3/)
+- [Passkey Developer Guide](https://passkeys.dev/)

libs/accounts/passkey/jest.config.ts

@@ -0,0 +1,29 @@
+import { Config } from 'jest';
+
+/* eslint-disable */
+const config: Config = {
+  displayName: 'passkey',
+  preset: '../../../jest.preset.js',
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.[tj]s$': ['ts-jest', { tsconfig: '<rootDir>/tsconfig.spec.json' }],
+  },
+  moduleFileExtensions: ['ts', 'js', 'html'],
+  coverageDirectory: '../../../coverage/libs/accounts/passkey',
+  reporters: [
+    'default',
+    [
+      'jest-junit',
+      {
+        outputDirectory: 'artifacts/tests/accounts-passkey',
+        // It is critical that the package_name here is unique among all
+        // Jest configs. This file is uploaded to GCS and will error on upload
+        // if not unique because permissions for the upload deliberately prevent
+        // overwriting files.
+        outputName: 'accounts-passkey-jest-unit-results.xml',
+      },
+    ],
+  ],
+};
+
+export default config;

libs/accounts/passkey/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@fxa/accounts/passkey",
+  "version": "0.0.1",
+  "private": true,
+  "type": "commonjs",
+  "main": "./index.cjs",
+  "types": "./index.d.ts",
+  "dependencies": {}
+}

libs/accounts/passkey/project.json

@@ -0,0 +1,38 @@
+{
+  "name": "accounts-passkey",
+  "$schema": "../../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/accounts/passkey/src",
+  "projectType": "library",
+  "tags": ["scope:shared:lib"],
+  "targets": {
+    "build": {
+      "executor": "@nx/esbuild:esbuild",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "outputPath": "dist/libs/accounts/passkey",
+        "main": "libs/accounts/passkey/src/index.ts",
+        "tsConfig": "libs/accounts/passkey/tsconfig.lib.json",
+        "assets": ["libs/accounts/passkey/*.md"],
+        "format": ["cjs"],
+        "generatePackageJson": true,
+        "declaration": true
+      }
+    },
+    "test-unit": {
+      "executor": "@nx/jest:jest",
+      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
+      "options": {
+        "jestConfig": "libs/accounts/passkey/jest.config.ts",
+        "testPathPattern": ["^(?!.*\\.in\\.spec\\.ts$).*$"]
+      }
+    },
+    "test-integration": {
+      "executor": "@nx/jest:jest",
+      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
+      "options": {
+        "jestConfig": "libs/accounts/passkey/jest.config.ts",
+        "testPathPattern": ["\\.in\\.spec\\.ts$"]
+      }
+    }
+  }
+}

libs/accounts/passkey/src/index.ts

@@ -0,0 +1,20 @@
+/**
+ * @fxa/accounts/passkey
+ *
+ * Passkey (WebAuthn) authentication library for Firefox Accounts.
+ *
+ * This library provides passkey registration and authentication functionality
+ * following the WebAuthn specification.
+ *
+ * Usage:
+ * - PasskeyService: High-level business logic for passkey operations
+ * - PasskeyManager: Database access layer for passkey storage
+ * - PasskeyError: Base error class for passkey-specific errors
+ * - PasskeyConfig: Configuration class
+ *
+ * @packageDocumentation
+ */
+export * from './lib/passkey.service';
+export * from './lib/passkey.manager';
+export * from './lib/passkey.errors';
+export * from './lib/passkey.config';

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

@@ -0,0 +1,83 @@
+/* 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 { IsArray, IsBoolean, IsNumber, IsString } from 'class-validator';
+
+/**
+ * Configuration for passkey (WebAuthn) functionality.
+ *
+ * This configuration is loaded from Convict in auth-server's config/index.ts
+ * and passed to PasskeyService constructor.
+ */
+export class PasskeyConfig {
+  /**
+   * Feature flag to enable/disable passkey functionality.
+   */
+  @IsBoolean()
+  public enabled?: boolean;
+
+  /**
+   * WebAuthn Relying Party ID (must match the domain).
+   * @example 'accounts.firefox.com'
+   */
+  @IsString()
+  public rpId!: string;
+
+  /**
+   * WebAuthn Relying Party display name.
+   * @example 'Mozilla Accounts'
+   */
+  @IsString()
+  public rpName!: string;
+
+  /**
+   * Allowed origins for WebAuthn credential creation and authentication.
+   * Must include protocol and domain.
+   * @example ['https://accounts.firefox.com', 'https://accounts.stage.mozaws.net']
+   */
+  @IsArray()
+  public allowedOrigins!: Array<string>;
+
+  /**
+   * Maximum number of passkeys a user can register.
+   */
+  @IsNumber()
+  public maxPasskeysPerUser?: number;
+
+  /**
+   * Challenge expiration timeout in milliseconds.
+   * @example 300000 (5 minutes)
+   */
+  @IsNumber()
+  public challengeTimeout?: number;
+
+  /**
+   * User verification requirement for WebAuthn.
+   * - 'required': User verification must occur (e.g., biometric, PIN)
+   * - 'preferred': User verification preferred but not required
+   * - 'discouraged': User verification should not occur
+   * @example 'required'
+   */
+  @IsString()
+  public userVerification?: string;
+
+  /**
+   * Resident key (discoverable credential) requirement.
+   * - 'required': Credential must be discoverable (stored on authenticator)
+   * - 'preferred': Discoverable credential preferred but not required
+   * - 'discouraged': Non-discoverable credential preferred
+   * @example 'preferred'
+   */
+  @IsString()
+  public residentKey?: string;
+
+  /**
+   * Authenticator attachment preference.
+   * - 'platform': Platform authenticators (built into device, like Touch ID)
+   * - 'cross-platform': Roaming authenticators (USB security keys)
+   * - undefined: No preference (allow any)
+   */
+  @IsString()
+  public authenticatorAttachment?: string;
+}

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

@@ -0,0 +1,38 @@
+/* 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 { BaseError } from '@fxa/shared/error';
+
+/**
+ * Base error class for passkey-related errors.
+ *
+ * Subclasses should use descriptive names ending in "Error" and include
+ * context (e.g., PasskeyNotFoundError, not NotFoundError).
+ *
+ * Error numbers (errno) must be defined in the central ERRNO object at
+ * libs/accounts/errors/src/constants.ts and imported for use in error info.
+ *
+ * @see libs/accounts/recovery-phone/src/lib/recovery-phone.errors.ts
+ */
+export class PasskeyError extends BaseError {
+  /**
+   * Creates a PasskeyError.
+   *
+   * @param message - Human-readable error message
+   * @param info - Structured data for logging and debugging (examples: { errno: 1001, uid: '1234' })
+   * @param cause - Optional underlying error that caused this error
+   *
+   * The resulting error object contains:
+   * @property {string} name - Always 'PasskeyError' for base class
+   * @property {object} info - Structured info object that provides context for the error (e.g., errno, uid)
+   * @property {Error} [cause] - The underlying error if provided
+   */
+  constructor(message: string, info: Record<string, any>, cause?: Error) {
+    super(message, {
+      name: 'PasskeyError',
+      cause,
+      info,
+    });
+  }
+}

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

@@ -0,0 +1,58 @@
+/* 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 { PasskeyManager } from './passkey.manager';
+import {
+  AccountDatabase,
+  AccountDbProvider,
+  testAccountDatabaseSetup,
+} from '@fxa/shared/db/mysql/account';
+import { Test } from '@nestjs/testing';
+
+describe('PasskeyManager (Integration)', () => {
+  let manager: PasskeyManager;
+  let db: AccountDatabase;
+
+  beforeAll(async () => {
+    // Set up real database connection for integration tests
+    // TODO: Add 'passkeys' table to the setup array once the table schema is created
+    try {
+      db = await testAccountDatabaseSetup(['accounts']);
+
+      const moduleRef = await Test.createTestingModule({
+        providers: [
+          PasskeyManager,
+          {
+            provide: AccountDbProvider,
+            useValue: db,
+          },
+        ],
+      }).compile();
+
+      manager = moduleRef.get(PasskeyManager);
+    } catch (error) {
+      // Log helpful message before failing fast
+      console.warn('\n⚠️  Integration tests require database infrastructure.');
+      console.warn(
+        '   Run "yarn start infrastructure" to enable these tests.\n'
+      );
+      // Re-throw to fail fast instead of running tests that will skip
+      throw error;
+    }
+  });
+
+  afterAll(async () => {
+    if (db) {
+      await db.destroy();
+    }
+  });
+
+  // TODO: Add actual integration tests once:
+  // 1. Passkey database schema is defined
+  // 2. PasskeyManager methods are implemented
+  // 3. Test data factories are created
+  it('should be defined', () => {
+    expect(manager).toBeDefined();
+  });
+});