@objectstack/plugin-auth 4.0.4 → 4.1.0

package/src/auth-plugin.ts

@@ -1,314 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { Plugin, PluginContext, IHttpServer } from '@objectstack/core';
-import { AuthConfig } from '@objectstack/spec/system';
-import { AuthManager } from './auth-manager.js';
-import {
-  SysUser, SysSession, SysAccount, SysVerification,
-  SysOrganization, SysMember, SysInvitation,
-  SysTeam, SysTeamMember,
-  SysApiKey, SysTwoFactor, SysUserPreference,
-} from './objects/index.js';
-
-/**
- * Auth Plugin Options
- * Extends AuthConfig from spec with additional runtime options
- */
-export interface AuthPluginOptions extends Partial<AuthConfig> {
-  /**
-   * Whether to automatically register auth routes
-   * @default true
-   */
-  registerRoutes?: boolean;
-  
-  /**
-   * Base path for auth routes
-   * @default '/api/v1/auth'
-   */
-  basePath?: string;
-}
-
-/**
- * Authentication Plugin
- * 
- * Provides authentication and identity services for ObjectStack applications.
- * 
- * **Dual-Mode Operation:**
- * - **Server mode** (HonoServerPlugin active): Registers HTTP routes at basePath,
- *   forwarding all auth requests to better-auth's universal handler.
- * - **MSW/Mock mode** (no HTTP server): Gracefully skips route registration but
- *   still registers the `auth` service, allowing HttpDispatcher.handleAuth() to
- *   simulate auth flows (sign-up, sign-in, etc.) for development and testing.
- * 
- * Features:
- * - Session management
- * - User registration/login
- * - OAuth providers (Google, GitHub, etc.)
- * - Organization/team support
- * - 2FA, passkeys, magic links
- * 
- * This plugin registers:
- * - `auth` service (auth manager instance) — always
- * - `app.com.objectstack.system` service (system object definitions) — always
- * - HTTP routes for authentication endpoints — only when HTTP server is available
- * 
- * Integrates with better-auth library to provide comprehensive
- * authentication capabilities including email/password, OAuth, 2FA,
- * magic links, passkeys, and organization support.
- */
-export class AuthPlugin implements Plugin {
-  name = 'com.objectstack.auth';
-  type = 'standard';
-  version = '1.0.0';
-  dependencies: string[] = ['com.objectstack.engine.objectql']; // manifest service required
-  
-  private options: AuthPluginOptions;
-  private authManager: AuthManager | null = null;
-
-  constructor(options: AuthPluginOptions = {}) {
-    this.options = {
-      registerRoutes: true,
-      basePath: '/api/v1/auth',
-      ...options
-    };
-  }
-
-  async init(ctx: PluginContext): Promise<void> {
-    ctx.logger.info('Initializing Auth Plugin...');
-
-    // Validate required configuration
-    if (!this.options.secret) {
-      throw new Error('AuthPlugin: secret is required');
-    }
-
-    // Get data engine service for database operations
-    const dataEngine = ctx.getService<any>('data');
-    if (!dataEngine) {
-      ctx.logger.warn('No data engine service found - auth will use in-memory storage');
-    }
-
-    // Initialize auth manager with data engine
-    this.authManager = new AuthManager({
-      ...this.options,
-      dataEngine,
-    });
-
-    // Register auth service
-    ctx.registerService('auth', this.authManager);
-
-    // Register system objects via the manifest service.
-    ctx.getService<{ register(m: any): void }>('manifest').register({
-      id: 'com.objectstack.system',
-      name: 'System',
-      version: '1.0.0',
-      type: 'plugin',
-      namespace: 'sys',
-      objects: [
-        SysUser, SysSession, SysAccount, SysVerification,
-        SysOrganization, SysMember, SysInvitation,
-        SysTeam, SysTeamMember,
-        SysApiKey, SysTwoFactor, SysUserPreference,
-      ],
-    });
-
-    // Contribute navigation items to the Setup App (if SetupPlugin is loaded).
-    // Uses try/catch so AuthPlugin works independently of SetupPlugin.
-    try {
-      const setupNav = ctx.getService<{ contribute(c: any): void }>('setupNav');
-      if (setupNav) {
-        setupNav.contribute({
-          areaId: 'area_administration',
-          items: [
-            { id: 'nav_users', type: 'object', label: 'Users', objectName: 'user', icon: 'users', order: 10 },
-            { id: 'nav_organizations', type: 'object', label: 'Organizations', objectName: 'organization', icon: 'building-2', order: 20 },
-            { id: 'nav_teams', type: 'object', label: 'Teams', objectName: 'team', icon: 'users-round', order: 30 },
-            { id: 'nav_api_keys', type: 'object', label: 'API Keys', objectName: 'api_key', icon: 'key', order: 40 },
-            { id: 'nav_sessions', type: 'object', label: 'Sessions', objectName: 'session', icon: 'monitor', order: 50 },
-          ],
-        });
-        ctx.logger.info('Auth navigation items contributed to Setup App');
-      }
-    } catch {
-      // SetupPlugin not loaded — skip silently
-    }
-
-    ctx.logger.info('Auth Plugin initialized successfully');
-  }
-
-  async start(ctx: PluginContext): Promise<void> {
-    ctx.logger.info('Starting Auth Plugin...');
-
-    if (!this.authManager) {
-      throw new Error('Auth manager not initialized');
-    }
-
-    // Defer HTTP route registration to kernel:ready hook.
-    // This ensures all plugins (including HonoServerPlugin) have completed
-    // their init and start phases before we attempt to look up the
-    // http-server service — making AuthPlugin resilient to plugin
-    // loading order.
-    if (this.options.registerRoutes) {
-      ctx.hook('kernel:ready', async () => {
-        let httpServer: IHttpServer | null = null;
-        try {
-          httpServer = ctx.getService<IHttpServer>('http-server');
-        } catch {
-          // Service not found — expected in MSW/mock mode
-        }
-
-        if (httpServer) {
-          // Auto-detect the actual server URL when no explicit baseUrl was
-          // configured, or when the configured baseUrl uses a different port
-          // than the running server (e.g. port 3000 configured but 3002 bound).
-          // getPort() is optional on IHttpServer; duck-type check for it.
-          const serverWithPort = httpServer as IHttpServer & { getPort?: () => number };
-          if (this.authManager && typeof serverWithPort.getPort === 'function') {
-            const actualPort = serverWithPort.getPort();
-            if (actualPort) {
-              const configuredUrl = this.options.baseUrl || 'http://localhost:3000';
-              const configuredOrigin = new URL(configuredUrl).origin;
-              const actualUrl = `http://localhost:${actualPort}`;
-
-              if (configuredOrigin !== actualUrl) {
-                this.authManager.setRuntimeBaseUrl(actualUrl);
-                ctx.logger.info(
-                  `Auth baseUrl auto-updated to ${actualUrl} (configured: ${configuredUrl})`,
-                );
-              }
-            }
-          }
-
-          // Route registration errors should propagate (server misconfiguration)
-          this.registerAuthRoutes(httpServer, ctx);
-          ctx.logger.info(`Auth routes registered at ${this.options.basePath}`);
-        } else {
-          ctx.logger.warn(
-            'No HTTP server available — auth routes not registered. ' +
-            'Auth service is still available for MSW/mock environments via HttpDispatcher.'
-          );
-        }
-      });
-    }
-
-    // Register auth middleware on ObjectQL engine (if available)
-    try {
-      const ql = ctx.getService<any>('objectql');
-      if (ql && typeof ql.registerMiddleware === 'function') {
-        ql.registerMiddleware(async (opCtx: any, next: () => Promise<void>) => {
-          // If context already has userId or isSystem, skip auth resolution
-          if (opCtx.context?.userId || opCtx.context?.isSystem) {
-            return next();
-          }
-          // Future: resolve session from AsyncLocalStorage or request context
-          await next();
-        });
-        ctx.logger.info('Auth middleware registered on ObjectQL engine');
-      }
-    } catch (_e) {
-      ctx.logger.debug('ObjectQL engine not available, skipping auth middleware registration');
-    }
-
-    ctx.logger.info('Auth Plugin started successfully');
-  }
-
-  async destroy(): Promise<void> {
-    // Cleanup if needed
-    this.authManager = null;
-  }
-
-  /**
-   * Register authentication routes with HTTP server
-   * 
-   * Uses better-auth's universal handler for all authentication requests.
-   * This forwards all requests under basePath to better-auth, which handles:
-   * - Email/password authentication
-   * - OAuth providers (Google, GitHub, etc.)
-   * - Session management
-   * - Password reset
-   * - Email verification
-   * - 2FA, passkeys, magic links (if enabled)
-   */
-  private registerAuthRoutes(httpServer: IHttpServer, ctx: PluginContext): void {
-    if (!this.authManager) return;
-
-    const basePath = this.options.basePath || '/api/v1/auth';
-
-    // Get raw Hono app to use native wildcard routing
-    // Type assertion is safe here because we explicitly require Hono server as a dependency
-    if (!('getRawApp' in httpServer) || typeof (httpServer as any).getRawApp !== 'function') {
-      ctx.logger.error('HTTP server does not support getRawApp() - wildcard routing requires Hono server');
-      throw new Error(
-        'AuthPlugin requires HonoServerPlugin for wildcard routing support. ' +
-        'Please ensure HonoServerPlugin is loaded before AuthPlugin.'
-      );
-    }
-
-    const rawApp = (httpServer as any).getRawApp();
-
-    // Register auth config endpoint - public endpoint for frontend discovery
-    rawApp.get(`${basePath}/config`, async (c: any) => {
-      try {
-        const config = this.authManager!.getPublicConfig();
-        return c.json({
-          success: true,
-          data: config,
-        });
-      } catch (error) {
-        const err = error instanceof Error ? error : new Error(String(error));
-        ctx.logger.error('Auth config error:', err);
-
-        return c.json({
-          success: false,
-          error: {
-            code: 'auth_config_error',
-            message: err.message,
-          },
-        }, 500);
-      }
-    });
-
-    // Register wildcard route to forward all auth requests to better-auth.
-    // better-auth is configured with basePath matching our route prefix, so we
-    // forward the original request directly — no path rewriting needed.
-    rawApp.all(`${basePath}/*`, async (c: any) => {
-      try {
-        // Forward the original request to better-auth handler
-        const response = await this.authManager!.handleRequest(c.req.raw);
-
-        // better-auth catches internal errors and returns error Responses
-        // without throwing, so the catch block below would never trigger.
-        // We proactively log server errors here for observability.
-        if (response.status >= 500) {
-          try {
-            const body = await response.clone().text();
-            ctx.logger.error('[AuthPlugin] better-auth returned server error', new Error(`HTTP ${response.status}: ${body}`));
-          } catch {
-            ctx.logger.error('[AuthPlugin] better-auth returned server error', new Error(`HTTP ${response.status}: (unable to read body)`));
-          }
-        }
-        
-        return response;
-      } catch (error) {
-        const err = error instanceof Error ? error : new Error(String(error));
-        ctx.logger.error('Auth request error:', err);
-        
-        // Return error response
-        return new Response(
-          JSON.stringify({
-            success: false,
-            error: err.message,
-          }),
-          {
-            status: 500,
-            headers: { 'Content-Type': 'application/json' },
-          }
-        );
-      }
-    });
-
-    ctx.logger.info(`Auth routes registered: All requests under ${basePath}/* forwarded to better-auth`);
-  }
-}
-
-
-

package/src/auth-schema-config.ts

@@ -1,339 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { SystemObjectName } from '@objectstack/spec/system';
-
-/**
- * better-auth ↔ ObjectStack Schema Mapping
- *
- * better-auth uses camelCase field names internally (e.g. `emailVerified`, `userId`)
- * while ObjectStack's protocol layer uses snake_case (e.g. `email_verified`, `user_id`).
- *
- * These constants declare the `modelName` and `fields` mappings for each core auth
- * model, following better-auth's official schema customisation API
- * ({@link https://www.better-auth.com/docs/concepts/database}).
- *
- * The mappings serve two purposes:
- * 1. `modelName` — maps the default model name to the ObjectStack protocol name
- *    (e.g. `user` → `sys_user`).
- * 2. `fields`   — maps camelCase field names to their snake_case database column
- *    equivalents. Only fields whose names differ need to be listed; fields that
- *    are already identical (e.g. `email`, `name`, `token`) are omitted.
- *
- * These mappings are consumed by:
- * - The `betterAuth()` configuration in {@link AuthManager} so that
- *   `getAuthTables()` builds the correct schema.
- * - The ObjectQL adapter factory (via `createAdapterFactory`) which uses the
- *   schema to transform data and where-clauses automatically.
- */
-
-// ---------------------------------------------------------------------------
-// User model
-// ---------------------------------------------------------------------------
-
-/**
- * better-auth `user` model mapping.
- *
- * | camelCase (better-auth) | snake_case (ObjectStack) |
- * |:------------------------|:-------------------------|
- * | emailVerified           | email_verified           |
- * | createdAt               | created_at               |
- * | updatedAt               | updated_at               |
- */
-export const AUTH_USER_CONFIG = {
-  modelName: SystemObjectName.USER, // 'sys_user'
-  fields: {
-    emailVerified: 'email_verified',
-    createdAt: 'created_at',
-    updatedAt: 'updated_at',
-  },
-} as const;
-
-// ---------------------------------------------------------------------------
-// Session model
-// ---------------------------------------------------------------------------
-
-/**
- * better-auth `session` model mapping.
- *
- * | camelCase (better-auth) | snake_case (ObjectStack) |
- * |:------------------------|:-------------------------|
- * | userId                  | user_id                  |
- * | expiresAt               | expires_at               |
- * | createdAt               | created_at               |
- * | updatedAt               | updated_at               |
- * | ipAddress               | ip_address               |
- * | userAgent               | user_agent               |
- */
-export const AUTH_SESSION_CONFIG = {
-  modelName: SystemObjectName.SESSION, // 'sys_session'
-  fields: {
-    userId: 'user_id',
-    expiresAt: 'expires_at',
-    createdAt: 'created_at',
-    updatedAt: 'updated_at',
-    ipAddress: 'ip_address',
-    userAgent: 'user_agent',
-  },
-} as const;
-
-// ---------------------------------------------------------------------------
-// Account model
-// ---------------------------------------------------------------------------
-
-/**
- * better-auth `account` model mapping.
- *
- * | camelCase (better-auth)   | snake_case (ObjectStack)       |
- * |:--------------------------|:-------------------------------|
- * | 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       |
- * | createdAt                 | created_at                     |
- * | updatedAt                 | updated_at                     |
- */
-export const AUTH_ACCOUNT_CONFIG = {
-  modelName: SystemObjectName.ACCOUNT, // 'sys_account'
-  fields: {
-    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',
-    createdAt: 'created_at',
-    updatedAt: 'updated_at',
-  },
-} as const;
-
-// ---------------------------------------------------------------------------
-// Verification model
-// ---------------------------------------------------------------------------
-
-/**
- * better-auth `verification` model mapping.
- *
- * | camelCase (better-auth) | snake_case (ObjectStack) |
- * |:------------------------|:-------------------------|
- * | expiresAt               | expires_at               |
- * | createdAt               | created_at               |
- * | updatedAt               | updated_at               |
- */
-export const AUTH_VERIFICATION_CONFIG = {
-  modelName: SystemObjectName.VERIFICATION, // 'sys_verification'
-  fields: {
-    expiresAt: 'expires_at',
-    createdAt: 'created_at',
-    updatedAt: 'updated_at',
-  },
-} as const;
-
-// ===========================================================================
-// Plugin Table Mappings
-// ===========================================================================
-//
-// better-auth plugins (organization, two-factor, etc.) introduce additional
-// tables with their own camelCase field names.  The mappings below are passed
-// to the plugin's `schema` option so that `createAdapterFactory` transforms
-// them to snake_case automatically, just like the core models above.
-// ===========================================================================
-
-// ---------------------------------------------------------------------------
-// Organization plugin – organization table
-// ---------------------------------------------------------------------------
-
-/**
- * better-auth Organization plugin `organization` model mapping.
- *
- * | camelCase (better-auth) | snake_case (ObjectStack) |
- * |:------------------------|:-------------------------|
- * | createdAt               | created_at               |
- * | updatedAt               | updated_at               |
- */
-export const AUTH_ORGANIZATION_SCHEMA = {
-  modelName: SystemObjectName.ORGANIZATION, // 'sys_organization'
-  fields: {
-    createdAt: 'created_at',
-    updatedAt: 'updated_at',
-  },
-} as const;
-
-// ---------------------------------------------------------------------------
-// Organization plugin – member table
-// ---------------------------------------------------------------------------
-
-/**
- * better-auth Organization plugin `member` model mapping.
- *
- * | camelCase (better-auth) | snake_case (ObjectStack) |
- * |:------------------------|:-------------------------|
- * | organizationId          | organization_id          |
- * | userId                  | user_id                  |
- * | createdAt               | created_at               |
- */
-export const AUTH_MEMBER_SCHEMA = {
-  modelName: SystemObjectName.MEMBER, // 'sys_member'
-  fields: {
-    organizationId: 'organization_id',
-    userId: 'user_id',
-    createdAt: 'created_at',
-  },
-} as const;
-
-// ---------------------------------------------------------------------------
-// Organization plugin – invitation table
-// ---------------------------------------------------------------------------
-
-/**
- * better-auth Organization plugin `invitation` model mapping.
- *
- * | camelCase (better-auth) | snake_case (ObjectStack) |
- * |:------------------------|:-------------------------|
- * | organizationId          | organization_id          |
- * | inviterId               | inviter_id               |
- * | expiresAt               | expires_at               |
- * | createdAt               | created_at               |
- * | teamId                  | team_id                  |
- */
-export const AUTH_INVITATION_SCHEMA = {
-  modelName: SystemObjectName.INVITATION, // 'sys_invitation'
-  fields: {
-    organizationId: 'organization_id',
-    inviterId: 'inviter_id',
-    expiresAt: 'expires_at',
-    createdAt: 'created_at',
-    teamId: 'team_id',
-  },
-} as const;
-
-// ---------------------------------------------------------------------------
-// Organization plugin – session additional fields
-// ---------------------------------------------------------------------------
-
-/**
- * Organization plugin adds `activeOrganizationId` (and optionally
- * `activeTeamId`) to the session model. These field mappings are
- * injected via the organization plugin's `schema.session.fields`.
- */
-export const AUTH_ORG_SESSION_FIELDS = {
-  activeOrganizationId: 'active_organization_id',
-  activeTeamId: 'active_team_id',
-} as const;
-
-// ---------------------------------------------------------------------------
-// Organization plugin – team table (optional, when teams enabled)
-// ---------------------------------------------------------------------------
-
-/**
- * better-auth Organization plugin `team` model mapping.
- *
- * | camelCase (better-auth) | snake_case (ObjectStack) |
- * |:------------------------|:-------------------------|
- * | organizationId          | organization_id          |
- * | createdAt               | created_at               |
- * | updatedAt               | updated_at               |
- */
-export const AUTH_TEAM_SCHEMA = {
-  modelName: SystemObjectName.TEAM, // 'sys_team'
-  fields: {
-    organizationId: 'organization_id',
-    createdAt: 'created_at',
-    updatedAt: 'updated_at',
-  },
-} as const;
-
-// ---------------------------------------------------------------------------
-// Organization plugin – teamMember table (optional, when teams enabled)
-// ---------------------------------------------------------------------------
-
-/**
- * better-auth Organization plugin `teamMember` model mapping.
- *
- * | camelCase (better-auth) | snake_case (ObjectStack) |
- * |:------------------------|:-------------------------|
- * | teamId                  | team_id                  |
- * | userId                  | user_id                  |
- * | createdAt               | created_at               |
- */
-export const AUTH_TEAM_MEMBER_SCHEMA = {
-  modelName: SystemObjectName.TEAM_MEMBER, // 'sys_team_member'
-  fields: {
-    teamId: 'team_id',
-    userId: 'user_id',
-    createdAt: 'created_at',
-  },
-} as const;
-
-// ---------------------------------------------------------------------------
-// Two-Factor plugin – twoFactor table
-// ---------------------------------------------------------------------------
-
-/**
- * better-auth Two-Factor plugin `twoFactor` model mapping.
- *
- * | camelCase (better-auth) | snake_case (ObjectStack) |
- * |:------------------------|:-------------------------|
- * | backupCodes             | backup_codes             |
- * | userId                  | user_id                  |
- */
-export const AUTH_TWO_FACTOR_SCHEMA = {
-  modelName: SystemObjectName.TWO_FACTOR, // 'sys_two_factor'
-  fields: {
-    backupCodes: 'backup_codes',
-    userId: 'user_id',
-  },
-} as const;
-
-/**
- * Two-Factor plugin adds a `twoFactorEnabled` field to the user model.
- */
-export const AUTH_TWO_FACTOR_USER_FIELDS = {
-  twoFactorEnabled: 'two_factor_enabled',
-} as const;
-
-/**
- * Builds the `schema` option for better-auth's `twoFactor()` plugin.
- *
- * @returns An object suitable for `twoFactor({ schema: … })`
- */
-export function buildTwoFactorPluginSchema() {
-  return {
-    twoFactor: AUTH_TWO_FACTOR_SCHEMA,
-    user: {
-      fields: AUTH_TWO_FACTOR_USER_FIELDS,
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Helper: build organization plugin schema option
-// ---------------------------------------------------------------------------
-
-/**
- * Builds the `schema` option for better-auth's `organization()` plugin.
- *
- * The organization plugin accepts a `schema` sub-option that allows
- * customising model names and field names for each table it manages.
- * This helper assembles the correct snake_case mappings from the
- * individual `AUTH_*_SCHEMA` constants above.
- *
- * @returns An object suitable for `organization({ schema: … })`
- */
-export function buildOrganizationPluginSchema() {
-  return {
-    organization: AUTH_ORGANIZATION_SCHEMA,
-    member: AUTH_MEMBER_SCHEMA,
-    invitation: AUTH_INVITATION_SCHEMA,
-    team: AUTH_TEAM_SCHEMA,
-    teamMember: AUTH_TEAM_MEMBER_SCHEMA,
-    session: {
-      fields: AUTH_ORG_SESSION_FIELDS,
-    },
-  };
-}

package/src/index.ts

@@ -1,16 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * @objectstack/plugin-auth
- * 
- * Authentication & Identity Plugin for ObjectStack
- * Powered by better-auth for robust, secure authentication
- * Uses ObjectQL for data persistence (no third-party ORM required)
- */
-
-export * from './auth-plugin.js';
-export * from './auth-manager.js';
-export * from './objectql-adapter.js';
-export * from './auth-schema-config.js';
-export * from './objects/index.js';
-export type { AuthConfig, AuthProviderConfig, AuthPluginConfig } from '@objectstack/spec/system';