Implement digest verification after push #40

New Issue

2026-01-03T23:45:12Z

KofTwentyTwo commented

2026-01-03 23:45:12 +00:00

(Migrated from github.com)

Part of #13

User Story

As a developer, I want qctl to verify the image digest after push so that I can be confident the image was uploaded correctly and hasn't been tampered with.

Design

Verification Flow

1. Build image locally → compute local digest
2. Push image to registry
3. Query registry for pushed manifest
4. Compare digests
5. Fail if mismatch

Digest Format

OCI digests use algorithm:hex format:

sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4

Verification Output

Verifying image integrity...
  Local digest:  sha256:abc123def456...
  Remote digest: sha256:abc123def456...
  Status: ✓ Match

# On failure:
Verification failed!
  Local digest:  sha256:abc123def456...
  Remote digest: sha256:xyz789ghi012...
  Status: ✗ Mismatch
  
Error: Image digest verification failed. The pushed image does not match the local build.
Possible causes:
  • Network corruption during upload
  • Registry modified the image
  • Race condition with another push

Suggested actions:
  • Retry the push: qrun publish --force
  • Check registry logs for errors

Options

# Skip verification (not recommended)
qrun publish --skip-verify

# Verbose verification output
qrun publish --verify-verbose

Files to Create/Modify

File	Action	Description
`DigestVerifier.java`	Create	Compares local and remote digests
`RegistryClient.java`	Create	Queries registry for manifest
`DigestMismatchException.java`	Create	Custom exception for failures
`PublishCommand.java`	Modify	Integrate verification step

Implementation Tasks

Create DigestVerifier class
Implement local digest computation
Implement registry manifest query
Implement digest comparison
Create DigestMismatchException with details
Add retry logic on mismatch (network issues)
Add --skip-verify option
Add --verify-verbose option
Log verification details at DEBUG level
Handle registry authentication for verification
Handle registry unavailability gracefully
Add unit tests with mock registry
Add integration test with real registry

Acceptance Criteria

Digest verified after every push
Mismatch produces clear error message
Suggested actions included in error
--skip-verify bypasses verification
Retry on transient failures
Exit code 7 (INTEGRITY) on mismatch
Works with authenticated registries

Part of #13 ## User Story As a **developer**, I want qctl to verify the image digest after push so that I can be confident the image was uploaded correctly and hasn't been tampered with. ## Design ### Verification Flow ``` 1. Build image locally → compute local digest 2. Push image to registry 3. Query registry for pushed manifest 4. Compare digests 5. Fail if mismatch ``` ### Digest Format OCI digests use `algorithm:hex` format: ``` sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4 ``` ### Verification Output ``` Verifying image integrity... Local digest: sha256:abc123def456... Remote digest: sha256:abc123def456... Status: ✓ Match # On failure: Verification failed! Local digest: sha256:abc123def456... Remote digest: sha256:xyz789ghi012... Status: ✗ Mismatch Error: Image digest verification failed. The pushed image does not match the local build. Possible causes: • Network corruption during upload • Registry modified the image • Race condition with another push Suggested actions: • Retry the push: qrun publish --force • Check registry logs for errors ``` ### Options ```bash # Skip verification (not recommended) qrun publish --skip-verify # Verbose verification output qrun publish --verify-verbose ``` ## Files to Create/Modify | File | Action | Description | |------|--------|-------------| | `DigestVerifier.java` | Create | Compares local and remote digests | | `RegistryClient.java` | Create | Queries registry for manifest | | `DigestMismatchException.java` | Create | Custom exception for failures | | `PublishCommand.java` | Modify | Integrate verification step | ## Implementation Tasks - [ ] Create `DigestVerifier` class - [ ] Implement local digest computation - [ ] Implement registry manifest query - [ ] Implement digest comparison - [ ] Create `DigestMismatchException` with details - [ ] Add retry logic on mismatch (network issues) - [ ] Add `--skip-verify` option - [ ] Add `--verify-verbose` option - [ ] Log verification details at DEBUG level - [ ] Handle registry authentication for verification - [ ] Handle registry unavailability gracefully - [ ] Add unit tests with mock registry - [ ] Add integration test with real registry ## Acceptance Criteria - [ ] Digest verified after every push - [ ] Mismatch produces clear error message - [ ] Suggested actions included in error - [ ] `--skip-verify` bypasses verification - [ ] Retry on transient failures - [ ] Exit code 7 (INTEGRITY) on mismatch - [ ] Works with authenticated registries

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: QRun-IO/qctl#40