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

regent_httpsig/__init__.py

@@ -4,26 +4,44 @@ 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.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",
+    "build_aauth_budget_header",
+    "build_aauth_requirement",
     "generate_seed",
     "jwk_thumbprint",
     "load_ed25519_jwk",

regent_httpsig/budget.py

@@ -0,0 +1,248 @@
+"""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 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
+
+
+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) -> None:
+        self._pools: dict[MeterKey, _Pool] = {}
+        self._lock = asyncio.Lock()
+        self._rids = itertools.count(1)
+        self._reservation_ttl = reservation_ttl
+        self._retention = retention_seconds
+
+    # ── 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]
+        # 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
+            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)
+
+    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,192 @@ 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,
+            )
+
+        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
+        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
+
+    # ── 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,
+    ) -> 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)
+
+    def _refusal(
+        self, *, reason: str | None, envelope: BudgetClaim | None,
+        remaining: int | None, key: MeterKey | None = None,
+        resource_token: str | 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, 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,51 @@ 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,
+    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."""
+    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 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/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.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: regent-httpsig
-Version: 0.2.0
+Version: 0.3.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,36 @@ 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).
+
 ## Security model (what a naive implementation gets wrong)
 
 The verifier fetches key directories from **attacker-nameable origins** — whoever signs a

regent_httpsig-0.3.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+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,,

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,,