@ambushsoftworks/nestjs-auth-graphql 0.9.0-rc.1 → 0.9.0-rc.3

package/CHANGELOG.md

@@ -0,0 +1,822 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Reading this file
+
+Alongside the standard Keep-a-Changelog sections, releases may carry:
+
+### ⚠ External configuration required
+
+Steps that must be performed **outside your codebase** — a frontend route, an
+OAuth provider console, a DNS record, an environment variable in your
+deployment platform — for the release to work.
+
+These get their own heading because they are a different species from API
+changes. A removed export, a new required field, a changed signature: your
+compiler, your tests, or a code review will catch every one of them. A reset
+link pointing at a route your frontend does not serve is invisible to all
+three, and surfaces as a user who cannot complete a flow.
+
+Grep for `⚠ External configuration required` across the versions you are
+skipping to build an upgrade checklist mechanically, rather than reading prose
+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.0] - Unreleased
+
+Three independent workstreams land here: a trim of the email interface surface
+down to what the package actually fires, a fix making
+`verificationMode: 'token'` functional for the first time, and enforcement of
+account status — which had never been checked at all. See **Security** first.
+
+Alongside them, `bcrypt` moves from 5 to 6, taking `tar@6.2.1` and its
+advisories out of consumers' production dependency trees. No hash migration.
+
+> Published as a release candidate under the `next` dist-tag first, so the
+> verification and password-reset emails could be confirmed through a real
+> mail client before reaching `latest`. That last hop — a mail client
+> rendering the link — is exactly where the original defect lived and the one
+> thing no test suite in this repo can exercise. Install the candidate with
+> `npm install @ambushsoftworks/nestjs-auth-graphql@next`.
+>
+> **Test against `0.9.0-rc.3`.** It is `rc.2` plus the move to bcrypt 6 in
+> **Security** below and its documentation — nothing else in the published
+> package changed. `rc.1` predates the account-status fix in the same section
+> and still has the suspension window open.
+
+### ⚠ External configuration required
+- **`verificationMode: 'token'` requires your frontend to serve two routes.**
+  Token-mode links point at `<verification.baseUrl>/verify-email` and
+  `<verification.baseUrl>/reset-password`, each carrying `token` and `email`
+  query parameters. Your app must serve both paths, read both parameters, and
+  pass them to `verifyEmail` / `resetPassword`. Nothing in this package can
+  check that — a link to a route you do not serve compiles, tests green, sends
+  successfully, and 404s in the recipient's browser. `verification.baseUrl`
+  itself IS validated at boot; the routes behind it cannot be.
+  **Not applicable in `'code'` mode**, which is the default and ships no link.
+
+### Security
+- **`status` and `deletedAt` were never checked — suspending a user revoked nothing.**
+  `IAuthUser.status` was documented as *"Checked during login to prevent
+  suspended/deleted users from authenticating"*. Nothing checked it, anywhere:
+  outside the `UserStatus` enum declaration and that docblock, `SUSPENDED` and
+  `DELETED` did not appear in `src/`. `login()` gated on rate limit, lockout,
+  user existence, password presence and password validity — never status.
+  `validateUser()`, the JWT path on every authenticated request, verified only
+  that the user still existed.
+
+  What provided revocation in practice was an **undocumented contract**: because
+  `refreshToken()` calls `findById` and rejects on `null`, revocation worked only
+  for consumers whose repository happened to filter revoked users. A consumer
+  who read the docblock and reasonably concluded the package handled it had an
+  **unbounded** exposure window — a suspended user kept refreshing indefinitely,
+  minting a fresh access token each time. Reported by the
+  nestjs-account-management team, who found it while planning a `suspendAccount`
+  operation; two consumers were affected in production.
+
+  Status is now enforced in four places: `login()` (after password verification,
+  so it cannot become an enumeration oracle), `validateUser()`, both branches of
+  `refreshToken()` including the grace-period cache, and as a backstop in the
+  private token-issuance sink every flow funnels through — so no path, including
+  `issueAuthSession`, can mint tokens for an inactive account. Rejection is
+  `AccountInactiveException` (code `ACCOUNT_INACTIVE`, HTTP 403) and logs the new
+  `ACCOUNT_INACTIVE_BLOCKED` security event with the phase.
+
+  **The default is a deny-list, and that is deliberate.** An account is inactive
+  when `deletedAt` is set, or `status` is `SUSPENDED`/`DELETED` compared
+  case-insensitively. It is *not* "anything that is not `ACTIVE`": `status` is
+  typed `string` so consumers can map their own model, and an allow-list would
+  have locked out every user of a consumer storing `'active'`, `'ENABLED'` or
+  `''` the moment they upgraded. A deny-list cannot produce a false rejection.
+  **If your vocabulary differs from `UserStatus`, the default cannot recognize
+  it** — supply the new `isUserActive` option.
+
+  **`jwtValidation: 'payload-only'` bounds revocation by token TTL rather than
+  making it immediate.** That mode skips the per-request lookup by design, so
+  there is nothing to check; a suspended user keeps working until their access
+  token expires. Refresh is still blocked, so the window is exactly one
+  access-token lifetime (15 minutes by default). This was previously
+  undocumented — the option's docblock said only that it "does not check if user
+  still exists" — and now states the consequence. No behavioral change to that
+  mode in this release.
+
+- **`bcrypt` 5.1.1 → 6.0.0: `tar@6.2.1` is no longer in your production dependencies.**
+  `bcrypt@5` installed its native binary through `@mapbox/node-pre-gyp@1.0.11`,
+  which depends on `tar@6.2.1` — 1 critical and 8 high advisories (path
+  traversal, file overwrite, denial of service). All three were the last release
+  of their major, so nothing on the bcrypt 5 line fixes it, and consumers could
+  not fix it either: this package declared `bcrypt ^5.1.1`, so upgrading your
+  own `bcrypt` only nested a second copy. `bcrypt@6` ships prebuilt binaries
+  loaded by `node-gyp-build`; its dependency tree is two packages and audits
+  clean. Reported by Lift, whose production-dependency audit gate flagged this
+  package as high.
+
+  **The exposure was at install time, not on the request path.** `tar` ran
+  while installing bcrypt, to unpack the downloaded binary; at runtime
+  `node-pre-gyp` loads and `tar` does not. The advisories still failed
+  `npm audit --omit=dev`, which is how consumers gate a release.
+
+  **No hash migration, in either direction.** Hashes written by bcrypt 5 verify
+  under 6 and the reverse, so existing users sign in unchanged and rolling back
+  to 0.8.0 does not lock out anyone who set a password on 0.9.0. Checked across
+  `$2a$` and `$2b$`, costs 10 and 12, unicode, and passwords past bcrypt's
+  72-byte limit, on Node 22 (glibc) and `node:20-alpine` (musl, no compiler
+  toolchain). `auth.service.password-hash-compat.spec.ts` pins it: it signs in
+  and changes passwords against hashes generated by bcrypt 5.1.1, which the
+  suite never regenerates.
+
+  **If your app also depends on `bcrypt` directly, move it to `^6.0.0`** in the
+  same deploy. Otherwise your own bcrypt 5 keeps `tar` in the tree.
+
+### Added
+- **`isUserActive?: (user: IAuthUser) => boolean` module option.** Overrides the
+  default account-active predicate for consumers whose status vocabulary differs
+  from `UserStatus`. Called on login, on refresh, on every request in
+  `jwtValidation: 'full'` mode, and before any token pair is minted. Must be pure
+  and synchronous — it runs on the authenticated request path and receives the
+  already-loaded user. Also exported: `isUserActiveByDefault` (the default
+  predicate) and `AccountInactiveException`.
+
+### Fixed
+- **`verificationMode: 'token'` produced unusable password-reset emails.** `AuthService.requestPasswordReset` built the reset URL by string concatenation (`${process.env.FRONTEND_URL}/reset-password`) with no query parameters, then passed the freshly minted credential separately — which `ConfigurableEmailService` discards in token mode. The recipient received a "Reset Password" button pointing at a bare page URL, with no path by which they could ever learn the token. Reported by the Ariadne team; reproduced end to end. No consumer configuration could work around it: both defects sat between `requestPasswordReset` and the renderer.
+- **`verificationMode: 'token'` produced unusable verification emails.** `ConfigurableEmailService.sendVerificationEmail` assigned the raw `code` to the renderer's `verificationUrl` parameter, so the "Verify Email" button's href was the 6-digit code itself (e.g. `href="483920"`), which mail clients resolve as a relative path. Both parameters are typed `string`, so the compiler could not catch it.
+- **`VerificationService.buildVerificationUrl` was never called by any send path.** The package shipped a correct URL builder (setting both `token` and `email`) alongside a second, incorrect one; the send paths used the one that loses the token. There is now exactly one place that knows the URL shape.
+- **Token mode was never wired into the auth flows at all.** `AuthService` called `generateCode`/`validateCode` unconditionally; `generateToken`, `verifyToken`, and `buildVerificationUrl` existed and were unit tested but unreachable from signup, resend, verify, request-reset, or reset. `ConfigurableEmailService` was the only consumer of the `verificationMode` flag, and read it at a layer that has a credential but no URL — which is why it fabricated one.
+- **`expiresInMinutes` was accepted and discarded** (`void expiresInMinutes`) by `ConfigurableEmailService.sendVerificationEmail`, so email copy could not state an accurate expiry. It is now plumbed to the renderer and reflects the active mode's real expiry (15 min for codes, `verification.tokenExpiresInMinutes` for tokens).
+
+### Added
+- **`IAuthLifecycleHooks.onAccountLocked(userId, email, ipAddress, lockDurationSeconds, realm?)`** — fires from `BruteForceProtectionService.recordFailedAttempt` on the not-locked → locked transition. Subsequent failed attempts while already locked do NOT re-fire; use `onAuthFailure` for per-attempt signal. Fire-and-forget (`void`, not `Promise`) — the lock is already recorded by the time the hook runs, and hook failures are caught and logged rather than rolling it back. This is the wiring point for account-locked notification email now that the package no longer sends one itself.
+- **`AuthService.readRefreshTokenFromCookie(req)`** — public symmetric counterpart to `setAuthCookies` / `clearAuthCookies`. Reads `refresh_token` / `__Host-refresh_token` from the request. Useful when wrapping the resolver methods yourself.
+- **`VerificationService.issueCredential(identifier, type, realm?)`** — mode-agnostic issuance returning `IssuedVerificationCredential` (`{ credential, url?, expiresInMinutes, mode }`). Mints the credential and builds its matching URL under a single mode decision, so the two cannot describe different verification schemes.
+- **`VerificationService.verifyCredential(identifier, type, submitted, realm?)`** — the counterpart; branches on the same mode, making it structurally impossible to issue under one scheme and validate under the other.
+- **`IssuedVerificationCredential`** — new exported interface.
+- **`VerificationService.codeExpiresInMinutes` / `tokenExpiresInMinutes` / `credentialExpiresInMinutes`** getters — single source for expiry values previously duplicated as literals across services.
+- **Boot-time validation: `verificationMode: 'token'` requires an absolute http(s) `verification.baseUrl`**, enforced by `validateAuthModuleOptions` → `InvalidAuthConfigException`. Token-mode emails carry no readable credential, so a missing base URL yields mail that delivers successfully and cannot be acted on; this makes it a deploy-time failure rather than a support ticket. Follows the existing `bruteForce.ipRateLimit` ↔ `rateLimiterInstance` precedent. **Code mode is unaffected — `baseUrl` remains optional there.**
+- **`ConfigurableEmailService` refuses to send a token-mode email with no link**, throwing `InternalServerErrorException` rather than delivering an unusable message.
+- Expiry line in the default renderer (HTML + plain text), sourced from the caller and omitted entirely when unknown rather than guessing.
+- **`NoOpEmailSender` now logs every link in the message it would have sent** (HTML entities decoded, duplicates collapsed, and an explicit "contains no links" line for code-mode mail). Previously it logged only recipient, sender, and subject, so locally "an email was sent" was the entirety of what a developer could observe and a dead href was undetectable without a real mailbox — the exact blind spot that let unusable links reach production. Walking an auth flow locally is now: trigger it, read the link from the log, open it. Suggested by the Ariadne team, who had independently built the same thing on their side.
+
+- **`RefreshTokenService` held the Node event loop open.** Its constructor
+  starts a 60-second sweep over the in-memory refresh-token cache, and the
+  timer was never `unref()`d. `onModuleDestroy` clears it, so a normal NestJS
+  shutdown was unaffected — but any process that finished its work and expected
+  to exit (a script, a CLI, a short-lived job importing the package) would hang
+  until something killed it, and Jest workers had to be force-exited. The timer
+  is now unref'd: it still fires for as long as the process is alive for its own
+  reasons, but no longer keeps it alive. `onModuleDestroy` still clears it.
+
+### Fixed (release tooling)
+- **`npm run lint` had never worked.** Five ESLint packages were in
+  `devDependencies` and the script had been present for months, but no config
+  file existed anywhere, so it failed on "couldn't find a configuration file" —
+  and CI never invoked it, so nothing surfaced. The glob also referenced a
+  `tests/` directory that does not exist, which fails ESLint on its own. Adds
+  `.eslintrc.js`, splits `lint` (checks) from `lint:fix` (mutates) so CI can
+  run the check form, and wires `npm run lint` into the pipeline. The existing
+  codebase produced exactly one violation.
+- **Test job now runs on the default branch.** It ran only on merge requests
+  and tags, so a semantic conflict introduced by a merge — green on both sides
+  in isolation — would not surface until someone cut a release.
+- **`--forceExit` removed from the CI test command**, now that nothing holds
+  the event loop open. Force-exiting masks precisely the leak fixed above.
+- **`CHANGELOG.md` is now published to npm** (added to `files`), so consumers
+  can read release notes without leaving the registry.
+- **Prerelease tags no longer publish as `latest`.** `.gitlab-ci.yml` now detects a prerelease tag (`v1.2.3-rc.1`, `-alpha`, `-beta`) and publishes under the `next` dist-tag. Previously `npm publish` defaulted to `latest` for every tag, so cutting an RC would have served it to anyone running a bare `npm install`.
+
+### Changed
+- **`BaseAuthResolver.performRefreshToken` and `performLogout` are now cookie/input symmetric.** When `features.cookieAuth` is enabled and `input.refreshToken` is empty, both read the refresh cookie instead. Browser SPAs cannot read HttpOnly cookies, so they send an empty input and rely on the credentialed request carrying the cookie. Explicit `input.refreshToken` still takes precedence for mobile/CLI callers. Both empty → `UnauthorizedException('Refresh token required')`. **Consumer DTOs must mark `refreshToken` `@IsOptional()`** (or `@IsString()` without `@IsNotEmpty()`) when targeting browser cookie auth, otherwise validation rejects the empty value before the resolver ever runs.
+- **`IEmailService.sendVerificationEmail`** gained an optional 4th parameter `verificationUrl?: string`; **`sendPasswordResetEmail`** gained an optional 4th parameter `expiresInMinutes?: number`. Both are optional, so existing implementations continue to satisfy the interface unchanged.
+- **`IEmailTemplateRenderer.renderVerificationEmail` / `renderPasswordResetEmail`** params gained optional `expiresInMinutes?: number`.
+- **Base URL resolution consolidated on `verification.baseUrl`.** `AuthService` no longer reads `process.env.FRONTEND_URL` directly. In code mode the legacy env var is still honored as a fallback (deprecated, logged once); in token mode `verification.baseUrl` is required and the env fallback is deliberately not consulted.
+- Default renderer copy is now mode-aware — a token-mode verification email no longer instructs the reader to "enter the code below" when the email contains no code.
+- `PASSWORD_RESET_COMPLETED` security-event metadata now reports the real `method` (`'code'` or `'token'`) instead of a hardcoded `'code'`.
+- **`engines.node` is now declared as `>=18`**, which bcrypt 6 requires. This declares the floor rather than raising it: `google-auth-library@10`, a dependency since 0.1.3, already required Node 18, so no install that worked before is excluded. npm warns on an older Node rather than refusing.
+
+### Breaking
+- **`IEmailService` — four notification methods removed.** The package never fired these on its own; they were interface surface consumers had to implement for no benefit. Notification beyond verification, password-reset, and password-changed is now consumer-owned via lifecycle hooks. Only affects consumers who implement `IEmailService` **directly** — the bundled `ConfigurableEmailService`, `SendGridEmailService`, and `NoOpEmailService` are updated, so `emailServiceInstance` / `email` users need no action. **If you did implement them, those emails were never sent** — the package had no call site for any of the four, so an implementation that looked wired up was dead code, and moving it onto the hooks below is the first time it will run. Raised by Lift.
+  - `sendAccountLockedEmail` → wire from the new `onAccountLocked` hook
+  - `sendWelcomeEmail` → wire from `onSignup` (or `onEmailVerified`)
+  - `sendAccountLinkedEmail` → wire from `onOAuthAccountLinked`
+  - `sendAccountUnlinkedEmail` → wire from your unlink resolver directly
+- **`IEmailTemplateRenderer.renderLoginAlertEmail` removed.** The package never fired a login-from-new-device event, so nothing rendered it. Device-fingerprint storage and the send belong on the consumer side.
+- **The corresponding renderers were deliberately kept.** `renderWelcomeEmail`, `renderAccountLockedEmail`, and `renderEmailChangedEmail` remain on `IEmailTemplateRenderer` and on `DefaultEmailTemplateRenderer`. Migration path for each removed send method is therefore: call the renderer you already have from your hook, then hand the result to your own `IEmailSender` — you keep the branded templates without the package pretending to own the trigger.
+
+### Documentation
+- **`IBruteForceRepository.deleteOlderThan` contract clarified.** Documented explicitly that it is a retention operation ("prune whatever attempt history you keep, if any"), not a guarantee the caller can rely on, and that **a no-op returning `0` is a valid implementation** for schemas keeping no attempt history — e.g. `failedLoginAttempts` / `lockedUntil` as columns on the user row, overwritten in place. Raised as a question by the Ariadne team, whose schema is exactly that shape.
+- README: the `deleteOlderThan` Prisma example no longer uses `createdAt`, and says to substitute whichever column records when an attempt happened. The name is schema-specific, and a copied name that happens to exist in your schema with a different meaning compiles and prunes the wrong rows. Raised by Lift, whose column is `attemptedAt`.
+- README: **Installation** states the Node.js 18 floor and the platforms bcrypt ships prebuilt binaries for; **Migrating to v0.9.0** covers the bcrypt move.
+- README: the two verification modes differ in **where the secret lives**, not merely in formatting — token mode puts the credential in the link, code mode keeps it in the body so it never reaches browser history, referrer headers, or proxy logs.
+- README: new "Migrating to v0.9.0" section covering both workstreams — the removed interface methods with their hook-based replacements, and the action-required items for token-mode consumers (`verification.baseUrl` now required at boot; `resetPassword`/`verifyEmail` now receive a 128-character token, so input DTO constraints sized for 6-digit codes must be relaxed).
+- README: "Verification Modes" section rewritten with a code-vs-token comparison table, the exact link format the package emits, base-URL resolution order, and guidance for custom `IEmailService` implementations.
+- CLAUDE.md: documents the single-place-for-the-mode-branch rule, the prohibition on calling `generateCode`/`generateToken` directly from `AuthService`, and the testing rule derived from how these bugs escaped.
+- LOCAL_DEVELOPMENT.md: added guidance for pnpm/yarn consumers (`link:` protocol rather than `npm link`), `npm pack` as the recommended way to verify a fix pre-release, and a rewritten "Nest can't resolve dependencies" entry covering duplicate peer-dependency resolution under symlinks.
+
+### Notes
+- **Backward compatibility of the verification fix:** code mode — the default, and what every existing consumer runs unless they opted into `'token'` — behaves identically, including the `FRONTEND_URL` fallback chain. Token mode was non-functional before this release, so there is no working behavior to preserve. The breaking changes in this release come from the email interface trim above, not from the verification fix.
+- **Why not a one-line patch:** wiring `buildVerificationUrl` into the existing send path would have produced a working link carrying a **6-digit code** as its `token` parameter — functional, but shipping code-mode entropy in a URL that lands in inboxes, referrer headers, and proxy logs. Token mode now mints real tokens end to end.
+- **Test-design change.** Both bugs survived because each side of the seam was unit tested against arguments the real call site never produced: `configurable-email.service.spec.ts` passed a ready-made URL in as the `code` parameter, so the assertion passed while production sent a bare digit string. New tests parse the rendered URL and feed the credential back through `verifyEmail`/`resetPassword` — see `auth.service.verification-mode.spec.ts` and `verification-credential.spec.ts`. Both fixes were verified by reintroducing each bug and confirming the new tests fail.
+
+## [0.8.0] - 2026-05-14
+
+### Added
+- **Async `IRealmExtractor` and `ITenantExtractor` returns** — both interfaces now accept `string | null | Promise<string | null>` from their extractor method. `RealmMiddleware` and `TenantGuard` await the result when a Promise is returned, with no microtask overhead for sync returns (`instanceof Promise` gate). Enables consumers to resolve realm/tenant from a database lookup without bootstrap-cache workarounds. Async extractor throws (rejected Promise or sync `throw`) are treated as `400 Bad Request`, identical to the existing sync-`null` path; the internal cause is logged server-side via Nest's `Logger` but is NOT leaked to the client. Backward-compatible — existing sync extractors compile unchanged.
+- **`BruteForceProtectionService.cleanupOldAttempts(olderThan: Date): Promise<number>`** — implemented. Calls through to the new `IBruteForceRepository.deleteOlderThan(beforeDate)` method and returns the deletion count. The package does not register a scheduler — wire your own cron with your own retention policy. See README "Brute Force Protection" section for an `@nestjs/schedule` example.
+- **`BruteForceProtectionService.checkIpRateLimit(ipAddress, realm?)`** — opt-in implementation behind the new `bruteForce.ipRateLimit` config slot. Reuses the existing `IRateLimiter` infrastructure (the same one used for password-reset throttling) — NO new interface or injection token. Behavior is unchanged when `bruteForce.ipRateLimit` is omitted: returns `false`. The previous per-request "not implemented" WARN log is replaced with a one-time WARN on first call. When `bruteForce.ipRateLimit` IS configured, consumers MUST also explicitly provide `rateLimiterInstance` — `AuthModule.forRootAsync` throws `InvalidAuthConfigException` at boot otherwise (the default `InMemoryRateLimiterService` is silently broken in multi-replica deployments and is not auto-applied for IP rate limiting). Realm-aware: when `realm` is provided, rate-limit keys are prefixed with the realm to prevent cross-realm collisions on a shared store.
+- **`AuthService.issueAuthSession(userId, res?, realm?)`** — new public method that mints an access + refresh pair, persists the refresh token, and sets cookies when `cookieAuth` is enabled AND `res` is supplied. Use after `changePassword()` to keep the current device logged in (other devices stay logged out — `changePassword` already revokes all refresh tokens). Also useful for admin-driven account creation, post-MFA-enrollment session bootstrap, and any flow that needs a session without going through `login()`. The caller is responsible for verifying the user's identity — this method takes a `userId` and trusts it.
+- **`SecurityEvent.IP_RATE_LIMIT_EXCEEDED`** — emitted by `checkIpRateLimit` when an IP exceeds the configured `bruteForce.ipRateLimit` threshold. Metadata: `ipHash`, `realm`, `remainingAttempts`, `resetAt`, `maxAttempts`, `windowMs`. Raw IP is never logged.
+- **`SecurityEvent.SESSION_ISSUED`** — emitted by `issueAuthSession`. Distinct from `LOGIN_SUCCESS` because no credential was verified at this layer. Metadata: `userId`, `realm`, `method: 'issueAuthSession'`.
+- **`hashIp(ipAddress, salt)` utility** — exported HMAC-SHA256-based IP hashing helper used by `checkIpRateLimit`. Pure function: the salt is passed in by the caller (resolved inside `BruteForceProtectionService` from `AUTH_IP_HASH_SALT` env var, falling back to `options.jwtSecret`, with a one-time INFO log on the fallback path when `bruteForce.ipRateLimit` is configured). Threading the salt through the options object (rather than reading `process.env.JWT_SECRET` directly) keeps the package compatible with consumers wiring their JWT secret via `@nestjs/config` / a secrets manager. Output is a 16-character hex prefix.
+- **`InvalidAuthConfigException`** — new exported exception thrown at boot from `AuthModule.forRootAsync` when configuration is internally inconsistent (currently: `bruteForce.ipRateLimit` set without explicit `rateLimiterInstance`). Extends native `Error`, NOT `HttpException` — this is a startup wiring error, not a runtime HTTP error.
+- **`validateAuthModuleOptions(opts)`** — exported (for unit testing) helper invoked inside the `forRootAsync` factory. Currently checks the `bruteForce.ipRateLimit` ↔ `rateLimiterInstance` invariant.
+- **`AUTH_IP_HASH_SALT` env var** — recommended dedicated salt for `hashIp`. Falls back to `JWT_SECRET` with a one-time INFO log when unset.
+
+### Changed
+- **`BruteForceProtectionService` constructor** — now requires `AUTH_MODULE_OPTIONS` and `RATE_LIMITER` injections in addition to the existing args. Internal change; Nest DI handles it. Consumer test code that constructs the service directly with `new BruteForceProtectionService(...)` must update its argument list.
+- **`RealmMiddleware.use` is now async** (`Promise<void>`). Express middleware accepts both shapes — no impact on consumers.
+
+### Breaking
+- **`BruteForceProtectionService.cleanupOldAttempts(olderThan: Date)`** — signature changed from no-arg `Promise<void>` to 1-arg `Promise<number>`. The previous no-arg version was a documented stub that did nothing, so callers wired into a cron were no-op'ing. Migration: `await bruteForce.cleanupOldAttempts(new Date(Date.now() - 90 * 24 * 60 * 60 * 1000));` (90-day retention).
+- **`IBruteForceRepository`** — new required method `deleteOlderThan(beforeDate: Date): Promise<number>`. Consumer implementations must add this method. Reference: `NoOpBruteForceRepository.deleteOlderThan` returns `0`. Prisma example: `return (await this.prisma.bruteForceAttempt.deleteMany({ where: { createdAt: { lt: beforeDate } } })).count;`.
+
+### Documentation
+- Tightened JSDoc on every `BaseAuthResolver.perform*` method to include a copy-paste-ready `@Mutation`/`@Query` snippet — actionable guidance instead of "consumer MUST override and add @Mutation."
+- New reference file `examples/full-resolver-template.ts` shipped in the published package. Consumers can copy this file wholesale as a starting point for their own AuthResolver. Listed in `package.json` `files` array (alongside `dist`, `README.md`, `LICENSE`).
+- README updated: new "IP Rate Limiting" and "Brute-Force Cleanup" subsections under Brute Force Protection; new "Stay Logged In After Password Change" subsection covering the `changePassword` + `issueAuthSession` two-call pattern; async-extractor note added to the Realm-Based Identity Isolation and Multi-Tenancy sections; configuration table extended with `bruteForce.ipRateLimit` and `AUTH_IP_HASH_SALT`; security-events list extended with `IP_RATE_LIMIT_EXCEEDED` and `SESSION_ISSUED`; `BaseAuthResolver` section now points consumers at `examples/full-resolver-template.ts`.
+
+### Notes
+- IP rate limit threshold is inclusive: `maxAttempts` is the first BLOCKED attempt, not the first allowed-over. With `maxAttempts: 5`, the user is blocked starting on the 5th attempt within the window.
+- Auto-cron registration (`@nestjs/schedule`) was considered for `cleanupOldAttempts` and explicitly rejected: pinning consumers to a scheduler is the wrong layer. The package exposes the working primitive; consumers wire their own cron.
+- A separate `IRateLimitStore` interface was considered for IP rate limiting and rejected: the existing `IRateLimiter` already covers the use case (its JSDoc explicitly lists "login attempt throttling"). Adding a parallel store would force consumers to wire two equivalent interfaces.
+- A `BaseAuthResolver` mutation-exposure feature was requested and rejected. The package's compiled output cannot register `@Mutation` decorators that consumers' GraphQL schemas pick up — TypeScript decorator metadata is not preserved across module boundaries (see `src/resolvers/base-auth.resolver.ts:38-40`). The two consolation deliverables above replace the rejected feature.
+- A `pwv` (password-version) JWT claim with immediate access-token revocation on `changePassword` is out of scope for this release; tracked for a future minor.
+
+## [0.7.2] - 2026-05-12
+
+### Fixed
+- **CI publish pipeline** - Switched the publish job to `node:24` (ships with npm 11+) and removed the brittle `npm install -g npm@latest` self-upgrade step that failed for v0.7.0 and v0.7.1 with `MODULE_NOT_FOUND: promise-retry`. The test job remains on `node:22` to match the realistic consumer runtime.
+- **Release plumbing** - Re-cuts the v0.7.0 release. No code changes from v0.7.0; CHANGELOG is brought up to date with the 0.4.0–0.7.0 release line.
+
+## [0.7.1] - 2026-05-12
+
+Skipped — tag pushed but publish failed in CI before reaching npm. Superseded by 0.7.2.
+
+## [0.7.0] - 2026-05-12
+
+### Added
+- **Realm-Based Identity Isolation** - Realms partition the user identity space so users in one realm are invisible to another. The same email address can exist independently in different realms, each with its own password, tokens, and verification state. Designed for white-label platforms, multi-brand businesses, and franchise systems.
+  - `IRealmExtractor` interface — extract a realm identifier from each request (subdomain, header, JWT claim, etc.)
+  - `RealmMiddleware` — registered automatically by `AuthModule` when an extractor is provided; runs before guards and rejects requests with `400 Bad Request` when the extractor returns `null` (strict mode)
+  - `@CurrentRealm()` decorator — pulls the resolved realm out of the GraphQL context
+  - `realm` claim embedded in JWT access tokens; `JwtStrategy` validates the claim against the request realm (mismatch → `401 Unauthorized`)
+  - Identity-resolution repository methods (`findByEmail`, `findByPhoneNumber`, `findByOAuthProvider`, `create`) accept an optional `realm` parameter so consumer implementations can scope queries
+  - `BruteForceProtectionService` and `VerificationService` accept an optional `realm` parameter; in-memory rate limiter keys are prefixed with the realm to prevent cross-realm interference
+  - `CreateUserData.realm` field on user creation payloads
+  - Opt-in: provide `realmExtractorInstance` in `AuthModuleOptions`. No separate feature flag. Existing single-realm consumers are unaffected.
+  - Files: `src/interfaces/realm-extractor.interface.ts`, `src/middleware/realm.middleware.ts`, `src/decorators/current-realm.decorator.ts`, plus updates across `auth.service.ts`, `brute-force-protection.service.ts`, `verification.service.ts`, `jwt.strategy.ts`, `base-auth.resolver.ts`
+
+### Fixed
+- Documentation accuracy pass — corrected several inaccuracies in the README and CLAUDE.md around realm wiring and middleware registration
+
+### Notes
+- The legacy OAuth controller callback methods (deprecated) are intentionally **not** realm-aware. Use the GraphQL mutations and token-based OAuth endpoints for realm-scoped flows.
+
+## [0.6.7] - 2026-05-01
+
+### Added
+- **Code Quality Audit (Phases 3–7)** - Comprehensive deduplication, type-safety, dead-code, and guard-cleanup pass across the codebase
+  - Extracted `generateTokenPairAndStore()` to deduplicate token generation logic
+  - Extracted `mapToRepositoryType()` and `resolveUser()` helpers in `VerificationService`
+  - Removed dead code paths and tightened types in several services
+
+### Fixed
+- **`ApiKeyStrategy`** - Returns `null` instead of throwing when the auth header is missing, allowing strategy chains (JWT → API key → anonymous) to fall through cleanly
+
+### Changed
+- **README rewrite** - Documentation overhauled for accuracy against the current feature set (cookie auth, CSRF, API keys, multi-tenancy, magic links, biometrics)
+- **Publishing checklist** - Added a required "review and update README before tagging" step to `CLAUDE.md`
+
+## [0.6.5] - 2026-04 (CI tracking releases)
+
+### Fixed
+- CI publishing pipeline: corrected OIDC audience, upgraded npm to 11.5.1+, added `SIGSTORE_ID_TOKEN` for provenance, switched to `NPM_ID_TOKEN` for trusted publishing
+- Multiple iterative CI fixes published as 0.6.1 – 0.6.5 while npm Trusted Publishing was being wired up
+
+## [0.6.0]
+
+### Added
+- **Email Template Architecture (P4)** - Branded email templates with token verification support, customizable per-consumer
+- **Security Hardening (P5)** - `__Host-` cookie prefix, `Referrer-Policy` header, additional cookie security defaults, and supporting documentation
+- GitLab CI with npm Trusted Publishing (OIDC) — eliminates need for long-lived npm tokens
+
+### Fixed
+- `JwtModule.expiresIn` type compatibility issue
+
+## [0.5.0]
+
+### Added
+- **Cookie-Based Authentication (P2)** - HTTP-only access/refresh token cookies as an alternative to bearer tokens
+- **CSRF Guard** - Double-submit cookie CSRF protection that pairs with cookie auth
+- **JWT Payload Factory (P3)** - `IJwtPayloadFactory` interface for customizing JWT claims; default factory provided; wired through `AuthService` and `JwtStrategy`
+- **API Key Strategy** - `ApiKeyStrategy` + `IApiKeyRepository` for service-account / non-interactive authentication
+- **Tenancy Layer (P1b)** - `TenantGuard`, `PermissionGuard`, `createAuthGuard()` factory, `HeaderTenantExtractor`, NoOp tenant implementations, `ITenantRepository`, `IResourcePermissionRepository`
+- **Auth Decorators** - `@Public()`, `@SkipTenant()`, `@RequirePermissions()`, `@ResourceScope()`, plus supporting metadata keys
+- Module options expansion to wire all of the above through `AuthModule.forRootAsync()`
+
+## [0.4.0]
+
+### Added
+- **Unified OAuth Methods on `IUserRepository`** - Consolidated `findByGoogleId`/`findByFacebookId` and friends into provider-agnostic `findByOAuthProvider(provider, providerId, realm?)` and related methods
+- **Modular Interface Split** - `IUserRepository` decomposed into `IUserRepositoryCore`, `IUserRepositoryOAuth`, `IUserRepositoryBiometric`, `IUserRepositoryPhone`. `IAuthUser` similarly split into sub-interfaces. Consumers can implement only the sub-interfaces relevant to the features they enable.
+- Widened peer dependency range for NestJS 11 compatibility; added `passport-custom` to peer deps
+
+## [0.3.4] - 2025-11-16
+
+### Fixed
+- **Phone Verification for OAuth Users** - Fixed "User not found" error when OAuth users (Google/Facebook) attempt to add phone verification
+  - Added `generateCodeForUserId()`, `validateCodeForUserId()`, `hasActiveCodeForUserId()` to `VerificationService`
+  - Updated `sendPhoneVerification()`, `verifyPhone()`, and `resendPhoneVerification()` to use user ID-based methods
+  - Previous implementation required phone number to exist in database before verification could be initiated
+  - New implementation uses user ID for code generation/validation, allowing OAuth users to add phone numbers
+  - Files: `src/services/verification.service.ts`, `src/services/auth.service.ts`
+
+## [0.3.0] - 2025-11-16
+
+### Added
+
+#### Enhancement #1: Configurable Password Policy
+- **PasswordPolicyConfig Interface** - Customize password strength requirements for signup and password reset
+  - Configurable: `minLength`, `maxLength`, `requireUppercase`, `requireLowercase`, `requireNumber`, `requireSpecialChar`
+  - Custom validator function support for advanced requirements (e.g., leaked password detection, dictionary checks)
+  - Default policy: min 8 chars, uppercase, lowercase, number (backward compatible with v0.2.x)
+  - Files: `src/interfaces/password-policy-config.interface.ts`
+
+- **PasswordValidationService** - Centralized password validation with configurable rules
+  - Fail-fast validation (returns all errors at once for better UX)
+  - Support for async custom validators
+  - Immutable policy configuration via `getPolicy()`
+  - 26 comprehensive unit tests
+  - Files: `src/services/password-validation.service.ts`, `src/services/password-validation.service.spec.ts`
+
+#### Enhancement #2: IP-Based Rate Limiting
+- **IRateLimiter Interface** - IP-based rate limiting to prevent abuse and email enumeration
+  - Methods: `checkRateLimit()`, `recordAttempt()`
+  - Sliding window algorithm for accurate rate limiting
+  - Files: `src/interfaces/rate-limiter.interface.ts`
+
+- **InMemoryRateLimiterService** - Production-ready rate limiter for single-instance deployments
+  - Sliding window algorithm
+  - Automatic cleanup of expired entries (prevents memory leaks)
+  - Default: 5 password reset requests per hour per IP
+  - 23 comprehensive unit tests (including edge cases, cleanup, concurrency)
+  - Files: `src/services/in-memory-rate-limiter.service.ts`, `src/services/in-memory-rate-limiter.service.spec.ts`
+
+- **NoOpRateLimiter** - Fallback implementation for development/testing
+  - Logs rate limit checks without enforcing limits
+  - Useful for testing environments
+  - Files: `src/repositories/noop-rate-limiter.ts`
+
+- **IP Rate Limiting in Password Reset** - Enhanced security for `requestPasswordReset()`
+  - Checks IP rate limit BEFORE user lookup (prevents enumeration)
+  - Throws `PasswordResetRateLimitException` with `retryAfterSeconds` field
+  - Configurable limits via `AuthModuleOptions.rateLimiterInstance`
+  - Security logging for rate limit violations
+
+#### Enhancement #3: Configurable Reset Strategy (Partial Implementation)
+- **IPasswordResetStrategy Interface** - Strategy pattern for password reset methods
+  - Methods: `generateResetToken()`, `validateResetToken()`, `getExpiryDuration()`, `deleteResetToken()`
+  - Enables flexible password reset implementations (codes, magic links, TOTP, etc.)
+  - Files: `src/interfaces/password-reset-strategy.interface.ts`
+
+- **VerificationCodeStrategy** - Current 6-digit code implementation (default, backward compatible)
+  - Wraps existing `VerificationService`
+  - 15-minute expiry, 3 attempts max, HMAC-SHA256 hashing
+  - Mobile-friendly (easy to copy-paste)
+  - Files: `src/strategies/verification-code.strategy.ts`
+
+- **MagicLinkStrategy** - JWT-based magic link implementation (ready for future use)
+  - JWT-signed tokens with 1-hour expiry
+  - HMAC-SHA256 storage in repository
+  - Web-friendly (click link, auto-fill form)
+  - Requires `IMagicLinkRepository` implementation by consumers
+  - Files: `src/strategies/magic-link.strategy.ts`
+
+- **IMagicLinkRepository Interface** - Storage contract for magic link tokens
+  - Methods: `storeMagicLink()`, `validateMagicLink()`, `deleteMagicLink()`
+  - Consumers implement with Prisma/TypeORM/etc.
+  - Files: `src/interfaces/magic-link-repository.interface.ts`
+
+- **NoOpMagicLinkRepository** - Fallback implementation
+  - Logs operations without storage (magic links won't work)
+  - Files: `src/repositories/noop-magic-link.repository.ts`
+
+### Changed
+
+- **AuthModuleOptions Extended** - Added optional configuration fields:
+  - `passwordPolicy?: PasswordPolicyConfig` - Customize password strength requirements
+  - `rateLimiterInstance?: IRateLimiter` - Provide custom rate limiter (default: `InMemoryRateLimiterService`)
+
+- **AuthService Updated** - Integrated new services:
+  - Now uses `PasswordValidationService` for password strength validation (was hardcoded)
+  - Now uses `IRateLimiter` for IP-based rate limiting on password reset
+  - Injects `AUTH_MODULE_OPTIONS` for password policy configuration
+  - Injects `RATE_LIMITER` for IP rate limiting
+
+- **Injection Tokens** - Added new constants:
+  - `RATE_LIMITER` - Rate limiter service token
+  - Exported from `src/constants.ts` and `src/auth.module.ts`
+
+### Tests
+
+- **Total Tests: 467 → 516 (+49 new tests, +10.5% coverage)**
+  - Password Validation: 26 tests (default policy, custom policies, custom validators, edge cases)
+  - IP Rate Limiting: 23 tests (sliding window, cleanup, concurrency, edge cases)
+  - All existing tests pass (backward compatibility verified)
+
+### Backward Compatibility
+
+- **100% Backward Compatible** - No breaking changes
+  - Default password policy matches v0.2.x hardcoded behavior
+  - Rate limiter defaults to `InMemoryRateLimiterService` (automatically registered)
+  - Password reset still uses verification codes by default
+  - Existing consumers require no code changes to upgrade
+
+### Security Improvements
+
+- **IP-based rate limiting** prevents email enumeration attacks on password reset
+- **Configurable password policies** enable stricter security requirements
+- **Custom validators** support leaked password detection (HaveIBeenPwned, etc.)
+- **Strategy pattern** enables future password reset methods with consistent security
+
+### Documentation
+
+- CLAUDE.md: Added "Optional Password Reset Enhancements" section (pending)
+- README.md: Added "Advanced Password Reset Configuration" section (pending)
+- All new interfaces/classes have comprehensive JSDoc documentation
+- Examples provided for all three enhancements
+
+### Migration Guide
+
+No migration required! All enhancements are optional and backward compatible.
+
+To use new features:
+
+```typescript
+import {
+  InMemoryRateLimiterService,
+  PasswordPolicyConfig
+} from '@ambushsoftworks/nestjs-auth-graphql';
+
+AuthModule.forRootAsync({
+  useFactory: () => ({
+    // Enhancement #1: Custom password policy
+    passwordPolicy: {
+      minLength: 12,
+      requireSpecialChar: true,
+      customValidator: async (password) => {
+        // Check against leaked passwords
+        const isLeaked = await checkLeakedPasswords(password);
+        return {
+          isValid: !isLeaked,
+          errors: isLeaked ? ['Password found in data breaches'] : []
+        };
+      }
+    },
+
+    // Enhancement #2: Rate limiting (default InMemoryRateLimiterService)
+    rateLimiterInstance: new InMemoryRateLimiterService(),
+
+    // ... other options
+  }),
+})
+```
+
+### Known Limitations
+
+- **Enhancement #3 (Reset Strategy)** - Partially implemented:
+  - Interfaces and strategies created but not integrated into AuthService
+  - Current implementation still uses VerificationService directly
+  - Full strategy pattern integration deferred to future release
+  - Magic link strategy requires consumer-implemented repository
+
+- **InMemoryRateLimiterService** - Not suitable for multi-instance deployments:
+  - Rate limit state not shared between instances
+  - For production load-balanced deployments, implement Redis-backed IRateLimiter
+  - Single-instance deployments work perfectly
+
+## [0.2.2] - 2025-11-16
+
+### Fixed
+
+- **Critical: Password Reset Email Template** - Fixed broken email template that was showing URL links instead of 6-digit verification codes
+  - Email service now properly displays 6-digit codes in mobile-responsive format
+  - Removed unused `_resetToken` parameter prefix from `sendPasswordResetEmail()` signature
+  - Updated HTML and plain text templates to match email/SMS verification pattern
+  - Users can now successfully complete password reset flow
+  - Template design: Mobile-responsive, centered code display, 15-minute expiry notice, security warning
+  - Files affected: `src/services/sendgrid-email.service.ts`
+
+### Added
+
+- **Comprehensive Password Reset Test Suite** - Added 17 unit tests covering all password reset scenarios
+  - `requestPasswordReset()` tests: rate limiting, enumeration protection, OAuth rejection, account lock detection
+  - `resetPassword()` tests: code validation, password strength, token revocation, lifecycle hooks
+  - Edge case tests: concurrent requests, email failures, invalid codes
+  - Achieved 95%+ line coverage for password reset code paths
+  - Total package test count: 246 → 263 tests
+  - Files affected: `src/services/auth.service.spec.ts`
+
+### Changed
+
+- **Documentation Improvements**
+  - Updated CLAUDE.md to clarify password reset implementation status and remove misleading "not yet supported" example
+  - Added comprehensive "Password Reset Flow" section to CLAUDE.md with security features documentation
+  - Added complete password reset section to README.md with step-by-step consumer setup guide
+  - Added consumer examples for GraphQL DTOs, resolver mutations, and error handling
+  - Documented 6-digit code approach (vs. magic link strategy) and security considerations
+  - Added lifecycle hooks example for `onPasswordReset()` event
+
+### Technical Details
+
+**Email Template Fix:**
+- Changed: `renderPasswordResetHtmlTemplate()` now accepts `code: string` parameter (was `_resetToken`)
+- Changed: `renderPasswordResetTextTemplate()` now accepts `code: string` parameter (was `_resetToken`)
+- Both templates now display 6-digit code prominently instead of URL links
+- Template design: Mobile-responsive, centered code display, 15-minute expiry notice, security warning
+
+**Test Suite:**
+- Added: 7 tests for `requestPasswordReset()` method
+- Added: 10 tests for `resetPassword()` method
+- Coverage: 95%+ lines, 100% branches, 100% functions for password reset code
+
+**Migration Notes:**
+- No breaking changes
+- No consumer action required (backward compatible)
+- Consumers implementing password reset for the first time should follow README.md setup guide
+- Existing implementations (if any) will automatically benefit from email template fix
+
+### Security
+
+- Email enumeration protection maintained (generic success messages)
+- Rate limiting enforced (60-second cooldown per user via `passwordResetSentAt` field)
+- HMAC-SHA256 code hashing with constant-time comparison
+- Token revocation on password change (all refresh tokens invalidated)
+- OAuth user protection (users without passwords cannot reset)
+- 15-minute code expiry with max 3 validation attempts
+- Account lock integration (brute force protection applies to reset flow)
+
+---
+
+## [0.2.1] - 2025-01-16
+
+### Fixed
+
+- **Facebook OAuth Email Fallback GraphQL Schema**: Added missing `performCompleteFacebookSignUp()` method to `BaseAuthResolver` for consumers using inheritance pattern
+  - Consumers extending `BaseAuthResolver` can now expose `completeFacebookSignUp` mutation in their GraphQL schema
+  - Fixes production issue where Facebook sign-in fails for users without public email (business accounts, privacy settings)
+  - Backend service logic already existed in `AuthService.completeFacebookSignUp()`, but was not accessible via `BaseAuthResolver`
+  - No breaking changes - additive only (new protected method + interface export)
+
+### Added
+
+- `IAuthCompleteFacebookSignUpInput` interface export for type safety in consumer resolvers
+- `BaseAuthResolver.performCompleteFacebookSignUp()` protected method following established pattern
+
+### Technical Details
+
+**Root Cause**: Facebook OAuth email fallback logic was implemented in `AuthService` (v0.2.0) but the corresponding `performCompleteFacebookSignUp()` protected method was never added to `BaseAuthResolver`. This broke the inheritance pattern for consumers.
+
+**Impact**: Consumers using recommended `BaseAuthResolver` pattern (e.g., Lift app) could not complete Facebook sign-in for users without public email (business accounts, privacy settings). This affected ~30% of Facebook OAuth users.
+
+**Solution**: Added protected `performCompleteFacebookSignUp()` method to `BaseAuthResolver`, following the same pattern as all other auth operations (signup, login, verifyEmail, verifyPhone, etc.).
+
+**Migration**: None required for existing consumers not using Facebook OAuth. Consumers needing Facebook email fallback should:
+1. Upgrade to v0.2.1
+2. Add `completeFacebookSignUp` mutation to their custom resolver (see example below)
+3. No configuration changes needed
+
+### Example Consumer Implementation
+
+```typescript
+import { Mutation, Args } from '@nestjs/graphql';
+import { Throttle } from '@nestjs/throttler';
+import { AuthCompleteFacebookSignUpInput } from './dto/complete-facebook-signup.input';
+import { AuthResponse } from './dto/auth-response.dto';
+
+@Mutation(() => AuthResponse, {
+  name: 'completeFacebookSignUp',
+  description: 'Complete Facebook sign-up when email not provided by Facebook',
+})
+@Throttle({ default: { limit: 5, ttl: 60000 } })
+async completeFacebookSignUp(
+  @Args('input') input: AuthCompleteFacebookSignUpInput,
+): Promise<AuthResponse> {
+  return this.performCompleteFacebookSignUp(input) as Promise<AuthResponse>;
+}
+```
+
+---
+
+## [0.2.0] - 2025-01-15
+
+### BREAKING CHANGES
+
+This version introduces a complete architectural refactor for maximum portability across diverse NestJS projects. The package now uses an interface-based architecture with abstract base classes instead of concrete decorated resolvers.
+
+**Migration Required**: See [MIGRATION.md](./MIGRATION.md) for step-by-step upgrade instructions.
+
+#### Removed
+
+- **Concrete `AuthResolver` class** - Package no longer exports a decorated GraphQL resolver
+  - Consumers must create their own resolver extending `BaseAuthResolver<T>`
+  - GraphQL decorators (@Mutation, @Query, etc.) must be added by consumer
+
+- **GraphQL decorators on package entities and DTOs** - Package no longer provides GraphQL types
+  - All package entities converted to interfaces (IAuthUser, IAuthSignupInput, etc.)
+  - Consumers define their own @ObjectType and @InputType classes implementing package interfaces
+  - This eliminates GraphQL schema conflicts when integrating into existing projects
+
+- **Direct Prisma/TypeORM coupling** - Package no longer assumes specific ORM
+  - Repository interfaces require manual implementation by consumer
+  - Full control over database schema and queries
+
+#### Added
+
+- **`BaseAuthResolver<T extends IAuthUser>` abstract class**
+  - Provides protected helper methods for all auth operations
+  - `performSignup()`, `performLogin()`, `performRefreshToken()`, etc.
+  - Type-safe generic parameter allows using any User model implementing IAuthUser
+
+- **Interface-based architecture for complete portability**
+  - `IAuthUser` - User model contract (replaces concrete User entity)
+  - `IAuthSignupInput`, `IAuthLoginInput`, etc. - Input DTOs as interfaces
+  - `IAuthResponse`, `ILogoutResponse`, etc. - Response DTOs as interfaces
+  - Works with any database, ORM, or GraphQL schema structure
+
+- **Comprehensive documentation**
+  - [QUICK-START.md](./QUICK-START.md) - Step-by-step setup guide
+  - [MIGRATION.md](./MIGRATION.md) - Upgrade guide from v0.1.x
+  - [docs/IMPLEMENTATION-ISSUES.md](./docs/IMPLEMENTATION-ISSUES.md) - Common issues and solutions
+  - [docs/IMPLEMENTATION-PLAN-V2.md](./docs/IMPLEMENTATION-PLAN-V2.md) - Architecture deep dive
+
+- **Canonical enum exports**
+  - Package owns `AuthProvider` enum (EMAIL, GOOGLE, FACEBOOK, APPLE)
+  - Package owns `UserStatus` enum (ACTIVE, SUSPENDED, DELETED)
+  - Single source of truth prevents enum compatibility issues
+
+#### Changed
+
+- **User entity**: `User` class → `IAuthUser` interface
+  - Consumers implement interface with their own GraphQL @ObjectType class
+  - Full control over additional custom fields and relationships
+
+- **All DTOs converted to interfaces with I* prefix**
+  - Example: `AuthSignupInput` → `IAuthSignupInput`
+  - Consumers create @InputType classes implementing these interfaces
+
+- **Repository interfaces use generic type constraints**
+  - More flexible type system allows adaptation to various ORMs
+  - Type assertions at repository boundary for Prisma/TypeORM compatibility
+
+- **Package architecture follows Layer 0 principles**
+  - Complete abstraction over database, ORM, and GraphQL implementation
+  - Zero coupling to Prisma, TypeORM, or specific GraphQL libraries
+  - Dependency injection via instance-based pattern (not class references)
+
+### Features Preserved
+
+All authentication features from v0.1.x remain fully functional:
+
+- JWT authentication with automatic refresh token rotation
+- OAuth 2.0 (Google, Facebook, Apple)
+- Email verification with 6-digit PIN codes
+- SMS verification via Twilio
+- Brute force protection with account lockout
+- Biometric authentication support
+- Account linking (multiple OAuth providers per account)
+- Security: HMAC-SHA256 token hashing, AES-256-GCM encryption, constant-time comparison
+
+### Migration Summary
+
+**Before (v0.1.x)**:
+```typescript
+import { AuthModule, AuthResolver } from '@ambushsoftworks/nestjs-auth-graphql';
+
+@Module({
+  imports: [AuthModule.forRoot(...)],
+  providers: [AuthResolver]  // Use package resolver directly
+})
+```
+
+**After (v0.2.0)**:
+```typescript
+import { AuthModule, BaseAuthResolver } from '@ambushsoftworks/nestjs-auth-graphql';
+
+// 1. Create your resolver
+@Resolver()
+export class MyAuthResolver extends BaseAuthResolver<User> {
+  @Mutation(() => AuthResponse)
+  async signup(@Args('input') input: SignupInput): Promise<AuthResponse> {
+    return this.performSignup(input) as Promise<AuthResponse>;
+  }
+  // ... override all 11 mutations + 3 queries
+}
+
+@Module({
+  imports: [AuthModule.forRoot(...)],
+  providers: [MyAuthResolver]  // Use your custom resolver
+})
+```
+
+**Benefits**:
+- Zero GraphQL schema conflicts with existing projects
+- Full control over GraphQL types, fields, and descriptions
+- Works with any database schema (not just Prisma)
+- Type-safe integration through interfaces
+- Easier to customize and extend
+
+### Testing
+
+- **553+ tests passing** in Lift integration (production validation)
+- **0 TypeScript errors** in package build
+- **0 runtime regressions** from architectural changes
+- **100% backward compatibility** of authentication features
+
+### Known Issues
+
+- **Pre-existing test failures**: BruteForceProtectionService and MuscleGroupRecoveryService tests have DI mock issues (not caused by v0.2.0 refactor, existed in v0.1.x)
+- **Migration effort**: Upgrading from v0.1.x requires 2-4 hours to create resolver and GraphQL types
+
+---
+
+## [0.1.10] - 2025-01-14
+
+### Fixed
+- Fixed instance-based DI pattern (removed ModuleRef complexity)
+- Cleaned up repository injection in AuthModule.forRootAsync()
+
+### Changed
+- Simplified dependency injection to use direct instance passing
+- Improved documentation for repository configuration
+
+---
+
+## [0.1.9] - 2025-01-13
+
+### Added
+- Published package to npm registry as `@ambushsoftworks/nestjs-auth-graphql`
+- Standalone repository on GitLab
+
+### Changed
+- Migrated Lift backend to use published npm package
+- Removed local package directory from monorepo
+
+---
+
+## [0.1.8] - 2025-01-12
+
+### Changed
+- Backend package cleanup and optimization
+- Updated authentication service interfaces
+
+---
+
+## [0.1.7] - 2025-01-11
+
+### Added
+- SMS verification via Twilio integration
+- Phone number validation using libphonenumber-js
+- `verifyPhone`, `resendPhoneVerification`, `removePhoneNumber` mutations
+
+### Changed
+- Enhanced verification service with SMS support
+- Router fixes for phone verification flow
+
+---
+
+## [0.1.0] - 2024-11-01
+
+### Added
+- Initial package extraction from Lift app
+- JWT authentication with refresh tokens
+- Email verification via SendGrid
+- Brute force protection
+- Google and Facebook OAuth
+- Biometric authentication support
+- 246+ tests from production codebase
+
+---
+
+[0.8.0]: https://gitlab.com/ambushworks/nestjs-auth-graphql/-/compare/v0.7.2...v0.8.0
+[0.2.2]: https://gitlab.com/ambushworks/nestjs-auth-graphql/-/compare/v0.2.1...v0.2.2
+[0.2.1]: https://gitlab.com/ambushworks/nestjs-auth-graphql/-/compare/v0.2.0...v0.2.1
+[0.2.0]: https://gitlab.com/ambushworks/nestjs-auth-graphql/-/compare/v0.1.10...v0.2.0
+[0.1.10]: https://gitlab.com/ambushworks/nestjs-auth-graphql/-/compare/v0.1.9...v0.1.10
+[0.1.9]: https://gitlab.com/ambushworks/nestjs-auth-graphql/-/compare/v0.1.8...v0.1.9
+[0.1.8]: https://gitlab.com/ambushworks/nestjs-auth-graphql/-/compare/v0.1.7...v0.1.8
+[0.1.7]: https://gitlab.com/ambushworks/nestjs-auth-graphql/-/compare/v0.1.0...v0.1.7
+[0.1.0]: https://gitlab.com/ambushworks/nestjs-auth-graphql/-/releases/v0.1.0