@lenne.tech/nest-server 11.41.7 → 11.41.8

package/migration-guides/11.41.7-to-11.41.8.md

@@ -0,0 +1,135 @@
+# Migration Guide: 11.41.7 → 11.41.8
+
+## Overview
+
+| Category              | Details                                                                                       |
+| --------------------- | --------------------------------------------------------------------------------------------- |
+| **Security**          | better-auth 1.7.7 is now the minimum — critical account takeover in < 1.7.7 (§1)                |
+| **Breaking Changes**  | None at runtime: 11.41.8 still works on better-auth 1.7.1 (§2). The peer floor rises to 1.7.7, so pnpm reports an unmet peer until you raise the pins |
+| **Data**              | Nothing to migrate. The boot drops one index that better-auth 1.7.0–1.7.2 left behind (§2)        |
+| **Tooling**           | The override guard reports unused overrides; husky and its hooks are gone (§3)                  |
+| **Migration Effort**  | Raise three pins in the API — and two in the app of a fullstack project, in the same change     |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+pnpm add better-auth@1.7.7 @better-auth/passkey@1.7.7 @better-auth/core@1.7.7
+pnpm run build && pnpm test
+```
+
+Fullstack projects raise the app in the same change — `@lenne.tech/nuxt-extensions` 1.18.4 and
+`better-auth` / `@better-auth/passkey` 1.7.7 in `projects/app` — see §1.
+
+Vendor-mode projects pick up the core update, and raise the same pins.
+
+## What's New in 11.41.8
+
+### 1. better-auth 1.7.7 is the minimum
+
+[GHSA-965c-763c-88jm](https://github.com/better-auth/better-auth/security/advisories/GHSA-965c-763c-88jm)
+(critical): an OAuth state value can be used as a Magic Link to sign in as another user. It covers
+`better-auth >= 1.4.0-beta.18, < 1.7.7`; 1.7.7 is fixed. A project is exposed when it registers the
+`magicLink` plugin — through `betterAuth.options.plugins` — next to a social or Generic OAuth
+provider, with OAuth state stored in the database (the default when a database is configured). An
+attacker who knows a user's email address then gets a normal session for that user, without access
+to the mailbox.
+
+At the time of writing the advisory lives only in better-auth's own repository, not yet in the
+database `pnpm audit` reads, so **your audit does not report it**. Do not wait for it to.
+
+The framework's peer range is now `>=1.7.7 <1.8.0` for `better-auth`, `@better-auth/passkey` and
+`@better-auth/core` (the floor is forced anyway: `@better-auth/passkey` 1.7.7 itself requires
+`better-auth ^1.7.7`). A project still on 1.7.1 gets an unmet-peer warning, and stays vulnerable
+if it uses Magic Link.
+
+**What to do:**
+
+```bash
+# projects/api (or a standalone API)
+pnpm add better-auth@1.7.7 @better-auth/passkey@1.7.7 @better-auth/core@1.7.7
+
+# projects/app of a fullstack project — in the SAME change
+pnpm add @lenne.tech/nuxt-extensions@1.18.4 better-auth@1.7.7 @better-auth/passkey@1.7.7
+```
+
+API and app must resolve the same better-auth version: they speak one protocol, and a split
+breaks flows like 2FA activation with errors that name neither side. In a monorepo,
+`check-workspace-consistency` fails the check when they differ.
+
+Upstream's upgrade note for 1.7.7, worth passing on to whoever deploys: upgrade every server that
+shares verification storage at the same time, have users request new Magic Links, and expect
+OAuth / SAML sign-ins that were in progress during the deploy to need a restart. No database
+migration is required. Custom `verification.storeIdentifier.overrides` rules, and storage code that
+inspects verification identifiers, must now expect the `magic-link:` and `auth-state:` prefixes.
+
+### 2. better-auth dropped its issuer schema again — what that means for your data
+
+better-auth 1.7.0 keyed accounts by `(issuer, accountId)`, and nest-server 11.37–11.41.7 followed:
+every account it wrote carried an `issuer`, and the boot backfilled it on older rows. better-auth
+1.7.3 restored the 1.6 schema — accounts keyed by `(providerId, accountId)` — and no longer reads or
+writes the field. 11.41.8 follows whichever line is INSTALLED, so the upgrade stays compatible in
+both directions:
+
+| You run | nest-server 11.41.8 does |
+| ------- | ------------------------ |
+| better-auth 1.7.7 (the target) | writes no `issuer`; on boot drops the unique `(issuer, accountId)` index better-auth 1.7.0–1.7.2 left behind, and forgets the old backfill marker |
+| better-auth 1.7.1 (pins not raised yet) | behaves exactly like 11.41.7: writes the `issuer`, runs the backfill. Still vulnerable (§1) — raise the pins |
+
+**Why the index has to go.** With the field no longer written, the index treats every new account
+as having the same, missing issuer, so a user who holds the same account ID at two providers can no
+longer link the second one. MongoDB has no `NOT NULL`, so dropping the index is the whole cleanup —
+upstream's 1.7 upgrade guide says the same. The log shows it once:
+`Dropped the unique index "account_issuer_accountId_uidx" on account(issuer, accountId)`.
+
+**Existing `issuer` values stay.** better-auth 1.7.3+ ignores them, and keeping them is what makes a
+rollback safe.
+
+**Rolling back to 11.41.7** (better-auth 1.7.1) works for password users: that version's backfill
+runs again on boot — 11.41.8 deleted its completion marker for exactly this — and gives the issuer
+back to every credential account written in the meantime. better-auth recreates its index on first
+use. Social accounts LINKED while on 11.41.8 stay without an issuer; 11.41.7 reports them at boot,
+and they need the issuer set per provider before their next social sign-in.
+
+**Vendor mode on better-auth 1.7.1** builds as well: the core compiles against both lines.
+
+**Code that imported `createLocalAccountIssuer`** from `@better-auth/core/db` stops compiling with
+better-auth 1.7.3+, which removed it. Remove the call; accounts no longer carry an issuer.
+
+### 3. Tooling (this repository)
+
+- **The override guard reports unused overrides again.** `scripts/check-overrides.mjs` searched the
+  whole lockfile, where pnpm echoes every override into a top-level `overrides:` block — so an
+  override whose package had left the tree still counted as "in the tree". It now reads only the
+  resolved part. A project that copied the guard (nest-server-starter ships it since 11.41.7) may
+  see new `UNUSED` lines after updating it: warnings, not failures — remove the dead entry.
+- **husky is gone.** Its `prepare` script had been removed in 2024, so the hooks never ran; the
+  `check` script is the gate. `.husky/`, `.lintstagedrc.json`, `extras/sync-version.ts` and the
+  devDependencies `husky` and `find-file-up` (used only by that hook) were removed. Nothing ships
+  in the package from any of them.
+
+## Compatibility Notes
+
+| Pattern | Status |
+| ------- | ------ |
+| `better-auth` / `@better-auth/*` pinned at 1.7.1 | Unmet peer — raise to 1.7.7 (§1) |
+| API on 1.7.7, app still on 1.7.1 | Breaks auth flows — raise both in one change (§1) |
+| `magicLink` plugin with an OAuth provider, on < 1.7.7 | Account takeover — raise now (§1) |
+| nest-server 11.41.8 with better-auth still at 1.7.1 | Works as before (§2); unmet-peer warning, still vulnerable |
+| Rollback to 11.41.7 after upgrading | Works — the backfill runs again (§2) |
+| Own code calling `createLocalAccountIssuer` | Remove it — gone in better-auth 1.7.3+ (§2) |
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| ------- | ----- | --- |
+| `unmet peer better-auth@">=1.7.7 <1.8.0": found 1.7.1` | Old pin | `pnpm add better-auth@1.7.7 @better-auth/passkey@1.7.7 @better-auth/core@1.7.7` |
+| 2FA activation or passkey sign-in fails with a generic client error after updating | API and app on different better-auth versions | Pin the same version in both |
+| `check-workspace-consistency` fails on better-auth | Same | Same |
+| New `UNUSED` lines from `check:overrides` | The guard sees dead overrides now (§3) | Remove the entry it names |
+| `Could not drop the legacy unique (issuer, accountId) index` at boot | The database user may not drop indexes | `db.account.dropIndex("account_issuer_accountId_uidx")` once, by hand |
+| `E11000 duplicate key … account_issuer_accountId_uidx` when linking an account | The legacy index is still there | Same |
+
+## Module Documentation
+
+- [BetterAuth INTEGRATION-CHECKLIST](../src/core/modules/better-auth/INTEGRATION-CHECKLIST.md) — Step 0, the peer dependencies

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.41.7",
+  "version": "11.41.8",
   "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",
@@ -144,10 +144,10 @@
     "@aws-sdk/client-s3": ">=3.1045.0 <4",
     "@aws-sdk/lib-storage": ">=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",
+    "@better-auth/core": ">=1.7.7 <1.8.0",
+    "@better-auth/passkey": ">=1.7.7 <1.8.0",
     "@tus/s3-store": ">=2.0.5 <3",
-    "better-auth": ">=1.7.1 <1.8.0",
+    "better-auth": ">=1.7.7 <1.8.0",
     "bullmq": ">=5.16.0 <7",
     "ioredis": ">=5.0.0 <7"
   },
@@ -184,8 +184,8 @@
     "@aws-sdk/client-s3": "3.1145.0",
     "@aws-sdk/lib-storage": "3.1145.0",
     "@aws-sdk/s3-request-presigner": "3.1145.0",
-    "@better-auth/core": "1.7.1",
-    "@better-auth/passkey": "1.7.1",
+    "@better-auth/core": "1.7.7",
+    "@better-auth/passkey": "1.7.7",
     "@compodoc/compodoc": "2.0.0",
     "@nestjs/cli": "11.0.24",
     "@nestjs/schematics": "11.1.0",
@@ -203,11 +203,9 @@
     "@types/passport": "1.0.17",
     "@vitest/coverage-v8": "4.1.11",
     "ansi-colors": "4.1.3",
-    "better-auth": "1.7.1",
+    "better-auth": "1.7.7",
     "bullmq": "6.3.11",
     "cross-env": "10.1.0",
-    "find-file-up": "2.0.1",
-    "husky": "9.1.7",
     "ioredis": "6.0.0",
     "nodemon": "3.1.14",
     "npm-watch": "0.13.0",

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

@@ -18,14 +18,14 @@ From `@lenne.tech/nest-server` 11.37.0, better-auth is **not** a dependency of t
 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
+pnpm add better-auth@1.7.7 @better-auth/passkey@1.7.7 @better-auth/core@1.7.7
 ```
 
 **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
+> packages are installed silently at whatever version satisfies `>=1.7.7 <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

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

@@ -1028,12 +1028,26 @@ Idempotent indices on `session`, `users`, `account` and `verification`, includin
 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.
+### 2. The account issuer — correctness (depends on the INSTALLED better-auth)
+
+better-auth 1.7.0–1.7.2 keyed accounts by `(issuer, accountId)`; 1.7.3 restored the 1.6 schema,
+`(providerId, accountId)`. The boot runs ONE of two steps, decided by what is installed
+(`core-better-auth-account-issuer.helper.ts`):
+
+- **better-auth 1.7.3+ (11.41.8+ requires it): `dropLegacyAccountIssuerIndex()`.** Databases that ran
+  1.7.0–1.7.2 (nest-server 11.37–11.41.7) carry a unique `(issuer, accountId)` index. With the field
+  no longer written it refuses a second provider with the same account ID, so the boot drops it —
+  recognised by shape, so a renamed collection or field is covered. Existing `issuer` values stay;
+  they are inert. The backfill marker is deleted, so a rollback to a better-auth that needs the
+  issuer runs the backfill again. Log line: `Dropped the unique index "…" on account(issuer,
+accountId)`. A failure is logged at `error` and the boot continues.
+- **better-auth 1.7.0–1.7.2: `backfillAccountIssuers()`, described below.** Kept for a project that
+  has not raised its better-auth pin yet.
+
+From better-auth 1.7.0 to 1.7.2 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. The backfill repairs those rows on the first boot after the upgrade.
 
 | Property         | Behaviour                                                                                                                                                                                    |
 | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

package/src/core/modules/better-auth/core-better-auth-account-issuer.helper.ts

@@ -0,0 +1,25 @@
+import * as betterAuthCoreDb from '@better-auth/core/db';
+
+/**
+ * The synthetic issuer better-auth 1.7.0–1.7.2 stores on credential accounts — or `undefined` when
+ * the installed better-auth no longer uses one.
+ *
+ * better-auth 1.7.0 keyed accounts by `(issuer, accountId)` and exported `createLocalAccountIssuer`
+ * to derive the credential issuer. 1.7.3 restored the 1.6 schema — accounts keyed by
+ * `(providerId, accountId)` — and removed both. This framework works with either line: its peer
+ * range starts at 1.7.7, but a project that has not raised its pin yet must keep signing users in.
+ * So every place that writes or repairs an account asks THIS function instead of importing the
+ * helper: a static import does not even compile against 1.7.3+, and an issuer written there would
+ * be dead data.
+ *
+ * Resolved at call time from the module namespace, never cached at load, so a test can swap it.
+ */
+export function legacyCredentialAccountIssuer(): string | undefined {
+  const create = (betterAuthCoreDb as unknown as Record<string, unknown>).createLocalAccountIssuer;
+  return typeof create === 'function' ? (create as (providerId: string) => string)('credential') : undefined;
+}
+
+/** Whether the installed better-auth keys accounts by `(issuer, accountId)` — 1.7.0 to 1.7.2. */
+export function usesLegacyAccountIssuer(): boolean {
+  return legacyCredentialAccountIssuer() !== undefined;
+}

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

@@ -1,4 +1,3 @@
-import { createLocalAccountIssuer } from '@better-auth/core/db';
 import { Injectable, Logger, Optional } from '@nestjs/common';
 import { InjectConnection } from '@nestjs/mongoose';
 import * as bcrypt from 'bcrypt';
@@ -19,6 +18,7 @@ const scryptPromise = (password: string, salt: string, keylen: number, options:
 
 import { RoleEnum } from '../../common/enums/role.enum';
 import { maskEmail } from '../../common/helpers/logging.helper';
+import { legacyCredentialAccountIssuer } from './core-better-auth-account-issuer.helper';
 
 /**
  * Interface for Better-Auth session user
@@ -531,16 +531,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.
+      // - issuer: ONLY while the installed better-auth is 1.7.0–1.7.2, which key accounts by
+      //   (issuer, accountId) — a row without it is not found, and the migrated user gets a 401 on
+      //   the very sign-in that triggered the migration. 1.7.3+ went back to (providerId,
+      //   accountId) and writes no issuer. Always derived from the helper, never hand-written.
+      const credentialIssuer = legacyCredentialAccountIssuer();
       await accountsCollection.insertOne({
         accountId: userIdHex,
         createdAt: now,
         id: this.generateId(),
-        issuer: createLocalAccountIssuer('credential'),
+        ...(credentialIssuer ? { issuer: credentialIssuer } : {}),
         password: passwordHash,
         providerId: 'credential',
         updatedAt: now,

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

@@ -73,27 +73,36 @@ export const BETTER_AUTH_CONFIG = 'BETTER_AUTH_CONFIG';
 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.
+ * better-auth's default names for the account collection and for fields 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.
+ * All are overridable by a consumer through `betterAuth.options.account.modelName` / `.fields.*`,
+ * 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 or an index better-auth does not
+ * use, and the operation then reports success by saying nothing.
+ *
+ * `issuer` is only used by better-auth 1.7.0–1.7.2; 1.7.3 restored the 1.6 schema (accounts keyed by
+ * `(providerId, accountId)` again). Its name is still needed on both lines: for the backfill while a
+ * project runs 1.7.0–1.7.2, and afterwards to recognise the unique index those versions left behind —
+ * see `CoreBetterAuthService.dropLegacyAccountIssuerIndex()`.
  */
 export const DEFAULT_ACCOUNT_MODEL_NAME = 'account';
 export const DEFAULT_ACCOUNT_ISSUER_FIELD = 'issuer';
+export const DEFAULT_ACCOUNT_ACCOUNT_ID_FIELD = 'accountId';
 
 /**
  * Collection holding one-shot completion markers for boot-time data migrations, and the marker id
- * of the `account.issuer` backfill (better-auth 1.7).
+ * of the `account.issuer` backfill.
+ *
+ * The backfill only runs while the installed better-auth still keys accounts by issuer (1.7.0–1.7.2,
+ * see `core-better-auth-account-issuer.helper.ts`). On 1.7.3+ the boot DELETES this marker instead:
+ * should the project roll back to a better-auth that needs the issuer, the backfill then runs again
+ * and repairs the accounts written in the meantime, rather than being skipped by a stale marker.
  *
  * 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.
+ * every replica pays a full pass over the account collection. 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,4 +1,3 @@
-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';
@@ -12,6 +11,7 @@ import { ConfigService } from '../../common/services/config.service';
 import { ErrorCode } from '../error-code/error-codes';
 import { resolveBetterAuthCookiePrefix } from './better-auth-cookie-prefix.helper';
 import { BetterAuthInstance } from './better-auth.config';
+import { legacyCredentialAccountIssuer, usesLegacyAccountIssuer } from './core-better-auth-account-issuer.helper';
 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';
@@ -21,6 +21,7 @@ import {
   BETTER_AUTH_CONFIG,
   BETTER_AUTH_COOKIE_DOMAIN,
   BETTER_AUTH_INSTANCE,
+  DEFAULT_ACCOUNT_ACCOUNT_ID_FIELD,
   DEFAULT_ACCOUNT_ISSUER_FIELD,
   DEFAULT_ACCOUNT_MODEL_NAME,
 } from './core-better-auth.constants';
@@ -113,12 +114,21 @@ export class CoreBetterAuthService implements OnModuleInit {
    *
    * Order matters: the backfill's update can use the `{ providerId: 1, userId: 1 }` index created
    * below, so indices come first.
+   *
+   * Which account step runs depends on the INSTALLED better-auth, not on this package's version:
+   * 1.7.0–1.7.2 key accounts by issuer and need the backfill; 1.7.3+ dropped the issuer and need the
+   * unique index those versions left behind removed instead. A project that has not raised its
+   * better-auth pin yet therefore keeps working exactly as before.
    */
   async onModuleInit(): Promise<void> {
     if (!this.isEnabled() || !this.connection?.db) return;
 
     await this.ensureIndices();
-    await this.backfillAccountIssuers();
+    if (usesLegacyAccountIssuer()) {
+      await this.backfillAccountIssuers();
+    } else {
+      await this.dropLegacyAccountIssuerIndex();
+    }
   }
 
   /**
@@ -195,6 +205,11 @@ export class CoreBetterAuthService implements OnModuleInit {
   protected async backfillAccountIssuers(): Promise<void> {
     if (!this.isEnabled() || !this.connection?.db) return;
 
+    // Only better-auth 1.7.0–1.7.2 key accounts by issuer. On 1.7.3+ there is nothing to backfill —
+    // and nothing to derive the value from.
+    const credentialIssuer = legacyCredentialAccountIssuer();
+    if (!credentialIssuer) return;
+
     const db = this.connection.db;
 
     // The consumer can rename both of these through `betterAuth.options.account`, which
@@ -243,7 +258,7 @@ export class CoreBetterAuthService implements OnModuleInit {
           pending.map((doc) => ({
             updateOne: {
               filter: { _id: doc._id },
-              update: { $set: { [issuerField]: createLocalAccountIssuer('credential') } },
+              update: { $set: { [issuerField]: credentialIssuer } },
             },
           })),
           { ordered: false },
@@ -306,6 +321,75 @@ export class CoreBetterAuthService implements OnModuleInit {
     }
   }
 
+  /**
+   * Drops the unique `(issuer, accountId)` index better-auth 1.7.0–1.7.2 created on the account
+   * collection, and forgets the issuer-backfill marker. Runs on better-auth 1.7.3+ only.
+   *
+   * better-auth 1.7.0 keyed accounts by `(issuer, accountId)`, and its MongoDB adapter created that
+   * index lazily. 1.7.3 restored the 1.6 schema — `(providerId, accountId)` — and no longer writes
+   * `issuer`. The index stays behind in every database that ran those versions (this framework
+   * required them from 11.37.0 to 11.41.7), and with the field gone it treats every new account as
+   * having the same, missing issuer: a user who holds the same account ID at two providers can no
+   * longer link the second one. MongoDB has no `NOT NULL`, so dropping the index is the whole
+   * cleanup — upstream's 1.7 upgrade guide, "Account identity keeps the provider key". Existing
+   * `issuer` values are inert and stay, which also keeps a rollback possible.
+   *
+   * The marker is deleted for the same rollback: back on a better-auth that needs the issuer, the
+   * backfill must run again and repair the accounts written in the meantime instead of being
+   * skipped as "already completed".
+   *
+   * The index is recognised by its SHAPE — unique, keyed exactly on the issuer and account-id fields
+   * — not by name: better-auth derives the name from the collection and field names (by default
+   * `account_issuer_accountId_uidx`), and a consumer can rename both through
+   * `betterAuth.options.account`.
+   *
+   * Idempotent and cheap: one `listIndexes` and one `deleteOne` per boot. Never fatal — a failure is
+   * logged as an error and the server still starts.
+   */
+  protected async dropLegacyAccountIssuerIndex(): Promise<void> {
+    if (!this.isEnabled() || !this.connection?.db) return;
+
+    const db = this.connection.db;
+    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;
+    const accountIdField: string = accountOptions?.fields?.accountId ?? DEFAULT_ACCOUNT_ACCOUNT_ID_FIELD;
+
+    try {
+      await db.collection(BACKFILL_MARKER_COLLECTION).deleteOne({ _id: ACCOUNT_ISSUER_BACKFILL_ID as any });
+
+      const accounts = db.collection(modelName);
+      let indexes: { key?: Record<string, unknown>; name?: string; unique?: boolean }[];
+      try {
+        indexes = await accounts.indexes();
+      } catch (error) {
+        // A collection that does not exist yet has no index to drop (NamespaceNotFound).
+        if ((error as { code?: number })?.code === 26) return;
+        throw error;
+      }
+
+      const legacy = indexes.filter(
+        (index) =>
+          index.unique === true &&
+          !!index.name &&
+          Object.keys(index.key ?? {}).join(',') === `${issuerField},${accountIdField}`,
+      );
+      for (const index of legacy) {
+        await accounts.dropIndex(index.name as string);
+        this.logger.log(
+          `Dropped the unique index "${index.name}" on ${modelName}(${issuerField}, ${accountIdField}): ` +
+            'better-auth >= 1.7.3 no longer writes the issuer, and the index would refuse new accounts.',
+        );
+      }
+    } catch (error) {
+      this.logger.error(
+        `Could not drop the legacy unique (${issuerField}, ${accountIdField}) index on "${modelName}": ` +
+          `${error instanceof Error ? error.message : 'unknown'}. Linking an account whose ID another ` +
+          'provider already uses will fail until it is dropped by hand.',
+      );
+    }
+  }
+
   /**
    * Checks if better-auth is enabled and initialized
    * Returns true only if:

package/src/core/modules/system-setup/core-system-setup.service.ts

@@ -1,10 +1,10 @@
-import { createLocalAccountIssuer } from '@better-auth/core/db';
 import { ForbiddenException, Injectable, Logger, OnApplicationBootstrap } from '@nestjs/common';
 import { InjectConnection } from '@nestjs/mongoose';
 import { isEmail } from 'class-validator';
 import { Connection } from 'mongoose';
 
 import { ConfigService } from '../../common/services/config.service';
+import { legacyCredentialAccountIssuer } from '../better-auth/core-better-auth-account-issuer.helper';
 import { CoreBetterAuthUserMapper } from '../better-auth/core-better-auth-user.mapper';
 import { CoreBetterAuthService } from '../better-auth/core-better-auth.service';
 import { ErrorCode } from '../error-code/error-codes';
@@ -305,18 +305,22 @@ export class CoreSystemSetupService implements OnApplicationBootstrap {
 
       // Hash password and create credential account
       const hashedPassword = await context.password.hash(normalizedPassword);
-      // better-auth >= 1.7 keys accounts by (issuer, accountId) and requires the
-      // issuer. Credential accounts have no real issuer, so better-auth derives a
-      // synthetic one — always via this helper, never a hand-written literal:
-      // the format is better-auth's to change, and a copy of it would silently
-      // stop matching the accounts better-auth writes itself.
+      // better-auth 1.7.0–1.7.2 key accounts by (issuer, accountId) and require the issuer;
+      // credential accounts carry a synthetic one, always derived via the helper, never a
+      // hand-written literal. better-auth 1.7.3+ went back to (providerId, accountId) and knows no
+      // issuer field, so the helper answers `undefined` there and nothing is written.
+      //
+      // Cast to the adapter's OWN parameter type: against better-auth 1.7.0–1.7.2 that type requires
+      // `issuer`, and a conditional spread reads as optional — a vendored core compiled against
+      // those versions would otherwise not build.
+      const credentialIssuer = legacyCredentialAccountIssuer();
       await context.internalAdapter.linkAccount({
         accountId: iamUser.id,
-        issuer: createLocalAccountIssuer('credential'),
+        ...(credentialIssuer ? { issuer: credentialIssuer } : {}),
         password: hashedPassword,
         providerId: 'credential',
         userId: iamUser.id,
-      });
+      } as Parameters<typeof context.internalAdapter.linkAccount>[0]);
 
       // Sync to nest-server users collection
       const syncedUser = await this.userMapper.linkOrCreateUser({