agentapprovalprotocol 0.2.0__tar.gz → 0.3.0__tar.gz

{agentapprovalprotocol-0.2.0 → agentapprovalprotocol-0.3.0}/.gitignore

@@ -15,5 +15,6 @@ playwright-report/
 /sdk/python/dist/
 /sdk/typescript/dist/
 /sdk/typescript-ai-sdk/dist/
+/sdk/typescript-mastra/dist/
 __pycache__/
 /sdk/python/.pytest_cache/

agentapprovalprotocol-0.2.0/README.md → agentapprovalprotocol-0.3.0/PKG-INFO

@@ -1,3 +1,34 @@
+Metadata-Version: 2.5
+Name: agentapprovalprotocol
+Version: 0.3.0
+Summary: Put an AI agent's tool calls behind an Agent Approval Protocol (AAP) approval provider.
+Project-URL: Homepage, https://agentapprovalprotocol.io
+Project-URL: Source, https://github.com/agentapprovalprotocol/agentapprovalprotocol
+License-Expression: Apache-2.0
+Keywords: aap,agents,ai,approval,human-in-the-loop
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: adk
+Requires-Dist: google-adk>=2.11; extra == 'adk'
+Provides-Extra: claude-agent-sdk
+Requires-Dist: claude-agent-sdk>=0.2.165; extra == 'claude-agent-sdk'
+Provides-Extra: crewai
+Requires-Dist: crewai>=1.15; (python_full_version < '3.14') and extra == 'crewai'
+Provides-Extra: deep-agents
+Requires-Dist: deepagents>=0.7.24; (python_full_version >= '3.11') and extra == 'deep-agents'
+Requires-Dist: langchain>=1.0; extra == 'deep-agents'
+Requires-Dist: langgraph>=1.0; extra == 'deep-agents'
+Provides-Extra: langgraph
+Requires-Dist: langchain>=1.0; extra == 'langgraph'
+Requires-Dist: langgraph>=1.0; extra == 'langgraph'
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.23; extra == 'openai-agents'
+Provides-Extra: pydantic-ai
+Requires-Dist: pydantic-ai-slim>=2.55; (python_full_version >= '3.11') and extra == 'pydantic-ai'
+Description-Content-Type: text/markdown
+
 # Agent Approval Protocol for Python
 
 Put an AI agent's tool calls behind an [AAP](https://agentapprovalprotocol.io) approval provider. Each call waits for the provider's decision, runs only if approved, and runs at most once.
@@ -30,6 +61,45 @@ With `mode="async"`, `check` returns `Pending` when there is no decision yet, so
 
 Framework integrations handle pausing and resuming for you.
 
+Start the receiver first, because the provider checks that it answers before registering it:
+
+```python
+from fastapi import FastAPI
+from agentapprovalprotocol import Receiver
+
+receiver = Receiver(resumers={"langgraph": resumer(agent)})
+app = FastAPI()
+app.add_route("/aap/events", receiver.asgi(), methods=["POST"])
+```
+
+Add it as a route, as shown. `app.mount("/aap/events", ...)` redirects `/aap/events` to `/aap/events/`, and providers do not follow redirects.
+
+Once the server is running, register the receiver:
+
+```python
+provisioned = await receiver.provision(
+    provider_url="https://approvals.example.com/api/aap",
+    provisioner_token=provisioner_token,
+    url="https://agent.example.com/aap/events",
+)
+```
+
+`provision` creates the signing secret and registration ID, and the receiver starts using the new instance credential. Save `token`, `secret`, `registration_id` and `instance_id` from the result. Nothing is saved for you. If it raises `WebhookVerificationFailed`, check the receiver is reachable at `url` and call `provision` again.
+
+On later starts, pass the saved values. `client` can be a function, called the first time a run is woken:
+
+```python
+receiver = Receiver(
+    secret=secret,
+    registration_id=registration_id,
+    instance_id=instance_id,
+    client=lambda: AsyncClient("https://approvals.example.com/api/aap", load_token()),
+    resumers={"langgraph": resumer(agent)},
+)
+```
+
+To register in your provider's app instead, start the receiver with the secret and registration ID you enter there. Without the registration ID, the receiver refuses the provider's check.
+
 ## LangChain, LangGraph and Deep Agents
 
 ```sh
@@ -45,7 +115,7 @@ agent = create_agent(model, tools=tools, middleware=[approvals])
 
 Every tool call the agent makes goes to the provider. A denied call returns the reason to the model as the tool result.
 
-For Deep Agents, also add the middleware to every subagent:
+For Deep Agents (Python 3.11 or later), install `agentapprovalprotocol[deep-agents]` and add the middleware to every subagent:
 
 ```python
 from agentapprovalprotocol.langgraph import deep_agent_subagents

agentapprovalprotocol-0.2.0/PKG-INFO → agentapprovalprotocol-0.3.0/README.md

@@ -1,30 +1,3 @@
-Metadata-Version: 2.5
-Name: agentapprovalprotocol
-Version: 0.2.0
-Summary: Put an AI agent's tool calls behind an Agent Approval Protocol (AAP) approval provider.
-Project-URL: Homepage, https://agentapprovalprotocol.io
-Project-URL: Source, https://github.com/agentapprovalprotocol/agentapprovalprotocol
-License-Expression: Apache-2.0
-Keywords: aap,agents,ai,approval,human-in-the-loop
-Classifier: Programming Language :: Python :: 3
-Classifier: Typing :: Typed
-Requires-Python: >=3.10
-Requires-Dist: httpx>=0.27
-Provides-Extra: adk
-Requires-Dist: google-adk>=2.11; extra == 'adk'
-Provides-Extra: claude-agent-sdk
-Requires-Dist: claude-agent-sdk>=0.2.165; extra == 'claude-agent-sdk'
-Provides-Extra: crewai
-Requires-Dist: crewai>=1.15; (python_full_version < '3.14') and extra == 'crewai'
-Provides-Extra: langgraph
-Requires-Dist: langchain>=1.0; extra == 'langgraph'
-Requires-Dist: langgraph>=1.0; extra == 'langgraph'
-Provides-Extra: openai-agents
-Requires-Dist: openai-agents>=0.23; extra == 'openai-agents'
-Provides-Extra: pydantic-ai
-Requires-Dist: pydantic-ai-slim>=2.55; (python_full_version >= '3.11') and extra == 'pydantic-ai'
-Description-Content-Type: text/markdown
-
 # Agent Approval Protocol for Python
 
 Put an AI agent's tool calls behind an [AAP](https://agentapprovalprotocol.io) approval provider. Each call waits for the provider's decision, runs only if approved, and runs at most once.
@@ -57,6 +30,45 @@ With `mode="async"`, `check` returns `Pending` when there is no decision yet, so
 
 Framework integrations handle pausing and resuming for you.
 
+Start the receiver first, because the provider checks that it answers before registering it:
+
+```python
+from fastapi import FastAPI
+from agentapprovalprotocol import Receiver
+
+receiver = Receiver(resumers={"langgraph": resumer(agent)})
+app = FastAPI()
+app.add_route("/aap/events", receiver.asgi(), methods=["POST"])
+```
+
+Add it as a route, as shown. `app.mount("/aap/events", ...)` redirects `/aap/events` to `/aap/events/`, and providers do not follow redirects.
+
+Once the server is running, register the receiver:
+
+```python
+provisioned = await receiver.provision(
+    provider_url="https://approvals.example.com/api/aap",
+    provisioner_token=provisioner_token,
+    url="https://agent.example.com/aap/events",
+)
+```
+
+`provision` creates the signing secret and registration ID, and the receiver starts using the new instance credential. Save `token`, `secret`, `registration_id` and `instance_id` from the result. Nothing is saved for you. If it raises `WebhookVerificationFailed`, check the receiver is reachable at `url` and call `provision` again.
+
+On later starts, pass the saved values. `client` can be a function, called the first time a run is woken:
+
+```python
+receiver = Receiver(
+    secret=secret,
+    registration_id=registration_id,
+    instance_id=instance_id,
+    client=lambda: AsyncClient("https://approvals.example.com/api/aap", load_token()),
+    resumers={"langgraph": resumer(agent)},
+)
+```
+
+To register in your provider's app instead, start the receiver with the secret and registration ID you enter there. Without the registration ID, the receiver refuses the provider's check.
+
 ## LangChain, LangGraph and Deep Agents
 
 ```sh
@@ -72,7 +84,7 @@ agent = create_agent(model, tools=tools, middleware=[approvals])
 
 Every tool call the agent makes goes to the provider. A denied call returns the reason to the model as the tool result.
 
-For Deep Agents, also add the middleware to every subagent:
+For Deep Agents (Python 3.11 or later), install `agentapprovalprotocol[deep-agents]` and add the middleware to every subagent:
 
 ```python
 from agentapprovalprotocol.langgraph import deep_agent_subagents

{agentapprovalprotocol-0.2.0 → agentapprovalprotocol-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentapprovalprotocol"
-version = "0.2.0"
+version = "0.3.0"
 description = "Put an AI agent's tool calls behind an Agent Approval Protocol (AAP) approval provider."
 readme = "README.md"
 license = "Apache-2.0"
@@ -22,6 +22,11 @@ langgraph = [
     "langchain>=1.0",
     "langgraph>=1.0",
 ]
+deep-agents = [
+    "langchain>=1.0",
+    "langgraph>=1.0",
+    "deepagents>=0.7.24 ; python_full_version >= '3.11'",
+]
 pydantic-ai = [
     "pydantic-ai-slim>=2.55 ; python_full_version >= '3.11'",
 ]

{agentapprovalprotocol-0.2.0 → agentapprovalprotocol-0.3.0}/src/agentapprovalprotocol/__init__.py

@@ -5,10 +5,10 @@ Put an agent's tool calls behind an AAP approval provider. ``Gate`` and
 on them. See https://agentapprovalprotocol.io.
 """
 
-from ._client import AAPError, AsyncClient, Client, ConflictError, CredentialRefused, NotFound
+from ._client import AAPError, AsyncClient, Client, ConflictError, CredentialRefused, NotFound, ProvisionError, WebhookVerificationFailed
 from ._gate import Allow, AsyncGate, Call, Deny, Gate, Pending, Verdict
 from ._wire import Consumption, Decision, Outcome, ProtocolError, Request
-from .receiver import Receiver
+from .receiver import Provisioned, Receiver
 
 __all__ = [
     "AAPError",
@@ -27,7 +27,10 @@ __all__ = [
     "Outcome",
     "Pending",
     "ProtocolError",
+    "Provisioned",
+    "ProvisionError",
     "Receiver",
     "Request",
     "Verdict",
+    "WebhookVerificationFailed",
 ]

{agentapprovalprotocol-0.2.0 → agentapprovalprotocol-0.3.0}/src/agentapprovalprotocol/_client.py

@@ -42,6 +42,23 @@ class NotFound(AAPError):
     """The request is unknown or unavailable to this instance."""
 
 
+class ProvisionError(AAPError):
+    """Provisioning an instance failed.
+
+    ``status`` is the HTTP status and ``code`` the provider's error code,
+    when the provider answered with them.
+    """
+
+    def __init__(self, message: str, *, status: int | None = None, code: str | None = None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+
+
+class WebhookVerificationFailed(ProvisionError):
+    """The provider could not verify the receiver (HTTP 422, ``webhook_verification_failed``)."""
+
+
 def validate_base_url(base_url: str) -> str:
     parts = urlsplit(base_url)
     if not parts.netloc or parts.username or parts.password or parts.query or parts.fragment:

{agentapprovalprotocol-0.2.0 → agentapprovalprotocol-0.3.0}/src/agentapprovalprotocol/crewai.py

@@ -161,6 +161,8 @@ class ApprovalHooks:
     ):
         if gate is None and (base_url is None or token is None):
             raise ValueError("pass base_url and token, or a gate")
+        if gate_options.get("mode") == "async":
+            raise ValueError("CrewAI cannot pause a run at a tool call, so it only supports sync mode")
         self.gate = gate if gate is not None else Gate(Client(base_url, token), **gate_options)
         self.context = {"framework": "crewai", **(context or {})}
         self._run = uuid.uuid4().hex

agentapprovalprotocol-0.3.0/src/agentapprovalprotocol/receiver.py

@@ -0,0 +1,340 @@
+"""Webhook receiver for asynchronous mode.
+
+The receiver verifies AAP webhooks, answers receiver verification during
+provisioning, and wakes paused runs. A notification only wakes a run: the
+gate fetches and consumes the decision itself, so the receiver keeps no
+state and a repeated or forged event at most wakes a run that pauses again.
+
+The resume handle is read from the request's ``context.resume``, which the
+gate wrote when it created the request. Its ``framework`` names the resumer
+to call.
+
+Verification needs only the signing secret and the registration ID, so a
+receiver can start before the instance exists. Waking a run needs a client
+for the instance credential, which exists only after provisioning: pass a
+client, a factory that builds one on first wake, or call ``provision``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import hashlib
+import hmac
+import inspect
+import json
+import logging
+import secrets
+import time
+import uuid
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Mapping
+
+import httpx
+
+from ._client import MAX_RESPONSE, USER_AGENT, AAPError, AsyncClient, ProvisionError, WebhookVerificationFailed, validate_base_url
+from ._wire import ProtocolError, Request, loads
+
+log = logging.getLogger("agentapprovalprotocol")
+
+Resumer = Callable[[Mapping[str, Any], Request], Awaitable[None] | None]
+#: Builds the client on first wake, for example from a credential saved after provisioning.
+ClientFactory = Callable[[], AsyncClient | Awaitable[AsyncClient]]
+
+
+def new_secret() -> str:
+    """A fresh signing secret: 32 random bytes as padded base64 with a ``whsec_`` prefix."""
+    return "whsec_" + base64.b64encode(secrets.token_bytes(32)).decode()
+
+
+@dataclass(frozen=True)
+class Provisioned:
+    """An instance created by ``Receiver.provision``.
+
+    Save ``token`` as the instance credential, and ``secret``,
+    ``registration_id`` and ``instance_id`` for the receiver's next start.
+    """
+
+    instance_id: str
+    instance_name: str
+    token: str
+    #: When the credential expires, as the provider returned it. ``None`` if no expiry is scheduled.
+    expires_at: str | None
+    secret: str
+    registration_id: str
+
+    def __repr__(self) -> str:
+        return f"Provisioned(instance_id={self.instance_id!r}, instance_name={self.instance_name!r}, registration_id={self.registration_id!r})"
+
+
+def signing_key(secret: str) -> bytes:
+    if not secret.startswith("whsec_"):
+        raise ValueError("signing secret must start with whsec_")
+    return base64.b64decode(secret[len("whsec_") :], validate=True)
+
+
+def sign(secret: str, message_id: str, timestamp: int, body: bytes) -> str:
+    """The ``webhook-signature`` header value for one delivery attempt."""
+    digest = hmac.new(signing_key(secret), f"{message_id}.{timestamp}.".encode() + body, hashlib.sha256).digest()
+    return "v1," + base64.b64encode(digest).decode()
+
+
+def verify(secret: str, headers: Mapping[str, str], body: bytes, *, tolerance: int = 300, now: float | None = None) -> dict[str, Any]:
+    """Verify a delivery and return its parsed body. Raises ``ValueError``."""
+    lower = {k.lower(): v for k, v in headers.items()}
+    message_id = lower.get("webhook-id", "")
+    stamp = lower.get("webhook-timestamp", "")
+    signatures = lower.get("webhook-signature", "").split()
+    if not message_id or not stamp.isdigit() or not signatures:
+        raise ValueError("missing webhook headers")
+    if abs((now if now is not None else time.time()) - int(stamp)) > tolerance:
+        raise ValueError("webhook timestamp outside tolerance")
+    expected = sign(secret, message_id, int(stamp), body)
+    if not any(hmac.compare_digest(expected, candidate) for candidate in signatures if candidate.startswith("v1,")):
+        raise ValueError("invalid webhook signature")
+    try:
+        message = loads(body)
+    except ProtocolError as err:
+        raise ValueError("invalid webhook body") from err
+    if not isinstance(message, dict) or message.get("id") != message_id:
+        raise ValueError("webhook ID does not match the body")
+    return message
+
+
+class Receiver:
+    """Verifies AAP webhooks and wakes paused runs.
+
+    ``secret`` is the instance's signing secret. ``registration_id`` is the
+    ID the provisioner generated for this receiver; verification messages for
+    any other registration are refused. ``provision`` generates both when
+    they are not given. ``instance_id``, once known, restricts notifications
+    to that instance.
+
+    ``client`` reads requests when a run is woken. It may be a client, a
+    zero-argument function returning one (called on first wake, then
+    cached), or ``None`` until ``provision`` installs one. ``resumers`` maps
+    a framework name to a function that resumes a run from its resume handle.
+    """
+
+    def __init__(
+        self,
+        *,
+        resumers: Mapping[str, Resumer],
+        secret: str | None = None,
+        client: AsyncClient | ClientFactory | None = None,
+        registration_id: str | None = None,
+        instance_id: str | None = None,
+        tolerance: int = 300,
+    ):
+        if secret is not None:
+            signing_key(secret)
+        self.secret = secret
+        self.client: AsyncClient | None = None if callable(client) else client
+        self._factory: ClientFactory | None = client if callable(client) else None
+        self._loading: asyncio.Future[AsyncClient] | None = None
+        self.resumers = dict(resumers)
+        self.registration_id = registration_id
+        self.instance_id = instance_id
+        self.tolerance = tolerance
+        self._tasks: set[asyncio.Task[None]] = set()
+
+    async def handle(self, headers: Mapping[str, str], body: bytes) -> tuple[int, bytes]:
+        """Process one delivery. Returns the HTTP status and body to send.
+
+        A notification is acknowledged at once and the run is woken in the
+        background, because a delivery attempt has a ten second limit.
+        """
+        if self.secret is None:
+            return 401, b""
+        try:
+            message = verify(self.secret, headers, body, tolerance=self.tolerance)
+        except ValueError:
+            return 401, b""
+        kind = message.get("type")
+        if kind == "webhook.verification":
+            if self.registration_id is None or message.get("registration_id") != self.registration_id or not isinstance(message.get("challenge"), str):
+                return 403, b""
+            return 200, json.dumps({"challenge": message["challenge"]}).encode()
+        if kind == "request.resolved":
+            if self.instance_id is not None and message.get("instance_id") != self.instance_id:
+                return 403, b""
+            request_id = message.get("request_id")
+            if isinstance(request_id, str):
+                task = asyncio.ensure_future(self.wake(request_id))
+                self._tasks.add(task)
+                task.add_done_callback(self._tasks.discard)
+            return 204, b""
+        return 400, b""
+
+    async def wake(self, request_id: str) -> bool:
+        """Resume the run waiting on a request. Also the recovery sweep's entry point.
+
+        Returns ``False`` when nothing was resumed, including when the
+        receiver has no client yet.
+        """
+        try:
+            client = await self._client()
+        except Exception:  # noqa: BLE001 - a failing factory must not crash the receiver
+            log.exception("could not create a client to resume request %s", request_id)
+            return False
+        if client is None:
+            log.warning("cannot resume request %s: the receiver has no client yet", request_id)
+            return False
+        try:
+            request = await client.get(request_id)
+        except (AAPError, ProtocolError):
+            log.warning("could not read request %s to resume it", request_id, exc_info=True)
+            return False
+        handle = (request.context or {}).get("resume")
+        resumer = self.resumers.get(handle.get("framework", "")) if isinstance(handle, dict) else None
+        if resumer is None:
+            log.warning("request %s has no resume handle this receiver can use", request_id)
+            return False
+        try:
+            result = resumer(handle, request)
+            if inspect.isawaitable(result):
+                await result
+            return True
+        except Exception:  # noqa: BLE001 - a failed resume must not crash the receiver
+            log.exception("resuming the run for request %s failed", request_id)
+            return False
+
+    async def _client(self) -> AsyncClient | None:
+        """The client, building it with the factory once if needed."""
+        if self.client is not None or self._factory is None:
+            return self.client
+        if self._loading is None:
+            self._loading = asyncio.ensure_future(_build(self._factory))
+        loading = self._loading
+        try:
+            client = await asyncio.shield(loading)
+        except BaseException:
+            if self._loading is loading and loading.done():
+                self._loading = None
+            raise
+        if self.client is None:
+            self.client = client
+        return self.client
+
+    async def provision(
+        self,
+        *,
+        provider_url: str,
+        provisioner_token: str,
+        url: str,
+        instance_name: str | None = None,
+        idempotency_key: str | None = None,
+        http: httpx.AsyncClient | None = None,
+    ) -> Provisioned:
+        """Create an instance whose notifications come to this receiver.
+
+        ``provider_url`` is the provider's AAP base URL and ``url`` this
+        receiver's public HTTPS URL. The provider verifies the receiver before
+        it answers, so the receiver must already be serving at ``url``.
+
+        Generates the signing secret and registration ID if the receiver has
+        none. ``idempotency_key`` defaults to the registration ID, so calling
+        again after a failure retries the same submission. On success the
+        receiver uses the new credential to wake runs and accepts
+        notifications only for the new instance. Save the result: nothing is
+        stored.
+
+        Raises ``WebhookVerificationFailed`` when the provider could not
+        verify the receiver, ``ProvisionError`` for other failures and
+        ``ProtocolError`` for a malformed answer.
+        """
+        if not provisioner_token or "\n" in provisioner_token or "\r" in provisioner_token:
+            raise ValueError("provisioner token is required and must not contain newlines")
+        base_url = validate_base_url(provider_url)
+        if self.secret is None:
+            self.secret = new_secret()
+        if self.registration_id is None:
+            self.registration_id = str(uuid.uuid4())
+        submission: dict[str, Any] = {"delivery": {"type": "webhook", "url": url, "registration_id": self.registration_id, "signing_secret": self.secret}}
+        if instance_name is not None:
+            submission = {"instance_name": instance_name, **submission}
+        headers = {
+            "Authorization": f"Bearer {provisioner_token}",
+            "Content-Type": "application/json",
+            "Idempotency-Key": idempotency_key or self.registration_id,
+            "User-Agent": USER_AGENT,
+        }
+        transport = http or httpx.AsyncClient(timeout=40.0, follow_redirects=False)
+        try:
+            response = await transport.post(base_url + "/v1/instances", headers=headers, content=json.dumps(submission).encode())
+            raw = await response.aread()
+        except httpx.TransportError as err:
+            raise ProvisionError("the provider could not be reached") from err
+        finally:
+            if http is None:
+                await transport.aclose()
+        instance_id, name, token, expires_at = _provisioned(response.status_code, raw)
+        self.client = AsyncClient(base_url, token, http=http)
+        self._factory = None
+        self.instance_id = instance_id
+        return Provisioned(instance_id=instance_id, instance_name=name, token=token, expires_at=expires_at, secret=self.secret, registration_id=self.registration_id)
+
+    def asgi(self) -> Callable[..., Awaitable[None]]:
+        """An ASGI app that accepts POSTed webhooks at any path it is served on.
+
+        It is an object rather than a function, so Starlette and FastAPI
+        routes serve it as an ASGI app.
+        """
+        return _ASGIApp(self)
+
+
+class _ASGIApp:
+    def __init__(self, receiver: Receiver):
+        self.receiver = receiver
+
+    async def __call__(self, scope: dict[str, Any], receive: Callable[[], Awaitable[dict[str, Any]]], send: Callable[[dict[str, Any]], Awaitable[None]]) -> None:
+        if scope["type"] != "http":
+            return
+        if scope["method"] != "POST":
+            await _respond(send, 405, b"")
+            return
+        chunks = []
+        more = True
+        while more:
+            event = await receive()
+            chunks.append(event.get("body", b""))
+            more = event.get("more_body", False)
+        headers = {k.decode("latin-1"): v.decode("latin-1") for k, v in scope.get("headers", [])}
+        status, body = await self.receiver.handle(headers, b"".join(chunks))
+        await _respond(send, status, body)
+
+
+async def _build(factory: ClientFactory) -> AsyncClient:
+    client = factory()
+    return await client if inspect.isawaitable(client) else client
+
+
+def _provisioned(status: int, raw: bytes) -> tuple[str, str, str, str | None]:
+    """Check a provisioning answer and return the instance ID, name, token and expiry."""
+    if status not in (200, 201):
+        code = None
+        try:
+            error = loads(raw)["error"]
+            code = error["code"] if isinstance(error["code"], str) else None
+        except (ProtocolError, KeyError, TypeError):
+            pass
+        if status == 422 and code == "webhook_verification_failed":
+            raise WebhookVerificationFailed("the provider could not verify the receiver", status=status, code=code)
+        raise ProvisionError(f"provisioning failed (HTTP {status}{f': {code}' if code else ''})", status=status, code=code)
+    if len(raw) > MAX_RESPONSE:
+        raise ProtocolError("AAP response too large")
+    body = loads(raw)
+    instance = body.get("instance") if isinstance(body, dict) else None
+    credential = body.get("credential") if isinstance(body, dict) else None
+    if not isinstance(instance, dict) or not isinstance(credential, dict):
+        raise ProtocolError("invalid provisioning response")
+    instance_id, name, token, expires_at = instance.get("id"), instance.get("name"), credential.get("token"), credential.get("expires_at")
+    if not all(isinstance(v, str) and v for v in (instance_id, name, token)) or not (expires_at is None or isinstance(expires_at, str)):
+        raise ProtocolError("invalid provisioning response")
+    return instance_id, name, token, expires_at
+
+
+async def _respond(send: Callable[[dict[str, Any]], Awaitable[None]], status: int, body: bytes) -> None:
+    headers = [(b"content-type", b"application/json")] if body else []
+    await send({"type": "http.response.start", "status": status, "headers": headers})
+    await send({"type": "http.response.body", "body": body})