Metadata-Version: 2.4
Name: szl-openshell-receipts
Version: 0.3.2
Summary: Governed, hash-chained receipts and an independent reach-delta witness for sandboxed agent runtimes.
License: Apache-2.0
Project-URL: Homepage, https://github.com/szl-holdings/szl-openshell-receipts
Project-URL: Source, https://github.com/szl-holdings/szl-openshell-receipts
Project-URL: Issues, https://github.com/szl-holdings/szl-openshell-receipts/issues
Project-URL: Changelog, https://github.com/szl-holdings/szl-openshell-receipts/releases
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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
License-File: LICENSE
Dynamic: license-file

# szl-openshell-receipts

<!-- szl:header v1 -->
<!-- Native identity: szl-brand@4309f6fce89179331b0b3ed8c99494e76c5be256; Orbit v2 icon. -->
<p>
  <a href="https://github.com/szl-holdings">
    <img src="https://raw.githubusercontent.com/szl-holdings/szl-brand/4309f6fce89179331b0b3ed8c99494e76c5be256/kit/logos/orbit-v2/suite/szl-icon-32.svg" alt="SZL Holdings — Orbit v2" width="32" height="32" />
  </a>
</p>

**Control before action. Evidence after.**

[Product](https://a-11-oy.com) · [Proof](https://a11oy.net) · [GitHub organization](https://github.com/szl-holdings)
<!-- /szl:header -->

[![PyPI](https://img.shields.io/pypi/v/szl-openshell-receipts)](https://pypi.org/project/szl-openshell-receipts/) [![Python](https://img.shields.io/pypi/pyversions/szl-openshell-receipts)](https://pypi.org/project/szl-openshell-receipts/) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/szl-holdings/szl-openshell-receipts/badge)](https://scorecard.dev/viewer/?uri=github.com/szl-holdings/szl-openshell-receipts)

Governed, hash-chained receipts and an independent policy reach-delta witness for sandboxed agent runtimes such as NVIDIA OpenShell.

## v0.2
- `ingest-log`: parses OpenShell-style audit tokens (HTTP:* DENIED/ALLOWED, CONFIG:PROPOSED/APPROVED/REJECTED/LOADED) into receipts. Only line digests and key=value fields are kept, never raw lines.
- `delta`: SZL reach-set witness. Computes what a policy change adds and flags the four categories OpenShell's prover reasons about, using an independent simplified model.
- Link-local reach checks cover IPv4, the full IPv6 link-local range, IPv4-mapped IPv6 literals, and absolute forms of the listed metadata hostnames. This remains a literal/name witness; it does not resolve DNS or prove runtime network isolation.
- Two-witness gate: `ALLOW_ELIGIBLE` only when this witness and the supplied prover result both report nothing.
- Approval receipts bind candidate hash and a digest of the review token.
- Controls ledger (`governance/controls.json`) with doctrine labels.
- Combined multimodal digest.

Rendered policy paths are quoted YAML scalars so comment or mapping punctuation
remains part of the filename and cannot broaden the validated permissions.

## Honest status
See `governance/controls.json`. Chain, gate, approvals and multimodal digest are MEASURED by tests. Live OpenShell field mapping and credential isolation are UNKNOWN. Signing is UNAVAILABLE; receipts are UNSIGNED_HONEST. Examples are SYNTHETIC. The reach model is not the OpenShell policy schema. The observation-consistency checker below is MEASURED on synthetic fixtures only (C-08); a live export adapter is UNAVAILABLE (C-09).

## Reference: observation-consistency checker
`reference/observation_checker/` is a standalone, standard-library, zero-model checker. It reads one saved agent-run evidence bundle and reports what the records consistently support: schema validity, identity, lifecycle, attempt accounting, call budget, admission, durable acknowledgement, fresh-process restoration, separate support assessment, claim strength and current-runtime evidence. Each is a separate PASS, FAIL, UNKNOWN or NOT_APPLICABLE finding. There is no overall verdict, and a PASS grants no authority.

It is not part of the installed package. It does no network or model work, never repairs or signs anything, and does not authenticate the evidence it is given. Missing, stale or denied evidence never becomes PASS. A cancellation acknowledgement is never treated as stopped effects. The wall-clock bound is always UNKNOWN. The 20 canonical scenarios are disclosed, authored synthetic fixtures, not a benchmark. The checker contains no PentAGI or other third-party code. Read its `README.md`, `review.md` and `completion_receipt.md` for the full contract and limits.

    cd reference/observation_checker
    python -B -m unittest -v test_observation_checker.py
    python -B observation_checker.py example_bundle.json example_policy.json

`verify.py` and the `independent_review/` scripts rewrite the committed result files, so run them in a copy. CI does this on Python 3.10, 3.12 and 3.13 and requires byte-identical output. `SHA256SUMS` binds every file.

## Usage
    pip install .
    szl-openshell-receipts ingest-log examples/openshell.sample.log --policy examples/policy.readonly-audit.yaml --commit <sha> --out r.jsonl
    szl-openshell-receipts verify r.jsonl
    szl-openshell-receipts delta examples/policy.before.json examples/policy.after.json --prover-findings capability_expansion
    szl-openshell-receipts controls governance/controls.json

Study notes: `docs/STUDY.md`.

### CLI workspace containment

The CLI confines every input/output path to `--root` (default: current working
directory). Put `--root` before the subcommand. Paths with traversal components,
NUL/control characters, symlink components, or non-regular leaf files are refused.
Absolute paths are accepted only inside the selected root. Parent directories
must already exist. Output is committed through a same-directory temporary file
and atomic replacement after every input/output path passes preflight validation.

Secure file operations require POSIX directory descriptors and `O_NOFOLLOW`;
unsupported platforms fail closed. Keep the root and its directories owned by a
trusted operator. This is an I/O boundary, not an operating-system sandbox.
The policy witness normalizes repeated separators and observes symlink resolution
on the **local host**; it does not prove remote-host containment or prevent changes
after a witness result. Invalid policy paths are rejected, not repaired silently.
