pyvorin-thin 1.0.9__py3-none-any.whl

pyvorin_thin/__init__.py

@@ -0,0 +1,124 @@
+"""
+Pyvorin Thin Client v1
+
+Safe thin-client path for licensing, signed-artifact delivery, usage tracking,
+and workload scanning.  The compiler is **not** shipped here: the thin client
+activates a licence, obtains a customer/device-bound ``.pyvpkg``, verifies and
+decrypts it, and loads the protected core through a single
+``ProtectedCoreLoader``.  Compilation happens locally on the customer's device;
+customer source is never uploaded.
+
+The public surface is a small, stable set of names (below).  Everything else
+in the package is internal and may change without notice.
+
+Typical use::
+
+    from pyvorin_thin import ThinCoreClient, ProtectedCoreLoader
+    from pyvorin_thin import resolve_runtime_artifact, format_error
+"""
+
+__version__ = '1.0.9'
+__experimental__ = False
+
+from .errors import (
+    PVL000_UNKNOWN,
+    ActivationError,
+    ConfigurationError,
+    EntitlementError,
+    InstallError,
+    IntegrityError,
+    PlatformUnsupportedError,
+    PythonIncompatibleError,
+    SelfTestError,
+    ThinClientError,
+    TransportError,
+    code_for,
+    format_error,
+)
+from .runtime_resolver import (
+    RuntimeRequirement,
+    current_requirement,
+    platform_tag,
+    python_tag,
+    resolve_artifact as resolve_runtime_artifact,
+)
+from .install_identity import (
+    Entitlement,
+    InstallationIdentity,
+    binding_digest,
+    device_fingerprint,
+)
+from .pinned_keys import default_pinned_keys
+from .protected_core_loader import (
+    CoreLoadError,
+    CoreManifest,
+    CoreTrustError,
+    LoadedCore,
+    PinnedKeys,
+    ProtectedCoreLoader,
+    SignatureVerifier,
+    compute_merkle_root,
+)
+from .core_installer import CoreInstaller, InstalledCore, PackageBindingError
+from .core_client import ThinCoreClient
+from .offline import (
+    OfflineLicense,
+    OfflineRequest,
+    generate_request,
+    load_stored_licence,
+    store_licence,
+    version_satisfies,
+)
+from .offline_import import OfflineImporter, OfflineImportResult
+
+__all__ = [
+    "__version__",
+    "__experimental__",
+    # error model
+    "ThinClientError",
+    "TransportError",
+    "EntitlementError",
+    "ActivationError",
+    "PythonIncompatibleError",
+    "PlatformUnsupportedError",
+    "IntegrityError",
+    "InstallError",
+    "SelfTestError",
+    "ConfigurationError",
+    "PVL000_UNKNOWN",
+    "code_for",
+    "format_error",
+    # runtime resolution
+    "RuntimeRequirement",
+    "current_requirement",
+    "platform_tag",
+    "python_tag",
+    "resolve_runtime_artifact",
+    # protected core: identity, trust and load
+    "InstallationIdentity",
+    "Entitlement",
+    "binding_digest",
+    "device_fingerprint",
+    "default_pinned_keys",
+    "PinnedKeys",
+    "SignatureVerifier",
+    "CoreManifest",
+    "CoreTrustError",
+    "CoreLoadError",
+    "ProtectedCoreLoader",
+    "LoadedCore",
+    "compute_merkle_root",
+    "CoreInstaller",
+    "InstalledCore",
+    "PackageBindingError",
+    "ThinCoreClient",
+    # enterprise offline (air-gap) flow
+    "OfflineRequest",
+    "OfflineLicense",
+    "OfflineImporter",
+    "OfflineImportResult",
+    "generate_request",
+    "load_stored_licence",
+    "store_licence",
+    "version_satisfies",
+]

pyvorin_thin/artifact_cache.py

@@ -0,0 +1,107 @@
+"""
+Local artifact cache for compiled .so files.
+
+Keys artifacts by source hash so repeated runs of the same function
+never recompile. Each cache entry stores:
+  - {hash}.so      : the compiled shared library
+  - {hash}.json    : metadata (function name, signature, artifact_id, backend)
+
+Cache directory: ~/.pyvorin/artifact_cache/
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import pathlib
+from typing import Any, Callable, Optional
+
+logger = logging.getLogger(__name__)
+
+
+def _default_cache_dir() -> pathlib.Path:
+    if os.name == "nt":
+        appdata = os.environ.get("LOCALAPPDATA") or os.environ.get("APPDATA")
+        if appdata:
+            return pathlib.Path(appdata) / "Pyvorin" / "artifact_cache"
+    return pathlib.Path.home() / ".pyvorin" / "artifact_cache"
+
+
+class ArtifactCache:
+    """Disk-backed cache for compiled artifacts."""
+
+    def __init__(self, cache_dir: Optional[pathlib.Path] = None):
+        self.cache_dir = cache_dir or _default_cache_dir()
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+    def _so_path(self, source_hash: str) -> pathlib.Path:
+        return self.cache_dir / f"{source_hash}.so"
+
+    def _meta_path(self, source_hash: str) -> pathlib.Path:
+        return self.cache_dir / f"{source_hash}.json"
+
+    def get(self, source_hash: str) -> Optional[tuple[pathlib.Path, dict]]:
+        """Return (so_path, metadata) if cached, else None."""
+        so_path = self._so_path(source_hash)
+        meta_path = self._meta_path(source_hash)
+        if not so_path.exists() or not meta_path.exists():
+            return None
+        try:
+            meta = json.loads(meta_path.read_text(encoding="utf-8"))
+            return so_path, meta
+        except Exception as exc:
+            logger.warning("Corrupt cache entry for %s: %s", source_hash[:16], exc)
+            self._remove(source_hash)
+            return None
+
+    def put(
+        self,
+        source_hash: str,
+        artifact_bytes: bytes,
+        metadata: dict,
+    ) -> pathlib.Path:
+        """Store artifact bytes and metadata. Returns path to .so."""
+        so_path = self._so_path(source_hash)
+        meta_path = self._meta_path(source_hash)
+        so_path.write_bytes(artifact_bytes)
+        meta_path.write_text(json.dumps(metadata, indent=2), encoding="utf-8")
+        logger.info("Cached artifact %s (%d bytes)", source_hash[:16], len(artifact_bytes))
+        return so_path
+
+    def remove(self, source_hash: str) -> None:
+        """Remove a cached entry."""
+        self._remove(source_hash)
+
+    def _remove(self, source_hash: str) -> None:
+        for p in (self._so_path(source_hash), self._meta_path(source_hash)):
+            try:
+                p.unlink(missing_ok=True)
+            except OSError:
+                pass
+
+    def clear(self) -> int:
+        """Remove all cached artifacts. Returns count removed."""
+        count = 0
+        for p in self.cache_dir.glob("*"):
+            try:
+                p.unlink()
+                count += 1
+            except OSError:
+                pass
+        logger.info("Cleared %d artifact cache entries", count)
+        return count
+
+    def list_entries(self) -> list[dict]:
+        """List all cached entries with metadata."""
+        entries = []
+        for meta_path in sorted(self.cache_dir.glob("*.json")):
+            try:
+                meta = json.loads(meta_path.read_text(encoding="utf-8"))
+                so_path = meta_path.with_suffix(".so")
+                meta["_so_exists"] = so_path.exists()
+                meta["_so_size"] = so_path.stat().st_size if so_path.exists() else 0
+                entries.append(meta)
+            except OSError:
+                pass
+        return entries

pyvorin_thin/artifact_crypto.py

@@ -0,0 +1,109 @@
+"""
+Encrypted protected-artifact envelope for the Pyvorin thin client.
+
+Protected release artifacts (.so compiled kernels, wheels, bundles) are
+stored on the platform encrypted with AES-256-GCM.  Only an activated
+device that completes the license-gated download handshake receives the
+per-release decryption key, so copied artifact files are unusable on
+their own.
+
+Envelope layout (all integers big-endian)::
+
+    0  .. 6   magic   b"PYVENC1"
+    7  .. 8   key_id  uint16  (server key-ring slot, enables rotation)
+    9  .. 20  nonce   12 bytes
+    21 .. end ciphertext || 16-byte GCM authentication tag
+
+The module is intentionally self-contained (no pyvorin.compiler imports)
+so the standalone ``pyvorin_thin`` wheel can use it with only the
+``cryptography`` package as a dependency.
+"""
+
+from __future__ import annotations
+
+from .errors import IntegrityError
+
+import os
+import struct
+
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+MAGIC = b"PYVENC1"
+_HEADER_LEN = len(MAGIC) + 2
+_NONCE_LEN = 12
+_TAG_LEN = 16
+KEY_LEN = 32
+
+
+class ArtifactCryptoError(IntegrityError):
+    """Raised when an encrypted artifact cannot be decrypted or verified."""
+
+
+def payload_key_id(data: bytes) -> int:
+    """Return the key-ring id embedded in an encrypted payload."""
+    if len(data) < _HEADER_LEN or not is_encrypted_payload(data):
+        raise ArtifactCryptoError("Not an encrypted Pyvorin artifact payload")
+    return struct.unpack(">H", data[len(MAGIC):_HEADER_LEN])[0]
+
+
+def is_encrypted_payload(data: bytes) -> bool:
+    """Return True if *data* starts with the PYVENC1 envelope magic."""
+    return bool(data) and data[:len(MAGIC)] == MAGIC
+
+
+def encrypt_payload(plaintext: bytes, key: bytes, key_id: int = 1) -> bytes:
+    """Encrypt *plaintext* into a self-describing protected-artifact envelope.
+
+    Args:
+        plaintext: Raw artifact bytes (e.g. a compiled ``.so``).
+        key: 32-byte AES-256 key.
+        key_id: Server key-ring slot recorded in the envelope header.
+
+    Returns:
+        ``MAGIC || key_id || nonce || ciphertext || tag``.
+    """
+    if len(key) != KEY_LEN:
+        raise ArtifactCryptoError(f"Artifact encryption key must be {KEY_LEN} bytes, got {len(key)}")
+    if not 0 <= key_id <= 0xFFFF:
+        raise ArtifactCryptoError(f"key_id out of range: {key_id}")
+    nonce = os.urandom(_NONCE_LEN)
+    ct_with_tag = AESGCM(key).encrypt(nonce, plaintext, None)
+    return MAGIC + struct.pack(">H", key_id) + nonce + ct_with_tag
+
+
+def decrypt_payload(data: bytes, key: bytes) -> bytes:
+    """Decrypt and authenticate a PYVENC1 envelope.
+
+    Raises:
+        ArtifactCryptoError: If the payload is malformed, tampered with, or
+            the key does not match.
+    """
+    if not is_encrypted_payload(data):
+        raise ArtifactCryptoError("Not an encrypted Pyvorin artifact payload")
+    if len(key) != KEY_LEN:
+        raise ArtifactCryptoError(f"Artifact decryption key must be {KEY_LEN} bytes, got {len(key)}")
+    body = data[_HEADER_LEN:]
+    if len(body) < _NONCE_LEN + _TAG_LEN:
+        raise ArtifactCryptoError("Encrypted artifact truncated (nonce/tag missing)")
+    nonce = body[:_NONCE_LEN]
+    ct_with_tag = body[_NONCE_LEN:]
+    try:
+        return AESGCM(key).decrypt(nonce, ct_with_tag, None)
+    except Exception as exc:
+        raise ArtifactCryptoError(
+            "Artifact decryption failed: tampered data or wrong key"
+        ) from exc
+
+
+def decode_key(key_b64: str) -> bytes:
+    """Decode a base64-encoded key from a download response."""
+    import base64
+    import binascii
+
+    try:
+        key = base64.b64decode(key_b64.strip(), validate=True)
+    except (binascii.Error, ValueError) as exc:
+        raise ArtifactCryptoError("Invalid base64 artifact key in download response") from exc
+    if len(key) != KEY_LEN:
+        raise ArtifactCryptoError(f"Decoded artifact key must be {KEY_LEN} bytes, got {len(key)}")
+    return key

pyvorin_thin/artifact_executor.py

@@ -0,0 +1,325 @@
+"""
+Artifact executor — load a compiled .so and create a Python callable.
+
+.. deprecated::
+    This is a low-level helper for compiled *kernel* objects.  It is **not**
+    a route into the protected compiler core: that path is owned solely by
+    :class:`pyvorin_thin.protected_core_loader.ProtectedCoreLoader`, which
+    verifies the manifest/Merkle chain and the entitlement binding before any
+    core byte is executed.  Kept for compiled-kernel call sites and their
+    existing tests; new code must use ``ProtectedCoreLoader``.
+
+Infers function signature from source AST when possible, then binds
+the C function with ctypes. Falls back gracefully when the signature
+cannot be determined or the .so cannot be loaded.
+"""
+
+from __future__ import annotations
+
+import ast
+import ctypes
+import json
+import logging
+import os
+import pathlib
+import sys
+from typing import Any, Callable, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+
+def _resolve_type(annotation: Optional[ast.AST]) -> type:
+    """Map a Python type annotation to a ctypes type."""
+    if annotation is None:
+        return ctypes.c_int64
+
+    # Handle ast.Name like 'int', 'float', 'str', 'bool'
+    if isinstance(annotation, ast.Name):
+        name = annotation.id
+        if name == "float":
+            return ctypes.c_double
+        if name == "str":
+            return ctypes.c_char_p
+        if name == "bool":
+            return ctypes.c_bool
+        return ctypes.c_int64
+
+    # Handle ast.Constant for Python 3.8+ style annotations
+    if isinstance(annotation, ast.Constant) and isinstance(annotation.value, str):
+        name = annotation.value
+        if name == "float":
+            return ctypes.c_double
+        if name == "str":
+            return ctypes.c_char_p
+        if name == "bool":
+            return ctypes.c_bool
+        return ctypes.c_int64
+
+    return ctypes.c_int64
+
+
+def infer_signature(
+    source: str,
+    function_name: str,
+) -> Optional[Tuple[int, List[type], type, bool]]:
+    """
+    Parse source and infer the C-compatible signature of *function_name*.
+
+    Returns (arg_count, arg_types, return_type, returns_bool) or None if
+    the function cannot be found.
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError as exc:
+        logger.warning("Cannot parse source for signature inference: %s", exc)
+        return None
+
+    for node in tree.body:
+        if isinstance(node, ast.FunctionDef) and node.name == function_name:
+            arg_types = [_resolve_type(arg.annotation) for arg in node.args.args]
+            # Ignore *args and **kwargs for C binding
+            ret_type = _resolve_type(node.returns)
+            returns_bool = (
+                isinstance(node.returns, ast.Name) and node.returns.id == "bool"
+            ) or (
+                isinstance(node.returns, ast.Constant)
+                and isinstance(node.returns.value, str)
+                and node.returns.value == "bool"
+            )
+            return len(arg_types), arg_types, ret_type, returns_bool
+
+    # Try to find the first function if the named one isn't found
+    for node in tree.body:
+        if isinstance(node, ast.FunctionDef):
+            arg_types = [_resolve_type(arg.annotation) for arg in node.args.args]
+            ret_type = _resolve_type(node.returns)
+            returns_bool = (
+                isinstance(node.returns, ast.Name) and node.returns.id == "bool"
+            ) or (
+                isinstance(node.returns, ast.Constant)
+                and isinstance(node.returns.value, str)
+                and node.returns.value == "bool"
+            )
+            return len(arg_types), arg_types, ret_type, returns_bool
+
+    return None
+
+
+def _guess_first_function_name(source: str) -> Optional[str]:
+    """Return the name of the first top-level function in source."""
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return None
+    for node in tree.body:
+        if isinstance(node, ast.FunctionDef):
+            return node.name
+    return None
+
+
+def is_compat_artifact(artifact_bytes: bytes) -> bool:
+    """Return True if the artifact is a JSON compat-mode metadata file."""
+    if not artifact_bytes:
+        return False
+    first = artifact_bytes[0:1]
+    return first == b"{" or first == b"["
+
+
+def _exec_safe_tmp_dir() -> pathlib.Path:
+    """Return a temp dir that allows exec (some systems mount /tmp noexec).
+
+    Prefers ``$TMPDIR``/``$PYVORIN_TMPDIR`` when set, then ``~/.pyvorin/tmp``.
+    The dir is created 0700 on first use.
+    """
+    cand = os.environ.get("PYVORIN_TMPDIR") or os.environ.get("TMPDIR") or ""
+    if cand:
+        p = pathlib.Path(cand)
+        try:
+            p.mkdir(parents=True, exist_ok=True)
+            return p
+        except OSError:
+            pass
+    p = pathlib.Path.home() / ".pyvorin" / "tmp"
+    p.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(p, 0o700)
+    except OSError:
+        pass
+    return p
+
+
+def _write_temp_so(data: bytes) -> pathlib.Path:
+    """Write artifact bytes to a temp .so and restrict permissions.
+
+    The file is created in an exec-safe directory (never a noexec /tmp),
+    mode 0600.  The caller owns cleanup (``unlink`` after ``ctypes.CDLL``
+    is safe on Linux: the mapped inode survives unlink).
+    """
+    import tempfile
+    with tempfile.NamedTemporaryFile(suffix=".so", delete=False, dir=_exec_safe_tmp_dir()) as tmp:
+        tmp.write(data)
+        tmp_path = pathlib.Path(tmp.name)
+    try:
+        os.chmod(tmp_path, 0o600)
+    except OSError:
+        pass
+    return tmp_path
+
+
+def load_artifact(
+    so_path: pathlib.Path,
+    function_name: str,
+    arg_types: Optional[List[type]] = None,
+    return_type: Optional[type] = None,
+    returns_bool: bool = False,
+    decryption_key: Optional[bytes] = None,
+) -> Callable:
+    """
+    Load a .so and return a callable that invokes the compiled function.
+
+    Args:
+        so_path: Path to the shared library.
+        function_name: C symbol name to call.
+        arg_types: ctypes types for each argument (defaults to [c_int64, ...]).
+        return_type: ctypes return type (defaults to c_int64).
+        returns_bool: If True, convert 0/1 result to Python bool.
+        decryption_key: 32-byte AES-256 key.  When the file is a PYVENC1
+            protected envelope it is decrypted to a 0600 temp file that is
+            unlinked immediately after ``dlopen``; the plaintext exists
+            only as an anonymous in-memory mapping.
+
+    Raises:
+        OSError: If the .so cannot be loaded.
+        AttributeError: If the symbol is not found.
+        ArtifactCryptoError: If the envelope is tampered or the key is wrong.
+    """
+    from .artifact_crypto import decrypt_payload, is_encrypted_payload
+
+    data = pathlib.Path(so_path).read_bytes()
+    _encrypted = is_encrypted_payload(data)
+    if _encrypted:
+        if decryption_key is None:
+            raise RuntimeError(
+                f"{so_path} is an encrypted protected artifact; a decryption key "
+                "from the license-gated download response is required"
+            )
+        data = decrypt_payload(data, decryption_key)
+        # Decrypted plaintext: transient temp file, unlinked right after load.
+        eff_path = _write_temp_so(data)
+        unlink_after_load = True
+    else:
+        eff_path = pathlib.Path(so_path)
+        unlink_after_load = False
+
+    lib = ctypes.CDLL(str(eff_path))
+    if unlink_after_load:
+        try:
+            eff_path.unlink()
+        except OSError:
+            pass
+    cfunc = getattr(lib, function_name)
+
+    effective_argtypes = arg_types or [ctypes.c_int64]
+    effective_restype = return_type or ctypes.c_int64
+
+    cfunc.argtypes = effective_argtypes
+    cfunc.restype = effective_restype
+
+    def wrapper(*args):
+        # Convert str args to bytes for c_char_p
+        converted = []
+        for arg, atype in zip(args, effective_argtypes):
+            if atype is ctypes.c_char_p and isinstance(arg, str):
+                converted.append(arg.encode("utf-8"))
+            else:
+                converted.append(arg)
+        # Pad with defaults if too few args provided
+        while len(converted) < len(effective_argtypes):
+            converted.append(0)
+        # Trim if too many
+        converted = converted[: len(effective_argtypes)]
+        result = cfunc(*converted)
+        if returns_bool:
+            return bool(result)
+        # Decode bytes to str for c_char_p return
+        if effective_restype is ctypes.c_char_p and isinstance(result, bytes):
+            return result.decode("utf-8")
+        return result
+
+    wrapper._lib = lib
+    wrapper._so_path = str(so_path)
+    wrapper._function_name = function_name
+    return wrapper
+
+
+def execute_artifact(
+    artifact_bytes: bytes,
+    function_name: str,
+    source: str,
+    *args: Any,
+    decryption_key: Optional[bytes] = None,
+) -> Any:
+    """
+    High-level helper: write bytes to a temp .so, infer signature, load, and call.
+
+    If the bytes are a PYVENC1 encrypted envelope, *decryption_key* (32-byte
+    AES-256, from the license-gated download response) is required; the
+    decrypted plaintext temp file is unlinked immediately after dlopen.
+
+    Returns the function result. Raises on failure so the caller can fall back.
+    """
+    from .artifact_crypto import decrypt_payload, is_encrypted_payload
+
+    if is_encrypted_payload(artifact_bytes):
+        if decryption_key is None:
+            raise RuntimeError(
+                "Encrypted protected artifact requires a decryption key from "
+                "the download response"
+            )
+        artifact_bytes = decrypt_payload(artifact_bytes, decryption_key)
+
+    if is_compat_artifact(artifact_bytes):
+        meta = json.loads(artifact_bytes)
+        logger.info("Compat-mode artifact: %s", meta.get("function_name", "unknown"))
+        # For compat mode, we cannot execute the .so — caller should fall back to CPython
+        raise RuntimeError("Compat-mode artifact cannot be executed via ctypes")
+
+    # Write to a temporary .so
+    tmp_path = _write_temp_so(artifact_bytes)
+
+    try:
+        sig = infer_signature(source, function_name)
+        if sig is None:
+            # Fallback: guess function name and assume all-int signature
+            guessed = _guess_first_function_name(source)
+            if guessed:
+                function_name = guessed
+            sig = (len(args), [ctypes.c_int64] * max(len(args), 1), ctypes.c_int64, False)
+
+        arg_count, arg_types, return_type, returns_bool = sig
+        # If caller provided args, ensure arg_types length matches
+        if args and len(arg_types) < len(args):
+            arg_types = [ctypes.c_int64] * len(args)
+        if not args and arg_count == 0:
+            arg_types = []
+
+        wrapper = load_artifact(
+            tmp_path,
+            function_name,
+            arg_types=arg_types,
+            return_type=return_type,
+            returns_bool=returns_bool,
+        )
+        result = wrapper(*args)
+        # The plaintext temp .so can be unlinked as soon as the call chain
+        # has dlopen'd it (Linux keeps the inode mapped).
+        try:
+            tmp_path.unlink()
+        except OSError:
+            pass
+        return result
+    finally:
+        try:
+            tmp_path.unlink()
+        except OSError:
+            pass