archetech / archon / 30923606546

87%

push

github

docs+test: trace where the entropy comes from, and guard the no-fallback property (#857)

* docs: trace where the entropy ultimately comes from

SECURITY.md documented the RNG as far as `crypto.getRandomValues` and stopped
there, which names the API Archon calls but not where the randomness is
created. Adds the rest of the chain, down to the physical layer.

The chain: @noble/hashes randomBytes -> crypto.getRandomValues -> OpenSSL 3.x
CTR-DRBG -> getrandom(2) -> the kernel's ChaCha20 CSPRNG, seeded from interrupt
timing, RDSEED/RDRAND, and seed material carried across boots.

None of that creates entropy — a DRBG expands it, a seed file carries it, a
syscall hands it over. Following the inputs down, they terminate in two
physical processes: thermal noise in silicon (RDSEED samples a metastable
circuit whose settling is decided by Johnson-Nyquist noise, then conditions the
biased output in hardware), and timing variance between physically independent
clocks (interrupt arrival is set by events elsewhere; the sampling oscillator
drifts through phase noise, which is thermal again).

Also records what probing the host showed rather than the generic story: this
machine exposes no hw_random device, so arch-random and interrupt timing carry
the load, and a cloud VM's virtio-rng passes the host's entropy through rather
than generating any — which is why a cloned guest is dangerous. Notes that
"random" here means physically unpredictable, not provably indeterminate.

Verified while writing: @noble/hashes tries crypto.getRandomValues first, and
since Node 19 exposes globalThis.crypto that is the branch every supported
deployment takes — the crypto.randomBytes fallback is never reached.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* test(cipher): guard against a silent weak-RNG substitution

SECURITY.md calls the throw-rather-than-fall-back property "the property most
worth preserving", but nothing asserted it. The July 2026 Coldcard incid... (continued)

3609 of 4063 branches covered (88.83%)

Branch coverage included in aggregate %.

8230 of 8512 relevant lines covered (96.69%)

687.14 hits per line