yanez-agent-authorization 0.1.0a1__tar.gz

yanez_agent_authorization-0.1.0a1/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.egg-info/
+node_modules/
+dist/
+.DS_Store
+.idea/
+*.swp
+.pytest_cache/
+.serena/

yanez_agent_authorization-0.1.0a1/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.5
+Name: yanez-agent-authorization
+Version: 0.1.0a1
+Summary: Yanez agent authorization: request human approval, verify signed receipts.
+Project-URL: Homepage, https://github.com/yanez-compliance/yanez-agent-authorization
+Project-URL: Repository, https://github.com/yanez-compliance/yanez-agent-authorization
+Project-URL: Issues, https://github.com/yanez-compliance/yanez-agent-authorization/issues
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pyjwt<3,>=2.8
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# yanez-agent-authorization (Python)
+
+Async client for requesting verifiable human approval through Yanez, and a verifier
+for the signed receipts. Import package: `yanez_authz`.
+
+```sh
+pip install yanez-agent-authorization   # pre-release: not on PyPI yet; pip install -e packages/python
+```
+
+```python
+from yanez_authz import AuthorizationClient, ReceiptVerifier
+
+async with AuthorizationClient(base_url, agent_api_key) as client:
+    pending = await client.request_authorization(terms={...})
+    result = await client.wait_for_authorization(pending.request_id, 900)
+
+receipt = ReceiptVerifier(base_url, expected_issuer).authorize_action(
+    result.artifact, expected_terms, max_age_seconds=900, consume=True,
+    expected_sub=account_yid)   # the YID your records tie to the account
+```
+
+`wait_for_authorization` raises the builtin `TimeoutError` when the local deadline
+passes; rejection and expiry are returned as values. `expected_issuer` is the issuer
+string your Yanez operator publishes for the deployment.
+
+Docs and the full integration model: https://github.com/yanez-compliance/yanez-agent-authorization

yanez_agent_authorization-0.1.0a1/README.md

@@ -0,0 +1,26 @@
+# yanez-agent-authorization (Python)
+
+Async client for requesting verifiable human approval through Yanez, and a verifier
+for the signed receipts. Import package: `yanez_authz`.
+
+```sh
+pip install yanez-agent-authorization   # pre-release: not on PyPI yet; pip install -e packages/python
+```
+
+```python
+from yanez_authz import AuthorizationClient, ReceiptVerifier
+
+async with AuthorizationClient(base_url, agent_api_key) as client:
+    pending = await client.request_authorization(terms={...})
+    result = await client.wait_for_authorization(pending.request_id, 900)
+
+receipt = ReceiptVerifier(base_url, expected_issuer).authorize_action(
+    result.artifact, expected_terms, max_age_seconds=900, consume=True,
+    expected_sub=account_yid)   # the YID your records tie to the account
+```
+
+`wait_for_authorization` raises the builtin `TimeoutError` when the local deadline
+passes; rejection and expiry are returned as values. `expected_issuer` is the issuer
+string your Yanez operator publishes for the deployment.
+
+Docs and the full integration model: https://github.com/yanez-compliance/yanez-agent-authorization

yanez_agent_authorization-0.1.0a1/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "yanez-agent-authorization"
+version = "0.1.0a1"
+description = "Yanez agent authorization: request human approval, verify signed receipts."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+]
+dependencies = [
+    "httpx>=0.27,<1",
+    "PyJWT>=2.8,<3",
+    "cryptography>=42",
+]
+
+[project.urls]
+Homepage = "https://github.com/yanez-compliance/yanez-agent-authorization"
+Repository = "https://github.com/yanez-compliance/yanez-agent-authorization"
+Issues = "https://github.com/yanez-compliance/yanez-agent-authorization/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/yanez_authz"]

yanez_agent_authorization-0.1.0a1/src/yanez_authz/__init__.py

@@ -0,0 +1,41 @@
+"""Yanez agent authorization SDK.
+
+Two halves, deliberately separate:
+
+- `AuthorizationClient` — the agent side: ask the key's owner to approve terms, poll
+  for the decision. Needs the yak_ agent key.
+- `ReceiptVerifier` — the relying-party side: verify and (for single-use actions)
+  consume a signed receipt. Needs no credentials at all.
+"""
+from yanez_authz.async_client import AuthorizationClient
+from yanez_authz.errors import (
+    AlreadyConsumedError,
+    AuthenticationError,
+    ConflictError,
+    ConsentPolicyError,
+    FeatureUnavailableError,
+    InvalidRequestError,
+    NotFoundError,
+    RateLimitError,
+    ReceiptVerificationError,
+    TermsTooLargeError,
+    TransportError,
+    YanezAuthzError,
+)
+from yanez_authz.models import (
+    AuthorizationResult,
+    IntrospectionResult,
+    PendingAuthorization,
+    VerifiedReceipt,
+)
+from yanez_authz.verifier import ReceiptVerifier
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AuthorizationClient", "ReceiptVerifier",
+    "PendingAuthorization", "AuthorizationResult", "IntrospectionResult", "VerifiedReceipt",
+    "YanezAuthzError", "AuthenticationError", "InvalidRequestError", "TermsTooLargeError",
+    "RateLimitError", "ConflictError", "NotFoundError", "FeatureUnavailableError",
+    "TransportError", "ReceiptVerificationError", "ConsentPolicyError", "AlreadyConsumedError",
+]

yanez_agent_authorization-0.1.0a1/src/yanez_authz/async_client.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+import asyncio
+import re
+import secrets
+import time
+from typing import Any, Optional
+from urllib.parse import quote, urlsplit
+
+import httpx
+
+from yanez_authz.errors import InvalidRequestError, TransportError, error_for_status
+from yanez_authz.models import TERMINAL, AuthorizationResult, PendingAuthorization
+
+_LOOPBACK = {"localhost", "127.0.0.1", "::1"}
+# Server ids look like azr_<hex>; anything outside this set could only be an attempt
+# to steer the keyed request at another path.
+_REQUEST_ID = re.compile(r"[A-Za-z0-9_-]{1,128}")
+
+
+def require_trusted_origin(base_url: str) -> str:
+    """HTTPS everywhere except loopback development hosts. The base URL is process
+    configuration, never a per-call (model-supplied) value."""
+    parts = urlsplit(base_url)
+    if parts.scheme == "https":
+        return base_url.rstrip("/")
+    if parts.scheme == "http" and parts.hostname in _LOOPBACK:
+        return base_url.rstrip("/")
+    raise ValueError("base_url must be https:// (plain http is allowed only for loopback)")
+
+
+def _raise_for(response: httpx.Response, *, create: bool = False) -> None:
+    if response.is_redirect:
+        # Never carry the Authorization header across a redirect; a credentialed
+        # request that gets redirected is treated as a transport failure.
+        raise TransportError("unexpected redirect")
+    if response.is_success:
+        return
+    try:
+        detail = response.json().get("detail")
+    except Exception:  # noqa: BLE001 — a non-JSON error body has no detail to extract
+        detail = None
+    raise error_for_status(response.status_code, detail, create=create)
+
+
+class AuthorizationClient:
+    """Agent-side client: create an authorization request and poll for its decision.
+
+    Async and context-managed:
+
+        async with AuthorizationClient(base_url, agent_api_key) as client:
+            pending = await client.request_authorization(terms={...})
+            result = await client.wait_for_authorization(pending.request_id, 900)
+    """
+
+    def __init__(self, base_url: str, agent_api_key: str, *,
+                 timeout_seconds: float = 10.0,
+                 transport: Optional[httpx.AsyncBaseTransport] = None) -> None:
+        self._base_url = require_trusted_origin(base_url)
+        self._timeout = timeout_seconds
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers={"Authorization": f"Bearer {agent_api_key}"},
+            follow_redirects=False,
+            timeout=timeout_seconds,
+            transport=transport,
+        )
+
+    async def __aenter__(self) -> "AuthorizationClient":
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def request_authorization(
+        self,
+        terms: dict[str, Any],
+        *,
+        decision_window_seconds: int = 900,
+        intent_expires_at: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> PendingAuthorization:
+        """Create a request. One idempotency key is generated per call and reused for
+        the internal retry, so an ambiguous network failure can never prompt the user
+        twice — the retry replays instead.
+
+        Supplying `idempotency_key` yourself is for resuming one specific earlier
+        create. Derive it from randomness, never from the terms: a content-derived key
+        makes a second genuine purchase of the same item replay the first one instead
+        of asking the user, and the reservation is permanent.
+        """
+        if idempotency_key is None:
+            idempotency_key = secrets.token_urlsafe(16)
+        body: dict[str, Any] = {"terms": terms,
+                                "decision_window_seconds": decision_window_seconds}
+        if intent_expires_at is not None:
+            body["intent_expires_at"] = intent_expires_at
+
+        response = await self._post_with_one_retry(
+            "/api/agent/authorizations", body, {"Idempotency-Key": idempotency_key})
+        _raise_for(response, create=True)
+        data = response.json()
+        return PendingAuthorization(
+            request_id=data["request_id"],
+            status=data["status"],
+            decide_by=data["decide_by"],
+            idempotency_key=idempotency_key,
+            replayed=response.headers.get("Idempotency-Replayed") == "true",
+        )
+
+    async def _post_with_one_retry(self, path: str, body: dict,
+                                   headers: dict[str, str]) -> httpx.Response:
+        # Safe to retry ONLY because the idempotency key rides along unchanged.
+        try:
+            return await self._client.post(path, json=body, headers=headers)
+        except httpx.TransportError:
+            try:
+                return await self._client.post(path, json=body, headers=headers)
+            except httpx.TransportError as e:
+                raise TransportError(type(e).__name__) from None
+
+    async def get_authorization(self, request_id: str,
+                                wait_seconds: int = 0) -> AuthorizationResult:
+        """One poll, long-polling server-side for up to `wait_seconds` (0-25)."""
+        if not _REQUEST_ID.fullmatch(request_id):
+            # The id may come from a model (MCP tool argument): validate before it
+            # touches the URL, and encode so it can never rewrite the path.
+            raise InvalidRequestError("malformed request id")
+        params = {"wait": wait_seconds} if wait_seconds else None
+        try:
+            response = await self._client.get(
+                f"/api/agent/authorizations/{quote(request_id, safe='')}", params=params,
+                # The server holds the connection for the whole long-poll.
+                timeout=self._timeout + wait_seconds,
+            )
+        except httpx.TransportError as e:
+            raise TransportError(type(e).__name__) from None
+        _raise_for(response)
+        data = response.json()
+        return AuthorizationResult(
+            request_id=data["request_id"], status=data["status"],
+            artifact=data.get("artifact"),
+            consent_not_after=data.get("consent_not_after"),
+            decided_at=data.get("decided_at"),
+        )
+
+    async def wait_for_authorization(
+        self,
+        request_id: str,
+        overall_timeout_seconds: float,
+        *,
+        long_poll_seconds: int = 25,
+    ) -> AuthorizationResult:
+        """Repeat bounded long-polls until a terminal state.
+
+        Rejection and expiry come back as values — they are answers, not failures.
+        Running out of local time raises TimeoutError, and cancellation propagates;
+        neither touches the server-side request, which the user can still decide.
+        """
+        deadline = time.monotonic() + overall_timeout_seconds
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError(f"no decision within {overall_timeout_seconds}s")
+            wait = max(0, min(long_poll_seconds, int(remaining)))
+            started = time.monotonic()
+            try:
+                result = await self.get_authorization(request_id, wait_seconds=wait)
+            except TransportError:
+                # A dropped long-poll is routine; back off briefly and ask again.
+                await asyncio.sleep(min(1.0, max(0.0, deadline - time.monotonic())))
+                continue
+            if result.status in TERMINAL:
+                return result
+            # A non-terminal reply that came back in under a second (wait 0 in the
+            # final second, or a proxy answering early) must not become a tight loop.
+            elapsed = time.monotonic() - started
+            if elapsed < 1.0:
+                await asyncio.sleep(min(1.0 - elapsed, max(0.0, deadline - time.monotonic())))

yanez_agent_authorization-0.1.0a1/src/yanez_authz/errors.py

@@ -0,0 +1,79 @@
+"""Typed errors, one per failure class of the agent-authorization contract.
+
+Messages never contain the agent key, the Authorization header, or a raw artifact —
+only HTTP status and the server's sanitized detail string.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+
+class YanezAuthzError(Exception):
+    """Base for every error this SDK raises deliberately."""
+
+
+class AuthenticationError(YanezAuthzError):
+    """Missing, malformed, or revoked agent key. Do not retry; reissue the key."""
+
+
+class InvalidRequestError(YanezAuthzError):
+    """Invalid terms, time, or schema. Fix the request."""
+
+
+class TermsTooLargeError(YanezAuthzError):
+    """Terms exceed the server's 4 KB cap. Reduce without losing material facts."""
+
+
+class RateLimitError(YanezAuthzError):
+    """Request or pending limit reached. Wait; never create a replacement loop."""
+
+
+class ConflictError(YanezAuthzError):
+    """Idempotency mismatch or terminal transition. Inspect the original request."""
+
+
+class NotFoundError(YanezAuthzError):
+    """Unknown or cross-key request id. The server discloses nothing more."""
+
+
+class FeatureUnavailableError(YanezAuthzError):
+    """Authorization routes are disabled or not deployed. Operator action needed."""
+
+
+class TransportError(YanezAuthzError):
+    """Timeout, TLS, DNS, connection failure — or an unexpected redirect, which is
+    never followed with credentials."""
+
+
+class ReceiptVerificationError(YanezAuthzError):
+    """Bad signature, issuer, claims, or exact terms. Never execute the action."""
+
+
+class ConsentPolicyError(YanezAuthzError):
+    """The receipt is genuine but stale or past the user's bound. Request new approval."""
+
+
+class AlreadyConsumedError(YanezAuthzError):
+    """A genuine single-use receipt was previously spent. Never execute again."""
+
+
+def error_for_status(status: int, detail: Optional[str], *, create: bool = False) -> YanezAuthzError:
+    """Map a non-2xx agent-API response to a typed error.
+
+    A 404 means two different things by route: on create, the whole router is absent
+    (feature disabled); on get, the request id is unknown or belongs to another key.
+    """
+    message = detail or f"HTTP {status}"
+    if status == 401:
+        return AuthenticationError(message)
+    if status == 404:
+        return FeatureUnavailableError(message) if create else NotFoundError(message)
+    if status == 409:
+        return ConflictError(message)
+    if status == 413:
+        return TermsTooLargeError(message)
+    if status == 429:
+        return RateLimitError(message)
+    if status in (400, 422):
+        return InvalidRequestError(message)
+    return TransportError(f"unexpected HTTP {status}")

yanez_agent_authorization-0.1.0a1/src/yanez_authz/models.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+# Wire statuses, verbatim. Exactly one per response; only `approved` carries an artifact.
+PENDING = "pending"
+APPROVED = "approved"
+REJECTED = "rejected"
+EXPIRED = "expired"
+TERMINAL = frozenset({APPROVED, REJECTED, EXPIRED})
+
+
+@dataclass(frozen=True)
+class PendingAuthorization:
+    request_id: str
+    status: str
+    decide_by: str
+    idempotency_key: str
+    replayed: bool  # True when the server answered from an earlier create
+
+
+@dataclass(frozen=True)
+class AuthorizationResult:
+    request_id: str
+    status: str
+    artifact: Optional[str] = None
+    # ISO timestamps as the server sent them; parse only if you need arithmetic.
+    consent_not_after: Optional[str] = None
+    decided_at: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class IntrospectionResult:
+    valid: bool
+    reason: Optional[str] = None
+    consumed_now: Optional[bool] = None
+    sub: Optional[str] = None
+    jti: Optional[str] = None
+    decided_at: Optional[int] = None
+    consent_not_after: Optional[int] = None
+    terms: Optional[dict[str, Any]] = None
+
+
+@dataclass(frozen=True)
+class VerifiedReceipt:
+    """A receipt that passed signature, issuer, claim-profile, exact-terms, freshness,
+    and consent checks. Holding one means "permission to act now", not just validity."""
+    sub: str
+    jti: str
+    agent_key_id: str
+    decided_at: int
+    match_overlap: int
+    terms: dict[str, Any]
+    consent_not_after: Optional[int] = None

yanez_agent_authorization-0.1.0a1/src/yanez_authz/verifier.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+import base64
+import math
+import time
+from typing import Any, Callable, Optional
+
+import httpx
+import jwt
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+from yanez_authz.async_client import _raise_for, require_trusted_origin
+from yanez_authz.errors import (
+    AlreadyConsumedError,
+    ConsentPolicyError,
+    ReceiptVerificationError,
+    TransportError,
+)
+from yanez_authz.models import IntrospectionResult, VerifiedReceipt
+
+_KEY_CACHE_TTL_SECONDS = 600
+# An unknown kid may force one early refresh (key rotation), but a stream of garbage
+# kids must not become a stream of key-set fetches.
+_KEY_REFRESH_COOLDOWN_SECONDS = 30
+_CLOCK_SKEW_SECONDS = 60
+
+_REQUIRED_CLAIMS = ("sub", "jti", "iat", "yanez_agent_key_id", "yanez_decision",
+                    "yanez_decided_at", "yanez_match_overlap", "yanez_terms")
+_STRING_CLAIMS = ("sub", "jti", "yanez_agent_key_id")
+# NumericDate claims the SDK does arithmetic on; a signed string here must be a typed
+# rejection, never a TypeError or a comparison that silently passes.
+_INTEGER_CLAIMS = ("yanez_decided_at", "yanez_consent_not_after")
+
+
+def _b64url_decode(s: str) -> bytes:
+    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+
+
+def _terms_equal(a: Any, b: Any) -> bool:
+    """Deep JSON equality with bool distinct from int, the verdict the TypeScript SDK's
+    isDeepStrictEqual reaches; plain `==` would let {"n": true} match {"n": 1}."""
+    if isinstance(a, bool) or isinstance(b, bool):
+        return isinstance(a, bool) and isinstance(b, bool) and a == b
+    if isinstance(a, dict) and isinstance(b, dict):
+        return a.keys() == b.keys() and all(_terms_equal(a[k], b[k]) for k in a)
+    if isinstance(a, list) and isinstance(b, list):
+        return len(a) == len(b) and all(map(_terms_equal, a, b))
+    if isinstance(a, (int, float)) and isinstance(b, (int, float)):
+        return a == b  # JSON has one number type
+    return type(a) is type(b) and a == b
+
+
+class ReceiptVerifier:
+    """Relying-party verification. Needs no agent key — a receipt is portable proof.
+
+    `expected_issuer` is mandatory: the unverified `iss` claim is never trusted to
+    name its own authority.
+    """
+
+    def __init__(self, base_url: str, expected_issuer: str, *,
+                 timeout_seconds: float = 10.0,
+                 now: Callable[[], float] = time.time,
+                 transport: Optional[httpx.BaseTransport] = None) -> None:
+        if not expected_issuer:
+            raise ValueError("expected_issuer is mandatory")
+        self._base_url = require_trusted_origin(base_url)
+        self._issuer = expected_issuer
+        self._now = now
+        self._http = httpx.Client(base_url=self._base_url, timeout=timeout_seconds,
+                                  follow_redirects=False, transport=transport)
+        self._keys: dict[str, Ed25519PublicKey] = {}
+        self._keys_fetched_at: Optional[float] = None
+
+    # --- key set ---
+
+    def _fetch_keys(self) -> None:
+        try:
+            response = self._http.get("/api/authz/public-keys")
+        except httpx.HTTPError as e:
+            raise TransportError(type(e).__name__) from None
+        _raise_for(response, create=True)  # a 404 here means the feature is absent
+        try:
+            entries = response.json()["keys"]
+            if not isinstance(entries, list):
+                raise TypeError
+        except (ValueError, TypeError, KeyError):
+            raise TransportError("malformed key set") from None
+        keys = {}
+        for jwk in entries:
+            if not isinstance(jwk, dict) or jwk.get("kty") != "OKP" \
+                    or jwk.get("crv") != "Ed25519" or not jwk.get("kid"):
+                continue
+            try:
+                keys[jwk["kid"]] = Ed25519PublicKey.from_public_bytes(
+                    _b64url_decode(jwk["x"]))
+            except (KeyError, TypeError, ValueError):
+                continue  # one bad entry must not take the whole key set down
+        self._keys = keys
+        self._keys_fetched_at = time.monotonic()
+
+    def _key_for(self, kid: str) -> Ed25519PublicKey:
+        """Cached for ten minutes; an unknown kid forces one early refresh (at most one
+        per cooldown) so a freshly rotated key verifies without a restart. Never
+        selected by algorithm."""
+        age = (math.inf if self._keys_fetched_at is None
+               else time.monotonic() - self._keys_fetched_at)
+        if age > _KEY_CACHE_TTL_SECONDS:
+            self._fetch_keys()
+        elif kid not in self._keys and age > _KEY_REFRESH_COOLDOWN_SECONDS:
+            self._fetch_keys()
+        key = self._keys.get(kid)
+        if key is None:
+            raise ReceiptVerificationError(f"unknown signing key {kid!r}")
+        return key
+
+    # --- verification ---
+
+    def verify(self, artifact: str, expected_terms: dict[str, Any],
+               max_age_seconds: int, *, now: Optional[float] = None,
+               expected_sub: Optional[str] = None,
+               expected_agent_key_id: Optional[str] = None) -> VerifiedReceipt:
+        """Signature + profile + exact terms + freshness + consent bound.
+
+        Freshness (`max_age_seconds`, against `yanez_decided_at`) and the user's
+        `yanez_consent_not_after` are THIS relying party's gate on acting; neither
+        affects whether the receipt is genuine. There is deliberately no `exp`
+        requirement — a receipt still verifies years later, when the dispute happens.
+
+        A genuine receipt says that *some* YID approved these terms. When the terms do
+        not name the account, pass `expected_sub` (and/or `expected_agent_key_id`) so
+        an approval by one user can never authorize an action for another.
+        """
+        current = self._now() if now is None else now
+
+        try:
+            header = jwt.get_unverified_header(artifact)
+        except jwt.PyJWTError as e:
+            raise ReceiptVerificationError(str(e)) from None
+        # Pinned algorithm; the token's own header is never an allow-list.
+        if header.get("alg") != "EdDSA" or not header.get("kid"):
+            raise ReceiptVerificationError("receipt must be EdDSA with a kid")
+
+        key = self._key_for(header["kid"])
+        try:
+            claims = jwt.decode(
+                artifact, key, algorithms=["EdDSA"], issuer=self._issuer,
+                leeway=_CLOCK_SKEW_SECONDS,
+            )
+        except jwt.PyJWTError as e:
+            raise ReceiptVerificationError(str(e)) from None
+
+        for name in _REQUIRED_CLAIMS:
+            if claims.get(name) is None:
+                raise ReceiptVerificationError(f"missing claim {name}")
+        for name in _STRING_CLAIMS:
+            if not isinstance(claims[name], str):
+                raise ReceiptVerificationError(f"claim {name} must be a string")
+        for name in _INTEGER_CLAIMS:
+            value = claims.get(name)
+            if value is not None and (isinstance(value, bool) or not isinstance(value, int)):
+                raise ReceiptVerificationError(f"claim {name} must be an integer NumericDate")
+        if claims["yanez_decision"] != "approved":
+            raise ReceiptVerificationError("receipt is not an approval")
+        if expected_sub is not None and claims["sub"] != expected_sub:
+            raise ReceiptVerificationError("sub does not match expected_sub")
+        if expected_agent_key_id is not None and claims["yanez_agent_key_id"] != expected_agent_key_id:
+            raise ReceiptVerificationError(
+                "yanez_agent_key_id does not match expected_agent_key_id")
+        if claims["iat"] != claims["yanez_decided_at"]:
+            raise ReceiptVerificationError("iat and yanez_decided_at disagree")
+        overlap = claims["yanez_match_overlap"]
+        # Any non-negative integer: the issuer's block count and threshold are its
+        # policy at signing time, not part of this public contract.
+        if isinstance(overlap, bool) or not isinstance(overlap, int) or overlap < 0:
+            raise ReceiptVerificationError("yanez_match_overlap must be a non-negative integer")
+        if not _terms_equal(claims["yanez_terms"], expected_terms):
+            # Deep equality, no ignored or wildcard fields: changed terms mean a new
+            # authorization, never a reused receipt.
+            raise ReceiptVerificationError("terms do not match the approved terms")
+
+        decided_at = claims["yanez_decided_at"]
+        not_after = claims.get("yanez_consent_not_after")
+        if decided_at > current + _CLOCK_SKEW_SECONDS:
+            raise ReceiptVerificationError("yanez_decided_at is in the future")
+        if current - decided_at > max_age_seconds:
+            raise ConsentPolicyError(
+                f"approval is {int(current - decided_at)}s old, policy allows {max_age_seconds}s")
+        if not_after is not None and current > not_after:
+            raise ConsentPolicyError("past the user's consent bound")
+
+        return VerifiedReceipt(
+            sub=claims["sub"], jti=claims["jti"],
+            agent_key_id=claims["yanez_agent_key_id"], decided_at=decided_at,
+            match_overlap=overlap, terms=claims["yanez_terms"],
+            consent_not_after=not_after,
+        )
+
+    def introspect(self, artifact: str, *, consume: bool = False) -> IntrospectionResult:
+        """Online check; `consume=True` permanently spends the receipt's jti."""
+        try:
+            response = self._http.post("/api/authz/introspect",
+                                       json={"artifact": artifact, "consume": consume})
+        except httpx.HTTPError as e:
+            raise TransportError(type(e).__name__) from None
+        _raise_for(response, create=True)  # a 404 here means the feature is absent
+        data = response.json()
+        return IntrospectionResult(**{k: data.get(k) for k in (
+            "valid", "reason", "consumed_now", "sub", "jti",
+            "decided_at", "consent_not_after", "terms")})
+
+    def authorize_action(self, artifact: str, expected_terms: dict[str, Any],
+                         max_age_seconds: int, *, consume: bool,
+                         expected_sub: Optional[str] = None,
+                         expected_agent_key_id: Optional[str] = None) -> VerifiedReceipt:
+        """Everything the action boundary needs, in order — but never the action itself.
+
+        For a single-use action pass consume=True and call this immediately before
+        executing. If the action then fails, the receipt stays spent: retry means a
+        new authorization, because consumption and a third-party side effect cannot
+        be one atomic transaction.
+        """
+        receipt = self.verify(artifact, expected_terms, max_age_seconds,
+                              expected_sub=expected_sub,
+                              expected_agent_key_id=expected_agent_key_id)
+        if consume:
+            result = self.introspect(artifact, consume=True)
+            if result.valid and result.reason == "already_consumed":
+                raise AlreadyConsumedError("receipt was already spent")
+            if result.valid and result.reason == "consent_expired":
+                raise ConsentPolicyError("past the user's consent bound")
+            if not result.valid:
+                raise ReceiptVerificationError(result.reason or "invalid receipt")
+            if result.consumed_now is not True:
+                # Only a consumption the server confirmed authorizes a single-use action.
+                raise ReceiptVerificationError(
+                    "receipt was not consumed" + (f": {result.reason}" if result.reason else ""))
+        return receipt

yanez_agent_authorization-0.1.0a1/tests/conftest.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+FIXTURES = Path(__file__).resolve().parents[3] / "conformance" / "fixtures"
+
+
+@pytest.fixture(scope="session")
+def jwks() -> dict:
+    return json.loads((FIXTURES / "jwks.json").read_text())
+
+
+@pytest.fixture(scope="session")
+def receipts() -> dict:
+    return json.loads((FIXTURES / "receipts.json").read_text())
+
+
+@pytest.fixture(scope="session")
+def http_fixtures() -> dict:
+    return json.loads((FIXTURES / "http.json").read_text())

yanez_agent_authorization-0.1.0a1/tests/test_client.py

@@ -0,0 +1,200 @@
+"""Agent-client behavior: auth header, idempotency, error typing, redirect refusal,
+and terminal-state polling. Async client driven through asyncio.run so the suite needs
+no async pytest plugin."""
+from __future__ import annotations
+
+import asyncio
+
+import httpx
+import pytest
+
+from yanez_authz import (
+    AuthenticationError,
+    AuthorizationClient,
+    ConflictError,
+    FeatureUnavailableError,
+    InvalidRequestError,
+    NotFoundError,
+    RateLimitError,
+    TermsTooLargeError,
+    TransportError,
+)
+
+BASE = "https://yanez.test"
+KEY = "yak_abc123abc123_s3cr3t-value"
+TERMS = {"action": "purchase", "summary": "Buy running shoes for $180 at Example Store"}
+
+
+def _client(handler, **kw) -> AuthorizationClient:
+    return AuthorizationClient(BASE, KEY, transport=httpx.MockTransport(handler), **kw)
+
+
+def test_create_sends_bearer_and_generated_idempotency_key(http_fixtures):
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["auth"] = request.headers.get("Authorization")
+        seen["idem"] = request.headers.get("Idempotency-Key")
+        return httpx.Response(201, json=http_fixtures["create_response"])
+
+    async def main():
+        async with _client(handler) as client:
+            return await client.request_authorization(TERMS)
+
+    pending = asyncio.run(main())
+    assert seen["auth"] == f"Bearer {KEY}"
+    assert seen["idem"] and pending.idempotency_key == seen["idem"]
+    assert pending.status == "pending" and not pending.replayed
+
+
+def test_transport_retry_reuses_the_same_idempotency_key(http_fixtures):
+    attempts = []
+
+    class FlakyTransport(httpx.AsyncBaseTransport):
+        async def handle_async_request(self, request):
+            attempts.append(request.headers.get("Idempotency-Key"))
+            if len(attempts) == 1:
+                raise httpx.ConnectError("boom", request=request)
+            return httpx.Response(201, json=http_fixtures["create_response"],
+                                  headers={"Idempotency-Replayed": "true"})
+
+    async def main():
+        async with AuthorizationClient(BASE, KEY, transport=FlakyTransport()) as client:
+            return await client.request_authorization(TERMS, idempotency_key="retry-1")
+
+    pending = asyncio.run(main())
+    assert attempts == ["retry-1", "retry-1"]
+    assert pending.replayed is True
+
+
+@pytest.mark.parametrize("status,exc,create", [
+    (401, AuthenticationError, True),
+    (404, FeatureUnavailableError, True),   # the whole router is absent on create
+    (404, NotFoundError, False),            # unknown or cross-key id on get
+    (400, InvalidRequestError, True),
+    (409, ConflictError, True),
+    (413, TermsTooLargeError, True),
+    (422, InvalidRequestError, True),
+    (429, RateLimitError, True),
+])
+def test_http_errors_are_typed(status, exc, create):
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(status, json={"detail": "nope"})
+
+    async def main():
+        async with _client(handler) as client:
+            if create:
+                await client.request_authorization(TERMS)
+            else:
+                await client.get_authorization("azr_x")
+
+    with pytest.raises(exc):
+        asyncio.run(main())
+
+
+def test_errors_never_carry_the_agent_key():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(401, json={"detail": "Unauthorized"})
+
+    async def main():
+        async with _client(handler) as client:
+            await client.request_authorization(TERMS)
+
+    with pytest.raises(AuthenticationError) as e:
+        asyncio.run(main())
+    assert KEY not in str(e.value) and KEY not in repr(e.value)
+
+
+def test_redirects_are_transport_errors_not_followed():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(307, headers={"Location": "https://evil.example/"})
+
+    async def main():
+        async with _client(handler) as client:
+            await client.get_authorization("azr_x")
+
+    with pytest.raises(TransportError):
+        asyncio.run(main())
+
+
+def test_https_is_required_off_loopback():
+    with pytest.raises(ValueError):
+        AuthorizationClient("http://yanez.example", KEY)
+
+
+def test_wait_returns_every_terminal_state_as_a_value(http_fixtures):
+    for terminal in ("poll_approved", "poll_rejected", "poll_expired"):
+        responses = iter([http_fixtures["poll_pending"], http_fixtures[terminal]])
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            return httpx.Response(200, json=next(responses))
+
+        async def main():
+            async with _client(handler) as client:
+                return await client.wait_for_authorization("azr_x", 30,
+                                                           long_poll_seconds=0)
+
+        result = asyncio.run(main())
+        assert result.status == http_fixtures[terminal]["status"]
+        assert (result.artifact is not None) == (result.status == "approved")
+
+
+def test_wait_times_out_locally_without_touching_the_request(http_fixtures):
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json=http_fixtures["poll_pending"])
+
+    async def main():
+        async with _client(handler) as client:
+            await client.wait_for_authorization("azr_x", 0.2, long_poll_seconds=0)
+
+    with pytest.raises(TimeoutError):
+        asyncio.run(main())
+
+
+def test_malformed_request_id_is_rejected_before_any_request():
+    """A model-supplied id must never steer the keyed request to another path."""
+    calls = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls.append(str(request.url))
+        return httpx.Response(200, json={})
+
+    async def main():
+        async with _client(handler) as client:
+            await client.get_authorization("../../admin/keys?x=1")
+
+    with pytest.raises(InvalidRequestError):
+        asyncio.run(main())
+    assert calls == []
+
+
+def test_long_poll_sends_the_wait_query(http_fixtures):
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["url"] = str(request.url)
+        return httpx.Response(200, json=http_fixtures["poll_approved"])
+
+    async def main():
+        async with _client(handler) as client:
+            return await client.get_authorization("azr_x", wait_seconds=25)
+
+    asyncio.run(main())
+    assert seen["url"] == f"{BASE}/api/agent/authorizations/azr_x?wait=25"
+
+
+def test_wait_paces_polls_when_the_server_answers_early(http_fixtures):
+    """Wait 0 in the final second, or a proxy answering early, must not spin."""
+    calls = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls.append(1)
+        return httpx.Response(200, json=http_fixtures["poll_pending"])
+
+    async def main():
+        async with _client(handler) as client:
+            await client.wait_for_authorization("azr_x", 0.3, long_poll_seconds=0)
+
+    with pytest.raises(TimeoutError):
+        asyncio.run(main())
+    assert len(calls) <= 3

yanez_agent_authorization-0.1.0a1/tests/test_verifier.py

@@ -0,0 +1,230 @@
+"""Verifier behavior against the shared conformance fixtures — the same cases the
+TypeScript SDK runs, so both languages reach the same verdict on every receipt."""
+from __future__ import annotations
+
+import httpx
+import jwt
+import pytest
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from yanez_authz import (
+    AlreadyConsumedError,
+    ConsentPolicyError,
+    InvalidRequestError,
+    ReceiptVerificationError,
+    ReceiptVerifier,
+    TransportError,
+)
+
+BASE = "https://yanez.test"
+ISSUER = "https://yanez.test"
+
+_ERRORS = {"verification": ReceiptVerificationError, "consent_policy": ConsentPolicyError}
+
+
+def _signed(receipts, **overrides) -> str:
+    """The conformance receipt re-signed under the fixture key with claim overrides."""
+    key = Ed25519PrivateKey.from_private_bytes(bytes(range(32)))  # generate_fixtures seed
+    claims = jwt.decode(receipts["cases"]["valid"]["artifact"],
+                        options={"verify_signature": False})
+    return jwt.encode({**claims, **overrides}, key, algorithm="EdDSA",
+                      headers={"kid": "authz_test_1"})
+
+
+def _verifier(jwks, extra_handler=None, **kw) -> tuple[ReceiptVerifier, list[str]]:
+    calls: list[str] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls.append(request.url.path)
+        if request.url.path == "/api/authz/public-keys":
+            return httpx.Response(200, json=jwks)
+        if extra_handler is not None:
+            return extra_handler(request)
+        return httpx.Response(404, json={"detail": "unknown"})
+
+    v = ReceiptVerifier(BASE, ISSUER, transport=httpx.MockTransport(handler), **kw)
+    return v, calls
+
+
+def test_conformance_cases(jwks, receipts):
+    verifier, _ = _verifier(jwks)
+    for name, case in receipts["cases"].items():
+        now = case.get("now", receipts["now_fresh"])
+        expected_terms = case.get("expected_terms", receipts["expected_terms"])
+        if case["ok"]:
+            receipt = verifier.verify(case["artifact"], expected_terms, 900, now=now)
+            assert receipt.jti and receipt.sub, name
+            assert receipt.terms == receipts["expected_terms"], name
+            assert receipt.match_overlap >= 0, name
+        else:
+            with pytest.raises(_ERRORS[case["error"]]):
+                verifier.verify(case["artifact"], expected_terms, 900, now=now)
+            # pytest.raises message loses `name`; re-raise manually if this ever fails.
+
+
+def test_valid_receipt_exposes_the_full_decoded_profile(jwks, receipts):
+    verifier, _ = _verifier(jwks)
+    case = receipts["cases"]["valid"]
+    receipt = verifier.verify(case["artifact"], receipts["expected_terms"], 900,
+                              now=receipts["now_fresh"])
+    assert receipt.decided_at == receipts["decided_at"]
+    assert receipt.agent_key_id.startswith("yak_")
+    assert receipt.consent_not_after is None
+
+
+def test_unknown_kids_do_not_refetch_within_the_cooldown(jwks, receipts):
+    """Anyone can submit garbage kids; that must not turn into a fetch per receipt."""
+    verifier, calls = _verifier(jwks)
+    case = receipts["cases"]["unknown_kid"]
+    for _ in range(5):
+        with pytest.raises(ReceiptVerificationError):
+            verifier.verify(case["artifact"], receipts["expected_terms"], 900,
+                            now=receipts["now_fresh"])
+    assert calls.count("/api/authz/public-keys") == 1
+
+
+def test_rotated_kid_verifies_after_the_cooldown_refresh(jwks, receipts):
+    """The rotation path the refresh exists for: after the cooldown, an unknown kid
+    fetches again and the second fetch carries the new kid."""
+    rotated = {"keys": [{**jwks["keys"][0], "kid": "authz_retired"}]}
+    fetches = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        fetches.append(1)
+        return httpx.Response(200, json=jwks if len(fetches) == 1 else rotated)
+
+    verifier = ReceiptVerifier(BASE, ISSUER, transport=httpx.MockTransport(handler))
+    verifier.verify(receipts["cases"]["valid"]["artifact"], receipts["expected_terms"],
+                    900, now=receipts["now_fresh"])
+    verifier._keys_fetched_at -= 31  # the cooldown has elapsed
+    case = receipts["cases"]["unknown_kid"]  # signed with kid authz_retired
+    receipt = verifier.verify(case["artifact"], receipts["expected_terms"], 900,
+                              now=receipts["now_fresh"])
+    assert receipt.jti and len(fetches) == 2
+
+
+def test_key_set_is_cached_between_verifies(jwks, receipts):
+    verifier, calls = _verifier(jwks)
+    case = receipts["cases"]["valid"]
+    for _ in range(3):
+        verifier.verify(case["artifact"], receipts["expected_terms"], 900,
+                        now=receipts["now_fresh"])
+    assert calls.count("/api/authz/public-keys") == 1
+
+
+def test_introspect_and_authorize_action_map_consumption(jwks, receipts, http_fixtures):
+    responses = iter([http_fixtures["introspect_first_consume"],
+                      http_fixtures["introspect_repeat_consume"]])
+
+    def introspect(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json=next(responses))
+
+    verifier, _ = _verifier(jwks, extra_handler=introspect,
+                            now=lambda: receipts["now_fresh"])
+    artifact = receipts["cases"]["valid"]["artifact"]
+
+    receipt = verifier.authorize_action(artifact, receipts["expected_terms"], 900,
+                                        consume=True)
+    assert receipt.jti == http_fixtures["introspect_first_consume"]["jti"]
+
+    # The repeat is a genuine receipt that must never authorize the action again.
+    with pytest.raises(AlreadyConsumedError):
+        verifier.authorize_action(artifact, receipts["expected_terms"], 900, consume=True)
+
+
+def test_expected_issuer_is_mandatory_and_https_is_enforced():
+    with pytest.raises(ValueError):
+        ReceiptVerifier(BASE, "")
+    with pytest.raises(ValueError):
+        ReceiptVerifier("http://yanez.example", ISSUER)
+    ReceiptVerifier("http://127.0.0.1:8001", ISSUER)  # loopback development is fine
+
+
+def test_expected_sub_and_agent_key_bind_the_receipt(jwks, receipts):
+    verifier, _ = _verifier(jwks)
+    artifact = receipts["cases"]["valid"]["artifact"]
+    terms, now = receipts["expected_terms"], receipts["now_fresh"]
+    genuine = verifier.verify(artifact, terms, 900, now=now)
+    bound = verifier.verify(artifact, terms, 900, now=now, expected_sub=genuine.sub,
+                            expected_agent_key_id=genuine.agent_key_id)
+    assert bound.jti == genuine.jti
+    with pytest.raises(ReceiptVerificationError):
+        verifier.verify(artifact, terms, 900, now=now, expected_sub="b" * 32)
+    with pytest.raises(ReceiptVerificationError):
+        verifier.authorize_action(artifact, terms, 900, consume=False,
+                                  expected_agent_key_id="yak_someone_else")
+
+
+def test_decided_at_in_the_future_is_rejected_beyond_clock_skew(jwks, receipts):
+    verifier, _ = _verifier(jwks)
+    terms, now = receipts["expected_terms"], receipts["now_fresh"]
+    with pytest.raises(ReceiptVerificationError):
+        verifier.verify(_signed(receipts, iat=now + 3600, yanez_decided_at=now + 3600),
+                        terms, 900, now=now)
+    assert verifier.verify(_signed(receipts, iat=now + 30, yanez_decided_at=now + 30),
+                           terms, 900, now=now).jti
+
+
+def test_null_or_mistyped_required_claims_are_rejected(jwks, receipts):
+    verifier, _ = _verifier(jwks)
+    for bad in (_signed(receipts, yanez_agent_key_id=None), _signed(receipts, sub=12345)):
+        with pytest.raises(ReceiptVerificationError):
+            verifier.verify(bad, receipts["expected_terms"], 900, now=receipts["now_fresh"])
+
+
+def test_terms_comparison_keeps_bool_and_int_distinct(jwks, receipts):
+    """Python's True == 1 must not reach a verdict the TypeScript SDK would not."""
+    verifier, _ = _verifier(jwks)
+    terms, now = receipts["expected_terms"], receipts["now_fresh"]
+    artifact = _signed(receipts, yanez_terms={**terms, "gift": True})
+    with pytest.raises(ReceiptVerificationError):
+        verifier.verify(artifact, {**terms, "gift": 1}, 900, now=now)
+    assert verifier.verify(artifact, {**terms, "gift": True}, 900, now=now).jti
+
+
+def test_malformed_key_set_is_tolerated_per_entry_and_refused_per_body(jwks, receipts):
+    good = jwks["keys"][0]
+    artifact, terms, now = (receipts["cases"]["valid"]["artifact"],
+                            receipts["expected_terms"], receipts["now_fresh"])
+    verifier, _ = _verifier({"keys": [{k: v for k, v in good.items() if k != "x"}, good]})
+    assert verifier.verify(artifact, terms, 900, now=now).jti  # bad entry skipped
+    verifier, _ = _verifier("not a key set")
+    with pytest.raises(TransportError):
+        verifier.verify(artifact, terms, 900, now=now)
+
+
+def test_introspection_outcomes_are_typed(jwks, receipts, http_fixtures):
+    artifact, terms = receipts["cases"]["valid"]["artifact"], receipts["expected_terms"]
+    outcomes = [
+        (httpx.Response(200, json=http_fixtures["introspect_bad_signature"]),
+         ReceiptVerificationError),
+        (httpx.Response(200, json={"valid": True, "reason": "consent_expired",
+                                   "consumed_now": False}), ConsentPolicyError),
+        (httpx.Response(422, json={"detail": "artifact too large"}), InvalidRequestError),
+    ]
+    for response, exc in outcomes:
+        verifier, _ = _verifier(jwks, extra_handler=lambda r, response=response: response,
+                                now=lambda: receipts["now_fresh"])
+        with pytest.raises(exc):
+            verifier.authorize_action(artifact, terms, 900, consume=True)
+
+
+def test_consume_requires_confirmed_consumption(jwks, receipts):
+    artifact, terms = receipts["cases"]["valid"]["artifact"], receipts["expected_terms"]
+    for body in ({"valid": True, "consumed_now": False}, {"valid": True}):
+        verifier, _ = _verifier(jwks, extra_handler=lambda r, body=body: httpx.Response(200, json=body),
+                                now=lambda: receipts["now_fresh"])
+        with pytest.raises(ReceiptVerificationError):
+            verifier.authorize_action(artifact, terms, 900, consume=True)
+
+
+def test_numeric_date_claims_must_be_integers(jwks, receipts):
+    verifier, _ = _verifier(jwks)
+    terms, now = receipts["expected_terms"], receipts["now_fresh"]
+    for bad in (_signed(receipts, yanez_consent_not_after="not-a-date"),
+                _signed(receipts, yanez_decided_at="x")):
+        with pytest.raises(ReceiptVerificationError):
+            verifier.verify(bad, terms, 900, now=now)
+    # A JSON null bound is "no bound", the same verdict the TypeScript SDK reaches.
+    receipt = verifier.verify(_signed(receipts, yanez_consent_not_after=None), terms, 900, now=now)
+    assert receipt.consent_not_after is None