@lenne.tech/nest-server 12.0.0 → 12.1.0

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

@@ -10,24 +10,31 @@ import {
   Type,
 } from '@nestjs/common';
 import { APP_GUARD } from '@nestjs/core';
-import { getConnectionToken } from '@nestjs/mongoose';
-import mongoose, { Connection } from 'mongoose';
+import { getConnectionToken } from '../../common/persistence/mongo/mongoose-compat.js';
+import type { Connection } from 'mongoose';
 
 import { maskEmail } from '../../common/helpers/logging.helper.js';
+import { getPersistenceRuntime } from '../../common/persistence/persistence-runtime.registry.js';
 import { IBetterAuth, ICorsConfig } from '../../common/interfaces/server-options.interface.js';
 import { BrevoService } from '../../common/services/brevo.service.js';
 import { ConfigService } from '../../common/services/config.service.js';
 import { RolesGuardRegistry } from '../auth/guards/roles-guard-registry.js';
+import { ROLE_GUARD } from '../auth/guards/role-guard.token.js';
 import { isLegacyEndpointEnabled } from '../auth/helpers/legacy-endpoints.helper.js';
 import { BetterAuthRolesGuard } from './better-auth-roles.guard.js';
 import { BetterAuthTokenService } from './better-auth-token.service.js';
 import {
   AuthEmailCallbackOptions,
   BetterAuthInstance,
+  buildBetterAuthOptions,
+  type CreateBetterAuthOptions,
   CreateBetterAuthResult,
-  createBetterAuthInstance,
+  instantiateBetterAuth,
   OnPasswordResetCallback,
 } from './better-auth.config.js';
+import { applyBetterAuthSchema } from './better-auth-sql.helper.js';
+import { getBetterAuthSqlStore, setBetterAuthSqlStore } from './core-better-auth-sql.registry.js';
+import { BetterAuthSqlStore, type IamSqlQueryable } from './core-better-auth-sql.store.js';
 import { DefaultBetterAuthResolver } from './better-auth.resolver.js';
 import { CoreBetterAuthApiMiddleware } from './core-better-auth-api.middleware.js';
 import { CoreBetterAuthChallengeService } from './core-better-auth-challenge.service.js';
@@ -48,6 +55,8 @@ import {
 } from './core-better-auth.registry.js';
 import { CoreBetterAuthResolver } from './core-better-auth.resolver.js';
 import { CoreBetterAuthService } from './core-better-auth.service.js';
+import { newObjectId } from '../../common/persistence/mongo/mongoose-compat.js';
+import { requireMongoPackages } from '../../common/persistence/mongo/mongo-packages.js';
 
 /**
  * @deprecated Import from `./core-better-auth.constants` instead. Re-exported only
@@ -464,6 +473,38 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
     }
   }
 
+  /**
+   * Better-Auth on the database the `users` table lives in (one row per user, shared with the user model): on a SQL
+   * source its adapter runs on that source's application pool, and its tables are brought up to date before the
+   * instance exists — Better-Auth validates its schema as it starts.
+   */
+  private static async createInstance(options: CreateBetterAuthOptions): Promise<CreateBetterAuthResult | null> {
+    const storage = await getPersistenceRuntime()?.iamStorage();
+    setBetterAuthSqlStore(undefined);
+    const built = buildBetterAuthOptions({ ...options, sqlPool: storage?.pool });
+    if (!built) {
+      return null;
+    }
+    if (storage) {
+      await applyBetterAuthSchema(built.options, storage);
+    }
+    const result = instantiateBetterAuth(built);
+    if (storage) {
+      setBetterAuthSqlStore(new BetterAuthSqlStore(storage.users, result.instance, storage.pool as IamSqlQueryable));
+    }
+    return result;
+  }
+
+  /** The MongoDB database Better-Auth's adapter runs on, once the connection is up */
+  private static async mongoDatabase(): Promise<unknown> {
+    await this.waitForMongoConnection();
+    const db = requireMongoPackages('Better-Auth on MongoDB').mongoose.connection.db;
+    if (!db) {
+      throw new Error('MongoDB database not available');
+    }
+    return db;
+  }
+
   /**
    * Waits for mongoose connection to be ready using polling
    * This is more reliable than event-based waiting in test environments
@@ -472,6 +513,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
   private static async waitForMongoConnection(): Promise<void> {
     const maxAttempts = 60; // 60 attempts * 500ms = 30 seconds max
     const pollInterval = 500;
+    const { mongoose } = requireMongoPackages('Better-Auth on MongoDB (the user model is not routed to a SQL source)');
 
     for (let attempt = 0; attempt < maxAttempts; attempt++) {
       // Check if already connected
@@ -687,12 +729,9 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
             // Enable middleware registration
             this.betterAuthEnabled = true;
 
-            await this.waitForMongoConnection();
-
-            const db = mongoose.connection.db;
-            if (!db) {
-              throw new Error('MongoDB database not available');
-            }
+            // On a SQL source Better-Auth runs on that source's pool (createInstance()); MongoDB is neither awaited
+            // nor needed then — a project on PostgreSQL alone has none
+            const db = (await getPersistenceRuntime()?.iamStorage()) ? undefined : await this.mongoDatabase();
 
             this.configServiceInstance = configService;
 
@@ -706,7 +745,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
 
             // Note: Secret validation is now handled in createBetterAuthInstance
             // with fallback to jwt.secret, jwt.refresh.secret, or auto-generation
-            const result = createBetterAuthInstance({
+            const result = await this.createInstance({
               config,
               db,
               fallbackSecrets,
@@ -802,6 +841,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
    */
   static reset(): void {
     this.authInstance = null;
+    setBetterAuthSqlStore(undefined);
     this.initialized = false;
     this.initLogged = false;
     this.betterAuthEnabled = false;
@@ -894,12 +934,16 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
         // This callback is called by Better-Auth when email is verified
         // Sync nest-server's verified/verifiedAt fields with Better-Auth's emailVerified
         try {
+          const sql = getBetterAuthSqlStore();
           const db = this.mongoConnection?.db;
-          if (db) {
-            const { ObjectId } = await import('mongodb');
+          if (sql) {
+            // One row per user on SQL: Better-Auth's user id is the row's id
+            await sql.updateUser({ id: userId }, { verified: true, verifiedAt: new Date() });
+            this.logger.debug(`Email verified for user ${userId} - synced verified/verifiedAt`);
+          } else if (db) {
             await db
               .collection('users')
-              .updateOne({ _id: new ObjectId(userId) }, { $set: { verified: true, verifiedAt: new Date() } });
+              .updateOne({ _id: newObjectId(userId) }, { $set: { verified: true, verifiedAt: new Date() } });
             this.logger.debug(`Email verified for user ${userId} - synced verified/verifiedAt`);
           } else {
             this.logger.warn(`Cannot sync verifiedAt for user ${userId} - no database connection`);
@@ -1040,7 +1084,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
           inject: [getConnectionToken(), CoreBetterAuthEmailVerificationService, ConfigService],
           provide: BETTER_AUTH_INSTANCE,
           useFactory: async (
-            connection: Connection,
+            connection: Connection | null,
             emailVerificationService: CoreBetterAuthEmailVerificationService,
             configService: ConfigService,
           ) => {
@@ -1067,26 +1111,13 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
               serverEnv: options?.serverEnv,
             };
 
-            // Connection is now guaranteed to be established
-            let result: CreateBetterAuthResult | null;
-            const db = connection.db;
-            if (!db) {
-              // Fallback to global mongoose if connection.db is not yet available
-              await this.waitForMongoConnection();
-              const globalDb = mongoose.connection.db;
-              if (!globalDb) {
-                throw new Error('MongoDB database not available');
-              }
-              result = createBetterAuthInstance({
-                ...sharedInstanceOptions,
-                db: globalDb,
-              });
-            } else {
-              result = createBetterAuthInstance({
-                ...sharedInstanceOptions,
-                db,
-              });
-            }
+            // On a SQL source Better-Auth runs on that source's pool; on MongoDB on the injected connection, falling
+            // back to the global mongoose connection while its database is not yet available
+            const sqlStorage = await getPersistenceRuntime()?.iamStorage();
+            const result: CreateBetterAuthResult | null = await this.createInstance({
+              ...sharedInstanceOptions,
+              db: sqlStorage ? undefined : (connection?.db ?? (await this.mongoDatabase())),
+            });
             this.authInstance = result?.instance ?? null;
             this.resolvedCookieDomain = result?.cookieDomain;
 
@@ -1163,7 +1194,12 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
         ...(this.shouldRegisterRolesGuardGlobally && !RolesGuardRegistry.isRegistered()
           ? (() => {
               RolesGuardRegistry.markRegistered('CoreBetterAuthModule');
-              return [BetterAuthRolesGuard, { provide: APP_GUARD, useExisting: BetterAuthRolesGuard }];
+              return [
+                BetterAuthRolesGuard,
+                { provide: APP_GUARD, useExisting: BetterAuthRolesGuard },
+                // How CoreTenantGuard reaches it
+                { provide: ROLE_GUARD, useExisting: BetterAuthRolesGuard },
+              ];
             })()
           : []),
       ],

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

@@ -4,10 +4,11 @@ import {
   Injectable,
   Logger,
   OnApplicationBootstrap,
+  OnModuleDestroy,
   OnModuleInit,
   Optional,
 } from '@nestjs/common';
-import { InjectConnection } from '@nestjs/mongoose';
+import { InjectConnection } from '../../common/persistence/mongo/mongoose-compat.js';
 import {
   freshSessionMiddleware,
   requestOnlySessionMiddleware,
@@ -19,6 +20,7 @@ import { importJWK, jwtVerify } from 'jose';
 import type { Connection } from 'mongoose';
 
 import { shouldConvertSessionTokenToJwt } from '../../common/helpers/cookies.helper.js';
+import { type ExpirySweep, scheduleExpirySweep } from '../../common/persistence/expiry-sweep.js';
 import { maskEmail, maskToken } from '../../common/helpers/logging.helper.js';
 import { type IBetterAuth, ICookiesConfig } from '../../common/interfaces/server-options.interface.js';
 import { ConfigService } from '../../common/services/config.service.js';
@@ -47,6 +49,7 @@ import {
   DEFAULT_ACCOUNT_ISSUER_FIELD,
   DEFAULT_ACCOUNT_MODEL_NAME,
 } from './core-better-auth.constants.js';
+import { getBetterAuthSqlStore } from './core-better-auth-sql.registry.js';
 
 /**
  * Result of a session validation
@@ -103,8 +106,9 @@ export { BETTER_AUTH_CONFIG, BETTER_AUTH_COOKIE_DOMAIN } from './core-better-aut
  * ```
  */
 @Injectable()
-export class CoreBetterAuthService implements OnApplicationBootstrap, OnModuleInit {
+export class CoreBetterAuthService implements OnApplicationBootstrap, OnModuleDestroy, OnModuleInit {
   private readonly logger = new Logger(CoreBetterAuthService.name);
+  protected expirySweep?: ExpirySweep;
   private readonly config: IBetterAuth;
   private openApiSchema: IBetterAuthOpenApiDocument | undefined;
   private unavailableOperations: Set<string> | undefined;
@@ -145,7 +149,8 @@ export class CoreBetterAuthService implements OnApplicationBootstrap, OnModuleIn
    * better-auth pin yet therefore keeps working exactly as before.
    */
   async onModuleInit(): Promise<void> {
-    if (!this.isEnabled() || !this.connection?.db) return;
+    // Both steps concern MongoDB's collections: on a SQL source Better-Auth's migrator created the tables and indices
+    if (!this.isEnabled() || !this.connection?.db || getBetterAuthSqlStore()) return;
 
     await this.ensureIndices();
     if (usesLegacyAccountIssuer()) {
@@ -164,6 +169,34 @@ export class CoreBetterAuthService implements OnApplicationBootstrap, OnModuleIn
    */
   async onApplicationBootstrap(): Promise<void> {
     await this.prepareOpenApiSchema();
+    this.startExpirySweep();
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    // Before the data sources close their connections (onApplicationShutdown)
+    await this.expirySweep?.stop();
+  }
+
+  /**
+   * On a SQL source, removes expired sessions and verification values periodically (`scheduleExpirySweep()`): there is
+   * no TTL index, and Better-Auth deletes neither an expired session nor, unless one is looked up, an expired
+   * verification value. MongoDB keeps its TTL index and gets no sweep.
+   */
+  protected startExpirySweep(): void {
+    const sql = getBetterAuthSqlStore();
+    if (!this.isEnabled() || !sql || this.expirySweep) {
+      return;
+    }
+    this.expirySweep = scheduleExpirySweep(
+      'iam',
+      async () => {
+        const { sessions, verificationValues } = await sql.deleteExpired();
+        if (sessions || verificationValues) {
+          this.logger.debug(`Removed ${sessions} expired session(s) and ${verificationValues} verification value(s)`);
+        }
+      },
+      { logger: this.logger },
+    );
   }
 
   /**
@@ -1087,7 +1120,14 @@ export class CoreBetterAuthService implements OnApplicationBootstrap, OnModuleIn
    * @returns Session and user data, or null if not found/expired
    */
   async getSessionByToken(token: string): Promise<SessionResult> {
-    if (!this.isEnabled() || !this.connection?.db) {
+    if (!this.isEnabled()) {
+      return { session: null, user: null };
+    }
+    const sql = getBetterAuthSqlStore();
+    if (sql) {
+      return this.liveSession(() => sql.findSession(token), 'getSessionByToken');
+    }
+    if (!this.connection?.db) {
       return { session: null, user: null };
     }
 
@@ -1183,7 +1223,14 @@ export class CoreBetterAuthService implements OnApplicationBootstrap, OnModuleIn
    * @returns Session result with token, or null if no active session exists
    */
   async getActiveSessionForUser(userId: string): Promise<SessionResult> {
-    if (!this.isEnabled() || !this.connection?.db) {
+    if (!this.isEnabled()) {
+      return { session: null, user: null };
+    }
+    const sql = getBetterAuthSqlStore();
+    if (sql) {
+      return this.liveSession(() => sql.findActiveSession(userId), 'getActiveSessionForUser');
+    }
+    if (!this.connection?.db) {
       return { session: null, user: null };
     }
 
@@ -1259,6 +1306,23 @@ export class CoreBetterAuthService implements OnApplicationBootstrap, OnModuleIn
     }
   }
 
+  /**
+   * A session from the SQL store, refused once expired — the check the MongoDB lookups make on the document
+   */
+  protected async liveSession(lookup: () => Promise<null | SessionResult>, caller: string): Promise<SessionResult> {
+    try {
+      const found = await lookup();
+      if (!found?.session || (found.session.expiresAt && new Date(found.session.expiresAt) < new Date())) {
+        this.logger.debug(`${caller}: no live session`);
+        return { session: null, user: null };
+      }
+      return found;
+    } catch (error) {
+      this.logger.debug(`${caller} error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      return { session: null, user: null };
+    }
+  }
+
   // ===================================================================================================================
   // User Lookup Methods
   // ===================================================================================================================
@@ -1353,8 +1417,8 @@ export class CoreBetterAuthService implements OnApplicationBootstrap, OnModuleIn
         return this.verifyHs256Token(token);
       }
 
-      // For asymmetric algorithms (EdDSA, RS256, ES256), use JWKS
-      if (kid && this.connection) {
+      // For asymmetric algorithms (EdDSA, RS256, ES256), use JWKS — from MongoDB or the SQL source, whichever holds them
+      if (kid) {
         return this.verifyJwksToken(token, kid, alg);
       }
 
@@ -1412,17 +1476,22 @@ export class CoreBetterAuthService implements OnApplicationBootstrap, OnModuleIn
     email?: string;
     sub: string;
   }> {
-    if (!this.connection) {
+    const sql = getBetterAuthSqlStore();
+    if (!this.connection && !sql) {
       this.logger.debug('JWKS verification failed: no database connection');
       return null;
     }
 
     try {
-      // Fetch the JWKS public key from database
-      const jwksCollection = this.connection.collection('jwks');
-      let keyRecord = await jwksCollection.findOne({ id: kid });
+      // Fetch the JWKS public key from database (on SQL through Better-Auth's adapter, by its logical names)
+      const jwksCollection = this.connection?.collection('jwks');
+      let keyRecord = sql ? await sql.findJwk(kid) : await jwksCollection?.findOne({ id: kid });
 
-      if (!keyRecord) {
+      if (!keyRecord && sql) {
+        this.logger.debug(`No JWKS key found for kid: ${kid}`);
+        return null;
+      }
+      if (!keyRecord && jwksCollection) {
         // Try with _id as fallback (MongoDB ObjectId)
         const allKeys = await jwksCollection.find({}).toArray();
         const matchingKey = allKeys.find((k) => k.id === kid || k._id?.toString() === kid);

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

@@ -57,6 +57,16 @@ and pages over them, `checkRights()` reads them per request. A directory listing
 that, and sidecar files would reinvent an index the database already is. So `'filesystem'` moves the
 bytes off the database, not the bookkeeping.
 
+**Which database holds it follows `database`** (db-agnostic phase 4). The S3 and filesystem metadata
+are two framework models, `CoreS3File` and `CoreFilesystemFile`: on MongoDB the collections `s3-files`
+and `filesystem-files` as before, on a SQL default source (or with `database.models` naming another
+source) the tables `s3_files` and `filesystem_files`. Nothing changes in a project's `FileModule`.
+Code of your own that reads that metadata uses `fileMetadataCollection(connection, 's3' | 'filesystem')`
+— it answers the collection or the table behind the same operations — never `connection.db.collection('s3-files')`,
+which would look at MongoDB while the files are in the table. GridFS keeps bytes and metadata in MongoDB
+(`fs.files`), so without `file.storage` a project whose file metadata is on SQL gets `'filesystem'`
+instead of `'gridfs'`; an explicit `'gridfs'` keeps working while MongoDB is connected.
+
 ### How an upload reaches S3
 
 No upload is read into memory on its way to S3. Which request carries it depends on whether its
@@ -98,11 +108,14 @@ operator did not believe they were in. Afterwards nobody can tell which file wen
 **Leave it unset and it is derived**, most capable first:
 
 1. `'s3'` — when `s3.bucket` is configured
-2. `'gridfs'` — when a database is configured
-3. `'filesystem'` — when neither is
+2. `'filesystem'` — when `database` routes the file metadata to a SQL source (a PostgreSQL default source
+   does): GridFS would put bytes and metadata into MongoDB. The directory is pod-local — mount
+   `storageDir` as a volume or configure `s3`, or the files are gone after the next restart
+3. `'gridfs'` — when a database is configured
+4. `'filesystem'` — when none is
 
 A configured-but-**unreachable** database is an error in its own right (Mongoose fails the boot), never
-a reason to fall through to the disk. Only a database that is not configured **at all** reaches step 3 —
+a reason to fall through to the disk. Only a database that is not configured **at all** reaches step 4 —
 which today is theoretical, since `CoreModule` always registers Mongoose.
 
 A derived driver is enforced too: `s3.bucket` in the config makes S3 the default, but the bytes still

package/src/core/modules/file/core-file-info.model.ts

@@ -1,10 +1,10 @@
 import { ObjectType } from '@nestjs/graphql';
-import { Types } from 'mongoose';
 
 import { Restricted } from '../../common/decorators/restricted.decorator.js';
 import { UnifiedField } from '../../common/decorators/unified-field.decorator.js';
 import { RoleEnum } from '../../common/enums/role.enum.js';
 import { CoreModel } from '../../common/models/core-model.model.js';
+import { newObjectId } from '../../common/persistence/mongo/mongoose-compat.js';
 
 /**
  * File info
@@ -18,7 +18,7 @@ export class CoreFileInfo extends CoreModel {
 
   @Restricted(RoleEnum.S_EVERYONE)
   get _id() {
-    return new Types.ObjectId(this.id);
+    return newObjectId(this.id);
   }
 
   // ===========================================================================

package/src/core/modules/file/core-file.service.ts

@@ -1,5 +1,6 @@
 import { Logger, NotFoundException } from '@nestjs/common';
-import { type Connection, mongo, Types } from 'mongoose';
+import type { Connection } from 'mongoose';
+import type { mongo, Types } from 'mongoose';
 import { Readable } from 'stream';
 
 import { FilterArgs } from '../../common/args/filter.args.js';
@@ -9,6 +10,7 @@ import { convertFilterArgsToQuery } from '../../common/helpers/filter.helper.js'
 import { GridFSHelper } from '../../common/helpers/gridfs.helper.js';
 import { check } from '../../common/helpers/input.helper.js';
 import { prepareOutput } from '../../common/helpers/service.helper.js';
+import { isWellFormedId } from '../../common/persistence/id-format.js';
 import { ConfigService } from '../../common/services/config.service.js';
 import { RequestContext } from '../../common/services/request-context.service.js';
 import { CoreS3Service } from '../../common/services/core-s3.service.js';
@@ -25,13 +27,11 @@ import {
   logFileStorage,
   resolveFileStorage,
 } from './file-storage.helper.js';
-import {
-  DEFAULT_FILESYSTEM_DIR,
-  FILESYSTEM_FILES_COLLECTION,
-  FilesystemFileHelper,
-  FilesystemFileInfo,
-} from './filesystem-file.helper.js';
-import { S3_FILES_COLLECTION, S3FileHelper, S3FileInfo } from './s3-file.helper.js';
+import type { FileCollection } from './file-metadata.helper.js';
+import { fileMetadataCollection } from './file-metadata.store.js';
+import { DEFAULT_FILESYSTEM_DIR, FilesystemFileHelper, FilesystemFileInfo } from './filesystem-file.helper.js';
+import { S3FileHelper, S3FileInfo } from './s3-file.helper.js';
+import { createGridFsBucket } from '../../common/persistence/mongo/mongoose-compat.js';
 
 /**
  * Type for checking input
@@ -56,11 +56,18 @@ export abstract class CoreFileService {
   // Use the native MongoDB driver's types (accessed via Mongoose's exports) to avoid BSON version conflicts
   files: mongo.GridFSBucket;
 
-  /** Metadata collection for files stored in S3 (no Mongoose schema) */
-  protected s3Files: mongo.Collection<any>;
+  /**
+   * Metadata of the files stored in S3: the `s3-files` collection, or the table of its model when `database` routes it
+   * to a SQL source (`fileMetadataCollection()`)
+   */
+  protected get s3Files(): FileCollection {
+    return fileMetadataCollection(this.connection, 's3');
+  }
 
-  /** Metadata collection for files stored on the local filesystem (no Mongoose schema) */
-  protected filesystemFiles: mongo.Collection<any>;
+  /** Metadata of the files stored on the local filesystem: `filesystem-files`, or its table on a SQL source */
+  protected get filesystemFiles(): FileCollection {
+    return fileMetadataCollection(this.connection, 'filesystem');
+  }
 
   protected readonly logger = new Logger(CoreFileService.name);
 
@@ -75,10 +82,9 @@ export abstract class CoreFileService {
     bucketName = 'fs',
     protected readonly options?: CoreFileServiceOptions,
   ) {
-    // Use the native MongoDB driver's GridFSBucket via Mongoose's mongo export to avoid BSON version conflicts
-    this.files = new mongo.GridFSBucket(connection.db, { bucketName });
-    this.s3Files = connection.db.collection(S3_FILES_COLLECTION);
-    this.filesystemFiles = connection.db.collection(FILESYSTEM_FILES_COLLECTION);
+    // GridFS needs MongoDB: without a connection (a project on PostgreSQL alone) there is no bucket, the GridFS reads
+    // find nothing, and `file.storage: 'gridfs'` fails the boot below as unavailable
+    this.files = connection?.db ? createGridFsBucket(connection.db, { bucketName }) : undefined;
 
     // Resolve from the global config rather than the optional injected
     // ConfigService: a project on the pre-11.33 constructor (`super(connection)`)
@@ -123,6 +129,9 @@ export abstract class CoreFileService {
    * library and the service wired through `super()`.
    */
   protected isStorageAvailable(driver: FileStorageDriver): boolean {
+    if (driver === 'gridfs') {
+      return !!this.files;
+    }
     return driver === 's3' ? !!this.options?.s3Service?.enabled : true;
   }
 
@@ -144,14 +153,14 @@ export abstract class CoreFileService {
    *
    * Every store keys files by an ObjectId, so a string that is not 24 hex characters — a TUS upload
    * id (which clients took for the file id), a filename, a typo in a URL — names no file. It is
-   * answered exactly like an unknown id. Handed to `new ObjectId()` it threw a BSONError instead,
+   * answered exactly like an unknown id. Handed to `new Types.ObjectId()` it threw a BSONError instead,
    * and `GET /files/id/<tus-upload-id>` answered 500 where an unknown id gets 404.
    *
    * Only strings are judged: anything else keeps its previous path, so an ObjectId from a second
    * copy of `bson` (where `instanceof` fails) is not suddenly reported as missing.
    */
   protected isMalformedFileId(id: unknown): boolean {
-    return typeof id === 'string' && !(id.length === 24 && Types.ObjectId.isValid(id));
+    return typeof id === 'string' && !isWellFormedId(id);
   }
 
   /**

package/src/core/modules/file/file-metadata.helper.ts

@@ -1,4 +1,5 @@
-import { mongo, Types } from 'mongoose';
+import type { mongo, Types } from 'mongoose';
+import { newObjectId } from '../../common/persistence/mongo/mongoose-compat.js';
 
 /**
  * The metadata shape every non-GridFS storage driver writes, and the queries against it.
@@ -25,7 +26,10 @@ import { mongo, Types } from 'mongoose';
  * `.claude/rules/architecture.md` → "DI Token Placement (SWC-Safe)".
  */
 
-/** Metadata collection handle (no Mongoose schema — these collections are driver-managed) */
+/**
+ * Metadata collection handle — the MongoDB collection, or its table on a SQL source behind the same operations
+ * (`fileMetadataCollection()` decides which)
+ */
 export type FileCollection = mongo.Collection<any>;
 
 /**
@@ -70,7 +74,7 @@ export async function findMetadataById(
   collection: FileCollection,
   id: string | Types.ObjectId,
 ): Promise<FileMetadataInfo | null> {
-  return (await collection.findOne({ _id: new Types.ObjectId(id) })) as FileMetadataInfo | null;
+  return (await collection.findOne({ _id: newObjectId(id) })) as FileMetadataInfo | null;
 }
 
 /**

package/src/core/modules/file/file-metadata.models.ts

@@ -0,0 +1,44 @@
+import type { Schema } from 'mongoose';
+
+import { createSchema } from '../../common/persistence/mongo/mongoose-compat.js';
+
+import { FILESYSTEM_FILES_COLLECTION } from './filesystem-file.helper.js';
+import { S3_FILES_COLLECTION } from './s3-file.helper.js';
+
+/**
+ * The metadata of files whose bytes live in S3 or on the filesystem, as models — what routes them with `database`
+ * like every other model (db-agnostic phase 4). On a SQL default source the rows live in the tables `s3_files` and
+ * `filesystem_files`; on MongoDB the file helpers keep reading and writing the collections natively, as before.
+ *
+ * `autoCreate` and `autoIndex` are off: these schemas only register the models. A deployment that never writes to a
+ * store must not grow an empty collection for it (`ensureFilenameIndex()` creates the index on the first write), and
+ * nothing may create an index next to the one the helpers ensure. GridFS has no model here: its `fs.files` belongs to
+ * the driver and stays on MongoDB.
+ */
+
+/** Model of the `s3-files` metadata */
+export const S3_FILE_MODEL = 'CoreS3File';
+
+/** Model of the `filesystem-files` metadata */
+export const FILESYSTEM_FILE_MODEL = 'CoreFilesystemFile';
+
+/** The shape both stores write — a GridFS `fs.files` document plus the `storage` marker (`FileMetadataInfo`) */
+function fileMetadataSchema(collection: string): Schema {
+  return createSchema(
+    {
+      contentType: { type: String },
+      filename: { index: true, type: String },
+      length: { type: Number },
+      metadata: { type: Object },
+      storage: { type: String },
+      uploadDate: { type: Date },
+    },
+    { autoCreate: false, autoIndex: false, collection, versionKey: false },
+  );
+}
+
+/** Registered by `CoreModule` through `CorePersistenceModule.forFeature()` */
+export const FILE_METADATA_MODELS = [
+  { name: S3_FILE_MODEL, schema: fileMetadataSchema(S3_FILES_COLLECTION) },
+  { name: FILESYSTEM_FILE_MODEL, schema: fileMetadataSchema(FILESYSTEM_FILES_COLLECTION) },
+];