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

fdai_deployment_cli/foundation_output.py

@@ -0,0 +1,154 @@
+"""Keep Foundation stderr in the existing display without owning subprocess execution."""
+
+from __future__ import annotations
+
+import codecs
+import os
+import select
+import sys
+import threading
+import time
+from collections.abc import Iterator
+from contextlib import ExitStack, contextmanager
+
+from fdai_deployment_cli.foundation_progress import FoundationCheckpoint, FoundationProgressStream
+
+_DRAIN_SECONDS = 1.0
+
+
+class _Reader:
+    """Drain one nonblocking pipe; a display failure cannot backpressure the child forever."""
+
+    def __init__(self, descriptor: int, stream: FoundationProgressStream) -> None:
+        self.descriptor = descriptor
+        self.stream = stream
+        self.stop = threading.Event()
+        self.failure: BaseException | None = None
+
+    def run(self) -> None:
+        decoder = codecs.getincrementaldecoder("utf-8")(errors="replace")
+        drain_deadline: float | None = None
+        try:
+            while True:
+                if self.stop.is_set():
+                    if drain_deadline is None:
+                        drain_deadline = time.monotonic() + _DRAIN_SECONDS
+                    if time.monotonic() >= drain_deadline:
+                        self.failure = self.failure or TimeoutError(
+                            "Foundation output drain expired"
+                        )
+                        break
+                readable, _, _ = select.select([self.descriptor], [], [], 0.05)
+                if not readable:
+                    if drain_deadline is not None:
+                        break
+                    continue
+                try:
+                    content = os.read(self.descriptor, 4096)
+                except BlockingIOError:
+                    continue
+                if not content:
+                    break
+                if self.failure is None:
+                    try:
+                        self.stream.feed(decoder.decode(content))
+                    except Exception as exc:  # noqa: BLE001 - rethrow in owner after draining the pipe.
+                        self.failure = exc
+            if self.failure is None:
+                self.stream.feed(decoder.decode(b"", final=True))
+                self.stream.finish()
+        except Exception as exc:  # noqa: BLE001 - transfer thread failures to the owning context.
+            self.failure = self.failure or exc
+        finally:
+            os.close(self.descriptor)
+
+
+@contextmanager
+def _capture(stream: FoundationProgressStream) -> Iterator[int]:
+    """Yield a child stderr descriptor while retaining the caller's run/timeout/exit policy."""
+    read_descriptor, write_descriptor = os.pipe()
+    try:
+        os.set_blocking(read_descriptor, False)
+        reader = _Reader(read_descriptor, stream)
+        thread = threading.Thread(target=reader.run, name="fdai-foundation-display", daemon=True)
+        thread.start()
+    except BaseException:
+        os.close(read_descriptor)
+        os.close(write_descriptor)
+        raise
+    primary_error: BaseException | None = None
+    try:
+        yield write_descriptor
+    except BaseException as exc:
+        primary_error = exc
+        raise
+    finally:
+        os.close(write_descriptor)
+        reader.stop.set()
+        thread.join(timeout=_DRAIN_SECONDS + 1)
+        failed = thread.is_alive() or reader.failure is not None
+        if failed:
+            message = "Foundation display output is incomplete; review retained execution evidence"
+            if primary_error is not None:
+                primary_error.add_note(message)
+            else:
+                raise ValueError(message) from reader.failure
+
+
+@contextmanager
+def foundation_output() -> Iterator[int | None]:
+    """Compact known presentation only for a live TTY dashboard; preserve all other modes.
+
+    Unknown output temporarily owns the terminal unchanged. Approvals use their separate existing
+    path. This adapter neither launches a process nor reads status, stdin, plans, or credentials.
+    """
+    from fdai_deployment_cli.deployment_progress import _CURRENT, terminal_output
+
+    progress = _CURRENT.get()
+    if progress is None or not progress.dynamic:
+        with terminal_output("Foundation checkpoint details"):
+            yield None
+        return
+
+    progress.reset_foundation()
+    native = ExitStack()
+    native_active = False
+
+    def close_native() -> None:
+        nonlocal native_active
+        native.close()
+        native_active = False
+
+    def output(text: str) -> None:
+        nonlocal native_active
+        if not native_active:
+            native.enter_context(progress.terminal_output("Foundation details"))
+            native_active = True
+        progress.console.file.write(text)
+        progress.console.file.flush()
+
+    def checkpoint(value: FoundationCheckpoint) -> None:
+        close_native()
+        progress.foundation_checkpoint(value)
+
+    def mode(value: str) -> None:
+        close_native()
+        progress.foundation_mode(value)
+
+    stream = FoundationProgressStream(
+        output=output,
+        checkpoint=checkpoint,
+        heartbeat=progress.foundation_signal,
+        mode=mode,
+    )
+    try:
+        with _capture(stream) as descriptor:
+            yield descriptor
+    finally:
+        original_error = sys.exception()
+        try:
+            close_native()
+        except (OSError, ValueError) as exc:
+            if original_error is None:
+                raise
+            original_error.add_note(f"Foundation display cleanup failed: {type(exc).__name__}")

fdai_deployment_cli/foundation_plan.py

@@ -0,0 +1,381 @@
+"""Private saved foundation plans and non-authoritative integrity verification."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import subprocess
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+
+from fdai_deployment_cli.cli_help import command
+from fdai_deployment_cli.contracts import (
+    ProvisionProfile,
+    canonical_bytes,
+    canonical_digest,
+    load_json_object,
+)
+from fdai_deployment_cli.private_output import (
+    read_private_bytes,
+    write_private_bytes,
+    write_private_output,
+)
+from fdai_deployment_cli.profile import load_profile
+
+PLAN_NAME = "foundation.tfplan"
+REVIEW_NAME = "foundation-plan.json"
+_MAX_PLAN_BYTES = 64 * 1024 * 1024
+_MAX_JSON_BYTES = 16 * 1024 * 1024
+_SCHEMA = "fdai.foundation-saved-plan.v1"
+SOURCE_REVIEW_SCHEMA = "fdai.foundation-saved-source-plan.v1"
+_SOURCE_SCHEMA = SOURCE_REVIEW_SCHEMA
+_DIGEST = re.compile(r"[0-9a-f]{64}")
+_CONTEXT_KEYS = {
+    "offline_manifest_digest",
+    "deployment_bundle_digest",
+    "profile_digest",
+    "target_binding",
+    "variables_digest",
+    "terraform_digest",
+    "provider_lock_digest",
+    "runner_image_observation_digest",
+    "run_digest",
+    "foundation_context_digest",
+    "source_commit",
+}
+_AUTHORITY = {
+    "apply_authorized": False,
+    "source_eligibility_verified": False,
+    "plan_origin_verified": False,
+    "subscription_ready": False,
+    "mutation_performed": False,
+}
+_SOURCE_CONTEXT_KEYS = (_CONTEXT_KEYS - {"offline_manifest_digest", "deployment_bundle_digest"}) | {
+    "source_input_digest",
+    "source_snapshot_digest",
+}
+
+
+def foundation_plan_context(
+    *,
+    profile: ProvisionProfile,
+    variables: dict[str, object],
+    offline_manifest_digest: str,
+    deployment_bundle_digest: str,
+    terraform_digest: str,
+    provider_lock: bytes,
+    runner_image_observation_digest: str,
+) -> dict[str, object]:
+    """Bind verified artifact metadata to normalized variables, not source eligibility."""
+
+    result = {
+        "offline_manifest_digest": offline_manifest_digest,
+        "deployment_bundle_digest": deployment_bundle_digest,
+        "profile_digest": canonical_digest(profile.to_mapping()),
+        "target_binding": profile.target_binding,
+        "variables_digest": canonical_digest(variables),
+        "terraform_digest": terraform_digest,
+        "provider_lock_digest": hashlib.sha256(provider_lock).hexdigest(),
+        "runner_image_observation_digest": runner_image_observation_digest,
+        "source_commit": variables["source_commit"],
+        "run_digest": variables["run_digest"],
+        "foundation_context_digest": variables["foundation_context_digest"],
+    }
+    _validate_context(result)
+    return result
+
+
+def source_foundation_plan_context(
+    *,
+    profile: ProvisionProfile,
+    variables: dict[str, object],
+    source_input_digest: str,
+    source_snapshot_digest: str,
+    terraform_digest: str,
+    provider_lock: bytes,
+    runner_image_observation_digest: str,
+) -> dict[str, object]:
+    """Bind selected source bytes without fabricating signed-kit provenance."""
+    if profile.environment != "dev" or profile.connectivity != "online":
+        raise ValueError("source Foundation plans require connected development")
+    result = {
+        "source_input_digest": source_input_digest,
+        "source_snapshot_digest": source_snapshot_digest,
+        "profile_digest": canonical_digest(profile.to_mapping()),
+        "target_binding": profile.target_binding,
+        "variables_digest": canonical_digest(variables),
+        "terraform_digest": terraform_digest,
+        "provider_lock_digest": hashlib.sha256(provider_lock).hexdigest(),
+        "runner_image_observation_digest": runner_image_observation_digest,
+        "source_commit": variables["source_commit"],
+        "run_digest": variables["run_digest"],
+        "foundation_context_digest": variables["foundation_context_digest"],
+    }
+    _validate_context(result)
+    return result
+
+
+def save_foundation_plan(
+    *,
+    plan: Path,
+    destination: Path,
+    terraform: Path,
+    root: Path,
+    environment: dict[str, str],
+    context: dict[str, object],
+    variables: dict[str, object],
+) -> dict[str, object]:
+    """Validate the exact saved plan and publish private bytes plus a review receipt.
+
+    The caller owns a new private destination and a temporary private plan directory.
+    No provider values reach the receipt. Source SHA and local time are declarations,
+    not provenance or authenticated approval-time evidence. No apply is performed.
+    """
+
+    _validate_context(context)
+    if context["variables_digest"] != canonical_digest(variables):
+        raise ValueError("foundation plan variables do not match the saved context")
+    payload = read_private_bytes(plan, max_bytes=_MAX_PLAN_BYTES)
+    projection = plan.parent / "plan.json"
+    descriptor = os.open(projection, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600)
+    with os.fdopen(descriptor, "wb") as stream:
+        shown = subprocess.run(
+            [str(terraform), "show", "-json", str(plan)],
+            cwd=root,
+            env=environment,
+            stdout=stream,
+            stderr=subprocess.DEVNULL,
+            check=False,
+            timeout=300,
+            umask=0o077,
+        )
+    if shown.returncode != 0:
+        raise ValueError("saved foundation plan could not be inspected")
+    projected = read_private_bytes(projection, max_bytes=_MAX_JSON_BYTES)
+    details = load_json_object(projected, label="saved foundation plan", max_bytes=_MAX_JSON_BYTES)
+    version = _validate_projection(details, variables)
+    if read_private_bytes(plan, max_bytes=_MAX_PLAN_BYTES) != payload:
+        raise ValueError("saved foundation plan changed during inspection")
+    now = datetime.now(UTC).replace(microsecond=0)
+    receipt: dict[str, object] = {
+        "schema_version": _SOURCE_SCHEMA if set(context) == _SOURCE_CONTEXT_KEYS else _SCHEMA,
+        "state": "review",
+        **_AUTHORITY,
+        "context": context,
+        "plan_digest": hashlib.sha256(payload).hexdigest(),
+        "plan_json_digest": hashlib.sha256(projected).hexdigest(),
+        "summary": _plan_summary(details),
+        "terraform_version": version,
+        "created_at": now.isoformat(),
+        "expires_at": (now + timedelta(hours=1)).isoformat(),
+    }
+    receipt["review_digest"] = canonical_digest(receipt)
+    output = destination / PLAN_NAME
+    write_private_bytes(output, payload)
+    try:
+        write_private_output(
+            destination / REVIEW_NAME, (canonical_bytes(receipt) + b"\n").decode("utf-8")
+        )
+    except (OSError, ValueError):
+        output.unlink()
+        raise
+    return receipt
+
+
+def verify_foundation_plan(
+    *,
+    directory: Path,
+    profile: ProvisionProfile,
+    expected_review_digest: str,
+    require_unexpired: bool = True,
+) -> dict[str, object]:
+    """Check private saved bytes against a separately retained digest; never approve apply."""
+
+    if _DIGEST.fullmatch(expected_review_digest) is None:
+        raise ValueError("expected foundation review digest is invalid")
+    receipt = load_json_object(
+        read_private_bytes(directory / REVIEW_NAME, max_bytes=65_536),
+        label="foundation review",
+    )
+    expected_keys = {
+        "schema_version",
+        "state",
+        "context",
+        "plan_digest",
+        "plan_json_digest",
+        "terraform_version",
+        "created_at",
+        "expires_at",
+        "review_digest",
+        *_AUTHORITY,
+    }
+    optional_keys = {"summary"}
+    if (
+        not expected_keys <= set(receipt) <= expected_keys | optional_keys
+        or receipt["schema_version"] not in {_SCHEMA, _SOURCE_SCHEMA}
+        or receipt["state"] != "review"
+        or any(receipt[key] is not value for key, value in _AUTHORITY.items())
+    ):
+        raise ValueError("foundation review schema or authority is invalid")
+    digest = receipt.pop("review_digest")
+    if digest != expected_review_digest or canonical_digest(receipt) != expected_review_digest:
+        raise ValueError("foundation review digest does not match")
+    context = receipt["context"]
+    expected_context_keys = (
+        _SOURCE_CONTEXT_KEYS if receipt["schema_version"] == _SOURCE_SCHEMA else _CONTEXT_KEYS
+    )
+    if not isinstance(context, dict) or set(context) != expected_context_keys:
+        raise ValueError("foundation review context is invalid")
+    _validate_context(context)
+    if (
+        context["profile_digest"] != canonical_digest(profile.to_mapping())
+        or context["target_binding"] != profile.target_binding
+    ):
+        raise ValueError("foundation review does not match the profile")
+    _validate_review_time(receipt, require_unexpired=require_unexpired)
+    payload = read_private_bytes(directory / PLAN_NAME, max_bytes=_MAX_PLAN_BYTES)
+    if hashlib.sha256(payload).hexdigest() != receipt["plan_digest"]:
+        raise ValueError("saved foundation plan digest does not match")
+    return {
+        "schema_version": "fdai.foundation-plan-integrity.v1",
+        "state": "review",
+        "review_digest": expected_review_digest,
+        "plan_digest": receipt["plan_digest"],
+        "integrity_verified": True,
+        **_AUTHORITY,
+    }
+
+
+def _validate_context(context: dict[str, object]) -> None:
+    if set(context) not in (_CONTEXT_KEYS, _SOURCE_CONTEXT_KEYS):
+        raise ValueError("foundation plan context fields are invalid")
+    for key, value in context.items():
+        pattern = r"[0-9a-f]{40}" if key == "source_commit" else r"[0-9a-f]{64}"
+        if not isinstance(value, str) or re.fullmatch(pattern, value) is None:
+            raise ValueError("foundation plan context binding is invalid")
+
+
+def _validate_projection(details: dict[str, object], variables: dict[str, object]) -> str:
+    if (
+        details.get("format_version") not in ("1.1", "1.2")
+        or details.get("complete") is not True
+        or details.get("errored") is not False
+        or type(details.get("applyable")) is not bool
+        or details.get("deferred_changes")
+    ):
+        raise ValueError("saved foundation plan is incomplete or unsupported")
+    version = details.get("terraform_version")
+    if not isinstance(version, str) or re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+", version) is None:
+        raise ValueError("saved foundation plan Terraform version is invalid")
+    actual = details.get("variables")
+    if not isinstance(actual, dict) or any(
+        canonical_bytes(actual.get(key)) != canonical_bytes({"value": value})
+        for key, value in variables.items()
+    ):
+        raise ValueError("saved foundation plan does not match the normalized input")
+    return version
+
+
+def _plan_summary(details: dict[str, object]) -> dict[str, object]:
+    """Return a value-free action summary for approval and transition gating."""
+
+    counts = {"create": 0, "update": 0, "delete": 0, "replace": 0, "read": 0, "no-op": 0}
+    resource_type_counts: dict[str, int] = {}
+    summarized_changes: list[dict[str, object]] = []
+    changes = details.get("resource_changes", [])
+    if not isinstance(changes, list):
+        raise ValueError("saved foundation plan resource changes are invalid")
+    for item in changes:
+        if not isinstance(item, dict):
+            raise ValueError("saved foundation plan resource changes are invalid")
+        change = item.get("change")
+        actions_value = change.get("actions") if isinstance(change, dict) else None
+        if not isinstance(actions_value, list) or not actions_value:
+            raise ValueError("saved foundation plan action summary is invalid")
+        actions = tuple(str(action) for action in actions_value)
+        if actions == ("delete", "create"):
+            counts["replace"] += 1
+        elif len(actions) == 1 and actions[0] in counts:
+            counts[actions[0]] += 1
+        else:
+            raise ValueError("saved foundation plan action summary is invalid")
+        address = item.get("address")
+        resource_type = item.get("type")
+        if not isinstance(address, str) or not address:
+            raise ValueError("saved foundation plan action summary is invalid")
+        if not isinstance(resource_type, str) or not resource_type:
+            resource_type = address.split(".", 1)[0]
+        resource_type_counts[resource_type] = resource_type_counts.get(resource_type, 0) + 1
+        summarized_changes.append({"address": address, "actions": list(actions)})
+    summary: dict[str, object] = {
+        "schema_version": "fdai.foundation-plan-summary.v1",
+        "action_counts": counts,
+        "resource_type_counts": resource_type_counts,
+        "resource_changes": summarized_changes,
+    }
+    summary["summary_digest"] = canonical_digest(summary)
+    return summary
+
+
+def _validate_review_time(receipt: dict[str, object], *, require_unexpired: bool = True) -> None:
+    timestamps: list[datetime] = []
+    for key in ("created_at", "expires_at"):
+        value = receipt[key]
+        if not isinstance(value, str) or not value:
+            raise ValueError("foundation review timestamp is invalid")
+        try:
+            parsed = datetime.fromisoformat(value)
+        except ValueError:
+            raise ValueError("foundation review timestamp is invalid") from None
+        if parsed.tzinfo is None or parsed.utcoffset() != timedelta(0):
+            raise ValueError("foundation review timestamp MUST be UTC")
+        timestamps.append(parsed)
+    created, expires = timestamps
+    now = datetime.now(UTC)
+    if (
+        expires - created != timedelta(hours=1)
+        or created > now
+        or (require_unexpired and now >= expires)
+    ):
+        raise ValueError("foundation review is expired or outside its local time window")
+
+
+def register_foundation_plan_command(
+    commands: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    """Register local saved-plan verification without Azure access or execution."""
+
+    parser = command(
+        commands,
+        "verify-foundation-plan",
+        "Verify a saved Foundation plan; does not authorize apply",
+    )
+    parser.add_argument(
+        "--directory",
+        type=Path,
+        required=True,
+        help="Private directory of the saved Foundation plan and review",
+    )
+    parser.add_argument("--profile", type=Path, required=True)
+    parser.add_argument("--expected-review-digest", required=True)
+    parser.add_argument("--allow-expired-after-claim", action="store_true", help=argparse.SUPPRESS)
+    parser.add_argument("--output", choices=("text", "json"), default="text")
+    parser.set_defaults(handler=_verify_command)
+
+
+def _verify_command(args: argparse.Namespace) -> int:
+    result = verify_foundation_plan(
+        directory=args.directory,
+        profile=load_profile(args.profile),
+        expected_review_digest=args.expected_review_digest,
+        require_unexpired=not args.allow_expired_after_claim,
+    )
+    print(
+        json.dumps(result, sort_keys=True, separators=(",", ":"))
+        if args.output == "json"
+        else "saved foundation plan integrity verified; protected approval remains required"
+    )
+    return 0

fdai_deployment_cli/foundation_process.py

@@ -0,0 +1,64 @@
+"""Supervise the installed Foundation coordinator without abandoning claimed effects."""
+
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+import threading
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+
+
+def _interrupted(signum: int, _frame: object) -> None:
+    signal.signal(signal.SIGTERM, signal.SIG_IGN)
+    raise SystemExit(128 + signum)
+
+
+def run_foundation_process(
+    command: Sequence[str],
+    *,
+    cwd: Path,
+    env: Mapping[str, str],
+    timeout: float,
+    stdout: int | None = None,
+    stderr: int | None = None,
+) -> subprocess.CompletedProcess[bytes]:
+    """Preserve terminal I/O and allow nested SIGTERM cleanup before forced termination.
+
+    Return the actual child exit code. Timeout or caller interruption stops the
+    process group with a five-second cleanup reserve; neither path grants retry.
+    Optional caller-owned output descriptors preserve presentation without changing
+    stdin, descriptor ownership, or the process-group termination contract.
+    """
+    process = subprocess.Popen(  # noqa: S603 - fixed signed Foundation entrypoint.
+        command, cwd=cwd, env=env, stdout=stdout, stderr=stderr, start_new_session=True
+    )
+    previous = None
+    if threading.current_thread() is threading.main_thread():
+        previous = signal.signal(signal.SIGTERM, _interrupted)
+    try:
+        status = process.wait(timeout=timeout)
+    except BaseException:
+        _stop(process)
+        raise
+    finally:
+        if previous is not None:
+            signal.signal(signal.SIGTERM, previous)
+    return subprocess.CompletedProcess(command, status)
+
+
+def _stop(process: subprocess.Popen[bytes]) -> None:
+    for selected_signal, grace in ((signal.SIGTERM, 5), (signal.SIGKILL, 1)):
+        try:
+            os.killpg(process.pid, selected_signal)
+        except ProcessLookupError:
+            return
+        try:
+            process.wait(timeout=grace)
+            # A terminated coordinator might have left another direct group member.
+            if selected_signal == signal.SIGTERM:
+                continue
+            return
+        except subprocess.TimeoutExpired:
+            continue