personal-agent-protocol 0.3.2__tar.gz → 0.3.3__tar.gz

{personal_agent_protocol-0.3.2 → personal_agent_protocol-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: personal-agent-protocol
-Version: 0.3.2
+Version: 0.3.3
 Summary: Python SDK for Personal Agent Protocol
 Project-URL: Home, https://github.com/datalayer/personal-agent-protocol
 Project-URL: Documentation, https://personalagentprotocol.org/docs

{personal_agent_protocol-0.3.2 → personal_agent_protocol-0.3.3}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datalayer/personal-agent-protocol",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "TypeScript SDK for Personal Agent Protocol",
   "repository": {
     "type": "git",

{personal_agent_protocol-0.3.2 → personal_agent_protocol-0.3.3}/personal_agent_protocol/__init__.py

@@ -41,6 +41,13 @@ from .crypto import (
     VerifiedDpopProof,
     verify_dpop_proof,
 )
+from .device import (
+    DEVICE_CODE_GRANT,
+    DeviceAuthorizationResponse,
+    DeviceSignInClient,
+    DeviceSignInPoll,
+    DeviceSignInStart,
+)
 from .discovery import DiscoveryClient
 from .errors import (
     AuthorizationError,
@@ -124,6 +131,7 @@ __all__ = [
     "BROWSER_HANDOFFS",
     "CACHES",
     "CLOCKS",
+    "DEVICE_CODE_GRANT",
     "DISCOVERY_TRANSPORTS",
     "DPOP_PROOF_PROVIDERS",
     "EXTENSION_HANDLERS",
@@ -156,6 +164,10 @@ __all__ = [
     "ConversationReceipt",
     "ConversationResponse",
     "CursorExpiredHandler",
+    "DeviceAuthorizationResponse",
+    "DeviceSignInClient",
+    "DeviceSignInPoll",
+    "DeviceSignInStart",
     "DirectSignInCallback",
     "DirectSignInClient",
     "DirectSignInRequest",

personal_agent_protocol-0.3.3/personal_agent_protocol/__tests__/test_device.py

@@ -0,0 +1,229 @@
+# Copyright (c) 2025-2026 Datalayer, Inc.
+#
+# BSD 3-Clause License
+
+import asyncio
+from datetime import datetime, timedelta, timezone
+from urllib.parse import parse_qsl
+
+import httpx
+import pytest
+from pydantic import SecretStr
+from reactor import PluginManifest  # type: ignore[import-untyped]
+
+from personal_agent_protocol import (
+    AUTHORIZATION_STATE_STORES,
+    CLOCKS,
+    DPOP_PROOF_PROVIDERS,
+    SIGNERS,
+    TOKEN_STORES,
+    AuthorizationError,
+    DeviceSignInClient,
+    DpopProofRequest,
+)
+from personal_agent_protocol.reactor import build_pap_reactor
+
+
+class MutableClock:
+    def __init__(self) -> None:
+        self.value = datetime(2026, 10, 10, tzinfo=timezone.utc)
+
+    def now(self) -> datetime:
+        return self.value
+
+    def advance(self, seconds: int) -> None:
+        self.value += timedelta(seconds=seconds)
+
+
+class MemoryState:
+    def __init__(self) -> None:
+        self.values: dict[str, object] = {}
+
+    async def put(self, reference: str, value: object, *, expires_at: datetime) -> None:
+        assert expires_at.tzinfo is not None
+        self.values[reference] = value
+
+    async def take(self, reference: str) -> object | None:
+        return self.values.pop(reference, None)
+
+
+class MemoryTokens:
+    def __init__(self) -> None:
+        self.values: dict[str, SecretStr] = {}
+
+    async def put(self, reference: str, token: SecretStr) -> None:
+        self.values[reference] = token
+
+    async def get(self, reference: str) -> SecretStr | None:
+        return self.values.get(reference)
+
+    async def delete(self, reference: str) -> None:
+        self.values.pop(reference, None)
+
+
+class Signer:
+    async def sign(self, _: dict[str, object], *, purpose: str) -> SecretStr:
+        assert purpose == "client_assertion"
+        return SecretStr("signed-client-assertion")
+
+
+class Dpop:
+    def __init__(self) -> None:
+        self.requests: list[DpopProofRequest] = []
+
+    async def create(self, request: DpopProofRequest) -> SecretStr:
+        self.requests.append(request)
+        return SecretStr("proof")
+
+
+class DevicePlugin:
+    def __init__(self) -> None:
+        self.clock = MutableClock()
+        self.state = MemoryState()
+        self.tokens = MemoryTokens()
+        self.dpop = Dpop()
+
+    def provide_contributions(self, contributions: object) -> None:
+        contribute = contributions.contribute  # type: ignore[attr-defined]
+        contribute(CLOCKS, self.clock, contribution_id="mutable")
+        contribute(AUTHORIZATION_STATE_STORES, self.state, contribution_id="memory")
+        contribute(TOKEN_STORES, self.tokens, contribution_id="memory")
+        contribute(SIGNERS, Signer(), contribution_id="signer")
+        contribute(DPOP_PROOF_PROVIDERS, self.dpop, contribution_id="dpop")
+
+
+def test_device_sign_in_paces_polling_and_protects_tokens() -> None:
+    async def scenario() -> None:
+        calls = 0
+        forms: list[dict[str, str]] = []
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            nonlocal calls
+            calls += 1
+            form = dict(parse_qsl(request.content.decode()))
+            forms.append(form)
+            if calls == 1:
+                assert "DPoP" not in request.headers
+                return httpx.Response(
+                    200,
+                    json={
+                        "device_code": "private-device-code",
+                        "user_code": "WDJB-MJHT",
+                        "verification_uri": "https://company.example/device",
+                        "verification_uri_complete": "https://company.example/device?user_code=WDJB-MJHT",
+                        "expires_in": 600,
+                        "interval": 5,
+                    },
+                )
+            assert request.headers["DPoP"] == "proof"
+            if calls == 2:
+                return httpx.Response(400, json={"error": "authorization_pending"})
+            if calls == 3:
+                return httpx.Response(400, json={"error": "slow_down"})
+            return httpx.Response(
+                200,
+                json={
+                    "access_token": "signed-in-session-token",
+                    "token_type": "DPoP",
+                    "expires_in": 300,
+                    "scope": "poppy:read",
+                    "session_id": "ses_existing",
+                    "signed_in": True,
+                    "refresh_token": "private-account-token",
+                },
+            )
+
+        async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+            reactor, _ = build_pap_reactor(http_client=http)
+            plugin = DevicePlugin()
+            reactor.register_plugin(PluginManifest(name="pap-test-device", version="1"), plugin)
+            client = DeviceSignInClient(reactor=reactor, http_client=http)
+            started = await client.begin(
+                device_authorization_endpoint="https://auth.example.com/oauth/device",
+                token_endpoint="https://auth.example.com/oauth/token",  # noqa: S106
+                issuer="https://auth.example.com",
+                client_id="https://agent.example/agent.json",
+                scopes=("poppy:read", "poppy:write"),
+                tenant_id="application-one",
+                pairwise_user_id="usr_AAECAwQFBgcICQoLDA0ODw",
+                session_id="ses_existing",
+            )
+            assert started.user_code == "WDJB-MJHT"
+            assert "private-device-code" not in started.model_dump_json()
+            assert calls == 1
+
+            early = await client.poll(started.reference)
+            assert early.status == "pending"
+            assert calls == 1
+            plugin.clock.advance(5)
+            pending = await client.poll(started.reference)
+            assert pending.retry_at == plugin.clock.now() + timedelta(seconds=5)
+            plugin.clock.advance(5)
+            slowed = await client.poll(started.reference)
+            assert slowed.retry_at == plugin.clock.now() + timedelta(seconds=10)
+            plugin.clock.advance(10)
+            complete = await client.poll(started.reference)
+            reactor.stop()
+
+        assert complete.status == "complete"
+        assert complete.granted_scopes == ("poppy:read",)
+        assert complete.missing_scopes == ("poppy:write",)
+        assert complete.token is not None and complete.token.refresh_token is None
+        assert complete.account_token_reference is not None
+        stored = plugin.tokens.values[complete.account_token_reference]
+        assert stored.get_secret_value() == "private-account-token"
+        assert forms[0]["scope"] == "poppy:read poppy:write"
+        assert all(form.get("device_code") == "private-device-code" for form in forms[1:])
+        assert len(plugin.dpop.requests) == 3
+
+    asyncio.run(scenario())
+
+
+def test_device_sign_in_denial_is_terminal() -> None:
+    async def scenario() -> None:
+        def handler(request: httpx.Request) -> httpx.Response:
+            if request.url.path.endswith("/device"):
+                return httpx.Response(
+                    200,
+                    json={
+                        "device_code": "private-device-code",
+                        "user_code": "ABCD-EFGH",
+                        "verification_uri": "https://company.example/device",
+                        "expires_in": 60,
+                        "interval": 1,
+                    },
+                )
+            return httpx.Response(
+                400,
+                json={"error": "access_denied", "error_description": "private detail"},
+            )
+
+        async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+            reactor, _ = build_pap_reactor(http_client=http)
+            plugin = DevicePlugin()
+            reactor.register_plugin(
+                PluginManifest(name="pap-test-device-denial", version="1"), plugin
+            )
+            client = DeviceSignInClient(reactor=reactor, http_client=http)
+            started = await client.begin(
+                device_authorization_endpoint="https://auth.example.com/oauth/device",
+                token_endpoint="https://auth.example.com/oauth/token",  # noqa: S106
+                issuer="https://auth.example.com",
+                client_id="https://agent.example/agent.json",
+                scopes=("poppy:read",),
+                tenant_id="application-one",
+                pairwise_user_id="usr_AAECAwQFBgcICQoLDA0ODw",
+                session_id="ses_existing",
+            )
+            plugin.clock.advance(1)
+            with pytest.raises(AuthorizationError) as caught:
+                await client.poll(started.reference)
+            with pytest.raises(AuthorizationError) as reused:
+                await client.poll(started.reference)
+            reactor.stop()
+
+        assert caught.value.code == "access_denied"
+        assert "private detail" not in str(caught.value)
+        assert reused.value.code == "invalid_or_expired_device_session"
+
+    asyncio.run(scenario())

{personal_agent_protocol-0.3.2 → personal_agent_protocol-0.3.3}/personal_agent_protocol/__version__.py

@@ -3,4 +3,4 @@
 
 """Personal Agent Protocol."""
 
-__version__ = "0.3.2"
+__version__ = "0.3.3"

personal_agent_protocol-0.3.3/personal_agent_protocol/device.py

@@ -0,0 +1,404 @@
+# Copyright (c) 2025-2026 Datalayer, Inc.
+#
+# BSD 3-Clause License
+
+"""PAP Device Sign-In with private polling state and proof-bound tokens."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from datetime import datetime, timedelta
+from typing import Literal, cast
+
+import httpx
+from pydantic import Field, SecretStr, field_validator
+from reactor import PluginPlatform  # type: ignore[import-untyped]
+
+from .auth import _https_url, _scopes
+from .errors import AuthorizationError, ProtocolValidationError
+from .json import loads_strict
+from .models import ProtocolModel
+from .reactor import (
+    AUTHORIZATION_STATE_STORES,
+    CLOCKS,
+    DPOP_PROOF_PROVIDERS,
+    RANDOM_SOURCES,
+    SIGNERS,
+    TOKEN_STORES,
+    AuthorizationStateStore,
+    Clock,
+    DpopProofProvider,
+    DpopProofRequest,
+    RandomSource,
+    Signer,
+    TokenStore,
+    first_contribution,
+)
+from .sessions import JWT_CLIENT_ASSERTION, ClientAssertionClaims, SessionToken, _opaque_id
+
+DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code"
+
+
+class DeviceAuthorizationResponse(ProtocolModel):
+    """Validated response from the OAuth device authorization endpoint."""
+
+    device_code: SecretStr
+    user_code: str = Field(min_length=1, max_length=256)
+    verification_uri: str
+    verification_uri_complete: str | None = None
+    expires_in: int = Field(gt=0, le=3600)
+    interval: int = Field(default=5, gt=0, le=300)
+
+    @field_validator("verification_uri", "verification_uri_complete")
+    @classmethod
+    def validate_verification_url(cls, value: str | None) -> str | None:
+        return None if value is None else _https_url(value, "verification URI")
+
+
+class DeviceSignInStart(ProtocolModel):
+    """User-facing device instructions without the private device code."""
+
+    reference: str = Field(pattern=r"^device_[A-Za-z0-9_-]{22,}$")
+    user_code: str
+    verification_uri: str
+    verification_uri_complete: str | None = None
+    expires_at: datetime
+    poll_interval: int
+    requested_scopes: tuple[str, ...]
+
+
+class DeviceSignInPoll(ProtocolModel):
+    """One poll result; pending responses tell callers when to try again."""
+
+    status: Literal["pending", "complete"]
+    retry_at: datetime | None = None
+    token: SessionToken | None = None
+    account_token_reference: str | None = None
+    granted_scopes: tuple[str, ...] = ()
+    missing_scopes: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class _PendingDeviceSignIn:
+    device_code: SecretStr
+    token_endpoint: str
+    issuer: str
+    client_id: str
+    tenant_id: str
+    pairwise_user_id: str
+    session_id: str
+    scopes: tuple[str, ...]
+    expires_at: datetime
+    next_poll_at: datetime
+    interval: int
+
+
+class DeviceSignInClient:
+    """Start and poll PAP Device Sign-In without exposing the device code."""
+
+    def __init__(
+        self,
+        *,
+        reactor: PluginPlatform,
+        http_client: httpx.AsyncClient,
+        max_response_bytes: int = 100 * 1024,
+    ) -> None:
+        if max_response_bytes <= 0:
+            raise ValueError("max_response_bytes must be positive")
+        self.reactor = reactor
+        self.http = http_client
+        self.max_response_bytes = max_response_bytes
+
+    async def begin(
+        self,
+        *,
+        device_authorization_endpoint: str,
+        token_endpoint: str,
+        issuer: str,
+        client_id: str,
+        scopes: tuple[str, ...],
+        tenant_id: str,
+        pairwise_user_id: str,
+        session_id: str,
+    ) -> DeviceSignInStart:
+        """Request a device code and retain it behind an opaque state reference."""
+
+        clock, random_source, signer = self._proof_inputs()
+        now = clock.now()
+        endpoint = _https_url(device_authorization_endpoint, "device authorization endpoint")
+        token_url = _https_url(token_endpoint, "token endpoint")
+        client_url = _https_url(client_id, "client ID")
+        issuer_url = _https_url(issuer, "issuer")
+        requested_scopes = _scopes(scopes)
+        self._validate_context(tenant_id, pairwise_user_id, session_id)
+        assertion = await signer.sign(
+            self._client_assertion(client_url, endpoint, now, random_source).model_dump(),
+            purpose="client_assertion",
+        )
+        try:
+            response = await self.http.post(
+                endpoint,
+                data={
+                    "scope": " ".join(requested_scopes),
+                    "client_id": client_url,
+                    "client_assertion_type": JWT_CLIENT_ASSERTION,
+                    "client_assertion": assertion.get_secret_value(),
+                },
+                headers={"Accept": "application/json"},
+                follow_redirects=False,
+            )
+        except httpx.HTTPError as exc:
+            raise AuthorizationError(
+                "request_failed", "Device authorization request failed"
+            ) from exc
+        payload = self._decode(response, "device authorization")
+        if not response.is_success:
+            raise self._remote_error(response, payload, "Company refused Device Sign-In")
+        try:
+            authorization = DeviceAuthorizationResponse.model_validate(payload)
+        except ValueError as exc:
+            raise AuthorizationError(
+                "invalid_device_response",
+                "Device authorization response is malformed",
+                status_code=response.status_code,
+            ) from exc
+        expires_at = now + timedelta(seconds=authorization.expires_in)
+        reference = _opaque_id("device", random_source.bytes)
+        pending = _PendingDeviceSignIn(
+            device_code=authorization.device_code,
+            token_endpoint=token_url,
+            issuer=issuer_url,
+            client_id=client_url,
+            tenant_id=tenant_id,
+            pairwise_user_id=pairwise_user_id,
+            session_id=session_id,
+            scopes=requested_scopes,
+            expires_at=expires_at,
+            next_poll_at=now + timedelta(seconds=authorization.interval),
+            interval=authorization.interval,
+        )
+        store = self._state_store()
+        await store.put(reference, pending, expires_at=expires_at)
+        return DeviceSignInStart(
+            reference=reference,
+            user_code=authorization.user_code,
+            verification_uri=authorization.verification_uri,
+            verification_uri_complete=authorization.verification_uri_complete,
+            expires_at=expires_at,
+            poll_interval=authorization.interval,
+            requested_scopes=requested_scopes,
+        )
+
+    async def poll(self, reference: str) -> DeviceSignInPoll:
+        """Perform at most one protocol poll and enforce RFC 8628 pacing."""
+
+        store = self._state_store()
+        pending = await store.take(reference)
+        if not isinstance(pending, _PendingDeviceSignIn):
+            raise AuthorizationError(
+                "invalid_or_expired_device_session",
+                "Device Sign-In is unknown, expired, complete, or already being polled",
+            )
+        clock, random_source, signer = self._proof_inputs()
+        now = clock.now()
+        if now >= pending.expires_at:
+            raise AuthorizationError("expired_token", "Device Sign-In has expired")
+        if now < pending.next_poll_at:
+            await store.put(reference, pending, expires_at=pending.expires_at)
+            return DeviceSignInPoll(status="pending", retry_at=pending.next_poll_at)
+
+        try:
+            response, payload = await self._poll_token(pending, now, random_source, signer)
+        except Exception:
+            await store.put(reference, pending, expires_at=pending.expires_at)
+            raise
+        if response.is_success:
+            return await self._complete(response, payload, pending, random_source)
+
+        error = payload.get("error") if isinstance(payload, dict) else None
+        if error in {"authorization_pending", "slow_down"}:
+            interval = pending.interval + (5 if error == "slow_down" else 0)
+            resumed = replace(
+                pending,
+                interval=interval,
+                next_poll_at=now + timedelta(seconds=interval),
+            )
+            await store.put(reference, resumed, expires_at=pending.expires_at)
+            return DeviceSignInPoll(status="pending", retry_at=resumed.next_poll_at)
+        if error in {"access_denied", "expired_token"}:
+            raise AuthorizationError(error, "Device Sign-In ended without authorization")
+        await store.put(reference, pending, expires_at=pending.expires_at)
+        raise self._remote_error(response, payload, "Company refused the device token request")
+
+    async def _poll_token(
+        self,
+        pending: _PendingDeviceSignIn,
+        now: datetime,
+        random_source: RandomSource,
+        signer: Signer,
+    ) -> tuple[httpx.Response, object]:
+        assertion = await signer.sign(
+            self._client_assertion(
+                pending.client_id, pending.token_endpoint, now, random_source
+            ).model_dump(),
+            purpose="client_assertion",
+        )
+        dpop = cast(
+            DpopProofProvider,
+            first_contribution(self.reactor, DPOP_PROOF_PROVIDERS, "DPoP proof provider"),
+        )
+        proof = await dpop.create(
+            DpopProofRequest(
+                method="POST",
+                url=pending.token_endpoint,
+                tenant_id=pending.tenant_id,
+                subject=pending.pairwise_user_id,
+                issuer=pending.issuer,
+            )
+        )
+        try:
+            response = await self.http.post(
+                pending.token_endpoint,
+                data={
+                    "grant_type": DEVICE_CODE_GRANT,
+                    "device_code": pending.device_code.get_secret_value(),
+                    "session_id": pending.session_id,
+                    "client_id": pending.client_id,
+                    "client_assertion_type": JWT_CLIENT_ASSERTION,
+                    "client_assertion": assertion.get_secret_value(),
+                },
+                headers={"Accept": "application/json", "DPoP": proof.get_secret_value()},
+                follow_redirects=False,
+            )
+        except httpx.HTTPError as exc:
+            raise AuthorizationError("request_failed", "Device token request failed") from exc
+        return response, self._decode(response, "device token")
+
+    async def _complete(
+        self,
+        response: httpx.Response,
+        payload: object,
+        pending: _PendingDeviceSignIn,
+        random_source: RandomSource,
+    ) -> DeviceSignInPoll:
+        try:
+            token = SessionToken.model_validate(payload)
+        except ValueError as exc:
+            raise AuthorizationError(
+                "invalid_token_response",
+                "Device Sign-In token response is malformed",
+                status_code=response.status_code,
+            ) from exc
+        if (
+            token.token_type != "DPoP"  # noqa: S105 - OAuth token type, not a credential
+            or not token.signed_in
+            or token.session_id != pending.session_id
+        ):
+            raise AuthorizationError(
+                "invalid_token_response",
+                "Device Sign-In must return the signed-in proof-bound Session",
+                status_code=response.status_code,
+            )
+        if any(scope not in pending.scopes for scope in token.scopes):
+            raise AuthorizationError(
+                "scope_escalation",
+                "Company returned a scope that was not requested",
+                status_code=response.status_code,
+            )
+        if token.refresh_token is None:
+            raise AuthorizationError(
+                "missing_account_token",
+                "Device Sign-In did not return an Account Token",
+                status_code=response.status_code,
+            )
+        token_reference = _opaque_id("account", random_source.bytes)
+        token_store = cast(
+            TokenStore,
+            first_contribution(self.reactor, TOKEN_STORES, "token store"),
+        )
+        await token_store.put(token_reference, token.refresh_token)
+        public_token = token.model_copy(update={"refresh_token": None})
+        return DeviceSignInPoll(
+            status="complete",
+            token=public_token,
+            account_token_reference=token_reference,
+            granted_scopes=public_token.scopes,
+            missing_scopes=tuple(
+                scope for scope in pending.scopes if scope not in public_token.scopes
+            ),
+        )
+
+    def _proof_inputs(self) -> tuple[Clock, RandomSource, Signer]:
+        return (
+            cast(Clock, first_contribution(self.reactor, CLOCKS, "clock")),
+            cast(RandomSource, first_contribution(self.reactor, RANDOM_SOURCES, "random source")),
+            cast(Signer, first_contribution(self.reactor, SIGNERS, "signer")),
+        )
+
+    def _state_store(self) -> AuthorizationStateStore:
+        return cast(
+            AuthorizationStateStore,
+            first_contribution(
+                self.reactor, AUTHORIZATION_STATE_STORES, "authorization state store"
+            ),
+        )
+
+    @staticmethod
+    def _validate_context(tenant_id: str, pairwise_user_id: str, session_id: str) -> None:
+        import re
+
+        if not tenant_id or len(tenant_id) > 256:
+            raise ValueError("tenant_id must contain between 1 and 256 characters")
+        for label, value in (("pairwise_user_id", pairwise_user_id), ("session_id", session_id)):
+            if not re.fullmatch(r"[A-Za-z0-9_-]{1,256}", value):
+                raise ValueError(f"{label} must be an opaque URL-safe identifier")
+
+    @staticmethod
+    def _client_assertion(
+        client_id: str,
+        audience: str,
+        now: datetime,
+        random_source: RandomSource,
+    ) -> ClientAssertionClaims:
+        issued_at = int(now.timestamp())
+        return ClientAssertionClaims(
+            iss=client_id,
+            sub=client_id,
+            aud=audience,
+            iat=issued_at,
+            exp=issued_at + 60,
+            jti=_opaque_id("jti", random_source.bytes),
+        )
+
+    def _decode(self, response: httpx.Response, label: str) -> object:
+        if len(response.content) > self.max_response_bytes:
+            raise AuthorizationError(
+                "response_too_large",
+                f"{label.title()} response exceeds size limit",
+                status_code=response.status_code,
+            )
+        if response.headers.get("content-type", "").split(";", 1)[0].strip() != "application/json":
+            raise AuthorizationError(
+                "invalid_content_type",
+                f"{label.title()} endpoint must return JSON",
+                status_code=response.status_code,
+            )
+        try:
+            return loads_strict(response.content)
+        except ProtocolValidationError as exc:
+            raise AuthorizationError(
+                "invalid_json",
+                f"{label.title()} endpoint returned invalid JSON",
+                status_code=response.status_code,
+            ) from exc
+
+    @staticmethod
+    def _remote_error(
+        response: httpx.Response, payload: object, message: str
+    ) -> AuthorizationError:
+        remote = payload.get("error") if isinstance(payload, dict) else None
+        return AuthorizationError(
+            remote if isinstance(remote, str) else "http_error",
+            message,
+            status_code=response.status_code,
+        )