regent-httpsig 0.4.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

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/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__(
@@ -223,7 +226,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 +250,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,
@@ -311,14 +314,17 @@ class BudgetMiddleware(BaseHTTPMiddleware):
 
     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.dist-info → regent_httpsig-0.5.0.dist-info}/METADATA

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

{regent_httpsig-0.4.0.dist-info → regent_httpsig-0.5.0.dist-info}/RECORD

@@ -1,16 +1,16 @@
 regent_httpsig/__init__.py,sha256=Ch-PdsMDo_uKG4U5A4xklU3jbCWdJTWXHG86n5VA7dc,1709
-regent_httpsig/budget.py,sha256=RfasLL3HAdLt5kJ2L8DeGoA3FaVXe94LIn1nzboWYKA,15095
+regent_httpsig/budget.py,sha256=sjNJiFyfqLHEdnbh8e4bmqZr2gPveYynZ5eXUYpES_k,16967
 regent_httpsig/cli.py,sha256=WUSLQ2WuEX4E85L2C2EgoUfu5cWpj6MRSG1UVNHpzcw,2005
 regent_httpsig/config.py,sha256=_xAIFYAyNbXzKg-famXLAs7eNdYwuvNA7NHQxcno0G4,2439
-regent_httpsig/fastapi.py,sha256=a2m_azGEoVx9gghJTkKaHFUpUYGrxTmFK8IKW7-9AUQ,15266
+regent_httpsig/fastapi.py,sha256=IijwDjnDKntRzavFzj2o6HM3XqvCHi2VZOv_xL_MLTA,15660
 regent_httpsig/jwk.py,sha256=h4vgnIgpnyKeWdWpm7g_hEyXZOPVREWn-bD4JN07tT0,1637
 regent_httpsig/netguard.py,sha256=Sqg08mdC94RWvnQLJaH4weZW0nN2VlTJF5wVF8VYGHY,2121
 regent_httpsig/sfv.py,sha256=O8eK3Xyw-lewSepLJQcBKfPZAIBZCYatw4zDNDsxxYo,7407
 regent_httpsig/sign.py,sha256=B5ChxFxuuKL0i10bGrgFImzyh8GMjWIqNDECXehBWTA,4397
 regent_httpsig/usage.py,sha256=PSIPXCtUZyh5cjn4SzwOgrXuJrwDIWu-kffJ-4NFeS0,9453
 regent_httpsig/verify.py,sha256=8z-x3trF5B8P8D1aDYoqzF4R5h8BVv91CKiubFKFIiI,19915
-regent_httpsig-0.4.0.dist-info/METADATA,sha256=FcXizrgtqWf9JnuL3ui_YtXDQFNgh-b5DG2zHzYJg-4,12023
-regent_httpsig-0.4.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-regent_httpsig-0.4.0.dist-info/entry_points.txt,sha256=SgZdmc27V14IAmwOjbBoCYLsbrALaqdTUHNHLbil2dU,59
-regent_httpsig-0.4.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-regent_httpsig-0.4.0.dist-info/RECORD,,
+regent_httpsig-0.5.0.dist-info/METADATA,sha256=9_2zaZrS2LBdENWDPnYVWrJhtIh9vgbG_7e7J5f3X_s,12187
+regent_httpsig-0.5.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+regent_httpsig-0.5.0.dist-info/entry_points.txt,sha256=SgZdmc27V14IAmwOjbBoCYLsbrALaqdTUHNHLbil2dU,59
+regent_httpsig-0.5.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+regent_httpsig-0.5.0.dist-info/RECORD,,