From d47bd84577cd6107360f026dea5d309c8577a9f6 Mon Sep 17 00:00:00 2001 From: Beon de Nood Date: Sat, 2 May 2026 13:56:38 -0400 Subject: [PATCH] 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 8a8fe69..9cf20a9 100644 --- a/README.md +++ b/README.md @@ -75,6 +75,18 @@ The Node.js wrapper includes specific commands to manage the binary: | `CAPISCIO_CORE_VERSION` | Override the default core binary version (e.g., `v1.0.2`) | | `CAPISCIO_CORE_PATH` | Use a specific binary path instead of auto-downloading | +## 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:** @@ -86,6 +98,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. + ## Related Packages - **[capiscio](https://pypi.org/project/capiscio/)** - Python CLI wrapper (identical functionality)