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

fdai_deployment_cli/github_workflow_values.py

@@ -0,0 +1,312 @@
+"""Validated immutable values for protected GitHub workflow operations."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+from fdai_deployment_cli.contracts import canonical_digest
+
+_REPOSITORY = re.compile(r"^[A-Za-z0-9_.-]{1,100}/[A-Za-z0-9_.-]{1,100}$")
+
+_COMMIT = re.compile(r"^[0-9a-f]{40}$")
+
+_DIGEST = re.compile(r"^[0-9a-f]{64}$")
+
+_OCI_DIGEST = re.compile(r"^sha256:[0-9a-f]{64}$")
+
+_PROVIDER_SOURCE_REVISION = re.compile(r"^[0-9a-f]{40,64}$")
+
+_PLAN_ID = re.compile(r"^plan-[1-9][0-9]*-[1-9][0-9]*$")
+
+_REQUEST_ID = re.compile(
+    r"^(?:plan|apply)-(?:cost-|history-|identity-|provider-cost-|provider-|rca-)?"
+    r"[0-9a-f]{48}$"
+)
+
+_ENVIRONMENTS = frozenset({"dev", "staging", "prod"})
+
+_RUNTIME_IMAGE_PROFILES = frozenset({"core-control-plane", "cost-governance"})
+
+_BOOL_INPUTS = (
+    "deploy_console",
+    "deploy_dev_operations_gateway",
+    "deploy_document_ingestion",
+    "deploy_identity_migration",
+    "deploy_isolated_executor",
+    "deploy_monitoring",
+    "deploy_operational_history",
+    "deploy_operator_api",
+)
+
+_EXPIRES_AT_RE = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$")
+
+
+@dataclass(frozen=True, slots=True)
+class CommandResult:
+    """Bounded process result from one fixed GitHub CLI invocation."""
+
+    returncode: int
+    stdout: str
+    stderr: str = ""
+
+
+CommandRunner = Callable[[tuple[str, ...]], CommandResult]
+
+
+@dataclass(frozen=True, slots=True)
+class DeploymentSelection:
+    """Feature selection sealed into both protected plan and apply requests."""
+
+    deploy_console: bool = True
+    deploy_dev_operations_gateway: bool = False
+    deploy_document_ingestion: bool = False
+    deploy_identity_migration: bool = False
+    deploy_isolated_executor: bool = False
+    deploy_monitoring: bool = False
+    deploy_operational_history: bool = False
+    deploy_operator_api: bool = True
+    deploy_operator_channel_edge: bool = False
+    deploy_provider_schema: bool = False
+    deploy_rca_reader_identity: bool = False
+    runtime_image_revision: str = ""
+    runtime_image_profile: str = "core-control-plane"
+
+    def __post_init__(self) -> None:
+        application_targets = (
+            self.deploy_console,
+            self.deploy_dev_operations_gateway,
+            self.deploy_document_ingestion,
+            self.deploy_isolated_executor,
+            self.deploy_operational_history,
+            self.deploy_operator_api,
+            self.deploy_operator_channel_edge,
+            self.deploy_provider_schema,
+        )
+        if self.deploy_monitoring and not any(application_targets) and self.runtime_image_revision:
+            raise ValueError("monitoring-only deployment cannot specify runtime_image_revision")
+        if self.runtime_image_revision and _COMMIT.fullmatch(self.runtime_image_revision) is None:
+            raise ValueError("runtime_image_revision MUST be a lowercase 40-character git SHA")
+        if self.runtime_image_profile not in _RUNTIME_IMAGE_PROFILES:
+            raise ValueError("runtime_image_profile is unsupported")
+        if self.runtime_image_profile != "core-control-plane" and not self.runtime_image_revision:
+            raise ValueError("non-default runtime_image_profile requires runtime_image_revision")
+        if self.runtime_image_profile != "core-control-plane" and (
+            self.deploy_identity_migration
+            or self.deploy_operational_history
+            or self.deploy_rca_reader_identity
+        ):
+            raise ValueError(
+                "non-default runtime_image_profile cannot be combined with a bounded operation"
+            )
+        if self.deploy_provider_schema:
+            provider_schema_mixed = (
+                self.deploy_console,
+                self.deploy_dev_operations_gateway,
+                self.deploy_document_ingestion,
+                self.deploy_identity_migration,
+                self.deploy_isolated_executor,
+                self.deploy_monitoring,
+                self.deploy_operational_history,
+                self.deploy_operator_api,
+                self.deploy_operator_channel_edge,
+                self.deploy_rca_reader_identity,
+            )
+            if any(provider_schema_mixed):
+                raise ValueError(
+                    "deploy_provider_schema cannot be combined with another deployment target"
+                )
+            if not self.runtime_image_revision:
+                raise ValueError("deploy_provider_schema requires runtime_image_revision")
+        if self.deploy_rca_reader_identity and (
+            any(application_targets) or self.deploy_monitoring or self.runtime_image_revision
+        ):
+            raise ValueError(
+                "deploy_rca_reader_identity cannot be combined with another deployment target"
+            )
+        if self.deploy_identity_migration and (
+            any(application_targets)
+            or self.deploy_monitoring
+            or self.deploy_operational_history
+            or self.deploy_rca_reader_identity
+            or self.runtime_image_revision
+        ):
+            raise ValueError(
+                "deploy_identity_migration cannot be combined with another bounded operation"
+            )
+
+    def to_mapping(self) -> dict[str, bool | str]:
+        """Return workflow input names in stable order."""
+
+        result: dict[str, bool | str] = {name: bool(getattr(self, name)) for name in _BOOL_INPUTS}
+        if self.deploy_operator_channel_edge:
+            result["deploy_operator_channel_edge"] = True
+        if self.deploy_provider_schema:
+            result["deploy_provider_schema"] = True
+        result["deploy_rca_reader_identity"] = self.deploy_rca_reader_identity
+        result["document_ocr_action"] = "preserve"
+        result["runtime_call_evidence_transition"] = False
+        result["runtime_image_revision"] = self.runtime_image_revision
+        result["runtime_image_profile"] = self.runtime_image_profile
+        return result
+
+
+@dataclass(frozen=True, slots=True)
+class WorkflowDispatch:
+    """Sanitized receipt for one accepted workflow dispatch."""
+
+    request_id: str
+    run_name: str
+    context_digest: str
+    mode: str
+
+    def to_mapping(self) -> dict[str, object]:
+        """Return stable dispatch output without credentials or target identifiers."""
+
+        return {
+            "schema_version": "fdai.workflow-dispatch.v1",
+            "request_id": self.request_id,
+            "run_name": self.run_name,
+            "context_digest": self.context_digest,
+            "mode": self.mode,
+            "mutation_performed": True,
+        }
+
+
+def parse_plan_expiry(expires_at: str) -> datetime:
+    """Parse a strict ISO-8601 UTC timestamp or raise fail-closed."""
+
+    if _EXPIRES_AT_RE.fullmatch(expires_at) is None:
+        raise ValueError("expires_at MUST be an ISO-8601 UTC timestamp ending in Z")
+    try:
+        return datetime.fromisoformat(expires_at)
+    except ValueError as exc:
+        raise ValueError("expires_at contains an invalid date or time") from exc
+
+
+def enforce_plan_not_expired(
+    expires_at: str,
+    *,
+    now: datetime | None = None,
+) -> None:
+    """Fail-closed: reject expired plans before apply dispatch."""
+
+    deadline = parse_plan_expiry(expires_at)
+    current = now if now is not None else datetime.now(UTC)
+    if current >= deadline:
+        raise ValueError("protected plan has expired; replan before applying")
+
+
+def deployment_context_digest(
+    *,
+    environment: str,
+    commit_sha: str,
+    selection: DeploymentSelection,
+) -> str:
+    """Seal the non-secret deployment inputs shared by plan and apply."""
+
+    if environment not in _ENVIRONMENTS:
+        raise ValueError("environment is unsupported")
+    if _COMMIT.fullmatch(commit_sha) is None:
+        raise ValueError("commit_sha MUST be a lowercase git SHA")
+    return canonical_digest(
+        {
+            "schema_version": "fdai.deployment-context.v1",
+            "environment": environment,
+            "commit_sha": commit_sha,
+            "selection": selection.to_mapping(),
+        }
+    )
+
+
+def request_id(
+    mode: str,
+    *,
+    run_id: str,
+    context_digest: str,
+    target_binding: str,
+    region: str,
+    attempt: int = 1,
+) -> str:
+    """Derive one bounded request id without exposing the local run id."""
+
+    if mode not in {"plan", "apply", "resume"}:
+        raise ValueError("workflow request mode is unsupported")
+    if not run_id or len(run_id) > 128:
+        raise ValueError("run_id MUST be from 1 through 128 characters")
+    if _DIGEST.fullmatch(context_digest) is None:
+        raise ValueError("context_digest MUST be a lowercase SHA-256")
+    if _DIGEST.fullmatch(target_binding) is None:
+        raise ValueError("target_binding MUST be a lowercase SHA-256")
+    if not region or len(region) > 64:
+        raise ValueError("region is invalid")
+    if not 1 <= attempt <= 9_999:
+        raise ValueError("workflow attempt MUST be from 1 through 9999")
+    binding = request_binding_prefix(
+        target_binding=target_binding,
+        context_digest=context_digest,
+        mode=mode,
+        region=region,
+    )
+    run_key = canonical_digest({"run_id": run_id})[:20]
+    suffix = f"{binding}{run_key}{attempt:04x}"
+    prefix = "apply" if mode == "resume" else mode
+    return f"{prefix}-{suffix}"
+
+
+def _request_binding_from_id(request_id_value: str) -> str:
+    """Return the target/context binding embedded in one validated request id."""
+
+    for prefix in (
+        "plan-history-",
+        "apply-history-",
+        "plan-identity-",
+        "apply-identity-",
+        "plan-provider-cost-",
+        "apply-provider-cost-",
+        "plan-provider-",
+        "apply-provider-",
+        "plan-rca-",
+        "apply-rca-",
+        "plan-cost-",
+        "apply-cost-",
+        "plan-",
+        "apply-",
+    ):
+        if request_id_value.startswith(prefix):
+            return request_id_value.removeprefix(prefix)[:24]
+    raise ValueError("request_id is invalid")
+
+
+def request_binding_prefix(
+    *,
+    target_binding: str,
+    context_digest: str,
+    mode: str,
+    region: str,
+) -> str:
+    """Return the target-bound prefix independently recomputed by the workflow."""
+
+    if _DIGEST.fullmatch(target_binding) is None:
+        raise ValueError("target_binding MUST be a lowercase SHA-256")
+    if _DIGEST.fullmatch(context_digest) is None:
+        raise ValueError("context_digest MUST be a lowercase SHA-256")
+    if mode not in {"plan", "apply", "resume"}:
+        raise ValueError("workflow request mode is unsupported")
+    if not region or len(region) > 64:
+        raise ValueError("region is invalid")
+    return canonical_digest(
+        {
+            "target_binding": target_binding,
+            "context_digest": context_digest,
+            "mode": mode,
+            "region": region.casefold(),
+        }
+    )[:24]
+
+
+def _validate_repository(repository: str) -> None:
+    if _REPOSITORY.fullmatch(repository) is None or ".." in repository:
+        raise ValueError("repository MUST be owner/name")

fdai_deployment_cli/hub_image_deploy.py

@@ -0,0 +1,354 @@
+"""Connected image-bootstrap inputs and public, self-reported request intake."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import http.client
+import os
+import re
+import ssl
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+from uuid import UUID
+
+from fdai_deployment_cli.contracts import canonical_bytes, canonical_digest, load_json_object
+from fdai_deployment_cli.hub_image_trust import (
+    MAX_EXPORT_BYTES,
+    MAX_SELECTION_BYTES,
+    HubImageSelection,
+    load_selection,
+    public_key,
+    selection_bytes,
+    validate_channel,
+    verify_export,
+)
+from fdai_deployment_cli.private_output import read_private_bytes, write_private_bytes
+from fdai_deployment_cli.source_input import inspect_source
+
+DEFAULT_HUB_URL = "https://hub.msfdai.com"
+
+
+def hub_source_inputs(args: argparse.Namespace) -> tuple[bool, Path | None, Path | None]:
+    hub_mode = args.hub is not None
+    source_root = args.hub if hub_mode else args.source
+    if not hub_mode and any(
+        getattr(args, name) is not None
+        for name in ("hub_url", "hub_public_key", "hub_release", "hub_channel")
+    ):
+        raise ValueError("Hub options require --hub and cannot modify source or offline mode")
+    hub_key = args.hub_public_key
+    if hub_mode and hub_key is None and os.environ.get("FDAI_HUB_PUBLIC_KEY"):
+        hub_key = Path(os.environ["FDAI_HUB_PUBLIC_KEY"])
+    if hub_mode and hub_key is None:
+        raise ValueError(
+            "--hub requires --hub-public-key PATH or FDAI_HUB_PUBLIC_KEY; provision the "
+            "Ed25519 public key independently, never download a TOFU key from the Hub"
+        )
+    if hub_mode and args.runtime != "aks":
+        raise ValueError("Hub image bootstrap currently requires AKS")
+    return hub_mode, source_root, hub_key
+
+
+def deployment_work_dir(args: argparse.Namespace) -> Path:
+    selected_dir: Path | None = args.work_dir
+    if selected_dir is None:
+        selected_dir = Path.home() / (
+            ".local/state/fdai/azure-hub"
+            if args.hub is not None
+            else ".local/state/fdai/azure-source"
+            if args.source is not None
+            else ".local/state/fdai/azure"
+        )
+    return selected_dir if selected_dir.is_absolute() else Path.cwd() / selected_dir
+
+
+def prepare_cli_selection(
+    args: argparse.Namespace, work_dir: Path, source_root: Path | None, hub_key: Path | None
+) -> HubImageSelection | None:
+    """Seal Hub inputs without permitting source/offline reuse of a retained Hub run."""
+    if args.hub is not None:
+        assert source_root is not None and hub_key is not None
+        if args.teardown:
+            raise ValueError(
+                "Hub image bootstrap does not authorize teardown; retain the run for review"
+            )
+        return prepare_hub_selection(
+            source_root=source_root,
+            work_dir=work_dir,
+            public_key_path=hub_key,
+            hub_url=DEFAULT_HUB_URL if args.hub_url is None else args.hub_url,
+            channel="RELEASE" if args.hub_channel is None else args.hub_channel,
+            release_id=args.hub_release,
+        )
+    if (work_dir / "hub-images").exists():
+        raise ValueError("source or offline artifact mode cannot reuse a Hub-image work directory")
+    return None
+
+
+def bind_support_receipt(
+    result: dict[str, Any], selection: HubImageSelection | None, *, require_receipt: bool = False
+) -> None:
+    """Preserve the support receipt identity before binding signed image provenance."""
+    if selection is not None:
+        result.update(selection.metadata())
+        if require_receipt or "receipt_digest" in result:
+            result["support_receipt_digest"] = result.pop("receipt_digest")
+            result["receipt_digest"] = canonical_digest(result)
+
+
+def application_selection(
+    selection: HubImageSelection | None, source_mode: bool, prepared: Any
+) -> HubImageSelection | None:
+    """Reverify Hub provenance without adding source/offline preparation prerequisites."""
+    if selection is not None:
+        selection = load_selection(selection.path, selection.digest)
+        if not source_mode or selection.source_commit != prepared.source_commit:
+            raise ValueError("Hub images require the matching checkout support snapshot")
+    return selection
+
+
+def source_binding(
+    snapshot_digest: str | None, selection: HubImageSelection | None
+) -> dict[str, object]:
+    return {
+        "source_snapshot_digest": snapshot_digest,
+        "provenance": "operator-selected-source",
+        **(selection.metadata() if selection is not None else {}),
+    }
+
+
+def require_retained_hub_recovery(
+    selection: HubImageSelection, *, work_dir: Path, target_binding: str
+) -> None:
+    """Check the original mode and human target before recovery can advance any effect."""
+    intent = load_json_object(
+        read_private_bytes(work_dir / "source-intent.json", max_bytes=65_536),
+        label="retained Hub support intent",
+        strict=True,
+    )
+    marker = load_json_object(
+        read_private_bytes(work_dir / "foundation/source-genesis.json", max_bytes=65_536),
+        label="retained Hub Foundation binding",
+        strict=True,
+    )
+    digest = marker.pop("receipt_digest", None)
+    if (
+        intent.get("hub_selection_digest") != selection.digest
+        or intent.get("artifact_source") != "hub-signed-images"
+        or canonical_digest(marker) != digest
+        or marker.get("target_binding") != target_binding
+        or marker.get("source_commit") != selection.source_commit
+    ):
+        raise ValueError("Hub recovery mode, Release or selected Azure target drifted")
+
+
+def validate_hub_url(url: str) -> str:
+    parsed = urlsplit(url)
+    if (
+        len(url) > 512
+        or parsed.scheme != "https"
+        or not parsed.hostname
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.path not in {"", "/"}
+        or parsed.query
+        or parsed.fragment
+        or re.fullmatch(r"https://[a-z0-9][a-z0-9.-]*(?::[1-9][0-9]{0,4})?/?", url) is None
+    ):
+        raise ValueError("Hub URL must be one explicit HTTPS origin without credentials or path")
+    if parsed.port is not None and parsed.port > 65535:
+        raise ValueError("Hub HTTPS port is invalid")
+    return url.rstrip("/")
+
+
+def hub_request(
+    hub_url: str, path: str, *, body: bytes | None = None
+) -> tuple[int, dict[str, str], bytes]:
+    """One bounded TLS request, without proxies, redirects, tokens or automatic retries."""
+    origin = urlsplit(validate_hub_url(hub_url))
+    assert origin.hostname is not None
+    if path not in {"/v1/catalog/export", "/v1/deployment-requests"}:
+        raise ValueError("Hub request path is not allowed")
+    limit = MAX_EXPORT_BYTES if body is None else 16_384
+    connection = http.client.HTTPSConnection(
+        origin.hostname, origin.port or 443, timeout=15, context=ssl.create_default_context()
+    )
+    deadline = time.monotonic() + 30
+    try:
+        headers = {"Accept": "application/json", "Connection": "close"}
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+        connection.request("GET" if body is None else "POST", path, body=body, headers=headers)
+        response = connection.getresponse()
+        if response.status not in ({200} if body is None else {200, 201}):
+            raise ValueError(
+                f"Hub request was refused (HTTP {response.status}); redirects and "
+                "source-build fallback are disabled"
+            )
+        if response.getheader("Content-Encoding", "identity") != "identity":
+            raise ValueError("Hub response encoding is unsupported")
+        length = response.getheader("Content-Length")
+        if length is not None and (not length.isdecimal() or int(length) > limit):
+            raise ValueError("Hub response exceeds its size bound")
+        result = bytearray()
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise ValueError("Hub request deadline exceeded")
+            if connection.sock is not None:
+                connection.sock.settimeout(min(15, remaining))
+            chunk = response.read1(min(65_536, limit + 1 - len(result)))
+            if not chunk:
+                break
+            result.extend(chunk)
+            if len(result) > limit:
+                raise ValueError("Hub response exceeds its size bound")
+        if length is not None and len(result) != int(length):
+            raise ValueError("Hub response body is incomplete")
+        signature_headers: dict[str, str] = {}
+        for name in ("X-FDAI-Export-Signature", "X-FDAI-Export-Key-Id"):
+            values = response.headers.get_all(name, [])
+            if len(values) > 1:
+                raise ValueError("Hub response has ambiguous signature headers")
+            signature_headers[name.lower()] = values[0] if values else ""
+        return response.status, signature_headers, bytes(result)
+    except (TimeoutError, OSError, http.client.HTTPException) as error:
+        raise ValueError(
+            "Hub network request failed; preserve retained inputs and inspect any pending "
+            "deployment request before retrying. No automatic retry or source-build fallback."
+        ) from error
+    finally:
+        connection.close()
+
+
+def prepare_hub_selection(
+    *,
+    source_root: Path,
+    work_dir: Path,
+    public_key_path: Path,
+    hub_url: str = DEFAULT_HUB_URL,
+    channel: str = "RELEASE",
+    release_id: str | None = None,
+) -> HubImageSelection:
+    """Verify before any Azure call and seal a selection that reruns cannot retarget."""
+    hub_url = validate_hub_url(hub_url)
+    validate_channel(channel)
+    with public_key_path.open("rb") as stream:
+        pem = stream.read(4097)
+    public_key(pem)
+    source = inspect_source(source_root)
+    if work_dir.resolve().is_relative_to(source.root):
+        raise ValueError("Hub work directory must be outside the selected checkout")
+    inputs = work_dir / "hub-images"
+    path = inputs / "selection.json"
+    previous = None
+    if path.exists():
+        raw = read_private_bytes(path, max_bytes=MAX_SELECTION_BYTES)
+        previous = load_selection(path, hashlib.sha256(raw).hexdigest())
+        if (
+            previous.document["hub_url"] != hub_url
+            or previous.document["channel"] != channel
+            or previous.document["public_key"] != pem.decode("ascii")
+            or release_id not in {None, previous.release_id}
+        ):
+            raise ValueError(
+                "Hub selection mode, origin, channel, key or Release drift; use a new work directory"
+            )
+        release_id = previous.release_id
+    elif work_dir.exists() and any(work_dir.iterdir()):
+        raise ValueError("Hub images cannot adopt source, kit, or partial work state")
+    _, headers, raw = hub_request(hub_url, "/v1/catalog/export")
+    verified = verify_export(
+        raw,
+        signature=headers["x-fdai-export-signature"],
+        export_key_id=headers["x-fdai-export-key-id"],
+        trusted_pem=pem,
+        channel=channel,
+        release_id=release_id,
+        minimum_revision=previous.document["catalog_revision"] if previous else 0,
+        previous_digest=previous.document["catalog_digest"] if previous else None,
+    )
+    if source.commit != verified["source_commit"]:
+        raise ValueError(
+            "Hub Release source_commit differs from checkout migrations and Console. "
+            f"Check out the exact approved commit {verified['source_commit']} and rerun; "
+            "no Azure deployment effect or source-build fallback was attempted."
+        )
+    selected = selection_bytes(
+        raw=raw,
+        signature=headers["x-fdai-export-signature"],
+        export_key_id=headers["x-fdai-export-key-id"],
+        pem=pem,
+        hub_url=hub_url,
+        channel=channel,
+        verified=verified,
+    )
+    digest = hashlib.sha256(selected).hexdigest()
+    if previous is not None:
+        if digest != previous.digest:
+            raise ValueError(
+                "Hub immutable catalog selection changed; preserve this run and use a new work directory"
+            )
+        return previous
+    inputs.mkdir(mode=0o700, parents=True, exist_ok=True)
+    work_dir.chmod(0o700)
+    write_private_bytes(path, selected)
+    return load_selection(path, digest)
+
+
+def record_deployment_request(
+    selection: HubImageSelection, *, subscription_id: str, region: str
+) -> dict[str, object]:
+    """Record self-reported metadata once; uncertain mutations remain an explicit stop."""
+    subscription_id = str(UUID(subscription_id))
+    if re.fullmatch(r"[a-z][a-z0-9]{0,63}", region) is None:
+        raise ValueError("Hub deployment request region is invalid")
+    payload = {
+        "subscription_id": subscription_id,
+        "release_id": selection.release_id,
+        "channel": selection.document["channel"],
+        "region": region,
+        "source_commit": selection.source_commit,
+        "catalog_digest": selection.document["catalog_digest"],
+    }
+    payload["request_id"] = hashlib.sha256(canonical_bytes(payload)).hexdigest()
+    root = selection.path.parent
+    pending, receipt = root / "request-pending.json", root / "request-receipt.json"
+    if pending.exists():
+        retained = load_json_object(
+            read_private_bytes(pending, max_bytes=16_384), label="Hub request", strict=True
+        )
+        if retained != payload:
+            raise ValueError("Hub deployment request target or inputs drifted")
+        if not receipt.exists():
+            raise ValueError(
+                "Hub deployment request has an uncertain outcome. Inspect its retained "
+                "request_id with a Hub operator; do not automatically resubmit."
+            )
+        result = load_json_object(
+            read_private_bytes(receipt, max_bytes=16_384), label="Hub request receipt", strict=True
+        )
+    else:
+        if receipt.exists():
+            raise ValueError("Hub request pending evidence is missing")
+        write_private_bytes(pending, canonical_bytes(payload))
+        _, _, raw = hub_request(
+            selection.document["hub_url"], "/v1/deployment-requests", body=canonical_bytes(payload)
+        )
+        result = load_json_object(raw, label="Hub request response", max_bytes=16_384, strict=True)
+    if (
+        set(result) != set(payload) | {"status", "trust", "recorded_at"}
+        or any(result.get(name) != value for name, value in payload.items())
+        or result["status"] != "requested"
+        or result["trust"] != "self-reported"
+        or not isinstance(result["recorded_at"], str)
+        or datetime.fromisoformat(result["recorded_at"]).tzinfo is None
+    ):
+        raise ValueError("Hub request receipt differs; deployment is stopped")
+    if not receipt.exists():
+        write_private_bytes(receipt, canonical_bytes(result))
+    return result