Decision Record: Establish SHHH Sentinel Foundations

Date: 2025-02-16
Status: Accepted
Context: CHORUS roadmap Phase 1 requires a secrets sentinel (pkg/shhh) before we wire COOEE/WHOOSH telemetry and audit plumbing. The runtime previously emitted placeholder TODOs and logged sensitive payloads without guard rails.

Problem

We lacked a reusable component to detect and redact secrets prior to log/telemetry fan-out.
Without a dedicated sentinel we could not attach audit sinks or surface metrics for redaction events, blocking roadmap item SEC-SHHH.

Introduce pkg/shhh as the SHHH sentinel with:
- Curated default rules (API keys, bearer/OAuth tokens, private key PEM blocks, OpenAI secrets).
- Extensible configuration for custom regex rules and per-rule severity/tags.
- Optional audit sink and statistics collection for integration with COOEE/WHOOSH pipelines.
- Helpers to redact free-form text and map[string]any payloads used by our logging pipeline.

Starting with a focused set of high-signal rules gives immediate coverage for the most damaging leak classes without delaying larger SLURP/SHHH workstreams.
The API mirrors other CHORUS subsystems (options, config structs, stats snapshots) so existing operators can plug metrics/audits without bespoke glue.
Providing deterministic findings/locations simplifies future enforcement (e.g., WHOOSH UI badges, COOEE replay) while keeping implementation lean.

Runtime components can now instantiate SHHH and guarantee [REDACTED] placeholders for sensitive fields.
Audit/event plumbing can be wired incrementally—hashes are emitted for replay without storing raw secrets.
Future roadmap tasks (policy driven rules, replay, UCXL evidence) can extend pkg/shhh rather than implementing ad-hoc redaction in each subsystem.