solvapay 0.1.0.dev4__py3-none-any.whl

solvapay/agents/calls.py

@@ -0,0 +1,302 @@
+"""One agent's paid call, start to finish.
+
+SolvaPay decides everything: ``authorize`` before the upstream call finds the
+customer, checks the spend policy, holds the estimate against the budget and
+the balance, and waits for the owner when they must approve; ``complete``
+after it settles at the cost the upstream reported. This module only drives
+those two requests and turns their answers into ``Allowed`` or ``Refused``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import logging
+import math
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from decimal import ROUND_HALF_UP, Decimal, localcontext
+from typing import Any, Literal
+
+from ..client import AsyncApiClient
+from ..errors import SolvaPayError
+from .identity import VerifiedAgent, agent_refusal
+
+logger = logging.getLogger("solvapay.agents")
+
+AUTHORIZE_WAIT_MAX_SECONDS = 55
+PROMPT_EXCERPT_MAX = 1500
+
+RefusalReason = Literal[
+    "customer_not_linked",
+    "ask",
+    "deny",
+    "topup_required",
+    "approval_declined",
+    "approval_expired",
+    "agent_not_accepted",
+    "approval_timed_out",
+    "approval_client_closed",
+    "unavailable",
+]
+
+# Refusals money or the owner can settle: HTTP 402.
+_OWNER_OR_MONEY_REASONS = frozenset(
+    {
+        "customer_not_linked",
+        "topup_required",
+        "ask",
+        "approval_declined",
+        "approval_expired",
+        "approval_timed_out",
+        "approval_client_closed",
+    }
+)
+
+NOT_ACCEPTED = "SolvaPay did not accept this agent (revoked or not for this merchant)."
+UNAVAILABLE = "SolvaPay could not be reached to authorize this call. Try again shortly."
+
+
+@dataclass(frozen=True)
+class Money:
+    amount: str
+    """A decimal amount with up to 8 places."""
+    currency: str
+    """ISO 4217, such as USD."""
+
+
+@dataclass(frozen=True)
+class PromptFacts:
+    prompt_hash: str
+    tool_error: bool
+    excerpt: str
+
+
+def prompt_facts(text: str, tool_error: bool = False) -> PromptFacts:
+    """A hash of the prompt (repeats show loops), and its end, sent only if the owner opted in.
+
+    The end is the last ``PROMPT_EXCERPT_MAX`` UTF-16 code units, as TypeScript's
+    ``slice`` counts and SolvaPay measures them: an emoji counts twice."""
+    units = text.encode("utf-16-le")
+    if len(units) <= 2 * PROMPT_EXCERPT_MAX:
+        excerpt = text
+    else:
+        end = units[-2 * PROMPT_EXCERPT_MAX :]
+        # The cut went through a character outside the BMP: drop its lone low half.
+        if 0xDC00 <= int.from_bytes(end[:2], "little") <= 0xDFFF:
+            end = end[2:]
+        excerpt = end.decode("utf-16-le")
+    return PromptFacts(
+        prompt_hash=f"sha256:{hashlib.sha256(text.encode('utf-8')).hexdigest()}",
+        tool_error=tool_error,
+        excerpt=excerpt,
+    )
+
+
+def amount_string(amount: float | Decimal | str) -> str:
+    """An amount as a decimal string with up to 8 places, trailing zeros trimmed.
+
+    A float is rounded from its exact binary value, as TypeScript's ``toFixed`` does:
+    ``1.5e-8`` is just under the half, so it is ``0.00000001``."""
+    exact = Decimal(amount) if isinstance(amount, float) else Decimal(str(amount))
+    # Enough precision for every integer digit plus the 8 places (the default 28
+    # fails from 1e20 up).
+    with localcontext() as context:
+        context.prec = max(28, exact.adjusted() + 10)
+        fixed = exact.quantize(Decimal("0.00000001"), rounding=ROUND_HALF_UP)
+    text = f"{fixed:f}".rstrip("0").rstrip(".")
+    return text or "0"
+
+
+@dataclass
+class AgentCall:
+    request_id: str
+    """The merchant's id for the call; SolvaPay keys the call on it."""
+    agent_token: str
+    """The token as presented: SolvaPay verifies it again."""
+    agent: VerifiedAgent
+    item: str
+    """What is used: a model id, a tool name."""
+    estimate: Money
+    prompt: PromptFacts | None = None
+    cancelled: Callable[[], bool] = lambda: False
+    """True once the caller has gone away, to stop waiting for the owner."""
+    log_fields: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Refused:
+    reason: RefusalReason
+    message: str
+    """The sentence for the human, in every case."""
+
+
+@dataclass(frozen=True)
+class CallResult:
+    status: int
+    """The status the upstream answered with."""
+    cost: tuple[float | Decimal | str, str] | None
+    """The cost the upstream reported, (amount, currency), or None when none arrived."""
+    interrupted: str | None = None
+
+
+class Allowed:
+    """The call may go ahead. Finish it once, when the upstream has answered."""
+
+    def __init__(self, api: AsyncApiClient, call: AgentCall, answer: Any) -> None:
+        self._api = api
+        self._call = call
+        self.call_ref: str = answer.call_ref
+        self.reservation = answer.reservation
+        self.item = call.item
+        self.estimate = call.estimate
+        self._completed = False
+
+    async def finish(self, result: CallResult) -> Any:
+        """Settles the call at how the upstream answered. ``None`` when SolvaPay could not
+        be told: logged, and the reservation lapses at the estimate."""
+        body: dict[str, Any] = {
+            "status": result.status,
+            "cost": None
+            if result.cost is None
+            else {"amount": amount_string(result.cost[0]), "currency": result.cost[1]},
+        }
+        if result.interrupted:
+            body["interrupted"] = result.interrupted
+        return await self._complete(body)
+
+    async def release(self, reason: str) -> None:
+        """The call never reached the upstream: completed as a failure, so nothing is charged."""
+        await self._complete({"status": 502, "cost": None, "interrupted": reason})
+
+    async def _complete(self, body: dict[str, Any]) -> Any:
+        if self._completed:
+            raise SolvaPayError(
+                f"Call {self.call_ref} was already completed", code="call_completed"
+            )
+        self._completed = True
+        try:
+            answer = await self._api.complete_agent_call(call_ref=self.call_ref, body=body)
+            # The call's books are settled on it: every field must be there.
+            _require_text(answer.call_ref, "callRef")
+            _require_text(answer.amount.amount, "amount.amount")
+            _require_text(answer.amount.currency, "amount.currency")
+            return answer
+        except SolvaPayError as error:
+            logger.error(
+                "call.complete_failed %s",
+                {**_fields(self._call), "callRef": self.call_ref, "status": error.status,
+                 "error": error.message},
+            )  # fmt: skip
+            return None
+
+
+def _require_text(value: str | None, label: str) -> None:
+    """A field TypeScript requires as a non-empty string; the generated model allows less."""
+    if not value:
+        raise SolvaPayError(f"{label} must be a non-empty string", code="invalid_response")
+
+
+def _check_authorize(answer: Any) -> None:
+    """Checked field by field, as TypeScript does: a paid call goes ahead on it."""
+    _require_text(answer.call_ref, "callRef")
+    if answer.status == "allowed":
+        _require_text(answer.reservation.expires_at, "reservation.expiresAt")
+        return
+    _require_text(answer.message, "message")
+    if answer.status == "waiting":
+        _require_text(answer.approval.reference, "approval.reference")
+        _require_text(answer.approval.expires_at, "approval.expiresAt")
+
+
+def _fields(call: AgentCall) -> dict[str, Any]:
+    return {
+        "requestId": call.request_id,
+        **call.log_fields,
+        "agentRef": call.agent.agent_ref,
+        "userRef": call.agent.principal_ref,
+        "item": call.item,
+        "estimate": f"{call.estimate.amount} {call.estimate.currency}",
+    }
+
+
+class AgentCalls:
+    """Authorizes agent calls with SolvaPay, waiting up to ``max_wait_seconds`` for the owner."""
+
+    def __init__(
+        self,
+        api: AsyncApiClient,
+        *,
+        max_wait_seconds: int,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self.api = api
+        self.max_wait_seconds = max_wait_seconds
+        self._clock = clock
+
+    def _refuse(
+        self, call: AgentCall, reason: RefusalReason, message: str, **fields: Any
+    ) -> Refused:
+        logger.info("call.refused %s", {**_fields(call), "reason": reason, **fields})
+        return Refused(reason, message)
+
+    async def begin(self, call: AgentCall) -> Allowed | Refused:
+        deadline = self._clock() + self.max_wait_seconds
+        while True:
+            wait = max(0, min(AUTHORIZE_WAIT_MAX_SECONDS, math.floor(deadline - self._clock())))
+            body: dict[str, Any] = {
+                "agentToken": call.agent_token,
+                "requestId": call.request_id,
+                "item": call.item,
+                "estimate": {"amount": call.estimate.amount, "currency": call.estimate.currency},
+                "wait": wait,
+            }
+            if call.prompt:
+                body["promptHash"] = call.prompt.prompt_hash
+                body["toolError"] = call.prompt.tool_error
+                # Only when the token SolvaPay minted says the owner opted in.
+                if call.agent.prompt_excerpt:
+                    body["promptExcerpt"] = call.prompt.excerpt
+            try:
+                answer = (await self.api.authorize_agent_call(body=body)).root
+                _check_authorize(answer)
+            except SolvaPayError as error:
+                logger.error(
+                    "call.authorize_failed %s",
+                    {**_fields(call), "status": error.status, "error": error.message},
+                )
+                # A refusal of the merchant (agent payments off, a secret key for the
+                # other environment) is not the agent's: unavailable, logged above.
+                if agent_refusal(error):
+                    return self._refuse(call, "agent_not_accepted", NOT_ACCEPTED)
+                return self._refuse(call, "unavailable", UNAVAILABLE)
+
+            if answer.status == "allowed":
+                logger.info("call.allowed %s", {**_fields(call), "callRef": answer.call_ref})
+                return Allowed(self.api, call, answer)
+            if answer.status == "refused":
+                return self._refuse(call, answer.reason, answer.message, callRef=answer.call_ref)
+            held = {"callRef": answer.call_ref, "approvalRef": answer.approval.reference}
+            if self.max_wait_seconds == 0:
+                return self._refuse(call, "ask", answer.message, **held)
+            if call.cancelled():
+                return self._refuse(call, "approval_client_closed", answer.message, **held)
+            if self._clock() >= deadline:
+                return self._refuse(call, "approval_timed_out", answer.message, **held)
+            logger.info("call.waiting %s", {**_fields(call), **held})
+            await asyncio.sleep(answer.retry_after_seconds)
+
+
+def refusal_status(reason: RefusalReason) -> int:
+    """The HTTP status for a refusal: 402 for what money or the owner can settle, 422 for a
+    policy deny, 401 for an agent SolvaPay did not accept, 502 when it could not be reached."""
+    if reason == "agent_not_accepted":
+        return 401
+    if reason == "unavailable":
+        return 502
+    if reason == "deny":
+        return 422
+    if reason in _OWNER_OR_MONEY_REASONS:
+        return 402
+    raise SolvaPayError(f"Refusal reason {reason!r} has no status", code="unknown_refusal_reason")

solvapay/agents/identity.py

@@ -0,0 +1,293 @@
+"""Who is calling: SolvaPay agent tokens and agent keys.
+
+Agent tokens are ES256 JWTs signed by SolvaPay's agent service, with keys at
+``<issuer>/jwks.json``, issued for one merchant (``aud`` is its provider
+reference, or this server's resource URL for OAuth tokens). Agent keys
+(``agk_…``) are opaque: SolvaPay says whose they are.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Literal
+
+import jwt
+
+from ..client import AsyncApiClient
+from ..errors import SolvaPayError
+from .oauth import canonical_resource
+
+AgentEnvironment = Literal["sandbox", "live"]
+AGENT_ENVIRONMENTS: tuple[AgentEnvironment, ...] = ("sandbox", "live")
+AGENT_KEY_PREFIX = "agk_"
+AGENT_TOKEN_EXCERPT_CLAIM = "px"
+AGENT_TOKEN_CLIENT_CLAIM = "cid"
+AGENT_TOKEN_ENV_CLAIM = "env"
+CLOCK_TOLERANCE_SECONDS = 30
+AGENT_KEY_CACHE_SECONDS = 30.0
+
+RejectionReason = Literal["expired", "invalid", "environment_mismatch"]
+
+
+@dataclass(frozen=True)
+class VerifiedAgent:
+    agent_ref: str
+    """The agent, ``agt_…`` (the token's ``sub``)."""
+    principal_ref: str
+    """Pairwise reference of the account at this merchant, ``ppl_…``."""
+    prompt_excerpt: bool
+    """The prompt's end may go to SolvaPay with this agent's calls (``px`` claim)."""
+    environment: AgentEnvironment
+    token_id: str | None = None
+    expires_at: datetime | None = None
+    client_id: str | None = None
+
+
+@dataclass(frozen=True)
+class AgentRejected:
+    reason: RejectionReason
+    detail: str
+
+
+AgentResult = VerifiedAgent | AgentRejected
+
+
+def _check_environment(agent: VerifiedAgent, merchant: AgentEnvironment | None) -> AgentResult:
+    if merchant is not None and agent.environment != merchant:
+        return AgentRejected(
+            "environment_mismatch",
+            f"This agent spends in {agent.environment}, and this secret key is for {merchant}",
+        )
+    return agent
+
+
+def _is_number(value: Any) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def _key_matches(jwk: dict[str, Any], kid: str | None) -> bool:
+    """Whether a JWKS member may verify an ES256 token with this ``kid``, by the rules
+    TypeScript's ``jose`` applies: a token without a ``kid`` may use any matching key."""
+    if jwk.get("kty") != "EC" or jwk.get("crv") != "P-256":
+        return False
+    if kid is not None and jwk.get("kid") != kid:
+        return False
+    if isinstance(jwk.get("alg"), str) and jwk["alg"] != "ES256":
+        return False
+    if isinstance(jwk.get("use"), str) and jwk["use"] != "sig":
+        return False
+    key_ops = jwk.get("key_ops")
+    return not isinstance(key_ops, list) or "verify" in key_ops
+
+
+class AgentTokenVerifier:
+    """Verifies agent tokens against SolvaPay's published keys."""
+
+    def __init__(
+        self,
+        *,
+        issuer: str,
+        provider_ref: str,
+        resource: str | None = None,
+        environment: AgentEnvironment | None = None,
+        jwks: jwt.PyJWKClient | None = None,
+        clock: Callable[[], float] = time.time,
+    ) -> None:
+        self.issuer = issuer
+        self.audiences = [provider_ref] + ([canonical_resource(resource)] if resource else [])
+        self.environment = environment
+        self._jwks = jwks or jwt.PyJWKClient(f"{issuer.rstrip('/')}/jwks.json", cache_keys=True)
+        self._clock = clock
+
+    def _key(self, kid: str | None) -> Any:
+        """The one key that may have signed the token. The set is fetched again once when
+        none matches, as after SolvaPay rotates its key; more than one is ambiguous."""
+        for refresh in (False, True):
+            keys = [
+                key.key
+                for key in self._jwks.get_jwk_set(refresh=refresh).keys
+                if _key_matches(getattr(key, "_jwk_data", {}), kid)
+            ]
+            if len(keys) > 1:
+                raise jwt.PyJWKClientError("More than one key in the JWKS matches the token")
+            if keys:
+                return keys[0]
+        raise jwt.PyJWKClientError("No key in the JWKS matches the token")
+
+    def _claims(self, token: str) -> dict[str, Any]:
+        header = jwt.get_unverified_header(token)
+        if header.get("alg") != "ES256":
+            raise jwt.InvalidAlgorithmError("The token is not signed with ES256")
+        kid = header.get("kid")
+        claims: dict[str, Any] = jwt.decode(
+            token,
+            self._key(kid if isinstance(kid, str) else None),
+            algorithms=["ES256"],
+            audience=self.audiences,
+            issuer=self.issuer,
+            # The times are checked below, as TypeScript's jose checks them: claims must
+            # be numbers, and an iat in the future is not refused.
+            options={
+                "require": ["sub", "exp", "iat", "jti"],
+                "verify_exp": False,
+                "verify_nbf": False,
+                "verify_iat": False,
+                "verify_sub": False,
+                "verify_jti": False,
+            },
+        )
+        now = int(self._clock())
+        if not _is_number(claims["iat"]):
+            raise jwt.InvalidIssuedAtError("iat must be a number")
+        nbf = claims.get("nbf")
+        if nbf is not None:
+            if not _is_number(nbf):
+                raise jwt.ImmatureSignatureError("nbf must be a number")
+            if nbf > now + CLOCK_TOLERANCE_SECONDS:
+                raise jwt.ImmatureSignatureError("The token is not yet valid (nbf)")
+        if not _is_number(claims["exp"]):
+            raise jwt.DecodeError("exp must be a number")
+        if claims["exp"] <= now - CLOCK_TOLERANCE_SECONDS:
+            raise jwt.ExpiredSignatureError("Signature has expired")
+        return claims
+
+    def verify(self, token: str) -> AgentResult:
+        try:
+            claims = self._claims(token)
+        except jwt.ExpiredSignatureError as error:
+            return AgentRejected("expired", str(error))
+        except jwt.PyJWTError as error:
+            return AgentRejected("invalid", str(error))
+
+        client_id = claims.get(AGENT_TOKEN_CLIENT_CLAIM)
+        if client_id is not None and not isinstance(client_id, str):
+            return AgentRejected("invalid", "cid is not a string")
+        sub, principal = claims.get("sub"), claims.get("principal")
+        if not isinstance(sub, str) or not sub.startswith("agt_"):
+            return AgentRejected("invalid", "sub is not an agent reference")
+        if not isinstance(principal, str) or not principal.startswith("ppl_"):
+            return AgentRejected("invalid", "principal is missing")
+        if claims.get("scope") != "usage":
+            return AgentRejected("invalid", "scope is not usage")
+        env = claims.get(AGENT_TOKEN_ENV_CLAIM)
+        if env not in AGENT_ENVIRONMENTS:
+            return AgentRejected("invalid", "env is not sandbox or live")
+        return _check_environment(
+            VerifiedAgent(
+                agent_ref=sub,
+                principal_ref=principal,
+                prompt_excerpt=claims.get(AGENT_TOKEN_EXCERPT_CLAIM) is True,
+                environment=env,
+                token_id=str(claims["jti"]),
+                expires_at=datetime.fromtimestamp(claims["exp"], tz=timezone.utc),
+                client_id=client_id or None,
+            ),
+            self.environment,
+        )
+
+
+class AgentKeyVerifier:
+    """Asks SolvaPay whose an agent key is, reusing each answer for 30 seconds.
+
+    SolvaPay out of reach raises: every paid call would fail the same way.
+    """
+
+    def __init__(
+        self,
+        api: AsyncApiClient,
+        *,
+        environment: AgentEnvironment | None = None,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self.api = api
+        self.environment = environment
+        self._clock = clock
+        self._answers: dict[str, tuple[float, AgentResult]] = {}
+
+    async def verify(self, agent_key: str) -> AgentResult:
+        cached = self._answers.get(agent_key)
+        if cached and cached[0] > self._clock():
+            return cached[1]
+        try:
+            verified = await self.api.verify_agent_key(body={"agentKey": agent_key})
+            result: AgentResult = _check_environment(
+                VerifiedAgent(
+                    agent_ref=verified.agent_ref,
+                    principal_ref=verified.principal_ref,
+                    prompt_excerpt=verified.prompt_excerpt,
+                    environment=verified.environment,
+                ),
+                self.environment,
+            )
+        except SolvaPayError as error:
+            # Only a refusal of the key itself is the agent's. SolvaPay failing, or
+            # refusing the merchant (agent payments off, a secret key for the other
+            # environment), is raised for the merchant to fix.
+            reason = agent_refusal(error)
+            if reason is None:
+                raise
+            result = AgentRejected(reason, error.message)
+        self._answers[agent_key] = (self._clock() + AGENT_KEY_CACHE_SECONDS, result)
+        return result
+
+
+def agent_refusal(error: SolvaPayError) -> Literal["invalid", "environment_mismatch"] | None:
+    """Whose a 401 or 403 from SolvaPay's agent endpoints is, as in TypeScript.
+
+    The agent's: the token or key is unknown, revoked or another merchant's (401,
+    or 403 with no code), or from the other environment (403
+    ``environment_mismatch``). Any other code, such as ``feature_not_enabled``
+    (agent payments are off for this merchant) or ``key_env_mismatch`` (the
+    secret key is for the other environment), is the merchant's: ``None``."""
+    if error.status == 401:
+        return "invalid"
+    if error.status != 403:
+        return None
+    if error.code == "http_403":  # SolvaPay sent no code
+        return "invalid"
+    if error.code == "environment_mismatch":
+        return "environment_mismatch"
+    return None
+
+
+_JWT = re.compile(r"^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$")
+
+
+def looks_like_jwt(value: str) -> bool:
+    return bool(_JWT.fullmatch(value))
+
+
+def is_agent_key(value: str) -> bool:
+    return value.startswith(AGENT_KEY_PREFIX) and len(value) > len(AGENT_KEY_PREFIX)
+
+
+@dataclass(frozen=True)
+class NotAgent:
+    """The credential is not an agent's: the merchant's own auth decides."""
+
+
+Identification = VerifiedAgent | AgentRejected | NotAgent
+
+
+class AgentLayer:
+    """Tells an agent's credential from the merchant's own, and verifies it."""
+
+    def __init__(
+        self,
+        *,
+        verify_token: Callable[[str], AgentResult],
+        verify_key: Callable[[str], Awaitable[AgentResult]] | None = None,
+    ) -> None:
+        self._verify_token = verify_token
+        self._verify_key = verify_key
+
+    async def identify(self, presented: str) -> Identification:
+        if is_agent_key(presented) and self._verify_key is not None:
+            return await self._verify_key(presented)
+        if not looks_like_jwt(presented):
+            return NotAgent()
+        return self._verify_token(presented)