@ambushsoftworks/nestjs-auth-graphql 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -27,6 +27,254 @@ 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.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
+instance, and guards that work on GraphQL subscriptions. Checking the first one
+turned up a retry bug that had been there since the first release. See
+**Fixed**.
+
+### Fixed
+- **Guards failed on GraphQL subscriptions over `graphql-ws`.** Guards read
+  `context.req`, which a subscription does not have. With `GraphQLModule`'s
+  `subscriptions: { 'graphql-ws': true }`, Nest puts graphql-ws's connection
+  object there instead. With an app's own `useServer`, there is no `req` at all.
+  Run over a real `graphql-ws` client on 0.10.0, the guard chain
+  `CsrfGuard` → `createAuthGuard(['jwt'])` → `TenantGuard` → `PermissionGuard`
+  refused every subscription:
+  - with `GraphQLModule` subscriptions, `CsrfGuard` answered `CSRF validation failed`
+  - with an own server, it threw `TypeError`s: `Cannot read properties of
+    undefined (reading 'headers')` with a context function, `(reading 'req')`
+    without one
+
+  Guards now read the WebSocket upgrade request. Authentication, realm, tenant
+  and permission checks all work on subscriptions, and with no request to read,
+  guards answer 401 or 403. Reported by Ambush Desk; Ariadne had been working
+  around it with a subclass.
+- **A retried token refresh was always rejected when the repository deletes
+  used tokens.** Refresh deletes the token it used and keeps the result for 10
+  seconds, so that a client that lost the response can retry. The retry then
+  looked up the used token to find the user, found nothing, and answered
+  `401 Invalid refresh token`. That covers every `IRefreshTokenRepository` whose
+  `delete` removes the row, which is what the method is for. The lookup has been
+  there since `v0.1.3`. The kept result now carries the user ID, and the retry
+  still re-checks account status. Reproduced on 0.10.0 before the fix, with a
+  repository that deletes.
+- **A retry arriving between deleting the used token and keeping the result was
+  rejected.** The result is now kept first.
+
+### Added
+- **`csrf.webSocket: 'reject' | 'skip'`**, default `'reject'`. Browsers cannot
+  send the CSRF header on a WebSocket, so this decides for cookie-authenticated
+  subscriptions: 403, or allow. `'skip'` is safe only with an `Origin` check
+  when the socket connects. A subscription whose upgrade request carries an
+  `Authorization` header is allowed either way. Any other value fails boot.
+  Requested by Ambush Desk.
+- **The realm on subscriptions.** `RealmMiddleware` never sees a WebSocket
+  upgrade, so `JwtStrategy` resolves the realm from the upgrade request itself,
+  once per connection, with the same `realm.skip` and extractor rules. A realm
+  the app sets itself (in `onConnect`, say) is kept. Requested by Ambush Desk.
+- **`isWebSocketContext(context)`, `requireRequestFromContext(context)` and
+  `readCookie(request, name)`**, exported. `readCookie` falls back to parsing
+  the `Cookie` header, which is all an upgrade request has.
+- **`refreshRetryCacheInstance?: IRefreshRetryCache`.** A retry that reached a
+  different instance than the first refresh got `401` and a
+  `TOKEN_REUSE_DETECTED` event, because the retry cache lived in one process.
+  Requested by Ambush Desk.
+  - Implement `get`, `set(key, value, ttlMs)` and `delete` over a store the
+    instances share. The interface's JSDoc has a Postgres example.
+  - Entries hold live tokens, so for any store but the in-memory one they are
+    AES-256-GCM encrypted with a key derived from `encryptionKey`, which then
+    becomes required and must match on every instance.
+  - The package enforces expiry itself, and treats store errors as a miss.
+- **`refreshGracePeriodSeconds`**, default 10. `0` turns retries off. Requested
+  by Ambush Desk.
+- **`InMemoryRefreshRetryCache`**, the default, exported so a single-instance app
+  can pass it explicitly.
+- **Boot warnings for in-memory defaults** that only work within one instance:
+  `rateLimiterInstance` (password-reset throttling) and
+  `refreshRetryCacheInstance`. Pass `new InMemoryRateLimiterService()` and
+  `new InMemoryRefreshRetryCache()` to confirm a single instance and silence
+  them. Requested by Ambush Desk.
+
+### Changed
+- **`getRequestFromContext` returns `Record<string, any> | undefined`.** It finds a
+  subscription's upgrade request, and returns `undefined` when a GraphQL context
+  holds no request. It did before too, while typed as never doing so. TypeScript
+  now flags call sites that assume a request.
+- **Cookie auth no longer requires cookie-parser.** The JWT cookie extractor and
+  `readRefreshTokenFromCookie` fall back to the `Cookie` header.
+- **`CsrfGuard` checks `exemptOperations` before reading any header**, and
+  answers 403 rather than throwing when a GraphQL operation's context holds no
+  request. HTTP outcomes are unchanged.
+- **`RefreshTokenService`'s retry cache methods are async and take the user ID:**
+  - `cacheRefreshResult(usedTokenHash, { userId, accessToken, refreshToken })`
+  - `getCachedRefreshResult(usedTokenHash)`, which resolves to that shape or `null`
+  - `invalidateCachedRefresh(usedTokenHash)`
+
+  The class no longer runs a cleanup timer, and `onModuleDestroy` is gone. This
+  only affects code that calls these methods directly or subclasses the service.
+  Implement `IRefreshRetryCache` instead.
+
+### Documentation
+- **CLAUDE.md described a `gracePeriodSeconds` option that never existed**, and a
+  Redis subclass of `RefreshTokenService` that could not work. It overrode the
+  synchronous cache methods with async ones, and the truthy Promise would have
+  sent every refresh down the cached branch. Both are replaced by the port's real
+  design.
+- README: **Refresh Retries**, **GraphQL Subscriptions**, **Migrating to
+  v0.11.0**, and rows for the new options and utilities.
+
+### Testing
+- **End-to-end subscriptions.** The suite drives real `graphql-ws` clients
+  against three server setups on both NestJS majors: `GraphQLModule`-managed, an
+  own `useServer` with a context, and one without. Against each, it checks
+  delivery, a missing cookie, a wrong realm, a missing permission, another
+  tenant, CSRF `'reject'` and `'skip'`, and a bearer token on the upgrade.
+- **Refresh retries end to end:**
+  - a retry gets the same pair
+  - two instances sharing a store
+  - without a shared store: `TOKEN_REUSE_DETECTED`
+  - after the grace period: 401
+  - a user suspended between the refresh and its retry is refused
+
 ## [0.10.0] - 2026-09-15
 
 Ambush Desk, a new consumer on NestJS 11, asked for routes that need no realm, a

package/README.md

@@ -13,6 +13,7 @@ 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)
   - [OAuth](#oauth)
@@ -20,6 +21,7 @@ Production-grade authentication module for NestJS GraphQL + REST APIs. JWT, cook
   - [Password Policy](#password-policy)
   - [Lifecycle Hooks](#lifecycle-hooks)
   - [Account Status](#account-status)
+  - [Refresh Retries](#refresh-retries)
   - [JWT Validation Modes](#jwt-validation-modes)
   - [JWT Payload Factory](#jwt-payload-factory)
 - [Configuration Reference](#configuration-reference)
@@ -35,8 +37,11 @@ Production-grade authentication module for NestJS GraphQL + REST APIs. JWT, cook
   - [Optional Instance Options](#optional-instance-options)
 - [Decorators](#decorators)
 - [Guards](#guards)
+  - [GraphQL Subscriptions](#graphql-subscriptions)
 - [Utilities](#utilities)
 - [Security Features](#security-features)
+- [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)
 - [License](#license)
@@ -556,6 +561,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).
@@ -685,6 +757,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:
 
@@ -926,6 +1032,35 @@ It must be synchronous and pure: it runs on every authenticated request, against
 
 **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.
 
+### Refresh Retries
+
+Refresh tokens rotate: each refresh deletes the token it used. A client that loses the response — a dropped connection, a timeout, an HTTP client that retries — sends the used token again, which looks exactly like a stolen token being replayed. For `refreshGracePeriodSeconds` (default 10) the package remembers the result and answers the retry with the same token pair. `0` turns this off.
+
+**One instance:** nothing to do.
+
+**More than one instance:** give every instance the same store, or a retry that reaches a different instance gets `401` and signs the user out:
+
+```typescript
+AuthModule.forRootAsync({
+  inject: [PgRefreshRetryCache, PgRateLimiter, ConfigService],
+  useFactory: (retryCache, rateLimiter, config) => ({
+    // ...required options
+    refreshRetryCacheInstance: retryCache,
+    encryptionKey: config.getOrThrow('ENCRYPTION_KEY'), // required with a shared store, same on every instance
+    rateLimiterInstance: rateLimiter, // password-reset throttling needs sharing for the same reason
+  }),
+})
+```
+
+- Implement `IRefreshRetryCache` (`get`, `set(key, value, ttlMs)`, `delete`) over Redis, Postgres, or any store the instances share. Its JSDoc has a Postgres example.
+- The values are AES-256-GCM ciphertext, because they hold live tokens. Boot fails with `InvalidAuthConfigException` when `encryptionKey` is missing.
+- The package enforces expiry itself, so the store's TTL can be approximate.
+- A store that errors costs retries, never the refresh itself.
+
+At boot the package warns for each in-memory default in use, `rateLimiterInstance` and `refreshRetryCacheInstance`, because it cannot tell how many instances run. Pass `new InMemoryRateLimiterService()` and `new InMemoryRefreshRetryCache()` explicitly to confirm a single instance and silence them.
+
+Before 0.11.0 a retry got `401` whenever `IRefreshTokenRepository.delete` removed the used token, even on a single instance.
+
 ### JWT Validation Modes
 
 - **`'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)).
@@ -987,6 +1122,9 @@ These sit beside `useFactory`, not in the object it returns.
 | `encryptionKey` | `string` | -- | 32-byte hex string for AES-256-GCM (OAuth token encryption) |
 | `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`)
 
@@ -1042,6 +1180,7 @@ Separate HMAC secrets for security isolation. All fall back to `jwtSecret` if no
 | `headerName` | `string` | `'X-Requested-With'` | Header to check |
 | `requireInProduction` | `boolean` | `true` | Require CSRF header in production |
 | `exemptOperations` | `string[]` | `[]` | GraphQL operations to skip |
+| `webSocket` | `'reject' \| 'skip'` | `'reject'` | Cookie-authenticated GraphQL subscriptions: refuse with 403, or allow. `'skip'` needs an `Origin` check when the socket connects. See [GraphQL Subscriptions](#graphql-subscriptions) |
 
 ### Composable Email (`email`)
 
@@ -1060,7 +1199,7 @@ 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 \| (realm?: string) => string` | — | 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 |
 
 ### Optional Instance Options
 
@@ -1079,6 +1218,7 @@ When `email` is provided, it takes precedence over `emailServiceInstance`.
 | `jwtPayloadFactoryInstance` | `IJwtPayloadFactory` | `DefaultJwtPayloadFactory` |
 | `apiKeyRepositoryInstance` | `IApiKeyRepository` | `null` |
 | `rateLimiterInstance` | `IRateLimiter` | `InMemoryRateLimiterService` (Note: this fallback does NOT apply when `bruteForce.ipRateLimit` is configured — boot fails with `InvalidAuthConfigException` and an explicit `rateLimiterInstance` is required. See [IP Rate Limiting](#ip-rate-limiting) above.) |
+| `refreshRetryCacheInstance` | `IRefreshRetryCache` | `InMemoryRefreshRetryCache`, which answers retries on the same instance only. A shared store requires `encryptionKey`. See [Refresh Retries](#refresh-retries) |
 | `realmExtractorInstance` | `IRealmExtractor` | `null` (realms disabled) |
 
 ---
@@ -1091,6 +1231,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 |
@@ -1104,6 +1245,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
@@ -1114,8 +1256,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 },
@@ -1124,13 +1267,45 @@ When realm support is enabled, `RealmMiddleware` runs before all guards (as Nest
 { provide: APP_GUARD, useClass: PermissionGuard },
 ```
 
+### GraphQL Subscriptions
+
+The guards also protect subscriptions over `graphql-ws`. A socket has no HTTP request, so they read the WebSocket upgrade request instead: the headers and cookies the client opened the connection with.
+
+| Guard | On a subscription |
+|-------|-------------------|
+| `createAuthGuard`, `JwtAuthGuard` | Authenticates from the upgrade request's `Authorization` header or session cookie. `RealmMiddleware` never sees the upgrade, so the realm is resolved from it once per connection |
+| `TenantGuard`, `PermissionGuard` | Resolve the tenant and check permissions from the upgrade request |
+| `CsrfGuard` | Browsers cannot send the CSRF header on a WebSocket, so `csrf.webSocket` decides: `'reject'` (default) answers 403, `'skip'` allows. A connection with an `Authorization` header is allowed either way |
+
+**Use `'skip'` only with an `Origin` check when the socket connects.** That check is what stops another site from opening a socket with your users' cookies.
+
+With your own `graphql-ws` server, also pass the connection through as the context. Without it, guards receive no request and refuse every subscription with 401:
+
+```typescript
+useServer(
+  {
+    schema,
+    context: (ctx) => ctx,
+    onConnect: (ctx) => ALLOWED_ORIGINS.includes(ctx.extra.request.headers.origin ?? ''),
+  },
+  wsServer,
+);
+```
+
+With `GraphQLModule`'s `subscriptions: { 'graphql-ws': { onConnect } }`, the guards find the upgrade request on their own; put the same `onConnect` there.
+
+`isWebSocketContext(context)` and `readCookie(request, name)` are exported for your own guards and connection handlers.
+
 ## Utilities
 
 Helper functions exported for use in custom guards, middleware and loggers:
 
 | Function | Description |
 |----------|-------------|
-| `getRequestFromContext(context)` | Extract request from `ExecutionContext` (handles GraphQL + HTTP) |
+| `getRequestFromContext(context)` | The request behind an `ExecutionContext`: HTTP, GraphQL, or a `graphql-ws` subscription's upgrade request. `undefined` when there is none |
+| `requireRequestFromContext(context)` | The same, but throws `UnauthorizedException` when there is no request |
+| `isWebSocketContext(context)` | Whether the context is a GraphQL subscription over a WebSocket |
+| `readCookie(request, name)` | A cookie's value from `request.cookies`, or parsed from the `Cookie` header (a WebSocket upgrade request has only the header) |
 | `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 |
@@ -1139,12 +1314,12 @@ Helper functions exported for use in custom guards, middleware and loggers:
 | `hashIp(ip, salt)` | HMAC-SHA256 IP hash (16 hex characters) used for rate-limit keys |
 
 ```typescript
-import { getRequestFromContext, extractIpAddress } from '@ambushsoftworks/nestjs-auth-graphql';
+import { requireRequestFromContext, extractIpAddress } from '@ambushsoftworks/nestjs-auth-graphql';
 
 @Injectable()
 export class CustomGuard implements CanActivate {
   canActivate(context: ExecutionContext): boolean {
-    const request = getRequestFromContext(context);
+    const request = requireRequestFromContext(context);
     const ip = extractIpAddress(request);
     // your logic
     return true;
@@ -1154,7 +1329,7 @@ export class CustomGuard implements CanActivate {
 
 ## Security Features
 
-- **Refresh token rotation** with HMAC-SHA256 hashing and idempotent 10-second grace period
+- **Refresh token rotation** with HMAC-SHA256 hashing; a retried refresh gets the same pair for 10 seconds (configurable, shareable across instances, encrypted at rest)
 - **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
@@ -1164,8 +1339,38 @@ 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.
 
+## 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`.
+
+**Subscriptions through `CsrfGuard`.** With cookie auth they answer 403 unless you set `csrf.webSocket: 'skip'`, together with an `Origin` check when the socket connects. They failed before 0.11.0 as well: with that same 403 on `GraphQLModule` subscriptions, or a `TypeError` on your own `graphql-ws` server. See [GraphQL Subscriptions](#graphql-subscriptions).
+
+**Cookie auth no longer needs cookie-parser.** The access and refresh token cookies are read from the `Cookie` header when `request.cookies` is absent.
+
+**More than one instance.** Set `refreshRetryCacheInstance` and `encryptionKey`, or retried refreshes that reach another instance sign users out; see [Refresh Retries](#refresh-retries). Boot now warns for each in-memory default in use. `RefreshTokenService`'s retry cache methods became async, which only matters if you call or override them.
+
 ## Migrating to v0.10.0
 
 No code change is required. Check the items that apply to you.