PyAgoraRTC 0.2.0__py3-none-any.whl

pyagorartc/__init__.py

@@ -0,0 +1,67 @@
+"""pyagorartc: an async client for Agora RTC signalling.
+
+``__all__`` is the supported surface (Constitution §10).
+"""
+
+from __future__ import annotations
+
+from pyagorartc.ap import AgoraAPClient, APResponse
+from pyagorartc.exceptions import (
+    APError,
+    APRejectedError,
+    GatewayConnectError,
+    JoinRejectedError,
+    JoinTimeoutError,
+    PyAgoraRTCError,
+    RtmError,
+    SdpError,
+    SessionClosedError,
+)
+from pyagorartc.models import (
+    ChannelCredentials,
+    ChannelEncryption,
+    CloseReason,
+    EdgeAddress,
+    IceCandidate,
+    ICEServer,
+    RemoteStream,
+    RtmCredentials,
+    SessionOptions,
+    TurnCredentialStrategy,
+    TurnMode,
+    fingerprint,
+)
+from pyagorartc.rtm import RtmRestClient
+from pyagorartc.sdp import extract_inline_candidates, filter_candidates, parse_trickle_fragment
+from pyagorartc.session import AgoraSession
+
+__all__ = [
+    "APError",
+    "APRejectedError",
+    "APResponse",
+    "AgoraAPClient",
+    "AgoraSession",
+    "ChannelCredentials",
+    "ChannelEncryption",
+    "CloseReason",
+    "EdgeAddress",
+    "GatewayConnectError",
+    "ICEServer",
+    "IceCandidate",
+    "JoinRejectedError",
+    "JoinTimeoutError",
+    "PyAgoraRTCError",
+    "RemoteStream",
+    "RtmCredentials",
+    "RtmError",
+    "RtmRestClient",
+    "SdpError",
+    "SessionClosedError",
+    "SessionOptions",
+    "TurnCredentialStrategy",
+    "TurnMode",
+    "extract_inline_candidates",
+    "filter_candidates",
+    "fingerprint",
+    "parse_trickle_fragment",
+]

pyagorartc/ap/__init__.py

@@ -0,0 +1,17 @@
+"""Access-point client: edge discovery and tickets."""
+
+from __future__ import annotations
+
+from pyagorartc.ap.client import AgoraAPClient, build_request_payload, encode_request
+from pyagorartc.ap.password import derive_password
+from pyagorartc.ap.response import APBlock, APResponse, fingerprints_from_edge
+
+__all__ = [
+    "APBlock",
+    "APResponse",
+    "AgoraAPClient",
+    "build_request_payload",
+    "derive_password",
+    "encode_request",
+    "fingerprints_from_edge",
+]

pyagorartc/ap/client.py

@@ -0,0 +1,244 @@
+"""``AgoraAPClient``: the access-point HTTP call (``choose_server``, ``update_ticket``) with host fallback.
+
+Every HTTP exchange goes through ``AgoraAPClient._post``, the same seam ``RtmRestClient`` has, so a unit
+test replaces that one method on the instance with a recorder instead of mocking aiohttp.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import secrets
+import time
+from typing import TYPE_CHECKING, Self
+from urllib.parse import urlsplit
+
+import aiohttp
+
+from pyagorartc.ap.response import APResponse
+from pyagorartc.const import (
+    AP_HOSTS,
+    AP_PATH,
+    AP_QUERY,
+    AP_TIMEOUT_S,
+    AP_URI_CHOOSE_SERVER,
+    AP_URI_UPDATE_TICKET,
+    DEFAULT_SERVICE_IDS,
+    ROLE_HOST,
+    SERVICE_GATEWAY,
+)
+from pyagorartc.exceptions import APError, APRejectedError
+from pyagorartc.models import fingerprint
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping, Sequence
+    from types import TracebackType
+
+    from pyagorartc.models import ChannelCredentials, EdgeAddress
+
+_LOGGER = logging.getLogger(__name__)
+
+_REQUEST_FIELD = "request"
+_HTTP_OK = 200
+_SID_BOUND = 2**31  # shipped: sid is a random int below 2**31, sent as a string
+_OPID_BOUND = 10**12
+
+
+def build_request_payload(  # noqa: PLR0913 -- pure: each wire value arrives as an argument
+    creds: ChannelCredentials,
+    *,
+    uri: int,
+    service_ids: Sequence[int],
+    sid: str,
+    opid: int,
+    client_ts: int,
+    role: int = ROLE_HOST,
+    edges: Sequence[EdgeAddress] = (),
+) -> dict[str, object]:
+    """The AP request (protocol.md §1.1); pure, so ids and ``client_ts`` (ms) come from the caller.
+
+    ``detail`` carries ``11``/``22`` (area code) and ``17`` (role), plus ``6`` when the credentials have a
+    string uid (Q9). ``edges`` become ``edges_services`` for ``update_ticket`` and are omitted when empty.
+    """
+    detail: dict[str, str] = {"11": creds.area_code}
+    if role:
+        detail["17"] = str(role)
+    detail["22"] = creds.area_code
+    if creds.string_uid:
+        detail["6"] = creds.string_uid
+    buffer: dict[str, object] = {
+        "cname": creds.channel_name,
+        "detail": detail,
+        "key": creds.token,
+        "service_ids": list(service_ids),
+        "uid": creds.uid,
+    }
+    if edges:
+        buffer["edges_services"] = [{"ip": edge.ip, "port": edge.port} for edge in edges]
+    return {
+        "appid": creds.app_id,
+        "client_ts": client_ts,
+        "opid": opid,
+        "sid": sid,
+        "request_bodies": [{"uri": uri, "buffer": buffer}],
+    }
+
+
+def encode_request(payload: Mapping[str, object]) -> str:
+    """The exact text sent in the form's ``request`` field."""
+    return json.dumps(payload)
+
+
+def _endpoint_url(host: str, proxy_server: str | None) -> str:
+    if proxy_server is None:
+        return f"{host}{AP_PATH}{AP_QUERY}"
+    return f"https://{proxy_server}/ap/?url={urlsplit(host).netloc}{AP_PATH}{AP_QUERY}"
+
+
+class AgoraAPClient:
+    """Edge discovery against Agora's access points, trying each host in order.
+
+    A borrowed ``session`` is never closed; without one the client creates its own on first use and
+    closes it in ``close()`` / ``__aexit__``. TLS is verified unless ``verify_ssl=False`` (D10).
+    ``id_factory``, when given, supplies the ``sid`` (when not passed) and then the ``opid`` of each
+    request; by default they are drawn from ``secrets`` in the SDK's ranges.
+    """
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession | None = None,
+        *,
+        hosts: Sequence[str] = AP_HOSTS,
+        verify_ssl: bool = True,
+        timeout_s: float = AP_TIMEOUT_S,
+        clock: Callable[[], float] = time.time,
+        id_factory: Callable[[], int] | None = None,
+    ) -> None:
+        self._session = session
+        self._owns_session = session is None
+        self._hosts = tuple(hosts)
+        self._verify_ssl = verify_ssl
+        self._timeout = aiohttp.ClientTimeout(total=timeout_s)
+        self._clock = clock
+        self._id_factory = id_factory
+
+    def __repr__(self) -> str:
+        return f"AgoraAPClient(hosts={list(self._hosts)!r}, verify_ssl={self._verify_ssl}, owns_session={self._owns_session})"
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the session this client created, if any; a borrowed session is left open."""
+        if self._owns_session and self._session is not None:
+            session, self._session = self._session, None
+            await session.close()
+
+    async def choose_server(
+        self,
+        creds: ChannelCredentials,
+        *,
+        role: int = ROLE_HOST,
+        service_ids: Sequence[int] = DEFAULT_SERVICE_IDS,
+        sid: str | None = None,
+        proxy_server: str | None = None,
+    ) -> APResponse:
+        """Ask for gateway (and by default TURN) edges for ``creds`` (URI 22).
+
+        Raises:
+            APRejectedError: An AP answered and every requested service failed.
+            APError: No host gave a usable answer; ``status`` is the last host's HTTP status, if any.
+
+        """
+        return await self._request(
+            creds, uri=AP_URI_CHOOSE_SERVER, service_ids=service_ids, sid=sid, role=role, proxy_server=proxy_server
+        )
+
+    async def update_ticket(
+        self,
+        creds: ChannelCredentials,
+        edges: Sequence[EdgeAddress],
+        *,
+        sid: str | None = None,
+        service_ids: Sequence[int] = (SERVICE_GATEWAY,),
+        proxy_server: str | None = None,
+    ) -> APResponse:
+        """Refresh the ticket for known ``edges`` (URI 28); raises as ``choose_server`` does."""
+        return await self._request(
+            creds, uri=AP_URI_UPDATE_TICKET, service_ids=service_ids, sid=sid, edges=edges, proxy_server=proxy_server
+        )
+
+    def _next_id(self, bound: int) -> int:
+        return self._id_factory() if self._id_factory is not None else secrets.randbelow(bound)
+
+    def _http(self) -> aiohttp.ClientSession:
+        if self._session is None:
+            self._session = aiohttp.ClientSession()
+        return self._session
+
+    async def _post(self, url: str, headers: Mapping[str, str], body: Mapping[str, object]) -> tuple[int, object]:
+        """POST ``body`` as the multipart ``request`` field; returns the status and decoded JSON (``None`` if not JSON)."""
+        form = aiohttp.FormData()
+        form.add_field(_REQUEST_FIELD, encode_request(body), content_type="application/json")
+        async with self._http().post(
+            url, headers=headers, data=form, timeout=self._timeout, ssl=self._verify_ssl
+        ) as response:
+            text = await response.text(errors="replace")
+        try:
+            return response.status, json.loads(text) if text else None
+        except (ValueError, RecursionError):
+            return response.status, None
+
+    async def _request(
+        self,
+        creds: ChannelCredentials,
+        *,
+        uri: int,
+        service_ids: Sequence[int],
+        sid: str | None,
+        proxy_server: str | None,
+        role: int = ROLE_HOST,
+        edges: Sequence[EdgeAddress] = (),
+    ) -> APResponse:
+        sid = str(self._next_id(_SID_BOUND)) if sid is None else sid
+        payload = build_request_payload(
+            creds,
+            uri=uri,
+            service_ids=service_ids,
+            sid=sid,
+            opid=self._next_id(_OPID_BOUND),
+            client_ts=int(self._clock() * 1000),
+            role=role,
+            edges=edges,
+        )
+        _LOGGER.debug(
+            "AP request uri=%s channel=%s services=%s token=%s",
+            uri,
+            creds.channel_name,
+            list(service_ids),
+            fingerprint(creds.token),
+        )
+        status: int | None = None
+        for host in self._hosts:
+            url = _endpoint_url(host, proxy_server)
+            try:
+                status, data = await self._post(url, {}, payload)
+            except (aiohttp.ClientError, TimeoutError) as exc:
+                status = None
+                _LOGGER.debug("AP host %s failed: %s", host, type(exc).__name__)
+                continue
+            if status != _HTTP_OK or not isinstance(data, dict):
+                _LOGGER.debug("AP host %s answered HTTP %s with %s", host, status, type(data).__name__)
+                continue
+            try:
+                return APResponse.from_api_response(data, clock=self._clock)
+            except APRejectedError:
+                raise
+            except APError:
+                _LOGGER.debug("AP host %s answered without a response_body", host)
+        raise APError(f"no access point host answered usefully ({len(self._hosts)} tried)", status=status)

pyagorartc/ap/password.py

@@ -0,0 +1,14 @@
+"""The uid-derived TURN password Agora's edges accept (D12)."""
+
+from __future__ import annotations
+
+import hashlib
+
+
+def derive_password(uid: int | str) -> str:
+    """The TURN credential for ``uid``: the lowercase hex SHA-256 of its decimal string.
+
+    This is the Web SDK's ``ENCRYPT_PROXY_USERNAME_AND_PSW`` rule (``agoraRTC_N-4.24.3.js:43740-43755``),
+    which shipped in both hosts; the matching username is ``str(uid)``.
+    """
+    return hashlib.sha256(str(uid).encode("utf-8")).hexdigest()

pyagorartc/ap/response.py

@@ -0,0 +1,329 @@
+"""``APResponse``: an access-point answer parsed into edges, tickets, ICE servers and the join's ``ap_response``.
+
+Merge rules are ``docs/analysis/divergence.md`` §1.1; the wire shape is ``docs/protocol.md`` §1.3-§1.4.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+import logging
+import time
+from typing import TYPE_CHECKING
+
+from pyagorartc.ap.password import derive_password
+from pyagorartc.const import (
+    AP_FLAG_GATEWAY,
+    AP_FLAG_TURN,
+    EDGE_DOMAIN_SUFFIX,
+    GATEWAY_TURN_PORT_OFFSET,
+    TURN_PORT,
+    TURNS_PORT,
+)
+from pyagorartc.exceptions import APError, APRejectedError
+from pyagorartc.models import EdgeAddress, ICEServer, TurnCredentialStrategy, TurnMode, as_int, fingerprint
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+_LOGGER = logging.getLogger(__name__)
+
+_DETAIL_FINGERPRINTS = "19"
+_DEFAULT_FINGERPRINT_ALGORITHM = "sha-256"
+_DETAIL_TURN_USERNAME = "8"
+_DETAIL_TURN_CREDENTIAL = "4"
+_MISSING_CODE = -1
+
+type JsonObject = Mapping[str, object]
+
+
+def _as_object(value: object) -> JsonObject:
+    return value if isinstance(value, Mapping) else {}
+
+
+def fingerprints_from_edge(edge: EdgeAddress) -> list[dict[str, str]]:
+    """``edge``'s detail-19 fingerprint as gateway-ORTC ``dtlsParameters.fingerprints`` (D26); empty when it has none.
+
+    Accepts ``sha-256 AA:BB:…`` and a bare ``AA:BB:…`` (read as sha-256), as both shipped hosts parsed it.
+    """
+    match (edge.fingerprint or "").split():
+        case [value]:
+            return [{"algorithm": _DEFAULT_FINGERPRINT_ALGORITHM, "fingerprint": value}]
+        case [algorithm, value]:
+            return [{"algorithm": algorithm, "fingerprint": value}]
+        case []:
+            return []
+        case parts:
+            _LOGGER.debug("Ignoring an AP edge fingerprint of %s words; expected 'algorithm value'", len(parts))
+            return []
+
+
+def _parse_edges(raw: object, ticket: str, detail: JsonObject) -> tuple[EdgeAddress, ...]:
+    # Fingerprints are matched to edges by index in the list as sent, before filtering (SDK:48698-48704).
+    fingerprints = [fp.strip() or None for fp in str(detail.get(_DETAIL_FINGERPRINTS) or "").split(";")]
+    edges: list[EdgeAddress] = []
+    for index, entry in enumerate(raw if isinstance(raw, list) else []):
+        edge = _as_object(entry)
+        ip = edge.get("ip")
+        port = as_int(edge.get("port"), 0)
+        if not isinstance(ip, str) or not ip or port <= 0:
+            continue
+        edges.append(
+            EdgeAddress(
+                ip=ip,
+                port=port,
+                ticket=ticket,
+                fingerprint=fingerprints[index] if index < len(fingerprints) else None,
+            )
+        )
+    return tuple(edges)
+
+
+@dataclass(frozen=True, repr=False)
+class APBlock:
+    """One successful ``response_body[].buffer``, keyed by its ``flag``.
+
+    ``detail`` is the top-level ``detail`` with the buffer's own merged over it (SDK:43726). Edges
+    carry the block's ticket and fingerprint but no TURN credentials; ``get_ice_servers`` resolves
+    those per ``TurnCredentialStrategy``.
+    """
+
+    flag: int
+    code: int
+    uid: int
+    cid: int
+    cname: str
+    ticket: str
+    detail: dict[str, object]
+    addresses: tuple[EdgeAddress, ...]
+
+    @classmethod
+    def from_buffer(cls, buffer: JsonObject, base_detail: JsonObject) -> APBlock:
+        """Parse one buffer; edges missing an ``ip`` or ``port`` are dropped."""
+        detail = {**base_detail, **_as_object(buffer.get("detail"))}
+        ticket = str(buffer.get("cert") or "")
+        return cls(
+            flag=as_int(buffer.get("flag"), 0),
+            code=as_int(buffer.get("code"), _MISSING_CODE),
+            uid=as_int(buffer.get("uid"), 0),
+            cid=as_int(buffer.get("cid"), 0),
+            cname=str(buffer.get("cname") or ""),
+            ticket=ticket,
+            detail=detail,
+            addresses=_parse_edges(buffer.get("edges_services"), ticket, detail),
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"APBlock(flag={self.flag}, code={self.code}, uid={self.uid}, cid={self.cid}, cname={self.cname!r}, "
+            f"ticket=<{fingerprint(self.ticket)}>, detail_keys={sorted(self.detail)}, addresses={len(self.addresses)})"
+        )
+
+
+def _turn_urls(ip: str, mode: TurnMode) -> list[str]:
+    urls: list[str] = []
+    if mode in {TurnMode.ALL, TurnMode.UDP_ONLY}:
+        urls.append(f"turn:{ip}:{TURN_PORT}?transport=udp")
+    if mode in {TurnMode.ALL, TurnMode.TCP_ONLY}:
+        urls.append(f"turn:{ip}:{TURN_PORT}?transport=tcp")
+    if mode in {TurnMode.ALL, TurnMode.TLS_ONLY}:
+        urls.append(f"turns:{ip.replace('.', '-')}{EDGE_DOMAIN_SUFFIX}:{TURNS_PORT}?transport=tcp")
+    return urls
+
+
+def _turn_credentials(block: APBlock, strategy: TurnCredentialStrategy, uid: int) -> tuple[str, str]:
+    username, credential = str(uid), derive_password(uid)
+    # Only the TURN block's detail 8/4 are credentials; the gateway block's detail 8 is its vid.
+    if strategy is TurnCredentialStrategy.DETAIL_FIRST and block.flag == AP_FLAG_TURN:
+        # Each key falls back on its own, as the PetKit copy shipped (D12).
+        username = str(block.detail.get(_DETAIL_TURN_USERNAME) or username)
+        credential = str(block.detail.get(_DETAIL_TURN_CREDENTIAL) or credential)
+    return username, credential
+
+
+@dataclass(frozen=True, repr=False)
+class APResponse:
+    """A parsed ``choose_server`` / ``update_ticket`` answer.
+
+    ``responses`` holds every successful block by flag, however many there are. The primary block
+    is flag 4096 when it succeeded, else the first successful block, and every primary scalar
+    (``ticket``, ``uid``, ``cid``, ``cname``, ``detail``, ``addresses``) is read from that one block.
+    """
+
+    responses: dict[int, APBlock]
+    primary_flag: int
+    server_ts: int
+    opid: int
+
+    @classmethod
+    def from_api_response(cls, data: JsonObject, *, clock: Callable[[], float] = time.time) -> APResponse:
+        """Parse the AP's JSON body; ``clock`` (seconds) stands in for a missing ``enter_ts``.
+
+        Raises:
+            APRejectedError: Every buffer carried a non-zero ``code``; ``codes`` maps flag to code.
+            APError: The body has no ``response_body`` entries at all.
+
+        """
+        body = data.get("response_body")
+        if not isinstance(body, list) or not body:
+            raise APError("access point response has no response_body")
+        base_detail = _as_object(data.get("detail"))
+        blocks: dict[int, APBlock] = {}
+        failed: dict[int, int] = {}
+        for item in body:
+            block = APBlock.from_buffer(_as_object(_as_object(item).get("buffer")), base_detail)
+            if block.code != 0:
+                _LOGGER.debug("AP block flag=%s failed with code=%s; skipped", block.flag, block.code)
+                failed[block.flag] = block.code
+                continue
+            blocks[block.flag] = block
+        if not blocks:
+            raise APRejectedError(failed)
+        enter_ts = data.get("enter_ts")
+        return cls(
+            responses=blocks,
+            primary_flag=AP_FLAG_GATEWAY if AP_FLAG_GATEWAY in blocks else next(iter(blocks)),
+            server_ts=int(clock() * 1000) if enter_ts is None else as_int(enter_ts, 0),
+            opid=as_int(data.get("opid"), 0),
+        )
+
+    @property
+    def primary(self) -> APBlock:
+        """The block every primary scalar comes from."""
+        return self.responses[self.primary_flag]
+
+    @property
+    def code(self) -> int:
+        """The primary block's ``code`` (always 0: failed blocks are not kept)."""
+        return self.primary.code
+
+    @property
+    def ticket(self) -> str:
+        """The primary block's ``cert``."""
+        return self.primary.ticket
+
+    @property
+    def uid(self) -> int:
+        """The uid the AP assigned in the primary block."""
+        return self.primary.uid
+
+    @property
+    def cid(self) -> int:
+        """The primary block's channel id."""
+        return self.primary.cid
+
+    @property
+    def cname(self) -> str:
+        """The primary block's channel name."""
+        return self.primary.cname
+
+    @property
+    def detail(self) -> dict[str, object]:
+        """The primary block's merged ``detail``."""
+        return self.primary.detail
+
+    @property
+    def addresses(self) -> list[EdgeAddress]:
+        """The primary block's edges."""
+        return list(self.primary.addresses)
+
+    def get_gateway_addresses(self) -> list[EdgeAddress]:
+        """The WebSocket gateway edges (flag 4096) in AP order; empty when that block failed."""
+        return list(block.addresses) if (block := self.responses.get(AP_FLAG_GATEWAY)) else []
+
+    def get_turn_addresses(self) -> list[EdgeAddress]:
+        """The TURN edges (flag 4194310) in AP order; empty when that block failed or was not asked for."""
+        return list(block.addresses) if (block := self.responses.get(AP_FLAG_TURN)) else []
+
+    def get_ice_servers(
+        self,
+        *,
+        use_all_turn_servers: bool = False,
+        turn_mode: TurnMode = TurnMode.ALL,
+        strategy: TurnCredentialStrategy = TurnCredentialStrategy.UID,
+        uid: int | None = None,
+    ) -> list[ICEServer]:
+        """ICE servers for a viewer: one entry per transport per TURN edge, one url each.
+
+        UDP and TCP use ``turn:{ip}:3478``; TLS uses ``turns:{a-b-c-d}.edge.agora.io:443``. Without
+        TURN edges the primary edges are used, as both hosts shipped. Credentials follow ``strategy``
+        (D12), with AP detail 8/4 read only from the TURN block; ``uid`` replaces the block's uid for the
+        uid-derived pair.
+        """
+        turn = self.responses.get(AP_FLAG_TURN)
+        block = turn if turn is not None and turn.addresses else self.primary
+        if block is not turn:
+            _LOGGER.debug("no TURN edges in the AP response; using flag %s edges", block.flag)
+        addresses = block.addresses if use_all_turn_servers else block.addresses[:1]
+        username, credential = _turn_credentials(block, strategy, block.uid if uid is None else uid)
+        return [
+            ICEServer(urls=[url], username=username, credential=credential)
+            for address in addresses
+            for url in _turn_urls(address.ip, turn_mode)
+        ]
+
+    def turn_server_config(self, gateway: EdgeAddress | None, token: str | None) -> dict[str, object]:
+        """The SDK's ``turnServer`` object (protocol.md §1.4); pure, and unused by the session.
+
+        ``servers`` are the TURN edges with uid-derived credentials. ``serversFromGateway`` holds the
+        connected gateway on its port + 30 with the channel token as password, only when both are given.
+        """
+        servers = [
+            {
+                "turnServerURL": address.ip,
+                "tcpport": address.port,
+                "udpport": address.port,
+                "username": str(self.uid),
+                "password": derive_password(self.uid),
+                "forceturn": False,
+                "security": True,
+            }
+            for address in self.get_turn_addresses()
+        ]
+        from_gateway: list[dict[str, object]] = []
+        if gateway is not None and token:
+            port = gateway.port + GATEWAY_TURN_PORT_OFFSET
+            from_gateway.append(
+                {
+                    "username": str(self.uid),
+                    "password": token,
+                    "turnServerURL": gateway.ip,
+                    "tcpport": port,
+                    "udpport": port,
+                    "forceturn": False,
+                }
+            )
+        return {"mode": "manual", "servers": servers, "serversFromGateway": from_gateway}
+
+    def to_ap_response(self, flag: int | None = None) -> dict[str, object]:
+        """One block (the primary by default) as the join's ``ap_response``: ``cert`` doubled as ``ticket``.
+
+        Raises:
+            APError: ``flag`` names a block this response does not hold.
+
+        """
+        if flag is None:
+            block = self.primary
+        elif (found := self.responses.get(flag)) is not None:
+            block = found
+        else:
+            raise APError(f"access point response has no block for flag {flag}")
+        return {
+            "code": block.code,
+            "server_ts": self.server_ts,
+            "uid": block.uid,
+            "cid": block.cid,
+            "cname": block.cname,
+            "detail": dict(block.detail),
+            "flag": block.flag,
+            "opid": self.opid,
+            "cert": block.ticket,
+            "ticket": block.ticket,
+        }
+
+    def __repr__(self) -> str:
+        return (
+            f"APResponse(primary_flag={self.primary_flag}, flags={list(self.responses)}, uid={self.uid}, "
+            f"cid={self.cid}, cname={self.cname!r}, ticket=<{fingerprint(self.ticket)}>, "
+            f"server_ts={self.server_ts}, opid={self.opid})"
+        )