@agentlayer.tech/wallet 0.1.101 → 0.1.102

package/agent-wallet/agent_wallet/connectors/client.py

@@ -0,0 +1,308 @@
+"""HTTPS client for untrusted read-only connector endpoints."""
+
+from __future__ import annotations
+
+import ipaddress
+import json
+import socket
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Callable, Iterable
+from urllib.parse import urlparse
+
+import httpx
+import httpcore
+from jsonschema import Draft202012Validator, SchemaError, ValidationError
+
+from agent_wallet.connectors.catalog import resolve_connector_tool
+from agent_wallet.connectors.registry import ConnectorRegistry
+
+
+MAX_CONNECTOR_RESPONSE_BYTES = 1024 * 1024
+MAX_RESPONSE_LIFETIME_SECONDS = 300
+RESERVED_WRITE_RESULT_KEYS = frozenset(
+    {
+        "approval_token",
+        "broadcast_request",
+        "evm_transaction_intent",
+        "payment_intent",
+        "raw_transaction",
+        "signed_transaction",
+        "signing_request",
+        "solana_transaction_intent",
+        "transaction_intent",
+    }
+)
+Resolver = Callable[[str], Iterable[str]]
+
+
+class ConnectorInvocationError(RuntimeError):
+    """Raised when a connector request or response cannot be trusted."""
+
+
+def _default_resolver(hostname: str) -> list[str]:
+    try:
+        records = socket.getaddrinfo(hostname, 443, type=socket.SOCK_STREAM)
+    except OSError as exc:
+        raise ConnectorInvocationError(f"Connector hostname could not be resolved: {hostname}.") from exc
+    return sorted({str(record[4][0]) for record in records})
+
+
+def _validate_endpoint_url(url: str) -> str:
+    parsed = urlparse(url)
+    hostname = str(parsed.hostname or "").lower()
+    if parsed.scheme != "https" or not hostname or parsed.username or parsed.password:
+        raise ConnectorInvocationError("Connector endpoint must be public HTTPS without credentials.")
+    if hostname == "localhost" or hostname.endswith(".localhost") or hostname.endswith(".local"):
+        raise ConnectorInvocationError("Connector endpoint cannot use a local hostname.")
+    return hostname
+
+
+def _resolve_public_addresses(hostname: str, resolver: Resolver) -> list[str]:
+    addresses = list(resolver(hostname))
+    if not addresses:
+        raise ConnectorInvocationError("Connector endpoint did not resolve to an address.")
+    for raw_address in addresses:
+        try:
+            address = ipaddress.ip_address(raw_address)
+        except ValueError as exc:
+            raise ConnectorInvocationError("Connector endpoint resolved to an invalid address.") from exc
+        if not address.is_global:
+            raise ConnectorInvocationError(
+                f"Connector endpoint resolved to a non-public address: {raw_address}."
+            )
+    return addresses
+
+
+def _assert_public_endpoint(url: str, resolver: Resolver) -> None:
+    """Validate mocked/injected clients that do not use the pinned transport."""
+
+    _resolve_public_addresses(_validate_endpoint_url(url), resolver)
+
+
+class _PinnedPublicNetworkBackend(httpcore.AsyncNetworkBackend):
+    """Resolve and validate at connect time, then open TCP to the validated IP.
+
+    HTTP Core retains the original origin hostname and therefore still uses it
+    for TLS SNI and certificate verification. Only the TCP destination is
+    replaced, closing the DNS-validation-to-connect race.
+    """
+
+    def __init__(
+        self,
+        resolver: Resolver,
+        network_backend: httpcore.AsyncNetworkBackend | None = None,
+    ) -> None:
+        self._resolver = resolver
+        self._network_backend = network_backend or httpcore.AnyIOBackend()
+
+    async def connect_tcp(
+        self,
+        host: str,
+        port: int,
+        timeout: float | None = None,
+        local_address: str | None = None,
+        socket_options: Iterable[tuple[int, int, int | bytes]] | None = None,
+    ) -> httpcore.AsyncNetworkStream:
+        addresses = _resolve_public_addresses(host.lower(), self._resolver)
+        return await self._network_backend.connect_tcp(
+            addresses[0],
+            port,
+            timeout=timeout,
+            local_address=local_address,
+            socket_options=socket_options,
+        )
+
+    async def connect_unix_socket(
+        self,
+        path: str,
+        timeout: float | None = None,
+        socket_options: Iterable[tuple[int, int, int | bytes]] | None = None,
+    ) -> httpcore.AsyncNetworkStream:
+        raise ConnectorInvocationError("Connector Unix socket transport is not allowed.")
+
+    async def sleep(self, seconds: float) -> None:
+        await self._network_backend.sleep(seconds)
+
+
+class _PinnedPublicAsyncTransport(httpx.AsyncHTTPTransport):
+    """HTTPX transport whose connection pool uses connect-time DNS pinning."""
+
+    def __init__(self, resolver: Resolver) -> None:
+        super().__init__(retries=0)
+        self._pool = httpcore.AsyncConnectionPool(
+            retries=0,
+            network_backend=_PinnedPublicNetworkBackend(resolver),
+        )
+
+
+def _parse_expiry(value: Any) -> datetime:
+    if not isinstance(value, str) or not value:
+        raise ConnectorInvocationError("Connector response expires_at is required.")
+    try:
+        expiry = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise ConnectorInvocationError("Connector response expires_at is invalid.") from exc
+    if expiry.tzinfo is None:
+        raise ConnectorInvocationError("Connector response expires_at must include a timezone.")
+    now = datetime.now(timezone.utc)
+    remaining = (expiry.astimezone(timezone.utc) - now).total_seconds()
+    if remaining <= 0:
+        raise ConnectorInvocationError("Connector response has expired.")
+    if remaining > MAX_RESPONSE_LIFETIME_SECONDS:
+        raise ConnectorInvocationError("Connector response expiry exceeds the allowed lifetime.")
+    return expiry
+
+
+def _validate_json(instance: Any, schema: dict[str, Any], *, label: str) -> None:
+    try:
+        Draft202012Validator.check_schema(schema)
+        Draft202012Validator(schema).validate(instance)
+    except SchemaError as exc:
+        raise ConnectorInvocationError(f"Connector {label} schema is invalid: {exc.message}") from exc
+    except ValidationError as exc:
+        raise ConnectorInvocationError(f"Connector {label} does not match its schema: {exc.message}") from exc
+
+
+def _reject_embedded_write_payload(result: Any) -> None:
+    pending = [result]
+    while pending:
+        value = pending.pop()
+        if isinstance(value, dict):
+            for key, item in value.items():
+                if str(key).lower() in RESERVED_WRITE_RESULT_KEYS:
+                    raise ConnectorInvocationError(
+                        f"Read-only connector result contains reserved write field: {key}."
+                    )
+                pending.append(item)
+        elif isinstance(value, list):
+            pending.extend(value)
+
+
+class ConnectorReadClient:
+    """Invoke enabled read-only connector tools with strict identity binding."""
+
+    def __init__(
+        self,
+        registry: ConnectorRegistry | None = None,
+        *,
+        http_client: httpx.AsyncClient | None = None,
+        resolver: Resolver | None = None,
+    ):
+        self.registry = registry or ConnectorRegistry()
+        self._http_client = http_client
+        self._resolver = resolver or _default_resolver
+
+    async def invoke(
+        self,
+        host_tool_name: str,
+        arguments: dict[str, Any],
+        *,
+        context: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        tool = resolve_connector_tool(host_tool_name, self.registry, include_write=False)
+        if tool["read_only"] is not True:
+            raise ConnectorInvocationError("ConnectorReadClient accepts only read-only tools.")
+        if not isinstance(arguments, dict):
+            raise ConnectorInvocationError("Connector tool arguments must be an object.")
+        _validate_json(arguments, tool["input_schema"], label="tool input")
+
+        connector_id = str(tool["connector_id"])
+        connector_version = str(tool["connector_version"])
+        manifest = self.registry.load_manifest(connector_id, connector_version)
+        transport = manifest["transport"]
+        base_url = str(transport["url"]).rstrip("/")
+        _validate_endpoint_url(base_url)
+        if self._http_client is not None:
+            _assert_public_endpoint(base_url, self._resolver)
+        request_id = str(uuid.uuid4())
+
+        safe_context: dict[str, Any] = {}
+        supplied_context = context if isinstance(context, dict) else {}
+        for field in ("chain", "network", "chain_id"):
+            value = supplied_context.get(field)
+            if value is not None:
+                safe_context[field] = value
+        if manifest["permissions"].get("wallet_address") is True:
+            wallet_address = supplied_context.get("wallet_address")
+            if isinstance(wallet_address, str) and wallet_address.strip():
+                safe_context["wallet_address"] = wallet_address.strip()
+
+        request_payload = {
+            "protocol_version": 1,
+            "request_id": request_id,
+            "connector": {
+                "id": connector_id,
+                "version": connector_version,
+                **(
+                    {"artifact_digest": manifest["artifact_digest"]}
+                    if manifest.get("artifact_digest")
+                    else {}
+                ),
+            },
+            "tool": str(tool["connector_tool"]),
+            "arguments": arguments,
+            "context": safe_context,
+        }
+
+        owns_client = self._http_client is None
+        client = self._http_client or httpx.AsyncClient(
+            transport=_PinnedPublicAsyncTransport(self._resolver),
+            follow_redirects=False,
+            trust_env=False,
+            headers={"Accept": "application/json", "Content-Type": "application/json"},
+        )
+        try:
+            try:
+                response = await client.post(
+                    f"{base_url}/invoke",
+                    json=request_payload,
+                    timeout=float(transport.get("timeout_ms", 10000)) / 1000.0,
+                )
+            except httpx.HTTPError as exc:
+                raise ConnectorInvocationError(f"Connector request failed: {exc}") from exc
+        finally:
+            if owns_client:
+                await client.aclose()
+
+        if 300 <= response.status_code < 400:
+            raise ConnectorInvocationError("Connector redirects are not allowed.")
+        if response.status_code != 200:
+            raise ConnectorInvocationError(f"Connector returned HTTP {response.status_code}.")
+        if len(response.content) > MAX_CONNECTOR_RESPONSE_BYTES:
+            raise ConnectorInvocationError("Connector response exceeds the size limit.")
+        try:
+            payload = response.json()
+        except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+            raise ConnectorInvocationError("Connector response is not valid JSON.") from exc
+        if not isinstance(payload, dict):
+            raise ConnectorInvocationError("Connector response root must be an object.")
+        if payload.get("protocol_version") != 1 or payload.get("request_id") != request_id:
+            raise ConnectorInvocationError("Connector response binding is invalid.")
+        response_connector = payload.get("connector")
+        if not isinstance(response_connector, dict):
+            raise ConnectorInvocationError("Connector response identity is missing.")
+        if (
+            response_connector.get("id") != connector_id
+            or response_connector.get("version") != connector_version
+        ):
+            raise ConnectorInvocationError("Connector response identity does not match the request.")
+        expected_artifact = manifest.get("artifact_digest")
+        if expected_artifact and response_connector.get("artifact_digest") != expected_artifact:
+            raise ConnectorInvocationError("Connector response artifact digest does not match.")
+        if payload.get("tool") != tool["connector_tool"]:
+            raise ConnectorInvocationError("Connector response tool does not match the request.")
+        if payload.get("kind") != "read_result":
+            raise ConnectorInvocationError("Read-only connector returned a non-read result.")
+        _parse_expiry(payload.get("expires_at"))
+        result = payload.get("result")
+        _reject_embedded_write_payload(result)
+        _validate_json(result, tool["output_schema"], label="tool output")
+        return {
+            "connector_id": connector_id,
+            "connector_version": connector_version,
+            "tool": str(tool["connector_tool"]),
+            "untrusted_external_data": True,
+            "result": result,
+            "expires_at": payload["expires_at"],
+        }

package/agent-wallet/agent_wallet/connectors/intent_policy.py

@@ -0,0 +1,243 @@
+"""Fail-closed local policy for unsigned write-capable connector intents."""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone
+from typing import Any
+
+from agent_wallet.connectors.manifest import DIGEST_PATTERN, validate_connector_manifest
+
+
+EVM_ADDRESS_PATTERN = re.compile(r"^0x[0-9a-fA-F]{40}$")
+HEX_DATA_PATTERN = re.compile(r"^0x(?:[0-9a-fA-F]{2})*$")
+UINT_PATTERN = re.compile(r"^(0|[1-9][0-9]*)$")
+ERC20_APPROVE_SELECTOR = "0x095ea7b3"
+MAX_UINT256 = (1 << 256) - 1
+MAX_INTENT_LIFETIME_SECONDS = 300
+
+
+class ConnectorIntentPolicyError(ValueError):
+    """Raised when a connector write intent is unsafe or incorrectly bound."""
+
+
+def _require_object(value: Any, field: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise ConnectorIntentPolicyError(f"{field} must be an object.")
+    return value
+
+
+def _require_uint(value: Any, field: str, *, positive: bool = False) -> int:
+    if not isinstance(value, str) or not UINT_PATTERN.fullmatch(value):
+        raise ConnectorIntentPolicyError(f"{field} must be an unsigned integer string.")
+    number = int(value)
+    if number >= 1 << 256:
+        raise ConnectorIntentPolicyError(f"{field} exceeds uint256.")
+    if positive and number <= 0:
+        raise ConnectorIntentPolicyError(f"{field} must be greater than zero.")
+    return number
+
+
+def _require_address(value: Any, field: str) -> str:
+    if not isinstance(value, str) or not EVM_ADDRESS_PATTERN.fullmatch(value):
+        raise ConnectorIntentPolicyError(f"{field} must be an EVM address.")
+    return value.lower()
+
+
+def _validate_expiry(value: Any) -> str:
+    if not isinstance(value, str) or not value:
+        raise ConnectorIntentPolicyError("expires_at is required.")
+    try:
+        expiry = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise ConnectorIntentPolicyError("expires_at is invalid.") from exc
+    if expiry.tzinfo is None:
+        raise ConnectorIntentPolicyError("expires_at must include a timezone.")
+    remaining = (expiry.astimezone(timezone.utc) - datetime.now(timezone.utc)).total_seconds()
+    if remaining <= 0:
+        raise ConnectorIntentPolicyError("Connector intent has expired.")
+    if remaining > MAX_INTENT_LIFETIME_SECONDS:
+        raise ConnectorIntentPolicyError("Connector intent expiry exceeds the allowed lifetime.")
+    return value
+
+
+def _evm_contract_policy(manifest: dict[str, Any], chain_id: int) -> dict[str, set[str]]:
+    result: dict[str, set[str]] = {}
+    for raw_policy in manifest.get("chains") or []:
+        if not isinstance(raw_policy, dict) or raw_policy.get("chain") != "evm":
+            continue
+        chain_ids = raw_policy.get("chain_ids")
+        if not isinstance(chain_ids, list) or chain_id not in chain_ids:
+            continue
+        for raw_contract in raw_policy.get("contracts") or []:
+            if not isinstance(raw_contract, dict) or raw_contract.get("chain_id") != chain_id:
+                continue
+            address = _require_address(raw_contract.get("address"), "manifest contract address")
+            selectors = raw_contract.get("selectors")
+            if not isinstance(selectors, list) or not selectors:
+                raise ConnectorIntentPolicyError("Manifest contract selectors are missing.")
+            result[address] = {str(selector).lower() for selector in selectors}
+    if not result:
+        raise ConnectorIntentPolicyError(f"Connector is not allowed on EVM chain {chain_id}.")
+    return result
+
+
+def _write_tool(manifest: dict[str, Any], tool_name: Any) -> dict[str, Any]:
+    if not isinstance(tool_name, str):
+        raise ConnectorIntentPolicyError("tool is required.")
+    for tool in manifest["tools"]:
+        if isinstance(tool, dict) and tool.get("name") == tool_name:
+            if tool.get("read_only") is True:
+                raise ConnectorIntentPolicyError("A read-only connector tool cannot return an intent.")
+            return tool
+    raise ConnectorIntentPolicyError(f"Connector write tool is not declared: {tool_name}.")
+
+
+def validate_evm_transaction_intent(
+    manifest_payload: dict[str, Any],
+    intent_payload: dict[str, Any],
+    *,
+    wallet_address: str,
+) -> dict[str, Any]:
+    """Validate an unsigned EVM intent and return an approval-safe summary.
+
+    This function does not simulate, sign, approve, or broadcast. Its output is
+    suitable as input to the later simulation and preview binding layers.
+    """
+
+    manifest = validate_connector_manifest(manifest_payload)
+    intent = _require_object(intent_payload, "intent")
+    if manifest["trust"] != "verified_write":
+        raise ConnectorIntentPolicyError("Only verified_write connectors may return intents.")
+    if manifest["permissions"].get("transaction_intents") is not True:
+        raise ConnectorIntentPolicyError("Connector is not permitted to return transaction intents.")
+    if intent.get("protocol_version") != 1 or intent.get("kind") != "evm_transaction_intent":
+        raise ConnectorIntentPolicyError("Unsupported EVM connector intent version or kind.")
+    if intent.get("connector_id") != manifest["id"]:
+        raise ConnectorIntentPolicyError("Connector intent id does not match the manifest.")
+    if intent.get("connector_version") != manifest["version"]:
+        raise ConnectorIntentPolicyError("Connector intent version does not match the manifest.")
+    if intent.get("artifact_digest") != manifest.get("artifact_digest"):
+        raise ConnectorIntentPolicyError("Connector intent artifact digest does not match.")
+    quote_fingerprint = intent.get("quote_fingerprint")
+    if not isinstance(quote_fingerprint, str) or not DIGEST_PATTERN.fullmatch(quote_fingerprint):
+        raise ConnectorIntentPolicyError("quote_fingerprint must be a lowercase sha256 digest.")
+    tool = _write_tool(manifest, intent.get("tool"))
+    expires_at = _validate_expiry(intent.get("expires_at"))
+
+    chain_id = intent.get("chain_id")
+    if not isinstance(chain_id, int) or isinstance(chain_id, bool) or chain_id <= 0:
+        raise ConnectorIntentPolicyError("chain_id must be a positive integer.")
+    contract_policy = _evm_contract_policy(manifest, chain_id)
+    expected_wallet = _require_address(wallet_address, "wallet_address")
+    intent_from = _require_address(intent.get("from"), "from")
+    if intent_from != expected_wallet:
+        raise ConnectorIntentPolicyError("Connector intent from address does not match the wallet.")
+
+    calls = intent.get("calls")
+    if not isinstance(calls, list) or not 1 <= len(calls) <= 16:
+        raise ConnectorIntentPolicyError("calls must contain between 1 and 16 entries.")
+    normalized_calls: list[dict[str, Any]] = []
+    for index, raw_call in enumerate(calls):
+        call = _require_object(raw_call, f"calls[{index}]")
+        target = _require_address(call.get("to"), f"calls[{index}].to")
+        selectors = contract_policy.get(target)
+        if selectors is None:
+            raise ConnectorIntentPolicyError(f"calls[{index}] targets an unapproved contract.")
+        data = call.get("data")
+        if not isinstance(data, str) or not HEX_DATA_PATTERN.fullmatch(data) or len(data) < 10:
+            raise ConnectorIntentPolicyError(f"calls[{index}].data must contain EVM calldata.")
+        selector = data[:10].lower()
+        if selector == ERC20_APPROVE_SELECTOR:
+            raise ConnectorIntentPolicyError(
+                "Connector intents must declare approvals separately from protocol calls."
+            )
+        if selector not in selectors:
+            raise ConnectorIntentPolicyError(f"calls[{index}] uses an unapproved selector.")
+        value_wei = _require_uint(call.get("value_wei"), f"calls[{index}].value_wei")
+        normalized_calls.append(
+            {
+                "to": target,
+                "selector": selector,
+                "value_wei": str(value_wei),
+                "calldata_bytes": (len(data) - 2) // 2,
+            }
+        )
+
+    approvals = intent.get("approvals")
+    if not isinstance(approvals, list) or len(approvals) > 16:
+        raise ConnectorIntentPolicyError("approvals must be an array of at most 16 entries.")
+    normalized_approvals: list[dict[str, str]] = []
+    for index, raw_approval in enumerate(approvals):
+        approval = _require_object(raw_approval, f"approvals[{index}]")
+        token = _require_address(approval.get("token"), f"approvals[{index}].token")
+        spender = _require_address(approval.get("spender"), f"approvals[{index}].spender")
+        if spender not in contract_policy:
+            raise ConnectorIntentPolicyError(f"approvals[{index}] uses an unapproved spender.")
+        amount = _require_uint(
+            approval.get("amount_raw"), f"approvals[{index}].amount_raw", positive=True
+        )
+        if amount == MAX_UINT256:
+            raise ConnectorIntentPolicyError("Unlimited connector token approvals are prohibited.")
+        normalized_approvals.append(
+            {
+                "token": token,
+                "spender": spender,
+                "amount_raw": str(amount),
+            }
+        )
+
+    effects = intent.get("expected_effects")
+    if not isinstance(effects, list) or not 1 <= len(effects) <= 64:
+        raise ConnectorIntentPolicyError("expected_effects must contain between 1 and 64 entries.")
+    normalized_effects: list[dict[str, Any]] = []
+    for index, raw_effect in enumerate(effects):
+        effect = _require_object(raw_effect, f"expected_effects[{index}]")
+        effect_type = effect.get("type")
+        if effect_type not in {"asset", "debt", "position", "protocol_fee", "network_fee"}:
+            raise ConnectorIntentPolicyError(f"expected_effects[{index}].type is unsupported.")
+        direction = effect.get("direction")
+        if direction not in {"debit", "credit", "increase", "decrease"}:
+            raise ConnectorIntentPolicyError(f"expected_effects[{index}].direction is unsupported.")
+        asset = effect.get("asset")
+        if not isinstance(asset, str) or not asset.strip() or len(asset) > 128:
+            raise ConnectorIntentPolicyError(f"expected_effects[{index}].asset is invalid.")
+        amount = _require_uint(effect.get("amount"), f"expected_effects[{index}].amount")
+        normalized_effects.append(
+            {
+                "type": effect_type,
+                "asset": asset.strip(),
+                "direction": direction,
+                "amount": str(amount),
+                **(
+                    {"recipient": str(effect["recipient"])}
+                    if isinstance(effect.get("recipient"), str) and effect["recipient"]
+                    else {}
+                ),
+            }
+        )
+
+    return {
+        "operation": "AgentLayer connector EVM transaction",
+        "connector_id": str(manifest["id"]),
+        "connector_version": str(manifest["version"]),
+        "artifact_digest": str(manifest["artifact_digest"]),
+        "tool": str(tool["name"]),
+        "chain": "evm",
+        "chain_id": chain_id,
+        "from": expected_wallet,
+        "quote_fingerprint": quote_fingerprint,
+        "expires_at": expires_at,
+        "calls": normalized_calls,
+        "approvals": normalized_approvals,
+        "expected_effects": normalized_effects,
+        "validation": {
+            "verified_connector": True,
+            "wallet_bound": True,
+            "targets_allowlisted": True,
+            "selectors_allowlisted": True,
+            "approvals_bounded": True,
+            "simulated": False,
+        },
+    }
+