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

fdai_deployment_cli/lifecycle_upgrade_bundle.py

@@ -0,0 +1,176 @@
+"""Signed offline upgrade bundle builder and Target Hub import verifier."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+
+from fdai_deployment_cli.contracts import canonical_bytes
+from fdai_deployment_cli.lifecycle_promotion import BoundaryRegistryMirror
+
+_IMAGE_DIGEST = re.compile(r"sha256:[0-9a-f]{64}\Z", re.ASCII)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SignedConfigurationTransferItem:
+    """Customer-authored signed configuration package carried alongside an upgrade bundle."""
+
+    package_id: str
+    payload: bytes
+    signature: bytes
+
+    def __post_init__(self) -> None:
+        if not self.package_id.strip():
+            raise ValueError("package_id MUST NOT be empty")
+        if not self.payload:
+            raise ValueError("payload MUST NOT be empty")
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SignedUpgradeBundle:
+    """Offline upgrade bundle carrying catalog metadata, minimal image layers, and checksums."""
+
+    bundle_id: str
+    extends_bundle_id: str | None
+    catalog_export_bytes: bytes
+    image_layers: Mapping[str, bytes] = field(default_factory=dict)
+    checksums: Mapping[str, str] = field(default_factory=dict)
+    checksum_signature: bytes = b""
+    configuration_packages: tuple[SignedConfigurationTransferItem, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not self.bundle_id.strip():
+            raise ValueError("bundle_id MUST NOT be empty")
+        if not self.catalog_export_bytes:
+            raise ValueError("catalog_export_bytes MUST NOT be empty")
+        for digest in self.image_layers:
+            if _IMAGE_DIGEST.fullmatch(digest) is None:
+                raise ValueError("image_layers keys MUST be sha256:<64 hex> digests")
+
+    def canonical_checksum_payload(self) -> bytes:
+        return canonical_bytes(
+            {
+                "schema_version": "fdai.upgrade-bundle-checksums.v1",
+                "bundle_id": self.bundle_id,
+                "extends_bundle_id": self.extends_bundle_id,
+                "checksums": dict(sorted(self.checksums.items())),
+            }
+        )
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class UpgradeBundleImportResult:
+    """Verified Target Hub import result for one signed upgrade bundle."""
+
+    bundle_id: str
+    extends_bundle_id: str | None
+    catalog_export_sha256: str
+    mirror: BoundaryRegistryMirror
+    verified_configuration_package_digests: tuple[str, ...]
+
+
+def compute_upgrade_bundle_checksums(
+    *,
+    catalog_export_bytes: bytes,
+    image_layers: Mapping[str, bytes],
+) -> dict[str, str]:
+    """Compute the canonical checksum map for a catalog export and minimal image layers."""
+
+    checksums: dict[str, str] = {
+        "catalog_export": hashlib.sha256(catalog_export_bytes).hexdigest(),
+    }
+    for digest, layer_bytes in sorted(image_layers.items()):
+        if _IMAGE_DIGEST.fullmatch(digest) is None:
+            raise ValueError("image_layers keys MUST be sha256:<64 hex> digests")
+        checksums[f"layer:{digest}"] = hashlib.sha256(layer_bytes).hexdigest()
+    return checksums
+
+
+def build_signed_upgrade_bundle(
+    *,
+    bundle_id: str,
+    extends_bundle_id: str | None,
+    catalog_export_bytes: bytes,
+    image_layers: Mapping[str, bytes],
+    sign_checksums: Callable[[bytes], bytes],
+    configuration_packages: tuple[SignedConfigurationTransferItem, ...] = (),
+) -> SignedUpgradeBundle:
+    """Build and sign an offline upgrade bundle."""
+
+    checksums = compute_upgrade_bundle_checksums(
+        catalog_export_bytes=catalog_export_bytes,
+        image_layers=image_layers,
+    )
+    unsigned = SignedUpgradeBundle(
+        bundle_id=bundle_id,
+        extends_bundle_id=extends_bundle_id,
+        catalog_export_bytes=catalog_export_bytes,
+        image_layers=dict(image_layers),
+        checksums=checksums,
+        configuration_packages=configuration_packages,
+    )
+    signature = sign_checksums(unsigned.canonical_checksum_payload())
+    return SignedUpgradeBundle(
+        bundle_id=bundle_id,
+        extends_bundle_id=extends_bundle_id,
+        catalog_export_bytes=catalog_export_bytes,
+        image_layers=dict(image_layers),
+        checksums=checksums,
+        checksum_signature=signature,
+        configuration_packages=configuration_packages,
+    )
+
+
+def verify_and_import_upgrade_bundle(
+    bundle: SignedUpgradeBundle,
+    *,
+    verify_vendor_signature: Callable[[bytes, bytes], bool],
+    verify_configuration_signature: Callable[[bytes, bytes], bool] | None = None,
+    mirror: BoundaryRegistryMirror | None = None,
+    expected_previous_bundle_id: str | None = None,
+) -> UpgradeBundleImportResult:
+    """Verify the vendor checksum signature, every checksum, and each configuration signature."""
+
+    if expected_previous_bundle_id is not None and (
+        bundle.extends_bundle_id != expected_previous_bundle_id
+    ):
+        raise ValueError("upgrade_bundle_lineage_mismatch")
+    if not bundle.checksum_signature or not bool(
+        verify_vendor_signature(bundle.canonical_checksum_payload(), bundle.checksum_signature)
+    ):
+        raise ValueError("upgrade_bundle_signature_invalid")
+
+    expected_checksums = compute_upgrade_bundle_checksums(
+        catalog_export_bytes=bundle.catalog_export_bytes,
+        image_layers=bundle.image_layers,
+    )
+    if dict(bundle.checksums) != expected_checksums:
+        raise ValueError("upgrade_bundle_checksum_mismatch")
+    for digest, layer_bytes in bundle.image_layers.items():
+        actual_layer_digest = f"sha256:{hashlib.sha256(layer_bytes).hexdigest()}"
+        if actual_layer_digest != digest:
+            raise ValueError("upgrade_bundle_checksum_mismatch")
+
+    verified_config_digests: list[str] = []
+    for item in bundle.configuration_packages:
+        if not item.signature:
+            raise ValueError("upgrade_bundle_configuration_package_unsigned")
+        if verify_configuration_signature is None or not bool(
+            verify_configuration_signature(item.payload, item.signature)
+        ):
+            raise ValueError("upgrade_bundle_configuration_package_signature_invalid")
+        verified_config_digests.append(hashlib.sha256(item.payload).hexdigest())
+
+    current_mirror = mirror or BoundaryRegistryMirror()
+    updated_mirror = BoundaryRegistryMirror(
+        mirrored_digests=current_mirror.mirrored_digests | frozenset(bundle.image_layers.keys())
+    )
+    return UpgradeBundleImportResult(
+        bundle_id=bundle.bundle_id,
+        extends_bundle_id=bundle.extends_bundle_id,
+        catalog_export_sha256=expected_checksums["catalog_export"],
+        mirror=updated_mirror,
+        verified_configuration_package_digests=tuple(verified_config_digests),
+    )

fdai_deployment_cli/notification_recipients_input.py

@@ -0,0 +1,222 @@
+"""Private operator-selected email recipients for the source AKS notifications add-on.
+
+Addresses are personal data, so they are accepted only from a private local file and travel to
+the managed host as one private staged file. They never enter the runtime profile, its digest,
+plan reviews, receipts or logs; only the digest of the canonical recipient list is retained in the
+managed host's private context so a later run can detect drift.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from fdai_deployment_cli.contracts import canonical_digest
+from fdai_deployment_cli.private_output import read_private_bytes
+from fdai_deployment_cli.standalone_host_state import replace_or_verify_private_json
+
+_STAGED_SCHEMA = "fdai.notification-recipients-staged-input.v1"
+_MAX_INPUT_BYTES = 16 * 1024
+_MAX_RECIPIENTS = 20
+_MAX_ADDRESS_LENGTH = 254
+# Mirrors the `notification_email_recipients` validation in `infra/variables.tf`.
+_ADDRESS = re.compile(r"[^@\s]+@[^@\s]+[.][^@\s]+")
+_PLACEHOLDER_DOMAINS = frozenset({"example.com", "example.org", "example.net", "invalid", "test"})
+_CONTEXT_KEY = "notification_recipients_digest"
+
+
+@dataclass(frozen=True, slots=True)
+class NotificationRecipientsDeploymentInput:
+    """Validated, deduplicated recipient list and its content digest."""
+
+    recipients: tuple[str, ...]
+    input_digest: str
+
+    def __repr__(self) -> str:
+        return f"NotificationRecipientsDeploymentInput(count={len(self.recipients)})"
+
+
+def load_notification_recipients(path: Path) -> NotificationRecipientsDeploymentInput:
+    """Load one private recipients file from the operator-selected path."""
+
+    return _from_mapping(_load_json_object(path, "notification recipients input"), staged=False)
+
+
+def staged_notification_recipients_from_path(
+    path: Path | None,
+) -> NotificationRecipientsDeploymentInput | None:
+    """Load a staged managed-host input, or report that none was supplied."""
+
+    if path is None:
+        return None
+    return _from_mapping(
+        _load_json_object(path, "staged notification recipients input"), staged=True
+    )
+
+
+def stage_notification_recipients(
+    value: NotificationRecipientsDeploymentInput | None,
+    *,
+    tunnel: Any,
+    prepared_root: Path,
+    remote_root: str,
+) -> tuple[str, ...]:
+    """Copy the private recipient list to the managed host and return CLI arguments."""
+
+    if value is None:
+        return ()
+    local_path = prepared_root / "notification-recipients-input.json"
+    remote_path = f"{remote_root}/notification-recipients-input.json"
+    replace_or_verify_private_json(
+        local_path,
+        {
+            "schema_version": _STAGED_SCHEMA,
+            "input_digest": value.input_digest,
+            "recipients": list(value.recipients),
+        },
+    )
+    tunnel.copy_to(local_path, remote_path, timeout=120)
+    return ("--notification-recipients", remote_path)
+
+
+def apply_notification_recipients(
+    values: dict[str, object],
+    value: NotificationRecipientsDeploymentInput | None,
+) -> None:
+    """Populate the Terraform recipients only when the input is supplied."""
+
+    if value is None:
+        return
+    values["notification_email_recipients"] = list(value.recipients)
+
+
+def require_recipients_for_notifications(
+    *, notifications_selected: bool, value: NotificationRecipientsDeploymentInput | None
+) -> None:
+    """Fail closed before any Azure effect when the add-on and its input disagree."""
+
+    if notifications_selected and value is None:
+        raise ValueError(
+            "the notifications add-on requires --notification-recipients with at least one address"
+        )
+    if value is not None and not notifications_selected:
+        raise ValueError("--notification-recipients requires the notifications add-on")
+
+
+def reconcile_retained_notification_recipients(
+    value: NotificationRecipientsDeploymentInput | None,
+    *,
+    retained: dict[str, object],
+    values: dict[str, object],
+) -> bool:
+    """Bind a recipient list onto a retained host context, or fail on drift."""
+
+    previous = retained.get(_CONTEXT_KEY, "")
+    if not isinstance(previous, str):
+        raise ValueError("standalone host retained context differs")
+    current = value.input_digest if value is not None else ""
+    if previous and previous != current:
+        raise ValueError("standalone host retained context differs")
+    if value is None:
+        return False
+    apply_notification_recipients(values, value)
+    if previous == current:
+        return False
+    retained[_CONTEXT_KEY] = current
+    return True
+
+
+def selected_notification_recipients(
+    args: Any, *, runtime_profile: Any, cwd: Path
+) -> NotificationRecipientsDeploymentInput | None:
+    """Load the operator's recipient file and require it to match the add-on selection."""
+
+    from fdai_service_contracts.product_profile import ProductAddOn
+
+    selected = getattr(args, "notification_recipients", None)
+    value = (
+        None
+        if selected is None
+        else load_notification_recipients(selected if selected.is_absolute() else cwd / selected)
+    )
+    if value is not None and (args.runtime != "aks" or args.source is None):
+        raise ValueError(
+            "--notification-recipients requires a source deployment with --runtime aks"
+        )
+    if args.source is not None and not (args.prepare_only or args.preflight_only or args.teardown):
+        require_recipients_for_notifications(
+            notifications_selected=runtime_profile.product_profile.selects(
+                ProductAddOn.NOTIFICATIONS
+            ),
+            value=value,
+        )
+    return value
+
+
+def context_digest(value: NotificationRecipientsDeploymentInput | None) -> str:
+    """Return the digest retained in the private managed-host context."""
+
+    return value.input_digest if value is not None else ""
+
+
+def _from_mapping(value: dict[str, Any], *, staged: bool) -> NotificationRecipientsDeploymentInput:
+    expected = {"schema_version", "input_digest", "recipients"} if staged else {"recipients"}
+    if set(value) != expected:
+        raise ValueError("notification recipients input fields are invalid")
+    recipients = _recipients(value["recipients"])
+    digest = canonical_digest({"notification_email_recipients": list(recipients)})
+    if staged:
+        if value["schema_version"] != _STAGED_SCHEMA:
+            raise ValueError("staged notification recipients input schema is unsupported")
+        if value["input_digest"] != digest:
+            raise ValueError("staged notification recipients input digest differs")
+    return NotificationRecipientsDeploymentInput(recipients=recipients, input_digest=digest)
+
+
+def _recipients(value: object) -> tuple[str, ...]:
+    if not isinstance(value, list) or not value:
+        raise ValueError("notification recipients MUST be a non-empty list")
+    seen: dict[str, str] = {}
+    for item in value:
+        if not isinstance(item, str):
+            raise ValueError("notification recipients MUST be strings")
+        address = item.strip()
+        if not address or len(address) > _MAX_ADDRESS_LENGTH or _ADDRESS.fullmatch(address) is None:
+            raise ValueError("a notification recipient address is invalid")
+        if address.rsplit("@", 1)[1].casefold() in _PLACEHOLDER_DOMAINS:
+            raise ValueError("a notification recipient address uses a placeholder domain")
+        seen.setdefault(address.casefold(), address)
+    if len(seen) > _MAX_RECIPIENTS:
+        raise ValueError(f"notification recipients exceed the limit of {_MAX_RECIPIENTS}")
+    return tuple(seen[key] for key in sorted(seen))
+
+
+def _load_json_object(path: Path, label: str) -> dict[str, Any]:
+    data = read_private_bytes(path, max_bytes=_MAX_INPUT_BYTES)
+    if not data:
+        raise ValueError(f"{label} is empty")
+    try:
+        value = json.loads(data.decode("utf-8"))
+    except UnicodeDecodeError as exc:
+        raise ValueError(f"{label} is not valid UTF-8") from exc
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"{label} is not valid JSON") from exc
+    if not isinstance(value, dict):
+        raise ValueError(f"{label} MUST be a JSON object")  # noqa: TRY004
+    return value
+
+
+__all__ = [
+    "NotificationRecipientsDeploymentInput",
+    "apply_notification_recipients",
+    "context_digest",
+    "load_notification_recipients",
+    "reconcile_retained_notification_recipients",
+    "require_recipients_for_notifications",
+    "selected_notification_recipients",
+    "stage_notification_recipients",
+    "staged_notification_recipients_from_path",
+]

fdai_deployment_cli/observer_artifact.py

@@ -0,0 +1,106 @@
+"""Read-only observer image evidence from the existing pinned deployment-kit trust chain."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from fdai_deployment_cli.contracts import canonical_bytes
+from fdai_deployment_cli.deployment_kit import acquire_deployment_kit
+from fdai_deployment_cli.private_output import read_private_bytes
+
+
+def inspect_observer_artifact(
+    *, offline_kit: Path, work_dir: Path, source_commit: str, image_digest: str
+) -> dict[str, Any]:
+    """Reverify signed local release bytes and exact Core image, never install or import them.
+
+    Trust roots and all kit verification remain deployment-owned. Output is process-local read
+    evidence, not a transferable authorization; an enrolled preflight producer signs it separately.
+    """
+    if re.fullmatch(r"[a-f0-9]{40}", source_commit) is None:
+        raise ValueError("observer artifact source revision is invalid")
+    if re.fullmatch(r"sha256:[a-f0-9]{64}", image_digest) is None:
+        raise ValueError("observer artifact image digest is invalid")
+    kit = acquire_deployment_kit(work_dir=work_dir, online=False, offline_kit=offline_kit)
+    catalog = kit.runtime.to_mapping()
+    if kit.source_commit != source_commit:
+        raise ValueError("observer artifact source revision differs from the selected release")
+    services = catalog.get("services")
+    core = services.get("core-control-plane") if isinstance(services, dict) else None
+    if not isinstance(core, dict) or core.get("image_digest") != image_digest:
+        raise ValueError("observer image differs from the signed Core release")
+    value: dict[str, Any] = {
+        "schema_version": "1.0.0",
+        "source_commit": source_commit,
+        "image_digest": image_digest,
+        "platform_tag": kit.runtime.platform_tag,
+        "runtime_digest": "sha256:" + kit.runtime.digest,
+        "bundle_digest": "sha256:" + kit.bundle_manifest_digest,
+        "release_signature_verified": True,
+        "execution_authority": False,
+    }
+    return {
+        **value,
+        "evidence_digest": "sha256:" + hashlib.sha256(canonical_bytes(value)).hexdigest(),
+    }
+
+
+def _unique(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    result: dict[str, object] = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError("observer artifact request contains duplicate fields")
+        result[key] = value
+    return result
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--request", type=Path, required=True)
+    args = parser.parse_args()
+    try:
+        request = json.loads(
+            read_private_bytes(args.request, max_bytes=16384), object_pairs_hook=_unique
+        )
+        if not isinstance(request, dict) or set(request) != {
+            "offline_kit",
+            "work_dir",
+            "source_commit",
+            "image_digest",
+        }:
+            raise ValueError("observer artifact request is invalid")
+        if not all(isinstance(value, str) and value for value in request.values()):
+            raise ValueError("observer artifact request values are invalid")
+        if (
+            not Path(request["offline_kit"]).is_absolute()
+            or not Path(request["work_dir"]).is_absolute()
+        ):
+            raise ValueError("observer artifact paths must be absolute")
+        result = inspect_observer_artifact(
+            offline_kit=Path(request["offline_kit"]),
+            work_dir=Path(request["work_dir"]),
+            source_commit=request["source_commit"],
+            image_digest=request["image_digest"],
+        )
+        print(json.dumps(result, sort_keys=True))
+        return 0
+    except (OSError, ValueError, RuntimeError):
+        print(
+            json.dumps(
+                {
+                    "status": "unavailable",
+                    "reason": "observer_artifact_verification_failed",
+                    "execution_authority": False,
+                }
+            )
+        )
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())