archy/docs/security/2.1-beta-esptool-v5.md

H12: esptool 5.6.0 source migration

Both reticulum-daemon/build.sh and build-esptool.sh now pin 5.6.0. Its pinned dependency declaration requires Python >=3.10 and replaces the old ecdsa dependency with cryptography. The disposable CPython 3.13.5/Linux x86_64 resolution contains 23 packages, with no ecdsa and no OSV findings. No suppression was added. This closes the retained source-dependency path; it does not replace or qualify an installed binary.

The implementation follows the upstream migration guide and supported CLI embedding API.

• Both packaged entry points share the public esptool.main(argv) adapter, reviewed-version check and actual ESP32-S3 resource check. Fatal/serial/interrupt errors retain a nonzero exit and stderr detail. The private _main IDE exception reporting hook is not initialized by the wrapper.
• The v5 stub constructor receives the real ESP32-S3 target with a closed serial object, so preflight exercises resources without opening a port. Build scripts collect esptool and esp-pylib resources/metadata; the frozen qualification script expects the new version.
• RNS 1.3.5's downloaded-runner substitution translates command/option/reset spellings while preserving offsets, paths, baud and board settings. Its actual writer exit and independent EEPROM/hash/signature checks remain required. MeshCore/Meshtastic use canonical write-flash --erase-all. Default-reset before connect and hard-reset afterward remain the upstream defaults and are tested.
• The owned adapter must install before importing esptool: new esp-pylib caches the serial enumerator. A disposable PTY test runs the real v5 loader and verifies duplicate-FD use, no pathname reopen, a single appointed inventory entry, rejection of a different device and retention of the owner's FD after borrower close.
• Piped progress is plain, newline-delimited output. The backend accepts v5 decimal percentages and legacy integer percentages; values outside 0–100 are ignored. It still captures stderr and preserves the existing conservative retry policy.

Source evidence

Receipts: /home/archipelago/Reports/21-security-credentials-20261109/esptool-v5/.

• source-tests-r2.log: 17/17 passed, real pinned v5 parser/resources/progress/ entry points and transport doubles, plus existing RNS crypto/EEPROM and negative writer fixtures. The earlier r1 records a test invocation path error, not a pass.
• inventory-tests.log: 4/4 passed, including stale pin and missing SHA refusal.
• Source UF2 self-test passes; build shell syntax and git diff --check pass.
• Backend execution is reserved for the parent isolated runner. Focused filter: mesh::flash::flashing_regression_tests; new test: accepts_v5_and_legacy_progress_without_out_of_range_percent. No backend execution was performed in this worktree.

Reproduce source checks in a disposable Python >=3.10 venv with esptool==5.6.0 and the exact runtime requirements, from reticulum-daemon/:

python -m unittest -v test_esptool_v5 test_rnode_wrapper

The updated dependency evidence lives under /home/archipelago/Reports/next-release-nine-issues-20261109/: python-resolution-linux-x86_64-r2.json, python-osv-resolved-r2.json, python-license-metadata-r2.json, python-graph-evidence-r2/, and security-inventory-qualified-r3/. Every resolved artifact SHA is verified. Unchanged licenses retain their existing exact provenance, including Reticulum's custom restrictions, RNS's exact release-tag license commit and PyInstaller's per-file terms. Nine new/changed artifacts have exact license-file hashes. The inventory has 2,498 components, 18 hashed inputs and zero missing package license declarations. Unchanged non-Python graphs were not rescanned.

Acceptance still required

No release artifact was built, installed, signed or published; no physical serial port was enumerated or flashed. Later artifact qualification must inspect actual frozen contents (including absence of ecdsa), notices and stub files, run both packaged capability/self-tests and qualify_frozen_rnode.py in the fixed runtime, and qualify the inherited FD descendant on that artifact. The recorded Python resolution is a point-in-time graph, not a transitive lock or another-platform SBOM.

Physical ESP acceptance still needs authorized Heltec v3/v4 MeshCore/Meshtastic and RNode write, reset, conservative retry/failure and post-write verification flows. v5's selected stub and hardware behavior are not proved by a mock writer. The user's prior RAK blind-fix waiver is specific to RAK and does not waive ESP acceptance. Maintainer UI/UX review of flashing progress/errors also remains separate. No broad hardware, artifact, release or security-clear claim is made.