Skip to content

docs: add binary integrity verification section (P0-4) #19

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
beonde merged 2 commits into from
May 2, 2026
Merged

docs: add binary integrity verification section (P0-4) #19

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
548f1cd
docs: add binary integrity verification section (P0-4)
beonde May 2, 2026
26d82cd
docs: clarify checksum bypass vs mismatch failure modes
beonde May 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,26 @@ 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.

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
# Bypass only when checksums.txt is unavailable (not for mismatches)
export CAPISCIO_SKIP_CHECKSUM=true
```
Comment on lines +64 to +80
Copy link
Copy Markdown
Member Author

@beonde beonde May 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 26d82cd — rewrote the section to clearly distinguish the two failure modes:\n1. Checksum mismatch (hard failure, cannot be bypassed)\n2. Checksums unavailable (can bypass with CAPISCIO_SKIP_CHECKSUM=true)


## Troubleshooting

**"Permission denied" errors:**
Expand All @@ -70,6 +90,16 @@ capiscio --wrapper-clean
**"Binary not found" or download errors:**
If you are behind a corporate firewall, ensure you can access `github.com`.

**"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

Apache-2.0
Loading