Add offline skill bundle verification command by pbakaus · Pull Request #845 · pbakaus/impeccable

pbakaus · 2026-09-21T20:44:27Z

Users reviewing downloaded skill releases currently need a Rust test invocation to verify a bundle without installing it. Add impeccable verify-bundle universal.zip --version 4.3.1 to authenticate local assets offline using the installer's pinned Ed25519 keys and SHA-256 verifier.

The expected skill version is required. The command reads <zip>.sig.json by default, supports --signature and --json, and reports authenticated release metadata. It performs no downloads, extraction, installation, or hook changes. Missing/invalid signatures, unknown keys, altered bytes, and mismatched releases fail closed.

Includes CLI help, trust-model and offline verification documentation, regression coverage, and reviewed oracle cases. Generated provider output is intentionally omitted; no release versions are bumped.

Validation:

Focused impeccable-skills tests and cargo test --workspace pass on the isolated branch.
cargo build --release -p impeccable passes.
Full bun run test passes against the release binary on the isolated branch (core, oracle, detector, live, framework, and plugin E2E).
The PR release binary verifies the published 4.3.1 bundle. Tampered bytes and a mismatched expected version were also checked and rejected during implementation.

Related: #479.

Prepared with AI assistance from Codex under maintainer direction.

Authenticate local release bundles with the installer's pinned keys, require an expected skill version, and provide JSON audit output without extraction or installation. Prepared with AI assistance from Codex under maintainer direction.

greptile-apps · 2026-09-21T20:47:33Z

Confidence Score: 5/5

The PR appears safe to merge; the new command reuses the established verifier and reports only authenticated metadata without adding write or network behavior.

Summary

This PR adds an offline command that verifies a local skill bundle using the installer’s existing Ed25519 keyring and SHA-256 verification path.

Supports top-level and legacy skills namespace invocation.
Requires an independently supplied expected release version and fails closed for invalid signatures, unknown keys, altered bytes, and release mismatches.
Reports authenticated metadata in human-readable or JSON form without downloading, extracting, installing, or modifying hooks.
Adds command documentation, CLI contract coverage, Rust regression tests, and reviewed oracle fixtures.

Diagram

sequenceDiagram
  actor User
  participant CLI
  participant Verify as verify-bundle
  participant Sidecar as Signature sidecar
  participant Keys as Pinned keyring
  participant Bundle as Local bundle

  User->>CLI: verify-bundle bundle.zip --version X
  CLI->>Verify: Parsed paths and expected version
  Verify->>Sidecar: Read capped signature manifest
  Verify->>Keys: Resolve declared key ID
  Verify->>Verify: Verify Ed25519-signed metadata
  Verify->>Bundle: Stream bytes and compute SHA-256/size
  Verify->>Verify: Compare digest, size, artifact, and version
  alt All checks pass
    Verify-->>User: Authenticated metadata
  else Any check fails
    Verify-->>User: Error and nonzero exit
  end

_{Reviews (1) · Last reviewed commit: "Add offline skill bundle verification co..."}

Copilot

Copilot review overview

🟡 Changes recommended

Add success-path coverage for human and JSON output, and correct the misleading invalid-version error message.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1 · 1

Open (2)

Add end-to-end tests for successful human and JSON output · New
Use a local error message for invalid skill versions · New

What changed in this PR

Adds an offline impeccable verify-bundle command for authenticating local skill bundles with pinned Ed25519 and SHA-256 verification.

Changes:

Adds CLI routing, strict version parsing, human-readable and JSON output.
Returns verified signature metadata.
Adds documentation, Rust tests, and oracle coverage.

File	Reviewed change
`tests/oracle/golden/skills-verify-bundle-version-required.json`	Records missing-version output.
`tests/oracle/golden/skills-verify-bundle-namespace-help.json`	Adds namespace help output.
`tests/oracle/golden/skills-verify-bundle-help.json`	Adds command help output.
`tests/oracle/golden/cli-help.json`	Updates root CLI help.
`tests/oracle/DELTAS.md`	Records oracle changes.
`tests/oracle/cases/skills.mjs`	Adds oracle scenarios.
`docs/CLI-CONTRACT.md`	Documents CLI behavior.
`docs/BUNDLE-SIGNING.md`	Documents offline verification.
`crates/skills/tests/verify_bundle_tests.rs`	Adds command regression tests.
`crates/skills/src/verify_bundle.rs`	Implements offline verification and output.
`crates/skills/src/lib.rs`	Registers the verifier module.
`crates/skills/src/commands.rs`	Routes the skills command.
`crates/skills/src/bundle_signature.rs`	Exposes verified envelope metadata.
`crates/detect/src/lib.rs`	Updates root help text.
`crates/cli/src/main.rs`	Adds root CLI dispatch.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

+    if options.json {
+        io.out(&format!(
+            "{}\n",
+            serde_json::json!({
+                "verified": true, "version": verified.version, "artifact": verified.artifact,
+                "keyId": verified.key_id, "size": verified.size, "sha256": verified.sha256,
+            })
+        ));
+    } else {
+        io.out(&format!(
+            "Verified {} (skill-v{}).\nSigning key: {}\nSHA-256: {}\nSize: {} bytes\n",
+            verified.artifact, verified.version, verified.key_id, verified.sha256, verified.size
+        ));


+    bundle_signature::release_version(&format!(
+        "https://github.com/pbakaus/impeccable/releases/download/skill-v{version}/universal.zip"
+    ))?;


cursor

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 825176f. Configure here.}

cursor · 2026-09-21T20:49:05Z

+    // Reuse the installer's exact release-version grammar.
+    bundle_signature::release_version(&format!(
+        "https://github.com/pbakaus/impeccable/releases/download/skill-v{version}/universal.zip"
+    ))?;


Invalid version error mentions downloads

Low Severity

--version validation reuses release_version, so a bad expected version (for example a leading v) fails with a GitHub redirect message even though verify-bundle never downloads. That reads as a network failure on an offline command.

^{Reviewed by Cursor Bugbot for commit 825176f. Configure here.}

Add offline skill bundle verification command

825176f

Authenticate local release bundles with the installer's pinned keys, require an expected skill version, and provide JSON audit output without extraction or installation. Prepared with AI assistance from Codex under maintainer direction.

Copilot AI lite review requested due to automatic review settings September 21, 2026 20:44

Copilot started reviewing on behalf of pbakaus September 21, 2026 20:45 View session

Copilot AI reviewed Sep 21, 2026

View reviewed changes

cursor Bot reviewed Sep 21, 2026

View reviewed changes

github-actions Bot added blocked: review threads Unresolved review feedback or requested changes remain waiting on contributor Waiting for the PR author to respond or make changes blocked: merge conflicts PR cannot merge until conflicts are resolved labels Sep 22, 2026

Navigation Menu

Add offline skill bundle verification command - #845

Add offline skill bundle verification command#845
pbakaus wants to merge 1 commit into
mainfrom
codex/verify-bundle

pbakaus commented Sep 21, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot commented Sep 21, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

cursor Bot left a comment

Uh oh!

cursor Bot Sep 21, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

pbakaus commented Sep 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

greptile-apps Bot commented Sep 21, 2026

Confidence Score: 5/5

Summary

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Sep 21, 2026

Choose a reason for hiding this comment

Invalid version error mentions downloads

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

pbakaus commented Sep 21, 2026 •

edited

Loading