@lenne.tech/nest-server 11.36.4 → 11.37.0

package/docs/REQUEST-LIFECYCLE.md

@@ -620,6 +620,30 @@ async updateUser(...): Promise<User> { ... }
 async getPublicUsers(): Promise<User[]> { ... }
 ```
 
+**Public does not mean anonymous (since 11.36.5).** On a public endpoint (`S_EVERYONE`, or no
+`@Roles` at all) `RolesGuard` still tries to IDENTIFY the caller before granting access —
+Better-Auth first, Passport JWT second, every failure swallowed. Access is granted either way: a
+missing, expired or malformed token can never turn a public endpoint into a 401. The effect is that
+`@CurrentUser()`, `serviceOptions.currentUser` and `securityCheck(user)` see a signed-in caller, so
+a public endpoint can personalise — a search ranking by the caller's own location, a list marking
+the caller's own entries.
+
+Before 11.36.5 the guard returned early and `request.user` stayed unset. That mattered **only in
+legacy-JWT deployments**: with Better-Auth enabled, `CoreBetterAuthMiddleware` is applied via
+`forRoutes('(.*)')` and had already set `request.user` before any guard ran. `BetterAuthRolesGuard`
+keeps its early return for exactly that reason — it only runs when Better-Auth is enabled, where the
+middleware has already done the work.
+
+Two consequences worth knowing when you own a public endpoint:
+
+- **Owner-restricted output widens for its owner.** `@Restricted(S_SELF)` / `@Restricted(S_CREATOR)`
+  fields evaluate against `currentUser`; with `undefined` they always stripped. They now appear for
+  the caller who owns the record. That is the declared policy finally being applied, not a leak —
+  but it may be the first time anyone sees those fields on that route.
+- **An anonymous caller stays ABSENT, not falsy.** Passport answers `false` for "no credentials";
+  the guard normalises that away so `@CurrentUser()` yields `undefined` as before. Pinned by
+  `tests/public-endpoint-identity.e2e-spec.ts`.
+
 **Important:** `@Roles()` already handles JWT authentication internally. Do NOT add `@UseGuards(AuthGuard(JWT))` — it is redundant.
 
 #### System Roles (S_ prefix)
@@ -634,7 +658,7 @@ When `X-Tenant-Id` header is present and a system role grants access, membership
 
 | System Role | Check Logic | Use Case |
 |-------------|-------------|----------|
-| `S_EVERYONE` | Always true | Public endpoints |
+| `S_EVERYONE` | Always true — access granted unconditionally; the caller is still identified when a valid token is present (see above) | Public endpoints |
 | `S_NO_ONE` | Always false | Permanently locked |
 | `S_USER` | `currentUser` exists | Any authenticated user |
 | `S_VERIFIED` | `user.verified \|\| user.verifiedAt \|\| user.emailVerified` | Email-verified users |

package/migration-guides/11.32.x-to-11.33.x.md

@@ -10,7 +10,7 @@
 | **Bugfixes** | Migration lock gained heartbeat + stale-break + bounded wait; `runOnInit` cron dedup no longer keyed on each replica's boot clock and no longer crashes the process on a failed startup run; BullMQ worker no longer swallows a tick delivered during bootstrap; rate limiters degrade instead of 500-ing on a Redis outage; Hub buffer mirror failures no longer recurse through the Logger they buffer; the email-verification cooldown timer can no longer expire a later cooldown early; a presigned S3 download no longer serves the file under a different name than the streamed one (§14) |
 | **Under the hood (§14)** | Two new MongoDB collections (`s3-files`, `filesystem-files` — include them in backups), new public exports, a bucket-less `s3` block is now ignored, NestJS 11.1.28 → 11.1.29, plus two dependency MAJORS: `js-sha256` 0.12.0 → 1.0.0 (**digests unchanged — no password-hash break**) and `graphql-query-complexity` 1.1.1 → 2.0.0 |
 | **Dependency Housekeeping** | The framework's own `pnpm audit` went from 20 findings to 0. Those are `pnpm-workspace.yaml` overrides, which **do not reach npm consumers** — run your own audit (§13) |
-| **Migration Effort** | **Start with §A and §B — they are the only changes that can break a single-replica project, and they break it silently** (no crash, just 401/403 on `/files/**` and `/tus`). Then **§11a / §11b if your config already contains a `redis` or an `s3` key** — the framework reads both now, and an existing `s3` key makes the boot FAIL until you act. Everything else is opt-in: read §1 if you call or override the rate limiters, §2 if you override Hub services, §4 before your next multi-replica deploy, §10 if you copied the avatar upload from `src/server`, **§11c if you rate-limit behind a reverse proxy** (a boot warning will tell you), §13 for what the security overrides do and do not do for you |
+| **Migration Effort** | **Start with §A and §B — they are the only changes that can break a single-replica project, and they break it silently** (no crash, just 401/403 on `/files/**` and `/tus`). Then **§11a / §11b if your config already contains a `redis` or an `s3` key** — the framework reads both now, and an existing `s3` key makes the boot FAIL until you act. Everything else is opt-in: read §1 if you call or override the rate limiters, §2 if you override Hub services, §4 before your next multi-replica deploy, §10 if you copied the avatar upload from `src/server`, **§11c if you rate-limit behind a reverse proxy** (a boot warning will tell you), §13 for what the security overrides do and do not do for you, and **§5 if any test suite of yours resets the database to replay system setup** — emptying `users` is no longer enough |
 
 Most of this release exists to make one deployment shape possible: **more than one replica**. Nothing there is required to keep running on one.
 
@@ -547,9 +547,42 @@ creating, an instance now claims the setup by upserting `{ _id: 'initial-admin'
 `system-setup-locks` collection — an atomic operation exactly one instance wins. The others log a
 debug line and skip. If creation then fails, the marker is removed so a later boot can retry.
 
-**Action: none.** The unique email index already prevented duplicate *users*; this removes the noisy
-failures and the ambiguity about which replica actually did the setup. A new collection
-`system-setup-locks` appears in the database with a single small document.
+**Action: none in production.** The unique email index already prevented duplicate *users*; this
+removes the noisy failures and the ambiguity about which replica actually did the setup. A new
+collection `system-setup-locks` appears in the database with a single small document.
+
+**Action (test suites only): if you reset the database to replay system setup.** The marker is
+removed only when creation FAILS. After a SUCCESSFUL setup it stays, which is what you want for a
+deployment: setup must never run twice. But it also means that emptying `users` no longer restores
+the fresh-install state, because `createInitialAdmin()` now guards on two conditions, not one. The
+second `POST /system-setup/init` is then refused until the claim goes stale — **five minutes after
+the claim was taken, i.e. after the successful setup, not five minutes after the refusal.** That is
+why the symptom looks intermittent and gets misfiled as flake: a suite resetting ten minutes after
+boot is not blocked at all, one resetting immediately is.
+
+Drop the collection wherever you drop `users`:
+
+```typescript
+// deleteMany, not drop: dropping `users` would drop its unique email index — the very
+// index that prevents a duplicate admin, credited above. deleteMany preserves indexes.
+for (const col of ['users', 'account', 'session', 'system-setup-locks']) {
+  await db.collection(col).deleteMany({});
+}
+```
+
+That is the framework's own reset, executed on every test run in
+`tests/stories/system-setup.e2e-spec.ts` — prefer reading it there over copying this snippet, since
+a spec that runs cannot drift. (The whole-database `dropDatabase()` elsewhere in `tests/` is a
+different job: per-run teardown, not a mid-run reset.)
+
+Both refusals raise the same `LTNS_0050`. **Up to 11.36.4** its message read *"System setup not
+available - users already exist"*, so a suite hitting the claim was told the users were the problem
+while the users collection was empty. **From 11.36.5** the message names both conditions and the
+server logs a warning naming `system-setup-locks`, the release-on-failure semantics and the stale
+window. If setup fails right after a reset, check this collection before anything else.
+
+Note that `GET /system-setup/status` does **not** help here: `needsSetup` is computed from the user
+count alone, so it reports `true` while init is refused by the claim.
 
 ---
 

package/migration-guides/11.36.4-to-11.36.5.md

@@ -0,0 +1,184 @@
+# Migration Guide: 11.36.4 → 11.36.5
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None that removes or renames anything. **One behaviour change** on the legacy-JWT path: a signed-in caller is now identified on public endpoints (§2). One **consumer-visible string**: the `LTNS_0050` message and both its translations (§1) |
+| **New Features** | None |
+| **Bugfixes** | A signed-in caller lost their identity on a public endpoint in legacy-JWT deployments (§2). `LTNS_0050` described only one of the two guards that raise it, so a caller that had just emptied `users` was told users already exist while the collection was empty (§1) |
+| **Migration Effort** | **None for most projects.** `pnpm update`. Read **§2 if you run legacy JWT auth WITHOUT Better-Auth and have public endpoints** — that is the only behaviour change here. Read §1 if you assert on the 403 body of `POST /system-setup/init`, or if a test suite of yours resets the database to replay system setup |
+
+---
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server@11.36.5
+```
+
+---
+
+## 1. `LTNS_0050` now names both of the conditions that raise it
+
+**Were you affected?** Only if you assert on the exact message text of a 403 from
+`POST /system-setup/init`, or if you reset the database in tests to replay the setup flow.
+
+### What changed
+
+`createInitialAdmin()` refuses under **two** different conditions, and both raise
+`ErrorCode.SYSTEM_SETUP_NOT_AVAILABLE` / `LTNS_0050`:
+
+1. Users already exist.
+2. The initial-admin setup is **claimed** — the marker `{ _id: 'initial-admin' }` in
+   `system-setup-locks` is held.
+
+Up to 11.36.4 the message described only the first:
+
+```diff
+- System setup not available - users already exist
++ System setup not available - users already exist, or the initial-admin setup is claimed
+```
+
+Both translations (`de`, `en`) moved with it, as did the `@ApiResponse` description on the
+controller and the sample response in the module README.
+
+**The code is unchanged.** It is still `LTNS_0050`, still HTTP 403. If you branch on the error
+**code** — which is what the framework asks you to do — nothing breaks. Only an assertion on the
+literal message string does.
+
+### Why this was worth a release
+
+The second guard is reachable in an ordinary situation that looks nothing like it: the marker is
+released **only when creation fails**, so it outlives a SUCCESSFUL setup by design. Emptying `users`
+to replay the flow therefore leaves setup refused — and the response said *"users already exist"*
+while `users` was empty. That is a message pointing away from the cause, in a flow that runs once per
+deployment and is rarely instrumented. It cost a consumer project a full CI cycle to find.
+
+Since 11.36.5 the claim path also logs a warning naming the collection, the release-on-failure
+semantics and the stale window, so the server log answers the question even when the response body is
+all you kept.
+
+### If you reset the database in tests
+
+Emptying `users` is not enough. Drop the claim collection alongside it:
+
+```typescript
+// deleteMany, not drop: dropping `users` would drop its unique email index,
+// which is what prevents a duplicate admin.
+for (const col of ['users', 'account', 'session', 'system-setup-locks']) {
+  await db.collection(col).deleteMany({});
+}
+```
+
+That is the framework's own reset, executed on every test run in
+`tests/stories/system-setup.e2e-spec.ts`.
+
+Two things that will otherwise mislead you:
+
+- **`GET /system-setup/status` does not see the claim.** `needsSetup` is computed from the user
+  count alone, so it reports `true` while init is refused.
+- **The stale window is measured from when the claim was taken**, not from your reset — five minutes
+  after the successful setup. A suite resetting ten minutes after boot is not blocked at all, one
+  resetting immediately is. That is why the symptom looks intermittent and gets misfiled as flake.
+
+---
+
+## 2. A signed-in caller is now IDENTIFIED on a public endpoint
+
+**Were you affected?** Only if **both** are true: you run **legacy JWT auth without Better-Auth**,
+and you have endpoints carrying `@Roles(RoleEnum.S_EVERYONE)` (or no `@Roles` at all).
+
+**With Better-Auth enabled, nothing changes for you.** `CoreBetterAuthMiddleware` is applied via
+`forRoutes('(.*)')`, so it already ran on public routes and set `request.user` before any guard.
+`BetterAuthRolesGuard` is deliberately unchanged for that reason.
+
+### What changed
+
+`RolesGuard` returned `true` for a public endpoint **without ever looking at the token**, so
+`request.user` stayed unset and a signed-in caller arrived anonymous:
+
+```typescript
+@Get('search')
+@Roles(RoleEnum.S_EVERYONE)          // public — intended, anonymous visitors may search
+search(@CurrentUser() user) {
+  // `user` was ALWAYS undefined, even with a valid Bearer token on the request
+}
+```
+
+Since 11.36.5 the guard identifies first — Better-Auth, then Passport JWT — with **every** failure
+swallowed. A missing, expired or malformed token still means "anonymous": this can never turn a
+public endpoint into a 401. **Access control is untouched.** Only identification is restored.
+
+An anonymous caller still yields `undefined`, not a falsy-but-present value — worth stating because
+Passport itself answers `false`, and code written as `if ('user' in request)` would have noticed.
+
+### What to check before updating
+
+Nothing needs changing to keep working. This is a list of places where behaviour may legitimately
+widen, in order of how likely they are to surprise you:
+
+1. **`@Restricted(S_SELF)` / `@Restricted(S_CREATOR)` fields un-hide for their owner.** They
+   evaluate against `currentUser`; with `undefined` they always stripped. On a public endpoint
+   returning records the caller owns, those fields now appear in the response — for that caller
+   only. The decorator sanctions it, but if you treated "this route is public, therefore always
+   anonymous, therefore owner-only fields never appear" as a redaction boundary, that assumption
+   no longer holds. Audit public endpoints whose response models carry owner-restricted fields.
+2. **`checkRights()` starts receiving a user on these routes.** Both common shapes flip:
+   `if (!user) return data;` was a bypass on public routes and is now enforced; `if (!user) throw …`
+   refused and now passes.
+3. **Ownership stamping.** `CrudService` writes `createdBy: serviceOptions?.currentUser?.id`. A
+   public create called by a signed-in caller now records ownership where it previously wrote
+   `undefined` — which later unlocks `S_CREATOR`-restricted fields on that record.
+4. **`securityCheck(user)` on your models** now sees a real user on public endpoints, so a branch
+   you wrote as "the anonymous path" stops being the only one taken.
+
+Find the places worth looking at:
+
+```bash
+# public endpoints that branch on the absence of a user
+grep -rn "S_EVERYONE" src/server/ --include="*.ts" | grep -v ".spec.ts"
+grep -rn "if (!currentUser\|if (!user" src/server/ --include="*.ts" | grep -v ".spec.ts"
+```
+
+### If you relied on the old behaviour
+
+A public endpoint that must be anonymous for **everyone** should not read `currentUser` at all.
+If you built on "public implies anonymous", make it explicit — the guard no longer enforces it
+for you as a side effect.
+
+### Also reachable now: `/ai/mcp` in legacy-JWT deployments
+
+`POST /ai/mcp` is `@Roles(S_EVERYONE)` and self-authenticating. In a legacy-JWT deployment it
+previously answered 401 for everyone, because `req.user` was unset and no other resolution path
+applied. It now authenticates any holder of a valid legacy access token. This is not an elevation —
+the MCP server is still built per user, with the tool registry's role filter and the per-owner
+session binding intact — but a surface you may have considered unreachable is now live. If you do
+not want it, set `ai.mcp: false`.
+
+---
+
+## Compatibility Notes
+
+| Pattern | Status |
+|---------|--------|
+| Branching on `error.code === 'LTNS_0050'` | Unaffected — the code did not change |
+| Asserting the literal 403 message string | **Update the expected string** (§1) |
+| Displaying the translated message to users | Unaffected, but the text is longer and now mentions the claim |
+| Overriding `CoreSystemSetupService.createInitialAdmin()` | Unaffected — the guard order and the thrown exception are unchanged |
+| A test suite that resets only `users` | Was already broken since 11.33; now the message and the server log say so (§1) |
+| Legacy JWT + public endpoints reading `currentUser` | **Now receives a user** (§2) |
+| Better-Auth enabled (hybrid or IAM-only) | Unaffected by §2 — the middleware already identified the caller |
+| Public endpoint returning owner-restricted fields | Those fields now reach the owner (§2.1) — audit before shipping |
+
+---
+
+## Troubleshooting
+
+**`POST /system-setup/init` returns 403 and `users` is empty.**
+The claim is held. Check `db.getCollection('system-setup-locks').find()`. Either another instance is
+running the setup, or a previous successful setup left the marker. Drop the collection, or wait five
+minutes from when the claim was taken.
+
+**A test asserting the 403 message fails after the update.**
+Expected — see §1. Prefer asserting the error **code** (`LTNS_0050`), which is stable.

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)