@rangka/core 0.0.1

package/src/audit/__tests__/audit.test.ts

@@ -0,0 +1,144 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { recordAudit, getAuditHistory } from '../record.js';
+
+function createMockDb() {
+  const rows: any[] = [];
+  let idCounter = 1;
+
+  const db: any = {
+    insertInto: (_table: string) => ({
+      values: (data: any) => ({
+        returningAll: () => ({
+          execute: async () => {
+            const row = {
+              id: `audit-${idCounter++}`,
+              ...data,
+              changes: typeof data.changes === 'string' ? JSON.parse(data.changes) : data.changes,
+              timestamp: new Date(),
+            };
+            rows.push(row);
+            return [row];
+          },
+        }),
+      }),
+    }),
+    selectFrom: (_table: string) => {
+      const filters: Array<{ col: string; val: any }> = [];
+      const builder: any = {
+        selectAll: () => builder,
+        where: (col: string, op: string, val: any) => {
+          filters.push({ col, val });
+          return builder;
+        },
+        orderBy: () => builder,
+        execute: async () => {
+          return rows.filter((r) => filters.every((f) => r[f.col] === f.val));
+        },
+      };
+      return builder;
+    },
+  };
+
+  return { db, rows };
+}
+
+describe('Audit Log', () => {
+  let db: any;
+
+  beforeEach(() => {
+    const mock = createMockDb();
+    db = mock.db;
+  });
+
+  it('records audit on create with all fields as changes', async () => {
+    const result = await recordAudit(db, {
+      model: 'sales.invoice',
+      documentId: 'inv-1',
+      action: 'create',
+      userId: 'user-1',
+      before: null,
+      after: { name: 'INV-001', amount: 1000 },
+    });
+
+    expect(result).not.toBeNull();
+    expect(result!.action).toBe('create');
+    expect(result!.changes.name).toEqual({ from: null, to: 'INV-001' });
+    expect(result!.changes.amount).toEqual({ from: null, to: 1000 });
+  });
+
+  it('records audit on update with only changed fields', async () => {
+    const result = await recordAudit(db, {
+      model: 'sales.invoice',
+      documentId: 'inv-1',
+      action: 'update',
+      userId: 'user-1',
+      before: { name: 'INV-001', amount: 1000, status: 'draft' },
+      after: { name: 'INV-001', amount: 2000, status: 'draft' },
+    });
+
+    expect(result).not.toBeNull();
+    expect(result!.changes.amount).toEqual({ from: 1000, to: 2000 });
+    expect(result!.changes.name).toBeUndefined();
+  });
+
+  it('returns null for update with no actual changes', async () => {
+    const result = await recordAudit(db, {
+      model: 'sales.invoice',
+      documentId: 'inv-1',
+      action: 'update',
+      userId: 'user-1',
+      before: { name: 'INV-001', amount: 1000 },
+      after: { name: 'INV-001', amount: 1000 },
+    });
+
+    expect(result).toBeNull();
+  });
+
+  it('records audit on delete with all fields removed', async () => {
+    const result = await recordAudit(db, {
+      model: 'sales.invoice',
+      documentId: 'inv-1',
+      action: 'delete',
+      userId: 'user-1',
+      before: { name: 'INV-001', amount: 1000 },
+      after: null,
+    });
+
+    expect(result).not.toBeNull();
+    expect(result!.changes.name).toEqual({ from: 'INV-001', to: null });
+  });
+
+  it('ignores internal timestamp fields in diff', async () => {
+    const result = await recordAudit(db, {
+      model: 'sales.invoice',
+      documentId: 'inv-1',
+      action: 'update',
+      userId: 'user-1',
+      before: { name: 'INV-001', updated_at: '2024-01-01' },
+      after: { name: 'INV-001', updated_at: '2024-01-02' },
+    });
+
+    expect(result).toBeNull();
+  });
+
+  it('retrieves audit history for a document', async () => {
+    await recordAudit(db, {
+      model: 'sales.invoice',
+      documentId: 'inv-1',
+      action: 'create',
+      before: null,
+      after: { name: 'INV-001' },
+    });
+
+    await recordAudit(db, {
+      model: 'sales.invoice',
+      documentId: 'inv-1',
+      action: 'submit',
+      before: { status: 'draft' },
+      after: { status: 'submitted' },
+    });
+
+    const history = await getAuditHistory(db, 'sales.invoice', 'inv-1');
+    expect(history).toHaveLength(2);
+  });
+});

package/src/audit/index.ts

@@ -0,0 +1,3 @@
+export { getAuditTables } from './tables.js';
+export { recordAudit, getAuditHistory } from './record.js';
+export type { AuditAction, AuditChange, AuditLogRecord, AuditOptions } from './types.js';

package/src/audit/record.ts

@@ -0,0 +1,69 @@
+import type { AuditLogRecord, AuditOptions } from './types.js';
+
+const IGNORED_FIELDS = new Set(['updated_at', 'created_at', '_fixture_source', '_fixture_hash']);
+
+// Compares two snapshots of a document and returns which fields changed.
+// Null/undefined snapshots are treated as empty (all fields added or removed).
+function computeFieldChanges(
+  previousState: Record<string, unknown> | null | undefined,
+  currentState: Record<string, unknown> | null | undefined,
+): Record<string, { from: unknown; to: unknown }> {
+  const previous = previousState ?? {};
+  const current = currentState ?? {};
+  const allFields = new Set([...Object.keys(previous), ...Object.keys(current)]);
+  const changes: Record<string, { from: unknown; to: unknown }> = {};
+
+  for (const field of allFields) {
+    if (IGNORED_FIELDS.has(field)) continue;
+
+    const previousValue = previous[field] ?? null;
+    const currentValue = current[field] ?? null;
+    const hasChanged = JSON.stringify(previousValue) !== JSON.stringify(currentValue);
+
+    if (hasChanged) {
+      changes[field] = { from: previousValue, to: currentValue };
+    }
+  }
+
+  return changes;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function recordAudit(db: any, options: AuditOptions): Promise<AuditLogRecord | null> {
+  const changes = computeFieldChanges(options.before, options.after);
+
+  if (options.action === 'update' && Object.keys(changes).length === 0) {
+    return null;
+  }
+
+  const [row] = await db
+    .insertInto('rangka_audit_log')
+    .values({
+      model: options.model,
+      document_id: options.documentId,
+      action: options.action,
+      changes: JSON.stringify(changes),
+      user_id: options.userId ?? null,
+    })
+    .returningAll()
+    .execute();
+
+  return row as AuditLogRecord;
+}
+
+export async function getAuditHistory(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  db: any,
+  model: string,
+  documentId: string,
+): Promise<AuditLogRecord[]> {
+  const rows = await db
+    .selectFrom('rangka_audit_log')
+    .selectAll()
+    .where('model', '=', model)
+    .where('document_id', '=', documentId)
+    .orderBy('timestamp', 'desc')
+    .execute();
+
+  return rows as AuditLogRecord[];
+}

package/src/audit/tables.ts

@@ -0,0 +1,48 @@
+import type { TableDefinition } from '../db/types.js';
+
+export function getAuditTables(): TableDefinition[] {
+  return [buildAuditLogTable()];
+}
+
+function buildAuditLogTable(): TableDefinition {
+  return {
+    name: 'rangka_audit_log',
+    columns: [
+      {
+        name: 'id',
+        type: 'UUID',
+        nullable: false,
+        primaryKey: true,
+        defaultValue: 'gen_random_uuid()',
+      },
+      { name: 'model', type: 'TEXT', nullable: false },
+      { name: 'document_id', type: 'UUID', nullable: false },
+      { name: 'action', type: 'TEXT', nullable: false },
+      { name: 'changes', type: 'JSONB', nullable: false, defaultValue: "'{}'" },
+      { name: 'user_id', type: 'UUID', nullable: true },
+      { name: 'timestamp', type: 'TIMESTAMPTZ', nullable: false, defaultValue: 'NOW()' },
+    ],
+    foreignKeys: [],
+    checkConstraints: [
+      {
+        name: 'chk_rangka_audit_log_action',
+        column: 'action',
+        expression: "action IN ('create', 'update', 'delete', 'submit', 'cancel')",
+      },
+    ],
+    indexes: [
+      {
+        name: 'idx_rangka_audit_log_model_doc',
+        table: 'rangka_audit_log',
+        columns: ['model', 'document_id'],
+        unique: false,
+      },
+      {
+        name: 'idx_rangka_audit_log_timestamp',
+        table: 'rangka_audit_log',
+        columns: ['timestamp'],
+        unique: false,
+      },
+    ],
+  };
+}

package/src/audit/types.ts

@@ -0,0 +1,26 @@
+export type AuditAction = 'create' | 'update' | 'delete' | 'submit' | 'cancel';
+
+export interface AuditChange {
+  field: string;
+  from: unknown;
+  to: unknown;
+}
+
+export interface AuditLogRecord {
+  id: string;
+  model: string;
+  document_id: string;
+  action: AuditAction;
+  changes: Record<string, { from: unknown; to: unknown }>;
+  user_id: string | null;
+  timestamp: Date;
+}
+
+export interface AuditOptions {
+  model: string;
+  documentId: string;
+  action: AuditAction;
+  userId?: string | null;
+  before?: Record<string, unknown> | null;
+  after?: Record<string, unknown> | null;
+}

package/src/auth/__tests__/core-module.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect } from 'vitest';
+import { getCoreModels, getCoreApp } from '../core-module.js';
+import { coreSchemas } from '../core-models.js';
+
+describe('core module', () => {
+  describe('coreSchemas', () => {
+    it('defines 4 schemas: user, role, user_role, session', () => {
+      expect(coreSchemas).toHaveLength(4);
+      const names = coreSchemas.map((s) => s.name);
+      expect(names).toEqual(['user', 'role', 'user_role', 'session']);
+    });
+
+    it('user schema has expected fields', () => {
+      const user = coreSchemas.find((s) => s.name === 'user')!;
+      expect(Object.keys(user.fields)).toEqual(['email', 'password_hash', 'full_name', 'enabled']);
+    });
+
+    it('session schema has token and expiry fields', () => {
+      const session = coreSchemas.find((s) => s.name === 'session')!;
+      expect(Object.keys(session.fields)).toContain('token');
+      expect(Object.keys(session.fields)).toContain('expires_at');
+      expect(Object.keys(session.fields)).toContain('user_id');
+    });
+  });
+
+  describe('getCoreModels', () => {
+    it('returns resolved models with core qualifiedName prefix', () => {
+      const models = getCoreModels();
+      expect(models).toHaveLength(4);
+      for (const m of models) {
+        expect(m.qualifiedName).toMatch(/^core\./);
+        expect(m.app).toBe('core');
+        expect(m.module).toBe('core');
+      }
+    });
+
+    it('each model has an id field', () => {
+      const models = getCoreModels();
+      for (const m of models) {
+        const idField = m.fields.find((f) => f.name === 'id');
+        expect(idField).toBeDefined();
+      }
+    });
+  });
+
+  describe('getCoreApp', () => {
+    it('returns a valid DiscoveredApp structure', () => {
+      const app = getCoreApp();
+      expect(app.config.name).toBe('core');
+      expect(app.schemas).toHaveLength(4);
+      expect(app.extensions).toEqual([]);
+    });
+  });
+});

package/src/auth/__tests__/debug.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from 'vitest';
+import { formatDebugResult } from '../debug.js';
+import type { DebugResult } from '../debug.js';
+
+describe('debug permissions', () => {
+  describe('formatDebugResult', () => {
+    it('formats a complete debug result', () => {
+      const result: DebugResult = {
+        user: { email: 'john@test.com', id: 'u1', enabled: true },
+        roles: ['Sales User', 'Sales Manager'],
+        inheritanceChains: {
+          'Sales User': [],
+          'Sales Manager': ['Sales User'],
+        },
+        effectivePermissions: {
+          'sales.customer': { read: true, write: true, create: true, delete: true },
+          'sales.invoice': { read: true, write: true },
+        },
+        fieldRestrictions: {
+          'sales.invoice': { hidden: ['cost_price'], readOnly: ['discount_limit'] },
+        },
+      };
+
+      const output = formatDebugResult(result);
+
+      expect(output).toContain('john@test.com');
+      expect(output).toContain('Sales User, Sales Manager');
+      expect(output).toContain('Sales Manager ← Sales User');
+      expect(output).toContain('sales.customer: read, write, create, delete');
+      expect(output).toContain('cost_price');
+      expect(output).toContain('discount_limit');
+    });
+
+    it('handles user with no roles', () => {
+      const result: DebugResult = {
+        user: { email: 'nobody@test.com', id: 'u3', enabled: true },
+        roles: [],
+        inheritanceChains: {},
+        effectivePermissions: {},
+        fieldRestrictions: {},
+      };
+
+      const output = formatDebugResult(result);
+      expect(output).toContain('Roles: (none)');
+    });
+  });
+});

package/src/auth/__tests__/field-permissions.test.ts

@@ -0,0 +1,245 @@
+import { describe, it, expect } from 'vitest';
+import {
+  createFieldWriteGuard,
+  createFieldStripHook,
+  resolveFieldPermissions,
+} from '../field-permissions.js';
+import { createTestServer } from '../../__tests__/helpers.js';
+import type { ResolvedModel } from '../../schema/types.js';
+
+const mockModel: ResolvedModel = {
+  qualifiedName: 'sales.invoice',
+  app: 'sales',
+  module: 'sales',
+  name: 'invoice',
+  auditLog: false,
+  traits: [],
+  fields: [
+    { name: 'id', config: { type: 'string' } as any, provenance: { source: 'base' } },
+    { name: 'total', config: { type: 'decimal' } as any, provenance: { source: 'base' } },
+    { name: 'cost_price', config: { type: 'decimal' } as any, provenance: { source: 'base' } },
+    { name: 'discount_limit', config: { type: 'decimal' } as any, provenance: { source: 'base' } },
+  ],
+  indexes: [],
+};
+
+describe('field permissions', () => {
+  describe('resolveFieldPermissions', () => {
+    it('identifies hidden fields (read: false)', () => {
+      const result = resolveFieldPermissions(mockModel, {
+        'sales.invoice': {
+          read: true,
+          fieldPermissions: {
+            cost_price: { read: false },
+          },
+        },
+      });
+      expect(result.hidden.has('cost_price')).toBe(true);
+      expect(result.readOnly.has('cost_price')).toBe(false);
+    });
+
+    it('identifies read-only fields (write: false, read: true)', () => {
+      const result = resolveFieldPermissions(mockModel, {
+        'sales.invoice': {
+          read: true,
+          fieldPermissions: {
+            discount_limit: { read: true, write: false },
+          },
+        },
+      });
+      expect(result.readOnly.has('discount_limit')).toBe(true);
+      expect(result.hidden.has('discount_limit')).toBe(false);
+    });
+
+    it('returns empty sets when no field permissions defined', () => {
+      const result = resolveFieldPermissions(mockModel, {
+        'sales.invoice': { read: true },
+      });
+      expect(result.hidden.size).toBe(0);
+      expect(result.readOnly.size).toBe(0);
+    });
+  });
+
+  describe('field write hook', () => {
+    it('rejects writes to read-only fields with 403', async () => {
+      const server = createTestServer();
+
+      server.addHook('onRequest', async (request) => {
+        (request as any).authContext = {
+          permissions: {
+            models: {
+              'sales.invoice': {
+                read: true,
+                write: true,
+                fieldPermissions: { discount_limit: { read: true, write: false } },
+              },
+            },
+            scopes: [],
+            version: 1,
+          },
+        };
+      });
+
+      server.put('/test', {
+        preHandler: createFieldWriteGuard(mockModel),
+        handler: async () => ({ ok: true }),
+      });
+
+      const res = await server.inject({
+        method: 'PUT',
+        url: '/test',
+        payload: { discount_limit: 50, total: 100 },
+      });
+      expect(res.statusCode).toBe(403);
+      expect(res.json().error.details.fields).toContain('discount_limit');
+    });
+
+    it('allows writes when field is not in body', async () => {
+      const server = createTestServer();
+
+      server.addHook('onRequest', async (request) => {
+        (request as any).authContext = {
+          permissions: {
+            models: {
+              'sales.invoice': {
+                read: true,
+                write: true,
+                fieldPermissions: { discount_limit: { read: true, write: false } },
+              },
+            },
+            scopes: [],
+            version: 1,
+          },
+        };
+      });
+
+      server.put('/test', {
+        preHandler: createFieldWriteGuard(mockModel),
+        handler: async () => ({ ok: true }),
+      });
+
+      const res = await server.inject({
+        method: 'PUT',
+        url: '/test',
+        payload: { total: 100 },
+      });
+      expect(res.statusCode).toBe(200);
+    });
+
+    it('ignores GET requests', async () => {
+      const server = createTestServer();
+
+      server.addHook('onRequest', async (request) => {
+        (request as any).authContext = {
+          permissions: {
+            models: {
+              'sales.invoice': {
+                read: true,
+                fieldPermissions: { cost_price: { read: false } },
+              },
+            },
+            scopes: [],
+            version: 1,
+          },
+        };
+      });
+
+      server.get('/test', {
+        preHandler: createFieldWriteGuard(mockModel),
+        handler: async () => ({ ok: true }),
+      });
+
+      const res = await server.inject({ method: 'GET', url: '/test' });
+      expect(res.statusCode).toBe(200);
+    });
+  });
+
+  describe('field strip hook', () => {
+    it('strips hidden fields from response', async () => {
+      const server = createTestServer();
+
+      server.addHook('onRequest', async (request) => {
+        (request as any).authContext = {
+          permissions: {
+            models: {
+              'sales.invoice': {
+                read: true,
+                fieldPermissions: { cost_price: { read: false } },
+              },
+            },
+            scopes: [],
+            version: 1,
+          },
+        };
+      });
+
+      server.get('/test', {
+        handler: async () => ({ data: { id: '1', total: 100, cost_price: 50 } }),
+        onSend: createFieldStripHook(mockModel) as any,
+      });
+
+      const res = await server.inject({ method: 'GET', url: '/test' });
+      const body = res.json();
+      expect(body.data.cost_price).toBeUndefined();
+      expect(body.data.total).toBe(100);
+    });
+
+    it('strips hidden fields from list responses', async () => {
+      const server = createTestServer();
+
+      server.addHook('onRequest', async (request) => {
+        (request as any).authContext = {
+          permissions: {
+            models: {
+              'sales.invoice': {
+                read: true,
+                fieldPermissions: { cost_price: { read: false } },
+              },
+            },
+            scopes: [],
+            version: 1,
+          },
+        };
+      });
+
+      server.get('/test', {
+        handler: async () => ({
+          data: [
+            { id: '1', total: 100, cost_price: 50 },
+            { id: '2', total: 200, cost_price: 75 },
+          ],
+        }),
+        onSend: createFieldStripHook(mockModel) as any,
+      });
+
+      const res = await server.inject({ method: 'GET', url: '/test' });
+      const body = res.json();
+      expect(body.data[0].cost_price).toBeUndefined();
+      expect(body.data[1].cost_price).toBeUndefined();
+      expect(body.data[0].total).toBe(100);
+    });
+
+    it('passes through when no field restrictions', async () => {
+      const server = createTestServer();
+
+      server.addHook('onRequest', async (request) => {
+        (request as any).authContext = {
+          permissions: {
+            models: { 'sales.invoice': { read: true } },
+            scopes: [],
+            version: 1,
+          },
+        };
+      });
+
+      server.get('/test', {
+        handler: async () => ({ data: { id: '1', total: 100, cost_price: 50 } }),
+        onSend: createFieldStripHook(mockModel) as any,
+      });
+
+      const res = await server.inject({ method: 'GET', url: '/test' });
+      const body = res.json();
+      expect(body.data.cost_price).toBe(50);
+    });
+  });
+});