agentbadge 0.1.0__tar.gz

agentbadge-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+build/
+dist/
+
+# Node
+node_modules/
+*.tsbuildinfo
+.pnpm-store/
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Docker
+docker-data/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# Local dev artifacts
+*.log
+.local-storage/

agentbadge-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,18 @@
+# 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/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "agentbadge"
+version = "0.1.0"
+description = "Agent Badge Python SDK — HTTP client for the Agent Badge API"
+requires-python = ">=3.12"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Swarm Intel" }]
+keywords = ["agent", "identity", "a2a", "agentcard", "x402", "verification"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+]
+
+dependencies = [
+    "agentbadge-core~=0.1.0",
+    "httpx>=0.27",
+    "pydantic>=2.5",
+]
+
+[tool.uv.sources]
+agentbadge-core = { workspace = true }
+
+[project.urls]
+Homepage = "https://badge.swarmintel.xyz"
+Documentation = "https://badge.swarmintel.xyz/.well-known/agentbadge.json"
+Repository = "https://github.com/casey1088/agent-badge"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentbadge"]

agentbadge-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/tests/test_sdk_client.py

@@ -0,0 +1,191 @@
+"""Tests for the Python SDK client (T15). All HTTP is mocked."""
+
+import json
+
+import httpx
+import pytest
+from agentbadge import (
+    AgentBadgeAPIError,
+    AgentBadgeClient,
+    VerificationResponse,
+)
+from agentbadge_core.config import CoreConfig
+from agentbadge_core.schemas import SchemaValidator
+
+FIXTURES = CoreConfig().fixtures_dir
+API = "https://api.agentbadge.example"
+BADGE_ID = "bdg_01HZXK7Q8W5N4YT2R3V6M9EAAA"
+CARD_URL = "https://agent.example.com/.well-known/agent-card.json"
+
+VERIFICATION_JSON = {
+    "badgeId": BADGE_ID,
+    "status": "active",
+    "tier": "verified",
+    "claims": ["domain-verified"],
+    "issuer": "https://badge.swarmintel.xyz",
+    "expires": "2026-11-05T12:00:00Z",
+    "cardHash": "sha256:" + "ab" * 32,
+}
+
+
+def load_fixture(rel: str) -> dict:
+    return json.loads((FIXTURES / rel).read_text())
+
+
+def make_client(handler) -> AgentBadgeClient:
+    http = httpx.AsyncClient(transport=httpx.MockTransport(handler))
+    return AgentBadgeClient(API, client=http)
+
+
+class TestVerifyBadge:
+    async def test_returns_typed_response(self) -> None:
+        def handler(request: httpx.Request) -> httpx.Response:
+            assert str(request.url) == f"{API}/v1/verify/{BADGE_ID}"
+            return httpx.Response(200, json=VERIFICATION_JSON)
+
+        client = make_client(handler)
+        result = await client.verify_badge(BADGE_ID)
+        assert isinstance(result, VerificationResponse)
+        assert result.status == "active"
+        assert result.tier == "verified"
+
+    async def test_unknown_badge_raises_typed_error(self) -> None:
+        def handler(request: httpx.Request) -> httpx.Response:
+            return httpx.Response(
+                404,
+                json={
+                    "error": "badge_not_found",
+                    "message": "No badge",
+                    "details": {},
+                    "requestId": "r-1",
+                },
+            )
+
+        client = make_client(handler)
+        with pytest.raises(AgentBadgeAPIError) as excinfo:
+            await client.verify_badge("bdg_01HZXK7Q8W5N4YT2R3V6M9EZZZ")
+        assert excinfo.value.status_code == 404
+        assert excinfo.value.error == "badge_not_found"
+
+
+class TestVerifyAgentCard:
+    async def test_fetches_card_and_verifies(self) -> None:
+        card = load_fixture("agent-cards/valid-agent-card-with-badge.json")
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            if str(request.url) == CARD_URL:
+                return httpx.Response(200, json=card)
+            if str(request.url) == f"{API}/v1/verify/{BADGE_ID}":
+                return httpx.Response(200, json=VERIFICATION_JSON)
+            return httpx.Response(404)
+
+        client = make_client(handler)
+        result = await client.verify_agent_card(CARD_URL)
+        assert result.badgeId == BADGE_ID
+        assert result.status == "active"
+
+    async def test_card_without_badge_raises(self) -> None:
+        card = load_fixture("agent-cards/valid-agent-card.json")
+        client = make_client(lambda r: httpx.Response(200, json=card))
+        with pytest.raises(AgentBadgeAPIError) as excinfo:
+            await client.verify_agent_card(CARD_URL)
+        assert excinfo.value.error == "badge_extension_not_found"
+
+
+class TestGetCredential:
+    async def test_returns_jws_dict(self) -> None:
+        jws = {"protected": "aGVhZGVy", "payload": "cGF5bG9hZA", "signature": "c2ln"}
+        client = make_client(lambda r: httpx.Response(200, json=jws))
+        assert await client.get_credential(BADGE_ID) == jws
+
+
+class TestSubscribe:
+    async def test_create_intent_sends_the_plan_and_issuance_terms(self) -> None:
+        body = {
+            "intent_id": "int_01ABC",
+            "identity_key": CARD_URL,
+            "plan": "monthly",
+            "amount_usdc_base_units": 50_000_000,
+            "subscribe_url": f"{API}/v1/subscribe/int_01ABC",
+            "renew_url": f"{API}/v1/billing/int_01ABC/renew",
+            "network": "eip155:84532",
+            "asset_contract": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+            "pay_to": "0x" + "aa" * 20,
+            "expires_at": "2026-08-08T12:00:00Z",
+        }
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            assert request.method == "POST"
+            assert str(request.url) == f"{API}/v1/subscribe/intents"
+            sent = json.loads(request.content)
+            assert sent["card_url"] == CARD_URL
+            assert sent["plan"] == "annual"
+            assert sent["badge_type"] == "compliance"
+            return httpx.Response(200, json=body)
+
+        client = make_client(handler)
+        result = await client.create_subscribe_intent(
+            CARD_URL, plan="annual", badge_type="compliance"
+        )
+        assert result["intent_id"] == "int_01ABC"
+        assert result["amount_usdc_base_units"] == 50_000_000
+
+    async def test_status_is_queried_by_intent_id(self) -> None:
+        def handler(request: httpx.Request) -> httpx.Response:
+            assert request.url.params["intent_id"] == "int_01ABC"
+            return httpx.Response(200, json={"intent_id": "int_01ABC", "status": "unpaid"})
+
+        client = make_client(handler)
+        assert (await client.subscribe_status("int_01ABC"))["status"] == "unpaid"
+
+    async def test_enroll_is_gone_and_says_where_issuance_went(self) -> None:
+        """The SDK refuses locally rather than calling a 410, so an old
+        integration gets an actionable error instead of a bare status code."""
+        called = False
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            nonlocal called
+            called = True
+            return httpx.Response(410, json={})
+
+        client = make_client(handler)
+        with pytest.raises(AgentBadgeAPIError) as exc:
+            await client.enroll(CARD_URL, "trust")
+        assert exc.value.error == "enroll_gone"
+        assert "create_subscribe_intent" in exc.value.message
+        assert not called, "the SDK must not spend a round trip on a removed endpoint"
+
+
+class TestGetJwks:
+    async def test_returns_jwks(self) -> None:
+        jwks = load_fixture("jwks/test-public-jwks.json")
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            assert str(request.url) == f"{API}/.well-known/jwks.json"
+            return httpx.Response(200, json=jwks)
+
+        client = make_client(handler)
+        result = await client.get_jwks()
+        SchemaValidator.validate("jwks", result)
+
+
+class TestConvenienceFunctions:
+    async def test_verify_badge_function(self, monkeypatch) -> None:
+        from agentbadge import verify as verify_module
+
+        class FakeClient:
+            def __init__(self, api_url: str):
+                assert api_url == API
+
+            async def __aenter__(self):
+                return self
+
+            async def __aexit__(self, *args):
+                return None
+
+            async def verify_badge(self, badge_id: str) -> VerificationResponse:
+                return VerificationResponse.model_validate(VERIFICATION_JSON)
+
+        monkeypatch.setattr(verify_module, "AgentBadgeClient", FakeClient)
+        result = await verify_module.verify_badge(BADGE_ID, API)
+        assert result.status == "active"

agentbadge-0.1.0/tests/test_sdk_e2e.py

@@ -0,0 +1,290 @@
+"""SDK end-to-end: the Python SDK drives the real API app (T19).
+
+The SDK's injected httpx client routes API calls into the FastAPI app via
+ASGITransport and serves the fixture AgentCard for card-URL fetches — the same
+API surface, no network, real test PostgreSQL underneath.
+"""
+
+import json
+import os
+from pathlib import Path
+
+import fakeredis.aioredis
+import httpx
+import pytest
+from agentbadge import AgentBadgeClient, EnrollResponse, VerificationResponse
+from agentbadge.client import AgentBadgeAPIError
+from agentbadge_core.config import find_project_root
+from agentbadge_core.crypto import JWSVerifier, KeyManager
+from alembic import command
+from alembic.config import Config
+
+
+def _synthetic_cdp_key() -> tuple[str, str]:
+    """A structurally valid CDP Ed25519 key: base64(seed || public), 64 bytes.
+
+    CDP authenticates with a JWT signed by the key, so the signing path runs
+    for real and a placeholder string cannot produce a token.
+    """
+    import base64
+
+    from nacl.signing import SigningKey
+
+    key = SigningKey.generate()
+    return (
+        "organizations/sdk-e2e/apiKeys/sdk-e2e",
+        base64.b64encode(bytes(key) + bytes(key.verify_key)).decode(),
+    )
+
+
+_CDP_KEY_ID, _CDP_KEY_SECRET = _synthetic_cdp_key()
+
+
+
+ROOT = find_project_root()
+API_DIR = ROOT / "apps" / "api"
+DOMAIN = "test-agent.example.com"
+CARD_URL = f"https://{DOMAIN}/.well-known/agent-card.json"
+TEST_DATABASE_URL = os.environ.get(
+    "AGENTBADGE_TEST_DATABASE_URL",
+    "postgresql+asyncpg://agentbadge:agentbadge@localhost:5432/agentbadge_test",
+)
+ADMIN_KEY = "sdk-e2e-admin-key"
+FACILITATOR_URL = "https://facilitator.test"
+PAY_TO = "0x" + "aa" * 20
+PAYER = "0x" + "bb" * 20
+
+
+def payment_header(resource: str) -> str:
+    """Stand-in for a signed x402 payload, carrying the one field
+    `FacilitatorClient._assert_bound` checks so intent binding is exercised."""
+    import base64
+
+    return base64.b64encode(
+        json.dumps({"payer": PAYER, "resource": resource}).encode()
+    ).decode()
+
+
+def facilitator_response(request: httpx.Request) -> httpx.Response | None:
+    """Mock CDP facilitator; None when the request is for something else.
+
+    A real x402 v2 facilitator cannot check intent binding:
+    PaymentRequirements no longer carries `resource`, so two purchases at the
+    same price are byte-identical to it. `FacilitatorClient._assert_bound`
+    enforces the binding before the request leaves, which is why this mock no
+    longer pretends to -- a mock enforcing a property production does not have
+    would hide the gap instead of testing it.
+    """
+    url = str(request.url)
+    if not url.startswith(FACILITATOR_URL):
+        return None
+    if url.endswith("/verify"):
+        return httpx.Response(200, json={"isValid": True, "payer": PAYER})
+    return httpx.Response(200, json={"success": True, "txHash": "0xsdktx", "payer": PAYER})
+
+
+def load_card() -> dict:
+    return json.loads((ROOT / "fixtures" / "agent-cards" / "valid-agent-card.json").read_text())
+
+
+class RoutingTransport(httpx.AsyncBaseTransport):
+    """Route the card URL to a canned response; everything else to the app."""
+
+    def __init__(self, app):
+        self._asgi = httpx.ASGITransport(app=app)
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        settled = facilitator_response(request)
+        if settled is not None:
+            return settled
+        if str(request.url) == CARD_URL:
+            return httpx.Response(200, json=load_card())
+        return await self._asgi.handle_async_request(request)
+
+
+@pytest.fixture(scope="session")
+def migrated_database() -> str:
+    config = Config(str(API_DIR / "alembic.ini"))
+    config.set_main_option(
+        "script_location", str(API_DIR / "src" / "agentbadge_api" / "migrations")
+    )
+    config.set_main_option("sqlalchemy.url", TEST_DATABASE_URL)
+    previous = os.environ.pop("AGENTBADGE_DATABASE_URL", None)
+    try:
+        command.downgrade(config, "base")
+        command.upgrade(config, "head")
+    finally:
+        if previous is not None:
+            os.environ["AGENTBADGE_DATABASE_URL"] = previous
+    return TEST_DATABASE_URL
+
+
+@pytest.fixture
+async def app(migrated_database: str, tmp_path: Path):
+    from agentbadge_api.database import create_engine
+    from agentbadge_api.dependencies import get_settings
+    from agentbadge_api.main import create_app
+    from agentbadge_api.models.db import Base
+    from agentbadge_api.settings import Settings
+    from sqlalchemy import text
+
+    engine = create_engine(migrated_database)
+    async with engine.begin() as conn:
+        tables = ", ".join(t.name for t in Base.metadata.sorted_tables)
+        await conn.execute(text(f"TRUNCATE {tables} RESTART IDENTITY CASCADE"))
+    await engine.dispose()
+
+    key_path = ROOT / "fixtures" / "jwks" / "test-private-key.jwk"
+    settings = Settings(
+        database_url=migrated_database,
+        admin_api_key=ADMIN_KEY,
+        signing_key_path=str(key_path),
+        signing_kid=json.loads(key_path.read_text())["kid"],
+        public_base_url="http://testserver",
+        credential_storage_dir=str(tmp_path / "credentials"),
+        cdp_api_key_id=_CDP_KEY_ID,
+        cdp_api_key_secret=_CDP_KEY_SECRET,
+        x402_pay_to_address=PAY_TO,
+        x402_facilitator_url=FACILITATOR_URL,
+    )
+    application = create_app()
+    application.state.tmp_card_dir = str(tmp_path)
+    application.dependency_overrides[get_settings] = lambda: settings
+    application.state.redis = fakeredis.aioredis.FakeRedis(decode_responses=True)
+    application.state.signing = (
+        KeyManager.load_private_key(settings.signing_key_path),
+        settings.signing_kid,
+    )
+    yield application
+    engine = getattr(application.state, "engine", None)
+    if engine is not None:
+        await engine.dispose()
+
+
+@pytest.fixture
+async def sdk_client(app):
+    routing = RoutingTransport(app)
+    # The app's own outbound card fetches use the same routing transport.
+    app.state.http_client = httpx.AsyncClient(transport=routing)
+    http = httpx.AsyncClient(transport=routing, base_url="http://testserver")
+    client = AgentBadgeClient("http://testserver", client=http)
+    yield client
+    await http.aclose()
+    await app.state.http_client.aclose()
+
+
+async def _verify_domain(app, sdk_http: httpx.AsyncClient) -> None:
+    pending = await sdk_http.post(
+        "http://testserver/v1/domain/verify", json={"domain": DOMAIN, "method": "dns_txt"}
+    )
+    token = pending.json()["challenge"]["token"]
+
+    async def resolver(name: str) -> list[str]:
+        return [token]
+
+    app.state.txt_resolver = resolver
+    verified = await sdk_http.post(
+        "http://testserver/v1/domain/verify", json={"domain": DOMAIN, "method": "dns_txt"}
+    )
+    assert verified.json()["status"] == "verified"
+
+
+async def test_sdk_full_flow(app, sdk_client: AgentBadgeClient) -> None:
+    # The retired free path is gone, and the SDK says where issuance went
+    # rather than surfacing a bare 410.
+    with pytest.raises(AgentBadgeAPIError) as gone:
+        await sdk_client.enroll(CARD_URL, "trust")
+    assert gone.value.error == "enroll_gone"
+
+    http = await sdk_client._http()
+
+    # An intent is free, and before the domain is verified the paid call still
+    # refuses to charge -- nobody pays for a badge that cannot be issued yet.
+    early = await sdk_client.create_subscribe_intent(CARD_URL)
+    unpayable = await http.post(f"http://testserver/v1/subscribe/{early['intent_id']}")
+    assert unpayable.json()["status"] == "pending_domain_verification"
+
+    await _verify_domain(app, http)
+
+    # Buy the badge: intent -> the agent's own wallet pays -> settlement.
+    intent = await sdk_client.create_subscribe_intent(CARD_URL, plan="monthly")
+    assert intent["amount_usdc_base_units"] == 50_000_000
+    assert intent["pay_to"] == PAY_TO
+    resource = f"/v1/subscribe/{intent['intent_id']}"
+    paid = await http.post(
+        f"http://testserver{resource}", headers={"PAYMENT-SIGNATURE": payment_header(resource)}
+    )
+    assert paid.status_code == 200, paid.text
+    settled = paid.json()
+    assert settled["status"] == "paid"
+    assert settled["settle_tx"] == "0xsdktx"
+    badge_id = settled["badge_id"]
+
+    # The public status lookup is the proof of payment a poller relies on.
+    status = await sdk_client.subscribe_status(intent["intent_id"])
+    assert status["status"] == "paid"
+    assert status["badge_id"] == badge_id
+
+    # The settle body names the exact command that closes the loop, and the
+    # SDK ships that command: the buyer patches its OWN card, in its own
+    # process. Nothing on our side ever writes to a card we do not host.
+    assert "agentbadge wear" in settled["wear_command"]
+    assert status["wear_command"] == settled["wear_command"]
+
+    card_path = Path(app.state.tmp_card_dir) / "agent-card.json"
+    card_path.write_text(json.dumps(load_card(), indent=2))
+    worn = await sdk_client.wear(intent["intent_id"], str(card_path))
+    from agentbadge_core.wear import is_worn
+
+    assert is_worn(worn, badge_id)
+    assert is_worn(json.loads(card_path.read_text()), badge_id)
+
+    enrolled = EnrollResponse.model_validate(
+        {"status": "enrolled", "badge": settled["badge"], "badge_id": badge_id}
+    )
+    assert enrolled.badge is not None
+    assert enrolled.badge.params["badgeId"] == badge_id
+
+    # verify_badge — typed VerificationResponse, active.
+    verification = await sdk_client.verify_badge(badge_id)
+    assert isinstance(verification, VerificationResponse)
+    assert verification.status == "active"
+    assert verification.tier == "monitored"
+
+    # verify_agent_card resolves the badge straight from the (patched) card.
+    from agentbadge_core.agent_card import AgentCard
+
+    patched_card = AgentCard.patch_extension(load_card(), enrolled.badge.model_dump())
+    original_handler = RoutingTransport.handle_async_request
+
+    async def patched_handler(self, request):
+        if str(request.url) == CARD_URL:
+            return httpx.Response(200, json=patched_card)
+        return await original_handler(self, request)
+
+    RoutingTransport.handle_async_request = patched_handler
+    try:
+        from_card = await sdk_client.verify_agent_card(CARD_URL)
+        assert from_card.badgeId == badge_id
+        assert from_card.status == "active"
+    finally:
+        RoutingTransport.handle_async_request = original_handler
+
+    # Credential + JWKS from the same API verify cryptographically.
+    jws = await sdk_client.get_credential(badge_id)
+    jwks = await sdk_client.get_jwks()
+    is_valid, payload = JWSVerifier.verify(jws, jwks)
+    assert is_valid
+    assert payload["badgeId"] == badge_id
+
+    # Revoke via the admin endpoint; the SDK sees the new status.
+    http = await sdk_client._http()
+    revoke = await http.post(
+        f"http://testserver/v1/badges/{badge_id}/revoke",
+        json={"reason": "sdk e2e"},
+        headers={"X-API-Key": ADMIN_KEY},
+    )
+    assert revoke.status_code == 200
+    after = await sdk_client.verify_badge(badge_id)
+    assert after.status == "revoked"
+    assert after.revocationReason == "sdk e2e"

agentbadge-0.1.0/tests/test_sdk_messaging.py

@@ -0,0 +1,171 @@
+"""SDK messaging + metadata methods against a mocked API."""
+
+import base64
+import json
+
+import httpx
+import pytest
+from agentbadge import AgentBadgeClient, agent_auth_headers
+from agentbadge.types import AgentBadgeAPIError
+from agentbadge_core.crypto import Ed25519KeyPair
+
+API = "https://api.agentbadge.example"
+BADGE_ID = "bdg_01HZXK7Q8W5N4YT2R3V6M9EAAA"
+KEYPAIR = Ed25519KeyPair.generate()
+
+
+def make_client(handler, admin_api_key: str | None = None) -> AgentBadgeClient:
+    transport = httpx.MockTransport(handler)
+    return AgentBadgeClient(
+        API,
+        client=httpx.AsyncClient(transport=transport),
+        admin_api_key=admin_api_key,
+    )
+
+
+class TestAgentAuthHeaders:
+    def test_headers_shape_and_signature(self) -> None:
+        headers = agent_auth_headers(BADGE_ID, KEYPAIR, timestamp=1700000000, nonce="abcd")
+        assert headers["X-Agent-Timestamp"] == "1700000000"
+        assert headers["X-Agent-Nonce"] == "abcd"
+        signature = base64.b64decode(headers["X-Agent-Signature"])
+        assert KEYPAIR.verify(f"{BADGE_ID}:1700000000:abcd".encode(), signature)
+
+    def test_fresh_nonce_each_call(self) -> None:
+        first = agent_auth_headers(BADGE_ID, KEYPAIR)
+        second = agent_auth_headers(BADGE_ID, KEYPAIR)
+        assert first["X-Agent-Nonce"] != second["X-Agent-Nonce"]
+
+
+class TestSendMessage:
+    async def test_posts_with_admin_key(self) -> None:
+        def handler(request: httpx.Request) -> httpx.Response:
+            assert request.url.path == f"/v1/agent-messages/{BADGE_ID}"
+            assert request.headers["X-API-Key"] == "admin-secret"
+            body = json.loads(request.content)
+            assert body["message_type"] == "opportunity"
+            assert body["payload"]["value_usdc"] == 0.10
+            return httpx.Response(
+                200,
+                json={
+                    "message_id": "m-1",
+                    "badge_id": BADGE_ID,
+                    "status": "pending",
+                    "webhook_deliveries": 0,
+                },
+            )
+
+        client = make_client(handler, admin_api_key="admin-secret")
+        result = await client.send_message(
+            BADGE_ID, {"type": "opportunity", "title": "Gig", "value_usdc": 0.10}
+        )
+        assert result.message_id == "m-1"
+        assert result.status == "pending"
+
+    async def test_requires_admin_key(self) -> None:
+        client = make_client(lambda request: httpx.Response(500))
+        with pytest.raises(AgentBadgeAPIError, match="admin_api_key_required"):
+            await client.send_message(BADGE_ID, {"type": "reward"})
+
+
+class TestPollAndAck:
+    async def test_poll_sends_signed_headers(self) -> None:
+        def handler(request: httpx.Request) -> httpx.Response:
+            ts = int(request.headers["X-Agent-Timestamp"])
+            nonce = request.headers["X-Agent-Nonce"]
+            signature = base64.b64decode(request.headers["X-Agent-Signature"])
+            assert KEYPAIR.verify(f"{BADGE_ID}:{ts}:{nonce}".encode(), signature)
+            return httpx.Response(
+                200,
+                json={
+                    "badge_id": BADGE_ID,
+                    "messages": [
+                        {
+                            "message_id": "m-1",
+                            "message_type": "llm_txt_update",
+                            "direction": "operator_to_agent",
+                            "payload": {"content": "# hi"},
+                            "status": "pending",
+                            "created_at": "2026-08-12T00:00:00Z",
+                        }
+                    ],
+                },
+            )
+
+        client = make_client(handler)
+        result = await client.poll_messages(BADGE_ID, KEYPAIR)
+        assert result.messages[0].payload["content"] == "# hi"
+
+    async def test_ack(self) -> None:
+        def handler(request: httpx.Request) -> httpx.Response:
+            assert request.url.path == f"/v1/agent-messages/{BADGE_ID}/ack"
+            assert json.loads(request.content) == {"message_ids": ["m-1"]}
+            return httpx.Response(200, json={"badge_id": BADGE_ID, "acked": ["m-1"]})
+
+        client = make_client(handler)
+        result = await client.ack_messages(BADGE_ID, KEYPAIR, ["m-1"])
+        assert result.acked == ["m-1"]
+
+
+class TestWebhooks:
+    async def test_register_and_unregister(self) -> None:
+        def handler(request: httpx.Request) -> httpx.Response:
+            if request.method == "POST":
+                assert json.loads(request.content) == {
+                    "badge_id": BADGE_ID,
+                    "webhook_url": "https://agent.example.com/hook",
+                }
+                return httpx.Response(
+                    200,
+                    json={
+                        "subscription_id": "s-1",
+                        "badge_id": BADGE_ID,
+                        "webhook_url": "https://agent.example.com/hook",
+                        "secret": "whsec_x",
+                    },
+                )
+            assert request.method == "DELETE"
+            assert request.url.path == "/v1/agent-subscriptions/s-1"
+            return httpx.Response(204)
+
+        client = make_client(handler)
+        subscription = await client.register_webhook(
+            BADGE_ID, KEYPAIR, "https://agent.example.com/hook"
+        )
+        assert subscription.secret == "whsec_x"
+        await client.unregister_webhook("s-1", BADGE_ID, KEYPAIR)
+
+
+class TestMetadata:
+    async def test_get_metadata_and_features(self) -> None:
+        def handler(request: httpx.Request) -> httpx.Response:
+            if request.url.path.endswith("/metadata"):
+                return httpx.Response(
+                    200,
+                    json={
+                        "badgeId": BADGE_ID,
+                        "trustScore": 0.87,
+                        "verificationCount": 42,
+                        "features": ["caching", "opportunity_feed"],
+                        "ambassadorCode": "amb_9F3KQ2",
+                        "recruitUrl": "https://badge.swarmintel.xyz/r/amb_9F3KQ2",
+                        "linkedCredentials": [],
+                        "openOffers": 3,
+                        "lastUpdated": "2026-08-12T00:00:00Z",
+                    },
+                )
+            return httpx.Response(
+                200,
+                json={
+                    "badgeId": BADGE_ID,
+                    "features": ["caching"],
+                    "lastUpdated": "2026-08-12T00:00:00Z",
+                },
+            )
+
+        client = make_client(handler)
+        metadata = await client.get_badge_metadata(BADGE_ID)
+        assert metadata.trustScore == 0.87
+        assert metadata.openOffers == 3
+        features = await client.get_badge_features(BADGE_ID)
+        assert features.features == ["caching"]

agentbadge-0.1.0/tests/test_sdk_placement.py

@@ -0,0 +1,53 @@
+"""The SDK re-exports placement so callers need one import site."""
+
+import json
+
+import agentbadge
+from agentbadge_core.config import CoreConfig
+from agentbadge_core.constants import EXTENSION_URI
+
+FIXTURES = CoreConfig().fixtures_dir
+
+
+def descriptor() -> dict:
+    return json.loads((FIXTURES / "badges" / "valid-badge-descriptor.json").read_text())
+
+
+def card() -> dict:
+    return json.loads((FIXTURES / "agent-cards" / "valid-agent-card.json").read_text())
+
+
+class TestPlacementReExports:
+    def test_patch_badge_defaults_to_a2a(self) -> None:
+        patched = agentbadge.patch_badge(card(), descriptor())
+        assert patched["capabilities"]["extensions"][0]["uri"] == EXTENSION_URI
+
+    def test_patch_badge_renders_several_protocols(self) -> None:
+        artifacts = agentbadge.patch_badge(
+            card(), descriptor(), protocols=["a2a", "mcp", "x402"]
+        )
+        assert set(artifacts) == {"a2a", "mcp", "x402"}
+
+    def test_badge_fragment_is_mergeable(self) -> None:
+        fragment = agentbadge.badge_fragment(descriptor(), "acp")
+        assert fragment["metadata"]["annotations"]["io.agentbadge/badge"]["uri"] == EXTENSION_URI
+
+    def test_badge_headers_carry_the_badge(self) -> None:
+        headers = agentbadge.badge_headers(descriptor())
+        assert headers["X-Agent-Badge"].startswith("bdg_")
+
+    def test_find_badge_round_trips(self) -> None:
+        patched = agentbadge.patch_badge(card(), descriptor(), protocols=["langgraph"])
+        assert agentbadge.find_badge(patched) is not None
+
+    def test_supported_protocols_and_table_agree(self) -> None:
+        table = agentbadge.placement_table()
+        assert [row["protocol"] for row in table] == list(agentbadge.SUPPORTED_PROTOCOLS)
+        assert len(agentbadge.SUPPORTED_PROTOCOLS) == 20
+
+    def test_card_hash_survives_placement(self) -> None:
+        original = card()
+        patched = agentbadge.patch_badge(original, descriptor(), protocols=["mcp"])
+        assert agentbadge.AgentCard.compute_hash(patched) == agentbadge.AgentCard.compute_hash(
+            original
+        )