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

regent_httpsig/__init__.py

@@ -9,28 +9,45 @@ from regent_httpsig.budget import (
     InMemoryMeter,
     InsufficientBudget,
     InvalidBudgetClaim,
+    TokenRevoked,
     UnitMismatch,
 )
 from regent_httpsig.config import HttpsigConfig
 from regent_httpsig.jwk import b64url, jwk_thumbprint, load_ed25519_jwk
 from regent_httpsig.netguard import NotPublicURL, assert_public_url
+from regent_httpsig.sfv import (
+    build_aauth_budget_header,
+    build_aauth_requirement,
+    build_person_token_requirement,
+    parse_signature_agent,
+    parse_signature_input,
+    parse_signature_key,
+)
+from regent_httpsig.sign import (
+    DIRECTORY_MEDIA_TYPE,
+    EgressSigner,
+    ServerSigner,
+    content_digest,
+    generate_seed,
+    sign_request,
+)
 from regent_httpsig.usage import (
     ResponseSigner,
     UsageQueryError,
     build_usage_response,
+    make_revocation_endpoint,
     make_usage_endpoint,
     parse_usage_request,
     validate_budget_grant,
 )
-from regent_httpsig.sfv import (
-    build_aauth_budget_header,
-    build_aauth_requirement,
-    parse_signature_agent,
+from regent_httpsig.verify import (
+    WBA_TAG,
+    HttpsigVerifier,
+    VerificationError,
+    VerifiedSignature,
 )
-from regent_httpsig.sign import DIRECTORY_MEDIA_TYPE, EgressSigner, generate_seed
-from regent_httpsig.verify import WBA_TAG, HttpsigVerifier, VerifiedSignature
 
-__version__ = "0.3.0"
+__version__ = "0.7.0"
 
 __all__ = [
     "DIRECTORY_MEDIA_TYPE",
@@ -40,10 +57,18 @@ __all__ = [
     "HttpsigVerifier",
     "InMemoryMeter",
     "InsufficientBudget",
+    "TokenRevoked",
     "InvalidBudgetClaim",
     "NotPublicURL",
     "UnitMismatch",
+    "VerificationError",
     "VerifiedSignature",
+    "ServerSigner",
+    "content_digest",
+    "sign_request",
+    "build_person_token_requirement",
+    "parse_signature_input",
+    "parse_signature_key",
     "WBA_TAG",
     "__version__",
     "assert_public_url",
@@ -51,6 +76,7 @@ __all__ = [
     "ResponseSigner",
     "UsageQueryError",
     "build_usage_response",
+    "make_revocation_endpoint",
     "make_usage_endpoint",
     "parse_usage_request",
     "validate_budget_grant",

regent_httpsig/budget.py

@@ -33,8 +33,8 @@ import asyncio
 import itertools
 import time
 from collections.abc import Mapping
-from datetime import UTC, datetime, timedelta
 from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
 from typing import Any
 
 __all__ = [
@@ -43,6 +43,7 @@ __all__ = [
     "InsufficientBudget",
     "InvalidBudgetClaim",
     "Reservation",
+    "TokenRevoked",
     "UnitMismatch",
 ]
 
@@ -112,6 +113,17 @@ class InsufficientBudget:
     exhausted: bool
 
 
+@dataclass(frozen=True)
+class TokenRevoked:
+    """Refusal: the presented token was revoked (base protocol §Token
+    Revocation, budgets §Token Scope). The budget ended with the token — no
+    new spend — while requests already in flight complete. ``drained`` says
+    whether those have all settled: only then may the resource state the
+    token's consumption record, which is then FINAL (AAuth issue #151)."""
+
+    drained: bool
+
+
 @dataclass
 class _Pool:
     unit: str
@@ -120,6 +132,7 @@ class _Pool:
     consumed: dict[str, int] = field(default_factory=dict)  # jti -> total committed
     jkt_of: dict[str, str] = field(default_factory=dict)  # jti -> presenting key thumbprint
     reservations: dict[int, tuple[str, int, float]] = field(default_factory=dict)
+    revoked: dict[str, float] = field(default_factory=dict)  # jti -> wall time of revocation
     last_activity: float = 0.0
 
 
@@ -178,6 +191,11 @@ class InMemoryMeter:
                  retention_seconds: float = 7200.0,
                  usage_key_retention: float = 86400.0) -> None:
         self._pools: dict[MeterKey, _Pool] = {}
+        self._jti_index: dict[tuple[str, str], MeterKey] = {}  # (iss, jti) -> ledger key
+        # -11 §11.12.1: revocations keyed by (iss, jti), kept until the token's
+        # own exp plus clock skew — whether or not the token was ever seen here.
+        self._revocations: dict[tuple[str, str], float] = {}  # (iss, jti) -> exp (wall)
+        self._revocation_skew = 60.0
         self._lock = asyncio.Lock()
         self._rids = itertools.count(1)
         self._reservation_ttl = reservation_ttl
@@ -190,7 +208,8 @@ class InMemoryMeter:
         # request" — so a key in continuous use is never pruned.
         self._usage_key_retention = usage_key_retention
         self._scope_usage: dict[tuple[str, str], _ScopeCounters] = {}  # (iss, sub)
-        self._key_usage: dict[tuple[str, str], tuple[int, float]] = {}  # (iss, jkt) -> (total, last_wall)
+        # (iss, jkt) -> (total, last_wall)
+        self._key_usage: dict[tuple[str, str], tuple[int, float]] = {}
         self._metering_unit: tuple[str, int] | None = None
 
     # ── internals (call under lock) ──────────────────────────────────────────
@@ -213,9 +232,16 @@ class InMemoryMeter:
         if (not pool.grants and not pool.reservations
                 and now - pool.last_activity > self._retention):
             del self._pools[key]
+            for pair in [p for p, k in self._jti_index.items() if k == key]:
+                del self._jti_index[pair]
             return None
         return pool
 
+    @staticmethod
+    def _drained(pool: _Pool, jti: str) -> bool:
+        """No request is in flight on this token any more."""
+        return not any(j == jti for j, _, _ in pool.reservations.values())
+
     @staticmethod
     def _remaining(pool: _Pool, jti: str) -> int:
         """The presented token's balance: its grant minus what was committed
@@ -251,14 +277,17 @@ class InMemoryMeter:
             pool.last_activity = now
             if jkt:
                 pool.jkt_of.setdefault(jti, jkt)
-            if jti not in pool.grants and wall_delta > 0:
+            self._jti_index.setdefault((key[0], jti), key)
+            if jti not in pool.grants and wall_delta > 0 and jti not in pool.revoked:
                 pool.grants[jti] = (claim.amount, now + wall_delta)
 
     async def reserve(self, key: MeterKey, jti: str,
-                      max_cost: int) -> Reservation | InsufficientBudget:
+                      max_cost: int) -> Reservation | InsufficientBudget | TokenRevoked:
         async with self._lock:
             now = time.monotonic()
             pool = self._purge(key, now)
+            if pool is not None and jti in pool.revoked:
+                return TokenRevoked(drained=self._drained(pool, jti))
             if pool is None or jti not in pool.grants:
                 return InsufficientBudget(remaining=0, exhausted=True)
             remaining = self._remaining(pool, jti)
@@ -301,6 +330,73 @@ class InMemoryMeter:
             pool = self._purge(key, time.monotonic())
             return 0 if pool is None else self._remaining(pool, jti)
 
+    def _prune_revocations(self, wall: float) -> None:
+        for pair, exp in list(self._revocations.items()):
+            if wall > exp + self._revocation_skew:
+                del self._revocations[pair]
+
+    def _withdraw(self, iss: str, jti: str) -> bool:
+        """Withdraw a known token's grant (call under lock). ``False`` when the
+        pair was never granted here — the revocation is still on record."""
+        key = self._jti_index.get((iss, jti))
+        if key is None:
+            return False
+        pool = self._purge(key, time.monotonic())
+        if pool is None:
+            return False
+        pool.revoked.setdefault(jti, time.time())
+        pool.grants.pop(jti, None)
+        pool.last_activity = time.monotonic()
+        return True
+
+    async def record_revocation(self, iss: str, jti: str, exp: float) -> bool:
+        """Record that ``iss`` revoked ``jti`` (-11 §11.12.1): remembered until
+        ``exp`` plus clock skew whether or not the token was ever presented
+        here, so a later presentation is answered ``revoked_jwt``. If the token
+        holds a grant, it is withdrawn — no new request can reserve against it;
+        requests already in flight complete and are committed as usual.
+        Returns whether the token was known here. Idempotent."""
+        async with self._lock:
+            wall = time.time()
+            self._prune_revocations(wall)
+            if wall <= float(exp) + self._revocation_skew:  # §11.12.1: past exp + skew is droppable
+                self._revocations[(iss, jti)] = float(exp)
+            return self._withdraw(iss, jti)
+
+    async def is_revoked(self, iss: str, jti: str) -> bool:
+        """Whether ``(iss, jti)`` is on record as revoked — the hook for
+        :class:`HttpsigVerifier` (``is_revoked=meter.is_revoked``)."""
+        async with self._lock:
+            self._prune_revocations(time.time())
+            return (iss, jti) in self._revocations
+
+    async def revoke(self, iss: str, jti: str) -> bool:
+        """Revoke a token this meter holds a grant for, by ``(iss, jti)``. Like
+        :meth:`record_revocation` with the grant's own ``exp``; ``False`` when
+        the pair is unknown here (nothing is recorded then — use
+        :meth:`record_revocation` when the issuer told you the exp)."""
+        async with self._lock:
+            key = self._jti_index.get((iss, jti))
+            if key is None:
+                return False
+            pool = self._purge(key, time.monotonic())
+            if pool is None:
+                return False
+            grant = pool.grants.get(jti)
+            wall = time.time()
+            exp = wall + max(0.0, grant[1] - time.monotonic()) if grant else wall
+            self._revocations[(iss, jti)] = max(self._revocations.get((iss, jti), 0.0), exp)
+            return self._withdraw(iss, jti)
+
+    async def revocation_state(self, key: MeterKey, jti: str) -> TokenRevoked | None:
+        """``TokenRevoked`` (with its drain state) if the token was revoked
+        here, else ``None``."""
+        async with self._lock:
+            pool = self._purge(key, time.monotonic())
+            if pool is None or jti not in pool.revoked:
+                return None
+            return TokenRevoked(drained=self._drained(pool, jti))
+
     def _record_usage(self, key: MeterKey, pool: _Pool, jti: str,
                       amount: int) -> None:
         """Post a committed cost to the usage counters (call under lock).
@@ -351,6 +447,10 @@ class InMemoryMeter:
             pool = self._purge(key, time.monotonic())
             if pool is None:
                 return None
+            if jti in pool.revoked and not self._drained(pool, jti):
+                # §Token Scope + AAuth #151: a revoked token's record is FINAL,
+                # so it is stated only once nothing is in flight on it.
+                return None
             total = pool.consumed.get(jti, 0)
             return {"jti": jti, "consumed": total} if total > 0 else None
 

regent_httpsig/config.py

@@ -5,22 +5,35 @@ from __future__ import annotations
 from collections.abc import Mapping
 from dataclasses import dataclass, field
 
-__all__ = ["HttpsigConfig"]
+__all__ = ["AAUTH_REQUIRED_COMPONENTS", "HttpsigConfig"]
+
+# AAuth -11 §11.3.3.1: what every agent signature MUST cover. A request with a
+# body to a PS/AS/revocation endpoint additionally covers content-digest and
+# content-type; the verifier adds those when it is handed the body.
+AAUTH_REQUIRED_COMPONENTS: tuple[str, ...] = ("@method", "@authority", "@path", "signature-key")
 
 
 @dataclass(frozen=True)
 class HttpsigConfig:
     """Configuration for :class:`regent_httpsig.HttpsigVerifier`.
 
-    Defaults are production-safe: https-only directory fetching over public IPs,
-    bounded cache, 25-hour max signature age (Web Bot Auth signatures carry
-    ``created``/``expires``; 25h tolerates a day of clock drift)."""
+    Defaults are production-safe and, on the AAuth path, follow -11 as
+    published: a 60-second ``created`` window, fully-specified algorithms only,
+    no clock-skew tolerance on ``exp``. Web Bot Auth keeps its own, looser age
+    rule (``max_age_hours``) because that profile defines no window."""
 
     # Origins/issuers you additionally mark as trusted (``VerifiedSignature.trusted``).
     # Verification itself never depends on this — it only annotates the result.
     trusted_agents: frozenset[str] = field(default_factory=frozenset)
-    # Reject signatures created earlier than this many hours ago.
+    # Web Bot Auth only: reject signatures created earlier than this many hours ago.
     max_age_hours: int = 25
+    # AAuth -11 §11.3.4 step 3: the signature validity window for `created`, in
+    # seconds. Older than the window → invalid_signature; further ahead of our
+    # clock → clock_skew. The same window bounds a token's `iat` (§11.5.2).
+    # Advertise a different value in resource metadata as `signature_window`.
+    signature_window_seconds: int = 60
+    # AAuth -11 §11.3.3.1: covered components every agent signature must include.
+    required_components: tuple[str, ...] = AAUTH_REQUIRED_COMPONENTS
     # Key-directory cache TTL (seconds); failures are cached for negative_cache_ttl.
     cache_ttl: float = 600.0
     negative_cache_ttl: float = 120.0
@@ -31,17 +44,19 @@ class HttpsigConfig:
     # Hosts exempt from the https-only + public-IP SSRF guard (local dev only —
     # e.g. frozenset({"localhost"})). Leave empty in production.
     insecure_hosts: frozenset[str] = field(default_factory=frozenset)
-    # AAuth -11 (editor's copy): JOSE algs must be fully-specified per RFC 9864 —
-    # implementations MUST NOT accept the polymorphic "EdDSA". True enforces that;
-    # the False default keeps accepting "EdDSA" while the -10 ecosystem migrates.
-    require_fully_specified_algs: bool = False
+    # AAuth -11 §11.3.1: JOSE algs must be fully-specified (RFC 9864); the
+    # polymorphic "EdDSA" and keys without `alg` are refused. False is the
+    # pre-cut-over behaviour kept only for private test rigs; -11 forbids it.
+    require_fully_specified_algs: bool = True
     # This service's public URL (e.g. "https://api.example"). Required to accept
-    # AAuth person tokens — their `aud` must name this resource. None disables
-    # the person-token path entirely.
+    # AAuth person tokens and auth tokens — their `aud` must name this resource.
+    # None disables both paths.
     resource_url: str | None = None
-    # AAuth auth tokens (typ "aa-auth+jwt" — the carrier of budget envelopes):
-    # issuer → JWKS URL for each Person Server this resource accepts auth tokens
-    # from. A resource has an established relationship with its PS, so the key
-    # location is pinned by configuration rather than discovered open-world.
-    # Empty (the default) disables the auth-token path entirely.
+    # AAuth auth tokens (typ "aa-auth+jwt" — the carrier of budget envelopes) and
+    # signed server requests (the jwks_uri scheme, §11.3.2): issuer → JWKS URL
+    # for each Person Server / Access Server this resource accepts. A resource has
+    # an established relationship with its PS, so trust is pinned by
+    # configuration. The value may be "" to discover the JWKS through the
+    # issuer's metadata document ({id}/.well-known/{dwk}) instead of a fixed URL.
+    # Empty (the default) disables the auth-token and server paths entirely.
     trusted_ps: Mapping[str, str] = field(default_factory=dict)