@lenne.tech/nest-server 11.43.3 → 12.1.0

package/src/core/modules/auth/guards/auth.guard.ts

@@ -2,18 +2,46 @@ import { CanActivate, ExecutionContext, Logger, mixin, Optional } from '@nestjs/
 import { ModuleRef } from '@nestjs/core';
 import { GqlExecutionContext } from '@nestjs/graphql';
 import { AuthModuleOptions, Type } from '@nestjs/passport';
-import { defaultOptions } from '@nestjs/passport/dist/options.js';
-import { memoize } from '@nestjs/passport/dist/utils/memoize.util.js';
-import passport = require('passport');
-
-import { enforceApiTokenRoute, getApiTokenContext } from '../../api-token/core-api-token.helpers';
-import { BetterAuthTokenService } from '../../better-auth/better-auth-token.service';
-import { BetterAuthenticatedUser } from '../../better-auth/better-auth.types';
-import { CoreBetterAuthService } from '../../better-auth/core-better-auth.service';
-import { AuthGuardStrategy } from '../auth-guard-strategy.enum';
-import { ExpiredRefreshTokenException } from '../exceptions/expired-refresh-token.exception';
-import { ExpiredTokenException } from '../exceptions/expired-token.exception';
-import { InvalidTokenException } from '../exceptions/invalid-token.exception';
+import passport from 'passport';
+
+import { enforceApiTokenRoute, getApiTokenContext } from '../../api-token/core-api-token.helpers.js';
+import { BetterAuthTokenService } from '../../better-auth/better-auth-token.service.js';
+import { BetterAuthenticatedUser } from '../../better-auth/better-auth.types.js';
+import { CoreBetterAuthService } from '../../better-auth/core-better-auth.service.js';
+import { AuthGuardStrategy } from '../auth-guard-strategy.enum.js';
+import { ExpiredRefreshTokenException } from '../exceptions/expired-refresh-token.exception.js';
+import { ExpiredTokenException } from '../exceptions/expired-token.exception.js';
+import { InvalidTokenException } from '../exceptions/invalid-token.exception.js';
+
+/**
+ * Passport defaults, as `@nestjs/passport` applies them in its own AuthGuard.
+ *
+ * Kept here rather than imported: until 11.x this file read them from `@nestjs/passport/dist/options.js`
+ * and `memoize` from `dist/utils/memoize.util.js`. `@nestjs/passport` 12 declares an `exports` map
+ * that only allows the package root, and neither helper is exported there, so the deep imports fail
+ * with ERR_PACKAGE_PATH_NOT_EXPORTED.
+ */
+const defaultOptions = {
+  property: 'user',
+  session: false,
+};
+
+/**
+ * One guard class per strategy key, so `AuthGuard('jwt')` returns the same class on every call —
+ * NestJS caches guard instances by class, and a fresh class per call would defeat that.
+ * Same behaviour as `@nestjs/passport`'s internal `memoize`.
+ */
+function memoize<T>(fn: (key?: string | string[]) => T): (key?: string | string[]) => T {
+  const defaultKey = 'default';
+  const cache: Record<string, T> = {};
+  return (...args) => {
+    const key = (args[0] as string) || defaultKey;
+    if (!(key in cache)) {
+      cache[key] = fn(key === defaultKey ? undefined : args[0]);
+    }
+    return cache[key];
+  };
+}
 
 /**
  * Missing strategy error

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

@@ -1,7 +1,7 @@
 import { CanActivate, ExecutionContext, HttpException, HttpStatus, Injectable } from '@nestjs/common';
 import { GqlExecutionContext } from '@nestjs/graphql';
 
-import { LegacyAuthRateLimiter } from '../services/legacy-auth-rate-limiter.service';
+import { LegacyAuthRateLimiter } from '../services/legacy-auth-rate-limiter.service.js';
 
 /**
  * Guard for rate limiting Legacy Auth endpoints
@@ -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/refresh-token.guard.ts

@@ -1,6 +1,6 @@
 import { Injectable } from '@nestjs/common';
 
-import { AuthGuard } from './auth.guard';
+import { AuthGuard } from './auth.guard.js';
 
 @Injectable()
 export class RefreshTokenGuard extends AuthGuard('jwt-refresh') {}

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/guards/roles.guard.ts

@@ -10,21 +10,21 @@ import {
 import { ModuleRef, Reflector } from '@nestjs/core';
 import { GqlExecutionContext } from '@nestjs/graphql';
 
-import { resolveGuardRequest } from '../../../common/helpers/execution-context-request.helper';
+import { resolveGuardRequest } from '../../../common/helpers/execution-context-request.helper.js';
 import { firstValueFrom, isObservable } from 'rxjs';
 
-import { RoleEnum } from '../../../common/enums/role.enum';
-import { ApiTokenKind } from '../../api-token/core-api-token.constants';
-import { enforceApiTokenRoute } from '../../api-token/core-api-token.helpers';
-import { BetterAuthTokenService } from '../../better-auth/better-auth-token.service';
-import { BetterAuthenticatedUser } from '../../better-auth/better-auth.types';
-import { CoreBetterAuthService } from '../../better-auth/core-better-auth.service';
-import { ErrorCode } from '../../error-code';
-import { delegatesRolesToTenantGuard, isSystemRole, mergeRolesMetadata } from '../../tenant/core-tenant.helpers';
-import { AuthGuardStrategy } from '../auth-guard-strategy.enum';
-import { ExpiredTokenException } from '../exceptions/expired-token.exception';
-import { InvalidTokenException } from '../exceptions/invalid-token.exception';
-import { AuthGuard } from './auth.guard';
+import { RoleEnum } from '../../../common/enums/role.enum.js';
+import { ApiTokenKind } from '../../api-token/core-api-token.constants.js';
+import { enforceApiTokenRoute } from '../../api-token/core-api-token.helpers.js';
+import { BetterAuthTokenService } from '../../better-auth/better-auth-token.service.js';
+import { BetterAuthenticatedUser } from '../../better-auth/better-auth.types.js';
+import { CoreBetterAuthService } from '../../better-auth/core-better-auth.service.js';
+import { ErrorCode } from '../../error-code/index.js';
+import { delegatesRolesToTenantGuard, isSystemRole, mergeRolesMetadata } from '../../tenant/core-tenant.helpers.js';
+import { AuthGuardStrategy } from '../auth-guard-strategy.enum.js';
+import { ExpiredTokenException } from '../exceptions/expired-token.exception.js';
+import { InvalidTokenException } from '../exceptions/invalid-token.exception.js';
+import { AuthGuard } from './auth.guard.js';
 
 /**
  * Role guard

package/src/core/modules/auth/helpers/legacy-endpoints.helper.ts

@@ -1,4 +1,4 @@
-import type { IAuthLegacyEndpoints } from '../../../common/interfaces/server-options.interface';
+import type { IAuthLegacyEndpoints } from '../../../common/interfaces/server-options.interface.js';
 
 /**
  * The two transports legacy auth is reachable over.

package/src/core/modules/auth/inputs/core-auth-sign-in.input.ts

@@ -1,10 +1,10 @@
 import { InputType } from '@nestjs/graphql';
 import { IsEmail, IsNotEmpty, IsString } from 'class-validator';
 
-import { Restricted } from '../../../common/decorators/restricted.decorator';
-import { UnifiedField } from '../../../common/decorators/unified-field.decorator';
-import { RoleEnum } from '../../../common/enums/role.enum';
-import { CoreInput } from '../../../common/inputs/core-input.input';
+import { Restricted } from '../../../common/decorators/restricted.decorator.js';
+import { UnifiedField } from '../../../common/decorators/unified-field.decorator.js';
+import { RoleEnum } from '../../../common/enums/role.enum.js';
+import { CoreInput } from '../../../common/inputs/core-input.input.js';
 
 /**
  * SignIn input

package/src/core/modules/auth/inputs/core-auth-sign-up.input.ts

@@ -1,8 +1,8 @@
 import { InputType } from '@nestjs/graphql';
 
-import { Restricted } from '../../../common/decorators/restricted.decorator';
-import { RoleEnum } from '../../../common/enums/role.enum';
-import { CoreAuthSignInInput } from './core-auth-sign-in.input';
+import { Restricted } from '../../../common/decorators/restricted.decorator.js';
+import { RoleEnum } from '../../../common/enums/role.enum.js';
+import { CoreAuthSignInInput } from './core-auth-sign-in.input.js';
 
 /**
  * SignUp input

package/src/core/modules/auth/interfaces/auth-provider.interface.ts

@@ -1,4 +1,4 @@
-import { JwtPayload } from './jwt-payload.interface';
+import { JwtPayload } from './jwt-payload.interface.js';
 
 /**
  * Auth Provider Interface

package/src/core/modules/auth/interfaces/core-auth-user.interface.ts

@@ -1,4 +1,4 @@
-import { CoreTokenData } from './core-token-data.interface';
+import { CoreTokenData } from './core-token-data.interface.js';
 
 /**
  * Interface for user used in authorization module

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

@@ -1,5 +1,5 @@
-import { ServiceOptions } from '../../../common/interfaces/service-options.interface';
-import { ICoreAuthUser } from '../interfaces/core-auth-user.interface';
+import { ServiceOptions } from '../../../common/interfaces/service-options.interface.js';
+import { ICoreAuthUser } from '../interfaces/core-auth-user.interface.js';
 
 /**
  * Abstract class for user service in authorization module

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

@@ -7,23 +7,23 @@ import {
   UnauthorizedException,
 } from '@nestjs/common';
 import { JwtService } from '@nestjs/jwt';
-import bcrypt = require('bcrypt');
+import bcrypt from 'bcrypt';
 import { randomUUID } from 'crypto';
 import { sha256 } from 'js-sha256';
 
-import { getStringIds } from '../../../common/helpers/db.helper';
-import { prepareServiceOptions } from '../../../common/helpers/service.helper';
-import { ServiceOptions } from '../../../common/interfaces/service-options.interface';
-import { ConfigService } from '../../../common/services/config.service';
-import { CoreBetterAuthUserMapper } from '../../better-auth/core-better-auth-user.mapper';
-import { CoreBetterAuthService } from '../../better-auth/core-better-auth.service';
-import { ErrorCode } from '../../error-code';
-import { CoreAuthModel } from '../core-auth.model';
-import { CoreAuthSignInInput } from '../inputs/core-auth-sign-in.input';
-import { CoreAuthSignUpInput } from '../inputs/core-auth-sign-up.input';
-import { ICoreAuthUser } from '../interfaces/core-auth-user.interface';
-import { JwtPayload } from '../interfaces/jwt-payload.interface';
-import { CoreAuthUserService } from './core-auth-user.service';
+import { getStringIds } from '../../../common/helpers/db.helper.js';
+import { prepareServiceOptions } from '../../../common/helpers/service.helper.js';
+import { ServiceOptions } from '../../../common/interfaces/service-options.interface.js';
+import { ConfigService } from '../../../common/services/config.service.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/index.js';
+import { CoreAuthModel } from '../core-auth.model.js';
+import { CoreAuthSignInInput } from '../inputs/core-auth-sign-in.input.js';
+import { CoreAuthSignUpInput } from '../inputs/core-auth-sign-up.input.js';
+import { ICoreAuthUser } from '../interfaces/core-auth-user.interface.js';
+import { JwtPayload } from '../interfaces/jwt-payload.interface.js';
+import { CoreAuthUserService } from './core-auth-user.service.js';
 
 /**
  * Options for getResult method
@@ -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/auth/services/legacy-auth-rate-limiter.service.ts

@@ -1,15 +1,15 @@
 import { Injectable, Logger, OnModuleInit, Optional } from '@nestjs/common';
 
-import { IAuthRateLimit } from '../../../common/interfaces/server-options.interface';
-import { ConfigService } from '../../../common/services/config.service';
-import { CoreRedisService } from '../../../common/services/core-redis.service';
+import { IAuthRateLimit } from '../../../common/interfaces/server-options.interface.js';
+import { ConfigService } from '../../../common/services/config.service.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/auth/strategies/jwt-refresh.strategy.ts

@@ -3,9 +3,9 @@ import { PassportStrategy } from '@nestjs/passport';
 import { Request, Request as RequestType } from 'express';
 import { ExtractJwt, Strategy } from 'passport-jwt';
 
-import { ConfigService } from '../../../common/services/config.service';
-import { AuthGuardStrategy } from '../auth-guard-strategy.enum';
-import { CoreAuthService } from '../services/core-auth.service';
+import { ConfigService } from '../../../common/services/config.service.js';
+import { AuthGuardStrategy } from '../auth-guard-strategy.enum.js';
+import { CoreAuthService } from '../services/core-auth.service.js';
 
 @Injectable()
 export class JwtRefreshStrategy extends PassportStrategy(Strategy, AuthGuardStrategy.JWT_REFRESH) {

package/src/core/modules/auth/strategies/jwt.strategy.ts

@@ -3,10 +3,10 @@ import { PassportStrategy } from '@nestjs/passport';
 import { Request as RequestType } from 'express';
 import { ExtractJwt, Strategy } from 'passport-jwt';
 
-import { ConfigService } from '../../../common/services/config.service';
-import { AuthGuardStrategy } from '../auth-guard-strategy.enum';
-import { JwtPayload } from '../interfaces/jwt-payload.interface';
-import { CoreAuthService } from '../services/core-auth.service';
+import { ConfigService } from '../../../common/services/config.service.js';
+import { AuthGuardStrategy } from '../auth-guard-strategy.enum.js';
+import { JwtPayload } from '../interfaces/jwt-payload.interface.js';
+import { CoreAuthService } from '../services/core-auth.service.js';
 
 /**
  * Use JWT strategy for passport

package/src/core/modules/auth/tokens.decorator.ts

@@ -1,6 +1,6 @@
 import { createParamDecorator, ExecutionContext } from '@nestjs/common';
 
-import { getContextData } from '../../common/helpers/context.helper';
+import { getContextData } from '../../common/helpers/context.helper.js';
 
 /**
  * Get current tokens

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

package/src/core/modules/better-auth/better-auth-roles.guard.ts

@@ -8,16 +8,16 @@ import {
 } from '@nestjs/common';
 import { GqlExecutionContext } from '@nestjs/graphql';
 
-import { resolveGuardRequest } from '../../common/helpers/execution-context-request.helper';
-
-import { RoleEnum } from '../../common/enums/role.enum';
-import { ApiTokenKind } from '../api-token/core-api-token.constants';
-import { enforceApiTokenRoute } from '../api-token/core-api-token.helpers';
-import { ErrorCode } from '../error-code';
-import { delegatesRolesToTenantGuard, isSystemRole, mergeRolesMetadata } from '../tenant/core-tenant.helpers';
-import { BetterAuthTokenService } from './better-auth-token.service';
-import { BetterAuthenticatedUser } from './better-auth.types';
-import { getBetterAuthTokenService } from './core-better-auth.registry';
+import { resolveGuardRequest } from '../../common/helpers/execution-context-request.helper.js';
+
+import { RoleEnum } from '../../common/enums/role.enum.js';
+import { ApiTokenKind } from '../api-token/core-api-token.constants.js';
+import { enforceApiTokenRoute } from '../api-token/core-api-token.helpers.js';
+import { ErrorCode } from '../error-code/index.js';
+import { delegatesRolesToTenantGuard, isSystemRole, mergeRolesMetadata } from '../tenant/core-tenant.helpers.js';
+import { BetterAuthTokenService } from './better-auth-token.service.js';
+import { BetterAuthenticatedUser } from './better-auth.types.js';
+import { getBetterAuthTokenService } from './core-better-auth.registry.js';
 
 /**
  * BetterAuth Roles Guard

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