Examples

Copy, run, verify.

Every example below uses the public Avow API. The expected output is the output the project tests, not an illustration.

CLI: a release decision

pip install "avow[cli]>=0.5.3"

avow keygen --out signing.key
cat > decision.json <<'JSON'
{"release":"checkout-api 2.4.1","approved_by":"dana","tests_passed":true}
JSON
avow sign --payload decision.json --key signing.key --out receipt.json
avow verify --receipt receipt.json --public-key signing.key.pub

avow.keygen.ok
avow.sign.ok
avow.verify.ok

Give the verifier only signing.key.pub. Keep signing.key on the signing machine.

Python: library only

from avow import generate_signing_key, public_key_hex, sign_payload, verify_receipt
from avow.errors import AvowError

private_key = generate_signing_key()
public_key = public_key_hex(private_key)

receipt = sign_payload(
    {"service": "checkout-api", "decision": "approved"},
    private_key,
)
verify_receipt(receipt, expected_public_key=public_key)
print("original: verified")

altered = receipt.model_copy(
    update={"payload": {"service": "checkout-api", "decision": "rejected"}}
)
try:
    verify_receipt(altered, expected_public_key=public_key)
except AvowError as error:
    print("altered:", error.code)

original: verified
altered: avow.payload_hash_mismatch

TypeScript: sign and verify

import {
  generateSeedHex,
  publicKeyHex,
  signPayload,
  verifySignature,
} from "@gainratio/avow";

const seed = generateSeedHex();
const pinned = await publicKeyHex(seed);
const receipt = await signPayload({ artifact: "sha256:abc" }, seed);
await verifySignature(receipt, pinned);
console.log("avow.verify.ok");

verifySignature takes the public key from your configuration, never from the receipt. A receipt signed by a different key fails with the signer mismatch error.

Ledger: ordered evidence

avow ledger append --receipt receipt.json --ledger evidence.jsonl --head evidence.head
avow ledger verify --ledger evidence.jsonl --head evidence.head --public-key signing.key.pub

avow.ledger.append.ok
avow.ledger.verify.ok

The ledger adds order and a final head on top of individual receipt signatures. If an append fails after installing a head, the command exits 3 with avow.ledger_recovery_required; follow the recovery steps instead of retrying.

Tamper detection

sed 's/dana/mallory/' receipt.json > tampered.json
avow verify --receipt tampered.json --public-key signing.key.pub
echo "exit code: $?"

avow.payload_hash_mismatch
exit code: 2

Changing one character of the payload changes the canonical hash. The verifier refuses before accepting the signature, so a forger cannot reword the record and keep the original signature.

The repository contains a runnable evidence-loop example that proves the wheel outside the source tree:

bash examples/run_evidence_loop.sh

Browse all examples on GitHub · Back to documentation