agentbadge 0.1.0__py3-none-any.whl

agentbadge/__init__.py

@@ -0,0 +1,55 @@
+"""Agent Badge Python SDK."""
+
+from agentbadge_core.agent_card import AgentCard, badge_fragment, patch_badge
+from agentbadge_core.protocols import (
+    SUPPORTED_PROTOCOLS,
+    badge_headers,
+    find_badge,
+    placement_table,
+)
+
+from agentbadge.auth import agent_auth_headers
+from agentbadge.client import AgentBadgeClient
+from agentbadge.types import (
+    AckResponse,
+    AgentBadgeAPIError,
+    AgentMessage,
+    BadgeDescriptor,
+    BadgeFeatures,
+    BadgeMetadata,
+    ChallengeInfo,
+    EnrollResponse,
+    MessagesResponse,
+    SendMessageResponse,
+    SubscribeResponse,
+    VerificationResponse,
+)
+from agentbadge.verify import verify_agent_card, verify_badge
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "SUPPORTED_PROTOCOLS",
+    "AckResponse",
+    "AgentBadgeAPIError",
+    "AgentBadgeClient",
+    "AgentCard",
+    "AgentMessage",
+    "BadgeDescriptor",
+    "BadgeFeatures",
+    "BadgeMetadata",
+    "ChallengeInfo",
+    "EnrollResponse",
+    "MessagesResponse",
+    "SendMessageResponse",
+    "SubscribeResponse",
+    "VerificationResponse",
+    "agent_auth_headers",
+    "badge_fragment",
+    "badge_headers",
+    "find_badge",
+    "patch_badge",
+    "placement_table",
+    "verify_agent_card",
+    "verify_badge",
+]

agentbadge/auth.py

@@ -0,0 +1,29 @@
+"""Agent-side authentication for the messaging endpoints.
+
+The agent proves control of its card key by signing
+"<badgeId>:<timestamp>:<nonce>" with the Ed25519 key its AgentCard exposes.
+"""
+
+import base64
+import secrets
+import time
+
+from agentbadge_core.crypto import Ed25519KeyPair
+
+
+def agent_auth_headers(
+    badge_id: str,
+    keypair: Ed25519KeyPair,
+    timestamp: int | None = None,
+    nonce: str | None = None,
+) -> dict[str, str]:
+    """The X-Agent-Signature / X-Agent-Timestamp / X-Agent-Nonce headers for one
+    request. Each call uses a fresh nonce — headers must not be reused."""
+    ts = timestamp if timestamp is not None else int(time.time())
+    n = nonce if nonce is not None else secrets.token_hex(16)
+    signature = keypair.sign(f"{badge_id}:{ts}:{n}".encode("ascii"))
+    return {
+        "X-Agent-Signature": base64.b64encode(signature).decode("ascii"),
+        "X-Agent-Timestamp": str(ts),
+        "X-Agent-Nonce": n,
+    }

agentbadge/client.py

@@ -0,0 +1,296 @@
+"""Async HTTP client for the Agent Badge API."""
+
+from datetime import datetime
+from typing import Any
+
+import httpx
+from agentbadge_core.agent_card import AgentCard
+from agentbadge_core.constants import EXTENSION_URI
+from agentbadge_core.crypto import Ed25519KeyPair
+
+from agentbadge.auth import agent_auth_headers
+from agentbadge.types import (
+    AckResponse,
+    AgentBadgeAPIError,
+    BadgeFeatures,
+    BadgeMetadata,
+    EnrollResponse,
+    MessagesResponse,
+    SendMessageResponse,
+    SubscribeResponse,
+    VerificationResponse,
+)
+
+
+class AgentBadgeClient:
+    """Thin typed client for the Agent Badge API.
+
+    An `httpx.AsyncClient` may be injected (tests pass one backed by
+    `httpx.MockTransport`); it is used both for API calls and for fetching
+    AgentCards in `verify_agent_card`. Operator-side messaging
+    (`send_message`) requires `admin_api_key`; agent-side messaging (poll,
+    ack, webhooks) signs each request with the agent's Ed25519 keypair.
+    """
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:8000",
+        client: httpx.AsyncClient | None = None,
+        admin_api_key: str | None = None,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self._client = client
+        self._owns_client = client is None
+        self.admin_api_key = admin_api_key
+
+    async def _http(self) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=10.0, follow_redirects=True)
+        return self._client
+
+    async def aclose(self) -> None:
+        if self._owns_client and self._client is not None:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> "AgentBadgeClient":
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.aclose()
+
+    async def _request(self, method: str, path_or_url: str, **kwargs: Any) -> Any:
+        url = path_or_url if path_or_url.startswith("http") else f"{self.base_url}{path_or_url}"
+        client = await self._http()
+        response = await client.request(method, url, **kwargs)
+        if response.status_code >= 400:
+            try:
+                body = response.json()
+            except ValueError:
+                body = {}
+            raise AgentBadgeAPIError(
+                status_code=response.status_code,
+                error=body.get("error", "http_error"),
+                message=body.get("message", response.text[:200]),
+                request_id=body.get("requestId"),
+            )
+        if response.status_code == 204 or not response.content:
+            return None
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise AgentBadgeAPIError(
+                status_code=response.status_code,
+                error="invalid_response",
+                message=f"Response from {url} is not valid JSON",
+            ) from exc
+
+    async def verify_badge(self, badge_id: str) -> VerificationResponse:
+        """GET /v1/verify/{badge_id} as a typed VerificationResponse."""
+        data = await self._request("GET", f"/v1/verify/{badge_id}")
+        return VerificationResponse.model_validate(data)
+
+    async def verify_agent_card(self, card_url: str) -> VerificationResponse:
+        """Fetch an AgentCard, find its Agent Badge extension, verify the badge."""
+        card = await self._request("GET", card_url)
+        if not isinstance(card, dict):
+            raise AgentBadgeAPIError(
+                200, "card_invalid", f"AgentCard at {card_url} is not an object"
+            )
+        extension = AgentCard.find_extension(card, EXTENSION_URI)
+        if extension is None:
+            raise AgentBadgeAPIError(
+                200,
+                "badge_extension_not_found",
+                f"AgentCard at {card_url} carries no Agent Badge extension ({EXTENSION_URI})",
+            )
+        badge_id = (extension.get("params") or {}).get("badgeId")
+        if not badge_id:
+            raise AgentBadgeAPIError(
+                200,
+                "badge_id_missing",
+                "Agent Badge extension params carry no badgeId",
+            )
+        return await self.verify_badge(badge_id)
+
+    async def get_credential(self, badge_id: str) -> dict:
+        """GET /v1/credentials/{badge_id} — the full flattened JWS credential."""
+        return await self._request("GET", f"/v1/credentials/{badge_id}")
+
+    async def create_subscribe_intent(
+        self,
+        card_url: str,
+        plan: str = "monthly",
+        badge_type: str = "trust",
+        evidence: dict | None = None,
+        linked_credentials: list[dict] | None = None,
+    ) -> dict:
+        """POST /v1/subscribe/intents — free, and the first half of buying a badge.
+
+        Returns the terms the agent's own wallet needs in order to pay:
+        `subscribe_url`, `amount_usdc_base_units`, `pay_to`, `network`,
+        `asset_contract`. The SDK deliberately stops here — it holds no key and
+        never pays.
+        """
+        body: dict = {"card_url": card_url, "plan": plan, "badge_type": badge_type}
+        if evidence is not None:
+            body["evidence"] = evidence
+        if linked_credentials is not None:
+            body["linked_credentials"] = linked_credentials
+        return await self._request("POST", "/v1/subscribe/intents", json=body)
+
+    async def subscribe_status(self, intent_id: str) -> dict:
+        """GET /v1/subscribe/status — has this intent been paid?
+
+        A subscription carrying a settle tx is the proof of payment; poll this
+        rather than trusting any party's self-report.
+        """
+        return await self._request("GET", "/v1/subscribe/status", params={"intent_id": intent_id})
+
+    async def wear(self, intent_id: str, card_path: str, *, dry_run: bool = False) -> dict:
+        """Place the badge bought under `intent_id` onto this agent's own card.
+
+        Runs entirely in the caller's process against the caller's own file:
+        the SDK fetches the descriptor it already paid for, then patches the
+        local card. Nothing here writes to anybody else's document — placement
+        is the badge holder's own act, and this only removes the JSON surgery.
+
+        Raises if the intent has not settled: there is no descriptor to wear
+        until it has been paid for.
+        """
+        from agentbadge_core.wear import wear_badge
+
+        status = await self.subscribe_status(intent_id)
+        descriptor = status.get("badge")
+        if not descriptor:
+            raise AgentBadgeAPIError(
+                409,
+                "not_settled",
+                f"Intent {intent_id} has no badge to wear yet (status: {status.get('status')}). "
+                "Pay the subscribe_url first.",
+            )
+        return wear_badge(descriptor, card_path, dry_run=dry_run)
+
+    async def enroll(
+        self, card_url: str, badge_type: str, evidence: dict | None = None
+    ) -> EnrollResponse:
+        """Removed — badges are bought, not enrolled.
+
+        Raises instead of calling the endpoint so an integration pinned to the
+        old SDK gets an error that says where issuance went, rather than a bare
+        410 from the wire.
+        """
+        raise AgentBadgeAPIError(
+            410,
+            "enroll_gone",
+            "Free enrollment was removed. Call create_subscribe_intent(...), have the "
+            "agent's own wallet pay the returned subscribe_url with an x402 `exact` "
+            "payment, then poll subscribe_status(intent_id).",
+        )
+
+    async def get_jwks(self) -> dict:
+        """GET /.well-known/jwks.json."""
+        return await self._request("GET", "/.well-known/jwks.json")
+
+    # ------------------------------------------------------------------
+    # Messaging channel
+
+    def _admin_headers(self) -> dict[str, str]:
+        if not self.admin_api_key:
+            raise AgentBadgeAPIError(
+                0, "admin_api_key_required", "This call requires admin_api_key on the client"
+            )
+        return {"X-API-Key": self.admin_api_key}
+
+    async def send_message(
+        self,
+        badge_id: str,
+        payload: dict,
+        message_type: str | None = None,
+        expires_at: str | datetime | None = None,
+    ) -> SendMessageResponse:
+        """Operator → agent: POST /v1/agent-messages/{badge_id}.
+
+        The message type defaults to payload["type"] (or "arbitrary").
+        """
+        body: dict = {
+            "message_type": message_type or payload.get("type", "arbitrary"),
+            "payload": payload,
+        }
+        if expires_at is not None:
+            body["expires_at"] = (
+                expires_at.isoformat() if isinstance(expires_at, datetime) else expires_at
+            )
+        data = await self._request(
+            "POST",
+            f"/v1/agent-messages/{badge_id}",
+            json=body,
+            headers=self._admin_headers(),
+        )
+        return SendMessageResponse.model_validate(data)
+
+    async def poll_messages(
+        self,
+        badge_id: str,
+        keypair: Ed25519KeyPair,
+        since: str | datetime | None = None,
+    ) -> MessagesResponse:
+        """Agent: GET /v1/agent-messages/{badge_id} with a signed request."""
+        params: dict = {}
+        if since is not None:
+            params["since"] = since.isoformat() if isinstance(since, datetime) else since
+        data = await self._request(
+            "GET",
+            f"/v1/agent-messages/{badge_id}",
+            params=params,
+            headers=agent_auth_headers(badge_id, keypair),
+        )
+        return MessagesResponse.model_validate(data)
+
+    async def ack_messages(
+        self, badge_id: str, keypair: Ed25519KeyPair, message_ids: list[str]
+    ) -> AckResponse:
+        """Agent: POST /v1/agent-messages/{badge_id}/ack with a signed request."""
+        data = await self._request(
+            "POST",
+            f"/v1/agent-messages/{badge_id}/ack",
+            json={"message_ids": message_ids},
+            headers=agent_auth_headers(badge_id, keypair),
+        )
+        return AckResponse.model_validate(data)
+
+    async def register_webhook(
+        self, badge_id: str, keypair: Ed25519KeyPair, webhook_url: str
+    ) -> SubscribeResponse:
+        """Agent: POST /v1/agent-subscriptions. The returned HMAC secret is
+        shown exactly once — store it."""
+        data = await self._request(
+            "POST",
+            "/v1/agent-subscriptions",
+            json={"badge_id": badge_id, "webhook_url": webhook_url},
+            headers=agent_auth_headers(badge_id, keypair),
+        )
+        return SubscribeResponse.model_validate(data)
+
+    async def unregister_webhook(
+        self, subscription_id: str, badge_id: str, keypair: Ed25519KeyPair
+    ) -> None:
+        """Agent: DELETE /v1/agent-subscriptions/{id}, signed with the badge
+        that owns the subscription."""
+        await self._request(
+            "DELETE",
+            f"/v1/agent-subscriptions/{subscription_id}",
+            headers=agent_auth_headers(badge_id, keypair),
+        )
+
+    # ------------------------------------------------------------------
+    # Live metadata (Strategy B)
+
+    async def get_badge_metadata(self, badge_id: str) -> BadgeMetadata:
+        """GET /v1/badges/{badge_id}/metadata — live, never-frozen badge data."""
+        data = await self._request("GET", f"/v1/badges/{badge_id}/metadata")
+        return BadgeMetadata.model_validate(data)
+
+    async def get_badge_features(self, badge_id: str) -> BadgeFeatures:
+        """GET /v1/badges/{badge_id}/features — cacheable feature flags."""
+        data = await self._request("GET", f"/v1/badges/{badge_id}/features")
+        return BadgeFeatures.model_validate(data)

agentbadge/types.py

@@ -0,0 +1,101 @@
+"""Typed responses mirroring the canonical JSON Schemas."""
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class VerificationResponse(BaseModel):
+    badgeId: str
+    status: Literal["active", "expired", "revoked", "downgraded", "unknown"]
+    tier: Literal["unknown", "monitored", "verified", "certified"]
+    claims: list[str]
+    issuer: str
+    expires: str
+    cardHash: str
+    revocationReason: str | None = None
+
+
+class BadgeDescriptor(BaseModel):
+    uri: str
+    description: str
+    required: bool = False
+    params: dict
+
+
+class ChallengeInfo(BaseModel):
+    domain: str
+    method: Literal["dns_txt", "well_known_http"]
+    token: str
+    instructions: str
+    expires_at: str
+
+
+class EnrollResponse(BaseModel):
+    status: Literal["enrolled", "pending_domain_verification"]
+    badge: BadgeDescriptor | None = None
+    badge_id: str | None = None
+    challenge: ChallengeInfo | None = None
+
+
+class SendMessageResponse(BaseModel):
+    message_id: str
+    badge_id: str
+    status: Literal["pending", "delivered"]
+    webhook_deliveries: int = 0
+
+
+class AgentMessage(BaseModel):
+    message_id: str
+    message_type: str
+    direction: str
+    payload: dict
+    status: str
+    created_at: str
+    expires_at: str | None = None
+
+
+class MessagesResponse(BaseModel):
+    badge_id: str
+    messages: list[AgentMessage]
+
+
+class AckResponse(BaseModel):
+    badge_id: str
+    acked: list[str]
+
+
+class SubscribeResponse(BaseModel):
+    subscription_id: str
+    badge_id: str
+    webhook_url: str
+    secret: str
+
+
+class BadgeMetadata(BaseModel):
+    badgeId: str
+    trustScore: float
+    verificationCount: int
+    features: list[str]
+    ambassadorCode: str | None = None
+    recruitUrl: str | None = None
+    linkedCredentials: list[dict] = []
+    openOffers: int
+    lastUpdated: str
+
+
+class BadgeFeatures(BaseModel):
+    badgeId: str
+    features: list[str]
+    lastUpdated: str
+
+
+class AgentBadgeAPIError(Exception):
+    """Raised when the API returns an error response."""
+
+    def __init__(self, status_code: int, error: str, message: str, request_id: str | None = None):
+        self.status_code = status_code
+        self.error = error
+        self.message = message
+        self.request_id = request_id
+        super().__init__(f"[{status_code}] {error}: {message}")

agentbadge/verify.py

@@ -0,0 +1,20 @@
+"""Convenience verification functions."""
+
+from agentbadge.client import AgentBadgeClient
+from agentbadge.types import VerificationResponse
+
+
+async def verify_badge(
+    badge_id: str, api_url: str = "http://localhost:8000"
+) -> VerificationResponse:
+    """Verify a badge by ID against the given API."""
+    async with AgentBadgeClient(api_url) as client:
+        return await client.verify_badge(badge_id)
+
+
+async def verify_agent_card(
+    card_url: str, api_url: str = "http://localhost:8000"
+) -> VerificationResponse:
+    """Fetch an AgentCard, find its badge extension, and verify the badge."""
+    async with AgentBadgeClient(api_url) as client:
+        return await client.verify_agent_card(card_url)

agentbadge-0.1.0.dist-info/METADATA

@@ -0,0 +1,39 @@
+Metadata-Version: 2.5
+Name: agentbadge
+Version: 0.1.0
+Summary: Agent Badge Python SDK — HTTP client for the Agent Badge API
+Project-URL: Homepage, https://badge.swarmintel.xyz
+Project-URL: Documentation, https://badge.swarmintel.xyz/.well-known/agentbadge.json
+Project-URL: Repository, https://github.com/casey1088/agent-badge
+Author: Swarm Intel
+License-Expression: MIT
+Keywords: a2a,agent,agentcard,identity,verification,x402
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Requires-Python: >=3.12
+Requires-Dist: agentbadge-core~=0.1.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.5
+Description-Content-Type: text/markdown
+
+# agentbadge
+
+Python HTTP client for the Agent Badge API.
+
+```python
+from agentbadge import AgentBadgeClient
+
+async with AgentBadgeClient("https://badge.swarmintel.xyz") as client:
+    status = await client.verify("bdg_...")
+```
+
+Verification is public and needs no credentials. Buying a badge requires an
+x402 payment from your own wallet; this client never holds a key and never
+pays on your behalf.
+
+Nothing here is required to integrate. The API is plain HTTP and the full
+flow is published at
+`https://badge.swarmintel.xyz/.well-known/agentbadge.json`.

agentbadge-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+agentbadge/__init__.py,sha256=RaNtQJmFtzDrD_iok3ao9IsnEhGBobrvdMWmflKfu1A,1232
+agentbadge/auth.py,sha256=d8ekKUkrn6eNrJOb2ZJEB2d6f0aDQPHk47RJDkGSoEM,957
+agentbadge/client.py,sha256=7nIOHBWgZrSoZSAfitJ_fVdYJ3W9qXibXlLLziGssk8,11720
+agentbadge/types.py,sha256=SsEDRF_Sd-b-We079odUWX1CZ0PXCintUcz64gSeNaM,2299
+agentbadge/verify.py,sha256=91T4n9l5GMSWbrE0Ke__Qtehum9nqI210Ve72d44D-c,710
+agentbadge-0.1.0.dist-info/METADATA,sha256=SNyv2OCMFZho4gKl647IjNBfA07jugApX_3ZMie5tWw,1366
+agentbadge-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+agentbadge-0.1.0.dist-info/RECORD,,

agentbadge-0.1.0.dist-info/WHEEL

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