eve-proof 0.1.0

EVE Proof SDK — Issue and verify Governed Decision Certificates

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

pip install eve-proof

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

pip install "eve-proof[async]"

---

Quickstart

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)

{
  "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:

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.

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

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

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