Metadata-Version: 2.4
Name: proofnest
Version: 0.3.0
Summary: Verifiable AI causal accountability — not what was done, but WHY. W3C VC 2.0, SHAKE256, EU AI Act.
Project-URL: Homepage, https://proofnest.stellanium.io
Project-URL: Documentation, https://proofnest.stellanium.io/docs
Project-URL: Repository, https://github.com/stellanium/proofnest
Project-URL: Bug Tracker, https://github.com/stellanium/proofnest/issues
Author-email: Stellanium LTD <legal@stellanium.io>, Andrus Salumäe <admin@stellanium.io>
License: AGPL-3.0-only
License-File: LICENSE
Keywords: ai,audit,eu-ai-act,gdpr,post-quantum,provenance,receipt,shake256,verifiable-credentials,w3c-vc
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: hatchling; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# proofnest

Verifiable AI receipt chain — W3C VC 2.0, quantum-safe, PROOFNEST protocol.

```
pip install proofnest
```

Every AI action leaves a cryptographically linked receipt. Tamper-evident. Auditable. Yours.

---

## Quick start

```python
from proofnest import create_receipt, append_receipt, verify_chain

# Create a receipt for any AI action
receipt = create_receipt(
    action="execute",
    tool="Bash",
    input_data={"command": "ls /tmp"},
    session_id="my-session-001",
)

# Persist to local JSONL chain
append_receipt(receipt)

# Verify the entire chain
is_valid, errors = verify_chain()
assert is_valid, errors
```

---

## Claude Code hook (PostToolUse)

Add to `.claude/settings.json`:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -m proofnest.hooks"
          }
        ]
      }
    ]
  }
}
```

The hook reads tool use data from stdin and appends a W3C VC 2.0 receipt to `~/.proofnest/dogfood/chain.jsonl`.

---

## Verify chain

```bash
# Verify all links are intact
proofnest verify

# Show statistics
proofnest stats

# Tail last 5 receipts
proofnest tail ~/.proofnest/chain.jsonl 5

# Export full chain as JSON
proofnest export ~/.proofnest/chain.jsonl out.json
```

---

## Architecture

```
                       ┌─────────────────────────────┐
                       │         Your Agent           │
                       │  (Claude / GPT / Codex / ...)│
                       └────────────┬────────────────-┘
                                    │ tool_use + tool_result
                                    ▼
                       ┌─────────────────────────────┐
                       │    PROOFNEST Middleware       │
                       │  ┌────────────────────────┐  │
                       │  │  Receipt Builder        │  │
                       │  │  - W3C VC 2.0 envelope  │  │
                       │  │  - SHAKE256-256 hash    │  │
                       │  │  - ML-DSA-65 signature  │  │
                       │  │  - previousHash link    │  │
                       │  └──────────┬─────────────┘  │
                       └────────────-│────────────────-┘
                                     │
                     ┌───────────────┼───────────────┐
                     ▼               ▼               ▼
              chain.jsonl       PROOFNEST        Optional:
              (local SSOT)       Node API        Bitcoin anchor
                                (verify peer)   (OpenTimestamps)
```

Each receipt contains:

- `@context` — W3C VC 2.0 + PROOFNEST context
- `id` — `urn:proofnest:receipt:sha256:<hash>`
- `type` — `["VerifiableCredential", "ProofNestReceipt"]`
- `issuer` — DID of the agent or node
- `issuanceDate` — ISO 8601 timestamp
- `credentialSubject` — tool name, input hash, output hash, model, session ID
- `proof` — ML-DSA-65 signature + SHAKE256-256 chain hash + `previousHash`

---

## W3C VC 2.0 compliance

Receipts conform to the [W3C Verifiable Credentials Data Model 2.0](https://www.w3.org/TR/vc-data-model-2.0/) specification. Each receipt is a valid Verifiable Credential that can be verified independently by any W3C VC-compatible verifier.

---

## Quantum safety

Signatures use **ML-DSA-65** (CRYSTALS-Dilithium, NIST FIPS 204). Hashes use **SHAKE256-256** (SHA-3 family, NIST FIPS 202). Both are quantum-resistant by NIST post-quantum standards.

---

## License

AGPL-3.0-or-later. See [LICENSE](LICENSE).

Commercial licensing and hosted verification available at [proofnest.io](https://proofnest.io).

---

## Links

- Website: [proofnest.io](https://proofnest.io)
- Docs: [docs.proofnest.io](https://docs.proofnest.io)
- Repository: [github.com/proofnest/proofnest-python](https://github.com/proofnest/proofnest-python)
- Protocol spec: [proofnest.io/spec](https://proofnest.io/spec)
