provenex-verifier

Standalone, offline verifier for Provenex receipts.

A Provenex receipt is a signed JSON artifact that a regulator or third party can validate without contacting the issuing organization. This library is the reference verifier: it takes a receipt and an Ed25519 public key, and tells you whether the signature is valid over the canonical payload.

• No network. Runs in air-gapped environments. No telemetry, no analytics, no phone-home.
• No provenex-core dependency. Implements the receipt-format spec directly.
• One runtime dependency (cryptography) for Ed25519. Everything else is stdlib.
• Tiny. Under 500 lines of actual code.

Install

pip install provenex-verifier

30-second example

import json
from provenex_verifier import verify_receipt

with open("receipt.json") as fh:
    receipt = json.load(fh)
with open("issuer_public_key.pem", "rb") as fh:
    public_key = fh.read()

result = verify_receipt(receipt, public_key)

if result.valid:
    print(f"Receipt OK. Signed by {result.signer} at {result.signed_at}.")
else:
    print("Receipt INVALID:")
    for err in result.errors:
        print(f"  - {err}")

Command line

provenex-verify receipt.json --public-key issuer_public_key.pem

Exit codes: 0 valid, 1 invalid, 2 usage error. Reads from stdin if the receipt argument is -.

API

Symbol	Purpose
verify_receipt(receipt, public_key) -> VerificationResult	Verify an Ed25519 receipt signature.
VerificationResult	NamedTuple: valid, signer, signed_at, errors, warnings.
canonicalize(receipt) -> bytes	Reproduce the canonical signed-payload bytes. Exposed so callers can audit the canonicalization step independently of signature verification.
verify_inclusion_proof(leaf_hash, proof, tree_root, leaf_index, tree_size) -> bool	Verify an RFC 6962 Merkle inclusion proof.

Every public function carries an inline docstring. See the source for parameter shapes and edge-case behavior.

What this library does not do

The verifier is deliberately narrow:

• No fingerprinting, normalization, indexing, or retrieval logic.
• No policy evaluation. Receipts record decisions; this library does not re-interpret them.
• No HTTP client, no key-fetching, no TSA lookups.
• No automatic Merkle inclusion check, no trajectory walking. Those are layered on top by callers.

If you need to issue receipts, use provenex-core. This library is purely the verification half.

Algorithm support

• Ed25519 -- yes. The verifier accepts public keys in PEM (SubjectPublicKeyInfo), DER, or 32-byte raw form.
• HMAC-SHA256 -- explicitly rejected. HMAC is symmetric: anyone able to verify can forge. A third-party verifier is by definition not the producer, so HMAC receipts are out of scope. Receipts using HMAC fail with a clear unsupported signature algorithm error.

Spec compatibility

This library implements:

• Receipt schema 2.5.0 canonicalization rules (docs/receipt_format.md in provenex-core).
• RFC 6962 Merkle inclusion proofs.

Test vectors live in test-vectors/ and are versioned alongside the library. The cross-compatibility test in tests/test_merkle.py pins a proof generated by provenex-core and asserts this verifier accepts it.

Stability promise

This library is at v1.0.0 because the receipt format is. Any change that breaks a previously valid receipt is a breaking change and bumps the major version.

Security

Report vulnerabilities to contact@provenex.ai (see SECURITY.md). The library has no network surface area, but a verifier that mis-validates a tampered receipt is a security issue.

License

MIT. See LICENSE.