Audit Logging

Audit Event Structure

interface AuditEvent { id: string; timestamp: string; // ISO 8601 actor: { id: string; type: 'user' | 'system' | 'api_key'; ip?: string; userAgent?: string; }; action: string; // 'user.created', 'order.deleted' resource: { type: string; // 'user', 'order' id: string; }; changes?: { // Before/after for updates field: string; before: unknown; after: unknown; }[]; metadata?: Record<string, unknown>; }

Audit Service

class AuditService { async log(event: Omit<AuditEvent, 'id' | 'timestamp'>): Promise<void> { const auditEntry: AuditEvent = { id: randomUUID(), timestamp: new Date().toISOString(), ...event, };

// Write to append-only table
await db.auditLog.create({ data: auditEntry });

// Optionally stream to external system
await this.eventStream?.publish('audit', auditEntry);

} }

// Usage in service layer async function updateUser(userId: string, data: UpdateUserDto, actor: Actor) { const before = await db.user.findUnique({ where: { id: userId } }); const after = await db.user.update({ where: { id: userId }, data });

await audit.log({ actor: { id: actor.id, type: 'user', ip: actor.ip }, action: 'user.updated', resource: { type: 'user', id: userId }, changes: diffFields(before, after, ['name', 'email', 'role']), });

return after; }

function diffFields(before: any, after: any, fields: string[]) { return fields .filter((f) => before[f] !== after[f]) .map((f) => ({ field: f, before: before[f], after: after[f] })); }

Express Middleware

function auditMiddleware(action: string) { return (req: Request, res: Response, next: NextFunction) => { const originalJson = res.json.bind(res); res.json = (body) => { audit.log({ actor: { id: req.user?.id ?? 'anonymous', type: 'user', ip: req.ip }, action, resource: { type: action.split('.')[0], id: req.params.id ?? body?.id }, }); return originalJson(body); }; next(); }; }

app.delete('/api/users/:id', auditMiddleware('user.deleted'), deleteUserHandler);

Database Schema

CREATE TABLE audit_logs ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), timestamp TIMESTAMPTZ NOT NULL DEFAULT now(), actor_id TEXT NOT NULL, actor_type TEXT NOT NULL, actor_ip INET, action TEXT NOT NULL, resource_type TEXT NOT NULL, resource_id TEXT NOT NULL, changes JSONB, metadata JSONB );

-- Append-only: revoke UPDATE and DELETE REVOKE UPDATE, DELETE ON audit_logs FROM app_user;

-- Indexes for common queries CREATE INDEX idx_audit_actor ON audit_logs (actor_id, timestamp DESC); CREATE INDEX idx_audit_resource ON audit_logs (resource_type, resource_id, timestamp DESC); CREATE INDEX idx_audit_action ON audit_logs (action, timestamp DESC);

Anti-Patterns

Anti-Pattern Fix

Logging inside transaction (fails = no log) Log after successful commit

Mutable audit table Revoke UPDATE/DELETE, use append-only

Missing actor identity Always capture who performed the action

Logging sensitive field values Redact PII (email → j***@example.com )

No retention policy Partition by month, archive after retention period

Production Checklist

• Append-only audit table (no UPDATE/DELETE)

• Actor identity captured on all events

• Before/after values for data changes

• PII redaction in audit entries

• Indexed for common query patterns

• Retention policy and archival

• Tamper detection (hash chain or external storage)