Metadata-Version: 2.4
Name: provenex-verifier
Version: 1.0.0
Summary: Standalone, offline verifier for Provenex receipts. Implements the receipt-format spec; no network, no telemetry, no dependencies on provenex-core.
Author-email: Provenex <contact@provenex.ai>
License: MIT
Project-URL: Homepage, https://provenex.ai
Project-URL: Source, https://github.com/aoptimystic/provenex-verifier-python
Project-URL: Issues, https://github.com/aoptimystic/provenex-verifier-python/issues
Project-URL: Documentation, https://github.com/aoptimystic/provenex-verifier-python#readme
Keywords: provenex,receipt,verifier,ed25519,merkle,rfc6962,ai-compliance,rag,llm-security
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=41.0.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Dynamic: license-file

# provenex-verifier

[![CI](https://github.com/aoptimystic/provenex-verifier-python/actions/workflows/ci.yml/badge.svg)](https://github.com/aoptimystic/provenex-verifier-python/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/provenex-verifier.svg)](https://pypi.org/project/provenex-verifier/)
[![Python](https://img.shields.io/pypi/pyversions/provenex-verifier.svg)](https://pypi.org/project/provenex-verifier/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Standalone, offline verifier for [Provenex](https://provenex.ai) 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

```python
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/`](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](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](LICENSE).
