@lenne.tech/nest-server 11.41.6 → 11.41.8

package/src/core/common/services/core-s3.service.ts

@@ -74,6 +74,16 @@ export class CoreS3Service implements OnApplicationShutdown, OnModuleInit {
    */
   protected presigner?: typeof import('@aws-sdk/s3-request-presigner');
 
+  /**
+   * Lazy-imported `@aws-sdk/lib-storage`, used to upload a stream whose length is unknown.
+   *
+   * Three states, and the third is the point: `undefined` means "not tried yet", a module means
+   * "available", and `null` means "tried and absent". Without the `null` the import would be
+   * retried on every single upload, and since the absence is permanent that is a resolver miss per
+   * request plus a repeated warning in the log.
+   */
+  protected multipartUploader?: null | typeof import('@aws-sdk/lib-storage');
+
   constructor(protected readonly configService: ConfigService) {
     const raw = this.configService.getFastButReadOnly<IS3Config | undefined>('s3');
     if (!raw || raw.enabled === false) {
@@ -189,6 +199,10 @@ export class CoreS3Service implements OnApplicationShutdown, OnModuleInit {
       ...(accessKeyId && secretAccessKey ? { credentials: { accessKeyId, secretAccessKey } } : {}),
     });
 
+    // Resolved at boot rather than on the first upload, so a missing optional peer is reported
+    // where operators look — the startup log — instead of during the first large upload.
+    await this.loadMultipartUploader();
+
     await this.verifyBuckets();
   }
 
@@ -263,10 +277,26 @@ export class CoreS3Service implements OnApplicationShutdown, OnModuleInit {
   /**
    * Upload an object to the main bucket.
    *
-   * A stream needs its length: without `Content-Length` the SDK switches to aws-chunked
-   * encoding and then fails on a missing `x-amz-decoded-content-length`, so a stream of
-   * unknown size is read into memory first. Pass `contentLength` whenever the size is
-   * known — that streams the body straight through instead of buffering it.
+   * A `PutObject` needs the body's length: without `Content-Length` the SDK switches to
+   * aws-chunked encoding and then fails on a missing `x-amz-decoded-content-length`. So pass
+   * `contentLength` whenever the size is known — that streams the body straight through as a
+   * single request.
+   *
+   * A stream of UNKNOWN length goes through a multipart upload instead (`@aws-sdk/lib-storage`),
+   * which is what that package exists for: it reads the stream in parts and needs no total up
+   * front. It used to be read into memory instead, which made the memory cost of an upload equal
+   * to its size — a multi-GB object then either threw "Array buffer allocation failed" or got the
+   * container OOM-killed at 100 % progress, taking every other in-flight request with it. That is
+   * not a hypothetical shape: any streamed HTTP upload has it, because a multipart request's
+   * `Content-Length` covers the whole envelope and therefore cannot be used as the object length.
+   *
+   * A KNOWN length above {@link CoreS3Service.MAX_SINGLE_PUT_BYTES} goes through the multipart
+   * upload as well: AWS S3 refuses a single PutObject that large with `EntityTooLarge`, which for a
+   * finished TUS upload means after the client has sent every byte.
+   *
+   * Without the optional peer dependency both cases behave exactly as before: an unknown length is
+   * read into memory, a known one goes up as one PutObject whatever its size (MinIO and RustFS
+   * accept that; AWS S3 does not above 5 GiB).
    */
   async putObject(
     key: string,
@@ -278,6 +308,15 @@ export class CoreS3Service implements OnApplicationShutdown, OnModuleInit {
 
     let payload: Buffer | Readable | string = body;
     let length = contentLength;
+    // Multipart for a stream of UNKNOWN length — nothing else carries it without buffering — and for
+    // one whose known length exceeds what S3 accepts in a single request.
+    if (this.isStream(body) && (length === undefined || length > CoreS3Service.MAX_SINGLE_PUT_BYTES)) {
+      const uploader = await this.loadMultipartUploader();
+      if (uploader) {
+        await this.putObjectMultipart(uploader, key, body, contentType, length);
+        return;
+      }
+    }
     if (this.isStream(body) && length === undefined) {
       payload = await this.collect(body);
       length = payload.length;
@@ -318,6 +357,69 @@ export class CoreS3Service implements OnApplicationShutdown, OnModuleInit {
     await send();
   }
 
+  /**
+   * The multipart uploader, or `undefined` when the optional peer dependency is absent.
+   *
+   * Absence is NOT an error here, unlike the missing `@aws-sdk/client-s3` in `onModuleInit`:
+   * multipart is an optimisation of a path that already works by buffering, so a project that
+   * never installs it keeps the previous behaviour instead of failing to boot. The cost of that
+   * choice is memory, which is why the caller's doc states it.
+   */
+  protected async loadMultipartUploader(): Promise<typeof import('@aws-sdk/lib-storage') | undefined> {
+    if (this.multipartUploader !== undefined) {
+      return this.multipartUploader ?? undefined;
+    }
+    try {
+      this.multipartUploader = await import('@aws-sdk/lib-storage');
+    } catch {
+      // `null`, not `undefined`: the field doubles as the "already tried" marker, and a failed
+      // import must not be retried on every upload.
+      this.multipartUploader = null;
+      this.logger.warn(
+        'Streaming an S3 upload of unknown length falls back to buffering it in memory because the ' +
+          'optional peer dependency "@aws-sdk/lib-storage" is not installed. Run: pnpm add @aws-sdk/lib-storage',
+      );
+    }
+    return this.multipartUploader ?? undefined;
+  }
+
+  /**
+   * Upload a stream of unknown length as a multipart upload.
+   *
+   * Memory stays bounded by the uploader's defaults — parts of 5 MiB, at most four in flight —
+   * whatever the object's size. A stream that ends within the first part is sent as one ordinary
+   * PutObject by `Upload` itself, so a small file costs no multipart round trips.
+   *
+   * No `guardBodyStream` here, and that is deliberate: the guard exists because the SDK pipes a
+   * `PutObject` body into its request without listening for the source's `error`, so a failed
+   * source surfaces as a successful upload of a truncated object. `Upload` does listen — a source
+   * error rejects `done()` and the already-uploaded parts are aborted — so wrapping it would add a
+   * second error path without adding a guarantee.
+   */
+  protected async putObjectMultipart(
+    uploader: typeof import('@aws-sdk/lib-storage'),
+    key: string,
+    body: Readable,
+    contentType?: string,
+    contentLength?: number,
+  ): Promise<void> {
+    const { client, config } = this.requireInit();
+    const upload = new uploader.Upload({
+      client,
+      params: {
+        Body: body,
+        Bucket: config.bucket,
+        // A known total lets `Upload` size its parts (`ceil(total / 10 000)`, at least 5 MiB) so the
+        // 10 000-part limit holds, and refuse a stream that yields a different NUMBER of parts than
+        // that total implies (it checks the part count, not the byte count). Not sent per part.
+        ...(contentLength === undefined ? {} : { ContentLength: contentLength }),
+        ...(contentType ? { ContentType: contentType } : {}),
+        Key: key,
+      },
+    });
+    await upload.done();
+  }
+
   /**
    * Shield the SDK from a REQUEST-BODY stream that can fail, and keep the cause.
    *
@@ -397,6 +499,12 @@ export class CoreS3Service implements OnApplicationShutdown, OnModuleInit {
    */
   static readonly MAX_COPY_OBJECT_BYTES = 5 * 1024 * 1024 * 1024;
 
+  /**
+   * Largest object a single `PutObject` can carry (AWS S3 hard limit). {@link CoreS3Service.putObject}
+   * sends a known length above it as a multipart upload instead.
+   */
+  static readonly MAX_SINGLE_PUT_BYTES = 5 * 1024 * 1024 * 1024;
+
   /**
    * Build the `CopySource` value for {@link CoreS3Service.copyObject}
    */
@@ -453,13 +561,23 @@ export class CoreS3Service implements OnApplicationShutdown, OnModuleInit {
    * Whether an object exists in the main bucket
    */
   async objectExists(key: string): Promise<boolean> {
+    return (await this.statObject(key)) !== null;
+  }
+
+  /**
+   * Size and content type of an object in the main bucket, or `null` when it does not exist.
+   *
+   * One HEAD request. This is how the length of an object uploaded WITHOUT a known length is
+   * learned afterwards: the stored object is the authority on its own size.
+   */
+  async statObject(key: string): Promise<null | { contentLength?: number; contentType?: string }> {
     const { client, config, sdk } = this.requireInit();
     try {
-      await client.send(new sdk.HeadObjectCommand({ Bucket: config.bucket, Key: key }));
-      return true;
+      const result = await client.send(new sdk.HeadObjectCommand({ Bucket: config.bucket, Key: key }));
+      return { contentLength: result.ContentLength, contentType: result.ContentType };
     } catch (error: any) {
       if (error?.$metadata?.httpStatusCode === 404 || error?.name === 'NotFound') {
-        return false;
+        return null;
       }
       throw error;
     }

package/src/core/modules/ai/README.md

@@ -621,6 +621,14 @@ the server log; the response carries only a stable `#LTNS_0901` code.
   framework's existing auth) — the MCP session is bound to that user, and
   `tools/list` / `tools/call` are filtered to and executed with their permissions.
 - Unauthenticated requests get `401` with a `WWW-Authenticate` header.
+- A session id the server does not know — which every restart produces, because the
+  transport map is process memory — gets **`404`**, and so does another user's id. 404
+  is the status the MCP spec has a client react to by sending a fresh `initialize`, so
+  clients recover from a deploy on their own rather than sitting dead until someone
+  reconnects by hand. A request with **no** session id and no `initialize` body still
+  gets `400`: there is nothing to recover, and a 404 would start a reconnect loop.
+- Answering a foreign id `404` rather than `403` is deliberate — a 403 would confirm
+  that the id exists, and the id travels in a response header and through client logs.
 
 ### Multi-replica / sticky sessions
 

package/src/core/modules/ai/core-ai-mcp.controller.ts

@@ -121,6 +121,27 @@ export class CoreAiMcpController implements OnModuleDestroy {
         this.foreignSession(res, owner);
         return;
       }
+
+      // A session id the client still holds that no replica knows — the state every restart
+      // produces, because the transport map is process memory. 404 is the only status a client
+      // reacts to by starting a fresh session itself (the spec requires it to), and it is what the
+      // SDK's own server returns for a mismatched id.
+      //
+      // Falling through to a new transport instead, as this did until now, looked like a silent
+      // recovery and was not one: after a restart the client's next request is a `tools/call` or
+      // `tools/list`, never an `initialize`, so the fresh transport's `validateSession()` answered
+      // `400 Bad Request: Server not initialized` — the same dead session, one layer down, and a
+      // 400 is a status no client recovers from. Found in a consumer project whose own older copy
+      // of this controller had the identical defect: after every deploy, every connected client
+      // stayed dead until somebody reconnected by hand.
+      //
+      // An `initialize` carrying a stale id still gets a new session rather than a 404: a client
+      // that keeps sending the old id would otherwise loop. No SDK client does that — it skips
+      // `initialize` entirely once its transport has an id — but the case costs one check.
+      if (!this.isInitializeRequest(req.body)) {
+        res.status(404).json({ error: 'Unknown or expired MCP session' });
+        return;
+      }
     }
 
     if (!entry) {
@@ -216,6 +237,18 @@ export class CoreAiMcpController implements OnModuleDestroy {
     return null;
   }
 
+  /**
+   * Whether the body is an `initialize` — the one request that legitimately starts a session.
+   *
+   * A batch counts when any member is an initialize, matching how the SDK transport reads it.
+   */
+  protected isInitializeRequest(body: any): boolean {
+    if (Array.isArray(body)) {
+      return body.some((message: any) => message?.method === 'initialize');
+    }
+    return body?.method === 'initialize';
+  }
+
   /**
    * Whether the OAuth 2.1 layer is enabled via `ai.mcp.oauth`.
    */

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/file/INTEGRATION-CHECKLIST.md

@@ -88,6 +88,31 @@ If some files are genuinely public and others are not, do not solve it with a ro
 record a visibility flag in the metadata and branch in `checkRights()`, or expose a separate public
 route for exactly the public files and leave the core routes gated.
 
+### 6. Switching to the S3 driver — in this order
+
+Each step fails on its own if skipped, and only the first one fails loudly:
+
+1. **Forward the services to `super()`.** `FileService` must call
+   `super(connection, 'fs', { configService, s3Service })`, as the reference implementation does. With
+   `super(connection)` the S3 store counts as unavailable and `file.storage: 's3'` fails the boot
+   with "that storage is not available".
+2. **Install the S3 packages as `dependencies`, not `devDependencies`:** `@aws-sdk/client-s3` and
+   `@aws-sdk/lib-storage` (same version), plus `@aws-sdk/s3-request-presigner` for
+   `s3.presignedDownloads`. A production image installed with `--prod` otherwise boots without them.
+   Vendor mode has them installed already (the vendored core references their types) — check which
+   section they are in.
+3. **Count stored files across all three metadata collections.** `fs.files` is GridFS only; the
+   filesystem driver records in `filesystem-files` and S3 in `s3-files`. Project code that
+   aggregates sizes or counts directly — a quota, a statistic — must cover all three, or it reads 0
+   after the switch and the quota never refuses anything. `findFileInfo()` already merges every
+   store.
+4. **Then switch the driver** — `file.storage: 's3'`, or leave it unset and let `s3.bucket` derive
+   it. Files written before stay readable: reads consult every store.
+
+An `s3` block with a `bucket` turns `CoreS3Service` on whatever `file.storage` says (TUS, where enabled, stages
+uploads in S3 as soon as it is on), so it needs `@aws-sdk/client-s3` at boot. To prepare the block
+without activating it, set `enabled: false`.
+
 ## Pick your project class first — the whole model is one dial with five settings
 
 `file.access` is the per-file rule as a DECLARATION instead of code. Until 11.35.0 the framework shipped
@@ -201,14 +226,17 @@ personal or medical, a per-file rule is not optional.
 
 ## Common Mistakes
 
-| Mistake                                            | Symptom                                  | Fix                                                                                                                    |
-| -------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| Overriding `getFileById` to add Swagger decorators | `file.downloadRoles` silently ignored    | Don't override; document at class level                                                                                |
-| Overriding without re-declaring `@Get(...)`        | Route 404s for everyone, no error logged | Don't override                                                                                                         |
-| `downloadRoles: []`                                | Warning logged, default applied          | Use a non-empty array; `[]` would read as "no roles required" and open the route                                       |
-| Expecting `metadata` back from `getFileInfo()`     | `undefined`                              | Use `getRawFileInfo()` inside `checkRights()`                                                                          |
-| `downloadRoles: ['member']` with multiTenancy      | Works from code, fails from `<img>`      | Both file classes carry `@SkipTenantCheck()`; roles resolve against `user.roles`. Use `checkRights()` for tenant rules |
-| Signed-in user can upload via TUS but not download | 403 on their own file                    | `tus.roles` and `file.downloadRoles` are separate. Add an owner to the metadata and authorize per file                 |
-| Rule narrows only `'id'` / `'filename'`            | `findFileInfo()` returns every file      | Refuse `'filterArgs'`; force a per-user filter server-side with `{ force: true }`                                      |
-| Treating the file id as unguessable                | Enumerable inventory                     | Ids share a per-process random part and an incrementing counter — authorize every read, do not rely on the id          |
-| Approving the caller's `filterArgs` as "narrowed"  | Bypass via a different filter shape      | `filterArgs` is client-controlled. Override the filter; never approve it                                               |
+| Mistake                                                        | Symptom                                     | Fix                                                                                                                    |
+| -------------------------------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Overriding `getFileById` to add Swagger decorators             | `file.downloadRoles` silently ignored       | Don't override; document at class level                                                                                |
+| Overriding without re-declaring `@Get(...)`                    | Route 404s for everyone, no error logged    | Don't override                                                                                                         |
+| `downloadRoles: []`                                            | Warning logged, default applied             | Use a non-empty array; `[]` would read as "no roles required" and open the route                                       |
+| Expecting `metadata` back from `getFileInfo()`                 | `undefined`                                 | Use `getRawFileInfo()` inside `checkRights()`                                                                          |
+| `downloadRoles: ['member']` with multiTenancy                  | Works from code, fails from `<img>`         | Both file classes carry `@SkipTenantCheck()`; roles resolve against `user.roles`. Use `checkRights()` for tenant rules |
+| Signed-in user can upload via TUS but not download             | 403 on their own file                       | `tus.roles` and `file.downloadRoles` are separate. Add an owner to the metadata and authorize per file                 |
+| Rule narrows only `'id'` / `'filename'`                        | `findFileInfo()` returns every file         | Refuse `'filterArgs'`; force a per-user filter server-side with `{ force: true }`                                      |
+| Treating the file id as unguessable                            | Enumerable inventory                        | Ids share a per-process random part and an incrementing counter — authorize every read, do not rely on the id          |
+| Approving the caller's `filterArgs` as "narrowed"              | Bypass via a different filter shape         | `filterArgs` is client-controlled. Override the filter; never approve it                                               |
+| `super(connection)` in `FileService` with `file.storage: 's3'` | Boot fails: "that storage is not available" | Forward `{ configService, s3Service }` — step 6                                                                        |
+| S3 packages in `devDependencies`                               | Production image cannot load S3             | Move them to `dependencies` — step 6                                                                                   |
+| A quota aggregating only `fs.files`                            | Reads 0 on the S3 / filesystem driver       | Aggregate `fs.files`, `filesystem-files` and `s3-files` — step 6                                                       |