oris-kya-verify 0.1.0__tar.gz

oris_kya_verify-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+node_modules/
+.next/
+dist/
+.turbo/
+*.log
+.env
+.env.local
+.env.production
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+celerybeat-schedule
+
+# Docker
+docker/certs/
+docker/data/
+docker/secrets/*.txt
+
+# Vault
+.vault-backup/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Ruff
+.ruff_cache/
+tsconfig.tsbuildinfo

oris_kya_verify-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: oris-kya-verify
+Version: 0.1.0
+Summary: Standalone Know-Your-Agent verifier. Reads on-chain EAS attestations + verifies EIP-712 signatures with zero Oris API dependency.
+Project-URL: Homepage, https://useoris.xyz
+Project-URL: Documentation, https://docs.useoris.xyz/kya-verify
+Project-URL: Repository, https://github.com/fluxaventures/oris
+Project-URL: Bug Tracker, https://github.com/fluxaventures/oris/issues
+Author-email: Fluxa Ventures <engineering@fluxa.ventures>
+License: Apache-2.0
+Keywords: agent-payments,attestation,compliance,eas,ethereum,kya
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: coincurve>=19
+Requires-Dist: eth-abi>=5
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# oris-kya-verify
+
+> Standalone Know-Your-Agent verifier. Reads on-chain EAS
+> attestations and verifies EIP-712 signatures with **zero Oris API
+> dependency**. Drop into any payment gateway, wallet provider, or
+> compliance pipeline to verify the agent on the other side of a
+> transaction.
+
+The package implements the public `KYABundle` schema published at
+[`docs.useoris.xyz/spec/kya-bundle-v1.json`](https://docs.useoris.xyz/spec/kya-bundle-v1.json).
+Any KYA attestation issued by Oris on Base, Ethereum, Arbitrum, or
+Optimism mainnet can be verified by this library without ever
+hitting an Oris service.
+
+## Why this exists
+
+Oris issues two parallel attestations for every Know-Your-Agent
+state transition (promote, demote, suspend):
+
+1. An off-chain **EIP-712** signed message recoverable to the
+   Oris MPC key.
+2. An on-chain **EAS** attestation on Base + Ethereum (with optional
+   replication to Arbitrum / Optimism).
+
+A third party can verify either independently. This library wraps
+both checks behind a single `KYAVerifier.verify()` call.
+
+## Install
+
+```bash
+pip install oris-kya-verify
+```
+
+Dependencies: `httpx`, `coincurve`, `eth-abi`. No web3.py, no
+Postgres, no Oris SDK.
+
+## Usage
+
+```python
+import asyncio
+from oris_kya import KYAVerifier
+
+async def main():
+    verifier = KYAVerifier(chain="base")
+    bundle = await verifier.verify("did:ethr:8453:0x7f3a9c2d1b4e5f6a7b8c9d0e1f2a3b4c5d6e7c2d")
+
+    print(f"KYA level: {bundle.kya_level}")
+    print(f"Risk score: {bundle.risk_score}/100")
+    print(f"Status: {bundle.kya_status}")
+    print(f"Attestation UID: {bundle.attestation_uid}")
+    print(f"Signed by: {bundle.signer_address}")  # Should match the Oris MPC key
+    print(f"Issued at: {bundle.issued_at}")
+    print(f"Expires at: {bundle.expires_at}")
+    print(f"Expired? {bundle.is_expired}")
+
+    if bundle.kya_level >= 3 and not bundle.is_expired:
+        # Authorize the payment.
+        pass
+
+asyncio.run(main())
+```
+
+## Supported chains
+
+| Chain | EAS contract | Default RPC |
+|---|---|---|
+| `base` | `0x4200000000000000000000000000000000000021` | `https://mainnet.base.org` |
+| `ethereum` | `0xA1207F3BBa224E2c9c3c6D5aF63D0eb1582Ce587` | `https://eth.llamarpc.com` |
+| `arbitrum` | `0xbD75f629A22Dc1ceD33dDA0b68c546A1c035c458` | `https://arb1.arbitrum.io/rpc` |
+| `optimism` | `0x4200000000000000000000000000000000000021` | `https://mainnet.optimism.io` |
+
+Override `rpc_url` in the `KYAVerifier` constructor to point at
+your own RPC (recommended for production: Alchemy, Infura, Helius,
+etc.).
+
+## Error handling
+
+The library raises typed exceptions you can catch by category:
+
+- `KYANotAttestedError` — no on-chain attestation exists for this agent.
+- `KYAExpiredError` — the latest attestation has passed its `expires_at`.
+- `KYAInvalidSignatureError` — the EIP-712 signature does not recover
+  to the expected Oris MPC signer.
+- `KYAVerificationError` — base class for any of the above.
+
+Network failures bubble up as `httpx.HTTPError`. The library never
+silently fails: every "yes" answer is cryptographically grounded.
+
+## Schema
+
+The `KYABundle` returned by `verify()` is a frozen dataclass that
+mirrors the public JSON schema at
+[`docs.useoris.xyz/spec/kya-bundle-v1.json`](https://docs.useoris.xyz/spec/kya-bundle-v1.json).
+Use the schema directly if you are implementing your own verifier
+in a different language.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

oris_kya_verify-0.1.0/README.md

@@ -0,0 +1,99 @@
+# oris-kya-verify
+
+> Standalone Know-Your-Agent verifier. Reads on-chain EAS
+> attestations and verifies EIP-712 signatures with **zero Oris API
+> dependency**. Drop into any payment gateway, wallet provider, or
+> compliance pipeline to verify the agent on the other side of a
+> transaction.
+
+The package implements the public `KYABundle` schema published at
+[`docs.useoris.xyz/spec/kya-bundle-v1.json`](https://docs.useoris.xyz/spec/kya-bundle-v1.json).
+Any KYA attestation issued by Oris on Base, Ethereum, Arbitrum, or
+Optimism mainnet can be verified by this library without ever
+hitting an Oris service.
+
+## Why this exists
+
+Oris issues two parallel attestations for every Know-Your-Agent
+state transition (promote, demote, suspend):
+
+1. An off-chain **EIP-712** signed message recoverable to the
+   Oris MPC key.
+2. An on-chain **EAS** attestation on Base + Ethereum (with optional
+   replication to Arbitrum / Optimism).
+
+A third party can verify either independently. This library wraps
+both checks behind a single `KYAVerifier.verify()` call.
+
+## Install
+
+```bash
+pip install oris-kya-verify
+```
+
+Dependencies: `httpx`, `coincurve`, `eth-abi`. No web3.py, no
+Postgres, no Oris SDK.
+
+## Usage
+
+```python
+import asyncio
+from oris_kya import KYAVerifier
+
+async def main():
+    verifier = KYAVerifier(chain="base")
+    bundle = await verifier.verify("did:ethr:8453:0x7f3a9c2d1b4e5f6a7b8c9d0e1f2a3b4c5d6e7c2d")
+
+    print(f"KYA level: {bundle.kya_level}")
+    print(f"Risk score: {bundle.risk_score}/100")
+    print(f"Status: {bundle.kya_status}")
+    print(f"Attestation UID: {bundle.attestation_uid}")
+    print(f"Signed by: {bundle.signer_address}")  # Should match the Oris MPC key
+    print(f"Issued at: {bundle.issued_at}")
+    print(f"Expires at: {bundle.expires_at}")
+    print(f"Expired? {bundle.is_expired}")
+
+    if bundle.kya_level >= 3 and not bundle.is_expired:
+        # Authorize the payment.
+        pass
+
+asyncio.run(main())
+```
+
+## Supported chains
+
+| Chain | EAS contract | Default RPC |
+|---|---|---|
+| `base` | `0x4200000000000000000000000000000000000021` | `https://mainnet.base.org` |
+| `ethereum` | `0xA1207F3BBa224E2c9c3c6D5aF63D0eb1582Ce587` | `https://eth.llamarpc.com` |
+| `arbitrum` | `0xbD75f629A22Dc1ceD33dDA0b68c546A1c035c458` | `https://arb1.arbitrum.io/rpc` |
+| `optimism` | `0x4200000000000000000000000000000000000021` | `https://mainnet.optimism.io` |
+
+Override `rpc_url` in the `KYAVerifier` constructor to point at
+your own RPC (recommended for production: Alchemy, Infura, Helius,
+etc.).
+
+## Error handling
+
+The library raises typed exceptions you can catch by category:
+
+- `KYANotAttestedError` — no on-chain attestation exists for this agent.
+- `KYAExpiredError` — the latest attestation has passed its `expires_at`.
+- `KYAInvalidSignatureError` — the EIP-712 signature does not recover
+  to the expected Oris MPC signer.
+- `KYAVerificationError` — base class for any of the above.
+
+Network failures bubble up as `httpx.HTTPError`. The library never
+silently fails: every "yes" answer is cryptographically grounded.
+
+## Schema
+
+The `KYABundle` returned by `verify()` is a frozen dataclass that
+mirrors the public JSON schema at
+[`docs.useoris.xyz/spec/kya-bundle-v1.json`](https://docs.useoris.xyz/spec/kya-bundle-v1.json).
+Use the schema directly if you are implementing your own verifier
+in a different language.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

oris_kya_verify-0.1.0/oris_kya/__init__.py

@@ -0,0 +1,38 @@
+"""Public API of the oris-kya-verify package.
+
+Import surface:
+
+    from oris_kya import (
+        KYAVerifier,
+        KYABundle,
+        KYAVerificationError,
+        KYAExpiredError,
+        KYAInvalidSignatureError,
+        KYANotAttestedError,
+        SCHEMA_VERSION,
+    )
+"""
+
+from oris_kya.bundle import KYABundle
+from oris_kya.errors import (
+    KYAExpiredError,
+    KYAInvalidSignatureError,
+    KYANotAttestedError,
+    KYAVerificationError,
+)
+from oris_kya.verifier import KYAVerifier
+
+SCHEMA_VERSION = "kya-bundle-v1"
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "KYAVerifier",
+    "KYABundle",
+    "KYAVerificationError",
+    "KYAExpiredError",
+    "KYAInvalidSignatureError",
+    "KYANotAttestedError",
+    "SCHEMA_VERSION",
+    "__version__",
+]

oris_kya_verify-0.1.0/oris_kya/bundle.py

@@ -0,0 +1,89 @@
+"""KYABundle dataclass mirroring the public JSON schema.
+
+Schema URL: https://docs.useoris.xyz/spec/kya-bundle-v1.json
+Schema version: kya-bundle-v1
+
+A bundle is the result of a successful verification. It contains
+everything a downstream caller needs to decide whether to allow a
+payment: the agent's KYA level (0-4), the latest composite risk
+score (0-100), the validity window, the on-chain attestation UID
+that proves provenance, and the recovered signer address that
+proves authenticity.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class KYABundle:
+    """Verified Know-Your-Agent state for one agent.
+
+    Frozen + slotted: cheap to pass around, deterministic equality,
+    safe to use as a dict key. Construct via KYAVerifier.verify().
+    """
+
+    # ── Identity ────────────────────────────────────────────────────
+    did: str                    # did:ethr:{chain_id}:{address}
+    agent_id_hex: str           # 0x-prefixed 64-char hex of the agent UID
+    chain: str                  # base | ethereum | arbitrum | optimism
+
+    # ── KYA verdict ─────────────────────────────────────────────────
+    kya_level: int              # 0..4
+    kya_status: int             # 0=pending, 1=verified, 2=suspended, 3=revoked
+    risk_score: int             # 0..100
+
+    # ── Provenance ──────────────────────────────────────────────────
+    attestation_uid: str        # on-chain EAS UID (0x-prefixed 32-byte hex)
+    signer_address: str         # recovered from the EIP-712 signature
+    issued_at: datetime
+    expires_at: datetime
+
+    # ── Schema versioning ───────────────────────────────────────────
+    schema_version: str = "kya-bundle-v1"
+
+    @property
+    def is_expired(self) -> bool:
+        """True if the attestation's expires_at is in the past.
+
+        Comparison is in UTC. Callers should still gate by both
+        is_expired and their own business window.
+        """
+        return datetime.now(timezone.utc) >= self.expires_at
+
+    @property
+    def kya_status_label(self) -> str:
+        """Human-readable status name (verified / pending / etc.)."""
+        return _STATUS_LABELS.get(self.kya_status, "unknown")
+
+    def to_dict(self) -> dict[str, Any]:
+        """JSON-serialisable form.
+
+        Conforms to kya-bundle-v1.json. Datetimes are ISO-8601 UTC.
+        """
+        return {
+            "schema_version": self.schema_version,
+            "did": self.did,
+            "agent_id_hex": self.agent_id_hex,
+            "chain": self.chain,
+            "kya_level": self.kya_level,
+            "kya_status": self.kya_status,
+            "kya_status_label": self.kya_status_label,
+            "risk_score": self.risk_score,
+            "attestation_uid": self.attestation_uid,
+            "signer_address": self.signer_address,
+            "issued_at": self.issued_at.astimezone(timezone.utc).isoformat(),
+            "expires_at": self.expires_at.astimezone(timezone.utc).isoformat(),
+            "is_expired": self.is_expired,
+        }
+
+
+_STATUS_LABELS = {
+    0: "pending",
+    1: "verified",
+    2: "suspended",
+    3: "revoked",
+}

oris_kya_verify-0.1.0/oris_kya/eas_reader.py

@@ -0,0 +1,250 @@
+"""Read EAS attestations over JSON-RPC.
+
+Pure-httpx, pure-eth-abi. No web3.py dependency. One `eth_call` to
+the EAS contract's `getAttestation(bytes32 uid)` method, plus the
+attestation lookup by recipient + schema if uid is not known.
+
+The encoded data field on the attestation carries the Oris KYA
+schema: `bytes32 agentId, uint8 kyaLevel, uint8 kyaStatus,
+uint32 riskScore, uint64 issuedAt, uint64 expiresAt`.
+
+Per-chain EAS contract addresses are pinned to mainnet values
+verified against https://docs.attest.org/docs/quick--start/contracts.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import httpx
+from eth_abi import decode as abi_decode
+from eth_abi import encode as abi_encode
+
+
+# Canonical mainnet EAS contracts. These are the official deployments.
+EAS_CONTRACTS: dict[str, str] = {
+    "base":     "0x4200000000000000000000000000000000000021",
+    "ethereum": "0xA1207F3BBa224E2c9c3c6D5aF63D0eb1582Ce587",
+    "arbitrum": "0xbD75f629A22Dc1ceD33dDA0b68c546A1c035c458",
+    "optimism": "0x4200000000000000000000000000000000000021",
+}
+
+# Default public RPCs. Production users should override via the
+# KYAVerifier(rpc_url=...) constructor for rate-limit headroom.
+DEFAULT_RPC: dict[str, str] = {
+    "base":     "https://mainnet.base.org",
+    "ethereum": "https://eth.llamarpc.com",
+    "arbitrum": "https://arb1.arbitrum.io/rpc",
+    "optimism": "https://mainnet.optimism.io",
+}
+
+# EAS chain IDs, used to validate did:ethr:{chain_id}:{address} inputs.
+EAS_CHAIN_IDS: dict[str, int] = {
+    "base": 8453,
+    "ethereum": 1,
+    "arbitrum": 42161,
+    "optimism": 10,
+}
+
+
+# Function selectors. Keccak256 of the canonical signature, first 4 bytes.
+#   getAttestation(bytes32) -> 0xa3112a64
+#   getAttestationUIDs(address,address,bytes32,bool,uint256,uint256) -> see Oris docs
+#
+# We use the simple getAttestation entry point and require the
+# caller to know the UID. UID lookup by (recipient, schema) is
+# left for a future revision; today the Oris API itself surfaces
+# the latest UID per agent, so external verifiers receive it as
+# part of the agent's published bundle metadata.
+_GET_ATTESTATION_SELECTOR = "0xa3112a64"
+
+
+@dataclass(frozen=True, slots=True)
+class RawAttestation:
+    """Decoded EAS Attestation struct + parsed Oris schema data."""
+
+    uid: str                # 0x-prefixed 32-byte hex
+    schema_uid: str
+    time: int               # unix seconds when attested
+    expiration_time: int
+    revocation_time: int    # 0 if not revoked
+    recipient: str
+    attester: str
+
+    # ── Decoded schema data ──
+    agent_id_hex: str
+    kya_level: int
+    kya_status: int
+    risk_score: int
+    issued_at: int
+    expires_at: int
+
+    @property
+    def is_revoked(self) -> bool:
+        return self.revocation_time != 0
+
+
+async def fetch_attestation(
+    *,
+    uid: str,
+    chain: str,
+    rpc_url: str | None = None,
+    client: httpx.AsyncClient | None = None,
+    timeout: float = 8.0,
+) -> RawAttestation | None:
+    """Return the EAS attestation for `uid`, or None if not found.
+
+    `uid` must be a 0x-prefixed 64-char hex (the 32-byte EAS UID).
+    `chain` must be one of `EAS_CONTRACTS.keys()`. `rpc_url` defaults
+    to a public RPC; production callers should override.
+
+    Returns None if the call returns the empty struct (UID never
+    attested). Raises httpx.HTTPError on network failure -- the
+    caller decides whether to retry.
+    """
+    if chain not in EAS_CONTRACTS:
+        raise ValueError(f"unsupported chain: {chain}")
+    rpc = rpc_url or DEFAULT_RPC[chain]
+    contract = EAS_CONTRACTS[chain]
+
+    # Strip 0x and pad to 32 bytes if needed.
+    uid_clean = uid.removeprefix("0x").rjust(64, "0").lower()
+    call_data = _GET_ATTESTATION_SELECTOR + uid_clean
+
+    payload = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "eth_call",
+        "params": [
+            {"to": contract, "data": call_data},
+            "latest",
+        ],
+    }
+
+    own_client = client is None
+    if own_client:
+        client = httpx.AsyncClient(timeout=timeout)
+
+    try:
+        response = await client.post(rpc, json=payload)
+        response.raise_for_status()
+        body = response.json()
+    finally:
+        if own_client:
+            await client.aclose()
+
+    if "error" in body:
+        raise RuntimeError(f"RPC error: {body['error']}")
+
+    hex_result = body.get("result", "0x")
+    if hex_result == "0x" or not hex_result:
+        return None
+
+    return _decode_attestation(uid_clean, hex_result)
+
+
+# ABI types for `Attestation` struct returned by getAttestation.
+# Per https://github.com/ethereum-attestation-service/eas-contracts:
+#   struct Attestation {
+#       bytes32 uid;
+#       bytes32 schema;
+#       uint64  time;
+#       uint64  expirationTime;
+#       uint64  revocationTime;
+#       bytes32 refUID;
+#       address recipient;
+#       address attester;
+#       bool    revocable;
+#       bytes   data;
+#   }
+_ATTESTATION_TUPLE_TYPES = (
+    "bytes32",  # uid
+    "bytes32",  # schema
+    "uint64",   # time
+    "uint64",   # expirationTime
+    "uint64",   # revocationTime
+    "bytes32",  # refUID
+    "address",  # recipient
+    "address",  # attester
+    "bool",     # revocable
+    "bytes",    # data
+)
+
+# ABI types of the Oris KYA schema (encoded in `data`).
+_ORIS_KYA_SCHEMA_TYPES = (
+    "bytes32",  # agentId
+    "uint8",    # kyaLevel
+    "uint8",    # kyaStatus
+    "uint32",   # riskScore
+    "uint64",   # issuedAt
+    "uint64",   # expiresAt
+)
+
+
+def _decode_attestation(uid_clean: str, hex_result: str) -> RawAttestation | None:
+    """Decode the eth_call return blob into a RawAttestation.
+
+    Returns None when the EAS contract returns a zero-uid struct
+    (UID not found).
+    """
+    raw_bytes = bytes.fromhex(hex_result.removeprefix("0x"))
+
+    # The returned struct is a single tuple wrapped in ABI encoding.
+    # eth_abi.decode with a tuple type extracts the fields in order.
+    try:
+        decoded = abi_decode(
+            ["(" + ",".join(_ATTESTATION_TUPLE_TYPES) + ")"],
+            raw_bytes,
+        )
+    except Exception:
+        return None
+
+    if not decoded:
+        return None
+    tup = decoded[0]
+    (uid_b, schema_b, time, expiration_time, revocation_time,
+     ref_uid_b, recipient, attester, revocable, data_bytes) = tup
+
+    # Empty attestation: uid is all zeros.
+    if int.from_bytes(uid_b, "big") == 0:
+        return None
+
+    # Decode the schema-specific data payload.
+    try:
+        (agent_id_b, kya_level, kya_status, risk_score,
+         issued_at, expires_at) = abi_decode(_ORIS_KYA_SCHEMA_TYPES, data_bytes)
+    except Exception:
+        return None
+
+    return RawAttestation(
+        uid="0x" + uid_b.hex(),
+        schema_uid="0x" + schema_b.hex(),
+        time=int(time),
+        expiration_time=int(expiration_time),
+        revocation_time=int(revocation_time),
+        recipient=_address_lower(recipient),
+        attester=_address_lower(attester),
+        agent_id_hex="0x" + agent_id_b.hex(),
+        kya_level=int(kya_level),
+        kya_status=int(kya_status),
+        risk_score=int(risk_score),
+        issued_at=int(issued_at),
+        expires_at=int(expires_at),
+    )
+
+
+def _address_lower(addr: str | bytes) -> str:
+    """Normalise an EVM address to 0x-prefixed lowercase hex."""
+    if isinstance(addr, bytes):
+        return "0x" + addr.hex()
+    return addr.lower()
+
+
+# Exported for caller-side schema validation if needed.
+__all__ = [
+    "EAS_CONTRACTS",
+    "DEFAULT_RPC",
+    "EAS_CHAIN_IDS",
+    "RawAttestation",
+    "fetch_attestation",
+]