@lenne.tech/nest-server 12.0.0 → 12.1.0

package/src/core/modules/better-auth/better-auth-sql.helper.ts

@@ -0,0 +1,191 @@
+import { getAuthTables } from 'better-auth/db';
+import { getMigrations } from 'better-auth/db/migration';
+
+import { DataSourceConfigError } from '../../common/persistence/data-source.config.js';
+import { generateId } from '../../common/persistence/id-format.js';
+import { type IamSqlStorage, registerForeignColumns } from '../../common/persistence/persistence-runtime.registry.js';
+import { columnName, quoteIdentifier } from '../../common/persistence/sql/sql-naming.js';
+
+/** The table Better-Auth shares with the user model — created and owned by the framework */
+const USERS_TABLE = 'users';
+
+/**
+ * Better-Auth's own fields of the user row that the user model does not declare. Their columns are Better-Auth's, not
+ * left-overs of a removed field: the framework's schema evolution must not report them at every boot.
+ */
+registerForeignColumns(USERS_TABLE, ['email_verified', 'image', 'name']);
+
+/** Postgres column type of a Better-Auth field, for a column the framework adds before Better-Auth's migration */
+const SQL_TYPES: Record<string, string> = {
+  boolean: 'boolean',
+  date: 'timestamptz',
+  json: 'jsonb',
+  number: 'integer',
+  'number[]': 'jsonb',
+  string: 'text',
+  'string[]': 'jsonb',
+};
+
+/** The tables Better-Auth's own options name (models of plugins come from the plugins) */
+const CORE_MODELS = ['user', 'session', 'account', 'verification'] as const;
+
+type Options = Record<string, any>;
+
+/**
+ * Better-Auth on a SQL data source: its built-in Kysely adapter on the given `pg` pool (Better-Auth recognises the
+ * pool and builds its own Kysely instance — the core imports no Kysely), ids in the framework's format, and every table
+ * and column named the way the framework names it.
+ *
+ * Naming is not cosmetic. Better-Auth and the user model share ONE row per user in `users`: the framework creates that
+ * table from the user model, its column for a field is `columnName(field)` (`firstName` → `first_name`), and Better-Auth
+ * must address exactly those columns — a second, camelCase `firstName` column would split one value in two. Applying the
+ * same rule to every name Better-Auth uses (the stored name it has on MongoDB, snake-cased) covers the user model's
+ * fields, Better-Auth's own tables and every plugin's tables, the project's plugins included, with no list to maintain.
+ * On MongoDB nothing of this applies: the stored names stay exactly as they are.
+ *
+ * Plugins are copied, never changed: a plugin object a project passes may also serve an instance on MongoDB in the same
+ * process, which must keep its names.
+ */
+export function withSqlStorage(options: Options, pool: unknown): Options {
+  const sqlOptions: Options = {
+    ...options,
+    advanced: {
+      ...options.advanced,
+      // ObjectId-hex, generated in the application: the id the framework gives every other row, so a user created by
+      // Better-Auth and one created through the user service are indistinguishable (plan §3.5)
+      database: { ...options.advanced?.database, generateId: () => generateId() },
+    },
+    database: pool,
+    plugins: (options.plugins ?? []).map((plugin: Options) =>
+      plugin?.schema ? { ...plugin, schema: snakeCaseSchema(plugin.schema) } : plugin,
+    ),
+  };
+  const tables = getAuthTables(sqlOptions as any) as Record<
+    string,
+    { fields: Record<string, Options>; modelName: string }
+  >;
+  for (const model of CORE_MODELS) {
+    const own = (sqlOptions[model] ?? {}) as Options;
+    const fields: Record<string, string> = {};
+    for (const [key, field] of Object.entries(tables[model]?.fields ?? {})) {
+      fields[key] = columnName(field.fieldName ?? key);
+    }
+    sqlOptions[model] = {
+      ...own,
+      additionalFields: own.additionalFields ? snakeCaseFields(own.additionalFields) : undefined,
+      fields,
+      modelName: columnName(own.modelName ?? tables[model]?.modelName ?? model),
+    };
+  }
+  return sqlOptions;
+}
+
+/** A plugin's schema with its tables and columns named like the framework's */
+function snakeCaseSchema(schema: Record<string, Options>): Record<string, Options> {
+  return Object.fromEntries(
+    Object.entries(schema).map(([key, table]) => [
+      key,
+      {
+        ...table,
+        fields: snakeCaseFields(table.fields ?? {}),
+        // A plugin's entry for a core table only adds fields; the table's name is Better-Auth's own option
+        ...((CORE_MODELS as readonly string[]).includes(key) ? {} : { modelName: columnName(table.modelName ?? key) }),
+      },
+    ]),
+  );
+}
+
+function snakeCaseFields(fields: Record<string, Options>): Record<string, Options> {
+  return Object.fromEntries(
+    Object.entries(fields).map(([key, field]) => [key, { ...field, fieldName: columnName(field.fieldName ?? key) }]),
+  );
+}
+
+/** The tables Better-Auth's options declare that Better-Auth owns: all of them but the shared `users` table */
+export function betterAuthOwnedTables(options: Options): string[] {
+  const tables = getAuthTables(options as any) as Record<string, { modelName: string }>;
+  return [...new Set(Object.values(tables).map((table) => table.modelName))].filter((name) => name !== USERS_TABLE);
+}
+
+/**
+ * Bring Better-Auth's tables up to date before the instance exists (it validates its schema as it starts): Better-Auth's
+ * own migrator, run as the owner under the framework's schema lock. It only creates tables and adds columns — on `users`
+ * the ones the user model does not declare (`name`, `email_verified`, `image`); it never drops or alters a column.
+ * Without an owner connection it only checks, and a pending change stops the boot like a framework table would.
+ */
+export async function applyBetterAuthSchema(options: Options, storage: IamSqlStorage): Promise<void> {
+  await storage.applySchema(async (pool, asOwner) => {
+    const nullable = asOwner ? await addRequiredUserColumnsAsNullable(options, pool as PgPool) : new Set<string>();
+    const { runMigrations, toBeAdded, toBeCreated } = await getMigrations({
+      ...options,
+      database: pool,
+      logger: withoutNullabilityWarnings(options.logger, nullable),
+    } as any);
+    if (asOwner) {
+      await runMigrations();
+      return;
+    }
+    const pending = [...toBeCreated, ...toBeAdded].map((change: { table: string }) => change.table);
+    if (pending.length) {
+      throw new DataSourceConfigError(
+        `Better-Auth's tables in "${storage.source}" are not up to date (${[...new Set(pending)].join(', ')}), and ` +
+          'without database.ownerUrl the application role may only verify them — configure the owner, or migrate them',
+      );
+    }
+  }, betterAuthOwnedTables(options));
+}
+
+interface PgPool {
+  query(text: string, params?: unknown[]): Promise<{ rows: any[] }>;
+}
+
+/**
+ * A field Better-Auth declares required without a default (`name`) becomes a NOT NULL column when Better-Auth adds it —
+ * and every user the FRAMEWORK creates (legacy sign-up, user service, system setup) would then fail to insert, because the
+ * user model knows nothing of it. On MongoDB such a user simply has no `name`. So the framework adds these columns
+ * first, nullable like every column it creates (the database does not enforce `required`, as on MongoDB); Better-Auth
+ * then finds them and adds nothing. Returns every required user column that is nullable by the framework's design.
+ */
+async function addRequiredUserColumnsAsNullable(options: Options, pool: PgPool): Promise<Set<string>> {
+  const users = (getAuthTables(options as any) as Record<string, any>).user;
+  const { rows } = await pool.query(
+    'SELECT column_name FROM information_schema.columns WHERE table_schema = current_schema() AND table_name = $1',
+    [users.modelName],
+  );
+  const existing = new Set(rows.map((row) => row.column_name as string));
+  const nullable = new Set<string>();
+  for (const [key, field] of Object.entries(users.fields as Record<string, any>)) {
+    const column = field.fieldName ?? key;
+    if (field.required === false) {
+      continue;
+    }
+    // Every column the framework created for a field is nullable — the user model's `email` and timestamps included
+    nullable.add(column);
+    if (field.defaultValue === undefined && !existing.has(column) && SQL_TYPES[field.type]) {
+      await pool.query(
+        `ALTER TABLE ${quoteIdentifier(users.modelName)} ADD COLUMN IF NOT EXISTS ${quoteIdentifier(column)} ${SQL_TYPES[field.type]}`,
+      );
+    }
+  }
+  return nullable;
+}
+
+/**
+ * Better-Auth's logger, minus the warning that a required user column is nullable — for the columns the framework made
+ * nullable on purpose; every other message (a type mismatch, an unsafe change) is still reported
+ */
+function withoutNullabilityWarnings(logger: Options | undefined, columns: Set<string>): Options | undefined {
+  if (!columns.size || typeof logger?.log !== 'function') {
+    return logger;
+  }
+  return {
+    ...logger,
+    log: (level: string, message: string, ...args: unknown[]) => {
+      const column = /^Column "([^"]+)" on table "users" stays nullable/.exec(String(message))?.[1];
+      if (level === 'warn' && column && columns.has(column)) {
+        return;
+      }
+      logger.log(level, message, ...args);
+    },
+  };
+}

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

@@ -1,8 +1,10 @@
 import { Injectable, Logger, Optional } from '@nestjs/common';
-import { InjectConnection } from '@nestjs/mongoose';
-import { type Connection, Types } from 'mongoose';
+import { InjectConnection } from '../../common/persistence/mongo/mongoose-compat.js';
+import type { Connection } from 'mongoose';
 
 import { BetterAuthenticatedUser } from './better-auth.types.js';
+import { BetterAuthMongoUsers, type IamUserLookup } from './core-better-auth-mongo.users.js';
+import { getBetterAuthSqlStore } from './core-better-auth-sql.registry.js';
 import { CoreBetterAuthService } from './core-better-auth.service.js';
 
 /**
@@ -95,7 +97,7 @@ export class BetterAuthTokenService {
    * @returns User object with hasRole method, or null if verification fails
    */
   async verifyAndLoadUser(token: string): Promise<BetterAuthenticatedUser | null> {
-    if (!this.betterAuthService || !this.connection) {
+    if (!this.betterAuthService || !this.users()) {
       return null;
     }
 
@@ -152,10 +154,19 @@ export class BetterAuthTokenService {
         }
         return roles.some((role) => userRoles.includes(role));
       },
-      id: (user._id as Types.ObjectId)?.toString() || (user.id as string),
+      // The row's id as a string, whatever the database: MongoDB's `_id`, the column `id` on SQL
+      id: user._id?.toString() || (user.id as string),
     } as BetterAuthenticatedUser;
   }
 
+  /**
+   * Where the app user is looked up: the SQL store when Better-Auth runs on SQL, MongoDB otherwise. Ids stay strings
+   * here — only the MongoDB lookup knows what an ObjectId is.
+   */
+  protected users(): IamUserLookup | undefined {
+    return getBetterAuthSqlStore() ?? (this.connection ? new BetterAuthMongoUsers(this.connection) : undefined);
+  }
+
   /**
    * Loads a user from JWT payload using direct MongoDB query.
    *
@@ -166,23 +177,14 @@ export class BetterAuthTokenService {
     [key: string]: unknown;
     sub: string;
   }): Promise<BetterAuthenticatedUser | null> {
-    if (!this.connection) {
+    const users = this.users();
+    if (!users) {
       return null;
     }
 
     try {
-      const usersCollection = this.connection.collection('users');
-      let user: null | Record<string, unknown> = null;
-
-      // Try to find by MongoDB _id first
-      if (Types.ObjectId.isValid(payload.sub)) {
-        user = await usersCollection.findOne({ _id: new Types.ObjectId(payload.sub) });
-      }
-
-      // If not found, try by iamId
-      if (!user) {
-        user = await usersCollection.findOne({ iamId: payload.sub });
-      }
+      // By the row's id first, then by iamId
+      const user = (await users.findUser({ id: payload.sub })) ?? (await users.findUser({ iamId: payload.sub }));
 
       if (!user) {
         return null;
@@ -207,28 +209,17 @@ export class BetterAuthTokenService {
     email?: string;
     id?: string;
   }): Promise<BetterAuthenticatedUser | null> {
-    if (!this.connection || !sessionUser) {
+    const users = this.users();
+    if (!users || !sessionUser) {
       return null;
     }
 
     try {
-      const usersCollection = this.connection.collection('users');
-      let user: null | Record<string, unknown> = null;
-
-      // Try to find by email (most reliable)
-      if (sessionUser.email) {
-        user = await usersCollection.findOne({ email: sessionUser.email });
-      }
-
-      // If not found by email, try by iamId
-      if (!user && sessionUser.id) {
-        user = await usersCollection.findOne({ iamId: sessionUser.id });
-      }
-
-      // If still not found, try by _id (if the ID looks like a MongoDB ObjectId)
-      if (!user && sessionUser.id && Types.ObjectId.isValid(sessionUser.id)) {
-        user = await usersCollection.findOne({ _id: new Types.ObjectId(sessionUser.id) });
-      }
+      // By email (most reliable), then by iamId, then by the row's id
+      const user =
+        (await users.findUser({ email: sessionUser.email })) ??
+        (await users.findUser({ iamId: sessionUser.id })) ??
+        (await users.findUser({ id: sessionUser.id }));
 
       if (!user) {
         return null;

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

@@ -1,7 +1,6 @@
 import { passkey } from '@better-auth/passkey';
 import { Logger } from '@nestjs/common';
 import { betterAuth, BetterAuthPlugin } from 'better-auth';
-import { mongodbAdapter } from 'better-auth/adapters/mongodb';
 import { jwt, openAPI, twoFactor } from 'better-auth/plugins';
 import * as crypto from 'crypto';
 import * as fs from 'fs';
@@ -13,7 +12,9 @@ import { revalidateWsConnectionsOf } from '../../common/helpers/graphql-ws-conne
 import { IBetterAuth, ICorsConfig } from '../../common/interfaces/server-options.interface.js';
 import { ConfigService } from '../../common/services/config.service.js';
 import { detectCookiePrefixDrift, resolveBetterAuthCookiePrefix } from './better-auth-cookie-prefix.helper.js';
+import { withSqlStorage } from './better-auth-sql.helper.js';
 import { projectProvidesOpenApiPlugin } from './core-better-auth-openapi.helper.js';
+import { requireBetterAuthMongoAdapter } from '../../common/persistence/mongo/mongo-packages.js';
 
 /**
  * Type for better-auth instance with plugins
@@ -155,7 +156,7 @@ export interface CreateBetterAuthOptions {
    * MongoDB database instance
    * Note: Uses 'any' type to handle version incompatibilities between
    * mongoose's bundled mongodb types and the project's mongodb package.
-   * At runtime, this is a mongodb.Db instance.
+   * At runtime, this is a mongodb.Db instance. Unused when `sqlPool` is set.
    */
   db: any;
 
@@ -230,6 +231,13 @@ export interface CreateBetterAuthOptions {
    * Used for local environment defaults.
    */
   serverEnv?: string;
+
+  /**
+   * The `pg` pool of the SQL data source the `users` table lives in (the application role's pool of the configured
+   * engine). Set, Better-Auth runs its built-in Kysely adapter on it instead of MongoDB, with the framework's ids and
+   * table and column names — see `withSqlStorage()`.
+   */
+  sqlPool?: unknown;
 }
 
 /**
@@ -480,7 +488,31 @@ export interface CreateBetterAuthResult {
   instance: BetterAuthInstance;
 }
 
+/** The options `createBetterAuthInstance()` builds, before Better-Auth is constructed from them */
+export interface BetterAuthOptionsResult {
+  /** Resolved cookie domain for cross-subdomain cookies, or undefined if disabled */
+  cookieDomain: string | undefined;
+  /** What `betterAuth()` receives */
+  options: Record<string, unknown>;
+}
+
 export function createBetterAuthInstance(options: CreateBetterAuthOptions): CreateBetterAuthResult | null {
+  const built = buildBetterAuthOptions(options);
+  return built ? instantiateBetterAuth(built) : null;
+}
+
+/** Construct Better-Auth from built options — a separate step so a SQL schema can be brought up to date in between */
+export function instantiateBetterAuth(built: BetterAuthOptionsResult): CreateBetterAuthResult {
+  // Type assertion needed for maximum flexibility - allows projects to use any Better-Auth option
+  return { cookieDomain: built.cookieDomain, instance: betterAuth(built.options as any) };
+}
+
+/**
+ * Better-Auth's options as `createBetterAuthInstance()` builds them, without constructing Better-Auth: on a SQL data
+ * source its tables must exist before the instance does, because Better-Auth validates its schema as it starts and
+ * reports every missing table as an error.
+ */
+export function buildBetterAuthOptions(options: CreateBetterAuthOptions): BetterAuthOptionsResult | null {
   const {
     config,
     db,
@@ -490,6 +522,7 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Crea
     sendResetPasswordEmail,
     sendVerificationEmail,
     serverEnv,
+    sqlPool,
   } = options;
 
   // Return null only if better-auth is explicitly disabled
@@ -615,7 +648,7 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Crea
     },
     basePath,
     baseURL: betterAuthBaseUrl,
-    database: mongodbAdapter(db),
+    database: sqlPool ? undefined : (requireBetterAuthMongoAdapter()(db) as any),
     // Enable email/password authentication by default (required by Better-Auth 1.x)
     // Can be disabled by setting config.emailAndPassword.enabled = false
     emailAndPassword: {
@@ -810,12 +843,14 @@ export function createBetterAuthInstance(options: CreateBetterAuthOptions): Crea
     finalConfig = betterAuthConfig;
   }
 
-  // Create and return the better-auth instance with resolved metadata
-  // Type assertion needed for maximum flexibility - allows projects to use any Better-Auth option
+  // On SQL the storage is applied last, so the naming also covers fields and plugins `config.options` added
+  if (sqlPool) {
+    finalConfig = withSqlStorage(finalConfig, sqlPool);
+  }
 
   return {
     cookieDomain: crossSubDomain.enabled ? crossSubDomain.domain : undefined,
-    instance: betterAuth(finalConfig as any),
+    options: finalConfig,
   };
 }
 
@@ -1037,7 +1072,8 @@ function buildPlugins(
       passkeyOptions.userVerification = normalizedPasskey.userVerification;
     }
     if (normalizedPasskey.webAuthnChallengeCookie) {
-      passkeyOptions.webAuthnChallengeCookie = normalizedPasskey.webAuthnChallengeCookie;
+      // The plugin reads the name from `advanced`; a top-level option is ignored
+      passkeyOptions.advanced = { webAuthnChallengeCookie: normalizedPasskey.webAuthnChallengeCookie };
     }
 
     plugins.push(passkey(passkeyOptions));

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

@@ -5,7 +5,7 @@
  * and reduce the need for `as any` casts throughout the codebase.
  */
 
-import { Types } from 'mongoose';
+import type { Types } from 'mongoose';
 
 import { BetterAuthSessionUser } from './core-better-auth-user.mapper.js';
 

package/src/core/modules/better-auth/core-better-auth-api.middleware.ts

@@ -243,6 +243,17 @@ export class CoreBetterAuthApiMiddleware implements NestMiddleware {
     return this.cookieHelper;
   }
 
+  /**
+   * The passkey challenge cookie as Better-Auth names it: the configured key under the instance's cookie prefix
+   * (`iam.better-auth-passkey` by default). Asked from Better-Auth itself, so the prefix the session cookie follows
+   * (`COOKIE_PREFIX`, the base path) applies here too.
+   */
+  protected async passkeyChallengeCookieName(authInstance: unknown): Promise<string> {
+    const key = this.challengeService?.getCookieName() || 'better-auth-passkey';
+    const context = await (authInstance as { $context?: Promise<any> }).$context;
+    return context?.createAuthCookie?.(key)?.name ?? key;
+  }
+
   /**
    * Check if database challenge storage should be used.
    * This is checked dynamically because the ChallengeService initializes in onModuleInit.
@@ -312,7 +323,8 @@ export class CoreBetterAuthApiMiddleware implements NestMiddleware {
 
       // Get config for cookie signing
       const config = this.betterAuthService.getConfig();
-      const cookieName = this.challengeService?.getCookieName() || 'better-auth.better-auth-passkey';
+      const cookieName =
+        isPasskeyGenerate || isPasskeyVerify ? await this.passkeyChallengeCookieName(authInstance) : '';
 
       // For passkey verify requests with DB storage, inject the verificationToken as a cookie
       let challengeIdToDelete: string | undefined;

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

@@ -1,11 +1,12 @@
 import { Injectable, Logger, OnModuleInit, Optional } from '@nestjs/common';
-import { InjectConnection } from '@nestjs/mongoose';
+import { InjectConnection } from '../../common/persistence/mongo/mongoose-compat.js';
 import * as crypto from 'crypto';
-import { Collection, Document } from 'mongodb';
+import type { Collection, Document } from 'mongodb';
 import type { Connection } from 'mongoose';
 
 import { IBetterAuth } from '../../common/interfaces/server-options.interface.js';
 import { ConfigService } from '../../common/services/config.service.js';
+import { getBetterAuthSqlStore } from './core-better-auth-sql.registry.js';
 
 /**
  * WebAuthn challenge mapping document structure.
@@ -104,8 +105,8 @@ export class CoreBetterAuthChallengeService implements OnModuleInit {
 
     try {
       if (!this.connection) {
-        this.logger.warn('MongoDB connection not available, challenge storage disabled');
-        this.enabled = false;
+        // No MongoDB (PostgreSQL alone): the mappings are Better-Auth verification values on the SQL source, reached per
+        // call through getBetterAuthSqlStore() — isEnabled() answers from it
         return;
       }
 
@@ -138,7 +139,7 @@ export class CoreBetterAuthChallengeService implements OnModuleInit {
    * Check if database challenge storage is enabled
    */
   isEnabled(): boolean {
-    return this.enabled && this.collection !== null;
+    return this.enabled && (this.collection !== null || !!getBetterAuthSqlStore());
   }
 
   /**
@@ -154,7 +155,8 @@ export class CoreBetterAuthChallengeService implements OnModuleInit {
     userId: string,
     type: 'authentication' | 'registration',
   ): Promise<string> {
-    if (!this.collection) {
+    const sql = getBetterAuthSqlStore();
+    if (!this.collection && !sql) {
       throw new Error('Challenge storage not initialized');
     }
 
@@ -164,6 +166,13 @@ export class CoreBetterAuthChallengeService implements OnModuleInit {
     const now = new Date();
     const expiresAt = new Date(now.getTime() + this.ttlSeconds * 1000);
 
+    if (sql) {
+      // On SQL as one of Better-Auth's verification values: short-lived, with an expiry, never sent to the client
+      await sql.storeChallenge(challengeId, { expiresAt, type, userId, verificationToken });
+      this.logger.debug(`Stored ${type} challenge mapping for user ${userId.substring(0, 8)}...`);
+      return challengeId;
+    }
+
     await this.collection.insertOne({
       challengeId,
       createdAt: now,
@@ -185,11 +194,12 @@ export class CoreBetterAuthChallengeService implements OnModuleInit {
    * @returns The verificationToken or null if not found/expired
    */
   async getVerificationToken(challengeId: string): Promise<null | string> {
-    if (!this.collection) {
+    const sql = getBetterAuthSqlStore();
+    if (!this.collection && !sql) {
       return null;
     }
 
-    const doc = await this.collection.findOne({ challengeId });
+    const doc = sql ? await sql.findChallenge(challengeId) : await this.collection.findOne({ challengeId });
 
     if (!doc) {
       this.logger.debug(`Challenge mapping not found: ${challengeId.substring(0, 8)}...`);
@@ -211,11 +221,14 @@ export class CoreBetterAuthChallengeService implements OnModuleInit {
    * @param challengeId - The challenge ID to delete
    */
   async deleteChallengeMapping(challengeId: string): Promise<void> {
-    if (!this.collection) {
+    const sql = getBetterAuthSqlStore();
+    if (sql) {
+      await sql.deleteChallenge(challengeId);
+    } else if (!this.collection) {
       return;
+    } else {
+      await this.collection.deleteOne({ challengeId });
     }
-
-    await this.collection.deleteOne({ challengeId });
     this.logger.debug(`Deleted challenge mapping: ${challengeId.substring(0, 8)}...`);
   }
 
@@ -225,13 +238,16 @@ export class CoreBetterAuthChallengeService implements OnModuleInit {
    * @param userId - User ID whose challenge mappings should be deleted
    */
   async deleteUserChallengeMappings(userId: string): Promise<void> {
-    if (!this.collection) {
+    const sql = getBetterAuthSqlStore();
+    if (!this.collection && !sql) {
       return;
     }
 
-    const result = await this.collection.deleteMany({ userId });
-    if (result.deletedCount > 0) {
-      this.logger.debug(`Deleted ${result.deletedCount} challenge mappings for user ${userId.substring(0, 8)}...`);
+    const deletedCount = sql
+      ? await sql.deleteUserChallenges(userId)
+      : (await this.collection.deleteMany({ userId })).deletedCount;
+    if (deletedCount > 0) {
+      this.logger.debug(`Deleted ${deletedCount} challenge mappings for user ${userId.substring(0, 8)}...`);
     }
   }
 
@@ -243,14 +259,16 @@ export class CoreBetterAuthChallengeService implements OnModuleInit {
   }
 
   /**
-   * Get the cookie name used by Better Auth for passkey challenges
+   * The key of Better-Auth's passkey challenge cookie (`passkey.webAuthnChallengeCookie`, default
+   * `better-auth-passkey`). Better-Auth puts its cookie prefix in front of it — the full name is
+   * `createAuthCookie(<key>).name` of the instance, as `CoreBetterAuthApiMiddleware` resolves it.
    */
   getCookieName(): string {
     if (!this.configService) {
-      return 'better-auth.better-auth-passkey';
+      return 'better-auth-passkey';
     }
     const config = this.configService.get<IBetterAuth>('betterAuth') || {};
     const passkeyConfig = typeof config.passkey === 'object' ? config.passkey : null;
-    return passkeyConfig?.webAuthnChallengeCookie || 'better-auth.better-auth-passkey';
+    return passkeyConfig?.webAuthnChallengeCookie || 'better-auth-passkey';
   }
 }

package/src/core/modules/better-auth/core-better-auth-mongo.users.ts

@@ -0,0 +1,35 @@
+import type { Connection } from 'mongoose';
+
+import type { IamUserMatch } from './core-better-auth-sql.store.js';
+import { isValidObjectId, newObjectId } from '../../common/persistence/mongo/mongoose-compat.js';
+
+/** One way to look the app user up on the per-request auth path — by one key at a time */
+export interface IamUserLookup {
+  findUser(match: IamUserMatch): Promise<null | Record<string, unknown>>;
+}
+
+/**
+ * The app user on MongoDB for the per-request auth path (token service). The one place on that path that knows a
+ * MongoDB id is an ObjectId: the services ask by string, and only this class turns an id into a `_id` filter — a
+ * string that is no ObjectId finds nobody, as before. On a SQL source `BetterAuthSqlStore` answers instead.
+ */
+export class BetterAuthMongoUsers implements IamUserLookup {
+  constructor(protected readonly connection: Connection) {}
+
+  async findUser(match: IamUserMatch): Promise<null | Record<string, unknown>> {
+    const or: Record<string, unknown>[] = [];
+    if (match.email) {
+      or.push({ email: match.email });
+    }
+    if (match.iamId) {
+      or.push({ iamId: match.iamId });
+    }
+    if (match.id && isValidObjectId(match.id)) {
+      or.push({ _id: newObjectId(match.id) });
+    }
+    if (!or.length) {
+      return null;
+    }
+    return this.connection.collection('users').findOne(or.length === 1 ? or[0] : { $or: or });
+  }
+}

package/src/core/modules/better-auth/core-better-auth-sql.registry.ts

@@ -0,0 +1,20 @@
+/**
+ * The SQL store of Better-Auth's data while Better-Auth runs on a SQL source — `undefined` on MongoDB. Set by
+ * `CoreBetterAuthModule` when it creates the instance (every creation sets it, so an application on MongoDB booted
+ * after one on SQL in the same process reads `undefined`), read by the user mapper, the token and challenge services,
+ * the system setup and the API token service at call time.
+ *
+ * `import type` only — an import-free leaf, so none of those files imports the module (see
+ * `.claude/rules/better-auth.md` §6).
+ */
+import type { BetterAuthSqlStore } from './core-better-auth-sql.store.js';
+
+let store: BetterAuthSqlStore | undefined;
+
+export function setBetterAuthSqlStore(value: BetterAuthSqlStore | undefined): void {
+  store = value;
+}
+
+export function getBetterAuthSqlStore(): BetterAuthSqlStore | undefined {
+  return store;
+}