aidr-verifier 0.1.0__py3-none-any.whl

aidr_verifier/__init__.py

@@ -0,0 +1,60 @@
+"""AIDR relying-party SDK — verify agent identity offline.
+
+Minimal integration::
+
+    from aidr_verifier import AgentVerifier, VerificationPolicy, build_trust_store, NonceCache
+
+    trust = build_trust_store(jwks, delta_token=delta, expected_issuer="https://registry.aidr.example")
+    verifier = AgentVerifier(trust, policy=VerificationPolicy(min_assurance=1),
+                             nonce_seen=NonceCache())
+
+    result = verifier.verify(method="GET", url="https://shop.example/api", headers=request.headers)
+
+Refresh ``jwks`` hourly and the revocation delta every 60 seconds, in the background. Nothing in
+the request path contacts the registry. For ASGI applications, :class:`AidrMiddleware` does all of
+this — background sync, shared replay protection, and the anonymous / verified / refused decision —
+and puts the result in ``request.state.aidr`` (see ``aidr_verifier.asgi``).
+"""
+
+from .agent import AgentClient, AgentCredentialHolder
+from .asgi import AidrIdentity, AidrMiddleware, RelyingPartyConfig
+from .edge import EdgeContextMiddleware, verify_edge_context
+from .nonce import MemoryNonceStore, NonceStore, NonceStoreUnavailable, RedisNonceStore
+from .sync import TrustSync
+from .trust import (
+    JWKS_REFRESH_SECONDS,
+    REVOCATION_REFRESH_SECONDS,
+    KeySet,
+    NonceCache,
+    RevocationState,
+    TrustStore,
+    build_trust_store,
+)
+from .verifier import AgentVerifier, VerificationPolicy, VerificationResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AgentClient",
+    "AgentCredentialHolder",
+    "AgentVerifier",
+    "VerificationPolicy",
+    "VerificationResult",
+    "TrustStore",
+    "KeySet",
+    "RevocationState",
+    "NonceCache",
+    "build_trust_store",
+    "AidrMiddleware",
+    "RelyingPartyConfig",
+    "AidrIdentity",
+    "EdgeContextMiddleware",
+    "verify_edge_context",
+    "TrustSync",
+    "NonceStore",
+    "NonceStoreUnavailable",
+    "MemoryNonceStore",
+    "RedisNonceStore",
+    "JWKS_REFRESH_SECONDS",
+    "REVOCATION_REFRESH_SECONDS",
+]

aidr_verifier/agent.py

@@ -0,0 +1,146 @@
+"""Agent-side helpers: hold a key, hold a credential, sign outgoing requests.
+
+This runs on the **agent operator's** infrastructure, never on the registry's. The private key is
+generated here, stays here, and is never transmitted. The registry only ever sees the public half,
+which is why a total compromise of the registry gives an attacker no ability to impersonate any
+agent.
+
+Usage::
+
+    private_key, public_key = generate_keypair()
+    holder = AgentCredentialHolder(aid, private_key, credential_token, expires_at)
+    headers = holder.sign_headers("GET", "https://shop.example/api/products")
+    response = httpx.get("https://shop.example/api/products", headers=headers)
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+from aidr_core.errors import CredentialExpired
+from aidr_crypto.keys import algorithm_for_key, generate_keypair, public_key_to_jwk
+from aidr_crypto.signatures import CREDENTIAL_HEADER, DEFAULT_COMPONENTS, sign_request
+
+logger = logging.getLogger(__name__)
+
+#: Renew this long before expiry. A credential that expires mid-flight produces a failure the
+#: agent cannot retry its way out of, so renewal is always early rather than just-in-time.
+RENEWAL_MARGIN = timedelta(minutes=3)
+
+
+@dataclass
+class AgentCredentialHolder:
+    """An agent identity in use: an identifier, a private key, and a current credential."""
+
+    aid: str
+    private_key: Any
+    credential: str
+    expires_at: datetime
+
+    def is_expired(self, *, now: datetime | None = None) -> bool:
+        return (now or datetime.now(timezone.utc)) >= self.expires_at
+
+    def needs_renewal(self, *, now: datetime | None = None,
+                      margin: timedelta = RENEWAL_MARGIN) -> bool:
+        return (now or datetime.now(timezone.utc)) >= self.expires_at - margin
+
+    def sign_headers(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        components: tuple[str, ...] = DEFAULT_COMPONENTS,
+        now: datetime | None = None,
+        algorithm: Any = None,
+    ) -> dict[str, str]:
+        """Return the headers to attach to one outgoing request.
+
+        A fresh nonce and timestamp are generated per request, so the headers are single-use.
+        Reusing them across requests would defeat the replay protection the verifier relies on.
+        """
+        if self.is_expired(now=now):
+            raise CredentialExpired(
+                "credential has expired — obtain a new one before signing", aid=self.aid
+            )
+
+        signed = sign_request(
+            method=method,
+            url=url,
+            headers=headers or {},
+            private_key=self.private_key,
+            keyid=self.aid,
+            components=components,
+            created=now,
+            # Derived from the key itself rather than configured. An agent holding a P-256 key
+            # cannot accidentally advertise ed25519 and have every verifier reject it.
+            algorithm=algorithm or algorithm_for_key(self.private_key),
+        )
+        signed[CREDENTIAL_HEADER] = self.credential
+        return signed
+
+    def public_jwk(self) -> dict[str, Any]:
+        return public_key_to_jwk(self.private_key.public_key())
+
+
+class AgentClient:
+    """An agent identity with automatic credential renewal.
+
+    ``renew`` is supplied by the operator: it calls the registry's issuance endpoint with whatever
+    authentication that deployment uses, and returns ``(credential_token, expires_at)``. Keeping
+    it injectable means this SDK carries no HTTP client and no opinion about authentication.
+    """
+
+    def __init__(
+        self,
+        aid: str,
+        private_key: Any,
+        renew: Callable[[], Awaitable[tuple[str, datetime]]],
+        *,
+        renewal_margin: timedelta = RENEWAL_MARGIN,
+    ) -> None:
+        self.aid = aid
+        self.private_key = private_key
+        self._renew = renew
+        self._margin = renewal_margin
+        self._holder: AgentCredentialHolder | None = None
+
+    @classmethod
+    def with_new_keypair(cls, aid: str,
+                         renew: Callable[[], Awaitable[tuple[str, datetime]]]) -> AgentClient:
+        private_key, _ = generate_keypair()
+        return cls(aid, private_key, renew)
+
+    async def ensure_credential(self, *, now: datetime | None = None) -> AgentCredentialHolder:
+        moment = now or datetime.now(timezone.utc)
+        if self._holder is None or self._holder.needs_renewal(now=moment, margin=self._margin):
+            token, expires_at = await self._renew()
+            self._holder = AgentCredentialHolder(
+                aid=self.aid, private_key=self.private_key,
+                credential=token, expires_at=expires_at,
+            )
+            logger.debug("renewed credential for %s, expires %s", self.aid, expires_at.isoformat())
+        return self._holder
+
+    async def sign_headers(self, method: str, url: str, **kwargs: Any) -> dict[str, str]:
+        holder = await self.ensure_credential()
+        return holder.sign_headers(method, url, **kwargs)
+
+    @property
+    def credential_expires_at(self) -> datetime | None:
+        return self._holder.expires_at if self._holder else None
+
+    def public_jwk(self) -> dict[str, Any]:
+        return public_key_to_jwk(self.private_key.public_key())
+
+    def forget_credential(self) -> None:
+        """Drop the cached credential, forcing renewal on next use.
+
+        Call after a 401 from a relying party: the credential may have been revoked, and the agent
+        should not keep presenting one that has already been refused.
+        """
+        self._holder = None

aidr_verifier/asgi.py

@@ -0,0 +1,444 @@
+"""ASGI middleware: verify AI agents in front of any ASGI application.
+
+Works with FastAPI, Starlette, and Django under ASGI::
+
+    from aidr_verifier.asgi import AidrMiddleware, RelyingPartyConfig
+
+    app.add_middleware(AidrMiddleware, config=RelyingPartyConfig(
+        issuer="https://registry.aidr.example",
+        public_origin="https://shop.example",
+        min_agal=1,
+        bypass=[r"/health", r"/static/.*"],
+    ))
+
+    @app.get("/api/products")
+    async def products(request: Request):
+        identity = request.state.aidr            # always present on HTTP requests
+        if identity.is_agent:
+            ...identity.organization, identity.agal, identity.org_domains...
+
+Every HTTP request ends in exactly one of these outcomes:
+
+* **anonymous** — none of ``Agent-Credential``, ``Signature``, ``Signature-Input`` is present. Passed
+  through: this is a person, or a bot that did not identify itself, and the site's other rules
+  apply to it as before.
+* **verified** — the agent's identity was proven and meets the site's policy. Passed through with
+  ``request.state.aidr`` populated.
+* **refused** — the request claims to be an agent and is not a valid one (401), is a revoked or
+  out-of-policy one (403, with a reason code), or cannot be checked right now (503).
+
+A request carrying *some* of the headers is a claim to be an agent, and is judged as one. Treating
+it as anonymous would let an agent whose credential fails simply fall back to being a stranger —
+which is the site's call to make for strangers, not ours to make for a failed identity.
+
+The identity is placed in the ASGI scope, never in request headers, so there is nothing a client
+could forge on the way in.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextvars
+import json
+import logging
+import math
+import posixpath
+import re
+from collections.abc import Callable, Iterable, Sequence
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Literal
+from urllib.parse import unquote, urlsplit
+
+from aidr_core.errors import (
+    AgentRevoked,
+    AidrError,
+    AssuranceTooLow,
+    CapabilityDenied,
+    CredentialRevoked,
+    MalformedToken,
+    PolicyViolation,
+    RegistryUnavailable,
+    ReplayDetected,
+    UnknownIssuer,
+)
+from aidr_crypto.signatures import (
+    CREDENTIAL_HEADER,
+    DEFAULT_MAX_AGE_SECONDS,
+    SIGNATURE_HEADER,
+    SIGNATURE_INPUT_HEADER,
+    effective_request_uri,
+)
+
+from .nonce import MemoryNonceStore, NonceStore
+from .sync import TrustSync
+from .trust import KeySet, TrustStore
+from .verifier import AgentVerifier, VerificationPolicy, VerificationResult
+
+logger = logging.getLogger("aidr.middleware")
+
+AGENT_HEADERS = tuple(h.lower() for h in (CREDENTIAL_HEADER, SIGNATURE_HEADER,
+                                          SIGNATURE_INPUT_HEADER))
+
+#: Refusals that mean "you are an agent, and not one this site will serve" rather than "you did
+#: not prove who you are".
+_FORBIDDEN = (AgentRevoked, CredentialRevoked, AssuranceTooLow, CapabilityDenied, PolicyViolation)
+
+
+# ==============================================================================================
+# Configuration
+# ==============================================================================================
+
+@dataclass
+class RelyingPartyConfig:
+    #: The registry, exactly as it appears in credentials' ``iss``. Trust material is discovered
+    #: from ``<issuer>/.well-known/aiaf-registry`` and must live on this origin.
+    issuer: str
+
+    #: This site's public origin, e.g. ``https://shop.example``. When set, the URI a signature is
+    #: checked against is built from it rather than from the Host header and scheme, which a
+    #: reverse proxy may have rewritten. Strongly recommended behind any proxy. It is also the
+    #: default expected audience.
+    public_origin: str | None = None
+
+    #: Assurance floors. AgAL is min(OAL, KAL); the separate floors let a site say which axis it
+    #: actually cares about — "a verified company" (OAL) or "a hardware-held key" (KAL).
+    min_agal: int = 0
+    min_oal: int = 0
+    min_kal: int = 0
+
+    required_capabilities: Sequence[str] = ()
+    max_upheld_abuse_reports: int | None = None
+
+    #: Audience this site accepts for audience-bound credentials. Defaults to ``public_origin``.
+    expected_audience: str | None = None
+
+    #: Regular expressions for paths where agent verification does not run at all. Each is
+    #: matched with ``fullmatch`` against the *normalised* path (decoded, dot segments resolved,
+    #: slashes collapsed), so ``/health`` never matches ``/health/../admin`` or ``/x/health``.
+    #: A path that does not normalise unambiguously is never bypassed.
+    bypass: Iterable[str] = ()
+
+    #: Replay protection. The default is correct only for a single worker process; any site with
+    #: more than one must pass a shared store (:class:`~aidr_verifier.nonce.RedisNonceStore`).
+    nonce_store: NonceStore | None = None
+
+    max_signature_age_seconds: int = DEFAULT_MAX_AGE_SECONDS
+
+    #: Pre-built trust. When given with ``sync=False``, nothing is fetched — for tests and for
+    #: sites that manage trust material themselves.
+    trust: TrustStore | None = None
+    sync: bool = True
+    #: An ``httpx.AsyncClient`` for the registry, e.g. one configured with a private CA.
+    http_client: Any = None
+    initial_sync_timeout: float = 10.0
+
+    #: Injected clock, for replaying time-bound test vectors. Leave unset in production.
+    clock: Callable[[], datetime] | None = None
+
+
+# ==============================================================================================
+# The identity handed to the application
+# ==============================================================================================
+
+@dataclass(frozen=True)
+class AidrIdentity:
+    """What the application sees in ``request.state.aidr``."""
+
+    status: Literal["anonymous", "verified", "bypassed"]
+    result: VerificationResult | None = None
+    warnings: tuple[str, ...] = field(default_factory=tuple)
+
+    @property
+    def is_agent(self) -> bool:
+        return self.status == "verified"
+
+    @property
+    def aid(self) -> str | None:
+        return self.result.aid if self.result else None
+
+    @property
+    def organization(self) -> str | None:
+        return self.result.organization if self.result else None
+
+    @property
+    def org_domains(self) -> list[str]:
+        """Proven domains. Key trust decisions on these, not on the ``organization`` string."""
+        return list(self.result.org_domains) if self.result else []
+
+    @property
+    def agal(self) -> int:
+        return self.result.agal if self.result else 0
+
+    @property
+    def oal(self) -> int:
+        return self.result.oal if self.result else 0
+
+    @property
+    def kal(self) -> int:
+        return self.result.kal if self.result else 0
+
+    @property
+    def capabilities(self) -> list[str]:
+        return list(self.result.capabilities) if self.result else []
+
+    @property
+    def declared(self) -> dict[str, Any]:
+        """Self-asserted by the operator. Not checked by the registry."""
+        return dict(self.result.declared) if self.result else {}
+
+
+ANONYMOUS = AidrIdentity("anonymous")
+BYPASSED = AidrIdentity("bypassed")
+
+
+# ==============================================================================================
+# Paths
+# ==============================================================================================
+
+def normalise_path(raw_path: str) -> str | None:
+    """The path a bypass rule is judged against, or ``None`` if it is ambiguous.
+
+    Decoded once; a ``%`` still present after that (double encoding such as ``%252e``, a literal
+    ``%25``, or a malformed escape) is ambiguous, as are invalid UTF-8, control characters and
+    backslashes, which servers disagree about. Dot segments are resolved and repeated slashes
+    collapsed, so the result is the path the application's router will most plausibly act on.
+    The contract is shared with the edge worker: sdk/testdata/path-normalisation.json.
+    """
+    try:
+        decoded = unquote(raw_path, errors="strict")
+    except UnicodeDecodeError:
+        return None
+    if "%" in decoded or "\\" in decoded:
+        return None
+    if any(ord(c) < 0x20 or ord(c) == 0x7F for c in decoded):
+        return None
+    if not decoded.startswith("/"):
+        decoded = "/" + decoded
+    trailing = decoded.endswith("/") and decoded != "/"
+    resolved = posixpath.normpath(re.sub(r"/{2,}", "/", decoded))
+    if resolved.startswith("//"):
+        resolved = "/" + resolved.lstrip("/")
+    return resolved + "/" if trailing and resolved != "/" else resolved
+
+
+# ==============================================================================================
+# The middleware
+# ==============================================================================================
+
+_collected_nonce: contextvars.ContextVar[list[str] | None] = contextvars.ContextVar(
+    "aidr_collected_nonce", default=None)
+
+
+def _collect_nonce(nonce: str) -> bool:
+    """Handed to the verifier as its replay check: remember the nonce, decide nothing yet.
+
+    The core verifier consults its replay check only after the signature verifies, but before the
+    site's own floors, and it can only call a synchronous check. Deferring the claim to the end
+    means a request refused for any reason never occupies a nonce, and lets the claim be async
+    (a shared store).
+    """
+    sink = _collected_nonce.get()
+    if sink is not None:
+        sink.append(nonce)
+    return False
+
+
+class AidrMiddleware:
+    def __init__(self, app: Any, config: RelyingPartyConfig) -> None:
+        self.app = app
+        self.config = config
+        self.issuer = config.issuer.rstrip("/")
+        self.trust = config.trust or TrustStore(KeySet(keys={}), expected_issuer=self.issuer)
+        if self.trust.expected_issuer is None:
+            self.trust.expected_issuer = self.issuer
+        self.sync = (TrustSync(self.issuer, self.trust, http_client=config.http_client)
+                     if config.sync else None)
+        self.nonce_store = config.nonce_store or MemoryNonceStore()
+        self.bypass = [re.compile(pattern) for pattern in config.bypass]
+
+        audience = config.expected_audience or (config.public_origin.rstrip("/")
+                                                if config.public_origin else None)
+        self.policy = VerificationPolicy(
+            required_capabilities=list(config.required_capabilities),
+            max_signature_age_seconds=config.max_signature_age_seconds,
+            require_nonce=True,
+            expected_issuer=self.issuer,
+            expected_audience=audience,
+            max_upheld_abuse_reports=config.max_upheld_abuse_reports,
+            # Fail closed on unknown revocation. Not configurable here on purpose.
+            allow_unknown_revocation=False,
+        )
+        self.verifier = AgentVerifier(self.trust, policy=self.policy, nonce_seen=_collect_nonce)
+        self._started = False
+        self._start_lock = asyncio.Lock()
+
+    # -- lifecycle -------------------------------------------------------------------------------
+
+    async def startup(self) -> None:
+        async with self._start_lock:
+            if self._started:
+                return
+            self._started = True
+            synced = await self.sync.start(initial_timeout=self.config.initial_sync_timeout) \
+                if self.sync else bool(self.trust.key_set.keys)
+            health = self.trust.health()
+            logger.info(
+                "AIDR relying party: issuer=%s trust=%s keys=%d revocation_serial=%d exact=%s | "
+                "policy AgAL>=%d OAL>=%d KAL>=%d | bypass=%d rule(s) | nonce store=%s",
+                self.issuer, "ready" if synced else "NOT READY (agent requests get 503)",
+                health["keys"], health["revocation_serial"], health["revocation_exact"],
+                self.config.min_agal, self.config.min_oal, self.config.min_kal,
+                len(self.bypass), type(self.nonce_store).__name__)
+            if isinstance(self.nonce_store, MemoryNonceStore):
+                logger.info("AIDR: in-memory nonce store — correct for ONE worker process only; "
+                            "use RedisNonceStore when running more")
+
+    async def shutdown(self) -> None:
+        if self.sync:
+            await self.sync.stop()
+
+    def health(self) -> dict[str, Any]:
+        return self.sync.health() if self.sync else self.trust.health()
+
+    # -- ASGI --------------------------------------------------------------------------------------
+
+    async def __call__(self, scope: dict[str, Any], receive: Any, send: Any) -> None:
+        if scope["type"] == "lifespan":
+            await self.app(scope, self._lifespan_receive(receive), send)
+            return
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+        if not self._started:
+            await self.startup()
+
+        identity, refusal = await self._authenticate(scope)
+        if refusal is not None:
+            await self._refuse(send, *refusal)
+            return
+        scope.setdefault("state", {})["aidr"] = identity
+        await self.app(scope, receive, send)
+
+    def _lifespan_receive(self, receive: Any) -> Any:
+        async def wrapped() -> dict[str, Any]:
+            message = await receive()
+            if message["type"] == "lifespan.startup":
+                await self.startup()
+            elif message["type"] == "lifespan.shutdown":
+                await self.shutdown()
+            return message
+        return wrapped
+
+    # -- the decision ------------------------------------------------------------------------------
+
+    def _headers(self, scope: dict[str, Any]) -> dict[str, str]:
+        headers: dict[str, str] = {}
+        for raw_name, raw_value in scope.get("headers", []):
+            name = raw_name.decode("latin-1").lower()
+            value = raw_value.decode("latin-1")
+            # Repeated fields combine per RFC 9110 §5.3; a doubled credential then fails to parse
+            # instead of one copy being silently chosen.
+            headers[name] = f"{headers[name]}, {value}" if name in headers else value
+        return headers
+
+    def _raw_path(self, scope: dict[str, Any]) -> str:
+        raw = scope.get("raw_path")
+        return raw.decode("latin-1") if isinstance(raw, bytes) and raw else scope.get("path", "/")
+
+    def _is_bypassed(self, raw_path: str) -> bool:
+        if not self.bypass:
+            return False
+        path = normalise_path(raw_path)
+        return path is not None and any(rule.fullmatch(path) for rule in self.bypass)
+
+    def _effective_url(self, scope: dict[str, Any], headers: dict[str, str], raw_path: str) -> str:
+        query = scope.get("query_string", b"")
+        target = raw_path + (f"?{query.decode('latin-1')}" if query else "")
+        if self.config.public_origin:
+            origin = urlsplit(self.config.public_origin)
+            return effective_request_uri(origin.scheme, origin.netloc, target)
+        return effective_request_uri(scope.get("scheme", "https"), headers.get("host", ""), target)
+
+    async def _authenticate(
+        self, scope: dict[str, Any]
+    ) -> tuple[AidrIdentity, tuple[int, str, str] | None]:
+        headers = self._headers(scope)
+        raw_path = self._raw_path(scope)
+
+        if self._is_bypassed(raw_path):
+            return BYPASSED, None
+        if not any(name in headers for name in AGENT_HEADERS):
+            return ANONYMOUS, None
+        if self.sync is not None and not self.sync.ready:
+            return ANONYMOUS, (503, RegistryUnavailable.code,
+                               "agent verification is not ready: registry trust not yet loaded")
+
+        now = self.config.clock() if self.config.clock else datetime.now(timezone.utc)
+        sink: list[str] = []
+        token = _collected_nonce.set(sink)
+        try:
+            result = self.verifier.verify(
+                method=scope.get("method", "GET"),
+                url=self._effective_url(scope, headers, raw_path),
+                headers=headers, now=now)
+            self._check_floors(result)
+            if not sink:
+                raise MalformedToken("the signature carries no nonce")
+            ttl = self._nonce_ttl(result, now)
+            if not await self.nonce_store.claim(result.aid, sink[0], ttl):
+                raise ReplayDetected("signature nonce has already been used")
+        except AidrError as exc:
+            if isinstance(exc, UnknownIssuer) and exc.context.get("kid") and self.sync:
+                self.sync.request_key_refresh()
+            return ANONYMOUS, self._classify(exc, scope)
+        except Exception:  # noqa: BLE001 - never let an unexpected input become a pass or a 500
+            logger.exception("AIDR: unexpected error verifying a request; refusing it")
+            return ANONYMOUS, (401, MalformedToken.code, "request could not be verified")
+        finally:
+            _collected_nonce.reset(token)
+
+        if result.warnings:
+            logger.warning("AIDR: verified %s with warnings: %s", result.aid,
+                           "; ".join(result.warnings))
+        return AidrIdentity("verified", result, tuple(result.warnings)), None
+
+    def _check_floors(self, result: VerificationResult) -> None:
+        for axis, have, need in (("AgAL", result.agal, self.config.min_agal),
+                                 ("OAL", result.oal, self.config.min_oal),
+                                 ("KAL", result.kal, self.config.min_kal)):
+            if have < need:
+                raise AssuranceTooLow(f"agent {axis} {have} is below this site's required {need}",
+                                      aid=result.aid, axis=axis, have=have, required=need)
+
+    def _nonce_ttl(self, result: VerificationResult, now: datetime) -> int:
+        """Remember the nonce exactly as long as its signature could still be accepted."""
+        created = result.signature_created_at or now
+        remaining = (created - now).total_seconds() + self.config.max_signature_age_seconds
+        return max(1, math.ceil(remaining) + 1)
+
+    def _classify(self, exc: AidrError, scope: dict[str, Any]) -> tuple[int, str, str]:
+        if isinstance(exc, RegistryUnavailable):
+            status = 503
+        elif isinstance(exc, _FORBIDDEN):
+            status = 403
+        else:
+            status = 401
+        # Never log the Signature header or the credential: within the signature's lifetime a
+        # logged pair is a replayable request on any instance without a shared nonce store.
+        logger.info("AIDR: refused %s %s: %d %s", scope.get("method"), scope.get("path"),
+                    status, exc.code)
+        return status, exc.code, exc.message
+
+    async def _refuse(self, send: Any, status: int, code: str, reason: str) -> None:
+        body = json.dumps({"error": code, "reason": reason}).encode()
+        headers = [(b"content-type", b"application/json"), (b"cache-control", b"no-store"),
+                   (b"content-length", str(len(body)).encode())]
+        if status == 503:
+            headers.append((b"retry-after", b"30"))
+        await send({"type": "http.response.start", "status": status, "headers": headers})
+        await send({"type": "http.response.body", "body": body})
+
+
+__all__ = ["AidrMiddleware", "RelyingPartyConfig", "AidrIdentity", "ANONYMOUS", "BYPASSED",
+           "normalise_path"]