@mriekki/project-forge 4.1.0 → 4.2.0

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

@@ -14,7 +14,8 @@ from .doctor import target_doctor, workstation_doctor
 from .environment_probe import plan_environment_proof
 from .errors import DeploymentKitError
 from .profiles import load_profile
-from .ssh import verify_access
+from .proof_receipt import load_environment_proof_receipt
+from .ssh import diagnose_access
 
 
 READINESS_ORDER = (
@@ -34,6 +35,13 @@ def _phase(label: str, state: str, *, detail: Any = None) -> dict[str, Any]:
     return value
 
 
+def _current_phase(phases: dict[str, dict[str, Any]]) -> str:
+    return next(
+        (key for key in READINESS_ORDER if phases[key]["state"] not in {"ready", "proven", "not-part-of-setup"}),
+        "application",
+    )
+
+
 def remote_setup_status(name: str) -> dict[str, Any]:
     """Return one read-only, terminal status model for remote environment setup."""
 
@@ -57,19 +65,15 @@ def remote_setup_status(name: str) -> dict[str, Any]:
         "application": _phase("APPLICATION DEPLOYED", "not-part-of-setup"),
     }
 
-    target_access: dict[str, Any] | None = None
     host_platform: dict[str, Any] | None = None
 
     if target["state"] == "ready-to-verify":
-        try:
-            target_access = verify_access(load_profile(name))
-            phases["targetAccess"] = _phase("TARGET ACCESS READY", "ready", detail=target_access)
-        except DeploymentKitError as error:
-            phases["targetAccess"] = _phase(
-                "TARGET ACCESS READY",
-                "verification-failed",
-                detail={"reason": str(error)},
-            )
+        target_access = diagnose_access(load_profile(name))
+        phases["targetAccess"] = _phase(
+            "TARGET ACCESS READY",
+            "ready" if target_access["state"] == "verified" else "diagnosis-required",
+            detail=target_access,
+        )
     elif target["state"] == "needs-profile":
         phases["targetAccess"] = _phase("TARGET ACCESS READY", "blocked-by-target-definition")
     else:
@@ -96,19 +100,76 @@ def remote_setup_status(name: str) -> dict[str, Any]:
     else:
         phases["hostPlatform"] = _phase("HOST PLATFORM READY", "blocked-by-target-access")
 
-    current = next(
-        (key for key in READINESS_ORDER if phases[key]["state"] not in {"ready", "not-part-of-setup"}),
-        "application",
-    )
     return {
         "targetName": name,
         "state": "host-platform-ready" if phases["hostPlatform"]["state"] == "ready" else "needs-setup",
-        "currentPhase": current,
+        "currentPhase": _current_phase(phases),
         "phases": phases,
         "mutated": False,
     }
 
 
+def _access_recovery(status: dict[str, Any]) -> dict[str, Any]:
+    detail = status["phases"]["targetAccess"].get("detail") or {}
+    category = detail.get("failureCategory")
+    target = status["targetName"]
+    command = f"project-forge-deploy environment setup status {target} --json"
+
+    if category in {"remote-authentication-rejected", "remote-account-policy-rejected"}:
+        return {
+            "kind": "operator-action-required",
+            "action": "inspect-remote-account-access-policy",
+            "command": command,
+            "reason": detail.get("guidance"),
+            "safety": (
+                "Use a trusted target console or already-authorized administrative session. "
+                "Do not reinstall keys repeatedly, enable password SSH, widen AllowUsers, or weaken host verification implicitly."
+            ),
+        }
+    if category == "local-signing-failed":
+        return {
+            "kind": "local-repair",
+            "action": "repair-local-key-signing",
+            "command": command,
+            "reason": detail.get("guidance"),
+        }
+    if category == "host-identity-rejected":
+        return {
+            "kind": "human-verification",
+            "action": "reverify-host-identity",
+            "command": f"project-forge-deploy target trust-candidates {target}",
+            "reason": detail.get("guidance"),
+        }
+    if category in {"transport-failed", "name-resolution-failed"}:
+        return {
+            "kind": "missing-facts",
+            "action": "repair-target-address-or-network-path",
+            "command": command,
+            "reason": detail.get("guidance") or detail.get("reason"),
+        }
+    if category == "missing-identity":
+        return {
+            "kind": "write-gated",
+            "action": "create-or-select-key",
+            "command": f"project-forge-deploy target key-create {target}",
+            "authorization": "[LOCAL KEY WRITE]",
+            "reason": detail.get("reason"),
+        }
+    if category == "missing-trust":
+        return {
+            "kind": "human-verification",
+            "action": "verify-and-enroll-host-trust",
+            "command": f"project-forge-deploy target trust-candidates {target}",
+            "reason": detail.get("reason"),
+        }
+    return {
+        "kind": "read-only",
+        "action": "diagnose-target-access",
+        "command": command,
+        "reason": detail.get("guidance") or detail.get("reason"),
+    }
+
+
 def _next_action(status: dict[str, Any]) -> dict[str, Any]:
     phases = status["phases"]
     target = phases["targetDefinition"].get("detail") or {}
@@ -151,12 +212,7 @@ def _next_action(status: dict[str, Any]) -> dict[str, Any]:
         }
 
     if phases["targetAccess"]["state"] != "ready":
-        return {
-            "kind": "read-only",
-            "action": "verify-target-access",
-            "command": f"project-forge-deploy target verify {status['targetName']}",
-            "reason": (phases["targetAccess"].get("detail") or {}).get("reason"),
-        }
+        return _access_recovery(status)
 
     platform = phases["hostPlatform"].get("detail") or {}
     platform_state = phases["hostPlatform"]["state"]
@@ -188,6 +244,14 @@ def _next_action(status: dict[str, Any]) -> dict[str, Any]:
             "reason": f"Host platform state is {platform_state}.",
         }
 
+    if phases["deploymentPath"]["state"] == "proven":
+        return {
+            "kind": "complete",
+            "action": "remote-environment-ready",
+            "reason": "Fresh workstation-local proof evidence matches this Project/environment/target context.",
+            "proofReceipt": phases["deploymentPath"].get("detail"),
+        }
+
     return {
         "kind": "proof-context-required",
         "action": "plan-deployment-path-proof",
@@ -204,7 +268,26 @@ def remote_setup_plan(
 ) -> dict[str, Any]:
     """Return the exact next deterministic setup action without mutating state."""
 
+    if (owner_repo is None) != (environment is None):
+        raise DeploymentKitError("ownerRepo and environment must be supplied together for setup proof planning.")
+
     status = remote_setup_status(name)
+    if owner_repo is not None and environment is not None and status["phases"]["hostPlatform"]["state"] == "ready":
+        receipt = load_environment_proof_receipt(
+            name,
+            owner_repo=owner_repo,
+            environment=environment,
+            production=production,
+        )
+        status["phases"]["deploymentPath"] = _phase(
+            "DEPLOYMENT PATH PROVEN",
+            "proven" if receipt["state"] == "proven" else "not-proven",
+            detail=receipt,
+        )
+        status["currentPhase"] = _current_phase(status["phases"])
+        if receipt["state"] == "proven":
+            status["state"] = "environment-ready"
+
     next_action = _next_action(status)
 
     if (
@@ -230,9 +313,8 @@ def remote_setup_plan(
             "command": command,
             "proofPlan": proof,
             "runAuthorization": proof["requiredAuthorization"],
+            "previousProof": status["phases"]["deploymentPath"].get("detail"),
         }
-    elif (owner_repo is None) != (environment is None):
-        raise DeploymentKitError("ownerRepo and environment must be supplied together for setup proof planning.")
 
     return {
         **status,

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

@@ -14,7 +14,7 @@ from .keys import key_fingerprint, public_key_info, required_tool as required_ss
 from .portable_profile import _machine_paths
 from .profiles import load_profile, save_profile, target_profile_path, validate_profile, validate_target_name
 from .security import check_identity_security, prepare_ssh_directory, validate_target_trust_file
-from .ssh import verify_access
+from .ssh import probe_authentication_methods, resolve_addresses, verify_access
 
 
 HOME_LAB_BOOTSTRAP_PHRASE = "[HOME LAB ACCESS BOOTSTRAP]"
@@ -212,6 +212,23 @@ def _password_bootstrap_args(profile: dict[str, Any], *, first_use: bool, comman
     ]
 
 
+def _require_password_bootstrap_capability(profile: dict[str, Any]) -> list[dict[str, Any]]:
+    """Fail before password onboarding when a trusted server advertises key-only auth."""
+
+    evidence = [probe_authentication_methods(profile, address) for address in resolve_addresses(profile)]
+    observed = [item for item in evidence if item["observed"]]
+    if observed and not any(item["passwordSupported"] for item in observed):
+        advertised = sorted({method for item in observed for method in item["methods"]})
+        shown = ", ".join(advertised) if advertised else "none observed"
+        raise DeploymentKitError(
+            "Password-assisted Home Lab bootstrap is unavailable for this trusted target: "
+            f"the SSH server advertises {shown}, not password/keyboard-interactive authentication. "
+            "Use the Strict key-onboarding path and a trusted console or already-authorized session "
+            "for any required server-side key/account-policy change. Do not enable password SSH merely for bootstrap."
+        )
+    return evidence
+
+
 def _install_public_key_with_password(profile: dict[str, Any], *, first_use: bool) -> None:
     info = public_key_info(profile)
     encoded = base64.b64encode(info["publicKey"].encode("utf-8")).decode("ascii")
@@ -316,6 +333,10 @@ def apply_home_lab_bootstrap(
         except DeploymentKitError:
             pass
 
+        # Existing trust lets us discover the server's advertised auth methods safely.
+        # Avoid a guaranteed-to-fail password prompt against public-key-only servers.
+        _require_password_bootstrap_capability(desired)
+
     _install_public_key_with_password(desired, first_use=first_use)
     validate_target_trust_file(desired)
     evidence = verify_access(desired)

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,
+    }