sentinel-python-client 2.0.0__py3-none-any.whl

sentinel/__init__.py

@@ -0,0 +1,69 @@
+"""Sentinel Python Client - Official client for the Sentinel v2 API."""
+
+from sentinel._async_client import AsyncSentinelClient
+from sentinel._client import SentinelClient
+from sentinel._exceptions import (
+    LicenseValidationError,
+    ReplayDetectedError,
+    SentinelApiError,
+    SentinelConnectionError,
+    SentinelError,
+    SignatureVerificationError,
+)
+from sentinel.models.license import (
+    BlacklistInfo,
+    License,
+    LicenseIssuer,
+    LicenseProduct,
+    LicenseTier,
+    SubUser,
+)
+from sentinel.models.page import Page
+from sentinel.models.requests import (
+    CLEAR,
+    CLEAR_EXPIRATION,
+    CreateLicenseRequest,
+    ListLicensesRequest,
+    UpdateLicenseRequest,
+    ValidationRequest,
+)
+from sentinel.models.validation import (
+    BlacklistFailureDetails,
+    ExcessiveIpsFailureDetails,
+    ExcessiveServersFailureDetails,
+    FailureDetails,
+    ValidationDetails,
+    ValidationResult,
+    ValidationResultType,
+)
+
+__all__ = [
+    "SentinelClient",
+    "AsyncSentinelClient",
+    "SentinelError",
+    "SentinelApiError",
+    "SentinelConnectionError",
+    "LicenseValidationError",
+    "SignatureVerificationError",
+    "ReplayDetectedError",
+    "License",
+    "LicenseProduct",
+    "LicenseTier",
+    "LicenseIssuer",
+    "SubUser",
+    "BlacklistInfo",
+    "ValidationResult",
+    "ValidationResultType",
+    "ValidationDetails",
+    "FailureDetails",
+    "BlacklistFailureDetails",
+    "ExcessiveServersFailureDetails",
+    "ExcessiveIpsFailureDetails",
+    "CreateLicenseRequest",
+    "UpdateLicenseRequest",
+    "ListLicensesRequest",
+    "ValidationRequest",
+    "CLEAR",
+    "CLEAR_EXPIRATION",
+    "Page",
+]

sentinel/_async_client.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from datetime import timedelta
+
+from sentinel._http import AsyncSentinelHttpClient
+from sentinel._replay import ReplayProtector
+from sentinel._signature import SignatureVerifier
+from sentinel.services._async_license import AsyncLicenseService
+
+
+class AsyncSentinelClient:
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        public_key: str | None = None,
+        connect_timeout: float = 5.0,
+        read_timeout: float = 10.0,
+        replay_protection_window: timedelta = timedelta(seconds=30),
+        nonce_cache_size: int = 1000,
+    ) -> None:
+        if not base_url:
+            raise ValueError("base_url is required")
+        if not api_key:
+            raise ValueError("api_key is required")
+
+        self._http = AsyncSentinelHttpClient(
+            base_url=base_url,
+            api_key=api_key,
+            connect_timeout=connect_timeout,
+            read_timeout=read_timeout,
+        )
+
+        sig: SignatureVerifier | None = None
+        replay: ReplayProtector | None = None
+        if public_key is not None:
+            sig = SignatureVerifier(public_key)
+            replay = ReplayProtector(
+                window_seconds=replay_protection_window.total_seconds(),
+                max_size=nonce_cache_size,
+            )
+
+        self.licenses = AsyncLicenseService(
+            http_client=self._http,
+            signature_verifier=sig,
+            replay_protector=replay,
+        )
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncSentinelClient:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.aclose()

sentinel/_client.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from datetime import timedelta
+
+from sentinel._http import SentinelHttpClient
+from sentinel._replay import ReplayProtector
+from sentinel._signature import SignatureVerifier
+from sentinel.services._license import LicenseService
+
+
+class SentinelClient:
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        public_key: str | None = None,
+        connect_timeout: float = 5.0,
+        read_timeout: float = 10.0,
+        replay_protection_window: timedelta = timedelta(seconds=30),
+        nonce_cache_size: int = 1000,
+    ) -> None:
+        if not base_url:
+            raise ValueError("base_url is required")
+        if not api_key:
+            raise ValueError("api_key is required")
+
+        self._http = SentinelHttpClient(
+            base_url=base_url,
+            api_key=api_key,
+            connect_timeout=connect_timeout,
+            read_timeout=read_timeout,
+        )
+
+        sig: SignatureVerifier | None = None
+        replay: ReplayProtector | None = None
+        if public_key is not None:
+            sig = SignatureVerifier(public_key)
+            replay = ReplayProtector(
+                window_seconds=replay_protection_window.total_seconds(),
+                max_size=nonce_cache_size,
+            )
+
+        self.licenses = LicenseService(
+            http_client=self._http,
+            signature_verifier=sig,
+            replay_protector=replay,
+        )
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> SentinelClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()

sentinel/_exceptions.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from sentinel.models.validation import ValidationResultType
+
+
+class SentinelError(Exception):
+    pass
+
+
+class SentinelApiError(SentinelError):
+    def __init__(
+        self,
+        http_status: int,
+        type: str | None,
+        message: str,
+        retry_after_seconds: float | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.http_status = http_status
+        self.type = type
+        self.retry_after_seconds = retry_after_seconds
+
+
+class SentinelConnectionError(SentinelError):
+    def __init__(self, message: str, cause: Exception | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        if cause is not None:
+            self.__cause__ = cause
+
+
+class LicenseValidationError(SentinelError):
+    def __init__(
+        self,
+        type: ValidationResultType,
+        message: str,
+        failure_details: object | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.type = type
+        self.failure_details = failure_details
+
+
+class SignatureVerificationError(SentinelError):
+    pass
+
+
+class ReplayDetectedError(SentinelError):
+    pass

sentinel/_http.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urlencode
+
+import httpx
+
+from sentinel._exceptions import SentinelApiError, SentinelConnectionError
+
+
+@dataclass
+class ApiResponse:
+    http_status: int
+    type: str | None
+    message: str | None
+    result: dict[str, Any] | None
+
+    def require_result(self) -> dict[str, Any]:
+        if self.result is None:
+            raise SentinelApiError(
+                http_status=self.http_status,
+                type=self.type,
+                message="Response contained no result",
+            )
+        return self.result
+
+
+def _parse_response(
+    status_code: int,
+    body: str,
+    headers: httpx.Headers,
+    allowed_statuses: set[int] | None,
+) -> ApiResponse:
+    if status_code == 204:
+        return ApiResponse(http_status=204, type=None, message=None, result=None)
+
+    try:
+        data = json.loads(body)
+    except (json.JSONDecodeError, ValueError) as e:
+        raise SentinelApiError(
+            http_status=status_code, type=None, message="Failed to parse response body"
+        ) from e
+
+    resp_type = data.get("type")
+    message = data.get("message")
+    result = data.get("result") if isinstance(data.get("result"), dict) else None
+
+    if 200 <= status_code < 300:
+        return ApiResponse(http_status=status_code, type=resp_type, message=message, result=result)
+
+    if allowed_statuses and status_code in allowed_statuses:
+        return ApiResponse(http_status=status_code, type=resp_type, message=message, result=result)
+
+    retry_after: float | None = None
+    if status_code == 429:
+        raw = headers.get("X-Rate-Limit-Retry-After-Seconds")
+        if raw is not None:
+            try:
+                retry_after = int(raw)
+            except ValueError:
+                pass
+
+    raise SentinelApiError(
+        http_status=status_code,
+        type=resp_type,
+        message=message or "Unknown error",
+        retry_after_seconds=retry_after,
+    )
+
+
+def _build_url(
+    base_url: str,
+    path: str,
+    query_params: dict[str, str] | None = None,
+    multi_query_params: dict[str, list[str]] | None = None,
+) -> str:
+    url = base_url + path
+    if multi_query_params:
+        parts: list[str] = []
+        for key in sorted(multi_query_params):
+            for val in sorted(multi_query_params[key]):
+                parts.append(f"{urlencode({key: val})}")
+        url += "?" + "&".join(parts)
+        return url
+    if query_params:
+        sorted_params = sorted(query_params.items())
+        url += "?" + urlencode(sorted_params)
+    return url
+
+
+class SentinelHttpClient:
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        connect_timeout: float = 5.0,
+        read_timeout: float = 10.0,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        if http_client is not None:
+            self._client = http_client
+        else:
+            self._client = httpx.Client(
+                timeout=httpx.Timeout(
+                    connect=connect_timeout, read=read_timeout, write=5.0, pool=5.0
+                ),
+            )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        json_body: dict[str, Any] | list[Any] | None = None,
+        query_params: dict[str, str] | None = None,
+        multi_query_params: dict[str, list[str]] | None = None,
+        allowed_statuses: set[int] | None = None,
+    ) -> ApiResponse:
+        url = _build_url(self._base_url, path, query_params, multi_query_params)
+        headers = {"Authorization": f"Bearer {self._api_key}"}
+        kwargs: dict[str, Any] = {"headers": headers}
+
+        if json_body is not None:
+            headers["Content-Type"] = "application/json"
+            kwargs["content"] = json.dumps(json_body)
+        try:
+            response = self._client.request(method, url, **kwargs)
+        except httpx.TimeoutException as e:
+            raise SentinelConnectionError("Failed to connect to Sentinel API", e) from e
+        except httpx.NetworkError as e:
+            raise SentinelConnectionError("Failed to connect to Sentinel API", e) from e
+
+        return _parse_response(
+            response.status_code, response.text, response.headers, allowed_statuses
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+
+class AsyncSentinelHttpClient:
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        connect_timeout: float = 5.0,
+        read_timeout: float = 10.0,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        if http_client is not None:
+            self._client = http_client
+        else:
+            self._client = httpx.AsyncClient(
+                timeout=httpx.Timeout(
+                    connect=connect_timeout, read=read_timeout, write=5.0, pool=5.0
+                ),
+            )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        json_body: dict[str, Any] | list[Any] | None = None,
+        query_params: dict[str, str] | None = None,
+        multi_query_params: dict[str, list[str]] | None = None,
+        allowed_statuses: set[int] | None = None,
+    ) -> ApiResponse:
+        url = _build_url(self._base_url, path, query_params, multi_query_params)
+        headers = {"Authorization": f"Bearer {self._api_key}"}
+        kwargs: dict[str, Any] = {"headers": headers}
+
+        if json_body is not None:
+            headers["Content-Type"] = "application/json"
+            kwargs["content"] = json.dumps(json_body)
+        try:
+            response = await self._client.request(method, url, **kwargs)
+        except httpx.TimeoutException as e:
+            raise SentinelConnectionError("Failed to connect to Sentinel API", e) from e
+        except httpx.NetworkError as e:
+            raise SentinelConnectionError("Failed to connect to Sentinel API", e) from e
+
+        return _parse_response(
+            response.status_code, response.text, response.headers, allowed_statuses
+        )
+
+    async def aclose(self) -> None:
+        await self._client.aclose()

sentinel/_replay.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import threading
+import time
+from collections import OrderedDict
+
+from sentinel._exceptions import ReplayDetectedError
+
+
+class ReplayProtector:
+    def __init__(self, window_seconds: float, max_size: int) -> None:
+        self._window_ms = window_seconds * 1000
+        self._max_size = max_size
+        self._nonce_cache: OrderedDict[str, bool] = OrderedDict()
+        self._lock = threading.Lock()
+
+    def check(self, nonce: str, response_timestamp_ms: int) -> None:
+        now = time.time() * 1000
+        drift = abs(now - response_timestamp_ms)
+
+        if drift > self._window_ms:
+            raise ReplayDetectedError(
+                f"Response timestamp is outside the acceptable window: "
+                f"drift={int(drift)}ms, window={int(self._window_ms)}ms"
+            )
+
+        with self._lock:
+            if nonce in self._nonce_cache:
+                raise ReplayDetectedError(f"Duplicate nonce detected: {nonce}")
+            self._nonce_cache[nonce] = True
+            while len(self._nonce_cache) > self._max_size:
+                self._nonce_cache.popitem(last=False)

sentinel/_signature.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import base64
+
+from nacl.exceptions import BadSignatureError
+from nacl.signing import VerifyKey
+
+from sentinel._exceptions import SignatureVerificationError
+
+
+class SignatureVerifier:
+    # X.509 SubjectPublicKeyInfo prefix for Ed25519 (OID 1.3.101.112)
+    _SPKI_PREFIX = bytes.fromhex("302a300506032b6570032100")
+
+    def __init__(self, base64_public_key: str) -> None:
+        try:
+            key_bytes = base64.b64decode(base64_public_key)
+            if key_bytes[:12] == self._SPKI_PREFIX:
+                raw_key = key_bytes[12:]
+            else:
+                raw_key = key_bytes
+            self._verify_key = VerifyKey(raw_key)
+        except Exception as e:
+            raise ValueError(f"Invalid Ed25519 public key: {e}") from e
+
+    def verify(
+        self,
+        signature_base64: str | None,
+        nonce: str,
+        timestamp: int,
+        expiration: str | None,
+        server_count: int,
+        max_servers: int,
+        ip_count: int,
+        max_ips: int,
+        tier: str | None,
+        entitlements: list[str] | None,
+    ) -> None:
+        if signature_base64 is None:
+            raise SignatureVerificationError(
+                "Response signature is null but signature verification is enabled"
+            )
+
+        canonical = self.build_canonical_payload(
+            nonce=nonce,
+            timestamp=timestamp,
+            expiration=expiration,
+            server_count=server_count,
+            max_servers=max_servers,
+            ip_count=ip_count,
+            max_ips=max_ips,
+            tier=tier,
+            entitlements=entitlements,
+        )
+
+        try:
+            sig_bytes = base64.b64decode(signature_base64)
+            self._verify_key.verify(canonical.encode("utf-8"), sig_bytes)
+        except BadSignatureError:
+            raise SignatureVerificationError("Signature verification failed")
+        except SignatureVerificationError:
+            raise
+        except Exception as e:
+            raise SignatureVerificationError(f"Signature verification error: {e}") from e
+
+    def build_canonical_payload(
+        self,
+        nonce: str,
+        timestamp: int,
+        expiration: str | None,
+        server_count: int,
+        max_servers: int,
+        ip_count: int,
+        max_ips: int,
+        tier: str | None,
+        entitlements: list[str] | None,
+    ) -> str:
+        parts: list[str] = ["{"]
+        parts.append('"entitlements":')
+        if entitlements is None:
+            parts.append("null")
+        else:
+            sorted_ent = sorted(entitlements)
+            parts.append("[")
+            parts.append(",".join(_json_string(e) for e in sorted_ent))
+            parts.append("]")
+        parts.append(f',"expiration":{_json_string(expiration)}')
+        parts.append(f',"ipCount":{ip_count}')
+        parts.append(f',"maxIps":{max_ips}')
+        parts.append(f',"maxServers":{max_servers}')
+        parts.append(f',"nonce":{_json_string(nonce)}')
+        parts.append(f',"serverCount":{server_count}')
+        parts.append(f',"tier":{_json_string(tier)}')
+        parts.append(f',"timestamp":{timestamp}')
+        parts.append("}")
+        return "".join(parts)
+
+
+def _json_string(value: str | None) -> str:
+    if value is None:
+        return "null"
+    result = ['"']
+    for ch in value:
+        if ch == '"':
+            result.append('\\"')
+        elif ch == "\\":
+            result.append("\\\\")
+        elif ch == "\n":
+            result.append("\\n")
+        elif ch == "\r":
+            result.append("\\r")
+        elif ch == "\t":
+            result.append("\\t")
+        elif ord(ch) < 0x20:
+            result.append(f"\\u{ord(ch):04x}")
+        else:
+            result.append(ch)
+    result.append('"')
+    return "".join(result)

sentinel/models/__init__.py

@@ -0,0 +1,24 @@
+"""Sentinel API models."""
+
+from sentinel.models.license import BlacklistInfo as BlacklistInfo
+from sentinel.models.license import License as License
+from sentinel.models.license import LicenseIssuer as LicenseIssuer
+from sentinel.models.license import LicenseProduct as LicenseProduct
+from sentinel.models.license import LicenseTier as LicenseTier
+from sentinel.models.license import SubUser as SubUser
+from sentinel.models.page import Page as Page
+from sentinel.models.requests import CLEAR as CLEAR
+from sentinel.models.requests import CLEAR_EXPIRATION as CLEAR_EXPIRATION
+from sentinel.models.requests import CreateLicenseRequest as CreateLicenseRequest
+from sentinel.models.requests import ListLicensesRequest as ListLicensesRequest
+from sentinel.models.requests import UpdateLicenseRequest as UpdateLicenseRequest
+from sentinel.models.requests import ValidationRequest as ValidationRequest
+from sentinel.models.validation import BlacklistFailureDetails as BlacklistFailureDetails
+from sentinel.models.validation import ExcessiveIpsFailureDetails as ExcessiveIpsFailureDetails
+from sentinel.models.validation import (
+    ExcessiveServersFailureDetails as ExcessiveServersFailureDetails,
+)
+from sentinel.models.validation import FailureDetails as FailureDetails
+from sentinel.models.validation import ValidationDetails as ValidationDetails
+from sentinel.models.validation import ValidationResult as ValidationResult
+from sentinel.models.validation import ValidationResultType as ValidationResultType

sentinel/models/license.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+from pydantic.alias_generators import to_camel
+
+
+class _CamelModel(BaseModel):
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        frozen=True,
+    )
+
+
+class LicenseProduct(_CamelModel):
+    id: str
+    name: str
+    description: str | None = None
+    logo_url: str | None = None
+
+
+class LicenseTier(_CamelModel):
+    id: str
+    name: str | None = None
+    entitlements: set[str] = set()
+
+
+class LicenseIssuer(_CamelModel):
+    type: str
+    id: str
+    display_name: str
+
+
+class SubUser(_CamelModel):
+    platform: str
+    value: str
+
+
+class BlacklistInfo(_CamelModel):
+    timestamp: datetime
+    reason: str | None = None
+
+
+class License(_CamelModel):
+    id: str
+    key: str
+    product: LicenseProduct
+    tier: LicenseTier | None = None
+    issuer: LicenseIssuer
+    created_at: datetime
+    expiration: datetime | None = None
+    max_servers: int
+    max_ips: int
+    note: str | None = None
+    connections: dict[str, str] = {}
+    sub_users: list[SubUser] = []
+    servers: dict[str, datetime] = {}
+    ips: dict[str, datetime] = {}
+    additional_entitlements: set[str] = set()
+    entitlements: set[str] = set()
+    blacklist: BlacklistInfo | None = None

sentinel/models/page.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class Page(Generic[T]):
+    content: list[T]
+    size: int
+    number: int
+    total_elements: int
+    total_pages: int