ralio 0.1.0__py3-none-any.whl

ralio/__init__.py

@@ -0,0 +1,59 @@
+"""Official Python SDK for the Ralio agentic payment API."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .client import RalioClient
+from .errors import (
+    RalioAPIError,
+    RalioAuthError,
+    RalioConfigError,
+    RalioError,
+    RalioNotFoundError,
+    RalioPermissionError,
+    RalioRateLimitError,
+    RalioRegistrationError,
+    RalioValidationError,
+)
+from .registration import register
+from .types import (
+    Agent,
+    ChatReply,
+    ChatStreamEvent,
+    CredentialBinding,
+    Message,
+    Page,
+    PaymentInstruction,
+    PaymentIntent,
+    Transaction,
+)
+
+# Single source of truth is the installed package metadata (pyproject.toml).
+try:
+    __version__ = version("ralio")
+except PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "RalioClient",
+    "register",
+    "Agent",
+    "ChatReply",
+    "ChatStreamEvent",
+    "CredentialBinding",
+    "Message",
+    "Page",
+    "PaymentIntent",
+    "PaymentInstruction",
+    "Transaction",
+    "RalioError",
+    "RalioConfigError",
+    "RalioRegistrationError",
+    "RalioAPIError",
+    "RalioAuthError",
+    "RalioPermissionError",
+    "RalioNotFoundError",
+    "RalioValidationError",
+    "RalioRateLimitError",
+]

ralio/_crypto.py

@@ -0,0 +1,161 @@
+"""ES256 / DPoP crypto primitives for the Ralio machine-auth path.
+
+Everything here mirrors what the Ralio API expects byte-for-byte:
+
+- P-256 (ES256) is the only curve the token endpoint accepts.
+- The public JWK is the canonical RFC 7638 form (``crv``/``kty``/``x``/``y``
+  only, sorted), so the thumbprint computed here matches the ``cnf.jkt`` the
+  server stamps on the access token and the fingerprint the owner confirms.
+- Client assertions follow RFC 7521/7523; DPoP proofs follow RFC 9449.
+"""
+
+from __future__ import annotations
+
+import base64
+import contextlib
+import hashlib
+import json
+import os
+import secrets
+import tempfile
+import time
+from pathlib import Path
+from typing import Any
+
+import jwt as pyjwt
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.primitives.asymmetric.ec import EllipticCurvePrivateKey
+
+CLIENT_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
+
+# The server rejects assertions older than 300s; stay well under to absorb skew.
+_CLIENT_ASSERTION_TTL_SECONDS = 60
+_SECRET_FILE_MODE = 0o600
+
+
+def b64url(raw: bytes) -> str:
+    """Unpadded base64url — the only form RFC 7515/7517/7638 accept."""
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+
+
+def generate_keypair() -> tuple[EllipticCurvePrivateKey, dict[str, str]]:
+    """Mint a P-256 keypair and return ``(private_key, canonical_public_jwk)``."""
+    private_key = ec.generate_private_key(ec.SECP256R1())
+    return private_key, public_jwk(private_key)
+
+
+def public_jwk(private_key: EllipticCurvePrivateKey) -> dict[str, str]:
+    """Return the canonical RFC 7638 public JWK for *private_key*."""
+    numbers = private_key.public_key().public_numbers()
+    return {
+        "crv": "P-256",
+        "kty": "EC",
+        "x": b64url(numbers.x.to_bytes(32, "big")),
+        "y": b64url(numbers.y.to_bytes(32, "big")),
+    }
+
+
+def jwk_thumbprint(canonical_jwk: dict[str, str]) -> str:
+    """RFC 7638 thumbprint of a canonical JWK — used as ``kid`` and key id."""
+    canonical_json = json.dumps(canonical_jwk, separators=(",", ":"), sort_keys=True)
+    return b64url(hashlib.sha256(canonical_json.encode("ascii")).digest())
+
+
+def save_private_key(path: str | Path, private_key: EllipticCurvePrivateKey) -> Path:
+    """Write *private_key* as PKCS8 PEM at *path*, mode 0600, atomically."""
+    dest = Path(path)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    pem = private_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    tmp_fd, tmp_path = tempfile.mkstemp(dir=dest.parent, prefix=".tmp-")
+    try:
+        with contextlib.suppress(OSError, AttributeError):
+            # fchmod unavailable on Windows; set perms before any bytes land.
+            os.fchmod(tmp_fd, _SECRET_FILE_MODE)
+        with os.fdopen(tmp_fd, "wb") as f:
+            tmp_fd = -1
+            f.write(pem)
+        os.replace(tmp_path, dest)
+    except BaseException:
+        if tmp_fd >= 0:
+            os.close(tmp_fd)
+        with contextlib.suppress(OSError):
+            os.unlink(tmp_path)
+        raise
+    return dest
+
+
+def load_private_key(path: str | Path) -> EllipticCurvePrivateKey:
+    """Load a PKCS8 PEM P-256 private key from *path*."""
+    key = serialization.load_pem_private_key(Path(path).read_bytes(), password=None)
+    if not isinstance(key, EllipticCurvePrivateKey):
+        raise ValueError("Ralio credentials require a P-256 (EC) private key")
+    return key
+
+
+def sign_client_assertion(
+    private_key: EllipticCurvePrivateKey,
+    *,
+    client_id: str,
+    audience: str,
+    kid: str,
+    ttl_seconds: int = _CLIENT_ASSERTION_TTL_SECONDS,
+) -> str:
+    """Sign an RFC 7523 JWT bearer client assertion.
+
+    ``iss`` and ``sub`` both equal *client_id*; ``aud`` is the absolute token
+    endpoint URL. ``kid`` is the JWK thumbprint so the server can locate the
+    binding directly.
+    """
+    iat = int(time.time())
+    payload = {
+        "iss": client_id,
+        "sub": client_id,
+        "aud": audience,
+        "iat": iat,
+        "exp": iat + ttl_seconds,
+        "jti": secrets.token_urlsafe(16),
+    }
+    return pyjwt.encode(payload, _pem(private_key), algorithm="ES256", headers={"kid": kid})
+
+
+def sign_dpop_proof(
+    private_key: EllipticCurvePrivateKey,
+    *,
+    method: str,
+    url: str,
+    access_token: str,
+    jwk: dict[str, str],
+) -> str:
+    """Sign a single-use DPoP proof (RFC 9449) for one method + URL + token.
+
+    *url* must already have its query and fragment stripped (``htu`` per
+    RFC 9449 §4.2). The embedded ``jwk`` must be the canonical public JWK so
+    its thumbprint matches the access token's ``cnf.jkt``.
+    """
+    iat = int(time.time())
+    payload: dict[str, Any] = {
+        "htm": method.upper(),
+        "htu": url,
+        "iat": iat,
+        "jti": secrets.token_urlsafe(16),
+        "ath": b64url(hashlib.sha256(access_token.encode("ascii")).digest()),
+    }
+    return pyjwt.encode(
+        payload,
+        _pem(private_key),
+        algorithm="ES256",
+        headers={"typ": "dpop+jwt", "alg": "ES256", "jwk": dict(jwk)},
+    )
+
+
+def _pem(private_key: EllipticCurvePrivateKey) -> bytes:
+    return private_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )

ralio/_store.py

@@ -0,0 +1,105 @@
+"""On-disk credential store, shared with the Ralio CLI.
+
+The layout mirrors the CLI byte-for-byte so :func:`ralio.register` and
+``ralio auth agent`` are interchangeable — either one can write the
+credentials and the other (or :class:`ralio.RalioClient`) can consume them:
+
+- ``~/.ralio/credentials.json`` (0600) — ``client_id``, ``key_jkt``, tokens.
+- ``~/.ralio/keys/<jkt>.pem``   (0600) — the P-256 private key, PKCS8 PEM,
+  named by its RFC 7638 thumbprint.
+
+``RALIO_CONFIG_DIR`` overrides ``~/.ralio`` (tests, multi-tenant hosts).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+DEFAULT_BASE_URL = "https://api.ralio.co"
+
+_DIR_MODE = 0o700
+_SECRET_FILE_MODE = 0o600
+
+
+def resolve_base_url(explicit: str | None = None) -> str:
+    """Explicit value, else ``RALIO_API_URL``, else production. No trailing slash."""
+    return (explicit or _env("RALIO_API_URL") or DEFAULT_BASE_URL).rstrip("/")
+
+
+def config_dir() -> Path:
+    return Path(_env("RALIO_CONFIG_DIR") or Path.home() / ".ralio")
+
+
+def credentials_path() -> Path:
+    return config_dir() / "credentials.json"
+
+
+def key_path_for(jkt: str) -> Path:
+    """Default on-disk location for the key whose RFC 7638 thumbprint is *jkt*."""
+    return config_dir() / "keys" / f"{jkt}.pem"
+
+
+def save_credentials(creds: dict[str, Any]) -> None:
+    """Persist *creds* at the CLI-compatible credentials path, mode 0600, atomically."""
+    _ensure_secret_dir(config_dir())
+    _write_secret_file(credentials_path(), json.dumps(creds, indent=2) + "\n")
+
+
+def load_credentials() -> dict[str, Any] | None:
+    """Load persisted credentials, or ``None`` when absent or unreadable."""
+    try:
+        raw = credentials_path().read_text()
+    except OSError:
+        return None
+    try:
+        parsed = json.loads(raw)
+    except ValueError:
+        return None
+    return parsed if isinstance(parsed, dict) else None
+
+
+def ensure_keys_dir() -> None:
+    """Create the keys directory (and config dir) with owner-only permissions."""
+    _ensure_secret_dir(config_dir())
+    _ensure_secret_dir(config_dir() / "keys")
+
+
+def delete_private_key(path: str | Path) -> None:
+    """Remove a private key file, if present. Idempotent."""
+    Path(path).unlink(missing_ok=True)
+
+
+def _env(name: str) -> str | None:
+    """Env var value, with the empty string treated as unset."""
+    return os.environ.get(name) or None
+
+
+def _ensure_secret_dir(directory: Path) -> None:
+    directory.mkdir(parents=True, exist_ok=True)
+    # mkdir's mode is masked by the umask and skipped for pre-existing dirs.
+    with contextlib.suppress(OSError):
+        directory.chmod(_DIR_MODE)
+
+
+def _write_secret_file(path: Path, data: str) -> None:
+    """Atomic secret write: temp file chmodded 0600 before any bytes land."""
+    tmp_fd, tmp_path = tempfile.mkstemp(dir=path.parent, prefix=".tmp-")
+    try:
+        with contextlib.suppress(OSError, AttributeError):
+            # fchmod unavailable on Windows.
+            os.fchmod(tmp_fd, _SECRET_FILE_MODE)
+        with os.fdopen(tmp_fd, "w") as f:
+            tmp_fd = -1
+            f.write(data)
+        os.replace(tmp_path, path)
+    except BaseException:
+        if tmp_fd >= 0:
+            os.close(tmp_fd)
+        with contextlib.suppress(OSError):
+            os.unlink(tmp_path)
+        raise

ralio/auth.py

@@ -0,0 +1,111 @@
+"""Access-token lifecycle for the machine path.
+
+A :class:`TokenManager` mints tokens via the ``private_key_jwt`` client
+assertion, caches the access token until shortly before expiry, and rotates
+the refresh token. All token mutations are serialised behind a lock:
+
+> Presenting a previously-rotated refresh token is treated as a replay attack
+> and revokes the whole chain.
+
+so two threads must never race a refresh.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+
+import httpx
+from cryptography.hazmat.primitives.asymmetric.ec import EllipticCurvePrivateKey
+
+from . import _crypto
+from .errors import raise_for_response
+
+
+class TokenManager:
+    def __init__(
+        self,
+        *,
+        client_id: str,
+        private_key: EllipticCurvePrivateKey,
+        kid: str,
+        token_url: str,
+        http: httpx.Client,
+        scopes: tuple[str, ...] | None = None,
+        refresh_leeway_seconds: float = 300.0,
+    ) -> None:
+        self._client_id = client_id
+        self._private_key = private_key
+        self._kid = kid
+        self._token_url = token_url
+        self._http = http
+        self._scopes = scopes
+        self._leeway = refresh_leeway_seconds
+
+        self._lock = threading.Lock()
+        self._access_token: str | None = None
+        self._refresh_token: str | None = None
+        self._expires_at = 0.0
+
+    def access_token(self) -> str:
+        """Return a valid access token, minting or refreshing as needed."""
+        with self._lock:
+            if self._access_token and time.time() < self._expires_at - self._leeway:
+                return self._access_token
+            return self._obtain_locked()
+
+    def force_refresh(self) -> str:
+        """Discard the cached token and obtain a fresh one. Used after a 401."""
+        with self._lock:
+            self._access_token = None
+            return self._obtain_locked()
+
+    def _obtain_locked(self) -> str:
+        if self._refresh_token:
+            try:
+                return self._refresh_locked()
+            except Exception:
+                # Refresh chains can be revoked or expired; fall back to a
+                # fresh client-assertion mint, which always works while the
+                # binding is active.
+                self._refresh_token = None
+        return self._mint_locked()
+
+    def _mint_locked(self) -> str:
+        assertion = _crypto.sign_client_assertion(
+            self._private_key,
+            client_id=self._client_id,
+            audience=self._token_url,
+            kid=self._kid,
+        )
+        data = {
+            "grant_type": "client_credentials",
+            "client_assertion_type": _crypto.CLIENT_ASSERTION_TYPE,
+            "client_assertion": assertion,
+        }
+        if self._scopes:
+            data["scope"] = " ".join(self._scopes)
+        return self._exchange_locked(data)
+
+    def _refresh_locked(self) -> str:
+        assert self._refresh_token is not None
+        return self._exchange_locked(
+            {
+                "grant_type": "refresh_token",
+                "refresh_token": self._refresh_token,
+                "client_id": self._client_id,
+            }
+        )
+
+    def _exchange_locked(self, data: dict[str, str]) -> str:
+        response = self._http.post(
+            self._token_url,
+            data=data,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+        raise_for_response(response)
+        body = response.json()
+        self._access_token = body["access_token"]
+        self._refresh_token = body.get("refresh_token") or self._refresh_token
+        self._expires_at = time.time() + float(body.get("expires_in", 1800))
+        return self._access_token

ralio/client.py

@@ -0,0 +1,131 @@
+"""The top-level :class:`RalioClient`."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from types import TracebackType
+
+import httpx
+from cryptography.hazmat.primitives.asymmetric.ec import EllipticCurvePrivateKey
+
+from . import _crypto, _store
+from .auth import TokenManager
+from .errors import RalioConfigError
+from .resources import (
+    AgentsResource,
+    ChatResource,
+    PaymentIntentsResource,
+    TransactionsResource,
+)
+from .transport import Transport
+
+
+class RalioClient:
+    """Synchronous client for the Ralio API, authenticated via a credential
+    binding (OAuth 2.1 ``client_credentials`` + ``private_key_jwt`` + DPoP).
+
+    After a one-time :func:`ralio.register` on this host, no configuration is
+    needed::
+
+        client = ralio.RalioClient()  # reads the persisted credentials
+        reply = client.chat.send(message="What's my balance?")
+
+    To manage credentials yourself, pass ``client_id`` and
+    ``private_key_path`` together.
+    """
+
+    def __init__(
+        self,
+        *,
+        client_id: str | None = None,
+        private_key_path: str | Path | None = None,
+        base_url: str | None = None,
+        scopes: list[str] | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self._base_url = _store.resolve_base_url(base_url)
+        client_id, key_path = _resolve_credentials(client_id, private_key_path)
+        private_key = _load_private_key(key_path)
+        public_jwk = _crypto.public_jwk(private_key)
+        kid = _crypto.jwk_thumbprint(public_jwk)
+
+        # SSE streams need no read timeout; keep connect/write/pool bounded.
+        self._http = httpx.Client(
+            timeout=httpx.Timeout(timeout, read=None),
+        )
+        tokens = TokenManager(
+            client_id=client_id,
+            private_key=private_key,
+            kid=kid,
+            token_url=f"{self._base_url}/oauth/token",
+            http=self._http,
+            scopes=tuple(scopes) if scopes else None,
+        )
+        transport = Transport(
+            base_url=self._base_url,
+            http=self._http,
+            tokens=tokens,
+            private_key=private_key,
+            public_jwk=public_jwk,
+        )
+
+        self.agents = AgentsResource(transport)
+        self.chat = ChatResource(transport, self.agents)
+        self.transactions = TransactionsResource(transport)
+        self.payment_intents = PaymentIntentsResource(transport)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> RalioClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+def _resolve_credentials(
+    client_id: str | None,
+    private_key_path: str | Path | None,
+) -> tuple[str, Path]:
+    """Resolve the binding handle and key path, falling back to the store."""
+    if client_id and private_key_path:
+        return client_id, Path(private_key_path)
+    if client_id or private_key_path:
+        raise RalioConfigError(
+            "client_id and private_key_path must be passed together; omit both "
+            "to use the credentials persisted by ralio.register()."
+        )
+
+    stored = _store.load_credentials() or {}
+    stored_client_id = stored.get("client_id")
+    stored_key_path = stored.get("key_path")
+    stored_jkt = stored.get("key_jkt")
+    key_path: Path | None = None
+    if isinstance(stored_key_path, str) and stored_key_path:
+        key_path = Path(stored_key_path)
+    elif isinstance(stored_jkt, str) and stored_jkt:
+        key_path = _store.key_path_for(stored_jkt)
+    if not isinstance(stored_client_id, str) or not stored_client_id or key_path is None:
+        raise RalioConfigError(
+            f"No Ralio credentials found at {_store.credentials_path()}. Run "
+            "ralio.register() (or `ralio auth agent`) on this host first, or "
+            "pass client_id and private_key_path explicitly."
+        )
+    return stored_client_id, key_path
+
+
+def _load_private_key(key_path: Path) -> EllipticCurvePrivateKey:
+    try:
+        return _crypto.load_private_key(key_path)
+    except FileNotFoundError:
+        raise RalioConfigError(
+            f"Private key missing at {key_path} — the binding may have been "
+            "revoked and the key removed. Re-run ralio.register() with a "
+            "fresh ticket."
+        ) from None

ralio/errors.py

@@ -0,0 +1,106 @@
+"""Exception hierarchy for the Ralio SDK."""
+
+from __future__ import annotations
+
+import json
+
+import httpx
+
+
+class RalioError(Exception):
+    """Base class for every error raised by the SDK."""
+
+
+class RalioConfigError(RalioError):
+    """Local configuration problem — missing key file, bad arguments."""
+
+
+class RalioRegistrationError(RalioError):
+    """A credential-binding registration failed — the ticket was invalid,
+    expired, or already consumed, the public key was unusable, or the
+    server's response didn't match the local key."""
+
+
+class RalioAPIError(RalioError):
+    """An error response from the Ralio API.
+
+    Carries the HTTP ``status_code``, the server-supplied ``detail`` string,
+    and the ``WWW-Authenticate`` challenge when present (DPoP/OAuth failures
+    put the specific reason there).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        detail: str | None = None,
+        www_authenticate: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.detail = detail
+        self.www_authenticate = www_authenticate
+
+
+class RalioAuthError(RalioAPIError):
+    """401 — missing/invalid token, failed client assertion, or rejected proof."""
+
+
+class RalioPermissionError(RalioAPIError):
+    """403 — token lacks the required scope, or the resource isn't owned."""
+
+
+class RalioNotFoundError(RalioAPIError):
+    """404 — resource does not exist."""
+
+
+class RalioValidationError(RalioAPIError):
+    """422 — invalid field values or a business-rule violation."""
+
+
+class RalioRateLimitError(RalioAPIError):
+    """429 — rate limited. Back off and retry."""
+
+
+_STATUS_MAP: dict[int, type[RalioAPIError]] = {
+    401: RalioAuthError,
+    403: RalioPermissionError,
+    404: RalioNotFoundError,
+    422: RalioValidationError,
+    429: RalioRateLimitError,
+}
+
+
+def raise_for_response(response: httpx.Response) -> None:
+    """Raise the appropriate :class:`RalioAPIError` if *response* is an error."""
+    if response.is_success:
+        return
+    detail = _extract_detail(response)
+    cls = _STATUS_MAP.get(response.status_code, RalioAPIError)
+    message = detail or f"HTTP {response.status_code}"
+    raise cls(
+        message,
+        status_code=response.status_code,
+        detail=detail,
+        www_authenticate=response.headers.get("www-authenticate"),
+    )
+
+
+def _extract_detail(response: httpx.Response) -> str | None:
+    """Return the FastAPI ``detail`` field, or the raw body as a fallback."""
+    try:
+        payload = response.json()
+    except (ValueError, json.JSONDecodeError):
+        return response.text or None
+    if isinstance(payload, dict):
+        detail = payload.get("detail")
+        if isinstance(detail, str):
+            return detail
+        if detail is not None:
+            return json.dumps(detail)
+        # OAuth-style error bodies use error/error_description instead.
+        oauth = payload.get("error_description") or payload.get("error")
+        if isinstance(oauth, str):
+            return oauth
+    return response.text or None