@lenne.tech/nest-server 11.36.5 → 11.38.0

package/docs/REQUEST-LIFECYCLE.md

@@ -78,7 +78,7 @@ JWT-based authentication for existing projects:
 | **Refresh Tokens** | Automatic token renewal |
 | **Sign In / Sign Up / Logout** | GraphQL mutations + REST endpoints |
 | **Rate Limiting** | Configurable per-endpoint rate limits (`auth.rateLimit`). Same `RateLimitStore` selection, async signatures and Redis-outage degradation as the BetterAuth row above (namespace `legacy-auth`) |
-| **Legacy Endpoint Controls** | Disable legacy endpoints after migration (`auth.legacyEndpoints`) |
+| **Legacy Endpoint Controls** | Legacy endpoints are OFF unless `auth.legacyEndpoints.enabled: true` (default flipped in 11.38.0 — it was an opt-out, it is now an opt-in). `CoreLegacyAuthDeprecationInitializer` reports the state and the IAM migration progress at boot |
 | **Migration Tracking** | `betterAuthMigrationStatus` query for monitoring |
 
 #### Role System
@@ -592,6 +592,40 @@ If authentication succeeds, `req.user` is set with the authenticated user (inclu
 > raw-forwarded routes. A forged `POST /iam/update-user {"roles":["admin"]}` is rejected with
 > `FIELD_NOT_ALLOWED` (HTTP 400) at the input-parse stage, before any persistence.
 
+> **"Raw" has one exception since 11.38.0: the password-setting reset routes.**
+> `CoreBetterAuthApiMiddleware.normalizeResetPassword()` rewrites the password field of
+> `/reset-password`, `/email-otp/reset-password` and `/phone-number/reset-password` to its
+> normalized (sha256) form **before** building the Web Request, then runs the Better-Auth handler
+> inside an `AsyncLocalStorage` context carrying that value.
+>
+> Both halves are load-bearing. Without the rewrite, a client posting a plaintext password would
+> have `scrypt(plaintext)` stored while every sign-in — which *is* normalized, in
+> `CoreBetterAuthController` — checks `scrypt(sha256(...))`: the account is locked out with the
+> password its owner just chose. Without the context, `emailAndPassword.onPasswordReset` knows
+> *which* user was reset but not to *what*, and cannot mirror the new password into the legacy
+> bcrypt store — leaving the old password valid on the legacy path after a reset.
+>
+> A project subclassing the middleware must know this: the body it forwards is no longer
+> byte-identical to the body it received. `normalizeResetPassword()` is `protected`.
+
+#### 2b. SecurityHeadersMiddleware
+
+Sets the browser security headers on **every** response — `X-Content-Type-Options`,
+`X-Frame-Options`, `Referrer-Policy`, `Strict-Transport-Security`, and the removal of
+`X-Powered-By`. On by default; `security.headers: false` disables it, individual fields switch off
+individually. No CSP is sent unless one is configured.
+
+Middleware rather than an interceptor, and the distinction is the whole point: an interceptor never
+runs for a request a guard turns away, and a `401` is still a response a browser renders. Those are
+also the responses an attacker generates most of. `tests/security-headers.e2e-spec.ts` asserts the
+headers on an actual guard rejection rather than trusting the ordering.
+
+HSTS is decided by the request protocol — `x-forwarded-proto` first, connection protocol as
+fallback — and never by configuration. A browser remembers it, so one sent over `http://localhost`
+makes every project on that host unreachable over http for up to a year, with no server-side undo.
+Behind a TLS-terminating proxy the inward connection is plain http, which makes `trustProxy`
+load-bearing for this header too.
+
 #### 3. graphqlUploadExpress
 
 Only for GraphQL routes. Handles multipart file upload requests according to the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec).

package/migration-guides/11.36.x-to-11.37.0.md

@@ -0,0 +1,344 @@
+# Migration Guide: 11.36.x → 11.37.0
+
+> **This MINOR carries breaking changes.** That is not a slip. In this package the MAJOR digit
+> tracks the NestJS major it targets — 11.x is NestJS 11 — so it moves only when NestJS does.
+> Breaking changes of our own ship in a minor, which is why every one of them is spelled out
+> below. Read §1 before you upgrade — and do not wait for `pnpm install` to tell you: on pnpm's
+> defaults it will quietly install the new peers for you, at a version you never pinned.
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | **`better-auth` is no longer a dependency of this package — it is a peer dependency you must declare yourself** (§1). It moves to **1.7.x** and cannot be held back (§2). `@better-auth/core` joins the contract as a third required peer (§1) |
+| **New Features** | `account.issuer` is backfilled automatically on the first boot after the upgrade, so existing password users keep signing in (§3) |
+| **Bugfixes** | Legacy→IAM account migration wrote an account better-auth 1.7 could not find, which turned the very sign-in that triggered the migration into a 401 (§3) |
+| **Migration Effort** | **Every project: one package.json change (§1) and one deployment note (§3).** Add ~15 minutes if you use social or SSO logins (§4), and read §5 before running two nest-server versions against one database |
+
+---
+
+## Quick Migration
+
+```bash
+pnpm add better-auth@1.7.1 @better-auth/passkey@1.7.1 @better-auth/core@1.7.1
+pnpm add @lenne.tech/nest-server@11.37.0
+pnpm run build
+```
+
+Then read §3 — it concerns your **data**, not your code, and no build will tell you about it.
+
+---
+
+## 1. `better-auth` is now a peer dependency
+
+**Were you affected?** Every project — and the failure mode depends on your package manager,
+which is why you cannot rely on the install to flag it.
+
+| Setting | What `pnpm install` does |
+|---|---|
+| `autoInstallPeers: true` (**pnpm's default**) | installs the peers **silently**, resolving anywhere inside `>=1.7.1 <1.8.0` |
+| `autoInstallPeers: false` | fails with a missing-peer error |
+| `strictPeerDependencies: true` | fails on a version outside the range |
+
+Most projects are on the default, so a green install proves nothing: you end up with an
+unpinned better-auth that can drift on the next install — exactly the split this section exists
+to prevent. Declare all three yourself, pinned, and verify with:
+
+```bash
+pnpm why better-auth       # must show YOUR declaration, not just a peer-resolved copy
+```
+
+### What changed
+
+Up to 11.36.x, `package.json` carried better-auth as an exactly pinned **dependency**:
+
+```jsonc
+"dependencies": {
+  "better-auth": "1.6.26",
+  "@better-auth/passkey": "1.6.26"
+}
+```
+
+From 11.37.0 they are **peer dependencies**, and `@better-auth/core` joins them:
+
+```jsonc
+"peerDependencies": {
+  "better-auth": ">=1.7.0 <1.8.0",
+  "@better-auth/passkey": ">=1.7.0 <1.8.0",
+  "@better-auth/core": ">=1.7.0 <1.8.0"
+}
+```
+
+All three are **non-optional**. That is deliberate and differs from the five peers this package
+already had (`ioredis`, `bullmq`, `@aws-sdk/*`, `@tus/s3-store`), which are `optional: true` and
+lazily imported. better-auth is imported statically at the top of
+`src/core/modules/better-auth/better-auth.config.ts` — if it is missing, the server does not
+degrade, it fails to boot.
+
+Add them to your own `package.json`, exactly pinned:
+
+```jsonc
+"dependencies": {
+  "better-auth": "1.7.1",
+  "@better-auth/passkey": "1.7.1",
+  "@better-auth/core": "1.7.1"
+}
+```
+
+### Why
+
+An exact pin inside a library makes the library the owner of that version. A project could not
+raise better-auth without overriding this package, and in a fullstack setup that is fatal: the
+frontend (`@lenne.tech/nuxt-extensions`) has always declared better-auth as a **peer**, so the app
+could move to 1.7 while the api was pinned to 1.6.26 — a client and a server speaking different
+versions of the same protocol. See §2 for what that actually broke.
+
+The version now belongs to the project, which is the only place that can keep client and server in
+step. The narrow range is not overcaution: better-auth breaks in **minor** releases (1.7 removed
+the `./plugins/oidc-provider` and `./plugins/mcp/client` subpath exports and changed the 2FA
+response shape), so `^1.7.0` would invite the same split at 1.8.
+
+### Vendor mode
+
+Vendor-mode projects already carry better-auth in their own `package.json` — that is what vendoring
+means — so the *mechanism* does not change. The work does:
+
+- bump `better-auth` and `@better-auth/passkey` from `1.6.26` to `1.7.1`, and
+- **add `@better-auth/core`**, which has never been in your manifest.
+
+`/lt-dev:backend:update-nest-server-core` rewrites `src/core/**` and does **not** touch
+`package.json` — these three lines are yours to change. For a NEW vendor-mode project, the `lt`
+CLI must be new enough to carry all three in `src/config/vendor-runtime-deps.json`; an older CLI
+vendors a core that imports packages the generated manifest never declares.
+
+---
+
+## 2. better-auth moves to 1.7.x
+
+**Were you affected?** Every project, and **fullstack projects most of all**.
+
+`>=1.7.0 <1.8.0` has no 1.6 in it. This is not a version you can defer.
+
+### What this fixes
+
+better-auth 1.7 gives `twoFactor.enable` a discriminated result carrying
+`method: "otp" | "totp"`. A 1.7 client narrows on that discriminant before reading `totpURI` and
+`backupCodes`. A 1.6.26 server never sends the field, so the narrowing fails and **every 2FA
+activation is rejected** — with a generic error, against a server that logs nothing unusual.
+
+If your app is on `@lenne.tech/nuxt-extensions` with better-auth 1.7 and your api was still on
+11.36.x, that is what your users were hitting.
+
+### What it costs
+
+Two API changes in better-auth 1.7 reach code you may have written yourself:
+
+- `context.internalAdapter.createUser(user)` now takes a second argument:
+  `createUser(user, { method })`, where `method` is the provisioning source
+  (`'email-password' | 'admin' | 'oauth' | …`).
+- `context.internalAdapter.linkAccount()` requires `issuer` — see §3.
+
+Both are compile errors, so `pnpm run build` finds them. Anything writing to the `account`
+collection **directly** will not be caught by the compiler — see §3.
+
+---
+
+## 3. `account.issuer`: the part no build will tell you about
+
+**Were you affected?** Every project with existing users. This is a **data** change.
+
+### What changed
+
+Up to 1.6 a credential account was identified by `providerId` + `userId`. From 1.7 an account is
+keyed by **(issuer, accountId)**, and the sign-in route filters on it verbatim:
+
+```js
+account.providerId === 'credential' && account.issuer === credentialIssuer && account.accountId === user.id
+```
+
+Every account row written by better-auth 1.6 has **no `issuer` field at all**. `undefined` never
+equals `'local:credential'`, so after the upgrade better-auth cannot find those accounts: **every
+existing password user is locked out**, with a 401 that says nothing about why.
+
+### What this package does about it
+
+On the first boot after the upgrade, `CoreBetterAuthService.onModuleInit()` backfills the field:
+
+```js
+db.collection('account').updateMany(
+  { issuer: { $exists: false }, providerId: 'credential' },
+  { $set: { issuer: createLocalAccountIssuer('credential') } },
+)
+```
+
+It is idempotent — the filter only matches rows still missing the field — and it logs how many rows
+it touched. If it fails, it logs an **error** and the server still starts, because a server that
+boots with a loud error beats one that will not boot at all. Check your logs for
+`Could not backfill account.issuer` after the first deployment.
+
+Credential accounts only. See §4 for why.
+
+### If you write to the `account` collection yourself
+
+Any code that inserts an account row directly through the Mongo driver bypasses better-auth's types
+and therefore the compiler. It must now set the issuer:
+
+```diff
+  await accountsCollection.insertOne({
+    accountId: userIdHex,
++   issuer: createLocalAccountIssuer('credential'),
+    password: passwordHash,
+    providerId: 'credential',
+    userId: userMongoId,
+  });
+```
+
+```ts
+import { createLocalAccountIssuer } from '@better-auth/core/db';
+```
+
+**Derive it, never hand-write `'local:credential'`.** The format is better-auth's to change, and a
+literal copy would keep compiling while silently no longer matching the accounts better-auth writes
+itself.
+
+This bug was live in this package: `CoreBetterAuthUserMapper.migrateAccountToIam()` wrote a
+credential account without the issuer, so a legacy user migrating to IAM got a 401 on the very
+sign-in that triggered the migration. It is fixed in 11.37.0, and 12 e2e tests that were red on
+better-auth 1.7 pin it.
+
+---
+
+## 4. Social and SSO logins are NOT backfilled
+
+**Were you affected?** Only projects using OAuth or SSO providers — but for those this is a
+**pre-upgrade** step, not a post-upgrade cleanup. See the numbered consequences below.
+
+The backfill deliberately stops at credential accounts. `local:credential` is a pure function of
+the provider id and therefore derivable. An OAuth account's issuer is not: it is either the
+provider's **real OIDC issuer** or the synthetic `local:oauth:<providerId>` fallback, decided per
+provider and overridable through the provider config.
+
+Guessing there would not fail loudly. It would write a key that looks valid, and produce a **second
+account** for the same user on the next social sign-in.
+
+So those rows are counted and reported instead. If your logs say
+
+```
+At least one non-credential account has no "issuer"
+```
+
+then act **before** the first social sign-in after the upgrade. Such a sign-in does **not** simply
+fail, which is the part that makes this urgent rather than merely broken:
+
+1. better-auth cannot match the row by `(issuer, accountId)`, so it falls back to matching the
+   user by the **provider-asserted email** and implicitly links a **second** account row. The
+   identity is now established from an email rather than from the provider key — a weaker binding.
+2. If the provider-side email has changed since the row was written, no user matches and
+   better-auth creates a **new user**. The original account is orphaned with its data.
+3. The orphaned row keeps its `accessToken` / `refreshToken`. Unlinking removes the *new* row, so
+   those provider credentials survive every unlink and every "revoke access" action.
+
+For a provider using the synthetic fallback:
+
+```js
+db.collection('account').updateMany(
+  { issuer: { $exists: false }, providerId: 'google' },
+  { $set: { issuer: 'local:oauth:google' } },
+)
+```
+
+For a provider with a real OIDC issuer, use that issuer verbatim. Confirm which of the two applies
+by reading a row better-auth wrote itself after the upgrade.
+
+---
+
+## 5. Deploying: do not run 11.36.x and 11.37.x against one database
+
+The backfill is safe to run repeatedly and safe to run while 11.37.x instances serve traffic. It is
+**not** safe to leave an 11.36.x instance running against the same database afterwards: 11.x keeps
+writing credential accounts without an issuer, and those rows are invisible to 11.37.x until the next
+restart backfills them.
+
+For a rolling deployment, either complete the rollout before relying on new sign-ups, or restart
+one 11.37.x instance after the last 11.36.x instance is gone.
+
+**Rollback** is safe in the other direction: 1.6 ignores the extra `issuer` field, so a backfilled
+database still works with 11.36.x.
+
+---
+
+## 6. Compatibility Notes
+
+Patterns this release does and does not disturb. All of these are override points projects
+legitimately use.
+
+| Pattern | Status | Notes |
+|---|---|---|
+| Subclassing `CoreBetterAuthService` | Compatible | `backfillAccountIssuers()` and `ensureIndices()` are `protected` — override either to change behaviour |
+| **Overriding `onModuleInit()`** | **Action required** | It now runs two steps. An override that does not call `super.onModuleInit()` silently skips the backfill, and your existing password users stay locked out with no error anywhere. Call `super`, or call both `protected` methods yourself |
+| Subclassing `CoreSystemSetupService` | Compatible | See §7 if you override `createInitialAdmin()` — it now passes a provisioning source |
+| Subclassing `CoreBetterAuthUserMapper` | Compatible | An override of `migrateAccountToIam()` that builds the account document itself MUST add `issuer: createLocalAccountIssuer('credential')`, or the migrated user gets a 401 on the sign-in that triggered the migration |
+| Custom `account` collection name / `issuer` field | Compatible | The backfill resolves both from the running better-auth instance and warns when they differ from the defaults |
+| `betterAuth.options.user.validateUserInfo` | **Action required** | See §7 |
+| Reading the `account` collection directly | Compatible | Framework reads deliberately filter on `providerId` alone, so they keep working on un-backfilled rows. Do not add `issuer` to such a filter |
+
+---
+
+## 7. `validateUserInfo` and the initial admin
+
+**Were you affected?** Only projects that configure `betterAuth.options.user.validateUserInfo`.
+
+better-auth 1.7 requires a *provisioning source* on `internalAdapter.createUser()`, and
+`CoreSystemSetupService` now passes `{ method: 'admin' }`. Two consequences:
+
+1. Your hook still runs — the source does not bypass it. It receives
+   `{ method: 'admin', action: 'create-user' }`, so a domain allowlist or invite-code gate can
+   branch on `method` and let the first-admin provisioning through.
+2. **When the hook is configured, initial-admin setup fails.** better-auth additionally calls
+   `getCurrentAuthContext()`, which throws outside an endpoint context. System setup runs from
+   `OnApplicationBootstrap` or a plain controller — never inside better-auth's request pipeline —
+   so the call ends in `FORBIDDEN / validation_context_missing` and no admin is created.
+
+If you use `validateUserInfo`, provision the first administrator another way: create it through a
+request-scoped IAM route, or seed it before enabling the hook.
+
+---
+
+## 8. Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| **Every password user gets 401 after the upgrade.** Correct password, no useful log line | Their `account` rows predate better-auth 1.7 and carry no `issuer` | The backfill runs on the first boot. Check the log for `Backfilled account.issuer on N credential account(s)`. If absent, see the next two rows |
+| No backfill log at all, and users still cannot sign in | The backfill did not run: better-auth disabled, no DB connection, or an `onModuleInit()` override without `super` (§6) | Check `betterAuth.enabled`, then your override |
+| `Backfilled N/M credential accounts. X user(s) CANNOT sign in` | The bulk write hit a duplicate `(issuer, accountId)` pair, usually from an earlier partial migration | Find them: `db.account.aggregate([{$group:{_id:{i:'$issuer',a:'$accountId'},n:{$sum:1}}},{$match:{n:{$gt:1}}}])`, resolve the duplicates, restart |
+| `Backfilling the account issuer against a customised schema` | You renamed the account model or the issuer field | Expected. Verify the names match what better-auth writes |
+| `Could not backfill the account issuer: …` | The database rejected the operation | Boot is not blocked, but affected users cannot sign in. Fix the cause and restart — the backfill retries until it completes |
+| Social login creates a second account, or a brand-new empty user | An OAuth row without an issuer (§4) | Set the issuer per provider. The already-created duplicate must be merged manually |
+| Setup fails with `FORBIDDEN / validation_context_missing` | `validateUserInfo` is configured (§7) | Provision the first admin through a request-scoped path |
+| `pnpm install` succeeded but versions drift later | pnpm auto-installed the peers (§1) | Declare all three explicitly and pin them; verify with `pnpm why better-auth` |
+
+---
+
+## Module Documentation
+
+| Document | Relevance |
+|---|---|
+| [`src/core/modules/better-auth/README.md`](../src/core/modules/better-auth/README.md) | Module overview, the boot-time backfill, troubleshooting |
+| [`src/core/modules/better-auth/INTEGRATION-CHECKLIST.md`](../src/core/modules/better-auth/INTEGRATION-CHECKLIST.md) | Integration steps — **step 0 (installing the three peers) is new in 11.37.0** |
+| [`src/core/modules/better-auth/CUSTOMIZATION.md`](../src/core/modules/better-auth/CUSTOMIZATION.md) | Registration patterns and override points |
+| [`src/core/modules/system-setup/README.md`](../src/core/modules/system-setup/README.md) | Initial-admin provisioning (§7) |
+| [`.claude/rules/better-auth.md`](../.claude/rules/better-auth.md) | Development rules for the module |
+
+---
+
+## Checklist
+
+- [ ] `better-auth`, `@better-auth/passkey`, `@better-auth/core` declared in your own `package.json`, pinned to the same version (§1)
+- [ ] `pnpm run build` green — it finds the `createUser` and `linkAccount` signature changes (§2)
+- [ ] Every direct write to the `account` collection sets `issuer` via `createLocalAccountIssuer` (§3)
+- [ ] First boot after deployment checked for `Backfilled account.issuer` and for `Could not backfill` (§3)
+- [ ] Social/SSO projects: log checked for un-backfilled accounts, issuer set per provider (§4)
+- [ ] Fullstack projects: api and app on the **same** better-auth version (§1)
+- [ ] Rollout does not leave 11.36.x and 11.37.x on one database (§5)
+- [ ] `onModuleInit()` overrides call `super.onModuleInit()` (§6)
+- [ ] Projects using `validateUserInfo`: first-admin provisioning path checked (§7)