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

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/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/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
@@ -229,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(
@@ -325,6 +331,27 @@ class BudgetMiddleware(BaseHTTPMiddleware):
             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 = (

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.1.dist-info → regent_httpsig-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: regent-httpsig
-Version: 0.5.1
+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,9 @@ 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

{regent_httpsig-0.5.1.dist-info → regent_httpsig-0.6.0.dist-info}/RECORD

@@ -1,16 +1,16 @@
-regent_httpsig/__init__.py,sha256=Ch-PdsMDo_uKG4U5A4xklU3jbCWdJTWXHG86n5VA7dc,1709
-regent_httpsig/budget.py,sha256=sjNJiFyfqLHEdnbh8e4bmqZr2gPveYynZ5eXUYpES_k,16967
+regent_httpsig/__init__.py,sha256=VDo7Yj7LvJ8newfCUpSFZbcncfLFAazMPbyw7MaQQsQ,1809
+regent_httpsig/budget.py,sha256=5yPRdai8ZTLp4lV-cn8y5kbsTtqE06XUhvT3JjJD_Ys,19667
 regent_httpsig/cli.py,sha256=WUSLQ2WuEX4E85L2C2EgoUfu5cWpj6MRSG1UVNHpzcw,2005
 regent_httpsig/config.py,sha256=_xAIFYAyNbXzKg-famXLAs7eNdYwuvNA7NHQxcno0G4,2439
-regent_httpsig/fastapi.py,sha256=RGkEHsNchEac7fXNYs2CT_MOETDktCxHcgQGwytSCCI,17714
+regent_httpsig/fastapi.py,sha256=-JKatY8RCVJm5el5zyPjnhwLbWYYje5iHQO9HpRmLqg,19220
 regent_httpsig/jwk.py,sha256=h4vgnIgpnyKeWdWpm7g_hEyXZOPVREWn-bD4JN07tT0,1637
 regent_httpsig/netguard.py,sha256=Sqg08mdC94RWvnQLJaH4weZW0nN2VlTJF5wVF8VYGHY,2121
 regent_httpsig/sfv.py,sha256=-nUUjyqyAMOSGro9Z0AIXiuchqsIAVaJWbKuIIO4fB0,7624
 regent_httpsig/sign.py,sha256=B5ChxFxuuKL0i10bGrgFImzyh8GMjWIqNDECXehBWTA,4397
-regent_httpsig/usage.py,sha256=PSIPXCtUZyh5cjn4SzwOgrXuJrwDIWu-kffJ-4NFeS0,9453
+regent_httpsig/usage.py,sha256=094CwFHZVDIwmDf8WDg1p4nYlVCBkpi2DrZXdFbFzEo,11889
 regent_httpsig/verify.py,sha256=p9VtHZz9HWHIstDBxNvVrc_xJdubbRA_pN9DjQQDzpk,21716
-regent_httpsig-0.5.1.dist-info/METADATA,sha256=AWYCmTad0KRJFx6ODUZso9fyUcvN6CdU2fbxh0-LTXw,12496
-regent_httpsig-0.5.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-regent_httpsig-0.5.1.dist-info/entry_points.txt,sha256=SgZdmc27V14IAmwOjbBoCYLsbrALaqdTUHNHLbil2dU,59
-regent_httpsig-0.5.1.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-regent_httpsig-0.5.1.dist-info/RECORD,,
+regent_httpsig-0.6.0.dist-info/METADATA,sha256=LBGeQCM6nfJ3f0hcQRTDjQKB2Our30hMhPMmwqCVZXQ,12725
+regent_httpsig-0.6.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+regent_httpsig-0.6.0.dist-info/entry_points.txt,sha256=SgZdmc27V14IAmwOjbBoCYLsbrALaqdTUHNHLbil2dU,59
+regent_httpsig-0.6.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+regent_httpsig-0.6.0.dist-info/RECORD,,