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

regent_httpsig-0.4.0/CHANGELOG.md

@@ -0,0 +1,98 @@
+# 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
+side, first known implementation (running in production on get4agent.com):
+
+- **Auth tokens** (`typ: aa-auth+jwt`): PS-issued budget carriers verified
+  against a configuration-pinned PS (`HttpsigConfig.trusted_ps`: issuer →
+  JWKS URL), `aud`-checked against `resource_url`, `cnf`-bound, ≤1h lifetime.
+- **`BudgetClaim` + `InMemoryMeter`**: atomic reserve → commit → release
+  pooled per the draft's `(iss, sub, aud)` aggregation key; conservative
+  crash-safety (an unresolved reservation counts as consumed); consumption
+  records **scoped to the presenting agent's `jkt`** so one agent never
+  learns about a sibling's spending.
+- **`BudgetMiddleware`** (FastAPI): `price_fn` hook, metering cycle,
+  refusals (401 + `AAuth-Requirement` with `reason=insufficient-budget` /
+  `budget-exhausted` and an optional resource token via
+  `resource_token_provider`), per-response `AAuth-Budget` header; error
+  responses release the reservation.
+- `build_aauth_budget_header` / `build_aauth_requirement` — RFC 9651
+  serialization (note: the field is a Dictionary, so members are
+  comma-separated; the draft's §11 example shows parameter separators).
+
+## 0.2.0
+
+AAuth draft **-11** support (per the editor's copy, ahead of datatracker publication):
+
+- **Fully-specified algorithms (RFC 9864):** `Ed25519` accepted everywhere
+  (registered with PyJWT, including JWKS entries PyJWK cannot parse).
+  New `HttpsigConfig.require_fully_specified_algs` enforces the -11 MUST NOT on
+  the polymorphic `EdDSA`; the default keeps accepting it while the -10
+  ecosystem migrates, and will flip when -11 posts.
+- **Person tokens** (`typ: aa-person+jwt`): PS-issued, per-resource `aud`,
+  `cnf`-bound, ≤1h lifetime — verified via `{iss}/.well-known/aauth-person.json`.
+  Opt-in: set `HttpsigConfig.resource_url` (the token's `aud` must name it).
+  Result scheme: `"aauth-person"`, `sub` = the PS's directed user identifier.
+- Strict mode also enforces the -11 requirement that `cnf.jwk` carries a
+  fully-specified `alg` member.
+
+## 0.1.1
+
+- AAuth: tolerate absent `keyid` (RFC 9421 makes it optional; the key comes from
+  the token's `cnf.jwk`). Exposed by cross-library interop with
+  christian-posta/aauth-signing, whose signers correctly omit it; that signer's
+  exact keyid-less shape is now pinned in CI.
+
+## 0.1.0
+
+Initial release, extracted from Regent Protocol's production marketplace
+(get4agent.com), where it authenticates self-onboarding AI agents.
+
+- `HttpsigVerifier` — RFC 9421 verification for both agent dialects:
+  - Web Bot Auth (draft -05): sf-dictionary `Signature-Agent` with `;key=`
+    member selection AND the legacy sf-string form OpenAI ships in production;
+    key discovery via `/.well-known/http-message-signatures-directory`.
+  - AAuth (identity-based mode, `[aauth]` extra): `aa-agent+jwt` in
+    `Signature-Key`, issuer JWKS discovery, `cnf.jwk` proof of possession.
+  - SSRF-guarded directory fetching (https-only, public-IP-only, no redirects,
+    size-capped) with bounded per-instance caching.
+- `EgressSigner` + `regent-httpsig keygen` — sign outbound agent traffic
+  (Web Bot Auth), generate keys and ready-to-publish well-known files.
+- FastAPI integration (`[fastapi]` extra): `SignatureDep` (enrichment) and
+  `RequiredSignatureDep` (authentication with a self-explaining 401).
+- Test suite pinned to the official RFC 9421 B.2.6 vector, both Web Bot Auth
+  appendix vectors (A.2.2 re-signed — the draft's printed signature does not
+  verify over its own base; reported), and full sign→verify roundtrips for
+  both dialects.

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

@@ -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.2.0 → regent_httpsig-0.4.0}/README.md

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "regent-httpsig"
-version = "0.2.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.2.0 → regent_httpsig-0.4.0}/src/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-0.4.0/src/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)
+            ]