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

fdai_deployment_cli/console_artifact.py

@@ -0,0 +1,218 @@
+"""Build a deterministic Console update artifact from protected Git source."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from fdai_deployment_cli.console_config import MANUAL_STUDIO_PLACEHOLDER_URL
+from fdai_deployment_cli.console_update import _regular_digest
+from fdai_deployment_cli.private_output import _open_private_parent, write_private_output
+
+_COMMIT = re.compile(r"[0-9a-f]{40}")
+
+
+def build_console_update_artifact(
+    *,
+    source_root: Path,
+    revision: str,
+    output_dir: Path,
+    timeout_seconds: int = 900,
+    require_protected_revision: bool = True,
+) -> dict[str, object]:
+    """Build one preconfigured-placeholder Console archive without Azure access.
+
+    A source deployment pins its own verified checkout commit and needs no protected branch, so it
+    passes `require_protected_revision=False`; the Console update command keeps the default.
+    """
+
+    if not 60 <= timeout_seconds <= 1800:
+        raise ValueError("Console artifact timeout MUST be between 60 and 1800 seconds")
+    if not source_root.is_absolute() or not source_root.is_dir() or source_root.is_symlink():
+        raise ValueError("Console artifact source MUST be an absolute regular directory")
+    if not output_dir.is_absolute() or output_dir.exists() or output_dir.is_symlink():
+        raise ValueError("Console artifact output MUST be a new absolute directory")
+    parent = _open_private_parent(output_dir)
+    os.close(parent)
+    source_commit = _resolve_revision(
+        source_root,
+        revision,
+        timeout_seconds=60,
+        require_protected_revision=require_protected_revision,
+    )
+    epoch = _git(
+        source_root,
+        "show",
+        "-s",
+        "--format=%ct",
+        source_commit,
+        timeout_seconds=60,
+    ).stdout.strip()
+    if not epoch.isdigit():
+        raise ValueError("Console artifact source timestamp is invalid")
+
+    with TemporaryDirectory(prefix=".console-artifact-", dir=output_dir.parent) as temporary:
+        temporary_root = Path(temporary)
+        temporary_root.chmod(0o700)
+        snapshot_archive = temporary_root / "source.tar"
+        snapshot = temporary_root / "source"
+        snapshot.mkdir(mode=0o700)
+        _run(
+            (
+                "git",
+                "-C",
+                str(source_root),
+                "archive",
+                "--format=tar",
+                f"--output={snapshot_archive}",
+                source_commit,
+            ),
+            timeout_seconds=120,
+        )
+        _run(("tar", "-xf", str(snapshot_archive), "-C", str(snapshot)), timeout_seconds=120)
+        _run(
+            (
+                "npm",
+                "--prefix",
+                str(snapshot / "console"),
+                "ci",
+                "--ignore-scripts",
+                "--no-audit",
+                "--no-fund",
+            ),
+            timeout_seconds=min(timeout_seconds, 600),
+        )
+        _run(
+            ("npm", "--prefix", str(snapshot / "console"), "run", "build:offline"),
+            timeout_seconds=timeout_seconds,
+        )
+        offline = snapshot / "console/dist/offline"
+        _run(
+            (
+                sys.executable,
+                str(snapshot / "scripts/deployment/azure/build_manual_studio_artifact.py"),
+                str(offline / "manuals"),
+                "--base-url",
+                MANUAL_STUDIO_PLACEHOLDER_URL,
+                "--repo-root",
+                str(snapshot),
+            ),
+            timeout_seconds=timeout_seconds,
+        )
+        if not (offline / "index.html").is_file() or not (offline / "fdai-config.js").is_file():
+            raise ValueError("Console artifact build output is incomplete")
+        if not all(
+            (offline / "manuals" / name).is_file()
+            for name in ("catalog.json", "library.html", "target-architecture.html")
+        ):
+            raise ValueError("Console Manual Studio artifact build output is incomplete")
+        staging = temporary_root / "artifact"
+        staging.mkdir(mode=0o700)
+        archive = staging / "console.tar.gz"
+        _run(
+            (
+                "tar",
+                "--sort=name",
+                f"--mtime=@{epoch}",
+                "--owner=0",
+                "--group=0",
+                "--numeric-owner",
+                "--transform=s,^offline,dist,",
+                "-czf",
+                str(archive),
+                "-C",
+                str(snapshot / "console/dist"),
+                "offline",
+            ),
+            timeout_seconds=120,
+        )
+        archive.chmod(0o600)
+        archive_digest = _regular_digest(archive)
+        manifest = {
+            "schema_version": "fdai.console-update-artifact.v1",
+            "source_commit": source_commit,
+            "archive_sha256": archive_digest,
+        }
+        write_private_output(
+            staging / "manifest.json",
+            json.dumps(manifest, sort_keys=True, separators=(",", ":")) + "\n",
+        )
+        os.rename(staging, output_dir)
+
+    return {
+        "schema_version": "fdai.console-update-artifact-build.v1",
+        "source_commit": source_commit,
+        "archive_sha256": archive_digest,
+        "artifact_directory": str(output_dir),
+        "azure_mutation_performed": False,
+    }
+
+
+def _resolve_revision(
+    source_root: Path,
+    revision: str,
+    *,
+    timeout_seconds: int,
+    require_protected_revision: bool,
+) -> str:
+    source_commit = _git(
+        source_root,
+        "rev-parse",
+        "--verify",
+        f"{revision}^{{commit}}",
+        timeout_seconds=timeout_seconds,
+    ).stdout.strip()
+    if _COMMIT.fullmatch(source_commit) is None:
+        raise ValueError("Console artifact revision is invalid")
+    if not require_protected_revision:
+        return source_commit
+    protected_head = _git(
+        source_root,
+        "rev-parse",
+        "--verify",
+        "refs/remotes/origin/main^{commit}",
+        timeout_seconds=timeout_seconds,
+    ).stdout.strip()
+    if _COMMIT.fullmatch(protected_head) is None:
+        raise ValueError("protected origin/main revision is unavailable")
+    _git(
+        source_root,
+        "merge-base",
+        "--is-ancestor",
+        source_commit,
+        protected_head,
+        timeout_seconds=timeout_seconds,
+    )
+    return source_commit
+
+
+def _git(
+    source_root: Path, *arguments: str, timeout_seconds: int
+) -> subprocess.CompletedProcess[str]:
+    completed = subprocess.run(
+        ("git", "-C", str(source_root), *arguments),
+        check=False,
+        capture_output=True,
+        text=True,
+        timeout=timeout_seconds,
+    )
+    if completed.returncode != 0:
+        raise ValueError("Console artifact source could not be verified")
+    return completed
+
+
+def _run(command: tuple[str, ...], *, timeout_seconds: int) -> None:
+    completed = subprocess.run(
+        command,
+        check=False,
+        capture_output=True,
+        text=True,
+        timeout=timeout_seconds,
+    )
+    if completed.returncode != 0:
+        raise ValueError("Console artifact build command failed")

fdai_deployment_cli/console_config.py

@@ -0,0 +1,214 @@
+"""Bind a generic Console build to public Entra and API deployment settings."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import stat
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from fdai_deployment_cli.contracts import load_json_object
+from fdai_deployment_cli.offline_kit import _read_regular
+from fdai_deployment_cli.private_output import _open_private_parent
+
+CONFIG_FILENAME = "fdai-config.js"
+CONFIG_PLACEHOLDER = b"globalThis.__FDAI_CONSOLE_CONFIG__ = null;\n"
+MANUAL_STUDIO_PLACEHOLDER_URL = "https://manual-studio.invalid/manuals"
+_UUID = r"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}"
+_FIELDS = {
+    "schema_version",
+    "operator_api_base_url",
+    "ingestion_api_base_url",
+    "tenant_id",
+    "spa_client_id",
+    "api_scope",
+}
+
+
+def render_console_config(settings: bytes) -> bytes:
+    """Validate public settings and render an external, authentication-only script.
+
+    This contains no secret or authorization decision. The browser still obtains
+    an Entra token and the APIs independently validate it. Unknown keys, including
+    authentication bypass flags, are rejected.
+    """
+    values = load_json_object(settings, label="Console settings", max_bytes=16_384)
+    if set(values) != _FIELDS or values["schema_version"] != "fdai.console-runtime.v1":
+        raise ValueError("Console settings fields do not match fdai.console-runtime.v1")
+    text_values: dict[str, str] = {}
+    for key, value in values.items():
+        if not isinstance(value, str) or not value.isascii():
+            raise ValueError("Console settings MUST contain only ASCII string values")
+        text_values[key] = value
+    for field in ("tenant_id", "spa_client_id"):
+        value = text_values[field]
+        if re.fullmatch(_UUID, value) is None:
+            raise ValueError(f"Console {field} MUST be a UUID")
+    for field in ("operator_api_base_url", "ingestion_api_base_url"):
+        value = text_values[field]
+        parsed = urlsplit(value)
+        if (
+            not value.lower().startswith("https://")
+            or any(
+                character.isspace() or ord(character) < 32 or ord(character) == 127
+                for character in value
+            )
+            or any(character in value for character in "\\?#")
+            or not parsed.hostname
+            or parsed.username is not None
+            or parsed.password is not None
+            or parsed.query
+            or parsed.fragment
+        ):
+            raise ValueError(
+                f"Console {field} MUST be HTTPS without credentials, query, or fragment"
+            )
+        try:
+            _ = parsed.port
+        except ValueError as exc:
+            raise ValueError(f"Console {field} has an invalid port") from exc
+    scope = text_values["api_scope"]
+    if re.fullmatch(rf"api://{_UUID}/[A-Za-z0-9._-]+", scope) is None:
+        raise ValueError("Console api_scope MUST identify an Entra API application scope")
+    document = json.dumps(text_values, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+    return f"globalThis.__FDAI_CONSOLE_CONFIG__ = {document};\n".encode("ascii")
+
+
+def configure_console(
+    directory: Path,
+    settings: Path,
+    *,
+    manual_studio_url: str | None = None,
+) -> dict[str, object]:
+    """Replace only the shipped placeholder in a private prebuilt Console directory.
+
+    Repeating identical settings is a no-op. A different existing configuration
+    requires a fresh copy of the original build, preventing an implicit tenant
+    switch. No package manager, build process, Azure call, or publication runs.
+    """
+    settings_parent = _open_private_parent(settings)
+    os.close(settings_parent)
+    details = settings.lstat()
+    if stat.S_IMODE(details.st_mode) != 0o600 or details.st_uid != os.geteuid():
+        raise PermissionError("Console settings MUST be a current-UID mode-0600 file")
+    rendered = render_console_config(_read_regular(settings, 16_384))
+    target = directory / CONFIG_FILENAME
+    parent = _open_private_parent(target)
+    temporary = ".fdai-config.js.pending"
+    created = False
+    try:
+        current = _read_regular(target, 16_384)
+        if current == rendered:
+            changed = False
+        elif current != CONFIG_PLACEHOLDER:
+            raise ValueError(
+                "Console config is not the shipped placeholder; use a fresh build copy"
+            )
+        else:
+            descriptor = os.open(
+                temporary,
+                os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW,
+                0o600,
+                dir_fd=parent,
+            )
+            created = True
+            with os.fdopen(descriptor, "wb") as stream:
+                stream.write(rendered)
+                stream.flush()
+                os.fsync(stream.fileno())
+            os.replace(temporary, CONFIG_FILENAME, src_dir_fd=parent, dst_dir_fd=parent)
+            created = False
+            os.fsync(parent)
+            changed = True
+    finally:
+        if created:
+            os.unlink(temporary, dir_fd=parent)
+        os.close(parent)
+    manual_pages_configured = _configure_manual_studio(directory, manual_studio_url)
+    return {
+        "schema_version": "fdai.console-configured.v1",
+        "runtime_config_digest": hashlib.sha256(rendered).hexdigest(),
+        "authentication": "entra",
+        "changed": changed,
+        "manual_studio_pages_configured": manual_pages_configured,
+        "cloud_mutation_performed": False,
+        "console_access_verified": False,
+    }
+
+
+def _configure_manual_studio(directory: Path, manual_studio_url: str | None) -> int:
+    """Replace only the reserved Manual Studio origin in prebuilt share pages."""
+
+    manual_root = directory / "manuals"
+    if not manual_root.exists():
+        return 0
+    if manual_studio_url is None:
+        raise ValueError("Console Manual Studio URL is required for bundled share pages")
+    parsed = urlsplit(manual_studio_url)
+    if (
+        not manual_studio_url.startswith("https://")
+        or not parsed.hostname
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.query
+        or parsed.fragment
+        or "\\" in manual_studio_url
+        or any(
+            character.isspace() or ord(character) < 32 or ord(character) > 126
+            for character in manual_studio_url
+        )
+    ):
+        raise ValueError("Console Manual Studio URL MUST be a safe HTTPS base URL")
+    manual_studio_url = manual_studio_url.rstrip("/")
+    if manual_studio_url == MANUAL_STUDIO_PLACEHOLDER_URL:
+        raise ValueError("Console Manual Studio URL MUST replace the build placeholder")
+    details = manual_root.lstat()
+    if (
+        not stat.S_ISDIR(details.st_mode)
+        or manual_root.is_symlink()
+        or details.st_uid != os.geteuid()
+    ):
+        raise ValueError("Console Manual Studio directory is invalid")
+    manual_root.chmod(0o700)
+    html_files = sorted(manual_root.glob("*.html"))
+    if not html_files:
+        raise ValueError("Console Manual Studio has no share pages")
+    placeholder = MANUAL_STUDIO_PLACEHOLDER_URL.encode("ascii")
+    replacement = manual_studio_url.encode("ascii")
+    parent = _open_private_parent(manual_root / "catalog.json")
+    pending: list[str] = []
+    try:
+        for path in html_files:
+            current = _read_regular(path, 4 * 1024 * 1024)
+            if placeholder in current:
+                configured = current.replace(placeholder, replacement)
+            elif replacement in current:
+                continue
+            else:
+                raise ValueError("Console Manual Studio share page is not configurable")
+            temporary = f".{path.name}.pending"
+            descriptor = os.open(
+                temporary,
+                os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW,
+                0o600,
+                dir_fd=parent,
+            )
+            pending.append(temporary)
+            with os.fdopen(descriptor, "wb") as stream:
+                stream.write(configured)
+                stream.flush()
+                os.fsync(stream.fileno())
+        for path in html_files:
+            temporary = f".{path.name}.pending"
+            if temporary in pending:
+                os.replace(temporary, path.name, src_dir_fd=parent, dst_dir_fd=parent)
+                pending.remove(temporary)
+        os.fsync(parent)
+    finally:
+        for temporary in pending:
+            os.unlink(temporary, dir_fd=parent)
+        os.close(parent)
+    return len(html_files)