docs(security): self-contain KEY-05 and PSBT; record the completed entropy migration

Verified the security subsystem's design-doc claims against code:

- KEY-05's foundational claims are accurate: entropy::draw_key_bytes exists,
  KeyGenRng is sealed with OsRng as its sole production member, MIN_GUARDED_LEN
  is 12, and core/clippy.toml bans rand::random/thread_rng exactly as stated.
- But its per-site table listed every production nonce/key site as disposition
  "migrate" (pending), when all of them have since been migrated to
  draw_key_bytes(OsRng) — storage_crypto, credentials/store, wallet/bdhke,
  mesh/x3dh — and zero rand::random/thread_rng remain in production. Added a
  completion note so the doc no longer reads as pending work.

Both KEY-05 and PSBT-SIGNING-ARCHITECTURE referenced
ENTROPY-SEED-AUDIT-2026-07-31.md five times as their evidence base — a doc that
was moved to local-only, so a public reader could not follow it. Reworded all
five to state the audit's findings inline ("the internal entropy audit found
...") without the unresolvable path. No published doc references it now. The
link-checker missed these because they were inline code, not markdown links.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
archipelago
2026-08-07 18:59:11 -04:00
co-authored by Claude Opus 5
parent bcbd4a7032
commit dc2d79ce77
2 changed files with 14 additions and 9 deletions
+10 -5
View File
@@ -2,12 +2,17 @@
**Requirement:** ROADMAP `KEY-05`.
**Supersedes:** backlog `R-13`. **Absorbs:** `R-05` (duplicate-`rand` visibility) and `R-09`
(CSPRNG-readiness record). **Resolves:** `F-10a` in
`docs/security/ENTROPY-SEED-AUDIT-2026-07-31.md`, which recorded raw match counts and
**deliberately declined to classify them**.
(CSPRNG-readiness record). **Resolves:** `F-10a` from the internal entropy and
seed-generation audit, which recorded raw match counts and **deliberately declined
to classify them**.
**Tree state this document was derived against:** `HEAD = c5a82cba` (2026-08-02).
**Update:** every `migrate` disposition in the table below has since been applied.
No `rand::random()` / `rand::thread_rng()` call remains in production `archipelago`
code — each draws through `entropy::draw_key_bytes` from a named `OsRng`, and
`core/clippy.toml` now bans both APIs, so a regression fails the build.
---
## Nothing here is broken today
@@ -206,8 +211,8 @@ lines are `core/archipelago/src/mesh/x3dh.rs:99` and `:113` —
produced there; `:100` and `:114` draw only the `u32` `id` fields of `SignedPrekey` and
`OneTimePrekey`. They remain in scope — they are values that go on the wire — but the
characterisation "X3DH key agreement — key material" overstates these two specific lines.
(The audit has since been corrected in place at `ENTROPY-SEED-AUDIT-2026-07-31.md:508`; this
section records the derivation independently.)
(The internal audit has since been corrected; this section records the derivation
independently.)
---
+4 -4
View File
@@ -32,8 +32,8 @@
> a phased rollout that a future `/gsd-plan-phase` can consume directly. It deliberately
> contains no code, adds no dependencies, and changes no wallet or signing behaviour.
>
> **Companion document:** `docs/security/ENTROPY-SEED-AUDIT-2026-07-31.md` — the entropy and
> seed-generation audit that motivated this spec. **Cross-linked design:**
> **Companion document:** the internal entropy and seed-generation audit that
> motivated this spec. **Cross-linked design:**
> `docs/hardware-signer-design.md` — the exploratory TROPIC01 air-gapped signer, which this
> architecture treats as the future *first-party* signer, not as a competing design.
@@ -425,7 +425,7 @@ nagged-at that users stop reading warnings. Concretely:
- **A software fix does not repair an already-generated seed.** If a seed was produced by a
defective RNG, updating the software leaves it exactly as guessable. This is why Coinkite told
users to migrate rather than merely update.
- **The audit found no such defect in Archipelago.** `docs/security/ENTROPY-SEED-AUDIT-2026-07-31.md`
- **The audit found no such defect in Archipelago.** The internal entropy audit's
§2 and §4 record that every first-party key-generation call site draws from a genuine CSPRNG,
that the mnemonic is a real 256-bit value, and that `[ARCHY-1]` is a *structural* risk with no
present exploitability.
@@ -609,7 +609,7 @@ current security posture and should not wait for the rest.
## 9. Related documents
- `docs/security/ENTROPY-SEED-AUDIT-2026-07-31.md` — the audit motivating this spec; see F-05
- The internal entropy and seed-generation audit motivating this spec; see F-05
(Argon2 parameters) and the F-13 addendum on the xprv-in-Core issue.
- `docs/hardware-signer-design.md` — the first-party TROPIC01 air-gapped signer; §4.3 above
answers two of its open items.