Metadata-Version: 2.4
Name: onetrace-verify
Version: 0.3.0
Summary: Reference verifier for stage-receipt records -- standard library only, no dependency on onetrace
Author-email: Shamik Saha <shamik.saha.rcciit@gmail.com>
License-Expression: Apache-2.0
Project-URL: Issues, https://github.com/shamiksaharcciit-oss/onetrace-issues
Keywords: provenance,verification,stage-receipt
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: crypto
Requires-Dist: asn1crypto==1.5.1; extra == "crypto"
Requires-Dist: cffi==2.1.1; extra == "crypto"
Requires-Dist: cryptography==50.0.1; extra == "crypto"
Requires-Dist: pycparser==3.0; extra == "crypto"
Requires-Dist: rfc3161-client==1.0.9; extra == "crypto"
Requires-Dist: typing-extensions==4.16.0; python_version < "3.11" and extra == "crypto"

# onetrace-verify

The reference verifier for stage-receipt records, packaged as its own distribution. Standard
library only -- no dependency on `onetrace`, or on anything else.

That independence is not a packaging convenience. `onetrace`'s own README states plainly that
the verifier does not trust the SDK that emitted a record -- a dependency edge from this package
to `onetrace` would contradict that sentence. A stranger must be able to install this alone and
check a record produced by anything.

## Install

```
pip install onetrace-verify
```

## Use

```
onetrace-verify <run-folder>
```

or, pointed at a manifest directly:

```
onetrace-verify <run-folder>/MANIFEST.json
```

Every outcome is PASS, FAIL, or NOT-RUN-with-a-reason -- never silence. Exit status 0 means
every check that ran passed; 1 means at least one failed; 2 means NOT VERIFIED (a receipt's
own format is not implemented, and nothing failed) or refused (the manifest cannot be read, or
its chain format is not implemented), or a usage error.

For a CI gate, three options turn a missing guarantee into a FAIL (exit 1); without them nothing
changes:

```
onetrace-verify --require-signature <run-folder>                   # a valid signature, by any key
onetrace-verify --require-trusted --trust trust.json <run-folder>  # a valid signature by a key you trust
onetrace-verify --require-complete <run-folder>                    # every declared stage emitted
```

An option the verifier doesn't know, a typo such as `--require-signatures` or one from a later
version, is a usage error, exit 2, from 0.3.0. Versions before 0.3.0 ignore options they don't know
and have no gates, so a run would pass them unchecked: in CI, pin `onetrace-verify>=0.3.0` or check
`onetrace-verify --version` first.

`onetrace-verify --help` lists every option.

## What this is

This is `verify.py` and `canonicalize.py` from the `onetrace` project's own bench
(`verifier/`), repackaged under this distribution's own name and entry point -- not a rewrite,
not a copy that can drift. The check this distribution's own build verifies: installed alone,
in an environment with no `onetrace` present, it verifies the golden example run and refuses
every rejection vector, row for row identical to running `verifier/verify.py` directly from the
source repository. On a run whose manifest records `edges`, `onetrace-verify` adds rows of its own
after the bench's, each named in its output; every other row is the bench's own.

## What this package does not claim

**This sdist ships no test suite of its own.** The behaviour that matters most for a package
this small and this static -- that the vendored `verify.py`/`canonicalize.py` stay byte-identical
to their bench originals, and that an unknown manifest-level format is refused rather than
silently accepted -- is exercised thoroughly from `onetrace`'s own test suite, which imports and
runs this code directly. A separate, parallel test harness inside this package's own sdist would
duplicate that coverage without adding an independent check: both suites would be asserting the
same thing against the same file. If that duplication ever stops being true -- if this package
diverges from `onetrace`'s own tests of it, or ships logic `onetrace`'s suite does not exercise --
its own tests belong here at that point, not before.
