@vobase/core 0.10.0 → 0.12.0

package/src/middleware/audit.test.ts

@@ -0,0 +1,169 @@
+import { Database } from 'bun:sqlite';
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { drizzle } from 'drizzle-orm/bun-sqlite';
+import { Hono } from 'hono';
+
+import type { VobaseDb } from '../db';
+import * as schema from '../modules/audit/schema';
+import { requestAuditMiddleware } from '../modules/audit/middleware';
+import { createAuthAuditHooks } from '../modules/auth/audit-hooks';
+
+interface AuditRow {
+  event: string;
+  actorId: string | null;
+  actorEmail: string | null;
+  ip: string | null;
+  details: string | null;
+}
+
+describe('audit middleware and hooks', () => {
+  let sqlite: Database;
+  let db: VobaseDb;
+
+  beforeEach(() => {
+    sqlite = new Database(':memory:');
+    sqlite.run('PRAGMA journal_mode=WAL');
+    sqlite.exec(`
+      CREATE TABLE _audit_log (
+        id TEXT PRIMARY KEY,
+        event TEXT NOT NULL,
+        actor_id TEXT,
+        actor_email TEXT,
+        ip TEXT,
+        details TEXT,
+        created_at INTEGER NOT NULL
+      )
+    `);
+    db = drizzle({ client: sqlite, schema }) as unknown as VobaseDb;
+  });
+
+  afterEach(() => {
+    sqlite.close();
+  });
+
+  function getRows(): AuditRow[] {
+    return sqlite
+      .prepare(
+        `
+          SELECT
+            event,
+            actor_id AS actorId,
+            actor_email AS actorEmail,
+            ip,
+            details
+          FROM _audit_log
+          ORDER BY rowid ASC
+        `,
+      )
+      .all() as AuditRow[];
+  }
+
+  it('logs api_mutation for POST requests', async () => {
+    const app = new Hono();
+    app.use('/api/*', async (c, next) => {
+      c.set('user', {
+        id: 'user_post',
+        email: 'post@example.com',
+        name: 'Post User',
+        role: 'user',
+      });
+      await next();
+    });
+    app.use('/api/*', requestAuditMiddleware(db));
+    app.post('/api/test', (c) => c.json({ ok: true }));
+
+    const response = await app.request('http://localhost/api/test', {
+      method: 'POST',
+      headers: { 'x-forwarded-for': '203.0.113.10' },
+    });
+
+    expect(response.status).toBe(200);
+
+    const rows = getRows();
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toEqual({
+      event: 'api_mutation',
+      actorId: 'user_post',
+      actorEmail: 'post@example.com',
+      ip: '203.0.113.10',
+      details: JSON.stringify({ method: 'POST', path: '/api/test' }),
+    });
+  });
+
+  it('does not log GET requests', async () => {
+    const app = new Hono();
+    app.use('/api/*', async (c, next) => {
+      c.set('user', {
+        id: 'user_get',
+        email: 'get@example.com',
+        name: 'Get User',
+        role: 'user',
+      });
+      await next();
+    });
+    app.use('/api/*', requestAuditMiddleware(db));
+    app.get('/api/test', (c) => c.json({ ok: true }));
+
+    const response = await app.request('http://localhost/api/test', {
+      method: 'GET',
+      headers: { 'x-forwarded-for': '203.0.113.11' },
+    });
+
+    expect(response.status).toBe(200);
+    expect(getRows()).toHaveLength(0);
+  });
+
+  it('logs signin events from auth hooks', async () => {
+    const hooks = createAuthAuditHooks(db);
+
+    await hooks.after({
+      path: '/sign-in/email',
+      method: 'POST',
+      headers: new Headers({ 'x-real-ip': '198.51.100.8' }),
+      context: {
+        newSession: {
+          user: { id: 'user_signin', email: 'signin@example.com' },
+        },
+        session: null,
+      },
+      returnHeaders: true,
+    } as unknown as Parameters<typeof hooks.after>[0]);
+
+    const rows = getRows();
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toEqual({
+      event: 'signin',
+      actorId: 'user_signin',
+      actorEmail: 'signin@example.com',
+      ip: '198.51.100.8',
+      details: JSON.stringify({ path: '/sign-in/email' }),
+    });
+  });
+
+  it('logs signup events from auth hooks', async () => {
+    const hooks = createAuthAuditHooks(db);
+
+    await hooks.after({
+      path: '/sign-up/email',
+      method: 'POST',
+      headers: new Headers({ 'x-forwarded-for': '192.0.2.25, 10.0.0.1' }),
+      context: {
+        newSession: {
+          user: { id: 'user_signup', email: 'signup@example.com' },
+        },
+        session: null,
+      },
+      returnHeaders: true,
+    } as unknown as Parameters<typeof hooks.after>[0]);
+
+    const rows = getRows();
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toEqual({
+      event: 'signup',
+      actorId: 'user_signup',
+      actorEmail: 'signup@example.com',
+      ip: '192.0.2.25',
+      details: JSON.stringify({ path: '/sign-up/email' }),
+    });
+  });
+});

package/src/module-registry.ts

@@ -0,0 +1,18 @@
+import { conflict } from './infra/errors';
+import type { VobaseModule } from './module';
+
+export function registerModules(
+  modules: VobaseModule[],
+): Map<string, VobaseModule> {
+  const registry = new Map<string, VobaseModule>();
+
+  for (const module of modules) {
+    if (registry.has(module.name)) {
+      throw conflict(`Module "${module.name}"`);
+    }
+
+    registry.set(module.name, module);
+  }
+
+  return registry;
+}

package/src/module.test.ts

@@ -0,0 +1,168 @@
+import { describe, expect, it } from 'bun:test';
+import { Hono } from 'hono';
+
+import { VobaseError } from './infra/errors';
+import { defineBuiltinModule, defineModule } from './module';
+import { registerModules } from './module-registry';
+
+function createBaseConfig(name: string) {
+  return {
+    name,
+    schema: { invoices: {} },
+    routes: new Hono(),
+  };
+}
+
+function expectValidationError(fn: () => void): void {
+  try {
+    fn();
+    throw new Error('Expected defineModule to throw a VobaseError');
+  } catch (error) {
+    expect(error).toBeInstanceOf(VobaseError);
+    expect((error as VobaseError).code).toBe('VALIDATION');
+  }
+}
+
+describe('defineModule()', () => {
+  it("returns a frozen VobaseModule for name='invoicing'", () => {
+    const module = defineModule(createBaseConfig('invoicing'));
+
+    expect(module.name).toBe('invoicing');
+    expect(module.schema).toEqual({ invoices: {} });
+    expect(Object.isFrozen(module)).toBe(true);
+  });
+
+  it("throws VobaseError for name='auth'", () => {
+    expectValidationError(() => {
+      defineModule(createBaseConfig('auth'));
+    });
+  });
+
+  it("throws VobaseError for name='mcp'", () => {
+    expectValidationError(() => {
+      defineModule(createBaseConfig('mcp'));
+    });
+  });
+
+  it("throws VobaseError for name='health'", () => {
+    expectValidationError(() => {
+      defineModule(createBaseConfig('health'));
+    });
+  });
+
+  it("throws VobaseError for name='api'", () => {
+    expectValidationError(() => {
+      defineModule(createBaseConfig('api'));
+    });
+  });
+
+  it("allows name='system'", () => {
+    const module = defineModule(createBaseConfig('system'));
+    expect(module.name).toBe('system');
+  });
+
+  it("throws for name='AUTH'", () => {
+    expectValidationError(() => {
+      defineModule(createBaseConfig('AUTH'));
+    });
+  });
+
+  it("allows name='invoice-2024'", () => {
+    const module = defineModule(createBaseConfig('invoice-2024'));
+    expect(module.name).toBe('invoice-2024');
+  });
+
+  it('allows empty schema for modules without tables', () => {
+    const module = defineModule({
+      ...createBaseConfig('billing'),
+      schema: {},
+    });
+    expect(module.name).toBe('billing');
+  });
+});
+
+describe('defineBuiltinModule()', () => {
+  it("succeeds for name='_audit'", () => {
+    const module = defineBuiltinModule({
+      name: '_audit',
+      schema: { auditLog: {} },
+      routes: new Hono(),
+    });
+    expect(module.name).toBe('_audit');
+    expect(Object.isFrozen(module)).toBe(true);
+  });
+
+  it("succeeds for name='_sequences'", () => {
+    const module = defineBuiltinModule({
+      name: '_sequences',
+      schema: { sequences: {} },
+      routes: new Hono(),
+    });
+    expect(module.name).toBe('_sequences');
+  });
+
+  it('accepts an init hook', () => {
+    const module = defineBuiltinModule({
+      name: '_credentials',
+      schema: { credentials: {} },
+      routes: new Hono(),
+      init: () => {},
+    });
+    expect(module.init).toBeDefined();
+  });
+
+  it('allows empty schema for built-in modules', () => {
+    const module = defineBuiltinModule({
+      name: '_system-proxy',
+      schema: {},
+      routes: new Hono(),
+    });
+    expect(module.name).toBe('_system-proxy');
+  });
+
+  it("throws for name without _ prefix (e.g., 'audit')", () => {
+    expectValidationError(() => {
+      defineBuiltinModule({
+        name: 'audit',
+        schema: { auditLog: {} },
+        routes: new Hono(),
+      });
+    });
+  });
+
+  it("throws for name with uppercase (e.g., '_Audit')", () => {
+    expectValidationError(() => {
+      defineBuiltinModule({
+        name: '_Audit',
+        schema: { auditLog: {} },
+        routes: new Hono(),
+      });
+    });
+  });
+});
+
+describe('defineModule rejects _ prefix', () => {
+  it("throws for name='_audit' via defineModule", () => {
+    expectValidationError(() => {
+      defineModule(createBaseConfig('_audit'));
+    });
+  });
+});
+
+describe('registerModules()', () => {
+  it('throws when duplicate module names are provided', () => {
+    const first = defineModule(createBaseConfig('orders'));
+    const second = defineModule({
+      ...createBaseConfig('orders'),
+      schema: { payments: {} },
+    });
+
+    try {
+      registerModules([first, second]);
+      throw new Error('Expected registerModules to throw for duplicate names');
+    } catch (error) {
+      expect(error).toBeInstanceOf(VobaseError);
+      expect((error as VobaseError).code).toBe('CONFLICT');
+    }
+  });
+});

package/src/module.ts

@@ -0,0 +1,111 @@
+import type { Hono } from 'hono';
+
+import type { ModuleInitContext } from './contracts/module';
+import { validation } from './infra/errors';
+import type { JobDefinition } from './infra/job';
+
+const MODULE_NAME_PATTERN = /^[a-z0-9-]+$/;
+const BUILTIN_NAME_PATTERN = /^_[a-z0-9-]+$/;
+const RESERVED_MODULE_NAMES = new Set(['auth', 'mcp', 'health', 'api']);
+
+export interface VobaseModule {
+  name: string;
+  schema: Record<string, unknown>;
+  routes: Hono;
+  jobs?: JobDefinition[];
+  pages?: Record<string, string>;
+  seed?: () => Promise<void>;
+  init?: (ctx: ModuleInitContext) => Promise<void> | void;
+}
+
+export interface DefineModuleConfig {
+  name: string;
+  schema: Record<string, unknown>;
+  routes: Hono;
+  jobs?: JobDefinition[];
+  pages?: Record<string, string>;
+  seed?: () => Promise<void>;
+  init?: (ctx: ModuleInitContext) => Promise<void> | void;
+}
+
+export function defineModule(config: DefineModuleConfig): VobaseModule {
+  if (!config.name.trim()) {
+    throw validation(
+      { name: config.name },
+      'Module name must be a non-empty string',
+    );
+  }
+
+  if (!MODULE_NAME_PATTERN.test(config.name)) {
+    throw validation(
+      { name: config.name },
+      'Module name must use lowercase alphanumeric characters and hyphens only',
+    );
+  }
+
+  if (RESERVED_MODULE_NAMES.has(config.name)) {
+    throw validation(
+      { name: config.name },
+      `Module name "${config.name}" is reserved`,
+    );
+  }
+
+  if (
+    typeof config.schema !== 'object' ||
+    config.schema === null ||
+    Array.isArray(config.schema)
+  ) {
+    throw validation(
+      { schema: config.schema },
+      'Module schema must be an object',
+    );
+  }
+
+  if (
+    typeof config.routes !== 'object' ||
+    config.routes === null ||
+    typeof config.routes.get !== 'function'
+  ) {
+    throw validation(
+      { routes: config.routes },
+      'Module routes must be a Hono router instance',
+    );
+  }
+
+  return Object.freeze({ ...config });
+}
+
+/**
+ * Internal-only factory for built-in modules. Bypasses user-facing name
+ * validation to allow the `_` prefix convention (e.g., `_audit`, `_sequences`).
+ * Not exported in the public API (index.ts).
+ */
+export function defineBuiltinModule(config: DefineModuleConfig): VobaseModule {
+  if (!config.name.trim()) {
+    throw validation(
+      { name: config.name },
+      'Module name must be a non-empty string',
+    );
+  }
+
+  if (!BUILTIN_NAME_PATTERN.test(config.name)) {
+    throw validation(
+      { name: config.name },
+      'Built-in module name must start with _ and use lowercase alphanumeric characters and hyphens',
+    );
+  }
+
+  // Built-in modules may have empty schemas (e.g., if they only read from other module tables)
+  if (
+    typeof config.routes !== 'object' ||
+    config.routes === null ||
+    typeof config.routes.get !== 'function'
+  ) {
+    throw validation(
+      { routes: config.routes },
+      'Module routes must be a Hono router instance',
+    );
+  }
+
+  return Object.freeze({ ...config });
+}

package/src/modules/audit/index.ts

@@ -0,0 +1,18 @@
+import { Hono } from 'hono';
+
+import { defineBuiltinModule } from '../../module';
+
+import { auditLog, recordAudits } from './schema';
+
+export { auditLog, recordAudits } from './schema';
+export { trackChanges } from './track-changes';
+export { requestAuditMiddleware } from './middleware';
+
+export function createAuditModule() {
+  return defineBuiltinModule({
+    name: '_audit',
+    schema: { auditLog, recordAudits },
+    routes: new Hono(),
+    init: () => {},
+  });
+}

package/src/modules/audit/middleware.ts

@@ -0,0 +1,33 @@
+import { createMiddleware } from 'hono/factory';
+
+import type { VobaseDb } from '../../db/client';
+
+import { auditLog } from './schema';
+
+const MUTATION_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+
+function getRequestIp(headers: Headers | undefined): string {
+  const forwardedFor = headers?.get('x-forwarded-for')?.split(',')[0]?.trim();
+  return forwardedFor || headers?.get('x-real-ip') || 'unknown';
+}
+
+export function requestAuditMiddleware(db: VobaseDb) {
+  return createMiddleware(async (c, next) => {
+    try {
+      await next();
+    } finally {
+      if (MUTATION_METHODS.has(c.req.method)) {
+        const user = c.get('user');
+        db.insert(auditLog)
+          .values({
+            event: 'api_mutation',
+            actorId: user?.id ?? null,
+            actorEmail: user?.email ?? null,
+            ip: getRequestIp(c.req.raw.headers),
+            details: JSON.stringify({ method: c.req.method, path: c.req.path }),
+          })
+          .run();
+      }
+    }
+  });
+}

package/src/modules/audit/schema.ts

@@ -0,0 +1,35 @@
+import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+
+import { nanoidPrimaryKey } from '../../db/helpers';
+
+/**
+ * Audit log table for tracking system events (sign-in, sign-up, role changes, etc.)
+ * Events are immutable - no updatedAt column
+ */
+export const auditLog = sqliteTable('_audit_log', {
+  id: nanoidPrimaryKey(),
+  event: text('event').notNull(),
+  actorId: text('actor_id'),
+  actorEmail: text('actor_email'),
+  ip: text('ip'),
+  details: text('details'), // JSON string
+  createdAt: integer('created_at', { mode: 'timestamp_ms' })
+    .notNull()
+    .$defaultFn(() => new Date()),
+});
+
+/**
+ * Record audits table for tracking changes to individual records
+ * Stores before/after data for data change auditing
+ */
+export const recordAudits = sqliteTable('_record_audits', {
+  id: nanoidPrimaryKey(),
+  tableName: text('table_name').notNull(),
+  recordId: text('record_id').notNull(),
+  oldData: text('old_data'), // JSON string
+  newData: text('new_data'), // JSON string
+  changedBy: text('changed_by'), // user ID
+  createdAt: integer('created_at', { mode: 'timestamp_ms' })
+    .notNull()
+    .$defaultFn(() => new Date()),
+});

package/src/modules/audit/track-changes.ts

@@ -0,0 +1,70 @@
+import type { VobaseDb } from '../../db/client';
+
+import { recordAudits } from './schema';
+
+function valuesAreEqual(left: unknown, right: unknown): boolean {
+  if (Object.is(left, right)) {
+    return true;
+  }
+
+  if (
+    typeof left === 'object' &&
+    left !== null &&
+    typeof right === 'object' &&
+    right !== null
+  ) {
+    return JSON.stringify(left) === JSON.stringify(right);
+  }
+
+  return false;
+}
+
+export function trackChanges(
+  db: VobaseDb,
+  tableName: string,
+  recordId: string,
+  oldData: Record<string, unknown> | null,
+  newData: Record<string, unknown> | null,
+  userId?: string,
+): void {
+  if (oldData === null && newData === null) {
+    return;
+  }
+
+  let oldDiff: Record<string, unknown> | null = null;
+  let newDiff: Record<string, unknown> | null = null;
+
+  if (oldData === null) {
+    newDiff = newData;
+  } else if (newData === null) {
+    oldDiff = oldData;
+  } else {
+    oldDiff = {};
+    newDiff = {};
+
+    const keys = new Set([...Object.keys(oldData), ...Object.keys(newData)]);
+    for (const key of keys) {
+      const previousValue = oldData[key];
+      const nextValue = newData[key];
+
+      if (!valuesAreEqual(previousValue, nextValue)) {
+        oldDiff[key] = previousValue;
+        newDiff[key] = nextValue;
+      }
+    }
+
+    if (Object.keys(oldDiff).length === 0) {
+      return;
+    }
+  }
+
+  db.insert(recordAudits)
+    .values({
+      tableName,
+      recordId,
+      oldData: oldDiff === null ? null : JSON.stringify(oldDiff),
+      newData: newDiff === null ? null : JSON.stringify(newDiff),
+      changedBy: userId ?? null,
+    })
+    .run();
+}

package/src/modules/auth/audit-hooks.ts

@@ -0,0 +1,74 @@
+import { createAuthMiddleware } from 'better-auth/api';
+
+import type { VobaseDb } from '../../db/client';
+import { auditLog } from '../audit/schema';
+
+const AUTH_EVENT_BY_PATH = {
+  '/sign-in/email': 'signin',
+  '/sign-up/email': 'signup',
+  '/sign-out': 'signout',
+} as const;
+
+function getRequestIp(headers: Headers | undefined): string {
+  const forwardedFor = headers?.get('x-forwarded-for')?.split(',')[0]?.trim();
+  return forwardedFor || headers?.get('x-real-ip') || 'unknown';
+}
+
+function writeAuditLog(
+  db: VobaseDb,
+  event: string,
+  actorId: string | null,
+  actorEmail: string | null,
+  ip: string,
+  details: Record<string, string>,
+): void {
+  db.insert(auditLog)
+    .values({
+      event,
+      actorId,
+      actorEmail,
+      ip,
+      details: JSON.stringify(details),
+    })
+    .run();
+}
+
+export function createAuthAuditHooks(db: VobaseDb) {
+  // Store user info before signout destroys the session
+  const pendingSignout = new WeakMap<Headers, { id: string; email: string }>();
+
+  return {
+    before: createAuthMiddleware(async (ctx) => {
+      if (ctx.path === '/sign-out') {
+        const user = ctx.context.session?.user;
+        if (user && ctx.headers) {
+          pendingSignout.set(ctx.headers, { id: user.id, email: user.email });
+        }
+      }
+    }),
+    after: createAuthMiddleware(async (ctx) => {
+      const event =
+        AUTH_EVENT_BY_PATH[ctx.path as keyof typeof AUTH_EVENT_BY_PATH];
+      if (!event) {
+        return;
+      }
+
+      let actor = (ctx.context.newSession ?? ctx.context.session)?.user;
+
+      // For signout, retrieve the user captured in the before hook
+      if (!actor && ctx.path === '/sign-out' && ctx.headers) {
+        actor = pendingSignout.get(ctx.headers) as typeof actor;
+        pendingSignout.delete(ctx.headers);
+      }
+
+      writeAuditLog(
+        db,
+        event,
+        actor?.id ?? null,
+        actor?.email ?? null,
+        getRequestIp(ctx.headers),
+        { path: ctx.path },
+      );
+    }),
+  };
+}