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

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

@@ -1,5 +1,52 @@
 # Changelog
 
+## 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
+editor's copy, September 2026; issue #120):
+
+- **No more pooling.** `InMemoryMeter` caps each auth token at its own `budget`
+  (§Aggregation): committed consumption plus outstanding reservations against
+  the presented `jti` never exceed *its* grant, and a token never draws on a
+  sibling's allocation. The `(iss, sub, aud)` key survives as the per-person
+  **ledger** for records and usage counters — it is not a second ceiling.
+  0.4 pooled a person's live grants into one purse, which let a jti spend past
+  its own grant; the overflow, spent from a sibling's allocation, was never
+  attributed and the sibling's remainder later released as unspent. The
+  `required` member makes a fragmented agent's re-authorization a calculation,
+  so the purse bought nothing worth that.
+- **One record on the wire.** Budget refusals carry a single
+  `budget_consumed` object — `{"jti", "consumed"}` for the PRESENTED token —
+  per §The Consumption Record. New `InMemoryMeter.consumed_record(key, jti)`;
+  `consumed_records(key, jkt=…)` stays as the audit view.
+- **Breaking:** `InMemoryMeter.remaining(key)` → `remaining(key, jti)`;
+  `resource_token_provider(key, records: list)` → `(key, record: dict | None)`.
+  `InsufficientBudget.remaining` is now the presented token's balance.
+- Test vectors regenerated (`consumption_records` is one object).
+
 ## 0.4.0
 
 **AAuth Budgets — the August 20 editor's-copy additions** (allocation model,

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: regent-httpsig
-Version: 0.4.0
+Version: 0.5.1
 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
@@ -146,8 +146,10 @@ to the control plane. The middleware does the whole resource-side checklist:
 verify the token against your pinned PS, atomically reserve → commit →
 release per request, answer with `AAuth-Budget`, and refuse exhausted
 envelopes with a `401` + `AAuth-Requirement` (optionally carrying your signed
-resource token with the agent's own consumption records — scoped to its key,
-so one agent never learns about a sibling's spending):
+resource token with **one** consumption record — the presented token's
+`{jti, consumed}` — so one agent never learns about a sibling's spending).
+The cap is **per token**: a jti never draws on a sibling's grant; the
+`(iss, sub, aud)` key is only the per-person ledger behind records and usage:
 
 ```python
 from regent_httpsig import HttpsigConfig, HttpsigVerifier, InMemoryMeter
@@ -172,6 +174,11 @@ 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.
+- 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.4.0 → regent_httpsig-0.5.1}/README.md

@@ -116,8 +116,10 @@ to the control plane. The middleware does the whole resource-side checklist:
 verify the token against your pinned PS, atomically reserve → commit →
 release per request, answer with `AAuth-Budget`, and refuse exhausted
 envelopes with a `401` + `AAuth-Requirement` (optionally carrying your signed
-resource token with the agent's own consumption records — scoped to its key,
-so one agent never learns about a sibling's spending):
+resource token with **one** consumption record — the presented token's
+`{jti, consumed}` — so one agent never learns about a sibling's spending).
+The cap is **per token**: a jti never draws on a sibling's grant; the
+`(iss, sub, aud)` key is only the per-person ledger behind records and usage:
 
 ```python
 from regent_httpsig import HttpsigConfig, HttpsigVerifier, InMemoryMeter
@@ -142,6 +144,11 @@ 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.
+- 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.4.0 → regent_httpsig-0.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "regent-httpsig"
-version = "0.4.0"
+version = "0.5.1"
 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.4.0 → regent_httpsig-0.5.1}/src/regent_httpsig/budget.py

@@ -5,11 +5,23 @@ The auth token carries a spending envelope::
     "budget": { "amount": 2000000, "unit": "USD", "decimals": 6 }   # = $2.00
 
 and the resource meters every request against it: reserve the request's maximum
-cost atomically, serve, commit the actual cost, release the difference. The
-draft requires consumption to be aggregated atomically across all live auth
-tokens for the key ``(iss, sub, aud)`` (§14.4), so the meter pools the grants
-of a principal's live tokens and counts reservations + consumption against
-that pool.
+cost atomically, serve, commit the actual cost, release the difference.
+
+Two things are counted, against different keys (draft §Aggregation):
+
+* the **cap** is per auth token — committed consumption plus outstanding
+  reservations against the presented ``jti`` never exceed *its* ``budget``;
+  no cross-token arithmetic, one token never draws on a sibling's grant;
+* the **ledger** is per person — consumption is posted to ``(iss, sub, aud)``
+  for the consumption record and the usage counters. It is not a second
+  ceiling: a request that fits its token's budget is never refused because
+  of a per-person total.
+
+(0.4 and earlier pooled a principal's live grants into one purse. That let a
+jti spend past its own grant, so the figure recorded against it could exceed
+what its issuer granted and the overflow — spent from a sibling's allocation —
+was never attributed. Dropped in 0.5.0; the ``required`` member makes a
+fragmented agent's re-authorization a calculation instead.)
 
 Everything here is framework-free; the FastAPI glue lives in
 :mod:`regent_httpsig.fastapi` (``BudgetMiddleware``).
@@ -42,7 +54,7 @@ class InvalidBudgetClaim(ValueError):
 
 
 class UnitMismatch(ValueError):
-    """A grant's unit/decimals differ from the pool's — one envelope, one unit."""
+    """A grant's unit/decimals differ from the ledger's — one envelope, one unit."""
 
 
 @dataclass(frozen=True)
@@ -80,8 +92,8 @@ class BudgetClaim:
 
 @dataclass(frozen=True)
 class Reservation:
-    """An atomic hold on the pool for one in-flight request. Never revised —
-    committed (with the actual cost) or released, exactly once."""
+    """An atomic hold on one token's budget for one in-flight request. Never
+    revised — committed (with the actual cost) or released, exactly once."""
 
     rid: int
     key: MeterKey
@@ -91,7 +103,8 @@ class Reservation:
 
 @dataclass(frozen=True)
 class InsufficientBudget:
-    """Refusal: the request's maximum cost exceeds the pool's remaining balance.
+    """Refusal: the request's maximum cost exceeds the presented token's
+    remaining balance.
     ``exhausted`` distinguishes the draft's two reason tokens: an empty envelope
     (``budget-exhausted``) vs a too-expensive request (``insufficient-budget``)."""
 
@@ -204,21 +217,25 @@ class InMemoryMeter:
         return pool
 
     @staticmethod
-    def _remaining(pool: _Pool) -> int:
-        live = sum(a for a, _ in pool.grants.values())
-        spent = sum(pool.consumed.get(jti, 0) for jti in pool.grants)
-        held = sum(a for _, a, _ in pool.reservations.values())
-        return max(0, live - spent - held)
+    def _remaining(pool: _Pool, jti: str) -> int:
+        """The presented token's balance: its grant minus what was committed
+        against it minus what is held for it. Sibling tokens of the same
+        person do not enter — the cap is per token (§Aggregation)."""
+        grant = pool.grants.get(jti)
+        if grant is None:
+            return 0
+        held = sum(a for j, a, _ in pool.reservations.values() if j == jti)
+        return max(0, grant[0] - pool.consumed.get(jti, 0) - held)
 
     # ── public interface (the BudgetMeter contract) ──────────────────────────
 
     async def observe_grant(self, key: MeterKey, jti: str, claim: BudgetClaim,
                             exp: float, jkt: str = "") -> None:
-        """Register a token's envelope in the principal's pool (idempotent per
-        ``jti``). ``jkt`` is the RFC 7638 thumbprint of the token's ``cnf`` key —
+        """Register a token's envelope under the person's ledger key (idempotent
+        per ``jti``). ``jkt`` is the RFC 7638 thumbprint of the token's ``cnf`` key —
         recorded so consumption records can be scoped to the presenting agent
         (one agent must not learn about its siblings). Raises
-        :class:`UnitMismatch` if the pool already runs in a different unit —
+        :class:`UnitMismatch` if the ledger already runs in a different unit —
         one envelope, one unit, no FX at the meter."""
         async with self._lock:
             now = time.monotonic()
@@ -229,7 +246,7 @@ class InMemoryMeter:
                     key, _Pool(unit=claim.unit, decimals=claim.decimals))
             if (pool.unit, pool.decimals) != (claim.unit, claim.decimals):
                 raise UnitMismatch(
-                    f"pool runs in {pool.unit}/{pool.decimals}, "
+                    f"ledger runs in {pool.unit}/{pool.decimals}, "
                     f"grant is {claim.unit}/{claim.decimals}")
             pool.last_activity = now
             if jkt:
@@ -244,7 +261,7 @@ class InMemoryMeter:
             pool = self._purge(key, now)
             if pool is None or jti not in pool.grants:
                 return InsufficientBudget(remaining=0, exhausted=True)
-            remaining = self._remaining(pool)
+            remaining = self._remaining(pool, jti)
             if max_cost > remaining:
                 return InsufficientBudget(remaining=remaining,
                                           exhausted=remaining == 0)
@@ -255,7 +272,7 @@ class InMemoryMeter:
 
     async def commit(self, res: Reservation, actual: int) -> int:
         """Commit the actual cost (clamped to the reserved amount — reservations
-        are never revised upward) and return the pool's remaining balance."""
+        are never revised upward) and return the token's remaining balance."""
         async with self._lock:
             now = time.monotonic()
             pool = self._purge(res.key, now)
@@ -267,7 +284,7 @@ class InMemoryMeter:
             pool.last_activity = now
             if cost > 0:
                 self._record_usage(res.key, pool, res.jti, cost)
-            return self._remaining(pool)
+            return self._remaining(pool, res.jti)
 
     async def release(self, res: Reservation) -> int:
         async with self._lock:
@@ -275,12 +292,14 @@ class InMemoryMeter:
             if pool is None:
                 return 0
             pool.reservations.pop(res.rid, None)
-            return self._remaining(pool)
+            return self._remaining(pool, res.jti)
 
-    async def remaining(self, key: MeterKey) -> int:
+    async def remaining(self, key: MeterKey, jti: str) -> int:
+        """The presented token's remaining balance (0 for an unknown or
+        expired ``jti``)."""
         async with self._lock:
             pool = self._purge(key, time.monotonic())
-            return 0 if pool is None else self._remaining(pool)
+            return 0 if pool is None else self._remaining(pool, jti)
 
     def _record_usage(self, key: MeterKey, pool: _Pool, jti: str,
                       amount: int) -> None:
@@ -322,11 +341,25 @@ class InMemoryMeter:
         or ``None`` before the first commit."""
         return self._metering_unit
 
+    async def consumed_record(self, key: MeterKey, jti: str) -> dict[str, Any] | None:
+        """The consumption record for the resource token's ``budget_consumed``
+        claim (draft §The Consumption Record): ``{"jti", "consumed"}`` for the
+        PRESENTED token — its total metered so far — or ``None`` when nothing
+        was metered against it. One record, the presented token's; the spend
+        under a person's other tokens is the usage endpoint's to report."""
+        async with self._lock:
+            pool = self._purge(key, time.monotonic())
+            if pool is None:
+                return None
+            total = pool.consumed.get(jti, 0)
+            return {"jti": jti, "consumed": total} if total > 0 else None
+
     async def consumed_records(self, key: MeterKey,
                                jkt: str | None = None) -> list[dict[str, Any]]:
-        """Per-token consumption for the resource token's ``budget_consumed``
-        claim: ``[{"jti": ..., "consumed": ...}, ...]``. Non-destructive — the
-        PS deduplicates by ``jti``, so reporting the same record twice is safe.
+        """Audit view: per-token consumption under this ledger key,
+        ``[{"jti": ..., "consumed": ...}, ...]``. Not what goes on the wire —
+        the resource token carries :meth:`consumed_record` — but the figures a
+        PS-side reconciliation or an operator wants to see.
 
         When ``jkt`` is given, records are scoped to tokens bound to that key:
         the agent carrying the resource token sees only its OWN spending, never

{regent_httpsig-0.4.0 → regent_httpsig-0.5.1}/src/regent_httpsig/fastapi.py

@@ -122,7 +122,7 @@ RequiredSignatureDep = Depends(require_signature)
 
 PriceFn = Callable[[Request], "int | None | Awaitable[int | None]"]
 ResourceTokenProvider = Callable[
-    [MeterKey, "list[dict[str, Any]]"], "str | None | Awaitable[str | None]"
+    [MeterKey, "dict[str, Any] | None"], "str | None | Awaitable[str | None]"
 ]
 
 
@@ -158,9 +158,12 @@ class BudgetMiddleware(BaseHTTPMiddleware):
       ``require=True`` refuses them with 401 + ``AAuth-Requirement``.
     - Error responses (4xx/5xx) release the reservation — nothing was served,
       the envelope is not charged.
-    - ``resource_token_provider(key, consumed_records)`` (optional) mints the
-      resource token embedded in budget-refusal responses so the agent can
-      carry ``budget_consumed`` back to its PS for re-authorization.
+    - ``resource_token_provider(key, record)`` (optional) mints the resource
+      token embedded in budget-refusal responses so the agent can carry
+      ``budget_consumed`` back to its PS for re-authorization. ``record`` is
+      the PRESENTED token's ``{"jti", "consumed"}`` (draft §The Consumption
+      Record — one record, two members) or ``None`` when nothing was metered
+      against it yet.
     """
 
     def __init__(
@@ -188,6 +191,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:
@@ -223,7 +233,7 @@ class BudgetMiddleware(BaseHTTPMiddleware):
             reason = "budget-exhausted" if outcome.exhausted else "insufficient-budget"
             return await self._refusal_with_token(
                 reason=reason, envelope=envelope, remaining=outcome.remaining,
-                key=key, jkt=sig.keyid,
+                key=key, jti=jti,
                 # `required` rides only on insufficient-budget: what THIS
                 # request needed, so the agent can lower its bound and retry.
                 required=int(max_cost) if reason == "insufficient-budget" else None,
@@ -247,7 +257,7 @@ class BudgetMiddleware(BaseHTTPMiddleware):
             # when `cost` is omitted — with `remaining` already net of the
             # hold, and commit when the stream completes. The agent recovers
             # the exact figure from the next response's `remaining`.
-            remaining = await self._meter.remaining(key)
+            remaining = await self._meter.remaining(key, jti)
             response.headers["AAuth-Budget"] = build_aauth_budget_header(
                 remaining=remaining, reserved=int(max_cost),
                 unit=envelope.unit, decimals=envelope.decimals,
@@ -304,21 +314,55 @@ 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 _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, jkt: str | None = None,
+        remaining: int, key: MeterKey, jti: str,
         required: int | None = None,
     ) -> Response:
         token: str | None = None
         if self._resource_token is not None:
             try:
-                records = await self._meter.consumed_records(key, jkt=jkt)
-                token = await _maybe_await(self._resource_token(key, records))
+                # One record, the presented token's (§The Consumption Record):
+                # what THIS jti has cost so far. Siblings' spend never rides
+                # home with this agent — the usage endpoint reports that.
+                record = await self._meter.consumed_record(key, jti)
+                token = await _maybe_await(self._resource_token(key, record))
             except Exception:  # noqa: BLE001 — refusal must not fail on the extras
                 logger.warning("resource_token_provider failed", exc_info=True)
         return self._refusal(reason=reason, envelope=envelope,

{regent_httpsig-0.4.0 → regent_httpsig-0.5.1}/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.4.0 → regent_httpsig-0.5.1}/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.4.0 → regent_httpsig-0.5.1}/tests/test_budget.py

@@ -105,19 +105,29 @@ async def test_meter_reserve_commit_release_math() -> None:
     await meter.observe_grant(KEY, "jti-1", _claim(1000), time.time() + 60)
     res = await meter.reserve(KEY, "jti-1", 300)
     assert isinstance(res, Reservation)
-    assert await meter.remaining(KEY) == 700  # 300 held
+    assert await meter.remaining(KEY, "jti-1") == 700  # 300 held
     assert await meter.commit(res, 120) == 880  # difference released
     assert await meter.consumed_records(KEY) == [{"jti": "jti-1", "consumed": 120}]
 
 
-async def test_meter_pools_across_live_tokens() -> None:
-    """The draft's (iss, sub, aud) aggregation: two live envelopes pool."""
+async def test_meter_caps_each_token_at_its_own_budget() -> None:
+    """§Aggregation: the cap is per auth token. Two live envelopes of one
+    person do NOT pool — a jti never draws on a sibling's grant, so the
+    figure recorded against it can never exceed what its issuer granted."""
     meter = InMemoryMeter()
     await meter.observe_grant(KEY, "a", _claim(300), time.time() + 60)
     await meter.observe_grant(KEY, "b", _claim(300), time.time() + 60)
-    res = await meter.reserve(KEY, "a", 500)  # more than either grant alone
+    refusal = await meter.reserve(KEY, "a", 500)  # would have fit a pooled purse
+    assert isinstance(refusal, InsufficientBudget)
+    assert refusal.remaining == 300 and not refusal.exhausted
+    res = await meter.reserve(KEY, "a", 300)
     assert isinstance(res, Reservation)
-    assert await meter.commit(res, 500) == 100
+    assert await meter.commit(res, 300) == 0          # a is spent…
+    assert await meter.remaining(KEY, "b") == 300      # …b is untouched
+    assert await meter.consumed_record(KEY, "a") == {"jti": "a", "consumed": 300}
+    assert await meter.consumed_record(KEY, "b") is None
+    # The ledger still aggregates per person for records/usage.
+    assert await meter.consumed_records(KEY) == [{"jti": "a", "consumed": 300}]
 
 
 async def test_meter_insufficient_vs_exhausted() -> None:
@@ -163,7 +173,7 @@ async def test_meter_expired_reservation_counts_as_consumed() -> None:
     res = await meter.reserve(KEY, "jti-1", 400)
     assert isinstance(res, Reservation)
     # Handler "crashed": never commits. The next touch resolves it as consumed.
-    assert await meter.remaining(KEY) == 600
+    assert await meter.remaining(KEY, "jti-1") == 600
     assert await meter.consumed_records(KEY) == [{"jti": "jti-1", "consumed": 400}]
 
 
@@ -176,9 +186,9 @@ async def test_meter_commit_clamps_to_reservation() -> None:
 
 
 async def test_consumed_records_scoped_to_presenting_jkt() -> None:
-    """Two agents of one principal share the (iss, sub, aud) pool, but each
-    sees only ITS OWN consumption records — never its siblings' (privacy +
-    no extra figures to infer the ceiling from)."""
+    """Two agents of one person post to the same (iss, sub, aud) ledger, but
+    each sees only ITS OWN consumption records — never its siblings' (privacy
+    + no extra figures to infer the ceiling from)."""
     meter = InMemoryMeter()
     now = time.time()
     await meter.observe_grant(KEY, "jti-a", _claim(500), now + 60, jkt="jkt-agent-A")
@@ -194,15 +204,16 @@ async def test_consumed_records_scoped_to_presenting_jkt() -> None:
     assert await meter.consumed_records(KEY, jkt="jkt-agent-B") == [
         {"jti": "jti-b", "consumed": 250}
     ]
-    # Unscoped (PS-side / audit view) still returns the whole pool.
+    # Unscoped (PS-side / audit view) still returns the whole ledger.
     assert len(await meter.consumed_records(KEY)) == 2
 
 
 async def test_refusal_records_scoped_to_presenter(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
-    """The resource token embedded in a refusal carries only the presenting
-    agent's records: sibling B's spend must not ride home with agent A."""
+    """The resource token embedded in a refusal carries ONE record — the
+    presented token's (§The Consumption Record): sibling A's spend must not
+    ride home with agent B, and B's other tokens don't either."""
     ps_priv, ps_jwk = _ps_pair()
     agent_a = EgressSigner(seed=generate_seed(), signature_agent=PS_ISS)
     agent_b = EgressSigner(seed=generate_seed(), signature_agent=PS_ISS)
@@ -216,15 +227,16 @@ async def test_refusal_records_scoped_to_presenter(
 
     app = _app(_verifier(ps_jwk, monkeypatch), resource_token_provider=provider)
 
-    # A spends 300 (price of /v1/search), B spends 300 — pool now at 200.
+    # A spends 300 (price of /v1/search) of its 400; B spends 300 of its 400.
     assert (await _post(app, "/v1/search",
                         _signed_headers(agent_a, token_a, "/v1/search"))).status_code == 200
     assert (await _post(app, "/v1/search",
                         _signed_headers(agent_b, token_b, "/v1/search"))).status_code == 200
-    # B asks again: 300 > 200 remaining → refusal with records — B's only.
+    # B asks again: 300 > 100 remaining on at-B → refusal carrying at-B's record only.
     r = await _post(app, "/v1/search", _signed_headers(agent_b, token_b, "/v1/search"))
     assert r.status_code == 401
-    assert provider_records == [[{"jti": "at-B", "consumed": 300}]]
+    assert provider_records == [{"jti": "at-B", "consumed": 300}]
+    assert r.headers["AAuth-Budget"] == 'remaining=100, required=300, unit="KZT", decimals=2'
 
 
 async def test_meter_concurrent_reserves_never_oversell() -> None:
@@ -254,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,
@@ -380,7 +394,7 @@ async def test_middleware_refuses_when_insufficient(
     assert (r2.headers["AAuth-Budget"] ==
             'remaining=200, required=300, unit="KZT", decimals=2')
     assert provider_calls and provider_calls[0][0] == (PS_ISS, "owner-1", RESOURCE)
-    assert provider_calls[0][1] == [{"jti": "at-1", "consumed": 300}]
+    assert provider_calls[0][1] == {"jti": "at-1", "consumed": 300}  # one record (#120)
 
 
 async def test_middleware_actual_cost_from_handler(
@@ -487,3 +501,70 @@ async def test_streaming_cost_omitted_reserved_math(
     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

{regent_httpsig-0.4.0 → regent_httpsig-0.5.1}/tests/test_usage.py

@@ -142,7 +142,7 @@ async def test_expired_reservation_reaches_usage_counters() -> None:
     await meter.observe_grant(KEY, "jti-1", CLAIM, time.time() + 3600, jkt=JKT_A)
     await meter.reserve(KEY, "jti-1", 700)
     await asyncio.sleep(0.02)
-    await meter.remaining(KEY)  # triggers the purge
+    await meter.remaining(KEY, "jti-1")  # triggers the purge
     assert (await meter.usage_keys(KEY[0], [JKT_A]))[JKT_A] == 700
 
 

{regent_httpsig-0.4.0 → regent_httpsig-0.5.1}/vectors/aauth-budgets-vectors.json

@@ -68,20 +68,15 @@
     ]
   },
   "consumption_records": {
-    "budget_consumed": [
-      {
-        "jti": "at-2",
-        "consumed": 431200
-      },
-      {
-        "jti": "at-1",
-        "consumed": 221200
-      }
-    ],
+    "budget_consumed": {
+      "jti": "at-2",
+      "consumed": 431200
+    },
     "notes": [
-      "two members and no more \u2014 the PS joins the rest from its ledger",
-      "records are scoped to the presenting agent's key (jkt): one agent never learns a sibling's spending",
-      "most recent first; SHOULD NOT exceed 20 records"
+      "ONE record \u2014 the presented token's \u2014 two members and no more; the issuer joins the rest from its ledger (#120)",
+      "consumed is that token's total as of the resource token's iat",
+      "final vs snapshot is decided by the issuer: resource token iat >= auth token exp is the final figure and releases the remainder; a record on a live token releases nothing",
+      "the spend under a person's other tokens is the usage endpoint's to report \u2014 never carried by a sibling"
     ]
   },
   "signed_usage_response": {

{regent_httpsig-0.4.0 → regent_httpsig-0.5.1}/vectors/generate.py

@@ -87,15 +87,16 @@ def budget_claim() -> dict:
 
 def consumption_records() -> dict:
     return {
-        "budget_consumed": [
-            {"jti": "at-2", "consumed": 431200},
-            {"jti": "at-1", "consumed": 221200},
-        ],
+        "budget_consumed": {"jti": "at-2", "consumed": 431200},
         "notes": [
-            "two members and no more — the PS joins the rest from its ledger",
-            "records are scoped to the presenting agent's key (jkt): one "
-            "agent never learns a sibling's spending",
-            "most recent first; SHOULD NOT exceed 20 records",
+            "ONE record — the presented token's — two members and no more; "
+            "the issuer joins the rest from its ledger (#120)",
+            "consumed is that token's total as of the resource token's iat",
+            "final vs snapshot is decided by the issuer: resource token iat >= "
+            "auth token exp is the final figure and releases the remainder; "
+            "a record on a live token releases nothing",
+            "the spend under a person's other tokens is the usage endpoint's "
+            "to report — never carried by a sibling",
         ],
     }