provenex-verifier 1.0.0__tar.gz

provenex_verifier-1.0.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-05-25
+
+Initial release.
+
+### Added
+
+* `verify_receipt(receipt, public_key)` returning `VerificationResult`.
+* `canonicalize(receipt)` exposed publicly so callers can audit the canonical-payload step.
+* `verify_inclusion_proof(leaf_hash, proof, tree_root, leaf_index, tree_size)` for RFC 6962 Merkle inclusion proofs.
+* `provenex-verify` CLI with stdin support and standard exit codes (0/1/2).
+* Static test vectors under `test-vectors/` plus a generator script.
+* 100% line and branch coverage on the verifier modules.
+* CI matrix across Python 3.9, 3.10, 3.11, 3.12, and 3.13.
+
+### Design notes
+
+* Ed25519 only. HMAC receipts are rejected with a clear error rather than silently accepted, because HMAC is symmetric and out of scope for third-party verification.
+* No network calls. Safe to run in air-gapped environments.
+* No dependency on `provenex-core`. The library implements the receipt-format spec directly.
+* Single runtime dependency: `cryptography` (for Ed25519 primitives).
+
+[1.0.0]: https://github.com/aoptimystic/provenex-verifier-python/releases/tag/v1.0.0

provenex_verifier-1.0.0/CODEOWNERS

@@ -0,0 +1,4 @@
+# Default owner for everything in this repo.
+# Replace with actual GitHub handles before publishing.
+
+*       @saurabh-provenex

provenex_verifier-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,65 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+**contact@provenex.ai**. All complaints will be reviewed and investigated
+promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

provenex_verifier-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing
+
+Thank you for your interest in contributing. The verifier is intentionally small: scope discipline is the project's defining property.
+
+## Ground rules
+
+1. **No new runtime dependencies.** The library depends on `cryptography` and nothing else. Proposals to add dependencies require a clear rationale and will be considered carefully.
+2. **No network access at runtime.** The library must run unmodified in an air-gapped environment.
+3. **No bidirectional dependency on `provenex-core`.** The verifier implements the receipt-format spec directly. If the spec changes, this library changes; if `provenex-core` adds an unrelated feature, this library does not.
+4. **Spec changes are major versions.** Any change that breaks a previously valid receipt requires a major version bump and a corresponding CHANGELOG entry.
+
+## Development
+
+```
+git clone https://github.com/aoptimystic/provenex-verifier-python
+cd provenex-verifier-python
+python -m pip install -e ".[test]"
+make test
+```
+
+Tests must:
+
+* Maintain 100% line and branch coverage on the `provenex_verifier` package.
+* Complete in under 5 seconds (`pytest -xvs`).
+* Pass on Python 3.9 through 3.13.
+
+## Adding a test
+
+Negative cases are first-class. Every new validation path should ship with a test for the failure mode it guards.
+
+## Pull requests
+
+* Open a PR against `main`.
+* Reference the issue or use case in the description.
+* The CI matrix must pass on all supported Python versions before merge.
+
+## Releases
+
+Releases are tagged `vX.Y.Z`, signed with Sigstore cosign, and published to PyPI with an SBOM. The first stable release is v1.0.0. See [CHANGELOG.md](CHANGELOG.md) for version history.

provenex_verifier-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saurabh Kulkarni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

provenex_verifier-1.0.0/MANIFEST.in

@@ -0,0 +1,15 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include SECURITY.md
+include CONTRIBUTING.md
+include CODE_OF_CONDUCT.md
+include CODEOWNERS
+include Makefile
+include pyproject.toml
+recursive-include provenex_verifier *.py py.typed
+recursive-include tests *.py
+recursive-include test-vectors *.py *.json *.pem *.md
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude .DS_Store

provenex_verifier-1.0.0/Makefile

@@ -0,0 +1,17 @@
+.PHONY: install test cov lint clean build
+
+install:
+	python -m pip install -e ".[test]"
+
+test:
+	pytest -xvs
+
+cov:
+	pytest --cov=provenex_verifier --cov-report=term-missing --cov-report=html
+
+clean:
+	rm -rf build dist *.egg-info .coverage htmlcov .pytest_cache
+
+build:
+	python -m pip install --upgrade build
+	python -m build

provenex_verifier-1.0.0/PKG-INFO

@@ -0,0 +1,130 @@
+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).

provenex_verifier-1.0.0/README.md

@@ -0,0 +1,98 @@
+# 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).

provenex_verifier-1.0.0/SECURITY.md

@@ -0,0 +1,49 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Email **contact@provenex.ai** with the subject line `[verifier] security`.
+
+Please include:
+
+* A description of the issue and its impact.
+* Steps to reproduce or a proof-of-concept.
+* Affected versions.
+* Your name or handle if you would like credit; otherwise we will publish the disclosure anonymously.
+
+Do **not** open public GitHub issues for security reports.
+
+## Response targets
+
+| Step | Target |
+| ---- | ------ |
+| Acknowledgement of report | 2 business days |
+| Initial triage and severity assessment | 5 business days |
+| Fix or mitigation in a tagged release | Critical: 7 days. High: 30 days. Lower: best-effort. |
+| Public disclosure | Coordinated with reporter; default 90 days after fix is shipped. |
+
+## Scope
+
+In scope:
+
+* Bugs that cause `verify_receipt` to return `valid=True` for a receipt whose signature does not match its canonical payload.
+* Bugs that cause `verify_inclusion_proof` to return `True` for an invalid proof.
+* Canonicalization mismatches that would let a producer and verifier disagree on the signed bytes.
+* Resource-exhaustion attacks reachable through public APIs (CPU, memory, file descriptors) on adversarial input.
+
+Out of scope:
+
+* Issues that require an attacker already holding the issuer's private key.
+* Policy interpretation, trajectory validation, or anything beyond cryptographic envelope verification: this library deliberately does not perform those checks.
+* Bugs in upstream `cryptography` (please report to PyCA).
+
+## Supported versions
+
+We support the latest minor release of the `1.x` line. Security fixes for older minor releases are best-effort.
+
+## Cryptographic primitives
+
+* Ed25519 via [pyca/cryptography](https://github.com/pyca/cryptography). Constant-time signature verification at the primitive level.
+* SHA-256 (stdlib `hashlib`) for RFC 6962 Merkle hashing.
+
+There is no random-number generation, no key derivation, and no symmetric encryption in this library. Public-key loading is offline (no key-fetching).

provenex_verifier-1.0.0/provenex_verifier/__init__.py

@@ -0,0 +1,33 @@
+"""Standalone verifier for Provenex receipts.
+
+Public API:
+
+    verify_receipt(receipt, public_key) -> VerificationResult
+        Verify the Ed25519 signature on a receipt.
+
+    canonicalize(receipt) -> bytes
+        Produce the canonical signed-payload bytes for a receipt.
+
+    verify_inclusion_proof(leaf_hash, proof, tree_root, leaf_index, tree_size) -> bool
+        Verify an RFC 6962 Merkle inclusion proof.
+
+    VerificationResult
+        NamedTuple returned by verify_receipt.
+
+The library has a single runtime dependency (``cryptography``) and makes no
+network calls. It is safe to run in an air-gapped environment.
+"""
+
+from .canonical import canonicalize
+from .merkle import verify_inclusion_proof
+from .verifier import VerificationResult, verify_receipt
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "VerificationResult",
+    "__version__",
+    "canonicalize",
+    "verify_inclusion_proof",
+    "verify_receipt",
+]

provenex_verifier-1.0.0/provenex_verifier/canonical.py

@@ -0,0 +1,57 @@
+"""Canonical JSON serialization for Provenex receipts.
+
+The canonical form is what gets signed. Any verifier that wants to reproduce
+the signed bytes must follow the same rules. The serialization is exposed
+publicly so callers can audit the canonicalization step independently of
+signature verification.
+
+Rules:
+
+* The ``signature`` block is stripped before serialization. Signing a receipt
+  is signing every byte of its canonical form *except* the signature itself.
+* Keys are sorted lexicographically at every level of nesting.
+* Separators are ``","`` and ``":"`` (no whitespace).
+* Non-ASCII characters (smart quotes, accented letters, CJK) are emitted as
+  raw UTF-8, not as ``\\uXXXX`` escapes. This matches the producer side and
+  keeps the form portable to non-Python verifiers.
+* ``NaN``, ``Infinity``, and ``-Infinity`` are rejected.
+
+Matches provenex-core ``ProvenanceReceipt.canonical_payload`` as of receipt
+schema 2.5.0.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Mapping
+
+
+def canonicalize(receipt: Mapping[str, Any]) -> bytes:
+    """Return the canonical signed-payload bytes for a receipt.
+
+    Args:
+        receipt: The receipt dict (typically the output of ``json.loads`` on a
+            receipt JSON file). The input is not mutated.
+
+    Returns:
+        UTF-8 encoded canonical JSON bytes, with any ``signature`` block
+        omitted.
+
+    Raises:
+        TypeError: If ``receipt`` is not a mapping, or contains values JSON
+            cannot serialize.
+        ValueError: If the receipt contains ``NaN``, ``Infinity``, or
+            ``-Infinity``.
+    """
+    if not isinstance(receipt, Mapping):
+        raise TypeError(
+            f"receipt must be a mapping (dict), got {type(receipt).__name__}"
+        )
+    payload = {k: v for k, v in receipt.items() if k != "signature"}
+    return json.dumps(
+        payload,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+        allow_nan=False,
+    ).encode("utf-8")

provenex_verifier-1.0.0/provenex_verifier/cli.py

@@ -0,0 +1,109 @@
+"""``provenex-verify`` command-line entry point.
+
+Usage::
+
+    provenex-verify <receipt.json> --public-key <key.pem>
+    cat receipt.json | provenex-verify - --public-key key.pem
+
+Exit codes:
+
+* ``0`` -- signature verified.
+* ``1`` -- signature did not verify (tampered receipt, wrong key, etc.).
+* ``2`` -- usage error (missing file, malformed JSON, bad arguments).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import List, Optional, TextIO
+
+from . import __version__
+from .verifier import verify_receipt
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="provenex-verify",
+        description=(
+            "Verify the Ed25519 signature on a Provenex receipt. "
+            "Reads receipt JSON from a file (or '-' for stdin) and an "
+            "Ed25519 public key (PEM or DER) from disk."
+        ),
+    )
+    parser.add_argument(
+        "receipt",
+        help="Path to receipt JSON file, or '-' to read from stdin.",
+    )
+    parser.add_argument(
+        "--public-key",
+        required=True,
+        help="Path to Ed25519 public key (PEM SubjectPublicKeyInfo or DER).",
+    )
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress per-field output; rely on exit code only.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"provenex-verify {__version__}",
+    )
+    return parser
+
+
+def main(
+    argv: Optional[List[str]] = None,
+    stdin: Optional[TextIO] = None,
+    stdout: Optional[TextIO] = None,
+    stderr: Optional[TextIO] = None,
+) -> int:
+    """Entry point. Returns an exit code; never raises on normal failures."""
+    stdin = stdin or sys.stdin
+    stdout = stdout or sys.stdout
+    stderr = stderr or sys.stderr
+
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        if args.receipt == "-":
+            receipt = json.load(stdin)
+        else:
+            with open(args.receipt, "r", encoding="utf-8") as fh:
+                receipt = json.load(fh)
+    except OSError as exc:
+        print(f"error: could not read receipt: {exc}", file=stderr)
+        return 2
+    except json.JSONDecodeError as exc:
+        print(f"error: receipt is not valid JSON: {exc}", file=stderr)
+        return 2
+
+    try:
+        with open(args.public_key, "rb") as fh:
+            key_bytes = fh.read()
+    except OSError as exc:
+        print(f"error: could not read public key: {exc}", file=stderr)
+        return 2
+
+    result = verify_receipt(receipt, key_bytes)
+
+    if not args.quiet:
+        print(f"valid:     {result.valid}", file=stdout)
+        print(f"signer:    {result.signer or '(missing)'}", file=stdout)
+        print(
+            f"signed_at: {result.signed_at.isoformat() if result.signed_at else '(unknown)'}",
+            file=stdout,
+        )
+        for err in result.errors:
+            print(f"error:     {err}", file=stderr)
+        for warn in result.warnings:
+            print(f"warning:   {warn}", file=stderr)
+
+    return 0 if result.valid else 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())