From dc2d79ce775a23ad8230779c28e62e1be63e39b0 Mon Sep 17 00:00:00 2001 From: archipelago Date: Fri, 7 Aug 2026 18:59:11 -0400 Subject: [PATCH] docs(security): self-contain KEY-05 and PSBT; record the completed entropy migration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- docs/security/KEY-05-ENTROPY-ENFORCEMENT.md | 15 ++++++++++----- docs/security/PSBT-SIGNING-ARCHITECTURE.md | 8 ++++---- 2 files changed, 14 insertions(+), 9 deletions(-) diff --git a/docs/security/KEY-05-ENTROPY-ENFORCEMENT.md b/docs/security/KEY-05-ENTROPY-ENFORCEMENT.md index f5536ebf..92df28cb 100644 --- a/docs/security/KEY-05-ENTROPY-ENFORCEMENT.md +++ b/docs/security/KEY-05-ENTROPY-ENFORCEMENT.md @@ -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.) --- diff --git a/docs/security/PSBT-SIGNING-ARCHITECTURE.md b/docs/security/PSBT-SIGNING-ARCHITECTURE.md index 313e83ce..71e0a2bf 100644 --- a/docs/security/PSBT-SIGNING-ARCHITECTURE.md +++ b/docs/security/PSBT-SIGNING-ARCHITECTURE.md @@ -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.