@ambushsoftworks/nestjs-auth-graphql 0.11.0 → 0.14.0

package/CHANGELOG.md

@@ -27,6 +27,306 @@ 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.14.0] - 2026-09-29
+
+Biometric authentication works. It has been exported since v0.1.3 and never did.
+
+### ⚠ Security
+
+- **The previous `authenticateWithBiometric` verified nothing.** It took
+  `(userId, deviceId)`, checked only that an enrolled credential's id equalled the
+  supplied `deviceId`, and then issued an access and refresh token. No signature,
+  no challenge, no nonce; the public key `enableBiometric` stored was never read
+  by anything. Neither input is a secret, so anyone who knew a user id and an
+  enrolled device id could obtain a session. It also minted its own tokens, so it
+  bypassed the account-status check every other login goes through — a suspended
+  user could sign in.
+
+  **If you wired biometric authentication on 0.13.0 or earlier, treat any session
+  it issued as unauthenticated**, and revoke refresh tokens for affected users.
+  We know of no consumer that did: `IBiometricRepository` had no implementations,
+  and LiftIQ, the only app with biometrics, built its own rather than use this.
+
+### Added
+
+- **A working challenge-response flow.**
+  ```
+  enrolCredential({ userId, publicKey, deviceName })  -> credentialId
+  requestChallenge(credentialId)                      -> { challengeId, challenge, expiresAt }
+  authenticateWithBiometric({ challengeId, credentialId, signature }) -> session
+  ```
+  32-byte single-use challenges, 60-second default expiry, ES256 signature
+  verification, and a session issued through `AuthService.issueAuthSession` — the
+  same sink as every other login, so `assertUserActive`, cookie auth, realm claims
+  and `SESSION_ISSUED` all apply without being reimplemented.
+- **`IBiometricVerifier`**, with `Es256DeviceKeyVerifier` as the default. The
+  verifier is selected by each credential's stored `algorithm`, so a credential
+  enrolled as ES256 is only ever verified as ES256 — the same pinning `JwtStrategy`
+  gained in 0.12.0. WebAuthn can be added later against this interface without
+  reshaping the port.
+- **`biometric` module options**: `verifiers`, `challengeExpirySeconds`,
+  `challengeRateLimit`. Boot refuses an empty verifier list, two verifiers claiming
+  one algorithm, a non-positive expiry, and a rate limit without
+  `rateLimiterInstance`.
+- **A per-IP rate limit** on challenge issuance alongside the per-credential one.
+  The per-credential limit cannot see a caller varying the credential id.
+
+### Changed — breaking
+
+- **`IBiometricRepository` is reshaped**, composed from a new
+  `IBiometricChallengeStore`. It had no implementations, so this breaks nobody in
+  practice. Credentials now carry `algorithm`, `isActive`, `lastUsedAt` and
+  optional `metadata`; challenges are keyed on `credentialId`.
+
+  Its one hard contract: **`consumeChallenge` must be atomic.** A read, a check and
+  then a write lets two concurrent requests with one challenge both succeed. Use a
+  single conditional update and check the affected count — the README has the
+  Prisma form.
+
+  Two schema notes: `credentialId` on a challenge is **not** a foreign key (a
+  challenge is stored for ids that do not exist, so the signed-out request cannot
+  reveal which credentials are enrolled), and there is **no uniqueness** on any
+  device string.
+- **`authenticateWithBiometric`'s signature changed** to
+  `({ challengeId, credentialId, signature }, opts)`.
+- **`enableBiometric`, `disableBiometric` and `updateLastBiometricLogin` are gone
+  from `IUserRepositoryBiometric`.** Having credentials in two ports is why
+  enrolment and authentication used different stores and never met.
+- **`NoOpBiometricRepository` is removed.** A no-op that accepts enrolments and
+  returns no credentials turns a missing implementation into a login that silently
+  never works. Without `biometricRepositoryInstance` the services are not
+  registered.
+- **`credentialId` is generated by the package**, not by the client or the adapter.
+  It travels on an unauthenticated request, so it must be unguessable.
+
+### Security properties worth knowing
+
+- **What it proves.** Possession of the enrolled private key — **not** that a
+  biometric check happened. Nothing in an ECDSA signature attests to that, and the
+  server cannot tell a hardware-backed key from a software one. Most mobile
+  biometric APIs accept a device PIN by default. Weigh that before making it a
+  sole factor.
+- **Every biometric failure returns one 401.** Unknown credential, deactivated
+  credential, replayed or mismatched challenge, bad signature, missing verifier.
+  The route is reachable signed-out, so anything distinguishable reveals which
+  credentials exist. An inactive *account* is deliberately not flattened into it.
+- **A failed attempt still burns the challenge**, so one challenge cannot be used
+  to try many signatures.
+
+### Documentation
+
+- README: **Biometric Authentication**, leading with what a successful
+  authentication does and does not prove, the `IBiometricRepository` contract with
+  the atomic-consume example, and a `biometric` options table.
+- CLAUDE.md: replaced a flow description that named three methods which never
+  existed and described verification the code never performed.
+
+### Testing
+
+- 24 unit tests on the flow with real P-256 keys, real signatures and a real
+  `AuthService` — so the suspended-user case exercises `assertUserActive` rather
+  than a double. The spec they replace mocked both sides of every seam and
+  asserted the method returned tokens, which was true and hid that it returned
+  them without verifying anything.
+- 9 end-to-end tests on both NestJS majors, including that the issued token works
+  on a guarded route, which is what proves the session came from the shared sink.
+- 13 on the challenge service, including twenty concurrent claims on one challenge
+  yielding exactly one winner.
+- Mutation checks: dropping the challenge/credential binding, forcing the verifier
+  true, ignoring `isActive`, minting tokens locally instead of via
+  `issueAuthSession`, and making the test store non-atomic. Each compiles; each
+  fails the suite.
+## [0.13.0] - 2026-09-29
+
+**Never published separately — these changes ship inside `0.14.0`.** Both landed
+on master before either was released, and `npm version` writes one version per
+release, so `0.13.0` does not exist on npm. The entry stays because the changes
+are real and worth reading on their own; if you are upgrading, everything here is
+in `0.14.0`.
+
+A documentation release, with one removal. Nothing in the runtime behaviour of
+any supported path changes.
+
+### Removed
+
+- **`MagicLinkStrategy`, `VerificationCodeStrategy`, `IPasswordResetStrategy`,
+  `IMagicLinkRepository` and `NoOpMagicLinkRepository`** are no longer exported,
+  and their files are gone. Nothing in the package consumed
+  `IPasswordResetStrategy` — `AuthService` calls `VerificationService` directly —
+  and `MagicLinkStrategy` could not be constructed through Nest DI at all,
+  because it injects a `'MAGIC_LINK_REPOSITORY'` token that `AuthModule` never
+  registered. The `NoOpMagicLinkRepository` docblock even showed a
+  `magicLinkRepositoryInstance` option that does not exist in
+  `AuthModuleOptions`.
+
+  This is a public API removal, hence the minor bump, but it cannot break a
+  working consumer: there was no supported way to reach any of it. If you
+  constructed `MagicLinkStrategy` yourself by registering that token, the file is
+  small and self-contained — copy it into your application. Password reset
+  through the package remains the 6-digit code flow, unchanged.
+
+### Documentation
+
+- **README: new `Password Reset` section.** The feature had one passing mention,
+  despite the properties a consumer cannot infer and must not discover in
+  production: 3 attempts before the code is destroyed, the 15-minute expiry, the
+  60-second per-user cooldown, the per-IP limit of 5/hour checked *before* the
+  user lookup for enumeration safety, and that a successful reset **revokes every
+  refresh token for that user**. It also states plainly that the response is
+  identical whether the address was sent a code, skipped or does not exist, and
+  that the distinguishing signal is `PASSWORD_RESET_REQUESTED` with
+  `result: 'SKIPPED_SOCIAL_ONLY'` on your `IAuthLogger`.
+- **README: new `Phone & SMS Verification` section.** Five `perform*` methods
+  that previously appeared only as rows in a table. Records that SMS is
+  code-only — `features.verificationMode: 'token'` does not apply to it — and
+  that omitting `smsServiceInstance` substitutes a no-op, so codes are stored
+  but never delivered.
+- **README: `sendgrid` and `twilio` option tables.** The only two of 42
+  `AuthModuleOptions` fields documented nowhere. Both are read solely by the
+  bundled services; a custom `IEmailService` or `ISmsService` ignores them.
+- **`verification.baseUrl`** now names its exported type,
+  `VerificationBaseUrlResolver`.
+- **`package.json` gains `homepage` and `bugs`.** npmjs.com renders both in the
+  sidebar, so until now the package page offered no route to the repository or
+  to filing an issue.
+
+## [0.12.0] - 2026-09-20
+
+Ambush Desk asked for two things: verifying JWTs that other systems sign, and API
+keys with scopes, expiry and prefixes. They also reported duplicate security
+events, and checking that turned up a false one. Jobsites then filed two more:
+a verification link that cannot follow a realm, and a password reset that
+silently skips accounts it should not. See **Fixed**.
+
+### Fixed
+- **Every signup, login and logout was logged twice.** `BaseAuthResolver` logged
+  `SIGNUP_SUCCESS`, `LOGIN_SUCCESS` and `LOGOUT_SUCCESS` after `AuthService` had
+  already logged each, so an `IAuthLogger` writing to an audit table stored two
+  rows per operation. `AuthService` keeps its copies: they also cover flows that
+  never reach the resolver. Reported by Ambush Desk, and reproduced end to end
+  before the fix.
+- **A signup refused by `features.preventEnumerationOnSignup` logged
+  `SIGNUP_SUCCESS`** for an account that was never created, carrying the
+  synthetic response's random user ID. The resolver logged it without being able
+  to tell the signup apart from a real one; `AuthService`, which can, does not.
+- **A password reset for an account with no password sent nothing, silently.**
+  Both `requestPasswordReset` and `resetPassword` tested `passwordHash == null`
+  and read it as "this user signed in with Google". It is also how an
+  operator-provisioned account starts, so an account created by an admin CLI
+  got no email — and the request returned the same generic success as a real
+  send, so the operator saw success for an account nobody could ever sign into.
+  Both guards now test for an actual social identity via the exported
+  `hasSocialIdentity(user)` (`googleId`, `facebookId` or `appleId`). A
+  social-only account behaves exactly as before. **The two guards have to agree**
+  — correcting only the first would email a credential the second refuses, which
+  is worse than the silence. A skip is now reported through `IAuthLogger` as
+  `PASSWORD_RESET_REQUESTED` with `result: 'SKIPPED_SOCIAL_ONLY'`; the public
+  response is deliberately unchanged, since `performRequestPasswordReset` is
+  reachable unauthenticated and a distinguishable return value would be an
+  enumeration oracle. Reported by jobsites.
+  - Consequence 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.
+
+### Added
+- **`createExternalJwtStrategy(name, options | { inject, useFactory })`**: a
+  Passport strategy for JWTs another system signs, with
+  `secretProvider(kid, request)`, required `algorithms`, `issuer`, `audience`,
+  `clockToleranceSec`, `maxTokenBytes` (default 8192), `mapClaims` and
+  `jwtFromRequest`. Separate from the package's `jwt` strategy: no realm check
+  and no user lookup. Every rejection fails softly, so it composes in
+  `createAuthGuard`. Requested by Ambush Desk.
+  - Unsafe configuration fails boot: missing or empty `algorithms`, `none`, an
+    algorithm jsonwebtoken does not know, HMAC mixed with asymmetric families
+    (which lets a public key be used as an HMAC secret), or one of the package's
+    own strategy names.
+  - The `{ inject, useFactory }` form wires constructor injection, so
+    `secretProvider` can use application services without a subclass.
+- **API key scopes**: `@RequireScopes(...)` and `ScopeGuard`, with
+  `IApiKeyAccount.scopes?: string[]`. A key needs every listed scope, and
+  otherwise gets 403 `INSUFFICIENT_SCOPE` naming what the operation requires. A
+  key with no `scopes` has none. Signed-in people pass, since their access is
+  `PermissionGuard`'s job. Requested by Ambush Desk.
+- **API key expiry**: `IApiKeyAccount.expiresAt?: Date | null`. A key past it is
+  refused with `401 API key has expired`. Requested by Ambush Desk.
+- **`apiKey.headerName`**, such as `'X-API-Key'`, read before
+  `Authorization: Bearer`, which keeps working. `CsrfGuard` treats a request
+  carrying it as credentialed, as it already does for `Authorization`. Requested
+  by Ambush Desk.
+- **`apiKey.prefix`**, such as `'ait_'`. A token without it is not an API key and
+  goes to the next strategy with no lookup; one with it that matches no key is
+  refused with `401 Invalid API key`, since it cannot be a JWT. That replaces the
+  requested `onUnknownKey: 'fail' | 'error'` switch. Requested by Ambush Desk.
+- **`IApiKeyRepository.touchLastUsed?(id)`**, called once per successful match
+  and never for a refused key. It is not awaited, and a failure is logged rather
+  than failing the request. Requested by Ambush Desk.
+- **`verification.baseUrl` accepts a resolver**: `string | ((realm?: string) =>
+  string)`. One deployment serving several brands needs a link that opens on the
+  site the user came from; the realm already reached the credential and was
+  dropped one line before the URL. It applies to both verification modes, since
+  the token link and the code page link are built from the same resolved base.
+  Purely additive — a string behaves exactly as before. Requested by jobsites.
+  - Called once per link and synchronous: resolve from a map, not a query.
+  - Must return a URL for `realm === undefined` too — a request exempted by
+    `realm.skip`, or a single-realm deployment, has no realm.
+  - Boot validation is necessarily weaker for a resolver: it is probed once with
+    `undefined`, because there is no request at startup to supply a realm. A
+    per-realm value is checked when the link is built, where token mode throws
+    (the link carries the only copy of the credential) and code mode warns and
+    sends without a link (the code is in the body).
+
+### Changed
+- **The `jwt` strategy pins `algorithms: ['HS256']`**, the algorithm the module's
+  `JwtModule` signs with. Unpinned, jsonwebtoken 9 also accepted HS384 and HS512
+  tokens signed with `jwtSecret`. Tokens this package issues are unaffected.
+- **`ApiKeyStrategy`'s constructor takes the `apiKey` options** as an optional
+  second argument. This matters only if you construct the strategy yourself.
+
+### Declined
+- **Publishable, origin-restricted API keys.** A key an app embeds is public by
+  construction: it identifies an app rather than authenticating anyone, and
+  `Origin` is set freely by any non-browser client, so restricting it is abuse
+  control rather than authentication. Keeping them out means every credential
+  this package accepts is a secret one. Requested by Ambush Desk, which keeps
+  ingest keys as its own concept.
+
+### Documentation
+- README: **External JWTs**; **API Key Authentication** extended with the prefix,
+  header, expiry, scopes and last-used tracking; `ScopeGuard` and
+  `@RequireScopes` in the guard and decorator tables; the new options; and
+  **Migrating to v0.12.0**.
+- CLAUDE.md: **API Keys, Scopes and External JWTs**, and the rule that each
+  security event is logged once, by the layer that performs the action.
+- README: **One API, several brands: `baseUrl` per realm**, the widened
+  `verification.baseUrl` row, and both new **Migrating to v0.12.0** notes.
+- CLAUDE.md: base URL resolution is realm-aware through one seam, with the
+  warning not to answer it by handing the raw token to the email renderer; and
+  the rule that password reset tests for a social identity, never for a missing
+  password hash.
+
+### Testing
+- **End-to-end** (`test/e2e/tokens-and-keys.e2e-spec.ts`), on both NestJS majors:
+  a customer token through `createAuthGuard(['customer-jwt'])` on an HTTP route
+  and in a resolver, both guard orders with staff tokens, and refusals for
+  another algorithm, an unknown key ID, another audience and an expired token.
+  For API keys: a staff JWT accepted with a prefix set, a key in `X-API-Key` with
+  its use recorded, an unknown prefixed key, an expired key, `@RequireScopes`
+  against keys and people, and the CSRF skip.
+- **Signup, login and logout now run end to end through `BaseAuthResolver`**,
+  counting the events each produces, including a signup refused by
+  `preventEnumerationOnSignup`.
+- **Per-realm links**, in `auth.service.verification-mode.spec.ts` against a real
+  `VerificationService`, and end to end in `auth-module.e2e-spec.ts` — the realm
+  is attached by `RealmMiddleware`, so only an assembled app proves it survives
+  the whole path from header to emailed link. Each test parses the rendered URL
+  and feeds the credential back through `resetPassword`, rather than asserting
+  that a send happened.
+- **43 mutation checks**, each reintroducing one defect: every one failed a test.
+  The five added here include reverting each password-reset guard separately —
+  reverting only `resetPassword` is caught by the close-the-loop test, which is
+  the half-fix worth guarding against.
+
 ## [0.11.0] - 2026-09-15
 
 Ambush Desk asked for two things: refresh retries that survive a second API