feat(plugin-auth): use better-auth modelName/fields mapping for snake_case compatibility

- Add auth-schema-config.ts with model/field mapping constants for all 4 core auth models
- Refactor objectql-adapter.ts to use createAdapterFactory from better-auth/adapters
- Update auth-manager.ts to pass user/session/account/verification config with modelName and fields
- Add tests for schema config, factory adapter, and config verification
- Update README and authentication guide documentation
- Keep legacy createObjectQLAdapter for backward compatibility

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

content/docs/guides/authentication.mdx

@@ -583,7 +583,20 @@ The plugin uses ObjectStack's `sys_` prefix convention for protocol object names
 - Object names: `sys_user`, `sys_session`, `sys_account`, `sys_verification` (protocol names)
 - Field names: `email_verified`, `created_at`, `user_id` (snake_case)
 
-better-auth internally uses model names like `user` and `session`. The ObjectQL adapter (`AUTH_MODEL_TO_PROTOCOL` mapping) automatically translates these to `sys_`-prefixed protocol names, providing seamless integration.
+better-auth internally uses camelCase model and field names (`user`, `emailVerified`, `userId`).
+The plugin bridges this gap using better-auth's official **`modelName` / `fields` schema customisation API**:
+
+```typescript
+// Declared in the betterAuth() config via AUTH_*_CONFIG constants:
+user:         { modelName: 'sys_user',         fields: { emailVerified: 'email_verified', … } },
+session:      { modelName: 'sys_session',      fields: { userId: 'user_id', expiresAt: 'expires_at', … } },
+account:      { modelName: 'sys_account',      fields: { providerId: 'provider_id', accountId: 'account_id', … } },
+verification: { modelName: 'sys_verification', fields: { expiresAt: 'expires_at', … } },
+```
+
+The ObjectQL adapter factory (`createObjectQLAdapterFactory`) then uses better-auth's `createAdapterFactory`
+which automatically transforms all data and where-clauses using these mappings — no manual
+camelCase ↔ snake_case conversion is needed in the adapter.
 
 > **Upgrade note:** If you have custom adapters or plugins that reference auth objects by name,
 > update them to use `sys_user`, `sys_session`, `sys_account`, `sys_verification`

packages/plugins/plugin-auth/README.md

@@ -220,33 +220,53 @@ The adapter automatically maps better-auth model names to protocol names:
 - `sys_account` (← better-auth `account`) - OAuth provider accounts (id, provider_id, account_id, user_id, tokens, etc.)
 - `sys_verification` (← better-auth `verification`) - Verification tokens (id, value, identifier, expires_at, etc.)
 
-**Adapter:**
-The `createObjectQLAdapter()` function bridges better-auth's database interface to ObjectQL's IDataEngine. It includes a model→protocol name mapping (`AUTH_MODEL_TO_PROTOCOL`) that translates better-auth's hardcoded model names (e.g. `user`) to ObjectStack protocol names (e.g. `sys_user`):
+**Schema Mapping (modelName + fields):**
 
-```typescript
-// Better-auth → ObjectQL Adapter (handles model name mapping + field transformation)
-import { createObjectQLAdapter, AUTH_MODEL_TO_PROTOCOL } from '@objectstack/plugin-auth';
-
-const adapter = createObjectQLAdapter(dataEngine);
+better-auth uses camelCase field names internally (`emailVerified`, `userId`, `createdAt`, etc.)
+while ObjectStack's protocol layer uses snake_case (`email_verified`, `user_id`, `created_at`).
 
-// Mapping: { user: 'sys_user', session: 'sys_session', account: 'sys_account', verification: 'sys_verification' }
-console.log(AUTH_MODEL_TO_PROTOCOL);
+The plugin leverages better-auth's official `modelName` / `fields` schema customisation API
+to declare the mapping at configuration time. The `createAdapterFactory` wrapper then
+transforms data and where-clauses automatically — no runtime camelCase ↔ snake_case
+conversion is needed in the adapter itself.
 
-// better-auth requires a DBAdapterInstance (factory function), not a raw adapter object.
-// Passing a plain object falls through to the Kysely adapter path and fails silently.
-// Wrap the adapter in a factory function:
+```typescript
+// Schema mapping constants (auth-schema-config.ts)
+import {
+  AUTH_USER_CONFIG,
+  AUTH_SESSION_CONFIG,
+  AUTH_ACCOUNT_CONFIG,
+  AUTH_VERIFICATION_CONFIG,
+} from '@objectstack/plugin-auth';
+
+// Applied to the betterAuth() config:
 const auth = betterAuth({
-  database: (options) => ({
-    id: 'objectql',
-    ...adapter,
-    transaction: async (cb) => cb(adapter),
-  }),
-  // ... other config
+  database: createObjectQLAdapterFactory(dataEngine),
+  user:         { ...AUTH_USER_CONFIG },
+  session:      { ...AUTH_SESSION_CONFIG, expiresIn: 604800 },
+  account:      { ...AUTH_ACCOUNT_CONFIG },
+  verification: { ...AUTH_VERIFICATION_CONFIG },
+  // ...
 });
 ```
 
-> **Note:** `AuthManager` handles this wrapping automatically when you provide a `dataEngine`.
-> You only need the factory pattern above when using `createObjectQLAdapter()` directly.
+**Adapter Factory:**
+The `createObjectQLAdapterFactory()` function uses better-auth's `createAdapterFactory` to
+bridge ObjectQL's IDataEngine with better-auth. Model-name and field-name transformations
+are applied by the factory wrapper so the adapter code stays simple:
+
+```typescript
+import { createObjectQLAdapterFactory } from '@objectstack/plugin-auth';
+
+const adapterFactory = createObjectQLAdapterFactory(dataEngine);
+// adapterFactory is (options: BetterAuthOptions) => DBAdapter
+```
+
+> **Note:** `AuthManager` handles all of this automatically when you provide a `dataEngine`.
+> You only need the factory/config above when using the adapter directly.
+
+A legacy `createObjectQLAdapter()` function (with manual model-name mapping via
+`AUTH_MODEL_TO_PROTOCOL`) is still exported for backward compatibility.
 
 ## Development
 

packages/plugins/plugin-auth/src/auth-manager.test.ts

@@ -107,7 +107,7 @@ describe('AuthManager', () => {
   });
 
   describe('createDatabaseConfig – adapter wrapping', () => {
-    it('should pass a function (DBAdapterInstance) to betterAuth when dataEngine is provided', () => {
+    it('should pass a function (AdapterFactory) to betterAuth when dataEngine is provided', () => {
       const mockDataEngine = {
         insert: vi.fn(),
         findOne: vi.fn(),
@@ -128,7 +128,7 @@ describe('AuthManager', () => {
       // We need to trigger the lazy init first
     });
 
-    it('should provide a factory function as database config that returns adapter with id and transaction', () => {
+    it('should provide a factory function as database config', () => {
       const mockDataEngine = {
         insert: vi.fn().mockResolvedValue({ id: '1' }),
         findOne: vi.fn().mockResolvedValue({ id: '1' }),
@@ -153,21 +153,75 @@ describe('AuthManager', () => {
       // Trigger lazy initialisation
       manager.getAuthInstance();
 
-      // The database config should be a function (DBAdapterInstance)
+      // The database config should be a function (AdapterFactory)
       expect(typeof capturedConfig.database).toBe('function');
+    });
+
+    it('should include modelName and fields mapping for user, session, account, verification', () => {
+      const mockDataEngine = {
+        insert: vi.fn().mockResolvedValue({ id: '1' }),
+        findOne: vi.fn().mockResolvedValue({ id: '1' }),
+        find: vi.fn().mockResolvedValue([]),
+        count: vi.fn().mockResolvedValue(0),
+        update: vi.fn().mockResolvedValue({ id: '1' }),
+        delete: vi.fn().mockResolvedValue(undefined),
+      };
+
+      let capturedConfig: any;
+      (betterAuth as any).mockImplementation((config: any) => {
+        capturedConfig = config;
+        return { handler: vi.fn(), api: {} };
+      });
+
+      const manager = new AuthManager({
+        secret: 'test-secret-at-least-32-chars-long',
+        baseUrl: 'http://localhost:3000',
+        dataEngine: mockDataEngine as any,
+      });
+
+      manager.getAuthInstance();
 
-      // Calling the factory should return an adapter object
-      const adapterResult = capturedConfig.database({});
-      expect(adapterResult).toHaveProperty('id', 'objectql');
-      expect(typeof adapterResult.create).toBe('function');
-      expect(typeof adapterResult.findOne).toBe('function');
-      expect(typeof adapterResult.findMany).toBe('function');
-      expect(typeof adapterResult.count).toBe('function');
-      expect(typeof adapterResult.update).toBe('function');
-      expect(typeof adapterResult.delete).toBe('function');
-      expect(typeof adapterResult.deleteMany).toBe('function');
-      expect(typeof adapterResult.updateMany).toBe('function');
-      expect(typeof adapterResult.transaction).toBe('function');
+      // Verify user model config
+      expect(capturedConfig.user).toBeDefined();
+      expect(capturedConfig.user.modelName).toBe('sys_user');
+      expect(capturedConfig.user.fields).toEqual(expect.objectContaining({
+        emailVerified: 'email_verified',
+        createdAt: 'created_at',
+        updatedAt: 'updated_at',
+      }));
+
+      // Verify session model config (merged with session timing config)
+      expect(capturedConfig.session).toBeDefined();
+      expect(capturedConfig.session.modelName).toBe('sys_session');
+      expect(capturedConfig.session.fields).toEqual(expect.objectContaining({
+        userId: 'user_id',
+        expiresAt: 'expires_at',
+        ipAddress: 'ip_address',
+        userAgent: 'user_agent',
+      }));
+
+      // Verify account model config
+      expect(capturedConfig.account).toBeDefined();
+      expect(capturedConfig.account.modelName).toBe('sys_account');
+      expect(capturedConfig.account.fields).toEqual(expect.objectContaining({
+        userId: 'user_id',
+        providerId: 'provider_id',
+        accountId: 'account_id',
+        accessToken: 'access_token',
+        refreshToken: 'refresh_token',
+        idToken: 'id_token',
+        accessTokenExpiresAt: 'access_token_expires_at',
+        refreshTokenExpiresAt: 'refresh_token_expires_at',
+      }));
+
+      // Verify verification model config
+      expect(capturedConfig.verification).toBeDefined();
+      expect(capturedConfig.verification.modelName).toBe('sys_verification');
+      expect(capturedConfig.verification.fields).toEqual(expect.objectContaining({
+        expiresAt: 'expires_at',
+        createdAt: 'created_at',
+        updatedAt: 'updated_at',
+      }));
     });
 
     it('should return undefined (in-memory fallback) when no dataEngine is provided', () => {

packages/plugins/plugin-auth/src/auth-manager.ts

@@ -4,7 +4,13 @@ import { betterAuth } from 'better-auth';
 import type { Auth, BetterAuthOptions } from 'better-auth';
 import type { AuthConfig } from '@objectstack/spec/system';
 import type { IDataEngine } from '@objectstack/core';
-import { createObjectQLAdapter } from './objectql-adapter.js';
+import { createObjectQLAdapterFactory } from './objectql-adapter.js';
+import {
+  AUTH_USER_CONFIG,
+  AUTH_SESSION_CONFIG,
+  AUTH_ACCOUNT_CONFIG,
+  AUTH_VERIFICATION_CONFIG,
+} from './auth-schema-config.js';
 
 /**
  * Extended options for AuthManager
@@ -71,17 +77,30 @@ export class AuthManager {
       basePath: '/',  // ← 关键修复！告诉 better-auth 路径已被剥离
 
       // Database adapter configuration
-      // For now, we configure a basic setup that will be enhanced
-      // when database URL is provided and drizzle-orm is available
       database: this.createDatabaseConfig(),
 
+      // Model/field mapping: camelCase (better-auth) → snake_case (ObjectStack)
+      // These declarations tell better-auth the actual table/column names used
+      // by ObjectStack's protocol layer, enabling automatic transformation via
+      // createAdapterFactory.
+      user: {
+        ...AUTH_USER_CONFIG,
+      },
+      account: {
+        ...AUTH_ACCOUNT_CONFIG,
+      },
+      verification: {
+        ...AUTH_VERIFICATION_CONFIG,
+      },
+      
       // Email configuration
       emailAndPassword: {
         enabled: true,
       },
 
       // Session configuration
       session: {
+        ...AUTH_SESSION_CONFIG,
         expiresIn: this.config.session?.expiresIn || 60 * 60 * 24 * 7, // 7 days default
         updateAge: this.config.session?.updateAge || 60 * 60 * 24, // 1 day default
       },
@@ -103,19 +122,14 @@ export class AuthManager {
    * so it is correctly recognised as a `DBAdapterInstance`.
    */
   private createDatabaseConfig(): any {
-    // Use ObjectQL adapter if dataEngine is provided
+    // Use ObjectQL adapter factory if dataEngine is provided
     if (this.config.dataEngine) {
-      const adapter = createObjectQLAdapter(this.config.dataEngine);
-      // Return a DBAdapterInstance factory function
-      return (_options: any) => ({
-        id: 'objectql',
-        ...adapter,
-        // ObjectQL does not yet expose a separate transaction context,
-        // so we pass the adapter itself.  better-auth patches this
-        // automatically when missing, but providing it avoids a
-        // runtime warning from getBaseAdapter().
-        transaction: async <R>(cb: (trx: any) => Promise<R>): Promise<R> => cb(adapter),
-      });
+      // createObjectQLAdapterFactory returns an AdapterFactory
+      // (options => DBAdapter) which better-auth invokes via getBaseAdapter().
+      // The factory is created by better-auth's createAdapterFactory and
+      // automatically applies modelName/fields transformations declared in
+      // the betterAuth config above.
+      return createObjectQLAdapterFactory(this.config.dataEngine);
     }
 
     // Fallback warning if no dataEngine is provided