compliance-patterns

Compliance Patterns

Data governance and regulatory compliance patterns for software systems.

Data Classification

// Tag every data field with its classification level
enum DataClass {
  PUBLIC = 'public',           // Marketing content, product info
  INTERNAL = 'internal',       // Business metrics, employee count
  CONFIDENTIAL = 'confidential', // Customer emails, order history
  RESTRICTED = 'restricted',   // Passwords, SSN, payment cards, health data
}

// Schema-level classification
interface UserRecord {
  id: string                    // INTERNAL
  email: string                 // CONFIDENTIAL (PII)
  displayName: string           // CONFIDENTIAL (PII)
  passwordHash: string          // RESTRICTED
  dateOfBirth: string           // RESTRICTED (sensitive PII)
  preferences: object           // INTERNAL
  createdAt: Date              // INTERNAL
}

// Field-level encryption for RESTRICTED data
const ENCRYPTED_FIELDS: Record<string, DataClass> = {
  'user.email': DataClass.CONFIDENTIAL,
  'user.dateOfBirth': DataClass.RESTRICTED,
  'user.ssn': DataClass.RESTRICTED,
  'payment.cardNumber': DataClass.RESTRICTED,
}

function shouldEncryptAtRest(fieldPath: string): boolean {
  const classification = ENCRYPTED_FIELDS[fieldPath]
  return classification === DataClass.RESTRICTED
}

function shouldMaskInLogs(fieldPath: string): boolean {
  const classification = ENCRYPTED_FIELDS[fieldPath]
  return classification === DataClass.CONFIDENTIAL || classification === DataClass.RESTRICTED
}

Audit Logging

interface AuditEvent {
  id: string
  timestamp: string         // ISO 8601
  actor: {
    id: string
    type: 'user' | 'system' | 'admin'
    ip?: string
  }
  action: string            // e.g., 'user.profile.updated', 'order.deleted'
  resource: {
    type: string
    id: string
  }
  changes?: {
    field: string
    oldValue: unknown       // Masked if RESTRICTED
    newValue: unknown       // Masked if RESTRICTED
  }[]
  metadata?: Record<string, unknown>
  result: 'success' | 'failure' | 'denied'
  reason?: string           // For denied/failure
}

class AuditLogger {
  constructor(private store: AuditStore) {}

  async log(event: Omit<AuditEvent, 'id' | 'timestamp'>): Promise<void> {
    const auditEvent: AuditEvent = {
      ...event,
      id: crypto.randomUUID(),
      timestamp: new Date().toISOString(),
      changes: event.changes?.map(c => ({
        ...c,
        oldValue: shouldMaskInLogs(c.field) ? '[REDACTED]' : c.oldValue,
        newValue: shouldMaskInLogs(c.field) ? '[REDACTED]' : c.newValue,
      })),
    }

    // Audit logs are append-only, immutable, tamper-evident
    await this.store.append(auditEvent)
  }
}

// Middleware: auto-audit all mutations
function auditMiddleware(auditLogger: AuditLogger) {
  return async (req: Request, res: Response, next: NextFunction) => {
    const originalJson = res.json.bind(res)

    res.json = function(body: any) {
      if (['POST', 'PUT', 'PATCH', 'DELETE'].includes(req.method)) {
        auditLogger.log({
          actor: { id: req.user?.id ?? 'anonymous', type: 'user', ip: req.ip },
          action: `${req.method.toLowerCase()}.${req.path}`,
          resource: { type: req.path.split('/')[2], id: req.params.id ?? 'N/A' },
          result: res.statusCode < 400 ? 'success' : 'failure',
        }).catch(err => console.error('Audit log failed:', err))
      }
      return originalJson(body)
    }

    next()
  }
}