@mriekki/project-forge 4.0.0 → 4.2.0

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

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import re
 import shlex
 import shutil
 import subprocess
@@ -13,6 +14,9 @@ from .registry_access import normalize_registry_image
 from .ssh import ssh_args, verify_access
 
 
+_IMAGE_ID_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
+
+
 def _docker() -> str:
     path = shutil.which("docker")
     if path is None:
@@ -20,13 +24,25 @@ def _docker() -> str:
     return path
 
 
+def _image_id(value: str) -> str:
+    if not isinstance(value, str) or _IMAGE_ID_RE.fullmatch(value) is None:
+        raise DeploymentKitError("Docker image ID must be sha256:<64 lowercase hex>.")
+    return value
+
+
 def verify_local_image(image: str) -> dict[str, str]:
+    """Verify the declared immutable registry digest and resolve its local config/image ID.
+
+    Registry RepoDigests are release identity. Docker's image ID is the config digest and is
+    the content identity preserved by ``docker save``/``docker load`` even when RepoTags are
+    absent from the archive.
+    """
+
     exact = normalize_registry_image(image)
     result = subprocess.run(
-        [_docker(), "image", "inspect", exact],
+        [_docker(), "image", "inspect", "--format", "{{.Id}}", exact],
         check=False,
-        stdout=subprocess.DEVNULL,
-        stderr=subprocess.PIPE,
+        capture_output=True,
         text=True,
         encoding="utf-8",
         errors="replace",
@@ -36,11 +52,17 @@ def verify_local_image(image: str) -> dict[str, str]:
             f"Exact image is not present in the workstation Docker engine: {exact}. "
             "Pull/build it locally before transfer."
         )
-    return {"image": exact, "localImage": "verified"}
+    image_id = _image_id(result.stdout.strip())
+    return {
+        "image": exact,
+        "registryDigest": exact,
+        "localImageId": image_id,
+    }
 
 
-def _remote_has_image(profile: dict[str, Any], address: str, image: str) -> bool:
-    command = "sudo -n docker image inspect " + shlex.quote(image) + " >/dev/null 2>&1"
+def _remote_has_image(profile: dict[str, Any], address: str, image_id: str) -> bool:
+    exact_id = _image_id(image_id)
+    command = "sudo -n docker image inspect " + shlex.quote(exact_id) + " >/dev/null 2>&1"
     result = subprocess.run(
         ssh_args(profile, address, command=command),
         check=False,
@@ -50,17 +72,31 @@ def _remote_has_image(profile: dict[str, Any], address: str, image: str) -> bool
     return result.returncode == 0
 
 
+def remote_image_present(name: str, image_id: str) -> bool:
+    """Read-only check for one exact Docker config/image ID on a verified target."""
+
+    exact_id = _image_id(image_id)
+    profile = load_profile(name)
+    access = verify_access(profile)
+    return _remote_has_image(profile, access["address"], exact_id)
+
+
 def transfer_image(name: str, image: str) -> dict[str, Any]:
-    exact = normalize_registry_image(image)
-    verify_local_image(exact)
+    local = verify_local_image(image)
+    exact = local["registryDigest"]
+    image_id = local["localImageId"]
     profile = load_profile(name)
     access = verify_access(profile)
     address = access["address"]
 
-    if _remote_has_image(profile, address, exact):
+    if _remote_has_image(profile, address, image_id):
         return {
             "targetName": name,
             "image": exact,
+            "registryDigest": exact,
+            "localImageId": image_id,
+            "remoteImageId": image_id,
+            "runtimeImage": image_id,
             "status": "already-present",
             "mutated": False,
         }
@@ -93,13 +129,17 @@ def transfer_image(name: str, image: str) -> dict[str, Any]:
         )
         raise DeploymentKitError(f"Remote Docker image load failed: {detail}")
 
-    if not _remote_has_image(profile, address, exact):
+    if not _remote_has_image(profile, address, image_id):
         raise DeploymentKitError(
-            "Remote docker load completed but the exact immutable image reference is not inspectable on the target."
+            "Remote docker load completed but the exact Docker config/image ID is not inspectable on the target."
         )
     return {
         "targetName": name,
         "image": exact,
+        "registryDigest": exact,
+        "localImageId": image_id,
+        "remoteImageId": image_id,
+        "runtimeImage": image_id,
         "status": "transferred",
         "mutated": True,
     }

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

@@ -0,0 +1,183 @@
+"""Durable workstation-local receipts for disposable environment proofs.
+
+Receipts are diagnostic/readiness evidence, not deployment authorization or a workflow
+database. They contain no credentials or mutable application data.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+from .errors import DeploymentKitError
+from .keys import key_fingerprint
+from .profiles import load_profile
+
+
+SCHEMA_VERSION = 1
+PROOF_CONTRACT_VERSION = 1
+_ENV_RE = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$")
+_REPO_RE = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$")
+
+
+def _root() -> Path:
+    configured = os.environ.get("PROJECT_FORGE_HOME")
+    return Path(configured).expanduser() if configured else Path.home() / ".project-forge"
+
+
+def _receipt_path(owner_repo: str, environment: str) -> Path:
+    if _REPO_RE.fullmatch(owner_repo) is None:
+        raise DeploymentKitError("ownerRepo must use GitHub owner/repository form without URL syntax.")
+    if _ENV_RE.fullmatch(environment) is None:
+        raise DeploymentKitError("environment must use lowercase letters, digits, and internal hyphens.")
+    owner, repo = owner_repo.split("/", 1)
+    return _root() / "evidence" / "environment-proofs" / owner / repo / f"{environment}.json"
+
+
+def _sha256_file(path: Path) -> str:
+    try:
+        data = path.read_bytes()
+    except OSError as error:
+        raise DeploymentKitError(f"Cannot read target trust evidence {path}: {error}") from error
+    return hashlib.sha256(data).hexdigest()
+
+
+def current_target_signature(target_name: str) -> dict[str, Any]:
+    """Return non-secret workstation/target identity used to invalidate stale proof."""
+
+    profile = load_profile(target_name)
+    identity = Path(profile["identityFile"])
+    known_hosts = Path(profile["knownHostsFile"])
+    signature = {
+        "targetName": profile["targetName"],
+        "targetOs": profile["targetOs"],
+        "hostName": profile["hostName"],
+        "sshAlias": profile["sshAlias"],
+        "user": profile["user"],
+        "port": profile["port"],
+        "addressOverride": profile["addressOverride"],
+        "identityFingerprint": key_fingerprint(identity),
+        "trustSha256": _sha256_file(known_hosts),
+    }
+    canonical = json.dumps(signature, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    return {**signature, "signatureSha256": hashlib.sha256(canonical).hexdigest()}
+
+
+def write_environment_proof_receipt(result: dict[str, Any]) -> dict[str, Any]:
+    required = {
+        "ownerRepo",
+        "environment",
+        "targetName",
+        "production",
+        "proof",
+        "cleanupState",
+        "finalMutationState",
+    }
+    missing = sorted(required.difference(result))
+    if missing:
+        raise DeploymentKitError("Environment proof result is missing receipt fields: " + ", ".join(missing))
+
+    path = _receipt_path(result["ownerRepo"], result["environment"])
+    target = current_target_signature(result["targetName"])
+    receipt = {
+        "schemaVersion": SCHEMA_VERSION,
+        "proofContractVersion": PROOF_CONTRACT_VERSION,
+        "deploymentKitVersion": __version__,
+        "recordedAt": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        "ownerRepo": result["ownerRepo"],
+        "environment": result["environment"],
+        "targetName": result["targetName"],
+        "production": bool(result["production"]),
+        "proof": result["proof"],
+        "cleanupState": result["cleanupState"],
+        "finalMutationState": result["finalMutationState"],
+        "registryDigest": result.get("registryDigest"),
+        "localImageId": result.get("localImageId"),
+        "remoteImageId": result.get("remoteImageId"),
+        "targetSignature": target,
+    }
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temp = path.with_suffix(".tmp")
+    temp.write_text(json.dumps(receipt, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    temp.replace(path)
+    return {"path": str(path), "recordedAt": receipt["recordedAt"], "state": "recorded"}
+
+
+def load_environment_proof_receipt(
+    target_name: str,
+    *,
+    owner_repo: str,
+    environment: str,
+    production: bool,
+) -> dict[str, Any]:
+    """Return whether a prior proof receipt is still applicable on this workstation."""
+
+    path = _receipt_path(owner_repo, environment)
+    if not path.is_file():
+        return {"state": "missing", "path": str(path), "mutated": False}
+    try:
+        receipt = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        return {
+            "state": "invalid",
+            "path": str(path),
+            "reason": f"Cannot read proof receipt: {error}",
+            "mutated": False,
+        }
+
+    expected = {
+        "schemaVersion": SCHEMA_VERSION,
+        "proofContractVersion": PROOF_CONTRACT_VERSION,
+        "deploymentKitVersion": __version__,
+        "ownerRepo": owner_repo,
+        "environment": environment,
+        "targetName": target_name,
+        "production": bool(production),
+    }
+    mismatches = [key for key, value in expected.items() if receipt.get(key) != value]
+    if mismatches:
+        return {
+            "state": "stale",
+            "path": str(path),
+            "reason": "Receipt context changed: " + ", ".join(mismatches),
+            "mutated": False,
+        }
+
+    if receipt.get("proof") != "passed" or receipt.get("cleanupState") not in {"removed", "absent"}:
+        return {
+            "state": "not-proven",
+            "path": str(path),
+            "reason": "Latest receipt is not a clean passing proof.",
+            "mutated": False,
+        }
+
+    try:
+        current = current_target_signature(target_name)
+    except DeploymentKitError as error:
+        return {"state": "stale", "path": str(path), "reason": str(error), "mutated": False}
+    previous = receipt.get("targetSignature") or {}
+    if previous.get("signatureSha256") != current.get("signatureSha256"):
+        return {
+            "state": "stale",
+            "path": str(path),
+            "reason": "Target/workstation identity or trust changed after the recorded proof.",
+            "mutated": False,
+        }
+
+    return {
+        "state": "proven",
+        "path": str(path),
+        "recordedAt": receipt.get("recordedAt"),
+        "targetName": target_name,
+        "ownerRepo": owner_repo,
+        "environment": environment,
+        "production": bool(production),
+        "finalMutationState": receipt.get("finalMutationState"),
+        "mutated": False,
+    }

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

@@ -1,7 +1,8 @@
-"""Strict SSH verification primitives for logical targets."""
+"""Strict SSH verification and bounded diagnostics for logical targets."""
 
 from __future__ import annotations
 
+import re
 import shutil
 import socket
 import subprocess
@@ -9,9 +10,14 @@ from pathlib import Path
 from typing import Any
 
 from .errors import DeploymentKitError
+from .keys import key_fingerprint
 from .security import check_ssh_material_security, validate_target_trust_file
 
 
+_AUTH_METHODS_RE = re.compile(r"Authentications that can continue:\s*(?P<methods>[^\r\n]+)")
+_PERMISSION_DENIED_RE = re.compile(r"Permission denied \((?P<methods>[^)]+)\)")
+
+
 def required_tool(name: str) -> str:
     path = shutil.which(name)
     if path is None:
@@ -40,7 +46,7 @@ def resolve_addresses(profile: dict[str, Any]) -> list[str]:
     return addresses
 
 
-def ssh_args(profile: dict[str, Any], address: str, *, command: str = "true") -> list[str]:
+def _strict_transport_args(profile: dict[str, Any], address: str) -> list[str]:
     return [
         required_tool("ssh"),
         "-F",
@@ -64,16 +70,6 @@ def ssh_args(profile: dict[str, Any], address: str, *, command: str = "true") ->
         "-o",
         f"HostKeyAlias={profile['sshAlias']}",
         "-o",
-        f"IdentityFile={profile['identityFile']}",
-        "-o",
-        "IdentitiesOnly=yes",
-        "-o",
-        "PasswordAuthentication=no",
-        "-o",
-        "KbdInteractiveAuthentication=no",
-        "-o",
-        "PreferredAuthentications=publickey",
-        "-o",
         "ForwardAgent=no",
         "-o",
         "ForwardX11=no",
@@ -81,11 +77,277 @@ def ssh_args(profile: dict[str, Any], address: str, *, command: str = "true") ->
         "ClearAllForwardings=yes",
         "-p",
         str(profile["port"]),
-        f"{profile['user']}@{address}",
-        command,
     ]
 
 
+def ssh_args(
+    profile: dict[str, Any],
+    address: str,
+    *,
+    command: str = "true",
+    verbose: bool = False,
+) -> list[str]:
+    args = _strict_transport_args(profile, address)
+    if verbose:
+        args.insert(1, "-vv")
+    args.extend(
+        [
+            "-o",
+            f"IdentityFile={profile['identityFile']}",
+            "-o",
+            "IdentitiesOnly=yes",
+            "-o",
+            "PasswordAuthentication=no",
+            "-o",
+            "KbdInteractiveAuthentication=no",
+            "-o",
+            "PreferredAuthentications=publickey",
+            f"{profile['user']}@{address}",
+            command,
+        ]
+    )
+    return args
+
+
+def authentication_probe_args(profile: dict[str, Any], address: str) -> list[str]:
+    """Build a read-only SSH handshake that discovers advertised auth methods.
+
+    Host identity is still verified through the configured target-specific trust file.
+    All actual client authentication mechanisms are disabled so the server's initial
+    authentication-method advertisement can be observed without attempting credentials.
+    """
+
+    args = _strict_transport_args(profile, address)
+    args.insert(1, "-vv")
+    args.extend(
+        [
+            "-o",
+            "PubkeyAuthentication=no",
+            "-o",
+            "PasswordAuthentication=no",
+            "-o",
+            "KbdInteractiveAuthentication=no",
+            "-o",
+            "GSSAPIAuthentication=no",
+            "-o",
+            "HostbasedAuthentication=no",
+            f"{profile['user']}@{address}",
+            "true",
+        ]
+    )
+    return args
+
+
+def _completed(args: list[str]) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        args,
+        check=False,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        stdin=subprocess.DEVNULL,
+    )
+
+
+def _auth_methods(text: str) -> list[str]:
+    methods: list[str] = []
+    for match in _AUTH_METHODS_RE.finditer(text):
+        for method in match.group("methods").split(","):
+            value = method.strip()
+            if value and value not in methods:
+                methods.append(value)
+    if not methods:
+        denied = _PERMISSION_DENIED_RE.search(text)
+        if denied:
+            for method in denied.group("methods").split(","):
+                value = method.strip()
+                if value and value not in methods:
+                    methods.append(value)
+    return methods
+
+
+def probe_authentication_methods(profile: dict[str, Any], address: str) -> dict[str, Any]:
+    result = _completed(authentication_probe_args(profile, address))
+    text = "\n".join(part for part in (result.stderr, result.stdout) if part)
+    methods = _auth_methods(text)
+    return {
+        "address": address,
+        "methods": methods,
+        "passwordSupported": "password" in methods or "keyboard-interactive" in methods,
+        "publicKeySupported": "publickey" in methods,
+        "observed": bool(methods),
+        "returnCode": result.returncode,
+    }
+
+
+def _tcp_probe(profile: dict[str, Any], address: str) -> dict[str, Any]:
+    try:
+        with socket.create_connection((address, int(profile["port"])), timeout=8):
+            pass
+        return {"state": "reachable", "address": address, "port": int(profile["port"])}
+    except OSError as error:
+        return {
+            "state": "unreachable",
+            "address": address,
+            "port": int(profile["port"]),
+            "reason": str(error),
+        }
+
+
+def _classify_failure(text: str, *, auth: dict[str, Any], offered: bool, accepted: bool) -> str:
+    lower = text.lower()
+    if "remote host identification has changed" in lower or "host key verification failed" in lower:
+        return "host-identity-rejected"
+    if any(
+        marker in lower
+        for marker in (
+            "sign_and_send_pubkey: signing failed",
+            "agent refused operation",
+            "incorrect passphrase",
+            "load key",
+        )
+    ):
+        return "local-signing-failed"
+    if "connection timed out" in lower or "connection refused" in lower or "no route to host" in lower:
+        return "transport-failed"
+    if "permission denied" in lower:
+        if accepted:
+            return "remote-account-policy-rejected"
+        if offered or auth.get("publicKeySupported"):
+            return "remote-authentication-rejected"
+        return "authentication-rejected"
+    return "ssh-verification-failed"
+
+
+def diagnose_access(profile: dict[str, Any]) -> dict[str, Any]:
+    """Return safe structured SSH failure evidence without changing workstation or target state."""
+
+    identity = Path(profile["identityFile"])
+    known_hosts = Path(profile["knownHostsFile"])
+    if not identity.is_file():
+        return {
+            "targetName": profile["targetName"],
+            "state": "failed",
+            "failureCategory": "missing-identity",
+            "reason": f"Dedicated private key is missing: {identity}",
+            "mutated": False,
+        }
+    if not known_hosts.is_file() or known_hosts.stat().st_size == 0:
+        return {
+            "targetName": profile["targetName"],
+            "state": "failed",
+            "failureCategory": "missing-trust",
+            "reason": f"Target-specific trust file is missing or empty: {known_hosts}",
+            "mutated": False,
+        }
+
+    try:
+        check_ssh_material_security(identity, known_hosts)
+        validate_target_trust_file(profile)
+    except DeploymentKitError as error:
+        return {
+            "targetName": profile["targetName"],
+            "state": "failed",
+            "failureCategory": "local-security-or-trust-invalid",
+            "reason": str(error),
+            "mutated": False,
+        }
+
+    try:
+        addresses = resolve_addresses(profile)
+    except DeploymentKitError as error:
+        return {
+            "targetName": profile["targetName"],
+            "state": "failed",
+            "failureCategory": "name-resolution-failed",
+            "reason": str(error),
+            "mutated": False,
+        }
+
+    fingerprint = key_fingerprint(identity)
+    attempts: list[dict[str, Any]] = []
+    for address in addresses:
+        tcp = _tcp_probe(profile, address)
+        if tcp["state"] != "reachable":
+            attempts.append({"address": address, "tcp": tcp, "state": "transport-failed"})
+            continue
+
+        auth = probe_authentication_methods(profile, address)
+        result = _completed(ssh_args(profile, address, verbose=True))
+        text = "\n".join(part for part in (result.stderr, result.stdout) if part)
+        offered = "offering public key" in text.lower()
+        accepted = "server accepts key" in text.lower()
+        if result.returncode == 0:
+            return {
+                "targetName": profile["targetName"],
+                "state": "verified",
+                "address": address,
+                "identityFingerprint": fingerprint,
+                "authentication": auth,
+                "offeredConfiguredIdentity": offered,
+                "serverAcceptedConfiguredIdentity": accepted,
+                "mutated": False,
+            }
+
+        attempts.append(
+            {
+                "address": address,
+                "tcp": tcp,
+                "authentication": auth,
+                "identityFingerprint": fingerprint,
+                "offeredConfiguredIdentity": offered,
+                "serverAcceptedConfiguredIdentity": accepted,
+                "returnCode": result.returncode,
+                "failureCategory": _classify_failure(
+                    text,
+                    auth=auth,
+                    offered=offered,
+                    accepted=accepted,
+                ),
+            }
+        )
+
+    category = "transport-failed"
+    for candidate in (
+        "host-identity-rejected",
+        "local-signing-failed",
+        "remote-account-policy-rejected",
+        "remote-authentication-rejected",
+        "authentication-rejected",
+        "ssh-verification-failed",
+    ):
+        if any(item.get("failureCategory") == candidate for item in attempts):
+            category = candidate
+            break
+
+    guidance = {
+        "transport-failed": "Verify the configured address/port and network path; do not scan or silently switch targets.",
+        "host-identity-rejected": "Re-verify host identity independently before any trust rotation.",
+        "local-signing-failed": "Repair local key/passphrase/agent use; do not weaken remote authentication policy.",
+        "remote-authentication-rejected": (
+            "The configured public-key path reached the server but authentication was rejected. "
+            "Verify authorized_keys and remote account/source access policy from a trusted console or already-authorized session."
+        ),
+        "remote-account-policy-rejected": (
+            "The server accepted the configured key but the session was still rejected. "
+            "Inspect remote account/source policy from a trusted console or already-authorized session."
+        ),
+        "authentication-rejected": "Inspect the server-advertised authentication policy and the configured account.",
+        "ssh-verification-failed": "Inspect the structured attempt evidence before changing target or SSH policy.",
+    }[category]
+
+    return {
+        "targetName": profile["targetName"],
+        "state": "failed",
+        "failureCategory": category,
+        "identityFingerprint": fingerprint,
+        "attempts": attempts,
+        "guidance": guidance,
+        "mutated": False,
+    }
+
+
 def verify_access(profile: dict[str, Any]) -> dict[str, str]:
     identity = Path(profile["identityFile"])
     known_hosts = Path(profile["knownHostsFile"])
@@ -101,15 +363,7 @@ def verify_access(profile: dict[str, Any]) -> dict[str, str]:
 
     failures: list[str] = []
     for address in resolve_addresses(profile):
-        result = subprocess.run(
-            ssh_args(profile, address),
-            check=False,
-            capture_output=True,
-            text=True,
-            encoding="utf-8",
-            errors="replace",
-            stdin=subprocess.DEVNULL,
-        )
+        result = _completed(ssh_args(profile, address))
         if result.returncode == 0:
             return {"targetName": profile["targetName"], "address": address, "status": "verified"}
         failures.append(f"{address}: exit {result.returncode}")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mriekki/project-forge",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "description": "Public consumer distribution and updater for Project Forge engineering assets.",
   "type": "module",
   "bin": {