@ambushsoftworks/nestjs-auth-graphql 0.11.0 → 0.14.0

package/README.md

@@ -13,10 +13,14 @@ Production-grade authentication module for NestJS GraphQL + REST APIs. JWT, cook
   - [Multi-Tenancy](#multi-tenancy)
   - [Realm-Based Identity Isolation](#realm-based-identity-isolation)
   - [API Key Authentication](#api-key-authentication)
+  - [External JWTs](#external-jwts)
   - [Email System](#email-system)
   - [Verification Modes](#verification-modes)
+  - [Phone \& SMS Verification](#phone--sms-verification)
   - [OAuth](#oauth)
+  - [Biometric Authentication](#biometric-authentication)
   - [Brute Force Protection](#brute-force-protection)
+  - [Password Reset](#password-reset)
   - [Password Policy](#password-policy)
   - [Lifecycle Hooks](#lifecycle-hooks)
   - [Account Status](#account-status)
@@ -33,12 +37,17 @@ Production-grade authentication module for NestJS GraphQL + REST APIs. JWT, cook
   - [CSRF Options](#csrf-options-csrf)
   - [Composable Email](#composable-email-email)
   - [Verification Options](#verification-options-verification)
+  - [Biometric Options (`biometric`)](#biometric-options-biometric)
+  - [SendGrid Options (`sendgrid`)](#sendgrid-options-sendgrid)
+  - [Twilio Options (`twilio`)](#twilio-options-twilio)
   - [Optional Instance Options](#optional-instance-options)
 - [Decorators](#decorators)
 - [Guards](#guards)
   - [GraphQL Subscriptions](#graphql-subscriptions)
 - [Utilities](#utilities)
 - [Security Features](#security-features)
+- [Upgrading from 0.9.x](#upgrading-from-09x)
+- [Migrating to v0.12.0](#migrating-to-v0120)
 - [Migrating to v0.11.0](#migrating-to-v0110)
 - [Migrating to v0.10.0](#migrating-to-v0100)
 - [Migrating to v0.9.0](#migrating-to-v090)
@@ -559,6 +568,73 @@ The `ApiKeyStrategy` hashes the bearer token with SHA-256 and calls `findByKeyHa
 
 Before 0.10.0 the API key strategy rejected an unknown bearer token itself, which stopped the chain: `['api-key', 'jwt']` rejected every JWT.
 
+#### Key options
+
+| Option | Example | Effect |
+|--------|---------|--------|
+| `apiKey.headerName` | `'X-API-Key'` | A header carrying the raw key, read before `Authorization: Bearer`, which keeps working. `CsrfGuard` treats a request carrying it as credentialed, as it already does for `Authorization` |
+| `apiKey.prefix` | `'ait_'` | The prefix every key you issue starts with. See below |
+
+Both are read only with `apiKeyRepositoryInstance`, and `apiKey.prefix` without it warns at boot. `headerName` must be a header name other than `Authorization`, and `prefix` must not be empty -- an empty one matches every token, so every unknown bearer token, JWTs included, would be refused. Boot fails on either.
+
+**A prefix makes an unknown key unambiguous.** Without one, the strategy cannot tell a mistyped key from a JWT:
+
+| Token | Without `prefix` | With `prefix` |
+|-------|------------------|---------------|
+| Does not start with the prefix (a JWT, say) | Looked up, then passed to the next strategy | Passed to the next strategy, with no lookup |
+| Starts with it, matches no key | Passed to the next strategy; a single-strategy guard answers a generic 401 | `401 Invalid API key` -- it cannot be a JWT, so no other strategy tries it |
+| Matches a key | Authenticated, unless the key is inactive or expired | The same |
+
+#### Expiry, scopes and last use
+
+`IApiKeyAccount` carries optional `scopes?: string[]` and `expiresAt?: Date | null`, and `IApiKeyRepository` may implement `touchLastUsed?(id)`. Existing repositories keep working.
+
+- **Expiry.** A key whose `expiresAt` has passed is refused with `401 API key has expired`, and no other strategy tries it. A key without one never expires.
+- **Scopes.** Mark the operation and register `ScopeGuard` after your authentication guard:
+
+  ```typescript
+  @Get('tickets')
+  @UseGuards(createAuthGuard(['api-key', 'jwt']), ScopeGuard)
+  @RequireScopes('tickets:read')
+  listTickets() { /* ... */ }
+  ```
+
+  A key must hold every listed scope. One that does not gets 403 with `{ message: 'Insufficient scope', code: 'INSUFFICIENT_SCOPE', requiredScopes, statusCode: 403 }`, naming what the operation requires. A key with no `scopes` holds none. **Signed-in people pass**: scopes restrict keys, while a person's access is `PermissionGuard`'s job. With no authenticated principal at all, `ScopeGuard` answers 401 -- which is why it goes after the auth guard.
+- **Last use.** `touchLastUsed(id)` is called once per successful match, and only then -- never for a key that is refused. It is not awaited: a failure is logged and never fails the request.
+
+### External JWTs
+
+`createExternalJwtStrategy(name, options)` verifies tokens another system signs -- each app's backend signing for its own users, say. It registers a separate Passport strategy under `name`, with no realm check and no user lookup, so the package's own `jwt` strategy is untouched.
+
+```typescript
+export const CustomerJwtStrategy = createExternalJwtStrategy('customer-jwt', {
+  inject: [AppSecretsService],           // optional; pass a plain options object instead
+  useFactory: (secrets: AppSecretsService) => ({
+    algorithms: ['HS256'],               // required
+    audience: 'ambush-desk',
+    secretProvider: (kid) => secrets.findSecret(kid),
+    mapClaims: (claims) => ({ id: claims.sub, app: claims.app, segments: claims.segments }),
+  }),
+});
+
+// providers: [CustomerJwtStrategy]
+// @UseGuards(createAuthGuard(['customer-jwt']))
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `secretProvider(kid, request)` | -- | The key that verifies a token: a shared secret for `HS*`, a PEM public key for `RS*`, `PS*` and `ES*`. May be async. `null` rejects the token; so does a throw, which is logged |
+| `algorithms` | -- | **Required.** The algorithms the issuer signs with |
+| `issuer`, `audience` | -- | Required `iss` / `aud`, when set |
+| `clockToleranceSec` | `0` | Clock skew allowed on `exp` and `nbf` |
+| `maxTokenBytes` | `8192` | A longer token is refused before anything parses it |
+| `mapClaims(payload)` | the payload | Builds `request.user`, arrays and custom claims intact. `null`, `undefined` or a throw rejects the token |
+| `jwtFromRequest(request)` | `Authorization: Bearer` | Where the token comes from |
+
+**Algorithms are pinned, one family at a time.** Boot fails with `InvalidAuthConfigException` for missing or empty `algorithms`, for `none`, for an algorithm jsonwebtoken does not know, and for HMAC (`HS*`) mixed with asymmetric algorithms -- the mix that lets a public key be used as an HMAC secret. `'jwt'` and `'api-key'` are refused as names, since Passport would replace the package's own strategy.
+
+**Every rejection fails softly**, so the strategy composes: `createAuthGuard(['customer-jwt', 'jwt'])` accepts either kind of token, in either order, and answers 401 when both fail.
+
 ### Email System
 
 The email system uses a composable architecture: a **sender** (transport) and a **template renderer** (HTML generation).
@@ -688,6 +764,40 @@ variable (deprecated — logged once). With neither, code-mode emails carry no
 link and nothing is logged: the code is in the body, so no link is needed. The
 code itself is never placed in a query string in either mode.
 
+#### One API, several brands: `baseUrl` per realm
+
+With [realms](#realm-based-identity-isolation) enabled, one deployment serves
+several frontends and a link must open on the site the user actually came from.
+`baseUrl` accepts a resolver as well as a string; it is called with the realm of
+the request the credential is being issued for:
+
+```typescript
+const SITES: Record<string, string> = {
+  'site-a': 'https://a.example.com',
+  'site-b': 'https://b.example.com',
+};
+
+verification: {
+  baseUrl: (realm?: string) => SITES[realm ?? ''] ?? 'https://www.example.com',
+},
+```
+
+It applies to both modes — the token link and the code page link — because both
+are built from the same resolved base. It is called once per link, so resolve
+from a map rather than a query, and it must be synchronous.
+
+**Boot validation is weaker for a resolver, by necessity.** A string is checked
+in full at startup. A resolver is only called once, with `undefined`, so the
+realm-less case is checked and a per-realm return value is not — there is no
+request at startup to supply a realm. What it returns for a specific realm is
+checked when the link is built, and the two modes differ exactly as they do
+elsewhere: token mode throws, because the link carries the only copy of the
+credential; code mode logs a warning and sends the email without a link,
+because the code is in the body.
+
+Returning a value for `realm === undefined` is required. A request exempted by
+`realm.skip`, or a single-realm deployment, has no realm.
+
 **Custom `IEmailService` implementations.** Both send methods receive the
 credential and its URL, and the mode determines which one is actionable:
 
@@ -702,6 +812,45 @@ link. `expiresInMinutes` reflects the mode's real expiry, so render it rather
 than hardcoding a duration. Both trailing parameters are optional, so existing
 implementations continue to compile.
 
+### Phone & SMS Verification
+
+An authenticated user adds a phone number, receives a 6-digit code by SMS, and
+confirms it. All five methods take the current user, so they sit behind your
+authentication guard — this is account management, not a sign-in path.
+
+| Method | Purpose |
+|---|---|
+| `performSendPhoneVerification(input, user)` | Store the number and send a code |
+| `performVerifyPhone(input, user)` | Confirm the code, mark the number verified |
+| `performResendPhoneVerification(phoneNumber, user)` | Send again, subject to the 60-second cooldown |
+| `performRemovePhoneNumber(user)` | Clear the number and its verified state |
+| `performPhoneVerificationStatus(user)` | Whether a number is present and verified |
+
+Provide `smsServiceInstance` and `verificationRepositoryInstance`. `ISmsService`
+has a single method, so the seam is small:
+
+```typescript
+export class TwilioSmsService implements ISmsService {
+  async sendVerificationSms(phoneNumber: string, code: string): Promise<void> {
+    await this.client.messages.create({ to: phoneNumber, body: `Your code is ${code}` });
+  }
+}
+```
+
+Two things worth knowing:
+
+- **SMS is code-only.** `features.verificationMode: 'token'` governs email
+  verification and password reset. A phone always receives a 6-digit code,
+  because a link is not usable from a text message in the same way — so
+  `verification.baseUrl` is irrelevant here.
+- **Omitting `smsServiceInstance` does not fail loudly.** The package substitutes
+  a no-op that logs, so codes are generated and stored but never delivered.
+  Verification then only succeeds for someone reading your application logs.
+
+The number's realm is scoped like any other identity field: with realms enabled,
+`findByPhoneNumber` receives the realm, so the same number can exist once per
+realm.
+
 ### OAuth
 
 Google and Facebook OAuth with encrypted token storage (AES-256-GCM).
@@ -755,6 +904,110 @@ It sits beside `useFactory` because Nest fixes a module's controllers before asy
 
 With realms enabled, a request without a realm gets `400 Realm required` first. Before 0.10.0 the lockout, inactive-account, rate-limit and unconfigured-provider cases answered 500.
 
+### Biometric Authentication
+
+A device holds an ECDSA P-256 keypair, gated behind the OS biometric prompt. The
+server stores the public key and verifies a signature over a challenge it issued.
+
+```typescript
+biometricRepositoryInstance: myBiometricRepo,   // enables the capability
+biometric: {
+  challengeExpirySeconds: 60,                   // default
+  challengeRateLimit: { maxAttempts: 5, windowMs: 60_000 },  // needs rateLimiterInstance
+},
+```
+
+#### ⚠ What a successful authentication actually proves
+
+**It proves the client still holds the private key. It does not prove a biometric
+check happened.** Nothing in an ECDSA signature attests to that, and the server
+cannot distinguish a key held in a hardware enclave from one generated in
+software. Whether a fingerprint was scanned — or a PIN accepted instead, which
+most mobile biometric APIs allow by default — is the client's word.
+
+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.
+
+#### The flow
+
+```typescript
+// 1. Enrol, authenticated. The package generates the credential id — keep it
+//    on the device alongside the private key.
+const { credentialId } = await biometricAuth.enrolCredential({
+  userId: user.id,
+  publicKey,                  // PEM, SPKI
+  deviceName: 'iPhone 15',
+  metadata: { yourDeviceString: '...' },   // optional, opaque to the package
+});
+
+// 2. Request a challenge. No user id — the caller is usually signed out.
+const challenge = await biometricAuth.requestChallenge(credentialId, {
+  ipAddress: req.ip,
+});
+if (!challenge) { /* rate limited */ }
+
+// 3. The client signs `challenge.challenge` (base64) with the private key.
+
+// 4. Verify and receive a session.
+const session = await biometricAuth.authenticateWithBiometric(
+  { challengeId: challenge.challengeId, credentialId, signature },
+  { res, realm, ipAddress: req.ip },
+);
+```
+
+Also `listCredentials(userId)` for a device list and `removeCredential(userId,
+credentialId)` to deactivate one.
+
+#### What the package guarantees
+
+| | |
+|---|---|
+| Challenge | 32 random bytes, single use, 60s default |
+| Replay | A challenge is consumed **atomically** before anything is checked, so a retry loses the race — and a failed attempt still burns it |
+| Cross-credential | A challenge issued for one credential cannot be answered with another's key |
+| Algorithm | Pinned **per credential**. A credential enrolled as ES256 is only verified as ES256; no verifier for its algorithm means refusal, not a fallback |
+| Account status | The session comes from the same sink as every other login, so a suspended or soft-deleted user is refused **after** a valid signature |
+| Enumeration | Every biometric failure returns the same 401, and a challenge is issued even for a credential that does not exist |
+| Rate limiting | Per credential, and per IP so varying the credential id cannot evade it |
+
+#### Implementing `IBiometricRepository`
+
+One method has a contract you cannot satisfy with a read followed by a write:
+
+```typescript
+async consumeChallenge(challengeId: string) {
+  // Atomic: mark used and return it, only if it was unused and unexpired.
+  const { count } = await prisma.biometricChallenge.updateMany({
+    where: { id: challengeId, used: false, expiresAt: { gt: new Date() } },
+    data: { used: true, usedAt: new Date() },
+  });
+  if (count !== 1) return null;    // someone else claimed it, or it expired
+  return this.load(challengeId);
+}
+```
+
+Read-then-write lets two concurrent requests with one challenge both succeed,
+which is the replay single use exists to prevent.
+
+Two more things your schema needs to know:
+
+- **`credentialId` on a challenge is not a foreign key.** A challenge is stored
+  for credential ids that do not exist, so that the signed-out request cannot be
+  used to discover which credentials are enrolled.
+- **No uniqueness on `deviceName` or any device string.** It is a display label,
+  never matched on. Key rotation is enrol-new then deactivate-old.
+
+`getCredential` must return deactivated credentials rather than hiding them — the
+package decides, so that a deactivated credential and an unknown one produce the
+same answer.
+
+**There is no no-op fallback.** Omit `biometricRepositoryInstance` and the
+biometric services are not registered at all, rather than silently accepting
+enrolments that can never authenticate.
+
 ### 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.
@@ -859,6 +1112,78 @@ async changePassword(
 
 `issueAuthSession(userId, res?, realm?)` mints a new access + refresh pair, persists the refresh token, and (when `features.cookieAuth` is enabled and `res` is supplied) sets the auth cookies on the response. The caller is responsible for verifying the user's identity — `issueAuthSession` takes a `userId` and trusts it. Pair it only with flows that have already authenticated the user (`changePassword`, MFA enrollment completion, admin-impersonation reissue, etc.). Emits `SecurityEvent.SESSION_ISSUED`.
 
+### Password Reset
+
+A reset is two calls: `performRequestPasswordReset` sends a 6-digit code, and
+`performResetPassword` redeems it. `performChangePassword` is the separate,
+authenticated path for a signed-in user who knows their current password.
+
+```typescript
+@Mutation(() => PasswordResetResponse)
+requestPasswordReset(@Args('input') input: RequestPasswordResetInput, @Context() ctx: any) {
+  return this.performRequestPasswordReset(input, ctx);
+}
+
+@Mutation(() => PasswordResetResponse)
+resetPassword(@Args('input') input: ResetPasswordInput, @Context() ctx: any) {
+  return this.performResetPassword(input, ctx);
+}
+```
+
+It needs `verificationRepositoryInstance` to store the code and
+`emailServiceInstance` to deliver it. Without the first, codes are logged rather
+than stored and no reset can complete.
+
+#### What the package enforces for you
+
+None of this is configurable, and most of it is invisible until it bites:
+
+| | |
+|---|---|
+| Code | 6 digits, HMAC-SHA256 hashed at rest, never logged |
+| Expiry | 15 minutes |
+| Attempts | **3**, then the code is destroyed and a new one must be requested |
+| Per-user cooldown | 60 seconds, tracked on `passwordResetSentAt` |
+| Per-IP limit | 5 per hour, checked **before** the user lookup |
+| On success | **every refresh token for that user is revoked** — all devices are signed out |
+| Comparison | constant-time |
+
+The IP limit runs before the lookup deliberately: checking it afterwards would
+make a request for a non-existent address measurably faster than one for a real
+address, which is the enumeration leak the generic message exists to prevent.
+
+#### The response never tells you what happened
+
+`requestPasswordReset` returns the same success payload whether the address does
+not exist, belongs to a social-login account, or was actually sent a code. That
+is deliberate — the mutation is reachable unauthenticated, so any distinguishable
+result is an oracle for whether an address is registered.
+
+If you need to know, read your `IAuthLogger`. A skip is reported as
+`PASSWORD_RESET_REQUESTED` with `result: 'SKIPPED_SOCIAL_ONLY'` and the user ID.
+An operator tool that creates accounts and invites by reset should assert on that
+event, not on the mutation's return value.
+
+#### Accounts with no password
+
+An account is refused only if it has an actual social identity — `googleId`,
+`facebookId` or `appleId`. A password-less account with none of those, which is
+how an operator-provisioned account starts, receives a code and can redeem it.
+This is the documented "invite by password reset" flow.
+
+**This changed in 0.12.0.** Before then the test was `passwordHash == null`, so
+operator-created accounts were skipped silently and could never sign in. See
+[Migrating to v0.12.0](#migrating-to-v0120) for the consequence worth deciding
+on. The predicate is exported as `hasSocialIdentity(user)` if you want the same
+test in your own code.
+
+#### Token mode
+
+With `features.verificationMode: 'token'` the email carries a link rather than a
+code, and `performResetPassword` takes the token lifted from that link in place
+of the 6-digit code. Everything above still applies. See
+[Verification Modes](#verification-modes).
+
 ### Password Policy
 
 ```typescript
@@ -1020,6 +1345,8 @@ These sit beside `useFactory`, not in the object it returns.
 | `bruteForce.ipRateLimit` | `{ maxAttempts, windowMs }` | -- | IP rate-limit policy for `checkIpRateLimit`. When set, `rateLimiterInstance` MUST also be provided explicitly (boot fails with `InvalidAuthConfigException` otherwise). See [IP Rate Limiting](#ip-rate-limiting). |
 | `realm.skip` | `(path, request) => boolean` | -- | Requests that need no realm, such as health checks and webhooks. Read only with `realmExtractorInstance`. See [Realm-Based Identity Isolation](#realm-based-identity-isolation) |
 | `refreshGracePeriodSeconds` | `number` | `10` | How long a retried refresh gets the same token pair. `0` turns retries off. See [Refresh Retries](#refresh-retries) |
+| `apiKey.headerName` | `string` | -- | A header carrying the raw API key, e.g. `'X-API-Key'`, read before `Authorization`. See [API Key Authentication](#api-key-authentication) |
+| `apiKey.prefix` | `string` | -- | The prefix every API key you issue starts with, e.g. `'ait_'`. Makes an unknown key unambiguous. See [API Key Authentication](#api-key-authentication) |
 
 ### Feature Flags (`features`)
 
@@ -1094,7 +1421,40 @@ When `email` is provided, it takes precedence over `emailServiceInstance`.
 |--------|------|---------|-------------|
 | `tokenLength` | `number` | `64` | Token length in bytes (token mode) |
 | `tokenExpiresInMinutes` | `number` | `60` | Token expiration (token mode) |
-| `baseUrl` | `string` | -- | Absolute http(s) base URL for verification/reset links. **Required when `verificationMode` is `'token'`** (validated at boot); optional in code mode |
+| `baseUrl` | `string \| VerificationBaseUrlResolver` | — | Absolute http(s) base URL for verification/reset links, or a resolver called with the request's realm. **Required when `verificationMode` is `'token'`** (validated at boot); optional in code mode |
+
+### SendGrid Options (`sendgrid`)
+
+Read only by the bundled `SendGridEmailService`. A custom `IEmailService` ignores
+this block entirely.
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `apiKey` | `string` | yes | SendGrid API key |
+| `fromEmail` | `string` | yes | Verified sender address |
+| `fromName` | `string` | — | Display name on the From header |
+
+### Twilio Options (`twilio`)
+
+Read only by the bundled `TwilioSmsService`. A custom `ISmsService` ignores this
+block entirely.
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `accountSid` | `string` | yes | Twilio account SID |
+| `authToken` | `string` | yes | Twilio auth token |
+| `phoneNumber` | `string` | yes | Sending number, E.164 |
+
+### Biometric Options (`biometric`)
+
+Read only when `biometricRepositoryInstance` is provided. Passing this block
+without it is reported at boot, not refused.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `verifiers` | `IBiometricVerifier[]` | `[new Es256DeviceKeyVerifier()]` | One per credential algorithm. Two claiming the same algorithm is refused at boot — resolution would depend on array order |
+| `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` |
 
 ### Optional Instance Options
 
@@ -1126,6 +1486,7 @@ When `email` is provided, it takes precedence over `emailServiceInstance`.
 | `@PublicEndpoint()` | Method/Class | Skip authentication + tenant resolution (combines `@Public()` + `@SkipTenant()`) |
 | `@SkipTenant()` | Method/Class | Skip tenant resolution |
 | `@RequirePermissions('p1', 'p2')` | Method/Class | Require specific permissions |
+| `@RequireScopes('s1', 's2')` | Method/Class | Require API key scopes, enforced by `ScopeGuard`. People are unaffected. See [API Key Authentication](#api-key-authentication) |
 | `@CurrentUser()` | Parameter | Inject authenticated user |
 | `@CurrentTenant()` | Parameter | Inject resolved tenant context |
 | `@CurrentRealm()` | Parameter | Inject resolved realm from request context |
@@ -1139,6 +1500,7 @@ When `email` is provided, it takes precedence over `emailServiceInstance`.
 | `CsrfGuard` | CSRF header validation for cookie auth |
 | `TenantGuard` | Multi-tenant context resolution |
 | `PermissionGuard` | Permission checking against tenant context |
+| `ScopeGuard` | `@RequireScopes()` enforcement for API keys; register it after the authentication guard |
 | `JwtAuthGuard` | JWT-only guard for GraphQL and HTTP routes (prefer `createAuthGuard` for several strategies or `@Public()`) |
 
 ### Recommended Guard Chains
@@ -1149,8 +1511,9 @@ When realm support is enabled, `RealmMiddleware` runs before all guards (as Nest
 // JWT only
 { provide: APP_GUARD, useClass: createAuthGuard(['jwt'], { allowPublic: true }) }
 
-// JWT + API keys
-{ provide: APP_GUARD, useClass: createAuthGuard(['jwt', 'api-key'], { allowPublic: true }) }
+// JWT + API keys, with scopes enforced on the keys
+{ provide: APP_GUARD, useClass: createAuthGuard(['jwt', 'api-key'], { allowPublic: true }) },
+{ provide: APP_GUARD, useClass: ScopeGuard },
 
 // Full stack with cookie auth + multi-tenancy
 { provide: APP_GUARD, useClass: CsrfGuard },
@@ -1231,8 +1594,53 @@ export class CustomGuard implements CanActivate {
 - **`__Host-` cookie prefix** support for enhanced cookie security
 - **Separate HMAC secrets** for refresh tokens, verification codes, and OAuth state
 - **Realm-based identity isolation** with JWT realm claim validation, realm-scoped rate limiting and lockout, and auth flows that refuse a request without a realm
+- **Pinned JWT algorithms** -- the package's own `jwt` strategy verifies `HS256` only, and `createExternalJwtStrategy` requires an explicit `algorithms` list from one family (see [External JWTs](#external-jwts))
+- **API keys with scopes and expiry**, refused hard when they carry your prefix and match no key, so no other strategy accepts them
 - **No raw personal data in package logs** — log lines use the user ID or a salted hash (`emailHash=`, `ipHash=`, under `AUTH_IP_HASH_SALT` or `jwtSecret`), phone numbers keep only their last two digits, and the default `ConsoleAuthLogger` redacts security-event metadata. A custom `authLoggerInstance` receives the raw fields; pass them through `redactSecurityEventMetadata` to store them redacted.
 
+## Upgrading from 0.9.x
+
+Four releases separate 0.9 from 0.14 and each has its own note below. If you are
+jumping the whole way, this is the order things will bite, and the short answer
+for each.
+
+| Release | What you have to do |
+|---|---|
+| **0.10.0** | Usually nothing. If you relied on `['api-key','jwt']` rejecting JWTs, it no longer does — an unknown key now fails softly so the next strategy runs |
+| **0.11.0** | `getRequestFromContext` can return `undefined`; TypeScript flags every call that assumed otherwise. If you use subscriptions with cookie auth, set `csrf.webSocket` |
+| **0.12.0** | The `jwt` strategy pins HS256 — check anything minting staff tokens elsewhere. Security events are logged once instead of twice, so counts built on them halve. Password reset now reaches password-less accounts with no social identity |
+| **0.13.0** | Nothing — and it was never published separately; its changes ship inside 0.14.0 |
+| **0.14.0** | Biometric authentication is rebuilt and breaking. If you never wired `biometricRepositoryInstance`, nothing changes. If you did, read the security note in the changelog first |
+
+Two things that are easy to miss because nothing errors:
+
+- **Security-event counts.** 0.12.0 stopped double-logging `SIGNUP_SUCCESS`,
+  `LOGIN_SUCCESS` and `LOGOUT_SUCCESS`. Dashboards built before it were reading
+  double and will step down on upgrade rather than when you fix the data.
+- **`verification.baseUrl`.** If you run realms and serve more than one frontend,
+  it accepts a resolver from 0.13.0. Before that, every realm got the same host.
+
+Take them in order rather than jumping straight to 0.14.0 — each note assumes the
+one before it.
+
+## Migrating to v0.12.0
+
+**Password reset now reaches accounts that have no password and no social login.** The guard on `requestPasswordReset` and `resetPassword` tested `passwordHash == null` and treated it as "this user signed in with Google". That is also how an operator-provisioned account starts, so an account created by an admin CLI was skipped silently — the request returned the same success message as a real send, and the reset would have been refused even if a code had arrived. Both guards now test for an actual social identity (`googleId`, `facebookId` or `appleId`), so a social-only account behaves exactly as before, and a password-less account with no social identity receives a reset code and can redeem it.
+
+Two consequences worth deciding on rather than discovering. A half-finished signup row with no password and no social identity can now be claimed by whoever controls the address — previously it was unreachable, which is not the same as safe. And if you wrote a placeholder password hash to work around the old behaviour, you can drop it; `hasSocialIdentity` is exported if you want the same predicate.
+
+The public response is unchanged in both cases. `requestPasswordReset` still returns the same generic message whether it sent, skipped or found nothing, because it is reachable unauthenticated and anything else would be an enumeration oracle. A skip is reported to your `IAuthLogger` instead, as `PASSWORD_RESET_REQUESTED` with `result: 'SKIPPED_SOCIAL_ONLY'`.
+
+**`verification.baseUrl` accepts a resolver.** Purely additive — a string behaves exactly as before. See [`baseUrl` per realm](#one-api-several-brands-baseurl-per-realm).
+
+**The `jwt` strategy now pins `HS256`.** That is the algorithm `JwtModule` signs with, so every token this package issues keeps working. A token signed with `jwtSecret` under HS384 or HS512 -- which jsonwebtoken accepted while nothing was pinned -- is now rejected. If another system mints tokens for the `jwt` strategy, check that it signs HS256, or give it its own strategy with [`createExternalJwtStrategy`](#external-jwts).
+
+**Each security event is logged once.** `BaseAuthResolver` logged `SIGNUP_SUCCESS`, `LOGIN_SUCCESS` and `LOGOUT_SUCCESS` on top of `AuthService`, so an `IAuthLogger` writing to an audit table stored two rows per signup, login and logout. The service's copy is the one that remains: it also covers flows that never reach the resolver. Counts built on those events halve, and `LOGOUT_SUCCESS` metadata is now `{ userId }` -- the resolver's copy also carried `email`. `SIGNUP_ATTEMPT` and `LOGOUT_ALL`, which only the resolver logs, are unchanged.
+
+**A signup refused by `features.preventEnumerationOnSignup` no longer logs `SIGNUP_SUCCESS`.** It used to log one, with the synthetic response's random user ID, for an account that was never created.
+
+**API keys.** Nothing changes until you set `apiKey.prefix` or `apiKey.headerName`, or store `scopes` / `expiresAt`. `ApiKeyStrategy`'s constructor takes the `apiKey` options as an optional second argument, which matters only if you construct it yourself.
+
 ## Migrating to v0.11.0
 
 **`getRequestFromContext` may return `undefined`.** It now also finds a `graphql-ws` subscription's upgrade request, and returns `undefined` where there is no request at all. TypeScript flags each call that assumes a request. In a guard that cannot decide without one, use `requireRequestFromContext`.

package/dist/auth.module.d.ts

@@ -14,6 +14,7 @@ import { ITenantRepository } from './interfaces/tenant-repository.interface';
 import { ITenantExtractor } from './interfaces/tenant-extractor.interface';
 import { IRealmExtractor } from './interfaces/realm-extractor.interface';
 import { IResourcePermissionRepository } from './interfaces/resource-permission-repository.interface';
+import { IBiometricVerifier } from './interfaces/biometric-verifier.interface';
 import { IJwtPayloadFactory } from './interfaces/jwt-payload-factory.interface';
 import { IApiKeyRepository } from './interfaces/api-key-repository.interface';
 import { PasswordPolicyConfig } from './interfaces/password-policy-config.interface';
@@ -56,6 +57,10 @@ export interface AuthModuleOptions {
     resourcePermissionRepositoryInstance?: IResourcePermissionRepository;
     jwtPayloadFactoryInstance?: IJwtPayloadFactory;
     apiKeyRepositoryInstance?: IApiKeyRepository;
+    apiKey?: {
+        headerName?: string;
+        prefix?: string;
+    };
     jwtValidation?: 'full' | 'payload-only';
     isUserActive?: (user: IAuthUser) => boolean;
     bcryptRounds?: number;
@@ -117,12 +122,21 @@ export interface AuthModuleOptions {
         branding?: EmailBrandingConfig;
         templateRenderer?: IEmailTemplateRenderer;
     };
+    biometric?: {
+        verifiers?: IBiometricVerifier[];
+        challengeExpirySeconds?: number;
+        challengeRateLimit?: {
+            maxAttempts: number;
+            windowMs: number;
+        };
+    };
     verification?: {
         tokenLength?: number;
         tokenExpiresInMinutes?: number;
-        baseUrl?: string;
+        baseUrl?: string | VerificationBaseUrlResolver;
     };
 }
+export type VerificationBaseUrlResolver = (realm?: string) => string;
 export interface AuthModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
     useFactory: (...args: any[]) => Promise<AuthModuleOptions> | AuthModuleOptions;
     inject?: any[];

package/dist/auth.module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.module.d.ts","sourceRoot":"","sources":["../src/auth.module.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"auth.module.d.ts","sourceRoot":"","sources":["../src/auth.module.ts"],"names":[],"mappings":"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"}