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

fdai_deployment_cli/hub_image_stage.py

@@ -0,0 +1,162 @@
+"""Mirror all signed FDAI images, independently observing every imported digest."""
+
+from __future__ import annotations
+
+import argparse
+import re
+from pathlib import Path
+
+from fdai_deployment_cli.contracts import canonical_bytes, canonical_digest, load_json_object
+from fdai_deployment_cli.hub_image_trust import HubImageSelection, load_selection
+from fdai_deployment_cli.private_output import read_private_bytes, write_private_bytes
+from fdai_deployment_cli.source_application_inputs import absolute_input_path
+from fdai_deployment_cli.source_image_stage import (
+    RegistryBuildService,
+    SourceImageStageStopped,
+    SourceImageTarget,
+)
+
+
+def prepare_host_inputs(args: argparse.Namespace, work_dir: Path) -> HubImageSelection | None:
+    selected_hub_path = getattr(args, "hub_selection", None)
+    selection = prepare_host_selection(
+        path=absolute_input_path(selected_hub_path) if selected_hub_path is not None else None,
+        digest=getattr(args, "hub_selection_digest", None),
+        work_dir=work_dir,
+    )
+    if selection is not None and not hasattr(args, "source_snapshot"):
+        raise ValueError("Hub images require checkout support, not offline-kit mode")
+    return selection
+
+
+def require_foundation_source(selection: HubImageSelection | None, source_commit: str) -> None:
+    if selection is not None and selection.source_commit != source_commit:
+        raise ValueError("Hub Release and Foundation source revisions differ")
+
+
+def require_retained_artifact_mode(
+    retained: dict[str, object], source_mode: bool, selection: HubImageSelection | None
+) -> None:
+    """Reject any retained artifact mode or exact signed selection drift."""
+    expected_source = (
+        "hub-signed-images"
+        if selection is not None
+        else "operator-selected-source"
+        if source_mode
+        else "signed-kit"
+    )
+    if retained.get("artifact_source") != expected_source or retained.get(
+        "hub_selection_digest"
+    ) != (selection.digest if selection is not None else None):
+        raise ValueError("standalone host artifact mode or Hub selection drifted")
+
+
+def bind_host_selection(context: dict[str, object], selection: HubImageSelection | None) -> None:
+    if selection is not None:
+        context.update(selection.metadata())
+        context["hub_selection"] = str(selection.path)
+
+
+def prepare_host_selection(
+    *, path: Path | None, digest: str | None, work_dir: Path
+) -> HubImageSelection | None:
+    """Retain the independently verified workstation pin, never a host-fetched TOFU key."""
+    retained = work_dir / "hub-selection.json"
+    if path is None and digest is None:
+        if retained.exists():
+            raise ValueError("Hub artifact mode cannot change to source or offline kit")
+        return None
+    if path is None or digest is None:
+        raise ValueError("Hub selection and exact digest are both required")
+    selection = load_selection(path, digest)
+    content = read_private_bytes(path, max_bytes=12 * 1024 * 1024)
+    if retained.exists():
+        if read_private_bytes(retained, max_bytes=12 * 1024 * 1024) != content:
+            raise ValueError("Hub host immutable image selection changed")
+    else:
+        write_private_bytes(retained, content)
+    return load_selection(retained, selection.digest)
+
+
+def run_hub_image_stage(
+    *,
+    selection: HubImageSelection,
+    target: SourceImageTarget,
+    registry: RegistryBuildService,
+    work_dir: Path,
+) -> dict[str, object]:
+    if (
+        re.fullmatch(r"[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}", target.subscription_id) is None
+        or re.fullmatch(r"[a-z0-9]{5,50}", target.registry_name) is None
+    ):
+        raise ValueError("Hub image target is malformed")
+    selection = load_selection(selection.path, selection.digest)
+    claim = {
+        "schema_version": "fdai.hub-image-stage-claim.v1",
+        "hub_selection_digest": selection.digest,
+        "subscription_id": target.subscription_id,
+        "registry_login_server": target.login_server,
+        "image_sources": selection.image_sources,
+        "artifact_source": "hub-signed-images",
+    }
+    work_dir.mkdir(mode=0o700, exist_ok=True)
+    claim_path, receipt_path = work_dir / "claim.json", work_dir / "receipt.json"
+    if claim_path.exists():
+        existing = load_json_object(
+            read_private_bytes(claim_path, max_bytes=65_536), label="Hub image claim", strict=True
+        )
+        if existing != claim:
+            raise ValueError("Hub image stage target, mode or selection changed")
+    else:
+        if any(work_dir.iterdir()):
+            raise ValueError("Hub image stage cannot adopt another artifact mode")
+        write_private_bytes(claim_path, canonical_bytes(claim))
+    digests = {name: ref.rsplit("@", 1)[1] for name, ref in selection.image_sources.items()}
+    tag = "hub-" + selection.digest[:32]
+    existing_receipt = None
+    if receipt_path.exists():
+        existing_receipt = load_json_object(
+            read_private_bytes(receipt_path, max_bytes=65_536),
+            label="Hub image receipt",
+            strict=True,
+        )
+        unsigned = {
+            key: value for key, value in existing_receipt.items() if key != "receipt_digest"
+        }
+        if (
+            existing_receipt.get("claim_digest") != canonical_digest(claim)
+            or existing_receipt.get("receipt_digest") != canonical_digest(unsigned)
+            or existing_receipt.get("image_digests") != digests
+        ):
+            raise ValueError("Hub image receipt binding differs")
+    try:
+        if existing_receipt is None:
+            registry.require_available(target)
+            for name, source in sorted(selection.image_sources.items()):
+                registry.import_image(target, source=source, image=f"{name}:{tag}")
+        for name, digest in sorted(digests.items()):
+            for reference in (f"{name}@{digest}", f"{name}:{tag}"):
+                if registry.read_digest(target, reference=reference) != digest:
+                    raise ValueError("Hub imported image digest readback differs")
+    except SourceImageStageStopped as error:
+        raise ValueError("Hub image import or observation failed; no builds or fallback") from error
+    if existing_receipt is not None:
+        return existing_receipt
+    receipt = {
+        "schema_version": "fdai.hub-image-stage-receipt.v1",
+        **selection.metadata(),
+        "claim_digest": canonical_digest(claim),
+        "source_commit": selection.source_commit,
+        "image_sources": selection.image_sources,
+        "image_digests": digests,
+        "image_refs": {
+            name: f"{target.login_server}/{name}@{digest}" for name, digest in digests.items()
+        },
+        "builder": "none",
+        "effect_verified": True,
+        "mutation_performed": True,
+        "deployment_ready": False,
+    }
+    receipt["receipt_digest"] = canonical_digest(receipt)
+    write_private_bytes(receipt_path, canonical_bytes(receipt))
+    return receipt

fdai_deployment_cli/hub_image_trust.py

@@ -0,0 +1,281 @@
+"""Verify a public signed export without importing the dependent lifecycle Hub package."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from base64 import b64decode, b64encode
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from functools import cmp_to_key
+from pathlib import Path
+from typing import Any
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+from fdai_deployment_cli.contracts import canonical_bytes, load_json_object
+from fdai_deployment_cli.lifecycle_release import (
+    APPLICATION_COMPONENT_RELEASE_SCHEMA,
+    parse_lifecycle_release_manifest,
+)
+from fdai_deployment_cli.private_output import read_private_bytes
+from fdai_deployment_cli.runtime_release import (
+    RecallRecord,
+    compare_release_ids,
+    evaluate_recall_candidate,
+    is_release_id,
+)
+from fdai_deployment_cli.source_image_stage import DEPENDENCY_IMAGES, SERVICE_ORDER
+
+MAX_EXPORT_BYTES = 8 * 1024 * 1024
+MAX_SELECTION_BYTES = 12 * 1024 * 1024
+EXPORT_DOMAIN = b"fdai.catalog-export.v1\n"
+PROVENANCE = "hub-signed-images-with-checkout-support"
+INVENTORY = frozenset(SERVICE_ORDER) | DEPENDENCY_IMAGES.keys()
+
+
+def public_key(pem: bytes) -> Ed25519PublicKey:
+    if not 0 < len(pem) <= 4096:
+        raise ValueError("Hub trust requires a bounded independently provisioned public PEM")
+    key = serialization.load_pem_public_key(pem)
+    if not isinstance(key, Ed25519PublicKey):
+        raise ValueError("Hub trust requires an Ed25519 public key")  # noqa: TRY004
+    return key
+
+
+def key_id(key: Ed25519PublicKey) -> str:
+    raw = key.public_bytes(serialization.Encoding.Raw, serialization.PublicFormat.Raw)
+    return "hub-" + hashlib.sha256(raw).hexdigest()[:16]
+
+
+def validate_channel(channel: str) -> None:
+    if (
+        len(channel) > 64
+        or re.fullmatch(r"(?:DEV|RELEASE_CANDIDATE|RELEASE|custom-[a-z0-9][a-z0-9-]*)", channel)
+        is None
+    ):
+        raise ValueError("Hub channel must be DEV, RELEASE_CANDIDATE, RELEASE, or custom-*")
+
+
+def _signature(key: Ed25519PublicKey, signature: object, payload: bytes) -> None:
+    if not isinstance(signature, str) or not 0 < len(signature) <= 128:
+        raise ValueError("Hub signature is missing or malformed")
+    try:
+        key.verify(b64decode(signature, validate=True), payload)
+    except (InvalidSignature, ValueError) as error:
+        raise ValueError("Hub signature verification failed; no source-build fallback") from error
+
+
+@dataclass(frozen=True)
+class HubImageSelection:
+    path: Path
+    digest: str
+    document: dict[str, Any]
+    release_id: str
+    source_commit: str
+    release_digest: str
+    image_sources: dict[str, str]
+
+    def metadata(self) -> dict[str, object]:
+        return {
+            "provenance": PROVENANCE,
+            "artifact_source": "hub-signed-images",
+            "hub_selection_digest": self.digest,
+            "hub_release_id": self.release_id,
+            "hub_channel": self.document["channel"],
+            "hub_catalog_digest": self.document["catalog_digest"],
+            "hub_catalog_revision": self.document["catalog_revision"],
+            "runtime_release_digest": self.release_digest,
+            "image_signature_verified": True,
+            "release_signature_verified": False,
+            "support_artifact_source": "operator-selected-source",
+        }
+
+
+def verify_export(
+    raw: bytes,
+    *,
+    signature: str,
+    export_key_id: str,
+    trusted_pem: bytes,
+    channel: str,
+    release_id: str | None = None,
+    now: datetime | None = None,
+    minimum_revision: int = 0,
+    previous_digest: str | None = None,
+) -> dict[str, Any]:
+    """Authenticate membership, all manifests and recall before selecting one exact Release."""
+    if not 0 < len(raw) <= MAX_EXPORT_BYTES:
+        raise ValueError("Hub export exceeds its size bound")
+    validate_channel(channel)
+    key = public_key(trusted_pem)
+    if export_key_id != key_id(key):
+        raise ValueError("Hub export key id differs from the independent trust key")
+    _signature(key, signature, EXPORT_DOMAIN + raw)
+    doc = load_json_object(raw, label="Hub signed export", max_bytes=MAX_EXPORT_BYTES, strict=True)
+    if set(doc) != {"revision", "expires_at", "releases", "channels", "recalls"}:
+        raise ValueError("Hub signed export fields are invalid")
+    revision = doc["revision"]
+    if type(revision) is not int or not 0 <= revision <= 2**63 - 1:
+        raise ValueError("Hub signed export revision is invalid")
+    digest = hashlib.sha256(raw).hexdigest()
+    if revision < minimum_revision or (
+        revision == minimum_revision and previous_digest not in {None, digest}
+    ):
+        raise ValueError("Hub catalog rollback or same-revision substitution refused")
+    now = now or datetime.now(UTC)
+    try:
+        expires = datetime.fromisoformat(doc["expires_at"])
+    except (TypeError, ValueError) as error:
+        raise ValueError("Hub catalog expiry is invalid") from error
+    if now.tzinfo is None or expires.tzinfo is None or now >= expires:
+        raise ValueError("Hub catalog expired; no source-build fallback")
+    releases, channels, recalls = doc["releases"], doc["channels"], doc["recalls"]
+    if (
+        not isinstance(releases, dict)
+        or not 1 <= len(releases) <= 4096
+        or not isinstance(channels, dict)
+        or not 1 <= len(channels) <= 256
+        or not isinstance(recalls, list)
+        or len(recalls) > 8192
+    ):
+        raise ValueError("Hub catalog inventory is invalid")
+    parsed = {}
+    for version, artifact in releases.items():
+        if not isinstance(version, str) or len(version) > 64 or not is_release_id(version):
+            raise ValueError("Hub release id is invalid")
+        if (
+            not isinstance(artifact, dict)
+            or set(artifact) != {"manifest", "signature"}
+            or not isinstance(artifact["manifest"], str)
+        ):
+            raise ValueError("Hub release artifact is invalid")
+        manifest = artifact["manifest"].encode("utf-8")
+        _signature(key, artifact["signature"], manifest)
+        release = parse_lifecycle_release_manifest(manifest)
+        if release.to_mapping().get("release_version", version) != version or (
+            release.configuration_schema is not None
+            and release.configuration_schema.release_version != version
+        ):
+            raise ValueError("Hub manifest version differs from the catalog release id")
+        parsed[version] = release
+    for name, members in channels.items():
+        validate_channel(name)
+        if (
+            not isinstance(members, list)
+            or len(members) > 4096
+            or any(not isinstance(member, str) or member not in parsed for member in members)
+            or len(set(members)) != len(members)
+        ):
+            raise ValueError("Hub channel members are invalid")
+    active: dict[tuple[str, str], RecallRecord] = {}
+    records: list[RecallRecord] = []
+    try:
+        for value in recalls:
+            if not isinstance(value, dict):
+                raise ValueError("Hub recall is invalid")  # noqa: TRY004
+            record = RecallRecord(**value)
+            identity = record.scope, record.target
+            prior = active.get(identity)
+            if prior is not None and record.sequence <= prior.sequence:
+                raise ValueError("Hub recall sequence did not advance")
+            active[identity] = record
+            records.append(record)
+    except (TypeError, ValueError) as error:
+        raise ValueError("Hub recall history is invalid") from error
+    members = channels.get(channel, [])
+    capabilities = tuple(record.target for record in records if record.scope == "capability")
+    eligible = [
+        version
+        for version in members
+        if evaluate_recall_candidate(
+            release_id=version, capability_ids=capabilities, recall_records=tuple(records)
+        ).allowed
+    ]
+    if release_id is not None:
+        if len(release_id) > 64 or not is_release_id(release_id) or release_id not in eligible:
+            raise ValueError("Hub requested Release is absent, outside channel, or recalled")
+        selected = release_id
+    else:
+        if not eligible:
+            raise ValueError("Hub channel has no non-recalled Release")
+        selected = max(eligible, key=cmp_to_key(compare_release_ids))
+    release = parsed[selected]
+    manifest_doc = release.to_mapping()
+    components = manifest_doc.get("components")
+    if (
+        release.schema_version != APPLICATION_COMPONENT_RELEASE_SCHEMA
+        or release.product != "fdai"
+        or release.platform_tag != "linux-x86_64"
+        or not isinstance(components, dict)
+        or set(components) != INVENTORY
+        or any(not isinstance(value.get("image_ref"), str) for value in components.values())
+    ):
+        raise ValueError(
+            "Hub bootstrap requires an fdai linux-x86_64 application-release.v2 with all "
+            "five services and two dependencies, each with signed digest-pinned image_ref"
+        )
+    return {
+        "release_id": selected,
+        "source_commit": release.source_commit,
+        "release_digest": release.digest,
+        "image_sources": {name: value["image_ref"] for name, value in components.items()},
+        "catalog_digest": digest,
+        "catalog_revision": revision,
+    }
+
+
+def load_selection(path: Path, expected_digest: str) -> HubImageSelection:
+    raw = read_private_bytes(path, max_bytes=MAX_SELECTION_BYTES)
+    if hashlib.sha256(raw).hexdigest() != expected_digest:
+        raise ValueError("Hub immutable selection digest differs")
+    doc = load_json_object(raw, label="Hub selection", max_bytes=MAX_SELECTION_BYTES, strict=True)
+    if doc.get("schema_version") != "fdai.hub-image-selection.v1":
+        raise ValueError("Hub selection schema is invalid")
+    result = verify_export(
+        b64decode(doc["catalog"], validate=True),
+        signature=doc["export_signature"],
+        export_key_id=doc["export_key_id"],
+        trusted_pem=doc["public_key"].encode("ascii"),
+        channel=doc["channel"],
+        release_id=doc["release_id"],
+        minimum_revision=doc["catalog_revision"],
+        previous_digest=doc["catalog_digest"],
+    )
+    if any(doc.get(name) != value for name, value in result.items()):
+        raise ValueError("Hub selection disagrees with its authenticated catalog")
+    return HubImageSelection(
+        path=path,
+        digest=expected_digest,
+        document=doc,
+        **{
+            name: result[name]
+            for name in ("release_id", "source_commit", "release_digest", "image_sources")
+        },
+    )
+
+
+def selection_bytes(
+    *,
+    raw: bytes,
+    signature: str,
+    export_key_id: str,
+    pem: bytes,
+    hub_url: str,
+    channel: str,
+    verified: dict[str, Any],
+) -> bytes:
+    return canonical_bytes(
+        {
+            "schema_version": "fdai.hub-image-selection.v1",
+            "hub_url": hub_url,
+            "channel": channel,
+            "catalog": b64encode(raw).decode("ascii"),
+            "export_signature": signature,
+            "export_key_id": export_key_id,
+            "public_key": pem.decode("ascii"),
+            **verified,
+        }
+    )

fdai_deployment_cli/hub_ownership.py

@@ -0,0 +1,161 @@
+"""Local Hub ownership marker: once the Lifecycle Agent owns the workloads, Terraform must not.
+
+The marker is recorded after the Terraform release step of the ownership handoff. While it exists,
+every entry point that would plan or apply the AKS workloads root refuses, so Terraform and the
+agent never write the same object. A present but unreadable marker also refuses: a damaged marker
+must not silently hand the objects back to Terraform. Rollback removes the marker only through the
+explicit release function after the agent has stopped reconciling.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from fdai_deployment_cli.contracts import canonical_digest
+from fdai_deployment_cli.standalone_host_state import private_json, replace_private_json
+
+MARKER_NAME = "hub-ownership.json"
+MARKER_SCHEMA = "fdai.hub-ownership-marker.v1"
+ADOPTION_SCHEMA = "fdai.runtime-adoption-receipt.v1"
+_ID = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,127}")
+_DIGEST = re.compile(r"sha256:[0-9a-f]{64}")
+
+
+def marker_path(work_dir: Path) -> Path:
+    return work_dir / MARKER_NAME
+
+
+def add_handoff_parser(subcommands: Any) -> None:
+    parser = subcommands.add_parser("record-hub-workload-handoff")
+    parser.add_argument("--adoption-receipt", type=Path, required=True)
+    parser.set_defaults(handler=_record_handoff_command)
+
+
+def _record_handoff_command(args: Any, work_dir: Path) -> dict[str, object]:
+    return record_hub_ownership_from_adoption(
+        work_dir,
+        adoption_receipt=args.adoption_receipt,
+    )
+
+
+def record_hub_ownership(
+    work_dir: Path,
+    *,
+    installation_id: str,
+    handoff_receipt_digest: str,
+    recorded_at: datetime | None = None,
+) -> dict[str, object]:
+    """Record the marker once; repeating the same handoff returns the retained record."""
+
+    if _ID.fullmatch(installation_id) is None or _DIGEST.fullmatch(handoff_receipt_digest) is None:
+        raise ValueError("hub ownership marker inputs are invalid")
+    path = marker_path(work_dir)
+    if path.exists():
+        retained = _read(path)
+        if (
+            retained["installation_id"] != installation_id
+            or retained["handoff_receipt_digest"] != handoff_receipt_digest
+        ):
+            raise ValueError("a different hub ownership marker is already recorded")
+        return retained
+    moment = recorded_at or datetime.now(tz=UTC)
+    if moment.tzinfo is None:
+        raise ValueError("hub ownership marker time MUST be timezone-aware")
+    body: dict[str, object] = {
+        "schema_version": MARKER_SCHEMA,
+        "installation_id": installation_id,
+        "handoff_receipt_digest": handoff_receipt_digest,
+        "recorded_at": moment.astimezone(UTC).isoformat(),
+    }
+    record = body | {"record_digest": "sha256:" + canonical_digest(body)}
+    replace_private_json(path, record)
+    return record
+
+
+def record_hub_ownership_from_adoption(
+    work_dir: Path,
+    *,
+    adoption_receipt: Path,
+) -> dict[str, object]:
+    """Record the marker only from one complete, digest-valid per-object adoption receipt."""
+
+    receipt = private_json(adoption_receipt.absolute(), "runtime adoption receipt")
+    digest = receipt.pop("receipt_digest", None)
+    if (
+        receipt.get("schema_version") != ADOPTION_SCHEMA
+        or receipt.get("complete") is not True
+        or not isinstance(receipt.get("objects"), list)
+        or not receipt["objects"]
+        or digest != "sha256:" + canonical_digest(receipt)
+        or _ID.fullmatch(str(receipt.get("installation_id", ""))) is None
+        or _ID.fullmatch(str(receipt.get("release_id", ""))) is None
+    ):
+        raise ValueError("runtime adoption receipt is invalid")
+    required = {"kind", "name", "uid", "resource_version", "render_digest"}
+    if any(
+        not isinstance(item, dict)
+        or set(item) != required
+        or _ID.fullmatch(str(item["kind"])) is None
+        or _ID.fullmatch(str(item["name"])) is None
+        or _ID.fullmatch(str(item["uid"])) is None
+        or _ID.fullmatch(str(item["resource_version"])) is None
+        or _DIGEST.fullmatch(str(item["render_digest"])) is None
+        for item in receipt["objects"]
+    ):
+        raise ValueError("runtime adoption receipt is invalid")
+    return record_hub_ownership(
+        work_dir,
+        installation_id=str(receipt["installation_id"]),
+        handoff_receipt_digest=str(digest),
+    )
+
+
+def release_hub_ownership(work_dir: Path, *, rollback_receipt_digest: str) -> None:
+    """Remove the marker for a verified rollback to Terraform; refuses without a receipt."""
+
+    if _DIGEST.fullmatch(rollback_receipt_digest) is None:
+        raise ValueError("hub ownership release requires a rollback receipt digest")
+    path = marker_path(work_dir)
+    if path.exists():
+        _read(path)
+        path.unlink()
+
+
+def require_terraform_owned_workloads(work_dir: Path) -> None:
+    """Refuse a Terraform workloads operation while the Hub owns the workloads."""
+
+    path = marker_path(work_dir)
+    if not path.exists() and not path.is_symlink():
+        return
+    _read(path)
+    raise ValueError(
+        "the workloads are Hub-managed; plan the Hub variant instead of the workloads root"
+    )
+
+
+def workloads_terraform_data(context: dict[str, object], work_dir: Path) -> object:
+    """Return the workloads Terraform data path only while Terraform owns the workloads."""
+
+    require_terraform_owned_workloads(work_dir)
+    return context.get("workloads_terraform_data")
+
+
+def _read(path: Path) -> dict[str, object]:
+    try:
+        record = private_json(path, "hub ownership marker")
+        digest = record.pop("record_digest", None)
+        if (
+            record.get("schema_version") != MARKER_SCHEMA
+            or set(record)
+            != {"schema_version", "installation_id", "handoff_receipt_digest", "recorded_at"}
+            or digest != "sha256:" + canonical_digest(record)
+            or _ID.fullmatch(str(record["installation_id"])) is None
+            or _DIGEST.fullmatch(str(record["handoff_receipt_digest"])) is None
+        ):
+            raise ValueError("hub ownership marker is invalid")
+    except (OSError, ValueError):
+        raise ValueError("hub ownership marker is unreadable; workloads stay Hub-managed") from None
+    return record | {"record_digest": digest}