thatcher 1.0.4

package/src/adapters/google-drive.js

@@ -0,0 +1,209 @@
+/**
+ * Google Drive Adapter - File storage and manipulation
+ * Upload, download, copy, export to PDF
+ */
+
+import { google } from 'googleapis';
+import fs from 'fs';
+import path from 'path';
+import { getJWTClient, getOAuth2Client } from './google-auth.js';
+import { buildConfig } from '../config/env.js';
+
+const DRIVE_SCOPES = ['https://www.googleapis.com/auth/drive'];
+
+/**
+ * Get authenticated Drive API client
+ * @param {object} [user] - User with oauth_token, or null for service account
+ * @returns {object}
+ */
+export function getDriveClient(user = null) {
+  let client;
+
+  if (user?.oauth_token) {
+    // User-delegated access
+    client = getOAuth2Client();
+    client.setCredentials({ access_token: user.oauth_token });
+  } else {
+    // Service account (app-wide)
+    client = getJWTClient();
+  }
+
+  if (!client) throw new Error('Google Drive not configured');
+
+  return google.drive({ version: 'v3', auth: client });
+}
+
+/**
+ * Upload a file to Google Drive
+ * @param {string} filePath - Local file path
+ * @param {string} name - File name in Drive
+ * @param {object} [options] - { folderId, mimeType, parents }
+ * @param {object} [user] - Optional user context
+ * @returns {object} File metadata
+ */
+export async function uploadFile(filePath, name, options = {}, user = null) {
+  const drive = getDriveClient(user);
+  const absPath = path.resolve(filePath);
+  const fileSize = fs.statSync(absPath).size;
+
+  const res = await drive.files.create({
+    requestBody: {
+      name,
+      parents: options.parents || [options.folderId || getDefaultFolder()],
+      mimeType: options.mimeType || 'application/octet-stream',
+    },
+    media: {
+      mimeType: options.mimeType || 'application/octet-stream',
+      body: fs.createReadStream(absPath),
+    },
+  });
+
+  return res.data;
+}
+
+/**
+ * Download file from Drive
+ * @param {string} fileId
+ * @param {string} [destPath] - If provided, write to file; else return buffer
+ * @param {object} [user] - Optional user context
+ * @returns {Buffer|string}
+ */
+export async function downloadFile(fileId, destPath = null, user = null) {
+  const drive = getDriveClient(user);
+  const res = await drive.files.get(
+    { fileId, alt: 'media' },
+    { responseType: destPath ? 'stream' : 'arraybuffer' }
+  );
+
+  if (destPath) {
+    const writeStream = fs.createWriteStream(destPath);
+    res.data
+      .on('end', () => {})
+      .on('error', err => { throw err; })
+      .pipe(writeStream);
+    return destPath;
+  }
+
+  return Buffer.from(res.data);
+}
+
+/**
+ * Create a copy of a file in Drive
+ * @param {string} fileId
+ * @param {string} [newName]
+ * @param {string} [folderId]
+ * @param {object} [user]
+ * @returns {object}
+ */
+export async function copyFile(fileId, newName = null, folderId = null, user = null) {
+  const drive = getDriveClient(user);
+  const res = await drive.files.copy({
+    requestBody: {
+      name: newName,
+      parents: folderId ? [folderId] : undefined,
+    },
+    fileId,
+  });
+  return res.data;
+}
+
+/**
+ * Export Google Doc to PDF
+ * @param {string} fileId
+ * @param {object} [user]
+ * @returns {Buffer}
+ */
+export async function exportToPdf(fileId, user = null) {
+  const drive = getDriveClient(user);
+  const res = await drive.files.export(
+    { fileId, mimeType: 'application/pdf' },
+    { responseType: 'arraybuffer' }
+  );
+  return Buffer.from(res.data);
+}
+
+/**
+ * List files in folder
+ * @param {string} [folderId]
+ * @param {object} [query]
+ * @param {object} [user]
+ * @returns {Array}
+ */
+export async function listFiles(folderId = null, query = {}, user = null) {
+  const drive = getDriveClient(user);
+  const qParts = [];
+
+  if (folderId) {
+    qParts.push(`'${folderId}' in parents`);
+  }
+  if (query.trashed === false) {
+    qParts.push("trashed = false");
+  }
+  if (query.mimeType) {
+    qParts.push(`mimeType = '${query.mimeType}'`);
+  }
+  if (query.name) {
+    qParts.push(`name = '${query.name}'`);
+  }
+
+  const res = await drive.files.list({
+    q: qParts.length ? qParts.join(' AND ') : undefined,
+    fields: 'files(id, name, mimeType, size, modifiedTime)',
+    pageSize: 100,
+  });
+
+  return res.data.files || [];
+}
+
+/**
+ * Delete file
+ * @param {string} fileId
+ * @param {object} [user]
+ */
+export async function deleteFile(fileId, user = null) {
+  const drive = getDriveClient(user);
+  await drive.files.delete({ fileId });
+}
+
+/**
+ * Get default root folder from config
+ * @returns {string}
+ */
+function getDefaultFolder() {
+  const cfg = buildConfig();
+  return cfg.drive.rootFolderId || 'root';
+}
+
+/**
+ * Ensure folder exists, create if not
+ * @param {string} name
+ * @param {string} [parentId]
+ * @param {object} [user]
+ * @returns {string} folderId
+ */
+export async function ensureFolder(name, parentId = null, user = null) {
+  const drive = getDriveClient(user);
+  const queryParts = [`name = '${name}'`, "mimeType = 'application/vnd.google-apps.folder'"];
+  if (parentId) queryParts.push(`'${parentId}' in parents`);
+
+  const res = await drive.files.list({
+    q: queryParts.join(' AND '),
+    fields: 'files(id)',
+    pageSize: 1,
+  });
+
+  if (res.data.files.length > 0) {
+    return res.data.files[0].id;
+  }
+
+  // Create folder
+  const createRes = await drive.files.create({
+    requestBody: {
+      name,
+      mimeType: 'application/vnd.google-apps.folder',
+      parents: parentId ? [parentId] : undefined,
+    },
+  });
+
+  return createRes.data.id;
+}

package/src/app/api/[entity]/[[...path]]/route.js

@@ -0,0 +1,33 @@
+import { createCrudHandlers } from '@/lib/crud-factory';
+import { setCurrentRequest } from '@/engine.server';
+
+function wrapHandler(method) {
+  return async (request, context) => {
+    setCurrentRequest(request);
+    const params = await context.params;
+    const pathArray = params.path || [];
+    const entityName = params.entity;
+    const parentEntity = params.parentEntity || null;
+    const parentId = params.parentId || null;
+
+    const enhancedContext = {
+      ...context,
+      params: {
+        entity: entityName,
+        id: pathArray[0] || null,
+        childKey: pathArray[1] || null,
+        parentEntity,
+        parentId,
+      },
+    };
+
+    const handlers = createCrudHandlers(entityName);
+    return handlers(request, enhancedContext);
+  };
+}
+
+export const GET = wrapHandler('GET');
+export const POST = wrapHandler('POST');
+export const PUT = wrapHandler('PUT');
+export const PATCH = wrapHandler('PATCH');
+export const DELETE = wrapHandler('DELETE');

package/src/app/api/audit/dashboard/route.js

@@ -0,0 +1,77 @@
+import { NextResponse } from '@/lib/next-polyfills';
+import { getUser, setCurrentRequest } from '@/engine.server';
+import {
+  getPermissionAuditTrail, getPermissionAuditStats, getPermissionAuditBreakdown,
+  getPermissionAuditByDateRange, searchPermissionAudit, getPermissionDiff,
+} from '@/lib/audit-logger';
+
+export async function GET(request) {
+  setCurrentRequest(request);
+  try {
+    const user = await getUser();
+    if (!user || (user.role !== 'partner' && user.role !== 'manager')) {
+      return NextResponse.json({ error: 'Permission denied' }, { status: 403 });
+    }
+
+    const { searchParams } = new URL(request.url);
+    const view = searchParams.get('view') || 'summary';
+    const days = parseInt(searchParams.get('days') || '30', 10);
+    const entityType = searchParams.get('entity_type');
+    const entityId = searchParams.get('entity_id');
+    const userId = searchParams.get('user_id');
+    const searchTerm = searchParams.get('search');
+    const limit = parseInt(searchParams.get('limit') || '100', 10);
+
+    const nowTs = Math.floor(Date.now() / 1000);
+    const startTs = nowTs - (days * 86400);
+
+    let data;
+    switch (view) {
+      case 'summary': {
+        const stats = getPermissionAuditStats();
+        const actionBreakdown = getPermissionAuditBreakdown('action');
+        const reasonBreakdown = getPermissionAuditBreakdown('reason_code');
+        const changes = getPermissionAuditByDateRange(startTs, nowTs, limit);
+        data = {
+          period_days: days,
+          total_changes: changes.length,
+          stats: { ...stats, unique_users: stats.unique_users, entity_types: stats.entity_types },
+          by_action: actionBreakdown.reduce((a, i) => { a[i.action] = i.count; return a; }, {}),
+          by_reason: reasonBreakdown.reduce((a, i) => { a[i.reason_code] = i.count; return a; }, {}),
+        };
+        break;
+      }
+      case 'recent':
+        data = { period: `Last ${days} days`, changes: getPermissionAuditByDateRange(startTs, nowTs, limit) };
+        break;
+      case 'user':
+        if (!userId) return NextResponse.json({ error: 'user_id required' }, { status: 400 });
+        data = { user_id: userId, changes: getPermissionAuditTrail({ userId, limit }) };
+        break;
+      case 'entity':
+        if (!entityType || !entityId) return NextResponse.json({ error: 'entity_type and entity_id required' }, { status: 400 });
+        data = {
+          entity_type: entityType, entity_id: entityId,
+          timeline: getPermissionAuditTrail({ entityType, entityId, limit }).map(c => ({
+            ...c, timestamp_iso: new Date(c.timestamp * 1000).toISOString(),
+            diff: c.old_permissions && c.new_permissions ? getPermissionDiff(c.old_permissions, c.new_permissions) : null,
+          })),
+        };
+        break;
+      case 'search':
+        if (!searchTerm) return NextResponse.json({ error: 'search parameter required' }, { status: 400 });
+        data = { search_term: searchTerm, results: searchPermissionAudit(searchTerm, limit) };
+        break;
+      case 'roles':
+        data = { changes: getPermissionAuditTrail({ limit }).filter(c => c.action === 'role_change') };
+        break;
+      default:
+        return NextResponse.json({ error: `Unknown view: ${view}` }, { status: 400 });
+    }
+
+    return NextResponse.json({ success: true, view, data });
+  } catch (error) {
+    console.error('[AuditDashboardAPI] GET error:', error);
+    return NextResponse.json({ error: 'Failed to retrieve audit dashboard data', details: error.message }, { status: 500 });
+  }
+}

package/src/app/api/audit/logs/route.js

@@ -0,0 +1,46 @@
+import { NextResponse } from '@/lib/next-polyfills';
+import { requireAuth } from '@/lib/auth-middleware';
+import { searchLogs, getLogStats, rotateLogsOlderThan } from '@/lib/audit-logger-enhanced';
+import { withErrorHandler } from '@/lib/with-error-handler';
+
+export const GET = withErrorHandler(async (request) => {
+  const user = await requireAuth();
+  if (user.role !== 'admin' && user.role !== 'partner') {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 403 });
+  }
+
+  const url = new URL(request.url);
+  const filters = {
+    level: url.searchParams.get('level'),
+    operation: url.searchParams.get('operation'),
+    entityType: url.searchParams.get('entityType'),
+    entityId: url.searchParams.get('entityId'),
+    userId: url.searchParams.get('userId'),
+    action: url.searchParams.get('action'),
+    searchText: url.searchParams.get('q'),
+    fromDate: url.searchParams.get('from') ? parseInt(url.searchParams.get('from')) : Math.floor(Date.now() / 1000) - (7 * 24 * 60 * 60),
+    toDate: url.searchParams.get('to') ? parseInt(url.searchParams.get('to')) : Math.floor(Date.now() / 1000),
+  };
+
+  const page = parseInt(url.searchParams.get('page') || '1');
+  const pageSize = parseInt(url.searchParams.get('pageSize') || '100');
+
+  const result = searchLogs(filters, page, pageSize);
+  return NextResponse.json(result);
+});
+
+export const POST = withErrorHandler(async (request) => {
+  const user = await requireAuth();
+  if (user.role !== 'admin') {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 403 });
+  }
+
+  const body = await request.json();
+  if (body.action === 'rotate') {
+    const daysOld = body.daysOld || 90;
+    const result = rotateLogsOlderThan(daysOld);
+    return NextResponse.json({ success: true, archived: result.archived, archiveId: result.archiveId });
+  }
+
+  return NextResponse.json({ error: 'Invalid action' }, { status: 400 });
+});

package/src/app/api/audit/permissions/[id]/route.js

@@ -0,0 +1,37 @@
+import { NextResponse, cookies } from '@/lib/next-polyfills';
+import { lucia } from '@/engine.server';
+import { getPermissionAuditById, getPermissionDiff } from '@/lib/audit-logger';
+
+async function getUser() {
+  const sessionId = (await cookies()).get(lucia.sessionCookieName)?.value ?? null;
+  if (!sessionId) return null;
+  const { user } = await lucia.validateSession(sessionId);
+  return user;
+}
+
+export async function GET(request, context) {
+  try {
+    const user = await getUser();
+    if (!user) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+
+    const params = await context.params;
+    const auditId = params.id;
+    if (!auditId) return NextResponse.json({ error: 'Audit ID is required' }, { status: 400 });
+
+    const audit = getPermissionAuditById(auditId);
+    if (!audit) return NextResponse.json({ error: 'Audit record not found' }, { status: 404 });
+
+    if (user.role === 'clerk' && audit.user_id !== user.id) return NextResponse.json({ error: 'Permission denied' }, { status: 403 });
+    if (user.role === 'client_admin' || user.role === 'client_user') return NextResponse.json({ error: 'Permission denied' }, { status: 403 });
+
+    const diff = audit.old_permissions && audit.new_permissions ? getPermissionDiff(audit.old_permissions, audit.new_permissions) : null;
+
+    return NextResponse.json({
+      success: true,
+      data: { ...audit, timestamp_iso: new Date(audit.timestamp * 1000).toISOString(), diff },
+    });
+  } catch (error) {
+    console.error('[AuditDetailAPI] GET error:', error);
+    return NextResponse.json({ error: 'Failed to retrieve audit record', details: error.message }, { status: 500 });
+  }
+}

package/src/app/api/audit/permissions/route.js

@@ -0,0 +1,93 @@
+import { NextResponse } from '@/lib/next-polyfills';
+import { lucia } from '@/engine.server';
+import { cookies } from '@/lib/next-polyfills';
+import {
+  logPermissionChange, getPermissionAuditTrail, searchPermissionAudit,
+  getPermissionAuditByDateRange, exportPermissionAuditCSV,
+} from '@/lib/audit-logger';
+
+async function getUser() {
+  const sessionId = (await cookies()).get(lucia.sessionCookieName)?.value ?? null;
+  if (!sessionId) return null;
+  const { user } = await lucia.validateSession(sessionId);
+  return user;
+}
+
+function checkAuditPermission(user) {
+  if (!user) return { allowed: false, error: 'Unauthorized' };
+  if (user.role === 'partner' || user.role === 'manager') return { allowed: true, scope: 'all' };
+  if (user.role === 'clerk') return { allowed: true, scope: 'own' };
+  return { allowed: false, error: 'Permission denied' };
+}
+
+export async function GET(request) {
+  try {
+    const user = await getUser();
+    const permCheck = checkAuditPermission(user);
+    if (!permCheck.allowed) return NextResponse.json({ error: permCheck.error }, { status: 403 });
+
+    const { searchParams } = new URL(request.url);
+    const search = searchParams.get('search');
+    const startDate = searchParams.get('start_date');
+    const endDate = searchParams.get('end_date');
+    const action = searchParams.get('action');
+    const limit = parseInt(searchParams.get('limit') || '100', 10);
+    const offset = parseInt(searchParams.get('offset') || '0', 10);
+    const format = searchParams.get('format');
+
+    let results;
+    if (search) {
+      results = searchPermissionAudit(search, limit);
+    } else if (startDate && endDate) {
+      results = getPermissionAuditByDateRange(parseInt(startDate, 10), parseInt(endDate, 10), limit);
+    } else {
+      const filters = {};
+      const entityType = searchParams.get('entity_type');
+      const entityId = searchParams.get('entity_id');
+      const userId = searchParams.get('user_id');
+      const affectedUserId = searchParams.get('affected_user_id');
+      if (entityType) filters.entityType = entityType;
+      if (entityId) filters.entityId = entityId;
+      if (permCheck.scope === 'own') filters.userId = user.id;
+      else if (userId) filters.userId = userId;
+      if (affectedUserId) filters.affectedUserId = affectedUserId;
+      filters.limit = limit;
+      filters.offset = offset;
+      results = getPermissionAuditTrail(filters);
+    }
+
+    if (format === 'csv') {
+      const csv = await exportPermissionAuditCSV({});
+      return new NextResponse(csv, { headers: { 'Content-Type': 'text/csv', 'Content-Disposition': 'attachment; filename="permission_audit.csv"' } });
+    }
+
+    return NextResponse.json({ success: true, data: results, count: results.length, scope: permCheck.scope });
+  } catch (error) {
+    console.error('[AuditAPI] GET error:', error);
+    return NextResponse.json({ error: 'Failed to retrieve audit trail', details: error.message }, { status: 500 });
+  }
+}
+
+export async function POST(request) {
+  try {
+    const user = await getUser();
+    if (!user) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+
+    const body = await request.json();
+    const { entityType, entityId, action, oldPermissions, newPermissions, reason, reasonCode, affectedUserId, metadata } = body;
+    if (!entityType || !entityId || !action) return NextResponse.json({ error: 'Missing required fields' }, { status: 400 });
+
+    const ipAddress = request.headers.get('x-forwarded-for') || request.headers.get('x-real-ip') || null;
+    const sessionId = (await cookies()).get(lucia.sessionCookieName)?.value ?? null;
+
+    const auditId = logPermissionChange({
+      userId: user.id, entityType, entityId, action, oldPermissions, newPermissions,
+      reason, reasonCode: reasonCode || 'other', affectedUserId, ipAddress, sessionId, metadata,
+    });
+
+    return NextResponse.json({ success: true, auditId });
+  } catch (error) {
+    console.error('[AuditAPI] POST error:', error);
+    return NextResponse.json({ error: 'Failed to log permission change', details: error.message }, { status: 500 });
+  }
+}

package/src/app/api/audit/permissions/stats/route.js

@@ -0,0 +1,29 @@
+import { NextResponse } from '@/lib/next-polyfills';
+import { getUser, setCurrentRequest } from '@/engine.server';
+import { getPermissionAuditStats, getPermissionAuditBreakdown } from '@/lib/audit-logger';
+
+export async function GET(request) {
+  setCurrentRequest(request);
+  try {
+    const user = await getUser();
+    if (!user) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    if (user.role !== 'partner' && user.role !== 'manager') return NextResponse.json({ error: 'Permission denied' }, { status: 403 });
+
+    const stats = getPermissionAuditStats();
+    const actionBreakdown = getPermissionAuditBreakdown('action');
+    const reasonCodeBreakdown = getPermissionAuditBreakdown('reason_code');
+
+    return NextResponse.json({
+      success: true,
+      stats: {
+        ...stats,
+        earliest_change: stats.earliest_change ? new Date(stats.earliest_change * 1000).toISOString() : null,
+        latest_change: stats.latest_change ? new Date(stats.latest_change * 1000).toISOString() : null,
+      },
+      breakdown: { by_action: actionBreakdown, by_reason_code: reasonCodeBreakdown },
+    });
+  } catch (error) {
+    console.error('[AuditStatsAPI] GET error:', error);
+    return NextResponse.json({ error: 'Failed to retrieve audit statistics', details: error.message }, { status: 500 });
+  }
+}

package/src/app/api/audit/route.js

@@ -0,0 +1,79 @@
+import { requireAuth, requirePermission } from '@/lib/auth-middleware';
+import { getAuditHistory, getActionStats, getUserStats } from '@/lib/audit-logger';
+import { getSpec } from '@/config/spec-helpers';
+import { paginated, ok } from '@/lib/response-formatter';
+import { withErrorHandler } from '@/lib/with-error-handler';
+import { AppError } from '@/lib/error-handler';
+import { HTTP } from '@/config/constants';
+import { parse as parseQuery } from '@/lib/query-string-adapter';
+
+export const GET = withErrorHandler(async (request) => {
+  const user = await requireAuth();
+  const url = new URL(request.url);
+
+  const entityType = url.searchParams.get('entityType');
+  const entityId = url.searchParams.get('entityId');
+  const userId = url.searchParams.get('userId');
+  const action = url.searchParams.get('action');
+  const fromDate = url.searchParams.get('fromDate') ? parseInt(url.searchParams.get('fromDate')) : null;
+  const toDate = url.searchParams.get('toDate') ? parseInt(url.searchParams.get('toDate')) : null;
+  const page = url.searchParams.get('page') ? parseInt(url.searchParams.get('page')) : 1;
+  const pageSize = url.searchParams.get('pageSize') ? parseInt(url.searchParams.get('pageSize')) : 50;
+  const stats = url.searchParams.get('stats');
+
+  if (page < 1) {
+    throw new AppError('page must be >= 1', 'BAD_REQUEST', HTTP.BAD_REQUEST);
+  }
+  if (pageSize < 1 || pageSize > 200) {
+    throw new AppError('pageSize must be between 1 and 200', 'BAD_REQUEST', HTTP.BAD_REQUEST);
+  }
+
+  if (stats === 'true') {
+    if (!fromDate || !toDate) {
+      throw new AppError('fromDate and toDate required for stats', 'BAD_REQUEST', HTTP.BAD_REQUEST);
+    }
+    const actionStats = getActionStats(fromDate, toDate);
+    const userStats = getUserStats(fromDate, toDate);
+    return ok({
+      actionStats,
+      userStats
+    });
+  }
+
+  const filters = {};
+  if (entityType) filters.entityType = entityType;
+  if (entityId) filters.entityId = entityId;
+  if (userId) filters.userId = userId;
+  if (action) filters.action = action;
+  if (fromDate) filters.fromDate = fromDate;
+  if (toDate) filters.toDate = toDate;
+
+  const { items, pagination } = getAuditHistory(filters, page, pageSize);
+
+  const enriched = items.map(log => ({
+    ...log,
+    timestamp: log.createdAt,
+    changes: log.beforeState && log.afterState ? findChanges(log.beforeState, log.afterState) : []
+  }));
+
+  return paginated(enriched, pagination);
+}, 'GET /api/audit');
+
+function findChanges(before, after) {
+  const changes = [];
+  const allKeys = new Set([...Object.keys(before || {}), ...Object.keys(after || {})]);
+
+  for (const key of allKeys) {
+    const beforeVal = before?.[key];
+    const afterVal = after?.[key];
+    if (JSON.stringify(beforeVal) !== JSON.stringify(afterVal)) {
+      changes.push({
+        field: key,
+        from: beforeVal,
+        to: afterVal
+      });
+    }
+  }
+
+  return changes;
+}

package/src/app/api/audit/stats/route.js

@@ -0,0 +1,18 @@
+import { NextResponse } from '@/lib/next-polyfills';
+import { requireAuth } from '@/lib/auth-middleware';
+import { getLogStats } from '@/lib/audit-logger-enhanced';
+import { withErrorHandler } from '@/lib/with-error-handler';
+
+export const GET = withErrorHandler(async (request) => {
+  const user = await requireAuth();
+  if (user.role !== 'admin' && user.role !== 'partner') {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 403 });
+  }
+
+  const url = new URL(request.url);
+  const fromDate = url.searchParams.get('from') ? parseInt(url.searchParams.get('from')) : Math.floor(Date.now() / 1000) - (24 * 60 * 60);
+  const toDate = url.searchParams.get('to') ? parseInt(url.searchParams.get('to')) : Math.floor(Date.now() / 1000);
+
+  const stats = getLogStats(fromDate, toDate);
+  return NextResponse.json({ success: true, stats, period: { from: fromDate, to: toDate } });
+});