@ambushsoftworks/nestjs-auth-graphql 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -27,6 +27,19 @@ 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.9.1] - 2026-09-14
+
+Documentation only — no code changes. npm shows the README of the latest
+published version, so these corrections needed a release to reach the package
+page.
+
+### Documentation
+- **README: account-status enforcement was undocumented.** 0.9.0 made suspension and deletion revoke access — `ACCOUNT_INACTIVE` (HTTP 403) at login, on refresh and on every authenticated request — and added the `isUserActive` option, but the README mentioned none of it, including in **Migrating to v0.9.0**. Adds an **Account Status** section, an `isUserActive` row under **Common Options**, a **Security Features** entry, and a migration item: clients need to handle `ACCOUNT_INACTIVE`, and repositories must stop hiding inactive users.
+- **README: JWT Validation Modes** now says `'full'` rejects inactive accounts on the next request, and that in `'payload-only'` a suspended user keeps working until their access token expires while refresh stays blocked.
+- **README: Utilities** lists the helpers 0.9.0 exported: `isUserActiveByDefault`, `emailForLog`, `ipForLog`, `maskPhoneDigits`, `redactSecurityEventMetadata` and `hashIp`.
+- **README: Migrating to v0.9.0** no longer says code mode is entirely unchanged. With no base URL at all, code-mode emails now carry no page link.
+- **CHANGELOG: the 0.9.0 release note** said the `rc.4` and `rc.5` changes had not been run on an adopter's staging. Lift had deployed `rc.5` to staging; the note is corrected in place.
+
 ## [0.9.0] - 2026-09-14
 
 Three independent workstreams land here: a trim of the email interface surface
@@ -43,12 +56,15 @@ phone numbers — see **Security**.
 > Shipped through five release candidates on the `next` dist-tag before
 > reaching `latest`; this release is the content of `0.9.0-rc.5` under its
 > final version. Ariadne verified token and code mode end to end before
-> `rc.1`, and Lift ran its automated staging checks and its real-inbox, phone
-> and Google sign-in checks against `rc.3`. What arrived after that — the
-> `features` flag removal and clean build in `rc.4`, and personal data in logs
-> and the code-mode base URL in `rc.5` — was verified by this package's test
-> suite and against the published candidates, not on an adopter's staging.
-> `rc.2` carried eight stale compiled files; see **Fixed (release tooling)**.
+> `rc.1`. Lift ran its automated staging checks and its real-inbox, phone and
+> Google sign-in checks against `rc.3`, then deployed `rc.5` to staging: 18/18
+> automated auth checks, a clean boot, no code-mode base URL warning, and no
+> raw email, IP address or phone number in the package's log output. `rc.2`
+> carried eight stale compiled files; see **Fixed (release tooling)**.
+>
+> *Corrected in 0.9.1. As published in 0.9.0, this note said the `rc.4` and
+> `rc.5` changes had not been run on an adopter's staging; Lift's `rc.5`
+> staging run had been recorded minutes before the note was written.*
 
 ### ⚠ External configuration required
 - **`verificationMode: 'token'` requires your frontend to serve two routes.**

package/README.md

@@ -19,6 +19,7 @@ Production-grade authentication module for NestJS GraphQL + REST APIs. JWT, cook
   - [Brute Force Protection](#brute-force-protection)
   - [Password Policy](#password-policy)
   - [Lifecycle Hooks](#lifecycle-hooks)
+  - [Account Status](#account-status)
   - [JWT Validation Modes](#jwt-validation-modes)
   - [JWT Payload Factory](#jwt-payload-factory)
 - [Configuration Reference](#configuration-reference)
@@ -847,10 +848,33 @@ All hooks are optional. Async hooks are awaited but failures are logged and do n
 
 `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.
 
+### Account Status
+
+Suspending or deleting a user takes effect on their next request. The package checks each user's `status` and `deletedAt` itself:
+
+| Where | Effect |
+|-------|--------|
+| `login` | Rejected after the password is verified, so the check cannot reveal to someone without the password that an address is suspended |
+| Every authenticated request (`jwtValidation: 'full'`) | Rejected on the next request, not at token expiry |
+| `refreshToken` | Rejected, including within the refresh grace period |
+| Any token issuance | Rejected, as a backstop for every flow that mints tokens |
+
+A rejected request throws `AccountInactiveException`: a GraphQL error with `extensions.code` `ACCOUNT_INACTIVE`, `statusCode` `403`, and the message `This account is no longer active.` It does not say whether the account was suspended or deleted. Unlike `AccountLockedException` it does not clear on its own, so clients should sign the user out rather than offer a retry. Each rejection logs `SecurityEvent.ACCOUNT_INACTIVE_BLOCKED` with a `phase` of `login`, `refresh`, `session` or `issue`.
+
+**Which accounts are inactive.** By default (`isUserActiveByDefault`), a user with `deletedAt` set, or whose `status` is `SUSPENDED` or `DELETED`, compared case-insensitively. Any other status — including one the package does not recognise — counts as active, so a status vocabulary that differs from `UserStatus` cannot lock everyone out. If yours differs, supply a predicate:
+
+```typescript
+isUserActive: (user) => user.status !== 'FROZEN' && user.status !== 'CLOSED' && !user.deletedAt,
+```
+
+It must be synchronous and pure: it runs on every authenticated request, against the user already loaded.
+
+**Your repository must return inactive users.** `findById` and `findByEmail` should return suspended and soft-deleted users like any other. A repository that hides them turns `ACCOUNT_INACTIVE` into a "not found" failure, and the package can no longer tell the client why.
+
 ### JWT Validation Modes
 
-- **`'full'`** (default) -- Calls `userRepository.findById()` on every request to verify the user still exists.
-- **`'payload-only'`** -- Returns `{ id, email }` from the JWT payload without a DB lookup. Faster, but does not detect deleted/disabled users until token expiry.
+- **`'full'`** (default) -- Calls `userRepository.findById()` on every request, rejecting the request if the user no longer exists or is no longer active (see [Account Status](#account-status)).
+- **`'payload-only'`** -- Returns `{ id, email }` from the JWT payload without a DB lookup. Faster, but nothing about the account is re-checked per request: a suspended or deleted user keeps working until their access token expires (`jwtExpiresIn`, 15 minutes by default). Refresh is still blocked, so one access-token lifetime is the whole window.
 
 ```typescript
 jwtValidation: 'payload-only',
@@ -890,6 +914,7 @@ jwtPayloadFactoryInstance: {
 | `jwtExpiresIn` | `string` | `'15m'` | Access token TTL |
 | `refreshTokenExpiresIn` | `string` | `'30d'` | Refresh token TTL |
 | `jwtValidation` | `'full' \| 'payload-only'` | `'full'` | JWT validation strategy |
+| `isUserActive` | `(user) => boolean` | `isUserActiveByDefault` | Decides whether an account may authenticate. See [Account Status](#account-status) |
 | `bcryptRounds` | `number` | `12` | Password hashing cost |
 | `nodeEnv` | `string` | `'production'` | Environment identifier |
 | `passwordPolicy` | `PasswordPolicyConfig` | See [Password Policy](#password-policy) | Password strength rules |
@@ -1034,12 +1059,17 @@ When realm support is enabled, `RealmMiddleware` runs before all guards (as Nest
 
 ## Utilities
 
-Helper functions exported for use in custom guards and middleware:
+Helper functions exported for use in custom guards, middleware and loggers:
 
 | Function | Description |
 |----------|-------------|
 | `getRequestFromContext(context)` | Extract request from `ExecutionContext` (handles GraphQL + HTTP) |
 | `extractIpAddress(request)` | Extract client IP (checks `clientIp`, `req.ip`, falls back to `'unknown'`) |
+| `isUserActiveByDefault(user)` | The default account-active predicate (see [Account Status](#account-status)) |
+| `emailForLog(email)`, `ipForLog(ip)` | An email or IP as it may appear in a log line — `emailHash=…` / `ipHash=…`, salted like the package's own logs |
+| `maskPhoneDigits(phone)` | Masks every digit but the last two, keeping formatting |
+| `redactSecurityEventMetadata(metadata)` | Security-event metadata with email, IP and phone fields hashed or masked — what `ConsoleAuthLogger` prints. Call it from a custom `IAuthLogger` for the same treatment |
+| `hashIp(ip, salt)` | HMAC-SHA256 IP hash (16 hex characters) used for rate-limit keys |
 
 ```typescript
 import { getRequestFromContext, extractIpAddress } from '@ambushsoftworks/nestjs-auth-graphql';
@@ -1059,6 +1089,7 @@ export class CustomGuard implements CanActivate {
 
 - **Refresh token rotation** with HMAC-SHA256 hashing and idempotent 10-second grace period
 - **Bcrypt password hashing** with configurable rounds (default: 12)
+- **Account status enforcement** -- suspended and deleted users are rejected at login, on refresh and on every authenticated request (`ACCOUNT_INACTIVE`)
 - **AES-256-GCM encryption** for OAuth tokens at rest
 - **Constant-time comparison** for verification codes
 - **Account enumeration prevention** on signup (optional)
@@ -1070,6 +1101,15 @@ export class CustomGuard implements CanActivate {
 
 ## Migrating to v0.9.0
 
+**Behaviour change — suspended and deleted accounts are rejected.** Before
+0.9.0 the package never checked `status` or `deletedAt`, so suspending a user
+revoked nothing unless your repository happened to hide them. Now those users
+get `ACCOUNT_INACTIVE` (HTTP 403) at login, on refresh and on their next
+request. Handle that error in your clients by signing the user out, check that
+your status values are recognised (supply `isUserActive` if not), and stop
+filtering inactive users out of `findById` / `findByEmail`. See
+[Account Status](#account-status).
+
 **Changed — log output no longer contains raw personal data.** If you parse
 `ConsoleAuthLogger` output or the package's log lines, expect `emailHash` /
 `ipHash` in place of `email` / `ipAddress`, masked phone numbers, and user IDs
@@ -1123,8 +1163,13 @@ Three things to check, in the order they are most likely to bite:
 Token TTL also differs from code TTL: 60 minutes by default
 (`verification.tokenExpiresInMinutes`) versus 15 for codes.
 
-**`verificationMode: 'code'` — the default — is unaffected.** Behaviour is
-identical, including the legacy `FRONTEND_URL` fallback for the reset page URL.
+**`verificationMode: 'code'` — the default — is unaffected by the token-mode
+fix**, including the legacy `FRONTEND_URL` fallback for the page link. One
+change applies to code mode separately: with neither `verification.baseUrl` nor
+`FRONTEND_URL` set, code-mode emails now carry no page link, where they used to
+carry an `https://app.example.com` placeholder that never resolved. The bundled
+email service never showed that link in code mode; only a custom `IEmailService`
+that rendered it notices.
 
 **`bcrypt` 5 → 6.** No code change and no hash migration: existing hashes
 verify unchanged, and hashes written by 0.9.0 still verify if you roll back to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ambushsoftworks/nestjs-auth-graphql",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Production-grade authentication package for NestJS with GraphQL, supporting JWT, OAuth, email/SMS verification, and biometric auth",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",