Reference
Usage
Seal once, emit a seal and one inclusion proof per member, then verify later — fully offline and pinned to the public key. Signing and verification run locally against node:crypto.
Install
# one-line install (installs the `waxseal` binary)$ curl -fsSL https://raw.githubusercontent.com/srivtx/waxseal/main/install.sh | sh # or run once, without installing$ bunx github:srivtx/waxseal#main seal capture.wacz # add to a project as a dev dependency$ bun add -d github:srivtx/waxseal # install globally$ bun add -g github:srivtx/waxseal$ waxseal --version
Options
| Option | Description |
|---|---|
--out <file> | Output file (keygen base name; seal output path) |
--key <pem> | Private key to sign with (seal) |
-s, --seal <file> | Seal file (verify, proof-verify) |
--proofs <file> | Proofs file (seal, proof-verify) |
--path <member> | Only verify this proof (proof-verify) |
--public-key <pem|base64> | Pin the expected SPKI public key (verify) |
--root <hex> | Pin the expected Merkle root (verify, proof-verify) |
--sha256 <hex> | Member content hash for offline proof-verify |
--created-at <iso> | Fixed ISO-8601 timestamp; the same archive, key, and timestamp produce a byte-identical seal (seal) |
--write-key | With seal and no --key, save the generated key pair next to the archive (private key mode 0600); without it the generated key is ephemeral and not saved |
--member-only | Allow a re-zip instead of strict byte-for-byte verification (verify) |
--force, --yes | Overwrite existing key files (keygen) |
--json | Machine-readable output (seal, verify, proof-verify, inspect) |
-h, --help | Show this help |
-v, --version | Show the version |
Examples
# 1. create a key pair$ waxseal keygen --out archive-key # 2. seal once, emit a seal and one inclusion proof per member$ waxseal seal capture.wacz --key archive-key.pem --out capture.seal.json --proofs capture.proofs.json # 3. verify later, fully offline, pinned to the public key$ waxseal verify capture.wacz -s capture.seal.json --public-key archive-key.pub.pem # 4. prove one member against the signed root, without the archive$ waxseal proof-verify --proofs capture.proofs.json --path archive/data.warc.gz --root <hex-root> --sha256 <hex-content-hash>
Exit codes
| Code | Meaning |
|---|---|
0 | success |
1 | findings or verification failure (e.g. a tampered archive, a mismatched pin, a failed proof; verify prints FAILED) |
2 | usage or argument error (unknown option, missing required argument, invalid flag value) |
3 | I/O failure (a missing or unreadable archive, seal, key, or proofs file) |
JSON output
With --json, seal, verify, proof-verify, and inspect print one machine-readable object instead of text. For example, a successful verification of a self-signed seal:
{
"ok": true,
"root": "7ce7902d6dc6619e28496d7c717bacfbfb36bc7982b6d424d8d1f11c9218fcf7",
"reasons": [],
"added": [],
"removed": [],
"modified": [],
"signatureOk": true,
"expectedRootOk": true,
"expectedPublicKeyOk": true,
"trusted": false,
"fingerprint": "8b3e7cbe526fdb46b70f4f3a8b2a3992475febd3f02f94a27a3b9395b2d3825c"
}trusted is false until a matching --public-key or --root is supplied; reasons explains a failure and added, removed, and modified list any member mismatches.