pyencode-protector 0.3.0__py3-none-any.whl

pyencode/runtime_template/_runtime.py

@@ -0,0 +1,1488 @@
+"""Portable in-memory runtime for PyEncode PYE2 distributions.
+
+The runtime intentionally remains pure Python so one generated runtime source
+works on Windows and Linux and across supported CPython releases. Marshalled
+payloads are still tied to the CPython minor version recorded by the build.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import importlib
+import importlib.abc
+import importlib.util
+import json
+import marshal
+import os
+import re
+import stat
+import sys
+import threading
+import types
+import zlib
+from datetime import date, datetime, time, timezone
+from pathlib import Path, PurePosixPath, PureWindowsPath
+from typing import Any, Iterator, Mapping, NoReturn
+
+try:
+    from importlib.resources.abc import ResourceReader as _ResourceReaderABC
+except ImportError:  # Python 3.10
+    from importlib.abc import ResourceReader as _ResourceReaderABC
+
+from . import _build
+
+
+_MAGIC = b"PYE2"
+_NONCE_SIZE = 12
+_TAG_SIZE = 16
+_KEY_SIZE = 32
+_MAX_INDEX_SIZE = 16 * 1024 * 1024
+_MAX_MARSHALLED_SIZE = 256 * 1024 * 1024
+_MASK_PREFIX = b"pyencode-key-mask\0"
+_ROOT_KEY_INFO = b"pyencode-root-key-v2\0"
+_INDEX_KEY_INFO = b"pyencode-module-index-v1\0"
+_INDEX_COMMITMENT_DOMAIN = b"pyencode-module-index-commitment-v1\0"
+_MODULE_ROOT_INFO = b"pyencode-module-root-v2\0"
+_ARTIFACT_KEY_INFO = b"pyencode-artifact-v2\0"
+_BOUND_FILES_DOMAIN = b"pyencode-bound-files-v1\0"
+_MANIFEST_NAME = ".pyencode-manifest.json"
+_TOKEN_RE = re.compile(r"[0-9a-f]{32}\Z")
+_DIGEST_RE = re.compile(r"[0-9a-f]{64}\Z")
+_PYTHON_TAG_RE = re.compile(r"cp[0-9]{2,}\Z")
+_WINDOWS_FORBIDDEN_CHARACTERS = frozenset('<>:"|?*')
+_WINDOWS_RESERVED_BASENAMES = frozenset(
+    {
+        "aux",
+        "con",
+        "conin$",
+        "conout$",
+        "nul",
+        "prn",
+        *(f"com{index}" for index in range(1, 10)),
+        *(f"lpt{index}" for index in range(1, 10)),
+    }
+)
+_CODE_SUFFIXES = frozenset(
+    {".py", ".pyc", ".pyo", ".pyd", ".so", ".dll", ".dylib"}
+)
+_RUNTIME_PATHS = frozenset(
+    {
+        "pyencode_runtime/__init__.py",
+        "pyencode_runtime/_mp_main.py",
+        "pyencode_runtime/_runtime.py",
+        "pyencode_runtime/_build.py",
+    }
+)
+
+
+class PyEncodeRuntimeError(ImportError):
+    """Raised when protected output is invalid, incompatible, or expired."""
+
+
+class IntegrityError(PyEncodeRuntimeError):
+    """Raised when signed or authenticated bytes do not match."""
+
+
+class CompatibilityError(PyEncodeRuntimeError):
+    """Raised when a distribution targets another Python runtime."""
+
+
+class PolicyError(PyEncodeRuntimeError):
+    """Raised when a signed policy prevents execution."""
+
+
+def _fail(message: str, *, cause: BaseException | None = None) -> NoReturn:
+    error = PyEncodeRuntimeError(f"pyencode runtime: {message}")
+    if cause is None:
+        raise error
+    raise error from cause
+
+
+def _canonical_json(value: Any) -> bytes:
+    try:
+        return json.dumps(
+            value,
+            sort_keys=True,
+            separators=(",", ":"),
+            ensure_ascii=False,
+            allow_nan=False,
+        ).encode("utf-8")
+    except (TypeError, ValueError, UnicodeEncodeError) as exc:
+        _fail("metadata cannot be encoded as canonical JSON", cause=exc)
+
+
+def _decode_json(raw: bytes, description: str) -> Any:
+    try:
+        return json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        _fail(f"invalid {description} JSON", cause=exc)
+
+
+def _decode_b64(value: object, description: str, *, minimum: int = 1) -> bytes:
+    if not isinstance(value, str) or not value:
+        _fail(f"{description} must be a non-empty base64 string")
+    try:
+        decoded = base64.b64decode(value, validate=True)
+    except (ValueError, binascii.Error) as exc:
+        _fail(f"{description} is not valid base64", cause=exc)
+    if len(decoded) < minimum:
+        _fail(f"{description} is too short")
+    return decoded
+
+
+def _decode_hex(value: object, description: str, *, size: int) -> bytes:
+    expected_length = size * 2
+    if (
+        not isinstance(value, str)
+        or len(value) != expected_length
+        or value != value.lower()
+    ):
+        _fail(
+            f"{description} must be exactly {expected_length} lowercase hexadecimal characters"
+        )
+    try:
+        decoded = bytes.fromhex(value)
+    except ValueError as exc:
+        _fail(f"{description} is not valid hexadecimal", cause=exc)
+    if len(decoded) != size:
+        _fail(f"{description} must decode to {size} bytes")
+    return decoded
+
+
+def _runtime_python_tag() -> str:
+    if getattr(sys.implementation, "name", None) != "cpython":
+        raise CompatibilityError("pyencode runtime: protected modules require CPython")
+    return f"cp{sys.version_info.major}{sys.version_info.minor}"
+
+
+def _validate_build_config() -> bytes:
+    required_strings = {
+        "BUILD_ID": _build.BUILD_ID,
+        "PYTHON_TAG": _build.PYTHON_TAG,
+        "PUBLIC_KEY_B64": _build.PUBLIC_KEY_B64,
+        "MANIFEST_NAME": _build.MANIFEST_NAME,
+        "LAUNCHER_NAME": _build.LAUNCHER_NAME,
+    }
+    for name, value in required_strings.items():
+        if not isinstance(value, str) or not value:
+            _fail(f"runtime build configuration {name} is missing")
+    build_id = _decode_hex(_build.BUILD_ID, "BUILD_ID", size=16)
+    if _PYTHON_TAG_RE.fullmatch(_build.PYTHON_TAG) is None:
+        _fail("runtime build configuration PYTHON_TAG is invalid")
+    if _build.MANIFEST_NAME != _MANIFEST_NAME:
+        _fail("runtime build configuration MANIFEST_NAME is invalid")
+    actual_tag = _runtime_python_tag()
+    if _build.PYTHON_TAG != actual_tag:
+        raise CompatibilityError(
+            "pyencode runtime: protected output targets "
+            f"{_build.PYTHON_TAG}, but this interpreter is {actual_tag}"
+        )
+    if not isinstance(_build.KEY_PARTS, (tuple, list)) or not _build.KEY_PARTS:
+        _fail("runtime build configuration KEY_PARTS is missing")
+    if not isinstance(_build.KEY_ORDER, (tuple, list)) or not _build.KEY_ORDER:
+        _fail("runtime build configuration KEY_ORDER is missing")
+    if (
+        not isinstance(_build.BOOTSTRAP_PATHS, (tuple, list))
+        or any(path != "_vendor" for path in _build.BOOTSTRAP_PATHS)
+        or len(set(_build.BOOTSTRAP_PATHS)) != len(_build.BOOTSTRAP_PATHS)
+    ):
+        _fail("runtime build configuration BOOTSTRAP_PATHS is invalid")
+    launcher = PurePosixPath(_build.LAUNCHER_NAME)
+    if (
+        len(launcher.parts) != 1
+        or launcher.suffix.lower() != ".py"
+        or not launcher.stem.isidentifier()
+    ):
+        _fail("runtime build configuration LAUNCHER_NAME is invalid")
+    return build_id
+
+
+def _embedded_master_key(build_id: bytes) -> bytearray:
+    parts = _build.KEY_PARTS
+    order = _build.KEY_ORDER
+    if any(isinstance(index, bool) or not isinstance(index, int) for index in order):
+        _fail("KEY_ORDER entries must be integers")
+    if len(order) != len(parts) or sorted(order) != list(range(len(parts))):
+        _fail("KEY_ORDER must be a permutation of all KEY_PARTS indexes")
+    decoded_parts: list[bytes] = []
+    for index in order:
+        part = parts[index]
+        if not isinstance(part, (str, bytes)) or not part:
+            _fail("KEY_PARTS entries must be non-empty base85 strings")
+        try:
+            decoded_parts.append(base64.b85decode(part))
+        except (ValueError, binascii.Error) as exc:
+            _fail("a KEY_PARTS entry is not valid base85", cause=exc)
+    material = b"".join(decoded_parts)
+    if len(material) != _KEY_SIZE:
+        _fail(f"decoded KEY_PARTS must contain exactly {_KEY_SIZE} bytes")
+    mask = hashlib.sha256(_MASK_PREFIX + build_id).digest()
+    return bytearray(left ^ right for left, right in zip(material, mask))
+
+
+def _hkdf(root_key: bytes | bytearray, build_id: bytes, info: bytes) -> bytes:
+    try:
+        from cryptography.hazmat.primitives import hashes
+        from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+    except ImportError as exc:  # pragma: no cover - installation dependent
+        _fail("the 'cryptography' package is required", cause=exc)
+    return HKDF(
+        algorithm=hashes.SHA256(),
+        length=_KEY_SIZE,
+        salt=build_id,
+        info=info,
+    ).derive(bytes(root_key))
+
+
+def _derive_support_root(
+    master_key: bytes | bytearray, build_id: bytes, commitment: bytes
+) -> bytes:
+    if len(commitment) != 32:
+        _fail("bound-files commitment must be exactly 32 bytes")
+    return _hkdf(master_key, build_id, _ROOT_KEY_INFO + commitment)
+
+
+def _index_aad(build_id_text: str, python_tag: str) -> bytes:
+    return _canonical_json(
+        {
+            "build_id": build_id_text,
+            "cipher": "aes-256-gcm",
+            "compression": "zlib",
+            "format": 1,
+            "python_tag": python_tag,
+        }
+    )
+
+
+def _index_commitment(
+    nonce: bytes, ciphertext: bytes, build_id_text: str, python_tag: str
+) -> bytes:
+    return hashlib.sha256(
+        _INDEX_COMMITMENT_DOMAIN
+        + _index_aad(build_id_text, python_tag)
+        + nonce
+        + ciphertext
+    ).digest()
+
+
+def _derive_index_key(support_root: bytes, build_id: bytes) -> bytes:
+    return _hkdf(support_root, build_id, _INDEX_KEY_INFO)
+
+
+def _derive_module_root(
+    support_root: bytes, build_id: bytes, index_commitment: bytes
+) -> bytes:
+    if len(index_commitment) != 32:
+        _fail("module-index commitment must be exactly 32 bytes")
+    return _hkdf(support_root, build_id, _MODULE_ROOT_INFO + index_commitment)
+
+
+def _derive_artifact_key(
+    module_root: bytes, build_id: bytes, token: str, fullname: str
+) -> bytes:
+    return _hkdf(
+        module_root,
+        build_id,
+        _ARTIFACT_KEY_INFO
+        + bytes.fromhex(token)
+        + b"\0"
+        + fullname.encode("utf-8"),
+    )
+
+
+def _artifact_aad(
+    *, fullname: str, package: bool, token: str, build_id: str, python_tag: str
+) -> bytes:
+    return _canonical_json(
+        {
+            "artifact": token,
+            "build_id": build_id,
+            "compression": "zlib",
+            "format": 2,
+            "marshal_version": marshal.version,
+            "module": fullname,
+            "package": package,
+            "python_tag": python_tag,
+        }
+    )
+
+
+def _manifest_path() -> Path:
+    package_dir = Path(__file__).resolve().parent
+    return package_dir.parent / _MANIFEST_NAME
+
+
+def _read_manifest() -> tuple[dict[str, Any], Path]:
+    path = _manifest_path()
+    try:
+        raw = path.read_bytes()
+    except OSError as exc:
+        _fail(f"cannot read manifest {path}", cause=exc)
+    wrapper = _decode_json(raw, "manifest wrapper")
+    if not isinstance(wrapper, dict) or set(wrapper) != {"manifest", "signature"}:
+        _fail("manifest wrapper must contain only 'manifest' and 'signature'")
+    payload = wrapper["manifest"]
+    if not isinstance(payload, dict):
+        _fail("signed manifest payload must be an object")
+    signature = _decode_b64(wrapper["signature"], "manifest signature", minimum=64)
+    public_key = _decode_b64(_build.PUBLIC_KEY_B64, "manifest public key", minimum=32)
+    if len(signature) != 64 or len(public_key) != 32:
+        _fail("manifest signature or public key has an invalid length")
+    try:
+        from cryptography.exceptions import InvalidSignature
+        from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+    except ImportError as exc:  # pragma: no cover - installation dependent
+        _fail("the 'cryptography' package is required", cause=exc)
+    try:
+        Ed25519PublicKey.from_public_bytes(public_key).verify(
+            signature, _canonical_json(payload)
+        )
+    except InvalidSignature as exc:
+        raise IntegrityError("pyencode runtime: manifest signature is invalid") from exc
+    except ValueError as exc:
+        _fail("invalid Ed25519 public key or signature", cause=exc)
+    return payload, path.parent.resolve()
+
+
+def _validate_module_name(value: object) -> str:
+    if not isinstance(value, str) or not value:
+        _fail("module name must be a non-empty string")
+    if any(not part or not part.isidentifier() for part in value.split(".")):
+        _fail(f"invalid protected module name {value!r}")
+    return value
+
+
+def _validate_inventory_path(value: object, description: str) -> str:
+    if (
+        not isinstance(value, str)
+        or not value
+        or "\0" in value
+        or "\\" in value
+    ):
+        _fail(f"{description} must be a canonical POSIX relative path")
+    posix = PurePosixPath(value)
+    windows = PureWindowsPath(value)
+    if (
+        posix.is_absolute()
+        or windows.is_absolute()
+        or bool(windows.drive)
+        or any(
+            part in ("", ".", "..")
+            or part.endswith((".", " "))
+            or any(
+                ord(character) < 32 or character in _WINDOWS_FORBIDDEN_CHARACTERS
+                for character in part
+            )
+            or part.partition(".")[0].casefold() in _WINDOWS_RESERVED_BASENAMES
+            for part in posix.parts
+        )
+        or posix.as_posix() != value
+    ):
+        _fail(f"unsafe {description}: {value!r}")
+    return value
+
+
+def _is_code_path(path: str) -> bool:
+    name = PurePosixPath(path).name.casefold()
+    return any(name.endswith(suffix) for suffix in _CODE_SUFFIXES) or ".so." in name
+
+
+def _is_link_or_reparse(metadata: os.stat_result) -> bool:
+    if stat.S_ISLNK(metadata.st_mode):
+        return True
+    flag = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0)
+    attributes = getattr(metadata, "st_file_attributes", 0)
+    return bool(flag and attributes & flag)
+
+
+def _walk_files(
+    directory: Path,
+    root: Path,
+    prefix: tuple[str, ...] = (),
+    directories: set[str] | None = None,
+) -> Iterator[str]:
+    try:
+        with os.scandir(directory) as iterator:
+            entries = sorted(iterator, key=lambda item: item.name)
+    except OSError as exc:
+        raise IntegrityError(
+            f"pyencode runtime: cannot scan distribution directory {'/'.join(prefix) or '.'!r}"
+        ) from exc
+    folded: dict[str, str] = {}
+    for entry in entries:
+        previous = folded.get(entry.name.casefold())
+        if previous is not None and previous != entry.name:
+            raise IntegrityError(
+                "pyencode runtime: case-folding file collision: "
+                f"{previous!r} and {entry.name!r}"
+            )
+        folded[entry.name.casefold()] = entry.name
+    for entry in entries:
+        relative = "/".join((*prefix, entry.name))
+        _validate_inventory_path(relative, "distribution path")
+        try:
+            metadata = entry.stat(follow_symlinks=False)
+        except OSError as exc:
+            raise IntegrityError(
+                f"pyencode runtime: cannot stat distribution path {relative!r}"
+            ) from exc
+        if _is_link_or_reparse(metadata):
+            raise IntegrityError(
+                f"pyencode runtime: distribution contains a link or reparse point: {relative!r}"
+            )
+        if stat.S_ISDIR(metadata.st_mode):
+            if directories is not None:
+                directories.add(relative)
+            yield from _walk_files(
+                Path(entry.path), root, (*prefix, entry.name), directories
+            )
+        elif stat.S_ISREG(metadata.st_mode):
+            try:
+                Path(entry.path).resolve(strict=True).relative_to(root)
+            except (OSError, ValueError) as exc:
+                raise IntegrityError(
+                    f"pyencode runtime: distribution file escapes its root: {relative!r}"
+                ) from exc
+            yield relative
+        else:
+            raise IntegrityError(
+                f"pyencode runtime: distribution contains a non-regular entry: {relative!r}"
+            )
+
+
+def _scan_distribution(root: Path) -> tuple[dict[str, Path], frozenset[str]]:
+    """Scan the tree once and retain exact, already-validated file paths."""
+
+    directories: set[str] = set()
+    files = {
+        relative: root.joinpath(*PurePosixPath(relative).parts)
+        for relative in _walk_files(root, root, directories=directories)
+    }
+    return files, frozenset(directories)
+
+
+def _exact_file(root: Path, relative: str) -> Path:
+    parts = PurePosixPath(relative).parts
+    current = root
+    for index, part in enumerate(parts):
+        try:
+            with os.scandir(current) as iterator:
+                entries = tuple(iterator)
+        except OSError as exc:
+            raise IntegrityError(
+                f"pyencode runtime: signed file {relative!r} is missing or unreadable"
+            ) from exc
+        exact = next((entry for entry in entries if entry.name == part), None)
+        if exact is None:
+            folded = next(
+                (entry.name for entry in entries if entry.name.casefold() == part.casefold()),
+                None,
+            )
+            if folded is not None:
+                raise IntegrityError(
+                    f"pyencode runtime: signed file {relative!r} has mismatched path casing"
+                )
+            raise IntegrityError(f"pyencode runtime: signed file {relative!r} is missing")
+        try:
+            metadata = exact.stat(follow_symlinks=False)
+        except OSError as exc:
+            raise IntegrityError(
+                f"pyencode runtime: cannot inspect signed file {relative!r}"
+            ) from exc
+        if _is_link_or_reparse(metadata):
+            raise IntegrityError(
+                f"pyencode runtime: signed file {relative!r} uses a link or reparse point"
+            )
+        last = index == len(parts) - 1
+        if last and not stat.S_ISREG(metadata.st_mode):
+            raise IntegrityError(
+                f"pyencode runtime: signed file {relative!r} is not a regular file"
+            )
+        if not last and not stat.S_ISDIR(metadata.st_mode):
+            raise IntegrityError(
+                f"pyencode runtime: parent of signed file {relative!r} is not a directory"
+            )
+        current = Path(exact.path)
+    try:
+        resolved = current.resolve(strict=True)
+        resolved.relative_to(root)
+    except (OSError, ValueError) as exc:
+        raise IntegrityError(
+            f"pyencode runtime: signed file {relative!r} escapes the distribution"
+        ) from exc
+    return resolved
+
+
+def _bound_files_commitment(file_digests: Mapping[str, str]) -> bytes:
+    descriptor = {"format": 1, "files": dict(sorted(file_digests.items()))}
+    return hashlib.sha256(_BOUND_FILES_DOMAIN + _canonical_json(descriptor)).digest()
+
+
+def _validate_bound_files(
+    payload: Mapping[str, Any], root: Path, inventory: Mapping[str, Path]
+) -> tuple[bytes, frozenset[str]]:
+    integrity = payload.get("integrity")
+    if not isinstance(integrity, dict) or set(integrity) != {
+        "format",
+        "algorithm",
+        "files",
+        "commitment_sha256",
+    }:
+        _fail("manifest integrity metadata is missing or has invalid fields")
+    if type(integrity["format"]) is not int or integrity["format"] != 1:
+        _fail("unsupported manifest integrity format")
+    if integrity["algorithm"] != "sha256":
+        _fail("unsupported manifest integrity algorithm")
+    raw_files = integrity["files"]
+    if not isinstance(raw_files, dict) or not raw_files:
+        _fail("manifest integrity files must be a non-empty object")
+
+    expected_mandatory = set(_RUNTIME_PATHS)
+    expected_mandatory.add(_build.LAUNCHER_NAME)
+    if not expected_mandatory.issubset(raw_files):
+        missing = sorted(expected_mandatory.difference(raw_files))
+        _fail("manifest integrity file set is missing " + ", ".join(missing))
+
+    signed: dict[str, str] = {}
+    folded_paths: dict[str, str] = {}
+    for raw_path, raw_digest in raw_files.items():
+        path = _validate_inventory_path(raw_path, "signed support file path")
+        previous = folded_paths.get(path.casefold())
+        if previous is not None and previous != path:
+            _fail(f"case-folding signed path collision: {previous!r} and {path!r}")
+        folded_paths[path.casefold()] = path
+        if not isinstance(raw_digest, str) or _DIGEST_RE.fullmatch(raw_digest) is None:
+            _fail(f"invalid sha256 for signed support file {path!r}")
+        signed[path] = raw_digest
+
+    actual: dict[str, str] = {}
+    for relative, expected_digest in sorted(signed.items()):
+        path = inventory.get(relative)
+        if path is None:
+            raise IntegrityError(
+                f"pyencode runtime: signed support file {relative!r} is missing"
+            )
+        try:
+            digest = hashlib.sha256(path.read_bytes()).hexdigest()
+        except OSError as exc:
+            raise IntegrityError(
+                f"pyencode runtime: cannot read signed support file {relative!r}"
+            ) from exc
+        if digest != expected_digest:
+            raise IntegrityError(
+                f"pyencode runtime: signed support file {relative!r} failed its hash check"
+            )
+        actual[relative] = digest
+
+    commitment = _bound_files_commitment(actual)
+    expected_commitment = _decode_hex(
+        integrity["commitment_sha256"], "bound-files commitment", size=32
+    )
+    if commitment != expected_commitment:
+        raise IntegrityError("pyencode runtime: bound-files commitment is invalid")
+
+    actual_code = {path for path in inventory if _is_code_path(path)}
+    allowed_code = {path for path in signed if _is_code_path(path)}
+    unexpected = sorted(actual_code.difference(allowed_code))
+    if unexpected:
+        raise IntegrityError(
+            "pyencode runtime: distribution contains unsigned executable file(s): "
+            + ", ".join(unexpected)
+        )
+    return commitment, frozenset(signed)
+
+
+def _expiry_value(payload: Mapping[str, Any]) -> object | None:
+    policy = payload.get("policy")
+    if not isinstance(policy, dict):
+        _fail("manifest policy must be an object")
+    for name in ("expiry", "expires_at", "expires"):
+        if name in policy and policy[name] is not None:
+            return policy[name]
+    return None
+
+
+def _parse_expiry(value: object) -> datetime:
+    if isinstance(value, bool):
+        _fail("policy expiry must be an ISO-8601 string or Unix timestamp")
+    if isinstance(value, (int, float)):
+        try:
+            return datetime.fromtimestamp(value, timezone.utc)
+        except (OverflowError, OSError, ValueError) as exc:
+            _fail("policy expiry timestamp is invalid", cause=exc)
+    if not isinstance(value, str) or not value:
+        _fail("policy expiry must be an ISO-8601 string or Unix timestamp")
+    try:
+        if len(value) == 10:
+            return datetime.combine(date.fromisoformat(value), time.max, timezone.utc)
+        normalized = value[:-1] + "+00:00" if value.endswith(("Z", "z")) else value
+        parsed = datetime.fromisoformat(normalized)
+    except ValueError as exc:
+        _fail("policy expiry is not valid ISO-8601", cause=exc)
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)
+
+
+def _check_policy(payload: Mapping[str, Any]) -> None:
+    value = _expiry_value(payload)
+    if value is None:
+        return
+    expiry = _parse_expiry(value)
+    if datetime.now(timezone.utc) > expiry:
+        raise PolicyError(
+            "pyencode runtime: this protected build expired at "
+            f"{expiry.isoformat().replace('+00:00', 'Z')}"
+        )
+
+
+def _allow_extra_data(payload: Mapping[str, Any]) -> bool:
+    policy = payload.get("policy")
+    if not isinstance(policy, dict):
+        _fail("manifest policy must be an object")
+    value = policy.get("allow_extra_data", False)
+    if type(value) is not bool:
+        _fail("manifest allow_extra_data policy must be boolean")
+    return value
+
+
+def _normalize_artifacts(value: object) -> dict[str, str]:
+    if not isinstance(value, dict) or not value:
+        _fail("manifest artifacts must be a non-empty object")
+    result: dict[str, str] = {}
+    for token, digest in value.items():
+        if not isinstance(token, str) or _TOKEN_RE.fullmatch(token) is None:
+            _fail("artifact tokens must be 32 lowercase hexadecimal characters")
+        if not isinstance(digest, str) or _DIGEST_RE.fullmatch(digest) is None:
+            _fail(f"sha256 for artifact {token!r} is invalid")
+        result[token] = digest
+    return dict(sorted(result.items()))
+
+
+def _normalize_index_envelope(value: object) -> tuple[bytes, bytes, bytes]:
+    if not isinstance(value, dict) or set(value) != {
+        "format",
+        "cipher",
+        "compression",
+        "nonce_b64",
+        "ciphertext_b64",
+        "commitment_sha256",
+    }:
+        _fail("manifest module_index metadata has invalid fields")
+    if type(value["format"]) is not int or value["format"] != 1:
+        _fail("unsupported module-index format")
+    if value["cipher"] != "aes-256-gcm" or value["compression"] != "zlib":
+        _fail("unsupported module-index cipher or compression")
+    nonce = _decode_b64(value["nonce_b64"], "module-index nonce")
+    ciphertext = _decode_b64(
+        value["ciphertext_b64"], "module-index ciphertext", minimum=_TAG_SIZE
+    )
+    if len(nonce) != _NONCE_SIZE:
+        _fail(f"module-index nonce must decode to {_NONCE_SIZE} bytes")
+    commitment = _decode_hex(
+        value["commitment_sha256"], "module-index commitment", size=32
+    )
+    return nonce, ciphertext, commitment
+
+
+def _validate_manifest(
+    payload: dict[str, Any], build_id: bytes
+) -> tuple[dict[str, str], bytes, bytes, bytes]:
+    required = {
+        "format",
+        "tool_version",
+        "build_id",
+        "python_tag",
+        "created_utc",
+        "module_index",
+        "artifacts",
+        "policy",
+        "integrity",
+    }
+    if set(payload) != required:
+        _fail("manifest format-3 fields are incomplete or unknown")
+    if type(payload["format"]) is not int or payload["format"] != 3:
+        _fail("unsupported manifest format")
+    if payload["build_id"] != _build.BUILD_ID:
+        raise IntegrityError("pyencode runtime: manifest build_id does not match runtime")
+    if payload["python_tag"] != _build.PYTHON_TAG:
+        raise CompatibilityError(
+            "pyencode runtime: manifest Python tag does not match runtime configuration"
+        )
+    if _decode_hex(payload["build_id"], "manifest build_id", size=16) != build_id:
+        _fail("manifest build_id is malformed")
+    _check_policy(payload)
+    artifacts = _normalize_artifacts(payload["artifacts"])
+    nonce, ciphertext, commitment = _normalize_index_envelope(payload["module_index"])
+    actual_commitment = _index_commitment(
+        nonce, ciphertext, _build.BUILD_ID, _build.PYTHON_TAG
+    )
+    if commitment != actual_commitment:
+        raise IntegrityError("pyencode runtime: module-index commitment is invalid")
+    return artifacts, nonce, ciphertext, commitment
+
+
+def _decompress_strict(compressed: bytes, maximum: int, description: str) -> bytes:
+    decompressor = zlib.decompressobj()
+    try:
+        value = decompressor.decompress(compressed, maximum + 1)
+        if len(value) > maximum or decompressor.unconsumed_tail:
+            _fail(f"{description} exceeds the runtime safety limit")
+        value += decompressor.flush()
+    except zlib.error as exc:
+        _fail(f"{description} is not valid zlib data", cause=exc)
+    if len(value) > maximum:
+        _fail(f"{description} exceeds the runtime safety limit")
+    if not decompressor.eof or decompressor.unused_data:
+        _fail(f"{description} contains incomplete or trailing compressed data")
+    return value
+
+
+def _decrypt_index(
+    nonce: bytes,
+    ciphertext: bytes,
+    support_root: bytes,
+    build_id: bytes,
+) -> tuple[str, dict[str, dict[str, Any]]]:
+    key = _derive_index_key(support_root, build_id)
+    try:
+        from cryptography.exceptions import InvalidTag
+        from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+    except ImportError as exc:  # pragma: no cover - installation dependent
+        _fail("the 'cryptography' package is required", cause=exc)
+    try:
+        compressed = AESGCM(key).decrypt(
+            nonce,
+            ciphertext,
+            _index_aad(_build.BUILD_ID, _build.PYTHON_TAG),
+        )
+    except InvalidTag as exc:
+        raise IntegrityError("pyencode runtime: module-index authentication failed") from exc
+    raw = _decompress_strict(compressed, _MAX_INDEX_SIZE, "module index")
+    index = _decode_json(raw, "module index")
+    if not isinstance(index, dict) or _canonical_json(index) != raw:
+        _fail("module-index JSON is not canonical")
+    if set(index) != {"format", "entry_module", "modules"}:
+        _fail("module index has invalid fields")
+    if type(index["format"]) is not int or index["format"] != 1:
+        _fail("unsupported decrypted module-index format")
+    entry = _validate_module_name(index["entry_module"])
+    raw_modules = index["modules"]
+    if not isinstance(raw_modules, dict) or not raw_modules:
+        _fail("module index modules must be a non-empty object")
+    modules: dict[str, dict[str, Any]] = {}
+    tokens: set[str] = set()
+    for raw_name, metadata in raw_modules.items():
+        name = _validate_module_name(raw_name)
+        if not isinstance(metadata, dict) or set(metadata) != {"artifact", "package"}:
+            _fail(f"module-index metadata for {name!r} is invalid")
+        token = metadata["artifact"]
+        package = metadata["package"]
+        if not isinstance(token, str) or _TOKEN_RE.fullmatch(token) is None:
+            _fail(f"artifact token for module {name!r} is invalid")
+        if token in tokens:
+            _fail(f"duplicate artifact token {token!r}")
+        if type(package) is not bool:
+            _fail(f"package flag for module {name!r} must be boolean")
+        tokens.add(token)
+        modules[name] = {"artifact": token, "package": package}
+    if entry not in modules:
+        _fail("module index does not contain its configured entry module")
+    return entry, dict(sorted(modules.items()))
+
+
+def _artifact_relative_path(fullname: str, package: bool, token: str) -> str:
+    parts = fullname.split(".")
+    directories = parts if package else parts[:-1]
+    return "/".join((*directories, f"{token}.pye"))
+
+
+def _validate_artifacts(
+    root: Path,
+    modules: dict[str, dict[str, Any]],
+    artifacts: Mapping[str, str],
+    inventory: Mapping[str, Path],
+    directories: frozenset[str],
+    signed_paths: frozenset[str],
+    allow_extra_data: bool,
+) -> None:
+    index_tokens = {metadata["artifact"] for metadata in modules.values()}
+    if index_tokens != set(artifacts):
+        missing = sorted(index_tokens.difference(artifacts))
+        extra = sorted(set(artifacts).difference(index_tokens))
+        details: list[str] = []
+        if missing:
+            details.append("missing " + ", ".join(missing))
+        if extra:
+            details.append("unexpected " + ", ".join(extra))
+        _fail("artifact token set does not match module index (" + "; ".join(details) + ")")
+
+    expected_paths: dict[str, tuple[str, str]] = {}
+    for fullname, metadata in modules.items():
+        token = metadata["artifact"]
+        relative = _artifact_relative_path(fullname, metadata["package"], token)
+        if relative in expected_paths:
+            _fail(f"multiple protected modules map to artifact path {relative!r}")
+        expected_paths[relative] = (token, fullname)
+
+    actual_pye = {path for path in inventory if path.casefold().endswith(".pye")}
+    if actual_pye != set(expected_paths):
+        missing = sorted(set(expected_paths).difference(actual_pye))
+        extra = sorted(actual_pye.difference(expected_paths))
+        details = []
+        if missing:
+            details.append("missing " + ", ".join(missing))
+        if extra:
+            details.append("unexpected " + ", ".join(extra))
+        raise IntegrityError(
+            "pyencode runtime: protected artifact file set failed integrity check ("
+            + "; ".join(details)
+            + ")"
+        )
+
+    for relative, (token, fullname) in sorted(expected_paths.items()):
+        path = inventory[relative]
+        try:
+            digest = hashlib.sha256(path.read_bytes()).hexdigest()
+        except OSError as exc:
+            _fail(f"cannot read protected module {fullname!r}", cause=exc)
+        if digest != artifacts[token]:
+            raise IntegrityError(
+                f"pyencode runtime: protected module {fullname!r} failed its hash check"
+            )
+
+    expected_files = signed_paths | set(expected_paths) | {_build.MANIFEST_NAME}
+    actual_files = set(inventory)
+    missing_files = sorted(expected_files.difference(actual_files))
+    unexpected_files = (
+        []
+        if allow_extra_data
+        else sorted(actual_files.difference(expected_files))
+    )
+    if missing_files or unexpected_files:
+        details = []
+        if missing_files:
+            details.append("missing " + ", ".join(missing_files))
+        if unexpected_files:
+            details.append("unexpected " + ", ".join(unexpected_files))
+        raise IntegrityError(
+            "pyencode runtime: immutable distribution file set changed ("
+            + "; ".join(details)
+            + ")"
+        )
+
+    expected_directories: set[str] = set()
+    for relative in expected_files:
+        parts = PurePosixPath(relative).parts
+        for end in range(1, len(parts)):
+            expected_directories.add("/".join(parts[:end]))
+    missing = sorted(expected_directories.difference(directories))
+    extra = (
+        []
+        if allow_extra_data
+        else sorted(set(directories).difference(expected_directories))
+    )
+    if missing or extra:
+        details = []
+        if missing:
+            details.append("missing " + ", ".join(missing))
+        if extra:
+            details.append("unexpected " + ", ".join(extra))
+        raise IntegrityError(
+            "pyencode runtime: immutable distribution directory set changed ("
+            + "; ".join(details)
+            + ")"
+        )
+
+
+class _ResourceReader(_ResourceReaderABC):
+    def __init__(self, directory: Path, root: Path) -> None:
+        self._directory = directory
+        self._root = root
+
+    def _resource(self, resource: str) -> Path:
+        if (
+            not isinstance(resource, str)
+            or not resource
+            or resource in (".", "..")
+            or "/" in resource
+            or "\\" in resource
+        ):
+            raise FileNotFoundError(resource)
+        path = (self._directory / resource).resolve()
+        try:
+            path.relative_to(self._root)
+        except ValueError as exc:
+            raise FileNotFoundError(resource) from exc
+        return path
+
+    def open_resource(self, resource: str):
+        return self._resource(resource).open("rb")
+
+    def resource_path(self, resource: str) -> str:
+        path = self._resource(resource)
+        if not path.is_file():
+            raise FileNotFoundError(resource)
+        return str(path)
+
+    def is_resource(self, name: str) -> bool:
+        try:
+            return self._resource(name).is_file()
+        except (FileNotFoundError, OSError):
+            return False
+
+    def contents(self) -> Iterator[str]:
+        try:
+            return (item.name for item in self._directory.iterdir())
+        except OSError:
+            return iter(())
+
+    def files(self):
+        """Expose a Traversable root for nested importlib.resources paths."""
+
+        return self._directory
+
+
+class _ProtectedLoader(importlib.abc.Loader):
+    def __init__(self, finder: "_ProtectedFinder", fullname: str) -> None:
+        self._finder = finder
+        self._fullname = fullname
+
+    def create_module(self, spec):
+        return None
+
+    def exec_module(self, module: types.ModuleType) -> None:
+        self._finder._execute(self._fullname, module.__dict__)
+
+    def get_code(self, fullname: str) -> types.CodeType:
+        """Return only a tiny runpy trampoline, never decrypted application code."""
+
+        if fullname != self._fullname:
+            raise ImportError(f"loader for {self._fullname!r} cannot load {fullname!r}")
+        source = (
+            "from pyencode_runtime._runtime import _exec_runpy as __pye_exec\n"
+            f"__pye_exec({fullname!r}, globals())\n"
+            "del __pye_exec\n"
+        )
+        return compile(
+            source,
+            f"<pyencode-runpy:{fullname}>",
+            "exec",
+            dont_inherit=True,
+            optimize=2,
+        )
+
+    def get_source(self, fullname: str) -> None:
+        if fullname != self._fullname:
+            raise ImportError(f"loader for {self._fullname!r} cannot load {fullname!r}")
+        return None
+
+    def is_package(self, fullname: str) -> bool:
+        return bool(self._finder._metadata(fullname)["package"])
+
+    def get_filename(self, fullname: str) -> str:
+        return str(self._finder._artifact_path(fullname))
+
+    def get_data(self, path: str) -> bytes:
+        candidate = Path(path).resolve()
+        try:
+            candidate.relative_to(self._finder._root)
+        except ValueError as exc:
+            raise OSError(f"resource is outside the protected distribution: {path}") from exc
+        return candidate.read_bytes()
+
+    def get_resource_reader(self, fullname: str):
+        if fullname != self._fullname or not self.is_package(fullname):
+            return None
+        return _ResourceReader(
+            self._finder._artifact_path(fullname).parent,
+            self._finder._root,
+        )
+
+
+class _ProtectedFinder(importlib.abc.MetaPathFinder):
+    def __init__(
+        self,
+        payload: dict[str, Any],
+        entry: str,
+        modules: dict[str, dict[str, Any]],
+        artifacts: dict[str, str],
+        root: Path,
+        build_id: bytes,
+        support_commitment: bytes,
+        index_commitment: bytes,
+    ) -> None:
+        self._payload = payload
+        self._entry = entry
+        self._modules = modules
+        self._artifacts = artifacts
+        self._root = root
+        self._build_id = build_id
+        self._support_commitment = support_commitment
+        self._index_commitment = index_commitment
+
+    def _parent_path_represented(self, fullname: str, path: object) -> bool:
+        if "." not in fullname:
+            return True
+        if path is None:
+            return False
+        logical_parent = self._root.joinpath(*fullname.split(".")[:-1]).resolve()
+        try:
+            locations = iter(path)
+        except TypeError:
+            return False
+        for raw_location in locations:
+            try:
+                if Path(raw_location).resolve() == logical_parent:
+                    return True
+            except (OSError, TypeError, ValueError):
+                continue
+        return False
+
+    def find_spec(self, fullname: str, path=None, target=None):
+        metadata = self._modules.get(fullname)
+        if metadata is None:
+            return None
+        if not self._parent_path_represented(fullname, path):
+            return None
+        loader = _ProtectedLoader(self, fullname)
+        artifact = self._artifact_path(fullname)
+        spec = importlib.util.spec_from_loader(
+            fullname,
+            loader,
+            origin=str(artifact),
+            is_package=bool(metadata["package"]),
+        )
+        spec.has_location = True
+        if spec.submodule_search_locations is not None:
+            location = str(artifact.parent)
+            if location not in spec.submodule_search_locations:
+                spec.submodule_search_locations.append(location)
+        return spec
+
+    def invalidate_caches(self) -> None:
+        return None
+
+    def _metadata(self, fullname: str) -> dict[str, Any]:
+        try:
+            return self._modules[fullname]
+        except KeyError as exc:
+            raise ImportError(f"unknown protected module {fullname!r}") from exc
+
+    def _artifact_path(self, fullname: str) -> Path:
+        metadata = self._metadata(fullname)
+        relative = _artifact_relative_path(
+            fullname, metadata["package"], metadata["artifact"]
+        )
+        return _exact_file(self._root, relative)
+
+    def _execute(self, fullname: str, namespace: dict[str, Any]) -> None:
+        _check_policy(self._payload)
+        metadata = self._metadata(fullname)
+        path = self._artifact_path(fullname)
+        try:
+            artifact = path.read_bytes()
+        except OSError as exc:
+            _fail(f"cannot read protected module {fullname!r}", cause=exc)
+        token = metadata["artifact"]
+        if hashlib.sha256(artifact).hexdigest() != self._artifacts[token]:
+            raise IntegrityError(
+                f"pyencode runtime: protected module {fullname!r} failed its hash check"
+            )
+        minimum = len(_MAGIC) + _NONCE_SIZE + _TAG_SIZE
+        if len(artifact) < minimum or artifact[: len(_MAGIC)] != _MAGIC:
+            _fail(f"protected module {fullname!r} has invalid PYE2 framing")
+        nonce_start = len(_MAGIC)
+        ciphertext_start = nonce_start + _NONCE_SIZE
+        nonce = artifact[nonce_start:ciphertext_start]
+        ciphertext = artifact[ciphertext_start:]
+        embedded = _embedded_master_key(self._build_id)
+        try:
+            support_root = _derive_support_root(
+                embedded, self._build_id, self._support_commitment
+            )
+            module_root = _derive_module_root(
+                support_root, self._build_id, self._index_commitment
+            )
+        finally:
+            for index in range(len(embedded)):
+                embedded[index] = 0
+        key = _derive_artifact_key(module_root, self._build_id, token, fullname)
+        aad = _artifact_aad(
+            fullname=fullname,
+            package=metadata["package"],
+            token=token,
+            build_id=_build.BUILD_ID,
+            python_tag=_build.PYTHON_TAG,
+        )
+        try:
+            from cryptography.exceptions import InvalidTag
+            from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+        except ImportError as exc:  # pragma: no cover - installation dependent
+            _fail("the 'cryptography' package is required", cause=exc)
+        try:
+            compressed = AESGCM(key).decrypt(nonce, ciphertext, aad)
+        except InvalidTag as exc:
+            raise IntegrityError(
+                f"pyencode runtime: authentication failed for module {fullname!r}"
+            ) from exc
+        marshalled = _decompress_strict(
+            compressed, _MAX_MARSHALLED_SIZE, f"module payload for {fullname!r}"
+        )
+        try:
+            code = marshal.loads(marshalled)
+        except (EOFError, TypeError, ValueError) as exc:
+            _fail(f"invalid marshalled code for module {fullname!r}", cause=exc)
+        if not isinstance(code, types.CodeType):
+            _fail(f"payload for module {fullname!r} is not a Python code object")
+        exec(code, namespace)
+
+    def _resolved_entry(self) -> tuple[str, dict[str, Any]]:
+        entry = self._entry
+        metadata = self._metadata(entry)
+        if metadata["package"]:
+            candidate = f"{entry}.__main__"
+            if candidate not in self._modules:
+                _fail(f"entry package {entry!r} has no protected __main__ module")
+            entry = candidate
+            metadata = self._metadata(entry)
+        return entry, metadata
+
+    def _protected_entry_names(self) -> frozenset[str]:
+        entry, _metadata = self._resolved_entry()
+        return frozenset({self._entry, entry})
+
+    def _prepare_parent(self, entry: str) -> str:
+        parent = entry.rpartition(".")[0]
+        if not parent:
+            return ""
+        parts = parent.split(".")
+        for end in range(1, len(parts) + 1):
+            name = ".".join(parts[:end])
+            child_name = name + ".__pyencode_child__"
+            existing = sys.modules.get(name)
+            if existing is not None:
+                locations = getattr(existing, "__path__", None)
+                if not self._parent_path_represented(child_name, locations):
+                    raise IntegrityError(
+                        f"pyencode runtime: parent package {name!r} for {entry!r} "
+                        "does not include the protected distribution path"
+                    )
+                continue
+
+            try:
+                spec = importlib.util.find_spec(name)
+            except (ImportError, AttributeError, ValueError) as exc:
+                raise IntegrityError(
+                    f"pyencode runtime: cannot resolve parent package {name!r} "
+                    f"for {entry!r}"
+                ) from exc
+            locations = None if spec is None else spec.submodule_search_locations
+            if not self._parent_path_represented(child_name, locations):
+                raise IntegrityError(
+                    f"pyencode runtime: parent package {name!r} for {entry!r} "
+                    "does not include the protected distribution path"
+                )
+            importlib.import_module(name)
+        return parent
+
+    def _multiprocessing_main(self, namespace: dict[str, Any]) -> None:
+        entry, metadata = self._resolved_entry()
+        parent = self._prepare_parent(entry)
+        loader = _ProtectedLoader(self, entry)
+        artifact = self._artifact_path(entry)
+        spec = importlib.util.spec_from_loader(
+            entry,
+            loader,
+            origin=str(artifact),
+            is_package=bool(metadata["package"]),
+        )
+        spec.has_location = True
+        namespace.update(
+            {
+                "__file__": str(artifact),
+                "__cached__": None,
+                "__loader__": loader,
+                "__package__": entry if metadata["package"] else parent,
+                "__spec__": spec,
+            }
+        )
+        self._execute(entry, namespace)
+
+    def _run_entry(self) -> dict[str, Any]:
+        entry, metadata = self._resolved_entry()
+        parent = self._prepare_parent(entry)
+        loader = _ProtectedLoader(self, entry)
+        artifact = self._artifact_path(entry)
+        spec = importlib.util.spec_from_loader(
+            entry,
+            loader,
+            origin=str(artifact),
+            is_package=bool(metadata["package"]),
+        )
+        spec.has_location = True
+        namespace: dict[str, Any] = {
+            "__name__": "__main__",
+            "__file__": str(artifact),
+            "__cached__": None,
+            "__loader__": loader,
+            "__package__": entry if metadata["package"] else parent,
+            "__spec__": spec,
+        }
+        main_module = types.ModuleType("__main__")
+        main_module.__dict__.update(namespace)
+        previous_main = sys.modules.get("__main__")
+        previous_argv0 = sys.argv[0] if sys.argv else None
+        sys.modules["__main__"] = main_module
+        if sys.argv:
+            sys.argv[0] = str(artifact)
+        try:
+            self._execute(entry, main_module.__dict__)
+            return main_module.__dict__
+        finally:
+            if previous_main is None:
+                sys.modules.pop("__main__", None)
+            else:
+                sys.modules["__main__"] = previous_main
+            if sys.argv and previous_argv0 is not None:
+                sys.argv[0] = previous_argv0
+
+
+_install_lock = threading.RLock()
+_installed_finder: _ProtectedFinder | None = None
+_multiprocessing_patch_installed = False
+
+
+def _exec_runpy(fullname: str, namespace: dict[str, Any]) -> None:
+    """Execute protected code into runpy's namespace without returning it."""
+
+    finder = _installed_finder
+    if finder is None:
+        _fail("runpy requested a protected module before runtime installation")
+    finder._execute(fullname, namespace)
+
+
+def _multiprocessing_bootstrap(namespace: dict[str, Any]) -> None:
+    """Populate multiprocessing's ``__mp_main__`` with the protected entry."""
+
+    install()
+    finder = _installed_finder
+    if finder is None:  # pragma: no cover - defensive invariant
+        _fail("multiprocessing bootstrap could not install the runtime")
+    finder._multiprocessing_main(namespace)
+
+
+def _validate_preloaded_modules(
+    modules: Mapping[str, Mapping[str, Any]], root: Path, finder: _ProtectedFinder | None
+) -> None:
+    missing = object()
+    protected_names = set(modules)
+    parent_names: set[str] = set()
+    for fullname in protected_names:
+        parts = fullname.split(".")
+        parent_names.update(".".join(parts[:end]) for end in range(1, len(parts)))
+
+    for fullname in sorted(protected_names):
+        existing = sys.modules.get(fullname, missing)
+        if existing is missing:
+            continue
+        spec = getattr(existing, "__spec__", None)
+        loader = getattr(spec, "loader", None)
+        if (
+            finder is not None
+            and isinstance(loader, _ProtectedLoader)
+            and loader._finder is finder
+            and loader._fullname == fullname
+            and getattr(spec, "name", None) == fullname
+            and getattr(existing, "__loader__", None) is loader
+            and getattr(spec, "origin", None) == str(finder._artifact_path(fullname))
+        ):
+            continue
+        raise IntegrityError(
+            f"pyencode runtime: protected module {fullname!r} was preloaded "
+            "outside the verified finder"
+        )
+
+    for parent in sorted(parent_names.difference(protected_names)):
+        existing = sys.modules.get(parent, missing)
+        if existing is missing:
+            continue
+        expected = root.joinpath(*parent.split(".")).resolve()
+        locations = getattr(existing, "__path__", None)
+        represented = False
+        if locations is not None:
+            for raw_location in locations:
+                try:
+                    if Path(raw_location).resolve() == expected:
+                        represented = True
+                        break
+                except (OSError, TypeError, ValueError):
+                    continue
+        if not represented:
+            raise IntegrityError(
+                f"pyencode runtime: protected parent namespace {parent!r} was "
+                "preloaded outside the verified distribution"
+            )
+
+
+def _enable_multiprocessing_bootstrap() -> None:
+    global _multiprocessing_patch_installed
+    if _multiprocessing_patch_installed:
+        return
+    try:
+        import multiprocessing.spawn as spawn
+    except ImportError:  # pragma: no cover - CPython always ships multiprocessing
+        return
+    original = spawn.get_preparation_data
+
+    def protected_preparation_data(name):
+        data = original(name)
+        finder = _installed_finder
+        initial_name = data.get("init_main_from_name")
+        if finder is not None and initial_name in finder._protected_entry_names():
+            data.pop("init_main_from_path", None)
+            data["init_main_from_name"] = "pyencode_runtime._mp_main"
+        return data
+
+    spawn.get_preparation_data = protected_preparation_data
+    # This is consumed when a fresh spawn interpreter starts, before it imports
+    # the signed runtime package and could otherwise create an unsigned cache.
+    os.environ["PYTHONDONTWRITEBYTECODE"] = "1"
+    _multiprocessing_patch_installed = True
+
+
+def _verified_build_state() -> tuple[
+    dict[str, Any],
+    str,
+    dict[str, dict[str, Any]],
+    dict[str, str],
+    Path,
+    bytes,
+    bytes,
+    bytes,
+]:
+    build_id = _validate_build_config()
+    payload, root = _read_manifest()
+    inventory, directories = _scan_distribution(root)
+    artifacts, nonce, ciphertext, index_commitment = _validate_manifest(
+        payload, build_id
+    )
+    allow_extra_data = _allow_extra_data(payload)
+    support_commitment, signed_paths = _validate_bound_files(payload, root, inventory)
+    embedded = _embedded_master_key(build_id)
+    try:
+        support_root = _derive_support_root(embedded, build_id, support_commitment)
+        entry, modules = _decrypt_index(nonce, ciphertext, support_root, build_id)
+    finally:
+        for index in range(len(embedded)):
+            embedded[index] = 0
+    if {metadata["artifact"] for metadata in modules.values()} != set(artifacts):
+        _fail("artifact token set does not match decrypted module index")
+    _validate_artifacts(
+        root,
+        modules,
+        artifacts,
+        inventory,
+        directories,
+        signed_paths,
+        allow_extra_data,
+    )
+    return (
+        payload,
+        entry,
+        modules,
+        artifacts,
+        root,
+        build_id,
+        support_commitment,
+        index_commitment,
+    )
+
+
+def install() -> None:
+    """Verify this distribution and install its exec-only import hook.
+
+    Repeated calls fully revalidate signed support files and encrypted metadata.
+    The function intentionally returns no finder or key-bearing state.
+    """
+
+    global _installed_finder
+    with _install_lock:
+        (
+            payload,
+            entry,
+            modules,
+            artifacts,
+            root,
+            build_id,
+            support_commitment,
+            index_commitment,
+        ) = _verified_build_state()
+        _validate_preloaded_modules(modules, root, _installed_finder)
+        if _installed_finder is not None:
+            finder = _installed_finder
+            stable = (
+                finder._entry == entry
+                and finder._modules == modules
+                and finder._artifacts == artifacts
+                and finder._root == root
+                and finder._build_id == build_id
+                and finder._support_commitment == support_commitment
+                and finder._index_commitment == index_commitment
+            )
+            if not stable:
+                raise IntegrityError(
+                    "pyencode runtime: verified build state changed after installation"
+                )
+            finder._payload = payload
+            if finder not in sys.meta_path:
+                sys.meta_path.insert(0, finder)
+            _enable_multiprocessing_bootstrap()
+            return None
+        finder = _ProtectedFinder(
+            payload,
+            entry,
+            modules,
+            artifacts,
+            root,
+            build_id,
+            support_commitment,
+            index_commitment,
+        )
+        sys.meta_path.insert(0, finder)
+        _installed_finder = finder
+        _enable_multiprocessing_bootstrap()
+        return None
+
+
+def run() -> dict[str, Any]:
+    """Verify, install, and execute the encrypted entry as ``__main__``."""
+
+    install()
+    finder = _installed_finder
+    if finder is None:  # pragma: no cover - defensive invariant
+        _fail("protected-module finder was not installed")
+    return finder._run_entry()
+
+
+def load_entry() -> types.ModuleType:
+    """Verify, install, and import the encrypted entry for an embedding host."""
+
+    install()
+    finder = _installed_finder
+    if finder is None:  # pragma: no cover - defensive invariant
+        _fail("protected-module finder was not installed")
+    return importlib.import_module(finder._entry)
+
+
+__all__ = [
+    "CompatibilityError",
+    "IntegrityError",
+    "PolicyError",
+    "PyEncodeRuntimeError",
+    "install",
+    "load_entry",
+    "run",
+]