@lenne.tech/nest-server 12.0.0 → 12.1.0

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 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-tenant-member.model.ts

@@ -1,5 +1,5 @@
 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.js';
 import { UnifiedField } from '../../common/decorators/unified-field.decorator.js';

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

@@ -0,0 +1,13 @@
+import type { DataStore } from '../../common/persistence/data-store.interface.js';
+import { getStoreForModel } from '../../common/persistence/persistence-runtime.registry.js';
+
+/**
+ * The store serving the membership model when it is routed to a SQL database; `undefined` on MongoDB, where the
+ * guard and the service keep their Mongoose path unchanged.
+ *
+ * Read from the model INSTANCE the guard and the service were given, so it is the store of their own application.
+ */
+export function routedMemberStore(memberModel: unknown): DataStore<any> | undefined {
+  const store = getStoreForModel(memberModel);
+  return store && !store.capabilities.mongoosePopulate ? store : undefined;
+}

package/src/core/modules/tenant/core-tenant.guard.ts

@@ -9,18 +9,23 @@ import {
   Optional,
   UnauthorizedException,
 } from '@nestjs/common';
-import { Reflector } from '@nestjs/core';
+import { ModuleRef, Reflector } from '@nestjs/core';
 import { GqlExecutionContext } from '@nestjs/graphql';
-import { InjectModel } from '@nestjs/mongoose';
-import { Model } from 'mongoose';
+import { InjectModel } from '../../common/persistence/mongo/mongoose-compat.js';
+import type { Model } from 'mongoose';
+import { firstValueFrom, isObservable } from 'rxjs';
 
 import { RoleEnum } from '../../common/enums/role.enum.js';
+import { ROLE_GUARD } from '../auth/guards/role-guard.token.js';
 import { resolveGuardRequest } from '../../common/helpers/execution-context-request.helper.js';
 import {
   revalidateAllWsConnections,
   revalidateWsConnectionsForTenant,
   revalidateWsConnectionsOf,
 } from '../../common/helpers/graphql-ws-connection.helper.js';
+import { DataSourceConfigError } from '../../common/persistence/data-source.config.js';
+import type { DataStore } from '../../common/persistence/data-store.interface.js';
+import { getStoreToken } from '../../common/persistence/persistence.tokens.js';
 import { ConfigService } from '../../common/services/config.service.js';
 import { ResolvedTenantContext, setTenantContextResolver } from '../../common/services/core-tenant-context.registry.js';
 import { CoreRedisService } from '../../common/services/core-redis.service.js';
@@ -33,6 +38,7 @@ import {
 } from '../api-token/core-api-token.helpers.js';
 import { ErrorCode } from '../error-code/error-codes.js';
 import { CoreTenantMemberModel } from './core-tenant-member.model.js';
+import { routedMemberStore } from './core-tenant-member.store.js';
 import { registerActiveTenantGuard } from './core-tenant-guard.registry.js';
 import { SKIP_TENANT_CHECK_KEY } from './core-tenant.decorators.js';
 import { TENANT_MEMBER_MODEL_TOKEN, TenantMemberStatus } from './core-tenant.enums.js';
@@ -171,6 +177,7 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
     private readonly reflector: Reflector,
     @InjectModel(TENANT_MEMBER_MODEL_TOKEN) private readonly memberModel: Model<CoreTenantMemberModel>,
     @Optional() protected readonly redisService?: CoreRedisService,
+    @Optional() protected readonly moduleRef?: ModuleRef,
   ) {
     // Clean up expired cache entries every 60 seconds
     this.cleanupInterval = setInterval(() => this.evictExpired(), 60_000);
@@ -189,6 +196,31 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
     this.releaseTenantGuard = registerActiveTenantGuard();
   }
 
+  /**
+   * The data store of a model registered with `CorePersistenceModule.forFeature()` in THIS application, for the
+   * `isTenantActive` hook — the tenant model may live in a SQL database, where `connection` cannot reach it.
+   *
+   * Throws for a model that is not registered that way, never answers `undefined`: the hook decides whether a
+   * deactivated tenant stays locked, and `store('Tenant')?.findById(id)` on an unregistered model would read as
+   * "active" — every tenant open, without a log line. A thrown error refuses the request instead.
+   */
+  protected readonly storeOf = (modelName: string): DataStore<any> => {
+    let store: DataStore<any> | undefined;
+    try {
+      store = this.moduleRef?.get(getStoreToken(modelName), { strict: false });
+    } catch {
+      store = undefined;
+    }
+    if (!store) {
+      throw new DataSourceConfigError(
+        `multiTenancy.isTenantActive asked for the store of '${modelName}', which is not registered with ` +
+          'CorePersistenceModule.forFeature() in this application — register it there, or look the tenant up ' +
+          'through context.connection',
+      );
+    }
+    return store;
+  };
+
   /** Releases this guard's registration (see core-tenant-guard.registry.ts). */
   private releaseTenantGuard?: () => void;
 
@@ -458,6 +490,14 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
       return true;
     }
 
+    // Global guards run in registration order, and CoreModule registers this module AHEAD of a project's AuthModule:
+    // with legacy JWTs (no middleware identifies them) the role guard has not run yet and nobody is on the request.
+    // The documented order is role guard, then tenant guard — so let this application's role guard identify the
+    // caller first. It decides exactly what it would decide right after this guard, so its 401/403 is the answer.
+    if (!request.user) {
+      await this.identifyThroughRoleGuard(context);
+    }
+
     const user = request.user;
     const adminBypass = config.adminBypass !== false;
     const isAdmin = adminBypass && user?.roles?.includes(RoleEnum.ADMIN);
@@ -679,14 +719,11 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
       }
     }
 
-    const memberships = await this.memberModel
-      .find({
-        status: TenantMemberStatus.ACTIVE,
-        user: userId,
-      })
-      .select('tenant role')
-      .lean()
-      .exec();
+    const active = { status: TenantMemberStatus.ACTIVE, user: userId };
+    const memberStore = routedMemberStore(this.memberModel);
+    const memberships = memberStore
+      ? await memberStore.find(active, { select: ['tenant', 'role'] })
+      : await this.memberModel.find(active).select('tenant role').lean().exec();
 
     let ids: string[];
     if (minLevel !== undefined) {
@@ -823,6 +860,32 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
     }
   }
 
+  /**
+   * Run this application's role guard when no caller is identified yet — see canActivate(). A no-op without one (a
+   * custom guard chain) and when the role guard is this guard.
+   */
+  protected async identifyThroughRoleGuard(context: ExecutionContext): Promise<void> {
+    let roleGuard: CanActivate | undefined;
+    try {
+      roleGuard = this.moduleRef?.get<CanActivate>(ROLE_GUARD, { strict: false });
+    } catch {
+      return;
+    }
+    if (roleGuard && roleGuard !== (this as CanActivate)) {
+      const result = roleGuard.canActivate(context);
+      await (isObservable(result) ? firstValueFrom(result) : result);
+    }
+  }
+
+  /** The active membership, from the membership store of the database the model is routed to */
+  private async findActiveMembership(userId: string, tenantId: string): Promise<CoreTenantMemberModel | null> {
+    const where = { status: TenantMemberStatus.ACTIVE, tenant: tenantId, user: userId };
+    const memberStore = routedMemberStore(this.memberModel);
+    return (
+      memberStore ? await memberStore.findOne(where) : await this.memberModel.findOne(where).lean().exec()
+    ) as CoreTenantMemberModel | null;
+  }
+
   /**
    * Look up a membership with process-level TTL cache.
    * Avoids repeated DB queries when the same user accesses the same tenant repeatedly.
@@ -832,10 +895,7 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
 
     // Cache disabled (ttl = 0): always query DB
     if (ttl <= 0) {
-      return this.memberModel
-        .findOne({ status: TenantMemberStatus.ACTIVE, tenant: tenantId, user: userId })
-        .lean()
-        .exec() as Promise<CoreTenantMemberModel | null>;
+      return this.findActiveMembership(userId, tenantId);
     }
 
     const key = `${userId}:${tenantId}`;
@@ -846,14 +906,7 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
       return cached.result;
     }
 
-    const result = (await this.memberModel
-      .findOne({
-        status: TenantMemberStatus.ACTIVE,
-        tenant: tenantId,
-        user: userId,
-      })
-      .lean()
-      .exec()) as CoreTenantMemberModel | null;
+    const result = await this.findActiveMembership(userId, tenantId);
 
     // Only cache positive results (active membership found).
     // Negative results (null) are NOT cached to ensure that:
@@ -928,7 +981,7 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
         return cached.active;
       }
     }
-    const active = (await hook(tenantId, { connection: this.memberModel.db })) !== false;
+    const active = (await hook(tenantId, { connection: this.memberModel.db, store: this.storeOf })) !== false;
     if (ttl > 0) {
       this.evictIfOverCapacity(this.tenantActiveCache);
       this.tenantActiveCache.set(tenantId, { active, expiresAt: now + ttl });

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

@@ -1,8 +1,9 @@
 import { CanActivate, DynamicModule, Global, Module, OnModuleDestroy, OnModuleInit, Type } from '@nestjs/common';
 import { APP_GUARD } from '@nestjs/core';
-import { MongooseModule, SchemaFactory, getModelToken } from '@nestjs/mongoose';
-import { Model } from 'mongoose';
+import { getModelToken, SchemaFactory } from '../../common/persistence/mongo/mongoose-compat.js';
+import type { Model } from 'mongoose';
 
+import { CorePersistenceModule } from '../../common/persistence/core-persistence.module.js';
 import { roleScopeRegistry } from './core-role-scope.registry.js';
 import { registerActiveTenantGuard } from './core-tenant-guard.registry.js';
 import { CoreTenantMemberModel } from './core-tenant-member.model.js';
@@ -127,7 +128,9 @@ export class CoreTenantModule implements OnModuleDestroy, OnModuleInit {
     return {
       exports: [CoreTenantService],
       global: true,
-      imports: [MongooseModule.forFeature([{ name: modelName, schema: memberSchema }])],
+      // Database-neutral registration: the membership model follows `database` like every other model, and the guard
+      // and the service switch to its store when it is routed to a SQL database
+      imports: [CorePersistenceModule.forFeature([{ name: modelName, schema: memberSchema }])],
       module: CoreTenantModule,
       providers,
     };

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

@@ -1,11 +1,13 @@
 import { BadRequestException, Injectable, Logger, NotFoundException, Optional } from '@nestjs/common';
-import { InjectModel } from '@nestjs/mongoose';
-import { Model } from 'mongoose';
+import { InjectModel } from '../../common/persistence/mongo/mongoose-compat.js';
+import type { Model } from 'mongoose';
 
 import { looksLikeGlobalOnlyRole, looksLikeSystemRole, SYSTEM_ROLE_PREFIX } from '../../common/enums/role.enum.js';
+import type { DataStore } from '../../common/persistence/data-store.interface.js';
 import { ConfigService } from '../../common/services/config.service.js';
 import { RequestContext } from '../../common/services/request-context.service.js';
 import { CoreTenantMemberModel } from './core-tenant-member.model.js';
+import { routedMemberStore } from './core-tenant-member.store.js';
 import { DEFAULT_ROLE_HIERARCHY, TENANT_MEMBER_MODEL_TOKEN, TenantMemberStatus } from './core-tenant.enums.js';
 import { CoreTenantGuard } from './core-tenant.guard.js';
 
@@ -37,6 +39,11 @@ export class CoreTenantService {
     @Optional() protected readonly tenantGuard?: CoreTenantGuard,
   ) {}
 
+  /** The membership store when the model is routed to SQL; `undefined` keeps the Mongoose path (MongoDB) */
+  protected get memberStore(): DataStore<any> | undefined {
+    return routedMemberStore(this.memberModel);
+  }
+
   /**
    * Get the configured role hierarchy.
    */
@@ -68,6 +75,11 @@ export class CoreTenantService {
    * Find all active tenant memberships for a user.
    */
   async findMemberships(userId: string): Promise<CoreTenantMemberModel[]> {
+    if (this.memberStore) {
+      return this.memberStore.find({ status: TenantMemberStatus.ACTIVE, user: userId }) as Promise<
+        CoreTenantMemberModel[]
+      >;
+    }
     return this.memberModel.find({ status: TenantMemberStatus.ACTIVE, user: userId }).lean().exec() as Promise<
       CoreTenantMemberModel[]
     >;
@@ -92,6 +104,9 @@ export class CoreTenantService {
    * For an authorization check use {@link getActiveMembership}.
    */
   async getMembership(tenantId: string, userId: string): Promise<CoreTenantMemberModel | null> {
+    if (this.memberStore) {
+      return this.memberStore.findOne({ tenant: tenantId, user: userId }) as Promise<CoreTenantMemberModel | null>;
+    }
     return this.memberModel
       .findOne({ tenant: tenantId, user: userId })
       .lean()
@@ -111,10 +126,11 @@ export class CoreTenantService {
       return null;
     }
 
-    return this.memberModel
-      .findOne({ status: TenantMemberStatus.ACTIVE, tenant: tenantId, user: userId })
-      .lean()
-      .exec() as Promise<CoreTenantMemberModel | null>;
+    const where = { status: TenantMemberStatus.ACTIVE, tenant: tenantId, user: userId };
+    if (this.memberStore) {
+      return this.memberStore.findOne(where) as Promise<CoreTenantMemberModel | null>;
+    }
+    return this.memberModel.findOne(where).lean().exec() as Promise<CoreTenantMemberModel | null>;
   }
 
   /**
@@ -146,33 +162,40 @@ export class CoreTenantService {
       }
       // Reactivate suspended/invited membership
       return RequestContext.runWithBypassTenantGuard(async () => {
-        const result = (await this.memberModel
-          .findOneAndUpdate(
-            { tenant: tenantId, user: userId },
-            {
-              invitedBy: invitedById,
-              joinedAt: new Date(),
-              role: effectiveRole,
-              status: TenantMemberStatus.ACTIVE,
-            },
-            { returnDocument: 'after' },
-          )
-          .lean()
-          .exec()) as CoreTenantMemberModel;
+        const reactivation = {
+          invitedBy: invitedById,
+          joinedAt: new Date(),
+          role: effectiveRole,
+          status: TenantMemberStatus.ACTIVE,
+        };
+        const result = (
+          this.memberStore
+            ? await this.memberStore.updateOne({ tenant: tenantId, user: userId }, reactivation)
+            : await this.memberModel
+                .findOneAndUpdate({ tenant: tenantId, user: userId }, reactivation, { returnDocument: 'after' })
+                .lean()
+                .exec()
+        ) as CoreTenantMemberModel;
         this.tenantGuard?.invalidateUser(userId);
         return result;
       });
     }
 
     return RequestContext.runWithBypassTenantGuard(async () => {
-      const doc = await this.memberModel.create({
+      const member = {
         invitedBy: invitedById,
         joinedAt: new Date(),
         role: effectiveRole,
         status: TenantMemberStatus.ACTIVE,
         tenant: tenantId,
         user: userId,
-      });
+      };
+      if (this.memberStore) {
+        const created = await this.memberStore.insert(member);
+        this.tenantGuard?.invalidateUser(userId);
+        return created as CoreTenantMemberModel;
+      }
+      const doc = await this.memberModel.create(member);
       this.tenantGuard?.invalidateUser(userId);
       return doc.toObject() as CoreTenantMemberModel;
     });
@@ -192,14 +215,13 @@ export class CoreTenantService {
     await this.assertNotLastOwner(tenantId, userId);
 
     return RequestContext.runWithBypassTenantGuard(async () => {
-      const result = await this.memberModel
-        .findOneAndUpdate(
-          { status: TenantMemberStatus.ACTIVE, tenant: tenantId, user: userId },
-          { status: TenantMemberStatus.SUSPENDED },
-          { returnDocument: 'after' },
-        )
-        .lean()
-        .exec();
+      const where = { status: TenantMemberStatus.ACTIVE, tenant: tenantId, user: userId };
+      const result = this.memberStore
+        ? await this.memberStore.updateOne(where, { status: TenantMemberStatus.SUSPENDED })
+        : await this.memberModel
+            .findOneAndUpdate(where, { status: TenantMemberStatus.SUSPENDED }, { returnDocument: 'after' })
+            .lean()
+            .exec();
 
       if (!result) {
         throw new NotFoundException('Membership not found');
@@ -237,14 +259,10 @@ export class CoreTenantService {
     }
 
     return RequestContext.runWithBypassTenantGuard(async () => {
-      const result = await this.memberModel
-        .findOneAndUpdate(
-          { status: TenantMemberStatus.ACTIVE, tenant: tenantId, user: userId },
-          { role },
-          { returnDocument: 'after' },
-        )
-        .lean()
-        .exec();
+      const where = { status: TenantMemberStatus.ACTIVE, tenant: tenantId, user: userId };
+      const result = this.memberStore
+        ? await this.memberStore.updateOne(where, { role })
+        : await this.memberModel.findOneAndUpdate(where, { role }, { returnDocument: 'after' }).lean().exec();
 
       if (!result) {
         throw new NotFoundException('Active membership not found');
@@ -267,11 +285,10 @@ export class CoreTenantService {
     const highestRole = this.getHighestRole();
 
     return RequestContext.runWithBypassTenantGuard(async () => {
-      const ownerCount = await this.memberModel.countDocuments({
-        role: highestRole,
-        status: TenantMemberStatus.ACTIVE,
-        tenant: tenantId,
-      });
+      const owners = { role: highestRole, status: TenantMemberStatus.ACTIVE, tenant: tenantId };
+      const ownerCount = this.memberStore
+        ? await this.memberStore.count(owners)
+        : await this.memberModel.countDocuments(owners);
 
       if (ownerCount <= 1) {
         const membership = await this.getActiveMembership(tenantId, userId);