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

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

@@ -1,5 +1,29 @@
 # 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

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

@@ -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 → regent_httpsig-0.6.0}/README.md

@@ -144,6 +144,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 → regent_httpsig-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "regent-httpsig"
-version = "0.5.1"
+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.1 → 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.1 → 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.1 → 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
@@ -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-0.5.1 → 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.1 → 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
 
@@ -489,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
@@ -497,9 +498,9 @@ 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
 
 
@@ -568,3 +569,98 @@ async def test_plain_verify_still_rejects_expired_tokens(
     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.1 → 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