ucii-sdk 1.0.0__py3-none-any.whl

ucii/__init__.py

@@ -0,0 +1,55 @@
+"""Public UCII Python SDK.
+
+Only publication-approved interoperability contracts are exported here.
+Private UCII trust, authority, enforcement, fleet, adoption, and provenance
+implementation details are intentionally outside this package surface.
+"""
+
+from .client import AsyncUCIIClient, UCIIClient
+from .errors import (
+    UCIIAPIError,
+    UCIIAuthenticationError,
+    UCIIAuthorizationError,
+    UCIIConfigurationError,
+    UCIIConflictError,
+    UCIIError,
+    UCIIPaymentRequiredError,
+    UCIIResourceNotFoundError,
+    UCIIServiceError,
+    UCIITransportError,
+    UCIIValidationError,
+)
+from .participant import ParticipantContext
+from .service_entitlement import (
+    ENTITLEMENT_PROOF_VERSION,
+    EntitlementProof,
+    EntitlementProofChallenge,
+    create_entitlement_proof,
+    entitlement_proof_header_value,
+    generate_entitlement_nonce,
+)
+from .signing import SigningProvider
+
+__all__ = [
+    "AsyncUCIIClient",
+    "ENTITLEMENT_PROOF_VERSION",
+    "EntitlementProof",
+    "EntitlementProofChallenge",
+    "ParticipantContext",
+    "SigningProvider",
+    "UCIIAPIError",
+    "UCIIClient",
+    "UCIIAuthenticationError",
+    "UCIIAuthorizationError",
+    "UCIIConfigurationError",
+    "UCIIConflictError",
+    "UCIIError",
+    "UCIIPaymentRequiredError",
+    "UCIIResourceNotFoundError",
+    "UCIIServiceError",
+    "UCIITransportError",
+    "UCIIValidationError",
+    "create_entitlement_proof",
+    "entitlement_proof_header_value",
+    "generate_entitlement_nonce",
+]

ucii/_transport.py

@@ -0,0 +1,208 @@
+"""Internal UCII SDK HTTP transport implementation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .errors import (
+    UCIIAPIError,
+    UCIIAuthenticationError,
+    UCIIAuthorizationError,
+    UCIIPaymentRequiredError,
+    UCIIConflictError,
+    UCIIResourceNotFoundError,
+    UCIIServiceError,
+    UCIITransportError,
+    UCIIValidationError,
+)
+
+
+def _error_from_response(response: httpx.Response) -> UCIIAPIError:
+    """Convert an HTTP error response into the public SDK error model."""
+
+    status_code = response.status_code
+    request_id = response.headers.get("x-request-id")
+    details: dict[str, Any] | None = None
+    message = f"UCII API request failed with status {status_code}"
+    error_code: str | None = None
+
+    try:
+        payload = response.json()
+    except ValueError:
+        payload = None
+
+    if isinstance(payload, dict):
+        detail = payload.get("detail")
+
+        if isinstance(detail, str):
+            message = detail
+        elif isinstance(detail, dict):
+            details = dict(detail)
+            message = str(
+                detail.get("message")
+                or detail.get("detail")
+                or message
+            )
+            error_code = detail.get("code") or detail.get("error_code")
+        elif detail is not None:
+            details = {"detail": detail}
+
+        error_code = error_code or payload.get("code") or payload.get("error_code")
+
+        if details is None:
+            extra = payload.get("details")
+            if isinstance(extra, dict):
+                details = dict(extra)
+
+        request_id = request_id or payload.get("request_id")
+
+    error_kwargs = {
+        "message": message,
+        "error_code": error_code,
+        "request_id": request_id,
+        "status_code": status_code,
+        "details": details,
+    }
+
+    if status_code == 402:
+        return UCIIPaymentRequiredError(**error_kwargs)
+    if status_code == 401:
+        return UCIIAuthenticationError(**error_kwargs)
+    if status_code == 403:
+        return UCIIAuthorizationError(**error_kwargs)
+    if status_code == 404:
+        return UCIIResourceNotFoundError(**error_kwargs)
+    if status_code == 409:
+        return UCIIConflictError(**error_kwargs)
+    if status_code == 422:
+        return UCIIValidationError(**error_kwargs)
+    if status_code >= 500:
+        return UCIIServiceError(**error_kwargs)
+
+    return UCIIAPIError(**error_kwargs)
+
+
+class HTTPTransport:
+    """Internal synchronous HTTP transport."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            timeout=self.timeout,
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any | None = None,
+        params: Any | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        request_headers = self._headers()
+        if headers:
+            request_headers.update(headers)
+
+        try:
+            response = self._client.request(
+                method,
+                path,
+                json=json,
+                params=params,
+                headers=request_headers,
+            )
+        except httpx.HTTPError as exc:
+            raise UCIITransportError(str(exc)) from exc
+
+        if response.is_error:
+            raise _error_from_response(response)
+
+        return response
+
+    def close(self) -> None:
+        self._client.close()
+
+    def _headers(self) -> dict[str, str]:
+        headers = {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+
+        return headers
+
+
+class AsyncHTTPTransport:
+    """Internal asynchronous HTTP transport."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=self.timeout,
+        )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any | None = None,
+        params: Any | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        request_headers = self._headers()
+        if headers:
+            request_headers.update(headers)
+
+        try:
+            response = await self._client.request(
+                method,
+                path,
+                json=json,
+                params=params,
+                headers=request_headers,
+            )
+        except httpx.HTTPError as exc:
+            raise UCIITransportError(str(exc)) from exc
+
+        if response.is_error:
+            raise _error_from_response(response)
+
+        return response
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    def _headers(self) -> dict[str, str]:
+        headers = {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+
+        return headers

ucii/authorization.py

@@ -0,0 +1,94 @@
+"""Public UCII authorization-check boundary."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def _payload(
+    *,
+    token: str,
+    identity_id: str,
+    credential_fingerprint: str,
+    operation: str,
+    message: str,
+    signature: str,
+) -> dict[str, Any]:
+    """Construct an authorization-check request payload."""
+
+    return {
+        "token": token,
+        "identity_id": identity_id,
+        "credential_fingerprint": credential_fingerprint,
+        "operation": operation,
+        "message": message,
+        "signature": signature,
+    }
+
+
+class AuthorizationNamespace:
+    """Thin synchronous non-executing authorization boundary."""
+
+    def __init__(self, transport: Any) -> None:
+        self._transport = transport
+
+    def check(
+        self,
+        *,
+        token: str,
+        identity_id: str,
+        credential_fingerprint: str,
+        operation: str,
+        message: str,
+        signature: str,
+    ) -> dict[str, Any]:
+        """Evaluate authorization without executing the operation."""
+
+        response = self._transport.request(
+            "POST",
+            "/v1/authorization/check",
+            json=_payload(
+                token=token,
+                identity_id=identity_id,
+                credential_fingerprint=credential_fingerprint,
+                operation=operation,
+                message=message,
+                signature=signature,
+            ),
+        )
+
+        return response.json()
+
+
+class AsyncAuthorizationNamespace:
+    """Thin asynchronous non-executing authorization boundary."""
+
+    def __init__(self, transport: Any) -> None:
+        self._transport = transport
+
+    async def check(
+        self,
+        *,
+        token: str,
+        identity_id: str,
+        credential_fingerprint: str,
+        operation: str,
+        message: str,
+        signature: str,
+    ) -> dict[str, Any]:
+        """Evaluate authorization without executing the operation."""
+
+        response = await self._transport.request(
+            "POST",
+            "/v1/authorization/check",
+            json=_payload(
+                token=token,
+                identity_id=identity_id,
+                credential_fingerprint=credential_fingerprint,
+                operation=operation,
+                message=message,
+                signature=signature,
+            ),
+        )
+
+        return response.json()

ucii/client.py

@@ -0,0 +1,92 @@
+"""Minimal public UCII SDK client.
+
+This client intentionally exposes only publication-approved interoperability
+namespaces. Private UCII trust, authority, enforcement, economic, fleet,
+adoption, and provenance machinery is not part of this client surface.
+"""
+
+from __future__ import annotations
+
+from .authorization import (
+    AsyncAuthorizationNamespace,
+    AuthorizationNamespace,
+)
+from ._transport import AsyncHTTPTransport, HTTPTransport
+from .credentials import AsyncCredentialsNamespace, CredentialsNamespace
+from .identity import AsyncIdentityNamespace, IdentityNamespace
+from .verification import AsyncVerificationNamespace, VerificationNamespace
+from .x402 import AsyncX402Namespace, X402Namespace
+
+
+class UCIIClient:
+    """Synchronous client for publication-approved UCII namespaces."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+
+        self._transport = HTTPTransport(
+            base_url=self.base_url,
+            api_key=self.api_key,
+            timeout=self.timeout,
+        )
+
+        self.identity = IdentityNamespace(self._transport)
+        self.authorization = AuthorizationNamespace(self._transport)
+        self.credentials = CredentialsNamespace(self._transport)
+        self.verification = VerificationNamespace(self._transport)
+        self.x402 = X402Namespace(self._transport)
+
+    def close(self) -> None:
+        """Close the underlying HTTP transport."""
+        self._transport.close()
+
+    def __enter__(self) -> "UCIIClient":
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
+        self.close()
+
+
+class AsyncUCIIClient:
+    """Asynchronous client for publication-approved UCII namespaces."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+
+        self._transport = AsyncHTTPTransport(
+            base_url=self.base_url,
+            api_key=self.api_key,
+            timeout=self.timeout,
+        )
+
+        self.identity = AsyncIdentityNamespace(self._transport)
+        self.authorization = AsyncAuthorizationNamespace(self._transport)
+        self.credentials = AsyncCredentialsNamespace(self._transport)
+        self.verification = AsyncVerificationNamespace(self._transport)
+        self.x402 = AsyncX402Namespace(self._transport)
+
+    async def close(self) -> None:
+        """Close the underlying HTTP transport."""
+        await self._transport.close()
+
+    async def __aenter__(self) -> "AsyncUCIIClient":
+        return self
+
+    async def __aexit__(self, exc_type, exc_value, traceback) -> None:
+        await self.close()