licantha-sdk 0.1.0__py3-none-any.whl

licantha_sdk/__init__.py

@@ -0,0 +1,44 @@
+"""Licantha SDK — license-gated model decryption for on-prem AI services.
+
+Public API:
+    SecureClient            — entry point; activates, heartbeats, decrypts models.
+    SecureClientConfigPM    — pydantic config model.
+    SecureClientCliConfig   — same fields, but loads from `.env` / env vars.
+    KeyProvider             — abstract source of AES-256-GCM model keys.
+    LicenseError + leaves   — actionable, customer-facing exceptions.
+"""
+
+from .__version__ import __version__
+from ._base import SecureClient
+from ._errors import (
+    ActivationError,
+    HeartbeatError,
+    KeyUnavailableError,
+    LicenseError,
+    LicenseExpiredError,
+    LicenseSuspendedError,
+    MachineMismatchError,
+    OfflineLicenseError,
+    ValidationError,
+)
+from ._providers import KeyProvider, LeaseKeyProvider
+from .config import SecureClientConfigPM, SecureClientCliConfig
+
+
+__all__ = [
+    "__version__",
+    "SecureClient",
+    "SecureClientConfigPM",
+    "SecureClientCliConfig",
+    "KeyProvider",
+    "LeaseKeyProvider",
+    "LicenseError",
+    "ActivationError",
+    "HeartbeatError",
+    "ValidationError",
+    "OfflineLicenseError",
+    "KeyUnavailableError",
+    "MachineMismatchError",
+    "LicenseExpiredError",
+    "LicenseSuspendedError",
+]

licantha_sdk/__main__.py

@@ -0,0 +1,53 @@
+# Standard libraries
+import os
+import sys
+import logging
+
+# Third-party libraries
+from dotenv import load_dotenv
+
+# Internal modules
+from ._base import SecureClient
+from .config import SecureClientCliConfig
+
+
+load_dotenv(dotenv_path=".env", override=True)
+logger = logging.getLogger(__name__)
+
+
+def main() -> None:
+    """CLI smoke test — activate the SDK against the configured license server.
+
+    Usage:
+        LICANTHA_SDK_ACCOUNT_ID=...  LICANTHA_SDK_LICENSE_KEY=... \\
+        LICANTHA_SDK_PUBLIC_KEY=...  python -m licantha_sdk
+
+    Prints the resolved license_id, machine_id, fingerprint, and the
+    available model_ids in the key cache, then deactivates.
+    """
+
+    _log_level = logging.INFO
+    if str(os.getenv("DEBUG", "0")).lower() in ("1", "true", "t", "yes", "y"):
+        _log_level = logging.DEBUG
+
+    logging.basicConfig(
+        stream=sys.stdout,
+        level=_log_level,
+        datefmt="%Y-%m-%d %H:%M:%S %z",
+        format="[%(asctime)s | %(levelname)s | %(filename)s:%(lineno)d]: %(message)s",
+    )
+
+    _config = SecureClientCliConfig()  # type: ignore[call-arg]
+    with SecureClient(config=_config) as _client:
+        logger.info(f"fingerprint  = {_client.fingerprint}")
+        logger.info(f"license_id   = {_client.license_id}")
+        logger.info(f"machine_id   = {_client.machine_id}")
+        # Touch the key cache via the private snapshot, for visibility.
+        _snapshot = _client.key_provider._snapshot  # type: ignore[attr-defined]
+        logger.info(f"cached keys  = {list(_snapshot.keys())}")
+
+    logger.info("Done!\n")
+
+
+if __name__ == "__main__":
+    main()

licantha_sdk/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

licantha_sdk/_base.py

@@ -0,0 +1,479 @@
+"""SecureClient — the public entry point.
+
+Orchestrates license validation, machine activation, the background
+heartbeat daemon, license-metadata-driven key provisioning, and
+AES-256-GCM model decryption.
+
+Online mode talks to Keygen; offline mode verifies an Ed25519-signed `.lic`
+file shipped alongside the binary.
+
+Lifecycle::
+
+    client = SecureClient(...)
+    client.activate()                  # validate + activate + prime + heartbeat
+    plaintext = client.decrypt_model("model.enc")
+    client.deactivate()                # stop heartbeat + release slot
+
+    # Or, equivalent and exception-safe:
+    with SecureClient(...) as client:
+        plaintext = client.decrypt_model("model.enc")
+"""
+
+# Standard libraries
+from __future__ import annotations
+
+import pprint
+import logging
+from types import TracebackType
+from typing import Any
+
+# Third-party libraries
+from pydantic import validate_call
+
+# Internal modules
+from . import _crypto, _keygen
+from . import _utils as utils
+from .__version__ import __version__
+from ._errors import (
+    ActivationError,
+    KeyUnavailableError,
+    LicenseExpiredError,
+    LicenseSuspendedError,
+    ValidationError,
+)
+from ._fingerprint import fingerprint as _fingerprint_fn
+from ._heartbeat import HeartbeatDaemon
+from ._offline import OfflineLicense, load_offline_license
+from ._providers import KeyProvider, LeaseKeyProvider
+from .config import SecureClientConfigPM
+
+
+logger = logging.getLogger(__name__)
+
+
+_TERMINAL_CODES = {
+    "EXPIRED": LicenseExpiredError,
+    "SUSPENDED": LicenseSuspendedError,
+}
+_ACTIVATION_NEEDED_CODES = {
+    "NO_MACHINE",
+    "NO_MACHINES",
+    "FINGERPRINT_SCOPE_MISMATCH",
+}
+
+
+class SecureClient:
+    """Entry point for license-gated model loading.
+
+    Online mode (default): activates with Keygen, runs a background
+    heartbeat, pulls model keys from signed license metadata.
+
+    Offline mode: pass `offline_license_path` on the config. No network
+    calls are made. Keys come from an Ed25519-signed, AES-256-GCM-encrypted
+    license file (Keygen's cryptographic license file format).
+
+    Use as a context manager whenever possible — it guarantees the
+    heartbeat daemon is stopped and the machine deactivated on exit.
+
+    Attributes:
+        config (SecureClientConfigPM): The active configuration.
+
+    Methods:
+        activate():       Validate + activate + prime keys + start heartbeat.
+        decrypt_model():  Decrypt an AES-256-GCM model envelope into memory.
+        deactivate():     Release this machine's activation slot.
+    """
+
+    @validate_call(config={"arbitrary_types_allowed": True})
+    def __init__(
+        self,
+        config: SecureClientConfigPM | dict[str, Any] | None = None,
+        *,
+        auto_activate: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize a `SecureClient`.
+
+        Args:
+            config         (SecureClientConfigPM | dict | None, optional): Config object,
+                                or a dict the SDK will coerce. Defaults to None
+                                (which only works if every required field is in `kwargs`).
+            auto_activate  (bool                              , optional): If True, call
+                                `activate()` at the end of `__init__`. Defaults to False.
+            **kwargs                                                     : Override individual
+                                config fields (e.g. `license_key="..."`).
+        """
+
+        logger.debug(
+            f"Initializing <{self.__class__.__name__}> object with '{__version__}' version..."
+        )
+
+        if config is None:
+            config = SecureClientConfigPM(**kwargs) if kwargs else None
+        elif kwargs:
+            if isinstance(config, dict):
+                config = {**config, **kwargs}
+            else:
+                config = config.model_copy(update=kwargs)
+
+        if config is None:
+            raise ValueError(
+                "`config` is required — pass a SecureClientConfigPM, a dict, or kwargs."
+            )
+
+        self.config = config
+
+        self._fingerprint = _fingerprint_fn(self.config.app_id)
+        self._session = _keygen.make_session(
+            user_agent=f"licantha-sdk/{__version__}"
+        )
+        self._key_provider: LeaseKeyProvider = LeaseKeyProvider()
+        self._heartbeat: HeartbeatDaemon | None = None
+
+        self._activated = False
+        self._license_id: str | None = None
+        self._machine_id: str | None = None
+        self._offline_license: OfflineLicense | None = None
+
+        logger.debug(
+            f"Initialized <{self.__class__.__name__}> object with '{__version__}' version."
+        )
+
+        if auto_activate:
+            self.activate()
+
+    # LIFECYCLE
+    def activate(self, *, start_heartbeat: bool = True) -> None:
+        """Validate the license, activate this machine if needed, prime keys.
+
+        Idempotent — calling twice is a no-op.
+
+        Offline mode: verifies the license file's Ed25519 signature,
+        decrypts the AES-256-GCM payload with the license key as the KDF
+        input, and pulls keys from the embedded metadata. No network calls.
+
+        Raises:
+            ActivationError, ValidationError, OfflineLicenseError,
+            LicenseExpiredError, LicenseSuspendedError.
+        """
+
+        if self._activated:
+            return
+
+        if self.config.offline_license_path is not None:
+            self._activate_offline()
+        else:
+            self._activate_online()
+            if start_heartbeat and self._machine_id is not None:
+                self.start_heartbeat()
+
+        self._activated = True
+
+    def start_heartbeat(self) -> None:
+        """Start the daemon heartbeat thread. No-op offline or when running."""
+
+        if self.config.offline_license_path is not None:
+            return
+
+        if self._machine_id is None:
+            raise ActivationError(
+                detail="cannot start heartbeat before activation",
+                code="NOT_ACTIVATED",
+            )
+
+        _hb = self._heartbeat
+        if _hb is None:
+            _hb = HeartbeatDaemon(
+                interval=self.config.heartbeat_interval,
+                ping=self._ping_once,
+            )
+            self._heartbeat = _hb
+        _hb.start()
+
+    def stop_heartbeat(self, *, timeout: float = 5.0) -> None:
+        """Signal the heartbeat thread to stop and join within `timeout` seconds."""
+
+        if self._heartbeat is not None:
+            self._heartbeat.stop(timeout=timeout)
+
+    def deactivate(self) -> None:
+        """Remove this machine's activation. No-op offline or when never activated."""
+
+        if self.config.offline_license_path is not None or self._machine_id is None:
+            return
+
+        try:
+            _keygen.deactivate_machine(
+                session=self._session,
+                api_url=self._api_url,
+                account_id=self.config.account_id,
+                license_key=self.config.license_key,
+                machine_id=self._machine_id,
+            )
+        finally:
+            self._machine_id = None
+            self._activated = False
+    # LIFECYCLE
+
+    # KEY + MODEL
+    def decrypt_model(self, path: str, *, model_id: str | None = None) -> bytes:
+        """Decrypt an AES-256-GCM-encrypted model envelope into memory.
+
+        If `model_id` is None, the envelope's embedded model_id is used to
+        select the key. Plaintext is never written to disk by the SDK.
+
+        Raises:
+            ActivationError: `activate()` has not been called.
+            KeyUnavailableError: no key for the requested model.
+            ValueError: envelope is malformed or tag verification failed.
+        """
+
+        if not self._activated:
+            raise ActivationError(
+                detail="decrypt_model called before activate()",
+                code="NOT_ACTIVATED",
+                remediation="Call client.activate() (or use a 'with' block) before decrypting.",
+            )
+
+        if model_id is None:
+            model_id = _crypto.read_model_id(path)
+        _key = self._key_provider.get_model_key(model_id)
+        return _crypto.decrypt_to_memory(path, _key)
+    # KEY + MODEL
+
+    # ATTRIBUTES
+    # config
+    @property
+    def config(self) -> SecureClientConfigPM:
+        try:
+            return self.__config
+        except AttributeError as _e:
+            raise AttributeError("`config` attribute is not set!") from _e
+
+    @config.setter
+    def config(self, config: SecureClientConfigPM | dict[str, Any]) -> None:
+        if (not isinstance(config, SecureClientConfigPM)) and (not isinstance(config, dict)):
+            raise TypeError(
+                f"`config` attribute type {type(config)} is invalid, "
+                "must be a <class 'SecureClientConfigPM'> or <dict>!"
+            )
+
+        if isinstance(config, dict):
+            config = SecureClientConfigPM(**config)
+        else:
+            config = config.model_copy(deep=True)
+
+        self.__config = config
+    # config
+
+    # key_provider
+    @property
+    def key_provider(self) -> KeyProvider:
+        """The KeyProvider backing this client. Same instance across calls."""
+        return self._key_provider
+    # key_provider
+
+    # fingerprint
+    @property
+    def fingerprint(self) -> str:
+        """Hardware fingerprint of this machine for `config.app_id`."""
+        return self._fingerprint
+    # fingerprint
+
+    # license_id
+    @property
+    def license_id(self) -> str | None:
+        """The resolved license UUID, or None before activation."""
+        return self._license_id
+    # license_id
+
+    # machine_id
+    @property
+    def machine_id(self) -> str | None:
+        """The activated machine UUID, or None offline/before activation."""
+        return self._machine_id
+    # machine_id
+    # ATTRIBUTES
+
+    # INTERNAL
+    @property
+    def _api_url(self) -> str:
+        # Tolerate api_url given with or without a trailing /v1 — the SDK
+        # appends /v1 itself at every call site, so we normalise here.
+        # Guaranteed non-None for online activation by the config validator.
+        if not self.config.api_url:
+            raise ValueError("api_url is required for online activation")
+        _base = self.config.api_url.rstrip("/")
+        if _base.endswith("/v1"):
+            _base = _base[:-3]
+        return _base
+
+    def _activate_offline(self) -> None:
+        _offline = load_offline_license(
+            path=self.config.offline_license_path,  # type: ignore[arg-type]
+            license_key=self.config.license_key,
+            public_key_hex=self.config.public_key,
+        )
+        self._offline_license = _offline
+        self._license_id = _offline.license_id or None
+        _keys = _extract_model_keys(_offline.metadata)
+        if not _keys:
+            raise KeyUnavailableError(
+                detail=(
+                    "offline license metadata contains no model keys "
+                    "(expected 'modelKey' or 'models' field)"
+                ),
+            )
+        self._key_provider.prime(_keys)
+        logger.info(
+            f"activated in offline mode license_id={self._license_id} keys={len(_keys)}"
+        )
+
+    def _activate_online(self) -> None:
+        _result = _keygen.validate_key(
+            session=self._session,
+            api_url=self._api_url,
+            account_id=self.config.account_id,
+            license_key=self.config.license_key,
+            fingerprint=self._fingerprint,
+        )
+        self._license_id = _result.license_id
+
+        if _result.code in _TERMINAL_CODES:
+            raise _TERMINAL_CODES[_result.code](detail=_result.detail or _result.code)
+
+        if _result.valid:
+            if _result.license_id is None:
+                raise ActivationError(detail="validate succeeded but returned no license_id")
+            _existing = _keygen.find_machine_id_for_fingerprint(
+                session=self._session,
+                api_url=self._api_url,
+                account_id=self.config.account_id,
+                license_key=self.config.license_key,
+                license_id=_result.license_id,
+                fingerprint=self._fingerprint,
+            )
+            if _existing is None:
+                raise ActivationError(
+                    detail="license is valid but no machine matches this fingerprint",
+                    code="MACHINE_LOOKUP_FAILED",
+                )
+            self._machine_id = _existing
+        elif _result.code in _ACTIVATION_NEEDED_CODES:
+            if _result.license_id is None:
+                raise ActivationError(
+                    detail="validate returned no license_id for activation"
+                )
+            self._machine_id = _keygen.activate_machine(
+                session=self._session,
+                api_url=self._api_url,
+                account_id=self.config.account_id,
+                license_key=self.config.license_key,
+                license_id=_result.license_id,
+                fingerprint=self._fingerprint,
+            )
+        else:
+            raise ValidationError(
+                detail=_result.detail or _result.code,
+                code=_result.code,
+            )
+
+        _metadata = _result.attributes.get("metadata")
+        if not isinstance(_metadata, dict):
+            _metadata = {}
+        _keys = _extract_model_keys(_metadata)
+        if not _keys:
+            raise KeyUnavailableError(
+                detail=(
+                    "license metadata contains no model keys "
+                    "(expected 'modelKey' or 'models' field)"
+                ),
+            )
+        self._key_provider.prime(_keys)
+        logger.info(
+            f"activated online license_id={self._license_id} "
+            f"machine_id={self._machine_id} keys={len(_keys)}"
+        )
+
+    def _ping_once(self) -> None:
+        if self._machine_id is None:
+            return
+        _keygen.ping_heartbeat(
+            session=self._session,
+            api_url=self._api_url,
+            account_id=self.config.account_id,
+            license_key=self.config.license_key,
+            machine_id=self._machine_id,
+        )
+    # INTERNAL
+
+    # METHOD OVERRIDING
+    def __enter__(self) -> SecureClient:
+        self.activate()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        try:
+            self.stop_heartbeat()
+        finally:
+            if self.config.deactivate_on_exit:
+                self.deactivate()
+
+    def __str__(self) -> str:
+        _self_dict = utils.clean_obj_dict(self.__dict__, self.__class__.__name__)
+        _self_dict.pop("_session", None)
+        return f"{self.__class__.__name__}: {pprint.pformat(_self_dict)}"
+
+    def __repr__(self) -> str:
+        return utils.obj_to_repr(self)
+    # METHOD OVERRIDING
+
+
+def _extract_model_keys(metadata: dict[str, Any]) -> dict[str | None, bytes]:
+    """Pull model keys out of a license-metadata blob.
+
+    Supported shapes::
+
+        {"modelKey": "<64 hex chars>"}                     -> single default key
+        {"models":   {"<id>": "<hex>", "<id2>": "<hex2>"}} -> multi-model
+
+    Both can coexist; the default key is stored under None. Hex strings are
+    64 characters (32 bytes / AES-256).
+    """
+
+    _out: dict[str | None, bytes] = {}
+    _default = metadata.get("modelKey")
+    if isinstance(_default, str):
+        _out[None] = _hex_to_aes_key(_default, where="metadata.modelKey")
+
+    _models = metadata.get("models")
+    if isinstance(_models, dict):
+        for _mid, _hex_key in _models.items():
+            if not isinstance(_mid, str) or not isinstance(_hex_key, str):
+                continue
+            _out[_mid] = _hex_to_aes_key(_hex_key, where=f"metadata.models[{_mid!r}]")
+    return _out
+
+
+def _hex_to_aes_key(hex_str: str, *, where: str) -> bytes:
+    try:
+        _raw = bytes.fromhex(hex_str)
+    except ValueError as _e:
+        raise KeyUnavailableError(
+            detail=f"{where} is not valid hex: {_e}",
+            code="INVALID_KEY_HEX",
+        ) from _e
+    if len(_raw) != 32:
+        raise KeyUnavailableError(
+            detail=f"{where} must decode to 32 bytes (AES-256), got {len(_raw)}",
+            code="INVALID_KEY_LENGTH",
+        )
+    return _raw
+
+
+__all__ = ["SecureClient"]