regent-httpsig 0.5.1__py3-none-any.whl → 0.7.0__py3-none-any.whl

regent_httpsig/sign.py

@@ -1,39 +1,63 @@
-"""Outbound RFC 9421 signing (Web Bot Auth) — give your agent a verifiable identity.
+"""Outbound RFC 9421 signing — give your agent (or your server) a verifiable identity.
 
-Sign every request your agent makes with an Ed25519 key whose public half you
-publish at ``{signature_agent}/.well-known/http-message-signatures-directory``.
-Verifiers that speak Web Bot Auth (Cloudflare, AWS WAF, Vercel, this library…)
-then see a *signed agent* instead of an anonymous bot.
+Three signers, one key format (a 32-byte Ed25519 seed, base64url):
 
-The ``Signature-Agent`` header is emitted in the LEGACY sf-string form
-(``"https://…"``) — the form OpenAI ships in production, accepted by every
-deployed verifier today; the draft -05 sf-dictionary form still has patchy
-support.
+- :class:`EgressSigner` signs as a **Web Bot Auth** agent: ``tag="web-bot-auth"``,
+  key published at ``{signature_agent}/.well-known/http-message-signatures-directory``.
+  Verifiers that speak Web Bot Auth (Cloudflare, AWS WAF, Vercel, this library…)
+  then see a *signed agent* instead of an anonymous bot. The ``Signature-Agent``
+  header is emitted in the LEGACY sf-string form (``"https://…"``) — the form
+  OpenAI ships in production, accepted by every deployed verifier today.
+- :meth:`EgressSigner.sign_aauth` signs as an **AAuth** agent (-11 §11.3.3): the
+  token rides in ``Signature-Key`` under the ``jwt`` scheme, the signature covers
+  ``@method @authority @path signature-key`` (plus ``content-digest`` and
+  ``content-type`` when there is a body), ``created`` only — no ``keyid``, no
+  ``tag``, no ``alg`` parameter (the key comes from the token's ``cnf.jwk``).
+- :class:`ServerSigner` signs as an AAuth **server** (-11 §11.3.2): a PS or AS
+  calling a resource's usage or revocation endpoint, under the ``jwks_uri``
+  scheme with ``id``, ``dwk`` and ``kid``.
 
 Unlike a service-level integration, this library FAILS LOUD: a bad seed raises
-at construction and a signing error raises from :meth:`EgressSigner.sign`.
-Wrap in try/except yourself if your egress path must never break on signing.
+at construction and a signing error raises from the ``sign`` methods. Wrap in
+try/except yourself if your egress path must never break on signing.
 """
 
 from __future__ import annotations
 
+import base64
+import hashlib
 import secrets
+import time
+from collections.abc import Mapping
 from datetime import datetime, timedelta
 from typing import Any
+from urllib.parse import urlsplit
 
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import ec
 from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+from cryptography.hazmat.primitives.asymmetric.utils import decode_dss_signature
 from http_message_signatures import (  # type: ignore[attr-defined]
     HTTPMessageSigner,
     HTTPSignatureKeyResolver,
 )
 
+from regent_httpsig.config import AAUTH_REQUIRED_COMPONENTS
 from regent_httpsig.jwk import b64url, b64url_decode, jwk_thumbprint
 from regent_httpsig.sfv import ED25519, Message
 
-__all__ = ["DIRECTORY_MEDIA_TYPE", "EgressSigner", "generate_seed"]
+__all__ = [
+    "DIRECTORY_MEDIA_TYPE",
+    "EgressSigner",
+    "ServerSigner",
+    "content_digest",
+    "generate_seed",
+    "sign_request",
+]
 
 DIRECTORY_MEDIA_TYPE = "application/http-message-signatures-directory+json"
 _DEFAULT_COVERED = ("@method", "@authority", "@path", "signature-agent")
+_BODY_COMPONENTS = ("content-digest", "content-type")
 
 
 def generate_seed() -> str:
@@ -41,6 +65,119 @@ def generate_seed() -> str:
     return b64url(secrets.token_bytes(32))
 
 
+def content_digest(body: bytes) -> str:
+    """RFC 9530 ``Content-Digest`` value for ``body`` (sha-256, sf-byte-sequence)."""
+    return "sha-256=:" + base64.b64encode(hashlib.sha256(body).digest()).decode() + ":"
+
+
+def _load_seed(seed: str) -> Ed25519PrivateKey:
+    raw = b64url_decode(seed)
+    if len(raw) != 32:
+        raise ValueError("seed must be 32 bytes (base64url-encoded)")
+    return Ed25519PrivateKey.from_private_bytes(raw)
+
+
+def _ed25519_jwk(key: Ed25519PrivateKey) -> dict[str, Any]:
+    return {"kty": "OKP", "crv": "Ed25519", "x": b64url(key.public_key().public_bytes_raw())}
+
+
+# ── RFC 9421 signature base, request side ─────────────────────────────────────
+
+
+def _field(headers: Mapping[str, str], name: str) -> str:
+    """RFC 9421 §2.1: the field value, whitespace trimmed, instances joined by ', '."""
+    values = [v.strip() for k, v in headers.items() if k.lower() == name]
+    if not values:
+        raise ValueError(f'covered header "{name}" is not in the message')
+    return ", ".join(values)
+
+
+def _derived(name: str, method: str, url: str) -> str:
+    parts = urlsplit(url)
+    if name == "@method":
+        return method.upper()
+    if name == "@authority":
+        host = (parts.hostname or "").lower()
+        port = parts.port
+        default = {"https": 443, "http": 80}.get(parts.scheme)
+        return host if port is None or port == default else f"{host}:{port}"
+    if name == "@path":
+        return parts.path or "/"
+    if name == "@query":
+        return "?" + parts.query
+    if name == "@target-uri":
+        return url
+    if name == "@scheme":
+        return parts.scheme
+    raise ValueError(f"unsupported derived component {name!r}")
+
+
+def _signature_base(method: str, url: str, headers: Mapping[str, str],
+                    covered: tuple[str, ...], params: str) -> str:
+    lines = []
+    for component in covered:
+        value = (_derived(component, method, url) if component.startswith("@")
+                 else _field(headers, component))
+        lines.append(f'"{component}": {value}')
+    lines.append(f'"@signature-params": {params}')
+    return "\n".join(lines)
+
+
+def _raw_sign(key: Any, data: bytes) -> bytes:
+    """RFC 9421 §3.3 signature bytes: Ed25519 raw, ECDSA as raw ``r || s``."""
+    if isinstance(key, Ed25519PrivateKey):
+        return key.sign(data)
+    if isinstance(key, ec.EllipticCurvePrivateKey):
+        r, s = decode_dss_signature(key.sign(data, ec.ECDSA(hashes.SHA256())))
+        size = (key.curve.key_size + 7) // 8
+        return r.to_bytes(size, "big") + s.to_bytes(size, "big")
+    raise TypeError("key must be an Ed25519 or EC private key")
+
+
+def sign_request(
+    key: Any,
+    method: str,
+    url: str,
+    headers: Mapping[str, str],
+    *,
+    covered: tuple[str, ...],
+    label: str = "sig",
+    created: int | None = None,
+    expires: int | None = None,
+) -> dict[str, str]:
+    """Sign ``(method, url, headers)`` the AAuth way: the covered components as
+    given, ``created`` (and ``expires`` if asked), no ``keyid``/``alg``/``tag``.
+    Returns ``headers`` plus ``Signature-Input`` and ``Signature``. Every
+    covered header must already be present (``Signature-Key``, ``Content-Digest``,
+    ``Content-Type``…) — the caller adds them first."""
+    created = int(created if created is not None else time.time())
+    inner = "(" + " ".join(f'"{c}"' for c in covered) + f");created={created}"
+    if expires is not None:
+        inner += f";expires={int(expires)}"
+    base = _signature_base(method, url, headers, covered, inner)
+    signature = base64.b64encode(_raw_sign(key, base.encode())).decode()
+    out = dict(headers)
+    out["Signature-Input"] = f"{label}={inner}"
+    out["Signature"] = f"{label}=:{signature}:"
+    return out
+
+
+def _covered_for(body: bytes | None, headers: Mapping[str, str]) -> tuple[str, ...]:
+    has_body = body is not None and len(body) > 0
+    return AAUTH_REQUIRED_COMPONENTS + (_BODY_COMPONENTS if has_body else ())
+
+
+def _with_body(headers: dict[str, str], body: bytes | None) -> dict[str, str]:
+    if body:
+        headers["Content-Digest"] = content_digest(body)
+        if not any(k.lower() == "content-type" for k in headers):
+            headers["Content-Type"] = "application/json"
+    return headers
+
+
+# ── Web Bot Auth / AAuth agent ────────────────────────────────────────────────
+
+
 class _Resolver(HTTPSignatureKeyResolver):
     def __init__(self, key: Ed25519PrivateKey):
         self._key = key
@@ -53,7 +190,8 @@ class _Resolver(HTTPSignatureKeyResolver):
 
 
 class EgressSigner:
-    """Sign outbound requests as a Web Bot Auth agent.
+    """Sign outbound requests as an agent — Web Bot Auth (:meth:`sign`) or
+    AAuth (:meth:`sign_aauth`) with the same Ed25519 key.
 
     Usage::
 
@@ -65,25 +203,22 @@ class EgressSigner:
     Publish ``signer.directory()`` as JSON at
     ``https://myagent.example/.well-known/http-message-signatures-directory``
     (or run ``regent-httpsig keygen`` to generate both the seed and the files).
+    For AAuth, register ``signer.public_jwk`` as the ``cnf.jwk`` of your agent
+    token and call :meth:`sign_aauth` with the token.
     """
 
     def __init__(self, *, seed: str, signature_agent: str, ttl_minutes: int = 5):
-        raw = b64url_decode(seed)
-        if len(raw) != 32:
-            raise ValueError("seed must be 32 bytes (base64url-encoded)")
-        self._key = Ed25519PrivateKey.from_private_bytes(raw)
+        self._key = _load_seed(seed)
         self.signature_agent = signature_agent
         self._ttl = ttl_minutes
-        self._jwk = {
-            "kty": "OKP",
-            "crv": "Ed25519",
-            "x": b64url(self._key.public_key().public_bytes_raw()),
-        }
+        self._jwk = _ed25519_jwk(self._key)
         self.keyid = jwk_thumbprint(self._jwk)
 
     @property
     def public_jwk(self) -> dict[str, Any]:
-        return dict(self._jwk)
+        """The public key as a JWK with a fully-specified ``alg`` (RFC 9864) —
+        what an AAuth token's ``cnf.jwk`` must carry under -11."""
+        return {**self._jwk, "alg": "Ed25519"}
 
     def directory(self) -> dict[str, Any]:
         """The JWKS document to serve at
@@ -101,7 +236,7 @@ class EgressSigner:
         covered: tuple[str, ...] = _DEFAULT_COVERED,
         label: str = "sig1",
     ) -> dict[str, str]:
-        """Return ``headers`` + ``Signature-Agent``/``Signature-Input``/``Signature``."""
+        """Web Bot Auth: ``headers`` + ``Signature-Agent``/``Signature-Input``/``Signature``."""
         out = dict(headers or {})
         out["Signature-Agent"] = f'"{self.signature_agent}"'  # legacy sf-string form
         message = Message(method.upper(), url, out)
@@ -119,3 +254,76 @@ class EgressSigner:
             covered_component_ids=covered,
         )
         return dict(message.headers)
+
+    def sign_aauth(
+        self,
+        method: str,
+        url: str,
+        headers: dict[str, str] | None = None,
+        *,
+        token: str,
+        body: bytes | None = None,
+        label: str = "sig",
+        created: int | None = None,
+    ) -> dict[str, str]:
+        """AAuth -11 §11.3.3: carry ``token`` (an agent, person or auth token
+        whose ``cnf.jwk`` is this signer's key) in ``Signature-Key`` under the
+        ``jwt`` scheme and sign ``@method @authority @path signature-key`` —
+        plus ``content-digest content-type`` when ``body`` is given, with
+        ``Content-Digest`` computed here. Send ``body`` exactly as passed."""
+        out = _with_body(dict(headers or {}), body)
+        out["Signature-Key"] = f'{label}=jwt;jwt="{token}"'
+        return sign_request(self._key, method, url, out,
+                            covered=_covered_for(body, out), label=label, created=created)
+
+
+# ── AAuth server (PS / AS / resource calling another server) ──────────────────
+
+
+class ServerSigner:
+    """Sign requests as an AAuth server under the ``jwks_uri`` scheme (-11
+    §11.3.2): ``Signature-Key: sig=jwks_uri;id="<server_id>";dwk="<dwk>";kid="…"``.
+    The recipient fetches ``{server_id}/.well-known/{dwk}``, follows its
+    ``jwks_uri`` and finds ``kid`` — serve :meth:`jwks` there.
+
+    ``dwk`` names the metadata document you publish: ``aauth-person.json`` for
+    a PS, ``aauth-access.json`` for an AS, ``aauth-resource.json`` for a
+    resource, ``aauth-agent.json`` for an agent provider.
+    """
+
+    def __init__(self, *, seed: str, server_id: str, dwk: str,
+                 kid: str | None = None, label: str = "sig") -> None:
+        self._key = _load_seed(seed)
+        self.server_id = server_id.rstrip("/")
+        self.dwk = dwk
+        self.label = label
+        self._jwk = _ed25519_jwk(self._key)
+        self.keyid = kid or jwk_thumbprint(self._jwk)
+
+    @property
+    def public_jwk(self) -> dict[str, Any]:
+        return {**self._jwk, "kid": self.keyid, "alg": "Ed25519", "use": "sig"}
+
+    def jwks(self) -> dict[str, Any]:
+        """The JWKS to serve at your metadata document's ``jwks_uri``."""
+        return {"keys": [self.public_jwk]}
+
+    def signature_key_header(self) -> str:
+        return (f'{self.label}=jwks_uri;id="{self.server_id}";'
+                f'dwk="{self.dwk}";kid="{self.keyid}"')
+
+    def sign(
+        self,
+        method: str,
+        url: str,
+        headers: dict[str, str] | None = None,
+        *,
+        body: bytes | None = None,
+        created: int | None = None,
+    ) -> dict[str, str]:
+        """Return ``headers`` + ``Signature-Key``/``Signature-Input``/``Signature``
+        (+ ``Content-Digest`` when ``body`` is given)."""
+        out = _with_body(dict(headers or {}), body)
+        out["Signature-Key"] = self.signature_key_header()
+        return sign_request(self._key, method, url, out,
+                            covered=_covered_for(body, out), label=self.label, created=created)

regent_httpsig/usage.py

@@ -36,7 +36,7 @@ from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
 from regent_httpsig.jwk import b64url_decode, jwk_thumbprint
 
 __all__ = ["UsageQueryError", "ResponseSigner", "build_usage_response",
-           "parse_usage_request", "make_usage_endpoint",
+           "parse_usage_request", "make_usage_endpoint", "make_revocation_endpoint",
            "validate_budget_grant"]
 
 _SCOPE_KEYS = ("sub", "tenant", "mission_s256")
@@ -109,19 +109,25 @@ async def build_usage_response(
 class ResponseSigner:
     """Signs a usage response per §The Signed Response: an Ed25519 HTTP Sig
     covering ``@status``, ``content-type``, ``content-digest``, bound to the
-    request via ``@authority``/``@path`` with the ``req`` parameter.
+    request via ``@authority``/``@path`` with the ``req`` parameter. The key is
+    identified the -11 way (§11.3.2): ``Signature-Key: sig=jwks_uri;
+    id="<server_id>";dwk="aauth-resource.json";kid="…"`` — the PS fetches
+    ``{server_id}/.well-known/aauth-resource.json``, follows ``jwks_uri`` and
+    finds ``kid`` there (serve :meth:`jwks`).
 
     Hand-built base string: response signing with request-bound components is
     beyond the request-oriented helper libraries, the component set is fixed by
     the draft, and the golden tests freeze every byte of it.
     """
 
-    def __init__(self, *, seed: str, jwks_url: str, label: str = "sig") -> None:
+    def __init__(self, *, seed: str, server_id: str, dwk: str = "aauth-resource.json",
+                 kid: str | None = None, label: str = "sig") -> None:
         raw = b64url_decode(seed)
         if len(raw) != 32:
             raise ValueError("seed must be 32 bytes (base64url-encoded)")
         self._key = Ed25519PrivateKey.from_private_bytes(raw)
-        self._jwks_url = jwks_url
+        self.server_id = server_id.rstrip("/")
+        self.dwk = dwk
         self._label = label
         self.public_jwk = {
             "kty": "OKP", "crv": "Ed25519",
@@ -129,7 +135,15 @@ class ResponseSigner:
                 self._key.public_key().public_bytes_raw()
             ).rstrip(b"=").decode(),
         }
-        self.keyid = jwk_thumbprint(self.public_jwk)
+        self.keyid = kid or jwk_thumbprint(self.public_jwk)
+
+    def jwks(self) -> dict[str, Any]:
+        """The JWKS to serve at the ``jwks_uri`` your metadata document names."""
+        return {"keys": [{**self.public_jwk, "kid": self.keyid, "alg": "Ed25519", "use": "sig"}]}
+
+    def signature_key_header(self) -> str:
+        return (f'{self._label}=jwks_uri;id="{self.server_id}";'
+                f'dwk="{self.dwk}";kid="{self.keyid}"')
 
     def sign(self, *, status: int, content_type: str, body: bytes,
              authority: str, path: str,
@@ -157,10 +171,41 @@ class ResponseSigner:
             "Content-Digest": digest,
             "Signature-Input": f"{self._label}={inner}",
             "Signature": f"{self._label}=:{sig}:",
-            "Signature-Key": f'{self._label}=jwks_uri; jwks_uri="{self._jwks_url}"',
+            "Signature-Key": self.signature_key_header(),
         }
 
 
+def _problem(status: int, error: str, detail: str,
+             headers: dict[str, str] | None = None) -> Any:
+    """-11 §11.9.2: ``application/problem+json`` with the REQUIRED ``error`` member.
+    Typed ``Any`` because starlette is an optional extra; it is a ``JSONResponse``."""
+    from starlette.responses import JSONResponse
+
+    return JSONResponse(
+        status_code=status, media_type="application/problem+json",
+        content={"error": error, "status": status, "title": error.replace("_", " "),
+                 "detail": detail},
+        headers=headers or {},
+    )
+
+
+async def _caller(authenticate: Callable[[Any], Awaitable[Any]],
+                  request: Any) -> tuple[str | None, Any]:
+    """Normalize what ``authenticate_ps`` returns: an issuer string, a
+    :class:`VerifiedSignature` (its ``agent``), a :class:`VerificationError`
+    (→ 401 + Signature-Error) or ``None`` (→ 401 invalid_signature)."""
+    from regent_httpsig.verify import VerificationError, VerifiedSignature
+
+    result = await authenticate(request)
+    if isinstance(result, VerifiedSignature):
+        return result.agent, None
+    if isinstance(result, str) and result:
+        return result, None
+    error = result if isinstance(result, VerificationError) else VerificationError(
+        "invalid_signature", "sign the request as a server (jwks_uri scheme)")
+    return None, _problem(401, error.code, error.detail, error.headers())
+
+
 def make_usage_endpoint(
     meter: Any,
     *,
@@ -171,19 +216,19 @@ def make_usage_endpoint(
 ) -> Callable[[Any], Awaitable[Any]]:
     """Build an ASGI-framework-agnostic handler: ``handler(request)`` returns a
     Starlette/FastAPI ``Response``. ``authenticate_ps(request)`` verifies the
-    calling person server's signature (jwks_uri scheme, per the AS token
-    endpoint rules) and returns its issuer identifier, or ``None`` to refuse —
-    the resource MUST only answer for values seen in tokens from that PS,
+    calling person server's signature (-11 §11.3.2, jwks_uri scheme) and
+    returns its identity — a ``VerifiedSignature`` from
+    :meth:`HttpsigVerifier.verify_server`, or the issuer string — or a
+    ``VerificationError``/``None`` to refuse with 401 + ``Signature-Error``.
+    The resource MUST only answer for values seen in tokens from that PS,
     which the ``iss``-keyed counters enforce structurally."""
     from starlette.responses import JSONResponse, Response
 
     async def handler(request: Any) -> Response:
-        iss = await authenticate_ps(request)
+        iss, refused = await _caller(authenticate_ps, request)
         if iss is None:
-            return JSONResponse(status_code=401, content={
-                "code": "PS_AUTH_REQUIRED",
-                "message": "Sign the query as a person server (jwks_uri scheme).",
-            })
+            refused_response: Response = refused
+            return refused_response
         try:
             payload = json.loads(await request.body() or b"{}")
             scope_key, scope_value, jkts = parse_usage_request(payload)
@@ -221,3 +266,63 @@ def validate_budget_grant(unit: str, decimals: int,
                     f"(declared in budget_units), got {decimals}")
             return
     raise ValueError(f"unit {unit!r} is not declared in budget_units")
+
+
+def make_revocation_endpoint(
+    meter: Any,
+    *,
+    authenticate_ps: Callable[[Any], Awaitable[Any]],
+    accepted_issuers: Callable[[str], bool] | None = None,
+    max_token_lifetime: float = 86400.0,
+    clock_skew: float = 60.0,
+) -> Callable[[Any], Awaitable[Any]]:
+    """The base protocol's revocation endpoint (-11 §11.12) for the budgets
+    meter: a signed ``POST {"jti", "exp"}``. The issuer is NOT a request
+    parameter — it is the identity verified on the caller's server signature
+    (§11.3.2), so a caller revokes only its own tokens. The pair ``(iss, jti)``
+    is recorded whether or not the token was ever seen here (a resource that
+    verifies statelessly still answers 200), and the answer is always an empty
+    ``200``: there is no "not found" (Appendix C.2.7).
+
+    Errors (§11.12.3, problem+json): ``invalid_request`` 400 for malformed
+    JSON or a missing/malformed ``jti``/``exp`` — including an ``exp`` further
+    ahead than ``max_token_lifetime`` + ``clock_skew``, the longest lifetime
+    this resource accepts; ``unsupported_iss`` 403 when ``accepted_issuers``
+    says no (default: any verified caller); a signature that does not verify
+    is 401 + ``Signature-Error``. ``rate_limited`` and ``server_error`` are
+    the application's to raise.
+
+    What revocation does to the meter is :meth:`InMemoryMeter.record_revocation`:
+    no new spend, in-flight requests complete, and the token's consumption
+    record is withheld until they have (AAuth #151); a later presentation of
+    the token is refused with ``revoked_jwt`` (§11.12.5)."""
+    from starlette.responses import Response
+
+    async def handler(request: Any) -> Response:
+        caller, refused = await _caller(authenticate_ps, request)
+        if caller is None:
+            refused_response: Response = refused
+            return refused_response
+        if accepted_issuers is not None and not accepted_issuers(caller):
+            unsupported: Response = _problem(
+                403, "unsupported_iss",
+                "this resource does not accept revocations from that issuer")
+            return unsupported
+        try:
+            payload = json.loads(await request.body() or b"")
+            if not isinstance(payload, dict):
+                raise ValueError("body must be a JSON object")
+            jti, exp = payload.get("jti"), payload.get("exp")
+            if not isinstance(jti, str) or not jti or len(jti) > 512:
+                raise ValueError("jti is REQUIRED (string)")
+            if isinstance(exp, bool) or not isinstance(exp, int | float):
+                raise ValueError("exp is REQUIRED (integer seconds)")
+            if exp > time.time() + max_token_lifetime + clock_skew:
+                raise ValueError("exp is further ahead than any token this resource accepts")
+        except (ValueError, json.JSONDecodeError) as exc:
+            invalid: Response = _problem(400, "invalid_request", str(exc)[:200])
+            return invalid
+        await meter.record_revocation(caller, jti, float(exp))
+        return Response(status_code=200)
+
+    return handler