@lenne.tech/nest-server 11.36.5 → 11.37.0

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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.36.5",
+  "version": "11.37.0",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -83,14 +83,13 @@
     "url": "https://github.com/lenneTech/nest-server/issues"
   },
   "engines": {
-    "node": ">= 22",
+    "node": ">= 22.12",
     "pnpm": "^11.0.0"
   },
   "packageManager": "pnpm@11.13.1+sha512.b2fc7683b8a6525414e7d13e1ba28caaddde96bf66ec540bfaeb7e702b81f3e0be4d1f295edf7f9fe0396740a8dce4509c582ddf79891f4543fea32d37645f25",
   "dependencies": {
     "@apollo/server": "5.5.1",
     "@as-integrations/express5": "1.1.2",
-    "@better-auth/passkey": "1.6.26",
     "@getbrevo/brevo": "6.0.3",
     "@modelcontextprotocol/sdk": "1.30.0",
     "@nestjs/apollo": "13.4.5",
@@ -108,7 +107,6 @@
     "@tus/server": "2.4.4",
     "@types/supertest": "7.2.1",
     "bcrypt": "6.0.0",
-    "better-auth": "1.6.26",
     "class-transformer": "0.5.1",
     "class-validator": "0.15.1",
     "compression": "1.8.1",
@@ -144,7 +142,10 @@
   "peerDependencies": {
     "@aws-sdk/client-s3": ">=3.1045.0 <4",
     "@aws-sdk/s3-request-presigner": ">=3.1045.0 <4",
+    "@better-auth/core": ">=1.7.1 <1.8.0",
+    "@better-auth/passkey": ">=1.7.1 <1.8.0",
     "@tus/s3-store": ">=2.0.5 <3",
+    "better-auth": ">=1.7.1 <1.8.0",
     "bullmq": ">=5.16.0 <7",
     "ioredis": ">=5.0.0 <7"
   },
@@ -155,9 +156,18 @@
     "@aws-sdk/s3-request-presigner": {
       "optional": true
     },
+    "@better-auth/core": {
+      "optional": false
+    },
+    "@better-auth/passkey": {
+      "optional": false
+    },
     "@tus/s3-store": {
       "optional": true
     },
+    "better-auth": {
+      "optional": false
+    },
     "bullmq": {
       "optional": true
     },
@@ -168,6 +178,8 @@
   "devDependencies": {
     "@aws-sdk/client-s3": "3.1115.0",
     "@aws-sdk/s3-request-presigner": "3.1115.0",
+    "@better-auth/core": "1.7.1",
+    "@better-auth/passkey": "1.7.1",
     "@compodoc/compodoc": "2.0.0",
     "@nestjs/cli": "11.0.24",
     "@nestjs/schematics": "11.1.0",
@@ -186,6 +198,7 @@
     "@types/passport": "1.0.17",
     "@vitest/coverage-v8": "4.1.11",
     "ansi-colors": "4.1.3",
+    "better-auth": "1.7.1",
     "bullmq": "6.2.0",
     "find-file-up": "2.0.1",
     "husky": "9.1.7",

package/src/core/modules/better-auth/INTEGRATION-CHECKLIST.md

@@ -2,7 +2,7 @@
 
 **For integrating BetterAuth into projects using `@lenne.tech/nest-server`.**
 
-> **Estimated time:** 10-15 minutes
+> **Estimated time:** 10-15 minutes (plus Step 0 on a fresh integration)
 
 **Need customization?** See [CUSTOMIZATION.md](./CUSTOMIZATION.md) for:
 
@@ -12,6 +12,29 @@
 
 ---
 
+## Step 0: Install the Peer Dependencies (required from 11.37.0)
+
+From `@lenne.tech/nest-server` 11.37.0, better-auth is **not** a dependency of this package. It is a
+non-optional **peer dependency**, so your project declares and owns the version:
+
+```bash
+pnpm add better-auth@1.7.1 @better-auth/passkey@1.7.1 @better-auth/core@1.7.1
+```
+
+**Pin all three to the same exact version** — no `^`, no `~`. They are one release train, and a
+mixed set fails in ways the type checker does not catch.
+
+> **Do not rely on `pnpm install` to remind you.** On pnpm's default `autoInstallPeers: true` the
+> packages are installed silently at whatever version satisfies `>=1.7.1 <1.8.0` — your build stays
+> green while the version is unpinned and free to drift. Verify with `pnpm why better-auth`.
+
+**Why peers rather than dependencies:** in a fullstack project the frontend talks to better-auth
+too. When this package owned the version, the API and the app could silently end up on different
+better-auth versions with incompatible payload shapes. Owning it in your own manifest makes that a
+single, visible decision.
+
+---
+
 ## Choose Your Scenario
 
 | Scenario                         | Use When                        | CoreModule Signature                                     | Steps |

package/src/core/modules/better-auth/README.md

@@ -30,6 +30,7 @@ const config = {
 - [Features](#features)
 - [Quick Integration](#quick-integration-for-claude-code--ai-assistants)
 - [Project Integration Guide](#project-integration-guide-required-steps)
+- [Boot-Time Behaviour](#boot-time-behaviour)
 - [Configuration](#configuration)
 - [REST API Endpoints](#rest-api-endpoints)
 - [GraphQL API](#graphql-api)
@@ -1015,6 +1016,61 @@ const config = {
 - Full flexibility for specialized plugins
 - No package updates needed for new Better-Auth plugins
 
+## Boot-Time Behaviour
+
+`CoreBetterAuthService.onModuleInit()` runs two steps against the database before the application
+starts listening. Both are `protected`, so a subclass can override either — **an override of
+`onModuleInit()` that does not call `super.onModuleInit()` skips both.**
+
+### 1. `ensureIndices()` — performance
+
+Idempotent indices on `session`, `users`, `account` and `verification`, including a TTL index that
+expires unconsumed verification and password-reset documents. Failures are logged at `warn` and do
+not block the boot: these help speed, not correctness.
+
+### 2. `backfillAccountIssuers()` — correctness (11.37.0+)
+
+From better-auth 1.7 an account is keyed by `(issuer, accountId)` and the sign-in route filters on
+it verbatim. Rows written by better-auth 1.6 have no `issuer` field, so **every existing password
+user would be locked out by the upgrade**, with a bare 401 and nothing in the log to explain it.
+This step repairs those rows on the first boot after the upgrade.
+
+| Property         | Behaviour                                                                                                                                                                                    |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Scope            | Credential accounts only. OAuth/SSO rows are reported, never rewritten — see below                                                                                                           |
+| Idempotency      | Structural: only rows missing the field are selected                                                                                                                                         |
+| Repeat cost      | A completion marker in `better-auth-backfills` short-circuits later boots to one `_id` lookup. Neither backfill query is indexable, so without it every boot would scan the whole collection |
+| Schema overrides | Collection and field names are resolved from the running better-auth instance; a customised name is logged at `warn`                                                                         |
+| Partial failure  | The write is unordered, so one bad row cannot shadow the rest. The marker is **not** written, and the next boot retries                                                                      |
+| Failure          | Logged at `error`; the boot continues. A server that starts with a loud error beats one that will not start                                                                                  |
+
+**Log lines to expect on the first boot after upgrading:**
+
+| Line                                                           | Meaning                                                                                                |
+| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `Backfilled account.issuer on N credential account(s)`         | Success — those N users can sign in again                                                              |
+| `Backfilled N/M credential accounts. X user(s) CANNOT sign in` | Partial. Usually a duplicate `(issuer, accountId)` pair from an earlier migration. Resolve and restart |
+| `Could not backfill the account issuer: …`                     | The operation failed entirely. Affected users cannot sign in until it succeeds                         |
+| `At least one non-credential account has no "issuer"`          | See below — act before the next social sign-in                                                         |
+| `Backfilling the account issuer against a customised schema`   | You renamed the account model or issuer field                                                          |
+
+**Why OAuth/SSO rows are not backfilled.** `local:credential` is a pure function of the provider id
+and therefore derivable. An OAuth issuer is not — it is either the provider's real OIDC issuer or
+the synthetic `local:oauth:<providerId>` fallback, decided per provider. Guessing would not fail
+loudly: better-auth falls back to matching the user by the provider-asserted email and implicitly
+links a **second** account row; if that email has changed, it creates a **new user** and orphans the
+old account together with its provider tokens, which no unlink will ever remove. So those rows are
+reported and the decision stays with the project. Set the issuer per provider **before** the first
+social sign-in after the upgrade — see
+[migration-guides/11.36.x-to-11.37.0.md](../../../../migration-guides/11.36.x-to-11.37.0.md) §4.
+
+> **Do not add `issuer` to this package's own reads of the `account` collection**
+> (`syncPasswordChangeToIam`, `migrateAccountToIam`, `getMigrationStatus`). They filter on
+> `providerId` alone on purpose, so they keep working on rows the backfill has not reached yet —
+> which matters most when the backfill has failed.
+
+---
+
 ## Module Setup
 
 See the [Project Integration Guide](#project-integration-guide-required-steps) at the top of this document for complete step-by-step instructions.
@@ -1895,6 +1951,14 @@ When a user is deleted:
    db.account.findOne({ userId: ObjectId('...'), providerId: 'credential' });
    ```
 
+   From better-auth 1.7 the row must ALSO carry `issuer: 'local:credential'`. A row matching only
+   `providerId` is not usable — better-auth keys accounts by `(issuer, accountId)` and will not find
+   it, so sign-in answers 401 while this query happily reports that the account exists:
+
+   ```javascript
+   db.account.findOne({ issuer: 'local:credential', providerId: 'credential', userId: ObjectId('...') });
+   ```
+
 3. Check server logs for sync warnings:
    ```
    [CoreUserService] Failed to sync password to IAM...

package/src/core/modules/better-auth/core-better-auth-user.mapper.ts

@@ -1,3 +1,4 @@
+import { createLocalAccountIssuer } from '@better-auth/core/db';
 import { Injectable, Logger, Optional } from '@nestjs/common';
 import { InjectConnection } from '@nestjs/mongoose';
 import * as bcrypt from 'bcrypt';
@@ -509,10 +510,16 @@ export class CoreBetterAuthUserMapper {
       // Store account matching Better-Auth's format:
       // - userId: ObjectId referencing users._id
       // - accountId: string version of users._id
+      // - issuer: from better-auth >= 1.7 accounts are keyed by (issuer,
+      //   accountId), and credential accounts carry a synthetic issuer. Writing
+      //   the row without it produces an account better-auth cannot find, so the
+      //   migrated user gets a 401 on the very sign-in that triggered the
+      //   migration. Always derive it from the helper, never hand-write it.
       await accountsCollection.insertOne({
         accountId: userIdHex,
         createdAt: now,
         id: this.generateId(),
+        issuer: createLocalAccountIssuer('credential'),
         password: passwordHash,
         providerId: 'credential',
         updatedAt: now,

package/src/core/modules/better-auth/core-better-auth.constants.ts

@@ -71,3 +71,29 @@ export const BETTER_AUTH_CONFIG = 'BETTER_AUTH_CONFIG';
  * Declared `@Optional()` in the CoreBetterAuthService constructor.
  */
 export const BETTER_AUTH_COOKIE_DOMAIN = 'BETTER_AUTH_COOKIE_DOMAIN';
+
+/**
+ * better-auth's default name for the account collection, and for the `issuer` field inside it.
+ *
+ * Both are overridable by a consumer through `betterAuth.options.account.modelName` /
+ * `.fields.issuer`, which `better-auth.config.ts` spreads onto the resolved config verbatim. Any
+ * framework code touching that collection directly MUST resolve the real names from the running
+ * instance and fall back to these — a hardcoded name silently addresses a collection better-auth
+ * does not use, which on the issuer backfill means every password user stays locked out while the
+ * operation reports success by saying nothing.
+ */
+export const DEFAULT_ACCOUNT_MODEL_NAME = 'account';
+export const DEFAULT_ACCOUNT_ISSUER_FIELD = 'issuer';
+
+/**
+ * Collection holding one-shot completion markers for boot-time data migrations, and the marker id
+ * of the `account.issuer` backfill (better-auth 1.7).
+ *
+ * The marker exists for cost, not for correctness: the backfill is idempotent and safe to repeat,
+ * but its filters (`$exists: false`, `$ne`) cannot use an index, so without a marker every boot of
+ * every replica pays a full pass over the account collection — forever, and inside the `await` that
+ * precedes `app.listen()`. Versioned in the id so a future backfill of the same field can run
+ * again without clearing this one.
+ */
+export const BACKFILL_MARKER_COLLECTION = 'better-auth-backfills';
+export const ACCOUNT_ISSUER_BACKFILL_ID = 'account-issuer-backfill-v1';