jetv-clearing-sdk 1.0.0__tar.gz

jetv_clearing_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: jetv-clearing-sdk
+Version: 1.0.0
+Summary: Official Python SDK for the Clearing economic-principal (EPID) service
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/jetv/clearing-sdk-python
+Project-URL: Source, https://github.com/jetv/clearing-sdk-python
+Keywords: clearing,epid,identity,sdk,jetv
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: cryptography>=42
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+
+# jetv-clearing-sdk
+
+Official Python SDK for the **Clearing** economic-principal (EPID) service.
+
+Clearing assigns every economic principal — humans, services, agents, organizations,
+and providers — a stable **EPID** and a canonical kind, and exposes signed, auditable
+operations for resolution, sourced writes, and identity unification.
+
+## Install
+
+```bash
+pip install jetv-clearing-sdk
+```
+
+## Tiers
+
+The SDK is layered so each caller only takes the capability (and trust) it needs:
+
+| Tier | Constructor | Capability |
+| --- | --- | --- |
+| L1 — read | `ClearingClient.read_only(...)` | resolve EPIDs, read canonical kinds (no signing keys) |
+| L2 — source | `ClearingClient.source(...)` | F4-signed `ensure` / `link` / `affiliate` writes |
+| L3 — unify | `ClearingClient.unify(...)` | key-proof, verified-attribute, bind, and realm-link flows |
+
+## Quick start (L1)
+
+```python
+import asyncio
+from clearing_sdk import ClearingClient
+
+async def main():
+    client = ClearingClient.read_only(base_url="https://clearing.internal")
+    resolved = await client.resolve("user", "alice@example.com")
+    print(resolved.epid, resolved.canonical_kind, resolved.status)
+
+asyncio.run(main())
+```
+
+## Canonical JSON & signing
+
+For source-authenticated (F4) and unify (L2/L3) operations the SDK produces a
+**Go-exact canonical JSON** encoding so signatures verify byte-for-byte against the
+server reference implementation, including HTML escaping of `<`, `>`, `&` and
+`U+2028` / `U+2029`. Floating-point numbers are rejected in signed bodies to keep
+canonicalization deterministic.
+
+## Resilience
+
+The L1 read client ships an in-process TTL cache, single-flight request
+deduplication, and a circuit breaker with zero required third-party runtime deps
+beyond `httpx` and `cryptography`.
+
+## License
+
+Apache-2.0

jetv_clearing_sdk-1.0.0/README.md

@@ -0,0 +1,55 @@
+# jetv-clearing-sdk
+
+Official Python SDK for the **Clearing** economic-principal (EPID) service.
+
+Clearing assigns every economic principal — humans, services, agents, organizations,
+and providers — a stable **EPID** and a canonical kind, and exposes signed, auditable
+operations for resolution, sourced writes, and identity unification.
+
+## Install
+
+```bash
+pip install jetv-clearing-sdk
+```
+
+## Tiers
+
+The SDK is layered so each caller only takes the capability (and trust) it needs:
+
+| Tier | Constructor | Capability |
+| --- | --- | --- |
+| L1 — read | `ClearingClient.read_only(...)` | resolve EPIDs, read canonical kinds (no signing keys) |
+| L2 — source | `ClearingClient.source(...)` | F4-signed `ensure` / `link` / `affiliate` writes |
+| L3 — unify | `ClearingClient.unify(...)` | key-proof, verified-attribute, bind, and realm-link flows |
+
+## Quick start (L1)
+
+```python
+import asyncio
+from clearing_sdk import ClearingClient
+
+async def main():
+    client = ClearingClient.read_only(base_url="https://clearing.internal")
+    resolved = await client.resolve("user", "alice@example.com")
+    print(resolved.epid, resolved.canonical_kind, resolved.status)
+
+asyncio.run(main())
+```
+
+## Canonical JSON & signing
+
+For source-authenticated (F4) and unify (L2/L3) operations the SDK produces a
+**Go-exact canonical JSON** encoding so signatures verify byte-for-byte against the
+server reference implementation, including HTML escaping of `<`, `>`, `&` and
+`U+2028` / `U+2029`. Floating-point numbers are rejected in signed bodies to keep
+canonicalization deterministic.
+
+## Resilience
+
+The L1 read client ships an in-process TTL cache, single-flight request
+deduplication, and a circuit breaker with zero required third-party runtime deps
+beyond `httpx` and `cryptography`.
+
+## License
+
+Apache-2.0

jetv_clearing_sdk-1.0.0/clearing_sdk/__init__.py

@@ -0,0 +1,60 @@
+"""clearing-sdk-py — official Python SDK for the Clearing EPID service.
+
+Three capability tiers with a uniform shape across the Go / Python / TS SDKs:
+
+    L1 ResolveClient — read: resolve / get_by_epid / kinds (cache + breaker)
+    L2 SourceClient  — register: ensure / link / affiliate (F4 RS256 auto-sign)
+    L3 UnifyClient   — unify: prove_key / submit_verified_attr / bind / link_realm
+
+Tier == permission boundary: building L2/L3 requires a source RSA key, so a
+read-only consumer cannot obtain the write/unify handles.
+"""
+
+from __future__ import annotations
+
+from .canonical import FloatInSignedBodyError, canonical_bytes
+from .client import CONTRACT_VERSION, ClearingClient
+from .errors import (
+    APIError,
+    ClearingError,
+    Conflict,
+    InvalidRequest,
+    NotRegistered,
+    PermissionDenied,
+    RateLimited,
+    Unavailable,
+)
+from .signing import RSASigner, load_rsa_private_key
+from .types import (
+    RELATION_ACCOUNTABLE_FOR,
+    RELATION_MEMBER_OF,
+    AttrAssertion,
+    DedupResult,
+    Ensured,
+    Identity,
+    Resolved,
+)
+
+__all__ = [
+    "ClearingClient",
+    "CONTRACT_VERSION",
+    "RSASigner",
+    "load_rsa_private_key",
+    "canonical_bytes",
+    "FloatInSignedBodyError",
+    "Identity",
+    "Resolved",
+    "Ensured",
+    "AttrAssertion",
+    "DedupResult",
+    "RELATION_MEMBER_OF",
+    "RELATION_ACCOUNTABLE_FOR",
+    "ClearingError",
+    "NotRegistered",
+    "Unavailable",
+    "PermissionDenied",
+    "Conflict",
+    "InvalidRequest",
+    "RateLimited",
+    "APIError",
+]

jetv_clearing_sdk-1.0.0/clearing_sdk/_resilience.py

@@ -0,0 +1,83 @@
+"""Minimal resilience primitives (TTL cache + circuit breaker), mirroring the Go
+epidclient defaults. Kept dependency-free (no cachetools) for a small footprint."""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass
+from typing import Callable, Generic, Optional, TypeVar
+
+__all__ = ["TTLCache", "Breaker", "CacheEntry"]
+
+T = TypeVar("T")
+
+
+@dataclass
+class CacheEntry(Generic[T]):
+    value: T
+    registered: bool
+    expires_at: float
+
+
+class TTLCache(Generic[T]):
+    """Thread-safe TTL cache with positive/negative entries."""
+
+    def __init__(self, now: Callable[[], float] = time.monotonic):
+        self._now = now
+        self._lock = threading.Lock()
+        self._data: dict[str, CacheEntry[T]] = {}
+
+    def get(self, key: str) -> Optional[CacheEntry[T]]:
+        with self._lock:
+            e = self._data.get(key)
+            if e is None:
+                return None
+            if self._now() > e.expires_at:
+                del self._data[key]
+                return None
+            return e
+
+    def put(self, key: str, value: T, registered: bool, ttl: float) -> None:
+        with self._lock:
+            self._data[key] = CacheEntry(value, registered, self._now() + ttl)
+
+    def invalidate(self, key: str) -> None:
+        with self._lock:
+            self._data.pop(key, None)
+
+
+class Breaker:
+    """Consecutive-failure circuit breaker (mirrors epidclient.breaker)."""
+
+    def __init__(self, threshold: int, open_timeout: float, now: Callable[[], float] = time.monotonic):
+        self._threshold = threshold
+        self._open_timeout = open_timeout
+        self._now = now
+        self._lock = threading.Lock()
+        self._failures = 0
+        self._opened_at = 0.0
+        self._open = False
+
+    def allow(self) -> bool:
+        with self._lock:
+            if not self._open:
+                return True
+            # half-open after the open window elapses.
+            if self._now() - self._opened_at >= self._open_timeout:
+                self._open = False
+                self._failures = 0
+                return True
+            return False
+
+    def success(self) -> None:
+        with self._lock:
+            self._failures = 0
+            self._open = False
+
+    def failure(self) -> None:
+        with self._lock:
+            self._failures += 1
+            if self._failures >= self._threshold:
+                self._open = True
+                self._opened_at = self._now()

jetv_clearing_sdk-1.0.0/clearing_sdk/canonical.py

@@ -0,0 +1,149 @@
+"""Go-exact canonical JSON for cross-language F4 signing.
+
+The Clearing server canonicalizes with Go ``encoding/json`` (pkg/sourcesign):
+keys sorted, no insignificant whitespace, number literals preserved, and — the
+subtle part — Go's HTML-safe string escaping (``<`` ``>`` ``&`` -> ``\\u003c``
+``\\u003e`` ``\\u0026``) plus ``\\u2028``/``\\u2029``. Python's ``json.dumps``
+does NOT escape those, so a naive implementation would byte-diverge and produce
+signatures the server rejects. This module reproduces Go byte-for-byte; the
+``html_escape`` golden vector guards it.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+__all__ = ["canonical_bytes", "FloatInSignedBodyError", "reject_float"]
+
+
+class FloatInSignedBodyError(ValueError):
+    """Raised when a signed body contains a JSON float (precision drift guard)."""
+
+
+class _Num(str):
+    """A JSON number token, kept verbatim (mirrors Go json.Number).
+
+    Subclasses str so we can distinguish a JSON number from a JSON string after
+    parsing (both would otherwise collapse to str under parse_int/parse_float).
+    """
+
+    __slots__ = ()
+
+    @property
+    def is_float(self) -> bool:
+        return "." in self or "e" in self or "E" in self
+
+
+# Short escapes match Go's encodeState.string exactly (no \b/\f shorthand: Go
+# emits \u0008 / \u000c for those).
+_SHORT = {
+    '"': '\\"',
+    "\\": "\\\\",
+    "\n": "\\n",
+    "\r": "\\r",
+    "\t": "\\t",
+}
+
+
+def _escape_string(s: str) -> str:
+    out = ['"']
+    for ch in s:
+        o = ord(ch)
+        short = _SHORT.get(ch)
+        if short is not None:
+            out.append(short)
+        elif ch in "<>&" or o < 0x20:
+            out.append("\\u%04x" % o)
+        elif o == 0x2028 or o == 0x2029:
+            out.append("\\u%04x" % o)
+        else:
+            out.append(ch)
+    out.append('"')
+    return "".join(out)
+
+
+def _write(v: Any, out: list[str]) -> None:
+    if isinstance(v, dict):
+        out.append("{")
+        first = True
+        for k in sorted(v.keys()):  # code-point order == Go UTF-8 byte order
+            if not first:
+                out.append(",")
+            first = False
+            out.append(_escape_string(k))
+            out.append(":")
+            _write(v[k], out)
+        out.append("}")
+    elif isinstance(v, list):
+        out.append("[")
+        for i, e in enumerate(v):
+            if i:
+                out.append(",")
+            _write(e, out)
+        out.append("]")
+    elif isinstance(v, _Num):
+        out.append(str(v))
+    elif v is True:
+        out.append("true")
+    elif v is False:
+        out.append("false")
+    elif v is None:
+        out.append("null")
+    elif isinstance(v, str):
+        out.append(_escape_string(v))
+    elif isinstance(v, bool):  # unreachable (handled above) but defensive
+        out.append("true" if v else "false")
+    elif isinstance(v, int):
+        out.append(str(v))
+    else:
+        raise TypeError(f"canonical: unsupported type {type(v)!r}")
+
+
+def _parse(body: bytes | str) -> Any:
+    if isinstance(body, bytes):
+        body = body.decode("utf-8")
+    # parse_int/parse_float keep the verbatim numeric token (Go json.Number).
+    return json.loads(body, parse_int=_Num, parse_float=_Num)
+
+
+def canonical_bytes(body: bytes | str | dict | list) -> bytes:
+    """Return the deterministic canonical byte sequence for a JSON value.
+
+    Accepts raw JSON (bytes/str) or an already-decoded dict/list. Raw input is
+    preferred for signing so number literals are preserved exactly.
+    """
+    if isinstance(body, (bytes, str)):
+        v = _parse(body)
+    else:
+        v = body
+    out: list[str] = []
+    _write(v, out)
+    return "".join(out).encode("utf-8")
+
+
+def reject_float(body: bytes | str | dict | list) -> None:
+    """Raise FloatInSignedBodyError if the value contains any JSON float.
+
+    Signed bodies must not contain floats (cross-language precision drift): use
+    integer minor units or strings.
+    """
+    if isinstance(body, (bytes, str)):
+        v = _parse(body)
+    else:
+        v = body
+    _walk_reject(v)
+
+
+def _walk_reject(v: Any) -> None:
+    if isinstance(v, dict):
+        for e in v.values():
+            _walk_reject(e)
+    elif isinstance(v, list):
+        for e in v:
+            _walk_reject(e)
+    elif isinstance(v, _Num):
+        if v.is_float:
+            raise FloatInSignedBodyError(str(v))
+    elif isinstance(v, float):
+        raise FloatInSignedBodyError(repr(v))

jetv_clearing_sdk-1.0.0/clearing_sdk/client.py

@@ -0,0 +1,79 @@
+"""ClearingClient facade. Capability == construction credential: read-only
+callers cannot obtain L2/L3 (no source key), mirroring the Go SDK tiers."""
+
+from __future__ import annotations
+
+import time
+from typing import Callable, Optional
+
+import httpx
+
+from .resolve import ResolveClient
+from .signing import RSASigner
+from .source import SourceClient
+from .transport import Transport
+from .unify import UnifyClient
+
+__all__ = ["ClearingClient", "CONTRACT_VERSION"]
+
+# OpenAPI contract version this SDK targets (compared against live info.version).
+CONTRACT_VERSION = "1.0.0"
+
+
+class ClearingClient:
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        signer: Optional[RSASigner] = None,
+        with_unify: bool = False,
+        http_client: Optional[httpx.AsyncClient] = None,
+        write_timeout: float = 5.0,
+        ttl: float = 300.0,
+        negative_ttl: float = 30.0,
+        failure_threshold: int = 5,
+        open_timeout: float = 10.0,
+        now: Callable[[], float] = time.time,
+        mono: Callable[[], float] = time.monotonic,
+    ):
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.AsyncClient(timeout=write_timeout)
+        tr = Transport(base_url, self._client, now=now)
+        self.l1 = ResolveClient(
+            tr,
+            ttl=ttl,
+            negative_ttl=negative_ttl,
+            failure_threshold=failure_threshold,
+            open_timeout=open_timeout,
+            now=mono,
+        )
+        self.l2: Optional[SourceClient] = SourceClient(tr, signer) if signer is not None else None
+        self.l3: Optional[UnifyClient] = (
+            UnifyClient(tr, signer) if (signer is not None and with_unify) else None
+        )
+
+    @classmethod
+    def read_only(cls, base_url: str, **kw) -> "ClearingClient":
+        return cls(base_url, **kw)
+
+    @classmethod
+    def source(cls, base_url: str, signer: RSASigner, **kw) -> "ClearingClient":
+        return cls(base_url, signer=signer, **kw)
+
+    @classmethod
+    def unify(cls, base_url: str, signer: RSASigner, **kw) -> "ClearingClient":
+        return cls(base_url, signer=signer, with_unify=True, **kw)
+
+    @property
+    def version(self) -> str:
+        return CONTRACT_VERSION
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> "ClearingClient":
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self.aclose()

jetv_clearing_sdk-1.0.0/clearing_sdk/errors.py

@@ -0,0 +1,105 @@
+"""SDK error taxonomy (mirrors the Go SDK sentinels).
+
+Consumers branch on these to choose fail-open/closed; the SDK never silently
+fabricates a fallback.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "ClearingError",
+    "NotRegistered",
+    "Unavailable",
+    "PermissionDenied",
+    "Conflict",
+    "InvalidRequest",
+    "RateLimited",
+    "APIError",
+    "classify_status",
+]
+
+
+class ClearingError(Exception):
+    """Base class for all SDK errors."""
+
+
+class NotRegistered(ClearingError):
+    """Principal/identity authoritatively absent (404, safe to negative-cache)."""
+
+
+class Unavailable(ClearingError):
+    """Clearing unreachable / circuit open / 5xx — not silently masked."""
+
+
+class PermissionDenied(ClearingError):
+    """Source unauthorized or admin/governance gate rejected (401/403)."""
+
+
+class Conflict(ClearingError):
+    """Unification/registration conflict (409)."""
+
+
+class InvalidRequest(ClearingError):
+    """Semantically invalid request (400/422)."""
+
+
+class RateLimited(ClearingError):
+    """Too many challenges/requests (429)."""
+
+
+class APIError(ClearingError):
+    """Carries the server's stable code + HTTP status. Subclass of the classified
+    error so ``except PermissionDenied`` and precise logging both work."""
+
+    def __init__(self, status: int, code: str, detail: str = ""):
+        self.status = status
+        self.code = code
+        self.detail = detail
+        msg = f"clearing: {code} (http {status})"
+        if detail:
+            msg += f": {detail}"
+        super().__init__(msg)
+
+
+# Concrete API error classes carrying the envelope, one per sentinel.
+class _APINotRegistered(APIError, NotRegistered):
+    pass
+
+
+class _APIPermission(APIError, PermissionDenied):
+    pass
+
+
+class _APIConflict(APIError, Conflict):
+    pass
+
+
+class _APIInvalid(APIError, InvalidRequest):
+    pass
+
+
+class _APIRateLimited(APIError, RateLimited):
+    pass
+
+
+class _APIUnavailable(APIError, Unavailable):
+    pass
+
+
+def classify_status(status: int, code: str, detail: str = "") -> APIError | None:
+    """Map an HTTP status + envelope code to a classified APIError (or None on
+    200). Single source of status->sentinel truth, aligned with the server's
+    writeRegistryError / writeUnifyError mappings."""
+    if status == 200:
+        return None
+    if status == 404:
+        return _APINotRegistered(status, code, detail)
+    if status in (401, 403):
+        return _APIPermission(status, code, detail)
+    if status in (409, 428):
+        return _APIConflict(status, code, detail)
+    if status in (400, 422):
+        return _APIInvalid(status, code, detail)
+    if status == 429:
+        return _APIRateLimited(status, code, detail)
+    return _APIUnavailable(status, code, detail)

jetv_clearing_sdk-1.0.0/clearing_sdk/kinds.py

@@ -0,0 +1,63 @@
+"""external->canonical kind mapping cache, with a compiled-in degraded fallback.
+
+The server is authoritative; the fallback is a last resort with a TTL and a
+``degraded`` flag (never silently authoritative)."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Callable
+
+from .errors import ClearingError
+from .transport import Transport
+
+__all__ = ["KindsCache", "COMPILED_MAPPING"]
+
+# Compiled-in fallback (mirrors clearing/pkg/canonicalkind.externalToCanonical
+# exactly — 5 entries, no invented keys). Used only when the server is
+# unreachable; flagged degraded.
+COMPILED_MAPPING: dict[str, str] = {
+    "user": "human",
+    "client": "service",
+    "agent": "agent",
+    "realm": "org",
+    "provider": "provider",
+}
+
+
+class KindsCache:
+    def __init__(self, transport: Transport, *, ttl: float = 300.0, now: Callable[[], float] = time.monotonic):
+        self._tr = transport
+        self._ttl = ttl
+        self._now = now
+        self._lock = asyncio.Lock()
+        self._mapping: dict[str, str] | None = None
+        self._expires_at = 0.0
+        self._degraded = False
+
+    async def get(self) -> dict[str, str]:
+        if self._mapping is not None and self._now() < self._expires_at:
+            return dict(self._mapping)
+        async with self._lock:
+            if self._mapping is not None and self._now() < self._expires_at:
+                return dict(self._mapping)
+            try:
+                data = await self._tr.get_json("/v1/kinds")
+                mapping = data.get("mapping") or {}
+                if mapping:
+                    self._store(dict(mapping), degraded=False)
+                    return dict(mapping)
+            except ClearingError:
+                pass
+            self._store(dict(COMPILED_MAPPING), degraded=True)
+            return dict(COMPILED_MAPPING)
+
+    def _store(self, mapping: dict[str, str], *, degraded: bool) -> None:
+        self._mapping = mapping
+        self._degraded = degraded
+        self._expires_at = self._now() + self._ttl
+
+    @property
+    def degraded(self) -> bool:
+        return self._degraded