@lenne.tech/nest-server 12.0.0 → 12.1.0

package/src/core/modules/ai/services/core-ai-tool-grant.service.ts

@@ -1,7 +1,8 @@
 import { Inject, Injectable, Logger } 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 { upsertRecord } from '../../../common/persistence/store-upsert.js';
 import { CrudService } from '../../../common/services/crud.service.js';
 import type { CoreModelConstructor } from '../../../common/types/core-model-constructor.type.js';
 import { AiToolGrantDocument, CoreAiToolGrant } from '../models/core-ai-tool-grant.model.js';
@@ -60,17 +61,14 @@ export class CoreAiToolGrantService extends CrudService<CoreAiToolGrant, CoreAiT
     const now = new Date();
     for (const c of candidates) {
       try {
-        const grant = await this.mainDbModel
-          .findOne({
-            $or: [{ expiresAt: { $exists: false } }, { expiresAt: null }, { expiresAt: { $gt: now } }],
-            decision: { $ne: 'deny' },
-            enabled: { $ne: false },
-            refId: c.refId,
-            scope: c.scope,
-            tool,
-          })
-          .lean<CoreAiToolGrant>()
-          .exec();
+        const grant = await this.dataStore.findOne({
+          $or: [{ expiresAt: { $exists: false } }, { expiresAt: null }, { expiresAt: { $gt: now } }],
+          decision: { $ne: 'deny' },
+          enabled: { $ne: false },
+          refId: c.refId,
+          scope: c.scope,
+          tool,
+        });
         if (grant) {
           return c.scope;
         }
@@ -90,20 +88,12 @@ export class CoreAiToolGrantService extends CrudService<CoreAiToolGrant, CoreAiT
       return;
     }
     try {
-      await this.mainDbModel
-        .updateOne(
-          { refId, scope, tool },
-          {
-            $set: {
-              decision: 'allow',
-              enabled: true,
-              expiresAt: options?.expiresAt ?? null,
-            },
-            $setOnInsert: { refId, scope, tool },
-          },
-          { upsert: true },
-        )
-        .exec();
+      // Upserts on the unique (scope, refId, tool) index
+      await upsertRecord(
+        this.dataStore,
+        { refId, scope, tool },
+        { decision: 'allow', enabled: true, expiresAt: options?.expiresAt ?? null },
+      );
     } catch (err) {
       this.logger.warn(`Could not persist tool grant (${scope}:${refId}:${tool}): ${(err as Error).message}`);
     }

package/src/core/modules/ai/services/core-ai-tool-policy.service.ts

@@ -1,6 +1,6 @@
 import { Inject, Injectable, Logger } 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 { CrudService } from '../../../common/services/crud.service.js';
 import type { CoreModelConstructor } from '../../../common/types/core-model-constructor.type.js';
@@ -77,14 +77,11 @@ export class CoreAiToolPolicyService extends CrudService<CoreAiToolPolicy, CoreA
 
     let policies: CoreAiToolPolicy[] = [];
     try {
-      policies = await this.mainDbModel
-        .find({
-          $or: refCandidates.map((c) => ({ refId: c.refId ?? null, scope: c.scope })),
-          enabled: { $ne: false },
-          tool,
-        })
-        .lean<CoreAiToolPolicy[]>()
-        .exec();
+      policies = (await this.dataStore.find({
+        $or: refCandidates.map((c) => ({ refId: c.refId ?? null, scope: c.scope })),
+        enabled: { $ne: false },
+        tool,
+      })) as CoreAiToolPolicy[];
     } catch {
       return undefined;
     }

package/src/core/modules/api-token/core-api-token.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/api-token/core-api-token.module.ts

@@ -1,6 +1,7 @@
 import { DynamicModule, Global, MiddlewareConsumer, Module, NestModule, Type } from '@nestjs/common';
-import { MongooseModule, SchemaFactory } from '@nestjs/mongoose';
+import { SchemaFactory } from '../../common/persistence/mongo/mongoose-compat.js';
 
+import { CorePersistenceModule } from '../../common/persistence/core-persistence.module.js';
 import { API_TOKEN_MODEL_TOKEN } from './core-api-token.constants.js';
 import { CoreApiTokenMiddleware } from './core-api-token.middleware.js';
 import { CoreApiTokenModel } from './core-api-token.model.js';
@@ -36,7 +37,8 @@ export class CoreApiTokenModule implements NestModule {
     return {
       exports: [CoreApiTokenService],
       global: true,
-      imports: [MongooseModule.forFeature([{ name: API_TOKEN_MODEL_TOKEN, schema }])],
+      // Database-neutral registration: the token model follows `database` like every other model
+      imports: [CorePersistenceModule.forFeature([{ name: API_TOKEN_MODEL_TOKEN, schema }])],
       module: CoreApiTokenModule,
       providers: [{ provide: CoreApiTokenService, useClass: options.service || CoreApiTokenService }],
     };

package/src/core/modules/api-token/core-api-token.service.ts

@@ -11,10 +11,17 @@ import {
   Optional,
   UnauthorizedException,
 } from '@nestjs/common';
-import { InjectConnection, InjectModel } from '@nestjs/mongoose';
-import { type Connection, Model, Types } from 'mongoose';
+import { ModuleRef } from '@nestjs/core';
+import { InjectConnection, InjectModel } from '../../common/persistence/mongo/mongoose-compat.js';
+import type { Connection, Model } from 'mongoose';
+import type { Types } from 'mongoose';
 
 import { RoleEnum } from '../../common/enums/role.enum.js';
+import type { DataStore } from '../../common/persistence/data-store.interface.js';
+import { isWellFormedId } from '../../common/persistence/id-format.js';
+import { getModelDescriptor } from '../../common/persistence/model-metadata.registry.js';
+import { getStoreForModel } from '../../common/persistence/persistence-runtime.registry.js';
+import { getStoreToken } from '../../common/persistence/persistence.tokens.js';
 import { ConfigService } from '../../common/services/config.service.js';
 import { CoreRedisService } from '../../common/services/core-redis.service.js';
 import { InMemoryRateLimitStore, RateLimitStore, RedisRateLimitStore } from '../../common/services/rate-limit-store.js';
@@ -44,6 +51,7 @@ import {
 } from './core-api-token.helpers.js';
 import { CoreApiTokenModel } from './core-api-token.model.js';
 import { ApiTokenOwnerIdentity, setApiTokenRevoker } from './core-api-token.registry.js';
+import { newObjectId } from '../../common/persistence/mongo/mongoose-compat.js';
 
 /** Fields a caller can never set through a create/update input. */
 const PROTECTED_FIELDS = new Set([
@@ -65,6 +73,24 @@ const PROTECTED_FIELDS = new Set([
 ]);
 
 /** User fields never loaded onto a token-authenticated request user. */
+/** Name of the user model whose store a token owner is loaded from on a SQL database */
+const API_TOKEN_USER_MODEL = 'User';
+
+/** A filter built for MongoDB (`_id`) as the neutral filter of a data store (`id`) */
+function toNeutralFilter(filter: Record<string, unknown>): Record<string, unknown> {
+  const { _id, ...rest } = filter;
+  return _id === undefined ? rest : { ...rest, id: String(_id) };
+}
+
+/** A user record without the fields `USER_SECRET_PROJECTION` keeps out of a request user */
+function withoutSecrets(record: Record<string, any>): Record<string, any> {
+  const copy = { ...record };
+  for (const field of Object.keys(USER_SECRET_PROJECTION)) {
+    delete copy[field];
+  }
+  return copy;
+}
+
 const USER_SECRET_PROJECTION = {
   password: 0,
   passwordResetToken: 0,
@@ -161,8 +187,30 @@ export class CoreApiTokenService implements OnModuleDestroy, OnModuleInit {
     @Optional() @InjectConnection() protected readonly connection?: Connection,
     @Optional() protected readonly tenantService?: CoreTenantService,
     @Optional() protected readonly redisService?: CoreRedisService,
+    @Optional() protected readonly moduleRef?: ModuleRef,
   ) {}
 
+  /** The token store when the token model is routed to SQL; `undefined` keeps the Mongoose path (MongoDB) */
+  protected get tokenStore(): DataStore<any> | undefined {
+    const store = getStoreForModel(this.apiTokenModel);
+    return store && !store.capabilities.mongoosePopulate ? store : undefined;
+  }
+
+  /**
+   * The users' store when the user model (`User`) is routed to SQL: a token's owner is loaded from where the users
+   * live. `undefined` keeps the `users` collection, the document Better-Auth and the legacy strategy resolve on MongoDB.
+   * `protected` so a project whose user model has another name can return its store.
+   */
+  protected userStore(): DataStore<any> | undefined {
+    let store: DataStore<any> | undefined;
+    try {
+      store = this.moduleRef?.get(getStoreToken(API_TOKEN_USER_MODEL), { strict: false });
+    } catch {
+      return undefined;
+    }
+    return store && !store.capabilities.mongoosePopulate ? store : undefined;
+  }
+
   onModuleInit(): void {
     assertApiTokenConfigIsUsable();
     // Let the password-reset paths (Better-Auth hook, legacy resetPassword) revoke user tokens
@@ -262,10 +310,13 @@ export class CoreApiTokenService implements OnModuleDestroy, OnModuleInit {
       this.lastUsedWrites.clear();
     }
     this.lastUsedWrites.set(tokenId, now);
-    this.apiTokenModel
-      .updateOne({ _id: tokenId }, { $set: { lastUsedAt: new Date(now) } }, { timestamps: false })
-      .exec()
-      .catch((error: Error) => this.logger.debug(`lastUsedAt update failed: ${error.message}`));
+    const tokens = this.tokenStore;
+    const write = tokens
+      ? tokens.updateById(tokenId, { $set: { lastUsedAt: new Date(now) } }, { timestamps: false })
+      : this.apiTokenModel
+          .updateOne({ _id: tokenId }, { $set: { lastUsedAt: new Date(now) } }, { timestamps: false })
+          .exec();
+    write.catch((error: Error) => this.logger.debug(`lastUsedAt update failed: ${error.message}`));
   }
 
   /** A token that may authenticate right now: known, not revoked, not expired, kind enabled. */
@@ -273,11 +324,14 @@ export class CoreApiTokenService implements OnModuleDestroy, OnModuleInit {
     publicId: string,
     config: IResolvedApiTokenConfig,
   ): Promise<CoreApiTokenModel | null> {
-    const token = (await this.apiTokenModel
-      .findOne({ publicId })
-      .select('+secretHash +signingKeyEncrypted')
-      .lean()
-      .exec()) as (CoreApiTokenModel & { _id: Types.ObjectId }) | null;
+    const tokens = this.tokenStore;
+    const token = (
+      tokens
+        ? await tokens
+            .findOne({ publicId }, { select: Object.keys(getModelDescriptor(tokens.modelName)?.fields ?? {}) })
+            .then((record) => record && { ...record, _id: record.id })
+        : await this.apiTokenModel.findOne({ publicId }).select('+secretHash +signingKeyEncrypted').lean().exec()
+    ) as (CoreApiTokenModel & { _id: Types.ObjectId | string }) | null;
     if (!token || token.revokedAt || (token.expiresAt && new Date(token.expiresAt).getTime() <= Date.now())) {
       return null;
     }
@@ -323,12 +377,15 @@ export class CoreApiTokenService implements OnModuleDestroy, OnModuleInit {
    * `protected` so a project with a different user store can override it.
    */
   protected async loadTokenUser(userId: string): Promise<null | Record<string, any>> {
-    if (!this.connection || !userId || !Types.ObjectId.isValid(userId)) {
+    const users = this.userStore();
+    if ((!users && !this.connection) || !userId || !isWellFormedId(userId)) {
       return null;
     }
-    const doc = await this.connection
-      .collection('users')
-      .findOne({ _id: new Types.ObjectId(userId) }, { projection: USER_SECRET_PROJECTION });
+    const doc = users
+      ? await users.findById(userId).then((record) => record && withoutSecrets({ ...record, _id: record.id }))
+      : await this.connection
+          .collection('users')
+          .findOne({ _id: newObjectId(userId) }, { projection: USER_SECRET_PROJECTION });
     if (!doc) {
       return null;
     }
@@ -425,12 +482,11 @@ export class CoreApiTokenService implements OnModuleDestroy, OnModuleInit {
    * or when the user is blocked. Returns the number of tokens revoked.
    */
   async revokeAllForUser(userId: string): Promise<number> {
-    const result = await this.apiTokenModel
-      .updateMany(
-        { kind: ApiTokenKind.USER, revokedAt: null, user: String(userId) },
-        { $set: { revokedAt: new Date() } },
-      )
-      .exec();
+    const active = { kind: ApiTokenKind.USER, revokedAt: null, user: String(userId) };
+    if (this.tokenStore) {
+      return this.tokenStore.updateMany(active, { $set: { revokedAt: new Date() } });
+    }
+    const result = await this.apiTokenModel.updateMany(active, { $set: { revokedAt: new Date() } }).exec();
     return result.modifiedCount ?? 0;
   }
 
@@ -441,19 +497,25 @@ export class CoreApiTokenService implements OnModuleDestroy, OnModuleInit {
    */
   async revokeAllForOwner(identity: ApiTokenOwnerIdentity): Promise<number> {
     let userId = identity?.userId;
-    if (!userId && this.connection && (identity?.email || identity?.iamId)) {
+    const users = this.userStore();
+    if (!userId && (users || this.connection) && (identity?.email || identity?.iamId)) {
       const or: Record<string, string>[] = [];
       if (identity.email) or.push({ email: identity.email });
       if (identity.iamId) or.push({ iamId: identity.iamId });
-      const doc = await this.connection.collection('users').findOne({ $or: or }, { projection: { _id: 1 } });
-      userId = doc?._id?.toString();
+      userId = users
+        ? (await users.findOne({ $or: or }, { select: ['id'] }))?.id
+        : (await this.connection.collection('users').findOne({ $or: or }, { projection: { _id: 1 } }))?._id?.toString();
     }
     return userId ? this.revokeAllForUser(userId) : 0;
   }
 
   /** Delete every token of a user (system operation, no rights check) — call it when deleting the user. */
   async deleteAllForUser(userId: string): Promise<number> {
-    const result = await this.apiTokenModel.deleteMany({ kind: ApiTokenKind.USER, user: String(userId) }).exec();
+    const owned = { kind: ApiTokenKind.USER, user: String(userId) };
+    if (this.tokenStore) {
+      return this.tokenStore.deleteMany(owned);
+    }
+    const result = await this.apiTokenModel.deleteMany(owned).exec();
     return result.deletedCount ?? 0;
   }
 
@@ -536,6 +598,9 @@ export class CoreApiTokenService implements OnModuleDestroy, OnModuleInit {
     if (!tenantId?.trim()) {
       throw new BadRequestException('tenantId must not be empty');
     }
+    if (this.tokenStore) {
+      return this.tokenStore.deleteMany({ tenant: tenantId });
+    }
     const result = await this.apiTokenModel.deleteMany({ tenant: tenantId }).exec();
     return result.deletedCount ?? 0;
   }
@@ -632,7 +697,7 @@ export class CoreApiTokenService implements OnModuleDestroy, OnModuleInit {
     const config = getApiTokenConfig();
     const { publicId, secret, token } = generateApiToken(config.prefix);
     const signingKey = generateApiTokenSigningKey();
-    const created = await this.apiTokenModel.create({
+    const record = {
       ...document,
       createdBy: String(currentUser.id),
       publicId,
@@ -640,12 +705,18 @@ export class CoreApiTokenService implements OnModuleDestroy, OnModuleInit {
       secretHash: hashApiTokenSecret(secret),
       signingKeyEncrypted: this.encryptSigningKey(signingKey),
       updatedBy: String(currentUser.id),
-    });
+    };
+    if (this.tokenStore) {
+      return { apiToken: this.toInfo(await this.tokenStore.insert(record)), signingKey, token };
+    }
+    const created = await this.apiTokenModel.create(record);
     return { apiToken: this.toInfo(created.toObject()), signingKey, token };
   }
 
   protected async list(filter: Record<string, unknown>): Promise<ApiTokenInfo[]> {
-    const tokens = await this.apiTokenModel.find(filter).sort({ createdAt: -1 }).lean().exec();
+    const tokens = this.tokenStore
+      ? await this.tokenStore.find(toNeutralFilter(filter), { sort: { createdAt: -1 } })
+      : await this.apiTokenModel.find(filter).sort({ createdAt: -1 }).lean().exec();
     return tokens.map((token) => this.toInfo(token));
   }
 
@@ -654,10 +725,10 @@ export class CoreApiTokenService implements OnModuleDestroy, OnModuleInit {
     $set: Record<string, unknown>,
     currentUser: any,
   ): Promise<ApiTokenInfo> {
-    const updated = await this.apiTokenModel
-      .findOneAndUpdate(filter, { $set: { ...$set, updatedBy: String(currentUser.id) } }, { returnDocument: 'after' })
-      .lean()
-      .exec();
+    const update = { $set: { ...$set, updatedBy: String(currentUser.id) } };
+    const updated = this.tokenStore
+      ? await this.tokenStore.updateOne(toNeutralFilter(filter), update)
+      : await this.apiTokenModel.findOneAndUpdate(filter, update, { returnDocument: 'after' }).lean().exec();
     if (!updated) {
       throw new NotFoundException('API token not found');
     }
@@ -665,19 +736,21 @@ export class CoreApiTokenService implements OnModuleDestroy, OnModuleInit {
   }
 
   protected async applyRevoke(filter: Record<string, unknown>, currentUser: any): Promise<ApiTokenInfo> {
-    const revoked = await this.apiTokenModel
-      .findOneAndUpdate(
-        { ...filter, revokedAt: null },
-        { $set: { revokedAt: new Date(), updatedBy: String(currentUser.id) } },
-        { returnDocument: 'after' },
-      )
-      .lean()
-      .exec();
+    const revocation = { $set: { revokedAt: new Date(), updatedBy: String(currentUser.id) } };
+    const tokens = this.tokenStore;
+    const revoked = tokens
+      ? await tokens.updateOne(toNeutralFilter({ ...filter, revokedAt: null }), revocation)
+      : await this.apiTokenModel
+          .findOneAndUpdate({ ...filter, revokedAt: null }, revocation, { returnDocument: 'after' })
+          .lean()
+          .exec();
     if (revoked) {
       return this.toInfo(revoked);
     }
     // Already revoked: answer with the current state rather than an error.
-    const existing = await this.apiTokenModel.findOne(filter).lean().exec();
+    const existing = tokens
+      ? await tokens.findOne(toNeutralFilter(filter))
+      : await this.apiTokenModel.findOne(filter).lean().exec();
     if (!existing) {
       throw new NotFoundException('API token not found');
     }
@@ -685,7 +758,9 @@ export class CoreApiTokenService implements OnModuleDestroy, OnModuleInit {
   }
 
   protected async applyDelete(filter: Record<string, unknown>): Promise<ApiTokenInfo> {
-    const deleted = await this.apiTokenModel.findOneAndDelete(filter).lean().exec();
+    const deleted = this.tokenStore
+      ? await this.tokenStore.deleteOne(toNeutralFilter(filter))
+      : await this.apiTokenModel.findOneAndDelete(filter).lean().exec();
     if (!deleted) {
       throw new NotFoundException('API token not found');
     }
@@ -705,7 +780,7 @@ export class CoreApiTokenService implements OnModuleDestroy, OnModuleInit {
     if (typeof tokenId !== 'string' || !/^[0-9a-f]{24}$/i.test(tokenId)) {
       throw new NotFoundException('API token not found');
     }
-    return new Types.ObjectId(tokenId);
+    return newObjectId(tokenId);
   }
 
   protected commonUpdate(input: IUpdateApiTokenInput, config: IResolvedApiTokenConfig): Record<string, unknown> {

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

@@ -9,6 +9,7 @@ import { CoreRedisService } from '../../common/services/core-redis.service.js';
 import { AuthGuardStrategy } from './auth-guard-strategy.enum.js';
 import { LegacyAuthRateLimitGuard } from './guards/legacy-auth-rate-limit.guard.js';
 import { RolesGuardRegistry } from './guards/roles-guard-registry.js';
+import { ROLE_GUARD } from './guards/role-guard.token.js';
 import { RolesGuard } from './guards/roles.guard.js';
 import { CoreAuthUserService } from './services/core-auth-user.service.js';
 import { CoreAuthService } from './services/core-auth.service.js';
@@ -59,6 +60,7 @@ export class CoreAuthModule {
           return [
             RolesGuard, // Register as regular provider first
             { provide: APP_GUARD, useExisting: RolesGuard }, // Reference the registered provider
+            { provide: ROLE_GUARD, useExisting: RolesGuard }, // How CoreTenantGuard reaches it
           ];
         })();
 

package/src/core/modules/auth/guards/legacy-auth-rate-limit.guard.ts

@@ -76,9 +76,10 @@ export class LegacyAuthRateLimitGuard implements CanActivate {
     const request = context.switchToHttp().getRequest();
     const ip = this.getClientIp(request);
 
-    // Get endpoint from URL path
-    const url = request.url || request.path || '';
-    const endpoint = url.split('/').pop() || 'unknown';
+    // The handler, never the URL: the URL carries the query string and the client's spelling of the path
+    // (Express routes case-insensitively and ignores a trailing slash), so every variant was a fresh bucket and
+    // `/auth/signin?n=1`, `?n=2`, … guessed passwords without ever reaching the limit.
+    const endpoint = context.getHandler()?.name || 'unknown';
 
     return { endpoint, ip };
   }

package/src/core/modules/auth/guards/role-guard.token.ts

@@ -0,0 +1,7 @@
+/**
+ * DI token under which the module that registers the global role guard (`RolesGuard` in `CoreAuthModule`,
+ * `BetterAuthRolesGuard` in `CoreBetterAuthModule`) also provides it — so `CoreTenantGuard` reaches the role guard of
+ * its own application without importing it. Import-free leaf (see `.claude/rules/architecture.md` → "DI Token
+ * Placement (SWC-Safe)").
+ */
+export const ROLE_GUARD = 'LtRoleGuard';

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

@@ -130,16 +130,30 @@ export class CoreAuthService {
       throw new UnauthorizedException(ErrorCode.INVALID_TOKEN);
     }
 
+    // A device is ended by writing `null` for it, not by deleting its key: update() MERGES the input into the stored
+    // record, so a key that is merely missing from the input survives — and with it the refresh token this logout
+    // must end. `validateUser()` reads a `null` device as "not signed in".
+    const ended = (deviceIds: string[]) => Object.fromEntries(deviceIds.map((id) => [id, null]));
+
     // Logout from all devices
     if (serviceOptions.allDevices) {
+      const deviceIds = Object.keys(user.refreshTokens);
       user.refreshTokens = {};
-      await this.userService.update(user.id, { refreshTokens: {} }, serviceOptions);
+      await this.userService.update(
+        user.id,
+        { refreshTokens: ended(deviceIds), tempTokens: ended(Object.keys(user.tempTokens ?? {})) },
+        serviceOptions,
+      );
       return true;
     }
 
     // Logout from specific devices
     delete user.refreshTokens[deviceId];
-    await this.userService.update(user.id, { refreshTokens: user.refreshTokens }, serviceOptions);
+    await this.userService.update(
+      user.id,
+      { refreshTokens: ended([deviceId]), tempTokens: ended([deviceId]) },
+      serviceOptions,
+    );
     return true;
   }
 

package/src/core/modules/better-auth/INTEGRATION-CHECKLIST.md

@@ -673,7 +673,7 @@ In JWT mode (`cookies: false`), the server stores WebAuthn challenges in the dat
 
 | Mode                                | Challenge Storage                                  | Client Approach         |
 | ----------------------------------- | -------------------------------------------------- | ----------------------- |
-| Cookie (`cookies: true` or not set) | Cookie (`better-auth.better-auth-passkey`)         | Either approach works   |
+| Cookie (`cookies: true` or not set) | Cookie (`iam.better-auth-passkey`)                 | Either approach works   |
 | JWT (`cookies: false`)              | Database with `challengeId` mapping (auto-enabled) | **Must use composable** |
 
 **Note:** Database challenge storage is automatically enabled when `options.cookies: false` is set. No additional configuration is required.

package/src/core/modules/better-auth/README.md

@@ -1083,6 +1083,15 @@ social sign-in after the upgrade — see
 > `providerId` alone on purpose, so they keep working on rows the backfill has not reached yet —
 > which matters most when the backfill has failed.
 
+### Storage on a SQL source
+
+When the user model (table `users`) is routed to a SQL source through `database`, Better-Auth follows it: it runs its
+built-in Kysely adapter on that source's application pool and shares ONE `users` row per user with the user model.
+Its tables are snake_case (`session`, `account`, `verification`, `jwks`, `two_factor`, `passkey`), ids keep the
+ObjectId format, and its migrations run at boot as the owner (`database.ownerUrl`) — without an owner connection the
+boot stops while any are pending. The two MongoDB steps above are skipped there. Nothing is copied from MongoDB.
+Details: `.claude/rules/better-auth.md` §11.
+
 ---
 
 ## Module Setup
@@ -1757,7 +1766,7 @@ const legacyToken = await authService.signIn({ email, password });
 
 ### Key Points
 
-1. **Shared Users Collection**: Both systems use the same `users` MongoDB collection
+1. **Shared Users Collection**: Both systems use the same `users` collection — on MongoDB, or one `users` table when the user model is routed to a SQL source (see [Storage on a SQL source](#storage-on-a-sql-source))
 2. **bcrypt Compatibility**: Both systems use bcrypt - passwords work with either system
 3. **User Linking**: When a user logs in via Better-Auth, `iamId` is set to link them
 4. **Role Preservation**: User roles work with both systems