jetv-clearing-sdk 1.0.0__py3-none-any.whl

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",
+]

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()

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))

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()

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)

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

clearing_sdk/resolve.py

@@ -0,0 +1,105 @@
+"""L1 read tier: resolve / get_by_epid / kinds, with TTL cache + single-flight +
+circuit breaker mirroring the Go epidclient resilience contract."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Callable
+
+from ._resilience import Breaker, TTLCache
+from .errors import APIError, NotRegistered, Unavailable
+from .kinds import KindsCache
+from .transport import Transport
+from .types import Identity, Resolved
+
+__all__ = ["ResolveClient"]
+
+
+class ResolveClient:
+    def __init__(
+        self,
+        transport: Transport,
+        *,
+        ttl: float = 300.0,
+        negative_ttl: float = 30.0,
+        failure_threshold: int = 5,
+        open_timeout: float = 10.0,
+        now: Callable[[], float] = time.monotonic,
+    ):
+        self._tr = transport
+        self._ttl = ttl
+        self._neg_ttl = negative_ttl
+        self._cache: TTLCache[Resolved] = TTLCache(now=now)
+        self._breaker = Breaker(failure_threshold, open_timeout, now=now)
+        self._kinds = KindsCache(transport, ttl=ttl, now=now)
+        self._locks: dict[str, asyncio.Lock] = {}
+        self._locks_guard = asyncio.Lock()
+
+    async def resolve(self, ident: Identity) -> Resolved:
+        key = ident.cache_key()
+        e = self._cache.get(key)
+        if e is not None:
+            if e.registered:
+                return e.value
+            raise NotRegistered(ident.cache_key())
+        if not self._breaker.allow():
+            raise Unavailable()  # circuit open — fail fast, no silent fallback
+
+        lock = await self._lock_for(key)
+        async with lock:  # single-flight per key
+            e = self._cache.get(key)
+            if e is not None:
+                if e.registered:
+                    return e.value
+                raise NotRegistered(ident.cache_key())
+            return await self._fetch(ident, key)
+
+    async def _fetch(self, ident: Identity, key: str) -> Resolved:
+        body = {
+            "auth_instance_id": ident.auth_instance_id,
+            "kind": ident.kind,
+            "principal_key": ident.key,
+        }
+        try:
+            data = await self._tr.post_json("/v1/principals/resolve", body)
+        except NotRegistered:
+            self._cache.put(key, Resolved("", "", ""), False, self._neg_ttl)
+            self._breaker.success()  # authoritative 404 is not a backend fault
+            raise
+        except APIError as e:
+            if e.status == 404:
+                self._cache.put(key, Resolved("", "", ""), False, self._neg_ttl)
+                self._breaker.success()
+                raise NotRegistered(ident.cache_key()) from e
+            self._breaker.failure()
+            raise Unavailable() from e
+        except Unavailable:
+            self._breaker.failure()
+            raise
+        res = Resolved(data.get("epid", ""), data.get("canonical_kind", ""), data.get("status", ""))
+        self._cache.put(key, res, True, self._ttl)
+        self._breaker.success()
+        return res
+
+    async def get_by_epid(self, epid: str) -> Resolved:
+        data = await self._tr.get_json(f"/v1/principals/{epid}")
+        return Resolved(data.get("epid", ""), data.get("canonical_kind", ""), data.get("status", ""))
+
+    async def kinds(self) -> dict[str, str]:
+        return await self._kinds.get()
+
+    @property
+    def kinds_degraded(self) -> bool:
+        return self._kinds.degraded
+
+    def invalidate(self, ident: Identity) -> None:
+        self._cache.invalidate(ident.cache_key())
+
+    async def _lock_for(self, key: str) -> asyncio.Lock:
+        async with self._locks_guard:
+            lock = self._locks.get(key)
+            if lock is None:
+                lock = asyncio.Lock()
+                self._locks[key] = lock
+            return lock

clearing_sdk/signing.py

@@ -0,0 +1,72 @@
+"""F4 RS256 + Ed25519 signing primitives, byte-aligned with the Go server.
+
+RS256 = RSA-PKCS1v15 + SHA-256 over the canonical body (canonical.py), base64
+standard-encoded. Ed25519 over raw challenge bytes. key_id is the sha256
+fingerprint of the raw public key (mirrors internal/unify.KeyFingerprint).
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import ed25519, padding, rsa
+
+from .canonical import canonical_bytes, reject_float
+
+__all__ = [
+    "RSASigner",
+    "load_rsa_private_key",
+    "ed25519_public_b64",
+    "ed25519_sign_b64",
+    "key_fingerprint",
+]
+
+
+def load_rsa_private_key(pem: bytes | str) -> rsa.RSAPrivateKey:
+    if isinstance(pem, str):
+        pem = pem.encode("utf-8")
+    key = serialization.load_pem_private_key(pem, password=None)
+    if not isinstance(key, rsa.RSAPrivateKey):
+        raise TypeError("signing: not an RSA private key")
+    return key
+
+
+class RSASigner:
+    """Binds a source identity to its RSA key for F4 write-auth."""
+
+    def __init__(self, source_id: str, priv: rsa.RSAPrivateKey):
+        self.source_id = source_id
+        self._priv = priv
+
+    def sign_b64(self, body: bytes | dict | list, *, forbid_float: bool = True) -> str:
+        """RS256 over canonical(body) -> base64(std). Rejects floats by default
+        (signed bodies must use integer minor units / strings)."""
+        if forbid_float:
+            reject_float(body)
+        canon = canonical_bytes(body)
+        sig = self._priv.sign(canon, padding.PKCS1v15(), hashes.SHA256())
+        return base64.standard_b64encode(sig).decode("ascii")
+
+    def rotate(self, priv: rsa.RSAPrivateKey) -> None:
+        self._priv = priv
+
+
+def ed25519_public_b64(priv: ed25519.Ed25519PrivateKey) -> str:
+    raw = priv.public_key().public_bytes(
+        serialization.Encoding.Raw, serialization.PublicFormat.Raw
+    )
+    return base64.standard_b64encode(raw).decode("ascii")
+
+
+def ed25519_sign_b64(priv: ed25519.Ed25519PrivateKey, challenge: str) -> str:
+    sig = priv.sign(challenge.encode("utf-8"))
+    return base64.standard_b64encode(sig).decode("ascii")
+
+
+def key_fingerprint(priv: ed25519.Ed25519PrivateKey) -> str:
+    raw = priv.public_key().public_bytes(
+        serialization.Encoding.Raw, serialization.PublicFormat.Raw
+    )
+    return "sha256:" + hashlib.sha256(raw).hexdigest()

clearing_sdk/source.py

@@ -0,0 +1,46 @@
+"""L2 registration tier: ensure / link / affiliate, every write F4-signed."""
+
+from __future__ import annotations
+
+from .signing import RSASigner
+from .transport import Transport
+from .types import Ensured, Identity
+
+__all__ = ["SourceClient"]
+
+
+class SourceClient:
+    def __init__(self, transport: Transport, signer: RSASigner):
+        self._tr = transport
+        self._signer = signer
+
+    async def ensure(self, ident: Identity) -> Ensured:
+        """Idempotently adopt an external identity. ``auth_instance_id`` must
+        equal the signing source (server enforces, else PermissionDenied)."""
+        body = {
+            "auth_instance_id": ident.auth_instance_id,
+            "kind": ident.kind,
+            "principal_key": ident.key,
+        }
+        data = await self._tr.post_json("/v1/principals/ensure", body, self._signer)
+        return Ensured(
+            data.get("epid", ""),
+            data.get("canonical_kind", ""),
+            bool(data.get("created", False)),
+        )
+
+    async def link(self, ident: Identity, target_epid: str) -> None:
+        body = {
+            "auth_instance_id": ident.auth_instance_id,
+            "kind": ident.kind,
+            "principal_key": ident.key,
+            "target_epid": target_epid,
+        }
+        await self._tr.post_json("/v1/principals/link", body, self._signer)
+
+    async def affiliate(self, subject_epid: str, relation: str, target_epid: str) -> None:
+        body = {"subject_epid": subject_epid, "relation": relation, "target_epid": target_epid}
+        await self._tr.post_json("/v1/principals/affiliate", body, self._signer)
+
+    def rotate_key(self, signer: RSASigner) -> None:
+        self._signer = signer

clearing_sdk/transport.py

@@ -0,0 +1,79 @@
+"""Async HTTP transport: signed/unsigned JSON calls + unified error decoding."""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any, Callable, Optional
+
+import httpx
+
+from .errors import Unavailable, classify_status
+from .signing import RSASigner
+
+# F4 source-signed write headers (authoritative server names; the CHP-005 sketch
+# used X-Clearing-Source-Id and omitted the timestamp — both corrected here).
+HEADER_SOURCE = "X-Clearing-Source"
+HEADER_SIGNATURE = "X-Clearing-Signature"
+HEADER_TIMESTAMP = "X-Clearing-Timestamp"
+
+
+class Transport:
+    def __init__(
+        self,
+        base_url: str,
+        client: httpx.AsyncClient,
+        now: Callable[[], float] = time.time,
+    ):
+        self._base = base_url.rstrip("/")
+        self._client = client
+        self._now = now
+
+    async def post_json(
+        self,
+        path: str,
+        body: dict,
+        signer: Optional[RSASigner] = None,
+        *,
+        forbid_float: bool = True,
+    ) -> dict:
+        # Serialize once; sign the exact bytes we send (server canonicalizes).
+        raw = json.dumps(body, ensure_ascii=False).encode("utf-8")
+        headers = {"Content-Type": "application/json"}
+        if signer is not None:
+            headers[HEADER_SIGNATURE] = signer.sign_b64(body, forbid_float=forbid_float)
+            headers[HEADER_SOURCE] = signer.source_id
+            headers[HEADER_TIMESTAMP] = str(int(self._now()))
+        try:
+            resp = await self._client.post(self._base + path, content=raw, headers=headers)
+        except httpx.HTTPError as e:
+            raise Unavailable(f"clearing: transport error: {e}") from e
+        return self._decode(resp)
+
+    async def get_json(self, path: str) -> dict:
+        try:
+            resp = await self._client.get(self._base + path)
+        except httpx.HTTPError as e:
+            raise Unavailable(f"clearing: transport error: {e}") from e
+        return self._decode(resp)
+
+    def _decode(self, resp: httpx.Response) -> dict:
+        if resp.status_code != 200:
+            code, detail = _envelope(resp)
+            raise classify_status(resp.status_code, code, detail)
+        if not resp.content:
+            return {}
+        try:
+            return resp.json()
+        except (json.JSONDecodeError, ValueError) as e:
+            raise Unavailable(f"clearing: bad response body: {e}") from e
+
+
+def _envelope(resp: httpx.Response) -> tuple[str, str]:
+    try:
+        data: Any = resp.json()
+        if isinstance(data, dict):
+            return str(data.get("error", "")), str(data.get("detail", ""))
+    except (json.JSONDecodeError, ValueError):
+        pass
+    return "", ""

clearing_sdk/types.py

@@ -0,0 +1,75 @@
+"""Public data types for the Clearing Python SDK (mirror the Go SDK shape)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+__all__ = [
+    "Identity",
+    "Resolved",
+    "Ensured",
+    "AttrAssertion",
+    "DedupResult",
+    "RELATION_MEMBER_OF",
+    "RELATION_ACCOUNTABLE_FOR",
+]
+
+RELATION_MEMBER_OF = "member_of"
+RELATION_ACCOUNTABLE_FOR = "accountable_for"
+
+
+@dataclass(frozen=True)
+class Identity:
+    """External identity natural key (realm is NOT part of the key, F1)."""
+
+    auth_instance_id: str
+    kind: str
+    key: str
+
+    def cache_key(self) -> str:
+        return f"{self.auth_instance_id}\x1f{self.kind}\x1f{self.key}"
+
+
+@dataclass(frozen=True)
+class Resolved:
+    epid: str
+    canonical_kind: str
+    status: str  # ACTIVE | MERGED | SUSPENDED
+
+
+@dataclass(frozen=True)
+class Ensured:
+    epid: str
+    canonical_kind: str
+    created: bool
+
+
+@dataclass
+class AttrAssertion:
+    """Verifier deduplication assertion. ``verifier_sig`` is filled by the SDK."""
+
+    epid: str
+    attr_type: str
+    salted_hash: str
+    assurance_tier: int = 0
+    method: str = ""
+
+    def signed_body(self, verifier_id: str) -> dict:
+        """The exact field set the server re-marshals for verification.
+
+        verifier_sig is excluded (server field is json:"-")."""
+        return {
+            "epid": self.epid,
+            "attr_type": self.attr_type,
+            "salted_hash": self.salted_hash,
+            "assurance_tier": self.assurance_tier,
+            "method": self.method,
+            "verifier_id": verifier_id,
+        }
+
+
+@dataclass(frozen=True)
+class DedupResult:
+    active_epid: str
+    merged: bool
+    needs_review: bool = False

clearing_sdk/unify.py

@@ -0,0 +1,122 @@
+"""L3 unification tier: key-proof / verified-attr / binding / realm-link.
+
+Hides the challenge fetch->sign->submit dance and the Ed25519/RSA + base64(std)
+footguns. Holds the source RSA key (verified-attr verifier_sig + realm-link F4)."""
+
+from __future__ import annotations
+
+import base64
+
+from cryptography.hazmat.primitives.asymmetric import ed25519
+
+from .signing import RSASigner, ed25519_public_b64, ed25519_sign_b64, key_fingerprint
+from .transport import Transport
+from .types import AttrAssertion, DedupResult, Identity
+
+__all__ = ["UnifyClient"]
+
+PURPOSE_KEY_PROOF = "key-proof"
+
+
+class UnifyClient:
+    def __init__(self, transport: Transport, signer: RSASigner):
+        self._tr = transport
+        self._signer = signer
+
+    async def prove_key(self, epid: str, ed_priv: ed25519.Ed25519PrivateKey) -> DedupResult:
+        """Deduplicate by key control: fetch challenge, sign with Ed25519, submit
+        public key + fingerprint + signature. Same key across sources => same
+        principal."""
+        challenge = await self._challenge(epid, PURPOSE_KEY_PROOF)
+        body = {
+            "epid": epid,
+            "key_id": key_fingerprint(ed_priv),
+            "public_key": ed25519_public_b64(ed_priv),
+            "challenge": challenge,
+            "signature": ed25519_sign_b64(ed_priv, challenge),
+        }
+        return await self._post_dedup("/v1/unify/key-proof", body)
+
+    async def submit_verified_attr(self, a: AttrAssertion) -> DedupResult:
+        """Sign the canonical assertion body WITHOUT verifier_sig (server field is
+        json:"-") with the source RSA key, attach it base64(std)."""
+        signed = a.signed_body(self._signer.source_id)
+        sig = self._signer.sign_b64(signed)
+        body = dict(signed)
+        body["verifier_sig"] = sig
+        return await self._post_dedup("/v1/unify/verified-attr", body)
+
+    async def bind(
+        self,
+        subject_epid: str,
+        target_epid: str,
+        subject_key: ed25519.Ed25519PrivateKey,
+        target_key: ed25519.Ed25519PrivateKey,
+    ) -> DedupResult:
+        """Dual-binding merge: both sides sign the same challenge."""
+        challenge = await self._start_binding(subject_epid, target_epid, "dual_key")
+        body = {
+            "challenge": challenge,
+            "subject_public_key": ed25519_public_b64(subject_key),
+            "subject_signature": ed25519_sign_b64(subject_key, challenge),
+            "target_public_key": ed25519_public_b64(target_key),
+            "target_signature": ed25519_sign_b64(target_key, challenge),
+        }
+        return await self._post_dedup("/v1/unify/binding/prove", body)
+
+    async def link_realm(
+        self,
+        org_epid: str,
+        realm: Identity,
+        admin_key: ed25519.Ed25519PrivateKey,
+    ) -> None:
+        """Project an org realm identity into the org EPID. Whole request is
+        F4-signed by the realm's source; admin control proven by signing the
+        canonical org-admin message with the org's Ed25519 admin key."""
+        msg = _org_admin_message(org_epid, realm)
+        body = {
+            "org_epid": org_epid,
+            "realm_identity": {
+                "auth_instance_id": realm.auth_instance_id,
+                "kind": realm.kind,
+                "principal_key": realm.key,
+            },
+            "admin_proof": {
+                "public_key": ed25519_public_b64(admin_key),
+                "signature": base64.standard_b64encode(
+                    admin_key.sign(msg.encode("utf-8"))
+                ).decode("ascii"),
+            },
+        }
+        await self._tr.post_json("/v1/unify/realm-link", body, self._signer)
+
+    async def _challenge(self, epid: str, purpose: str) -> str:
+        data = await self._tr.post_json("/v1/unify/challenge", {"epid": epid, "purpose": purpose})
+        return data.get("challenge", "")
+
+    async def _start_binding(self, subject_epid: str, target_epid: str, method: str) -> str:
+        data = await self._tr.post_json(
+            "/v1/unify/binding",
+            {"subject_epid": subject_epid, "target_epid": target_epid, "method": method},
+        )
+        return data.get("challenge", "")
+
+    async def _post_dedup(self, path: str, body: dict) -> DedupResult:
+        data = await self._tr.post_json(path, body)
+        return DedupResult(
+            data.get("active_epid", ""),
+            bool(data.get("merged", False)),
+            bool(data.get("needs_review", False)),
+        )
+
+
+def key_fingerprint_pub(raw_pub: bytes) -> str:
+    """Fingerprint a raw Ed25519 public key (mirrors internal/unify.KeyFingerprint)."""
+    import hashlib
+
+    return "sha256:" + hashlib.sha256(raw_pub).hexdigest()
+
+
+def _org_admin_message(org_epid: str, realm: Identity) -> str:
+    """Mirror internal/unify.orgAdminMessage (wire contract)."""
+    return f"realm-link|{org_epid}|{realm.auth_instance_id}|{realm.kind}|{realm.key}"

jetv_clearing_sdk-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,17 @@
+clearing_sdk/__init__.py,sha256=aku_d8_qRJucHsWhHYqVPl5sZxfqcU4p6RrZxsUHOHA,1527
+clearing_sdk/_resilience.py,sha256=XHAqzqPJ0haVT_OH1zeqAnw88qM8ZzmseWbjPSYTyj0,2471
+clearing_sdk/canonical.py,sha256=eVml6Ft22zWr29FmlQJS7ac9PlJXeN8xG8KMWfYNGdk,4447
+clearing_sdk/client.py,sha256=XOtnXHZbgiCdCctkp1n-kk_7Sp3RHL0T0gaMtEsDiJ0,2490
+clearing_sdk/errors.py,sha256=jov5dTOsusvtqF69w4khj1kIZtcaUfuUOwsLNEFugjs,2731
+clearing_sdk/kinds.py,sha256=cKB-JZdbyySPBufc8c7xBgpTXHQktwhmtqTfEEoSZcM,2114
+clearing_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clearing_sdk/resolve.py,sha256=MuB3dNml9pwDuJy9vr2MAIc-1vg0980x9udUxjR6UnY,3742
+clearing_sdk/signing.py,sha256=E0AbXzmstz1qzusezfCkQLQMKI2z-730dxlYjxMpepY,2436
+clearing_sdk/source.py,sha256=2pqSJX2T8JtjCRk-kh9ze1YI6aZqrbDwEXRCT3gup9I,1695
+clearing_sdk/transport.py,sha256=FaBAWzSFghmswfZTZI5IZUhXV-c4G6fAE6yEsKuH920,2667
+clearing_sdk/types.py,sha256=nJrx1CXRWeWIZ9b54AUV0eMIHoPL2kh5KH0ukCUB3Bo,1685
+clearing_sdk/unify.py,sha256=I9YISUCSEgGjaLH-kr9hXMJLeVPTKGihxIH2rLoSyT8,4884
+jetv_clearing_sdk-1.0.0.dist-info/METADATA,sha256=HIFU3k_aoKbZl-iL2ucFqERGQ1ViIG20BZIoJ1JrM7U,2572
+jetv_clearing_sdk-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+jetv_clearing_sdk-1.0.0.dist-info/top_level.txt,sha256=uhUBP-Q1Z25q9jig_ypsHHDNUMwNx3XfZBPAr2kytMw,13
+jetv_clearing_sdk-1.0.0.dist-info/RECORD,,

jetv_clearing_sdk-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

jetv_clearing_sdk-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+clearing_sdk