task(libs): Add passkeys data model

Because:

* We are adding WebAuthn/FIDO2 passkey support

This commit:

* Adds database migration creating passkeys table with composite primary key and proper indexing
* Generates Kysely types (Passkey, NewPasskey, PasskeyUpdate) with type guards for validation
* Implements 8 pure repository functions for CRUD operations following FxA patterns
* Creates PasskeyFactory for generating test data and updates integration test infrastructure
* Provides comprehensive field documentation in PASSKEY_FIELDS.md covering WebAuthn spec and usage

Closes #FXA-12901

Author: vpomerleau

libs/accounts/passkey/PASSKEY_FIELDS.md

@@ -63,6 +63,15 @@ Unlike `libs/shared/nestjs/*`, this library **does not export a NestJS module**.
 
 This pattern gives consuming applications full control over DI setup.
 
+## Database Schema
+
+See [PASSKEY_FIELDS.md](./PASSKEY_FIELDS.md) for complete field documentation including:
+
+- Field types and constraints
+- WebAuthn backup flags (BE/BS)
+- Type conversion details (ColumnType)
+- Usage examples and patterns
+
 ## WebAuthn / Passkey Background
 
 Passkeys are a WebAuthn-based authentication method that replaces passwords:
@@ -84,6 +93,7 @@ Key WebAuthn concepts:
 
 - [WebAuthn Spec](https://www.w3.org/TR/webauthn-3/)
 - [Passkey Developer Guide](https://passkeys.dev/)
+- [Field Documentation](./PASSKEY_FIELDS.md) (detailed schema reference)
 
 ## Error Handling
 

libs/accounts/passkey/README.md

@@ -9,12 +9,19 @@
  * Usage:
  * - PasskeyService: High-level business logic for passkey operations
  * - PasskeyManager: Database access layer for passkey storage
+ * - Repository functions: Pure data access functions (findPasskeysByUid, etc.)
  * - PasskeyError: Base error class for passkey-specific errors
  * - PasskeyConfig: Configuration class
  *
+ * Types (import directly from shared):
+ * ```typescript
+ * import { Passkey, NewPasskey, PasskeyUpdate } from '@fxa/shared/db/mysql/account';
+ * ```
+ *
  * @packageDocumentation
  */
 export * from './lib/passkey.service';
 export * from './lib/passkey.manager';
+export * from './lib/passkey.repository';
 export * from './lib/passkey.errors';
 export * from './lib/passkey.config';

libs/accounts/passkey/src/index.ts

@@ -16,9 +16,8 @@ describe('PasskeyManager (Integration)', () => {
 
   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']);
+      db = await testAccountDatabaseSetup(['accounts', 'passkeys']);
 
       const moduleRef = await Test.createTestingModule({
         providers: [
@@ -48,10 +47,7 @@ describe('PasskeyManager (Integration)', () => {
     }
   });
 
-  // TODO: Add actual integration tests once:
-  // 1. Passkey database schema is defined
-  // 2. PasskeyManager methods are implemented
-  // 3. Test data factories are created
+  // TODO: Add actual integration tests once PasskeyManager methods are implemented
   it('should be defined', () => {
     expect(manager).toBeDefined();
   });

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

@@ -5,13 +5,192 @@
 /**
  * Pure data access functions for passkey storage using Kysely query builder.
  *
- * TODO: Implement repository functions once database migration is applied in FXA-12901.
- * Expected functions:
- * - findPasskeysByUid(db, uid)
- * - findPasskeyByCredentialId(db, credentialId)
- * - insertPasskey(db, passkey)
- * - updatePasskeyCounterAndLastUsed(db, credentialId, signCount)
- * - deletePasskey(db, uid, credentialId)
- * - deleteAllPasskeysForUser(db, uid)
- * - countPasskeysByUid(db, uid)
+ * These are pure functions that take the database instance as the first parameter,
+ * following the functional repository pattern used throughout FxA.
+ *
+ * Note: On successful authentication, update:
+ * - lastUsedAt: Current timestamp
+ * - signCount: Value from authenticator data (should increment)
+ * - backupState: Current backup state flag (BS) from authenticator data (0 or 1)
+ *
+ * On registration:
+ * - Set backupEligible from authenticator data (BE flag) - 0 or 1
+ * - Set backupState from authenticator data (BS flag) - 0 or 1
+ * - Leave lastUsedAt as NULL (never used for authentication)
+ *
+ * On failed authentication, do not update anything.
+ *
+ * Type conversion: Backup flags are stored as TINYINT(1) in MySQL (0 or 1).
+ * - For INSERT/UPDATE: Pass numbers (0 or 1)
+ * - For SELECT: Kysely returns booleans (false or true)
+ */
+
+import type {
+  AccountDatabase,
+  Passkey,
+  NewPasskey,
+} from '@fxa/shared/db/mysql/account';
+
+/**
+ * Find all passkeys for a given user.
+ *
+ * Note: Results are not ordered. The number of passkeys per user will be
+ * constrained (typically < 10), so ordering is not necessary and clients
+ * can sort as needed.
+ *
+ * @param db - Database instance
+ * @param uid - User ID (16-byte Buffer)
+ * @returns Array of passkeys for the user (unordered)
+ */
+export async function findPasskeysByUid(
+  db: AccountDatabase,
+  uid: Buffer
+): Promise<Passkey[]> {
+  return await db
+    .selectFrom('passkeys')
+    .selectAll()
+    .where('uid', '=', uid)
+    .execute();
+}
+
+/**
+ * Find a passkey by its credential ID.
+ *
+ * @param db - Database instance
+ * @param credentialId - WebAuthn credential ID (Buffer)
+ * @returns Passkey if found, undefined otherwise
  */
+export async function findPasskeyByCredentialId(
+  db: AccountDatabase,
+  credentialId: Buffer
+): Promise<Passkey | undefined> {
+  return await db
+    .selectFrom('passkeys')
+    .selectAll()
+    .where('credentialId', '=', credentialId)
+    .executeTakeFirst();
+}
+
+/**
+ * Insert a new passkey record.
+ *
+ * @param db - Database instance
+ * @param passkey - New passkey data to insert
+ */
+export async function insertPasskey(
+  db: AccountDatabase,
+  passkey: NewPasskey
+): Promise<void> {
+  await db.insertInto('passkeys').values(passkey).execute();
+}
+
+/**
+ * Update passkey metadata after successful authentication.
+ *
+ * Updates lastUsedAt, signCount, and backupState for a passkey.
+ * Should only be called after successful authentication.
+ *
+ * @param db - Database instance
+ * @param credentialId - WebAuthn credential ID (Buffer)
+ * @param signCount - New signature count from authenticator data
+ * @param backupState - Current backup state flag (0 or 1) from authenticator data
+ */
+export async function updatePasskeyCounterAndLastUsed(
+  db: AccountDatabase,
+  credentialId: Buffer,
+  signCount: number,
+  backupState: number
+): Promise<void> {
+  await db
+    .updateTable('passkeys')
+    .set({
+      lastUsedAt: Date.now(),
+      signCount: signCount,
+      backupState: backupState,
+    })
+    .where('credentialId', '=', credentialId)
+    .execute();
+}
+
+/**
+ * Update the friendly name for a passkey.
+ *
+ * @param db - Database instance
+ * @param credentialId - WebAuthn credential ID (Buffer)
+ * @param name - New friendly name for the passkey
+ * @returns Number of rows updated (should be 1 if successful)
+ */
+export async function updatePasskeyName(
+  db: AccountDatabase,
+  credentialId: Buffer,
+  name: string
+): Promise<number> {
+  const result = await db
+    .updateTable('passkeys')
+    .set({ name })
+    .where('credentialId', '=', credentialId)
+    .execute();
+
+  return result.length;
+}
+
+/**
+ * Delete a specific passkey for a user.
+ *
+ * @param db - Database instance
+ * @param uid - User ID (16-byte Buffer)
+ * @param credentialId - WebAuthn credential ID (Buffer)
+ * @returns true if a passkey was deleted, false otherwise
+ */
+export async function deletePasskey(
+  db: AccountDatabase,
+  uid: Buffer,
+  credentialId: Buffer
+): Promise<boolean> {
+  const result = await db
+    .deleteFrom('passkeys')
+    .where('uid', '=', uid)
+    .where('credentialId', '=', credentialId)
+    .executeTakeFirst();
+
+  return result.numDeletedRows === BigInt(1);
+}
+
+/**
+ * Delete all passkeys for a user.
+ *
+ * @param db - Database instance
+ * @param uid - User ID (16-byte Buffer)
+ * @returns Number of passkeys deleted
+ */
+export async function deleteAllPasskeysForUser(
+  db: AccountDatabase,
+  uid: Buffer
+): Promise<number> {
+  const result = await db
+    .deleteFrom('passkeys')
+    .where('uid', '=', uid)
+    .executeTakeFirst();
+
+  return Number(result.numDeletedRows);
+}
+
+/**
+ * Count the number of passkeys for a user.
+ *
+ * @param db - Database instance
+ * @param uid - User ID (16-byte Buffer)
+ * @returns Number of passkeys for the user
+ */
+export async function countPasskeysByUid(
+  db: AccountDatabase,
+  uid: Buffer
+): Promise<number> {
+  const result = await db
+    .selectFrom('passkeys')
+    .select(db.fn.count('credentialId').as('count'))
+    .where('uid', '=', uid)
+    .executeTakeFirst();
+
+  return Number(result?.count ?? 0);
+}

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

@@ -16,6 +16,25 @@ import { PasskeyManager } from './passkey.manager';
  * - Passkey management (list, rename, delete)
  * - Challenge generation and verification
  *
+ * ## WebAuthn Library Integration
+ *
+ * This service will use a WebAuthn library (e.g., @simplewebauthn/server) for:
+ * - Challenge generation and validation
+ * - Cryptographic signature verification
+ * - CBOR/COSE parsing (publicKey, credentialId, authenticator data)
+ * - Extracting: signCount, transports, aaguid, backup flags (BE/BS)
+ *
+ * The library handles WebAuthn spec compliance and crypto operations.
+ * This service translates between WebAuthn responses and our database model.
+ *
+ * ## Data Normalization
+ *
+ * When storing passkey data from WebAuthn library responses:
+ * - **AAGUID**: Normalize all-zeros (00000000-0000-0000-0000-000000000000) to NULL
+ *   Many authenticators return all-zeros for privacy. Store NULL when meaningless.
+ * - **transports**: Trust library-provided JSON array string (validated by library)
+ * - **backupEligible/backupState**: Extract from authenticator data flags (BE/BS bits)
+ *
  */
 @Injectable()
 export class PasskeyService {
@@ -27,10 +46,24 @@ export class PasskeyService {
 
   // TODO: Add methods for passkey operations such as:
   // - generateRegistrationChallenge
-  // - verifyRegistrationResponse
+  // - verifyRegistrationResponse (normalize AAGUID here before storing)
   // - generateAuthenticationChallenge
-  // - verifyAuthenticationResponse
+  // - verifyAuthenticationResponse (extract backup state, signCount, validate rollback)
   // - listPasskeysForUser
   // - renamePasskey
   // - deletePasskey
+  //
+  // TODO: Add normalizeAaguid() helper:
+  //   function normalizeAaguid(aaguid: Buffer | null | undefined): Buffer | null {
+  //     if (!aaguid || aaguid.length !== 16) return null;
+  //     if (aaguid.every(byte => byte === 0)) return null;
+  //     return aaguid;
+  //   }
+  //
+  // TODO: Add signCount rollback detection in verifyAuthenticationResponse():
+  //   - Fetch existing passkey with current signCount
+  //   - Compare new signCount from authenticator response
+  //   - If new < old AND old > 0: Log security warning (potential cloning attack)
+  //   - Allow authenticators that always return 0 (batch attestation per spec)
+  //   - Log event: 'passkey.signCount.rollback' with uid, credentialId, oldCount, newCount
 }

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

@@ -9,6 +9,7 @@ export {
   AccountFactory,
   AccountCustomerFactory,
   PaypalCustomerFactory,
+  PasskeyFactory,
   RecoveryPhoneFactory,
 } from './lib/factories';
 export { setupAccountDatabase, AccountDbProvider } from './lib/setup';

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

@@ -10,6 +10,7 @@ import {
   AccountCustomers,
   Accounts,
   Carts,
+  Passkeys,
   PaypalCustomers,
   SessionTokens,
   UnverifiedTokens,
@@ -43,3 +44,7 @@ export type CartUpdate = Updateable<Carts>;
 export type RecoveryPhone = Selectable<RecoveryPhones>;
 export type NewRecoveryPhone = Insertable<RecoveryPhones>;
 export type RecoveryPhoneUpdate = Updateable<RecoveryPhones>;
+
+export type Passkey = Selectable<Passkeys>;
+export type NewPasskey = Insertable<Passkeys>;
+export type PasskeyUpdate = Updateable<Passkeys>;

libs/shared/db/mysql/account/src/index.ts

@@ -8,6 +8,7 @@ import {
   Account,
   AccountCustomer,
   NewCart,
+  NewPasskey,
   PaypalCustomer,
   SessionToken,
   UnverifiedToken,
@@ -182,3 +183,30 @@ export const RecoveryPhoneFactory = (override?: Partial<RecoveryPhone>) => ({
   }),
   ...override,
 });
+
+export const PasskeyFactory = (override?: Partial<NewPasskey>): NewPasskey => ({
+  uid: getHexBuffer(32),
+  credentialId: getHexBuffer(faker.number.int({ min: 32, max: 128 })),
+  publicKey: getHexBuffer(128),
+  signCount: 0,
+  transports: faker.helpers.arrayElement([
+    '["internal"]',
+    '["usb"]',
+    '["internal","hybrid"]',
+    null,
+  ]),
+  aaguid: faker.datatype.boolean() ? getHexBuffer(32) : null,
+  name: faker.helpers.arrayElement([
+    'Touch ID',
+    'YubiKey 5',
+    'Security Key',
+    'iPhone Face ID',
+    null,
+  ]),
+  createdAt: faker.date.recent().getTime(),
+  lastUsedAt: faker.datatype.boolean() ? faker.date.recent().getTime() : null,
+  backupEligible: faker.helpers.arrayElement([0, 1]),
+  backupState: faker.helpers.arrayElement([0, 1]),
+  prfEnabled: faker.helpers.arrayElement([0, 1]),
+  ...override,
+});