agentsync-sdk 1.0.0__tar.gz

agentsync_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: agentsync-sdk
+Version: 1.0.0
+Summary: Python SDK for the AgentSync x402 micropayment gateway on Radix
+License: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT 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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: PyNaCl>=1.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: pytest-httpx>=0.30.0; extra == "dev"
+
+# AgentSync Python SDK
+
+Python SDK for the AgentSync x402 micropayment gateway on Radix.
+
+## Install
+
+```bash
+pip install agentsync-sdk
+```
+
+> Note: the distribution name is `agentsync-sdk`; the import package remains
+> `agentsync` (`from agentsync import ...`). For local development use
+> `pip install -e .` in the repo.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Platform Attestation Verification
+
+Verify a platform-signed attestation envelope against the trusted platform
+Ed25519 public key:
+
+```python
+from agentsync import SignatureEnvelope, verify_platform_attestation
+
+trusted_public_key = "9afcc1cf66b256d7d9567a906fba4317305d92c3e7fd7f27386dffe182332576"
+envelope = SignatureEnvelope(
+    payload="account_tdx_2_...:5.500000:0",
+    signature="<128-char hex>",
+    public_key=trusted_public_key,
+    algorithm="ed25519+sha256",
+)
+
+valid = verify_platform_attestation(envelope, trusted_public_key)  # bool
+```
+
+`verify_platform_attestation()` is pure and synchronous: the trusted key is
+injected by the caller and never fetched from the network. It asserts that the
+envelope's `public_key` matches the trusted key before verifying the
+`Ed25519(SHA-256(payload))` signature.
+
+The TypeScript counterpart lives at [`../sdk-typescript`](../sdk-typescript).

agentsync_sdk-1.0.0/README.md

@@ -0,0 +1,46 @@
+# AgentSync Python SDK
+
+Python SDK for the AgentSync x402 micropayment gateway on Radix.
+
+## Install
+
+```bash
+pip install agentsync-sdk
+```
+
+> Note: the distribution name is `agentsync-sdk`; the import package remains
+> `agentsync` (`from agentsync import ...`). For local development use
+> `pip install -e .` in the repo.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Platform Attestation Verification
+
+Verify a platform-signed attestation envelope against the trusted platform
+Ed25519 public key:
+
+```python
+from agentsync import SignatureEnvelope, verify_platform_attestation
+
+trusted_public_key = "9afcc1cf66b256d7d9567a906fba4317305d92c3e7fd7f27386dffe182332576"
+envelope = SignatureEnvelope(
+    payload="account_tdx_2_...:5.500000:0",
+    signature="<128-char hex>",
+    public_key=trusted_public_key,
+    algorithm="ed25519+sha256",
+)
+
+valid = verify_platform_attestation(envelope, trusted_public_key)  # bool
+```
+
+`verify_platform_attestation()` is pure and synchronous: the trusted key is
+injected by the caller and never fetched from the network. It asserts that the
+envelope's `public_key` matches the trusted key before verifying the
+`Ed25519(SHA-256(payload))` signature.
+
+The TypeScript counterpart lives at [`../sdk-typescript`](../sdk-typescript).

agentsync_sdk-1.0.0/agentsync/__init__.py

@@ -0,0 +1,88 @@
+"""
+AgentSync Python SDK.
+
+Idiomatic Python client for the AgentSync x402 micropayment gateway
+on the Radix ledger. Supports ROLA authentication, Mode A (credit
+buffer), Mode B (single-pay), and Mode C (RAP/1 bundled non-custodial
+on-chain settlement), plus catalog discovery and withdrawal attestation.
+"""
+
+from .attestation import SignatureEnvelope, verify_platform_attestation
+from .client import AgentSyncClient, CatalogModule, set_default_registry_component
+from .errors import AuthenticationError, GatewayError, InsufficientCreditError
+from .rap import generate_composite_manifest, generate_rap_manifest
+from .types import (
+    AgentSyncClientOptions,
+    AgentSyncFetchOptions,
+    AuthChallengeResponse,
+    AuthVerifyResponse,
+    CatalogEntry,
+    CatalogResponse,
+    CompositeManifestConfig,
+    CompositePurchase,
+    InsufficientCreditPayload,
+    PremiumDataResponse,
+    RadixAccountAddress,
+    RapManifestConfig,
+    RapPublicKey,
+    RapSignatureValue,
+    RapHash,
+    RapRootManifest,
+    RapNotary,
+    RapDraftInputs,
+    RapEconomicParams,
+    RapSignatureFile,
+    RapPayload,
+    RolaSigner,
+    SessionDebitEntry,
+    SessionSummary,
+    SettleResponse,
+    WithdrawalPayload,
+    WithdrawResponse,
+    UsdcDecimal,
+)
+
+__all__ = [
+    # Client
+    "AgentSyncClient",
+    "CatalogModule",
+    "set_default_registry_component",
+    # Standalone functions
+    "generate_composite_manifest",
+    "generate_rap_manifest",
+    "verify_platform_attestation",
+    # Errors
+    "AuthenticationError",
+    "GatewayError",
+    "InsufficientCreditError",
+    # Types
+    "AgentSyncClientOptions",
+    "AgentSyncFetchOptions",
+    "AuthChallengeResponse",
+    "AuthVerifyResponse",
+    "CatalogEntry",
+    "CatalogResponse",
+    "CompositeManifestConfig",
+    "CompositePurchase",
+    "InsufficientCreditPayload",
+    "PremiumDataResponse",
+    "RadixAccountAddress",
+    "RapManifestConfig",
+    "RapPublicKey",
+    "RapSignatureValue",
+    "RapHash",
+    "RapRootManifest",
+    "RapNotary",
+    "RapDraftInputs",
+    "RapEconomicParams",
+    "RapSignatureFile",
+    "RapPayload",
+    "RolaSigner",
+    "SessionDebitEntry",
+    "SessionSummary",
+    "SettleResponse",
+    "SignatureEnvelope",
+    "WithdrawalPayload",
+    "WithdrawResponse",
+    "UsdcDecimal",
+]

agentsync_sdk-1.0.0/agentsync/attestation.py

@@ -0,0 +1,89 @@
+"""
+Platform attestation verification for AgentSync.
+
+Verifies the Ed25519 signature over the SHA-256 pre-hash of an attestation
+payload, mirroring the platform signing path in ``worker/src/attestation.ts``.
+
+Signature scheme: SHA-256 pre-hash → Ed25519 verify (matches Scrypto's
+``verify_ed25519`` convention where messages are hashed before verifying).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+from dataclasses import dataclass
+
+from nacl.exceptions import BadSignatureError
+from nacl.signing import VerifyKey
+
+SUPPORTED_ALGORITHM = "ed25519+sha256"
+
+
+@dataclass(frozen=True)
+class SignatureEnvelope:
+    """Attestation envelope produced by the platform."""
+
+    payload: str
+    signature: str
+    public_key: str
+    algorithm: str
+
+
+def verify_platform_attestation(
+    envelope: SignatureEnvelope,
+    trusted_public_key: str,
+) -> bool:
+    """Verify a platform attestation envelope against the trusted platform key.
+
+    The function is pure and synchronous: the trusted public key is injected by
+    the caller, never fetched from the network. To prevent tautological spoofing
+    (an attacker signing a tampered payload with their own key), the envelope's
+    ``public_key`` must match ``trusted_public_key`` before any signature check.
+
+    Args:
+        envelope: Attestation envelope (payload, signature, public key,
+            algorithm) produced by the platform.
+        trusted_public_key: Hex-encoded 32-byte Ed25519 public key the caller
+            has independently verified as the platform's key.
+
+    Returns:
+        ``True`` if the algorithm is supported, the embedded key matches the
+        trusted key, and the signature verifies over ``SHA-256(payload)``.
+    """
+    if envelope.algorithm != SUPPORTED_ALGORITHM:
+        return False
+
+    if not _constant_time_hex_equals(envelope.public_key, trusted_public_key):
+        return False
+
+    public_key = _hex_to_bytes(trusted_public_key)
+    signature = _hex_to_bytes(envelope.signature)
+    if public_key is None or signature is None:
+        return False
+    if len(public_key) != 32 or len(signature) != 64:
+        return False
+
+    # SHA-256 pre-hash — matches the platform's Ed25519(SHA-256(payload)) scheme.
+    message_hash = hashlib.sha256(envelope.payload.encode("utf-8")).digest()
+
+    try:
+        VerifyKey(public_key).verify(message_hash, signature)
+        return True
+    except (BadSignatureError, ValueError):
+        return False
+
+
+def _hex_to_bytes(value: str) -> bytes | None:
+    """Decode a hex string to bytes, returning ``None`` on malformed input."""
+    try:
+        return bytes.fromhex(value)
+    except ValueError:
+        return None
+
+
+def _constant_time_hex_equals(a: str, b: str) -> bool:
+    """Compare two hex strings in constant time."""
+    if len(a) != len(b):
+        return False
+    return hmac.compare_digest(a.encode("utf-8"), b.encode("utf-8"))