Merge pull request #745 from objectstack-ai/copilot/adapt-better-auth-sys-prefix

Author: hotlong

ROADMAP.md

@@ -162,6 +162,7 @@ business/custom objects, aligning with industry best practices (e.g., ServiceNow
 
 **Migration (v3.x → v4.0):**
 - v3.x: The `SystemObjectName` constants now emit `sys_`-prefixed names. Implementations using `StorageNameMapping.resolveTableName()` can set `tableName` to preserve legacy physical table names during the transition.
+- v3.x: The `@objectstack/plugin-auth` ObjectQL adapter now includes `AUTH_MODEL_TO_PROTOCOL` mapping to translate better-auth's hardcoded model names (`user`, `session`, `account`, `verification`) to protocol names (`sys_user`, `sys_session`, `sys_account`, `sys_verification`). Custom adapters must adopt the same mapping.
 - v4.0: Legacy un-prefixed aliases will be fully removed.
 
 ---
@@ -364,7 +365,7 @@ business/custom objects, aligning with industry best practices (e.g., ServiceNow
   - [ ] **Phase A: Core Driver** (v3.1) — `IDataDriver` + `ISchemaDriver` implementation, QueryAST→SQL compiler, plugin wrapper
   - [ ] **Phase B: Edge & Sync** (v3.2) — Embedded replica sync, WASM build for Cloudflare/Deno, offline write queue
   - [ ] **Phase C: Multi-Tenancy** (v3.3) — Database-per-tenant router, Turso Platform API integration
-  - [ ] **Phase D: Advanced** (v4.0) — Vector search + `IAIService`, FTS5 + `ISearchService`, better-auth adapter
+  - [ ] **Phase D: Advanced** (v4.0) — Vector search + `IAIService`, FTS5 + `ISearchService`, ~~better-auth adapter~~ (✅ done in plugin-auth)
 - [ ] Driver benchmark suite comparing performance across all drivers
 
 ### 6.2 Multi-Tenancy

content/docs/guides/authentication.mdx

@@ -111,11 +111,15 @@ That's it! Your authentication endpoints are now available at `/api/v1/auth/*`.
 
 The plugin automatically uses ObjectQL for data persistence. No additional database configuration is required - it works with your existing ObjectQL setup.
 
-The plugin creates the following auth objects:
-- `user` - User accounts
-- `session` - Active sessions
-- `account` - OAuth provider accounts
-- `verification` - Email/phone verification tokens
+The plugin creates the following auth objects (using ObjectStack `sys_` protocol names):
+- `sys_user` - User accounts (mapped from better-auth's `user` model)
+- `sys_session` - Active sessions (mapped from better-auth's `session` model)
+- `sys_account` - OAuth provider accounts (mapped from better-auth's `account` model)
+- `sys_verification` - Email/phone verification tokens (mapped from better-auth's `verification` model)
+
+> **Note:** better-auth uses hardcoded model names (`user`, `session`, etc.). The ObjectQL adapter
+> automatically maps these to `sys_`-prefixed protocol names via `AUTH_MODEL_TO_PROTOCOL`.
+> Client-side API routes (`/api/v1/auth/*`) are **not affected** — they do not expose object names.
 
 ---
 
@@ -569,12 +573,16 @@ try {
 
 ### ObjectStack Field Naming
 
-The plugin uses ObjectStack's snake_case naming convention for field names, which is required by the ObjectStack protocol:
+The plugin uses ObjectStack's `sys_` prefix convention for protocol object names and snake_case for field names, which is required by the ObjectStack protocol:
 
-- Table names: `user`, `session`, `account`, `verification` (compatible with better-auth)
+- Object names: `sys_user`, `sys_session`, `sys_account`, `sys_verification` (protocol names)
 - Field names: `email_verified`, `created_at`, `user_id` (snake_case)
 
-The ObjectQL adapter automatically handles field name transformation between better-auth's expectations and ObjectStack's snake_case convention, providing seamless integration while maintaining protocol compliance.
+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.
+
+> **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`
+> (or import from `SystemObjectName` constants).
 
 ---
 

packages/plugins/plugin-auth/README.md

@@ -34,10 +34,10 @@ Authentication & Identity Plugin for ObjectStack.
 - ✅ **No Third-Party ORM** - No dependency on drizzle-orm or other ORMs
 - ✅ **Better-Auth Native Schema** - Uses better-auth's naming conventions for seamless migration
 - ✅ **Object Definitions** - Auth objects defined using ObjectStack's Object Protocol
-  - `user` - User accounts (better-auth native table name)
-  - `session` - Active sessions (better-auth native table name)
-  - `account` - OAuth provider accounts (better-auth native table name)
-  - `verification` - Email/phone verification tokens (better-auth native table name)
+  - `sys_user` - User accounts (protocol name, mapped from better-auth's `user`)
+  - `sys_session` - Active sessions (protocol name, mapped from better-auth's `session`)
+  - `sys_account` - OAuth provider accounts (protocol name, mapped from better-auth's `account`)
+  - `sys_verification` - Email/phone verification tokens (protocol name, mapped from better-auth's `verification`)
 - ✅ **ObjectQL Adapter** - Custom adapter bridges better-auth to ObjectQL
 
 The plugin uses [better-auth](https://www.better-auth.com/) for robust, production-ready authentication functionality. All requests are forwarded directly to better-auth's universal handler, ensuring full compatibility with all better-auth features. Data persistence is handled by ObjectQL using **ObjectStack's snake_case naming conventions** for field names to maintain consistency across the platform.
@@ -187,7 +187,7 @@ The plugin uses **ObjectQL** for data persistence instead of third-party ORMs:
 ```typescript
 // Object definitions use ObjectStack's snake_case naming conventions
 export const AuthUser = ObjectSchema.create({
-  name: 'user',  // better-auth compatible table name
+  name: 'sys_user',  // ObjectStack protocol name (better-auth model 'user' is mapped automatically)
   fields: {
     id: Field.text({ label: 'User ID', required: true }),
     email: Field.email({ label: 'Email', required: true }),
@@ -213,19 +213,25 @@ export const AuthUser = ObjectSchema.create({
 - ✅ **Compatible Schema** - Uses better-auth compatible table structure with ObjectStack's snake_case field naming
 
 **Database Objects:**
-Uses better-auth compatible table names with ObjectStack's snake_case field naming:
-- `user` - User accounts (id, email, name, email_verified, created_at, etc.)
-- `session` - Active sessions (id, token, user_id, expires_at, ip_address, etc.)
-- `account` - OAuth provider accounts (id, provider_id, account_id, user_id, tokens, etc.)
-- `verification` - Verification tokens (id, value, identifier, expires_at, etc.)
+Uses ObjectStack `sys_` prefixed protocol names with snake_case field naming.
+The adapter automatically maps better-auth model names to protocol names:
+- `sys_user` (← better-auth `user`) - User accounts (id, email, name, email_verified, created_at, etc.)
+- `sys_session` (← better-auth `session`) - Active sessions (id, token, user_id, expires_at, ip_address, etc.)
+- `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 with field name transformation:
+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`):
 
 ```typescript
-// Better-auth → ObjectQL Adapter (handles snake_case transformation)
+// Better-auth → ObjectQL Adapter (handles model name mapping + field transformation)
+import { createObjectQLAdapter, AUTH_MODEL_TO_PROTOCOL } from '@objectstack/plugin-auth';
+
 const adapter = createObjectQLAdapter(dataEngine);
 
+// Mapping: { user: 'sys_user', session: 'sys_session', account: 'sys_account', verification: 'sys_verification' }
+console.log(AUTH_MODEL_TO_PROTOCOL);
+
 // Better-auth uses this adapter for all database operations
 const auth = betterAuth({
   database: adapter,

packages/plugins/plugin-auth/src/objectql-adapter.test.ts

@@ -0,0 +1,113 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  createObjectQLAdapter,
+  AUTH_MODEL_TO_PROTOCOL,
+  resolveProtocolName,
+} from './objectql-adapter';
+import { SystemObjectName } from '@objectstack/spec/system';
+import type { IDataEngine } from '@objectstack/core';
+
+describe('AUTH_MODEL_TO_PROTOCOL mapping', () => {
+  it('should map all four core better-auth models to sys_ protocol names', () => {
+    expect(AUTH_MODEL_TO_PROTOCOL.user).toBe('sys_user');
+    expect(AUTH_MODEL_TO_PROTOCOL.session).toBe('sys_session');
+    expect(AUTH_MODEL_TO_PROTOCOL.account).toBe('sys_account');
+    expect(AUTH_MODEL_TO_PROTOCOL.verification).toBe('sys_verification');
+  });
+
+  it('should align with SystemObjectName constants', () => {
+    expect(AUTH_MODEL_TO_PROTOCOL.user).toBe(SystemObjectName.USER);
+    expect(AUTH_MODEL_TO_PROTOCOL.session).toBe(SystemObjectName.SESSION);
+    expect(AUTH_MODEL_TO_PROTOCOL.account).toBe(SystemObjectName.ACCOUNT);
+    expect(AUTH_MODEL_TO_PROTOCOL.verification).toBe(SystemObjectName.VERIFICATION);
+  });
+});
+
+describe('resolveProtocolName', () => {
+  it('should resolve core models to sys_ prefixed names', () => {
+    expect(resolveProtocolName('user')).toBe('sys_user');
+    expect(resolveProtocolName('session')).toBe('sys_session');
+    expect(resolveProtocolName('account')).toBe('sys_account');
+    expect(resolveProtocolName('verification')).toBe('sys_verification');
+  });
+
+  it('should fall back to original name for unknown models', () => {
+    expect(resolveProtocolName('organization')).toBe('organization');
+    expect(resolveProtocolName('custom_model')).toBe('custom_model');
+  });
+});
+
+describe('createObjectQLAdapter – model name mapping', () => {
+  let mockEngine: IDataEngine;
+
+  beforeEach(() => {
+    mockEngine = {
+      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),
+    } as unknown as IDataEngine;
+  });
+
+  it('create: should call dataEngine.insert with sys_ protocol name', async () => {
+    const adapter = createObjectQLAdapter(mockEngine);
+    await adapter.create({ model: 'user', data: { email: 'a@b.com' } });
+    expect(mockEngine.insert).toHaveBeenCalledWith('sys_user', { email: 'a@b.com' });
+  });
+
+  it('findOne: should call dataEngine.findOne with sys_ protocol name', async () => {
+    const adapter = createObjectQLAdapter(mockEngine);
+    await adapter.findOne({
+      model: 'session',
+      where: [{ field: 'token', value: 'abc', operator: 'eq', connector: 'AND' }],
+    });
+    expect(mockEngine.findOne).toHaveBeenCalledWith('sys_session', expect.objectContaining({
+      filter: { token: 'abc' },
+    }));
+  });
+
+  it('findMany: should call dataEngine.find with sys_ protocol name', async () => {
+    const adapter = createObjectQLAdapter(mockEngine);
+    await adapter.findMany({ model: 'account', limit: 10 });
+    expect(mockEngine.find).toHaveBeenCalledWith('sys_account', expect.objectContaining({
+      limit: 10,
+    }));
+  });
+
+  it('count: should call dataEngine.count with sys_ protocol name', async () => {
+    const adapter = createObjectQLAdapter(mockEngine);
+    await adapter.count({ model: 'verification' });
+    expect(mockEngine.count).toHaveBeenCalledWith('sys_verification', expect.anything());
+  });
+
+  it('update: should call dataEngine with sys_ protocol name', async () => {
+    const adapter = createObjectQLAdapter(mockEngine);
+    await adapter.update({
+      model: 'user',
+      where: [{ field: 'id', value: '1', operator: 'eq', connector: 'AND' }],
+      update: { name: 'New' },
+    });
+    expect(mockEngine.findOne).toHaveBeenCalledWith('sys_user', expect.anything());
+    expect(mockEngine.update).toHaveBeenCalledWith('sys_user', expect.objectContaining({ name: 'New', id: '1' }));
+  });
+
+  it('delete: should call dataEngine with sys_ protocol name', async () => {
+    const adapter = createObjectQLAdapter(mockEngine);
+    await adapter.delete({
+      model: 'session',
+      where: [{ field: 'id', value: '1', operator: 'eq', connector: 'AND' }],
+    });
+    expect(mockEngine.findOne).toHaveBeenCalledWith('sys_session', expect.anything());
+    expect(mockEngine.delete).toHaveBeenCalledWith('sys_session', expect.anything());
+  });
+
+  it('should pass through unknown model names unchanged', async () => {
+    const adapter = createObjectQLAdapter(mockEngine);
+    await adapter.create({ model: 'organization', data: { name: 'Acme' } });
+    expect(mockEngine.insert).toHaveBeenCalledWith('organization', { name: 'Acme' });
+  });
+});

packages/plugins/plugin-auth/src/objectql-adapter.ts

@@ -2,6 +2,28 @@
 
 import type { IDataEngine } from '@objectstack/core';
 import type { CleanedWhere } from 'better-auth/adapters';
+import { SystemObjectName } from '@objectstack/spec/system';
+
+/**
+ * Mapping from better-auth model names to ObjectStack protocol object names.
+ *
+ * better-auth uses hardcoded model names ('user', 'session', 'account', 'verification')
+ * while ObjectStack's protocol layer uses `sys_` prefixed names. This map bridges the two.
+ */
+export const AUTH_MODEL_TO_PROTOCOL: Record<string, string> = {
+  user: SystemObjectName.USER,
+  session: SystemObjectName.SESSION,
+  account: SystemObjectName.ACCOUNT,
+  verification: SystemObjectName.VERIFICATION,
+};
+
+/**
+ * Resolve a better-auth model name to the ObjectStack protocol object name.
+ * Falls back to the original model name for custom / non-core models.
+ */
+export function resolveProtocolName(model: string): string {
+  return AUTH_MODEL_TO_PROTOCOL[model] ?? model;
+}
 
 /**
  * ObjectQL Adapter for better-auth
@@ -10,7 +32,8 @@ import type { CleanedWhere } from 'better-auth/adapters';
  * This allows better-auth to use ObjectQL for data persistence instead of
  * third-party ORMs like drizzle-orm.
  * 
- * Uses better-auth's native naming conventions (camelCase) for seamless migration.
+ * Model names from better-auth (e.g. 'user') are automatically mapped to
+ * ObjectStack protocol names (e.g. 'sys_user') via {@link AUTH_MODEL_TO_PROTOCOL}.
  * 
  * @param dataEngine - ObjectQL data engine instance
  * @returns better-auth CustomAdapter
@@ -50,8 +73,7 @@ export function createObjectQLAdapter(dataEngine: IDataEngine) {
 
   return {
     create: async <T extends Record<string, any>>({ model, data, select: _select }: { model: string; data: T; select?: string[] }): Promise<T> => {
-      // Use model name as-is (no conversion needed)
-      const objectName = model;
+      const objectName = resolveProtocolName(model);
 
       // Note: select parameter is currently not supported by ObjectQL's insert operation
       // The full record is always returned after insertion
@@ -60,7 +82,7 @@ export function createObjectQLAdapter(dataEngine: IDataEngine) {
     },
 
     findOne: async <T>({ model, where, select, join: _join }: { model: string; where: CleanedWhere[]; select?: string[]; join?: any }): Promise<T | null> => {
-      const objectName = model;
+      const objectName = resolveProtocolName(model);
       const filter = convertWhere(where);
 
       // Note: join parameter is not currently supported by ObjectQL's findOne operation
@@ -76,7 +98,7 @@ export function createObjectQLAdapter(dataEngine: IDataEngine) {
     },
 
     findMany: async <T>({ model, where, limit, offset, sortBy, join: _join }: { model: string; where?: CleanedWhere[]; limit: number; offset?: number; sortBy?: { field: string; direction: 'asc' | 'desc' }; join?: any }): Promise<T[]> => {
-      const objectName = model;
+      const objectName = resolveProtocolName(model);
       const filter = where ? convertWhere(where) : {};
 
       // Note: join parameter is not currently supported by ObjectQL's find operation
@@ -98,14 +120,14 @@ export function createObjectQLAdapter(dataEngine: IDataEngine) {
     },
 
     count: async ({ model, where }: { model: string; where?: CleanedWhere[] }): Promise<number> => {
-      const objectName = model;
+      const objectName = resolveProtocolName(model);
       const filter = where ? convertWhere(where) : {};
 
       return await dataEngine.count(objectName, { filter });
     },
 
     update: async <T>({ model, where, update }: { model: string; where: CleanedWhere[]; update: Record<string, any> }): Promise<T | null> => {
-      const objectName = model;
+      const objectName = resolveProtocolName(model);
       const filter = convertWhere(where);
 
       // Find the record first to get its ID
@@ -123,7 +145,7 @@ export function createObjectQLAdapter(dataEngine: IDataEngine) {
     },
 
     updateMany: async ({ model, where, update }: { model: string; where: CleanedWhere[]; update: Record<string, any> }): Promise<number> => {
-      const objectName = model;
+      const objectName = resolveProtocolName(model);
       const filter = convertWhere(where);
 
       // Note: Sequential updates are used here because ObjectQL's IDataEngine interface
@@ -145,7 +167,7 @@ export function createObjectQLAdapter(dataEngine: IDataEngine) {
     },
 
     delete: async ({ model, where }: { model: string; where: CleanedWhere[] }): Promise<void> => {
-      const objectName = model;
+      const objectName = resolveProtocolName(model);
       const filter = convertWhere(where);
 
       // Note: We need to find the record first to get its ID because ObjectQL's
@@ -160,7 +182,7 @@ export function createObjectQLAdapter(dataEngine: IDataEngine) {
     },
 
     deleteMany: async ({ model, where }: { model: string; where: CleanedWhere[] }): Promise<number> => {
-      const objectName = model;
+      const objectName = resolveProtocolName(model);
       const filter = convertWhere(where);
 
       // Note: Sequential deletes are used here because ObjectQL's delete operation

packages/plugins/plugin-auth/src/objects/auth-account.object.ts

@@ -21,7 +21,7 @@ import { ObjectSchema, Field } from '@objectstack/spec/data';
  * - password: string | null (for email/password provider)
  */
 export const AuthAccount = ObjectSchema.create({
-  name: 'account',
+  name: 'sys_account',
   label: 'Account',
   pluralLabel: 'Accounts',
   icon: 'link',

packages/plugins/plugin-auth/src/objects/auth-session.object.ts

@@ -16,7 +16,7 @@ import { ObjectSchema, Field } from '@objectstack/spec/data';
  * - user_agent: string | null
  */
 export const AuthSession = ObjectSchema.create({
-  name: 'session',
+  name: 'sys_session',
   label: 'Session',
   pluralLabel: 'Sessions',
   icon: 'key',

packages/plugins/plugin-auth/src/objects/auth-user.object.ts

@@ -15,7 +15,7 @@ import { ObjectSchema, Field } from '@objectstack/spec/data';
  * - image: string | null
  */
 export const AuthUser = ObjectSchema.create({
-  name: 'user',
+  name: 'sys_user',
   label: 'User',
   pluralLabel: 'Users',
   icon: 'user',

packages/plugins/plugin-auth/src/objects/auth-verification.object.ts

@@ -14,7 +14,7 @@ import { ObjectSchema, Field } from '@objectstack/spec/data';
  * - identifier: string (email or phone number)
  */
 export const AuthVerification = ObjectSchema.create({
-  name: 'verification',
+  name: 'sys_verification',
   label: 'Verification',
   pluralLabel: 'Verifications',
   icon: 'shield-check',