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

fdai_deployment_cli/private_output.py

@@ -0,0 +1,192 @@
+"""Descriptor-safe writes for private deployment CLI artifacts."""
+
+from __future__ import annotations
+
+import os
+import secrets
+import stat
+from pathlib import Path
+
+_COPY_BUFFER_BYTES = 1024 * 1024
+
+
+def write_private_output(path: Path, content: str) -> None:
+    """Create one mode-0600 artifact through a held mode-0700 parent."""
+
+    write_private_bytes(path, content.encode("utf-8"))
+
+
+def write_private_bytes(path: Path, content: bytes) -> None:
+    """Exclusively persist binary content through a held private parent."""
+
+    directory = _open_private_parent(path)
+    try:
+        descriptor = os.open(
+            path.name,
+            os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW,
+            0o600,
+            dir_fd=directory,
+        )
+        try:
+            with os.fdopen(descriptor, "wb") as stream:
+                stream.write(content)
+                stream.flush()
+                os.fsync(stream.fileno())
+        except BaseException:
+            os.unlink(path.name, dir_fd=directory)
+            raise
+    finally:
+        os.close(directory)
+
+
+def read_private_bytes(path: Path, *, max_bytes: int) -> bytes:
+    """Read bounded current-UID mode-0600 content without following any symlink."""
+
+    if max_bytes <= 0:
+        raise ValueError("private input size bound MUST be positive")
+    directory = _open_private_parent(path)
+    try:
+        descriptor = os.open(
+            path.name, os.O_RDONLY | os.O_NONBLOCK | os.O_NOFOLLOW, dir_fd=directory
+        )
+        with os.fdopen(descriptor, "rb") as stream:
+            details = os.fstat(stream.fileno())
+            if (
+                not stat.S_ISREG(details.st_mode)
+                or stat.S_IMODE(details.st_mode) != 0o600
+                or details.st_uid != os.geteuid()
+                or details.st_nlink != 1
+            ):
+                raise PermissionError(
+                    "private input MUST be a current-UID mode-0600 single-link file"
+                )
+            if not 0 < details.st_size <= max_bytes:
+                raise ValueError("private input is empty or exceeds its size limit")
+            content = stream.read(max_bytes + 1)
+            after = os.fstat(stream.fileno())
+            if (
+                len(content) != details.st_size
+                or after.st_size != details.st_size
+                or after.st_mtime_ns != details.st_mtime_ns
+                or after.st_ctime_ns != details.st_ctime_ns
+            ):
+                raise ValueError("private input changed while being read")
+            return content
+    finally:
+        os.close(directory)
+
+
+def copy_private_file(source: Path, destination: Path, *, max_bytes: int) -> int:
+    """Copy one bounded regular file to a new mode-0600 private destination."""
+
+    if max_bytes <= 0:
+        raise ValueError("private copy size bound MUST be positive")
+    source_parent = _open_private_parent(source)
+    destination_parent = _open_private_parent(destination)
+    try:
+        source_descriptor = os.open(
+            source.name,
+            os.O_RDONLY | os.O_NONBLOCK | os.O_NOFOLLOW,
+            dir_fd=source_parent,
+        )
+        try:
+            source_details = os.fstat(source_descriptor)
+            if (
+                not stat.S_ISREG(source_details.st_mode)
+                or source_details.st_uid != os.geteuid()
+                or source_details.st_nlink != 1
+                or not 0 < source_details.st_size <= max_bytes
+            ):
+                raise PermissionError("private copy source is not an owned bounded regular file")
+            temporary_name = f".{destination.name}.copy-{os.getpid()}-{secrets.token_hex(8)}"
+            destination_descriptor = os.open(
+                temporary_name,
+                os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW,
+                0o600,
+                dir_fd=destination_parent,
+            )
+            copied = 0
+            published = False
+            try:
+                with os.fdopen(source_descriptor, "rb", closefd=False) as input_stream:
+                    with os.fdopen(destination_descriptor, "wb") as output_stream:
+                        while chunk := input_stream.read(_COPY_BUFFER_BYTES):
+                            copied += len(chunk)
+                            if copied > max_bytes:
+                                raise ValueError("private copy source exceeds its size limit")
+                            output_stream.write(chunk)
+                        output_stream.flush()
+                        os.fsync(output_stream.fileno())
+                after = os.fstat(source_descriptor)
+                if (
+                    copied != source_details.st_size
+                    or after.st_size != source_details.st_size
+                    or after.st_mtime_ns != source_details.st_mtime_ns
+                    or after.st_ctime_ns != source_details.st_ctime_ns
+                ):
+                    raise ValueError("private copy source changed while being copied")
+                os.link(
+                    temporary_name,
+                    destination.name,
+                    src_dir_fd=destination_parent,
+                    dst_dir_fd=destination_parent,
+                    follow_symlinks=False,
+                )
+                published = True
+                os.unlink(temporary_name, dir_fd=destination_parent)
+                os.fsync(destination_parent)
+            except BaseException:
+                if published:
+                    try:
+                        os.unlink(destination.name, dir_fd=destination_parent)
+                    except FileNotFoundError:
+                        pass
+                try:
+                    os.unlink(temporary_name, dir_fd=destination_parent)
+                except FileNotFoundError:
+                    pass
+                raise
+            return copied
+        finally:
+            os.close(source_descriptor)
+    finally:
+        os.close(source_parent)
+        os.close(destination_parent)
+
+
+def _open_private_parent(path: Path) -> int:
+    if not path.is_absolute() or path.name in {"", ".", ".."}:
+        raise ValueError("private output path MUST be an absolute file path")
+    descriptor = os.open(path.anchor, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+    trusted_owners = {0, os.geteuid()}
+    try:
+        for part in path.parent.parts[1:]:
+            if part in {"", "."}:
+                continue
+            if part == "..":
+                raise ValueError("private output path MUST NOT traverse parent directories")
+            child = os.open(
+                part,
+                os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW,
+                dir_fd=descriptor,
+            )
+            details = os.fstat(child)
+            if details.st_uid not in trusted_owners:
+                os.close(child)
+                raise PermissionError("private output path has an unsafe owner")
+            mode = stat.S_IMODE(details.st_mode)
+            if mode & 0o022 and not details.st_mode & stat.S_ISVTX:
+                os.close(child)
+                raise PermissionError("private output path has a replaceable ancestor")
+            os.close(descriptor)
+            descriptor = child
+        details = os.fstat(descriptor)
+        mode = stat.S_IMODE(details.st_mode)
+        if details.st_uid != os.geteuid() or mode not in {0o700, 0o2700}:
+            raise PermissionError(
+                "private output directory MUST be current-UID owner-only mode 0700"
+            )
+        return descriptor
+    except BaseException:
+        os.close(descriptor)
+        raise

fdai_deployment_cli/profile.py

@@ -0,0 +1,70 @@
+"""Secure local persistence for secret-free provisioning profiles."""
+
+from __future__ import annotations
+
+import os
+import stat
+from pathlib import Path
+
+from fdai_deployment_cli.contracts import ProvisionProfile, canonical_bytes, load_json_object
+
+
+def write_profile(path: Path, profile: ProvisionProfile, *, force: bool = False) -> None:
+    """Create a private profile atomically without following links."""
+
+    parent = path.parent
+    parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    _require_private_directory(parent)
+    if path.exists() or path.is_symlink():
+        if not force:
+            raise FileExistsError("provision profile already exists")
+        _require_regular_private_file(path)
+    temporary = parent / f".{path.name}.tmp-{os.getpid()}"
+    descriptor = os.open(
+        temporary,
+        os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW,
+        0o600,
+    )
+    try:
+        with os.fdopen(descriptor, "wb") as stream:
+            stream.write(canonical_bytes(profile.to_mapping()) + b"\n")
+            stream.flush()
+            os.fsync(stream.fileno())
+        _publish_profile(temporary, path, force=force)
+        path.chmod(0o600)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def _publish_profile(temporary: Path, destination: Path, *, force: bool) -> None:
+    if force:
+        os.replace(temporary, destination)
+        return
+    os.link(temporary, destination, follow_symlinks=False)
+    temporary.unlink()
+
+
+def load_profile(path: Path) -> ProvisionProfile:
+    """Read and validate a private regular-file profile."""
+
+    descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+    with os.fdopen(descriptor, "rb") as stream:
+        details = os.fstat(stream.fileno())
+        if not stat.S_ISREG(details.st_mode) or stat.S_IMODE(details.st_mode) != 0o600:
+            raise PermissionError("provision profile MUST be a mode-0600 regular file")
+        payload = stream.read(1_048_577)
+    return ProvisionProfile.from_mapping(load_json_object(payload, label="provision profile"))
+
+
+def _require_private_directory(path: Path) -> None:
+    details = path.lstat()
+    if not stat.S_ISDIR(details.st_mode) or stat.S_IMODE(details.st_mode) != 0o700:
+        raise PermissionError("provision profile directory MUST have mode 0700")
+
+
+def _require_regular_private_file(path: Path) -> None:
+    details = path.lstat()
+    if not stat.S_ISREG(details.st_mode):
+        raise PermissionError("provision profile MUST be a regular file")
+    if stat.S_IMODE(details.st_mode) != 0o600:
+        raise PermissionError("provision profile MUST have mode 0600")

fdai_deployment_cli/progress.py

@@ -0,0 +1,183 @@
+"""Monotonic run progress and full-subscription inventory closure."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import StrEnum
+
+
+class ProgressState(StrEnum):
+    """Current progress disposition."""
+
+    RUNNING = "running"
+    WAITING = "waiting"
+    FAILED = "failed"
+    COMPLETE = "complete"
+
+
+@dataclass(frozen=True, slots=True)
+class ProgressSnapshot:
+    """Bounded counters shared by CLI and operator projections."""
+
+    sequence: int
+    state: ProgressState
+    stages_completed: int
+    stages_total: int
+    checkpoints_completed: int
+    checkpoints_total: int
+    started_at: str
+    last_progress_at: str
+    resources_observed: int | None = None
+    resources_expected: int | None = None
+    pages_completed: int | None = None
+    pages_expected: int | None = None
+
+    def __post_init__(self) -> None:
+        if self.sequence < 1:
+            raise ValueError("progress sequence MUST be positive")
+        _bounded_pair(self.stages_completed, self.stages_total, "stages")
+        _bounded_pair(self.checkpoints_completed, self.checkpoints_total, "checkpoints")
+        _optional_pair(self.resources_observed, self.resources_expected, "resources")
+        _optional_pair(self.pages_completed, self.pages_expected, "pages")
+        started = _moment(self.started_at, "started_at")
+        progressed = _moment(self.last_progress_at, "last_progress_at")
+        if progressed < started:
+            raise ValueError("last_progress_at MUST NOT precede started_at")
+        if self.state is ProgressState.COMPLETE and (
+            self.stages_completed != self.stages_total
+            or self.checkpoints_completed != self.checkpoints_total
+        ):
+            raise ValueError("complete progress MUST close every stage and checkpoint")
+
+    @property
+    def fraction(self) -> float:
+        """Return exact work completion, never an elapsed-time estimate."""
+
+        stage_fraction = self.stages_completed / self.stages_total
+        checkpoint_fraction = self.checkpoints_completed / self.checkpoints_total
+        value = (stage_fraction + checkpoint_fraction) / 2
+        return 1.0 if self.state is ProgressState.COMPLETE else min(value, 0.999)
+
+
+def validate_progression(
+    previous: ProgressSnapshot,
+    current: ProgressSnapshot,
+) -> None:
+    """Reject replay, regression, changing totals, and post-terminal progress."""
+
+    if previous.state in {ProgressState.COMPLETE, ProgressState.FAILED}:
+        raise ValueError("terminal progress cannot advance")
+    if current.sequence != previous.sequence + 1:
+        raise ValueError("progress sequence MUST advance by one")
+    if (
+        current.stages_total != previous.stages_total
+        or current.checkpoints_total != previous.checkpoints_total
+    ):
+        raise ValueError("sealed progress totals MUST NOT change")
+    if (
+        current.stages_completed < previous.stages_completed
+        or current.checkpoints_completed < previous.checkpoints_completed
+    ):
+        raise ValueError("progress counters MUST NOT regress")
+    _validate_optional_progression(
+        previous.resources_observed,
+        previous.resources_expected,
+        current.resources_observed,
+        current.resources_expected,
+        "resources",
+    )
+    _validate_optional_progression(
+        previous.pages_completed,
+        previous.pages_expected,
+        current.pages_completed,
+        current.pages_expected,
+        "pages",
+    )
+    if _moment(current.last_progress_at, "last_progress_at") < _moment(
+        previous.last_progress_at,
+        "last_progress_at",
+    ):
+        raise ValueError("progress time MUST NOT regress")
+
+
+@dataclass(frozen=True, slots=True)
+class InventoryClosure:
+    """Independent postconditions required to close genesis inventory."""
+
+    subscription_root: bool
+    resource_type_filter: bool
+    final_fence: bool
+    provider_coverage_complete: bool
+    truncated: bool
+    active_generation_matches: bool
+    overlay_open: bool
+    child_sources_complete: bool
+    observer_distinct: bool
+
+    def blockers(self) -> tuple[str, ...]:
+        """Return stable reasons that keep the initial scan incomplete."""
+
+        reasons: list[str] = []
+        if not self.subscription_root:
+            reasons.append("subscription_root_missing")
+        if self.resource_type_filter:
+            reasons.append("genesis_resource_type_filter_present")
+        if not self.final_fence:
+            reasons.append("final_fence_missing")
+        if not self.provider_coverage_complete:
+            reasons.append("provider_coverage_incomplete")
+        if self.truncated:
+            reasons.append("inventory_truncated")
+        if not self.active_generation_matches:
+            reasons.append("active_generation_mismatch")
+        if self.overlay_open:
+            reasons.append("newer_change_overlay_open")
+        if not self.child_sources_complete:
+            reasons.append("child_source_incomplete")
+        if not self.observer_distinct:
+            reasons.append("observer_not_independent")
+        return tuple(reasons)
+
+    @property
+    def complete(self) -> bool:
+        """Return whether independent inventory closure succeeded."""
+
+        return not self.blockers()
+
+
+def _bounded_pair(completed: int, total: int, label: str) -> None:
+    if total < 1 or not 0 <= completed <= total:
+        raise ValueError(f"{label} progress MUST be within a positive total")
+
+
+def _optional_pair(completed: int | None, total: int | None, label: str) -> None:
+    if (completed is None) != (total is None):
+        raise ValueError(f"{label} progress values MUST be supplied together")
+    if completed is not None and total is not None and (completed < 0 or total < 0):
+        raise ValueError(f"{label} progress values MUST be non-negative")
+
+
+def _validate_optional_progression(
+    previous_completed: int | None,
+    previous_total: int | None,
+    current_completed: int | None,
+    current_total: int | None,
+    label: str,
+) -> None:
+    if previous_completed is None:
+        return
+    if current_completed is None or current_total is None or previous_total is None:
+        raise ValueError(f"{label} progress MUST NOT disappear")
+    if current_completed < previous_completed or current_total < previous_total:
+        raise ValueError(f"{label} progress MUST NOT regress")
+
+
+def _moment(value: str, field: str) -> datetime:
+    try:
+        moment = datetime.fromisoformat(value)
+    except ValueError as exc:
+        raise ValueError(f"{field} MUST be ISO 8601") from exc
+    if moment.tzinfo is None:
+        raise ValueError(f"{field} MUST be timezone-aware")
+    return moment