eve-proof 0.1.0__py3-none-any.whl

eve_proof/__init__.py

@@ -0,0 +1,39 @@
+"""EVE Proof SDK — Issue and verify Governed Decision Certificates.
+
+Quickstart::
+
+    from eve_proof import ProofClient
+
+    client = ProofClient(api_key="eve_sk_...")
+
+    # Issue a certificate
+    cert = client.issue(decision_input={"action": "approve_transfer", "amount": 50000})
+
+    # Verify it
+    result = client.verify(cert)
+    assert result.valid
+
+    # Retrieve by ID later
+    same_cert = client.get(cert.certificate_id)
+"""
+
+from eve_proof.client import ProofClient
+from eve_proof.exceptions import (
+    CertificateInvalidError,
+    CertificateNotFoundError,
+    ProofError,
+    TransportError,
+)
+from eve_proof.models import Certificate, EnforcementDetail, VerificationResult
+
+__version__ = "0.1.0"
+__all__ = [
+    "ProofClient",
+    "Certificate",
+    "EnforcementDetail",
+    "VerificationResult",
+    "ProofError",
+    "CertificateInvalidError",
+    "CertificateNotFoundError",
+    "TransportError",
+]

eve_proof/cli.py

@@ -0,0 +1,71 @@
+"""Minimal CLI for EVE Proof — smoke-test the API from the command line.
+
+Usage::
+
+    EVE_PROOF_API_KEY=eve_sk_... eve-proof-demo
+    EVE_PROOF_API_KEY=eve_sk_... EVE_PROOF_BASE_URL=http://localhost:8079 eve-proof-demo
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+
+def main() -> None:
+    """Issue a demo certificate, verify it, and print both."""
+    api_key = os.environ.get("EVE_PROOF_API_KEY", "")
+    base_url = os.environ.get("EVE_PROOF_BASE_URL", "https://api.eveaicore.com")
+
+    if not api_key:
+        print(
+            "ERROR: EVE_PROOF_API_KEY environment variable is not set.\n"
+            "       Export it before running: export EVE_PROOF_API_KEY=eve_sk_...",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    # Import here so the module is importable without running any code
+    from eve_proof import ProofClient  # noqa: PLC0415
+
+    client = ProofClient(api_key=api_key, base_url=base_url)
+
+    print(f"Connecting to {base_url} ...")
+    print()
+
+    demo_input = {
+        "action": "demo_smoke_test",
+        "source": "eve-proof-demo",
+        "note": "CLI smoke test — not a real decision",
+    }
+
+    print("Issuing certificate ...")
+    cert, result = client.issue_and_verify(decision_input=demo_input)
+
+    print(f"Certificate ID  : {cert.certificate_id}")
+    print(f"Decision        : {cert.decision}")
+    print(f"Schema version  : {cert.schema_version}")
+    print(f"Issued at       : {cert.issued_at}")
+    print(f"Signature       : {cert.signature[:24]}...")
+    print()
+
+    if cert.enforcement_detail:
+        ed = cert.enforcement_detail
+        print(f"Enforcement     : verdict={ed.verdict}, severity={ed.severity}")
+        if ed.matched_vector:
+            print(f"  Matched vector: {ed.matched_vector}")
+        if ed.pattern:
+            print(f"  Pattern       : {ed.pattern}")
+        print()
+
+    print(f"Verification    : valid={result.valid}")
+    if result.checks:
+        for check, passed in result.checks.items():
+            status = "PASS" if passed else "FAIL"
+            print(f"  {check}: {status}")
+    if not result.valid and result.reason:
+        print(f"  Reason: {result.reason}")
+
+    print()
+    print("Done.")

eve_proof/client.py

@@ -0,0 +1,320 @@
+"""EVE Proof client — issue and verify Governed Decision Certificates.
+
+Usage::
+
+    from eve_proof import ProofClient
+
+    client = ProofClient(api_key="eve_sk_...")
+
+    # Issue a signed certificate for any decision
+    cert = client.issue(decision_input={"action": "approve_transfer", "amount": 50000})
+
+    # Verify the certificate (typically done by the auditor, not the issuer)
+    result = client.verify(cert)
+    print(result.valid)     # True
+
+    # Retrieve a stored certificate by ID (e.g., from an audit log)
+    cert2 = client.get(cert.certificate_id)
+
+    # One-shot round-trip for CI smoke tests
+    cert, result = client.issue_and_verify(
+        decision_input={"action": "data_export", "user_id": "u_123"}
+    )
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional, Tuple
+
+from eve_proof.exceptions import (
+    CertificateInvalidError,
+    CertificateNotFoundError,
+    ProofError,
+)
+from eve_proof.models import Certificate, VerificationResult
+from eve_proof.transport import Transport
+
+
+class ProofClient:
+    """Client for the EVE Proof Decision Certification API.
+
+    EVE Proof wraps three backend endpoints that issue, verify, and retrieve
+    Governed Decision Certificates — HMAC-SHA256 signed records that prove a
+    decision passed through (or was blocked by) EVE's governance pipeline.
+
+    Certificates are the primary artifact for audit teams, compliance officers,
+    and regulators who need verifiable evidence of AI decision governance.
+
+    Args:
+        api_key:          EVE API key (format: ``eve_sk_...`` or ``eve_...``).
+        base_url:         Base URL of the EVE API. Defaults to the production
+                          endpoint. Set to ``http://localhost:8079`` for local
+                          development.
+        timeout:          Per-request timeout in seconds (default 30).
+        max_retries:      Retry attempts for 5xx server errors (default 3).
+        raise_on_invalid: If ``True``, ``verify()`` raises
+                          ``CertificateInvalidError`` when the server reports
+                          the certificate as invalid instead of returning a
+                          ``VerificationResult`` with ``valid=False``.
+
+    Raises:
+        ProofError: If ``api_key`` is empty.
+    """
+
+    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,
+    ) -> None:
+        if not api_key:
+            raise ProofError("api_key is required")
+        self._transport = Transport(
+            base_url=base_url,
+            api_key=api_key,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._raise_on_invalid = raise_on_invalid
+
+    # ------------------------------------------------------------------
+    # Core operations
+    # ------------------------------------------------------------------
+
+    def issue(
+        self,
+        *,
+        decision_input: Dict[str, Any],
+        policy_set: Optional[str] = None,
+        tenant_id: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Certificate:
+        """Issue a Governed Decision Certificate for a decision.
+
+        Sends the ``decision_input`` payload to the governance pipeline.
+        The backend evaluates it against enforcement pillars, records the
+        verdict, and returns a signed certificate containing the decision
+        outcome, enforcement detail, and HMAC-SHA256 signature.
+
+        This wraps ``POST /api/tve/governed-generate``.
+
+        Args:
+            decision_input:   The decision payload to certify.  At minimum
+                              include an ``action`` or ``type`` key.  Any
+                              domain-specific fields (``amount``, ``user_id``,
+                              ``resource``, etc.) are passed through to the
+                              enforcement engine.
+            policy_set:       Optional policy pack name to evaluate against
+                              (e.g. ``"lending_v1"``).  Defaults to the
+                              server's configured default when omitted.
+            tenant_id:        Optional tenant/organization identifier for
+                              multi-tenant deployments.
+            idempotency_key:  Optional idempotency key.  If provided and a
+                              certificate was already issued for this key, the
+                              server returns the existing certificate without
+                              re-running enforcement.  Auto-generated UUID
+                              when omitted.
+
+        Returns:
+            A ``Certificate`` instance with the signed governance decision.
+
+        Raises:
+            ProofError:      On server errors or invalid request parameters.
+            TransportError:  On network failures after retries are exhausted.
+        """
+        # The governed-generate endpoint requires a top-level `prompt` string.
+        # Callers pass a structured `decision_input` for readability; we
+        # flatten it to the wire format the backend expects:
+        #   - `prompt` lifted to the top level (from `decision_input["prompt"]`,
+        #     `decision_input["content"]`, `decision_input["action"]`, or a
+        #     JSON-serialized decision_input as a last-resort fallback)
+        #   - remaining fields passed under `_context` so the server can still
+        #     see the structured payload in audit records.
+        import json as _json
+        prompt_text = (
+            decision_input.get("prompt")
+            or decision_input.get("content")
+            or decision_input.get("action")
+        )
+        if not prompt_text:
+            # Structured decision with no obvious text field — serialize so the
+            # governance pipeline has SOMETHING to evaluate. Callers can always
+            # pass `decision_input={"prompt": "..."}` for full control.
+            prompt_text = _json.dumps(decision_input, sort_keys=True)
+
+        # Everything else goes into context, excluding the key we lifted.
+        context: Dict[str, Any] = {
+            k: v for k, v in decision_input.items()
+            if k not in ("prompt", "content", "action")
+        }
+
+        body: Dict[str, Any] = {
+            "prompt": prompt_text,
+            "idempotency_key": idempotency_key or str(uuid.uuid4()),
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        }
+        if context:
+            body["_context"] = context
+        if policy_set is not None:
+            body["policy_set"] = policy_set
+        if tenant_id is not None:
+            body["tenant_id"] = tenant_id
+
+        resp = self._transport.post("/api/tve/governed-generate", body)
+        # Accept either shape:
+        #   (a) Bare certificate dict (legacy / test fixtures):
+        #       {"certificate_id": "...", "signature": "...", ...}
+        #   (b) Full governance response with cert nested (live backend):
+        #       {"veto": true, "decision_certificate": {...}, "evidence": [...]}
+        if not isinstance(resp, dict):
+            from eve_proof.exceptions import ProofError
+            raise ProofError("Unexpected response shape from governed-generate")
+
+        if "certificate_id" in resp:
+            cert_payload = resp  # shape (a)
+        elif "decision_certificate" in resp and isinstance(resp["decision_certificate"], dict):
+            cert_payload = resp["decision_certificate"]  # shape (b)
+        else:
+            from eve_proof.exceptions import ProofError
+            raise ProofError(
+                "No certificate issued: the governance layer passed the decision "
+                "without emitting an enforcement certificate. Certificates are "
+                "currently issued on enforcement paths (BLOCK / MODIFY). "
+                "See /proof docs for details."
+            )
+        return Certificate.from_dict(cert_payload)
+
+    def verify(
+        self,
+        certificate: "Certificate | Dict[str, Any]",
+    ) -> VerificationResult:
+        """Verify a certificate's signature and chain integrity.
+
+        Sends the certificate (or its raw dict representation) to
+        ``POST /api/tve/verify-attestation`` and returns a structured
+        verification result.
+
+        If ``raise_on_invalid=True`` was set on the client and the server
+        reports the certificate as invalid, ``CertificateInvalidError`` is
+        raised instead of returning a result with ``valid=False``.
+
+        This wraps ``POST /api/tve/verify-attestation``.
+
+        Args:
+            certificate: Either a ``Certificate`` instance (returned by
+                         ``issue()`` or ``get()``) or a raw dict such as one
+                         parsed from a stored JSON audit record.
+
+        Returns:
+            A ``VerificationResult`` with ``valid``, individual ``checks``,
+            and an optional failure ``reason``.
+
+        Raises:
+            CertificateInvalidError: If ``raise_on_invalid=True`` and the
+                                     certificate fails verification.
+            ProofError:              On server errors.
+            TransportError:          On network failures.
+        """
+        # The verify endpoint expects the cert wrapped under
+        # `decision_certificate`. Accept callers passing either a Certificate
+        # instance, a raw cert dict, or an already-wrapped payload.
+        if isinstance(certificate, Certificate):
+            cert_dict = certificate.raw
+        elif isinstance(certificate, dict) and "decision_certificate" in certificate:
+            cert_dict = certificate["decision_certificate"]
+        elif isinstance(certificate, dict):
+            cert_dict = certificate
+        else:
+            from eve_proof.exceptions import ProofError
+            raise ProofError("verify() expects a Certificate or dict")
+
+        payload: Dict[str, Any] = {"decision_certificate": cert_dict}
+        resp = self._transport.post("/api/tve/verify-attestation", payload)
+        result = VerificationResult.from_dict(resp)
+
+        if self._raise_on_invalid and not result.valid:
+            raise CertificateInvalidError(
+                f"Certificate {result.certificate_id!r} failed verification: "
+                f"{result.reason or 'unknown reason'}",
+                reason=result.reason or "",
+            )
+
+        return result
+
+    def get(self, certificate_id: str) -> Certificate:
+        """Retrieve a stored certificate by its ID.
+
+        This wraps ``GET /api/tve/certificates/{certificate_id}``.
+
+        Args:
+            certificate_id: The certificate identifier as returned in
+                            ``Certificate.certificate_id``.
+
+        Returns:
+            The ``Certificate`` stored on the server.
+
+        Raises:
+            CertificateNotFoundError: If no certificate with the given ID
+                                      exists on the server (HTTP 404).
+            ProofError:               On other server errors.
+            TransportError:           On network failures.
+        """
+        try:
+            resp = self._transport.get(f"/api/tve/certificates/{certificate_id}")
+        except ProofError as exc:
+            if exc.status_code == 404:
+                raise CertificateNotFoundError(certificate_id) from exc
+            raise
+        return Certificate.from_dict(resp)
+
+    # ------------------------------------------------------------------
+    # Convenience
+    # ------------------------------------------------------------------
+
+    def issue_and_verify(
+        self,
+        *,
+        decision_input: Dict[str, Any],
+        policy_set: Optional[str] = None,
+        tenant_id: Optional[str] = None,
+    ) -> Tuple[Certificate, VerificationResult]:
+        """Issue a certificate and immediately verify it.
+
+        This is the recommended pattern for CI smoke tests and integration
+        health checks — it exercises the full round-trip (issue, sign,
+        verify) in one call.
+
+        Note: ``raise_on_invalid`` on the client does NOT apply here.
+        ``VerificationResult.valid`` will always be returned so callers can
+        inspect the result and decide how to handle failures.
+
+        Args:
+            decision_input: The decision payload to certify.
+            policy_set:     Optional policy pack name.
+            tenant_id:      Optional tenant identifier.
+
+        Returns:
+            A tuple of ``(Certificate, VerificationResult)``.  Inspect
+            ``result.valid`` to confirm end-to-end integrity.
+
+        Raises:
+            ProofError:      On server errors during either operation.
+            TransportError:  On network failures.
+        """
+        cert = self.issue(
+            decision_input=decision_input,
+            policy_set=policy_set,
+            tenant_id=tenant_id,
+        )
+        # Bypass raise_on_invalid so callers always get both objects
+        original_flag = self._raise_on_invalid
+        object.__setattr__(self, "_raise_on_invalid", False)
+        try:
+            result = self.verify(cert)
+        finally:
+            object.__setattr__(self, "_raise_on_invalid", original_flag)
+        return cert, result

eve_proof/exceptions.py

@@ -0,0 +1,53 @@
+"""Exception hierarchy for the EVE Proof SDK."""
+
+from __future__ import annotations
+
+
+class ProofError(Exception):
+    """Base exception for all EVE Proof SDK errors.
+
+    Attributes:
+        status_code: HTTP status code returned by the server, or 0 for
+            transport-level failures.
+    """
+
+    def __init__(self, message: str, status_code: int = 0):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class CertificateInvalidError(ProofError):
+    """A certificate failed signature or chain verification.
+
+    Raised by ``ProofClient.verify()`` when ``raise_on_invalid=True`` and
+    the server reports the certificate as invalid.
+
+    Attributes:
+        reason: The failure explanation returned by the verification endpoint.
+    """
+
+    def __init__(self, message: str, reason: str = ""):
+        super().__init__(message, status_code=0)
+        self.reason = reason
+
+
+class CertificateNotFoundError(ProofError):
+    """No certificate with the given ID was found on the server.
+
+    Raised by ``ProofClient.get()`` when the server returns HTTP 404.
+    """
+
+    def __init__(self, certificate_id: str):
+        super().__init__(
+            f"Certificate not found: {certificate_id!r}",
+            status_code=404,
+        )
+        self.certificate_id = certificate_id
+
+
+class TransportError(ProofError):
+    """A network or HTTP-level error occurred.
+
+    Raised for connection failures and unrecoverable 5xx responses after
+    all retry attempts are exhausted.
+    """

eve_proof/models.py

@@ -0,0 +1,180 @@
+"""Data models for EVE Proof SDK.
+
+All models are frozen dataclasses with ``__slots__`` for memory efficiency.
+They are constructed via ``from_dict()`` classmethods that tolerate missing
+fields by substituting ``None``, so the SDK degrades gracefully when the
+server adds new fields or omits optional ones.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+
+@dataclass(frozen=True, slots=True)
+class EnforcementDetail:
+    """Structured record of which enforcement pillar acted on this decision.
+
+    Populated for BLOCK and MODIFY verdicts; may be ``None`` on clean ALLOW.
+
+    Attributes:
+        matched_vector: Attack or policy vector identifier (e.g. ``"v421"``).
+        pattern:        Human-readable name of the matched pattern group.
+        verdict:        Enforcement verdict string (``"BLOCK"``, ``"ALLOW"``, etc.).
+        severity:       Severity classification (``"critical"``, ``"high"``, etc.).
+        payload_hash:   SHA-256 hash of the raw input payload at enforcement time.
+    """
+
+    matched_vector: Optional[str]
+    pattern: Optional[str]
+    verdict: str
+    severity: Optional[str]
+    payload_hash: Optional[str]
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "EnforcementDetail":
+        """Parse an enforcement_detail block from the certificate payload."""
+        return cls(
+            matched_vector=d.get("matched_vector"),
+            pattern=d.get("pattern"),
+            verdict=d.get("verdict", "UNKNOWN"),
+            severity=d.get("severity"),
+            payload_hash=d.get("payload_hash"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Certificate:
+    """A Governed Decision Certificate (schema v1.1).
+
+    Certificates are HMAC-SHA256 signed records that prove a specific
+    decision passed through (or was blocked by) EVE's governance pipeline.
+    They are the primary artifact for audit and compliance purposes.
+
+    Attributes:
+        certificate_id:    Globally unique certificate identifier.
+        certificate_type:  Category of certificate (e.g. ``"governed_decision"``).
+        schema_version:    Certificate schema version (``"1.1"`` for current).
+        decision:          Final governance verdict (``"ALLOW"``, ``"BLOCK"``,
+                           ``"MODIFY"``).
+        enforcement_detail: Structured enforcement metadata; ``None`` when the
+                           decision was a clean ALLOW with no pillar match.
+        signature:         HMAC-SHA256 hex digest of the certificate payload.
+        signing_algorithm: Algorithm used for the signature (``"hmac-sha256"``).
+        issued_at:         ISO 8601 timestamp of certificate issuance.
+        raw:               The full server response dict, preserved for any
+                           fields not represented by named attributes.
+    """
+
+    certificate_id: str
+    certificate_type: str
+    schema_version: str
+    decision: str
+    enforcement_detail: Optional[EnforcementDetail]
+    signature: str
+    signing_algorithm: str
+    issued_at: str
+    raw: Dict[str, Any] = field(hash=False, compare=False)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Certificate":
+        """Parse a certificate from the backend JSON response.
+
+        Tolerates missing fields by substituting sensible defaults or ``None``.
+        The original dict is stored in ``raw`` so callers can access any extra
+        fields the server may return in future schema versions.
+
+        Args:
+            d: Raw dict from the ``/api/tve/governed-generate`` or
+               ``/api/tve/certificates/{id}`` response.
+
+        Returns:
+            A fully populated ``Certificate`` instance.
+        """
+        # The certificate payload may be nested under a "certificate" key
+        # or returned flat — handle both.
+        payload = d.get("certificate", d)
+
+        raw_detail = payload.get("enforcement_detail")
+        enforcement_detail: Optional[EnforcementDetail] = (
+            EnforcementDetail.from_dict(raw_detail)
+            if isinstance(raw_detail, dict)
+            else None
+        )
+
+        return cls(
+            certificate_id=payload.get("certificate_id", ""),
+            certificate_type=payload.get("certificate_type", "governed_decision"),
+            schema_version=payload.get("schema_version", "1.1"),
+            decision=payload.get("decision", "UNKNOWN"),
+            enforcement_detail=enforcement_detail,
+            signature=payload.get("signature", ""),
+            signing_algorithm=payload.get("signing_algorithm", "hmac-sha256"),
+            issued_at=payload.get("issued_at", ""),
+            raw=d,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class VerificationResult:
+    """Result of a certificate verification request.
+
+    Attributes:
+        valid:          ``True`` if the certificate signature and chain are
+                        intact; ``False`` if any check failed.
+        certificate_id: The certificate that was verified.
+        verdict:        The decision recorded in the certificate (echoed from
+                        the cert for convenience).
+        checks:         Dict of individual verification check names to their
+                        boolean outcomes (e.g. ``{"signature": True,
+                        "chain": True, "schema": True}``).
+        reason:         Human-readable explanation when ``valid`` is ``False``;
+                        ``None`` on success.
+    """
+
+    valid: bool
+    certificate_id: str
+    verdict: str
+    checks: Dict[str, Any]
+    reason: Optional[str]
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "VerificationResult":
+        """Parse a verification response from ``/api/tve/verify-attestation``.
+
+        The backend signals success via either:
+          - a top-level ``valid: true`` boolean (legacy shape), OR
+          - a ``verdict`` string starting with ``"VALID"`` plus ALL ``checks``
+            entries reporting ``status: "PASS"`` (live shape).
+        """
+        verdict = d.get("verdict", "UNKNOWN")
+        checks = d.get("checks", [])
+
+        # Primary: honour explicit boolean if present.
+        if "valid" in d:
+            valid = bool(d.get("valid"))
+        else:
+            # Fallback: derive from verdict string + per-check statuses.
+            verdict_says_valid = isinstance(verdict, str) and verdict.upper().startswith("VALID")
+            checks_all_pass = True
+            if isinstance(checks, list):
+                for c in checks:
+                    if isinstance(c, dict) and c.get("status") != "PASS":
+                        checks_all_pass = False
+                        break
+            elif isinstance(checks, dict):
+                # Dict-shaped checks: treat non-"PASS" values as failure.
+                checks_all_pass = all(
+                    (v == "PASS") or (isinstance(v, dict) and v.get("status") == "PASS")
+                    for v in checks.values()
+                )
+            valid = verdict_says_valid and checks_all_pass
+
+        return cls(
+            valid=valid,
+            certificate_id=d.get("certificate_id", ""),
+            verdict=verdict,
+            checks=checks,
+            reason=d.get("reason") or d.get("error"),
+        )

eve_proof/transport.py

@@ -0,0 +1,176 @@
+"""HTTP transport for the EVE Proof SDK.
+
+Uses Python stdlib only (``urllib.request``).  No third-party dependencies
+are required for synchronous usage.
+
+Retry policy:
+    5xx responses are retried with exponential backoff (base 0.5 s, doubles
+    per attempt).  4xx responses are never retried — they represent caller
+    errors.  ``TransportError`` is raised when all retry attempts are
+    exhausted or a connection-level failure occurs.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Dict, Optional, Tuple
+
+from eve_proof.exceptions import ProofError, TransportError
+
+logger = logging.getLogger("eve_proof")
+
+_RETRYABLE_STATUS = frozenset({500, 502, 503, 504})
+_USER_AGENT = "eve-proof-python/0.1.0"
+
+
+class Transport:
+    """Synchronous HTTP transport using ``urllib`` (stdlib-only).
+
+    Args:
+        base_url:     Root URL of the EVE API (scheme + host, no trailing slash).
+        api_key:      EVE API key forwarded as both ``X-EVE-API-Key`` header
+                      and ``Authorization: Bearer`` token.
+        timeout:      Per-request timeout in seconds.
+        max_retries:  Number of additional attempts after the first failure
+                      on retryable status codes.
+        backoff_base: Base delay in seconds for exponential backoff.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        backoff_base: float = 0.5,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.backoff_base = backoff_base
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "X-EVE-API-Key": self.api_key,
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": _USER_AGENT,
+        }
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Dict[str, Any]] = None,
+    ) -> Tuple[int, Dict[str, Any]]:
+        """Execute an HTTP request with retry logic.
+
+        Returns:
+            Tuple of ``(http_status, response_json_dict)``.
+
+        Raises:
+            ProofError:     On 4xx client errors (non-retryable).
+            TransportError: On connection failure or exhausted 5xx retries.
+        """
+        url = self.base_url + path
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        last_exc: Optional[Exception] = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                req = urllib.request.Request(
+                    url,
+                    data=data,
+                    headers=self._headers(),
+                    method=method,
+                )
+                with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                    status: int = resp.status
+                    payload: Dict[str, Any] = json.loads(resp.read().decode("utf-8"))
+                    return status, payload
+
+            except urllib.error.HTTPError as exc:
+                status = exc.code
+                try:
+                    resp_body: Dict[str, Any] = json.loads(exc.read().decode("utf-8"))
+                except Exception:
+                    resp_body = {"error": str(exc)}
+
+                if status in (401, 403):
+                    raise ProofError(
+                        resp_body.get("detail", resp_body.get("error", "Authentication failed")),
+                        status_code=status,
+                    )
+
+                if status == 429:
+                    retry_after = float(exc.headers.get("Retry-After", "60"))
+                    raise ProofError(
+                        resp_body.get("detail", "Rate limit exceeded — retry after "
+                                      f"{retry_after:.0f}s"),
+                        status_code=429,
+                    )
+
+                if status < 500:
+                    # 4xx (other than auth/rate-limit): surface as ProofError
+                    raise ProofError(
+                        resp_body.get("detail", resp_body.get("error", f"HTTP {status}")),
+                        status_code=status,
+                    )
+
+                # 5xx: retry with backoff
+                last_exc = exc
+                if attempt < self.max_retries:
+                    sleep_s = self.backoff_base * (2 ** attempt)
+                    logger.debug(
+                        "HTTP %s on %s (attempt %d/%d); retrying in %.1fs",
+                        status, path, attempt + 1, self.max_retries + 1, sleep_s,
+                    )
+                    time.sleep(sleep_s)
+                    continue
+
+                raise TransportError(
+                    resp_body.get("detail", f"Server error HTTP {status} after "
+                                  f"{self.max_retries + 1} attempts"),
+                    status_code=status,
+                )
+
+            except (urllib.error.URLError, OSError) as exc:
+                last_exc = exc
+                if attempt < self.max_retries:
+                    sleep_s = self.backoff_base * (2 ** attempt)
+                    logger.debug(
+                        "Connection error on %s (attempt %d/%d): %s; retrying in %.1fs",
+                        path, attempt + 1, self.max_retries + 1, exc, sleep_s,
+                    )
+                    time.sleep(sleep_s)
+                    continue
+
+                raise TransportError(
+                    f"Connection failed after {self.max_retries + 1} attempts: {exc}",
+                )
+
+        raise TransportError(f"Request failed: {last_exc}")
+
+    # ------------------------------------------------------------------
+    # Public interface
+    # ------------------------------------------------------------------
+
+    def get(self, path: str) -> Dict[str, Any]:
+        """Perform a GET request and return the parsed JSON body."""
+        _, body = self._request("GET", path)
+        return body
+
+    def post(self, path: str, body: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Perform a POST request with a JSON body and return the parsed response."""
+        _, resp = self._request("POST", path, body)
+        return resp

eve_proof-0.1.0.dist-info/METADATA

@@ -0,0 +1,284 @@
+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

eve_proof-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+eve_proof/__init__.py,sha256=vivoA7YDqizScw57lzIenlwM0sMtJEtkDO32QiBL1m8,923
+eve_proof/cli.py,sha256=Tm6XH5wLXaY6AWv000tgQNsuBkrOMmix4AOAHgMWOto,2226
+eve_proof/client.py,sha256=ofpf0Lih22NPPRUdJaPBJl4HRLkQ-M5Q7nNa8xKnTPA,13305
+eve_proof/exceptions.py,sha256=vuHWsoIjhll3Z1g7cQh1tZOwB8PjKr3rbmnwPFH4TSQ,1514
+eve_proof/models.py,sha256=STMqHqgv0gB9xf9NYy8-AY_mO0vRwn5mgr53PM_y3p4,7263
+eve_proof/transport.py,sha256=rW1HVFgmqLNoW4hGYcJHfvsaoOHfVjYaX-XKDohyeqk,6573
+eve_proof-0.1.0.dist-info/METADATA,sha256=wjHHycnoCm1LYbgNGU31EstOgGxvxyUeyE40dV_4c18,8657
+eve_proof-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+eve_proof-0.1.0.dist-info/entry_points.txt,sha256=DNSQB2uwmAkMAcvbGGOxdTIO8PZmF1Dt1gQPOyhyKB4,54
+eve_proof-0.1.0.dist-info/RECORD,,

eve_proof-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

eve_proof-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+eve-proof-demo = eve_proof.cli:main