swarmfile-verify-history
swarmfile-verify-history is a standalone verifier for a project's signed commit history. It walks the commit DAG from a branch's current HEAD back toward genesis, refetching each commit object from the hub, and recomputes every hash from the commit's own facts to prove the chain hasn't been tampered with: each parent link resolves and each stored hash matches what its facts actually hash to. Every desktop installer puts it on PATH (/usr/bin, /usr/local/bin via the app bundle, or the Windows install folder).
It also verifies the hub's checkpoint signatures. Every checkpoint the hub has published for the branch is fetched and its signature checked against a public-key ring - see the trust caveat below.
It does its own minimal HTTP GETs, with no dependency on a running engine or mount, so it can run on a CI box or an audit host.
Usage#
swarmfile-verify-history \
--hub-url https://hub.swarmfile.com/orgs/org_.../projects/proj_... \
--org-id org_... \
--project-id proj_... \
--branch main \
--header 'x-swarmfile-dispatch-secret: ...'
--hub-url is the project-scoped base: the verifier appends /history/… and /metadata/… paths to it, while --org-id/--project-id are sent as headers.
Add --json for a machine-readable report.
Flags#
| Flag | Description |
|---|---|
--hub-url <URL> | Project-scoped hub base URL (required) - the project this run verifies, e.g. https://hub.swarmfile.com/orgs/org_.../projects/proj_.... |
--project-id <ID> | Project to verify (required). Sent as x-swarmfile-project-id. |
--org-id <ID> | Org id (required). Sent as x-swarmfile-org-id. |
--branch <NAME> | Branch to verify. Default main. |
--header "Key: Value" | Extra raw header, repeatable - pass whatever auth/dispatch secret this deployment requires. No auth scheme is hardcoded. |
--checkpoint-hash <HASH> | Stop walking when this commit is reached (inclusive), instead of continuing to genesis. Use when older history has been pruned server-side. |
--pin-key <PUBKEY|FILE> | Pin the hub's checkpoint-signing Ed25519 public key out-of-band (64 hex, base64, or a file path). Repeatable for key rotation. |
--json | Emit JSON instead of the human-readable report. |
What it proves - and what it doesn't#
- Structural integrity is real: every hash recomputes and every parent link resolves across the commits the hub served. That shows the chain is internally consistent, not that it is the chain the hub previously attested to.
- Signatures without
--pin-keyare checked against the key ring fetched from the same hub being audited (trust-on-first-use). That proves the checkpoints were signed by whatever key that hub currently publishes - not that the key is the hub's real one. The report says so on every run. - With
--pin-keysignatures are verified only against keys you supply out-of-band; the run fails if none is in the hub's ring, and a checkpoint signed by any other key fails. This is the mode that gives independent assurance. - A hub with no signing key configured answers
404on the key route: unpinned that is "verifiable history isn't enabled here" (informational, exit OK); with--pin-keyit is a failure.
Exit code is non-zero on any verification failure, so it is safe to gate CI on.