openenv-openshell 0.1.1__py3-none-any.whl

openenv_openshell/config.py

@@ -0,0 +1,249 @@
+"""Typed configuration for the OpenShell provider."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterator, Mapping, Sequence
+from copy import deepcopy
+from dataclasses import dataclass, field
+from math import isfinite
+from pathlib import Path
+from types import MappingProxyType
+from typing import TypeAlias
+
+from openenv_openshell._naming import MAX_SANDBOX_NAME_LENGTH
+
+Policy: TypeAlias = str | Path | Mapping[str, object] | None
+
+_MAX_SERVICE_NAME_LENGTH = 19
+_MAX_LABEL_KEY_LENGTH = 128
+_MAX_LABEL_VALUE_LENGTH = 256
+_MAX_PORT = 65535
+_NAME_PATTERN = re.compile(r"[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\Z")
+_LABEL_KEY_PATTERN = re.compile(r"[A-Za-z0-9](?:[A-Za-z0-9._/-]*[A-Za-z0-9])?\Z")
+_MEMORY_PATTERN = re.compile(r"(?P<amount>\d+(?:\.\d+)?)(?P<unit>[A-Za-z]+)?\Z")
+_SENSITIVE_LABEL_TERMS = frozenset(
+    {
+        "credential",
+        "credentials",
+        "password",
+        "passwd",
+        "prompt",
+        "secret",
+        "token",
+        "user-data",
+        "user_data",
+    }
+)
+_SENSITIVE_LABEL_PHRASES = ("api-key", "task-content", "user-data")
+
+
+class _PolicySnapshot(Mapping[str, object]):
+    """Read-only mapping whose nested values are detached on every read."""
+
+    def __init__(self, source: Mapping[str, object]) -> None:
+        """Capture caller input without changing its authored types."""
+        self._values = deepcopy(dict(source))
+
+    def __getitem__(self, key: str) -> object:
+        """Return a detached value so nested edits cannot change the snapshot."""
+        return deepcopy(self._values[key])
+
+    def __iter__(self) -> Iterator[str]:
+        """Iterate the captured keys."""
+        return iter(self._values)
+
+    def __len__(self) -> int:
+        """Return the number of captured fields."""
+        return len(self._values)
+
+
+def _validate_name(value: str, *, field_name: str, max_length: int) -> None:
+    if not value:
+        msg = f"{field_name} must not be empty"
+        raise ValueError(msg)
+    if len(value) > max_length or _NAME_PATTERN.fullmatch(value) is None:
+        msg = (
+            f"{field_name} must be at most {max_length} lowercase letters, "
+            "digits, or hyphens, and must start and end with a letter or digit"
+        )
+        raise ValueError(msg)
+
+
+def _validate_service_name(value: str) -> None:
+    # OpenShell 0.1.2 grpc/service.rs permits the unnamed exposure, otherwise
+    # applies MAX_ROUTABLE_NAME_LEN, forbids '--', and requires is_dns_label.
+    if value == "":
+        return
+    if (
+        len(value) > _MAX_SERVICE_NAME_LENGTH
+        or _NAME_PATTERN.fullmatch(value) is None
+        or "--" in value
+    ):
+        msg = (
+            f"service_name must be empty or at most {_MAX_SERVICE_NAME_LENGTH} "
+            "lowercase letters, digits, or hyphens, start and end with a letter "
+            "or digit, and contain no consecutive hyphens"
+        )
+        raise ValueError(msg)
+
+
+def _validate_positive_number(value: float, *, field_name: str) -> None:
+    if isinstance(value, bool) or not isfinite(value) or value <= 0:
+        msg = f"{field_name} must be a positive finite number"
+        raise ValueError(msg)
+
+
+def _validate_labels(labels: Mapping[str, str]) -> None:
+    for key, value in labels.items():
+        if not isinstance(key, str) or not isinstance(value, str):  # pyright: ignore[reportUnnecessaryIsInstance]
+            msg = "labels must contain only string keys and values"
+            raise TypeError(msg)
+        if (
+            len(key) > _MAX_LABEL_KEY_LENGTH
+            or _LABEL_KEY_PATTERN.fullmatch(key) is None
+        ):
+            msg = f"invalid label key: {key!r}"
+            raise ValueError(msg)
+        normalized_key = key.casefold().replace("_", "-")
+        normalized_parts = set(re.split(r"[-./]", normalized_key))
+        if normalized_parts & _SENSITIVE_LABEL_TERMS or any(
+            phrase in normalized_key for phrase in _SENSITIVE_LABEL_PHRASES
+        ):
+            msg = f"label key must not identify sensitive or private data: {key!r}"
+            raise ValueError(msg)
+        if len(value) > _MAX_LABEL_VALUE_LENGTH or any(
+            character.isspace() and character != " " for character in value
+        ):
+            msg = f"invalid label value for {key!r}"
+            raise ValueError(msg)
+
+
+def validate_command(command: Sequence[str] | None) -> tuple[str, ...]:
+    """Require exact argv without exposing command contents in errors."""
+    if command is None:
+        msg = "OpenShell 0.1.2 requires explicit command argv; configure command"
+        raise ValueError(msg)
+    if isinstance(command, (str, bytes)) or not isinstance(command, Sequence):  # pyright: ignore[reportUnnecessaryIsInstance] - Validate untyped callers.
+        msg = "command must be a non-empty sequence of string arguments"
+        raise TypeError(msg)
+    argv = tuple(command)
+    if (
+        not argv
+        or any(not isinstance(arg, str) or "\x00" in arg for arg in argv)  # pyright: ignore[reportUnnecessaryIsInstance]
+        or not argv[0].strip()
+    ):
+        msg = "command requires a non-empty executable and NUL-free string arguments"
+        raise ValueError(msg)
+    return argv
+
+
+@dataclass(frozen=True, slots=True)
+class OpenShellResources:
+    """Resource requests passed through to OpenShell."""
+
+    cpu: float | None = None
+    memory: str | None = None
+    gpu_count: int | None = None
+
+    def __post_init__(self) -> None:
+        """Reject resource requests that cannot represent positive capacity."""
+        if self.cpu is not None:
+            _validate_positive_number(self.cpu, field_name="resources.cpu")
+        if self.memory is not None:
+            match = _MEMORY_PATTERN.fullmatch(self.memory)
+            if match is None or float(match.group("amount")) <= 0:
+                msg = "resources.memory must be a positive quantity"
+                raise ValueError(msg)
+        if self.gpu_count is not None and (
+            isinstance(self.gpu_count, bool)
+            or not isinstance(self.gpu_count, int)  # pyright: ignore[reportUnnecessaryIsInstance]
+            or self.gpu_count <= 0
+        ):
+            msg = "resources.gpu_count must be a positive integer"
+            raise ValueError(msg)
+
+
+@dataclass(frozen=True, slots=True)
+class OpenShellProviderConfig:
+    """Immutable provider settings shared by lifecycle components."""
+
+    workspace: str = "default"
+    sandbox_name: str | None = None
+    policy: Policy = None
+    command: Sequence[str] | None = field(default=None, repr=False)
+    service_port: int = 8000
+    service_name: str = ""
+    startup_timeout_s: float = 120.0
+    deletion_timeout_s: float = 60.0
+    health_poll_interval_s: float = 0.5
+    health_request_timeout_s: float = 2.0
+    gateway: str | None = None
+    keep_sandbox: bool = False
+    restricted_alpha_cleanup_acknowledged: bool = False
+    labels: Mapping[str, str] = field(default_factory=dict[str, str])
+    providers: Sequence[str] = field(default_factory=tuple[str, ...])
+    resources: OpenShellResources | None = None
+
+    def __post_init__(self) -> None:
+        """Validate settings and detach mutable values supplied by callers."""
+        if self.command is not None:
+            object.__setattr__(self, "command", validate_command(self.command))
+        if not self.workspace.strip():
+            msg = "workspace must not be empty"
+            raise ValueError(msg)
+        if self.sandbox_name is not None:
+            _validate_name(
+                self.sandbox_name,
+                field_name="sandbox_name",
+                max_length=MAX_SANDBOX_NAME_LENGTH,
+            )
+        _validate_service_name(self.service_name)
+        if (
+            isinstance(self.service_port, bool)
+            or not isinstance(self.service_port, int)  # pyright: ignore[reportUnnecessaryIsInstance]
+            or self.service_port < 1
+            or self.service_port > _MAX_PORT
+        ):
+            msg = f"service_port must be an integer from 1 through {_MAX_PORT}"
+            raise ValueError(msg)
+        _validate_positive_number(
+            self.startup_timeout_s, field_name="startup_timeout_s"
+        )
+        _validate_positive_number(
+            self.deletion_timeout_s, field_name="deletion_timeout_s"
+        )
+        _validate_positive_number(
+            self.health_poll_interval_s, field_name="health_poll_interval_s"
+        )
+        _validate_positive_number(
+            self.health_request_timeout_s, field_name="health_request_timeout_s"
+        )
+        if self.gateway is not None and not self.gateway.strip():
+            msg = "gateway must not be empty"
+            raise ValueError(msg)
+        if not isinstance(  # pyright: ignore[reportUnnecessaryIsInstance] - Validate untyped callers.
+            self.restricted_alpha_cleanup_acknowledged, bool
+        ):
+            msg = "restricted_alpha_cleanup_acknowledged must be a boolean"
+            raise TypeError(msg)
+
+        labels = dict(self.labels)
+        _validate_labels(labels)
+        object.__setattr__(self, "labels", MappingProxyType(labels))
+
+        if isinstance(self.providers, str):
+            msg = "providers must be a sequence of provider names"
+            raise TypeError(msg)
+        providers = tuple(self.providers)
+        if any(
+            not isinstance(provider, str)  # pyright: ignore[reportUnnecessaryIsInstance]
+            or not provider.strip()
+            for provider in providers
+        ):
+            msg = "providers must contain non-empty strings"
+            raise ValueError(msg)
+        object.__setattr__(self, "providers", providers)
+
+        if isinstance(self.policy, Mapping):
+            object.__setattr__(self, "policy", _PolicySnapshot(self.policy))

openenv_openshell/errors.py

@@ -0,0 +1,37 @@
+"""Provider-specific exceptions with stable public meanings."""
+
+
+class OpenShellProviderError(RuntimeError):
+    """Base class for provider failures."""
+
+
+class OpenShellConnectionError(OpenShellProviderError):
+    """Raised when the provider cannot communicate with OpenShell."""
+
+
+class SandboxCreationError(OpenShellProviderError):
+    """Raised when sandbox creation fails."""
+
+
+class SandboxReadinessError(OpenShellProviderError):
+    """Raised when an OpenShell sandbox does not become ready."""
+
+
+class OpenEnvReadinessTimeout(OpenShellProviderError):  # noqa: N818
+    """Raised when the OpenEnv health endpoint does not become ready."""
+
+
+class ServiceAccessError(OpenShellProviderError):
+    """Raised when TLS rejects access the OpenEnv client cannot provide.
+
+    Examples are an untrusted route certificate or a required TLS client
+    certificate. Retrying cannot help.
+    """
+
+
+class SandboxDeletionError(OpenShellProviderError):
+    """Raised when an owned sandbox cannot be deleted."""
+
+
+class PolicyConfigurationError(OpenShellProviderError):
+    """Raised when an explicit policy cannot be loaded or validated."""

openenv_openshell/metadata.py

@@ -0,0 +1,50 @@
+"""Lifecycle state and audit metadata models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib.metadata import PackageNotFoundError, version
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+
+@dataclass(slots=True)
+class ProviderState:
+    """Mutable state for the provider's single owned sandbox."""
+
+    sandbox_name: str | None = None
+    sandbox_id: str | None = None
+    image: str | None = None
+    base_url: str | None = None
+    created: bool = False
+    ready: bool = False
+    deleted: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class OpenShellRunMetadata:
+    """Non-secret provenance for one OpenEnv run."""
+
+    sandbox_name: str
+    sandbox_id: str | None
+    workspace: str
+    image: str
+    service_url: str
+    policy_digest: str | None
+    created_at: datetime
+
+    openenv_provider_version: str | None = None
+    openshell_version: str | None = None
+    openenv_version: str | None = None
+    ready_at: datetime | None = None
+    deleted_at: datetime | None = None
+
+
+def package_version(distribution: str) -> str | None:
+    """Read installed distribution provenance without importing runtime SDKs."""
+    try:
+        return version(distribution)
+    except PackageNotFoundError:
+        return None

openenv_openshell/policy.py

@@ -0,0 +1,108 @@
+"""Fail-closed loading of explicit policies without gateway access."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from hashlib import sha256
+from pathlib import Path
+from typing import TYPE_CHECKING, cast
+
+import yaml
+
+from openenv_openshell._adapter import ensure_sdk
+from openenv_openshell.errors import PolicyConfigurationError
+
+_INVALID = "Invalid explicit policy; use supported OpenShell 0.1.2 policy fields."
+_MAX_BYTES = 1024 * 1024
+_MAX_DEPTH = 64
+
+if TYPE_CHECKING:
+    from collections.abc import Hashable, Iterator
+
+    from yaml.events import Event
+    from yaml.nodes import MappingNode
+
+
+def policy_digest(policy: Mapping[str, object]) -> str:
+    """Hash normalized SDK fields as sorted, compact UTF-8 JSON.
+
+    Preserve list order; only mapping order and authored schema spellings are
+    normalized. The caller must pass the validated output of load_policy.
+    """
+    canonical = json.dumps(
+        dict(policy), sort_keys=True, separators=(",", ":"), ensure_ascii=False
+    ).encode("utf-8")
+    return sha256(canonical).hexdigest()
+
+
+class _PolicyLoader(yaml.SafeLoader):
+    """Reject duplicate keys and merge keys instead of silently overriding."""
+
+    def construct_mapping(
+        self,
+        node: MappingNode,
+        deep: bool = False,  # noqa: FBT001, FBT002 - PyYAML override.
+    ) -> dict[Hashable, object]:
+        keys: set[str] = set()
+        for key_node, _ in node.value:
+            key: object = self.construct_object(key_node, deep=deep)  # pyright: ignore[reportUnknownMemberType] - PyYAML stub lacks node type.
+            if not isinstance(key, str) or key in keys or key == "<<":
+                raise PolicyConfigurationError(_INVALID)
+            keys.add(key)
+        return cast("dict[Hashable, object]", super().construct_mapping(node, deep))
+
+
+def _detach(value: object, depth: int = 0) -> object:
+    if depth > _MAX_DEPTH:
+        raise PolicyConfigurationError(_INVALID)
+    if isinstance(value, Mapping):
+        result: dict[str, object] = {}
+        for key, child in cast("Mapping[object, object]", value).items():
+            if not isinstance(key, str):
+                raise PolicyConfigurationError(_INVALID)
+            result[key] = _detach(child, depth + 1)
+        return dict(sorted(result.items()))
+    if isinstance(value, list):
+        return [_detach(child, depth + 1) for child in cast("list[object]", value)]
+    if isinstance(value, (str, bool, int)):
+        return value
+    raise PolicyConfigurationError(_INVALID)
+
+
+def load_policy(source: object) -> dict[str, object]:
+    """Load a YAML path or mapping and return detached normalized SDK fields.
+
+    None is not an explicit policy. Image/default policy selection belongs to
+    the caller and must never be used to recover from an explicit-policy error.
+    """
+    try:
+        if isinstance(source, (str, Path)):
+            with Path(source).open("rb") as stream:
+                data = stream.read(_MAX_BYTES + 1)
+            if len(data) > _MAX_BYTES:
+                raise PolicyConfigurationError(_INVALID)
+            # Reject aliases/anchors: no recursive or exponentially expanded YAML.
+            events = cast("Iterator[Event]", yaml.parse(data))  # pyright: ignore[reportUnknownMemberType] - PyYAML parse return is untyped.
+            for event in events:
+                if getattr(event, "anchor", None) is not None:
+                    raise PolicyConfigurationError(_INVALID)
+            source = yaml.load(data, Loader=_PolicyLoader)  # noqa: S506 - SafeLoader subclass.
+        detached = _detach(source)
+        if not isinstance(detached, dict):
+            raise PolicyConfigurationError(_INVALID)
+        policy = cast("dict[str, object]", detached)
+        if type(policy.get("version")) is not int or policy["version"] != 1:
+            raise PolicyConfigurationError(_INVALID)
+        if "filesystem_policy" in policy:
+            if "filesystem" in policy:
+                raise PolicyConfigurationError(_INVALID)
+            policy["filesystem"] = policy.pop("filesystem_policy")
+        ensure_sdk()
+        from openenv_openshell._sdk import (  # noqa: PLC0415 - Guarded lazy model boundary.
+            normalize_policy,
+        )
+
+        return cast("dict[str, object]", _detach(normalize_policy(policy)))
+    except (OSError, UnicodeError, yaml.YAMLError, RecursionError):
+        raise PolicyConfigurationError(_INVALID) from None