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

regent_httpsig/__init__.py

@@ -4,26 +4,58 @@ Web Bot Auth (what OpenAI ships, what Cloudflare/AWS/Google verify) and AAuth
 (draft-hardt), in plain Python. See https://github.com/regent-protocol/regent-httpsig
 """
 
+from regent_httpsig.budget import (
+    BudgetClaim,
+    InMemoryMeter,
+    InsufficientBudget,
+    InvalidBudgetClaim,
+    UnitMismatch,
+)
 from regent_httpsig.config import HttpsigConfig
 from regent_httpsig.jwk import b64url, jwk_thumbprint, load_ed25519_jwk
 from regent_httpsig.netguard import NotPublicURL, assert_public_url
-from regent_httpsig.sfv import parse_signature_agent
+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,
+    parse_signature_agent,
+)
 from regent_httpsig.sign import DIRECTORY_MEDIA_TYPE, EgressSigner, generate_seed
 from regent_httpsig.verify import WBA_TAG, HttpsigVerifier, VerifiedSignature
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 __all__ = [
     "DIRECTORY_MEDIA_TYPE",
+    "BudgetClaim",
     "EgressSigner",
     "HttpsigConfig",
     "HttpsigVerifier",
+    "InMemoryMeter",
+    "InsufficientBudget",
+    "InvalidBudgetClaim",
     "NotPublicURL",
+    "UnitMismatch",
     "VerifiedSignature",
     "WBA_TAG",
     "__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",
     "jwk_thumbprint",
     "load_ed25519_jwk",

regent_httpsig/budget.py

@@ -0,0 +1,345 @@
+"""AAuth Budgets (draft-hardt-aauth-budgets, editor's copy) — resource-side core.
+
+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.
+
+Everything here is framework-free; the FastAPI glue lives in
+:mod:`regent_httpsig.fastapi` (``BudgetMiddleware``).
+"""
+
+from __future__ import annotations
+
+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
+
+__all__ = [
+    "BudgetClaim",
+    "InMemoryMeter",
+    "InsufficientBudget",
+    "InvalidBudgetClaim",
+    "Reservation",
+    "UnitMismatch",
+]
+
+MeterKey = tuple[str, str, str]  # (iss, sub, aud) — the draft's aggregation key
+
+
+class InvalidBudgetClaim(ValueError):
+    """A ``budget`` member is present but malformed (issuer bug — not spendable)."""
+
+
+class UnitMismatch(ValueError):
+    """A grant's unit/decimals differ from the pool's — one envelope, one unit."""
+
+
+@dataclass(frozen=True)
+class BudgetClaim:
+    """The ``budget`` claim: integer amount in ``unit`` scaled by ``decimals``.
+
+    ``amount=5000000, unit="USD", decimals=6`` is $5.00 — all arithmetic stays
+    in integers; the scale only matters at display time.
+    """
+
+    amount: int
+    unit: str
+    decimals: int
+
+    @staticmethod
+    def parse(claims: Mapping[str, Any]) -> BudgetClaim | None:
+        """Extract the claim from a token's claim set. ``None`` when absent;
+        :class:`InvalidBudgetClaim` when present but malformed (all three
+        members are REQUIRED, integers must be non-negative, bools are not
+        integers here)."""
+        raw = claims.get("budget")
+        if raw is None:
+            return None
+        if not isinstance(raw, Mapping):
+            raise InvalidBudgetClaim("budget claim must be an object")
+        amount, unit, decimals = raw.get("amount"), raw.get("unit"), raw.get("decimals")
+        if (
+            isinstance(amount, bool) or not isinstance(amount, int) or amount < 0
+            or not isinstance(unit, str) or not unit
+            or isinstance(decimals, bool) or not isinstance(decimals, int) or decimals < 0
+        ):
+            raise InvalidBudgetClaim("budget claim requires amount/unit/decimals")
+        return BudgetClaim(amount=amount, unit=unit, decimals=decimals)
+
+
+@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."""
+
+    rid: int
+    key: MeterKey
+    jti: str
+    amount: int
+
+
+@dataclass(frozen=True)
+class InsufficientBudget:
+    """Refusal: the request's maximum cost exceeds the pool's remaining balance.
+    ``exhausted`` distinguishes the draft's two reason tokens: an empty envelope
+    (``budget-exhausted``) vs a too-expensive request (``insufficient-budget``)."""
+
+    remaining: int
+    exhausted: bool
+
+
+@dataclass
+class _Pool:
+    unit: str
+    decimals: int
+    grants: dict[str, tuple[int, float]] = field(default_factory=dict)  # jti -> (amount, exp)
+    consumed: dict[str, int] = field(default_factory=dict)  # jti -> total committed
+    jkt_of: dict[str, str] = field(default_factory=dict)  # jti -> presenting key thumbprint
+    reservations: dict[int, tuple[str, int, float]] = field(default_factory=dict)
+    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.
+
+    Crash-safety is conservative: a reservation not committed or released within
+    ``reservation_ttl`` seconds is treated as fully consumed — the owner's
+    envelope is never silently under-counted by a crashed handler.
+    """
+
+    def __init__(self, *, reservation_ttl: float = 120.0,
+                 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) ──────────────────────────────────────────
+
+    def _purge(self, key: MeterKey, now: float) -> _Pool | None:
+        pool = self._pools.get(key)
+        if pool is None:
+            return None
+        # Expired, unresolved reservations count as consumed (conservative).
+        for rid, (jti, amount, deadline) in list(pool.reservations.items()):
+            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()):
+            if exp <= now:
+                del pool.grants[jti]
+        if (not pool.grants and not pool.reservations
+                and now - pool.last_activity > self._retention):
+            del self._pools[key]
+            return None
+        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)
+
+    # ── 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 —
+        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 —
+        one envelope, one unit, no FX at the meter."""
+        async with self._lock:
+            now = time.monotonic()
+            wall_delta = exp - time.time()
+            pool = self._purge(key, now)
+            if pool is None:
+                pool = self._pools.setdefault(
+                    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"grant is {claim.unit}/{claim.decimals}")
+            pool.last_activity = now
+            if jkt:
+                pool.jkt_of.setdefault(jti, jkt)
+            if jti not in pool.grants and wall_delta > 0:
+                pool.grants[jti] = (claim.amount, now + wall_delta)
+
+    async def reserve(self, key: MeterKey, jti: str,
+                      max_cost: int) -> Reservation | InsufficientBudget:
+        async with self._lock:
+            now = time.monotonic()
+            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)
+            if max_cost > remaining:
+                return InsufficientBudget(remaining=remaining,
+                                          exhausted=remaining == 0)
+            rid = next(self._rids)
+            pool.reservations[rid] = (jti, max_cost, now + self._reservation_ttl)
+            pool.last_activity = now
+            return Reservation(rid=rid, key=key, jti=jti, amount=max_cost)
+
+    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."""
+        async with self._lock:
+            now = time.monotonic()
+            pool = self._purge(res.key, now)
+            if pool is None:
+                return 0
+            held = pool.reservations.pop(res.rid, None)
+            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
+            if cost > 0:
+                self._record_usage(res.key, pool, res.jti, cost)
+            return self._remaining(pool)
+
+    async def release(self, res: Reservation) -> int:
+        async with self._lock:
+            pool = self._purge(res.key, time.monotonic())
+            if pool is None:
+                return 0
+            pool.reservations.pop(res.rid, None)
+            return self._remaining(pool)
+
+    async def remaining(self, key: MeterKey) -> int:
+        async with self._lock:
+            pool = self._purge(key, time.monotonic())
+            return 0 if pool is None else self._remaining(pool)
+
+    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_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.
+
+        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
+        its siblings' (privacy between a principal's agents, and no extra
+        figures to infer the ceiling from). Consequence: an abandoned agent's
+        records are never carried home by siblings — the PS-side conservative
+        rule (unreported expired allocation = fully consumed) is the backstop."""
+        async with self._lock:
+            pool = self._purge(key, time.monotonic())
+            if pool is None:
+                return []
+            return [
+                {"jti": jti, "consumed": total}
+                for jti, total in sorted(pool.consumed.items())
+                if total > 0 and (jkt is None or pool.jkt_of.get(jti) == jkt)
+            ]

regent_httpsig/config.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from dataclasses import dataclass, field
 
 __all__ = ["HttpsigConfig"]
@@ -38,3 +39,9 @@ class HttpsigConfig:
     # AAuth person tokens — their `aud` must name this resource. None disables
     # the person-token path entirely.
     resource_url: str | None = None
+    # AAuth auth tokens (typ "aa-auth+jwt" — the carrier of budget envelopes):
+    # issuer → JWKS URL for each Person Server this resource accepts auth tokens
+    # from. A resource has an established relationship with its PS, so the key
+    # location is pinned by configuration rather than discovered open-world.
+    # Empty (the default) disables the auth-token path entirely.
+    trusted_ps: Mapping[str, str] = field(default_factory=dict)

regent_httpsig/fastapi.py

@@ -25,13 +25,37 @@ $scheme;``), or verification will fail on the scheme mismatch.
 
 from __future__ import annotations
 
-from fastapi import Depends, FastAPI, HTTPException, Request
+import inspect
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Any
 
+from fastapi import Depends, FastAPI, HTTPException, Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.responses import JSONResponse
+
+from regent_httpsig.budget import (
+    BudgetClaim,
+    InMemoryMeter,
+    InsufficientBudget,
+    InvalidBudgetClaim,
+    MeterKey,
+    Reservation,
+    UnitMismatch,
+)
+from regent_httpsig.sfv import build_aauth_budget_header, build_aauth_requirement
 from regent_httpsig.verify import HttpsigVerifier, VerifiedSignature
 
-__all__ = ["RequiredSignatureDep", "SignatureDep", "VerifiedSignature", "attach"]
+__all__ = [
+    "BudgetMiddleware",
+    "RequiredSignatureDep",
+    "SignatureDep",
+    "VerifiedSignature",
+    "attach",
+]
 
 _STATE_ATTR = "regent_httpsig_verifier"
+logger = logging.getLogger("regent_httpsig")
 
 
 def attach(app: FastAPI, verifier: HttpsigVerifier) -> None:
@@ -92,3 +116,243 @@ async def require_signature(request: Request) -> VerifiedSignature:
 
 SignatureDep = Depends(get_signature)
 RequiredSignatureDep = Depends(require_signature)
+
+
+# ── AAuth Budgets enforcement (draft-hardt-aauth-budgets) ────────────────────
+
+PriceFn = Callable[[Request], "int | None | Awaitable[int | None]"]
+ResourceTokenProvider = Callable[
+    [MeterKey, "list[dict[str, Any]]"], "str | None | Awaitable[str | None]"
+]
+
+
+async def _maybe_await(value: Any) -> Any:
+    return await value if inspect.isawaitable(value) else value
+
+
+class BudgetMiddleware(BaseHTTPMiddleware):
+    """Meter budget-carrying requests: reserve the maximum cost atomically,
+    serve, commit the actual, release the difference, and answer with an
+    ``AAuth-Budget`` header. The full checklist a resource owes the draft —
+    pricing excepted, which is the one thing only the resource can know.
+
+    Usage::
+
+        meter = InMemoryMeter()
+        app.add_middleware(
+            BudgetMiddleware,
+            verifier=HttpsigVerifier(HttpsigConfig(
+                resource_url="https://api.example",
+                trusted_ps={"https://ps.example": "https://ps.example/jwks.json"},
+            )),
+            meter=meter,
+            price_fn=lambda request: PRICES.get(request.url.path),
+        )
+
+    - ``price_fn(request)`` returns the request's MAXIMUM cost in the envelope's
+      minor units, or ``None`` for routes outside budget enforcement.
+    - A handler that knows the actual cost sets ``request.state.budget_cost``
+      before returning; otherwise the full reservation is committed.
+    - ``require=False`` (default) lets requests without a budget envelope pass
+      through untouched — run per-decision authorization for them instead.
+      ``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.
+    """
+
+    def __init__(
+        self,
+        app: Any,
+        *,
+        verifier: HttpsigVerifier,
+        meter: InMemoryMeter | Any = None,
+        price_fn: PriceFn,
+        require: bool = False,
+        resource_token_provider: ResourceTokenProvider | None = None,
+    ) -> None:
+        super().__init__(app)
+        self._verifier = verifier
+        self._meter = meter if meter is not None else InMemoryMeter()
+        self._price_fn = price_fn
+        self._require = require
+        self._resource_token = resource_token_provider
+
+    async def dispatch(
+        self, request: Request, call_next: RequestResponseEndpoint
+    ) -> Response:
+        max_cost = await _maybe_await(self._price_fn(request))
+        if max_cost is None:
+            return await call_next(request)
+
+        sig = await self._verified(request)
+        envelope: BudgetClaim | None = None
+        if sig is not None:
+            try:
+                envelope = BudgetClaim.parse(sig.claims)
+            except InvalidBudgetClaim as exc:
+                logger.warning("malformed budget claim from %s: %s", sig.agent, exc)
+        jti = str(sig.claims.get("jti") or "") if sig else ""
+
+        if sig is None or envelope is None or not jti:
+            if self._require:
+                return self._refusal(reason=None, envelope=None, remaining=None)
+            return await call_next(request)  # per-decision path handles it
+
+        key: MeterKey = (
+            str(sig.claims.get("iss", "")),
+            str(sig.claims.get("sub", "")),
+            str(sig.claims.get("aud", "")),
+        )
+        try:
+            # sig.keyid is the RFC 7638 thumbprint of the token's cnf key (jkt) —
+            # recorded so refusal-time consumption records are scoped to the
+            # presenting agent and never disclose its siblings' spending.
+            await self._meter.observe_grant(key, jti, envelope,
+                                            float(sig.claims.get("exp", 0)),
+                                            jkt=sig.keyid)
+        except UnitMismatch as exc:
+            logger.warning("budget unit mismatch for %s: %s", key, exc)
+            return self._refusal(reason="insufficient-budget", envelope=envelope,
+                                 remaining=0, key=key)
+
+        outcome = await self._meter.reserve(key, jti, int(max_cost))
+        if isinstance(outcome, InsufficientBudget):
+            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,
+                # `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
+        try:
+            response = await call_next(request)
+        except Exception:
+            await self._meter.release(reservation)
+            raise
+
+        if response.status_code >= 400:
+            # 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)
+            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)
+            remaining = await self._meter.commit(reservation, cost)
+        response.headers["AAuth-Budget"] = build_aauth_budget_header(
+            remaining=remaining, cost=cost,
+            unit=envelope.unit, decimals=envelope.decimals,
+        )
+        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:
+        cached = getattr(request.state, "regent_httpsig_result", "unset")
+        if cached != "unset":
+            return cached  # type: ignore[return-value]
+        result = None
+        if "signature" in request.headers:
+            result = await self._verifier.verify(
+                request.method, _public_url(request), dict(request.headers)
+            )
+        request.state.regent_httpsig_result = result
+        return result
+
+    async def _refusal_with_token(
+        self, *, reason: str, envelope: BudgetClaim,
+        remaining: int, key: MeterKey, jkt: str | None = None,
+        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))
+            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,
+                             required=required)
+
+    def _refusal(
+        self, *, reason: str | None, envelope: BudgetClaim | None,
+        remaining: int | None, key: MeterKey | None = None,
+        resource_token: str | None = None, required: int | None = None,
+    ) -> Response:
+        headers = {
+            "AAuth-Requirement": build_aauth_requirement(
+                reason=reason or "insufficient-budget",
+                resource_token=resource_token,
+            )
+        }
+        if remaining is not None and envelope is not None:
+            headers["AAuth-Budget"] = build_aauth_budget_header(
+                remaining=remaining, required=required,
+                unit=envelope.unit, decimals=envelope.decimals,
+            )
+        code = "AUTH_TOKEN_REQUIRED" if reason is None else reason.upper().replace("-", "_")
+        return JSONResponse(
+            status_code=401,
+            content={
+                "code": code,
+                "message": (
+                    "Present an auth token with a budget envelope "
+                    "(AAuth Budgets) to call this endpoint."
+                    if reason is None else
+                    "The request's maximum cost exceeds the envelope's remaining "
+                    "balance. Re-authorize with your PS for a fresh auth token."
+                ),
+            },
+            headers=headers,
+        )

regent_httpsig/sfv.py

@@ -32,6 +32,8 @@ __all__ = [
     "SFDictionary",
     "SFItem",
     "StaticKeyResolver",
+    "build_aauth_budget_header",
+    "build_aauth_requirement",
     "parse_signature_agent",
     "parse_signature_key_header",
 ]
@@ -130,3 +132,57 @@ def parse_signature_key_header(value: str) -> tuple[str, str] | None:
     except Exception:  # noqa: BLE001
         return None
     return None
+
+
+# ── AAuth Budgets response headers (draft-hardt-aauth-budgets) ───────────────
+# Hand-serialized: the value space is tiny (non-negative sf-integers, one
+# sf-string, sf-tokens) and the golden tests round-trip the output through the
+# real http_sfv parser. NOTE: the field is declared an RFC 9651 *Dictionary*,
+# so members are comma-separated — the draft's §11 example shows semicolons,
+# which is the *parameter* separator; flagged for the implementation report.
+
+
+def _sf_string(value: str) -> str:
+    return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+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`` 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] = []
+    if cost is not None:
+        members.append(f"cost={cost}")
+    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}")
+    return ", ".join(members)
+
+
+def build_aauth_requirement(*, reason: str, resource_token: str | None = None) -> str:
+    """Serialize ``AAuth-Requirement`` for a budget refusal:
+    ``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."""
+    out = "requirement=auth-token"
+    if resource_token:
+        out += f";resource-token={_sf_string(resource_token)}"
+    out += f";reason={reason}"
+    return out

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/verify.py

@@ -58,7 +58,8 @@ AAUTH_METADATA_PATH = "/.well-known/aauth-agent.json"
 AAUTH_PERSON_METADATA_PATH = "/.well-known/aauth-person.json"
 AAUTH_JWT_TYP = "aa-agent+jwt"
 AAUTH_PERSON_TYP = "aa-person+jwt"
-# -11: a person token "lives at most one hour" — enforced with a small tolerance.
+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
 
 
@@ -311,9 +312,11 @@ class HttpsigVerifier:
         if header.get("alg") in (None, "none"):
             return None
 
-        # -11 token-type dispatch: agent tokens (identity mode) and person tokens
-        # (PS-issued, per-resource, opt-in via config.resource_url).
+        # -11 token-type dispatch: agent tokens (identity mode), person tokens
+        # (PS-issued, per-resource, opt-in via config.resource_url) and auth
+        # tokens (PS-issued budget carriers, opt-in via config.trusted_ps).
         typ = header.get("typ")
+        jwks_override: str | None = None
         if typ == AAUTH_JWT_TYP:
             scheme, expected_dwk = "aauth", "aauth-agent.json"
             metadata_path, audience = AAUTH_METADATA_PATH, None
@@ -324,15 +327,32 @@ class HttpsigVerifier:
                 return None
             scheme, expected_dwk = "aauth-person", "aauth-person.json"
             metadata_path, audience = AAUTH_PERSON_METADATA_PATH, self.config.resource_url
+        elif typ == AAUTH_AUTH_TYP:
+            if not self.config.resource_url or not self.config.trusted_ps:
+                logger.info("auth token presented but resource_url/trusted_ps is not "
+                            "configured — auth-token verification is disabled")
+                return None
+            scheme, expected_dwk = "aauth-auth", None
+            metadata_path, audience = None, self.config.resource_url
         else:
             return None
 
         iss = str(unverified.get("iss", ""))
-        bad_iss = unverified.get("dwk") != expected_dwk or not iss.startswith("https://")
-        if bad_iss and not (
-            iss and urlsplit(iss).hostname in self.config.insecure_hosts  # dev escape
-        ):
-            return None
+        if typ == AAUTH_AUTH_TYP:
+            # The resource pins its PS: issuer must be explicitly trusted and its
+            # JWKS location comes from configuration, not open-world discovery.
+            override = self.config.trusted_ps.get(iss)
+            if override is None:
+                logger.info("auth token issuer %s is not a configured PS", iss[:100])
+                return None
+            jwks_override = override
+        else:
+            bad_iss = (unverified.get("dwk") != expected_dwk
+                       or not iss.startswith("https://"))
+            if bad_iss and not (
+                iss and urlsplit(iss).hostname in self.config.insecure_hosts  # dev escape
+            ):
+                return None
 
         # AAuth -11 / RFC 9864: fully-specified algorithms. "EdDSA" (polymorphic)
         # is accepted only while require_fully_specified_algs is False — a
@@ -342,10 +362,13 @@ class HttpsigVerifier:
             allowed_algs.append("EdDSA")
 
         # 1) Verify the token against the issuer's published JWKS.
-        metadata = await self._fetch_json(iss.rstrip("/") + metadata_path)
-        if not metadata or not metadata.get("jwks_uri"):
-            return None
-        jwks = await self._fetch_json(str(metadata["jwks_uri"]))
+        if jwks_override is not None:
+            jwks = await self._fetch_json(jwks_override)
+        else:
+            metadata = await self._fetch_json(iss.rstrip("/") + str(metadata_path))
+            if not metadata or not metadata.get("jwks_uri"):
+                return None
+            jwks = await self._fetch_json(str(metadata["jwks_uri"]))
         if not jwks:
             return None
         issuer_key = None
@@ -379,11 +402,11 @@ class HttpsigVerifier:
             logger.info("aauth token invalid iss=%s: %s", iss, str(exc)[:200])
             return None
 
-        # -11: a person token "lives at most one hour".
-        if typ == AAUTH_PERSON_TYP:
+        # -11: person and auth tokens live at most one hour.
+        if typ in (AAUTH_PERSON_TYP, AAUTH_AUTH_TYP):
             lifetime = int(claims.get("exp", 0)) - int(claims.get("iat", 0))
             if lifetime <= 0 or lifetime > PERSON_TOKEN_MAX_LIFETIME:
-                logger.info("person token lifetime %ss out of bounds iss=%s", lifetime, iss)
+                logger.info("%s lifetime %ss out of bounds iss=%s", typ, lifetime, iss)
                 return None
 
         # 2) Proof of possession: the request signature must verify against cnf.jwk.
@@ -423,12 +446,14 @@ class HttpsigVerifier:
             scheme=scheme,
             agent=iss,
             keyid=jwk_thumbprint(cnf_jwk),
-            trusted=iss in self.config.trusted_agents,
+            # An auth-token issuer is by definition a configured, trusted PS.
+            trusted=iss in self.config.trusted_agents or typ == AAUTH_AUTH_TYP,
             sub=str(claims.get("sub", "")),
             label=label,
             claims={
                 k: claims[k]
-                for k in ("iss", "sub", "exp", "ps", "aud", "jti", "mission_s256")
+                for k in ("iss", "sub", "exp", "ps", "aud", "jti", "mission_s256",
+                          "budget")  # budgets: the envelope rides in the token
                 if k in claims
             },
         )

{regent_httpsig-0.2.0.dist-info → regent_httpsig-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: regent-httpsig
-Version: 0.2.0
+Version: 0.4.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
@@ -138,6 +138,72 @@ keyid-less shape is pinned in CI.
   [christian-posta/aauth-python-library](https://github.com/christian-posta/aauth-python-library) —
   this library is the thin relying-party verifier that handles both dialects.
 
+## Budgets: meter a spending envelope (draft-hardt-aauth-budgets)
+
+An agent can carry a PS-issued **auth token** (`typ: aa-auth+jwt`) with a
+`budget` claim — a spending envelope it uses offline, no per-call round trip
+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):
+
+```python
+from regent_httpsig import HttpsigConfig, HttpsigVerifier, InMemoryMeter
+from regent_httpsig.fastapi import BudgetMiddleware
+
+app.add_middleware(
+    BudgetMiddleware,
+    verifier=HttpsigVerifier(HttpsigConfig(
+        resource_url="https://api.example",
+        trusted_ps={"my-ps": "https://ps.example/jwks.json"},
+    )),
+    meter=InMemoryMeter(),
+    price_fn=lambda request: PRICES.get(request.url.path),  # max cost, minor units
+)
+```
+
+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.4.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+regent_httpsig/__init__.py,sha256=Ch-PdsMDo_uKG4U5A4xklU3jbCWdJTWXHG86n5VA7dc,1709
+regent_httpsig/budget.py,sha256=RfasLL3HAdLt5kJ2L8DeGoA3FaVXe94LIn1nzboWYKA,15095
+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/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.2.0.dist-info/RECORD

@@ -1,14 +0,0 @@
-regent_httpsig/__init__.py,sha256=9TWY0NncSbLGXq4mosCKEB1SGKHcIPOpYgAyOzPp_7Y,987
-regent_httpsig/cli.py,sha256=WUSLQ2WuEX4E85L2C2EgoUfu5cWpj6MRSG1UVNHpzcw,2005
-regent_httpsig/config.py,sha256=dGWzZtS5DhCr59ecR3scX-JdHD4iZ4XFcioejz2KXDA,1954
-regent_httpsig/fastapi.py,sha256=YmfrKdeMft2vpuiRlivIEHYC4BIs3ioR7T3t1ZEzcJ4,3707
-regent_httpsig/jwk.py,sha256=h4vgnIgpnyKeWdWpm7g_hEyXZOPVREWn-bD4JN07tT0,1637
-regent_httpsig/netguard.py,sha256=Sqg08mdC94RWvnQLJaH4weZW0nN2VlTJF5wVF8VYGHY,2121
-regent_httpsig/sfv.py,sha256=kcQsBLw9h4h_6D3z2rv0-3_gLZQYC47B9VZi-oS_Vgk,4975
-regent_httpsig/sign.py,sha256=B5ChxFxuuKL0i10bGrgFImzyh8GMjWIqNDECXehBWTA,4397
-regent_httpsig/verify.py,sha256=nMSOc1hY29X4SW2g9SD9LwLXt6ladBI7-iUU-1bYpwA,18461
-regent_httpsig-0.2.0.dist-info/METADATA,sha256=76bz3NCU5pNPZfPWg-URUmeFvJjqOd-vIlpM03aFXEU,9129
-regent_httpsig-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-regent_httpsig-0.2.0.dist-info/entry_points.txt,sha256=SgZdmc27V14IAmwOjbBoCYLsbrALaqdTUHNHLbil2dU,59
-regent_httpsig-0.2.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-regent_httpsig-0.2.0.dist-info/RECORD,,