regent-httpsig 0.5.0__tar.gz → 0.6.0__tar.gz

{regent_httpsig-0.5.0 → regent_httpsig-0.6.0}/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 0.6.0
+
+**Budgets — revocation reaches the meter** (base protocol §Token Revocation,
+budgets §Token Scope; drain rule per AAuth issue #151, raised from our
+production and not yet in the editor's copy):
+
+- **`InMemoryMeter.revoke(iss, jti)`**: withdraws the grant so no new request
+  can reserve against the token; requests already in flight complete and are
+  committed as usual. Idempotent; `False` for an unknown `(iss, jti)`.
+- **`TokenRevoked(drained)`**: what `reserve()` returns for a revoked token.
+  `drained` is true once nothing is in flight on it.
+- **Final record only after the drain**: `consumed_record()` withholds a
+  revoked token's record while requests are in flight, so a record the
+  resource issues after the revocation is the token's final figure and the
+  issuer can settle on it (the ordering is checkable by `iat`).
+- **`make_revocation_endpoint(meter, authenticate_ps=…)`**: the base
+  protocol's endpoint — signed `POST {"iss","jti"}`, `200` empty on success or
+  already-invalid, `404` unknown, `403` when the caller is not the issuer.
+- **`BudgetMiddleware`** answers a revoked token with the plain
+  `requirement=auth-token` challenge (`code: AUTH_TOKEN_REVOKED`, no
+  `AAuth-Budget`), the resource token carrying the final record once drained.
+- `revocation_state(key, jti)` for resources that learn of revocation out of
+  band (e.g. from their own registry) and want the same challenge.
+
+## 0.5.1
+
+**Budgets — the final-record challenge for expired auth tokens** (draft
+§Budget Exhaustion "auth token expired" + §Settlement). The final/snapshot
+settlement rule needs a moment at which the resource *states* a token's final
+figure — and that moment is the challenge to an expired token. A verifier that
+refuses to look at an expired token can never build it, so the issuer never
+sees a final record and accounts every allocation as fully consumed forever.
+
+- `BudgetMiddleware` answers a genuine-but-expired `aa-auth+jwt` (issuer
+  signature and proof of possession verified, request signature fresh) with
+  `401` + plain `AAuth-Requirement: requirement=auth-token;resource-token=…`
+  (no `reason` — the budget didn't run out, the token did) and `code:
+  AUTH_TOKEN_EXPIRED`. The resource token carries the presented token's
+  `{jti, consumed}`; no `AAuth-Budget` header. Nothing is served or metered.
+- `HttpsigVerifier.verify(..., allow_expired_auth_token=True)` — **opt-in,
+  default False**: returns the token with `VerifiedSignature.expired=True`
+  for up to `EXPIRED_AUTH_TOKEN_GRACE` (2h, the meter's retention) after
+  `exp`. Access decisions through `verify()`/`require_signature` are
+  unchanged: an expired token is still `None` there, and the middleware never
+  caches an expired result for downstream dependencies.
+- `build_aauth_requirement(reason=None, …)` emits the reason-less challenge.
+
 ## 0.5.0
 
 **AAuth Budgets — per-token cap, one consumption record** (draft-hardt-aauth-budgets

{regent_httpsig-0.5.0 → regent_httpsig-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: regent-httpsig
-Version: 0.5.0
+Version: 0.6.0
 Summary: Verify and sign AI agent HTTP traffic in Python — RFC 9421 HTTP Message Signatures: Web Bot Auth (what OpenAI ships) and AAuth.
 Project-URL: Homepage, https://github.com/regent-protocol/regent-httpsig
 Project-URL: Repository, https://github.com/regent-protocol/regent-httpsig
@@ -174,6 +174,14 @@ production on [get4agent.com](https://get4agent.com).
 
 - `insufficient-budget` refusals carry **`required`** — the refused request's
   maximum cost — so the agent lowers its bound and retries instead of guessing.
+- **Revocation**: `make_revocation_endpoint(meter, authenticate_ps=…)` is the
+  base protocol's endpoint; a revoked token stops spending at once, in-flight
+  requests complete, and its final record rides on the next challenge.
+- An **expired** auth token gets the base protocol's plain challenge with a
+  resource token carrying that token's **final** consumption record — the
+  figure its issuer needs to settle the allocation (a record stated at or
+  after `exp` is final; one on a live token is a snapshot and releases
+  nothing).
 - **Streaming** responses run in the draft's cost-omitted mode: `reserved` in
   the header, commit when the stream ends (set `request.state.budget_cost`
   mid-stream if you learn the actual), and the agent recovers the exact cost

{regent_httpsig-0.5.0 → regent_httpsig-0.6.0}/README.md

@@ -144,6 +144,14 @@ production on [get4agent.com](https://get4agent.com).
 
 - `insufficient-budget` refusals carry **`required`** — the refused request's
   maximum cost — so the agent lowers its bound and retries instead of guessing.
+- **Revocation**: `make_revocation_endpoint(meter, authenticate_ps=…)` is the
+  base protocol's endpoint; a revoked token stops spending at once, in-flight
+  requests complete, and its final record rides on the next challenge.
+- An **expired** auth token gets the base protocol's plain challenge with a
+  resource token carrying that token's **final** consumption record — the
+  figure its issuer needs to settle the allocation (a record stated at or
+  after `exp` is final; one on a live token is a snapshot and releases
+  nothing).
 - **Streaming** responses run in the draft's cost-omitted mode: `reserved` in
   the header, commit when the stream ends (set `request.state.budget_cost`
   mid-stream if you learn the actual), and the agent recovers the exact cost

{regent_httpsig-0.5.0 → regent_httpsig-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "regent-httpsig"
-version = "0.5.0"
+version = "0.6.0"
 description = "Verify and sign AI agent HTTP traffic in Python — RFC 9421 HTTP Message Signatures: Web Bot Auth (what OpenAI ships) and AAuth."
 readme = "README.md"
 license = "Apache-2.0"

{regent_httpsig-0.5.0 → regent_httpsig-0.6.0}/src/regent_httpsig/__init__.py

@@ -9,28 +9,30 @@ 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,
+    parse_signature_agent,
+)
+from regent_httpsig.sign import DIRECTORY_MEDIA_TYPE, EgressSigner, generate_seed
 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.sign import DIRECTORY_MEDIA_TYPE, EgressSigner, generate_seed
 from regent_httpsig.verify import WBA_TAG, HttpsigVerifier, VerifiedSignature
 
-__version__ = "0.3.0"
+__version__ = "0.6.0"
 
 __all__ = [
     "DIRECTORY_MEDIA_TYPE",
@@ -40,6 +42,7 @@ __all__ = [
     "HttpsigVerifier",
     "InMemoryMeter",
     "InsufficientBudget",
+    "TokenRevoked",
     "InvalidBudgetClaim",
     "NotPublicURL",
     "UnitMismatch",
@@ -51,6 +54,7 @@ __all__ = [
     "ResponseSigner",
     "UsageQueryError",
     "build_usage_response",
+    "make_revocation_endpoint",
     "make_usage_endpoint",
     "parse_usage_request",
     "validate_budget_grant",

{regent_httpsig-0.5.0 → regent_httpsig-0.6.0}/src/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,7 @@ 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
         self._lock = asyncio.Lock()
         self._rids = itertools.count(1)
         self._reservation_ttl = reservation_ttl
@@ -190,7 +204,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 +228,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 +273,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 +326,33 @@ class InMemoryMeter:
             pool = self._purge(key, time.monotonic())
             return 0 if pool is None else self._remaining(pool, jti)
 
+    async def revoke(self, iss: str, jti: str) -> bool:
+        """Revoke an auth token by ``(iss, jti)`` — the base protocol's
+        revocation identifier. The grant is withdrawn so no new request can
+        reserve against it; requests already in flight complete and are
+        committed as usual. ``False`` when the pair is unknown here (the
+        endpoint answers 404). Idempotent."""
+        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
+            pool.revoked.setdefault(jti, time.time())
+            pool.grants.pop(jti, None)
+            pool.last_activity = time.monotonic()
+            return True
+
+    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 +403,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-0.5.0 → regent_httpsig-0.6.0}/src/regent_httpsig/fastapi.py

@@ -41,6 +41,7 @@ from regent_httpsig.budget import (
     InvalidBudgetClaim,
     MeterKey,
     Reservation,
+    TokenRevoked,
     UnitMismatch,
 )
 from regent_httpsig.sfv import build_aauth_budget_header, build_aauth_requirement
@@ -191,6 +192,13 @@ class BudgetMiddleware(BaseHTTPMiddleware):
             return await call_next(request)
 
         sig = await self._verified(request)
+        if sig is not None and sig.expired:
+            # §Budget Exhaustion, "auth token expired": the base protocol's plain
+            # 401 — and the resource token we attach carries the presented
+            # token's FINAL consumption record (stated at/after its exp), which
+            # is what lets its issuer settle the allocation exactly. Without
+            # this challenge an issuer never sees a final figure at all.
+            return await self._expired_challenge(sig)
         envelope: BudgetClaim | None = None
         if sig is not None:
             try:
@@ -222,6 +230,11 @@ class BudgetMiddleware(BaseHTTPMiddleware):
                                  remaining=0, key=key)
 
         outcome = await self._meter.reserve(key, jti, int(max_cost))
+        if isinstance(outcome, TokenRevoked):
+            # §Token Scope: the budget ended with the token. The challenge is
+            # the base protocol's plain one; the resource token on it carries
+            # the token's FINAL record once nothing is in flight (AAuth #151).
+            return await self._revoked_challenge(key, jti, outcome.drained)
         if isinstance(outcome, InsufficientBudget):
             reason = "budget-exhausted" if outcome.exhausted else "insufficient-budget"
             return await self._refusal_with_token(
@@ -307,11 +320,63 @@ class BudgetMiddleware(BaseHTTPMiddleware):
         result = None
         if "signature" in request.headers:
             result = await self._verifier.verify(
-                request.method, _public_url(request), dict(request.headers)
+                request.method, _public_url(request), dict(request.headers),
+                allow_expired_auth_token=True,
             )
-        request.state.regent_httpsig_result = result
+        # An expired token is never handed to the app: the middleware answers
+        # it with the final-record challenge and nothing downstream runs. The
+        # per-request cache still must not carry it — a later dependency
+        # reading the cache would otherwise see a token that is not valid.
+        request.state.regent_httpsig_result = (
+            None if result is not None and result.expired else result)
         return result
 
+    async def _revoked_challenge(self, key: MeterKey, jti: str, drained: bool) -> Response:
+        token: str | None = None
+        if self._resource_token is not None:
+            try:
+                record = await self._meter.consumed_record(key, jti) if drained else None
+                token = await _maybe_await(self._resource_token(key, record))
+            except Exception:  # noqa: BLE001 — the challenge must not fail on the extras
+                logger.warning("resource_token_provider failed", exc_info=True)
+        return JSONResponse(
+            status_code=401,
+            content={
+                "code": "AUTH_TOKEN_REVOKED",
+                "message": "This auth token was revoked by its issuer. Take the resource "
+                           "token in AAuth-Requirement to your PS for a fresh one."
+                           + ("" if drained else " Its final consumption record follows once "
+                              "in-flight requests settle."),
+            },
+            headers={"AAuth-Requirement": build_aauth_requirement(
+                reason=None, resource_token=token)},
+        )
+
+    async def _expired_challenge(self, sig: VerifiedSignature) -> Response:
+        jti = str(sig.claims.get("jti") or "")
+        key: MeterKey = (
+            str(sig.claims.get("iss", "")),
+            str(sig.claims.get("sub", "")),
+            str(sig.claims.get("aud", "")),
+        )
+        token: str | None = None
+        if self._resource_token is not None and jti:
+            try:
+                record = await self._meter.consumed_record(key, jti)
+                token = await _maybe_await(self._resource_token(key, record))
+            except Exception:  # noqa: BLE001 — the challenge must not fail on the extras
+                logger.warning("resource_token_provider failed", exc_info=True)
+        return JSONResponse(
+            status_code=401,
+            content={
+                "code": "AUTH_TOKEN_EXPIRED",
+                "message": "The auth token has expired. Take the resource token in "
+                           "AAuth-Requirement to your PS for a fresh one.",
+            },
+            headers={"AAuth-Requirement": build_aauth_requirement(
+                reason=None, resource_token=token)},
+        )
+
     async def _refusal_with_token(
         self, *, reason: str, envelope: BudgetClaim,
         remaining: int, key: MeterKey, jti: str,

{regent_httpsig-0.5.0 → regent_httpsig-0.6.0}/src/regent_httpsig/sfv.py

@@ -176,13 +176,18 @@ def build_aauth_budget_header(
     return ", ".join(members)
 
 
-def build_aauth_requirement(*, reason: str, resource_token: str | None = None) -> str:
-    """Serialize ``AAuth-Requirement`` for a budget refusal:
+def build_aauth_requirement(*, reason: str | None,
+                            resource_token: str | None = None) -> str:
+    """Serialize ``AAuth-Requirement`` for a budget challenge:
     ``requirement=auth-token;resource-token="eyJ…";reason=insufficient-budget``.
-    ``reason`` is an sf-token (``insufficient-budget`` | ``budget-exhausted``);
-    the resource token (when the resource issues one) rides as an sf-string."""
+    ``reason`` is an sf-token (``insufficient-budget`` | ``budget-exhausted``)
+    for an exhaustion refusal, or ``None`` for the base protocol's plain
+    challenge (an EXPIRED auth token — the budget did not run out, the token
+    did); the resource token (when the resource issues one) rides as an
+    sf-string."""
     out = "requirement=auth-token"
     if resource_token:
         out += f";resource-token={_sf_string(resource_token)}"
-    out += f";reason={reason}"
+    if reason:
+        out += f";reason={reason}"
     return out

{regent_httpsig-0.5.0 → regent_httpsig-0.6.0}/src/regent_httpsig/usage.py

@@ -221,3 +221,51 @@ 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[str | None]],
+) -> Callable[[Any], Awaitable[Any]]:
+    """The base protocol's revocation endpoint (§Token Revocation) for the
+    budgets meter: a signed ``POST`` identifying an auth token by
+    ``{"iss", "jti"}`` — both REQUIRED, keyed together because a jti is unique
+    only within its issuer. ``200`` when the token was revoked or is already
+    invalid here, ``404`` when the pair is not recognized. The body is
+    deliberately empty on success: the response must not vary with what the
+    recipient holds.
+
+    ``authenticate_ps`` is the same pinned-PS check the usage endpoint uses.
+    The issuer named in the body must be the caller: a PS revokes tokens it
+    issued, never another issuer's. What revocation does to the meter is in
+    :meth:`InMemoryMeter.revoke` — no new spend, in-flight requests complete,
+    and the token's consumption record is withheld until they have (AAuth
+    issue #151: a record issued after the revocation is then final)."""
+    from starlette.responses import JSONResponse, Response
+
+    async def handler(request: Any) -> Response:
+        caller = await authenticate_ps(request)
+        if caller is None:
+            return JSONResponse(status_code=401, content={
+                "code": "PS_AUTH_REQUIRED",
+                "message": "Sign the revocation as the person server that issued the token.",
+            })
+        try:
+            payload = json.loads(await request.body() or b"{}")
+            iss, jti = payload.get("iss"), payload.get("jti")
+            if not isinstance(iss, str) or not isinstance(jti, str) or not iss or not jti:
+                raise ValueError("iss and jti are REQUIRED strings")
+        except (ValueError, json.JSONDecodeError) as exc:
+            return JSONResponse(status_code=400, content={
+                "code": "INVALID_REVOCATION", "message": str(exc)})
+        if iss.rstrip("/") != caller.rstrip("/"):
+            return JSONResponse(status_code=403, content={
+                "code": "NOT_YOUR_TOKEN",
+                "message": "A person server may revoke only tokens it issued."})
+        if not await meter.revoke(iss, jti):
+            return JSONResponse(status_code=404, content={
+                "code": "TOKEN_UNKNOWN", "message": "No such (iss, jti) here."})
+        return Response(status_code=200)
+
+    return handler

{regent_httpsig-0.5.0 → regent_httpsig-0.6.0}/src/regent_httpsig/verify.py

@@ -61,6 +61,10 @@ AAUTH_PERSON_TYP = "aa-person+jwt"
 AAUTH_AUTH_TYP = "aa-auth+jwt"  # PS-issued auth tokens — the budget carrier
 # -11: person and auth tokens live at most one hour — enforced with tolerance.
 PERSON_TOKEN_MAX_LIFETIME = 3600 + 90
+# How long after its exp an auth token still earns the budgets "final record"
+# challenge (opt-in, BudgetMiddleware only): the meter retains consumption for
+# about this long after last activity; beyond it there is no figure to carry.
+EXPIRED_AUTH_TOKEN_GRACE = 7200
 
 
 def _register_fully_specified_algs() -> None:
@@ -86,6 +90,11 @@ class VerifiedSignature:
     sub: str | None = None  # AAuth agent id (token `sub`)
     label: str = ""
     claims: dict[str, Any] = field(default_factory=dict)  # AAuth token claims (redacted)
+    # Set only when ``verify(..., allow_expired_auth_token=True)`` accepted an
+    # auth token PAST its exp: genuine (issuer signature + proof of possession
+    # verified) but NOT valid for access. BudgetMiddleware uses it to answer
+    # with the final-record challenge; nothing else should ever see it True.
+    expired: bool = False
 
     def context(self) -> dict[str, Any]:
         """A flat dict suitable for logging / policy engines / audit trails."""
@@ -164,18 +173,28 @@ class HttpsigVerifier:
         self._cache: dict[str, tuple[float, dict[str, Any] | None]] = {}
 
     async def verify(
-        self, method: str, url: str, headers: Mapping[str, str]
+        self, method: str, url: str, headers: Mapping[str, str],
+        *, allow_expired_auth_token: bool = False,
     ) -> VerifiedSignature | None:
         """Verify the request's agent signature. Returns ``None`` when there is
         no ``Signature`` header, the signature is invalid, or the signer's keys
-        cannot be (safely) fetched — never raises on untrusted input."""
+        cannot be (safely) fetched — never raises on untrusted input.
+
+        ``allow_expired_auth_token`` (default False — leave it so for access
+        decisions) lets a genuine ``aa-auth+jwt`` past its ``exp`` come back
+        with ``expired=True`` instead of ``None``, for up to
+        :data:`EXPIRED_AUTH_TOKEN_GRACE` seconds. Budgets need this: the
+        resource owes the holder of an expired token a challenge carrying that
+        token's final consumption record (draft §Budget Exhaustion), and it
+        cannot build one for a token it refused to look at."""
         hdrs = {str(k): str(v) for k, v in headers.items()}
         if not any(k.lower() == "signature" for k in hdrs):
             return None
         result: VerifiedSignature | None = None
         try:
             if any(k.lower() == "signature-key" for k in hdrs):
-                result = await self._verify_aauth(method, url, hdrs)
+                result = await self._verify_aauth(
+                    method, url, hdrs, allow_expired_auth_token=allow_expired_auth_token)
             if result is None:
                 result = await self._verify_web_bot_auth(method, url, hdrs)
         except Exception as exc:  # noqa: BLE001 — belt and braces
@@ -288,7 +307,8 @@ class HttpsigVerifier:
     # ── AAuth (identity-based mode) ──────────────────────────────────────────
 
     async def _verify_aauth(
-        self, method: str, url: str, headers: dict[str, str]
+        self, method: str, url: str, headers: dict[str, str],
+        *, allow_expired_auth_token: bool = False,
     ) -> VerifiedSignature | None:
         try:
             import jwt as pyjwt  # the [aauth] extra
@@ -387,6 +407,7 @@ class HttpsigVerifier:
                         continue
         if issuer_key is None:
             return None
+        tolerate_exp = allow_expired_auth_token and typ == AAUTH_AUTH_TYP
         try:
             claims = pyjwt.decode(
                 token,
@@ -396,11 +417,20 @@ class HttpsigVerifier:
                 options={
                     "require": ["iss", "sub", "exp", "iat"],
                     "verify_aud": audience is not None,
+                    "verify_exp": not tolerate_exp,
                 },
             )
         except Exception as exc:  # noqa: BLE001
             logger.info("aauth token invalid iss=%s: %s", iss, str(exc)[:200])
             return None
+        expired = False
+        if tolerate_exp:
+            overdue = int(time.time()) - int(claims.get("exp", 0))
+            expired = overdue >= 0
+            if overdue > EXPIRED_AUTH_TOKEN_GRACE:
+                logger.info("aauth auth token expired %ss ago — past grace iss=%s",
+                            overdue, iss)
+                return None
 
         # -11: person and auth tokens live at most one hour.
         if typ in (AAUTH_PERSON_TYP, AAUTH_AUTH_TYP):
@@ -456,4 +486,5 @@ class HttpsigVerifier:
                           "budget")  # budgets: the envelope rides in the token
                 if k in claims
             },
+            expired=expired,
         )

{regent_httpsig-0.5.0 → regent_httpsig-0.6.0}/tests/test_budget.py

@@ -28,7 +28,7 @@ from regent_httpsig import (
     build_aauth_requirement,
     generate_seed,
 )
-from regent_httpsig.budget import Reservation
+from regent_httpsig.budget import Reservation, TokenRevoked
 from regent_httpsig.fastapi import BudgetMiddleware
 from regent_httpsig.sfv import SFDictionary
 
@@ -266,11 +266,13 @@ def _ps_pair() -> tuple[Ed25519PrivateKey, dict[str, Any]]:
 
 
 def _auth_token(ps_priv: Ed25519PrivateKey, agent: EgressSigner, *,
-                amount: int, jti: str = "at-1") -> str:
+                amount: int, jti: str = "at-1", age: int = 0) -> str:
+    """``age`` > 600 mints a token that has ALREADY expired (iat/exp shifted
+    into the past) — genuine, possession-bound, not valid for access."""
     from regent_httpsig.verify import _register_fully_specified_algs
 
     _register_fully_specified_algs()  # PyJWT knows "Ed25519" only after this
-    now = int(time.time())
+    now = int(time.time()) - age
     return pyjwt.encode(
         {
             "iss": PS_ISS, "sub": "owner-1", "aud": RESOURCE, "jti": jti,
@@ -487,7 +489,8 @@ async def test_streaming_cost_omitted_reserved_math(
 
     r1 = await _post(app, "/v1/stream", _signed_headers(agent, token, "/v1/stream"))
     assert r1.status_code == 200
-    d1 = SFDictionary(); d1.parse(r1.headers["AAuth-Budget"].encode())
+    d1 = SFDictionary()
+    d1.parse(r1.headers["AAuth-Budget"].encode())
     assert "cost" not in d1                      # omitted — no trailer runtime
     assert int(str(d1["reserved"].value)) == 300  # REQUIRED when cost omitted
     assert int(str(d1["remaining"].value)) == 700  # net of the hold
@@ -495,7 +498,169 @@ async def test_streaming_cost_omitted_reserved_math(
 
     # Stream ended → the actual 120 was committed, 180 returned to the grant.
     r2 = await _post(app, "/v1/search", _signed_headers(agent, token, "/v1/search"))
-    d2 = SFDictionary(); d2.parse(r2.headers["AAuth-Budget"].encode())
+    d2 = SFDictionary()
+    d2.parse(r2.headers["AAuth-Budget"].encode())
     next_remaining = int(str(d2["remaining"].value)) + 300  # add back r2's own cost
-    recovered = 1000 + 300 - 700 - (1000 - next_remaining)  # draft's subtraction…
     assert 700 + 300 - next_remaining == 120     # …prev + reserved − next = cost
+
+
+async def test_expired_token_gets_final_record_challenge(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """§Budget Exhaustion, "auth token expired": plain requirement=auth-token
+    (no reason) + a resource token carrying the token's FINAL record — the
+    figure the issuer needs to settle the allocation (§Settlement: a record
+    stated at/after exp is final)."""
+    ps_priv, ps_jwk = _ps_pair()
+    agent = EgressSigner(seed=generate_seed(), signature_agent=PS_ISS)
+    live = _auth_token(ps_priv, agent, amount=1000, jti="at-9")
+    provider_calls: list[Any] = []
+
+    def provider(key: Any, record: Any) -> str:
+        provider_calls.append((key, record))
+        return "resource.token.final"
+
+    meter = InMemoryMeter()
+    app = _app(_verifier(ps_jwk, monkeypatch), meter=meter,
+               resource_token_provider=provider)
+    # Spend 300 on the live token, so there is a figure to carry.
+    r = await _post(app, "/v1/search", _signed_headers(agent, live, "/v1/search"))
+    assert r.status_code == 200
+
+    # The same jti, now past its exp (same issuer, same key, same claims).
+    stale = _auth_token(ps_priv, agent, amount=1000, jti="at-9", age=700)
+    r = await _post(app, "/v1/search", _signed_headers(agent, stale, "/v1/search"))
+    assert r.status_code == 401
+    assert r.json()["code"] == "AUTH_TOKEN_EXPIRED"
+    assert (r.headers["AAuth-Requirement"]
+            == 'requirement=auth-token;resource-token="resource.token.final"')
+    assert "AAuth-Budget" not in r.headers  # the budget didn't run out; the token did
+    assert provider_calls[-1] == ((PS_ISS, "owner-1", RESOURCE),
+                                  {"jti": "at-9", "consumed": 300})
+    # Nothing was served and nothing more was metered.
+    assert await meter.consumed_record(
+        (PS_ISS, "owner-1", RESOURCE), "at-9") == {"jti": "at-9", "consumed": 300}
+
+
+async def test_expired_token_past_grace_is_no_envelope(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Beyond the grace window there is no figure left to carry: the token is
+    just an unknown one and the request falls through as unsigned."""
+    ps_priv, ps_jwk = _ps_pair()
+    agent = EgressSigner(seed=generate_seed(), signature_agent=PS_ISS)
+    ancient = _auth_token(ps_priv, agent, amount=1000, jti="at-old", age=3 * 3600)
+    app = _app(_verifier(ps_jwk, monkeypatch), require=True)
+    r = await _post(app, "/v1/search", _signed_headers(agent, ancient, "/v1/search"))
+    assert r.status_code == 401 and r.json()["code"] == "AUTH_TOKEN_REQUIRED"
+
+
+async def test_plain_verify_still_rejects_expired_tokens(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The tolerance is opt-in for the budgets middleware only: an access
+    decision through ``verify()`` never sees an expired token as verified."""
+    ps_priv, ps_jwk = _ps_pair()
+    agent = EgressSigner(seed=generate_seed(), signature_agent=PS_ISS)
+    stale = _auth_token(ps_priv, agent, amount=1000, jti="at-9", age=700)
+    verifier = _verifier(ps_jwk, monkeypatch)
+    headers = _signed_headers(agent, stale, "/v1/search")
+    assert await verifier.verify("POST", f"{RESOURCE}/v1/search", headers) is None
+    sig = await verifier.verify("POST", f"{RESOURCE}/v1/search", headers,
+                                allow_expired_auth_token=True)
+    assert sig is not None and sig.expired
+
+
+# ── revocation (base protocol §Token Revocation · budgets §Token Scope · AAuth #151) ──
+
+async def test_meter_revoke_drains_before_final_record() -> None:
+    """Revocation stops new spend at once; a request already in flight completes;
+    the token's record is withheld until nothing is in flight, then it is final."""
+    meter = InMemoryMeter()
+    await meter.observe_grant(KEY, "jti-r", _claim(1000), time.time() + 600)
+    inflight = await meter.reserve(KEY, "jti-r", 300)
+    assert isinstance(inflight, Reservation)
+
+    assert await meter.revoke(KEY[0], "jti-r") is True
+    assert await meter.revoke(KEY[0], "jti-r") is True   # idempotent
+    assert await meter.revoke(KEY[0], "never-seen") is False
+
+    # No new spend, and the record is withheld while the in-flight request runs.
+    outcome = await meter.reserve(KEY, "jti-r", 1)
+    assert outcome == TokenRevoked(drained=False)
+    assert await meter.consumed_record(KEY, "jti-r") is None
+    # The in-flight request completes and is committed as usual.
+    await meter.commit(inflight, 250)
+    assert await meter.reserve(KEY, "jti-r", 1) == TokenRevoked(drained=True)
+    assert await meter.consumed_record(KEY, "jti-r") == {"jti": "jti-r", "consumed": 250}
+    assert await meter.revocation_state(KEY, "jti-r") == TokenRevoked(drained=True)
+    assert await meter.revocation_state(KEY, "other") is None
+    # A later observe_grant of the same jti does not resurrect the grant.
+    await meter.observe_grant(KEY, "jti-r", _claim(1000), time.time() + 600)
+    assert await meter.reserve(KEY, "jti-r", 1) == TokenRevoked(drained=True)
+
+
+def _revocation_app(meter: InMemoryMeter, caller: str | None) -> FastAPI:
+    from regent_httpsig import make_revocation_endpoint
+
+    async def auth(request: Any) -> str | None:
+        return caller
+
+    handler = make_revocation_endpoint(meter, authenticate_ps=auth)
+    app = FastAPI()
+
+    @app.post("/revoke")
+    async def revoke(request: Request):  # type: ignore[no-untyped-def]
+        return await handler(request)
+
+    return app
+
+
+async def test_revocation_endpoint_contract() -> None:
+    from starlette.testclient import TestClient
+
+    meter = InMemoryMeter()
+    await meter.observe_grant(KEY, "jti-e", _claim(500), time.time() + 600)
+    # Unauthenticated → 401, nothing revoked.
+    r = TestClient(_revocation_app(meter, None)).post(
+        "/revoke", json={"iss": PS_ISS, "jti": "jti-e"})
+    assert r.status_code == 401
+    assert isinstance(await meter.reserve(KEY, "jti-e", 1), Reservation)
+    client = TestClient(_revocation_app(meter, PS_ISS))
+    assert client.post("/revoke", json={"iss": PS_ISS}).status_code == 400       # jti REQUIRED
+    other = {"iss": "https://other.example", "jti": "jti-e"}
+    assert client.post("/revoke", json=other).status_code == 403
+    assert client.post("/revoke", json={"iss": PS_ISS, "jti": "ghost"}).status_code == 404
+    r = client.post("/revoke", json={"iss": PS_ISS, "jti": "jti-e"})
+    assert r.status_code == 200 and r.content == b""                            # empty on success
+    again = client.post("/revoke", json={"iss": PS_ISS, "jti": "jti-e"})
+    assert again.status_code == 200  # already invalid → still 200
+    assert isinstance(await meter.reserve(KEY, "jti-e", 1), TokenRevoked)
+
+
+async def test_middleware_revoked_token_gets_challenge_then_final_record(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    ps_priv, ps_jwk = _ps_pair()
+    agent = EgressSigner(seed=generate_seed(), signature_agent=PS_ISS)
+    token = _auth_token(ps_priv, agent, amount=1000, jti="at-rv")
+    calls: list[Any] = []
+
+    def provider(key: Any, record: Any) -> str:
+        calls.append(record)
+        return "resource.token.rv"
+
+    meter = InMemoryMeter()
+    app = _app(_verifier(ps_jwk, monkeypatch), meter=meter, resource_token_provider=provider)
+    first = await _post(app, "/v1/search", _signed_headers(agent, token, "/v1/search"))
+    assert first.status_code == 200
+
+    # The issuer revokes; the next request is refused with the plain challenge
+    # and, nothing being in flight, the FINAL record rides on it.
+    assert await meter.revoke(PS_ISS, "at-rv")
+    r = await _post(app, "/v1/search", _signed_headers(agent, token, "/v1/search"))
+    assert r.status_code == 401 and r.json()["code"] == "AUTH_TOKEN_REVOKED"
+    assert (r.headers["AAuth-Requirement"]
+            == 'requirement=auth-token;resource-token="resource.token.rv"')
+    assert "AAuth-Budget" not in r.headers
+    assert calls[-1] == {"jti": "at-rv", "consumed": 300}

{regent_httpsig-0.5.0 → regent_httpsig-0.6.0}/tests/test_usage.py

@@ -8,9 +8,7 @@ from __future__ import annotations
 
 import asyncio
 import base64
-import json
 import time
-from typing import Any
 
 import pytest
 from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey