Security audit: python-codex32 findings

[BenWestgate]

Security-audit umbrella originating from c118a834. The attached report.md remains historical evidence; its Finding 1 (opaque-HRP deadline bypass) was subsequently falsified and is not tracked as a defect.

This issue also tracks the three independent adversarial reviews and their consolidated-review.md disposition so the release gate has one exhaustive map rather than only the highest-severity implementation findings.

Material validated findings

• BL1 — documented dev setup failed: fixed by merged Wallet: use Core for setup and remove test crypto deps #7 removing the test-only bip32/Coincurve dependency; current CI installs .[dev] and runs the suite. Draft docs: Replace contributor boilerplate #115 rewrites the contributor on-ramp around that actual setup.
• BL2 — BSD notice omitted from distributions: fixed by merged build: Include all code license notices #15; current pyproject.toml includes LICENSES/* and MANIFEST.in recursively includes LICENSES.
• H1 — artifact repr/str disclosure: fixed by merged bip93: Redact artifact string rendering #25 / Redact secret-bearing artifact string representations #22; rendering is redacted and .text is the explicit export path.
• H2 — wallet import before recovery identity: tracked by Verify recovered wallet identity before import #26/Verify CLI recovery identity before wallet import #30. CLI/library release gate is wallet: Require the recorded fingerprint before import #57 plus cli: Remove unreachable recovery and search paths #105/wallet: Distinguish unavailable Bails checks #80/wallet: Check existing seed before sharing #81/cli: Announce recovery secret switch #95; GUI replay is draft gui: Require wallet identity before restore #118. Current reviewed heads enforce verify-before-mutate; final human integration and GUI/Tails qualification remain.
• H3 — overlong HRPs: bip93: Reject human-readable parts longer than 83 characters #32 / focused bip93: reject HRPs longer than 83 characters #33; current head is CI-green, all review threads are resolved, and it has a current-head Codex ACK.
• M1 — mixed-case correction reported no result: correct: Handle mixed-case damage explicitly #37 / correct: Interpret mixed-case damage #42, already integrated into reviewability-v1; Define correction exit statuses #45 supplies the distinct exit-status contract.
• M2 — ms32 Core requirement during recovery/correction: retained as an explicit ms32 trust-boundary choice rather than silently weakened. cli: Name the real Bitcoin Core requirement when it is missing #84 / cli: Name the real Bitcoin Core requirement when it is missing #99 now names Bitcoin Core 32+/RPC, explains what Core supplies, points secret/share/correct to the Core-independent codex32 fallback, connects before damaged-seed search, stays under <5200, has current-head Codex ACK, and exact-head Python-package + Core-fixture CI are green.
• M3 — supplying S mid-recovery silently discarded shares: cli: Announce recovery secret switch #95 keeps the deliberate mode switch but announces it. The focused patch is reviewed; human rewrite/squash/integration remains.
• M4 — reviewability/narrative gap: docs: Prepare the v1 review handoff #38 owns the frozen-candidate review guide, exact commit pins, review order and final fresh adversarial review. Draft Add comprehensive codex32 CLI, correction, and wallet integration #94 is only a moving placeholder and is not the final integration PR.
• M5 — inherited Bitcoin Core contributor boilerplate: draft docs: Replace contributor boilerplate #115 is focused, CI-green and content-ACKed by Codex; responsible-human rewrite/squash is the remaining policy step.
• M6 — stale benchmark numbers: draft docs: Label benchmark evidence historical #116 labels the measurements/raw files as historical evidence tied to commit 6802d86 and directs reviewers to current CI/budget evidence. Exact-head CI is green and Codex ACKed it.
• M7 — optimized tests/correction-constant verifier absent from CI: ci: Test optimized mode and correction constants #40 is closed; current python-package.yml runs both python -O -m pytest -q and tools/verify_correction_constants.py.
• M8 — supplied-seed paths skipped BIP32-root validity: merged generation: Validate supplied BIP32 seeds #16 fixes supplied raw bytes, but did not validate an existing MasterSeed passed to CreationCeremony.from_secret. New generation: Validate existing Bitcoin roots before sharing #125 / focused generation: Validate roots before re-sharing #126 rejects an invalid BIP32 root before identifier randomness or share creation; CL secrets are unchanged. The behavioral patch passed all 953 tests normally and under python -O, Ruff, strict mypy, and fresh wheel/sdist checks. Current head 8cd584e is CI-green and has a current-head Codex ACK; human integration remains.
• M9 — threshold digit 1 differs from the BIP-93 reference decoder: accepted v1 parser divergence, not a secret-safety defect. docs: Close adversarial audit tracking gaps #127 records it in the API guide; docs: Prepare the v1 review handoff #38 requires the frozen reviewer handoff to carry that qualification.

Low / reviewability findings

• L1 — correct overloaded exit 1: cli: Define stable correct exit statuses #39 / Define correction exit statuses #45 defines stable 0/1/2/3 statuses; integrated with correct: Interpret mixed-case damage #42.
• L2 — unreachable CLI/search branches: Remove pre-review CLI dead code #46 is integrated; focused cli: Remove unreachable recovery and search paths #105 removes the remaining reviewed dead paths without behavior change.
• L3 — assert statements vanish under -O: no reproduced security failure. The release control is ci: Test optimized mode and correction constants #40's full optimized suite in CI; docs: Close adversarial audit tracking gaps #127 explicitly documents that public input/identity gates use exceptions and remaining assertions concern validated internal state. docs: Prepare the v1 review handoff #38 must call out the optimized gate in reviewer evidence.
• L4 — host-specific raw benchmark data: retained intentionally as historical evidence rather than current qualification data; docs: Label benchmark evidence historical #116 makes that status explicit.
• L5 — bespoke/nearly-full review budget: the maintainer-authorized library cap is <5200; docs: Replace contributor boilerplate #115 documents the metric/change-control contract and the existing enforcement test remains authoritative. GUI has a separate authorized cap.
• L6 — commit hygiene: final stacked AI-assisted follow-ups require responsible-human rewrite/squash under the repository AI policy; docs: Prepare the v1 review handoff #38 tracks this human-only integration step.

Tiny / edge findings

• package __all__ count: wallet: Privatize Core descriptor records #64 removes obsolete core_descriptors, sets the intended package surface to 23 names and adds regression coverage;
• Core test-double signature drift: one-line draft tests: Match Core initializer signature #117, exact-head CI-green and Codex-ACKed;
• stale MANIFEST.in provenance exclusion: fixed on current reviewability-v1 (d6a9f99);
• ignored provenance/plans: deliberate local-only unfinished work belongs under ignored docs/planning/; finished security audit material belongs under docs/security/;
• Beta classifier with 1.0.0rc1: final release metadata remains governed by Gate v1 publication on final-RC integration and built-artifact verification #5/release: Qualify exact artifacts before publish #52; no security behavior depends on this Trove label;
• stray pyproject.toml blank line: no longer present on current reviewability-v1;
• repository .codex/config.toml: removed by codex: Remove project-level agent overrides #41;
• Bitcoin Core RC documentation links: docs: Trim offline signing to what Core's tutorial lacks #93 moves the user guidance to the maintained upstream tutorial path;
• budget-test discoverability: docs: Prepare the v1 review handoff #38 requires the final reviewer guide to point directly at the enforcement tests; no runtime move is required;
• private cross-module helper imports: api: Stop requiring private vector helpers #49 / api: Expose reference-vector helpers #53 publishes the vector helpers that reviewers/users actually need and documents the remaining intentional internal couplings;
• stale sibling branch names: repository housekeeping only, not a release/security gate; do not treat those names as fix provenance.

Current release-gate disposition

The audit verdict itself is focused PR #23. Security-contract wording is #59 / #4. Exact-artifact release qualification is #52 / #5. No material validated finding from the supplied reviews now lacks a tracker or a focused fix/defer path. The newly reproduced existing-secret part of M8 is #125/#126, not already fixed by #16. #127 adds the exhaustive original/consolidated finding ledger at docs/security/adversarial-2026-10-04.md, with all numbered findings, nits, source qualifications, and explicit limitations.

Keep this umbrella open until the remaining focused PRs are human-integrated, the GUI restore delta is replayed and manually qualified, #23 is on the frozen candidate, and a fresh adversarial review covers the frozen library/CLI/GUI/user-documentation tips.

Local composed proof on 2026-10-04 applied the reviewed #99 delta to the #53 + #126 behavioral tree and #127's AST-equivalent tuple cleanup: 59 focused Core/CLI/disclosure tests passed; the library measured 5,198 logical review lines; the official Bitcoin Core 32.0rc2 regtest fixture passed (/Satoshi:32.0.0/). This is limited interaction evidence, not a frozen-candidate full-suite or GUI qualification. The downloaded archive's SHA-256 matched the official HTTPS checksum list; this run did not newly verify its PGP signature.

[BenWestgate]

report.md

[BenWestgate]

Release-gate threat-model correction: the restore ordering finding remains valid, but its v1 requirement is accident safety, not malicious-threshold-share authentication. PRs #57/#28 require the operator to identify the recovered wallet before mutation using a typed record fingerprint or the explicit no-record visual fingerprint + codex32/Bails identifier fallback. A 32-bit fingerprint is not claimed to resist deliberate grinding/replacement. The separate malicious-tampering design is #55: authenticate/decrypt the full descriptor backup and require the recovered seed to reproduce it before mutation. PR #23's audit verdict has been updated to make this separation explicit.