@mriekki/project-forge 4.26.0 → 4.27.1

package/assets/generated/deployment/src/project_forge_deployment/auth_recovery_capture.py

@@ -0,0 +1,164 @@
+"""Exact provenance + stopped-Docker adapter for isolated Auth Kit capture.
+
+Internal library only. Never stops/restarts a service, configures a provider,
+logs Docker environment or offers an operator-ready Production backup CLI.
+The caller independently manages quiescence and must validate service
+resumption/health, scheduling, alert receipt and application restore.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import stat
+import sys
+import types
+
+from .auth_recovery_guard import docker_auth_quiescence_guard
+from .errors import DeploymentKitError
+
+SHA256 = re.compile(r"^[0-9a-f]{64}$")
+REVISION = re.compile(r"^[0-9a-f]{40}$")
+HELPER_PATH = "tools/project-forge-auth-kit/project_auth_recovery.py"
+BASELINE_NAME = "AUTHENTICATION_BASELINE.json"
+
+
+def _safe_regular(path: Path) -> os.stat_result:
+    for part in (path, *path.parents):
+        if part.is_symlink():
+            raise DeploymentKitError("Managed recovery source contains a symlink.")
+    try:
+        st = path.lstat()
+    except OSError as exc:
+        raise DeploymentKitError("Managed recovery source is missing.") from exc
+    if not stat.S_ISREG(st.st_mode) or st.st_nlink != 1:
+        raise DeploymentKitError("Managed recovery source is not a regular owned file.")
+    return st
+
+
+def _load_pinned_helper(
+    project_root: Path, reviewed_revision: str, reviewed_sha256: str
+):
+    """Load exactly reviewed source bytes, not an attacker-modified pathname."""
+    if (type(reviewed_revision) is not str or
+            REVISION.fullmatch(reviewed_revision) is None or
+            type(reviewed_sha256) is not str or
+            SHA256.fullmatch(reviewed_sha256) is None):
+        raise DeploymentKitError("Exact reviewed Auth component provenance required.")
+    root = Path(os.path.abspath(project_root))
+    for part in (root, *root.parents):
+        if part.is_symlink():
+            raise DeploymentKitError("Project root may not contain a symlink.")
+    if not root.is_dir():
+        raise DeploymentKitError("Generated Project root does not exist.")
+    baseline_path = root / BASELINE_NAME
+    helper_path = root / HELPER_PATH
+    _safe_regular(baseline_path)
+    _safe_regular(helper_path)
+    try:
+        if baseline_path.stat().st_size > 512 * 1024:
+            raise DeploymentKitError("Auth baseline is too large.")
+        baseline = json.loads(baseline_path.read_text(encoding="utf-8"))
+    except (ValueError, UnicodeError, OSError) as exc:
+        raise DeploymentKitError("Auth baseline is unreadable.") from exc
+    if (type(baseline) is not dict or
+            baseline.get("schemaVersion") != 2 or
+            baseline.get("component") != "authentication" or
+            baseline.get("distribution") != "greenfield-project" or
+            baseline.get("revision") != reviewed_revision):
+        raise DeploymentKitError("Installed Authentication baseline identity differs from reviewed revision.")
+    entries = baseline.get("managedPaths")
+    if type(entries) is not list or not entries or len(entries) > 1000:
+        raise DeploymentKitError("Installed Authentication managed-file ledger is invalid.")
+    matching = []
+    seen = set()
+    for entry in entries:
+        if (type(entry) is not dict or
+                set(entry) != {"source", "path", "sha256"} or
+                type(entry["path"]) is not str or
+                type(entry["sha256"]) is not str or
+                SHA256.fullmatch(entry["sha256"]) is None or
+                entry["path"] in seen):
+            raise DeploymentKitError("Installed Authentication managed-file ledger is malformed.")
+        seen.add(entry["path"])
+        if entry["path"] == HELPER_PATH:
+            matching.append(entry)
+    if len(matching) != 1 or matching[0]["sha256"] != reviewed_sha256:
+        raise DeploymentKitError("Auth recovery helper is missing from reviewed managed baseline.")
+
+    # Hash and compile the same bytes; no check-then-import path race.
+    try:
+        with helper_path.open("rb") as source:
+            data = source.read(256 * 1024 + 1)
+        if (not data or len(data) > 256 * 1024 or
+                hashlib.sha256(data).hexdigest() != reviewed_sha256):
+            raise DeploymentKitError("Auth recovery helper bytes differ from reviewed release.")
+        module = types.ModuleType("_project_forge_verified_auth_recovery")
+        module.__file__ = str(helper_path)
+        exec(compile(data, str(helper_path), "exec"), module.__dict__)
+    except DeploymentKitError:
+        raise
+    except (OSError, SyntaxError, UnicodeError, ValueError, RuntimeError) as exc:
+        raise DeploymentKitError("Reviewed Auth recovery helper cannot be loaded.") from exc
+    if not callable(getattr(module, "capture_quiesced_set", None)):
+        raise DeploymentKitError("Reviewed Auth recovery helper is missing its capture contract.")
+    return module
+
+
+def capture_reviewed_stopped_auth_project(
+    *, project_root: Path, source_data_root: Path, destination: Path,
+    declaration: dict, reviewed_auth_revision: str,
+    reviewed_recovery_sha256: str, reviewed_docker_binding: dict
+) -> dict:
+    """Write only a new private capture when exact reviewed Docker is stopped.
+
+    The source/storage, expected image, labels, container name and binding must
+    come from separately reviewed Project deployment evidence. The helper's
+    accepted SHA and component revision must come from an independent immutable
+    release/provenance receipt, not merely the editable local baseline.
+    """
+    if sys.platform != "linux":
+        raise DeploymentKitError("Stopped Auth Project capture is Linux-host only.")
+    source = Path(os.path.abspath(source_data_root))
+    if type(reviewed_docker_binding) is not dict or set(reviewed_docker_binding) != {
+        "container_name", "expected_owner", "expected_environment",
+        "expected_image_digest", "expected_data_source",
+        "expected_data_destination", "owner_label", "environment_label",
+        "required_auth_environment",
+    }:
+        raise DeploymentKitError("Exact reviewed Docker binding is required.")
+    bind_source = reviewed_docker_binding["expected_data_source"]
+    if not isinstance(bind_source, Path) or Path(os.path.abspath(bind_source)) != source:
+        raise DeploymentKitError("Reviewed Docker data source differs from Auth data root.")
+    required = reviewed_docker_binding["required_auth_environment"]
+    mount = reviewed_docker_binding["expected_data_destination"]
+    if (type(required) is not dict or type(mount) is not str or
+            required.get("ProjectForge__Authentication__DbPath") !=
+            mount.rstrip("/") + "/auth.sqlite" or
+            required.get("ProjectForge__Authentication__DataProtectionKeysPath") !=
+            mount.rstrip("/") + "/keys"):
+        raise DeploymentKitError("Exact Auth database and key-ring container bindings required.")
+    helper = _load_pinned_helper(
+        project_root, reviewed_auth_revision, reviewed_recovery_sha256)
+    try:
+        guard = docker_auth_quiescence_guard(**reviewed_docker_binding)
+        proof = guard()
+        if (type(proof) is not dict or proof.get("stopped") is not True):
+            raise DeploymentKitError("Exact stopped Auth service not proven.")
+        report = helper.capture_quiesced_set(
+            source, Path(destination), declaration, guard)
+    except DeploymentKitError:
+        raise
+    except Exception as exc:
+        # Do not print Docker inspect, private host paths, credential env or
+        # key files on failure; never return apparent success.
+        raise DeploymentKitError("Reviewed Auth backup capture failed closed.") from exc
+    if (type(report) is not dict or
+            report.get("backupArtifactIntegrityVerified") is not True or
+            report.get("applicationRecoveryReady") is not False or
+            report.get("quiescenceGuardRuntimeId") != proof.get("runtimeId") or
+            report.get("quiescenceGuardImageDigest") != proof.get("imageDigest")):
+        raise DeploymentKitError("Auth recovery helper did not prove expected capture receipt.")
+    return report

package/assets/generated/deployment/src/project_forge_deployment/auth_recovery_guard.py

@@ -0,0 +1,225 @@
+"""Read-only, exact Docker quiescence evidence for future Auth Kit recovery.
+
+No container stop/restart, backup, key read, provider operation or Production
+mutation is performed. Do not expose this primitive as a supported backup
+workflow until Deployment Kit owns a reviewed quiescence orchestration driver.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import stat
+import subprocess
+import sys
+from typing import Any, Callable
+
+from .errors import DeploymentKitError
+
+_HEX64 = re.compile(r"^[0-9a-f]{64}$")
+_CONTAINER = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$")
+
+
+def _exact_dict(value: object, required: set[str], context: str) -> dict:
+    if not isinstance(value, dict) or not required.issubset(value):
+        raise DeploymentKitError(f"Invalid {context} runtime evidence.")
+    return value
+
+
+def _host_directory_is_real(path: Path) -> None:
+    # Local host only. A symlink anywhere in the owned mount path is
+    # forbidden even when its final resolution would be inside the root.
+    if not path.is_absolute():
+        raise DeploymentKitError("Auth recovery data mount must be absolute.")
+    for part in (path, *path.parents):
+        if part.is_symlink():
+            raise DeploymentKitError("Auth recovery mount may not use symlinks.")
+    try:
+        st = path.lstat()
+    except OSError as error:
+        raise DeploymentKitError("Auth recovery data directory is unavailable.") from error
+    if not stat.S_ISDIR(st.st_mode):
+        raise DeploymentKitError("Auth recovery data mount must be a directory.")
+
+
+def verify_stopped_auth_container(
+    observed: dict[str, Any],
+    *,
+    container_name: str,
+    expected_owner: str,
+    expected_environment: str,
+    expected_image_digest: str,
+    expected_data_source: Path,
+    expected_data_destination: str,
+    owner_label: str,
+    environment_label: str,
+    required_auth_environment: dict[str, str],
+) -> dict[str, object]:
+    """Return only non-secret proof for an exactly owned, stopped container.
+
+    The caller must provide expected identity, image, labels, mount and auth
+    settings from a reviewed Project deployment receipt. This does not stop
+    the application or establish a viable restored application.
+    """
+    if not _CONTAINER.fullmatch(container_name):
+        raise DeploymentKitError("Invalid inspected container name.")
+    if not _HEX64.fullmatch(expected_image_digest.removeprefix("sha256:")) or (
+        not expected_image_digest.startswith("sha256:")
+    ):
+        raise DeploymentKitError("An exact immutable Docker image digest is required.")
+    if (not isinstance(expected_owner, str) or not expected_owner or
+            not isinstance(expected_environment, str) or not expected_environment or
+            not isinstance(owner_label, str) or not owner_label or
+            not isinstance(environment_label, str) or not environment_label or
+            type(required_auth_environment) is not dict or
+            not required_auth_environment or
+            any(not isinstance(k, str) or not k or not isinstance(v, str)
+                for k, v in required_auth_environment.items())):
+        raise DeploymentKitError("Exact Auth recovery ownership declaration required.")
+    mount_root = Path(expected_data_source)
+    _host_directory_is_real(mount_root)
+    if (not isinstance(expected_data_destination, str) or
+            not expected_data_destination.startswith("/") or
+            ".." in expected_data_destination.split("/")):
+        raise DeploymentKitError("Invalid reviewed container data destination.")
+
+    info = _exact_dict(observed, {
+        "Id", "Name", "Image", "State", "Config", "HostConfig", "Mounts"
+    }, "container")
+    runtime_id = info["Id"]
+    if (not isinstance(runtime_id, str) or not _HEX64.fullmatch(runtime_id) or
+            info["Name"] != "/" + container_name or
+            info["Image"] != expected_image_digest):
+        raise DeploymentKitError("Auth container identity or image drift detected.")
+    state = _exact_dict(info["State"], {"Running", "Restarting", "Status"}, "state")
+    policy = _exact_dict(info["HostConfig"], {"RestartPolicy"}, "host configuration")
+    restart = _exact_dict(policy["RestartPolicy"], {"Name"}, "restart policy")
+    if (state["Running"] is not False or state["Restarting"] is not False or
+            state["Status"] != "exited" or restart["Name"] != "no"):
+        raise DeploymentKitError(
+            "Auth recovery requires a stopped, restart-disabled exact container."
+        )
+
+    config = _exact_dict(info["Config"], {"Labels", "Env"}, "configuration")
+    labels = _exact_dict(config["Labels"], {owner_label, environment_label}, "labels")
+    if (labels[owner_label] != expected_owner or
+            labels[environment_label] != expected_environment):
+        raise DeploymentKitError("Auth runtime ownership labels do not match.")
+    raw_env = config["Env"]
+    if not isinstance(raw_env, list):
+        raise DeploymentKitError("Malformed Auth runtime environment.")
+    env: dict[str, str] = {}
+    for item in raw_env:
+        if not isinstance(item, str) or "=" not in item:
+            raise DeploymentKitError("Malformed Auth runtime environment.")
+        name, value = item.split("=", 1)
+        if name in env or not name:
+            raise DeploymentKitError("Duplicate Auth runtime environment key.")
+        env[name] = value
+    for key, value in required_auth_environment.items():
+        if env.get(key) != value:
+            raise DeploymentKitError("Auth runtime binding differs from approved receipt.")
+
+    mounts = info["Mounts"]
+    if not isinstance(mounts, list):
+        raise DeploymentKitError("Malformed Auth container mount inventory.")
+    data = [m for m in mounts if isinstance(m, dict)
+            and m.get("Destination") == expected_data_destination]
+    if (len(data) != 1 or data[0].get("Type") != "bind" or
+            data[0].get("RW") is not True or
+            data[0].get("Source") != str(mount_root)):
+        raise DeploymentKitError("Auth owned data bind is not the reviewed mount.")
+    if any(not isinstance(m, dict) for m in mounts):
+        raise DeploymentKitError("Malformed Auth container mount inventory.")
+
+    return {
+        "stopped": True,
+        "runtimeId": runtime_id,
+        "imageDigest": expected_image_digest,
+    }
+
+
+
+def verify_running_auth_container(
+    observed: dict[str, Any], **binding: Any
+) -> dict[str, object]:
+    """Verify the *same* strict Auth owner/image/mount, but in running state.
+
+    Reuse the stopped proof's complete configuration inspection after
+    independently checking the actual running state. The normalized copy
+    below is verification-only and never sent to Docker.
+    """
+    if type(observed) is not dict:
+        raise DeploymentKitError("Malformed running Auth Docker inspection.")
+    state = observed.get("State")
+    if (type(state) is not dict or state.get("Running") is not True
+            or state.get("Restarting") is not False
+            or state.get("Status") != "running"):
+        raise DeploymentKitError("Exact Auth container is not running.")
+    projection = {
+        **observed,
+        "State": {**state, "Running": False, "Status": "exited"},
+    }
+    proof = verify_stopped_auth_container(projection, **binding)
+    return {
+        "running": True,
+        "runtimeId": proof["runtimeId"],
+        "imageDigest": proof["imageDigest"],
+    }
+
+
+def docker_auth_quiescence_guard(
+    *,
+    container_name: str,
+    expected_owner: str,
+    expected_environment: str,
+    expected_image_digest: str,
+    expected_data_source: Path,
+    expected_data_destination: str,
+    owner_label: str,
+    environment_label: str,
+    required_auth_environment: dict[str, str],
+) -> Callable[[], dict[str, object]]:
+    """Build a read-only local Linux Docker inspect guard, to call twice.
+
+    Raw Docker inspect includes sensitive environment material. Never log the
+    response, return it, or include stderr in user-facing failure messages.
+    """
+    if sys.platform != "linux":
+        raise DeploymentKitError(
+            "Auth recovery Docker quiescence requires a reviewed Linux host driver."
+        )
+    if not _CONTAINER.fullmatch(container_name):
+        raise DeploymentKitError("Invalid container identity.")
+    docker = shutil.which("docker")
+    if docker is None:
+        raise DeploymentKitError("Docker runtime is unavailable.")
+
+    def inspect() -> dict[str, object]:
+        try:
+            cmd = subprocess.run(
+                [docker, "inspect", "--format", "{{json .}}", container_name],
+                capture_output=True, text=True, check=False,
+                timeout=15, encoding="utf-8", errors="replace",
+            )
+            if cmd.returncode != 0 or len(cmd.stdout) > 256 * 1024:
+                raise DeploymentKitError("Auth runtime inspect failed closed.")
+            observed = json.loads(cmd.stdout)
+        except (OSError, subprocess.TimeoutExpired, ValueError) as error:
+            raise DeploymentKitError(
+                "Auth runtime evidence is unavailable or invalid."
+            ) from error
+        return verify_stopped_auth_container(
+            observed, container_name=container_name,
+            expected_owner=expected_owner,
+            expected_environment=expected_environment,
+            expected_image_digest=expected_image_digest,
+            expected_data_source=expected_data_source,
+            expected_data_destination=expected_data_destination,
+            owner_label=owner_label,
+            environment_label=environment_label,
+            required_auth_environment=required_auth_environment,
+        )
+    return inspect