@lenne.tech/nest-server 11.36.4 → 11.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.36.4",
+  "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/ai/core-ai-mcp.controller.ts

@@ -18,9 +18,15 @@ import { CoreAiMcpService } from './services/core-ai-mcp.service';
  * Exposes the AI tool registry to external MCP clients. The request must carry a
  * valid Bearer token (or session); the handler resolves the user via
  * {@link CoreAiMcpController.resolveUser} (which reuses `req.user` and falls back to
- * verifying the Bearer token directly, since `@Roles(S_EVERYONE)` does not populate
- * `req.user`). The MCP session is bound to that user and only their permitted tools
- * are exposed/executed.
+ * verifying the Bearer token directly). Since 11.36.5 `@Roles(S_EVERYONE)` DOES populate
+ * `req.user` — the guard identifies without denying — so the fallback is now a second line
+ * of defence rather than the only path. One consequence worth knowing: in a legacy-JWT
+ * deployment this endpoint 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. That is not an elevation — the server is still built per user with
+ * the registry's role filter and the per-owner session binding — but it is a surface that
+ * was effectively unreachable before. The MCP session is bound to that user and only their
+ * permitted tools are exposed/executed.
  *
  * `@Roles(S_EVERYONE)` lets the request reach the handler (the guard would
  * otherwise reject), and the handler performs the MCP-specific 401 with a

package/src/core/modules/auth/guards/roles.guard.ts

@@ -147,7 +147,14 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
 
     // If no roles required, or S_EVERYONE is set, allow access without authentication
     // This allows public endpoints (without @Roles decorator or with S_EVERYONE) to work
+    //
+    // Access is granted either way, but the caller is still IDENTIFIED when they sent a valid
+    // token: returning early here left `request.user` unset, so a signed-in user hitting a
+    // public endpoint arrived as anonymous. Endpoints that are public AND personalise for
+    // signed-in callers — a search ranking by the caller's own location, a list marking the
+    // caller's own entries — silently lost that personalisation, with no error anywhere.
     if (!roles || !roles.some((value) => !!value) || roles.includes(RoleEnum.S_EVERYONE)) {
+      await this.tryIdentifyOptionalUser(context);
       return true;
     }
 
@@ -339,6 +346,67 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
     return user;
   }
 
+  /**
+   * Identify the caller on a PUBLIC endpoint without ever denying access.
+   *
+   * Mirrors the authentication order of the protected path (Better-Auth first, Passport JWT
+   * second) but treats every failure as "anonymous" instead of raising: a missing, expired or
+   * malformed token must not turn a public endpoint into a 401. It only sets `request.user`,
+   * so `@CurrentUser()` and `serviceOptions.currentUser` see a signed-in caller again.
+   *
+   * ANONYMOUS MUST STAY ABSENT. Passport's verify callback answers `false` — not `undefined` —
+   * when a request carries no usable credentials, and `MixinAuthGuard` assigns that verbatim.
+   * Without the normalisation at the end, every anonymous request to a public route would come
+   * out of here with `request.user === false` where it previously had no `user` at all. That is
+   * invisible to `!!user` and to `user?.id`, and visible to a handler that types the parameter
+   * `User`, tests `'user' in request`, or forwards it into `serviceOptions.currentUser`. Pinned
+   * by the `userType` assertions in tests/public-endpoint-identity.e2e-spec.ts.
+   */
+  protected async tryIdentifyOptionalUser(context: ExecutionContext): Promise<void> {
+    try {
+      const request = this.getRequest(context);
+      if (!request || request.user) {
+        return;
+      }
+
+      this.resolveServices();
+
+      if (this.betterAuthService?.isEnabled()) {
+        const user = await this.verifyBetterAuthTokenFromContext(context);
+        if (user) {
+          request.user = user;
+          return;
+        }
+      }
+
+      const result = super.canActivate(context);
+      if (isObservable(result)) {
+        await firstValueFrom(result);
+      } else {
+        await result;
+      }
+    } catch (error) {
+      // Never denies — but "the caller sent no usable token" and "the strategy itself failed" are
+      // not the same thing, and a bare `catch {}` makes them indistinguishable. A rotated secret,
+      // an unreachable database inside `validate()`, or a throwing user lookup would degrade every
+      // PUBLIC endpoint to anonymous while protected ones 401 — a split brain with nothing in the
+      // log to explain it. `debug`, not `warn`: the ordinary case (no credentials, expired token)
+      // reaches here too and must not be noise.
+      this.logger.debug(
+        `Optional identification failed on a public endpoint: ${
+          error instanceof Error ? error.message : 'Unknown error'
+        }`,
+      );
+    } finally {
+      // `finally`, not the try body: the catch above swallows a throw from Passport, and that
+      // path can have assigned a falsy user before throwing.
+      const request = this.getRequest(context);
+      if (request && !request.user && 'user' in request) {
+        delete request.user;
+      }
+    }
+  }
+
   /**
    * Integrate request from GraphQL
    */

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';

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

@@ -1,3 +1,4 @@
+import { createLocalAccountIssuer } from '@better-auth/core/db';
 import { BadRequestException, Inject, Injectable, Logger, OnModuleInit, Optional } from '@nestjs/common';
 import { InjectConnection } from '@nestjs/mongoose';
 import { Request } from 'express';
@@ -14,7 +15,15 @@ import { BetterAuthInstance } from './better-auth.config';
 import { isJwtShaped } from './core-better-auth-token.helper';
 import { BetterAuthSessionUser } from './core-better-auth-user.mapper';
 import { convertExpressHeaders, parseCookieHeader, signCookieValueIfNeeded } from './core-better-auth-web.helper';
-import { BETTER_AUTH_CONFIG, BETTER_AUTH_COOKIE_DOMAIN, BETTER_AUTH_INSTANCE } from './core-better-auth.constants';
+import {
+  ACCOUNT_ISSUER_BACKFILL_ID,
+  BACKFILL_MARKER_COLLECTION,
+  BETTER_AUTH_CONFIG,
+  BETTER_AUTH_COOKIE_DOMAIN,
+  BETTER_AUTH_INSTANCE,
+  DEFAULT_ACCOUNT_ISSUER_FIELD,
+  DEFAULT_ACCOUNT_MODEL_NAME,
+} from './core-better-auth.constants';
 
 /**
  * Result of a session validation
@@ -94,12 +103,31 @@ export class CoreBetterAuthService implements OnModuleInit {
   }
 
   /**
-   * Ensure performance indices exist on the session, users, account and verification collections.
-   * Indices are idempotent — calling createIndex on an existing index is a no-op.
+   * Boot steps for the better-auth integration.
+   *
+   * Two jobs live here and they are deliberately separate methods: ensuring indices is a
+   * PERFORMANCE concern that repeats forever and degrades gracefully (hence `warn`), while the
+   * issuer backfill is a CORRECTNESS concern that should happen once and locks users out when it
+   * does not (hence `error`). Keeping them in one method made those two severities look like one
+   * decision.
+   *
+   * Order matters: the backfill's update can use the `{ providerId: 1, userId: 1 }` index created
+   * below, so indices come first.
    */
   async onModuleInit(): Promise<void> {
     if (!this.isEnabled() || !this.connection?.db) return;
 
+    await this.ensureIndices();
+    await this.backfillAccountIssuers();
+  }
+
+  /**
+   * Ensure performance indices exist on the session, users, account and verification collections.
+   * Indices are idempotent — calling createIndex on an existing index is a no-op.
+   */
+  protected async ensureIndices(): Promise<void> {
+    if (!this.connection?.db) return;
+
     try {
       const db = this.connection.db;
 
@@ -130,6 +158,154 @@ export class CoreBetterAuthService implements OnModuleInit {
     }
   }
 
+  /**
+   * Backfills `account.issuer` on rows written before better-auth 1.7.
+   *
+   * From 1.7 an account is keyed by (issuer, accountId), and sign-in filters on
+   * it verbatim:
+   *
+   *   account.providerId === 'credential' && account.issuer === credentialIssuer
+   *
+   * A row written by 1.6 has no `issuer` at all, so that comparison can never
+   * hold: every existing password user would be locked out by the upgrade
+   * itself, with a 401 and nothing in the logs to explain it. This closes that
+   * gap on the first boot after the upgrade.
+   *
+   * Idempotent — the filter only matches rows still missing the field, so the
+   * second start updates nothing.
+   *
+   * Scope is deliberately limited to credential accounts, where the issuer is
+   * derivable without guessing. OAuth accounts are NOT touched: their issuer
+   * depends on the provider (a real OIDC issuer, or the synthetic
+   * `local:oauth:<id>` fallback), and writing the wrong one would not fail
+   * loudly — it would create a second account on the next social sign-in. Those
+   * rows are reported instead, so the decision stays with the project.
+   *
+   * ONE THING NOT TO "TIDY UP": this package's own reads of the `account`
+   * collection filter on `providerId` alone — `syncPasswordChangeToIam`,
+   * `migrateAccountToIam` and `getMigrationStatus` in
+   * core-better-auth-user.mapper.ts. Adding `issuer` to those filters looks like
+   * consistency and is a regression. This backfill is deliberately NON-FATAL: if
+   * it fails, the server still boots and logs an error. Reads that do not require
+   * the field keep working on un-backfilled rows — `getMigrationStatus` would
+   * otherwise report zero migrated users, and `syncPasswordChangeToIam` would
+   * stop finding the account it is meant to update. Only better-auth's own
+   * sign-in path needs the issuer, and that one is better-auth's code, not ours.
+   */
+  protected async backfillAccountIssuers(): Promise<void> {
+    if (!this.isEnabled() || !this.connection?.db) return;
+
+    const db = this.connection.db;
+
+    // The consumer can rename both of these through `betterAuth.options.account`, which
+    // better-auth.config.ts spreads onto the resolved config verbatim. Hardcoding them turns this
+    // whole method into a silent no-op on such a project: nothing matches, `modifiedCount` is 0,
+    // neither log line fires, and every password user is locked out while the operator's upgrade
+    // checklist is satisfied by silence in both directions.
+    const accountOptions = (this.authInstance as any)?.options?.account;
+    const modelName: string = accountOptions?.modelName ?? DEFAULT_ACCOUNT_MODEL_NAME;
+    const issuerField: string = accountOptions?.fields?.issuer ?? DEFAULT_ACCOUNT_ISSUER_FIELD;
+
+    try {
+      const accounts = db.collection(modelName);
+
+      // A completion marker, checked before anything expensive. Without it both queries below run
+      // on EVERY boot of EVERY replica, forever — and neither is indexable (`$exists: false` cannot
+      // appear in a partialFilterExpression, `$ne` is not selective), so each is a full pass over
+      // the account collection, awaited before the app starts listening. With the marker the steady
+      // state is a single `_id` lookup. `system-setup-locks` in CoreSystemSetupService is the
+      // precedent for this kind of once-per-deployment boot state.
+      const markers = db.collection(BACKFILL_MARKER_COLLECTION);
+      if (await markers.findOne({ _id: ACCOUNT_ISSUER_BACKFILL_ID as any })) {
+        this.logger.debug(`account.${issuerField} backfill already completed — skipping.`);
+        return;
+      }
+
+      if (modelName !== DEFAULT_ACCOUNT_MODEL_NAME || issuerField !== DEFAULT_ACCOUNT_ISSUER_FIELD) {
+        this.logger.warn(
+          `Backfilling the account issuer against a customised schema (collection "${modelName}", ` +
+            `field "${issuerField}"). Verify these match what better-auth actually writes.`,
+        );
+      }
+
+      const pending = await accounts
+        .find({ [issuerField]: { $exists: false }, providerId: 'credential' }, { projection: { _id: 1 } })
+        .toArray();
+
+      let backfilled = 0;
+
+      if (pending.length) {
+        // `ordered: false` is load-bearing. better-auth declares a UNIQUE index on
+        // (issuer, accountId); a single pre-existing duplicate would abort an ordered write and
+        // leave every row after it untouched — those users stay locked out, with one log line and
+        // a green boot. Unordered, one bad row costs only itself.
+        const result = await accounts.bulkWrite(
+          pending.map((doc) => ({
+            updateOne: {
+              filter: { _id: doc._id },
+              update: { $set: { [issuerField]: createLocalAccountIssuer('credential') } },
+            },
+          })),
+          { ordered: false },
+        );
+
+        backfilled = result.modifiedCount;
+
+        if (backfilled > 0) {
+          this.logger.log(
+            `Backfilled account.${issuerField} on ${backfilled} credential account(s) for better-auth >= 1.7. ` +
+              'Without it these users could not sign in.',
+          );
+        }
+
+        if (backfilled < pending.length) {
+          // Do NOT write the marker in this case — the next boot must retry the remainder.
+          this.logger.error(
+            `Backfilled ${backfilled}/${pending.length} credential accounts. ` +
+              `${pending.length - backfilled} user(s) CANNOT sign in until this is resolved manually. ` +
+              'The most likely cause is a duplicate (issuer, accountId) pair from an earlier partial migration.',
+          );
+          return;
+        }
+      } else {
+        this.logger.debug(`No account.${issuerField} backfill needed — no credential rows predate better-auth 1.7.`);
+      }
+
+      // Only a complete run earns the marker.
+      await markers.updateOne(
+        { _id: ACCOUNT_ISSUER_BACKFILL_ID as any },
+        { $set: { backfilled, completedAt: new Date(), issuerField, modelName } },
+        { upsert: true },
+      );
+
+      // Existence probe rather than a count: `$ne` cannot use an index, so counting to the end is a
+      // guaranteed collection scan for a log line. "At least one" is all the message needs to say.
+      const staleOther = await accounts.findOne(
+        { [issuerField]: { $exists: false }, providerId: { $ne: 'credential' } },
+        { projection: { _id: 1 } },
+      );
+
+      if (staleOther) {
+        this.logger.warn(
+          `At least one non-credential account has no "${issuerField}". better-auth >= 1.7 will not match it by ` +
+            '(issuer, accountId) — and such a sign-in does NOT simply fail: it falls back to matching the user by ' +
+            'the provider-asserted email and implicitly links a SECOND account row. If the provider-side email has ' +
+            'changed, a NEW user is created instead and the existing account is orphaned, together with the provider ' +
+            'tokens on the old row, which no unlink will ever remove. Set the issuer per provider BEFORE the first ' +
+            "social sign-in after this upgrade: the provider's real OIDC issuer, or the synthetic " +
+            '"local:oauth:<providerId>".',
+        );
+      }
+    } catch (error) {
+      // Correctness, not performance — say so loudly, but do not stop the boot:
+      // a server that starts with a warning beats one that will not start at all.
+      this.logger.error(
+        `Could not backfill the account issuer: ${error instanceof Error ? error.message : 'unknown'}. ` +
+          'Existing password users may be unable to sign in until this succeeds.',
+      );
+    }
+  }
+
   /**
    * Checks if better-auth is enabled and initialized
    * Returns true only if:

package/src/core/modules/error-code/error-codes.ts

@@ -468,12 +468,22 @@ export const LtnsErrors = {
   // System Setup Errors (LTNS_0050-LTNS_0059)
   // =====================================================
 
+  /**
+   * Raised by BOTH guards in `createInitialAdmin()`, which is why the message names both.
+   *
+   * The first guard refuses because users exist. The second refuses because the initial-admin
+   * claim in `system-setup-locks` is held — and that marker is removed only when creation FAILS,
+   * so it OUTLIVES a successful setup by design. A test suite that resets the database by
+   * emptying `users` therefore still hits the claim, and until 11.36.5 was told "users already
+   * exist" while the users collection was empty. That mismatch cost a consumer project a full CI
+   * cycle to diagnose, so the message now covers both conditions.
+   */
   SYSTEM_SETUP_NOT_AVAILABLE: {
     code: 'LTNS_0050',
-    message: 'System setup not available - users already exist',
+    message: 'System setup not available - users already exist, or the initial-admin setup is claimed',
     translations: {
-      de: 'System-Setup nicht verfügbar - es existieren bereits Benutzer.',
-      en: 'System setup not available - users already exist.',
+      de: 'System-Setup nicht verfügbar - es existieren bereits Benutzer, oder das Initial-Admin-Setup ist bereits beansprucht.',
+      en: 'System setup not available - users already exist, or the initial-admin setup is claimed.',
     },
   },
 

package/src/core/modules/system-setup/INTEGRATION-CHECKLIST.md

@@ -92,13 +92,14 @@ export class SystemSetupController extends CoreSystemSetupController {
 
 ## Common Mistakes
 
-| Mistake                                     | Symptom                          | Fix                                      |
-| ------------------------------------------- | -------------------------------- | ---------------------------------------- |
-| BetterAuth not enabled                      | 404 on endpoints or 403 on init  | Ensure `betterAuth` is configured        |
-| Calling init with existing users            | 403 "System setup not available" | Init only works on empty database        |
-| Password too short                          | 400 validation error             | Password must be at least 8 characters   |
-| Missing ENV password                        | Auto-creation silently skipped   | Set both `email` and `password` ENV vars |
-| `systemSetup: { enabled: false }` in config | 404 on endpoints                 | Remove the explicit disable              |
+| Mistake                                     | Symptom                          | Fix                                                                                                                                                                |
+| ------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| BetterAuth not enabled                      | 404 on endpoints or 403 on init  | Ensure `betterAuth` is configured                                                                                                                                  |
+| Calling init with existing users            | 403 "System setup not available" | Init requires an empty `users` collection                                                                                                                          |
+| Re-running init after a successful setup    | 403, even with an empty `users`  | The claim marker in `system-setup-locks` outlives a SUCCESSFUL setup (it is released only on failure) — drop that collection too, or wait 5 min for it to go stale |
+| Password too short                          | 400 validation error             | Password must be at least 8 characters                                                                                                                             |
+| Missing ENV password                        | Auto-creation silently skipped   | Set both `email` and `password` ENV vars                                                                                                                           |
+| `systemSetup: { enabled: false }` in config | 404 on endpoints                 | Remove the explicit disable                                                                                                                                        |
 
 ---