From 548f1cd680ce11f0cec31924bd1570af3e9c9ca8 Mon Sep 17 00:00:00 2001 From: Beon de Nood Date: Sat, 2 May 2026 13:56:34 -0400 Subject: [PATCH 1/2] docs: add binary integrity verification section (P0-4) Document the checksum verification behavior, CAPISCIO_SKIP_CHECKSUM env var, and add troubleshooting entry for checksum failures. Ref: DOCS_REMEDIATION_PLAN P0-4 Part B --- README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/README.md b/README.md index 7d16499..ee3fc45 100644 --- a/README.md +++ b/README.md @@ -59,6 +59,18 @@ The Python wrapper includes specific commands to manage the binary: - **Linux**: AMD64, ARM64 - **Windows**: AMD64 +## Binary Integrity Verification + +On first run, the wrapper downloads the capiscio-core binary and verifies its SHA-256 checksum +against the published `checksums.txt` from the GitHub release. + +If verification fails or the checksums file is unavailable: + +```bash +# Temporary bypass (not recommended for production) +export CAPISCIO_SKIP_CHECKSUM=true +``` + ## Troubleshooting **"Permission denied" errors:** @@ -70,6 +82,10 @@ capiscio --wrapper-clean **"Binary not found" or download errors:** If you are behind a corporate firewall, ensure you can access `github.com`. +**Checksum verification failures:** +If you see "Checksum verification failed", the binary integrity could not be confirmed. +This can happen with pre-release versions or network issues. See the [Binary Integrity Verification](#binary-integrity-verification) section above. + ## License Apache-2.0 From 26d82cdc6991a058f25f53c9ed93047a30f68955 Mon Sep 17 00:00:00 2001 From: Beon de Nood Date: Sat, 2 May 2026 14:12:07 -0400 Subject: [PATCH 2/2] docs: clarify checksum bypass vs mismatch failure modes Address review comment: CAPISCIO_SKIP_CHECKSUM only bypasses when checksums.txt is unavailable/missing entry. Actual checksum mismatches are hard failures that cannot be bypassed. --- README.md | 24 +++++++++++++++++++----- 1 file changed, 19 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index ee3fc45..5bf9909 100644 --- a/README.md +++ b/README.md @@ -64,10 +64,18 @@ The Python wrapper includes specific commands to manage the binary: On first run, the wrapper downloads the capiscio-core binary and verifies its SHA-256 checksum against the published `checksums.txt` from the GitHub release. -If verification fails or the checksums file is unavailable: +Two failure modes exist: + +1. **Checksum mismatch** ("Binary integrity check failed"): The downloaded file does not match + the published checksum. This indicates tampering or corruption and **cannot be bypassed**. + Delete the cached binary and retry. + +2. **Checksums unavailable** ("checksums.txt could not be fetched" or "no entry for …"): + The checksums file could not be downloaded or does not contain an entry for the platform + binary. This can happen with pre-release versions or network issues. To bypass: ```bash -# Temporary bypass (not recommended for production) +# Bypass only when checksums.txt is unavailable (not for mismatches) export CAPISCIO_SKIP_CHECKSUM=true ``` @@ -82,9 +90,15 @@ capiscio --wrapper-clean **"Binary not found" or download errors:** If you are behind a corporate firewall, ensure you can access `github.com`. -**Checksum verification failures:** -If you see "Checksum verification failed", the binary integrity could not be confirmed. -This can happen with pre-release versions or network issues. See the [Binary Integrity Verification](#binary-integrity-verification) section above. +**"Binary integrity check failed":** +The downloaded binary does not match the published checksum — this may indicate a corrupted +or tampered download. Delete the cached binary (`capiscio --wrapper-clean`) and retry. +This error **cannot** be bypassed with `CAPISCIO_SKIP_CHECKSUM`. + +**"Checksum verification failed: checksums.txt could not be fetched":** +The checksums file is unavailable (network issue or pre-release version). You can set +`CAPISCIO_SKIP_CHECKSUM=true` to proceed without verification, but only do this in +development environments. ## License