Metadata-Version: 2.4
Name: eve-proof
Version: 0.1.0
Summary: EVE Proof SDK — Issue and verify Governed Decision Certificates
Project-URL: Homepage, https://eveaicore.com
Project-URL: Documentation, https://docs.eveaicore.com/proof
Author: EVE NeuroSystems LLC
License-Expression: LicenseRef-Proprietary
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Legal Industry
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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 :: Office/Business
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: async
Requires-Dist: aiohttp>=3.8; extra == 'async'
Description-Content-Type: text/markdown

# EVE Proof SDK

**eve-proof** issues and verifies Governed Decision Certificates — HMAC-SHA256 signed,
auditable records that prove a decision passed through (or was blocked by) EVE's
governance pipeline.

Every certificate is a tamper-evident receipt your audit team can verify independently,
without calling EVE again and without trusting the issuer.

---

## Install

```bash
pip install eve-proof
```

No required runtime dependencies. Uses Python stdlib (`urllib`) only.
Optional async support via `aiohttp`:

```bash
pip install "eve-proof[async]"
```

---

## Quickstart

```python
from eve_proof import ProofClient

client = ProofClient(api_key="eve_sk_...")

# 1. Issue a signed certificate for a decision
cert = client.issue(
    decision_input={"action": "approve_wire_transfer", "amount": 125_000}
)
print(cert.certificate_id)   # cert_abc123
print(cert.decision)         # ALLOW, BLOCK, or MODIFY

# 2. Verify the certificate's signature and chain
result = client.verify(cert)
print(result.valid)          # True

# 3. Retrieve a stored certificate by ID (e.g., from an audit log)
same_cert = client.get(cert.certificate_id)

# 4. CI smoke test: issue and verify in one call
cert, result = client.issue_and_verify(
    decision_input={"action": "data_export", "user_id": "u_123"}
)
assert result.valid
```

---

## Why Proof vs CoreGuard

| Capability | eve-coreguard | eve-proof |
|---|---|---|
| Primary purpose | Block harmful AI outputs at the gate | Witness and certify decisions for audit |
| Primary buyer | AI/ML engineering teams | Compliance, audit, legal |
| Returns | Enforcement decision (ALLOWED / BLOCKED) | Signed certificate + verification result |
| Verification | Server-side, synchronous | Independent, offline-capable |
| Key question answered | "Should this AI output be allowed?" | "Can we prove what the AI decided?" |

Use **CoreGuard** when you need to gate AI output before it reaches users.
Use **Proof** when regulators, auditors, or internal compliance teams need
verifiable records of what the AI decided and why.

---

## Certificate anatomy (schema v1.1)

```json
{
  "certificate_id":   "cert_a1b2c3d4",
  "certificate_type": "governed_decision",
  "schema_version":   "1.1",
  "decision":         "BLOCK",
  "enforcement_detail": {
    "matched_vector": "v421",
    "pattern":        "airgap_ghost",
    "verdict":        "BLOCK",
    "severity":       "critical",
    "payload_hash":   "sha256:deadbeef..."
  },
  "signature":          "a1b2c3d4e5f6...",
  "signing_algorithm":  "hmac-sha256",
  "issued_at":          "2026-04-14T12:00:00Z"
}
```

Fields:

| Field | Type | Description |
|---|---|---|
| `certificate_id` | string | Globally unique certificate identifier |
| `certificate_type` | string | Always `"governed_decision"` in v1.1 |
| `schema_version` | string | Schema version (`"1.1"` is current) |
| `decision` | string | Final governance verdict: `ALLOW`, `BLOCK`, or `MODIFY` |
| `enforcement_detail.matched_vector` | string or null | Attack/policy vector ID (e.g. `"v421"`) |
| `enforcement_detail.pattern` | string or null | Human-readable pattern group name |
| `enforcement_detail.verdict` | string | Per-pillar verdict |
| `enforcement_detail.severity` | string or null | Severity (`"critical"`, `"high"`, `"medium"`, `"low"`) |
| `enforcement_detail.payload_hash` | string or null | SHA-256 of the raw input payload |
| `signature` | string | HMAC-SHA256 hex digest of the certificate payload |
| `signing_algorithm` | string | Algorithm identifier (`"hmac-sha256"`) |
| `issued_at` | string | ISO 8601 timestamp of issuance |

On a clean `ALLOW` with no enforcement pillar match, `enforcement_detail` may be `null`.

---

## Verifying a certificate from a file

An auditor who has received a certificate as JSON can verify it without
any knowledge of the original request:

```python
import json
from eve_proof import ProofClient

# Load from audit log or file
with open("cert_a1b2c3d4.json") as f:
    cert_dict = json.load(f)

client = ProofClient(
    api_key="eve_sk_...",
    raise_on_invalid=True,   # raise CertificateInvalidError if signature fails
)

from eve_proof import Certificate, CertificateInvalidError

cert = Certificate.from_dict(cert_dict)
try:
    result = client.verify(cert)
    print(f"Valid: {result.valid}")
    for check, passed in result.checks.items():
        print(f"  {check}: {'PASS' if passed else 'FAIL'}")
except CertificateInvalidError as exc:
    print(f"TAMPERED or INVALID: {exc}")
```

---

## Environment variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `EVE_PROOF_API_KEY` | Yes (for CLI) | — | Your EVE API key |
| `EVE_PROOF_BASE_URL` | No | `https://api.eveaicore.com` | API base URL; use `http://localhost:8079` for local dev |

The SDK constructor accepts `api_key` and `base_url` directly.
Environment variables are only consumed by the CLI entry point (`eve-proof-demo`)
and the example script.

---

## Error types

| Exception | When raised |
|---|---|
| `ProofError` | Base exception; also raised for auth failures (401/403), rate limits (429), and malformed requests (4xx) |
| `CertificateInvalidError` | `verify()` with `raise_on_invalid=True` and server reports invalid signature/chain |
| `CertificateNotFoundError` | `get()` when no certificate with that ID exists (HTTP 404) |
| `TransportError` | Network failure or unrecoverable 5xx after all retries exhausted |

All exceptions expose `status_code: int` (0 for non-HTTP failures).
`CertificateInvalidError` adds `reason: str`.
`CertificateNotFoundError` adds `certificate_id: str`.

```python
from eve_proof import ProofClient, CertificateNotFoundError, ProofError

client = ProofClient(api_key="eve_sk_...")

try:
    cert = client.get("cert_does_not_exist")
except CertificateNotFoundError as exc:
    print(f"Not found: {exc.certificate_id}")
except ProofError as exc:
    print(f"API error {exc.status_code}: {exc}")
```

---

## Zero runtime dependencies

`eve-proof` uses only Python stdlib (`urllib.request`, `json`, `dataclasses`,
`uuid`, `datetime`). No `requests`, `httpx`, or `pydantic` required.

Optional `aiohttp` support is available for async usage in future SDK releases.

---

## ProofClient reference

```python
class ProofClient:
    def __init__(
        self,
        api_key: str,
        base_url: str = "https://api.eveaicore.com",
        timeout: float = 30.0,
        max_retries: int = 3,
        raise_on_invalid: bool = False,
    ): ...

    def issue(
        self,
        *,
        decision_input: dict,
        policy_set: str | None = None,
        tenant_id: str | None = None,
        idempotency_key: str | None = None,
    ) -> Certificate: ...

    def verify(
        self,
        certificate: Certificate | dict,
    ) -> VerificationResult: ...

    def get(self, certificate_id: str) -> Certificate: ...

    def issue_and_verify(
        self,
        *,
        decision_input: dict,
        policy_set: str | None = None,
        tenant_id: str | None = None,
    ) -> tuple[Certificate, VerificationResult]: ...
```

The `Transport` layer retries 5xx responses with exponential backoff
(base 0.5 s, doubling per attempt). 4xx responses are never retried.

---

## CLI smoke test

```bash
export EVE_PROOF_API_KEY=eve_sk_...
export EVE_PROOF_BASE_URL=http://localhost:8079   # local dev

eve-proof-demo
```

Outputs the certificate ID, decision, enforcement detail (if any), and
per-check verification results.

---

## Support

- Documentation: https://docs.eveaicore.com/proof
- Homepage: https://eveaicore.com
