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

cf_bootstrap_instance/__init__.py

@@ -0,0 +1,11 @@
+"""Stable Cogniflow instance bootstrap package."""
+
+from pathlib import Path
+
+
+def semantics_dir() -> Path:
+    return Path(__file__).resolve().parent / "semantics"
+
+
+def semantic_files() -> tuple[Path, ...]:
+    return (semantics_dir() / "package.trig", semantics_dir() / "service.trig")

cf_bootstrap_instance/handoff.py

@@ -0,0 +1,135 @@
+"""Target-side JSON-lines handoff to the installed MCP service client."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+from .transition_authority import classify, recover, rebind
+from .uninstall_authority import classify_uninstall
+
+CAPABILITY = "urn:cf:service:BootstrapInstallationHandoff"
+PROFILED_OPERATION = "urn:cf:service:accept_profiled_bootstrap_handoff"
+PROFILED_CAPABILITY = "urn:cf:service:ProfiledBootstrapInstallationHandoff"
+PYPI_PROFILED_CAPABILITY = "urn:cf:service:PublicPyPIProfiledBootstrapInstallationHandoff"
+_AUTHORITY_REQUEST = "cf.bootstrap.profile-transition-authority.request.v1"
+_AUTHORITY_RESULT = "cf.bootstrap.profile-transition-authority.result.v1"
+_UNINSTALL_BINDING_FIELDS = {"instance_id", "profile", "installation_root", "target_python", "cogniflow_home", "accepted_digests"}
+
+
+def _uninstall_reauthentication(request: dict[str, object]) -> dict[str, object]:
+    if set(request) != {"schema", "target_python", "cogniflow_home", "expected"} or any(not isinstance(request.get(key), str) for key in ("target_python", "cogniflow_home")):
+        raise ValueError("invalid uninstall reauthentication request")
+    expected = request.get("expected")
+    if not isinstance(expected, dict) or set(expected) != _UNINSTALL_BINDING_FIELDS:
+        raise ValueError("invalid uninstall reauthentication binding")
+    digests = expected.get("accepted_digests")
+    if (expected.get("target_python") != request["target_python"] or expected.get("cogniflow_home") != request["cogniflow_home"]
+            or not isinstance(digests, dict) or not digests
+            or any(not isinstance(value, str) or len(value) != 71 or not value.startswith("sha256:") or any(character not in "0123456789abcdef" for character in value[7:]) for value in digests.values())):
+        raise ValueError("invalid uninstall reauthentication binding")
+    classified = classify_uninstall(Path(request["target_python"]), Path(request["cogniflow_home"]))
+    authority = {key: classified[key] for key in _UNINSTALL_BINDING_FIELDS}
+    if authority != expected:
+        raise ValueError("accepted instance no longer matches uninstall authorization")
+    return authority
+
+
+def _authority_request(request: dict[str, object]) -> dict[str, object] | None:
+    if request.get("schema") != _AUTHORITY_REQUEST:
+        return None
+    operation = request.get("operation")
+    basic = {"schema", "operation", "installation_root"}
+    rebind_fields = basic | {"current", "target", "marker", "handoff", "manifest", "recovery", "target_handoff", "target_manifest", "target_recovery", "target_marker"}
+    expected = rebind_fields if operation == "rebind" else basic
+    if operation not in {"classify", "recover", "rebind"} or set(request) != expected:
+        raise ValueError("invalid profile transition authority request")
+    root_value = request["installation_root"]
+    if not isinstance(root_value, str) or not root_value or not Path(root_value).is_absolute() or Path(root_value) == Path(Path(root_value).anchor):
+        raise ValueError("invalid profile transition authority root")
+    root = Path(root_value).resolve()
+    try:
+        if operation == "classify":
+            status = classify(root)
+        elif operation == "recover":
+            status = recover(root)
+        else:
+            mappings = {name: request[name] for name in rebind_fields - basic}
+            if any(not isinstance(value, dict) for value in mappings.values()):
+                raise ValueError("profile transition authority values must be objects")
+            rebind(root, mappings["current"], mappings["target"], marker=mappings["marker"], handoff=mappings["handoff"], manifest=mappings["manifest"], recovery=mappings["recovery"], target_handoff=mappings["target_handoff"], target_manifest=mappings["target_manifest"], target_recovery=mappings["target_recovery"], target_marker=mappings["target_marker"])
+            status = "complete-b"
+    except ValueError as error:
+        return {"schema": _AUTHORITY_RESULT, "operation": operation, "error": {"code": "AUTHORITY_INVALID", "message": str(error)}}
+    return {"schema": _AUTHORITY_RESULT, "operation": operation, "status": status}
+
+
+def main() -> int:
+    for line in sys.stdin:
+        request = json.loads(line)
+        if not isinstance(request, dict):
+            raise ValueError("invalid handoff request")
+        if request.get("schema") == "cf.bootstrap.uninstall-reauthentication.request.v1":
+            try:
+                authority = _uninstall_reauthentication(request)
+                response = {"schema": "cf.bootstrap.uninstall-reauthentication.result.v1", "status": "accepted", "authority": authority}
+            except ValueError as error:
+                response = {"schema": "cf.bootstrap.uninstall-reauthentication.result.v1", "status": "rejected", "error": {"code": "AUTHORITY_INVALID", "message": str(error)}}
+            sys.stdout.write(json.dumps(response, sort_keys=True, separators=(",", ":")) + "\n")
+            sys.stdout.flush()
+            continue
+        if request.get("schema") == "cf.bootstrap.uninstall-authority.request.v1":
+            if set(request) != {"schema", "target_python", "cogniflow_home"} or any(not isinstance(request.get(key), str) for key in ("target_python", "cogniflow_home")):
+                raise ValueError("invalid uninstall authority request")
+            try:
+                authority = classify_uninstall(Path(request["target_python"]), Path(request["cogniflow_home"]))
+                response = {"schema": "cf.bootstrap.uninstall-authority.result.v1", "status": "accepted", "authority": authority}
+            except ValueError as error:
+                response = {"schema": "cf.bootstrap.uninstall-authority.result.v1", "status": "rejected", "error": {"code": "AUTHORITY_INVALID", "message": str(error)}}
+            sys.stdout.write(json.dumps(response, sort_keys=True, separators=(",", ":")) + "\n")
+            sys.stdout.flush()
+            continue
+        authority_result = _authority_request(request)
+        if authority_result is not None:
+            sys.stdout.write(json.dumps(authority_result, sort_keys=True, separators=(",", ":")) + "\n")
+            sys.stdout.flush()
+            continue
+        if request.get("schema") in {"cf.bootstrap.service-handoff.request.v2", "cf.bootstrap.service-handoff.request.v3"}:
+            local_fields = {"schema", "instance_id", "installation_root", "cogniflow_home", "checkout_path", "plan_digest", "artifact_set_digest", "profile", "profile_digest", "selection_digest", "post_handoff_artifact_root", "post_handoff_artifact_set_digest", "post_handoff_selection_digest", "post_handoff_binding_digest", "post_handoff_profile_digest", "post_handoff_catalog_digest", "post_handoff_repository_source_digest", "post_handoff_index_digest"}
+            pypi_fields = {"schema", "instance_id", "installation_root", "cogniflow_home", "artifact_source", "plan_digest", "artifact_set_digest", "profile", "selection_digest", "post_handoff_artifact_root", "post_handoff_artifact_set_digest", "post_handoff_selection_digest", "post_handoff_binding_digest"}
+            fields = pypi_fields if request["schema"].endswith(".v3") else local_fields
+            if set(request) != fields:
+                raise ValueError("invalid profiled handoff request")
+            service_client = __import__("cf_" + "service_client", fromlist=["ServiceClient"])
+            client = service_client.ServiceClient.for_runtime("production", home=request["cogniflow_home"])
+            capability = PYPI_PROFILED_CAPABILITY if request["schema"].endswith(".v3") else PROFILED_CAPABILITY
+            result = client.call_service(capability, inputs={key: request[key] for key in fields if key != "schema"})
+            if result.is_error or not isinstance(result.content, dict) or result.content.get("ok") is not True:
+                raise RuntimeError(f"installer service did not accept the profiled handoff: {result.content}")
+            outputs = result.content.get("outputs", []) if isinstance(result.content, dict) else []
+            record = next((item.get("value", {}).get("data") for item in outputs if isinstance(item, dict) and item.get("key") == "accepted_handoff_record"), None)
+            if not isinstance(record, dict):
+                raise RuntimeError("handoff service did not return its persisted accepted record")
+            sys.stdout.write(json.dumps({"schema": "cf.bootstrap.service-handoff.result.v2", "status": "accepted", "profile": request["profile"], "profile_digest": request.get("profile_digest"), "selection_digest": request["selection_digest"], "handoff_receipt": record, "content": result.content}, sort_keys=True, separators=(",", ":")) + "\n")
+            sys.stdout.flush()
+            continue
+        if set(request) != {"schema", "cogniflow_home", "instance_id", "installation_root", "plan_digest", "artifact_set_digest"} or request["schema"] != "cf.bootstrap.service-handoff.request.v1":
+            raise ValueError("invalid handoff request")
+        service_client = __import__("cf_" + "service_client", fromlist=["ServiceClient"])
+        client = service_client.ServiceClient.for_runtime("production", home=request["cogniflow_home"])
+        result = client.call_service(CAPABILITY, inputs={key: request[key] for key in ("instance_id", "installation_root", "plan_digest", "artifact_set_digest")})
+        if result.is_error:
+            raise RuntimeError(str(result.content))
+        if not isinstance(result.content, dict) or set(result.content) != {"protocol", "ok", "outputs", "diagnostics", "metadata"} or result.content.get("protocol") != "cf.service.result.v1" or result.content.get("ok") is not True:
+            raise RuntimeError("service returned an invalid result envelope")
+        outputs = {item.get("key"): item.get("value", {}).get("data") for item in result.content["outputs"] if isinstance(item, dict) and isinstance(item.get("value"), dict)}
+        if outputs.get("status") != "accepted":
+            raise RuntimeError("installer service did not accept the handoff")
+        sys.stdout.write(json.dumps({"schema": "cf.bootstrap.service-handoff.result.v1", "content": result.content}, sort_keys=True, separators=(",", ":")) + "\n")
+        sys.stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cf_bootstrap_instance/install.py

@@ -0,0 +1,119 @@
+"""Validated wheel-only target environment installation."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from pathlib import Path
+import tempfile
+import sys
+
+from .model import InstanceError, _validate_artifacts
+from .process import run
+
+
+def _entries(artifact_set: dict[str, object]) -> list[dict[str, object]]:
+    entries = artifact_set.get("artifacts")
+    if not isinstance(entries, list) or not entries:
+        raise InstanceError("ARTIFACT_INVALID", "artifact set is empty")
+    mode = "pypi" if isinstance(entries[0], dict) and "requested" in entries[0] else "local-repository"
+    _validate_artifacts(entries, mode)
+    return entries
+
+
+def requirements(wheelhouse: Path, artifact_set: dict[str, object], temp_dir: Path | None = None) -> Path:
+    lines: list[str] = []
+    for item in _entries(artifact_set):
+        wheel = wheelhouse / item["filename"]
+        if wheel.is_symlink() or not wheel.is_file() or wheel.stat().st_size != item["size_bytes"] or hashlib.sha256(wheel.read_bytes()).hexdigest() != item["sha256"]:
+            raise InstanceError("ARTIFACT_INVALID", f"wheel validation failed: {item['filename']}")
+        lines.append(f"{item['normalized_distribution']}=={item['version']} --hash=sha256:{item['sha256']}")
+    fd, name = tempfile.mkstemp(prefix="cf-bootstrap-", suffix=".lock", dir=str(temp_dir) if temp_dir else None)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as stream:
+            stream.write("\n".join(lines) + "\n")
+            stream.flush()
+            os.fsync(stream.fileno())
+    except BaseException:
+        try:
+            os.close(fd)
+        except OSError:
+            pass
+        Path(name).unlink(missing_ok=True)
+        raise
+    return Path(name)
+
+
+def create_environment(environment: Path, temp_root: Path | None = None) -> Path:
+    run([sys.executable, "-m", "venv", "--copies", str(environment)], timeout=120, temp_root=temp_root)
+    executable = environment / ("Scripts/python.exe" if sys.platform == "win32" else "bin/python")
+    if not executable.is_file():
+        raise InstanceError("VENV_INVALID", "venv interpreter was not created")
+    return executable
+
+
+def install(executable: Path, wheelhouse: Path, artifact_set: dict[str, object], temp_dir: Path | None = None) -> None:
+    lock = requirements(wheelhouse, artifact_set, temp_dir)
+    try:
+        count_file = os.environ.get("CF_BOOTSTRAP_TEST_PIP_COUNT_FILE")
+        if count_file:
+            count = Path(count_file)
+            count.write_text(str(int(count.read_text(encoding="utf-8") if count.exists() else "0") + 1), encoding="utf-8")
+        run([str(executable), "-m", "pip", "--isolated", "install", "--no-index", "--find-links", str(wheelhouse), "--require-hashes", "--no-deps", "--no-cache-dir", "--disable-pip-version-check", "--no-input", "--requirement", str(lock)], timeout=300, temp_root=temp_dir)
+    finally:
+        lock.unlink(missing_ok=True)
+
+
+_LAUNCHER_CHECK = r'''
+from importlib import metadata
+from pathlib import Path
+from pip._vendor.distlib.scripts import ScriptMaker
+import os
+import sys
+
+scripts = Path(sys.argv[1]).resolve()
+final_executable = Path(sys.argv[2]).resolve()
+staging_executable = Path(sys.argv[3]).resolve()
+entries = []
+names = set()
+for distribution in metadata.distributions():
+    for entry in distribution.entry_points:
+        if entry.group != "console_scripts":
+            continue
+        if entry.name in names:
+            raise RuntimeError("duplicate console script: " + entry.name)
+        names.add(entry.name)
+        entries.append(entry.name + " = " + entry.value)
+maker = ScriptMaker(str(scripts), str(scripts), add_launchers=True)
+maker.executable = str(final_executable)
+maker.clobber = True
+maker.variants = {""}
+written = maker.make_multiple(sorted(entries))
+written_names = {Path(item).stem for item in written}
+if written_names != names:
+    raise RuntimeError("launcher set differs from console-script metadata")
+final_bytes = str(final_executable).encode()
+staging_bytes = str(staging_executable).encode()
+for item in written:
+    path = Path(item)
+    data = path.read_bytes()
+    if staging_bytes in data:
+        raise RuntimeError("launcher contains staging interpreter path: " + str(path))
+    if os.name == "nt":
+        if final_bytes not in data and final_bytes.replace(b"\\", b"/") not in data:
+            raise RuntimeError("Windows launcher is not bound to final interpreter: " + str(path))
+    elif data.splitlines()[0] != b"#!" + str(final_executable).encode():
+        raise RuntimeError("POSIX launcher is not bound to final interpreter: " + str(path))
+'''
+
+
+def prepare_launchers(staging_executable: Path, final_executable: Path) -> None:
+    """Generate deterministic final-path-bound launchers inside staging."""
+    scripts = staging_executable.parent
+    run([str(staging_executable), "-c", _LAUNCHER_CHECK, str(scripts), str(final_executable), str(staging_executable)], timeout=60)
+
+
+def remove_build_tools(executable: Path) -> None:
+    # pip is only an installation tool; leaving it would violate the exact
+    # validated-distribution inventory of the non-editable instance.
+    run([str(executable), "-m", "pip", "--isolated", "uninstall", "--yes", "pip", "setuptools", "wheel"], timeout=60)

cf_bootstrap_instance/layout.py

@@ -0,0 +1,156 @@
+"""External instance layout validation and atomic marker publication."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import tempfile
+import re
+import stat
+
+from .model import InstanceError, MARKER_SCHEMA, MARKER_SCHEMA_V2, _IDENTIFIER, _VERSION, canonical_json, normalize_distribution
+
+
+def validate_root(root: Path, checkout: Path | None, wheelhouse: Path, home: Path) -> None:
+    root = _lexical_absolute(root, "installation_root")
+    wheelhouse = _lexical_absolute(wheelhouse, "wheelhouse_path")
+    home = _lexical_absolute(home, "cogniflow_home")
+    checkout = _lexical_absolute(checkout, "checkout_path") if checkout is not None else None
+    _assert_link_free(root, "installation_root")
+    _assert_link_free(root.parent, "installation_root parent")
+    _assert_link_free(wheelhouse, "wheelhouse_path")
+    _assert_link_free(wheelhouse.parent, "wheelhouse parent")
+    _assert_link_free(home, "cogniflow_home")
+    _assert_link_free(home.parent, "cogniflow_home parent")
+    if checkout is not None:
+        _assert_link_free(checkout, "checkout_path")
+        _assert_link_free(checkout.parent, "checkout parent")
+    if root == Path(root.anchor):
+        raise InstanceError("ROOT_INVALID", "installation root must be a real non-root directory")
+    root_canonical = root.resolve(strict=False)
+    wheelhouse_canonical = wheelhouse.resolve(strict=False)
+    home_canonical = home.resolve(strict=False)
+    checkout_canonical = checkout.resolve(strict=False) if checkout is not None else None
+    if checkout_canonical is not None and (_under(wheelhouse_canonical, checkout_canonical) or _under(checkout_canonical, wheelhouse_canonical)):
+        raise InstanceError("ROOT_INVALID", "wheelhouse and checkout must be disjoint")
+    if root_canonical == Path(root_canonical.anchor):
+        raise InstanceError("ROOT_INVALID", "installation root must be a real non-root directory")
+    for protected, label in ((home_canonical, "Cogniflow home"), (wheelhouse_canonical, "artifact output"), (checkout_canonical, "checkout")):
+        if protected is not None and (_under(root_canonical, protected) or _under(protected, root_canonical)):
+            raise InstanceError("ROOT_INVALID", f"installation root must be disjoint from {label}")
+    if root.exists() and not root.is_dir():
+        raise InstanceError("ROOT_INVALID", "installation root is not a directory")
+
+
+def _lexical_absolute(path: Path | None, label: str) -> Path:
+    if path is None:
+        raise InstanceError("SCHEMA_INVALID", f"{label} is missing")
+    value = os.fspath(path)
+    if not isinstance(value, str) or not value or value != value.strip() or "\x00" in value or any(ord(char) < 32 for char in value) or ".." in Path(value).parts:
+        raise InstanceError("SCHEMA_INVALID", f"{label} is unsafe")
+    lexical = Path(os.path.abspath(value))
+    if not lexical.is_absolute() or lexical == Path(lexical.anchor):
+        raise InstanceError("SCHEMA_INVALID", f"{label} must be an absolute non-root path")
+    return lexical
+
+
+def _components(path: Path) -> tuple[Path, ...]:
+    current = path
+    result: list[Path] = []
+    while current != Path(current.anchor):
+        result.append(current)
+        current = current.parent
+    result.reverse()
+    return tuple(result)
+
+
+def _is_redirecting_directory(path: Path) -> bool:
+    if path.is_symlink():
+        return True
+    if os.name == "nt" and path.exists():
+        try:
+            attributes = os.lstat(path).st_file_attributes
+        except OSError as error:
+            raise InstanceError("ROOT_INVALID", f"cannot inspect path component: {path}") from error
+        return bool(attributes & stat.FILE_ATTRIBUTE_REPARSE_POINT)
+    return False
+
+
+def _assert_link_free(path: Path, label: str) -> None:
+    for component in _components(path):
+        if component.is_symlink() or (component.exists() and _is_redirecting_directory(component)):
+            raise InstanceError("ROOT_INVALID", f"{label} contains a symbolic link or redirecting reparse point")
+
+
+def _under(left: Path, right: Path) -> bool:
+    try:
+        left.relative_to(right)
+        return True
+    except ValueError:
+        return False
+
+
+def atomic_write(path: Path, data: bytes) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temporary = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    try:
+        with os.fdopen(fd, "wb") as stream:
+            stream.write(data)
+            stream.flush()
+            os.fsync(stream.fileno())
+        Path(temporary).replace(path)
+    except OSError:
+        try:
+            Path(temporary).unlink()
+        except OSError:
+            pass
+        raise
+
+
+def read_marker(path: Path) -> tuple[dict[str, object], bytes]:
+    expected_v1 = {"schema", "instance_id", "installation_root", "environment_root", "python_executable", "plan_digest", "artifact_set_digest", "installed_distributions", "state"}
+    expected_v2 = {"schema", "instance_id", "installation_root", "environment_root", "python_executable", "profile", "plan_digest", "profile_digest", "catalog_digest", "selection_digest", "artifact_set_digest", "installed_distributions", "recovery_manifest_path", "recovery_manifest_digest"}
+    try:
+        before = os.lstat(path)
+        if not stat.S_ISREG(before.st_mode) or path.is_symlink() or (os.name != "nt" and before.st_mode & 0o077):
+            raise OSError("marker is not a regular safe file")
+        descriptor = os.open(os.fspath(path), os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
+        try:
+            raw = os.read(descriptor, 16 * 1024 * 1024)
+        finally:
+            os.close(descriptor)
+        value = json.loads(raw)
+    except (OSError, ValueError) as error:
+        raise InstanceError("MARKER_INVALID", "instance marker is unreadable") from error
+    schema = value.get("schema") if isinstance(value, dict) else None
+    expected = expected_v2 if schema == MARKER_SCHEMA_V2 else expected_v1
+    if not isinstance(value, dict) or set(value) != expected or (schema == MARKER_SCHEMA and value.get("state") != "ready") or schema not in {MARKER_SCHEMA, MARKER_SCHEMA_V2} or raw != canonical_json(value):
+        raise InstanceError("MARKER_INVALID", "instance marker is not canonical")
+    for key in ("instance_id",):
+        if not isinstance(value[key], str) or not _IDENTIFIER.fullmatch(value[key]):
+            raise InstanceError("MARKER_INVALID", f"marker {key} is invalid")
+    for key in ("installation_root", "environment_root", "python_executable"):
+        if not isinstance(value[key], str):
+            raise InstanceError("MARKER_INVALID", f"marker {key} is invalid")
+        marker_path = Path(value[key])
+        if not marker_path.is_absolute() or ".." in marker_path.parts or marker_path == Path(marker_path.anchor):
+            raise InstanceError("MARKER_INVALID", f"marker {key} is invalid")
+    for key in ("plan_digest", "artifact_set_digest"):
+        if not isinstance(value[key], str) or not re.fullmatch(r"sha256:[0-9a-f]{64}", value[key]):
+            raise InstanceError("MARKER_INVALID", f"marker {key} is invalid")
+    if schema == MARKER_SCHEMA_V2:
+        if not isinstance(value["profile"], str) or not re.fullmatch(r"[A-Za-z][A-Za-z0-9+.-]*:[^\s]+", value["profile"]):
+            raise InstanceError("MARKER_INVALID", "marker profile is invalid")
+        for key in ("profile_digest", "catalog_digest", "selection_digest", "recovery_manifest_digest"):
+            if not isinstance(value[key], str) or not re.fullmatch(r"sha256:[0-9a-f]{64}", value[key]):
+                raise InstanceError("MARKER_INVALID", f"marker {key} is invalid")
+    installed = value["installed_distributions"]
+    if not isinstance(installed, list) or installed != sorted(installed, key=lambda item: item.get("name", "").lower() if isinstance(item, dict) else ""):
+        raise InstanceError("MARKER_INVALID", "marker inventory is not sorted")
+    seen: set[str] = set()
+    for item in installed:
+        if not isinstance(item, dict) or set(item) != {"name", "version"} or not isinstance(item["name"], str) or not isinstance(item["version"], str) or not _IDENTIFIER.fullmatch(item["name"]) or not _VERSION.fullmatch(item["version"]) or normalize_distribution(item["name"]) in seen:
+            raise InstanceError("MARKER_INVALID", "marker inventory is invalid")
+        seen.add(normalize_distribution(item["name"]))
+    return value, raw