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

regent_httpsig/__init__.py

@@ -14,6 +14,14 @@ from regent_httpsig.budget import (
 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.usage import (
+    ResponseSigner,
+    UsageQueryError,
+    build_usage_response,
+    make_usage_endpoint,
+    parse_usage_request,
+    validate_budget_grant,
+)
 from regent_httpsig.sfv import (
     build_aauth_budget_header,
     build_aauth_requirement,
@@ -40,6 +48,12 @@ __all__ = [
     "__version__",
     "assert_public_url",
     "b64url",
+    "ResponseSigner",
+    "UsageQueryError",
+    "build_usage_response",
+    "make_usage_endpoint",
+    "parse_usage_request",
+    "validate_budget_grant",
     "build_aauth_budget_header",
     "build_aauth_requirement",
     "generate_seed",

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``).
@@ -21,6 +33,7 @@ import asyncio
 import itertools
 import time
 from collections.abc import Mapping
+from datetime import UTC, datetime, timedelta
 from dataclasses import dataclass, field
 from typing import Any
 
@@ -41,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)
@@ -79,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
@@ -90,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``)."""
 
@@ -109,6 +123,48 @@ class _Pool:
     last_activity: float = 0.0
 
 
+@dataclass
+class _ScopeCounters:
+    """Calendar counters for one usage scope (draft §calendar-counters): running
+    integers bucketed on UTC boundaries — no per-record history is kept."""
+
+    all_time: int = 0
+    day: int = 0
+    week: int = 0
+    month: int = 0
+    year: int = 0
+    day_start: float = 0.0
+    week_start: float = 0.0
+    month_start: float = 0.0
+    year_start: float = 0.0
+
+    def add(self, amount: int, wall: float) -> None:
+        self._roll(wall)
+        self.all_time += amount
+        self.day += amount
+        self.week += amount
+        self.month += amount
+        self.year += amount
+
+    def snapshot(self, wall: float) -> dict[str, int]:
+        self._roll(wall)
+        return {"day": self.day, "week": self.week, "month": self.month,
+                "year": self.year, "all_time": self.all_time}
+
+    def _roll(self, wall: float) -> None:
+        dt = datetime.fromtimestamp(wall, tz=UTC)
+        day = dt.replace(hour=0, minute=0, second=0, microsecond=0)
+        week = day - timedelta(days=dt.weekday())  # Monday 00:00 UTC (ISO 8601)
+        month = day.replace(day=1)
+        year = month.replace(month=1)
+        for name, start in (("day", day), ("week", week),
+                            ("month", month), ("year", year)):
+            ts = start.timestamp()
+            if getattr(self, f"{name}_start") < ts:
+                setattr(self, name, 0)
+                setattr(self, f"{name}_start", ts)
+
+
 class InMemoryMeter:
     """Single-process meter (asyncio-safe). Right for a single-instance service;
     multi-replica deployments need a shared backend behind the same interface.
@@ -119,12 +175,23 @@ class InMemoryMeter:
     """
 
     def __init__(self, *, reservation_ttl: float = 120.0,
-                 retention_seconds: float = 7200.0) -> None:
+                 retention_seconds: float = 7200.0,
+                 usage_key_retention: float = 86400.0) -> None:
         self._pools: dict[MeterKey, _Pool] = {}
         self._lock = asyncio.Lock()
         self._rids = itertools.count(1)
         self._reservation_ttl = reservation_ttl
         self._retention = retention_seconds
+        # Usage counters (draft §usage-counters) — wall-clock, keyed by the
+        # issuing PS so the endpoint only answers the party whose tokens we
+        # accepted. Scope counters never expire (all_time reaches as far back
+        # as the resource retains); per-key figures are pruned on IDLE time —
+        # "SHOULD retain … at least 24 hours after that key's last metered
+        # 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)
+        self._metering_unit: tuple[str, int] | None = None
 
     # ── internals (call under lock) ──────────────────────────────────────────
 
@@ -137,6 +204,7 @@ class InMemoryMeter:
             if deadline <= now:
                 pool.consumed[jti] = pool.consumed.get(jti, 0) + amount
                 del pool.reservations[rid]
+                self._record_usage(key, pool, jti, amount)
         # Expired grants leave the pool; their consumption records remain for
         # budget_consumed reporting until the retention window passes.
         for jti, (_, exp) in list(pool.grants.items()):
@@ -149,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()
@@ -174,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:
@@ -189,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)
@@ -200,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)
@@ -210,7 +282,9 @@ class InMemoryMeter:
             cost = min(max(actual, 0), held[1] if held else res.amount)
             pool.consumed[res.jti] = pool.consumed.get(res.jti, 0) + cost
             pool.last_activity = now
-            return self._remaining(pool)
+            if cost > 0:
+                self._record_usage(res.key, pool, res.jti, cost)
+            return self._remaining(pool, res.jti)
 
     async def release(self, res: Reservation) -> int:
         async with self._lock:
@@ -218,18 +292,74 @@ 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:
+        """Post a committed cost to the usage counters (call under lock).
+        Wall-clock, because calendar boundaries are UTC by definition."""
+        if amount <= 0:
+            return
+        wall = time.time()
+        iss, sub, _aud = key
+        self._metering_unit = self._metering_unit or (pool.unit, pool.decimals)
+        self._scope_usage.setdefault((iss, sub), _ScopeCounters()).add(amount, wall)
+        jkt = pool.jkt_of.get(jti)
+        if jkt:
+            total, _ = self._key_usage.get((iss, jkt), (0, 0.0))
+            self._key_usage[(iss, jkt)] = (total + amount, wall)
+
+    async def usage_scope(self, iss: str, sub: str) -> dict[str, int] | None:
+        """Calendar counters for a ``sub`` scope query, or ``None`` when the
+        resource holds no figure — the endpoint then omits ``usage``, keeping
+        "never seen" indistinguishable from "nothing consumed"."""
+        async with self._lock:
+            counters = self._scope_usage.get((iss, sub))
+            return None if counters is None else counters.snapshot(time.time())
+
+    async def usage_keys(self, iss: str, jkts: list[str]) -> dict[str, int]:
+        """Per-key totals for a ``jkts`` query. Unrecognized or pruned keys are
+        OMITTED, never reported as zero — absence means "cannot answer", a
+        present zero would be a wrong answer to an allocation decision."""
+        async with self._lock:
+            wall = time.time()
+            for pair, (_, last) in list(self._key_usage.items()):
+                if wall - last > self._usage_key_retention:
+                    del self._key_usage[pair]
+            return {jkt: self._key_usage[(iss, jkt)][0]
+                    for jkt in jkts if (iss, jkt) in self._key_usage}
+
+    def metering_unit(self) -> tuple[str, int] | None:
+        """The one unit every usage figure is denominated in (draft §one-unit),
+        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,10 @@ 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,
             )
 
         reservation: Reservation = outcome
@@ -237,6 +243,21 @@ class BudgetMiddleware(BaseHTTPMiddleware):
             # Nothing was served — the envelope is not charged for errors.
             remaining = await self._meter.release(reservation)
             cost = 0
+        elif self._is_streamed(request, response):
+            # Cost-omitted mode (draft §cost-omitted): a streamed response's
+            # actual cost is known only when the stream ends, and this runtime
+            # sends no trailers. We state what we HOLD — `reserved`, REQUIRED
+            # 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, jti)
+            response.headers["AAuth-Budget"] = build_aauth_budget_header(
+                remaining=remaining, reserved=int(max_cost),
+                unit=envelope.unit, decimals=envelope.decimals,
+            )
+            self._commit_after_stream(request, response, reservation,
+                                      int(max_cost))
+            return response
         else:
             actual = getattr(request.state, "budget_cost", None)
             cost = int(actual) if actual is not None else int(max_cost)
@@ -247,6 +268,36 @@ class BudgetMiddleware(BaseHTTPMiddleware):
         )
         return response
 
+    @staticmethod
+    def _is_streamed(request: Request, response: Response) -> bool:
+        """A handler opts in with ``request.state.budget_streaming = True``;
+        SSE responses are recognized on their own."""
+        if getattr(request.state, "budget_streaming", False):
+            return True
+        ctype = response.headers.get("content-type", "")
+        return ctype.startswith("text/event-stream")
+
+    def _commit_after_stream(self, request: Request, response: Response,
+                             reservation: Reservation, max_cost: int) -> None:
+        """Wrap the body iterator: commit when the stream ends (the handler may
+        set ``request.state.budget_cost`` while streaming), release the unspent
+        remainder; a broken stream commits the full hold — conservative, per
+        the reservation-timeout rule."""
+        inner = response.body_iterator  # type: ignore[attr-defined]
+
+        async def metered() -> Any:
+            ok = False
+            try:
+                async for chunk in inner:
+                    yield chunk
+                ok = True
+            finally:
+                actual = getattr(request.state, "budget_cost", None)
+                cost = int(actual) if (ok and actual is not None) else max_cost
+                await self._meter.commit(reservation, cost)
+
+        response.body_iterator = metered()  # type: ignore[attr-defined]
+
     # ── helpers ──────────────────────────────────────────────────────────────
 
     async def _verified(self, request: Request) -> VerifiedSignature | None:
@@ -263,22 +314,27 @@ 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,
-                             remaining=remaining, resource_token=token)
+                             remaining=remaining, resource_token=token,
+                             required=required)
 
     def _refusal(
         self, *, reason: str | None, envelope: BudgetClaim | None,
         remaining: int | None, key: MeterKey | None = None,
-        resource_token: str | None = None,
+        resource_token: str | None = None, required: int | None = None,
     ) -> Response:
         headers = {
             "AAuth-Requirement": build_aauth_requirement(
@@ -288,7 +344,8 @@ class BudgetMiddleware(BaseHTTPMiddleware):
         }
         if remaining is not None and envelope is not None:
             headers["AAuth-Budget"] = build_aauth_budget_header(
-                remaining=remaining, unit=envelope.unit, decimals=envelope.decimals
+                remaining=remaining, required=required,
+                unit=envelope.unit, decimals=envelope.decimals,
             )
         code = "AUTH_TOKEN_REQUIRED" if reason is None else reason.upper().replace("-", "_")
         return JSONResponse(

regent_httpsig/sfv.py

@@ -151,11 +151,15 @@ def build_aauth_budget_header(
     remaining: int,
     cost: int | None = None,
     reserved: int | None = None,
+    required: int | None = None,
     unit: str | None = None,
     decimals: int | None = None,
 ) -> str:
     """Serialize the ``AAuth-Budget`` response header. ``remaining`` is the only
-    REQUIRED member; ``unit``/``decimals`` must travel together or not at all."""
+    REQUIRED member; ``unit``/``decimals`` must travel together or not at all.
+    ``required`` is the maximum cost of a request refused ``insufficient-budget``
+    — sent only with that refusal, so the agent's retry is a calculation
+    (lower the bound to fit ``remaining``) rather than a search."""
     if (unit is None) != (decimals is None):
         raise ValueError("unit and decimals must be provided together")
     members: list[str] = []
@@ -164,6 +168,8 @@ def build_aauth_budget_header(
     members.append(f"remaining={remaining}")
     if reserved is not None:
         members.append(f"reserved={reserved}")
+    if required is not None:
+        members.append(f"required={required}")
     if unit is not None and decimals is not None:
         members.append(f"unit={_sf_string(unit)}")
         members.append(f"decimals={decimals}")

regent_httpsig/usage.py

@@ -0,0 +1,223 @@
+"""AAuth Budgets usage endpoint (draft-hardt-aauth-budgets, §Usage Counters).
+
+Consumption records reach the PS only when an agent carries a resource token
+home; this endpoint removes the agent from that loop — the PS queries the
+resource directly, on a channel the agent is never on.
+
+The library owns the contract: query validation, the response shape, and the
+RECOMMENDED response signature. Caller authentication is the application's
+(``authenticate_ps``) — it already knows which person servers it trusts and
+how it verifies their signatures, exactly as it does for auth tokens.
+
+Draft rules encoded here, each load-bearing:
+
+- Exactly one scope key (``sub`` | ``tenant`` | ``mission_s256``) or ``jkts``;
+  both MAY appear; two scope keys or neither-nor-jkts is an error.
+- An unrecognized scope value returns ``200`` with ``usage`` omitted — "never
+  seen" and "nothing consumed" are deliberately indistinguishable, so a query
+  cannot discover whether a person holds an account.
+- An unrecognized or pruned thumbprint is OMITTED from ``jkts``, never zero:
+  absence means "cannot answer"; a present zero would be a wrong answer to an
+  allocation decision.
+- One unit per response, named once at the top level.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import time
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from regent_httpsig.jwk import b64url_decode, jwk_thumbprint
+
+__all__ = ["UsageQueryError", "ResponseSigner", "build_usage_response",
+           "parse_usage_request", "make_usage_endpoint",
+           "validate_budget_grant"]
+
+_SCOPE_KEYS = ("sub", "tenant", "mission_s256")
+_MAX_JKTS = 100
+
+
+class UsageQueryError(ValueError):
+    """The query violates the request contract (two scope keys, neither a
+    scope key nor ``jkts``, or malformed members)."""
+
+
+def parse_usage_request(body: Any) -> tuple[str | None, str | None, list[str]]:
+    """Validate a usage query. Returns ``(scope_key, scope_value, jkts)``."""
+    if not isinstance(body, dict):
+        raise UsageQueryError("body must be a JSON object")
+    present = [k for k in _SCOPE_KEYS if k in body]
+    if len(present) > 1:
+        raise UsageQueryError("at most one scope key may appear")
+    jkts_raw = body.get("jkts", [])
+    if not isinstance(jkts_raw, list) or len(jkts_raw) > _MAX_JKTS or not all(
+        isinstance(j, str) and 20 <= len(j) <= 100 for j in jkts_raw
+    ):
+        raise UsageQueryError("jkts must be a short array of JWK thumbprints")
+    if not present and not jkts_raw:
+        raise UsageQueryError("a scope key or jkts is required")
+    scope_key = present[0] if present else None
+    scope_value = None
+    if scope_key is not None:
+        scope_value = body[scope_key]
+        if not isinstance(scope_value, str) or not scope_value:
+            raise UsageQueryError(f"{scope_key} must be a non-empty string")
+    return scope_key, scope_value, [str(j) for j in jkts_raw]
+
+
+async def build_usage_response(
+    meter: Any,
+    *,
+    iss: str,
+    aud: str,
+    unit: str,
+    decimals: int,
+    scope_key: str | None,
+    scope_value: str | None,
+    jkts: list[str],
+    now: float | None = None,
+) -> dict[str, Any]:
+    """Assemble the response body per §Usage Response. ``iss`` scopes every
+    figure to tokens the calling PS issued; ``aud`` echoes who the response is
+    for (what stops a signed response being shown to a third party)."""
+    out: dict[str, Any] = {
+        "as_of": int(now if now is not None else time.time()),
+        "aud": aud,
+        "unit": unit,
+        "decimals": decimals,
+    }
+    if scope_key is not None:
+        out[scope_key] = scope_value
+        if scope_key == "sub":
+            counters = await meter.usage_scope(iss, str(scope_value))
+            if counters is not None:
+                out["usage"] = counters
+        # tenant / mission_s256: this meter holds no figure for them — the
+        # scope value is echoed and ``usage`` omitted, per the unrecognized
+        # scope rule. A backend that tracks them plugs in here.
+    if jkts:
+        out["jkts"] = await meter.usage_keys(iss, jkts)
+    return out
+
+
+class ResponseSigner:
+    """Signs a usage response per §The Signed Response: an Ed25519 HTTP Sig
+    covering ``@status``, ``content-type``, ``content-digest``, bound to the
+    request via ``@authority``/``@path`` with the ``req`` parameter.
+
+    Hand-built base string: response signing with request-bound components is
+    beyond the request-oriented helper libraries, the component set is fixed by
+    the draft, and the golden tests freeze every byte of it.
+    """
+
+    def __init__(self, *, seed: str, jwks_url: str, label: str = "sig") -> None:
+        raw = b64url_decode(seed)
+        if len(raw) != 32:
+            raise ValueError("seed must be 32 bytes (base64url-encoded)")
+        self._key = Ed25519PrivateKey.from_private_bytes(raw)
+        self._jwks_url = jwks_url
+        self._label = label
+        self.public_jwk = {
+            "kty": "OKP", "crv": "Ed25519",
+            "x": base64.urlsafe_b64encode(
+                self._key.public_key().public_bytes_raw()
+            ).rstrip(b"=").decode(),
+        }
+        self.keyid = jwk_thumbprint(self.public_jwk)
+
+    def sign(self, *, status: int, content_type: str, body: bytes,
+             authority: str, path: str,
+             created: int | None = None) -> dict[str, str]:
+        """Return the four response headers: ``Content-Digest``,
+        ``Signature-Input``, ``Signature``, ``Signature-Key``."""
+        digest = "sha-256=:" + base64.b64encode(
+            hashlib.sha256(body).digest()).decode() + ":"
+        created = int(created if created is not None else time.time())
+        inner = (
+            '("@status" "content-type" "content-digest" '
+            '"@authority";req "@path";req)'
+            f";created={created}"
+        )
+        base = "\n".join([
+            f'"@status": {status}',
+            f'"content-type": {content_type}',
+            f'"content-digest": {digest}',
+            f'"@authority";req: {authority}',
+            f'"@path";req: {path}',
+            f'"@signature-params": {inner}',
+        ])
+        sig = base64.b64encode(self._key.sign(base.encode())).decode()
+        return {
+            "Content-Digest": digest,
+            "Signature-Input": f"{self._label}={inner}",
+            "Signature": f"{self._label}=:{sig}:",
+            "Signature-Key": f'{self._label}=jwks_uri; jwks_uri="{self._jwks_url}"',
+        }
+
+
+def make_usage_endpoint(
+    meter: Any,
+    *,
+    authenticate_ps: Callable[[Any], Awaitable[str | None]],
+    unit: str,
+    decimals: int,
+    signer: ResponseSigner | None = None,
+) -> Callable[[Any], Awaitable[Any]]:
+    """Build an ASGI-framework-agnostic handler: ``handler(request)`` returns a
+    Starlette/FastAPI ``Response``. ``authenticate_ps(request)`` verifies the
+    calling person server's signature (jwks_uri scheme, per the AS token
+    endpoint rules) and returns its issuer identifier, or ``None`` to refuse —
+    the resource MUST only answer for values seen in tokens from that PS,
+    which the ``iss``-keyed counters enforce structurally."""
+    from starlette.responses import JSONResponse, Response
+
+    async def handler(request: Any) -> Response:
+        iss = await authenticate_ps(request)
+        if iss is None:
+            return JSONResponse(status_code=401, content={
+                "code": "PS_AUTH_REQUIRED",
+                "message": "Sign the query as a person server (jwks_uri scheme).",
+            })
+        try:
+            payload = json.loads(await request.body() or b"{}")
+            scope_key, scope_value, jkts = parse_usage_request(payload)
+        except (UsageQueryError, ValueError) as exc:
+            return JSONResponse(status_code=400, content={
+                "code": "INVALID_USAGE_QUERY", "message": str(exc)[:200]})
+        doc = await build_usage_response(
+            meter, iss=iss, aud=iss, unit=unit, decimals=decimals,
+            scope_key=scope_key, scope_value=scope_value, jkts=jkts)
+        body = json.dumps(doc, separators=(",", ":")).encode()
+        headers: dict[str, str] = {}
+        if signer is not None:
+            headers = signer.sign(
+                status=200, content_type="application/json", body=body,
+                authority=request.url.netloc, path=request.url.path)
+        return Response(content=body, media_type="application/json",
+                        headers=headers)
+
+    return handler
+
+
+def validate_budget_grant(unit: str, decimals: int,
+                          budget_units: list[dict[str, Any]]) -> None:
+    """Enforce the §Resource Metadata MUSTs before minting a resource token:
+    a resource that declares ``budget_units`` MUST NOT issue a token whose
+    ``budget.unit`` is absent from the array, and MUST set ``budget.decimals``
+    to the declared value — the mismatch this stops is the draft's
+    "thousandfold error"."""
+    for entry in budget_units:
+        if entry.get("unit") == unit:
+            declared = entry.get("decimals")
+            if declared != decimals:
+                raise ValueError(
+                    f"budget.decimals must be {declared} for {unit!r} "
+                    f"(declared in budget_units), got {decimals}")
+            return
+    raise ValueError(f"unit {unit!r} is not declared in budget_units")

{regent_httpsig-0.3.0.dist-info → regent_httpsig-0.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: regent-httpsig
-Version: 0.3.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
@@ -168,6 +170,42 @@ The only thing the library cannot do for you is pricing (`price_fn`) — that
 is your domain. First known implementation of the draft; running in
 production on [get4agent.com](https://get4agent.com).
 
+**The August 20 additions** are covered too:
+
+- `insufficient-budget` refusals carry **`required`** — the refused request's
+  maximum cost — so the agent lowers its bound and retries instead of guessing.
+- **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
+  from the next response's `remaining`.
+- The **usage endpoint** (§Usage Counters) lets your PS query consumption
+  without the agent in the loop — scope counters (`sub`, UTC calendar buckets)
+  and per-key `jkts` totals, optionally signed:
+
+```python
+from regent_httpsig import InMemoryMeter, ResponseSigner, make_usage_endpoint
+
+handler = make_usage_endpoint(
+    meter,
+    authenticate_ps=my_ps_authenticator,   # verify the PS's jwks_uri signature
+    unit="USD", decimals=6,
+    signer=ResponseSigner(seed=SEED, jwks_url="https://api.example/jwks.json"),
+)
+
+@app.post("/usage")
+async def usage(request: Request):
+    return await handler(request)
+```
+
+- `validate_budget_grant(unit, decimals, budget_units)` enforces the resource
+  metadata MUSTs before you mint a resource token — the "thousandfold error"
+  guard.
+
+**Test vectors**: [`vectors/aauth-budgets-vectors.json`](vectors/aauth-budgets-vectors.json) —
+header serializations (including `required` and the cost-omitted streaming
+case), the budget object, consumption records, and a fully worked signed
+usage response with a fixed key, ready for cross-implementation checks.
+
 ## Security model (what a naive implementation gets wrong)
 
 The verifier fetches key directories from **attacker-nameable origins** — whoever signs a

regent_httpsig-0.5.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+regent_httpsig/__init__.py,sha256=Ch-PdsMDo_uKG4U5A4xklU3jbCWdJTWXHG86n5VA7dc,1709
+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=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.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,,

regent_httpsig-0.3.0.dist-info/RECORD

@@ -1,15 +0,0 @@
-regent_httpsig/__init__.py,sha256=TCRliXblszIoUdlNNQzPf41jA2lZ8Pu3OImylFGzaMk,1372
-regent_httpsig/budget.py,sha256=8B0Zb5exfjorP1pcvezpuYqHN13ytrwJG3MNOEhnvE4,10563
-regent_httpsig/cli.py,sha256=WUSLQ2WuEX4E85L2C2EgoUfu5cWpj6MRSG1UVNHpzcw,2005
-regent_httpsig/config.py,sha256=_xAIFYAyNbXzKg-famXLAs7eNdYwuvNA7NHQxcno0G4,2439
-regent_httpsig/fastapi.py,sha256=cDOk7qHdz58JO3MlTDLsyDwGEQm6t3ZO3S3hyyo7OyU,12550
-regent_httpsig/jwk.py,sha256=h4vgnIgpnyKeWdWpm7g_hEyXZOPVREWn-bD4JN07tT0,1637
-regent_httpsig/netguard.py,sha256=Sqg08mdC94RWvnQLJaH4weZW0nN2VlTJF5wVF8VYGHY,2121
-regent_httpsig/sfv.py,sha256=zTxPf2f0XdSu3yKl3rw_CV4_Gbpl1ZJzOM_IA9nM7H0,7076
-regent_httpsig/sign.py,sha256=B5ChxFxuuKL0i10bGrgFImzyh8GMjWIqNDECXehBWTA,4397
-regent_httpsig/verify.py,sha256=8z-x3trF5B8P8D1aDYoqzF4R5h8BVv91CKiubFKFIiI,19915
-regent_httpsig-0.3.0.dist-info/METADATA,sha256=T0gBVK2_fZOYuWj_5ZlIYH5WJk7nn9RbmG-uWAFzcqM,10439
-regent_httpsig-0.3.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-regent_httpsig-0.3.0.dist-info/entry_points.txt,sha256=SgZdmc27V14IAmwOjbBoCYLsbrALaqdTUHNHLbil2dU,59
-regent_httpsig-0.3.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-regent_httpsig-0.3.0.dist-info/RECORD,,