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

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

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.4.0
+
+**AAuth Budgets — the August 20 editor's-copy additions** (allocation model,
+omitted cost, `required`, usage counters):
+
+- **`required` member**: an `insufficient-budget` refusal now carries the
+  refused request's maximum cost in `AAuth-Budget`, so the agent's retry is a
+  calculation (fit the bound to `remaining`) rather than a search.
+- **Streaming / cost-omitted** (§cost-omitted): a streamed response states
+  `reserved` (REQUIRED when `cost` is omitted) with `remaining` already net of
+  the hold, commits when the stream ends (`request.state.budget_cost` may be
+  set mid-stream), and the agent recovers the exact figure from the next
+  response's `remaining`. SSE is recognized automatically; other streams opt
+  in with `request.state.budget_streaming = True`.
+- **Usage endpoint** (§Usage Counters): `make_usage_endpoint(meter, …)` —
+  scope queries (`sub` calendar counters: day/week/month/year/all_time on UTC
+  boundaries) and per-key `jkts` queries; unrecognized scope values omit
+  `usage` (never zero — a query must not reveal whether an account exists);
+  unrecognized/pruned thumbprints are omitted from `jkts` (never zero — a
+  false zero misleads an allocation decision); per-key figures pruned on 24h
+  IDLE, so a key in continuous use is never pruned; figures keyed by the
+  issuing PS, so the endpoint structurally answers only the party whose
+  tokens were accepted. PS authentication is pluggable (`authenticate_ps`).
+- **Signed usage responses** (§The Signed Response): `ResponseSigner` — an
+  Ed25519 HTTP Sig over `@status`, `content-type`, `content-digest`, bound to
+  the request via `@authority`/`@path` with the `req` parameter.
+- **`validate_budget_grant`**: the §Resource Metadata MUSTs (only declared
+  units; declared decimals) as a pre-mint guard against the draft's
+  "thousandfold error".
+
 ## 0.3.0
 
 **AAuth Budgets** (draft-hardt-aauth-budgets, editor's copy) — the resource

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: regent-httpsig
-Version: 0.3.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
@@ -168,6 +168,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.3.0 → regent_httpsig-0.4.0}/README.md

@@ -138,6 +138,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.3.0 → regent_httpsig-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "regent-httpsig"
-version = "0.3.0"
+version = "0.4.0"
 description = "Verify and sign AI agent HTTP traffic in Python — RFC 9421 HTTP Message Signatures: Web Bot Auth (what OpenAI ships) and AAuth."
 readme = "README.md"
 license = "Apache-2.0"

{regent_httpsig-0.3.0 → regent_httpsig-0.4.0}/src/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-0.3.0 → regent_httpsig-0.4.0}/src/regent_httpsig/budget.py

@@ -21,6 +21,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
 
@@ -109,6 +110,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 +162,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 +191,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()):
@@ -210,6 +265,8 @@ 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
+            if cost > 0:
+                self._record_usage(res.key, pool, res.jti, cost)
             return self._remaining(pool)
 
     async def release(self, res: Reservation) -> int:
@@ -225,6 +282,46 @@ class InMemoryMeter:
             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``

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

@@ -224,6 +224,9 @@ class BudgetMiddleware(BaseHTTPMiddleware):
             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
@@ -237,6 +240,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)
+            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 +265,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:
@@ -264,6 +312,7 @@ class BudgetMiddleware(BaseHTTPMiddleware):
     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:
@@ -273,12 +322,13 @@ class BudgetMiddleware(BaseHTTPMiddleware):
             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 +338,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-0.3.0 → regent_httpsig-0.4.0}/src/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-0.4.0/src/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 → regent_httpsig-0.4.0}/tests/test_budget.py

@@ -276,7 +276,8 @@ def _app(verifier: HttpsigVerifier, **mw_kwargs: Any) -> FastAPI:
     app.add_middleware(
         BudgetMiddleware,
         verifier=verifier,
-        price_fn=lambda request: 300 if request.url.path == "/v1/search" else None,
+        price_fn=lambda request: (
+            300 if request.url.path in ("/v1/search", "/v1/stream") else None),
         **mw_kwargs,
     )
 
@@ -293,6 +294,17 @@ def _app(verifier: HttpsigVerifier, **mw_kwargs: Any) -> FastAPI:
     async def free() -> dict[str, bool]:
         return {"ok": True}
 
+    @app.post("/v1/stream")
+    async def stream(request: Request):  # type: ignore[no-untyped-def]
+        from starlette.responses import StreamingResponse
+
+        async def gen():  # type: ignore[no-untyped-def]
+            yield b"data: one\n\n"
+            request.state.budget_cost = 120  # actual, learned mid-stream
+            yield b"data: two\n\n"
+
+        return StreamingResponse(gen(), media_type="text/event-stream")
+
     return app
 
 
@@ -365,7 +377,8 @@ async def test_middleware_refuses_when_insufficient(
     assert (r2.headers["AAuth-Requirement"] ==
             'requirement=auth-token;resource-token="resource.token.here"'
             ";reason=insufficient-budget")
-    assert r2.headers["AAuth-Budget"] == 'remaining=200, unit="KZT", decimals=2'
+    assert (r2.headers["AAuth-Budget"] ==
+            'remaining=200, required=300, unit="KZT", decimals=2')
     assert provider_calls and provider_calls[0][0] == (PS_ISS, "owner-1", RESOURCE)
     assert provider_calls[0][1] == [{"jti": "at-1", "consumed": 300}]
 
@@ -447,3 +460,30 @@ async def test_middleware_releases_on_error_response(
     assert r.status_code == 422
     # Nothing served → envelope not charged.
     assert r.headers["AAuth-Budget"] == 'cost=0, remaining=1000, unit="KZT", decimals=2'
+
+
+async def test_streaming_cost_omitted_reserved_math(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """§cost-omitted: no trailer runtime — the header states `reserved` (and no
+    `cost`), `remaining` is net of the hold, and the agent recovers the exact
+    figure from the NEXT response: prev remaining + reserved − next remaining."""
+    ps_priv, ps_jwk = _ps_pair()
+    agent = EgressSigner(seed=generate_seed(), signature_agent=PS_ISS)
+    token = _auth_token(ps_priv, agent, amount=1000)
+    app = _app(_verifier(ps_jwk, monkeypatch))
+
+    r1 = await _post(app, "/v1/stream", _signed_headers(agent, token, "/v1/stream"))
+    assert r1.status_code == 200
+    d1 = SFDictionary(); d1.parse(r1.headers["AAuth-Budget"].encode())
+    assert "cost" not in d1                      # omitted — no trailer runtime
+    assert int(str(d1["reserved"].value)) == 300  # REQUIRED when cost omitted
+    assert int(str(d1["remaining"].value)) == 700  # net of the hold
+    assert r1.text.count("data:") == 2
+
+    # Stream ended → the actual 120 was committed, 180 returned to the grant.
+    r2 = await _post(app, "/v1/search", _signed_headers(agent, token, "/v1/search"))
+    d2 = SFDictionary(); d2.parse(r2.headers["AAuth-Budget"].encode())
+    next_remaining = int(str(d2["remaining"].value)) + 300  # add back r2's own cost
+    recovered = 1000 + 300 - 700 - (1000 - next_remaining)  # draft's subtraction…
+    assert 700 + 300 - next_remaining == 120     # …prev + reserved − next = cost

regent_httpsig-0.4.0/tests/test_usage.py

@@ -0,0 +1,231 @@
+"""AAuth Budgets §Usage Counters + the Aug-20 additions (required, streaming).
+
+Every rule these tests pin comes with the draft's reasoning in the test name
+or a comment — they double as our conformance notes.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import time
+from typing import Any
+
+import pytest
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+from fastapi import FastAPI, Request
+from starlette.testclient import TestClient
+
+from regent_httpsig import (
+    BudgetClaim,
+    InMemoryMeter,
+    ResponseSigner,
+    UsageQueryError,
+    build_aauth_budget_header,
+    build_usage_response,
+    make_usage_endpoint,
+    parse_usage_request,
+)
+from regent_httpsig.budget import MeterKey
+from regent_httpsig.jwk import b64url, b64url_decode
+from regent_httpsig.sfv import SFDictionary
+
+KEY: MeterKey = ("https://ps.example", "sub-1", "https://api.example")
+CLAIM = BudgetClaim.parse({"budget": {"amount": 10_000, "unit": "USD", "decimals": 2}})
+JKT_A = "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs"
+JKT_B = "0ZcOCORZNYy-DWpqq30BbmLzO1Yw3ZQhIgnHZQKxNVE"
+
+
+async def _spend(meter: InMemoryMeter, jti: str, jkt: str, cost: int) -> None:
+    await meter.observe_grant(KEY, jti, CLAIM, time.time() + 3600, jkt=jkt)
+    res = await meter.reserve(KEY, jti, cost)
+    await meter.commit(res, cost)
+
+
+# ── required member (header) ─────────────────────────────────────────────────
+
+def test_header_golden_with_required() -> None:
+    out = build_aauth_budget_header(remaining=300, required=750,
+                                    unit="USD", decimals=2)
+    assert out == 'remaining=300, required=750, unit="USD", decimals=2'
+    parsed = SFDictionary()
+    parsed.parse(out.encode())
+    assert int(parsed["required"].value) == 750  # real SFV parser round-trip
+
+
+def test_header_member_order_is_the_drafts() -> None:
+    out = build_aauth_budget_header(remaining=1, cost=2, reserved=3, required=4)
+    assert out == "cost=2, remaining=1, reserved=3, required=4"
+
+
+# ── usage request validation (§usage-request) ────────────────────────────────
+
+def test_query_two_scope_keys_is_an_error() -> None:
+    with pytest.raises(UsageQueryError):
+        parse_usage_request({"sub": "s", "tenant": "t"})
+
+
+def test_query_neither_scope_nor_jkts_is_an_error() -> None:
+    with pytest.raises(UsageQueryError):
+        parse_usage_request({})
+
+
+def test_query_scope_and_jkts_may_both_appear() -> None:
+    scope_key, scope_value, jkts = parse_usage_request(
+        {"sub": "s", "jkts": [JKT_A]})
+    assert (scope_key, scope_value, jkts) == ("sub", "s", [JKT_A])
+
+
+# ── calendar counters + per-key figures ──────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_scope_counters_accumulate_and_echo() -> None:
+    meter = InMemoryMeter()
+    await _spend(meter, "jti-1", JKT_A, 400)
+    await _spend(meter, "jti-2", JKT_B, 100)
+    doc = await build_usage_response(
+        meter, iss=KEY[0], aud=KEY[0], unit="USD", decimals=2,
+        scope_key="sub", scope_value="sub-1", jkts=[])
+    assert doc["sub"] == "sub-1"
+    assert doc["usage"]["all_time"] == 500
+    assert doc["usage"]["day"] == 500  # committed just now, same UTC day
+    assert doc["unit"] == "USD" and doc["decimals"] == 2 and doc["aud"] == KEY[0]
+
+
+@pytest.mark.asyncio
+async def test_unknown_scope_value_omits_usage_not_zero() -> None:
+    """"Never seen" must be indistinguishable from "nothing consumed" — a
+    query cannot be used to discover whether a person holds an account."""
+    meter = InMemoryMeter()
+    doc = await build_usage_response(
+        meter, iss=KEY[0], aud=KEY[0], unit="USD", decimals=2,
+        scope_key="sub", scope_value="nobody", jkts=[])
+    assert "usage" not in doc and doc["sub"] == "nobody"
+
+
+@pytest.mark.asyncio
+async def test_per_key_totals_and_unknown_key_omitted() -> None:
+    """Unknown/pruned thumbprints are OMITTED, never zero: a present zero
+    would be a wrong answer to an allocation decision."""
+    meter = InMemoryMeter()
+    await _spend(meter, "jti-1", JKT_A, 400)
+    doc = await build_usage_response(
+        meter, iss=KEY[0], aud=KEY[0], unit="USD", decimals=2,
+        scope_key=None, scope_value=None, jkts=[JKT_A, JKT_B])
+    assert doc["jkts"] == {JKT_A: 400}
+
+
+@pytest.mark.asyncio
+async def test_per_key_pruned_on_idle_not_age() -> None:
+    meter = InMemoryMeter(usage_key_retention=0.05)
+    await _spend(meter, "jti-1", JKT_A, 100)
+    await asyncio.sleep(0.08)
+    assert await meter.usage_keys(KEY[0], [JKT_A]) == {}
+
+
+@pytest.mark.asyncio
+async def test_usage_scoped_to_the_calling_ps() -> None:
+    """The resource only answers for tokens the calling PS issued — figures
+    are keyed by iss, so another PS simply holds no records."""
+    meter = InMemoryMeter()
+    await _spend(meter, "jti-1", JKT_A, 400)
+    assert await meter.usage_keys("https://other-ps.example", [JKT_A]) == {}
+    assert await meter.usage_scope("https://other-ps.example", "sub-1") is None
+
+
+@pytest.mark.asyncio
+async def test_expired_reservation_reaches_usage_counters() -> None:
+    """The conservative rule (unresolved reservation = consumed) must show up
+    in usage too, or the PS's pull path would under-count a crashed handler."""
+    meter = InMemoryMeter(reservation_ttl=0.01)
+    await meter.observe_grant(KEY, "jti-1", CLAIM, time.time() + 3600, jkt=JKT_A)
+    await meter.reserve(KEY, "jti-1", 700)
+    await asyncio.sleep(0.02)
+    await meter.remaining(KEY)  # triggers the purge
+    assert (await meter.usage_keys(KEY[0], [JKT_A]))[JKT_A] == 700
+
+
+# ── the endpoint handler ─────────────────────────────────────────────────────
+
+def _app(meter: InMemoryMeter, iss: str | None,
+         signer: ResponseSigner | None = None) -> FastAPI:
+    async def auth(_request: Request) -> str | None:
+        return iss
+
+    handler = make_usage_endpoint(meter, authenticate_ps=auth,
+                                  unit="USD", decimals=2, signer=signer)
+    app = FastAPI()
+
+    @app.post("/usage")
+    async def usage(request: Request):  # type: ignore[no-untyped-def]
+        return await handler(request)
+
+    return app
+
+
+def test_endpoint_refuses_unauthenticated_ps() -> None:
+    client = TestClient(_app(InMemoryMeter(), iss=None))
+    assert client.post("/usage", json={"sub": "s"}).status_code == 401
+
+
+def test_endpoint_rejects_bad_query() -> None:
+    client = TestClient(_app(InMemoryMeter(), iss=KEY[0]))
+    r = client.post("/usage", json={"sub": "a", "tenant": "b"})
+    assert r.status_code == 400 and r.json()["code"] == "INVALID_USAGE_QUERY"
+
+
+@pytest.mark.asyncio
+async def test_endpoint_end_to_end_signed() -> None:
+    meter = InMemoryMeter()
+    await _spend(meter, "jti-1", JKT_A, 400)
+    seed = b64url(b"\x07" * 32)
+    signer = ResponseSigner(seed=seed, jwks_url="https://api.example/jwks.json")
+    client = TestClient(_app(meter, iss=KEY[0], signer=signer))
+    r = client.post("/usage", json={"sub": "sub-1", "jkts": [JKT_A, JKT_B]})
+    assert r.status_code == 200
+    doc = r.json()
+    assert doc["usage"]["all_time"] == 400 and doc["jkts"] == {JKT_A: 400}
+
+    # The signature covers @status/content-type/content-digest + the request's
+    # @authority/@path (req-bound) — verify it from scratch with the public key.
+    digest = "sha-256=:" + base64.b64encode(
+        __import__("hashlib").sha256(r.content).digest()).decode() + ":"
+    assert r.headers["content-digest"] == digest
+    inner = r.headers["signature-input"].split("=", 1)[1]
+    base = "\n".join([
+        '"@status": 200',
+        '"content-type": application/json',
+        f'"content-digest": {digest}',
+        '"@authority";req: testserver',
+        '"@path";req: /usage',
+        f'"@signature-params": {inner}',
+    ])
+    sig_b64 = r.headers["signature"].split("=", 1)[1].strip(":")
+    pub = Ed25519PublicKey.from_public_bytes(
+        b64url_decode(signer.public_jwk["x"]))
+    pub.verify(base64.b64decode(sig_b64), base.encode())  # raises on mismatch
+    assert 'jwks_uri="https://api.example/jwks.json"' in r.headers["signature-key"]
+
+
+def test_validate_budget_grant_enforces_declared_units() -> None:
+    units = [{"unit": "USD", "decimals": 6, "max": 10_000_000}]
+    from regent_httpsig import validate_budget_grant
+    validate_budget_grant("USD", 6, units)  # declared → fine
+    with pytest.raises(ValueError):
+        validate_budget_grant("USD", 2, units)  # the thousandfold error
+    with pytest.raises(ValueError):
+        validate_budget_grant("EUR", 2, units)  # undeclared unit
+
+
+def test_vectors_are_current() -> None:
+    """The published vectors must match what the code emits today."""
+    import pathlib
+    import subprocess
+    import sys
+    root = pathlib.Path(__file__).resolve().parent.parent
+    before = (root / "vectors" / "aauth-budgets-vectors.json").read_text()
+    subprocess.run([sys.executable, str(root / "vectors" / "generate.py")],
+                   check=True, capture_output=True)
+    after = (root / "vectors" / "aauth-budgets-vectors.json").read_text()
+    assert before == after

regent_httpsig-0.4.0/vectors/aauth-budgets-vectors.json

@@ -0,0 +1,124 @@
+{
+  "source": "regent-httpsig, first implementation of draft-hardt-aauth-budgets (editor's copy, 2026-08-20)",
+  "headers": {
+    "aauth_budget": [
+      {
+        "name": "success-with-cost",
+        "input": {
+          "remaining": 1568800,
+          "cost": 221200,
+          "unit": "USD",
+          "decimals": 6
+        },
+        "expected": "cost=221200, remaining=1568800, unit=\"USD\", decimals=6"
+      },
+      {
+        "name": "refusal-insufficient-with-required",
+        "note": "`required` rides only on insufficient-budget refusals: what THIS request needed, so the retry is a calculation.",
+        "input": {
+          "remaining": 300,
+          "required": 750,
+          "unit": "USD",
+          "decimals": 6
+        },
+        "expected": "remaining=300, required=750, unit=\"USD\", decimals=6"
+      },
+      {
+        "name": "streaming-cost-omitted",
+        "note": "No-trailer runtime: cost omitted, reserved REQUIRED, remaining already net of the hold. The agent recovers cost = prev remaining + reserved - next remaining.",
+        "input": {
+          "remaining": 1568800,
+          "reserved": 431200,
+          "unit": "USD",
+          "decimals": 6
+        },
+        "expected": "remaining=1568800, reserved=431200, unit=\"USD\", decimals=6"
+      },
+      {
+        "name": "exhaustion-zero",
+        "input": {
+          "remaining": 0,
+          "unit": "USD",
+          "decimals": 6
+        },
+        "expected": "remaining=0, unit=\"USD\", decimals=6"
+      }
+    ],
+    "aauth_requirement": [
+      {
+        "name": "refusal-with-resource-token",
+        "input": {
+          "reason": "budget-exhausted",
+          "resource_token": "eyJexample"
+        },
+        "expected": "requirement=auth-token;resource-token=\"eyJexample\";reason=budget-exhausted"
+      }
+    ]
+  },
+  "budget_claim": {
+    "shape": {
+      "amount": 5000000,
+      "unit": "USD",
+      "decimals": 6
+    },
+    "notes": [
+      "amount: non-negative integer, bounded by the 15-digit SF limit",
+      "decimals is NOT constrained to the ISO 4217 minor unit",
+      "all three members REQUIRED wherever `budget` appears"
+    ]
+  },
+  "consumption_records": {
+    "budget_consumed": [
+      {
+        "jti": "at-2",
+        "consumed": 431200
+      },
+      {
+        "jti": "at-1",
+        "consumed": 221200
+      }
+    ],
+    "notes": [
+      "two members and no more \u2014 the PS joins the rest from its ledger",
+      "records are scoped to the presenting agent's key (jkt): one agent never learns a sibling's spending",
+      "most recent first; SHOULD NOT exceed 20 records"
+    ]
+  },
+  "signed_usage_response": {
+    "signing_key": {
+      "seed_b64url": "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8",
+      "public_jwk": {
+        "kty": "OKP",
+        "crv": "Ed25519",
+        "x": "A6EHv_POEL4dcN0Y50vAmWfk1jCbpQ1fHdyGZBJVMbg"
+      },
+      "keyid_rfc7638": "1IG2tMH7J2wbJZnOf8LJzQitKf7LMvoAElsuDMVM54Y"
+    },
+    "request_context": {
+      "authority": "api.example",
+      "path": "/usage"
+    },
+    "body": {
+      "as_of": 1756500000,
+      "aud": "https://ps.example",
+      "unit": "USD",
+      "decimals": 6,
+      "sub": "8f14e45fceea167a5a36dedd4bea2543",
+      "usage": {
+        "day": 1243180,
+        "all_time": 61438050
+      },
+      "jkts": {
+        "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs": 38215600
+      }
+    },
+    "body_canonical_json": "{\"as_of\":1756500000,\"aud\":\"https://ps.example\",\"unit\":\"USD\",\"decimals\":6,\"sub\":\"8f14e45fceea167a5a36dedd4bea2543\",\"usage\":{\"day\":1243180,\"all_time\":61438050},\"jkts\":{\"NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs\":38215600}}",
+    "signature_base": "\"@status\": 200\n\"content-type\": application/json\n\"content-digest\": sha-256=:Jj+8+vDgDSFJryQMnASY9O2TEznYDi1lsJ/+DRo7s14=:\n\"@authority\";req: api.example\n\"@path\";req: /usage\n\"@signature-params\": (\"@status\" \"content-type\" \"content-digest\" \"@authority\";req \"@path\";req);created=1756500001",
+    "response_headers": {
+      "Content-Digest": "sha-256=:Jj+8+vDgDSFJryQMnASY9O2TEznYDi1lsJ/+DRo7s14=:",
+      "Signature-Input": "sig=(\"@status\" \"content-type\" \"content-digest\" \"@authority\";req \"@path\";req);created=1756500001",
+      "Signature": "sig=:tPyxKUn/9Grz7cMH0k6RIKjoy78KuoqkrMUZsocLi1UtWxFgqyKo0yANnu4TBlZm6593A9BzgoaUrv7mgFtUCA==:",
+      "Signature-Key": "sig=jwks_uri; jwks_uri=\"https://api.example/jwks.json\""
+    }
+  }
+}

regent_httpsig-0.4.0/vectors/generate.py

@@ -0,0 +1,157 @@
+"""Generate the AAuth Budgets test vectors (vectors/*.json).
+
+Deterministic by construction: fixed seeds, fixed timestamps. Re-run after any
+serialization change; the test suite pins the same bytes.
+
+    .venv/bin/python vectors/generate.py
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import pathlib
+import sys
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent / "src"))
+
+from regent_httpsig import ResponseSigner, build_aauth_budget_header  # noqa: E402
+from regent_httpsig.jwk import b64url  # noqa: E402
+from regent_httpsig.sfv import build_aauth_requirement  # noqa: E402
+
+OUT = pathlib.Path(__file__).resolve().parent
+
+
+def headers() -> dict:
+    """AAuth-Budget / AAuth-Requirement serializations. The field is an
+    RFC 9651 Dictionary — members are COMMA-separated (the draft's prose);
+    parameters inside AAuth-Requirement members use semicolons."""
+    cases = [
+        {
+            "name": "success-with-cost",
+            "input": {"remaining": 1568800, "cost": 221200,
+                      "unit": "USD", "decimals": 6},
+            "expected": build_aauth_budget_header(
+                remaining=1568800, cost=221200, unit="USD", decimals=6),
+        },
+        {
+            "name": "refusal-insufficient-with-required",
+            "note": "`required` rides only on insufficient-budget refusals: "
+                    "what THIS request needed, so the retry is a calculation.",
+            "input": {"remaining": 300, "required": 750,
+                      "unit": "USD", "decimals": 6},
+            "expected": build_aauth_budget_header(
+                remaining=300, required=750, unit="USD", decimals=6),
+        },
+        {
+            "name": "streaming-cost-omitted",
+            "note": "No-trailer runtime: cost omitted, reserved REQUIRED, "
+                    "remaining already net of the hold. The agent recovers "
+                    "cost = prev remaining + reserved - next remaining.",
+            "input": {"remaining": 1568800, "reserved": 431200,
+                      "unit": "USD", "decimals": 6},
+            "expected": build_aauth_budget_header(
+                remaining=1568800, reserved=431200, unit="USD", decimals=6),
+        },
+        {
+            "name": "exhaustion-zero",
+            "input": {"remaining": 0, "unit": "USD", "decimals": 6},
+            "expected": build_aauth_budget_header(
+                remaining=0, unit="USD", decimals=6),
+        },
+    ]
+    requirement = [
+        {
+            "name": "refusal-with-resource-token",
+            "input": {"reason": "budget-exhausted",
+                      "resource_token": "eyJexample"},
+            "expected": build_aauth_requirement(
+                reason="budget-exhausted", resource_token="eyJexample"),
+        },
+    ]
+    return {"aauth_budget": cases, "aauth_requirement": requirement}
+
+
+def budget_claim() -> dict:
+    """The one budget-object shape, appearing unchanged in every position."""
+    return {
+        "shape": {"amount": 5000000, "unit": "USD", "decimals": 6},
+        "notes": [
+            "amount: non-negative integer, bounded by the 15-digit SF limit",
+            "decimals is NOT constrained to the ISO 4217 minor unit",
+            "all three members REQUIRED wherever `budget` appears",
+        ],
+    }
+
+
+def consumption_records() -> dict:
+    return {
+        "budget_consumed": [
+            {"jti": "at-2", "consumed": 431200},
+            {"jti": "at-1", "consumed": 221200},
+        ],
+        "notes": [
+            "two members and no more — the PS joins the rest from its ledger",
+            "records are scoped to the presenting agent's key (jkt): one "
+            "agent never learns a sibling's spending",
+            "most recent first; SHOULD NOT exceed 20 records",
+        ],
+    }
+
+
+def signed_usage_response() -> dict:
+    """A fully worked signed usage response with a FIXED key and timestamp —
+    verify it independently: Ed25519 over the base string below."""
+    seed = b64url(bytes(range(32)))
+    signer = ResponseSigner(seed=seed, jwks_url="https://api.example/jwks.json")
+    body_doc = {
+        "as_of": 1756500000,
+        "aud": "https://ps.example",
+        "unit": "USD",
+        "decimals": 6,
+        "sub": "8f14e45fceea167a5a36dedd4bea2543",
+        "usage": {"day": 1243180, "all_time": 61438050},
+        "jkts": {"NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs": 38215600},
+    }
+    body = json.dumps(body_doc, separators=(",", ":")).encode()
+    headers = signer.sign(status=200, content_type="application/json",
+                          body=body, authority="api.example", path="/usage",
+                          created=1756500001)
+    digest = "sha-256=:" + base64.b64encode(
+        hashlib.sha256(body).digest()).decode() + ":"
+    base = "\n".join([
+        '"@status": 200',
+        '"content-type": application/json',
+        f'"content-digest": {digest}',
+        '"@authority";req: api.example',
+        '"@path";req: /usage',
+        '"@signature-params": ' + headers["Signature-Input"].split("=", 1)[1],
+    ])
+    return {
+        "signing_key": {"seed_b64url": seed, "public_jwk": signer.public_jwk,
+                        "keyid_rfc7638": signer.keyid},
+        "request_context": {"authority": "api.example", "path": "/usage"},
+        "body": body_doc,
+        "body_canonical_json": body.decode(),
+        "signature_base": base,
+        "response_headers": headers,
+    }
+
+
+def main() -> None:
+    vectors = {
+        "source": "regent-httpsig, first implementation of "
+                  "draft-hardt-aauth-budgets (editor's copy, 2026-08-20)",
+        "headers": headers(),
+        "budget_claim": budget_claim(),
+        "consumption_records": consumption_records(),
+        "signed_usage_response": signed_usage_response(),
+    }
+    out = OUT / "aauth-budgets-vectors.json"
+    out.write_text(json.dumps(vectors, indent=2) + "\n")
+    print(f"wrote {out} ({out.stat().st_size} bytes)")
+
+
+if __name__ == "__main__":
+    main()