fdai-deployment-cli 0.1.2__py3-none-any.whl

fdai_deployment_cli/offline_kit.py

@@ -0,0 +1,797 @@
+"""Signed, exact-file-set offline kit construction and verification."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import platform
+import re
+import stat
+import sys
+import sysconfig
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path, PurePosixPath
+from typing import Final
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+from cryptography.hazmat.primitives.serialization import load_pem_public_key
+
+from fdai_deployment_cli.contracts import canonical_bytes, load_json_object
+
+MANIFEST_NAME: Final = "offline-kit.json"
+SIGNATURE_NAME: Final = "offline-kit.json.sig"
+ROOT_MANIFEST_NAME: Final = "deployment-root.json"
+ROOT_SIGNATURE_NAME: Final = "deployment-root.json.sig"
+ROOT_SCHEMA_VERSION: Final = "fdai.deployment-root.v1"
+_MAX_MANIFEST_BYTES = 4 * 1024 * 1024
+_MAX_FILES = 20_000
+_MAX_FILE_BYTES = 512 * 1024 * 1024
+_MAX_TOTAL_BYTES = 8 * 1024 * 1024 * 1024
+_DIGEST = re.compile(r"^[0-9a-f]{64}$")
+_PROFILE_ID = re.compile(r"^[a-z][a-z0-9._-]{0,127}$")
+_PROFILE_NAME = re.compile(r"^[a-z][a-z0-9._-]{0,127}$")
+_LIBC_TAG = re.compile(
+    r"^(?P<name>[a-z0-9._-]+)-(?P<major>[0-9]+)\.(?P<minor>[0-9]+)"
+    r"(?:\.(?P<patch>[0-9]+))?$"
+)
+_PROFILE_CLOSURES: Final = frozenset({"connected", "offline", "appliance"})
+
+
+class OfflineKitVerificationError(ValueError):
+    """The offline kit failed trust, compatibility, or content checks."""
+
+
+@dataclass(frozen=True, slots=True)
+class OfflineKitVerification:
+    """Sanitized result of a successful kit verification."""
+
+    kit_version: str
+    cli_version: str
+    bundle_version: str
+    platform_tag: str
+    python_tag: str
+    libc_tag: str
+    file_count: int
+    total_bytes: int
+    manifest_digest: str
+    deployment_root_required: bool
+    terraform_binary: str
+    provider_mirror_prefix: str
+    deployment_bundle: str
+    rule_activation_profile: str | None
+    rule_activation_profile_id: str | None
+    rule_activation_profile_created_at: str | None
+    file_digests: tuple[tuple[str, str], ...]
+    file_sizes: tuple[tuple[str, int], ...]
+
+    def to_json(self) -> str:
+        """Return stable, non-secret machine output."""
+
+        return json.dumps(
+            {
+                "schema_version": "fdai.offline-kit-verification.v1",
+                "kit_version": self.kit_version,
+                "cli_version": self.cli_version,
+                "bundle_version": self.bundle_version,
+                "platform_tag": self.platform_tag,
+                "python_tag": self.python_tag,
+                "libc_tag": self.libc_tag,
+                "file_count": self.file_count,
+                "total_bytes": self.total_bytes,
+                "manifest_digest": self.manifest_digest,
+                "deployment_root_required": self.deployment_root_required,
+            },
+            sort_keys=True,
+            separators=(",", ":"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class RootManifestVerification:
+    """Sanitized result of a successful deployment-root verification."""
+
+    schema_version: str
+    profiles: tuple[str, ...]
+    kit_manifest_digest: str
+
+    def to_json(self) -> str:
+        return json.dumps(
+            {
+                "schema_version": "fdai.deployment-root-verification.v1",
+                "manifest_schema_version": self.schema_version,
+                "profiles": list(self.profiles),
+                "kit_manifest_digest": self.kit_manifest_digest,
+            },
+            sort_keys=True,
+            separators=(",", ":"),
+        )
+
+
+def build_offline_kit_manifest(
+    root: Path,
+    *,
+    kit_version: str,
+    cli_version: str,
+    bundle_version: str,
+    platform_tag: str,
+    python_wheel: str,
+    deployment_bundle: str,
+    terraform_binary: str,
+    provider_mirror_prefix: str,
+    opa_binary: str,
+    sbom_path: str,
+    rule_activation_profile: str | None = None,
+    rule_activation_profile_id: str | None = None,
+    rule_activation_profile_created_at: str | None = None,
+    python_tag: str | None = None,
+    libc_tag: str | None = None,
+    deployment_root_required: bool = False,
+) -> bytes:
+    """Build canonical manifest bytes from the exact staged tree."""
+
+    required = {
+        "python_wheel": _relative_path(python_wheel),
+        "deployment_bundle": _relative_path(deployment_bundle),
+        "terraform_binary": _relative_path(terraform_binary),
+        "provider_mirror_prefix": _relative_path(provider_mirror_prefix),
+        "opa_binary": _relative_path(opa_binary),
+        "sbom_path": _relative_path(sbom_path),
+    }
+    activation_profile = (
+        _relative_path(rule_activation_profile) if rule_activation_profile is not None else None
+    )
+    if activation_profile is not None and not activation_profile.startswith("rule-activation/"):
+        raise OfflineKitVerificationError(
+            "offline kit Rule activation profile MUST be under rule-activation/"
+        )
+    profile_values = (
+        activation_profile,
+        rule_activation_profile_id,
+        rule_activation_profile_created_at,
+    )
+    if any(value is None for value in profile_values) and any(
+        value is not None for value in profile_values
+    ):
+        raise OfflineKitVerificationError(
+            "offline kit Rule activation profile path, id, and time MUST be supplied together"
+        )
+    if (
+        rule_activation_profile_id is not None
+        and _PROFILE_ID.fullmatch(rule_activation_profile_id) is None
+    ):
+        raise OfflineKitVerificationError("offline kit Rule activation profile id is invalid")
+    if rule_activation_profile_created_at is not None:
+        _absolute_timestamp(
+            rule_activation_profile_created_at,
+            "offline kit Rule activation profile time",
+        )
+    if not required["python_wheel"].startswith("python/"):
+        raise OfflineKitVerificationError("offline kit Python wheel MUST be under python/")
+    files, _sizes, _total = _scan_tree(root)
+    for label in (
+        "python_wheel",
+        "deployment_bundle",
+        "terraform_binary",
+        "opa_binary",
+        "sbom_path",
+    ):
+        if required[label] not in files:
+            raise OfflineKitVerificationError(f"offline kit is missing {label}")
+    if activation_profile is not None and activation_profile not in files:
+        raise OfflineKitVerificationError("offline kit is missing rule_activation_profile")
+    prefix = required["provider_mirror_prefix"].rstrip("/") + "/"
+    if not any(path.startswith(prefix) for path in files):
+        raise OfflineKitVerificationError("offline kit provider mirror is empty")
+    payload: dict[str, object] = {
+        "schema_version": "fdai.offline-kit.v1",
+        "kit_version": kit_version,
+        "cli_version": cli_version,
+        "bundle_version": bundle_version,
+        "platform_tag": platform_tag,
+        "python_tag": python_tag or _runtime_python_tag(),
+        "libc_tag": libc_tag or _runtime_libc_tag(),
+        **required,
+        "files": files,
+    }
+    if activation_profile is not None:
+        payload["rule_activation_profile"] = activation_profile
+        payload["rule_activation_profile_id"] = rule_activation_profile_id
+        payload["rule_activation_profile_created_at"] = rule_activation_profile_created_at
+    if deployment_root_required:
+        payload["deployment_root_required"] = True
+    return canonical_bytes(payload)
+
+
+def build_root_manifest(
+    *,
+    kit_manifest_digest: str,
+    profiles: set[str] | list[str] | tuple[str, ...],
+) -> bytes:
+    """Build a canonical signed-root payload for supported artifact profiles."""
+
+    if _DIGEST.fullmatch(kit_manifest_digest) is None:
+        raise OfflineKitVerificationError("deployment root offline-kit digest is invalid")
+    profile_items = tuple(sorted(dict.fromkeys(profiles)))
+    if not profile_items:
+        raise OfflineKitVerificationError("deployment root profiles MUST be non-empty")
+    if any(item not in _PROFILE_CLOSURES for item in profile_items):
+        raise OfflineKitVerificationError("deployment root profiles contain an unsupported value")
+    return canonical_bytes(
+        {
+            "schema_version": ROOT_SCHEMA_VERSION,
+            "kit_manifest_digest": kit_manifest_digest,
+            "profiles": list(profile_items),
+        }
+    )
+
+
+def verify_root_manifest(
+    root: Path,
+    *,
+    release_root_pem: bytes,
+    expected_profile: str | None = None,
+) -> RootManifestVerification:
+    """Verify the deployment root and its exact legacy kit-manifest binding."""
+
+    manifest_path = root / ROOT_MANIFEST_NAME
+    signature_path = root / ROOT_SIGNATURE_NAME
+    manifest = _read_regular(manifest_path, _MAX_MANIFEST_BYTES)
+    signature = _read_regular(signature_path, 64)
+    if len(signature) != 64:
+        raise OfflineKitVerificationError("deployment root signature MUST be 64 bytes")
+    _verify_signature(release_root_pem, manifest, signature)
+    payload = load_json_object(
+        manifest,
+        label="deployment root manifest",
+        max_bytes=_MAX_MANIFEST_BYTES,
+    )
+    if set(payload) != {"schema_version", "kit_manifest_digest", "profiles"}:
+        raise OfflineKitVerificationError("deployment root manifest schema does not match")
+    if payload["schema_version"] != ROOT_SCHEMA_VERSION:
+        raise OfflineKitVerificationError("deployment root manifest schema does not match")
+    if canonical_bytes(payload) != manifest:
+        raise OfflineKitVerificationError("deployment root manifest is not canonical")
+
+    kit_manifest_digest = payload["kit_manifest_digest"]
+    if not isinstance(kit_manifest_digest, str) or _DIGEST.fullmatch(kit_manifest_digest) is None:
+        raise OfflineKitVerificationError("deployment root offline-kit digest is invalid")
+    observed_kit_digest = hashlib.sha256(
+        _read_regular(root / MANIFEST_NAME, _MAX_MANIFEST_BYTES)
+    ).hexdigest()
+    if kit_manifest_digest != observed_kit_digest:
+        raise OfflineKitVerificationError("deployment root offline-kit digest does not match")
+
+    raw_profiles = payload["profiles"]
+    if not isinstance(raw_profiles, list) or not raw_profiles:
+        raise OfflineKitVerificationError("deployment root profiles MUST be a non-empty list")
+    profiles: list[str] = []
+    for item in raw_profiles:
+        if not isinstance(item, str) or item not in _PROFILE_CLOSURES:
+            raise OfflineKitVerificationError(
+                "deployment root profiles contain an unsupported value"
+            )
+        if item in profiles:
+            raise OfflineKitVerificationError("deployment root profiles MUST be unique")
+        profiles.append(item)
+    if profiles != sorted(profiles):
+        raise OfflineKitVerificationError("deployment root profiles MUST be sorted")
+    if expected_profile is not None:
+        if _PROFILE_NAME.fullmatch(expected_profile) is None:
+            raise OfflineKitVerificationError("deployment root expected profile is invalid")
+        if expected_profile not in profiles:
+            raise OfflineKitVerificationError("deployment root expected profile is not in profiles")
+    return RootManifestVerification(
+        schema_version=ROOT_SCHEMA_VERSION,
+        profiles=tuple(profiles),
+        kit_manifest_digest=kit_manifest_digest,
+    )
+
+
+def verify_offline_kit(
+    root: Path,
+    *,
+    release_root_pem: bytes,
+    cli_version: str,
+    platform_tag: str,
+    python_tag: str | None = None,
+    libc_tag: str | None = None,
+) -> OfflineKitVerification:
+    """Verify signature before parsing, then compatibility, exact files, and digests."""
+
+    manifest_path = root / MANIFEST_NAME
+    signature_path = root / SIGNATURE_NAME
+    manifest = _read_regular(manifest_path, _MAX_MANIFEST_BYTES)
+    signature = _read_regular(signature_path, 64)
+    if len(signature) != 64:
+        raise OfflineKitVerificationError("offline kit signature MUST be 64 bytes")
+    _verify_signature(release_root_pem, manifest, signature)
+    try:
+        payload = load_json_object(
+            manifest,
+            label="offline kit manifest",
+            max_bytes=_MAX_MANIFEST_BYTES,
+        )
+        expected = {
+            "schema_version",
+            "kit_version",
+            "cli_version",
+            "bundle_version",
+            "platform_tag",
+            "python_tag",
+            "libc_tag",
+            "python_wheel",
+            "deployment_bundle",
+            "terraform_binary",
+            "provider_mirror_prefix",
+            "opa_binary",
+            "sbom_path",
+            "files",
+        }
+        activation_fields = {
+            "rule_activation_profile",
+            "rule_activation_profile_id",
+            "rule_activation_profile_created_at",
+        }
+        allowed = expected | activation_fields | {"deployment_root_required"}
+        keys = set(payload)
+        if (
+            not expected.issubset(keys)
+            or not keys.issubset(allowed)
+            or (keys & activation_fields and not activation_fields.issubset(keys))
+            or payload["schema_version"] != "fdai.offline-kit.v1"
+        ):
+            raise OfflineKitVerificationError("offline kit manifest schema does not match")
+        deployment_root_required = payload.get("deployment_root_required", False)
+        if not isinstance(deployment_root_required, bool):
+            raise OfflineKitVerificationError("offline kit deployment root requirement is invalid")
+        if payload["cli_version"] != cli_version:
+            raise OfflineKitVerificationError("offline kit CLI version does not match")
+        if payload["platform_tag"] != platform_tag:
+            raise OfflineKitVerificationError("offline kit platform does not match")
+        if payload["python_tag"] != (python_tag or _runtime_python_tag()):
+            raise OfflineKitVerificationError("offline kit Python ABI does not match")
+        _require_compatible_libc(
+            _payload_text(payload, "libc_tag"),
+            libc_tag or _runtime_libc_tag(),
+        )
+        files_value = payload["files"]
+        if not isinstance(files_value, dict) or not files_value:
+            raise OfflineKitVerificationError("offline kit files MUST be a non-empty object")
+        declared: dict[str, str] = {}
+        for raw_path, raw_digest in files_value.items():
+            if not isinstance(raw_path, str) or not isinstance(raw_digest, str):
+                raise OfflineKitVerificationError("offline kit file entries are invalid")
+            path = _relative_path(raw_path)
+            if _DIGEST.fullmatch(raw_digest) is None:
+                raise OfflineKitVerificationError("offline kit file digest is invalid")
+            declared[path] = raw_digest
+        required_paths = (
+            "python_wheel",
+            "deployment_bundle",
+            "terraform_binary",
+            "opa_binary",
+            "sbom_path",
+        )
+        for field in required_paths:
+            value = payload[field]
+            if not isinstance(value, str) or _relative_path(value) not in declared:
+                raise OfflineKitVerificationError(f"offline kit {field} is not declared")
+        activation_profile_value = payload.get("rule_activation_profile")
+        activation_profile_id_value = payload.get("rule_activation_profile_id")
+        activation_profile_time_value = payload.get("rule_activation_profile_created_at")
+        activation_profile = None
+        activation_profile_id = None
+        activation_profile_created_at = None
+        if activation_profile_value is not None:
+            if not isinstance(activation_profile_value, str):
+                raise OfflineKitVerificationError(
+                    "offline kit Rule activation profile path is invalid"
+                )
+            activation_profile = _relative_path(activation_profile_value)
+            if (
+                not activation_profile.startswith("rule-activation/")
+                or activation_profile not in declared
+            ):
+                raise OfflineKitVerificationError(
+                    "offline kit Rule activation profile is not declared"
+                )
+            if (
+                not isinstance(activation_profile_id_value, str)
+                or _PROFILE_ID.fullmatch(activation_profile_id_value) is None
+            ):
+                raise OfflineKitVerificationError(
+                    "offline kit Rule activation profile id is invalid"
+                )
+            activation_profile_id = activation_profile_id_value
+            if not isinstance(activation_profile_time_value, str):
+                raise OfflineKitVerificationError(
+                    "offline kit Rule activation profile time is invalid"
+                )
+            _absolute_timestamp(
+                activation_profile_time_value,
+                "offline kit Rule activation profile time",
+            )
+            activation_profile_created_at = activation_profile_time_value
+        elif activation_profile_id_value is not None or activation_profile_time_value is not None:
+            raise OfflineKitVerificationError(
+                "offline kit Rule activation profile id has no profile artifact"
+            )
+        if not _payload_text(payload, "python_wheel").startswith("python/"):
+            raise OfflineKitVerificationError("offline kit Python wheel MUST be under python/")
+        prefix_value = payload["provider_mirror_prefix"]
+        if not isinstance(prefix_value, str):
+            raise OfflineKitVerificationError("offline kit provider mirror prefix is invalid")
+        prefix = _relative_path(prefix_value).rstrip("/") + "/"
+        if not any(path.startswith(prefix) for path in declared):
+            raise OfflineKitVerificationError("offline kit provider mirror is empty")
+        observed, sizes, total = _scan_tree(root)
+        if observed != declared:
+            raise OfflineKitVerificationError("offline kit exact file set or digest does not match")
+        _verify_sbom(root, payload, declared)
+        if canonical_bytes(payload) != manifest:
+            raise OfflineKitVerificationError("offline kit manifest is not canonical")
+        if (
+            deployment_root_required
+            or os.path.lexists(root / ROOT_MANIFEST_NAME)
+            or os.path.lexists(root / ROOT_SIGNATURE_NAME)
+        ):
+            verify_root_manifest(
+                root,
+                release_root_pem=release_root_pem,
+            )
+        return OfflineKitVerification(
+            kit_version=_payload_text(payload, "kit_version"),
+            cli_version=_payload_text(payload, "cli_version"),
+            bundle_version=_payload_text(payload, "bundle_version"),
+            platform_tag=_payload_text(payload, "platform_tag"),
+            python_tag=_payload_text(payload, "python_tag"),
+            libc_tag=_payload_text(payload, "libc_tag"),
+            file_count=len(observed),
+            total_bytes=total,
+            manifest_digest=hashlib.sha256(manifest).hexdigest(),
+            deployment_root_required=deployment_root_required,
+            terraform_binary=_payload_text(payload, "terraform_binary"),
+            provider_mirror_prefix=_payload_text(payload, "provider_mirror_prefix"),
+            deployment_bundle=_payload_text(payload, "deployment_bundle"),
+            rule_activation_profile=activation_profile,
+            rule_activation_profile_id=activation_profile_id,
+            rule_activation_profile_created_at=activation_profile_created_at,
+            file_digests=tuple(sorted(declared.items())),
+            file_sizes=tuple(sorted(sizes.items())),
+        )
+    except OfflineKitVerificationError:
+        raise
+    except (KeyError, TypeError, ValueError) as exc:
+        raise OfflineKitVerificationError("offline kit manifest is invalid") from exc
+
+
+def _scan_tree(root: Path) -> tuple[dict[str, str], dict[str, int], int]:
+    if root.is_symlink() or not root.is_dir():
+        raise OfflineKitVerificationError("offline kit root MUST be a directory")
+    files: dict[str, str] = {}
+    sizes: dict[str, int] = {}
+    total = 0
+    for directory, directories, names in os.walk(root, followlinks=False):
+        base = Path(directory)
+        for name in directories:
+            candidate = base / name
+            if candidate.is_symlink():
+                raise OfflineKitVerificationError("offline kit MUST NOT contain symlinks")
+        for name in names:
+            candidate = base / name
+            relative = candidate.relative_to(root).as_posix()
+            if relative in {
+                MANIFEST_NAME,
+                SIGNATURE_NAME,
+                ROOT_MANIFEST_NAME,
+                ROOT_SIGNATURE_NAME,
+            }:
+                continue
+            if candidate.is_symlink():
+                raise OfflineKitVerificationError("offline kit MUST NOT contain symlinks")
+            if len(files) >= _MAX_FILES:
+                raise OfflineKitVerificationError("offline kit exceeds its file count limit")
+            details = candidate.lstat()
+            if not stat.S_ISREG(details.st_mode):
+                raise OfflineKitVerificationError("offline kit MUST contain only regular files")
+            if details.st_size > _MAX_FILE_BYTES:
+                raise OfflineKitVerificationError("offline kit file exceeds its size limit")
+            total += details.st_size
+            if total > _MAX_TOTAL_BYTES:
+                raise OfflineKitVerificationError("offline kit exceeds its total size limit")
+            files[relative] = _sha256_nofollow(candidate, expected=details)
+            sizes[relative] = details.st_size
+    return dict(sorted(files.items())), dict(sorted(sizes.items())), total
+
+
+@dataclass(frozen=True, slots=True)
+class MaterializedOfflineArtifacts:
+    """Private verified copies used after kit verification."""
+
+    terraform_binary: Path
+    provider_mirror: Path
+    deployment_bundle: Path
+    python_wheels: Path
+
+
+def materialize_verified_artifacts(
+    root: Path,
+    verification: OfflineKitVerification,
+    destination: Path,
+    *,
+    include_all: bool = False,
+) -> MaterializedOfflineArtifacts:
+    """Snapshot signed inputs, optionally including the complete release payload."""
+
+    if destination.exists():
+        raise OfflineKitVerificationError("offline artifact destination already exists")
+    destination.mkdir(parents=True, mode=0o700)
+    destination.chmod(0o700)
+    digests = dict(verification.file_digests)
+    sizes = dict(verification.file_sizes)
+    prefix = verification.provider_mirror_prefix.rstrip("/") + "/"
+    python_prefix = "python/"
+    selected = {
+        verification.terraform_binary,
+        verification.deployment_bundle,
+        *(path for path in digests if path.startswith(prefix)),
+        *(path for path in digests if path.startswith(python_prefix)),
+    }
+    if include_all:
+        selected = set(digests)
+    total_bytes = 0
+    for relative in sorted(selected):
+        expected = digests.get(relative)
+        expected_size = sizes.get(relative)
+        if expected is None or expected_size is None:
+            raise OfflineKitVerificationError("verified offline artifact is not declared")
+        total_bytes += expected_size
+        if total_bytes > _MAX_TOTAL_BYTES:
+            raise OfflineKitVerificationError("offline artifact snapshot exceeds its size limit")
+        target = destination / relative
+        target.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        _copy_verified_file(
+            root / relative,
+            target,
+            expected_digest=expected,
+            expected_size=expected_size,
+        )
+    terraform = destination / verification.terraform_binary
+    terraform.chmod(0o700)
+    # Pinned kubectl, kubelogin, and opa run from bin/ on the execution host.
+    for tool in sorted((destination / "bin").glob("*")):
+        if tool.is_file() and not tool.is_symlink():
+            tool.chmod(0o700)
+    return MaterializedOfflineArtifacts(
+        terraform_binary=terraform,
+        provider_mirror=destination / verification.provider_mirror_prefix,
+        deployment_bundle=destination / verification.deployment_bundle,
+        python_wheels=destination / "python",
+    )
+
+
+def _copy_verified_file(
+    source: Path,
+    target: Path,
+    *,
+    expected_digest: str,
+    expected_size: int,
+) -> None:
+    details = source.lstat()
+    if not stat.S_ISREG(details.st_mode) or details.st_size != expected_size:
+        raise OfflineKitVerificationError("verified offline artifact size changed")
+    if expected_size > _MAX_FILE_BYTES:
+        raise OfflineKitVerificationError("verified offline artifact exceeds its size limit")
+    descriptor = os.open(source, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+    output_descriptor = os.open(
+        target,
+        os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW,
+        0o600,
+    )
+    digest = hashlib.sha256()
+    copied = 0
+    try:
+        with (
+            os.fdopen(descriptor, "rb") as input_stream,
+            os.fdopen(output_descriptor, "wb") as output_stream,
+        ):
+            opened = os.fstat(input_stream.fileno())
+            _require_same_file(details, opened)
+            for chunk in iter(lambda: input_stream.read(1024 * 1024), b""):
+                copied += len(chunk)
+                if copied > expected_size:
+                    raise OfflineKitVerificationError("verified offline artifact size changed")
+                digest.update(chunk)
+                output_stream.write(chunk)
+            output_stream.flush()
+            os.fsync(output_stream.fileno())
+            _require_same_file(opened, os.fstat(input_stream.fileno()))
+    except BaseException:
+        target.unlink(missing_ok=True)
+        raise
+    if digest.hexdigest() != expected_digest:
+        target.unlink(missing_ok=True)
+        raise OfflineKitVerificationError("verified offline artifact digest changed")
+    if copied != expected_size:
+        target.unlink(missing_ok=True)
+        raise OfflineKitVerificationError("verified offline artifact size changed")
+
+
+def _sha256_nofollow(path: Path, *, expected: os.stat_result) -> str:
+    descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+    digest = hashlib.sha256()
+    copied = 0
+    with os.fdopen(descriptor, "rb") as stream:
+        opened = os.fstat(stream.fileno())
+        _require_same_file(expected, opened)
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            copied += len(chunk)
+            if copied > expected.st_size:
+                raise OfflineKitVerificationError("offline kit file grew during verification")
+            digest.update(chunk)
+        _require_same_file(opened, os.fstat(stream.fileno()))
+    if copied != expected.st_size:
+        raise OfflineKitVerificationError("offline kit file size changed during verification")
+    return digest.hexdigest()
+
+
+def _require_same_file(expected: os.stat_result, observed: os.stat_result) -> None:
+    if (
+        not stat.S_ISREG(observed.st_mode)
+        or expected.st_dev != observed.st_dev
+        or expected.st_ino != observed.st_ino
+        or expected.st_size != observed.st_size
+        or expected.st_mtime_ns != observed.st_mtime_ns
+    ):
+        raise OfflineKitVerificationError("offline kit file changed during verification")
+
+
+def _read_regular(path: Path, maximum: int) -> bytes:
+    try:
+        details = path.lstat()
+    except OSError as exc:
+        raise OfflineKitVerificationError("offline kit metadata is unavailable") from exc
+    if not stat.S_ISREG(details.st_mode) or details.st_size > maximum:
+        raise OfflineKitVerificationError("offline kit metadata is invalid")
+    descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+    with os.fdopen(descriptor, "rb") as stream:
+        opened = os.fstat(stream.fileno())
+        _require_same_file(details, opened)
+        payload = stream.read(maximum + 1)
+        _require_same_file(opened, os.fstat(stream.fileno()))
+        return payload
+
+
+def _verify_signature(public_pem: bytes, document: bytes, signature: bytes) -> None:
+    try:
+        key = load_pem_public_key(public_pem)
+    except (TypeError, ValueError) as exc:
+        raise OfflineKitVerificationError("offline kit release root is invalid") from exc
+    if not isinstance(key, Ed25519PublicKey):
+        raise OfflineKitVerificationError("offline kit release root MUST be Ed25519")
+    try:
+        key.verify(signature, document)
+    except InvalidSignature as exc:
+        raise OfflineKitVerificationError("offline kit signature is invalid") from exc
+
+
+def _verify_sbom(
+    root: Path,
+    manifest: dict[str, object],
+    declared: dict[str, str],
+) -> None:
+    sbom_value = manifest["sbom_path"]
+    if not isinstance(sbom_value, str):
+        raise OfflineKitVerificationError("offline kit sbom_path is invalid")
+    sbom_path = _relative_path(sbom_value)
+    sbom = load_json_object(
+        _read_regular(root / sbom_path, 16 * 1024 * 1024),
+        label="offline kit SBOM",
+        max_bytes=16 * 1024 * 1024,
+    )
+    if sbom.get("bomFormat") != "CycloneDX" or sbom.get("specVersion") != "1.5":
+        raise OfflineKitVerificationError("offline kit SBOM format is unsupported")
+    components = sbom.get("components")
+    if not isinstance(components, list):
+        raise OfflineKitVerificationError("offline kit SBOM components are invalid")
+    covered: dict[str, str] = {}
+    for component in components:
+        if not isinstance(component, dict):
+            raise OfflineKitVerificationError("offline kit SBOM component is invalid")
+        name = component.get("name")
+        hashes = component.get("hashes")
+        if not isinstance(name, str) or not isinstance(hashes, list):
+            raise OfflineKitVerificationError("offline kit SBOM component is invalid")
+        sha256_values = [
+            item.get("content")
+            for item in hashes
+            if isinstance(item, dict) and item.get("alg") == "SHA-256"
+        ]
+        if len(sha256_values) != 1 or not isinstance(sha256_values[0], str):
+            raise OfflineKitVerificationError("offline kit SBOM SHA-256 is invalid")
+        path = _relative_path(name)
+        if path in covered:
+            raise OfflineKitVerificationError("offline kit SBOM contains duplicate paths")
+        covered[path] = sha256_values[0]
+    expected = {path: digest for path, digest in declared.items() if path != sbom_path}
+    if covered != expected:
+        raise OfflineKitVerificationError("offline kit SBOM coverage does not match")
+
+
+def _relative_path(value: str) -> str:
+    path = PurePosixPath(value)
+    if (
+        not value
+        or value.startswith("/")
+        or "\\" in value
+        or any(part in {"", ".", ".."} for part in path.parts)
+    ):
+        raise OfflineKitVerificationError("offline kit path is invalid")
+    return path.as_posix()
+
+
+def _payload_text(value: dict[str, object], field: str) -> str:
+    item = value[field]
+    if not isinstance(item, str) or not item:
+        raise OfflineKitVerificationError(f"offline kit {field} MUST be text")
+    return item
+
+
+def _absolute_timestamp(value: str, label: str) -> datetime:
+    try:
+        parsed = datetime.fromisoformat(value)
+    except ValueError as exc:
+        raise OfflineKitVerificationError(f"{label} is invalid") from exc
+    if parsed.tzinfo is None or parsed.utcoffset() is None:
+        raise OfflineKitVerificationError(f"{label} MUST be timezone-aware")
+    return parsed
+
+
+def _runtime_python_tag() -> str:
+    soabi = sysconfig.get_config_var("SOABI")
+    if not isinstance(soabi, str) or re.fullmatch(r"[A-Za-z0-9._-]+", soabi) is None:
+        raise OfflineKitVerificationError("runtime Python ABI identity is unavailable")
+    return (
+        f"{sys.implementation.name}-{sys.version_info.major}{sys.version_info.minor}-"
+        f"{soabi.casefold()}"
+    )
+
+
+def _runtime_libc_tag() -> str:
+    name, version = platform.libc_ver()
+    normalized_name = name.casefold().strip()
+    normalized_version = version.casefold().strip()
+    if (
+        re.fullmatch(r"[a-z0-9._-]+", normalized_name) is None
+        or re.fullmatch(r"[a-z0-9._-]+", normalized_version) is None
+    ):
+        raise OfflineKitVerificationError("runtime libc identity is unavailable")
+    return f"{normalized_name}-{normalized_version}"
+
+
+def _require_compatible_libc(required: str, observed: str) -> None:
+    """Require exact non-glibc identity or a glibc runtime at least as new as the kit."""
+
+    if required == observed:
+        return
+    required_match = _LIBC_TAG.fullmatch(required)
+    observed_match = _LIBC_TAG.fullmatch(observed)
+    if (
+        required_match is None
+        or observed_match is None
+        or required_match.group("name") != "glibc"
+        or observed_match.group("name") != "glibc"
+        or _libc_version(observed_match) < _libc_version(required_match)
+    ):
+        raise OfflineKitVerificationError("offline kit libc is incompatible")
+
+
+def _libc_version(match: re.Match[str]) -> tuple[int, int, int]:
+    return (
+        int(match.group("major")),
+        int(match.group("minor")),
+        int(match.group("patch") or 0),
+    )