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

regent_httpsig/fastapi.py

@@ -191,6 +191,13 @@ class BudgetMiddleware(BaseHTTPMiddleware):
             return await call_next(request)
 
         sig = await self._verified(request)
+        if sig is not None and sig.expired:
+            # §Budget Exhaustion, "auth token expired": the base protocol's plain
+            # 401 — and the resource token we attach carries the presented
+            # token's FINAL consumption record (stated at/after its exp), which
+            # is what lets its issuer settle the allocation exactly. Without
+            # this challenge an issuer never sees a final figure at all.
+            return await self._expired_challenge(sig)
         envelope: BudgetClaim | None = None
         if sig is not None:
             try:
@@ -307,11 +314,42 @@ class BudgetMiddleware(BaseHTTPMiddleware):
         result = None
         if "signature" in request.headers:
             result = await self._verifier.verify(
-                request.method, _public_url(request), dict(request.headers)
+                request.method, _public_url(request), dict(request.headers),
+                allow_expired_auth_token=True,
             )
-        request.state.regent_httpsig_result = result
+        # An expired token is never handed to the app: the middleware answers
+        # it with the final-record challenge and nothing downstream runs. The
+        # per-request cache still must not carry it — a later dependency
+        # reading the cache would otherwise see a token that is not valid.
+        request.state.regent_httpsig_result = (
+            None if result is not None and result.expired else result)
         return result
 
+    async def _expired_challenge(self, sig: VerifiedSignature) -> Response:
+        jti = str(sig.claims.get("jti") or "")
+        key: MeterKey = (
+            str(sig.claims.get("iss", "")),
+            str(sig.claims.get("sub", "")),
+            str(sig.claims.get("aud", "")),
+        )
+        token: str | None = None
+        if self._resource_token is not None and jti:
+            try:
+                record = await self._meter.consumed_record(key, jti)
+                token = await _maybe_await(self._resource_token(key, record))
+            except Exception:  # noqa: BLE001 — the challenge must not fail on the extras
+                logger.warning("resource_token_provider failed", exc_info=True)
+        return JSONResponse(
+            status_code=401,
+            content={
+                "code": "AUTH_TOKEN_EXPIRED",
+                "message": "The auth token has expired. Take the resource token in "
+                           "AAuth-Requirement to your PS for a fresh one.",
+            },
+            headers={"AAuth-Requirement": build_aauth_requirement(
+                reason=None, resource_token=token)},
+        )
+
     async def _refusal_with_token(
         self, *, reason: str, envelope: BudgetClaim,
         remaining: int, key: MeterKey, jti: str,

regent_httpsig/sfv.py

@@ -176,13 +176,18 @@ def build_aauth_budget_header(
     return ", ".join(members)
 
 
-def build_aauth_requirement(*, reason: str, resource_token: str | None = None) -> str:
-    """Serialize ``AAuth-Requirement`` for a budget refusal:
+def build_aauth_requirement(*, reason: str | None,
+                            resource_token: str | None = None) -> str:
+    """Serialize ``AAuth-Requirement`` for a budget challenge:
     ``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."""
+    ``reason`` is an sf-token (``insufficient-budget`` | ``budget-exhausted``)
+    for an exhaustion refusal, or ``None`` for the base protocol's plain
+    challenge (an EXPIRED auth token — the budget did not run out, the token
+    did); 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}"
+    if reason:
+        out += f";reason={reason}"
     return out

regent_httpsig/verify.py

@@ -61,6 +61,10 @@ AAUTH_PERSON_TYP = "aa-person+jwt"
 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
+# How long after its exp an auth token still earns the budgets "final record"
+# challenge (opt-in, BudgetMiddleware only): the meter retains consumption for
+# about this long after last activity; beyond it there is no figure to carry.
+EXPIRED_AUTH_TOKEN_GRACE = 7200
 
 
 def _register_fully_specified_algs() -> None:
@@ -86,6 +90,11 @@ class VerifiedSignature:
     sub: str | None = None  # AAuth agent id (token `sub`)
     label: str = ""
     claims: dict[str, Any] = field(default_factory=dict)  # AAuth token claims (redacted)
+    # Set only when ``verify(..., allow_expired_auth_token=True)`` accepted an
+    # auth token PAST its exp: genuine (issuer signature + proof of possession
+    # verified) but NOT valid for access. BudgetMiddleware uses it to answer
+    # with the final-record challenge; nothing else should ever see it True.
+    expired: bool = False
 
     def context(self) -> dict[str, Any]:
         """A flat dict suitable for logging / policy engines / audit trails."""
@@ -164,18 +173,28 @@ class HttpsigVerifier:
         self._cache: dict[str, tuple[float, dict[str, Any] | None]] = {}
 
     async def verify(
-        self, method: str, url: str, headers: Mapping[str, str]
+        self, method: str, url: str, headers: Mapping[str, str],
+        *, allow_expired_auth_token: bool = False,
     ) -> VerifiedSignature | None:
         """Verify the request's agent signature. Returns ``None`` when there is
         no ``Signature`` header, the signature is invalid, or the signer's keys
-        cannot be (safely) fetched — never raises on untrusted input."""
+        cannot be (safely) fetched — never raises on untrusted input.
+
+        ``allow_expired_auth_token`` (default False — leave it so for access
+        decisions) lets a genuine ``aa-auth+jwt`` past its ``exp`` come back
+        with ``expired=True`` instead of ``None``, for up to
+        :data:`EXPIRED_AUTH_TOKEN_GRACE` seconds. Budgets need this: the
+        resource owes the holder of an expired token a challenge carrying that
+        token's final consumption record (draft §Budget Exhaustion), and it
+        cannot build one for a token it refused to look at."""
         hdrs = {str(k): str(v) for k, v in headers.items()}
         if not any(k.lower() == "signature" for k in hdrs):
             return None
         result: VerifiedSignature | None = None
         try:
             if any(k.lower() == "signature-key" for k in hdrs):
-                result = await self._verify_aauth(method, url, hdrs)
+                result = await self._verify_aauth(
+                    method, url, hdrs, allow_expired_auth_token=allow_expired_auth_token)
             if result is None:
                 result = await self._verify_web_bot_auth(method, url, hdrs)
         except Exception as exc:  # noqa: BLE001 — belt and braces
@@ -288,7 +307,8 @@ class HttpsigVerifier:
     # ── AAuth (identity-based mode) ──────────────────────────────────────────
 
     async def _verify_aauth(
-        self, method: str, url: str, headers: dict[str, str]
+        self, method: str, url: str, headers: dict[str, str],
+        *, allow_expired_auth_token: bool = False,
     ) -> VerifiedSignature | None:
         try:
             import jwt as pyjwt  # the [aauth] extra
@@ -387,6 +407,7 @@ class HttpsigVerifier:
                         continue
         if issuer_key is None:
             return None
+        tolerate_exp = allow_expired_auth_token and typ == AAUTH_AUTH_TYP
         try:
             claims = pyjwt.decode(
                 token,
@@ -396,11 +417,20 @@ class HttpsigVerifier:
                 options={
                     "require": ["iss", "sub", "exp", "iat"],
                     "verify_aud": audience is not None,
+                    "verify_exp": not tolerate_exp,
                 },
             )
         except Exception as exc:  # noqa: BLE001
             logger.info("aauth token invalid iss=%s: %s", iss, str(exc)[:200])
             return None
+        expired = False
+        if tolerate_exp:
+            overdue = int(time.time()) - int(claims.get("exp", 0))
+            expired = overdue >= 0
+            if overdue > EXPIRED_AUTH_TOKEN_GRACE:
+                logger.info("aauth auth token expired %ss ago — past grace iss=%s",
+                            overdue, iss)
+                return None
 
         # -11: person and auth tokens live at most one hour.
         if typ in (AAUTH_PERSON_TYP, AAUTH_AUTH_TYP):
@@ -456,4 +486,5 @@ class HttpsigVerifier:
                           "budget")  # budgets: the envelope rides in the token
                 if k in claims
             },
+            expired=expired,
         )

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: regent-httpsig
-Version: 0.5.0
+Version: 0.5.1
 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
@@ -174,6 +174,11 @@ production on [get4agent.com](https://get4agent.com).
 
 - `insufficient-budget` refusals carry **`required`** — the refused request's
   maximum cost — so the agent lowers its bound and retries instead of guessing.
+- An **expired** auth token gets the base protocol's plain challenge with a
+  resource token carrying that token's **final** consumption record — the
+  figure its issuer needs to settle the allocation (a record stated at or
+  after `exp` is final; one on a live token is a snapshot and releases
+  nothing).
 - **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

{regent_httpsig-0.5.0.dist-info → regent_httpsig-0.5.1.dist-info}/RECORD

@@ -2,15 +2,15 @@ regent_httpsig/__init__.py,sha256=Ch-PdsMDo_uKG4U5A4xklU3jbCWdJTWXHG86n5VA7dc,17
 regent_httpsig/budget.py,sha256=sjNJiFyfqLHEdnbh8e4bmqZr2gPveYynZ5eXUYpES_k,16967
 regent_httpsig/cli.py,sha256=WUSLQ2WuEX4E85L2C2EgoUfu5cWpj6MRSG1UVNHpzcw,2005
 regent_httpsig/config.py,sha256=_xAIFYAyNbXzKg-famXLAs7eNdYwuvNA7NHQxcno0G4,2439
-regent_httpsig/fastapi.py,sha256=IijwDjnDKntRzavFzj2o6HM3XqvCHi2VZOv_xL_MLTA,15660
+regent_httpsig/fastapi.py,sha256=RGkEHsNchEac7fXNYs2CT_MOETDktCxHcgQGwytSCCI,17714
 regent_httpsig/jwk.py,sha256=h4vgnIgpnyKeWdWpm7g_hEyXZOPVREWn-bD4JN07tT0,1637
 regent_httpsig/netguard.py,sha256=Sqg08mdC94RWvnQLJaH4weZW0nN2VlTJF5wVF8VYGHY,2121
-regent_httpsig/sfv.py,sha256=O8eK3Xyw-lewSepLJQcBKfPZAIBZCYatw4zDNDsxxYo,7407
+regent_httpsig/sfv.py,sha256=-nUUjyqyAMOSGro9Z0AIXiuchqsIAVaJWbKuIIO4fB0,7624
 regent_httpsig/sign.py,sha256=B5ChxFxuuKL0i10bGrgFImzyh8GMjWIqNDECXehBWTA,4397
 regent_httpsig/usage.py,sha256=PSIPXCtUZyh5cjn4SzwOgrXuJrwDIWu-kffJ-4NFeS0,9453
-regent_httpsig/verify.py,sha256=8z-x3trF5B8P8D1aDYoqzF4R5h8BVv91CKiubFKFIiI,19915
-regent_httpsig-0.5.0.dist-info/METADATA,sha256=9_2zaZrS2LBdENWDPnYVWrJhtIh9vgbG_7e7J5f3X_s,12187
-regent_httpsig-0.5.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-regent_httpsig-0.5.0.dist-info/entry_points.txt,sha256=SgZdmc27V14IAmwOjbBoCYLsbrALaqdTUHNHLbil2dU,59
-regent_httpsig-0.5.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-regent_httpsig-0.5.0.dist-info/RECORD,,
+regent_httpsig/verify.py,sha256=p9VtHZz9HWHIstDBxNvVrc_xJdubbRA_pN9DjQQDzpk,21716
+regent_httpsig-0.5.1.dist-info/METADATA,sha256=AWYCmTad0KRJFx6ODUZso9fyUcvN6CdU2fbxh0-LTXw,12496
+regent_httpsig-0.5.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+regent_httpsig-0.5.1.dist-info/entry_points.txt,sha256=SgZdmc27V14IAmwOjbBoCYLsbrALaqdTUHNHLbil2dU,59
+regent_httpsig-0.5.1.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+regent_httpsig-0.5.1.dist-info/RECORD,,