@lenne.tech/nest-server 11.43.3 → 12.1.0

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 { Connection } from 'mongoose';
+import type { Collection, Document } from 'mongodb';
+import type { Connection } from 'mongoose';
 
-import { IBetterAuth } from '../../common/interfaces/server-options.interface';
-import { ConfigService } from '../../common/services/config.service';
+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-cookie.helper.ts

@@ -1,10 +1,10 @@
 import { Logger } from '@nestjs/common';
 import { Response } from 'express';
 
-import { isProductionLikeEnv } from '../../common/helpers/cookies.helper';
-import { resolveBetterAuthSessionCookieName } from './better-auth-cookie-prefix.helper';
-import { isJwtShaped } from './core-better-auth-token.helper';
-import { signCookieValue } from './core-better-auth-web.helper';
+import { isProductionLikeEnv } from '../../common/helpers/cookies.helper.js';
+import { resolveBetterAuthSessionCookieName } from './better-auth-cookie-prefix.helper.js';
+import { isJwtShaped } from './core-better-auth-token.helper.js';
+import { signCookieValue } from './core-better-auth-web.helper.js';
 
 /**
  * Last-resort logger for the JWT refusal below.

package/src/core/modules/better-auth/core-better-auth-email-verification.service.ts

@@ -1,18 +1,19 @@
 import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
 import { randomUUID } from 'node:crypto';
-import ejs = require('ejs');
+import ejs from 'ejs';
 import * as fs from 'fs';
 import * as path from 'path';
 
-import { isLocalEnv, isProductionLikeEnv, resolveAppUrlFromConfig } from '../../common/helpers/cookies.helper';
-import { maskEmail } from '../../common/helpers/logging.helper';
-import { IBetterAuthEmailVerificationConfig } from '../../common/interfaces/server-options.interface';
-import { BrevoService } from '../../common/services/brevo.service';
-import { ConfigService } from '../../common/services/config.service';
-import { CoreRedisService } from '../../common/services/core-redis.service';
-import { EmailService } from '../../common/services/email.service';
-import { TemplateService } from '../../common/services/template.service';
-import { AuthEmailCallbackOptions, formatProjectName } from './better-auth.config';
+import { isLocalEnv, isProductionLikeEnv, resolveAppUrlFromConfig } from '../../common/helpers/cookies.helper.js';
+import { maskEmail } from '../../common/helpers/logging.helper.js';
+import { IBetterAuthEmailVerificationConfig } from '../../common/interfaces/server-options.interface.js';
+import { BrevoService } from '../../common/services/brevo.service.js';
+import { ConfigService } from '../../common/services/config.service.js';
+import { CoreRedisService } from '../../common/services/core-redis.service.js';
+import { EmailService } from '../../common/services/email.service.js';
+import { TemplateService } from '../../common/services/template.service.js';
+import { AuthEmailCallbackOptions, formatProjectName } from './better-auth.config.js';
+import { callerDirectory } from '../../common/helpers/module-location.helper.js';
 
 /**
  * Resolved configuration type for email verification
@@ -637,6 +638,15 @@ export class CoreBetterAuthEmailVerificationService {
     // a client that names its page is a better authority on that page than a framework default.
     if (!target) {
       target = this.readCallbackUrlFromBetterAuthLink(options.url);
+      // Only an absolute http(s) URL or a root-relative path names a page. Anything else — a path without
+      // its leading slash (`redirectTo: 'reset'`), or a template literal over an unset variable
+      // (`${baseUrl}/reset` → 'undefined/reset') — would reach the mail as a relative link that resolves
+      // nowhere, and a mail is the one place nobody can fix it afterwards. Use the default page instead.
+      // Debug, not warn: the route is unauthenticated, and a log line per request is a log-flooding lever.
+      if (target && !target.startsWith('/') && !/^https?:\/\//i.test(target)) {
+        this.logger.debug(`Ignoring redirectTo "${target}" for the reset link: not an absolute URL or a path`);
+        target = undefined;
+      }
     }
 
     // The SAME resolver the legacy twin uses. Until 11.39.0 this read `appUrl` straight off the
@@ -777,7 +787,7 @@ export class CoreBetterAuthEmailVerificationService {
     }
 
     const projectTemplatesPath = this.configService.getFastButReadOnly<string>('templates.path');
-    const nestServerTemplatesPath = path.join(__dirname, '..', '..', '..', 'templates');
+    const nestServerTemplatesPath = path.join(callerDirectory(), '..', '..', '..', 'templates');
 
     const candidates = [
       // Project templates (with locale)

package/src/core/modules/better-auth/core-better-auth-error-codes.helper.ts

@@ -1,4 +1,4 @@
-import { ErrorCode } from '../error-code/error-codes';
+import { ErrorCode } from '../error-code/error-codes.js';
 
 /**
  * Translate Better-Auth's own error codes into nest-server's `#LTNS_XXXX:` message format.

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

@@ -1,7 +1,7 @@
 import { Field, ObjectType } from '@nestjs/graphql';
 
-import { Restricted } from '../../common/decorators/restricted.decorator';
-import { RoleEnum } from '../../common/enums/role.enum';
+import { Restricted } from '../../common/decorators/restricted.decorator.js';
+import { RoleEnum } from '../../common/enums/role.enum.js';
 
 /**
  * Better-Auth User Model for GraphQL

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-openapi.helper.ts

@@ -1,4 +1,4 @@
-import type { IBetterAuth } from '../../common/interfaces/server-options.interface';
+import type { IBetterAuth } from '../../common/interfaces/server-options.interface.js';
 
 /**
  * What the Swagger document needs to know about the routes under the Better-Auth base path.

package/src/core/modules/better-auth/core-better-auth-rate-limit.middleware.ts

@@ -1,8 +1,8 @@
 import { HttpException, HttpStatus, Injectable, NestMiddleware } from '@nestjs/common';
 import { NextFunction, Request, Response } from 'express';
 
-import { CoreBetterAuthRateLimiter, RateLimitResult } from './core-better-auth-rate-limiter.service';
-import { CoreBetterAuthService } from './core-better-auth.service';
+import { CoreBetterAuthRateLimiter, RateLimitResult } from './core-better-auth-rate-limiter.service.js';
+import { CoreBetterAuthService } from './core-better-auth.service.js';
 
 /**
  * Middleware that applies rate limiting to Better-Auth endpoints

package/src/core/modules/better-auth/core-better-auth-rate-limiter.service.ts

@@ -1,14 +1,14 @@
 import { Injectable, Logger, Optional } from '@nestjs/common';
 
-import { IBetterAuthRateLimit } from '../../common/interfaces/server-options.interface';
-import { CoreRedisService } from '../../common/services/core-redis.service';
+import { IBetterAuthRateLimit } from '../../common/interfaces/server-options.interface.js';
+import { CoreRedisService } from '../../common/services/core-redis.service.js';
 import {
   InMemoryRateLimitStore,
   rateLimitKey,
   rateLimitKeyPrefix,
   RateLimitStore,
   RedisRateLimitStore,
-} from '../../common/services/rate-limit-store';
+} from '../../common/services/rate-limit-store.js';
 
 /**
  * Result of a rate limit check

package/src/core/modules/better-auth/core-better-auth-signup-validator.service.ts

@@ -1,8 +1,8 @@
 import { BadRequestException, Injectable, Logger } from '@nestjs/common';
 
-import { IBetterAuthSignUpChecksConfig } from '../../common/interfaces/server-options.interface';
-import { ConfigService } from '../../common/services/config.service';
-import { ErrorCode } from '../error-code/error-codes';
+import { IBetterAuthSignUpChecksConfig } from '../../common/interfaces/server-options.interface.js';
+import { ConfigService } from '../../common/services/config.service.js';
+import { ErrorCode } from '../error-code/error-codes.js';
 
 /**
  * Default configuration for sign-up checks

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;
+}

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

@@ -0,0 +1,309 @@
+import type { DataStore } from '../../common/persistence/data-store.interface.js';
+import { quoteIdentifier } from '../../common/persistence/sql/sql-naming.js';
+import { RequestContext } from '../../common/services/request-context.service.js';
+import type { BetterAuthInstance } from './better-auth.config.js';
+
+/** A user row identified by any of its keys — the lookups the framework did with `$or` on MongoDB */
+export interface IamUserMatch {
+  email?: string;
+  iamId?: string;
+  id?: string;
+}
+
+/** What `findSession()` and `findActiveSession()` answer: Better-Auth's session and its user, with logical names */
+export interface IamSessionRecord {
+  session: { expiresAt: Date; id: string; token: string; userId: string };
+  user: { email: string; emailVerified?: boolean; id: string; name?: string };
+}
+
+/** The counts behind the IAM migration status, over every user and account */
+export interface IamMigrationCounts {
+  /** Users with an `iamId` AND a credential account */
+  fullyMigrated: number;
+  /** Addresses of users without one of the two, at most the requested number */
+  pendingEmails: string[];
+  total: number;
+  /** Distinct users holding a credential account */
+  withIamAccount: number;
+  withIamId: number;
+}
+
+/** What the store needs of the `pg` pool Better-Auth runs on */
+export interface IamSqlQueryable {
+  query(text: string, values?: unknown[]): Promise<{ rows: any[] }>;
+}
+
+/** A passkey challenge mapping as `CoreBetterAuthChallengeService` keeps it */
+export interface IamChallengeMapping {
+  expiresAt: Date;
+  type: 'authentication' | 'registration';
+  userId?: string;
+  verificationToken: string;
+}
+
+/** Identifier prefix of passkey challenge mappings in Better-Auth's `verification` table */
+const CHALLENGE_PREFIX = 'lt-passkey-challenge:';
+
+/**
+ * Better-Auth's data on a SQL source, for the framework code that reached it natively on MongoDB (user mapper, token
+ * service, session and JWKS lookups, passkey challenges, system setup). Two ways in, by who owns the data:
+ *
+ * - the user row's FRAMEWORK fields (roles, verified, the legacy password, iamId …) through the user model's store, so
+ *   the framework's policies apply to them as everywhere else — `users` is one table shared with Better-Auth;
+ * - Better-Auth's OWN fields and tables (name, emailVerified, sessions, accounts, JWKS, verification values) through
+ *   Better-Auth's own adapter, which knows their names and runs Better-Auth's database hooks (a deleted session reaches
+ *   the WebSocket revocation plugin).
+ *
+ * Ids are strings: on SQL Better-Auth's user id IS the framework's id (one row), and `iamId` equals it.
+ */
+export class BetterAuthSqlStore {
+  constructor(
+    readonly users: DataStore<any>,
+    protected readonly auth: BetterAuthInstance,
+    protected readonly pool?: IamSqlQueryable,
+  ) {}
+
+  // ---------------------------------------------------------------------------------------------
+  // The user row: framework fields
+  // ---------------------------------------------------------------------------------------------
+
+  async findUser(match: IamUserMatch, select?: readonly string[]): Promise<any | null> {
+    const where = whereOf(match);
+    return where ? this.users.findOne(where, select ? { select } : undefined) : null;
+  }
+
+  /** Set framework fields on the first matching user; `null` when none matches */
+  async updateUser(match: IamUserMatch, set: Record<string, unknown>): Promise<any | null> {
+    const where = whereOf(match);
+    return where ? this.users.updateOne(where, { $set: set } as any) : null;
+  }
+
+  /**
+   * Set fields the role guard protects (`roles`) as system work — what the native write on MongoDB did, which no plugin
+   * saw. Only for the framework's own decisions (the initial administrator), never for request input.
+   */
+  async updateUserAsSystem(id: string, set: Record<string, unknown>): Promise<any | null> {
+    return RequestContext.runWithBypassRoleGuard(() => this.users.updateById(id, { $set: set } as any));
+  }
+
+  async countUsers(where: Record<string, unknown> = {}): Promise<number> {
+    return this.users.count(where as any);
+  }
+
+  async findUsers(where: Record<string, unknown>, limit: number, select?: readonly string[]): Promise<any[]> {
+    return this.users.find(where as any, { limit, select });
+  }
+
+  async deleteUser(id: string): Promise<void> {
+    await this.users.deleteById(id);
+  }
+
+  // ---------------------------------------------------------------------------------------------
+  // Better-Auth's fields and tables
+  // ---------------------------------------------------------------------------------------------
+
+  /** Better-Auth's own fields of the user row (`name`, `emailVerified`, `image`) — the user model does not declare them */
+  async updateIamUser(userId: string, data: Record<string, unknown>): Promise<void> {
+    await (await this.context()).internalAdapter.updateUser(userId, data);
+  }
+
+  async findCredentialAccount(userId: string): Promise<any | null> {
+    return (await this.context()).internalAdapter.findCredentialAccount(userId);
+  }
+
+  async createAccount(account: Record<string, unknown>): Promise<any> {
+    return (await this.context()).internalAdapter.createAccount(account);
+  }
+
+  async updateCredentialPassword(userId: string, hash: string): Promise<void> {
+    await (await this.context()).internalAdapter.updatePassword(userId, hash);
+  }
+
+  /** End every session of a user; answers how many there were */
+  async deleteSessions(userId: string): Promise<number> {
+    const { adapter, internalAdapter } = await this.context();
+    const count = Number(await adapter.count({ model: 'session', where: [{ field: 'userId', value: userId }] }));
+    await internalAdapter.deleteUserSessions(userId);
+    return count;
+  }
+
+  /** Remove every account of a user; answers how many there were */
+  async deleteAccounts(userId: string): Promise<number> {
+    const { adapter, internalAdapter } = await this.context();
+    const count = Number(await adapter.count({ model: 'account', where: [{ field: 'userId', value: userId }] }));
+    await internalAdapter.deleteAccounts(userId);
+    return count;
+  }
+
+  async countCredentialAccounts(): Promise<number> {
+    const adapter = (await this.context()).adapter;
+    return Number(await adapter.count({ model: 'account', where: [{ field: 'providerId', value: 'credential' }] }));
+  }
+
+  /**
+   * The IAM migration counts, computed in the database over every user and account — the definitions of the MongoDB
+   * aggregation (`CoreBetterAuthUserMapper.getMigrationStatus()`). Never a page of rows: Better-Auth's `findMany()`
+   * stops at 100 without a limit, which capped the status at 100 migrated users. Table and column names come from
+   * Better-Auth's own schema, so they follow what `withSqlStorage()` mapped.
+   */
+  async migrationCounts(pendingEmailLimit: number): Promise<IamMigrationCounts> {
+    if (!this.pool) {
+      throw new Error('BetterAuthSqlStore: migration counts need the pool Better-Auth runs on');
+    }
+    const { tables } = await this.context();
+    const table = (model: string) => quoteIdentifier(tables[model].modelName);
+    const column = (model: string, field: string) => quoteIdentifier(tables[model].fields[field]?.fieldName ?? field);
+    const users = table('user');
+    const accounts = table('account');
+    const iamId = column('user', 'iamId');
+    const userId = column('account', 'userId');
+    const providerId = column('account', 'providerId');
+    const migrated = `EXISTS (SELECT 1 FROM ${accounts} a WHERE a.${userId} = u."id" AND a.${providerId} = $1)`;
+    const {
+      rows: [counts],
+    } = await this.pool.query(
+      `SELECT (SELECT count(*) FROM ${users})::int AS "total",
+              (SELECT count(*) FROM ${users} WHERE ${iamId} IS NOT NULL)::int AS "withIamId",
+              (SELECT count(DISTINCT ${userId}) FROM ${accounts} WHERE ${providerId} = $1)::int AS "withIamAccount",
+              (SELECT count(*) FROM ${users} u WHERE u.${iamId} IS NOT NULL AND ${migrated})::int AS "fullyMigrated"`,
+      ['credential'],
+    );
+    const pending =
+      pendingEmailLimit > 0
+        ? await this.pool.query(
+            `SELECT u.${column('user', 'email')} AS "email" FROM ${users} u
+              WHERE u.${iamId} IS NULL OR NOT ${migrated} ORDER BY u."id" LIMIT $2`,
+            ['credential', pendingEmailLimit],
+          )
+        : { rows: [] };
+    return { ...counts, pendingEmails: pending.rows.map((row) => row.email).filter(Boolean) };
+  }
+
+  /** A session by its token with its user; `null` when unknown — expiry is the caller's check, as on MongoDB */
+  async findSession(token: string): Promise<IamSessionRecord | null> {
+    const found = await (await this.context()).internalAdapter.findSession(token);
+    return found?.session && found.user ? toSessionRecord(found.session, found.user) : null;
+  }
+
+  /** The newest session of a user that has not expired yet */
+  async findActiveSession(userId: string): Promise<IamSessionRecord | null> {
+    const context = await this.context();
+    const [session] = await context.adapter.findMany({
+      limit: 1,
+      model: 'session',
+      sortBy: { direction: 'desc', field: 'createdAt' },
+      where: [
+        { field: 'userId', value: userId },
+        { field: 'expiresAt', operator: 'gt', value: new Date() },
+      ],
+    });
+    const user = session ? await context.internalAdapter.findUserById(userId) : null;
+    return session && user ? toSessionRecord(session, user) : null;
+  }
+
+  async findJwk(kid: string): Promise<any | null> {
+    return (await this.context()).adapter.findOne({ model: 'jwks', where: [{ field: 'id', value: kid }] });
+  }
+
+  // ---------------------------------------------------------------------------------------------
+  // Passkey challenge mappings — Better-Auth's verification values: short-lived, with an expiry, one row each
+  // ---------------------------------------------------------------------------------------------
+
+  async storeChallenge(challengeId: string, mapping: IamChallengeMapping): Promise<void> {
+    const { internalAdapter, adapter } = await this.context();
+    // Expired mappings are removed as new ones arrive: there is no TTL index on SQL, and expiry is checked on read anyway
+    await adapter.deleteMany({
+      model: 'verification',
+      where: [
+        { field: 'identifier', operator: 'starts_with', value: CHALLENGE_PREFIX },
+        { field: 'expiresAt', operator: 'lt', value: new Date() },
+      ],
+    });
+    await internalAdapter.createVerificationValue({
+      expiresAt: mapping.expiresAt,
+      identifier: CHALLENGE_PREFIX + challengeId,
+      value: JSON.stringify({
+        type: mapping.type,
+        userId: mapping.userId,
+        verificationToken: mapping.verificationToken,
+      }),
+    });
+  }
+
+  async findChallenge(challengeId: string): Promise<IamChallengeMapping | null> {
+    const stored = await (await this.context()).internalAdapter.findVerificationValue(CHALLENGE_PREFIX + challengeId);
+    if (!stored) {
+      return null;
+    }
+    try {
+      return { ...JSON.parse(stored.value), expiresAt: new Date(stored.expiresAt) };
+    } catch {
+      return null;
+    }
+  }
+
+  async deleteChallenge(challengeId: string): Promise<void> {
+    await (await this.context()).internalAdapter.deleteVerificationByIdentifier(CHALLENGE_PREFIX + challengeId);
+  }
+
+  async deleteUserChallenges(userId: string): Promise<number> {
+    const { adapter } = await this.context();
+    const stored = await adapter.findMany({
+      model: 'verification',
+      where: [{ field: 'identifier', operator: 'starts_with', value: CHALLENGE_PREFIX }],
+    });
+    const owned = stored.filter((row: { value: string }) => {
+      try {
+        return JSON.parse(row.value).userId === userId;
+      } catch {
+        return false;
+      }
+    });
+    for (const row of owned) {
+      await adapter.delete({ model: 'verification', where: [{ field: 'id', value: row.id }] });
+    }
+    return owned.length;
+  }
+
+  /**
+   * Remove the sessions and verification values whose expiry has passed. Better-Auth never deletes an expired session
+   * itself, and it clears expired verification values only when somebody looks one up; on MongoDB a TTL index removes
+   * the verification documents. Readers check the expiry either way, so this only keeps the tables from growing
+   */
+  async deleteExpired(now = new Date()): Promise<{ sessions: number; verificationValues: number }> {
+    const { adapter } = await this.context();
+    const expired = [{ field: 'expiresAt', operator: 'lt', value: now }];
+    return {
+      sessions: Number(await adapter.deleteMany({ model: 'session', where: expired })),
+      verificationValues: Number(await adapter.deleteMany({ model: 'verification', where: expired })),
+    };
+  }
+
+  /** Better-Auth's context: its adapter maps every model and field to the tables `withSqlStorage()` named */
+  protected context(): Promise<any> {
+    return (this.auth as any).$context;
+  }
+}
+
+/** The `$or` the framework queried on MongoDB, over the keys given; `undefined` when none is */
+function whereOf(match: IamUserMatch): Record<string, unknown> | undefined {
+  const or = Object.entries(match)
+    .filter(([, value]) => typeof value === 'string' && value.length > 0)
+    .map(([key, value]) => ({ [key]: value }));
+  if (!or.length) {
+    return undefined;
+  }
+  return or.length === 1 ? or[0] : { $or: or };
+}
+
+function toSessionRecord(session: any, user: any): IamSessionRecord {
+  return {
+    session: {
+      expiresAt: new Date(session.expiresAt),
+      id: String(session.id),
+      token: session.token,
+      userId: String(session.userId),
+    },
+    user: { email: user.email, emailVerified: user.emailVerified, id: String(user.id), name: user.name },
+  };
+}