Metadata-Version: 2.4
Name: stateproof
Version: 0.3.1
Summary: Proof-carrying exact state verification for Python environments
Author: Adnan Allemon
Maintainer: Adnan Allemon
License-Expression: MIT
Project-URL: Homepage, https://github.com/adnanomar77/stateproof
Project-URL: Repository, https://github.com/adnanomar77/stateproof
Project-URL: Issues, https://github.com/adnanomar77/stateproof/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: signing
Requires-Dist: cryptography>=42; extra == "signing"
Dynamic: license-file

# StateProof

![StateProof](stateproof-logo.jpeg)


Version 0.3.0 — proof-carrying post-install Python environment exactness.

StateProof has one security property: it determines whether a selected Python directory matches an approved state. It reports `EXACT` or `NOT_EXACT`; it does not classify code as benign or malicious.

## Quick start

```bash
python -m stateproof.cli capture ./my_env --output approved.px.json
python -m stateproof.cli verify ./my_env --against approved.px.json --evidence evidence.json
python -m stateproof.cli evidence-verify ./my_env --evidence evidence.json --against approved.px.json
```

## Independent Proof of Exact State

A proof is a self-contained, canonical Merkle representation of the captured state. It includes the ordered entry set, a Merkle `state_root`, inclusion-proof paths, the manifest root, and optionally an Ed25519 signature.

```bash
python -m stateproof.cli keygen --private owner.pem --public owner.pub.pem
python -m stateproof.cli prove ./my_env --private owner.pem --output state.proof.json
python -m stateproof.cli proof-verify state.proof.json --public-key owner.pub.pem --require-signature
# PROOF_VALID
```

`PROOF_VALID` means that the proof is internally consistent and, when signed, the signature is valid. It does not claim that a different machine's files are still unchanged after the proof was produced. To assert the current machine's files are exact, run `verify` on that machine; to prove both facts, use `verify` and a signed proof.

The same flow is available as a library API:

```python
from stateproof import ProofCarryingEnvironment

proof = ProofCarryingEnvironment.create("./my_env", private_path="owner.pem")
assert ProofCarryingEnvironment.verify(proof, "owner.pub.pem", require_signature=True)
```

## Optional manifest signing

```bash
python -m stateproof.cli keygen --private owner.pem --public owner.pub.pem
python -m stateproof.cli sign approved.px.json --private owner.pem --output approved.signed.px.json
python -m stateproof.cli verify ./my_env --against approved.signed.px.json --public-key owner.pub.pem --require-signature
```

Signing is optional and requires `cryptography`: `pip install 'stateproof[signing]'`.

## Deterministic scope

The snapshot includes regular files, directories, empty directories, and symlinks below the selected root. Symlinks are recorded but never followed. Unsupported special filesystem entries and unstable scans are rejected rather than marked exact. Default cache directories are excluded.

`EXACT` means byte-for-byte equality for every registered file, with the recorded path, type, size, target, and mode matching. `NOT_EXACT` means a deterministic mismatch exists.
