---
phase: 10-key-material-hardening
plan: 06
subsystem: entropy
tags: [security, key-material, entropy, rng, KEY-05, F-10a, F-07, R-05, R-09, R-13]
status: complete
requires:
  - "docs/security/ENTROPY-SEED-AUDIT-2026-07-31.md F-10a (the deliberately-unclassified raw match table), F-07, F-02, F-09"
  - "10-01 (F-01 onboarding gate) and 10-05 (F-13 Core wallet deletion) committed first"
provides:
  - "crate::entropy — sealed KeyGenRng allowlist, degenerate-entropy predicate, CSPRNG-readiness ledger"
  - "core/clippy.toml — crate-wide compile-time ban on rand::random / rand::thread_rng"
  - "core/deny.toml — change-detecting rand duplicate-major rule, grandfathered 2026-08-02"
  - "docs/security/KEY-05-ENTROPY-ENFORCEMENT.md — per-site classification + observed gate evidence"
affects:
  - "core/archipelago/src/entropy.rs (new)"
  - "core/archipelago/src/seed.rs"
  - "core/archipelago/src/session.rs"
  - "core/archipelago/src/storage_crypto.rs"
  - "core/archipelago/src/credentials/store.rs"
  - "core/archipelago/src/wallet/bdhke.rs"
  - "core/archipelago/src/mesh/x3dh.rs"
  - "core/archipelago/src/container/secrets.rs"
  - "core/archipelago/src/totp.rs"
  - "17 further call-site files (see the commit)"
tech-stack:
  added:
    - "cargo-deny 0.20.2 (pinned; installed from crates.io in CI)"
  patterns:
    - "Sealed trait as an allowlist: supertrait in a private module, so no other module can add a member"
    - "Hardcoded pre-migration ciphertext vectors from an INDEPENDENT implementation, because a same-process round trip proves self-consistency rather than compatibility"
    - "Degenerate-entropy predicate restricted to shapes with closed-form false-positive bounds — no heuristics, no entropy estimators"
    - "Gates proven by observation (inject -> observe failure -> revert -> observe pass), never by assumption"
key-files:
  created:
    - "core/archipelago/src/entropy.rs"
    - "core/clippy.toml"
    - "core/deny.toml"
  modified:
    - "docs/security/KEY-05-ENTROPY-ENFORCEMENT.md"
    - ".github/workflows/ci.yml"
    - "23 source files under core/archipelago/src (see commit 09a1f762)"
decisions:
  - "cargo-deny wired as bans-only; advisories deliberately NOT enabled (human checkpoint, Task 5) — F-07's advisory half stays OPEN"
  - "cargo-deny installed from crates.io at a pinned 0.20.2 rather than via EmbarkStudios/cargo-deny-action, because that action exposes no version-pinning input and an unpinned supply-chain checker reproduces the very failure shape this plan removes"
  - "generate_mnemonic_with switched from generate_in_with to from_entropy so the draw is inspectable at the seam; equivalence held by the pre-existing known-answer test"
  - "The blinding factor in bdhke.rs is deliberately NOT routed through the guard — intercepting it would mean reimplementing secp256k1 rejection sampling, a larger correctness risk than the guard buys"
  - "totp.rs migrated SOURCE only; the % charset.len() reduction and 32-char charset untouched (R-12 stays deferred, bias is presently zero)"
  - "session token minting aborts rather than returns on a degenerate draw, because the callers live in files this plan does not own and widening them to Result is an API change out of scope"
metrics:
  duration: "resumed session; migration pre-existing uncommitted, gates + evidence completed 2026-08-02"
  completed: 2026-08-02
  tasks_completed: 6
  tasks_total: 6
---

# 10-06 — KEY-05 entropy enforcement

## What shipped

Five layers, all landed:

| Layer | What | Where |
|---|---|---|
| (a) | Every production key/nonce/token draw names `rand::rngs::OsRng` at its own call site; the mnemonic seam is bound to a **sealed** `KeyGenRng` allowlist | `entropy.rs`, 23 source files |
| (b) | Crate-wide compile-time ban on `rand::random` / `rand::thread_rng` | `core/clippy.toml` |
| (c) | `rand` duplicate-major rule that is change-detecting, grandfathered | `core/deny.toml`, CI step |
| (d) | Degenerate-entropy predicate refusing all-zero / all-identical / ±1-counter draws | `entropy::draw_key_bytes` |
| (e) | Durable kernel-CSPRNG readiness record at master-seed generation (R-09) | `entropy::record_csprng_readiness` |

`impl rand::CryptoRng` count in the crate is now **zero** — the false marker promise at the old
`seed.rs:656` is retired, as the roadmap required.

## Why this was worth doing when nothing was broken

Nothing in F-10a's table is broken today: on the pinned `rand 0.8.5` both banned entry points
resolve to a ChaCha12 CSPRNG seeded from `getrandom(2)`. What they lacked was a *stated* backend —
fixed by dependency and build configuration rather than by the calling code, with no compile error
if it changed. That is the structural shape ("T1") behind the 2026-07-30 COLDCARD entropy defect,
and here the blast radius included Cashu blinded-key-exchange values, X3DH prekey material, session
bearer tokens and a ChaCha20-Poly1305 nonce.

## Evidence

- `cargo test -p archipelago`: **1068 passed, 2 failed**. Both failures are
  `container::boot_reconciler` timing tests in a file this plan never touches; **re-run in
  isolation they pass 4/4 in 0.84s**, so they are full-suite parallel-load flakes, not regressions.
- Format compatibility proven with **hardcoded pre-migration ciphertext vectors** produced by an
  independent RFC 8439 implementation — a same-process seal/open round trip would have passed even
  if the envelope had changed.
- Both gates observed working (inject → fail → revert → pass for clippy; remove grandfather →
  exit 2 → restore → exit 0 for cargo-deny). Full transcripts in the evidence doc.

## Open, and deliberately so

1. **⚠️ Layer (b)'s gate is live but not yet EFFECTIVE.** The tree carries **42 pre-existing clippy
   warnings** unrelated to KEY-05 (unused imports, dead code, ~39 style lints). Under the CI step's
   `-D warnings` every one is already an error, so that step cannot pass today for reasons that
   predate this plan. The ban is correctly configured and proven to fire, but until a dedicated
   lint-clearing pass lands, a new banned RNG call is one error among many rather than the
   distinctive build-stopper the design intends. **Recommended next follow-up.**
2. **F-07's advisory half stays OPEN** (bans-only policy).
3. **`core/models` is outside the enforcement graph** — not a workspace member, so no
   `disallowed-methods` entry can reach its two matches. Stated limitation, not an omission.
4. **F-09/R-12 and F-11/R-14 remain deferred.**
5. **Sealing does not prevent an edit to `entropy.rs` itself** — it raises the act from an invisible
   default to a reviewable change to the one file whose purpose is this guarantee. That is the
   honest claim; "impossible" would not be.

Nothing already generated is suspect: the previous source was, and remains, `getrandom(2)`-backed.
This plan removes a *future* failure mode and implies no re-generation of existing key material.