Assure Python 3.13 dependencies

Carry the owner-authored bip32 Coincurve 21 range patch by exact source hash and pin every supported 3.12/3.13 Coincurve wheel. Keep Python 3.14 as a non-blocking probe because no selected native wheel exists yet.

Author: BenWestgate

.github/workflows/python-package.yml

@@ -4,20 +4,51 @@ on:
   push:
   pull_request:
 
+env:
+  SOURCE_DATE_EPOCH: "1763060600"
+
 jobs:
   test:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.12", "3.13", "3.14"]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.12", "3.13"]
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-      - run: python -m pip install -e '.[dev]'
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install --require-hashes -r requirements/cli-build-dependencies.txt
+      - run: >-
+          python -m pip install --no-build-isolation --require-hashes
+          -r requirements/cli-dependencies.txt
+      - run: python -m pip install --no-build-isolation -e '.[dev]'
+      - run: python -m pip check
       - run: python -m pytest -q
       - run: python -m mypy src/codex32
       - run: python -m ruff check .
-      - run: python -m build
+      - run: python -m ruff format --check .
+      - run: python tools/differential_correction.py --verify
+      - run: python tools/differential_wallet.py --verify
+      - run: python -m build --no-isolation
+
+  experimental-python:
+    continue-on-error: true
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install --require-hashes -r requirements/cli-build-dependencies.txt
+      - run: >-
+          python -m pip install --no-build-isolation --require-hashes
+          -r requirements/cli-dependencies.txt
+      - run: python -m pip install --no-build-isolation -e '.[dev]'
+      - run: python -m pip check
+      - run: python -m pytest -q
+      - run: python tools/differential_wallet.py --verify

MANIFEST.in

@@ -1,4 +1,5 @@
 include LICENSE README.md SECURITY.md
 recursive-include docs *.md
+recursive-include requirements *.txt
 recursive-include tests *.py *.json *.md
 recursive-include tools *.py

README.md

@@ -25,12 +25,17 @@ reviewed by someone you trust before relying on it with funds. See
 
 ## Install and test
 
-Supported Python versions are 3.12 through 3.14.
+Supported Python versions are 3.12 and 3.13. Python 3.14 remains a
+non-blocking compatibility probe until the required native wheels are
+available and the platform matrix passes.
 
 ```bash
 python -m venv .venv
 source .venv/bin/activate
-python -m pip install -e '.[dev]'
+python -m pip install --require-hashes -r requirements/cli-build-dependencies.txt
+SOURCE_DATE_EPOCH=1763060600 python -m pip install \
+  --no-build-isolation --require-hashes -r requirements/cli-dependencies.txt
+python -m pip install --no-build-isolation -e '.[dev]'
 python -m pytest -q
 python -m mypy src/codex32
 python -m ruff check .

SECURITY.md

@@ -39,9 +39,12 @@ through 64 bytes.
 - On supported terminals, a rejected entry is temporarily retained for editing.
   Automatic Readline history is disabled and this project never writes a history
   file, but terminal scrollback and Python or native editor memory may retain it.
-- `bip32>=5,<6` is a security-sensitive dependency. This project wraps it
-  narrowly and verifies BIP93 BIP32 vectors, but does not independently audit
-  its cryptographic implementation.
+- `bip32>=5,<6` and Coincurve are security-sensitive dependencies. This project
+  wraps BIP32 narrowly and verifies official BIP32 plus wallet vectors, but
+  does not independently audit their cryptographic implementations. The tested
+  CLI resolution carries upstream BIP32 PR #53 and pins Coincurve 21 wheels.
+- Python 3.12 and 3.13 are supported. Python 3.14 CI is non-blocking until the
+  selected Coincurve release has the required binary wheels.
 - Fresh unshared `ms` identifiers expose 20 bits of the BIP32 fingerprint.
   Shared sets, supplied raw seeds, re-sharing, and CL generation use random or
   explicit identifiers.

docs/accepted-risks.md

@@ -7,7 +7,7 @@ turn a checksum into authentication or remove the verification gates in the
 | ID | Risk and exposure | Disposition and controls | Review trigger |
 |---|---|---|---|
 | AR-001 | Pending BIP93 PR #2258 changes the checksum boundary for expanded HRPs. `ms` strings carrying 44--46-byte seeds can be incompatible with software implementing only the currently published BIP93 rule. | Accepted pending-standard compatibility risk. Follow the frozen PR head and boundary vectors; do not add ambiguous dual decoding. Fresh CLI generation permits only 16 or 32 bytes. The API and imported existing seeds retain all 16--64-byte BIP93 sizes. | Recheck the exact upstream revision before the RC and final release; reassess if the PR changes, closes, or merges differently. |
-| AR-002 | Root-key and wallet derivation rely on `bip32` and its native secp256k1 dependency stack, which this project does not independently audit. | Accepted architecture boundary. Keep all interaction in `_bip32.py`; retain official BIP32, BIP48, descriptor, and wallet fixtures. Gate 2 must add reproducible hash-pinned CLI constraints and cross-platform evidence. | Any resolved dependency change, adapter change, vector failure, advisory, or unsupported release artifact. |
+| AR-002 | Root-key and wallet derivation rely on `bip32` and Coincurve/libsecp256k1, which this project does not independently audit. Published `bip32` 5.0.0 metadata has a stale Coincurve `<21` limit. | Accepted architecture boundary. Keep all interaction in `_bip32.py`; retain official BIP32, BIP48, descriptor, wallet, and large differential fixtures. The tested CLI resolution carries owner-authored upstream PR #53 and hash-pins Coincurve 21 wheels for Python 3.12/3.13. Python 3.14 remains non-blocking. | Any resolved dependency or adapter change, vector failure, advisory, upstream PR change, or unsupported release artifact. |
 | AR-003 | A fresh unshared `ms` identifier reveals 20 bits of the BIP32 fingerprint. Identifiers and checksums are public metadata, not authentication. | Accepted BIP93 usability/privacy tradeoff. Shared sets, supplied raw seeds, re-sharing, and CL generation instead use random or explicit identifiers. | Any workflow starts treating an identifier as secret, unique, or proof of wallet identity. |
 | AR-004 | Python and terminal environments cannot guarantee secret zeroization, locked memory, constant-time execution, or removal from scrollback and editor memory. | Accepted implementation-platform limitation. Keep protected material out of argv and machine stdout, disable automatic line history, and document offline use. | A supported runtime or interface adds a stronger secret-memory or terminal boundary. |
 

docs/dependencies.md

@@ -1,56 +1,115 @@
 # Runtime dependency review
 
-The package has one direct runtime dependency: `bip32>=5,<6`. The compatible
-range permits bug-fix releases, but a release must record and review the exact
-resolved dependency set. A resolved-version change requires the full BIP32 and
-wallet-vector suite before publication.
+The package retains one direct runtime dependency: `bip32>=5,<6`. Only
+`src/codex32/_bip32.py` imports it. That 49-line typed adapter exposes the three
+operations this project needs and converts an invalid master scalar to
+`CodexError`. Bitcoin Core cannot replace it because Core has no interface that
+derives this project's root key or wallet records from raw seed bytes.
 
-The metadata now reserves `1.0.0rc1`; it is not authorization to publish. The
-compatible library range remains deliberate. Gate 2 must add a tested,
-hash-pinned CLI installation constraint and reconcile native wheels across
-Python 3.12--3.14 before the release candidate can be considered dependency-
-assured. Bitcoin Core cannot replace this boundary because it has no interface
-that derives this project's root key and wallet records from raw seed bytes.
+Python 3.12 and 3.13 are supported. Python 3.14 is an explicitly non-blocking
+CI probe until the selected Coincurve release publishes 3.14 wheels and the
+required platform matrix passes. It is not a v1 support claim.
 
-## Reviewed resolution
+## Reviewed Coincurve 21 resolution
 
-Reviewed on 2026-08-22 with Python 3.13 on Linux x86-64:
+The published `bip32` 5.0.0 metadata says `coincurve>=15,<21`. Upstream owner
+Antoine Poinsot's open [PR #53](https://github.com/darosior/python-bip32/pull/53)
+changes only that range to `<22` and adds Coincurve 21 to upstream CI. The CLI
+constraint carries its exact commit
+`45db547bdf5a5bc19a8c55ef447dbf9169928792`; the archive SHA-256 is
+`a25be30641b381eed9a5249bbc4a73124905223c9c50f93140f519bcf259e415`.
+The compatible library dependency remains unchanged, so this is not a local
+BIP32 fork or a change to the installed implementation.
 
-| Package | Version | Purpose |
-|---|---:|---|
-| `bip32` | 5.0.0 | BIP32 root keys, fingerprints, and path derivation |
-| `coincurve` | 20.0.0 | secp256k1 implementation selected by `bip32` |
-| `asn1crypto` | 1.5.1 | transitive `coincurve` dependency |
-| `cffi` | 2.1.1 | Python/native boundary used by `coincurve` |
-| `pycparser` | 3.0 | transitive `cffi` dependency |
+The resolution is:
 
-`bip32` 5.0.0 declares `coincurve>=15,<21`. It does not publish `py.typed` or
-type stubs. Only `src/codex32/_bip32.py` imports it; that adapter defines the
-three operations used by this project and converts its invalid-seed exception
-to `CodexError`. The rest of the package is checked by strict mypy without
-import suppression.
+| Package | Version | License | Purpose |
+|---|---:|---|---|
+| `bip32` | 5.0.0 plus PR #53 metadata | BSD-3-Clause | BIP32 private-tree derivation |
+| `coincurve` | 21.0.0 | MIT or Apache-2.0 | libsecp256k1 binding |
 
-Published `bip32` 5.0.0 artifact SHA-256 hashes:
+The installed dependency license-file SHA-256 values are:
 
-- sdist: `4caa1f74eed9f2cd4624b55f34a4094f52542552fe3d0cc52e1179b8d6e9f21e`
-- wheel: `b20872795ae2bb4e5fac351f53ccdf2b998f82e927413922a2c5473a004bd6d0`
+- BIP32 `LICENCE`: `ba32f1ce36d4b107164ff3b70f145eca686e6e5e74f9080f628545ebe9209dcc`;
+- Coincurve `LICENSE-MIT`: `d502748a33db7ade1318e37f0b5f219f478330ed74a673e387756e53fb516715`;
+- Coincurve `LICENSE-APACHE`: `cebfb5eab4eff50df87c3c5e7eb11a634d0fa32bb4b6380800f82fae606599ae`;
+- Coincurve's retained `LICENSE-cffi` notice:
+  `04b80f5b077bbed68808cfebadeb5e3523f2a8c9a96495c587bd96df1eac2a33`.
 
-The project verifies the official BIP93 BIP32 vectors, mainnet and testnet
-extended keys, BIP48 account xpubs, and public/private Bitcoin Core descriptor
-fixtures. This is dependency-boundary evidence, not an independent audit of
-`bip32`, `coincurve`, or libsecp256k1.
+Coincurve 21 removes the former runtime CFFI and ASN.1 dependencies. Its
+[release notes](https://github.com/ofek/coincurve/releases/tag/v21.0.0) record
+Python 3.13 support and libsecp256k1 0.6.0. Its CPython 3.12 and 3.13 release has
+binary wheels for Intel and ARM macOS, x86-64/ARM/i686 glibc and musl Linux,
+and AMD64/ARM64 Windows. `requirements/cli-dependencies.txt` pins every one of
+those wheel hashes and prohibits a Coincurve source build.
 
-Sources: [`bip32` on PyPI](https://pypi.org/project/bip32/) and the installed
-wheel metadata captured by the clean-environment release check.
+The BIP32 patch archive is pure Python. `requirements/cli-build-dependencies.txt`
+pins the universal Setuptools 80.9.0 wheel used to build it, and the dependency
+installation disables build isolation. A clean Python 3.13 install completed
+without a compiler and `pip check` reported no broken requirements.
+Setting `SOURCE_DATE_EPOCH=1763060600`, the upstream patch commit time, produced
+the same BIP32 wheel twice: SHA-256
+`637e98a3fc3318d29a6bf69025abe0dbe4a02f5911fabd8443b16ef4f5088176`.
+Without that environment variable, ZIP timestamps make the wheel hash vary even
+though its files are identical. CI sets it explicitly.
+
+## Compatibility evidence
+
+The Coincurve APIs used by `bip32` were inspected at tags v20.0.0 and v21.0.0:
+`PrivateKey`, its `secret` property and `add` method, plus `PublicKey`,
+`from_secret`, `combine_keys`, and `format`. Their signatures, libsecp256k1
+operations, and `ValueError` failure behavior are unchanged at this boundary.
+
+On 2026-08-24 under Python 3.13.12:
+
+- all seven upstream `bip32` tests passed with Coincurve 21, including the four
+  official private-tree BIP32 vectors and invalid extended-key cases;
+- all 499 repository tests passed with the carried patch and Coincurve 21;
+- a deterministic corpus covered all seed lengths 16--64, 64 cases per length,
+  both networks, root xprvs, BIP48 account xpubs, and all public/private Core
+  descriptors;
+- all 6,272 records matched Coincurve 20 and 21 byte for byte, with SHA-256
+  `a51c9833408bd02d8fbafc339a7d4b48ada02af655e268e0bd165040c45b0249`.
+
+`python tools/differential_wallet.py --verify` reproduces the last check. A
+resolved dependency, adapter, or vector change requires the upstream and local
+suites plus this corpus before publication.
+
+Pip-audit 2.10.1, using its PyPI advisory service on 2026-08-24, reported no
+known vulnerability for exact versions BIP32 5.0.0 and Coincurve 21.0.0. The
+local unpublished codex32 release candidate is necessarily outside that service,
+and this result is a known-advisory check rather than a cryptographic audit.
+
+## Bounded `cryptography` prototype
+
+A private-seed-only prototype using `cryptography` 50.0.0 was evaluated before
+this decision. It matched all 17 official vector path outputs and the complete
+6,272-record corpus. Five forced HMAC cases explicitly checked zero or
+out-of-range master scalars, out-of-range child tweaks, zero child scalars, and
+the valid zero-tweak case.
+
+It did not meet the replacement cut conditions:
+
+- 167 implementation lines would replace the 49-line adapter, taking the
+  installed project from 2,999 to about 3,117 physical Python lines;
+- the corpus took about 90 seconds rather than 27 seconds in this diagnostic
+  run;
+- the installed cryptography/CFFI surface was about 17 MB, compared with a
+  2.6 MB Coincurve install, and introduced CFFI plus a general OpenSSL binding;
+- cryptography 50.0.0 publishes no Intel macOS or Windows ARM wheel, while
+  Coincurve 21 covers both.
+
+The prototype proved feasibility, not a security or performance benchmark.
+Because it is neither materially smaller nor easier to audit and violates the
+line and wheel criteria, the roadmap retains `bip32` behind its narrow adapter.
 
 ## Development-tool baseline
 
 Most development tools remain compatible ranges or unpinned extras rather than
 a reproducible release environment. Ruff is pinned to 0.16.2 because it defines
 the formatting baseline. On 2026-08-24 the existing Python 3.13.12 environment
 also contained pytest 8.4.2, Hypothesis 6.165.2, mypy 2.3.0, build
-1.2.2.post1, and Twine 6.2.0. Ruff 0.16.2 reports formatting drift already
-present at the Gate 0 starting revision, despite lint passing. A mechanical
-110-column Ruff baseline reconciles that drift at 2,970 production lines; a
-100-column probe produced 3,021 and was rejected. Gate 2 must freeze the final
-cross-platform release-tool and dependency evidence.
+1.2.2.post1, and Twine 6.2.0. A mechanical 110-column Ruff baseline reconciles
+the inherited formatting at 2,970 production lines; a 100-column probe produced
+3,021 and was rejected. New code still prefers lines under 100 characters when
+that preserves readability.

docs/generation.md

@@ -34,3 +34,14 @@ Explicit output indices preserve caller order. A share count uses
 `SystemRandom.sample` over the 31 ordinary indices and preserves sample order.
 There is no entropy injection, sorting, partial-basis completion, or BIP39
 generation.
+
+## Independent Gate 2 review record
+
+The delegated standard security scan on 2026-08-24 independently reviewed the
+OS CSPRNG boundary, one-call mask sampling, unbiased u5 mapping, rejection
+sampling, CRC/zero padding, identifier policy, random distinct-index selection,
+and re-sharing. It found no medium-or-higher generation issue. Its one low
+availability finding was that a string index selector was copied and normalized
+before enforcing the 31-index maximum. Gate 0 fixed that ordering in
+`generation._indices` and added a regression through every public generation
+API. No injectable or fallback entropy source was added.

docs/production-ready-v1.md

@@ -1,7 +1,8 @@
 # Production-ready v1 completion plan
 
 Status: active implementation roadmap. The mandatory new-session scan
-precondition and Gates 0--1 passed on 2026-08-24; Gate 2 is next.
+precondition and Gates 0--1 passed on 2026-08-24; Gate 2 local work is in
+progress and its remote platform matrix remains pending.
 
 This plan turns the current reference implementation into a narrowly scoped
 real-funds release. It does not add a GUI, networking, RPC, secret storage,
@@ -216,13 +217,18 @@ Work:
   compatible library dependency range;
 - reconcile the documented and tested versions of `bip32`, coincurve, CFFI,
   libsecp256k1 bindings, and transitive dependencies;
-- run BIP32 and wallet vectors on Python 3.12--3.14 and supported Linux, macOS,
-  and Windows wheels.
-
-Do not replace `bip32` with locally implemented BIP32. Bitcoin Core currently
-has no interface that accepts raw seed bytes and returns this project's root
-key, account xpubs, or descriptors. A Core proposal belongs to a separate
-project.
+- run BIP32 and wallet vectors on Python 3.12 and 3.13 across supported Linux,
+  macOS, and Windows wheels;
+- keep Python 3.14 as a non-blocking CI probe until the selected Coincurve
+  release publishes the required wheels and the full platform matrix passes.
+
+Do not replace `bip32` merely to work around stale dependency metadata. A
+bounded `cryptography` prototype must be materially smaller and easier to audit,
+fit the 3,000-line budget, match every official vector and a large differential
+corpus, handle invalid scalars explicitly, and have wheels on every supported
+platform before replacement is reconsidered. Bitcoin Core currently has no
+interface that accepts raw seed bytes and returns this project's root key,
+account xpubs, or descriptors.
 
 Success criteria:
 
@@ -236,6 +242,16 @@ Success criteria:
 
 Dependency: Gate 1.
 
+Local evidence (2026-08-24): upstream `bip32`'s complete seven-test suite and
+all 499 project tests pass with Coincurve 21. The inspected Coincurve 20-to-21
+APIs used by `bip32` are behaviorally unchanged. A 6,272-record wallet corpus
+matches exactly under both versions. The owner-authored upstream range-only PR
+#53 is carried by exact commit and archive hash, and all published Python 3.12
+and 3.13 Coincurve wheel hashes are pinned. A bounded `cryptography` prototype
+matched the vectors and corpus but failed the size, audit-surface, performance,
+and wheel-coverage cut conditions, so the roadmap retains the narrow adapter.
+The required remote Linux/macOS/Windows matrix must pass before Gate 2 closes.
+
 ## Gate 3 -- Cuttable bounded structural correction
 
 Objective: reduce realistic transcription burden while keeping the BCH core
@@ -395,7 +411,8 @@ Required evidence:
 - extended malformed-input and fuzz campaigns;
 - clean Bitcoin Core integration from both wheel and sdist;
 - reproducible build, dependency manifest, and package-content comparison;
-- clean installation and CLI smoke tests on Python 3.12--3.14.
+- clean installation and CLI smoke tests on supported Python 3.12 and 3.13,
+  with Python 3.14 reported separately as non-blocking compatibility evidence.
 
 Release criteria: