feat(plugin-auth): add schema mappings for organization, twoFactor, magicLink plugins

- Add AUTH_ORGANIZATION_SCHEMA, AUTH_MEMBER_SCHEMA, AUTH_INVITATION_SCHEMA,
  AUTH_TEAM_SCHEMA, AUTH_TEAM_MEMBER_SCHEMA for organization plugin tables
- Add AUTH_TWO_FACTOR_SCHEMA and AUTH_TWO_FACTOR_USER_FIELDS for 2FA plugin
- Add AUTH_ORG_SESSION_FIELDS for org plugin session extensions
- Add buildOrganizationPluginSchema() and buildTwoFactorPluginSchema() helpers
- Wire up plugin registration in AuthManager.buildPluginList() based on
  AuthPluginConfig flags (organization, twoFactor, magicLink)
- Add 14 new tests for plugin schema configs and plugin registration
- Update README documentation with plugin table mappings

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

Author: Copilot

packages/plugins/plugin-auth/README.md

@@ -215,11 +215,23 @@ export const AuthUser = ObjectSchema.create({
 **Database Objects:**
 Uses ObjectStack `sys_` prefixed protocol names with snake_case field naming.
 The adapter automatically maps better-auth model names to protocol names:
+
+*Core models:*
 - `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.)
 
+*Organization plugin (when `plugins.organization: true`):*
+- `sys_organization` (← `organization`) - Organizations (id, name, slug, logo, created_at, etc.)
+- `sys_member` (← `member`) - Organization members (id, organization_id, user_id, role, created_at)
+- `sys_invitation` (← `invitation`) - Invitations (id, organization_id, inviter_id, email, role, expires_at, etc.)
+- `sys_team` (← `team`) - Teams (id, name, organization_id, created_at, etc.)
+- `sys_team_member` (← `teamMember`) - Team members (id, team_id, user_id, created_at)
+
+*Two-Factor plugin (when `plugins.twoFactor: true`):*
+- `sys_two_factor` (← `twoFactor`) - 2FA secrets (id, secret, backup_codes, user_id)
+
 **Schema Mapping (modelName + fields):**
 
 better-auth uses camelCase field names internally (`emailVerified`, `userId`, `createdAt`, etc.)
@@ -237,6 +249,8 @@ import {
   AUTH_SESSION_CONFIG,
   AUTH_ACCOUNT_CONFIG,
   AUTH_VERIFICATION_CONFIG,
+  buildOrganizationPluginSchema,
+  buildTwoFactorPluginSchema,
 } from '@objectstack/plugin-auth';
 
 // Applied to the betterAuth() config:
@@ -246,7 +260,10 @@ const auth = betterAuth({
   session:      { ...AUTH_SESSION_CONFIG, expiresIn: 604800 },
   account:      { ...AUTH_ACCOUNT_CONFIG },
   verification: { ...AUTH_VERIFICATION_CONFIG },
-  // ...
+  plugins: [
+    organization({ schema: buildOrganizationPluginSchema() }),
+    twoFactor({ schema: buildTwoFactorPluginSchema() }),
+  ],
 });
 ```
 

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

@@ -11,6 +11,20 @@ vi.mock('better-auth', () => ({
   })),
 }));
 
+// Mock plugin imports — we only need to verify they are called with the
+// correct schema options; the actual plugin logic is tested by better-auth.
+vi.mock('better-auth/plugins/organization', () => ({
+  organization: vi.fn((opts: any) => ({ id: 'organization', _opts: opts })),
+}));
+
+vi.mock('better-auth/plugins/two-factor', () => ({
+  twoFactor: vi.fn((opts: any) => ({ id: 'two-factor', _opts: opts })),
+}));
+
+vi.mock('better-auth/plugins/magic-link', () => ({
+  magicLink: vi.fn((_opts?: any) => ({ id: 'magic-link' })),
+}));
+
 import { betterAuth } from 'better-auth';
 
 describe('AuthManager', () => {
@@ -244,4 +258,117 @@ describe('AuthManager', () => {
       warnSpy.mockRestore();
     });
   });
+
+  describe('plugin registration', () => {
+    it('should not include any plugins when no plugin config is provided', () => {
+      let capturedConfig: any;
+      (betterAuth as any).mockImplementation((config: any) => {
+        capturedConfig = config;
+        return { handler: vi.fn(), api: {} };
+      });
+
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const manager = new AuthManager({
+        secret: 'test-secret-at-least-32-chars-long',
+        baseUrl: 'http://localhost:3000',
+      });
+      manager.getAuthInstance();
+      warnSpy.mockRestore();
+
+      expect(capturedConfig.plugins).toEqual([]);
+    });
+
+    it('should register organization plugin with schema mapping when enabled', () => {
+      let capturedConfig: any;
+      (betterAuth as any).mockImplementation((config: any) => {
+        capturedConfig = config;
+        return { handler: vi.fn(), api: {} };
+      });
+
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const manager = new AuthManager({
+        secret: 'test-secret-at-least-32-chars-long',
+        baseUrl: 'http://localhost:3000',
+        plugins: { organization: true },
+      });
+      manager.getAuthInstance();
+      warnSpy.mockRestore();
+
+      const orgPlugin = capturedConfig.plugins.find((p: any) => p.id === 'organization');
+      expect(orgPlugin).toBeDefined();
+      // Verify schema was passed to organization() call
+      expect(orgPlugin._opts.schema.organization.modelName).toBe('sys_organization');
+      expect(orgPlugin._opts.schema.member.modelName).toBe('sys_member');
+      expect(orgPlugin._opts.schema.invitation.modelName).toBe('sys_invitation');
+      expect(orgPlugin._opts.schema.team.modelName).toBe('sys_team');
+      expect(orgPlugin._opts.schema.teamMember.modelName).toBe('sys_team_member');
+      expect(orgPlugin._opts.schema.session.fields.activeOrganizationId).toBe('active_organization_id');
+    });
+
+    it('should register twoFactor plugin with schema mapping when enabled', () => {
+      let capturedConfig: any;
+      (betterAuth as any).mockImplementation((config: any) => {
+        capturedConfig = config;
+        return { handler: vi.fn(), api: {} };
+      });
+
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const manager = new AuthManager({
+        secret: 'test-secret-at-least-32-chars-long',
+        baseUrl: 'http://localhost:3000',
+        plugins: { twoFactor: true },
+      });
+      manager.getAuthInstance();
+      warnSpy.mockRestore();
+
+      const tfPlugin = capturedConfig.plugins.find((p: any) => p.id === 'two-factor');
+      expect(tfPlugin).toBeDefined();
+      expect(tfPlugin._opts.schema.twoFactor.modelName).toBe('sys_two_factor');
+      expect(tfPlugin._opts.schema.twoFactor.fields.backupCodes).toBe('backup_codes');
+      expect(tfPlugin._opts.schema.twoFactor.fields.userId).toBe('user_id');
+      expect(tfPlugin._opts.schema.user.fields.twoFactorEnabled).toBe('two_factor_enabled');
+    });
+
+    it('should register magicLink plugin when enabled', () => {
+      let capturedConfig: any;
+      (betterAuth as any).mockImplementation((config: any) => {
+        capturedConfig = config;
+        return { handler: vi.fn(), api: {} };
+      });
+
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const manager = new AuthManager({
+        secret: 'test-secret-at-least-32-chars-long',
+        baseUrl: 'http://localhost:3000',
+        plugins: { magicLink: true },
+      });
+      manager.getAuthInstance();
+      warnSpy.mockRestore();
+
+      const mlPlugin = capturedConfig.plugins.find((p: any) => p.id === 'magic-link');
+      expect(mlPlugin).toBeDefined();
+    });
+
+    it('should register multiple plugins when multiple flags are enabled', () => {
+      let capturedConfig: any;
+      (betterAuth as any).mockImplementation((config: any) => {
+        capturedConfig = config;
+        return { handler: vi.fn(), api: {} };
+      });
+
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const manager = new AuthManager({
+        secret: 'test-secret-at-least-32-chars-long',
+        baseUrl: 'http://localhost:3000',
+        plugins: { organization: true, twoFactor: true, magicLink: true },
+      });
+      manager.getAuthInstance();
+      warnSpy.mockRestore();
+
+      expect(capturedConfig.plugins).toHaveLength(3);
+      expect(capturedConfig.plugins.map((p: any) => p.id).sort()).toEqual(
+        ['magic-link', 'organization', 'two-factor'],
+      );
+    });
+  });
 });

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

@@ -2,6 +2,9 @@
 
 import { betterAuth } from 'better-auth';
 import type { Auth, BetterAuthOptions } from 'better-auth';
+import { organization } from 'better-auth/plugins/organization';
+import { twoFactor } from 'better-auth/plugins/two-factor';
+import { magicLink } from 'better-auth/plugins/magic-link';
 import type { AuthConfig } from '@objectstack/spec/system';
 import type { IDataEngine } from '@objectstack/core';
 import { createObjectQLAdapterFactory } from './objectql-adapter.js';
@@ -10,6 +13,8 @@ import {
   AUTH_SESSION_CONFIG,
   AUTH_ACCOUNT_CONFIG,
   AUTH_VERIFICATION_CONFIG,
+  buildOrganizationPluginSchema,
+  buildTwoFactorPluginSchema,
 } from './auth-schema-config.js';
 
 /**
@@ -104,11 +109,54 @@ export class AuthManager {
         expiresIn: this.config.session?.expiresIn || 60 * 60 * 24 * 7, // 7 days default
         updateAge: this.config.session?.updateAge || 60 * 60 * 24, // 1 day default
       },
+      
+      // better-auth plugins — registered based on AuthPluginConfig flags
+      plugins: this.buildPluginList(),
     };
 
     return betterAuth(betterAuthConfig);
   }
 
+  /**
+   * Build the list of better-auth plugins based on AuthPluginConfig flags.
+   *
+   * Each plugin that introduces its own database tables is configured with
+   * a `schema` option containing the appropriate snake_case field mappings,
+   * so that `createAdapterFactory` transforms them automatically.
+   */
+  private buildPluginList(): any[] {
+    const pluginConfig = this.config.plugins;
+    const plugins: any[] = [];
+    
+    if (pluginConfig?.organization) {
+      plugins.push(organization({
+        schema: buildOrganizationPluginSchema(),
+      }));
+    }
+    
+    if (pluginConfig?.twoFactor) {
+      plugins.push(twoFactor({
+        schema: buildTwoFactorPluginSchema(),
+      }));
+    }
+
+    if (pluginConfig?.magicLink) {
+      // magic-link reuses the `verification` table — no extra schema mapping needed.
+      // The sendMagicLink callback must be provided by the application at a higher level.
+      // Here we provide a no-op default that logs a warning; real applications should
+      // override this via AuthManagerOptions or a config extension point.
+      plugins.push(magicLink({
+        sendMagicLink: async ({ email, url }) => {
+          console.warn(
+            `[AuthManager] Magic-link requested for ${email} but no sendMagicLink handler configured. URL: ${url}`,
+          );
+        },
+      }));
+    }
+    
+    return plugins;
+  }
+
   /**
    * Create database configuration using ObjectQL adapter
    *