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

fdai_deployment_cli/standalone_catalog_review.py

@@ -0,0 +1,251 @@
+"""Standalone AKS frozen-scenario catalog-review checkpoint."""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from fdai_deployment_cli.contracts import canonical_digest
+from fdai_deployment_cli.standalone_aks_job_execution import execute_aks_cronjob_once
+from fdai_deployment_cli.standalone_host_state import private_json, replace_private_json
+
+_NAMESPACE = "fdai-runtime"
+_TRIGGER_SCHEMA = "fdai.operational-catalog-review-trigger-receipt.v3"
+_SCHEMA = "fdai.standalone-catalog-review-receipt.v3"
+
+
+def run_catalog_review(
+    context: dict[str, Any],
+    work_dir: Path,
+    *,
+    login: Callable[[dict[str, object], Path], None],
+) -> dict[str, object]:
+    """Run one deployed draft-only review and persist its sanitized receipt."""
+
+    receipt_path = work_dir / "catalog-review-receipt.json"
+    if receipt_path.exists():
+        return _validated_receipt(
+            private_json(receipt_path, "standalone catalog review receipt"),
+            context=context,
+        )
+    if context.get("catalog_review_selected") is not True:
+        receipt: dict[str, object] = {
+            "schema_version": _SCHEMA,
+            "state": "skipped",
+            "selected": False,
+            "reason": "not_selected",
+            "source_revision": str(context.get("source_commit", "")),
+            "catalog_review_profile_digest": str(context.get("catalog_review_profile_digest", "")),
+            "mutation_performed": False,
+            "subscription_ready": False,
+        }
+        receipt["receipt_digest"] = canonical_digest(receipt)
+        replace_private_json(receipt_path, receipt)
+        return receipt
+    if _runtime_platform(context) != "aks":
+        raise ValueError("catalog review one-shot execution requires AKS")
+    if not (work_dir / "application-receipt.json").is_file():
+        raise ValueError("catalog review application prerequisite is incomplete")
+    values = private_json(work_dir / "workloads.auto.tfvars.json", "AKS workload variables")
+    scheduled_jobs = _mapping(values.get("scheduled_jobs"), "AKS scheduled jobs")
+    job = scheduled_jobs.get("catalog-review")
+    if not isinstance(job, dict) or context.get("catalog_review_available") is not True:
+        raise ValueError("catalog review private GitOps binding is unavailable")
+    login(context, work_dir)
+    execution = execute_aks_cronjob_once(
+        context,
+        work_dir,
+        template_name="catalog-review",
+        purpose="catalog-review",
+        expected_container_name="catalog-review",
+        expected_image=str(job.get("image", "")),
+        expected_command=(
+            "python",
+            "-m",
+            "fdai.runtime.operational_catalog_review_trigger",
+        ),
+        expected_service_account="catalog-review-job",
+        args=(),
+        environment={},
+        require_suspended=True,
+        timeout_seconds=360,
+    )
+    kubeconfig = Path(str(context["kubeconfig"]))
+    logs = _capture(
+        (
+            "kubectl",
+            "logs",
+            f"job/{execution.name}",
+            "--namespace",
+            _NAMESPACE,
+            "--container",
+            "catalog-review",
+            "--tail",
+            "20",
+            "--limit-bytes",
+            "65536",
+            f"--kubeconfig={kubeconfig}",
+        ),
+        cwd=work_dir,
+        timeout=60,
+        reason="catalog review sanitized receipt readback failed",
+    )
+    trigger_receipt = _receipt_from_logs(
+        logs,
+        source_revision=str(context.get("source_commit", "")),
+    )
+    receipt = {key: item for key, item in trigger_receipt.items() if key != "receipt_digest"}
+    receipt.update(
+        schema_version=_SCHEMA,
+        selected=True,
+        catalog_review_profile_digest=str(context["catalog_review_profile_digest"]),
+        trigger_receipt_digest=trigger_receipt["receipt_digest"],
+    )
+    receipt["receipt_digest"] = canonical_digest(receipt)
+    replace_private_json(receipt_path, receipt)
+    return receipt
+
+
+def _receipt_from_logs(logs: str, *, source_revision: str) -> dict[str, object]:
+    for line in reversed(logs.splitlines()):
+        try:
+            candidate = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(candidate, dict) and candidate.get("schema_version") == _TRIGGER_SCHEMA:
+            return _validated_trigger_receipt(candidate, source_revision=source_revision)
+    raise ValueError("catalog review sanitized receipt is unavailable")
+
+
+def _validated_trigger_receipt(
+    value: dict[str, Any],
+    *,
+    source_revision: str,
+) -> dict[str, object]:
+    receipt = {str(key): item for key, item in value.items()}
+    supplied_digest = receipt.pop("receipt_digest", None)
+    required_labels = receipt.get("required_labels")
+    observed_labels = receipt.get("observed_labels")
+    if (
+        receipt.get("schema_version") != _TRIGGER_SCHEMA
+        or receipt.get("state") != "draft-review-published"
+        or receipt.get("source_revision") != source_revision
+        or re.fullmatch(r"[0-9a-f]{40}", source_revision) is None
+        or not isinstance(required_labels, list)
+        or any(not isinstance(label, str) for label in required_labels)
+        or len(required_labels) != len(set(required_labels))
+        or required_labels != sorted(required_labels)
+        or observed_labels != required_labels
+        or not {"draft", "shadow", "governance", "catalog-review"}.issubset(required_labels)
+        or sum(isinstance(label, str) and label.startswith("rule:") for label in required_labels)
+        != 1
+        or sum(isinstance(label, str) and label.startswith("action:") for label in required_labels)
+        != 1
+        or receipt.get("draft") is not True
+        or receipt.get("mode") != "shadow"
+        or receipt.get("catalog_activation_performed") is not False
+        or receipt.get("code_path_merge_authority") is not False
+        or receipt.get("independent_pr_observation_required") is not True
+        or receipt.get("independent_pr_observation_verified") is not True
+        or receipt.get("independent_observation_scope") != "gitops-pr"
+        or receipt.get("durable_intent_verified") is not True
+        or receipt.get("durable_terminal_verified") is not True
+        or receipt.get("managed_resource_mutation_status") != "unknown"
+        or receipt.get("managed_resource_mutation_performed") is not None
+        or receipt.get("grants_authority") is not False
+        or not isinstance(receipt.get("already_existed"), bool)
+        or receipt.get("subscription_ready") is not False
+        or any(
+            re.fullmatch(r"[0-9a-f]{64}", str(receipt.get(name, ""))) is None
+            for name in (
+                "candidate_digest",
+                "package_digest",
+                "review_ref_digest",
+                "binding_digest",
+                "publication_observation_digest",
+                "review_document_digest",
+                "durable_audit_digest",
+            )
+        )
+        or re.fullmatch(
+            r"(?:[0-9a-f]{40}|[0-9a-f]{64})",
+            str(receipt.get("publication_head_sha", "")),
+        )
+        is None
+        or supplied_digest != canonical_digest(receipt)
+    ):
+        raise ValueError("catalog review sanitized receipt is invalid")
+    receipt["receipt_digest"] = supplied_digest
+    return receipt
+
+
+def _validated_receipt(
+    value: dict[str, Any],
+    *,
+    context: dict[str, Any],
+) -> dict[str, object]:
+    receipt = {str(key): item for key, item in value.items()}
+    supplied_digest = receipt.pop("receipt_digest", None)
+    if (
+        receipt.get("schema_version") != _SCHEMA
+        or receipt.get("source_revision") != context.get("source_commit")
+        or receipt.get("catalog_review_profile_digest")
+        != context.get("catalog_review_profile_digest")
+        or supplied_digest != canonical_digest(receipt)
+    ):
+        raise ValueError("catalog review sanitized receipt is invalid")
+    selected = context.get("catalog_review_selected") is True
+    if selected:
+        if (
+            receipt.get("selected") is not True
+            or receipt.get("state") != "draft-review-published"
+            or receipt.get("independent_pr_observation_verified") is not True
+            or receipt.get("independent_observation_scope") != "gitops-pr"
+        ):
+            raise ValueError("selected catalog review receipt is incomplete")
+    elif (
+        receipt.get("selected") is not False
+        or receipt.get("state") != "skipped"
+        or receipt.get("reason") != "not_selected"
+    ):
+        raise ValueError("unselected catalog review receipt is invalid")
+    receipt["receipt_digest"] = supplied_digest
+    return receipt
+
+
+def _runtime_platform(context: dict[str, Any]) -> str:
+    value = context.get("runtime_profile")
+    if value is None:
+        return "container-apps"
+    profile = _mapping(value, "runtime deployment profile")
+    platform = profile.get("runtime_platform")
+    if platform not in {"container-apps", "aks"}:
+        raise ValueError("runtime deployment platform is invalid")
+    return str(platform)
+
+
+def _capture(command: tuple[str, ...], *, cwd: Path, timeout: int, reason: str) -> str:
+    result = subprocess.run(
+        command,
+        cwd=cwd,
+        check=False,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+    )
+    if result.returncode != 0:
+        raise ValueError(reason)
+    return result.stdout
+
+
+def _mapping(value: object, label: str) -> dict[str, Any]:
+    if not isinstance(value, dict) or any(not isinstance(key, str) for key in value):
+        raise ValueError(f"{label} is invalid")
+    return {str(key): item for key, item in value.items()}
+
+
+__all__ = ["run_catalog_review"]

fdai_deployment_cli/standalone_checkpoint_failure.py

@@ -0,0 +1,127 @@
+"""Bounded failure summaries for standalone managed-host checkpoints."""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+from typing import Any
+
+_ARM_RESOURCE_ID = re.compile(r"/subscriptions/[^\s\"']+", re.IGNORECASE)
+_GUID = re.compile(r"[0-9a-fA-F]{8}(?:-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}")
+_SECRET_ASSIGNMENT = re.compile(
+    r"(?i)\b(token|secret|password|key|connection[_ -]?string)\b\s*[:=]\s*\S+"
+)
+_HOSTNAME = re.compile(
+    r"\b(?=[A-Za-z0-9.-]{5,253}\b)(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}"
+    r"[A-Za-z0-9])?\.)+(?:[A-Za-z]{2,63})\b"
+)
+_PROVIDER_ERROR_CODE = re.compile(
+    r"\b(?:OverconstrainedZonalAllocationRequest|AllocationFailed|ParameterOutOfRange|"
+    r"[A-Z][A-Za-z0-9]*(?:Failed|Failure|Denied|Error|NotFound|OutOfRange|Request))\b"
+)
+_FAILURE_EXCERPT_LIMIT = 700
+
+
+class ManagedHostCheckpointError(ValueError):
+    """A checkpoint failure that can be returned to the workstation safely."""
+
+    def __init__(
+        self,
+        reason_code: str,
+        message: str,
+        *,
+        provider_error_codes: tuple[str, ...] = (),
+        excerpt: str = "",
+    ) -> None:
+        super().__init__(message)
+        self.reason_code = reason_code
+        self.provider_error_codes = provider_error_codes
+        self.excerpt = excerpt
+
+
+def failure_record(exc: BaseException) -> dict[str, object]:
+    if isinstance(exc, ManagedHostCheckpointError):
+        reason_code = exc.reason_code
+        provider_error_codes = list(exc.provider_error_codes)
+        excerpt = exc.excerpt or sanitize_failure_text(str(exc))
+    else:
+        reason_code = "managed_host_checkpoint_failed"
+        provider_error_codes = provider_error_codes_from_text(str(exc))
+        excerpt = sanitize_failure_text(str(exc))
+    return {
+        "schema_version": "fdai.standalone-host-failure.v1",
+        "state": "failed",
+        "reason_code": reason_code,
+        "provider_error_codes": provider_error_codes,
+        "message_excerpt": excerpt,
+        "mutation_performed": False,
+        "subscription_ready": False,
+    }
+
+
+def remote_failure(result: subprocess.CompletedProcess[object]) -> dict[str, Any] | None:
+    for stream in (getattr(result, "stderr", ""), getattr(result, "stdout", "")):
+        text = (
+            stream.decode("utf-8", errors="replace") if isinstance(stream, bytes) else str(stream)
+        )
+        for line in reversed(text.splitlines()):
+            try:
+                value = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if (
+                isinstance(value, dict)
+                and value.get("schema_version") == "fdai.standalone-host-failure.v1"
+                and isinstance(value.get("reason_code"), str)
+                and isinstance(value.get("message_excerpt"), str)
+            ):
+                return value
+    return None
+
+
+def terraform_failure(reason: str, result: subprocess.CompletedProcess[Any]) -> ValueError:
+    output = "\n".join(
+        _output_part(part)
+        for part in (getattr(result, "stdout", ""), getattr(result, "stderr", ""))
+        if part not in (None, b"", "")
+    )
+    codes = tuple(provider_error_codes_from_text(output))
+    if codes:
+        # Terraform prints progress before diagnostics; the bounded excerpt must keep the error.
+        first_error = output.find("Error: ")
+        excerpt = sanitize_failure_text(output[first_error:] if first_error >= 0 else output)
+        return ManagedHostCheckpointError(
+            "terraform_provider_error",
+            f"{reason}; provider_error_code={','.join(codes)}; excerpt={excerpt}",
+            provider_error_codes=codes,
+            excerpt=excerpt,
+        )
+    return ValueError(reason)
+
+
+def sanitize_failure_text(value: object) -> str:
+    text = value.decode("utf-8", errors="replace") if isinstance(value, bytes) else str(value)
+    text = _ARM_RESOURCE_ID.sub("<redacted-resource-id>", text)
+    text = _GUID.sub("<redacted-guid>", text)
+    text = _SECRET_ASSIGNMENT.sub(lambda match: f"{match.group(1)}=<redacted-secret>", text)
+    text = re.sub(r"(?i)\bBearer\s+[A-Za-z0-9._~+/=-]+", "Bearer <redacted-token>", text)
+    text = _HOSTNAME.sub("<redacted-hostname>", text)
+    text = re.sub(r"\s+", " ", text).strip()
+    if len(text) > _FAILURE_EXCERPT_LIMIT:
+        return text[: _FAILURE_EXCERPT_LIMIT - 3].rstrip() + "..."
+    return text
+
+
+def provider_error_codes_from_text(value: object) -> list[str]:
+    codes: list[str] = []
+    text = value.decode("utf-8", errors="replace") if isinstance(value, bytes) else str(value)
+    for match in _PROVIDER_ERROR_CODE.finditer(text):
+        code = match.group(0)
+        if code not in codes:
+            codes.append(code)
+    return codes[:5]
+
+
+def _output_part(value: object) -> str:
+    return value.decode("utf-8", errors="replace") if isinstance(value, bytes) else str(value)

fdai_deployment_cli/standalone_console_publish.py

@@ -0,0 +1,174 @@
+"""Publish the verified standalone Console artifact."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import shutil
+import stat
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from fdai_deployment_cli.bundle import extract_bundle_archive
+from fdai_deployment_cli.console_config import configure_console
+from fdai_deployment_cli.contracts import canonical_digest
+from fdai_deployment_cli.private_output import write_private_output
+from fdai_deployment_cli.standalone_host_state import replace_private_json
+
+_DIGEST = re.compile(r"[0-9a-f]{64}")
+_PUBLISHER_FIXED_REASON = re.compile(r'echo "([^"$`\\]+)" >&2')
+
+
+def publish_verified_console(
+    *,
+    console_archive: Path,
+    console_archive_sha256: str,
+    bundle_root: Path,
+    prepared_root: Path,
+    entra_bindings: dict[str, str],
+    browser_console: dict[str, Any],
+    scripts: Path,
+    subscription_id: str,
+    tenant_id: str,
+    timeout_seconds: int,
+    redirect_changed: bool,
+    verify_only: bool = False,
+    verify_service_contracts: bool = True,
+) -> dict[str, object]:
+    """Configure a verified Console artifact, publish it, and read back exact bytes."""
+
+    _require_archive_digest(console_archive, console_archive_sha256)
+    extraction = prepared_root / "console-publish"
+    # A retained extraction may contain a prior release, not the just-verified archive.
+    _remove_retained_extraction(extraction)
+    console_directory = extract_bundle_archive(console_archive, extraction)
+    console_directory.chmod(0o700)
+    settings: dict[str, object] = {
+        "schema_version": "fdai.console-runtime.v1",
+        "operator_api_base_url": str(browser_console["operator_api_base_url"]),
+        "ingestion_api_base_url": str(browser_console["ingestion_api_base_url"]),
+        "tenant_id": tenant_id,
+        "spa_client_id": str(entra_bindings["ENTRA_CONSOLE_SPA_CLIENT_ID"]),
+        "api_scope": str(entra_bindings["ENTRA_CONSOLE_API_SCOPE"]),
+    }
+    settings_path = prepared_root / "console-runtime-settings.json"
+    replace_private_json(settings_path, settings)
+    configured = configure_console(
+        console_directory,
+        settings_path,
+        manual_studio_url=f"{browser_console['console_origin']}/manuals",
+    )
+    summary = prepared_root / "console-publish-summary.txt"
+    if not summary.exists():
+        write_private_output(summary, "")
+    environment: dict[str, str] = {
+        **os.environ,
+        "EXPECTED_AZURE_TENANT_ID": str(settings["tenant_id"]),
+        "ENTRA_CONSOLE_SPA_CLIENT_ID": str(settings["spa_client_id"]),
+        "ENTRA_CONSOLE_API_SCOPE": str(settings["api_scope"]),
+        "ARM_SUBSCRIPTION_ID": subscription_id,
+        "CONSOLE_DEFAULT_HOSTNAME": str(browser_console["console_hostname"]),
+        "CONSOLE_STATIC_WEB_APP_ID": str(browser_console["console_static_web_app_id"]),
+        "BROWSER_GATEWAY_OPERATOR_URL": str(settings["operator_api_base_url"]),
+        "BROWSER_GATEWAY_INGESTION_URL": str(settings["ingestion_api_base_url"]),
+        "CONSOLE_PREBUILT_DIRECTORY": str(console_directory),
+        "FDAI_CONSOLE_VERIFY_ONLY": "1" if verify_only else "0",
+        "FDAI_CONSOLE_VERIFY_SERVICE_CONTRACTS": "1" if verify_service_contracts else "0",
+        "GITHUB_STEP_SUMMARY": str(summary),
+    }
+    completed = subprocess.run(
+        (
+            "/bin/bash",
+            str(scripts / "publish-console.sh"),
+            str(bundle_root / "infra/runtimes/aks/workloads"),
+        ),
+        cwd=bundle_root,
+        env=environment,
+        check=False,
+        capture_output=True,
+        text=True,
+        timeout=timeout_seconds,
+    )
+    if completed.returncode != 0:
+        reason = _publisher_failure_reason(scripts / "publish-console.sh", completed.stderr)
+        raise ValueError(
+            "prebuilt Console publication or browser verification failed"
+            + (f": {reason}" if reason else "")
+        )
+    receipt: dict[str, object] = {
+        "schema_version": "fdai.standalone-console-publication.v1",
+        "state": "verified" if verify_only else "published",
+        "console_origin": browser_console["console_origin"],
+        "console_archive_sha256": console_archive_sha256,
+        "runtime_config_digest": configured["runtime_config_digest"],
+        "entra_redirect_changed": redirect_changed,
+        "artifact_hash_verified": True,
+        "spa_fallback_verified": True,
+        "api_health_verified": verify_service_contracts,
+        "authorization_preflight_verified": verify_service_contracts,
+        "unauthenticated_denial_verified": verify_service_contracts,
+        "entra_redirect_verified": verify_service_contracts,
+        "mutation_performed": not verify_only,
+        "subscription_ready": False,
+    }
+    receipt["receipt_digest"] = canonical_digest(receipt)
+    replace_private_json(prepared_root / "console-publication-receipt.json", receipt)
+    return receipt
+
+
+def _publisher_failure_reason(publisher: Path, stderr: str | None) -> str | None:
+    """Return the publisher's final literal failure reason, never a variable diagnostic."""
+
+    try:
+        fixed_reasons = set(_PUBLISHER_FIXED_REASON.findall(publisher.read_text(encoding="utf-8")))
+    except OSError:
+        return None
+    for line in reversed((stderr or "").splitlines()):
+        if line.strip():
+            return line.strip() if line.strip() in fixed_reasons else None
+    return None
+
+
+def _remove_retained_extraction(extraction: Path) -> None:
+    """Remove a prior Console extraction without following a substituted link."""
+
+    try:
+        status = extraction.lstat()
+    except FileNotFoundError:
+        return
+    if not stat.S_ISDIR(status.st_mode) or status.st_uid != os.getuid():
+        raise ValueError("retained Console extraction is not a private directory")
+    shutil.rmtree(extraction)
+
+
+def _require_archive_digest(path: Path, expected_digest: str) -> None:
+    if _DIGEST.fullmatch(expected_digest) is None:
+        raise ValueError("Console archive digest is invalid")
+    descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW)
+    try:
+        before = os.fstat(descriptor)
+        if not stat.S_ISREG(before.st_mode):
+            raise ValueError("Console archive is not a regular file")
+        with os.fdopen(descriptor, "rb", closefd=False) as stream:
+            observed = hashlib.file_digest(stream, "sha256").hexdigest()
+        after = os.fstat(descriptor)
+        if (
+            before.st_dev,
+            before.st_ino,
+            before.st_size,
+            before.st_mtime_ns,
+            before.st_ctime_ns,
+        ) != (
+            after.st_dev,
+            after.st_ino,
+            after.st_size,
+            after.st_mtime_ns,
+            after.st_ctime_ns,
+        ):
+            raise ValueError("Console archive changed while it was read")
+        if observed != expected_digest:
+            raise ValueError("Console archive digest does not match the signed release")
+    finally:
+        os.close(descriptor)

fdai_deployment_cli/standalone_database_principals.py

@@ -0,0 +1,41 @@
+"""Principal selection for the in-cluster PostgreSQL stage of an AKS installation."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from fdai_deployment_cli.standalone_operational_evidence import (
+    runtime_principal_ids_with_operational_evidence_verifier,
+)
+
+
+def database_reader_principals(
+    identities: Mapping[str, Any],
+) -> tuple[set[str], str | None, str | None]:
+    """Return the DSN reader principals for the in-cluster database stage.
+
+    Core and inventory always run. The Operator, executor, and document-ingestion identities exist
+    only when their product option is selected, so an absent one is granted nothing instead of
+    stopping the stage. A present identity must still be well formed.
+    """
+
+    names = tuple(
+        name
+        for name in ("core", "operator", "executor", "inventory")
+        if name in {"core", "inventory"} or identities.get(name) is not None
+    )
+
+    def optional(name: str, label: str) -> str | None:
+        value = identities.get(name)
+        if value is None:
+            return None
+        if not isinstance(value, dict) or not isinstance(value.get("principal_id"), str):
+            raise ValueError(f"{label} is invalid")
+        return str(value["principal_id"])
+
+    return (
+        runtime_principal_ids_with_operational_evidence_verifier(identities, names),
+        optional("ingestion", "ingestion runtime identity"),
+        optional("ingestion_worker", "ingestion worker runtime identity"),
+    )