@ambushsoftworks/nestjs-auth-graphql 0.15.1 → 0.16.0-rc.2

package/CHANGELOG.md

@@ -27,6 +27,166 @@ for buried obligations. **The marker was introduced in 0.9.0 and has not been
 retro-applied**, so it is reliable from 0.9.0 onward only. Convention adopted
 from `@ambushsoftworks/nestjs-payments-graphql`.
 
+## [0.16.0-rc.2] - 2026-10-01
+
+Fixes from LiftIQ's pilot of rc.1 on a real Android Credential Manager. Still a
+release candidate on `next`.
+
+### Changed — breaking (for rc.1 adopters)
+
+- **A rejected step-up proof is `STEP_UP_FAILED` (403), not `401
+  UNAUTHENTICATED`.** Clients read `UNAUTHENTICATED` as an expired session, so
+  an Apollo error link refreshed the token and re-sent `reauthenticate`: a wrong
+  password counted **twice** toward lockout, a passkey proof's retry always
+  failed (its challenge was spent), and a failed refresh signed the user out.
+  The message is unchanged. Do not map `STEP_UP_FAILED` to a token refresh.
+- **Passkey sign-in failure is `PASSKEY_AUTHENTICATION_FAILED` (401)**, same
+  message, same answer for every reason. Its own code for the same reason: a
+  client still holding an old token would refresh and retry an assertion whose
+  challenge is spent.
+- **The two passkey conflicts have codes:** `PASSKEY_ALREADY_REGISTERED` and
+  `CANNOT_REMOVE_LAST_AUTH_METHOD`, both 409, in the style of
+  `CANNOT_UNLINK_LAST_AUTH_METHOD`. Before, both were `CONFLICT` with English
+  text only.
+- **The package emails the owner when a passkey is added or removed.** Through
+  the new optional `IEmailService.sendPasskeyAddedEmail(email, passkeyName,
+  addedAt)` and `sendPasskeyRemovedEmail(email, passkeyName, removedAt)`, when
+  the email service has them; `ConfigurableEmailService` does when its renderer
+  implements the new `renderPasskeyAddedEmail` / `renderPasskeyRemovedEmail`,
+  and `DefaultEmailTemplateRenderer` does. **If you send these from
+  `onPasskeyRegistered` / `onPasskeyRemoved`, stop, or owners get two** — or
+  turn the package's off with `passkey.emailNotifications: { added: false,
+  removed: false }`. rc.1 told adopters to wire the email themselves without
+  giving them anything to wire it to; a security notice the owner depends on
+  should not be opt-in.
+
+### Added
+
+- **`@ambushsoftworks/nestjs-auth-graphql/testing`**, a public entry with:
+  - `assertPasskeyRepositoryContract(factory)`: checks an `IPasskeyRepository`
+    adapter against the contract, against your real database, and rejects
+    naming the rule broken. The README pointed adopters at a spec file that is
+    not published; this replaces it. It is verified to catch a read-then-write
+    claim or counter update, a 32-bit counter column, an unmapped unique
+    violation, a dropped realm, hidden deactivated credentials, and expiry left
+    to a TTL.
+  - `SoftwareAuthenticator`, previously reachable only as a deep import into
+    `dist/` (which keeps working).
+  It is a published `testing/` folder rather than an `exports` map, because an
+  `exports` map would break existing deep imports.
+- `passkey.emailNotifications: { added?, removed? }`, both default `true`,
+  validated at boot (a misspelt key would otherwise leave a notice on).
+- Exceptions `StepUpFailedException`, `PasskeyAuthenticationFailedException`,
+  `PasskeyAlreadyRegisteredException`, `CannotRemoveLastAuthMethodException`.
+
+### Documented
+
+- **A step-up token is reusable until it expires, not single-use**, and a test
+  pins it. One re-authentication may cover several protected actions within
+  `stepUp.ttlSeconds` (default 300). The token is bound to user and realm and
+  is useless without that user's session.
+
+## [0.16.0-rc.1] - 2026-10-01
+
+Passkeys (WebAuthn), and step-up re-authentication to protect adding one.
+
+**Release candidate**, published to the `next` dist-tag for a pilot on real
+devices; `latest` stays on 0.15.x. Install with
+`npm install @ambushsoftworks/nestjs-auth-graphql@next`.
+
+### ⚠ External configuration required
+
+Only if you enable passkeys. None of these is visible to a compiler or a test
+suite; each fails as an opaque error on the device. Details in the README,
+"Passkeys → Platform setup".
+
+- **Install the optional peer** `@simplewebauthn/server@^14`. It needs
+  **Node.js 20+**; the package itself still supports 18 without passkeys. Boot
+  fails with the install command if it is missing.
+- **Web:** serve the frontend over HTTPS on `passkey.rp.id` or a subdomain of it,
+  and list its exact origin in `passkey.rp.origins`.
+- **Android:** publish `https://<rp.id>/.well-known/assetlinks.json` with
+  `delegate_permission/common.get_login_creds` for the app, and add
+  `android:apk-key-hash:<base64url SHA-256 of the signing certificate>` to
+  `passkey.rp.origins`. With Play App Signing, that is Google's app signing key.
+- **iOS:** publish `https://<rp.id>/.well-known/apple-app-site-association` with
+  the app under `webcredentials.apps`, and add `webcredentials:<rp.id>` to the
+  app's Associated Domains entitlement.
+- **Database:** tables for passkey credentials and challenges (reference Prisma
+  schema in the README), and, if your verification repository stores the type
+  in a database enum, the new value `step-up`.
+
+### Added
+
+- **Passkeys.** `PasskeyService` and `IPasskeyRepository`, enabled by
+  `passkeyRepositoryInstance` and `passkey.rp`:
+  ```
+  registrationOptions(userId, { stepUpToken })        -> { challengeId, options }
+  verifyRegistration(userId, { challengeId, responseJson, name? })
+  authenticationOptions()                             -> { challengeId, options }   // no username
+  verifyAuthentication({ challengeId, responseJson }) -> session
+  listPasskeys / renamePasskey / removePasskey
+  ```
+  Discoverable credentials (usernameless sign-in, browser autofill),
+  `userVerification` configurable and `'required'` by default, EdDSA / ES256 /
+  RS256. Sessions come from `issueAuthSession`, so account status, cookie auth,
+  realm claims and `SESSION_ISSUED` apply unchanged. Verification is by
+  `@simplewebauthn/server`, loaded only when passkeys are configured and kept
+  out of the published type declarations.
+- **What the package enforces on top of the library:** single-use challenges
+  bound to purpose, user and realm and consumed before anything is checked; the
+  realm on the stored credential; the `userHandle` (the library does not check
+  it); the signature counter, with a compare-and-set and a
+  `PASSKEY_COUNTER_REGRESSION` event; global uniqueness of credential ids
+  (`PasskeyCredentialExistsError`); refusing to remove an account's last way in.
+- **Step-up re-authentication.** `StepUpService` and `StepUpTokenService`: a
+  signed-in user re-authenticates with a password, a passkey or an emailed
+  6-digit code and receives a five-minute token bound to user and realm.
+  **Adding a passkey requires one**: a passkey survives a password change and
+  logout-all, so a stolen session must not be able to add one. Wrong passwords
+  count toward brute-force lockout. The token is signed with an HKDF-derived
+  key, so it never passes as an access token.
+- `BaseAuthResolver` methods: `performGetStepUpMethods`,
+  `performRequestStepUpEmailCode`, `performStepUpPasskeyOptions`,
+  `performReauthenticate`, `performPasskeyRegistrationOptions`,
+  `performVerifyPasskeyRegistration`, `performPasskeyAuthenticationOptions`,
+  `performVerifyPasskeyAuthentication`, `performListPasskeys`,
+  `performRenamePasskey`, `performRemovePasskey`. WebAuthn JSON crosses GraphQL
+  as a `String`.
+- Options `passkey` (`rp`, `userVerification`, timeouts, `rateLimit`,
+  `userDisplayName`) and `stepUp.ttlSeconds`, validated at boot.
+- Lifecycle hooks `onPasskeyRegistered` and `onPasskeyRemoved`, not awaited.
+  Wire the first to a notification email.
+- Security events `PASSKEY_REGISTERED`, `PASSKEY_REGISTRATION_FAILURE`,
+  `PASSKEY_LOGIN_SUCCESS`, `PASSKEY_LOGIN_FAILURE`, `PASSKEY_COUNTER_REGRESSION`,
+  `PASSKEY_RENAMED`, `PASSKEY_REMOVED`, `STEP_UP_SUCCESS`, `STEP_UP_FAILURE`.
+- Exceptions `StepUpRequiredException` (`STEP_UP_REQUIRED`),
+  `StepUpUnavailableException` (`STEP_UP_UNAVAILABLE`), `AuthRateLimitException`
+  (`RATE_LIMIT_EXCEEDED`), as `GraphQLError`s so the code reaches clients.
+- `IEmailService.sendStepUpCodeEmail` and
+  `IEmailTemplateRenderer.renderStepUpCodeEmail`, both optional; implemented by
+  `ConfigurableEmailService` and `DefaultEmailTemplateRenderer`.
+- `VerificationType.STEP_UP`, and `generateCodeForUserId` /
+  `validateCodeForUserId` accept `'step-up'`.
+- `AuthService.requireActiveUser` and `AuthService.verifyPasswordForStepUp`.
+- `InMemoryPasskeyRepository`, for tests and a single instance.
+
+### Changed
+
+- `RepositoryVerificationType` includes `VerificationType.STEP_UP`. An adapter
+  with an exhaustive `switch` over it needs the new case.
+- `BaseAuthResolver` gains the protected properties `authPasskeys` and
+  `authStepUp`, injected by property so its constructor is unchanged. A
+  subclass that declares members with those names must rename them.
+
+### Fixed
+
+- The 0.14.0 notes and code comments said WebAuthn could be added as a second
+  `IBiometricVerifier` "without reshaping the port". It could not: a passkey
+  needs authenticator data and a user handle, a counter write, a registration
+  ceremony and challenges issued before any credential is known. Passkeys have
+  their own port, and the comments now say so.
+
 ## [0.15.1] - 2026-10-01
 
 ### Fixed

package/README.md

@@ -19,6 +19,8 @@ Production-grade authentication module for NestJS GraphQL + REST APIs. JWT, cook
   - [Phone \& SMS Verification](#phone--sms-verification)
   - [OAuth](#oauth)
   - [Biometric Authentication](#biometric-authentication)
+  - [Passkeys](#passkeys)
+  - [Step-Up Re-authentication](#step-up-re-authentication)
   - [Brute Force Protection](#brute-force-protection)
   - [Password Reset](#password-reset)
   - [Password Policy](#password-policy)
@@ -38,6 +40,8 @@ Production-grade authentication module for NestJS GraphQL + REST APIs. JWT, cook
   - [Composable Email](#composable-email-email)
   - [Verification Options](#verification-options-verification)
   - [Biometric Options (`biometric`)](#biometric-options-biometric)
+  - [Passkey Options (`passkey`)](#passkey-options-passkey)
+  - [Step-Up Options (`stepUp`)](#step-up-options-stepup)
   - [SendGrid Options (`sendgrid`)](#sendgrid-options-sendgrid)
   - [Twilio Options (`twilio`)](#twilio-options-twilio)
   - [Optional Instance Options](#optional-instance-options)
@@ -79,6 +83,8 @@ npm install @nestjs/common @nestjs/core @nestjs/graphql @nestjs/jwt @nestjs/pass
 
 `resend` is an optional peer dependency -- install it only if using the Resend email sender.
 
+`@simplewebauthn/server` (^14, Node.js 20+) is an optional peer dependency -- install it only if using [passkeys](#passkeys). Boot fails with the install command if passkeys are configured without it.
+
 Supports NestJS 10 and NestJS 11. CI runs the unit and end-to-end suites on both: NestJS 10 with `@nestjs/graphql` 12, Express 4 and Apollo Server 4, and NestJS 11 with `@nestjs/graphql` 13, Express 5 and Apollo Server 5.
 
 ## Quick Start
@@ -266,6 +272,22 @@ When cookie auth is enabled, pass the GraphQL `context` so tokens are set as Htt
 | `performResetPassword(input, context?)` | Reset password |
 | `performChangePassword(userId, current, new)` | Change password |
 
+**Passkeys and step-up** (see [Passkeys](#passkeys)):
+
+| Method | Purpose |
+|--------|---------|
+| `performGetStepUpMethods(user, context?)` | Which re-authentication methods this account has |
+| `performRequestStepUpEmailCode(user, context?)` | Email a 6-digit re-authentication code |
+| `performStepUpPasskeyOptions(user, context?)` | Options for re-authenticating with a passkey |
+| `performReauthenticate(user, input, context?)` | Prove identity again; returns a step-up token |
+| `performPasskeyRegistrationOptions(user, input, context?)` | Options for adding a passkey (needs a step-up token) |
+| `performVerifyPasskeyRegistration(user, input, context?)` | Store the new passkey |
+| `performPasskeyAuthenticationOptions(context?)` | Options for signing in (public) |
+| `performVerifyPasskeyAuthentication(input, context?)` | Sign in; same response as `performLogin` |
+| `performListPasskeys(user, context?)` | The user's passkeys |
+| `performRenamePasskey(user, input, context?)` | Rename one |
+| `performRemovePasskey(user, input, context?)` | Remove one (refused for the last way in) |
+
 **Other:**
 
 | Method | Purpose |
@@ -929,7 +951,7 @@ Treat this as *possession of a device-bound key that the client promises to
 gate*. It is a good second factor and a good convenience login. Before making it
 the sole factor for something sensitive, be clear that you are trusting the app,
 not the biometric. WebAuthn's `userVerification` flag is what actually attests to
-user verification, and is not this.
+user verification, and is not this: for that, use [passkeys](#passkeys).
 
 #### The flow
 
@@ -1012,6 +1034,340 @@ same answer.
 biometric services are not registered at all, rather than silently accepting
 enrolments that can never authenticate.
 
+### Passkeys
+
+WebAuthn passkeys (since 0.16.0): registration for a signed-in user, then
+sign-in with no username at all. Enabled by `passkeyRepositoryInstance` plus
+`passkey.rp`, and needs the optional peer `@simplewebauthn/server` (^14,
+Node.js 20+).
+
+```typescript
+passkeyRepositoryInstance: myPasskeyRepo,       // enables the capability
+passkey: {
+  rp: {
+    id: 'example.com',                           // the domain passkeys are bound to
+    name: 'Example',
+    origins: [
+      'https://app.example.com',
+      'android:apk-key-hash:<base64url SHA-256 of your signing certificate>',
+    ],
+  },
+  // userVerification: 'required',               // default; see below
+},
+```
+
+#### What a passkey sign-in proves
+
+With `userVerification: 'required'` (the default): the user unlocked an
+authenticator **bound to this domain** that holds the registered key. Unlike
+the [biometric device key](#biometric-authentication), the authenticator itself
+attests that it verified the user, and a lookalike domain cannot use the
+credential. It does not prove *which* person unlocked the device, and a synced
+passkey is only as safe as the iCloud or Google account it syncs through.
+
+**`'required'` adds no prompt for users.** On phones and laptops the Face ID,
+fingerprint or device PIN prompt *is* the passkey prompt, once per sign-in;
+sessions then continue through refresh tokens as usual. What `'required'`
+changes is that the server refuses an authenticator reporting that it did not
+verify the user, which in practice means a presence-only hardware key.
+`'preferred'` and `'discouraged'` accept those, and give up that guarantee.
+
+#### The flow
+
+```
+Add a passkey (signed in)
+  performReauthenticate({ password })            -> { stepUpToken }        (see Step-Up)
+  performPasskeyRegistrationOptions({ stepUpToken }) -> { challengeId, optionsJson }
+  client: navigator.credentials.create(...)
+  performVerifyPasskeyRegistration({ challengeId, responseJson, name? })
+
+Sign in (signed out)
+  performPasskeyAuthenticationOptions()          -> { challengeId, optionsJson }
+  client: navigator.credentials.get(...)
+  performVerifyPasskeyAuthentication({ challengeId, responseJson }) -> AuthResponse
+```
+
+WebAuthn JSON crosses GraphQL as a `String`: send `optionsJson` to the platform
+API unchanged, and send back `JSON.stringify` of what it returns. In a browser:
+
+```typescript
+const { challengeId, optionsJson } = await passkeyAuthenticationOptions();
+const credential = await navigator.credentials.get({
+  publicKey: PublicKeyCredential.parseRequestOptionsFromJSON(JSON.parse(optionsJson)),
+});
+await passkeyLogin({ challengeId, responseJson: JSON.stringify(credential.toJSON()) });
+```
+
+(`@simplewebauthn/browser`'s `startRegistration({ optionsJSON })` /
+`startAuthentication({ optionsJSON })` do the same on browsers without the
+`parse…FromJSON` helpers.) The sign-in options also serve browser autofill:
+call `navigator.credentials.get` with `mediation: 'conditional'`, and fetch
+fresh options when they expire (120 s by default). On Flutter, use a plugin that
+exchanges WebAuthn JSON with Android Credential Manager and iOS
+`ASAuthorization`, and pass the same two strings through.
+
+A consumer resolver, in the same shape as every other operation:
+
+```typescript
+@ObjectType() class PasskeyOptions { @Field() challengeId!: string; @Field() optionsJson!: string; }
+@ObjectType() class Passkey {
+  @Field() credentialId!: string; @Field() name!: string;
+  @Field() deviceType!: string; @Field() backedUp!: boolean;
+  @Field() createdAt!: Date; @Field({ nullable: true }) lastUsedAt?: Date;
+}
+@ObjectType() class StepUpToken { @Field() stepUpToken!: string; @Field() expiresAt!: Date; }
+@InputType() class ReauthenticateInput {
+  @Field({ nullable: true }) password?: string;
+  @Field({ nullable: true }) emailCode?: string;
+  @Field({ nullable: true }) passkeyChallengeId?: string;
+  @Field({ nullable: true }) @MaxLength(16384) passkeyResponseJson?: string;
+}
+@InputType() class PasskeyRegistrationOptionsInput { @Field() stepUpToken!: string; }
+@InputType() class VerifyPasskeyInput {
+  @Field() challengeId!: string;
+  @Field() @MaxLength(16384) responseJson!: string;
+  @Field({ nullable: true }) @MaxLength(64) name?: string;
+}
+
+@Resolver()
+export class AppAuthResolver extends BaseAuthResolver<User> {
+  @Mutation(() => StepUpToken) @UseGuards(JwtAuthGuard)
+  reauthenticate(@Args('input') input: ReauthenticateInput, @CurrentUser() user: User, @Context() ctx: any) {
+    return this.performReauthenticate(user, input, ctx);
+  }
+
+  @Mutation(() => PasskeyOptions) @UseGuards(JwtAuthGuard)
+  passkeyRegistrationOptions(@Args('input') input: PasskeyRegistrationOptionsInput, @CurrentUser() user: User, @Context() ctx: any) {
+    return this.performPasskeyRegistrationOptions(user, input, ctx);
+  }
+
+  @Mutation(() => Passkey) @UseGuards(JwtAuthGuard)
+  verifyPasskeyRegistration(@Args('input') input: VerifyPasskeyInput, @CurrentUser() user: User, @Context() ctx: any) {
+    return this.performVerifyPasskeyRegistration(user, input, ctx);
+  }
+
+  @Mutation(() => PasskeyOptions)
+  passkeyAuthenticationOptions(@Context() ctx: any) {
+    return this.performPasskeyAuthenticationOptions(ctx);
+  }
+
+  @Mutation(() => AuthResponse)
+  passkeyLogin(@Args('input') input: VerifyPasskeyInput, @Context() ctx: any) {
+    return this.performVerifyPasskeyAuthentication(input, ctx) as Promise<AuthResponse>;
+  }
+}
+```
+
+`PasskeyService` (exported) has the same operations if you need them outside a
+resolver.
+
+#### What the package guarantees
+
+| | |
+|---|---|
+| Phishing | Origin and rpId are verified against `passkey.rp`; an assertion made for another site fails |
+| Replay | Every challenge is single use, consumed atomically **before** anything is checked, and burned by a failed attempt. It carries its purpose, user and realm, so a sign-in challenge cannot be spent on registration or step-up |
+| Adding a passkey | Needs a [step-up token](#step-up-re-authentication). A passkey survives a password change and logout-all, so a stolen session must not be able to add one |
+| Realms | A passkey signs in only to the realm it was registered in, checked on the stored record whatever the repository does |
+| User handle | Must match the stored one on sign-in (the library does not check it) |
+| Cloned authenticators | A counting authenticator's counter must increase, enforced by the package with a compare-and-set; a regression is refused and logged as `PASSKEY_COUNTER_REGRESSION`. Synced passkeys always report 0, which is accepted |
+| Account status | Sessions come from `issueAuthSession`, so a suspended user is refused after a valid assertion, with `ACCOUNT_INACTIVE` rather than the generic failure |
+| Enumeration | Sign-in options take no input; every sign-in failure is the same `PASSKEY_AUTHENTICATION_FAILED` (401) |
+| Duplicates | A credential id already registered to anyone is refused with `PASSKEY_ALREADY_REGISTERED` (409), leaving the existing one untouched |
+| Last way in | Removing the only passkey of an account with no password and no social identity is refused with `CANNOT_REMOVE_LAST_AUTH_METHOD` (409) |
+| Owner notified | The package emails the owner when a passkey is added or removed (see [Notification emails](#notification-emails)) |
+| Rate limiting | Options are limited per user (registration, step-up) and per IP (sign-in); each verification consumes a challenge, so it is bounded by them |
+
+#### Platform setup
+
+None of this is visible to a compiler or a test suite; each item fails as an
+opaque error on the device.
+
+| Platform | Needs |
+|---|---|
+| Web | The frontend on HTTPS, on a host equal to `rp.id` or under it, listed exactly in `rp.origins` (scheme, host, port; no path, no trailing slash) |
+| Android | `https://<rp.id>/.well-known/assetlinks.json` granting `delegate_permission/common.get_login_creds` to your package name and SHA-256 certificate fingerprint, **and** `android:apk-key-hash:<hash>` in `rp.origins` |
+| iOS | `https://<rp.id>/.well-known/apple-app-site-association` listing your app under `webcredentials.apps`, and `webcredentials:<rp.id>` in the app's Associated Domains entitlement. iOS reports the web origin `https://<rp.id>`, which must be in `rp.origins` |
+
+The Android origin is the **base64url** SHA-256 of the signing certificate,
+not the colon-separated hex `keytool` prints. Convert it:
+
+```bash
+echo 'AB:CD:...:EF' | tr -d ':' | xxd -r -p | base64 | tr '+/' '-_' | tr -d '='
+```
+
+With Play App Signing, use the fingerprint of Google's app signing key (Play
+Console → App integrity), not your upload key. Boot refuses an Android origin
+that is not 43 base64url characters.
+
+**Several brands, one API:** every `rp` field can be a resolver taking the
+request's realm, e.g. `id: (realm) => brands[realm].domain`. Resolved values are
+checked per call, since boot cannot know every realm.
+
+#### Implementing `IPasskeyRepository`
+
+Two methods must be one conditional statement each, never a read followed by a
+write:
+
+```typescript
+async consumeChallenge(challengeId: string) {
+  const { count } = await prisma.passkeyChallenge.updateMany({
+    where: { id: challengeId, used: false, expiresAt: { gt: new Date() } },
+    data: { used: true, usedAt: new Date() },
+  });
+  if (count !== 1) return null;
+  return this.loadChallenge(challengeId);
+}
+
+async updateCounter({ credentialId, expectedCounter, newCounter, backedUp, lastUsedAt }) {
+  const { count } = await prisma.passkeyCredential.updateMany({
+    where: { credentialId, counter: expectedCounter },
+    data: { counter: newCounter, backedUp, lastUsedAt },
+  });
+  return count === 1;
+}
+```
+
+And `createCredential` must throw `PasskeyCredentialExistsError` on a duplicate
+`credentialId` **for any user**, from a unique constraint (map Prisma's
+`P2002`). A reference schema:
+
+```prisma
+model PasskeyCredential {
+  credentialId String    @id              // base64url, unique across all users
+  userId       String
+  realm        String?                    // required when realms are enabled
+  publicKey    String                     // base64url COSE key
+  counter      BigInt    @default(0)      // uint32 on the wire; Int is too small
+  userHandle   String
+  transports   String[]
+  deviceType   String
+  backedUp     Boolean
+  aaguid       String?
+  name         String
+  createdAt    DateTime  @default(now())
+  lastUsedAt   DateTime?
+  isActive     Boolean   @default(true)
+  metadata     Json?
+  user         User      @relation(fields: [userId], references: [id], onDelete: Cascade)
+  @@index([userId, realm])
+}
+
+model PasskeyChallenge {
+  id         String    @id @default(uuid())
+  challenge  String
+  purpose    String                       // registration | authentication | step-up
+  userId     String?                      // not a foreign key
+  realm      String?
+  userHandle String?                      // registration only
+  expiresAt  DateTime
+  used       Boolean   @default(false)
+  usedAt     DateTime?
+  @@index([expiresAt])
+}
+```
+
+`getCredential` returns deactivated credentials too; the package decides.
+
+**Check your adapter against the contract** with the helper the package's own
+tests use, against a real database:
+
+```typescript
+import { assertPasskeyRepositoryContract } from '@ambushsoftworks/nestjs-auth-graphql/testing';
+
+it('meets the passkey repository contract', async () => {
+  await assertPasskeyRepositoryContract(() => new PrismaPasskeyRepository(prisma));
+});
+```
+
+It resolves when the adapter is correct and otherwise rejects naming the rule
+broken: concurrent claims of one challenge, a counter column too small for a
+uint32, an unmapped duplicate, a dropped realm, hidden deactivated
+credentials, expiry left to a TTL. Framework-agnostic.
+`InMemoryPasskeyRepository` is exported for tests and single-instance
+development.
+
+**Driving real ceremonies in your own tests:** `SoftwareAuthenticator`, from
+the same `/testing` entry, produces real WebAuthn responses (CBOR, COSE keys,
+signatures) from the options your API returns, with options to forge any field:
+
+```typescript
+import { SoftwareAuthenticator } from '@ambushsoftworks/nestjs-auth-graphql/testing';
+
+const device = new SoftwareAuthenticator();
+const response = device.create(JSON.parse(optionsJson), { origin: 'https://app.example.com' });
+// ... later, for sign-in:
+const assertion = device.get(JSON.parse(signInOptionsJson), { origin: 'https://app.example.com' });
+```
+
+#### Notification emails
+
+The package emails the account owner when a passkey is **added** and when one
+is **removed**, through `IEmailService.sendPasskeyAddedEmail` /
+`sendPasskeyRemovedEmail`. The "added" email matters most: a passkey survives a
+password change and signing out everywhere, so it is how an owner learns of one
+they did not add.
+
+| Your email setup | What happens |
+|---|---|
+| `email: {...}` (default renderer) | Sent, with the package's templates |
+| `ConfigurableEmailService` with your own renderer | Sent when your renderer implements `renderPasskeyAddedEmail` / `renderPasskeyRemovedEmail`; otherwise nothing is sent |
+| Your own `IEmailService` | Sent when it implements `sendPasskeyAddedEmail(email, passkeyName, addedAt)` / `sendPasskeyRemovedEmail(email, passkeyName, removedAt)`; otherwise nothing is sent |
+
+`passkeyName` is chosen by the user: **escape it** in any HTML you render. The
+default templates do.
+
+To send your own instead, or none, turn either off:
+
+```typescript
+passkey: {
+  rp: { /* ... */ },
+  emailNotifications: { added: true, removed: false },   // both default to true
+},
+```
+
+**Don't also send them from `onPasskeyRegistered` / `onPasskeyRemoved`**, or
+owners get two. The hooks still fire, for anything else you want to do.
+
+### Step-Up Re-authentication
+
+A signed-in user proves again who they are and receives a short-lived **step-up
+token** (5 minutes by default) for a protected action. Adding a passkey requires
+one.
+
+| Proof | Available when |
+|---|---|
+| `{ password }` | The account has a password. **Failures count toward [lockout](#brute-force-protection)**, so a stolen session cannot guess it freely |
+| `{ passkeyChallengeId, passkeyResponseJson }` | Passkeys are configured and the user has one (options from `performStepUpPasskeyOptions`) |
+| `{ emailCode }` | `verificationRepositoryInstance` is set and the email service implements `sendStepUpCodeEmail` (`ConfigurableEmailService` does). Always a 6-digit code, never a link; one email a minute |
+
+`performGetStepUpMethods` says which apply, so the client shows only working
+buttons.
+
+| Code | Status | When |
+|---|---|---|
+| `STEP_UP_FAILED` | 403 | The proof was wrong: password, code or passkey |
+| `STEP_UP_REQUIRED` | 403 | An action needs a token and got none, or an invalid one |
+| `STEP_UP_UNAVAILABLE` | 403 | The account has no such method |
+
+**A failed proof is deliberately not `UNAUTHENTICATED`.** Clients read that as
+an expired session and refresh-and-retry: the wrong password would count twice
+toward lockout, and a passkey proof's retry always fails because its challenge
+is already spent. Don't map `STEP_UP_FAILED` to a token refresh.
+
+The token is signed with a key derived from `jwtSecret` (HKDF), never with
+`jwtSecret` itself, so it can never pass as an access token. It is bound to the
+user and realm.
+
+**A token is reusable until it expires, not single-use.** One re-authentication
+can cover adding a passkey and then another protected action within the five
+minutes. That is deliberate: the token is useless without the same user's
+session in the same realm, and single use would need storage for little gain
+over a short expiry. Shorten `stepUp.ttlSeconds` if you want a tighter window.
+
+**Email codes use a new verification type, `step-up`.** If your verification
+repository stores the type in a database enum, add the value.
+
 ### Brute Force Protection
 
 Provide a `bruteForceRepositoryInstance` and the module tracks failed login attempts and temporarily locks accounts. Without one, `NoOpBruteForceRepository` is used and no account is ever locked; there is no flag to set. The lockout policy (attempt thresholds, lockout duration) is determined by your `IBruteForceRepository` implementation.
@@ -1228,10 +1584,12 @@ lifecycleHooksInstance: {
   onAccountLocked(userId, email, ip, lockSeconds, realm) {
     /* send account-locked notification email, alert security tooling */
   },
+  async onPasskeyRegistered(user, passkey, realm) { /* analytics; the package emails the owner */ },
+  async onPasskeyRemoved(user, passkey, realm) { /* likewise */ },
 }
 ```
 
-All hooks are optional. Async hooks are awaited but failures are logged and do not block the auth operation. `onAuthFailure` and `onAccountLocked` are synchronous (fire-and-forget) — both are security signals and the underlying state (lock recorded, attempt logged) is already persisted by the time the hook fires, so hook failures must not roll it back.
+All hooks are optional. Async hooks are awaited but failures are logged and do not block the auth operation; the passkey hooks are not awaited. The package sends the passkey notification emails itself (see [Notification emails](#notification-emails)); don't send them again from these hooks. `onAuthFailure` and `onAccountLocked` are synchronous (fire-and-forget) — both are security signals and the underlying state (lock recorded, attempt logged) is already persisted by the time the hook fires, so hook failures must not roll it back.
 
 `onAccountLocked` fires from `BruteForceProtectionService.recordFailedAttempt` on the transition from "not locked" → "locked". Subsequent failed attempts while the account remains locked do **not** re-fire (use `onAuthFailure` for per-attempt signal). Wire it to send the account-locked email yourself — the package no longer ships a `sendAccountLockedEmail` method on `IEmailService`; notification surface area beyond verification, password-reset, and password-changed is consumer-owned via this hook.
 
@@ -1460,6 +1818,29 @@ without it is reported at boot, not refused.
 | `challengeExpirySeconds` | `number` | `60` | Short on purpose: it bounds replay |
 | `challengeRateLimit` | `{ maxAttempts, windowMs }` | `5 / 60s` | Per credential. **Requires `rateLimiterInstance`** — the same guardrail as `bruteForce.ipRateLimit`, because per-replica counters would make the limit silently looser. A per-IP limit at ten times this bound also applies when you pass `ipAddress` |
 
+### Passkey Options (`passkey`)
+
+Read only when `passkeyRepositoryInstance` is provided; without it this block is
+reported at boot as ignored. With it, `rp` is required.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `rp.id` | `string \| (realm?) => string` | — | The registrable domain passkeys are bound to. No scheme, port or path; not an IP |
+| `rp.name` | `string \| (realm?) => string` | — | Shown by some authenticators |
+| `rp.origins` | `string[] \| (realm?) => string[]` | — | Exact origins accepted, each `rp.id` or a subdomain of it, https except localhost; Android `android:apk-key-hash:` origins |
+| `userVerification` | `'required' \| 'preferred' \| 'discouraged'` | `'required'` | See [What a passkey sign-in proves](#what-a-passkey-sign-in-proves) |
+| `registrationTimeoutSeconds` | `number` | `300` | Registration ceremony lifetime |
+| `authenticationTimeoutSeconds` | `number` | `120` | Sign-in and step-up ceremony lifetime |
+| `rateLimit` | `{ maxAttempts, windowMs }` | `10 / 60s` | Options per user (registration, step-up) and per IP (sign-in). **Requires `rateLimiterInstance`** when set |
+| `userDisplayName` | `(user) => string` | the email | What authenticators show for the account |
+| `emailNotifications` | `{ added?: boolean, removed?: boolean }` | both `true` | Email the owner when a passkey is added / removed. See [Notification emails](#notification-emails) |
+
+### Step-Up Options (`stepUp`)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `ttlSeconds` | `number` | `300` | Step-up token lifetime, 1 to 3600 |
+
 ### Optional Instance Options
 
 | Option | Interface | Fallback |
@@ -1469,7 +1850,8 @@ without it is reported at boot, not refused.
 | `lifecycleHooksInstance` | `IAuthLifecycleHooks` | `{}` (no-op) |
 | `verificationRepositoryInstance` | `IVerificationRepository` | `NoOpVerificationRepository` |
 | `bruteForceRepositoryInstance` | `IBruteForceRepository` | `NoOpBruteForceRepository` |
-| `biometricRepositoryInstance` | `IBiometricRepository` | `NoOpBiometricRepository` |
+| `biometricRepositoryInstance` | `IBiometricRepository` | none: biometrics disabled |
+| `passkeyRepositoryInstance` | `IPasskeyRepository` | none: passkeys disabled |
 | `authLoggerInstance` | `IAuthLogger` | `ConsoleAuthLogger` |
 | `tenantRepositoryInstance` | `ITenantRepository` | `null` |
 | `tenantExtractorInstance` | `ITenantExtractor` | `null` |

package/dist/auth.module.d.ts

@@ -9,6 +9,8 @@ import { IRefreshTokenRepository } from './interfaces/refresh-token-repository.i
 import { IVerificationRepository } from './interfaces/verification-repository.interface';
 import { IBruteForceRepository } from './interfaces/brute-force-repository.interface';
 import { IBiometricRepository } from './interfaces/biometric-repository.interface';
+import { IPasskeyRepository } from './interfaces/passkey-repository.interface';
+import { PasskeyRelyingPartyConfig } from './utils/passkey-rp';
 import { IAuthLogger } from './interfaces/auth-logger.interface';
 import { ITenantRepository } from './interfaces/tenant-repository.interface';
 import { ITenantExtractor } from './interfaces/tenant-extractor.interface';
@@ -32,6 +34,7 @@ export interface AuthModuleOptions {
     verificationRepositoryInstance?: IVerificationRepository;
     bruteForceRepositoryInstance?: IBruteForceRepository;
     biometricRepositoryInstance?: IBiometricRepository;
+    passkeyRepositoryInstance?: IPasskeyRepository;
     authLoggerInstance?: IAuthLogger;
     refreshTokenSecret?: string;
     verificationCodeSecret?: string;
@@ -130,6 +133,24 @@ export interface AuthModuleOptions {
             windowMs: number;
         };
     };
+    passkey?: {
+        rp: PasskeyRelyingPartyConfig;
+        userVerification?: 'required' | 'preferred' | 'discouraged';
+        registrationTimeoutSeconds?: number;
+        authenticationTimeoutSeconds?: number;
+        rateLimit?: {
+            maxAttempts: number;
+            windowMs: number;
+        };
+        userDisplayName?: (user: IAuthUser) => string;
+        emailNotifications?: {
+            added?: boolean;
+            removed?: boolean;
+        };
+    };
+    stepUp?: {
+        ttlSeconds?: number;
+    };
     verification?: {
         tokenLength?: number;
         tokenExpiresInMinutes?: number;