Best Practices, Audit & Compliance

Production hardening guidance, the at-rest encryption scheme, the tamper-evident audit trail, and framework mappings for teams under SOC 2 / HIPAA / PCI / GDPR obligations.

Encryption at Rest (EncryptionService)

Per-record salt means every ciphertext derives an independent subkey, a single leaked derived key does not generalize. The GCM tag authenticates each record; tampering fails decryption rather than yielding garbage plaintext. The prefix makes encrypted values self-identifying, enabling transparent migration and mixed-state reads. Fail-loud invariant: with ENCRYPTION_KEY unset the service silently degrades to plaintext with only a warning, CI aside, an unset key in any real environment is a critical misconfiguration.

Audit Middleware & Redaction

auditMiddleware is mounted globally and records every state-changing verb (POST/PUT/PATCH/DELETE) plus login, approval, and execution events; read-only queries are not logged. Entity IDs are derived from the URL path UUID or the response body. Sensitive fields, password, token, secret, apiKey, mfaToken, and peers, are redacted before the record is written, so before/after diffs never persist live secrets.

{
  "id": 12345,
  "timestamp": "2025-01-15T14:30:00.000Z",
  "userEmail": "developer@company.com",
  "action": "script.execute",
  "entityType": "script",
  "entityId": 42,
  "oldValues": { ... },
  "newValues": { ... },
  "ipAddress": "192.168.1.100",
  "success": true
}

Immutable, Tamper-Evident Audit Trail

The trail is append-only and cryptographically sealed by the database. On insert, a trigger assigns a monotonic sequence number, links the row to the hash of its predecessor, and stores a SHA-256 over the record contents concatenated with that prior hash. Each hash therefore depends on the entire prefix of the chain: any modification, deletion, reorder, or back-dated insertion of a historical record invalidates every subsequent hash and is detectable.

• Append-only enforcement: triggers reject UPDATE and DELETE on the audit table outright. The application cannot mutate a sealed record; the only sanctioned deletion is the controlled retention purge.
• Sealing occurs in the database, not the application layer, a compromised or malicious app process cannot forge, reorder, or backdate the chain.
• Verification: GET /api/db-devops/audit/integrity (Enterprise) walks the whole chain and returns { valid, brokenSeq, total }. valid: false plus brokenSeq pinpoints the first record whose hash no longer reconciles, including tampering performed by a database superuser editing the table directly.

Honest caveat: stock PostgreSQL cannot make a table physically unwritable to a superuser. This design does not claim to prevent superuser writes; it makes any such write cryptographically detectable and blocks every ordinary mutation path. Where hardware-enforced immutability is mandated, target a ledger-backed or WORM store (append-only object storage, or a managed ledger database) behind the same interface.

Retention

Records live in the DevOps Postgres database; retention is the only sanctioned removal path.

• Default 90 days, configurable in Settings → Audit.
• Purge mechanism: a privileged, itself-audited database function removes only the oldest records, the tail of the chain, so the surviving chain stays internally verifiable end-to-end. Ad-hoc DELETE is refused by the append-only triggers.
• Archival: export the tail to S3 / Azure Blob / a log platform before purge for long-horizon retention (compliance windows commonly ≥1 year).

Production Hardening

Network

• TLS 1.2+ at the edge; TLS 1.0/1.1 disabled; trusted-CA certs; HSTS via Helmet.
• App and datastore in private subnets; egress via NAT only for the repo integrations that need it (GitHub, GitLab, Dropbox, S3).
• Security groups: inbound 80/443 to the edge only; app→Postgres on 5432; deny-all otherwise.
• Prefer VPN / private-link for internal-only deployments to remove public exposure entirely.

Secrets

Never place secrets in source, committed .env, image layers, or logs. Note that keys/license-private.pem is currently committed to the repo, a tracked debt item; inject it from a secrets manager for real signing.

Container & Datastore

• Non-root runtime user; minimal (Alpine) base; scan and block critical/high CVEs; pin immutable tags; readOnlyRootFilesystem with writable mounts scoped to /tmp and logs.
• Dedicated least-privilege Postgres role (DML + CREATE TABLE for migrations; no SUPERUSER/CREATEDB/CREATEROLE); sslmode=require|verify-full; storage encryption on; a CONNECTION LIMIT to bound pool exhaustion.

Compliance Framework Mapping

SOC 2 (Type II)

HIPAA (164.312)

PCI DSS

GDPR

Scope note: these controls support compliance; they do not constitute it. Certification depends on your full stack, organizational policy, physical and vendor controls, and evidence collection beyond this application. Engage your auditor for an authoritative assessment.