Tainted-value wrapper for sensitive material that must NOT reach an AI assistant or any debug surface — but whose presence and identity should still be observable via stable per-run hash tokens.
Where hive-system.secrets.core/Secret is the storage primitive for
credentials ("don't print, don't compare, don't serialize"), Tainted
is a diagnostic primitive: it wraps any value (hostnames, ports,
identities, env values, argv slots) so we can correlate the same
underlying value across many log lines with a short hash token like
<host:#a3f4> — without ever printing the value itself.
Tainted is a defrecord with three fields:
:value — the wrapped sensitive value :source — non-sensitive label (e.g. "pass:vps/r1/ip", :argv-host) :hash — 4-hex-char stable token derived from HMAC-SHA256(salt, value)
<host:#a3f4> across log lines.print-method ALWAYS emits <redacted src=... h=#xxxx> and NEVER
the underlying value. toString mirrors that.
untaint — the ONE blessed unwrap. Every call site is a leak risk.
This is the only safe extraction point and MUST only be invoked at
trust boundaries (process spawn, network write, file write to a
trusted local sink). Never call it within reach of a log appender,
event subscriber, or anything whose output may be surfaced to the
assistant.Secret apply.Tainted-value wrapper for sensitive material that must NOT reach an AI
assistant or any debug surface — but whose *presence and identity*
should still be observable via stable per-run hash tokens.
## Purpose
Where `hive-system.secrets.core/Secret` is the storage primitive for
credentials ("don't print, don't compare, don't serialize"), `Tainted`
is a *diagnostic* primitive: it wraps any value (hostnames, ports,
identities, env values, argv slots) so we can correlate the same
underlying value across many log lines with a short hash token like
`<host:#a3f4>` — without ever printing the value itself.
## Type
`Tainted` is a defrecord with three fields:
:value — the wrapped sensitive value
:source — non-sensitive label (e.g. "pass:vps/r1/ip", :argv-host)
:hash — 4-hex-char stable token derived from HMAC-SHA256(salt, value)
## Hash semantics
- Hash is computed once at construction and cached.
- Same value within a single JVM run produces the SAME hash token,
so operators can correlate `<host:#a3f4>` across log lines.
- Salt is generated per JVM at namespace-load time via SecureRandom
and held in a private atom — cross-JVM-restart unlinkability is by
design (the salt cannot be reconstructed from prior runs).
- Hash space is 16^4 = 65,536 — collision probability is acceptable
within a single run's working set of distinct sensitive values.
## Print safety
`print-method` ALWAYS emits `<redacted src=... h=#xxxx>` and NEVER
the underlying value. `toString` mirrors that.
## Audit surface
- `untaint` — the ONE blessed unwrap. Every call site is a leak risk.
This is the only safe extraction point and MUST only be invoked at
trust boundaries (process spawn, network write, file write to a
trusted local sink). Never call it within reach of a log appender,
event subscriber, or anything whose output may be surfaced to the
assistant.
## Non-goals
- Encryption / secure memory wiping. JVM strings can't be reliably
zeroed; the same caveats as `Secret` apply.
- Cross-process correlation. By design — see Hash semantics above.(taint value source)Wrap value as a Tainted carrier with non-sensitive source label.
The returned Tainted carries a 4-hex-char stable hash derived from the per-JVM salt + value via HMAC-SHA256. Same value within a JVM run → same hash. Different JVM run → different hash (salt is per-process).
Examples:
(taint "10.0.0.42" "pass:vps/r1/ip") (taint 22 :argv-port)
value may be any value that has a meaningful (str value). source
is non-sensitive and printed verbatim in the redacted form.
Wrap `value` as a Tainted carrier with non-sensitive `source` label. The returned Tainted carries a 4-hex-char stable hash derived from the per-JVM salt + value via HMAC-SHA256. Same value within a JVM run → same hash. Different JVM run → different hash (salt is per-process). Examples: (taint "10.0.0.42" "pass:vps/r1/ip") (taint 22 :argv-port) `value` may be any value that has a meaningful `(str value)`. `source` is non-sensitive and printed verbatim in the redacted form.
(tainted? x)Truthy if x is a Tainted instance.
Truthy if x is a Tainted instance.
(token x)Return the stable token form <src:#hash> for a Tainted, or nil if
x is not Tainted. Useful for ssh-argv / structural redactors that
want to substitute Tainted slots with a short string token.
Return the stable token form `<src:#hash>` for a Tainted, or nil if x is not Tainted. Useful for ssh-argv / structural redactors that want to substitute Tainted slots with a short string token.
(untaint t)Return the underlying value of a Tainted.
AUDIT: this is the ONLY safe extraction point and MUST only be called at trust boundaries — process spawn, file write to a trusted local sink, etc. Every call site is a leak risk. Never invoke within reach of a log appender, event subscriber, REPL transcript, or anywhere whose output may be surfaced to an AI assistant.
For non-Tainted inputs, returns the value unchanged so callers can uniformly call (untaint x) over a heterogeneous structure.
Return the underlying value of a Tainted. AUDIT: this is the ONLY safe extraction point and MUST only be called at trust boundaries — process spawn, file write to a trusted local sink, etc. Every call site is a leak risk. Never invoke within reach of a log appender, event subscriber, REPL transcript, or anywhere whose output may be surfaced to an AI assistant. For non-Tainted inputs, returns the value unchanged so callers can uniformly call (untaint x) over a heterogeneous structure.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |