# HX-Provenance: synthetic offline verification demo

This package contains a fictional record, a real ML-DSA-65 signed receipt binding its exact bytes, a signed evidence bundle, and the matching standalone verifiers. It was generated locally through existing HX-Provenance signing and bundle APIs. It is a synthetic mechanism demonstration, not production evidence or customer proof.

The key was created only for this demonstration. Its private bytes were held in the signing process's memory and were not saved, logged, or included here. No production signing identity or customer data was used.

## Run the demonstration

Use Python 3.11 or later. The package was generated and checked with Python 3.12. Dependencies must be installed before disconnecting; the verification itself does not require a network, appliance, API account, or HX-Provenance installation.

From this directory, create an environment and install the release-pinned dependencies:

```bash
python3 -m venv .venv
.venv/bin/python -m pip install -r verifier/requirements.txt
.venv/bin/python verify_demo.py
```

On Windows, use `.venv\Scripts\python.exe` for the environment's Python executable. The dependencies are `pqcrypto==0.4.0` and `zstandard==0.25.0`. The JSON-directory sample itself does not use zstandard, but it is included in the supplied verifier's requirements for its supported compressed-bundle format.

The runner checks `SHA256SUMS`, then invokes the actual standalone verifiers for seven cases. Expected results:

| Case | Expected result |
|---|---|
| Original receipt + original record | Valid, exit 0 |
| Original bundle + original record | Valid, exit 0 |
| Record value changed from 21 to 22 | Rejected, exit 15 |
| Signed receipt's artifact hash changed | Rejected, exit 14 |
| Receipt changed inside the bundle without changing its manifest | Rejected, exit 22 |
| Receipt checked against a different expected issuer key | Rejected, exit 13 |
| Bundle checked against a different expected issuer key | Rejected, exit 23 |

These outcomes were observed during package creation. `verification-results.json` records the actual commands, exit codes, and output. Run the checks yourself to reproduce the results.

## Run the standalone tools directly

The expected demo issuer public-key fingerprint is:

```text
d9bf869b298636bbe7ad0226b4a4063da60b2a8ca5863a9dc9ff31b1a9f7367e
```

After installing dependencies into the environment above:

```bash
.venv/bin/python verifier/verify_receipt.py \
  --receipt receipt.json \
  --public-key issuer-public.pub \
  --expected-fingerprint d9bf869b298636bbe7ad0226b4a4063da60b2a8ca5863a9dc9ff31b1a9f7367e \
  --artifact record.json

.venv/bin/python verifier/verify_bundle.py \
  --bundle evidence-bundle.jsondir --format json-dir \
  --public-key issuer-public.pub \
  --expected-fingerprint d9bf869b298636bbe7ad0226b4a4063da60b2a8ca5863a9dc9ff31b1a9f7367e \
  --artifact record.json
```

The verifier receives both the expected key and its fingerprint. A fingerprint supplied inside the same download proves only the package's internal consistency. To authenticate an intended issuer, obtain the expected fingerprint through an independently trusted publisher channel before comparing it. This demonstration key is not a production issuer identity.

## What is included

- `record.json`: a small fictional record with an example value of 21.
- `receipt.json`: a GENERIC receipt signing the record's SHA-256 and explicit demo metadata.
- `evidence-bundle.jsondir`: a JSON container with base64-encoded receipt, metadata, manifest, and manifest signature.
- `issuer-public.pub` and `issuer-fingerprint.txt`: the raw demonstration public key and its SHA-256.
- `negative/`: deliberately altered inputs and a different public key for rejection checks. These files are expected to fail verification.
- `verifier/`: exact copies of the current standalone verifier pair, requirements, and upstream instructions; their proprietary notices are preserved.
- `GENERATION.json`: generation APIs, source revision and exact source hashes, runtime versions, and scope. It identifies working source files that differ from the recorded repository revision; this package is not a production release attestation.
- `verification-results.json`: observed verification results.
- `reproduction-environment.json`: exact versions in a fresh verification environment containing no HX-Provenance package or NumPy. All seven cases also passed in that environment.
- `SHA256SUMS`: the exact package file inventory and hashes, excluding itself. This plain manifest is not a separately signed release attestation.

## Scope and limits

A successful GENERIC check proves that the artifact bytes match the signed digest and that the signature verifies under the specified key. It does not prove that a record's statement is true, that a particular customer ran a workload, or that a deployment meets performance or compliance requirements. The recorded timestamp comes from the generation host's clock; this demo does not include a trusted timestamp authority.

Verification needs only the supplied scripts and installed dependencies. Generating these artifacts used the existing product APIs; the product implementation and signing keys are not distributed in this package. See `TERMS.md` for the applicable product terms and preserved notices.