@mriekki/project-forge 0.0.0-stage → 2.0.0

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

@@ -0,0 +1,348 @@
+"""Personal GitHub project-forge-profile repository and validated local cache."""
+
+from __future__ import annotations
+
+import base64
+import json
+import shutil
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .errors import DeploymentKitError
+from .portable_profile import (
+    BUNDLE_KIND,
+    BUNDLE_SCHEMA_VERSION,
+    apply_import,
+    export_bundle,
+    plan_import,
+    validate_bundle,
+)
+from .profiles import config_root
+
+
+PROFILE_REPOSITORY = "project-forge-profile"
+PROFILE_FILE = "project-forge-profile.json"
+PERSONAL_PROFILE_WRITE_PHRASE = "[PERSONAL PROFILE WRITE]"
+LOCAL_PROFILE_SYNC_PHRASE = "[LOCAL PROFILE SYNC]"
+
+
+def _gh() -> str:
+    path = shutil.which("gh")
+    if path is None:
+        raise DeploymentKitError("GitHub CLI is unavailable; personal profile sync cannot reach GitHub.")
+    return path
+
+
+def _run_gh(args: list[str]) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [_gh(), *args],
+        check=False,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+
+
+def _detail(result: subprocess.CompletedProcess[str]) -> str:
+    return result.stderr.strip() or result.stdout.strip() or f"exit {result.returncode}"
+
+
+def _not_found(result: subprocess.CompletedProcess[str]) -> bool:
+    text = (result.stderr + "\n" + result.stdout).lower()
+    return result.returncode != 0 and (
+        "http 404" in text
+        or "not found" in text
+        or "could not resolve to a repository" in text
+        or "could not resolve to a resource" in text
+    )
+
+
+def authenticated_login() -> str:
+    result = _run_gh(["api", "user"])
+    if result.returncode != 0:
+        raise DeploymentKitError(f"Cannot resolve authenticated GitHub identity: {_detail(result)}")
+    try:
+        value = json.loads(result.stdout)
+    except json.JSONDecodeError as error:
+        raise DeploymentKitError("GitHub CLI returned malformed authenticated-user data.") from error
+    login = value.get("login") if isinstance(value, dict) else None
+    if not isinstance(login, str) or not login:
+        raise DeploymentKitError("GitHub CLI authenticated-user data omitted login.")
+    return login
+
+
+def repository_status() -> dict[str, Any]:
+    login = authenticated_login()
+    full_name = f"{login}/{PROFILE_REPOSITORY}"
+    result = _run_gh(["api", f"repos/{full_name}"])
+    if _not_found(result):
+        return {
+            "login": login,
+            "repository": full_name,
+            "state": "missing",
+            "private": None,
+            "mutated": False,
+        }
+    if result.returncode != 0:
+        raise DeploymentKitError(f"Cannot inspect personal Project Forge profile repository: {_detail(result)}")
+    try:
+        value = json.loads(result.stdout)
+    except json.JSONDecodeError as error:
+        raise DeploymentKitError("GitHub CLI returned malformed repository data.") from error
+    if not isinstance(value, dict):
+        raise DeploymentKitError("GitHub CLI returned malformed repository data.")
+    owner = (value.get("owner") or {}).get("login") if isinstance(value.get("owner"), dict) else None
+    name = value.get("name")
+    private = value.get("private")
+    if owner != login or name != PROFILE_REPOSITORY or type(private) is not bool:
+        raise DeploymentKitError("Personal Project Forge profile repository identity could not be verified.")
+    if not private:
+        raise DeploymentKitError(
+            f"Personal Project Forge profile repository {full_name} is public; it must be private before Project Forge will use it."
+        )
+    return {
+        "login": login,
+        "repository": full_name,
+        "state": "ready",
+        "private": True,
+        "mutated": False,
+    }
+
+
+def _profile_dirs() -> tuple[Path, Path, Path]:
+    root = config_root() / "profile"
+    return root / "current", root / "last-known-good", root / "sync-state.json"
+
+
+def _write_json_atomic(path: Path, value: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.is_symlink() or path.parent.is_symlink():
+        raise DeploymentKitError(f"Refusing to write profile cache through a symbolic link: {path}")
+    temp = path.with_name(path.name + ".tmp")
+    temp.write_text(json.dumps(value, indent=2) + "\n", encoding="utf-8")
+    temp.replace(path)
+
+
+def cache_valid_profile(bundle: dict[str, Any], *, source: str, remote_sha: str | None) -> dict[str, Any]:
+    normalized = validate_bundle(bundle)
+    current, lkg, state_path = _profile_dirs()
+    current_file = current / PROFILE_FILE
+    lkg_file = lkg / PROFILE_FILE
+    _write_json_atomic(current_file, normalized)
+    _write_json_atomic(lkg_file, normalized)
+    state = {
+        "schemaVersion": 1,
+        "lastValidatedAt": datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z"),
+        "source": source,
+        "remoteSha": remote_sha,
+        "current": str(current_file),
+        "lastKnownGood": str(lkg_file),
+    }
+    _write_json_atomic(state_path, state)
+    return state
+
+
+def load_last_known_good() -> dict[str, Any]:
+    _, lkg, _ = _profile_dirs()
+    path = lkg / PROFILE_FILE
+    if path.is_symlink() or not path.is_file():
+        raise DeploymentKitError("No validated last-known-good personal Project Forge profile is cached on this workstation.")
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as error:
+        raise DeploymentKitError(f"Cannot read last-known-good personal Project Forge profile: {error}") from error
+    return validate_bundle(value)
+
+
+def _empty_bundle() -> dict[str, Any]:
+    return {"schemaVersion": BUNDLE_SCHEMA_VERSION, "kind": BUNDLE_KIND, "targets": []}
+
+
+def fetch_remote_profile() -> dict[str, Any]:
+    status = repository_status()
+    if status["state"] != "ready":
+        raise DeploymentKitError(f"Personal Project Forge profile repository does not exist: {status['repository']}")
+    full_name = status["repository"]
+    result = _run_gh(["api", f"repos/{full_name}/contents/{PROFILE_FILE}"])
+    if _not_found(result):
+        return {"bundle": _empty_bundle(), "sha": None, "repository": full_name}
+    if result.returncode != 0:
+        raise DeploymentKitError(f"Cannot fetch personal Project Forge profile: {_detail(result)}")
+    try:
+        value = json.loads(result.stdout)
+        encoded = value["content"]
+        sha = value["sha"]
+        if value.get("encoding") != "base64" or not isinstance(encoded, str) or not isinstance(sha, str):
+            raise ValueError("unexpected content payload")
+        decoded = base64.b64decode(encoded.encode("ascii"), validate=False).decode("utf-8")
+        bundle = validate_bundle(json.loads(decoded))
+    except (KeyError, TypeError, ValueError, UnicodeError, json.JSONDecodeError) as error:
+        raise DeploymentKitError(
+            "Remote personal Project Forge profile is invalid; the validated local last-known-good profile was not replaced."
+        ) from error
+    return {"bundle": bundle, "sha": sha, "repository": full_name}
+
+
+def sync_profile(*, apply: bool) -> dict[str, Any]:
+    try:
+        remote = fetch_remote_profile()
+        state = cache_valid_profile(remote["bundle"], source="github", remote_sha=remote["sha"])
+        bundle = remote["bundle"]
+        source = "github"
+        remote_error = None
+    except DeploymentKitError as error:
+        bundle = load_last_known_good()
+        state = {"source": "last-known-good"}
+        source = "last-known-good"
+        remote_error = str(error)
+
+    plan = plan_import(bundle)
+    result: dict[str, Any] = {
+        "source": source,
+        "targetCount": len(bundle["targets"]),
+        "importPlan": plan,
+        "cache": state,
+        "remoteError": remote_error,
+        "mutated": False,
+    }
+    if apply and not plan["hasConflicts"]:
+        applied = apply_import(plan)
+        result["importResult"] = applied
+        result["mutated"] = bool(applied["mutated"])
+    elif apply and plan["hasConflicts"]:
+        result["blocked"] = "Local target-definition conflicts require explicit resolution; no target was overwritten."
+    return result
+
+
+def _create_repository(login: str) -> None:
+    full_name = f"{login}/{PROFILE_REPOSITORY}"
+    result = _run_gh(
+        [
+            "repo",
+            "create",
+            full_name,
+            "--private",
+            "--description",
+            "Portable non-secret Project Forge developer environment definitions",
+        ]
+    )
+    if result.returncode != 0:
+        raise DeploymentKitError(f"Cannot create personal Project Forge profile repository: {_detail(result)}")
+    status = repository_status()
+    if status["state"] != "ready" or not status["private"]:
+        raise DeploymentKitError("Personal Project Forge profile repository creation returned without a verified private repository.")
+
+
+def _put_remote_profile(repository: str, bundle: dict[str, Any], *, current_sha: str | None) -> str:
+    normalized = validate_bundle(bundle)
+    encoded = base64.b64encode((json.dumps(normalized, indent=2) + "\n").encode("utf-8")).decode("ascii")
+    args = [
+        "api",
+        "--method",
+        "PUT",
+        f"repos/{repository}/contents/{PROFILE_FILE}",
+        "-f",
+        "message=Update personal Project Forge profile",
+        "-f",
+        f"content={encoded}",
+    ]
+    if current_sha:
+        args.extend(["-f", f"sha={current_sha}"])
+    result = _run_gh(args)
+    if result.returncode != 0:
+        raise DeploymentKitError(f"Cannot publish personal Project Forge profile: {_detail(result)}")
+    try:
+        value = json.loads(result.stdout)
+        sha = value["content"]["sha"]
+    except (KeyError, TypeError, json.JSONDecodeError) as error:
+        raise DeploymentKitError("GitHub returned malformed profile publication evidence.") from error
+    if not isinstance(sha, str) or not sha:
+        raise DeploymentKitError("GitHub profile publication omitted content SHA.")
+    return sha
+
+
+def ensure_profile_repository() -> dict[str, Any]:
+    status = repository_status()
+    created = False
+    if status["state"] == "missing":
+        _create_repository(status["login"])
+        created = True
+        status = repository_status()
+    remote = fetch_remote_profile()
+    if remote["sha"] is None:
+        local = export_bundle(None)
+        sha = _put_remote_profile(status["repository"], local, current_sha=None)
+        cache = cache_valid_profile(local, source="github", remote_sha=sha)
+        return {
+            "repository": status["repository"],
+            "createdRepository": created,
+            "publishedInitialProfile": True,
+            "targetCount": len(local["targets"]),
+            "cache": cache,
+            "mutated": True,
+        }
+    cache = cache_valid_profile(remote["bundle"], source="github", remote_sha=remote["sha"])
+    return {
+        "repository": status["repository"],
+        "createdRepository": created,
+        "publishedInitialProfile": False,
+        "targetCount": len(remote["bundle"]["targets"]),
+        "cache": cache,
+        "mutated": created,
+    }
+
+
+def _merge_non_conflicting(remote: dict[str, Any], local: dict[str, Any]) -> dict[str, Any]:
+    remote = validate_bundle(remote)
+    local = validate_bundle(local)
+    by_name = {item["targetName"]: item for item in remote["targets"]}
+    conflicts: list[str] = []
+    for item in local["targets"]:
+        current = by_name.get(item["targetName"])
+        if current is not None and current != item:
+            conflicts.append(item["targetName"])
+            continue
+        by_name[item["targetName"]] = item
+    if conflicts:
+        raise DeploymentKitError(
+            "Personal profile publish found conflicting existing definitions: "
+            + ", ".join(sorted(conflicts))
+            + ". Resolve explicitly; remote definitions were not overwritten."
+        )
+    return validate_bundle(
+        {
+            "schemaVersion": BUNDLE_SCHEMA_VERSION,
+            "kind": BUNDLE_KIND,
+            "targets": [by_name[name] for name in sorted(by_name)],
+        }
+    )
+
+
+def publish_profile() -> dict[str, Any]:
+    status = repository_status()
+    if status["state"] != "ready":
+        raise DeploymentKitError("Create/ensure the private personal Project Forge profile repository before publishing.")
+    remote = fetch_remote_profile()
+    local = export_bundle(None)
+    merged = _merge_non_conflicting(remote["bundle"], local)
+    if merged == remote["bundle"]:
+        cache = cache_valid_profile(merged, source="github", remote_sha=remote["sha"])
+        return {
+            "repository": status["repository"],
+            "status": "already-current",
+            "targetCount": len(merged["targets"]),
+            "cache": cache,
+            "mutated": False,
+        }
+    sha = _put_remote_profile(status["repository"], merged, current_sha=remote["sha"])
+    cache = cache_valid_profile(merged, source="github", remote_sha=sha)
+    return {
+        "repository": status["repository"],
+        "status": "published",
+        "targetCount": len(merged["targets"]),
+        "cache": cache,
+        "mutated": True,
+    }

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

@@ -0,0 +1,204 @@
+"""User-scoped logical target profiles."""
+
+from __future__ import annotations
+
+import ipaddress
+import json
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+from .errors import DeploymentKitError
+
+
+PROFILE_SCHEMA_VERSION = 1
+TARGET_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,63}$")
+ALIAS_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$")
+USER_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_.-]{0,31}$")
+HOST_LABEL_RE = re.compile(r"^[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?$")
+SUPPORTED_TARGET_OS = {"ubuntu"}
+
+
+def _unique_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    value: dict[str, Any] = {}
+    for key, item in pairs:
+        if key in value:
+            raise DeploymentKitError(f"Duplicate JSON property: {key}")
+        value[key] = item
+    return value
+
+
+def config_root(home: Path | None = None) -> Path:
+    override = os.environ.get("PROJECT_FORGE_HOME")
+    if override:
+        candidate = Path(override).expanduser()
+        if not candidate.is_absolute():
+            raise DeploymentKitError("PROJECT_FORGE_HOME must be an absolute path.")
+        return candidate.resolve()
+    return ((home or Path.home()).resolve() / ".project-forge").resolve()
+
+
+def validate_target_name(name: str) -> str:
+    if not isinstance(name, str) or TARGET_NAME_RE.fullmatch(name) is None:
+        raise DeploymentKitError(
+            "Target name must use lowercase letters, digits, and hyphens, and must start with a letter or digit."
+        )
+    return name
+
+
+def target_profile_path(name: str, home: Path | None = None) -> Path:
+    validate_target_name(name)
+    return config_root(home) / "targets" / f"{name}.json"
+
+
+def _validate_host_name(value: Any) -> str:
+    if not isinstance(value, str) or not value or len(value) > 253:
+        raise DeploymentKitError("hostName must be a DNS/mDNS hostname.")
+    if value.endswith("."):
+        value = value[:-1]
+    try:
+        ipaddress.ip_address(value)
+    except ValueError:
+        pass
+    else:
+        raise DeploymentKitError(
+            "hostName must be a stable DNS/mDNS name, not an IP address; use addressOverride for a verified temporary IP."
+        )
+    labels = value.split(".")
+    if any(HOST_LABEL_RE.fullmatch(label) is None for label in labels):
+        raise DeploymentKitError("hostName must be a valid DNS/mDNS hostname.")
+    return value.lower()
+
+
+def _ssh_path(value: Any, field: str, home: Path) -> Path:
+    if not isinstance(value, str) or not value.strip():
+        raise DeploymentKitError(f"{field} must not be empty.")
+    if value == "~":
+        candidate = home
+    elif value.startswith("~/") or value.startswith("~\\"):
+        candidate = home / value[2:]
+    else:
+        candidate = Path(value)
+    if not candidate.is_absolute():
+        raise DeploymentKitError(f"{field} must be absolute or home-relative with '~'.")
+    resolved = candidate.resolve()
+    ssh_dir = (home / ".ssh").resolve()
+    if resolved == ssh_dir or not resolved.is_relative_to(ssh_dir):
+        raise DeploymentKitError(f"{field} must be a file inside the user's SSH directory: {ssh_dir}")
+    return resolved
+
+
+def validate_profile(
+    value: dict[str, Any],
+    *,
+    expected_target_name: str | None = None,
+    home: Path | None = None,
+) -> dict[str, Any]:
+    expected_fields = {
+        "schemaVersion",
+        "targetName",
+        "targetOs",
+        "hostName",
+        "sshAlias",
+        "user",
+        "port",
+        "identityFile",
+        "knownHostsFile",
+        "addressOverride",
+    }
+    if not isinstance(value, dict) or set(value) != expected_fields:
+        raise DeploymentKitError(
+            "Target profile must contain exactly: " + ", ".join(sorted(expected_fields)) + "."
+        )
+    if type(value["schemaVersion"]) is not int or value["schemaVersion"] != PROFILE_SCHEMA_VERSION:
+        raise DeploymentKitError("Unsupported target profile schemaVersion.")
+
+    target_name = validate_target_name(value["targetName"])
+    if expected_target_name is not None and target_name != expected_target_name:
+        raise DeploymentKitError(
+            f"Target profile mismatch: expected '{expected_target_name}', got '{target_name}'."
+        )
+
+    target_os = value["targetOs"]
+    if target_os not in SUPPORTED_TARGET_OS:
+        raise DeploymentKitError(
+            f"Unsupported targetOs '{target_os}'. Initial support is limited to: {', '.join(sorted(SUPPORTED_TARGET_OS))}."
+        )
+
+    host_name = _validate_host_name(value["hostName"])
+    alias = value["sshAlias"]
+    if not isinstance(alias, str) or ALIAS_RE.fullmatch(alias) is None:
+        raise DeploymentKitError("sshAlias contains unsupported characters.")
+
+    username = value["user"]
+    if not isinstance(username, str) or USER_RE.fullmatch(username) is None:
+        raise DeploymentKitError("user contains unsupported characters.")
+
+    port = value["port"]
+    if type(port) is not int or not 1 <= port <= 65535:
+        raise DeploymentKitError("port must be an integer from 1 through 65535.")
+
+    user_home = (home or Path.home()).resolve()
+    identity_file = _ssh_path(value["identityFile"], "identityFile", user_home)
+    known_hosts_file = _ssh_path(value["knownHostsFile"], "knownHostsFile", user_home)
+    if identity_file == known_hosts_file:
+        raise DeploymentKitError("identityFile and knownHostsFile must be different paths.")
+
+    address_override = value["addressOverride"]
+    if address_override is not None:
+        if not isinstance(address_override, str):
+            raise DeploymentKitError("addressOverride must be null or an IP address.")
+        try:
+            parsed = ipaddress.ip_address(address_override)
+        except ValueError as error:
+            raise DeploymentKitError("addressOverride must be a valid IPv4 or IPv6 address.") from error
+        if isinstance(parsed, ipaddress.IPv6Address) and parsed.scope_id is not None:
+            raise DeploymentKitError("addressOverride must not include an IPv6 scope identifier.")
+        address_override = str(parsed)
+
+    return {
+        "schemaVersion": PROFILE_SCHEMA_VERSION,
+        "targetName": target_name,
+        "targetOs": target_os,
+        "hostName": host_name,
+        "sshAlias": alias,
+        "user": username,
+        "port": port,
+        "identityFile": str(identity_file),
+        "knownHostsFile": str(known_hosts_file),
+        "addressOverride": address_override,
+    }
+
+
+def load_profile(name: str, *, home: Path | None = None) -> dict[str, Any]:
+    path = target_profile_path(name, home)
+    if path.is_symlink() or path.parent.is_symlink():
+        raise DeploymentKitError("Target profile and its containing directory must not be symbolic links.")
+    if not path.is_file():
+        raise DeploymentKitError(f"Target profile is missing: {path}")
+    try:
+        with path.open(encoding="utf-8") as source:
+            value = json.load(source, object_pairs_hook=_unique_object)
+    except (OSError, UnicodeError, json.JSONDecodeError) as error:
+        raise DeploymentKitError(f"Cannot read target profile {path}: {error}") from error
+    return validate_profile(value, expected_target_name=name, home=home)
+
+
+def save_profile(value: dict[str, Any], *, home: Path | None = None) -> Path:
+    normalized = validate_profile(value, home=home)
+    path = target_profile_path(normalized["targetName"], home)
+    directory = path.parent
+    if directory.exists() and (directory.is_symlink() or not directory.is_dir()):
+        raise DeploymentKitError(f"Target profile directory is not a real directory: {directory}")
+    directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+    if os.name != "nt":
+        directory.chmod(0o700)
+    if path.exists() and path.is_symlink():
+        raise DeploymentKitError(f"Refusing to replace symbolic-link target profile: {path}")
+    temporary = path.with_suffix(".tmp")
+    temporary.write_text(json.dumps(normalized, indent=2) + "\n", encoding="utf-8")
+    if os.name != "nt":
+        temporary.chmod(0o600)
+    temporary.replace(path)
+    return path

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

@@ -0,0 +1,114 @@
+"""Read-only exact-image registry access verification for logical targets."""
+
+from __future__ import annotations
+
+import re
+import shlex
+import subprocess
+from typing import Any
+
+from .errors import DeploymentKitError
+from .profiles import load_profile
+from .ssh import ssh_args, verify_access
+
+
+_IMAGE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._/:+-]*@sha256:[0-9a-f]{64}$")
+
+_REMOTE_SCRIPT = r'''#!/usr/bin/env bash
+set -Eeuo pipefail
+
+unset DOCKER_CONFIG
+
+IMAGE="$1"
+
+[[ "$IMAGE" =~ ^[A-Za-z0-9][A-Za-z0-9._/:+-]*@sha256:[0-9a-f]{64}$ ]] || {
+    echo "Image must be an immutable sha256 digest reference." >&2
+    exit 41
+}
+
+command -v docker >/dev/null 2>&1 || {
+    echo "Docker CLI is unavailable on the target." >&2
+    exit 42
+}
+
+config_dir="$HOME/.docker"
+config_file="$config_dir/config.json"
+credential_state="absent"
+
+if [[ -e "$config_file" ]]; then
+    [[ -d "$config_dir" && ! -L "$config_dir" && -f "$config_file" && ! -L "$config_file" ]] || {
+        echo "Docker credential path is not a regular protected directory/file." >&2
+        exit 43
+    }
+    dir_mode="$(stat -c '%a' "$config_dir")"
+    file_mode="$(stat -c '%a' "$config_file")"
+    current_uid="$(id -u)"
+    if (( (8#$dir_mode & 077) != 0 || (8#$file_mode & 077) != 0 )) ||
+       [[ "$(stat -c '%u' "$config_dir")" != "$current_uid" || "$(stat -c '%u' "$config_file")" != "$current_uid" ]]; then
+        echo "Docker credentials must be owned by the deployment account and deny group/other access." >&2
+        exit 43
+    fi
+    export DOCKER_CONFIG="$config_dir"
+    credential_state="protected"
+fi
+
+if ! docker manifest inspect "$IMAGE" </dev/null >/dev/null 2>&1; then
+    echo "Registry manifest access failed for the exact image." >&2
+    exit 44
+fi
+
+printf 'ACCESS\t%s\n' "$credential_state"
+'''
+
+
+def normalize_registry_image(value: str) -> str:
+    if not isinstance(value, str) or _IMAGE_RE.fullmatch(value) is None:
+        raise DeploymentKitError(
+            "image must be an immutable image reference ending in @sha256:<64 lowercase hex>."
+        )
+    return value
+
+
+def build_remote_script() -> str:
+    return _REMOTE_SCRIPT
+
+
+def _parse_access(output: str) -> str:
+    lines = [line for line in output.splitlines() if line]
+    if len(lines) != 1:
+        raise DeploymentKitError("Malformed registry access verification output.")
+    parts = lines[0].split("\t")
+    if len(parts) != 2 or parts[0] != "ACCESS" or parts[1] not in {"absent", "protected"}:
+        raise DeploymentKitError("Malformed registry access verification output.")
+    return parts[1]
+
+
+def verify_registry_access(name: str, image: str) -> dict[str, Any]:
+    exact_image = normalize_registry_image(image)
+    profile = load_profile(name)
+    access = verify_access(profile)
+    command = ssh_args(
+        profile,
+        access["address"],
+        command="bash -s -- " + shlex.quote(exact_image),
+    )
+    completed = subprocess.run(
+        command,
+        input=build_remote_script().encode("utf-8"),
+        check=False,
+        capture_output=True,
+    )
+    stdout = completed.stdout.decode("utf-8", errors="replace")
+    stderr = completed.stderr.decode("utf-8", errors="replace")
+    if completed.returncode != 0:
+        detail = stderr.strip() or stdout.strip() or f"exit {completed.returncode}"
+        raise DeploymentKitError(f"Read-only registry access verification failed: {detail}")
+
+    credential_state = _parse_access(stdout)
+    return {
+        "targetName": name,
+        "image": exact_image,
+        "manifestAccess": "verified",
+        "credentialConfig": credential_state,
+        "mutated": False,
+    }