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

sentinel/models/requests.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, fields
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from sentinel.models.license import SubUser
+
+
+class _ClearValue:
+    """Sentinel indicating a field should be cleared in the API."""
+
+    _instance: _ClearValue | None = None
+
+    def __new__(cls) -> _ClearValue:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return "CLEAR"
+
+
+CLEAR: Any = _ClearValue()
+"""Pass as a field value in :class:`UpdateLicenseRequest` to clear the stored value.
+Sends the appropriate empty/reset value per field type (empty string for text fields,
+empty collection for collection fields, epoch for expiration)."""
+
+CLEAR_EXPIRATION = datetime(1970, 1, 1, tzinfo=UTC)
+"""Pass as ``expiration`` in :class:`UpdateLicenseRequest` to clear a license's expiration
+(i.e. set it to never expire). The API interprets the Unix epoch as "no expiration"."""
+
+
+@dataclass(frozen=True)
+class CreateLicenseRequest:
+    product: str
+    key: str | None = None
+    tier: str | None = None
+    expiration: datetime | None = None
+    max_servers: int | None = None
+    max_ips: int | None = None
+    note: str | None = None
+    connections: dict[str, str] | None = None
+    additional_entitlements: set[str] | None = None
+
+    def to_body(self) -> dict[str, Any]:
+        body: dict[str, Any] = {"product": self.product}
+        if self.key is not None:
+            body["key"] = self.key
+        if self.tier is not None:
+            body["tier"] = self.tier
+        if self.expiration is not None:
+            body["expiration"] = self.expiration.isoformat()
+        if self.max_servers is not None:
+            body["maxServers"] = self.max_servers
+        if self.max_ips is not None:
+            body["maxIps"] = self.max_ips
+        if self.note is not None:
+            body["note"] = self.note
+        if self.connections is not None:
+            body["connections"] = self.connections
+        if self.additional_entitlements is not None:
+            body["additionalEntitlements"] = list(self.additional_entitlements)
+        return body
+
+
+_CLEAR_JSON_VALUES: dict[str, Any] = {
+    "connections": {},
+    "subUsers": [],
+    "servers": [],
+    "ips": [],
+    "additionalEntitlements": [],
+    "expiration": datetime(1970, 1, 1, tzinfo=UTC).isoformat(),
+}
+
+_FIELD_TO_JSON: dict[str, str] = {
+    "product": "product",
+    "tier": "tier",
+    "expiration": "expiration",
+    "max_servers": "maxServers",
+    "max_ips": "maxIps",
+    "note": "note",
+    "blacklist_reason": "blacklistReason",
+    "connections": "connections",
+    "sub_users": "subUsers",
+    "servers": "servers",
+    "ips": "ips",
+    "additional_entitlements": "additionalEntitlements",
+}
+
+
+@dataclass
+class UpdateLicenseRequest:
+    product: str | None = None
+    tier: str | None = None
+    expiration: datetime | None = None
+    max_servers: int | None = None
+    max_ips: int | None = None
+    note: str | None = None
+    blacklist_reason: str | None = None
+    connections: dict[str, str] | None = None
+    sub_users: list[SubUser] | None = None
+    servers: set[str] | None = None
+    ips: set[str] | None = None
+    additional_entitlements: set[str] | None = None
+
+    def to_body(self) -> dict[str, Any]:
+        body: dict[str, Any] = {}
+        for f in fields(self):
+            value = getattr(self, f.name)
+            json_key = _FIELD_TO_JSON.get(f.name, f.name)
+            if isinstance(value, _ClearValue):
+                body[json_key] = _CLEAR_JSON_VALUES.get(json_key, "")
+            elif value is not None:
+                if isinstance(value, datetime):
+                    body[json_key] = value.isoformat()
+                elif isinstance(value, set):
+                    body[json_key] = list(value)
+                elif isinstance(value, list):
+                    body[json_key] = [
+                        item.model_dump() if hasattr(item, "model_dump") else item
+                        for item in value
+                    ]
+                else:
+                    body[json_key] = value
+        return body
+
+
+@dataclass(frozen=True)
+class ListLicensesRequest:
+    product: str | None = None
+    status: str | None = None
+    query: str | None = None
+    platform: str | None = None
+    value: str | None = None
+    server: str | None = None
+    ip: str | None = None
+    page: int = 0
+    size: int = 50
+
+    def to_query_params(self) -> dict[str, str]:
+        params: dict[str, str] = {}
+        if self.product is not None:
+            params["product"] = self.product
+        if self.status is not None:
+            params["status"] = self.status
+        if self.query is not None:
+            params["query"] = self.query
+        if self.platform is not None:
+            params["platform"] = self.platform
+        if self.value is not None:
+            params["value"] = self.value
+        if self.server is not None:
+            params["server"] = self.server
+        if self.ip is not None:
+            params["ip"] = self.ip
+        params["page"] = str(self.page)
+        params["size"] = str(self.size)
+        return params
+
+
+@dataclass(frozen=True)
+class ValidationRequest:
+    product: str
+    key: str | None = None
+    server: str | None = None
+    ip: str | None = None
+    connection_platform: str | None = None
+    connection_value: str | None = None
+
+    def to_body(self) -> dict[str, str]:
+        body: dict[str, str] = {"product": self.product}
+        if self.key is not None:
+            body["key"] = self.key
+        if self.server is not None:
+            body["server"] = self.server
+        if self.ip is not None:
+            body["ip"] = self.ip
+        if self.connection_platform is not None:
+            body["connectionPlatform"] = self.connection_platform
+        if self.connection_value is not None:
+            body["connectionValue"] = self.connection_value
+        return body

sentinel/models/validation.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import StrEnum
+
+from sentinel._exceptions import LicenseValidationError
+
+
+class ValidationResultType(StrEnum):
+    SUCCESS = "SUCCESS"
+    INVALID_PRODUCT = "INVALID_PRODUCT"
+    INVALID_LICENSE = "INVALID_LICENSE"
+    INVALID_PLATFORM = "INVALID_PLATFORM"
+    EXPIRED_LICENSE = "EXPIRED_LICENSE"
+    BLACKLISTED_LICENSE = "BLACKLISTED_LICENSE"
+    CONNECTION_MISMATCH = "CONNECTION_MISMATCH"
+    EXCESSIVE_SERVERS = "EXCESSIVE_SERVERS"
+    EXCESSIVE_IPS = "EXCESSIVE_IPS"
+    UNKNOWN = "UNKNOWN"
+
+    @staticmethod
+    def from_string(value: str | None) -> ValidationResultType:
+        if value is None:
+            return ValidationResultType.UNKNOWN
+        try:
+            return ValidationResultType(value)
+        except ValueError:
+            return ValidationResultType.UNKNOWN
+
+
+@dataclass(frozen=True)
+class ValidationDetails:
+    expiration: datetime | None
+    server_count: int
+    max_servers: int
+    ip_count: int
+    max_ips: int
+    tier: str | None
+    entitlements: set[str]
+
+
+@dataclass(frozen=True)
+class FailureDetails:
+    pass
+
+
+@dataclass(frozen=True)
+class BlacklistFailureDetails(FailureDetails):
+    timestamp: datetime
+    reason: str | None
+
+
+@dataclass(frozen=True)
+class ExcessiveServersFailureDetails(FailureDetails):
+    max_servers: int
+
+
+@dataclass(frozen=True)
+class ExcessiveIpsFailureDetails(FailureDetails):
+    max_ips: int
+
+
+@dataclass(frozen=True)
+class ValidationResult:
+    type: ValidationResultType
+    message: str
+    is_valid: bool
+    details: ValidationDetails | None = None
+    failure_details: FailureDetails | None = None
+
+    @staticmethod
+    def success(details: ValidationDetails, message: str) -> ValidationResult:
+        return ValidationResult(
+            type=ValidationResultType.SUCCESS,
+            message=message,
+            is_valid=True,
+            details=details,
+        )
+
+    @staticmethod
+    def failure(
+        type: ValidationResultType,
+        message: str,
+        failure_details: FailureDetails | None = None,
+    ) -> ValidationResult:
+        return ValidationResult(
+            type=type,
+            message=message,
+            is_valid=False,
+            failure_details=failure_details,
+        )
+
+    def require_valid(self) -> ValidationDetails:
+        if not self.is_valid:
+            raise LicenseValidationError(
+                type=self.type,
+                message=self.message,
+                failure_details=self.failure_details,
+            )
+        assert self.details is not None
+        return self.details

sentinel/services/__init__.py

@@ -0,0 +1 @@
+"""Sentinel API services."""

sentinel/services/_async_license.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from sentinel._exceptions import SentinelApiError
+from sentinel._http import ApiResponse, AsyncSentinelHttpClient
+from sentinel._replay import ReplayProtector
+from sentinel._signature import SignatureVerifier
+from sentinel.models.license import License
+from sentinel.models.page import Page
+from sentinel.models.requests import (
+    CreateLicenseRequest,
+    ListLicensesRequest,
+    UpdateLicenseRequest,
+    ValidationRequest,
+)
+from sentinel.models.validation import (
+    ValidationDetails,
+    ValidationResult,
+    ValidationResultType,
+)
+from sentinel.services._async_operations import (
+    AsyncLicenseConnectionOperations,
+    AsyncLicenseIpOperations,
+    AsyncLicenseServerOperations,
+    AsyncLicenseSubUserOperations,
+)
+from sentinel.services._license import _parse_failure_details
+
+_BASE_PATH = "/api/v2/licenses"
+
+
+class AsyncLicenseService:
+    def __init__(
+        self,
+        http_client: AsyncSentinelHttpClient,
+        signature_verifier: SignatureVerifier | None = None,
+        replay_protector: ReplayProtector | None = None,
+    ) -> None:
+        self._http = http_client
+        self._sig = signature_verifier
+        self._replay = replay_protector
+        self.connections = AsyncLicenseConnectionOperations(http_client)
+        self.servers = AsyncLicenseServerOperations(http_client)
+        self.ips = AsyncLicenseIpOperations(http_client)
+        self.sub_users = AsyncLicenseSubUserOperations(http_client)
+
+    async def validate(self, request: ValidationRequest) -> ValidationResult:
+        body = request.to_body()
+        if "server" not in body:
+            import asyncio
+
+            from sentinel.util.fingerprint import generate_fingerprint
+
+            body["server"] = await asyncio.to_thread(generate_fingerprint)
+
+        resp = await self._http.request(
+            "POST", f"{_BASE_PATH}/validate", json_body=body, allowed_statuses={403}
+        )
+
+        if resp.http_status == 200:
+            return self._parse_validation_success(resp)
+        if resp.http_status == 403:
+            return self._parse_validation_failure(resp)
+        raise SentinelApiError(
+            http_status=resp.http_status,
+            type=resp.type,
+            message=resp.message or "Unknown error",
+        )
+
+    async def create(self, request: CreateLicenseRequest) -> License:
+        resp = await self._http.request("POST", _BASE_PATH, json_body=request.to_body())
+        return License.model_validate(resp.require_result()["license"])
+
+    async def get(self, key: str) -> License:
+        resp = await self._http.request("GET", f"{_BASE_PATH}/{key}")
+        return License.model_validate(resp.require_result()["license"])
+
+    async def list(self, request: ListLicensesRequest) -> Page[License]:
+        resp = await self._http.request("GET", _BASE_PATH, query_params=request.to_query_params())
+        page_data = resp.require_result()["page"]
+        licenses = [License.model_validate(item) for item in page_data["content"]]
+        meta = page_data["page"]
+        return Page(
+            content=licenses,
+            size=meta["size"],
+            number=meta["number"],
+            total_elements=meta["totalElements"],
+            total_pages=meta["totalPages"],
+        )
+
+    async def update(self, key: str, request: UpdateLicenseRequest) -> License:
+        resp = await self._http.request(
+            "PATCH", f"{_BASE_PATH}/{key}", json_body=request.to_body()
+        )
+        return License.model_validate(resp.require_result()["license"])
+
+    async def delete(self, key: str) -> None:
+        await self._http.request("DELETE", f"{_BASE_PATH}/{key}")
+
+    async def regenerate_key(self, key: str, new_key: str | None = None) -> License:
+        params = {"newKey": new_key} if new_key else None
+        resp = await self._http.request(
+            "POST", f"{_BASE_PATH}/{key}/regenerate-key", query_params=params
+        )
+        return License.model_validate(resp.require_result()["license"])
+
+    def _parse_validation_success(self, resp: ApiResponse) -> ValidationResult:
+        validation = resp.require_result()["validation"]
+        nonce = validation["nonce"]
+        timestamp = validation["timestamp"]
+        signature = validation.get("signature")
+        details_data = validation["details"]
+
+        expiration_str = details_data.get("expiration")
+        expiration = datetime.fromisoformat(expiration_str) if expiration_str else None
+        server_count = details_data["serverCount"]
+        max_servers = details_data["maxServers"]
+        ip_count = details_data["ipCount"]
+        max_ips = details_data["maxIps"]
+        tier = details_data.get("tier")
+
+        raw_entitlements = details_data.get("entitlements")
+        entitlements_list: list[str] | None = None
+        entitlements_set: set[str] = set()
+        if raw_entitlements is not None:
+            entitlements_list = list(raw_entitlements)
+            entitlements_set = set(raw_entitlements)
+
+        details = ValidationDetails(
+            expiration=expiration,
+            server_count=server_count,
+            max_servers=max_servers,
+            ip_count=ip_count,
+            max_ips=max_ips,
+            tier=tier,
+            entitlements=entitlements_set,
+        )
+        result = ValidationResult.success(details=details, message=resp.message or "")
+
+        if self._sig is not None:
+            self._sig.verify(
+                signature_base64=signature,
+                nonce=nonce,
+                timestamp=timestamp,
+                expiration=expiration_str,
+                server_count=server_count,
+                max_servers=max_servers,
+                ip_count=ip_count,
+                max_ips=max_ips,
+                tier=tier,
+                entitlements=entitlements_list,
+            )
+            if self._replay is not None:
+                self._replay.check(nonce, timestamp)
+
+        return result
+
+    def _parse_validation_failure(self, resp: ApiResponse) -> ValidationResult:
+        result_type = ValidationResultType.from_string(resp.type)
+        if result_type == ValidationResultType.UNKNOWN:
+            raise SentinelApiError(
+                http_status=resp.http_status,
+                type=resp.type,
+                message=resp.message or "Unknown error",
+            )
+        failure_details = _parse_failure_details(result_type, resp.result)
+        return ValidationResult.failure(
+            type=result_type,
+            message=resp.message or "",
+            failure_details=failure_details,
+        )

sentinel/services/_async_operations.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from sentinel._http import AsyncSentinelHttpClient
+from sentinel.models.license import License, SubUser
+
+_BASE_PATH = "/api/v2/licenses"
+
+
+class AsyncLicenseConnectionOperations:
+    def __init__(self, http_client: AsyncSentinelHttpClient) -> None:
+        self._http = http_client
+
+    async def add(self, key: str, connections: dict[str, str]) -> License:
+        resp = await self._http.request(
+            "POST", f"{_BASE_PATH}/{key}/connections", json_body=connections
+        )
+        return License.model_validate(resp.require_result()["license"])
+
+    async def remove(self, key: str, platforms: set[str]) -> License:
+        resp = await self._http.request(
+            "DELETE",
+            f"{_BASE_PATH}/{key}/connections",
+            multi_query_params={"platforms": sorted(platforms)},
+        )
+        return License.model_validate(resp.require_result()["license"])
+
+
+class AsyncLicenseServerOperations:
+    def __init__(self, http_client: AsyncSentinelHttpClient) -> None:
+        self._http = http_client
+
+    async def add(self, key: str, identifiers: set[str]) -> License:
+        resp = await self._http.request(
+            "POST", f"{_BASE_PATH}/{key}/servers", json_body=sorted(identifiers)
+        )
+        return License.model_validate(resp.require_result()["license"])
+
+    async def remove(self, key: str, identifiers: set[str]) -> License:
+        resp = await self._http.request(
+            "DELETE",
+            f"{_BASE_PATH}/{key}/servers",
+            multi_query_params={"servers": sorted(identifiers)},
+        )
+        return License.model_validate(resp.require_result()["license"])
+
+
+class AsyncLicenseIpOperations:
+    def __init__(self, http_client: AsyncSentinelHttpClient) -> None:
+        self._http = http_client
+
+    async def add(self, key: str, addresses: set[str]) -> License:
+        resp = await self._http.request(
+            "POST", f"{_BASE_PATH}/{key}/ips", json_body=sorted(addresses)
+        )
+        return License.model_validate(resp.require_result()["license"])
+
+    async def remove(self, key: str, addresses: set[str]) -> License:
+        resp = await self._http.request(
+            "DELETE",
+            f"{_BASE_PATH}/{key}/ips",
+            multi_query_params={"ips": sorted(addresses)},
+        )
+        return License.model_validate(resp.require_result()["license"])
+
+
+class AsyncLicenseSubUserOperations:
+    def __init__(self, http_client: AsyncSentinelHttpClient) -> None:
+        self._http = http_client
+
+    async def add(self, key: str, sub_users: list[SubUser]) -> License:
+        body = [su.model_dump() for su in sub_users]
+        resp = await self._http.request("POST", f"{_BASE_PATH}/{key}/sub-users", json_body=body)
+        return License.model_validate(resp.require_result()["license"])
+
+    async def remove(self, key: str, sub_users: list[SubUser]) -> License:
+        body = [su.model_dump() for su in sub_users]
+        resp = await self._http.request(
+            "POST", f"{_BASE_PATH}/{key}/sub-users/remove", json_body=body
+        )
+        return License.model_validate(resp.require_result()["license"])