cf-bootstrap-instance 0.1.8__py3-none-any.whl

cf_bootstrap_instance/model.py

@@ -0,0 +1,322 @@
+"""Strict instance apply protocol and canonical marker models."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import platform
+import sys
+from pathlib import Path
+import re
+from typing import Any
+
+REQUEST_SCHEMA = "cf.bootstrap.instance-apply.request.v1"
+RESULT_SCHEMA = "cf.bootstrap.instance-apply.result.v1"
+REQUEST_SCHEMA_V2 = "cf.bootstrap.instance-apply.request.v2"
+RESULT_SCHEMA_V2 = "cf.bootstrap.instance-apply.result.v2"
+PROTOCOL = "cf.bootstrap.instance-provider.v1"
+MARKER_SCHEMA = "cf.bootstrap.instance-marker.v1"
+MARKER_SCHEMA_V2 = "cf.bootstrap.instance-marker.v2"
+PLAN_SCHEMA = "cf.bootstrap.plan.v1"
+PLAN_SCHEMA_V2 = "cf.bootstrap.plan.v2"
+STAGES = ("validate-inputs", "select-artifact-source", "prepare-installation", "install-artifacts", "verify-installation", "handoff-to-service")
+_IDENTIFIER = re.compile(r"[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?\Z")
+_VERSION = re.compile(r"[0-9][A-Za-z0-9.!+_-]*\Z")
+_HEX = re.compile(r"[0-9a-f]{64}\Z")
+
+
+class InstanceError(ValueError):
+    def __init__(self, code: str, message: str, details: dict[str, object] | None = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.details = details or {}
+
+
+def canonical_json(value: object) -> bytes:
+    return (json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":")) + "\n").encode("utf-8")
+
+
+def digest(value: object) -> str:
+    return "sha256:" + hashlib.sha256(canonical_json(value)).hexdigest()
+
+
+def _absolute(value: object, label: str) -> Path:
+    if not isinstance(value, str) or not value or value != value.strip() or any(ord(char) < 32 for char in value) or ".." in Path(value).parts:
+        raise InstanceError("SCHEMA_INVALID", f"{label} is unsafe")
+    path = Path(value)
+    if not path.is_absolute() or path == Path(path.anchor):
+        raise InstanceError("SCHEMA_INVALID", f"{label} must be an absolute non-root path")
+    return path
+
+
+def _text(value: object, label: str, pattern: re.Pattern[str] | None = None) -> str:
+    if not isinstance(value, str) or not value or value != value.strip() or any(ord(char) < 32 or char.isspace() for char in value):
+        raise InstanceError("SCHEMA_INVALID", f"{label} must be a clean string")
+    if pattern is not None and not pattern.fullmatch(value):
+        raise InstanceError("SCHEMA_INVALID", f"{label} is invalid")
+    return value
+
+
+def normalize_distribution(value: str) -> str:
+    return re.sub(r"[-_.]+", "-", value).lower()
+
+
+def _native_wheel_tag() -> tuple[str, str]:
+    machine = platform.machine().lower()
+    if platform.system().lower() == "windows" and machine in {"amd64", "x86_64"}:
+        return "py3-none-win_amd64", ".exe"
+    if platform.system().lower() == "linux" and machine in {"amd64", "x86_64"}:
+        return "py3-none-manylinux_2_39_x86_64", ""
+    raise InstanceError("ARTIFACT_INVALID", "native artifact platform is unsupported")
+
+
+def _under(left: Path, right: Path) -> bool:
+    try:
+        left.resolve(strict=False).relative_to(right.resolve(strict=False))
+        return True
+    except ValueError:
+        return False
+
+
+def _validate_plan(plan: object) -> dict[str, Any]:
+    if isinstance(plan, dict) and plan.get("schema") == PLAN_SCHEMA_V2:
+        fields = {"schema", "instance_id", "installation_root", "cogniflow_home", "artifact_source", "profile", "stages"}
+        if set(plan) != fields or not isinstance(plan.get("profile"), str) or not re.fullmatch(r"[A-Za-z][A-Za-z0-9+.-]*:[^\s]+", plan["profile"]):
+            raise InstanceError("SCHEMA_INVALID", "v2 bootstrap plan fields are invalid")
+        checked = {key: value for key, value in plan.items() if key != "profile"} | {"schema": PLAN_SCHEMA}
+        _validate_plan(checked)
+        return plan
+    fields = {"schema", "instance_id", "installation_root", "cogniflow_home", "artifact_source", "stages"}
+    if not isinstance(plan, dict) or set(plan) != fields or plan.get("schema") != PLAN_SCHEMA:
+        raise InstanceError("SCHEMA_INVALID", "bootstrap plan fields are invalid")
+    instance_id = _text(plan.get("instance_id"), "instance_id", _IDENTIFIER)
+    if len(instance_id) > 64:
+        raise InstanceError("SCHEMA_INVALID", "instance_id is too long")
+    root = _absolute(plan.get("installation_root"), "installation_root")
+    home = _absolute(plan.get("cogniflow_home"), "cogniflow_home")
+    if _under(root, home) or _under(home, root):
+        raise InstanceError("ROOT_INVALID", "installation root and Cogniflow home must be disjoint")
+    source = plan.get("artifact_source")
+    if not isinstance(source, dict) or set(source) not in ({"mode", "checkout_path"}, {"mode", "package", "version"}):
+        raise InstanceError("SCHEMA_INVALID", "artifact source fields are invalid")
+    if source.get("mode") == "local-repository":
+        if set(source) != {"mode", "checkout_path"}:
+            raise InstanceError("SCHEMA_INVALID", "local source fields are invalid")
+        _absolute(source.get("checkout_path"), "checkout_path")
+    elif source.get("mode") == "pypi":
+        if set(source) != {"mode", "package", "version"}:
+            raise InstanceError("SCHEMA_INVALID", "PyPI source fields are invalid")
+        _text(source.get("package"), "package", _IDENTIFIER)
+        _text(source.get("version"), "version", _VERSION)
+    else:
+        raise InstanceError("SCHEMA_INVALID", "unsupported artifact source mode")
+    stages = plan.get("stages")
+    if not isinstance(stages, list) or len(stages) != len(STAGES):
+        raise InstanceError("SCHEMA_INVALID", "lifecycle stages are incomplete")
+    names: list[str] = []
+    for index, stage in enumerate(stages):
+        if not isinstance(stage, dict) or set(stage) != {"name", "ordinal", "handoff"} or stage.get("name") != STAGES[index] or stage.get("ordinal") != index or stage.get("handoff") is not (index == 5):
+            raise InstanceError("SCHEMA_INVALID", "lifecycle stages are not canonical")
+        names.append(stage["name"])
+    if len(set(names)) != len(names):
+        raise InstanceError("SCHEMA_INVALID", "lifecycle stages contain duplicates")
+    return plan
+
+
+def parse_request(value: object) -> tuple[dict[str, Any], dict[str, Any], Path]:
+    if isinstance(value, dict) and value.get("schema") == REQUEST_SCHEMA_V2:
+        return _parse_request_v2(value)
+    if not isinstance(value, dict) or set(value) != {"schema", "bootstrap_plan", "artifact_resolution"}:
+        raise InstanceError("SCHEMA_INVALID", "instance request fields are invalid")
+    if value["schema"] != REQUEST_SCHEMA:
+        raise InstanceError("SCHEMA_INVALID", "unsupported instance request schema")
+    plan = _validate_plan(value["bootstrap_plan"])
+    root = _absolute(plan.get("installation_root"), "installation_root")
+    home = _absolute(plan.get("cogniflow_home"), "cogniflow_home")
+    resolution = value["artifact_resolution"]
+    if not isinstance(resolution, dict) or set(resolution) not in ({"schema", "wheelhouse_path", "artifact_set"}, {"schema", "wheelhouse_path", "artifact_set", "lock_filename"}):
+        raise InstanceError("SCHEMA_INVALID", "artifact resolution is invalid")
+    wheelhouse = _absolute(resolution.get("wheelhouse_path"), "wheelhouse_path")
+    source_mode = plan["artifact_source"]["mode"]
+    if source_mode == "local-repository" and (_under(wheelhouse, Path(plan["artifact_source"]["checkout_path"])) or _under(Path(plan["artifact_source"]["checkout_path"]), wheelhouse)):
+        raise InstanceError("ROOT_INVALID", "wheelhouse and checkout must be disjoint")
+    if _under(wheelhouse, home) or _under(home, wheelhouse):
+        raise InstanceError("ROOT_INVALID", "wheelhouse and Cogniflow home must be disjoint")
+    resolution_schema = "cf.bootstrap.pypi-artifact-resolution.v1" if source_mode == "pypi" else "cf.bootstrap.local-artifact-resolution.v1"
+    artifact_schema = "cf.bootstrap.pypi-artifact-set.v1" if source_mode == "pypi" else "cf.bootstrap.artifact-set.v1"
+    required_resolution = {"schema", "wheelhouse_path", "artifact_set", "lock_filename"} if source_mode == "pypi" else {"schema", "wheelhouse_path", "artifact_set"}
+    if set(resolution) != required_resolution or resolution.get("schema") != resolution_schema:
+        raise InstanceError("SCHEMA_INVALID", "artifact resolution fields do not match source mode")
+    if source_mode == "pypi" and resolution.get("lock_filename") != "requirements.lock":
+        raise InstanceError("SCHEMA_INVALID", "PyPI lock filename is invalid")
+    artifact_set = resolution.get("artifact_set")
+    if not isinstance(artifact_set, dict) or artifact_set.get("schema") != artifact_schema or artifact_set.get("source_mode") != source_mode or not isinstance(artifact_set.get("artifacts"), list):
+        raise InstanceError("SCHEMA_INVALID", "artifact set is invalid")
+    expected_fields = {"schema", "source_mode", "root_requirement", "resolver", "target_environment", "resolution_digest", "lock_sha256", "artifacts"} if source_mode == "pypi" else {"schema", "source_mode", "source_digest", "index_digest", "artifacts"}
+    if set(artifact_set) != expected_fields:
+        raise InstanceError("SCHEMA_INVALID", "artifact set fields are invalid")
+    if source_mode == "pypi":
+        root_requirement = artifact_set["root_requirement"]
+        if not isinstance(root_requirement, dict) or set(root_requirement) != {"distribution", "normalized_distribution", "version"} or root_requirement["distribution"] != plan["artifact_source"]["package"] or root_requirement["version"] != plan["artifact_source"]["version"] or normalize_distribution(root_requirement["distribution"]) != root_requirement["normalized_distribution"]:
+            raise InstanceError("ARTIFACT_INVALID", "PyPI root requirement is not bound to the plan")
+        if not isinstance(artifact_set["resolution_digest"], str) or not artifact_set["resolution_digest"].startswith("sha256:") or not _HEX.fullmatch(artifact_set["resolution_digest"][7:]) or not isinstance(artifact_set["lock_sha256"], str) or not _HEX.fullmatch(artifact_set["lock_sha256"]):
+            raise InstanceError("ARTIFACT_INVALID", "PyPI digests are invalid")
+        environment = artifact_set["target_environment"]
+        environment_keys = {"implementation_name", "implementation_version", "os_name", "platform_machine", "platform_system", "python_full_version", "python_version", "platform_python_implementation", "sys_platform"}
+        if not isinstance(environment, dict) or set(environment) != environment_keys or any(not isinstance(item, str) or not item for item in environment.values()):
+            raise InstanceError("ARTIFACT_INVALID", "PyPI target environment is invalid")
+        resolver = artifact_set["resolver"]
+        if not isinstance(resolver, dict) or set(resolver) != {"pip_report_version", "pip_version"} or any(not isinstance(item, str) or not item for item in resolver.values()):
+            raise InstanceError("ARTIFACT_INVALID", "PyPI resolver metadata is invalid")
+    else:
+        for key in ("source_digest", "index_digest"):
+            if not isinstance(artifact_set[key], str) or not artifact_set[key].startswith("sha256:") or not _HEX.fullmatch(artifact_set[key][7:]):
+                raise InstanceError("ARTIFACT_INVALID", "Local source digest is invalid")
+    _validate_artifacts(artifact_set["artifacts"], source_mode)
+    return plan, resolution, root
+
+
+def _parse_request_v2(value: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any], Path]:
+    if set(value) != {"schema", "bootstrap_plan", "artifact_resolution"}:
+        raise InstanceError("SCHEMA_INVALID", "v2 instance request fields are invalid")
+    plan = _validate_plan(value["bootstrap_plan"])
+    root = _absolute(plan["installation_root"], "installation_root")
+    resolution = value["artifact_resolution"]
+    if not isinstance(resolution, dict) or set(resolution) != {"schema", "wheelhouse_path", "artifact_set"} or resolution.get("schema") != "cf.bootstrap.local-artifact-resolution.v2":
+        raise InstanceError("SCHEMA_INVALID", "v2 artifact resolution is invalid")
+    wheelhouse = _absolute(resolution["wheelhouse_path"], "wheelhouse_path")
+    checkout = _absolute(plan["artifact_source"].get("checkout_path"), "checkout_path") if plan["artifact_source"].get("mode") == "local-repository" else None
+    home = _absolute(plan["cogniflow_home"], "cogniflow_home")
+    if checkout is not None and (_under(wheelhouse, checkout) or _under(checkout, wheelhouse)):
+        raise InstanceError("ROOT_INVALID", "v2 wheelhouse and checkout must be disjoint")
+    if _under(wheelhouse, root) or _under(root, wheelhouse) or _under(wheelhouse, home) or _under(home, wheelhouse):
+        raise InstanceError("ROOT_INVALID", "v2 wheelhouse is not disjoint from protected roots")
+    if wheelhouse.exists() and (wheelhouse.is_symlink() or not wheelhouse.is_dir()):
+        raise InstanceError("ARTIFACT_INVALID", "v2 wheelhouse is not a regular directory")
+    artifact_set = resolution["artifact_set"]
+    fields = {"schema", "source_mode", "plan_digest", "profile", "profile_digest", "catalog_digest", "requested_capabilities", "post_install_verification_capability", "selected_roots", "selected_first_party", "selected_external", "selection_digest", "repository_source_digest", "selected_source_digest", "index_digest", "resolver", "target_environment", "artifacts"}
+    if not isinstance(artifact_set, dict) or set(artifact_set) != fields or artifact_set.get("schema") != "cf.bootstrap.artifact-set.v2" or artifact_set.get("source_mode") != "local-repository" or artifact_set.get("profile") != plan["profile"]:
+        raise InstanceError("SCHEMA_INVALID", "v2 artifact set is invalid")
+    for key in ("plan_digest", "profile_digest", "catalog_digest", "selection_digest", "repository_source_digest", "selected_source_digest", "index_digest"):
+        if not isinstance(artifact_set[key], str) or not _HEX.fullmatch(artifact_set[key].removeprefix("sha256:")):
+            raise InstanceError("ARTIFACT_INVALID", "v2 artifact set digest is invalid")
+    if artifact_set["plan_digest"] != digest(plan):
+        raise InstanceError("ARTIFACT_INVALID", "v2 plan digest does not match the supplied plan")
+    selection = {
+        "profile": artifact_set["profile"],
+        "profile_digest": artifact_set["profile_digest"],
+        "catalog_digest": artifact_set["catalog_digest"],
+        "requested_capabilities": artifact_set["requested_capabilities"],
+        "post_install_verification_capability": artifact_set["post_install_verification_capability"],
+        "provider_roots": artifact_set["selected_roots"],
+        "first_party_closure": artifact_set["selected_first_party"],
+        "external_requirements": artifact_set["selected_external"],
+        "target_environment": artifact_set["target_environment"],
+    }
+    if artifact_set["selection_digest"] != digest(selection):
+        raise InstanceError("ARTIFACT_INVALID", "v2 selection digest does not match the selection object")
+    _validate_v2_artifacts(artifact_set["artifacts"])
+    _validate_v2_selection(artifact_set)
+    return plan, resolution, root
+
+
+def _external_name(requirement: str) -> str:
+    return re.split(r"[<>=!;\s\[]", requirement, maxsplit=1)[0].replace("_", "-").lower()
+
+
+def _validate_v2_selection(artifact_set: dict[str, Any]) -> None:
+    local = {item["normalized_distribution"] for item in artifact_set["artifacts"] if item["source_kind"] == "stonecastle-local" and item.get("artifact_kind") != "native"}
+    external = {item["normalized_distribution"] for item in artifact_set["artifacts"] if item["source_kind"] == "external-wheelhouse"}
+    expected_external = {_external_name(value) for value in artifact_set["selected_external"]}
+    roots = set(artifact_set["selected_roots"])
+    if local != set(artifact_set["selected_first_party"]):
+        raise InstanceError("ARTIFACT_INVALID", "local artifacts do not match selected first-party closure")
+    if external != expected_external or not roots <= local:
+        raise InstanceError("ARTIFACT_INVALID", "artifact lists do not match v2 selection")
+    if any(item.startswith("cf-") for item in external):
+        raise InstanceError("EXTERNAL_SOURCE_FORBIDDEN", "external wheelhouse contains a cf-* artifact")
+    environment = artifact_set["target_environment"]
+    expected = {"implementation_name": "cpython", "python_full_version": platform.python_version(), "python_version": platform.python_version(), "sys_platform": sys.platform, "platform_system": platform.system(), "platform_machine": platform.machine().lower(), "platform_python_implementation": platform.python_implementation()}
+    if not isinstance(environment, dict) or any(environment.get(key) != value for key, value in expected.items()):
+        raise InstanceError("ARTIFACT_INVALID", "artifact target environment does not match active interpreter")
+
+
+def _validate_v2_artifacts(entries: object) -> None:
+    if not isinstance(entries, list) or not entries:
+        raise InstanceError("ARTIFACT_INVALID", "v2 artifact set is empty")
+    local_keys = {"distribution", "normalized_distribution", "version", "filename", "sha256", "size", "source_kind", "source_project"}
+    external_keys = local_keys - {"source_project"}
+    names: set[str] = set()
+    for item in entries:
+        native_keys = local_keys | {"artifact_kind", "wheel_tags", "executable"}
+        if not isinstance(item, dict) or set(item) not in (local_keys, external_keys, native_keys) or item["source_kind"] not in {"stonecastle-local", "external-wheelhouse"} or (item["source_kind"] == "stonecastle-local" and set(item) not in (local_keys, native_keys)) or (item["source_kind"] == "external-wheelhouse" and set(item) != external_keys) or not isinstance(item["sha256"], str) or not _HEX.fullmatch(item["sha256"]) or type(item["size"]) is not int or item["size"] < 0:
+            raise InstanceError("ARTIFACT_INVALID", "v2 artifact entry is invalid")
+        if item["normalized_distribution"] in names:
+            raise InstanceError("ARTIFACT_INVALID", "v2 artifact distributions are duplicated")
+        names.add(item["normalized_distribution"])
+    if entries != sorted(entries, key=lambda item: (item["normalized_distribution"], item["filename"])):
+        raise InstanceError("ARTIFACT_INVALID", "v2 artifact entries are not sorted")
+
+
+def _validate_artifacts(entries: object, mode: str) -> None:
+    if not isinstance(entries, list) or not entries:
+        raise InstanceError("ARTIFACT_INVALID", "artifact set is empty")
+    names: set[str] = set()
+    normalized_names: set[str] = set()
+    filenames: set[str] = set()
+    base_expected = {"distribution", "normalized_distribution", "version", "filename", "sha256", "size_bytes", "requested"} if mode == "pypi" else {"distribution", "normalized_distribution", "version", "filename", "sha256", "size_bytes", "source_project"}
+    for item in entries:
+        expected = base_expected
+        if mode == "local-repository" and isinstance(item, dict) and item.get("source_kind") == "external-wheelhouse":
+            expected = {"distribution", "normalized_distribution", "version", "filename", "sha256", "size_bytes", "source_kind"}
+        if mode == "local-repository" and isinstance(item, dict) and item.get("artifact_kind") == "native":
+            expected = expected | {"artifact_kind", "wheel_tags", "executable"}
+        if not isinstance(item, dict) or set(item) != expected:
+            raise InstanceError("ARTIFACT_INVALID", "artifact entry fields are invalid")
+        distribution = _text(item["distribution"], "distribution", _IDENTIFIER)
+        normalized = _text(item["normalized_distribution"], "normalized_distribution", re.compile(r"[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?\Z"))
+        if normalize_distribution(distribution) != normalized or distribution in names or normalized in normalized_names:
+            raise InstanceError("ARTIFACT_INVALID", "artifact distributions are duplicated or not normalized")
+        _text(item["version"], "version", _VERSION)
+        filename = _text(item["filename"], "filename")
+        if not filename.endswith(".whl") or Path(filename).name != filename or filename in filenames:
+            raise InstanceError("ARTIFACT_INVALID", "artifact filename is unsafe or duplicated")
+        if not isinstance(item["sha256"], str) or not _HEX.fullmatch(item["sha256"]):
+            raise InstanceError("ARTIFACT_INVALID", "artifact hash is invalid")
+        if type(item["size_bytes"]) is not int or item["size_bytes"] < 1:
+            raise InstanceError("ARTIFACT_INVALID", "artifact size is invalid")
+        if mode == "pypi" and type(item["requested"]) is not bool:
+            raise InstanceError("ARTIFACT_INVALID", "artifact requested flag is invalid")
+        if mode == "local-repository" and item.get("source_kind") != "external-wheelhouse":
+            source_project = item["source_project"]
+            if not isinstance(source_project, str) or not source_project.startswith("stonecastle/") or ".." in Path(source_project).parts:
+                raise InstanceError("ARTIFACT_INVALID", "local artifact provenance is invalid")
+            if item.get("artifact_kind") == "native":
+                tag, suffix = _native_wheel_tag()
+                authorities = {
+                    "cf-service-mcp-server": ("stonecastle/cf_service_mcp_server", "cf-service-mcp-server"),
+                    "cogniflow-tui": ("stonecastle/cf_install_tui_ratatui", "cogniflow-tui"),
+                }
+                authority = authorities.get(item["normalized_distribution"])
+                wheel_name = item["normalized_distribution"].replace("-", "_")
+                expected_filename = f"{wheel_name}-{item['version']}-{tag}.whl"
+                expected_executable = f"{wheel_name}-{item['version']}.data/scripts/{authority[1] if authority else ''}{suffix}"
+                if authority is None or source_project != authority[0] or item["distribution"] != item["normalized_distribution"] or item["wheel_tags"] != [tag] or item["filename"] != expected_filename or item["executable"] != expected_executable:
+                    raise InstanceError("ARTIFACT_INVALID", "native artifact metadata is not canonical")
+                if not isinstance(item["wheel_tags"], list) or not all(isinstance(value, str) for value in item["wheel_tags"]) or not isinstance(item["executable"], str) or "\\" in item["executable"] or not item["executable"].startswith(f"{wheel_name}-"):
+                    raise InstanceError("ARTIFACT_INVALID", "native artifact fields are unsafe")
+        names.add(distribution); normalized_names.add(normalized); filenames.add(filename)
+    if entries != sorted(entries, key=lambda item: (item["normalized_distribution"], item["filename"])):
+        raise InstanceError("ARTIFACT_INVALID", "artifact entries are not canonically sorted")
+
+
+def marker(plan: dict[str, Any], artifact_set: dict[str, Any], root: Path, environment: Path, executable: Path, installed: list[dict[str, str]]) -> dict[str, object]:
+    return {"schema": MARKER_SCHEMA, "instance_id": plan["instance_id"], "installation_root": str(root), "environment_root": str(environment), "python_executable": str(executable), "plan_digest": digest(plan), "artifact_set_digest": digest(artifact_set), "installed_distributions": installed, "state": "ready"}
+
+
+def marker_v2(plan: dict[str, Any], artifact_set: dict[str, Any], root: Path, environment: Path, executable: Path, installed: list[dict[str, str]], recovery_manifest_path: str | None = None, recovery_manifest_digest: str | None = None) -> dict[str, object]:
+    value = {"schema": MARKER_SCHEMA_V2, "instance_id": plan["instance_id"], "installation_root": str(root), "environment_root": str(environment), "python_executable": str(executable), "profile": plan["profile"], "plan_digest": digest(plan), "profile_digest": artifact_set["profile_digest"], "catalog_digest": artifact_set["catalog_digest"], "selection_digest": artifact_set["selection_digest"], "artifact_set_digest": digest(artifact_set), "installed_distributions": installed}
+    if recovery_manifest_path is not None and recovery_manifest_digest is not None:
+        value["recovery_manifest_path"] = recovery_manifest_path
+        value["recovery_manifest_digest"] = recovery_manifest_digest
+    return value

cf_bootstrap_instance/process.py

@@ -0,0 +1,28 @@
+"""Bounded child-process execution with a controlled environment."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import subprocess
+import sys
+
+from .model import InstanceError
+
+
+def run(command: list[str], *, timeout: float, cwd: Path | None = None, temp_root: Path | None = None) -> subprocess.CompletedProcess[str]:
+    removed = {"PYTHONPATH", "PYTHONHOME", "PYTHONUSERBASE", "PIP_CONFIG_FILE", "PIP_INDEX_URL", "PIP_EXTRA_INDEX_URL", "PIP_FIND_LINKS", "PIP_TRUSTED_HOST", "PIP_REQUIREMENT", "PIP_CONSTRAINT", "PIP_BUILD_CONSTRAINT", "PIP_TARGET", "PIP_PREFIX", "PIP_ROOT", "PIP_USER", "PIP_EDITABLE", "PIP_PRE", "PIP_NO_BINARY", "PIP_ONLY_BINARY", "PIP_NO_DEPS", "PIP_REPORT", "PIP_DRY_RUN", "PIP_CACHE_DIR"}
+    environment = {key: value for key, value in os.environ.items() if key not in removed}
+    environment.update({"PYTHONNOUSERSITE": "1", "PYTHONDONTWRITEBYTECODE": "1", "PIP_NO_INPUT": "1", "PIP_DISABLE_PIP_VERSION_CHECK": "1", "PIP_NO_CACHE_DIR": "1", "PIP_CONFIG_FILE": "NUL" if os.name == "nt" else "/dev/null", "PATH": str(Path(sys.executable).parent)})
+    if temp_root is not None:
+        temp_root.mkdir(parents=True, exist_ok=True)
+        environment.update({"HOME": str(temp_root), "USERPROFILE": str(temp_root), "TMPDIR": str(temp_root), "TEMP": str(temp_root), "TMP": str(temp_root), "XDG_CACHE_HOME": str(temp_root / "cache")})
+    try:
+        result = subprocess.run(command, cwd=cwd, env=environment, capture_output=True, text=True, timeout=timeout, shell=False, check=False)
+    except subprocess.TimeoutExpired as error:
+        raise InstanceError("PROCESS_TIMEOUT", "child process exceeded its timeout") from error
+    except OSError as error:
+        raise InstanceError("PROCESS_START_FAILED", "child process could not be started") from error
+    if result.returncode != 0:
+        raise InstanceError("PROCESS_FAILED", (result.stderr or result.stdout or "child process failed").strip()[:1000])
+    return result