Metadata-Version: 2.4
Name: qrs-replay
Version: 1.0.0rc1
Summary: Verify QRS reproducibility seals offline.
Author: Quantum Risk Systems, Inc.
License-Expression: MIT
Project-URL: Homepage, https://github.com/jordanmarkwith/qrs-replay
Project-URL: Repository, https://github.com/jordanmarkwith/qrs-replay
Project-URL: Specification, https://github.com/jordanmarkwith/qrs-seal-verification
Project-URL: Trust Center, https://app.qrsrisk.com/trust/seal-verification
Keywords: reproducibility,verification,audit,cryptography,catastrophe-modeling,transparency-log,offline
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography<46,>=42
Requires-Dist: requests<3,>=2.31
Provides-Extra: full-replay
Requires-Dist: docker<8,>=7; extra == "full-replay"
Dynamic: license-file

# qrs-replay

Verify QRS reproducibility seals offline.

## Install

```bash
pip install qrs-replay          # pre-release versions: pip install --pre qrs-replay
```

> Publication to PyPI is a gated release step. If the package is not yet
> visible on PyPI, install from a source checkout of this package directory
> instead: `pip install -e .`

## Use

```bash
# Crypto-only verification (~milliseconds; no Docker needed):
qrs-replay verify --run-id <ID> --api-token "$QRS_API_TOKEN"

# Verify a pre-downloaded seal OFFLINE (no QRS account, no token):
qrs-replay verify --seal ./seal.json

# Fully AIR-GAPPED (no network at all) — also pass the published public key:
qrs-replay verify --seal ./seal.json --public-key ./qrs-seal-key-v1.pem

# Also re-hash the original input files against the sealed input-lineage
# manifest (a file is matched by its metadata.filename or source_id):
qrs-replay verify --seal ./seal.json --inputs-dir ./inputs/

# Full bit-identical replay (Docker required; ~minutes) — install the
# 'full-replay' extra (pip install "qrs-replay[full-replay]"), then:
qrs-replay verify --run-id <ID> --api-token "$QRS_API_TOKEN" \
    --full-replay --portfolio /path/to/portfolio.json

# Verify a release-bundle meta-seal, fetching its constituent per-run
# seals from the API (needs a token):
qrs-replay verify-meta-seal --meta-seal ./engine-v1.0.0.json \
    --api-token "$QRS_API_TOKEN"

# Verify a meta-seal FULLY AIR-GAPPED — read the constituents from a
# directory of exported per-run seals (one <run_id>.json each) and pass
# the published key, so no network call is made:
qrs-replay verify-meta-seal --meta-seal ./engine-v1.0.0.json \
    --seals-dir ./seals/ --public-key ./qrs-seal-key-v1.pem

# Verify transparency-log proofs OFFLINE — "Certificate Transparency for Risk".
# Inclusion: prove a run's seal digest is committed to the public log
# (save it from GET /trust/log/proof/<run_id>):
qrs-replay logverify --inclusion ./proof.json

# Bind the inclusion proof to a real seal envelope — proves the proof is for
# THAT seal (recomputes the seal's canonical digest, fully offline):
qrs-replay logverify --inclusion ./proof.json --seal ./seal.json

# Consistency: prove the log is append-only between two checkpoints
# (save it from GET /trust/log/consistency?first=M&second=N):
qrs-replay logverify --consistency ./consistency.json
```

> **Phase 1 transparency-log checkpoints are UNSIGNED (pre-KMS).** `logverify`
> succeeds with `signed=false`: a verified proof shows the log's append-only
> structure relative to the checkpoint(s) it cites — it does **not** prove
> authoritative non-equivocation (the root is QRS-asserted until Phase 2 signs
> the tree head and Phase 3 anchors it externally) and does not attest any
> number is accurate.

> Constituent-run verification of a meta-seal otherwise requires QRS API
> access (`GET /runs/{id}/seal` per certified run). `--seals-dir` removes that
> dependency by reading exported per-run seal envelopes from a local directory;
> add `--public-key` to also skip the signing-key fetch for a fully offline run.

Save a seal for offline use from the run-detail page or `GET /runs/{id}/seal`.
The published signing key is served at
`https://api.qrsrisk.com/trust/seal-key/v1.pem` (canonical); seal payloads
advertise the `https://trust.qrsrisk.com/seal-key-v1.pem` alias, which serves
the same key once the trust host is live.

## What this verifies

Normative specification (third-party-implementable):
<https://github.com/jordanmarkwith/qrs-seal-verification>. It is also rendered
in the QRS Trust Center, alongside the friendly quickstart:
<https://app.qrsrisk.com/trust/seal-verification>.

## Exit codes

| Code | Meaning |
|------|---------|
| 0    | OK / `SEAL_VERIFIED` |
| 10   | `SEAL_NOT_FOUND` |
| 11   | `INVALID_SIGNATURE` |
| 12   | `LINEAGE_HEAD_MISMATCH` |
| 13   | `WHEEL_LOCK_MISMATCH` (full-replay only) |
| 14   | `PORTFOLIO_HASH_MISMATCH` (full-replay only) |
| 15   | `OUTPUT_HASH_MISMATCH` (full-replay only) |
| 16   | `META_SEAL_ROLLUP_MISMATCH` (verify-meta-seal only) |
| 17   | `INPUT_LINEAGE_MALFORMED` |
| 18   | `INPUT_HASH_MISMATCH` (with `--inputs-dir`) |
| 20   | `KMS_PUBLIC_KEY_UNREACHABLE` |
| 30   | `DOCKER_PULL_FAILED` (full-replay only) |
| 40   | `LOG_PROOF_MALFORMED` (logverify) |
| 41   | `LOG_INCLUSION_MISMATCH` (logverify) |
| 42   | `LOG_CONSISTENCY_MISMATCH` (logverify) |
| 43   | `LOG_DIGEST_MISMATCH` (logverify `--seal`) |

## License

MIT.
