thatcher 1.0.7 → 1.0.34

package/src/lib/audit-logger-enhanced.js

@@ -1,8 +1,8 @@
-import { getDatabase, genId, now } from '@/lib/database-core';
-import { Mutex } from '@/lib/hot-reload/mutex';
+import { createLogger } from './logger.js';
+import { genId, now } from '@/lib/id-helpers';
 
-const db = getDatabase();
-const auditMutex = new Mutex('audit-logger-enhanced');
+const log = createLogger('[AuditEnhanced]');
+import { list, create, remove } from '@/lib/busybase-store';
 
 export const LOG_LEVELS = { DEBUG: 'debug', INFO: 'info', WARN: 'warn', ERROR: 'error' };
 export const OPERATION_TYPES = { CREATE: 'create', UPDATE: 'update', DELETE: 'delete', READ: 'read', AUTH: 'auth', AUTHZ: 'authz' };
@@ -10,108 +10,102 @@ export const OPERATION_TYPES = { CREATE: 'create', UPDATE: 'update', DELETE: 'de
 const MAX_LOG_SIZE = 10000;
 const MAX_STACK_DEPTH = 20;
 
+// Structured log writes go to the busybase `structured_logs` table. Fire-and-forget:
+// logging must never break the operation it records.
 export const logStructured = ({ level = LOG_LEVELS.INFO, operation, entityType, entityId, userId, action, details = {}, error = null, performanceMs = null }) => {
-  return auditMutex.runExclusive(() => {
-    const id = genId();
-    const timestamp = now();
-    const logEntry = {
-      id, timestamp, level, operation, entity_type: entityType, entity_id: entityId, user_id: userId, action,
-      details: JSON.stringify(details).substring(0, MAX_LOG_SIZE),
-      error_message: error ? String(error.message || error).substring(0, MAX_LOG_SIZE) : null,
-      error_stack: error && error.stack ? String(error.stack).split('\n').slice(0, MAX_STACK_DEPTH).join('\n') : null,
-      performance_ms: performanceMs,
-    };
-    db.prepare(`INSERT INTO structured_logs (id, timestamp, level, operation, entity_type, entity_id, user_id, action, details, error_message, error_stack, performance_ms)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(
-      id, timestamp, level, operation, entityType, entityId, userId, action, logEntry.details, logEntry.error_message, logEntry.error_stack, performanceMs
-    );
-    return id;
-  });
+  const id = genId();
+  const row = {
+    id, timestamp: now(), level, operation: operation || '', entity_type: entityType || '', entity_id: entityId || '',
+    user_id: userId || '', action: action || '',
+    details: JSON.stringify(details).substring(0, MAX_LOG_SIZE),
+    error_message: error ? String(error.message || error).substring(0, MAX_LOG_SIZE) : '',
+    error_stack: error && error.stack ? String(error.stack).split('\n').slice(0, MAX_STACK_DEPTH).join('\n') : '',
+    performance_ms: performanceMs ?? 0,
+  };
+  Promise.resolve(create('structured_logs', row)).catch(e => log.error('log failed:', { message: e?.message || String(e) }));
+  return id;
 };
 
-export const logCreate = (entityType, entityId, userId, afterState) => {
-  return logStructured({ level: LOG_LEVELS.INFO, operation: OPERATION_TYPES.CREATE, entityType, entityId, userId, action: 'create', details: { after_state: afterState } });
-};
+export const logCreate = (entityType, entityId, userId, afterState) =>
+  logStructured({ level: LOG_LEVELS.INFO, operation: OPERATION_TYPES.CREATE, entityType, entityId, userId, action: 'create', details: { after_state: afterState } });
 
-export const logUpdate = (entityType, entityId, userId, beforeState, afterState) => {
-  return logStructured({ level: LOG_LEVELS.INFO, operation: OPERATION_TYPES.UPDATE, entityType, entityId, userId, action: 'update', details: { before_state: beforeState, after_state: afterState } });
-};
+export const logUpdate = (entityType, entityId, userId, beforeState, afterState) =>
+  logStructured({ level: LOG_LEVELS.INFO, operation: OPERATION_TYPES.UPDATE, entityType, entityId, userId, action: 'update', details: { before_state: beforeState, after_state: afterState } });
 
-export const logDelete = (entityType, entityId, userId, beforeState) => {
-  return logStructured({ level: LOG_LEVELS.INFO, operation: OPERATION_TYPES.DELETE, entityType, entityId, userId, action: 'delete', details: { before_state: beforeState } });
-};
+export const logDelete = (entityType, entityId, userId, beforeState) =>
+  logStructured({ level: LOG_LEVELS.INFO, operation: OPERATION_TYPES.DELETE, entityType, entityId, userId, action: 'delete', details: { before_state: beforeState } });
 
-export const logAuthSuccess = (userId, method, metadata = {}) => {
-  return logStructured({ level: LOG_LEVELS.INFO, operation: OPERATION_TYPES.AUTH, entityType: 'auth', entityId: userId, userId, action: 'login_success', details: { method, ...metadata } });
-};
+export const logAuthSuccess = (userId, method, metadata = {}) =>
+  logStructured({ level: LOG_LEVELS.INFO, operation: OPERATION_TYPES.AUTH, entityType: 'auth', entityId: userId, userId, action: 'login_success', details: { method, ...metadata } });
 
-export const logAuthFailure = (email, reason, metadata = {}) => {
-  return logStructured({ level: LOG_LEVELS.WARN, operation: OPERATION_TYPES.AUTH, entityType: 'auth', entityId: email, userId: null, action: 'login_failure', details: { reason, ...metadata } });
-};
+export const logAuthFailure = (email, reason, metadata = {}) =>
+  logStructured({ level: LOG_LEVELS.WARN, operation: OPERATION_TYPES.AUTH, entityType: 'auth', entityId: email, userId: null, action: 'login_failure', details: { reason, ...metadata } });
 
-export const logAuthzFailure = (userId, entityType, entityId, requiredPermission, metadata = {}) => {
-  return logStructured({ level: LOG_LEVELS.WARN, operation: OPERATION_TYPES.AUTHZ, entityType, entityId, userId, action: 'access_denied', details: { required_permission: requiredPermission, ...metadata } });
-};
+export const logAuthzFailure = (userId, entityType, entityId, requiredPermission, metadata = {}) =>
+  logStructured({ level: LOG_LEVELS.WARN, operation: OPERATION_TYPES.AUTHZ, entityType, entityId, userId, action: 'access_denied', details: { required_permission: requiredPermission, ...metadata } });
 
 export const logPerformance = (operation, entityType, durationMs, userId = null, metadata = {}) => {
   const level = durationMs > 1000 ? LOG_LEVELS.WARN : LOG_LEVELS.DEBUG;
   return logStructured({ level, operation: 'performance', entityType, entityId: null, userId, action: operation, performanceMs: durationMs, details: metadata });
 };
 
-export const logError = (error, context = {}) => {
-  return logStructured({ level: LOG_LEVELS.ERROR, operation: 'error', entityType: context.entityType || 'system', entityId: context.entityId || null, userId: context.userId || null, action: context.action || 'error', error, details: context });
+export const logError = (error, context = {}) =>
+  logStructured({ level: LOG_LEVELS.ERROR, operation: 'error', entityType: context.entityType || 'system', entityId: context.entityId || null, userId: context.userId || null, action: context.action || 'error', error, details: context });
+
+const t = (r) => r.timestamp || 0;
+
+export const searchLogs = async (filters = {}, page = 1, pageSize = 100) => {
+  const where = {};
+  if (filters.level) where.level = filters.level;
+  if (filters.operation) where.operation = filters.operation;
+  if (filters.entityType) where.entity_type = filters.entityType;
+  if (filters.entityId) where.entity_id = filters.entityId;
+  if (filters.userId) where.user_id = filters.userId;
+  if (filters.action) where.action = filters.action;
+  let rows = await list('structured_logs', where);
+  if (filters.fromDate) rows = rows.filter(r => t(r) >= filters.fromDate);
+  if (filters.toDate) rows = rows.filter(r => t(r) <= filters.toDate);
+  if (filters.searchText) {
+    const q = String(filters.searchText).toLowerCase();
+    rows = rows.filter(r => [r.details, r.error_message, r.action].some(v => String(v ?? '').toLowerCase().includes(q)));
+  }
+  rows.sort((a, b) => t(b) - t(a));
+  const total = rows.length;
+  const items = rows.slice((page - 1) * pageSize, page * pageSize)
+    .map(i => ({ ...i, details: i.details ? (() => { try { return JSON.parse(i.details); } catch { return null; } })() : null }));
+  return { items, pagination: { page, pageSize, total, totalPages: Math.ceil(total / pageSize) } };
 };
 
-export const searchLogs = (filters = {}, page = 1, pageSize = 100) => {
-  const wc = [], params = [];
-  if (filters.level) { wc.push('level = ?'); params.push(filters.level); }
-  if (filters.operation) { wc.push('operation = ?'); params.push(filters.operation); }
-  if (filters.entityType) { wc.push('entity_type = ?'); params.push(filters.entityType); }
-  if (filters.entityId) { wc.push('entity_id = ?'); params.push(filters.entityId); }
-  if (filters.userId) { wc.push('user_id = ?'); params.push(filters.userId); }
-  if (filters.action) { wc.push('action = ?'); params.push(filters.action); }
-  if (filters.fromDate) { wc.push('timestamp >= ?'); params.push(filters.fromDate); }
-  if (filters.toDate) { wc.push('timestamp <= ?'); params.push(filters.toDate); }
-  if (filters.searchText) { wc.push('(details LIKE ? OR error_message LIKE ? OR action LIKE ?)'); const escaped = filters.searchText.replace(/[%_]/g, c => '\\' + c); const pat = `%${escaped}%`; params.push(pat, pat, pat); }
-  const where = wc.length ? 'WHERE ' + wc.join(' AND ') : '';
-  const { count: total } = db.prepare(`SELECT COUNT(*) as count FROM structured_logs ${where}`).get(...params);
-  const offset = (page - 1) * pageSize;
-  const items = db.prepare(`SELECT * FROM structured_logs ${where} ORDER BY timestamp DESC LIMIT ? OFFSET ?`).all(...params, pageSize, offset);
-  return { items: items.map(i => ({ ...i, details: i.details ? JSON.parse(i.details) : null })), pagination: { page, pageSize, total, totalPages: Math.ceil(total / pageSize) } };
+const groupCount = (rows, field) => {
+  const c = {};
+  for (const r of rows) { const k = r[field]; c[k] = (c[k] || 0) + 1; }
+  return Object.entries(c).map(([k, count]) => ({ [field]: k, count })).sort((a, b) => b.count - a.count);
 };
 
-export const getLogStats = (fromDate, toDate) => {
-  const byLevel = db.prepare('SELECT level, COUNT(*) as count FROM structured_logs WHERE timestamp >= ? AND timestamp <= ? GROUP BY level').all(fromDate, toDate);
-  const byOperation = db.prepare('SELECT operation, COUNT(*) as count FROM structured_logs WHERE timestamp >= ? AND timestamp <= ? GROUP BY operation ORDER BY count DESC').all(fromDate, toDate);
-  const byEntity = db.prepare('SELECT entity_type, COUNT(*) as count FROM structured_logs WHERE timestamp >= ? AND timestamp <= ? GROUP BY entity_type ORDER BY count DESC LIMIT 20').all(fromDate, toDate);
-  const errorRate = db.prepare('SELECT COUNT(*) as total, SUM(CASE WHEN level = ? THEN 1 ELSE 0 END) as errors FROM structured_logs WHERE timestamp >= ? AND timestamp <= ?').get(LOG_LEVELS.ERROR, fromDate, toDate);
-  const avgPerf = db.prepare('SELECT AVG(performance_ms) as avg, MAX(performance_ms) as max FROM structured_logs WHERE timestamp >= ? AND timestamp <= ? AND performance_ms IS NOT NULL').get(fromDate, toDate);
-  return { byLevel, byOperation, byEntity, errorRate: errorRate.total > 0 ? errorRate.errors / errorRate.total : 0, avgPerformanceMs: avgPerf.avg, maxPerformanceMs: avgPerf.max };
+export const getLogStats = async (fromDate, toDate) => {
+  const rows = (await list('structured_logs', {})).filter(r => t(r) >= fromDate && t(r) <= toDate);
+  const errors = rows.filter(r => r.level === LOG_LEVELS.ERROR).length;
+  const perf = rows.map(r => r.performance_ms).filter(v => typeof v === 'number' && v > 0);
+  return {
+    byLevel: groupCount(rows, 'level'),
+    byOperation: groupCount(rows, 'operation'),
+    byEntity: groupCount(rows, 'entity_type').slice(0, 20),
+    errorRate: rows.length > 0 ? errors / rows.length : 0,
+    avgPerformanceMs: perf.length ? perf.reduce((a, b) => a + b, 0) / perf.length : null,
+    maxPerformanceMs: perf.length ? Math.max(...perf) : null,
+  };
 };
 
-export const rotateLogsOlderThan = (daysOld = 90) => {
-  const cutoffTimestamp = now() - (daysOld * 24 * 60 * 60);
+export const rotateLogsOlderThan = async (daysOld = 90) => {
+  const cutoff = now() - (daysOld * 24 * 60 * 60);
   const archiveId = genId();
-  const archived = db.prepare('SELECT * FROM structured_logs WHERE timestamp < ?').all(cutoffTimestamp);
+  const archived = (await list('structured_logs', {})).filter(r => t(r) < cutoff);
   if (archived.length > 0) {
-    db.prepare('INSERT INTO archived_logs (archive_id, archived_at, log_data) VALUES (?, ?, ?)').run(archiveId, now(), JSON.stringify(archived));
-    db.prepare('DELETE FROM structured_logs WHERE timestamp < ?').run(cutoffTimestamp);
+    await create('archived_logs', { archive_id: archiveId, archived_at: now(), log_data: JSON.stringify(archived) });
+    for (const r of archived) await remove('structured_logs', r.id);
   }
   return { archived: archived.length, archiveId };
 };
 
-export const ensureTables = () => {
-  db.exec(`CREATE TABLE IF NOT EXISTS structured_logs (
-    id TEXT PRIMARY KEY, timestamp INTEGER NOT NULL, level TEXT NOT NULL, operation TEXT, entity_type TEXT,
-    entity_id TEXT, user_id TEXT, action TEXT, details TEXT, error_message TEXT, error_stack TEXT, performance_ms REAL
-  )`);
-  db.exec(`CREATE INDEX IF NOT EXISTS idx_structured_logs_timestamp ON structured_logs(timestamp)`);
-  db.exec(`CREATE INDEX IF NOT EXISTS idx_structured_logs_level ON structured_logs(level)`);
-  db.exec(`CREATE INDEX IF NOT EXISTS idx_structured_logs_entity ON structured_logs(entity_type, entity_id)`);
-  db.exec(`CREATE INDEX IF NOT EXISTS idx_structured_logs_user ON structured_logs(user_id)`);
-  db.exec(`CREATE TABLE IF NOT EXISTS archived_logs (
-    archive_id TEXT PRIMARY KEY, archived_at INTEGER NOT NULL, log_data TEXT NOT NULL
-  )`);
-};
-
-ensureTables();
+// busybase is schemaless — tables are created lazily on first insert.
+export const ensureTables = () => {};

package/src/lib/auth-middleware.js

@@ -1,7 +1,4 @@
-/**
- * Auth Middleware - Authentication and authorization utilities
- * Adapted from moonlanding/src/lib/auth-middleware.js
- */
+// Adapted from moonlanding/src/lib/auth-middleware.js
 
 import { getUser, getLucia } from '../engine.server.js';
 import { getSpec } from '../config/spec-helpers.js';
@@ -18,11 +15,6 @@ const actionMap = {
   delete: 'delete',
 };
 
-/**
- * Get session token from request headers
- * @param {object} req - HTTP request
- * @returns {string|null}
- */
 export function getSessionToken(req) {
   const cookieHeader = req?.headers?.cookie || '';
   if (!cookieHeader) return null;
@@ -35,22 +27,12 @@ export function getSessionToken(req) {
   return value ? decodeURIComponent(value.trim()) : null;
 }
 
-/**
- * Require authentication (throws if not authenticated)
- * @returns {Promise<object>} User object
- */
 export async function requireAuth() {
   const user = await getUser();
   if (!user) throw UnauthorizedError('Authentication required');
   return user;
 }
 
-/**
- * Require permission for action on spec
- * @param {object} user
- * @param {object} spec
- * @param {string} action
- */
 export async function requirePermission(user, spec, action) {
   const mapped = actionMap[action] || action;
   if (!(await can(user, spec, mapped))) {
@@ -58,12 +40,6 @@ export async function requirePermission(user, spec, action) {
   }
 }
 
-/**
- * Create authenticated handler wrapper
- * @param {Function} handler
- * @param {string} action
- * @returns {Function}
- */
 export function withAuth(handler, action = 'view') {
   return async (request, context) => {
     const user = await requireAuth();
@@ -74,13 +50,6 @@ export function withAuth(handler, action = 'view') {
   };
 }
 
-/**
- * Page auth (for HTML page rendering)
- * @param {string} entityName
- * @param {string} action
- * @param {object} options
- * @returns {Promise<{user, spec}>}
- */
 export async function withPageAuth(entityName, action = 'view', options = {}) {
   const user = await getUser();
   if (!user) throw UnauthorizedError('Not authenticated');

package/src/lib/auth-route-helpers.js

@@ -79,5 +79,10 @@ export function validateOAuthState(code, state, storedState, storedCodeVerifier)
   if (!storedState || !storedCodeVerifier) {
     return { valid: false, error: 'state_not_found' };
   }
+  // The submitted state must equal the stored state, or an attacker can forge an
+  // OAuth callback (CSRF). Existence alone is not enough -- compare the values.
+  if (state !== storedState) {
+    return { valid: false, error: 'state_mismatch' };
+  }
   return { valid: true };
 }

package/src/lib/busybase-adapter.js

@@ -1,8 +1,3 @@
-/**
- * BusyBase Database Adapter - Supabase-compatible database layer for Thatcher
- * Supports embedded mode (in-process) and remote mode (HTTP client)
- */
-
 import { createLogger } from './logger.js';
 import { hookEngine } from './hook-engine.js';
 

package/src/lib/busybase-audit-reads.js

@@ -0,0 +1,142 @@
+/*
+ * BusyBase-backed audit READ API — replaces the SQLite audit-logger read functions.
+ * busybase has no SQL GROUP BY / aggregates, so stats are computed in JS over the
+ * audit_logs and permission_audit tables.
+ */
+
+import { list, create } from '@/lib/busybase-store.js';
+import { genId, now } from '@/lib/id-helpers.js';
+
+const parseJson = (val) => { try { return val ? JSON.parse(val) : null; } catch { return null; } };
+
+const parsePermRow = (row) => row ? {
+  ...row,
+  old_permissions: parseJson(row.old_permissions),
+  new_permissions: parseJson(row.new_permissions),
+  metadata: parseJson(row.metadata),
+  before_state: parseJson(row.before_state),
+  after_state: parseJson(row.after_state),
+} : null;
+
+function ts(r) { return r.timestamp || r.created_at || 0; }
+
+export async function getAuditHistory(filters = {}, page = 1, pageSize = 50) {
+  const where = {};
+  if (filters.entityType) where.entity_type = filters.entityType;
+  if (filters.entityId) where.entity_id = filters.entityId;
+  if (filters.userId) where.user_id = filters.userId;
+  if (filters.action) where.action = filters.action;
+  let rows = await list('audit_logs', where);
+  if (filters.fromDate) rows = rows.filter(r => ts(r) >= filters.fromDate);
+  if (filters.toDate) rows = rows.filter(r => ts(r) <= filters.toDate);
+  rows.sort((a, b) => ts(b) - ts(a));
+  const total = rows.length;
+  const items = rows.slice((page - 1) * pageSize, page * pageSize).map(i => ({
+    id: i.id, entityType: i.entity_type, entityId: i.entity_id, action: i.action,
+    userId: i.user_id, beforeState: parseJson(i.before_state), afterState: parseJson(i.after_state), createdAt: ts(i),
+  }));
+  return { items, pagination: { page, pageSize, total, totalPages: Math.ceil(total / pageSize) } };
+}
+
+export async function getEntityAuditTrail(entityType, entityId) {
+  const rows = (await list('audit_logs', { entity_type: entityType, entity_id: entityId })).sort((a, b) => ts(b) - ts(a));
+  return rows.map(i => ({ id: i.id, action: i.action, userId: i.user_id, beforeState: parseJson(i.before_state), afterState: parseJson(i.after_state), createdAt: ts(i) }));
+}
+
+async function rangeStats(field, fromDate, toDate) {
+  const rows = (await list('audit_logs', {})).filter(r => ts(r) >= fromDate && ts(r) <= toDate);
+  const counts = {};
+  for (const r of rows) { const k = r[field]; counts[k] = (counts[k] || 0) + 1; }
+  return Object.entries(counts).map(([k, count]) => ({ [field]: k, count })).sort((a, b) => b.count - a.count);
+}
+export const getActionStats = (fromDate, toDate) => rangeStats('action', fromDate, toDate);
+export const getUserStats = (fromDate, toDate) => rangeStats('user_id', fromDate, toDate);
+
+export async function getPermissionAuditTrail({ entityType, entityId, userId, affectedUserId, limit = 100, offset = 0 }) {
+  const where = {};
+  if (entityType) where.entity_type = entityType;
+  if (entityId) where.entity_id = entityId;
+  if (userId) where.user_id = userId;
+  if (affectedUserId) where.affected_user_id = affectedUserId;
+  const rows = (await list('permission_audit', where)).sort((a, b) => ts(b) - ts(a));
+  return rows.slice(offset, offset + limit).map(parsePermRow);
+}
+
+export async function getPermissionAuditById(auditId) {
+  const rows = await list('permission_audit', { id: auditId });
+  return parsePermRow(rows[0] || null);
+}
+
+export async function getPermissionAuditStats() {
+  const rows = await list('permission_audit', {});
+  const users = new Set(rows.map(r => r.user_id).filter(Boolean));
+  const types = new Set(rows.map(r => r.entity_type).filter(Boolean));
+  const times = rows.map(ts).filter(Boolean);
+  return {
+    total_audits: rows.length,
+    unique_users: users.size,
+    entity_types: types.size,
+    earliest_change: times.length ? Math.min(...times) : null,
+    latest_change: times.length ? Math.max(...times) : null,
+  };
+}
+
+export async function getPermissionAuditBreakdown(field) {
+  const rows = await list('permission_audit', {});
+  const counts = {};
+  for (const r of rows) { const k = r[field]; counts[k] = (counts[k] || 0) + 1; }
+  return Object.entries(counts).map(([k, count]) => ({ [field]: k, count })).sort((a, b) => b.count - a.count);
+}
+
+export async function getPermissionAuditByDateRange(startDate, endDate, limit = 100) {
+  const rows = (await list('permission_audit', {})).filter(r => ts(r) >= startDate && ts(r) <= endDate).sort((a, b) => ts(b) - ts(a));
+  return rows.slice(0, limit).map(parsePermRow);
+}
+
+export async function searchPermissionAudit(searchTerm, limit = 100) {
+  const q = String(searchTerm || '').toLowerCase();
+  const rows = (await list('permission_audit', {}))
+    .filter(r => [r.reason, r.entity_type, r.entity_id].some(v => String(v ?? '').toLowerCase().includes(q)))
+    .sort((a, b) => ts(b) - ts(a));
+  return rows.slice(0, limit).map(parsePermRow);
+}
+
+export async function exportPermissionAuditCSV(filters = {}) {
+  const rows = await getPermissionAuditTrail({ ...filters, limit: 100000, offset: 0 });
+  const cols = ['id', 'user_id', 'entity_type', 'entity_id', 'action', 'reason', 'reason_code', 'timestamp', 'affected_user_id'];
+  const esc = (v) => `"${String(v ?? '').replace(/"/g, '""')}"`;
+  const header = cols.join(',');
+  const lines = rows.map(r => cols.map(c => esc(r[c])).join(','));
+  return [header, ...lines].join('\n');
+}
+
+export async function logPermissionChange({
+  userId, entityType, entityId, action, oldPermissions = null, newPermissions = null,
+  reason = null, reasonCode = 'other', affectedUserId = null, ipAddress = null, sessionId = null, metadata = null,
+}) {
+  if (!userId || !entityType || !entityId || !action) throw new Error('Missing required audit fields');
+  const auditId = genId();
+  const timestamp = now();
+  await create('permission_audit', {
+    id: auditId, user_id: userId, entity_type: entityType, entity_id: entityId, action,
+    old_permissions: oldPermissions ? JSON.stringify(oldPermissions) : '',
+    new_permissions: newPermissions ? JSON.stringify(newPermissions) : '',
+    reason: reason || '', reason_code: reasonCode, timestamp, ip_address: ipAddress || '',
+    session_id: sessionId || '', affected_user_id: affectedUserId || '',
+    metadata: metadata ? JSON.stringify(metadata) : '', created_at: timestamp, updated_at: timestamp,
+    created_by: userId, updated_by: userId,
+  });
+  return auditId;
+}
+
+// Pure diff (no DB) — kept here so consumers import everything audit-read from one place.
+export function getPermissionDiff(oldPerms, newPerms) {
+  const o = oldPerms || {}, n = newPerms || {};
+  const keys = [...new Set([...Object.keys(o), ...Object.keys(n)])];
+  const changes = [];
+  for (const k of keys) {
+    const before = o[k], after = n[k];
+    if (JSON.stringify(before) !== JSON.stringify(after)) changes.push({ field: k, before, after });
+  }
+  return changes;
+}

package/src/lib/busybase-audit.js

@@ -0,0 +1,41 @@
+/*
+ * BusyBase-backed audit log — async replacement for the better-sqlite3 audit-logger's
+ * logAction(). Writes an audit_logs document through the busybase store.
+ *
+ * Audit logging must never break the request it records, so logAction is fire-and-
+ * forget: it returns immediately and swallows/logs write errors rather than throwing.
+ */
+
+import { createLogger } from './logger.js';
+import { genId, now } from './id-helpers.js';
+
+const log = createLogger('[BusyBaseAudit]');
+
+let _client = null;
+
+// Wire the busybase client (same instance as the store). Called at bootstrap.
+export function setBusyBaseClient(client) {
+  _client = client;
+}
+
+export function logAction(entityType, entityId, action, userId, beforeState, afterState) {
+  const id = genId();
+  const timestamp = now();
+  // LanceDB infers column types from values and cannot type an all-null column on the
+  // first insert, so use '' (typed string) instead of null for optional text columns.
+  const row = {
+    id,
+    entity_type: entityType,
+    entity_id: String(entityId),
+    action,
+    user_id: userId || '',
+    before_state: beforeState ? JSON.stringify(beforeState) : '',
+    after_state: afterState ? JSON.stringify(afterState) : '',
+    created_at: timestamp,
+  };
+  if (_client) {
+    Promise.resolve(_client.from('audit_logs').insert(row))
+      .catch(err => log.error('logAction failed:', { message: err?.message || String(err) }));
+  }
+  return { id, timestamp };
+}

package/src/lib/busybase-lucia-adapter.js

@@ -0,0 +1,72 @@
+/*
+ * Lucia v3 session adapter backed by busybase (replaces @lucia-auth/adapter-sqlite's
+ * BetterSqlite3Adapter). Sessions live in the `sessions` table, users in `users`.
+ *
+ * Lucia stores a session row as { id, user_id, expires_at, ...attributes } and a user
+ * row as { id, ...attributes }. Lucia expects expires_at as a JS Date in the objects it
+ * receives back; busybase stores it as an epoch-ms number, so we convert at the boundary.
+ */
+
+import { list, get, create, update, remove } from '@/lib/busybase-store.js';
+
+const SESSION = 'sessions';
+const USER = 'users';
+
+function rowToSession(row) {
+  if (!row) return null;
+  const { id, user_id, expires_at, ...rest } = row;
+  return { id, userId: user_id, expiresAt: new Date(Number(expires_at)), attributes: rest };
+}
+
+function rowToUser(row) {
+  if (!row) return null;
+  const { id, ...attributes } = row;
+  return { id, attributes };
+}
+
+export class BusyBaseLuciaAdapter {
+  async getSessionAndUser(sessionId) {
+    const sRow = await get(SESSION, sessionId);
+    if (!sRow) return [null, null];
+    const session = rowToSession(sRow);
+    const uRow = await get(USER, session.userId);
+    return [session, rowToUser(uRow)];
+  }
+
+  async getUserSessions(userId) {
+    const rows = await list(SESSION, { user_id: userId });
+    return rows.map(rowToSession);
+  }
+
+  async setSession(session) {
+    await create(SESSION, {
+      id: session.id,
+      user_id: session.userId,
+      expires_at: session.expiresAt instanceof Date ? session.expiresAt.getTime() : Number(session.expiresAt),
+      ...session.attributes,
+    });
+  }
+
+  async updateSessionExpiration(sessionId, expiresAt) {
+    await update(SESSION, sessionId, {
+      expires_at: expiresAt instanceof Date ? expiresAt.getTime() : Number(expiresAt),
+    });
+  }
+
+  async deleteSession(sessionId) {
+    await remove(SESSION, sessionId);
+  }
+
+  async deleteUserSessions(userId) {
+    const rows = await list(SESSION, { user_id: userId });
+    for (const r of rows) await remove(SESSION, r.id);
+  }
+
+  async deleteExpiredSessions() {
+    const now = Date.now();
+    const rows = await list(SESSION, {});
+    for (const r of rows) {
+      if (Number(r.expires_at) <= now) await remove(SESSION, r.id);
+    }
+  }
+}