Build an Immutable Audit Log for Regulated Industries

// src/audit/event-store.ts
import { z } from 'zod';
import { createHash, createHmac } from 'crypto';
import { Pool } from 'pg';

const db = new Pool({ connectionString: process.env.DATABASE_URL });
const SIGNING_KEY = process.env.AUDIT_SIGNING_KEY!;

export const AuditEvent = z.object({
  eventId: z.string().uuid(),
  timestamp: z.string().datetime(),
  actor: z.object({
    userId: z.string(),
    email: z.string().email(),
    role: z.string(),
    ipAddress: z.string(),
    userAgent: z.string().optional(),
  }),
  action: z.enum([
    'read', 'create', 'update', 'delete', 'export',
    'login', 'logout', 'permission_change', 'config_change',
  ]),
  resource: z.object({
    type: z.string(),       // "patient_record", "financial_report"
    id: z.string(),
    name: z.string().optional(),
  }),
  details: z.object({
    fieldsAccessed: z.array(z.string()).optional(),
    oldValues: z.record(z.string(), z.unknown()).optional(),
    newValues: z.record(z.string(), z.unknown()).optional(),
    reason: z.string().optional(),  // why was this data accessed?
    query: z.string().optional(),   // for read events
  }).default({}),
  metadata: z.record(z.string(), z.unknown()).default({}),
});

type AuditEvent = z.infer<typeof AuditEvent>;

// Each event includes a hash chain: hash(current event + previous hash)
export async function appendEvent(event: AuditEvent): Promise<{
  sequenceNumber: number;
  hash: string;
}> {
  // Get previous event's hash for chain
  const { rows: [prev] } = await db.query(
    `SELECT sequence_number, event_hash FROM audit_log ORDER BY sequence_number DESC LIMIT 1`
  );

  const previousHash = prev?.event_hash ?? '0'.repeat(64);
  const sequenceNumber = (prev?.sequence_number ?? 0) + 1;

  // Create deterministic hash of event + chain
  const eventPayload = JSON.stringify({
    ...event,
    sequenceNumber,
    previousHash,
  });

  const eventHash = createHash('sha256').update(eventPayload).digest('hex');

  // Create HMAC signature (proves we wrote it, not someone else)
  const signature = createHmac('sha256', SIGNING_KEY)
    .update(eventHash)
    .digest('hex');

  // Append to immutable table (no UPDATE or DELETE grants on this table)
  await db.query(`
    INSERT INTO audit_log (
      sequence_number, event_id, timestamp, actor, action,
      resource, details, metadata, previous_hash, event_hash, signature
    ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)
  `, [
    sequenceNumber, event.eventId, event.timestamp,
    JSON.stringify(event.actor), event.action,
    JSON.stringify(event.resource), JSON.stringify(event.details),
    JSON.stringify(event.metadata), previousHash, eventHash, signature,
  ]);

  return { sequenceNumber, hash: eventHash };
}

// src/audit/verifier.ts
import { createHash, createHmac } from 'crypto';
import { Pool } from 'pg';

const db = new Pool({ connectionString: process.env.DATABASE_URL });
const SIGNING_KEY = process.env.AUDIT_SIGNING_KEY!;

export async function verifyChainIntegrity(
  fromSequence: number = 1,
  toSequence?: number
): Promise<{
  verified: boolean;
  totalEvents: number;
  brokenAt?: number;
  errors: string[];
}> {
  const { rows } = await db.query(`
    SELECT * FROM audit_log
    WHERE sequence_number >= $1 ${toSequence ? `AND sequence_number <= ${toSequence}` : ''}
    ORDER BY sequence_number ASC
  `, [fromSequence]);

  const errors: string[] = [];
  let previousHash = fromSequence === 1 ? '0'.repeat(64) : null;

  // If starting mid-chain, get the hash before our start
  if (fromSequence > 1 && !previousHash) {
    const { rows: [prev] } = await db.query(
      `SELECT event_hash FROM audit_log WHERE sequence_number = $1`,
      [fromSequence - 1]
    );
    previousHash = prev?.event_hash;
  }

  for (const row of rows) {
    // Verify hash chain
    if (previousHash && row.previous_hash !== previousHash) {
      errors.push(`Chain broken at sequence ${row.sequence_number}: previous_hash mismatch`);
    }

    // Recompute hash
    const eventPayload = JSON.stringify({
      eventId: row.event_id,
      timestamp: row.timestamp.toISOString(),
      actor: row.actor,
      action: row.action,
      resource: row.resource,
      details: row.details,
      metadata: row.metadata,
      sequenceNumber: row.sequence_number,
      previousHash: row.previous_hash,
    });

    const computedHash = createHash('sha256').update(eventPayload).digest('hex');
    if (computedHash !== row.event_hash) {
      errors.push(`Hash mismatch at sequence ${row.sequence_number}: event was tampered with`);
    }

    // Verify signature
    const computedSig = createHmac('sha256', SIGNING_KEY).update(row.event_hash).digest('hex');
    if (computedSig !== row.signature) {
      errors.push(`Invalid signature at sequence ${row.sequence_number}`);
    }

    previousHash = row.event_hash;
  }

  return {
    verified: errors.length === 0,
    totalEvents: rows.length,
    brokenAt: errors.length > 0 ? parseInt(errors[0].match(/\d+/)?.[0] ?? '0') : undefined,
    errors,
  };
}

// src/api/audit.ts
import { Hono } from 'hono';
import { Pool } from 'pg';
import { verifyChainIntegrity } from '../audit/verifier';

const app = new Hono();
const db = new Pool({ connectionString: process.env.DATABASE_URL });

app.get('/v1/audit/events', async (c) => {
  const userId = c.req.query('userId');
  const resourceId = c.req.query('resourceId');
  const action = c.req.query('action');
  const from = c.req.query('from');
  const to = c.req.query('to');
  const limit = parseInt(c.req.query('limit') ?? '100');

  let sql = 'SELECT * FROM audit_log WHERE 1=1';
  const params: any[] = [];
  let i = 1;

  if (userId) { sql += ` AND actor->>'userId' = $${i++}`; params.push(userId); }
  if (resourceId) { sql += ` AND resource->>'id' = $${i++}`; params.push(resourceId); }
  if (action) { sql += ` AND action = $${i++}`; params.push(action); }
  if (from) { sql += ` AND timestamp >= $${i++}`; params.push(from); }
  if (to) { sql += ` AND timestamp <= $${i++}`; params.push(to); }

  sql += ` ORDER BY sequence_number DESC LIMIT $${i++}`;
  params.push(limit);

  const { rows } = await db.query(sql, params);
  return c.json({ events: rows, count: rows.length });
});

// Who accessed this patient record?
app.get('/v1/audit/resource/:type/:id/access-log', async (c) => {
  const type = c.req.param('type');
  const id = c.req.param('id');

  const { rows } = await db.query(`
    SELECT actor, action, timestamp, details
    FROM audit_log
    WHERE resource->>'type' = $1 AND resource->>'id' = $2
    ORDER BY timestamp DESC LIMIT 500
  `, [type, id]);

  return c.json({ resourceType: type, resourceId: id, accessLog: rows });
});

// Verify integrity for auditors
app.get('/v1/audit/verify', async (c) => {
  const result = await verifyChainIntegrity();
  return c.json(result);
});

export default app;