Implement SHA-512 integrity verification #35

New Issue

2026-01-03T23:40:30Z

KofTwentyTwo commented

2026-01-03 23:40:30 +00:00

(Migrated from github.com)

Part of #11

User Story

As a developer, I want package integrity verified so I know downloaded packages haven't been tampered with.

Design

Integrity Format

Uses Subresource Integrity (SRI) format: sha512-<base64-hash>

# In qbits.lock
packages:
  "@qrun/auth-sso":
    version: "2.0.1"
    resolved: "https://voyage.qrun.io/qbits/@qrun/auth-sso/2.0.1.tar.gz"
    integrity: "sha512-abc123def456..."

Verification Flow

Download package tarball to temp file
Compute SHA-512 hash of downloaded file
Compare with integrity field from registry/lockfile
If match: extract to vendor directory
If mismatch: delete temp file, report error, exit 7 (INTEGRITY)

Integrity File Format

# vendor/qbits/.integrity
# Generated by qctl - do not edit
@qrun/auth-sso@2.0.1 sha512-abc123def456...
@qrun/reports@1.3.0 sha512-xyz789...

Files to Create/Modify

File	Action	Description
`qctl-qbit/src/main/java/io/qrun/qctl/qbit/integrity/IntegrityVerifier.java`	Create	Hash computation and verification
`qctl-qbit/src/main/java/io/qrun/qctl/qbit/integrity/IntegrityFile.java`	Create	Read/write `.integrity` file
`qctl-qbit/src/main/java/io/qrun/qctl/qbit/vendor/PackageDownloader.java`	Modify	Integrate verification

Verify Command (Future)

qctl qbit verify              # Verify all packages
qctl qbit verify @qrun/auth   # Verify specific package

Error Messages

Integrity check failed for @qrun/auth-sso@2.0.1

Expected: sha512-abc123def456...
Got:      sha512-xyz789bad...

This could indicate:
  - Corrupted download (try again)
  - Tampered package (contact registry admin)
  - Outdated lockfile (run qbit update)

Use --skip-integrity to bypass (not recommended)

Implementation Tasks

Create IntegrityVerifier class
Implement SHA-512 hash computation for files
Implement SRI format parsing (sha512-...)
Implement SRI format generation
Create IntegrityFile for .integrity management
Integrate verification into PackageDownloader
Add --skip-integrity flag (with warning)
Clear error message on verification failure
Add unit tests for hash computation
Add unit tests for SRI parsing
Add integration test for verification flow

Acceptance Criteria

SHA-512 hash computed correctly
Verification passes for valid packages
Verification fails for corrupted/tampered packages
Clear error message with expected vs actual hash
Exit code 7 (INTEGRITY) on failure
--skip-integrity bypasses check with warning
.integrity file updated after successful download

Part of #11 ## User Story As a developer, I want package integrity verified so I know downloaded packages haven't been tampered with. ## Design ### Integrity Format Uses Subresource Integrity (SRI) format: `sha512-<base64-hash>` ```yaml # In qbits.lock packages: "@qrun/auth-sso": version: "2.0.1" resolved: "https://voyage.qrun.io/qbits/@qrun/auth-sso/2.0.1.tar.gz" integrity: "sha512-abc123def456..." ``` ### Verification Flow 1. Download package tarball to temp file 2. Compute SHA-512 hash of downloaded file 3. Compare with `integrity` field from registry/lockfile 4. If match: extract to vendor directory 5. If mismatch: delete temp file, report error, exit 7 (INTEGRITY) ### Integrity File Format ``` # vendor/qbits/.integrity # Generated by qctl - do not edit @qrun/auth-sso@2.0.1 sha512-abc123def456... @qrun/reports@1.3.0 sha512-xyz789... ``` ### Files to Create/Modify | File | Action | Description | |------|--------|-------------| | `qctl-qbit/src/main/java/io/qrun/qctl/qbit/integrity/IntegrityVerifier.java` | Create | Hash computation and verification | | `qctl-qbit/src/main/java/io/qrun/qctl/qbit/integrity/IntegrityFile.java` | Create | Read/write `.integrity` file | | `qctl-qbit/src/main/java/io/qrun/qctl/qbit/vendor/PackageDownloader.java` | Modify | Integrate verification | ### Verify Command (Future) ```bash qctl qbit verify # Verify all packages qctl qbit verify @qrun/auth # Verify specific package ``` ### Error Messages ``` Integrity check failed for @qrun/auth-sso@2.0.1 Expected: sha512-abc123def456... Got: sha512-xyz789bad... This could indicate: - Corrupted download (try again) - Tampered package (contact registry admin) - Outdated lockfile (run qbit update) Use --skip-integrity to bypass (not recommended) ``` ## Implementation Tasks - [ ] Create `IntegrityVerifier` class - [ ] Implement SHA-512 hash computation for files - [ ] Implement SRI format parsing (`sha512-...`) - [ ] Implement SRI format generation - [ ] Create `IntegrityFile` for `.integrity` management - [ ] Integrate verification into `PackageDownloader` - [ ] Add `--skip-integrity` flag (with warning) - [ ] Clear error message on verification failure - [ ] Add unit tests for hash computation - [ ] Add unit tests for SRI parsing - [ ] Add integration test for verification flow ## Acceptance Criteria - [ ] SHA-512 hash computed correctly - [ ] Verification passes for valid packages - [ ] Verification fails for corrupted/tampered packages - [ ] Clear error message with expected vs actual hash - [ ] Exit code 7 (INTEGRITY) on failure - [ ] `--skip-integrity` bypasses check with warning - [ ] `.integrity` file updated after successful download

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: QRun-IO/qctl#35