@lenne.tech/nest-server 11.43.3 → 12.1.0

package/src/core/modules/migrate/sql-state-store.ts

@@ -0,0 +1,198 @@
+import type { DatabaseSqlEngine } from '../../common/interfaces/server-options.interface.js';
+import { createSqlExecutor, installedSqlEngine } from '../../common/persistence/sql/sql-executor.factory.js';
+import type { SqlExecutor, SqlTenantScope } from '../../common/persistence/sql/sql-executor.interface.js';
+import { quoteIdentifier, quoteMysqlIdentifier } from '../../common/persistence/sql/sql-naming.js';
+import type { MigrationSet, MigrationStateStore } from './migration-state-store.interface.js';
+
+const SYSTEM: SqlTenantScope = { kind: 'system' };
+
+/**
+ * Serialises migration runs of every replica: a transaction-scoped advisory lock, held by the transaction that
+ * surrounds the whole run. It ends with that transaction — and with its connection, so a replica killed mid-migration
+ * leaves nothing behind that another one would have to break (MongoDB needs a heartbeat and a stale-lock rule for
+ * that). A key of its own: the boot's schema evolution (`SCHEMA_LOCK_SQL`) must stay possible while a run waits.
+ */
+const MIGRATION_RUN_LOCK_SQL = "SELECT pg_advisory_xact_lock(hashtext('lenne.tech:migrations'))";
+
+/**
+ * MySQL / MariaDB: a named lock per database, held by the session of the locking connection. It ends with that
+ * connection too, so a killed replica leaves nothing behind; released explicitly at the end of a run. The wait is
+ * bounded at a day — a run that takes longer is not waited for
+ */
+const MYSQL_RUN_LOCK_NAME = "CONCAT('lenne.tech:migrations:', SHA1(DATABASE()))";
+const MYSQL_RUN_LOCK_TIMEOUT_SECONDS = 86_400;
+
+export interface SqlStateStoreOptions {
+  /**
+   * SQL engine of the connection, the project's configured one. Without it the first INSTALLED engine is used
+   * (`typeorm`, `kysely`, `drizzle`): `createMigrationStore()` runs in the migrate CLI, which has no configuration to
+   * read it from. @default the first installed engine
+   */
+  engine?: DatabaseSqlEngine;
+  /** `false` runs migrations without the run lock — one replica only. @default true */
+  lock?: boolean;
+  /** Table holding the migration state. @default 'lt_migrations' */
+  tableName?: string;
+  /**
+   * Connection URL of the table OWNER (`database.ownerUrl`): migrations change the schema and the data of every
+   * tenant, which the application role may not
+   */
+  url: string;
+}
+
+/**
+ * Migration state on PostgreSQL, MySQL and MariaDB (the URL's scheme decides) — the counterpart of `MongoStateStore`:
+ * one row with the last run and the applied migrations, read and written by `MigrationRunner` and the `migrate` CLI,
+ * with every run serialised across replicas.
+ *
+ * Each call opens and closes its own connection, as `MongoStateStore` does: the CLI and the container entrypoint run it
+ * once per boot, and a pool kept open would hold the process.
+ */
+export class SqlStateStore implements MigrationStateStore {
+  readonly url: string;
+  protected readonly engine: DatabaseSqlEngine | undefined;
+  protected readonly locked: boolean;
+  /** MySQL and MariaDB share one dialect here */
+  protected readonly mysql: boolean;
+  protected readonly table: string;
+
+  constructor(options: SqlStateStoreOptions | string) {
+    const resolved = typeof options === 'string' ? { url: options } : options;
+    if (!resolved.url) {
+      throw new Error('SqlStateStore needs the connection URL of the table owner (database.ownerUrl)');
+    }
+    this.url = resolved.url;
+    this.engine = resolved.engine;
+    this.locked = resolved.lock !== false;
+    this.mysql = /^(mysql|mariadb):/i.test(resolved.url);
+    this.table = (this.mysql ? quoteMysqlIdentifier : quoteIdentifier)(resolved.tableName ?? 'lt_migrations');
+  }
+
+  load(fn: (err?: Error, set?: MigrationSet) => void): void {
+    this.loadAsync()
+      .then((result) => fn(undefined, result))
+      .catch((err) => fn(err));
+  }
+
+  async loadAsync(): Promise<MigrationSet> {
+    return this.request(async (executor) => {
+      const { rows } = await executor.run<{ last_run: null | string; migrations: MigrationSet['migrations'] | string }>(
+        {
+          params: [],
+          text: this.mysql
+            ? `SELECT \`last_run\`, \`migrations\` FROM ${this.table} WHERE \`id\` = 'state'`
+            : `SELECT "last_run", "migrations" FROM ${this.table} WHERE "id" = 'state'`,
+        },
+        SYSTEM,
+      );
+      if (!rows.length) {
+        console.debug('No migrations found, probably running the very first time');
+        // An empty object, as MongoStateStore returns for a first run
+        return {} as MigrationSet;
+      }
+      const migrations = rows[0].migrations;
+      return {
+        lastRun: rows[0].last_run ?? undefined,
+        // MariaDB's JSON is text where the driver does not recognise it
+        migrations: typeof migrations === 'string' ? JSON.parse(migrations) : migrations,
+      } as MigrationSet;
+    });
+  }
+
+  save(set: MigrationSet, fn: (err?: Error) => void): void {
+    this.saveAsync(set)
+      .then(() => fn())
+      .catch((err) => fn(err));
+  }
+
+  async saveAsync(set: MigrationSet): Promise<void> {
+    const { lastRun, migrations } = set;
+    await this.request((executor) =>
+      executor.run(
+        {
+          params: [lastRun ?? null, JSON.stringify(migrations ?? [])],
+          text: this.mysql
+            ? `INSERT INTO ${this.table} (\`id\`, \`last_run\`, \`migrations\`, \`updated_at\`) VALUES ('state', $1, $2, UTC_TIMESTAMP(3))
+              ON DUPLICATE KEY UPDATE \`last_run\` = $1, \`migrations\` = $2, \`updated_at\` = UTC_TIMESTAMP(3)`
+            : `INSERT INTO ${this.table} ("id", "last_run", "migrations", "updated_at") VALUES ('state', $1, $2::jsonb, now())
+              ON CONFLICT ("id") DO UPDATE SET "last_run" = EXCLUDED."last_run", "migrations" = EXCLUDED."migrations", "updated_at" = now()`,
+        },
+        SYSTEM,
+      ),
+    );
+  }
+
+  async withLock<T>(fn: () => Promise<T>): Promise<T> {
+    if (!this.locked) {
+      return fn();
+    }
+    const executor = await this.open();
+    try {
+      // The work itself runs on other connections (the runner reads and saves the state, migrations open their own);
+      // this transaction only holds the lock for as long as the work takes
+      return await executor.transaction(async (tx) => {
+        if (!this.mysql) {
+          await tx.run({ params: [], text: MIGRATION_RUN_LOCK_SQL }, SYSTEM);
+          return fn();
+        }
+        const { rows } = await tx.run<{ locked: number | string }>(
+          {
+            params: [MYSQL_RUN_LOCK_TIMEOUT_SECONDS],
+            text: `SELECT GET_LOCK(${MYSQL_RUN_LOCK_NAME}, $1) AS locked`,
+          },
+          SYSTEM,
+        );
+        if (Number(rows[0]?.locked) !== 1) {
+          throw new Error('Timed out waiting for the migration run of another process');
+        }
+        try {
+          return await fn();
+        } finally {
+          await tx
+            .run({ params: [], text: `SELECT RELEASE_LOCK(${MYSQL_RUN_LOCK_NAME})` }, SYSTEM)
+            .catch(() => undefined);
+        }
+      });
+    } finally {
+      await executor.close();
+    }
+  }
+
+  protected async request<R>(work: (executor: SqlExecutor) => Promise<R>): Promise<R> {
+    const executor = await this.open();
+    try {
+      return await work(executor);
+    } finally {
+      await executor.close();
+    }
+  }
+
+  /** A connection of its own, with the state table in place */
+  protected async open(): Promise<SqlExecutor> {
+    const executor = await createSqlExecutor({
+      applicationName: 'nest-server-migrations',
+      engine: this.engine ?? (await installedSqlEngine()),
+      maxConnections: 1,
+      url: this.url,
+    });
+    try {
+      await executor.run(
+        {
+          params: [],
+          text: this.mysql
+            ? `CREATE TABLE IF NOT EXISTS ${this.table} (\`id\` varchar(255) NOT NULL PRIMARY KEY, \`last_run\` longtext, \`migrations\` json NOT NULL, \`updated_at\` datetime(3) NOT NULL) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin`
+            : `CREATE TABLE IF NOT EXISTS ${this.table} ("id" text PRIMARY KEY, "last_run" text, "migrations" jsonb NOT NULL DEFAULT '[]'::jsonb, "updated_at" timestamptz NOT NULL DEFAULT now())`,
+        },
+        SYSTEM,
+      );
+    } catch (error) {
+      // Two replicas creating the table at the same moment: IF NOT EXISTS is not atomic in PostgreSQL, the loser fails
+      // with a duplicate of the table (42P07) or of its row type (23505) — and the table exists, which is all it asked
+      if (!['23505', '42P07'].includes((error as { code?: string })?.code)) {
+        await executor.close();
+        throw error;
+      }
+    }
+    return executor;
+  }
+}

package/src/core/modules/migrate/templates/migration-project.template.ts

@@ -1,5 +1,7 @@
 import { getDb, uploadFileToGridFS } from '@lenne.tech/nest-server';
 import { Db, ObjectId } from 'mongodb';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
 
 /**
  * Migration template for nest-server projects
@@ -12,21 +14,36 @@ import { Db, ObjectId } from 'mongodb';
  * - uploadFileToGridFS(uri, filePath, options): Upload file to GridFS
  *
  * MongoDB URI resolution (in order):
- * 1. config.env.ts (local development via ts-node)
+ * 1. the project's config.env — next to `migrations/` when run from source (through the `--compiler ts:` loader), or
+ *    the compiled `dist/src/config.env.js` when run from `dist/migrations`
  * 2. NSC__MONGOOSE__URI environment variable (Docker production)
  */
 
-let MONGO_URL: string;
-try {
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  const config = require('../src/config.env');
-  MONGO_URL = (config.default || config).mongoose.uri;
-} catch {
-  // Fallback for Docker production where config.env.ts is not available as TypeScript source
-  if (!process.env.NSC__MONGOOSE__URI) {
-    throw new Error('MongoDB URI not available. Set NSC__MONGOOSE__URI or ensure config.env.ts is loadable.');
+// `createRequire` rather than `require`, so the migration works in CommonJS and ESM projects alike. `__dirname` exists
+// in a CommonJS project only and finds config.env relative to this file — in the source tree and in `dist/` alike. An ES
+// module project has no `__dirname` here; it falls back to the directory the migrate scripts run from.
+const projectRequire = createRequire(join(process.cwd(), 'package.json'));
+const configCandidates = [
+  ...(typeof __dirname === 'string' ? [join(__dirname, '..', 'src', 'config.env')] : []),
+  join(process.cwd(), 'src', 'config.env'),
+  join(process.cwd(), 'dist', 'src', 'config.env'),
+];
+
+let configuredUri: string | undefined;
+for (const candidate of configCandidates) {
+  try {
+    const config = projectRequire(candidate);
+    configuredUri = (config.default || config).mongoose?.uri;
+  } catch {
+    // Not loadable in this layout — try the next one.
+  }
+  if (configuredUri) {
+    break;
   }
-  MONGO_URL = process.env.NSC__MONGOOSE__URI;
+}
+const MONGO_URL = configuredUri ?? process.env.NSC__MONGOOSE__URI;
+if (!MONGO_URL) {
+  throw new Error('MongoDB URI not available. Set NSC__MONGOOSE__URI or ensure config.env is loadable.');
 }
 
 /**
@@ -46,7 +63,7 @@ export const up = async () => {
   // Example: Upload a file to GridFS
   // const fileId: ObjectId = await uploadFileToGridFS(
   //   MONGO_URL,
-  //   '../assets/image.png',
+  //   '../assets/image.png', // relative to this migration file
   //   { bucketName: 'images', filename: 'logo.png' }
   // );
 };

package/src/core/modules/permissions/core-permissions.controller.ts

@@ -1,7 +1,7 @@
 import { Controller, Get, Header, Headers, Post } from '@nestjs/common';
 
-import { CorePermissionsService } from './core-permissions.service';
-import type { PermissionsReport } from './interfaces/permissions.interface';
+import { CorePermissionsService } from './core-permissions.service.js';
+import type { PermissionsReport } from './interfaces/permissions.interface.js';
 
 @Controller()
 export class CorePermissionsController {

package/src/core/modules/permissions/core-permissions.module.ts

@@ -1,11 +1,11 @@
 import { DynamicModule, Module } from '@nestjs/common';
 import { PATH_METADATA } from '@nestjs/common/constants';
 
-import { RoleEnum } from '../../common/enums/role.enum';
+import { RoleEnum } from '../../common/enums/role.enum.js';
 
-import { CorePermissionsController } from './core-permissions.controller';
-import { CorePermissionsService } from './core-permissions.service';
-import type { IPermissions } from './interfaces/permissions.interface';
+import { CorePermissionsController } from './core-permissions.controller.js';
+import { CorePermissionsService } from './core-permissions.service.js';
+import type { IPermissions } from './interfaces/permissions.interface.js';
 
 @Module({})
 export class CorePermissionsModule {

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

@@ -3,8 +3,8 @@ import * as fs from 'fs';
 import { existsSync } from 'fs';
 import { join } from 'path';
 
-import type { ModulePermissions, PermissionsReport } from './interfaces/permissions.interface';
-import { findProjectRoot, generateMarkdownReport, scanPermissions } from './permissions-scanner';
+import type { ModulePermissions, PermissionsReport } from './interfaces/permissions.interface.js';
+import { findProjectRoot, generateMarkdownReport, scanPermissions } from './permissions-scanner.js';
 
 @Injectable()
 export class CorePermissionsService implements OnModuleDestroy {

package/src/core/modules/permissions/permissions-scanner.ts

@@ -26,7 +26,7 @@ import type {
   SecurityCheckInfo,
   SecurityWarning,
   WarningsByType,
-} from './interfaces/permissions.interface';
+} from './interfaces/permissions.interface.js';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Public API

package/src/core/modules/system-setup/README.md

@@ -172,6 +172,9 @@ NEST_SERVER_CONFIG='{ "systemSetup": { "initialAdmin": { "email": "admin@example
   After a SUCCESSFUL setup the marker REMAINS — setup must never run twice in a deployment. Test
   suites that reset the database to replay the setup flow therefore have to drop `system-setup-locks`
   alongside `users`; clearing only `users` leaves setup refused until the claim goes stale (5 min).
+- **On a PostgreSQL default source** (`database`) the claim is the row `system-setup:initial-admin` in
+  the lease table `lt_locks`, with the same semantics: one replica wins, released on failure, kept
+  after success, taken over once stale. Where this README names `system-setup-locks`, read that row.
 
 ### Security Best Practices
 
@@ -248,8 +251,10 @@ confirms a state that is not the problem, and step 2 confirms an empty database
 empty.
 
 1. Look at the server log. Since 11.36.5 the service logs a warning naming the collection, the
-   release-on-failure semantics and the stale window.
-2. Check the collection directly: `db.getCollection('system-setup-locks').find()`
+   release-on-failure semantics and the stale window — on a PostgreSQL default source the
+   `lt_locks` row instead.
+2. Check the collection directly: `db.getCollection('system-setup-locks').find()` — on PostgreSQL
+   `SELECT * FROM lt_locks WHERE id = 'system-setup:initial-admin'`
 3. If you reset the database to replay the setup, drop `system-setup-locks` alongside `users` -
    see **Resetting for tests** below. Otherwise wait for the claim to go stale (5 minutes after it
    was taken).
@@ -267,6 +272,13 @@ for (const col of ['users', 'account', 'session', 'system-setup-locks']) {
 }
 ```
 
+On a PostgreSQL default source, the same reset (run there by the same suite in the `postgres` project):
+
+```sql
+DELETE FROM session; DELETE FROM account; DELETE FROM users;
+DELETE FROM lt_locks WHERE id = 'system-setup:initial-admin';
+```
+
 ### Init returns 403 "System setup requires BetterAuth"
 
 **Cause:** BetterAuth is not configured or not enabled.

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

@@ -2,9 +2,9 @@ import { Body, Controller, Get, Post } from '@nestjs/common';
 import { ApiBody, ApiOperation, ApiProperty, ApiResponse, ApiTags } from '@nestjs/swagger';
 import { IsEmail, IsNotEmpty, IsOptional, IsString, MinLength } from 'class-validator';
 
-import { Roles } from '../../common/decorators/roles.decorator';
-import { RoleEnum } from '../../common/enums/role.enum';
-import { CoreSystemSetupService, SystemSetupInitResult, SystemSetupStatus } from './core-system-setup.service';
+import { Roles } from '../../common/decorators/roles.decorator.js';
+import { RoleEnum } from '../../common/enums/role.enum.js';
+import { CoreSystemSetupService, SystemSetupInitResult, SystemSetupStatus } from './core-system-setup.service.js';
 
 /**
  * DTO for system setup init request

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

@@ -1,7 +1,7 @@
 import { Module } from '@nestjs/common';
 
-import { CoreSystemSetupController } from './core-system-setup.controller';
-import { CoreSystemSetupService } from './core-system-setup.service';
+import { CoreSystemSetupController } from './core-system-setup.controller.js';
+import { CoreSystemSetupService } from './core-system-setup.service.js';
 
 /**
  * CoreSystemSetupModule provides initial admin creation for fresh deployments.

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

@@ -1,21 +1,36 @@
+import { randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
+
 import { ForbiddenException, Injectable, Logger, OnApplicationBootstrap } from '@nestjs/common';
-import { InjectConnection } from '@nestjs/mongoose';
+import { InjectConnection } from '../../common/persistence/mongo/mongoose-compat.js';
 import { isEmail } from 'class-validator';
-import { Connection } from 'mongoose';
-
-import { ConfigService } from '../../common/services/config.service';
-import { legacyCredentialAccountIssuer } from '../better-auth/core-better-auth-account-issuer.helper';
-import { CoreBetterAuthUserMapper } from '../better-auth/core-better-auth-user.mapper';
-import { CoreBetterAuthService } from '../better-auth/core-better-auth.service';
-import { ErrorCode } from '../error-code/error-codes';
+import type { Collection } from 'mongodb';
+import type { Connection } from 'mongoose';
+
+import {
+  defaultSqlLockStore,
+  SYSTEM_SETUP_CLAIM_STALE_AFTER_MS,
+  SYSTEM_SETUP_LOCK_COLLECTION,
+  SYSTEM_SETUP_LOCK_KEY,
+  systemSetupMongoLocks,
+} from '../../common/persistence/infrastructure-locks.js';
+import type { LockStore } from '../../common/persistence/lock-store.interface.js';
+import { ConfigService } from '../../common/services/config.service.js';
+import { legacyCredentialAccountIssuer } from '../better-auth/core-better-auth-account-issuer.helper.js';
+import { CoreBetterAuthUserMapper } from '../better-auth/core-better-auth-user.mapper.js';
+import { CoreBetterAuthService } from '../better-auth/core-better-auth.service.js';
+import { ErrorCode } from '../error-code/error-codes.js';
+import { getPersistenceRuntime } from '../../common/persistence/persistence-runtime.registry.js';
+import { getBetterAuthSqlStore } from '../better-auth/core-better-auth-sql.registry.js';
 
 /**
- * Collection holding the bootstrap claim markers.
+ * Collection holding the bootstrap claim marker on MongoDB — the 12.0.0 document (`{ _id, claimedAt }`), kept so
+ * an older replica in a rolling deploy claims the same marker (see `infrastructure-locks.ts`).
  *
  * Native collection access is intentional here: no Mongoose schema exists for it
  * (see docs/native-driver-security.md).
  */
-const SETUP_LOCK_COLLECTION = 'system-setup-locks';
+const SETUP_LOCK_COLLECTION = SYSTEM_SETUP_LOCK_COLLECTION;
 
 /**
  * How long an initial-admin claim may stand before another replica takes it over.
@@ -23,10 +38,7 @@ const SETUP_LOCK_COLLECTION = 'system-setup-locks';
  * Long enough that a slow but live creation is never stolen, short enough that a crashed
  * claimer does not lock the deployment out for good.
  */
-const INITIAL_ADMIN_CLAIM_STALE_AFTER_MS = 5 * 60_000;
-
-/** `_id` of the marker claiming the initial-admin creation */
-const INITIAL_ADMIN_LOCK_ID = 'initial-admin';
+const INITIAL_ADMIN_CLAIM_STALE_AFTER_MS = SYSTEM_SETUP_CLAIM_STALE_AFTER_MS;
 
 /**
  * Input for creating the initial admin user
@@ -70,6 +82,9 @@ export interface SystemSetupStatus {
 export class CoreSystemSetupService implements OnApplicationBootstrap {
   private readonly logger = new Logger(CoreSystemSetupService.name);
 
+  /** Who holds the claim: one owner per instance, so a second concurrent claim of the same process is refused too */
+  private readonly claimOwner = `${hostname()}:${process.pid}:${randomUUID()}`;
+
   constructor(
     @InjectConnection() private readonly connection: Connection,
     private readonly betterAuthService: CoreBetterAuthService,
@@ -149,39 +164,19 @@ export class CoreSystemSetupService implements OnApplicationBootstrap {
   /**
    * Try to claim the initial-admin creation for this instance
    *
-   * The upsert on a fixed `_id` is atomic, so exactly one of N concurrently booting
-   * replicas sees no previous document and wins the claim.
+   * A lease (`LockStore`), so exactly one of N concurrently booting replicas — or of N anonymous
+   * `POST /system-setup/init` callers — wins the claim.
    *
    * @returns true when this instance may create the initial admin
    */
   protected async claimInitialAdminSetup(): Promise<boolean> {
-    try {
-      const collection = this.connection.collection(SETUP_LOCK_COLLECTION);
-
-      // The marker is a CLAIM, not a permanent record: a replica SIGKILLed between claiming and
-      // creating (OOM, node drain, a failed first rollout — all ordinary) never reaches the
-      // release in the catch below. Without an expiry that leaves a deployment with zero users
-      // and no way in, recoverable only by deleting a document from an undocumented collection.
-      // A stale claim is therefore taken over rather than obeyed.
-      const staleBefore = new Date(Date.now() - INITIAL_ADMIN_CLAIM_STALE_AFTER_MS);
-      await collection.deleteOne({ _id: INITIAL_ADMIN_LOCK_ID as any, claimedAt: { $lt: staleBefore } });
-
-      const previous = await collection.findOneAndUpdate(
-        { _id: INITIAL_ADMIN_LOCK_ID as any },
-        { $setOnInsert: { claimedAt: new Date() } },
-        { returnDocument: 'before', upsert: true },
-      );
-
-      // No previous document → this instance inserted the marker and owns the setup
-      return !previous;
-    } catch (error) {
-      // Two replicas upserting the same `_id` at the very same moment: one insert wins,
-      // the other gets a duplicate key error — which means the claim is taken.
-      if (error instanceof Error && (error.message?.includes('duplicate key') || error.message?.includes('E11000'))) {
-        return false;
-      }
-      throw error;
-    }
+    // The marker is a CLAIM, not a permanent record: a replica SIGKILLed between claiming and
+    // creating (OOM, node drain, a failed first rollout — all ordinary) never reaches the
+    // release in createInitialAdmin(). Without an expiry that leaves a deployment with zero users
+    // and no way in, recoverable only by deleting a document from an undocumented collection.
+    // A stale claim is therefore taken over rather than obeyed.
+    const locks = await this.setupLocks();
+    return locks.tryAcquire(SYSTEM_SETUP_LOCK_KEY, this.claimOwner, INITIAL_ADMIN_CLAIM_STALE_AFTER_MS / 1000);
   }
 
   /**
@@ -189,7 +184,7 @@ export class CoreSystemSetupService implements OnApplicationBootstrap {
    */
   protected async releaseInitialAdminSetupClaim(): Promise<void> {
     try {
-      await this.connection.collection(SETUP_LOCK_COLLECTION).deleteOne({ _id: INITIAL_ADMIN_LOCK_ID as any });
+      await (await this.setupLocks()).release(SYSTEM_SETUP_LOCK_KEY, this.claimOwner);
     } catch (error) {
       // Never mask the failure that triggered the release
       this.logger.warn(
@@ -198,11 +193,42 @@ export class CoreSystemSetupService implements OnApplicationBootstrap {
     }
   }
 
+  /**
+   * Where the claim lives: the lease table when the default data source is a SQL database, else the MongoDB marker
+   */
+  protected async setupLocks(): Promise<LockStore> {
+    return (
+      (await defaultSqlLockStore('system-setup')) ??
+      systemSetupMongoLocks(this.connection.collection(SETUP_LOCK_COLLECTION) as unknown as Collection<any>)
+    );
+  }
+
+  /**
+   * Where the claim lives, in the words an operator needs to clear it: the lease row on a SQL default source, the
+   * marker collection on MongoDB. The refusal log names it, so it must name the store `setupLocks()` actually uses.
+   */
+  protected async setupClaimLocation(): Promise<{ remedy: string; where: string }> {
+    if (await defaultSqlLockStore('system-setup')) {
+      const row = `system-setup:${SYSTEM_SETUP_LOCK_KEY}`;
+      return { remedy: `delete the row "${row}" from "lt_locks"`, where: `"lt_locks" (row "${row}")` };
+    }
+    return { remedy: `drop "${SETUP_LOCK_COLLECTION}"`, where: `"${SETUP_LOCK_COLLECTION}"` };
+  }
+
+  /**
+   * How many users exist, wherever the `users` table lives: a user model on a SQL source is counted there — counting the
+   * MongoDB collection instead would find none and let an anonymous caller create an administrator
+   */
+  protected async countUsers(): Promise<number> {
+    const users = getBetterAuthSqlStore()?.users ?? (await getPersistenceRuntime()?.iamStorage())?.users;
+    return users ? users.count({}) : this.connection.collection('users').countDocuments({});
+  }
+
   /**
    * Check if the system needs initial setup (zero users)
    */
   async getSetupStatus(): Promise<SystemSetupStatus> {
-    const userCount = await this.connection.collection('users').countDocuments({});
+    const userCount = await this.countUsers();
     return {
       betterAuthEnabled: this.betterAuthService.isEnabled(),
       needsSetup: userCount === 0,
@@ -217,7 +243,7 @@ export class CoreSystemSetupService implements OnApplicationBootstrap {
    */
   async createInitialAdmin(input: SystemSetupInitInput): Promise<SystemSetupInitResult> {
     // Pre-check: only allow when zero users exist
-    const userCount = await this.connection.collection('users').countDocuments({});
+    const userCount = await this.countUsers();
     if (userCount > 0) {
       throw new ForbiddenException(ErrorCode.SYSTEM_SETUP_NOT_AVAILABLE);
     }
@@ -253,11 +279,12 @@ export class CoreSystemSetupService implements OnApplicationBootstrap {
       // Two records with contradictory severity for one non-event trains operators to ignore the
       // louder one. The HTTP caller is not left without a diagnosis: the message is unchanged and
       // an operator investigating a 403 reads it at the default level.
+      const claim = await this.setupClaimLocation();
       this.logger.log(
-        `System setup refused: the initial-admin claim in "${SETUP_LOCK_COLLECTION}" is held. ` +
+        `System setup refused: the initial-admin claim in ${claim.where} is held. ` +
           'Either another instance is running the setup right now, or a previous SUCCESSFUL setup ' +
           'left the marker behind — it is removed only when creation FAILS. If you reset the ' +
-          `database to replay the setup, drop "${SETUP_LOCK_COLLECTION}" alongside "users"; ` +
+          `database to replay the setup, ${claim.remedy} alongside "users"; ` +
           `otherwise setup stays refused until the claim goes stale after ` +
           `${INITIAL_ADMIN_CLAIM_STALE_AFTER_MS / 60_000} minutes.`,
       );
@@ -334,10 +361,15 @@ export class CoreSystemSetupService implements OnApplicationBootstrap {
         throw new Error('Failed to sync user to nest-server collection');
       }
 
-      // Set admin role directly
-      await this.connection
-        .collection('users')
-        .updateOne({ _id: syncedUser._id }, { $set: { roles: ['admin'], updatedAt: new Date() } });
+      // Set admin role directly — the framework's own decision, as system work
+      const sql = getBetterAuthSqlStore();
+      if (sql) {
+        await sql.updateUserAsSystem(String(syncedUser._id), { roles: ['admin'] });
+      } else {
+        await this.connection
+          .collection('users')
+          .updateOne({ _id: syncedUser._id }, { $set: { roles: ['admin'], updatedAt: new Date() } });
+      }
 
       // Sync password to Legacy Auth for backwards compatibility
       await this.userMapper.syncPasswordToLegacy(iamUser.id, input.email, input.password);

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

@@ -247,11 +247,18 @@ for members, API tokens and the header-less tenant list — unless the project t
 ```typescript
 // config.env.ts
 multiTenancy: {
-  isTenantActive: async (tenantId, { connection }) =>
-    (await connection.collection('tenants').findOne({ _id: new Types.ObjectId(tenantId) }))?.active !== false,
+  // Any database: the project's tenant model, registered with CorePersistenceModule.forFeature()
+  isTenantActive: async (tenantId, { store }) => (await store('Tenant').findById(tenantId))?.active !== false,
 }
 ```
 
+`store(modelName)` returns the data store of a model registered with `CorePersistenceModule.forFeature()` in the
+running application, wherever `database` routes it. For a model registered any other way (`MongooseModule.forFeature()`,
+which `lt server module` generates) it throws a `DataSourceConfigError`, and the request is refused: answering
+`undefined` would make a hook written with `?.` count every deactivated tenant as active. `context.connection` (the MongoDB connection) is still passed
+for a lookup on MongoDB only:
+`(await connection.collection('tenants').findOne({ _id: new Types.ObjectId(tenantId) }))?.active !== false`.
+
 | Path                                                           | Deactivated tenant                                                                                                                                                                         |
 | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | Header + tenant role, or `S_USER` / `S_VERIFIED` with a header | **403** `#LTNS_0106: Tenant is inactive`                                                                                                                                                   |

package/src/core/modules/tenant/core-role-scope.registry.ts

@@ -1,6 +1,6 @@
-import { GLOBAL_ONLY_ROLES, isSystemRole, looksLikeSystemRole } from '../../common/enums/role.enum';
-import { ConfigService } from '../../common/services/config.service';
-import { DEFAULT_ROLE_HIERARCHY } from './core-tenant.enums';
+import { GLOBAL_ONLY_ROLES, isSystemRole, looksLikeSystemRole } from '../../common/enums/role.enum.js';
+import { ConfigService } from '../../common/services/config.service.js';
+import { DEFAULT_ROLE_HIERARCHY } from './core-tenant.enums.js';
 
 /**
  * Where a role's authority comes from — and therefore which source may answer it.

package/src/core/modules/tenant/core-tenant-member.model.ts

@@ -1,14 +1,14 @@
 import { ObjectType } from '@nestjs/graphql';
-import { Schema } from '@nestjs/mongoose';
+import { Schema } from '../../common/persistence/mongo/mongoose-compat.js';
 
-import { Restricted } from '../../common/decorators/restricted.decorator';
-import { UnifiedField } from '../../common/decorators/unified-field.decorator';
-import { RoleEnum } from '../../common/enums/role.enum';
-import { accessDeniedException } from '../../common/exceptions/access-denied.exception';
-import { CorePersistenceModel } from '../../common/models/core-persistence.model';
-import { RequestContext } from '../../common/services/request-context.service';
-import { DefaultHR, TenantMemberStatus } from './core-tenant.enums';
-import { checkRoleAccess } from './core-tenant.helpers';
+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 { accessDeniedException } from '../../common/exceptions/access-denied.exception.js';
+import { CorePersistenceModel } from '../../common/models/core-persistence.model.js';
+import { RequestContext } from '../../common/services/request-context.service.js';
+import { DefaultHR, TenantMemberStatus } from './core-tenant.enums.js';
+import { checkRoleAccess } from './core-tenant.helpers.js';
 
 /**
  * Core tenant member model (join table: User <-> Tenant).