@lenne.tech/nest-server 11.43.3 → 12.1.0

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,
@@ -16,27 +17,28 @@ import {
 } from 'better-auth/api';
 import { Request } from 'express';
 import { importJWK, jwtVerify } from 'jose';
-import { Connection } from 'mongoose';
-
-import { shouldConvertSessionTokenToJwt } from '../../common/helpers/cookies.helper';
-import { maskEmail, maskToken } from '../../common/helpers/logging.helper';
-import { IBetterAuth, ICookiesConfig } from '../../common/interfaces/server-options.interface';
-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 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';
+import { ErrorCode } from '../error-code/error-codes.js';
+import { resolveBetterAuthCookiePrefix } from './better-auth-cookie-prefix.helper.js';
+import type { BetterAuthInstance } from './better-auth.config.js';
+import { legacyCredentialAccountIssuer, usesLegacyAccountIssuer } from './core-better-auth-account-issuer.helper.js';
 import {
   BUILT_IN_BETTER_AUTH_PLUGIN_IDS,
   HANDLER_SESSION_PATHS,
   isUnavailableOperation,
   toOpenApiPath,
   unavailableBetterAuthOperations,
-} from './core-better-auth-openapi.helper';
-import type { IBetterAuthOpenApiDocument, IBetterAuthRuntime } from './core-better-auth-openapi.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';
+} from './core-better-auth-openapi.helper.js';
+import type { IBetterAuthOpenApiDocument, IBetterAuthRuntime } from './core-better-auth-openapi.helper.js';
+import { isJwtShaped } from './core-better-auth-token.helper.js';
+import { BetterAuthSessionUser } from './core-better-auth-user.mapper.js';
+import { convertExpressHeaders, parseCookieHeader, signCookieValueIfNeeded } from './core-better-auth-web.helper.js';
 import {
   ACCOUNT_ISSUER_BACKFILL_ID,
   BACKFILL_MARKER_COLLECTION,
@@ -46,7 +48,8 @@ import {
   DEFAULT_ACCOUNT_ACCOUNT_ID_FIELD,
   DEFAULT_ACCOUNT_ISSUER_FIELD,
   DEFAULT_ACCOUNT_MODEL_NAME,
-} from './core-better-auth.constants';
+} from './core-better-auth.constants.js';
+import { getBetterAuthSqlStore } from './core-better-auth-sql.registry.js';
 
 /**
  * Result of a session validation
@@ -77,7 +80,7 @@ export interface SessionResult {
  * ambiguity error. The mechanical guards are `pnpm run check:swc-tdz` and
  * `tests/unit/better-auth-di-tokens.spec.ts`.
  */
-export { BETTER_AUTH_CONFIG, BETTER_AUTH_COOKIE_DOMAIN } from './core-better-auth.constants';
+export { BETTER_AUTH_CONFIG, BETTER_AUTH_COOKIE_DOMAIN } from './core-better-auth.constants.js';
 
 /**
  * CoreBetterAuthService provides a NestJS-friendly wrapper around the better-auth instance.
@@ -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/better-auth/index.ts

@@ -22,28 +22,28 @@
  * - DefaultBetterAuthResolver: Default resolver implementation (use as fallback)
  */
 
-export * from './better-auth-roles.guard';
-export * from './better-auth-token.service';
-export * from './better-auth.config';
-export * from './better-auth.resolver';
-export * from './better-auth.types';
-export * from './core-better-auth-api.middleware';
-export * from './core-better-auth-auth.model';
-export * from './core-better-auth-cookie.helper';
-export * from './core-better-auth-email-verification.service';
-export * from './core-better-auth-error-codes.helper';
-export * from './core-better-auth-migration-status.model';
-export * from './core-better-auth-models';
-export * from './core-better-auth-rate-limit.middleware';
-export * from './core-better-auth-rate-limiter.service';
-export * from './core-better-auth-signup-validator.service';
-export * from './core-better-auth-token.helper';
-export * from './core-better-auth-user.mapper';
-export * from './core-better-auth-web.helper';
-export * from './core-better-auth.constants';
-export * from './core-better-auth.controller';
-export * from './core-better-auth.middleware';
-export * from './core-better-auth.module';
+export * from './better-auth-roles.guard.js';
+export * from './better-auth-token.service.js';
+export * from './better-auth.config.js';
+export * from './better-auth.resolver.js';
+export * from './better-auth.types.js';
+export * from './core-better-auth-api.middleware.js';
+export * from './core-better-auth-auth.model.js';
+export * from './core-better-auth-cookie.helper.js';
+export * from './core-better-auth-email-verification.service.js';
+export * from './core-better-auth-error-codes.helper.js';
+export * from './core-better-auth-migration-status.model.js';
+export * from './core-better-auth-models.js';
+export * from './core-better-auth-rate-limit.middleware.js';
+export * from './core-better-auth-rate-limiter.service.js';
+export * from './core-better-auth-signup-validator.service.js';
+export * from './core-better-auth-token.helper.js';
+export * from './core-better-auth-user.mapper.js';
+export * from './core-better-auth-web.helper.js';
+export * from './core-better-auth.constants.js';
+export * from './core-better-auth.controller.js';
+export * from './core-better-auth.middleware.js';
+export * from './core-better-auth.module.js';
 // NOT exported: './core-better-auth.registry'.
 //
 // It is module-internal plumbing that only exists so BetterAuthRolesGuard can reach
@@ -52,5 +52,5 @@ export * from './core-better-auth.module';
 // consumer swap or null the very token service the guard makes its authorization decisions with.
 // Consumers that need the instance already have the public, read-only
 // `CoreBetterAuthModule.getTokenServiceInstance()`.
-export * from './core-better-auth.resolver';
-export * from './core-better-auth.service';
+export * from './core-better-auth.resolver.js';
+export * from './core-better-auth.service.js';

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

@@ -1,9 +1,9 @@
 import { Controller, Get, NotFoundException, Param } from '@nestjs/common';
 
-import { Roles } from '../../common/decorators/roles.decorator';
-import { RoleEnum } from '../../common/enums/role.enum';
-import { CoreErrorCodeService } from './core-error-code.service';
-import { IErrorTranslationResponse, SupportedLocale } from './interfaces/error-code.interfaces';
+import { Roles } from '../../common/decorators/roles.decorator.js';
+import { RoleEnum } from '../../common/enums/role.enum.js';
+import { CoreErrorCodeService } from './core-error-code.service.js';
+import { type IErrorTranslationResponse, SupportedLocale } from './interfaces/error-code.interfaces.js';
 
 /**
  * Core Error Code Controller

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

@@ -1,7 +1,7 @@
 import { Injectable } from '@nestjs/common';
 
-import { getAllErrorDefinitions, IErrorRegistry } from './error-codes';
-import { SupportedLocale } from './interfaces/error-code.interfaces';
+import { getAllErrorDefinitions, IErrorRegistry } from './error-codes.js';
+import { SupportedLocale } from './interfaces/error-code.interfaces.js';
 
 /**
  * Core Error Code Service

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

@@ -1,8 +1,8 @@
 import { DynamicModule, Global, Module, Type } from '@nestjs/common';
 
-import { CoreErrorCodeController } from './core-error-code.controller';
-import { CoreErrorCodeService } from './core-error-code.service';
-import { IErrorCodeModuleConfig } from './interfaces/error-code.interfaces';
+import { CoreErrorCodeController } from './core-error-code.controller.js';
+import { CoreErrorCodeService } from './core-error-code.service.js';
+import { IErrorCodeModuleConfig } from './interfaces/error-code.interfaces.js';
 
 /**
  * Error Code Module

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

@@ -1,14 +1,14 @@
 // Controller
-export * from './core-error-code.controller';
+export * from './core-error-code.controller.js';
 
 // Service
-export * from './core-error-code.service';
+export * from './core-error-code.service.js';
 
 // Module
-export * from './error-code.module';
+export * from './error-code.module.js';
 
 // Error Codes
-export * from './error-codes';
+export * from './error-codes.js';
 
 // Interfaces
-export * from './interfaces/error-code.interfaces';
+export * from './interfaces/error-code.interfaces.js';

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

@@ -1,7 +1,7 @@
 import { Type } from '@nestjs/common';
 
-import { CoreErrorCodeService } from '../core-error-code.service';
-import { IErrorRegistry } from '../error-codes';
+import { CoreErrorCodeService } from '../core-error-code.service.js';
+import { IErrorRegistry } from '../error-codes.js';
 
 /**
  * Configuration for the error code module

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-access-audit.initializer.ts

@@ -1,16 +1,16 @@
 import { Injectable, Logger, OnApplicationBootstrap, Optional } from '@nestjs/common';
 import { DiscoveryService } from '@nestjs/core';
 
-import { ConfigService } from '../../common/services/config.service';
-import { CoreFileController } from './core-file.controller';
-import { CoreFileResolver } from './core-file.resolver';
-import { CoreFileService } from './core-file.service';
+import { ConfigService } from '../../common/services/config.service.js';
+import { CoreFileController } from './core-file.controller.js';
+import { CoreFileResolver } from './core-file.resolver.js';
+import { CoreFileService } from './core-file.service.js';
 import {
   FILE_ROLE_MEMBERS,
   FileEndpointClassName,
   ObservedFileHandler,
   warnOnUndecidedEffectiveFileAccess,
-} from './file-roles.config';
+} from './file-roles.config.js';
 
 /**
  * Audits the file endpoints a project ACTUALLY registered, and warns when one of them is open beyond

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';
-import { UnifiedField } from '../../common/decorators/unified-field.decorator';
-import { RoleEnum } from '../../common/enums/role.enum';
-import { CoreModel } from '../../common/models/core-model.model';
+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.controller.ts

@@ -2,14 +2,14 @@ import { BadRequestException, Controller, Get, Logger, NotFoundException, Param,
 import type { Response } from 'express';
 import type { Readable } from 'stream';
 
-import { CurrentUser } from '../../common/decorators/current-user.decorator';
-import { Roles } from '../../common/decorators/roles.decorator';
-import { RoleEnum } from '../../common/enums/role.enum';
-import { buildContentDisposition } from '../../common/helpers/content-disposition.helper';
-import { ErrorCode } from '../error-code/error-codes';
-import { SkipTenantCheck } from '../tenant/core-tenant.decorators';
-import { CoreFileService } from './core-file.service';
-import type { FileServiceOptions } from './interfaces/file-service-options.interface';
+import { CurrentUser } from '../../common/decorators/current-user.decorator.js';
+import { Roles } from '../../common/decorators/roles.decorator.js';
+import { RoleEnum } from '../../common/enums/role.enum.js';
+import { buildContentDisposition } from '../../common/helpers/content-disposition.helper.js';
+import { ErrorCode } from '../error-code/error-codes.js';
+import { SkipTenantCheck } from '../tenant/core-tenant.decorators.js';
+import { CoreFileService } from './core-file.service.js';
+import type { FileServiceOptions } from './interfaces/file-service-options.interface.js';
 
 const fileStreamLogger = new Logger('CoreFileController');
 

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

@@ -1,13 +1,12 @@
 import { Args, Mutation, Query, Resolver } from '@nestjs/graphql';
-import * as GraphQLUpload from 'graphql-upload/GraphQLUpload.js';
-
-import { CurrentUser } from '../../common/decorators/current-user.decorator';
-import { Roles } from '../../common/decorators/roles.decorator';
-import { RoleEnum } from '../../common/enums/role.enum';
-import { SkipTenantCheck } from '../tenant/core-tenant.decorators';
-import { CoreFileInfo } from './core-file-info.model';
-import { CoreFileService } from './core-file.service';
-import { FileUpload } from './interfaces/file-upload.interface';
+import { CurrentUser } from '../../common/decorators/current-user.decorator.js';
+import { Roles } from '../../common/decorators/roles.decorator.js';
+import { RoleEnum } from '../../common/enums/role.enum.js';
+import { GraphQLUpload } from '../../common/scalars/upload.scalar.js';
+import { SkipTenantCheck } from '../tenant/core-tenant.decorators.js';
+import { CoreFileInfo } from './core-file-info.model.js';
+import { CoreFileService } from './core-file.service.js';
+import type { FileUpload } from './interfaces/file-upload.interface.js';
 
 /**
  * File resolver

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

@@ -1,37 +1,37 @@
 import { Logger, NotFoundException } from '@nestjs/common';
-import { 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';
-import { accessDeniedException } from '../../common/exceptions/access-denied.exception';
-import { getObjectIds, getStringIds } from '../../common/helpers/db.helper';
-import { convertFilterArgsToQuery } from '../../common/helpers/filter.helper';
-import { GridFSHelper } from '../../common/helpers/gridfs.helper';
-import { check } from '../../common/helpers/input.helper';
-import { prepareOutput } from '../../common/helpers/service.helper';
-import { ConfigService } from '../../common/services/config.service';
-import { RequestContext } from '../../common/services/request-context.service';
-import { CoreS3Service } from '../../common/services/core-s3.service';
-import { MaybePromise } from '../../common/types/maybe-promise.type';
-import { CoreFileInfo } from './core-file-info.model';
-import { decideFileAccess, fileAccessNeedsRawDocument, resolveFileAccessPreset } from './file-access.helper';
-import { warnOnUndecidedFileAccess } from './file-roles.config';
-import { FileServiceOptions } from './interfaces/file-service-options.interface';
-import { FileUploadSource } from './interfaces/file-upload.interface';
+import { FilterArgs } from '../../common/args/filter.args.js';
+import { accessDeniedException } from '../../common/exceptions/access-denied.exception.js';
+import { getObjectIds, getStringIds } from '../../common/helpers/db.helper.js';
+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';
+import { MaybePromise } from '../../common/types/maybe-promise.type.js';
+import { CoreFileInfo } from './core-file-info.model.js';
+import { decideFileAccess, fileAccessNeedsRawDocument, resolveFileAccessPreset } from './file-access.helper.js';
+import { warnOnUndecidedFileAccess } from './file-roles.config.js';
+import { FileServiceOptions } from './interfaces/file-service-options.interface.js';
+import { FileUploadSource } from './interfaces/file-upload.interface.js';
 import {
   assertFileStorageAvailable,
   FileStorageDriver,
   FileStorageResolution,
   logFileStorage,
   resolveFileStorage,
-} from './file-storage.helper';
-import {
-  DEFAULT_FILESYSTEM_DIR,
-  FILESYSTEM_FILES_COLLECTION,
-  FilesystemFileHelper,
-  FilesystemFileInfo,
-} from './filesystem-file.helper';
-import { S3_FILES_COLLECTION, S3FileHelper, S3FileInfo } from './s3-file.helper';
+} from './file-storage.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-access.helper.ts

@@ -37,7 +37,7 @@
  * be split for the same reason (it imports the endpoint classes, which inject `CoreFileService`), and
  * this file is read FROM the service. See `.claude/rules/architecture.md` → "DI Token Placement".
  */
-import { RoleEnum } from '../../common/enums/role.enum';
+import { RoleEnum } from '../../common/enums/role.enum.js';
 
 /** Which of the four project classes this deployment is. */
 export type FileAccessPreset = 'authenticated' | 'custom' | 'owner' | 'public' | 'tenant';