aex-sdk 1.2.0a1__tar.gz

aex_sdk-1.2.0a1/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: aex-sdk
+Version: 1.2.0a1
+Summary: Python SDK for AEX — the Agent Exchange Protocol.
+Author-email: Icaro Holding <oss@spize.ai>
+License: Apache-2.0
+Project-URL: Homepage, https://spize.ai
+Project-URL: Repository, https://github.com/icaroholding/spize
+Project-URL: Documentation, https://github.com/icaroholding/spize/tree/master/docs
+Keywords: aex,agent,protocol,identity,transfer,p2p
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: cryptography>=42
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.3; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+
+# spize (Python SDK)
+
+Python client for the [Agent Exchange Protocol (AEX)](https://github.com/icaroholding/spize).
+
+## Install
+
+```sh
+pip install spize
+```
+
+## Quick start
+
+```python
+from spize import Identity, SpizeClient
+
+# One-time: create + register an identity.
+identity = Identity.generate(org="acme", name="alice")
+identity.save("alice.key")
+
+client = SpizeClient(base_url="http://localhost:8080", identity=identity)
+client.register()
+
+# Send.
+transfer = client.send(
+    recipient="spize:acme/bob:aabbcc",
+    file="invoice.pdf",
+    declared_mime="application/pdf",
+)
+print(transfer.state)  # 'ready_for_pickup' or 'rejected'
+
+# Receive (as Bob).
+bob = Identity.load("bob.key")
+bob_client = SpizeClient(base_url="http://localhost:8080", identity=bob)
+bytes_in = bob_client.download(transfer.transfer_id)
+bob_client.ack(transfer.transfer_id)
+```
+
+## Components
+
+- `Identity` — Ed25519 keypair + canonical agent_id derivation. Save/load to disk.
+- `SpizeClient` — thin HTTP wrapper over the control plane. Handles signing + replay nonces.
+- `wire` — canonical byte functions that mirror `spize_core::wire` exactly; change only in lockstep.

aex_sdk-1.2.0a1/README.md

@@ -0,0 +1,42 @@
+# spize (Python SDK)
+
+Python client for the [Agent Exchange Protocol (AEX)](https://github.com/icaroholding/spize).
+
+## Install
+
+```sh
+pip install spize
+```
+
+## Quick start
+
+```python
+from spize import Identity, SpizeClient
+
+# One-time: create + register an identity.
+identity = Identity.generate(org="acme", name="alice")
+identity.save("alice.key")
+
+client = SpizeClient(base_url="http://localhost:8080", identity=identity)
+client.register()
+
+# Send.
+transfer = client.send(
+    recipient="spize:acme/bob:aabbcc",
+    file="invoice.pdf",
+    declared_mime="application/pdf",
+)
+print(transfer.state)  # 'ready_for_pickup' or 'rejected'
+
+# Receive (as Bob).
+bob = Identity.load("bob.key")
+bob_client = SpizeClient(base_url="http://localhost:8080", identity=bob)
+bytes_in = bob_client.download(transfer.transfer_id)
+bob_client.ack(transfer.transfer_id)
+```
+
+## Components
+
+- `Identity` — Ed25519 keypair + canonical agent_id derivation. Save/load to disk.
+- `SpizeClient` — thin HTTP wrapper over the control plane. Handles signing + replay nonces.
+- `wire` — canonical byte functions that mirror `spize_core::wire` exactly; change only in lockstep.

aex_sdk-1.2.0a1/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aex-sdk"
+version = "1.2.0a1"
+description = "Python SDK for AEX — the Agent Exchange Protocol."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Icaro Holding", email = "oss@spize.ai" }]
+keywords = ["aex", "agent", "protocol", "identity", "transfer", "p2p"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "httpx>=0.27",
+    "cryptography>=42",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.3",
+    "mypy>=1.8",
+]
+
+[project.urls]
+Homepage = "https://spize.ai"
+Repository = "https://github.com/icaroholding/spize"
+Documentation = "https://github.com/icaroholding/spize/tree/master/docs"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+aex_sdk = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

aex_sdk-1.2.0a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aex_sdk-1.2.0a1/src/aex_sdk/__init__.py

@@ -0,0 +1,16 @@
+"""Agent Exchange Protocol (AEX) — Python SDK."""
+
+from aex_sdk.client import DataPlaneTicket, SpizeClient, TransferResponse
+from aex_sdk.errors import SpizeError, SpizeHTTPError
+from aex_sdk.identity import Identity
+
+__all__ = [
+    "DataPlaneTicket",
+    "Identity",
+    "SpizeClient",
+    "SpizeError",
+    "SpizeHTTPError",
+    "TransferResponse",
+]
+
+__version__ = "1.2.0a1"

aex_sdk-1.2.0a1/src/aex_sdk/client.py

@@ -0,0 +1,333 @@
+"""Synchronous HTTP client for the Spize control plane."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional
+
+import json
+import httpx
+
+from aex_sdk.errors import SpizeError, SpizeHTTPError
+from aex_sdk.identity import Identity, random_nonce
+from aex_sdk.wire import (
+    registration_challenge_bytes,
+    transfer_intent_bytes,
+    transfer_receipt_bytes,
+)
+
+
+@dataclass
+class TransferResponse:
+    transfer_id: str
+    state: str
+    sender_agent_id: str
+    recipient: str
+    size_bytes: int
+    declared_mime: Optional[str]
+    filename: Optional[str]
+    scanner_verdict: Optional[dict[str, Any]]
+    policy_decision: Optional[dict[str, Any]]
+    rejection_code: Optional[str]
+    rejection_reason: Optional[str]
+
+    @classmethod
+    def from_json(cls, body: dict[str, Any]) -> "TransferResponse":
+        return cls(
+            transfer_id=body["transfer_id"],
+            state=body["state"],
+            sender_agent_id=body["sender_agent_id"],
+            recipient=body["recipient"],
+            size_bytes=int(body["size_bytes"]),
+            declared_mime=body.get("declared_mime"),
+            filename=body.get("filename"),
+            scanner_verdict=body.get("scanner_verdict"),
+            policy_decision=body.get("policy_decision"),
+            rejection_code=body.get("rejection_code"),
+            rejection_reason=body.get("rejection_reason"),
+        )
+
+    @property
+    def was_delivered(self) -> bool:
+        return self.state == "delivered"
+
+    @property
+    def was_rejected(self) -> bool:
+        return self.state == "rejected"
+
+
+class SpizeClient:
+    """Thin wrapper over the control-plane REST API.
+
+    The client is stateless beyond `base_url` + `identity`; each call
+    builds a fresh nonce and signs the canonical payload. Reuses an
+    httpx.Client for connection pooling.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        identity: Identity,
+        *,
+        timeout: float = 30.0,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.identity = identity
+        self._http = httpx.Client(base_url=self.base_url, timeout=timeout)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "SpizeClient":
+        return self
+
+    def __exit__(self, *exc) -> None:  # noqa: D401 - context manager boilerplate
+        self.close()
+
+    # ------------------------------ health ------------------------------
+
+    def health(self) -> dict[str, Any]:
+        r = self._http.get("/healthz")
+        self._raise_for_status(r)
+        return r.json()
+
+    # ---------------------------- registration ---------------------------
+
+    def register(self) -> dict[str, Any]:
+        """Register this identity with the control plane (idempotent-safe:
+        re-registering the same public key returns 409 Conflict — callers
+        can treat that as 'already registered')."""
+        issued_at = int(time.time())
+        nonce = random_nonce()
+        challenge = registration_challenge_bytes(
+            self.identity.public_key_hex,
+            self.identity.org,
+            self.identity.name,
+            nonce,
+            issued_at,
+        )
+        signature = self.identity.sign(challenge)
+        payload = {
+            "public_key_hex": self.identity.public_key_hex,
+            "org": self.identity.org,
+            "name": self.identity.name,
+            "nonce": nonce,
+            "issued_at": issued_at,
+            "signature_hex": signature.hex(),
+        }
+        r = self._http.post("/v1/agents/register", json=payload)
+        self._raise_for_status(r)
+        return r.json()
+
+    def get_agent(self, agent_id: str) -> dict[str, Any]:
+        r = self._http.get(f"/v1/agents/{agent_id}")
+        self._raise_for_status(r)
+        return r.json()
+
+    # ------------------------------- send -------------------------------
+
+    def send(
+        self,
+        recipient: str,
+        *,
+        data: Optional[bytes] = None,
+        file: Optional[str | Path] = None,
+        declared_mime: str = "",
+        filename: str = "",
+    ) -> TransferResponse:
+        """Initiate a transfer. Provide exactly one of `data` or `file`."""
+        if (data is None) == (file is None):
+            raise SpizeError("pass exactly one of data= or file=")
+        if file is not None:
+            p = Path(file)
+            data = p.read_bytes()
+            if not filename:
+                filename = p.name
+        assert data is not None
+
+        issued_at = int(time.time())
+        nonce = random_nonce()
+        canonical = transfer_intent_bytes(
+            self.identity.agent_id,
+            recipient,
+            len(data),
+            declared_mime,
+            filename,
+            nonce,
+            issued_at,
+        )
+        signature = self.identity.sign(canonical)
+        payload = {
+            "sender_agent_id": self.identity.agent_id,
+            "recipient": recipient,
+            "declared_mime": declared_mime,
+            "filename": filename,
+            "nonce": nonce,
+            "issued_at": issued_at,
+            "intent_signature_hex": signature.hex(),
+            "blob_hex": data.hex(),
+        }
+        r = self._http.post("/v1/transfers", json=payload)
+        self._raise_for_status(r)
+        return TransferResponse.from_json(r.json())
+
+    # ----------------------------- receive ------------------------------
+
+    def send_via_tunnel(
+        self,
+        *,
+        recipient: str,
+        declared_size: int,
+        declared_mime: str,
+        filename: str,
+        tunnel_url: str,
+    ) -> TransferResponse:
+        """M2: announce a transfer without uploading bytes. The sender
+        must serve the blob via `tunnel_url` (a data-plane URL)."""
+        if not self.identity:
+            raise ValueError("client has no identity")
+        nonce = random_nonce()
+        issued_at = int(time.time())
+        intent = transfer_intent_bytes(
+            sender_agent_id=self.identity.agent_id,
+            recipient=recipient,
+            size_bytes=declared_size,
+            declared_mime=declared_mime,
+            filename=filename,
+            nonce=nonce,
+            issued_at_unix=issued_at,
+        )
+        sig = self.identity.sign(intent)
+        payload = {
+            "sender_agent_id": self.identity.agent_id,
+            "recipient": recipient,
+            "declared_mime": declared_mime,
+            "filename": filename,
+            "nonce": nonce,
+            "issued_at": issued_at,
+            "intent_signature_hex": sig.hex(),
+            "blob_hex": "",
+            "tunnel_url": tunnel_url,
+            "declared_size": declared_size,
+        }
+        r = self._http.post("/v1/transfers", json=payload)
+        self._raise_for_status(r)
+        return TransferResponse.from_json(r.json())
+
+    def get_transfer(self, transfer_id: str) -> TransferResponse:
+        r = self._http.get(f"/v1/transfers/{transfer_id}")
+        self._raise_for_status(r)
+        return TransferResponse.from_json(r.json())
+
+    def download(self, transfer_id: str) -> bytes:
+        """Download the blob bytes. Must be called by the declared
+        recipient (signature bound to the recipient's identity)."""
+        body = self._build_receipt(transfer_id, "download")
+        r = self._http.post(f"/v1/transfers/{transfer_id}/download", json=body)
+        self._raise_for_status(r)
+        return bytes.fromhex(r.json()["blob_hex"])
+
+    def ack(self, transfer_id: str) -> dict[str, Any]:
+        """Acknowledge delivery. The returned `audit_chain_head` is proof
+        the delivery was logged at this chain position."""
+        body = self._build_receipt(transfer_id, "ack")
+        r = self._http.post(f"/v1/transfers/{transfer_id}/ack", json=body)
+        self._raise_for_status(r)
+        return r.json()
+
+    def request_ticket(self, transfer_id: str) -> "DataPlaneTicket":
+        """M2: request a signed data-plane ticket to fetch the blob directly
+        from the sender's tunnel, bypassing the control plane for payload.
+        Requires the transfer to be in ``ready_for_pickup`` with a tunnel_url.
+        """
+        receipt = self._build_receipt(transfer_id, "request_ticket")
+        r = self._http.post(
+            f"/v1/transfers/{transfer_id}/ticket",
+            json=receipt,
+        )
+        self._raise_for_status(r)
+        body = r.json()
+        return DataPlaneTicket(
+            transfer_id=body["transfer_id"],
+            recipient=body["recipient"],
+            data_plane_url=body["data_plane_url"],
+            expires=int(body["expires"]),
+            nonce=body["nonce"],
+            signature=body["signature"],
+        )
+
+    def fetch_from_tunnel(self, ticket: "DataPlaneTicket") -> bytes:
+        """M2: fetch blob bytes from the sender's data plane using a ticket."""
+        r = httpx.get(
+            f"{ticket.data_plane_url}/blob/{ticket.transfer_id}",
+            headers={"X-AEX-Ticket": ticket.as_header()},
+            timeout=30.0,
+        )
+        self._raise_for_status(r)
+        return r.content
+
+    def inbox(self) -> dict[str, Any]:
+        """List transfers waiting for this identity (state:
+        `ready_for_pickup` or `accepted`). Capped at 100 most recent rows."""
+        body = self._build_receipt("inbox", "inbox")
+        r = self._http.post("/v1/inbox", json=body)
+        self._raise_for_status(r)
+        return r.json()
+
+    def _build_receipt(self, transfer_id: str, action: str) -> dict[str, Any]:
+        issued_at = int(time.time())
+        nonce = random_nonce()
+        canonical = transfer_receipt_bytes(
+            self.identity.agent_id, transfer_id, action, nonce, issued_at
+        )
+        signature = self.identity.sign(canonical)
+        return {
+            "recipient_agent_id": self.identity.agent_id,
+            "nonce": nonce,
+            "issued_at": issued_at,
+            "signature_hex": signature.hex(),
+        }
+
+    # ------------------------------ helpers ------------------------------
+
+    @staticmethod
+    def _raise_for_status(r: httpx.Response) -> None:
+        if r.is_success:
+            return
+        try:
+            body = r.json()
+        except Exception:
+            body = {}
+        raise SpizeHTTPError(
+            status_code=r.status_code,
+            code=body.get("code"),
+            message=body.get("message") or r.text or "unknown error",
+        )
+
+
+# ---------- M2 additions ----------
+
+@dataclass(frozen=True)
+class DataPlaneTicket:
+    transfer_id: str
+    recipient: str
+    data_plane_url: str
+    expires: int
+    nonce: str
+    signature: str
+
+    def as_header(self) -> str:
+        """JSON-encoded ticket for the `X-AEX-Ticket` header."""
+        return json.dumps(
+            {
+                "transfer_id": self.transfer_id,
+                "recipient": self.recipient,
+                "data_plane_url": self.data_plane_url,
+                "expires": self.expires,
+                "nonce": self.nonce,
+                "signature": self.signature,
+            },
+            separators=(",", ":"),
+        )

aex_sdk-1.2.0a1/src/aex_sdk/errors.py

@@ -0,0 +1,19 @@
+"""Spize SDK exception hierarchy."""
+
+
+class SpizeError(Exception):
+    """Root class for SDK errors."""
+
+
+class SpizeHTTPError(SpizeError):
+    """Raised when the control plane returns a non-2xx response."""
+
+    def __init__(self, status_code: int, code: str | None, message: str) -> None:
+        super().__init__(f"[{status_code}] {code or 'error'}: {message}")
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+
+
+class IdentityError(SpizeError):
+    """Raised for identity-file corruption or mismatched keys."""

aex_sdk-1.2.0a1/src/aex_sdk/identity.py

@@ -0,0 +1,173 @@
+"""Spize-native Ed25519 identity."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import secrets
+import string
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+
+from aex_sdk.errors import IdentityError
+
+_LABEL_ALPHABET = set(string.ascii_letters + string.digits + "-_")
+_LABEL_MAX = 64
+
+
+def _validate_label(s: str, field: str) -> None:
+    if not s:
+        raise IdentityError(f"{field} is empty")
+    if len(s) > _LABEL_MAX:
+        raise IdentityError(f"{field} exceeds {_LABEL_MAX} chars")
+    for c in s:
+        if c not in _LABEL_ALPHABET:
+            raise IdentityError(
+                f"{field} must match [a-zA-Z0-9_-]+, got {c!r}"
+            )
+
+
+def _compute_fingerprint(public_key_bytes: bytes) -> str:
+    """First 3 bytes of SHA-256 over the public key, hex-encoded."""
+    return hashlib.sha256(public_key_bytes).digest()[:3].hex()
+
+
+@dataclass(frozen=True)
+class Identity:
+    """Ed25519 keypair + canonical Spize agent_id."""
+
+    org: str
+    name: str
+    private_key_bytes: bytes  # 32 bytes
+    public_key_bytes: bytes  # 32 bytes
+
+    @classmethod
+    def generate(cls, org: str, name: str) -> "Identity":
+        _validate_label(org, "org")
+        _validate_label(name, "name")
+        private_key = Ed25519PrivateKey.generate()
+        private_bytes = private_key.private_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PrivateFormat.Raw,
+            encryption_algorithm=serialization.NoEncryption(),
+        )
+        public_bytes = private_key.public_key().public_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PublicFormat.Raw,
+        )
+        return cls(org=org, name=name, private_key_bytes=private_bytes, public_key_bytes=public_bytes)
+
+    @classmethod
+    def from_secret(cls, org: str, name: str, private_key_bytes: bytes) -> "Identity":
+        _validate_label(org, "org")
+        _validate_label(name, "name")
+        if len(private_key_bytes) != 32:
+            raise IdentityError(f"Ed25519 secret must be 32 bytes, got {len(private_key_bytes)}")
+        private_key = Ed25519PrivateKey.from_private_bytes(private_key_bytes)
+        public_bytes = private_key.public_key().public_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PublicFormat.Raw,
+        )
+        return cls(org=org, name=name, private_key_bytes=private_key_bytes, public_key_bytes=public_bytes)
+
+    # ---------- derived properties ----------
+
+    @property
+    def fingerprint(self) -> str:
+        return _compute_fingerprint(self.public_key_bytes)
+
+    @property
+    def agent_id(self) -> str:
+        return f"spize:{self.org}/{self.name}:{self.fingerprint}"
+
+    @property
+    def public_key_hex(self) -> str:
+        return self.public_key_bytes.hex()
+
+    # ---------- signing ----------
+
+    def sign(self, message: bytes) -> bytes:
+        return Ed25519PrivateKey.from_private_bytes(self.private_key_bytes).sign(message)
+
+    # ---------- persistence ----------
+
+    def save(self, path: str | os.PathLike, *, overwrite: bool = False) -> None:
+        """Persist the identity to a JSON file with 0600 perms.
+
+        Write pattern: write to a sibling tmp file → fsync → rename. This
+        guarantees the final path either contains the full, valid JSON or
+        nothing at all — a crash during save cannot leave a truncated key
+        file that re-opens as corrupt.
+        """
+        p = Path(path)
+        if p.exists() and not overwrite:
+            raise IdentityError(f"{p} already exists; pass overwrite=True to replace")
+        payload = {
+            "version": 1,
+            "org": self.org,
+            "name": self.name,
+            "private_key_hex": self.private_key_bytes.hex(),
+            "public_key_hex": self.public_key_bytes.hex(),
+            "agent_id": self.agent_id,
+        }
+        data = json.dumps(payload, indent=2).encode("utf-8")
+
+        tmp = p.with_name(p.name + ".tmp")
+        flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
+        fd = os.open(tmp, flags, 0o600)
+        try:
+            with os.fdopen(fd, "wb") as f:
+                f.write(data)
+                f.flush()
+                os.fsync(f.fileno())
+            os.replace(tmp, p)
+        except Exception:
+            try:
+                tmp.unlink(missing_ok=True)
+            except OSError:
+                pass
+            raise
+
+    @classmethod
+    def load(cls, path: str | os.PathLike) -> "Identity":
+        p = Path(path)
+        with open(p, "rb") as f:
+            payload = json.loads(f.read().decode("utf-8"))
+        if payload.get("version") != 1:
+            raise IdentityError(f"unsupported identity file version: {payload.get('version')}")
+        try:
+            org = payload["org"]
+            name = payload["name"]
+            private_key_hex = payload["private_key_hex"]
+        except KeyError as e:
+            raise IdentityError(f"missing field in identity file: {e.args[0]}") from e
+
+        identity = cls.from_secret(org, name, bytes.fromhex(private_key_hex))
+        # Sanity: stored public/agent_id should match derived values.
+        if "public_key_hex" in payload and payload["public_key_hex"] != identity.public_key_hex:
+            raise IdentityError("stored public_key_hex does not match derived public key")
+        if "agent_id" in payload and payload["agent_id"] != identity.agent_id:
+            raise IdentityError("stored agent_id does not match derived agent_id")
+        return identity
+
+
+def random_nonce(byte_length: int = 16) -> str:
+    """Hex nonce with `byte_length` bytes of entropy."""
+    return secrets.token_hex(byte_length)
+
+
+def verify_signature(public_key_bytes: bytes, message: bytes, signature: bytes) -> bool:
+    """Verify an Ed25519 signature; returns True/False without raising."""
+    try:
+        Ed25519PublicKey.from_public_bytes(public_key_bytes).verify(signature, message)
+        return True
+    except Exception:
+        return False

aex_sdk-1.2.0a1/src/aex_sdk/wire.py

@@ -0,0 +1,106 @@
+"""Canonical wire-format functions.
+
+These MUST produce byte-for-byte identical output to the corresponding
+Rust functions in ``aex_core::wire``. The test suite in
+``tests/test_wire.py`` checks this against the golden vectors exported
+from the Rust tests — DO NOT modify without updating both sides
+together.
+"""
+
+from __future__ import annotations
+
+PROTOCOL_VERSION = "v1"
+MAX_CLOCK_SKEW_SECS = 300
+MIN_NONCE_LEN = 32
+MAX_NONCE_LEN = 128
+
+
+def _validate_ascii_line(s: str, field: str, *, allow_empty: bool = False) -> None:
+    if not s:
+        if allow_empty:
+            return
+        raise ValueError(f"{field} is empty")
+    for i, c in enumerate(s):
+        if ord(c) > 127 or c in ("\n", "\r", "\0"):
+            raise ValueError(f"{field} has invalid char at {i}: {c!r}")
+
+
+def _validate_nonce(nonce: str) -> None:
+    if not (MIN_NONCE_LEN <= len(nonce) <= MAX_NONCE_LEN):
+        raise ValueError(
+            f"nonce length {len(nonce)} outside [{MIN_NONCE_LEN}, {MAX_NONCE_LEN}]"
+        )
+    if not all(c in "0123456789abcdefABCDEF" for c in nonce):
+        raise ValueError("nonce must be hex")
+
+
+def registration_challenge_bytes(
+    public_key_hex: str,
+    org: str,
+    name: str,
+    nonce: str,
+    issued_at_unix: int,
+) -> bytes:
+    _validate_ascii_line(public_key_hex, "public_key_hex")
+    _validate_ascii_line(org, "org")
+    _validate_ascii_line(name, "name")
+    _validate_nonce(nonce)
+    return (
+        f"spize-register:{PROTOCOL_VERSION}\n"
+        f"pub={public_key_hex}\n"
+        f"org={org}\n"
+        f"name={name}\n"
+        f"nonce={nonce}\n"
+        f"ts={issued_at_unix}"
+    ).encode("ascii")
+
+
+def transfer_intent_bytes(
+    sender_agent_id: str,
+    recipient: str,
+    size_bytes: int,
+    declared_mime: str,
+    filename: str,
+    nonce: str,
+    issued_at_unix: int,
+) -> bytes:
+    _validate_ascii_line(sender_agent_id, "sender_agent_id")
+    _validate_ascii_line(recipient, "recipient")
+    _validate_ascii_line(declared_mime, "declared_mime", allow_empty=True)
+    _validate_ascii_line(filename, "filename", allow_empty=True)
+    _validate_nonce(nonce)
+    return (
+        f"spize-transfer-intent:{PROTOCOL_VERSION}\n"
+        f"sender={sender_agent_id}\n"
+        f"recipient={recipient}\n"
+        f"size={size_bytes}\n"
+        f"mime={declared_mime}\n"
+        f"filename={filename}\n"
+        f"nonce={nonce}\n"
+        f"ts={issued_at_unix}"
+    ).encode("ascii")
+
+
+def transfer_receipt_bytes(
+    recipient_agent_id: str,
+    transfer_id: str,
+    action: str,
+    nonce: str,
+    issued_at_unix: int,
+) -> bytes:
+    _validate_ascii_line(recipient_agent_id, "recipient_agent_id")
+    _validate_ascii_line(transfer_id, "transfer_id")
+    _validate_ascii_line(action, "action")
+    _validate_nonce(nonce)
+    if action not in ("download", "ack", "inbox", "request_ticket"):
+        raise ValueError(
+            f"action must be 'download', 'ack', 'inbox' or 'request_ticket', got {action}"
+        )
+    return (
+        f"spize-transfer-receipt:{PROTOCOL_VERSION}\n"
+        f"recipient={recipient_agent_id}\n"
+        f"transfer={transfer_id}\n"
+        f"action={action}\n"
+        f"nonce={nonce}\n"
+        f"ts={issued_at_unix}"
+    ).encode("ascii")

aex_sdk-1.2.0a1/src/aex_sdk.egg-info/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: aex-sdk
+Version: 1.2.0a1
+Summary: Python SDK for AEX — the Agent Exchange Protocol.
+Author-email: Icaro Holding <oss@spize.ai>
+License: Apache-2.0
+Project-URL: Homepage, https://spize.ai
+Project-URL: Repository, https://github.com/icaroholding/spize
+Project-URL: Documentation, https://github.com/icaroholding/spize/tree/master/docs
+Keywords: aex,agent,protocol,identity,transfer,p2p
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: cryptography>=42
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.3; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+
+# spize (Python SDK)
+
+Python client for the [Agent Exchange Protocol (AEX)](https://github.com/icaroholding/spize).
+
+## Install
+
+```sh
+pip install spize
+```
+
+## Quick start
+
+```python
+from spize import Identity, SpizeClient
+
+# One-time: create + register an identity.
+identity = Identity.generate(org="acme", name="alice")
+identity.save("alice.key")
+
+client = SpizeClient(base_url="http://localhost:8080", identity=identity)
+client.register()
+
+# Send.
+transfer = client.send(
+    recipient="spize:acme/bob:aabbcc",
+    file="invoice.pdf",
+    declared_mime="application/pdf",
+)
+print(transfer.state)  # 'ready_for_pickup' or 'rejected'
+
+# Receive (as Bob).
+bob = Identity.load("bob.key")
+bob_client = SpizeClient(base_url="http://localhost:8080", identity=bob)
+bytes_in = bob_client.download(transfer.transfer_id)
+bob_client.ack(transfer.transfer_id)
+```
+
+## Components
+
+- `Identity` — Ed25519 keypair + canonical agent_id derivation. Save/load to disk.
+- `SpizeClient` — thin HTTP wrapper over the control plane. Handles signing + replay nonces.
+- `wire` — canonical byte functions that mirror `spize_core::wire` exactly; change only in lockstep.

aex_sdk-1.2.0a1/src/aex_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+src/aex_sdk/__init__.py
+src/aex_sdk/client.py
+src/aex_sdk/errors.py
+src/aex_sdk/identity.py
+src/aex_sdk/py.typed
+src/aex_sdk/wire.py
+src/aex_sdk.egg-info/PKG-INFO
+src/aex_sdk.egg-info/SOURCES.txt
+src/aex_sdk.egg-info/dependency_links.txt
+src/aex_sdk.egg-info/requires.txt
+src/aex_sdk.egg-info/top_level.txt
+tests/test_client_end_to_end.py
+tests/test_identity.py
+tests/test_wire.py

aex_sdk-1.2.0a1/src/aex_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

aex_sdk-1.2.0a1/src/aex_sdk.egg-info/requires.txt

@@ -0,0 +1,8 @@
+httpx>=0.27
+cryptography>=42
+
+[dev]
+pytest>=8
+pytest-asyncio>=0.23
+ruff>=0.3
+mypy>=1.8

aex_sdk-1.2.0a1/src/aex_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+aex_sdk

aex_sdk-1.2.0a1/tests/test_client_end_to_end.py

@@ -0,0 +1,111 @@
+"""End-to-end integration test for the Python SDK.
+
+Requires a running control plane (started automatically via a subprocess
+fixture if not already up). Marked optional because it spins up services
+and runs real HTTP — skip it in CI where Postgres isn't available.
+"""
+
+from __future__ import annotations
+
+import os
+import socket
+import subprocess
+import tempfile
+import time
+
+import pytest
+
+from aex_sdk import Identity, SpizeClient
+from aex_sdk.errors import SpizeHTTPError
+
+
+def _server_reachable(url: str) -> bool:
+    """Quick TCP check against base url host:port."""
+    import urllib.parse as up
+
+    parsed = up.urlparse(url)
+    host = parsed.hostname or "127.0.0.1"
+    port = parsed.port or 80
+    try:
+        with socket.create_connection((host, port), timeout=0.25):
+            return True
+    except OSError:
+        return False
+
+
+BASE_URL = os.environ.get("SPIZE_TEST_BASE_URL", "http://127.0.0.1:8080")
+
+
+@pytest.mark.skipif(
+    not _server_reachable(BASE_URL),
+    reason=f"control plane at {BASE_URL} not reachable; run it manually",
+)
+def test_alice_sends_clean_file_to_bob(tmp_path) -> None:
+    alice = Identity.generate(
+        org="sdktest",
+        name=f"alice{int(time.time())}",
+    )
+    bob = Identity.generate(
+        org="sdktest",
+        name=f"bob{int(time.time())}",
+    )
+
+    with SpizeClient(BASE_URL, alice) as alice_client, SpizeClient(
+        BASE_URL, bob
+    ) as bob_client:
+        alice_client.register()
+        bob_client.register()
+
+        payload = b"e2e-test-" + os.urandom(32)
+        tx = alice_client.send(
+            recipient=bob.agent_id,
+            data=payload,
+            declared_mime="text/plain",
+            filename="note.txt",
+        )
+        assert tx.state == "ready_for_pickup", f"unexpected state: {tx.state}"
+
+        received = bob_client.download(tx.transfer_id)
+        assert received == payload
+
+        ack = bob_client.ack(tx.transfer_id)
+        assert ack["state"] == "delivered"
+        assert len(ack["audit_chain_head"]) == 64
+
+
+@pytest.mark.skipif(
+    not _server_reachable(BASE_URL),
+    reason="control plane not reachable",
+)
+def test_eicar_blocked() -> None:
+    alice = Identity.generate(
+        org="sdktest",
+        name=f"eicarsend{int(time.time())}",
+    )
+    bob = Identity.generate(
+        org="sdktest",
+        name=f"eicarrecv{int(time.time())}",
+    )
+
+    with SpizeClient(BASE_URL, alice) as alice_client, SpizeClient(
+        BASE_URL, bob
+    ) as bob_client:
+        alice_client.register()
+        bob_client.register()
+
+        eicar = (
+            b"X5O!P%@AP[4\\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*"
+        )
+        tx = alice_client.send(
+            recipient=bob.agent_id,
+            data=eicar,
+            declared_mime="text/plain",
+            filename="test.txt",
+        )
+        assert tx.was_rejected, f"EICAR should be rejected; state = {tx.state}"
+        assert tx.rejection_code == "scanner_malicious"
+
+        # Bob can't download a rejected transfer.
+        with pytest.raises(SpizeHTTPError) as ei:
+            bob_client.download(tx.transfer_id)
+        assert ei.value.status_code == 404

aex_sdk-1.2.0a1/tests/test_identity.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import os
+import stat
+
+import pytest
+
+from aex_sdk import Identity
+from aex_sdk.errors import IdentityError
+from aex_sdk.identity import verify_signature
+
+
+def test_generate_produces_valid_agent_id(tmp_path) -> None:
+    ident = Identity.generate(org="acme", name="alice")
+    assert ident.agent_id.startswith("spize:acme/alice:")
+    assert len(ident.fingerprint) == 6
+    assert all(c in "0123456789abcdef" for c in ident.fingerprint)
+
+
+def test_deterministic_from_secret() -> None:
+    secret = b"\x07" * 32
+    a = Identity.from_secret("acme", "alice", secret)
+    b = Identity.from_secret("acme", "alice", secret)
+    assert a.agent_id == b.agent_id
+    assert a.public_key_bytes == b.public_key_bytes
+
+
+def test_sign_and_verify_roundtrip() -> None:
+    ident = Identity.generate(org="acme", name="alice")
+    sig = ident.sign(b"hello")
+    assert verify_signature(ident.public_key_bytes, b"hello", sig)
+    assert not verify_signature(ident.public_key_bytes, b"hxllo", sig)
+
+
+def test_save_load_roundtrip(tmp_path) -> None:
+    ident = Identity.generate(org="acme", name="alice")
+    path = tmp_path / "alice.key"
+    ident.save(path)
+    loaded = Identity.load(path)
+    assert loaded.agent_id == ident.agent_id
+    assert loaded.public_key_bytes == ident.public_key_bytes
+    assert loaded.private_key_bytes == ident.private_key_bytes
+
+
+def test_save_refuses_overwrite(tmp_path) -> None:
+    ident = Identity.generate(org="acme", name="alice")
+    path = tmp_path / "alice.key"
+    ident.save(path)
+    with pytest.raises(IdentityError):
+        ident.save(path)
+    # With overwrite=True it succeeds.
+    ident.save(path, overwrite=True)
+
+
+def test_saved_file_has_0600_perms(tmp_path) -> None:
+    ident = Identity.generate(org="acme", name="alice")
+    path = tmp_path / "alice.key"
+    ident.save(path)
+    mode = stat.S_IMODE(os.stat(path).st_mode)
+    assert mode == 0o600, f"expected 0600 perms, got {oct(mode)}"
+
+
+def test_tampered_file_rejected(tmp_path) -> None:
+    ident = Identity.generate(org="acme", name="alice")
+    path = tmp_path / "alice.key"
+    ident.save(path)
+    # Corrupt the stored public_key_hex so it mismatches the private key.
+    content = path.read_text()
+    content = content.replace(ident.public_key_hex, "00" * 32)
+    path.write_text(content)
+    with pytest.raises(IdentityError, match="public_key_hex"):
+        Identity.load(path)
+
+
+def test_bad_org_rejected() -> None:
+    with pytest.raises(IdentityError):
+        Identity.generate(org="acme corp", name="alice")
+
+
+def test_empty_name_rejected() -> None:
+    with pytest.raises(IdentityError):
+        Identity.generate(org="acme", name="")
+
+
+def test_bad_secret_length_rejected() -> None:
+    with pytest.raises(IdentityError):
+        Identity.from_secret("acme", "alice", b"short")

aex_sdk-1.2.0a1/tests/test_wire.py

@@ -0,0 +1,111 @@
+"""Canonical wire bytes must be byte-identical to the Rust side.
+
+The expected byte strings here are the same golden vectors used in
+`crates/spize-core/src/wire.rs` tests. If you modify either side, update
+both in the same commit.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from aex_sdk import wire
+
+
+def test_registration_challenge_stable_bytes() -> None:
+    bytes_ = wire.registration_challenge_bytes(
+        public_key_hex="aabbcc",
+        org="acme",
+        name="alice",
+        nonce="0123456789abcdef0123456789abcdef",
+        issued_at_unix=1_700_000_000,
+    )
+    expected = (
+        b"spize-register:v1\n"
+        b"pub=aabbcc\n"
+        b"org=acme\n"
+        b"name=alice\n"
+        b"nonce=0123456789abcdef0123456789abcdef\n"
+        b"ts=1700000000"
+    )
+    assert bytes_ == expected
+
+
+def test_transfer_intent_stable_bytes() -> None:
+    bytes_ = wire.transfer_intent_bytes(
+        sender_agent_id="spize:acme/alice:aabbcc",
+        recipient="spize:acme/bob:ddeeff",
+        size_bytes=12345,
+        declared_mime="application/pdf",
+        filename="invoice.pdf",
+        nonce="0123456789abcdef0123456789abcdef",
+        issued_at_unix=1_700_000_000,
+    )
+    expected = (
+        b"spize-transfer-intent:v1\n"
+        b"sender=spize:acme/alice:aabbcc\n"
+        b"recipient=spize:acme/bob:ddeeff\n"
+        b"size=12345\n"
+        b"mime=application/pdf\n"
+        b"filename=invoice.pdf\n"
+        b"nonce=0123456789abcdef0123456789abcdef\n"
+        b"ts=1700000000"
+    )
+    assert bytes_ == expected
+
+
+def test_transfer_intent_empty_optionals() -> None:
+    bytes_ = wire.transfer_intent_bytes(
+        sender_agent_id="spize:acme/alice:aabbcc",
+        recipient="bob@example.com",
+        size_bytes=100,
+        declared_mime="",
+        filename="",
+        nonce="0123456789abcdef0123456789abcdef",
+        issued_at_unix=1_700_000_000,
+    )
+    s = bytes_.decode()
+    assert "mime=\n" in s
+    assert "filename=\n" in s
+
+
+def test_transfer_receipt_stable_bytes() -> None:
+    bytes_ = wire.transfer_receipt_bytes(
+        recipient_agent_id="spize:acme/bob:ddeeff",
+        transfer_id="tx_abc123",
+        action="ack",
+        nonce="0123456789abcdef0123456789abcdef",
+        issued_at_unix=1_700_000_000,
+    )
+    expected = (
+        b"spize-transfer-receipt:v1\n"
+        b"recipient=spize:acme/bob:ddeeff\n"
+        b"transfer=tx_abc123\n"
+        b"action=ack\n"
+        b"nonce=0123456789abcdef0123456789abcdef\n"
+        b"ts=1700000000"
+    )
+    assert bytes_ == expected
+
+
+def test_invalid_action_rejected() -> None:
+    with pytest.raises(ValueError):
+        wire.transfer_receipt_bytes(
+            "spize:acme/bob:ddeeff", "tx_abc", "overwrite",
+            "0123456789abcdef0123456789abcdef", 1,
+        )
+
+
+def test_short_nonce_rejected() -> None:
+    with pytest.raises(ValueError):
+        wire.registration_challenge_bytes(
+            "aa", "acme", "alice", "deadbeef", 100,
+        )
+
+
+def test_newline_in_field_rejected() -> None:
+    with pytest.raises(ValueError):
+        wire.registration_challenge_bytes(
+            "aa", "ac\nme", "alice",
+            "0123456789abcdef0123456789abcdef", 100,
+        )