feat(preflight): host/toolchain validation + VERSIONS pin-file — T01

- VERSIONS: 7 container images (CONTRACT_003 §3.2) + 13 host tools, KEY=value,
  source-able+greppable; images carry :PIN_DIGEST placeholders with a documented
  pin-digests procedure (D5 determinism — no real deploy until pinned).
- preflight.sh: fails closed (non-zero on any required check), bash-3.2 safe,
  composable checks/ (versions,tools,env,docker) + gated (ssh,dns) that WARN-skip
  until the stack is configured.
- env check honors D2 (passphrase presence only, never printed).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

preflight/checks/env.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# -----------------------------------------------------------------------------
+# checks/env.sh — required environment for a `pulumi up` (CONTRACT_001 §1, §1.3).
+#   * PULUMI_CONFIG_PASSPHRASE : set & non-empty (the single external secret, D2).
+#                                NEVER printed — only its presence is reported.
+#   * SSH_PRIVATE_KEY_PATH      : path to the VM key (default ~/.ssh/id_rsa) exists.
+#   Exits non-zero if a required var is missing/empty or the key file is absent.
+# -----------------------------------------------------------------------------
+set -euo pipefail
+PF_DIR=$(cd "$(dirname "$0")/.." && pwd)
+# shellcheck source=../lib/common.sh
+. "$PF_DIR/lib/common.sh"
+
+echo "[env] required environment variables and secrets (CONTRACT_001 §1.3)"
+
+# --- PULUMI_CONFIG_PASSPHRASE: presence only, value is sacred (D2) ---
+if [ -n "${PULUMI_CONFIG_PASSPHRASE:-}" ]; then
+  pf_pass "PULUMI_CONFIG_PASSPHRASE is set (value not shown — D2)"
+elif [ -n "${PULUMI_CONFIG_PASSPHRASE_FILE:-}" ]; then
+  if [ -f "${PULUMI_CONFIG_PASSPHRASE_FILE}" ]; then
+    pf_pass "PULUMI_CONFIG_PASSPHRASE_FILE set and file exists (value not shown)"
+  else
+    pf_fail "PULUMI_CONFIG_PASSPHRASE_FILE='${PULUMI_CONFIG_PASSPHRASE_FILE}' does not exist"
+  fi
+else
+  pf_fail "PULUMI_CONFIG_PASSPHRASE is unset/empty (and no PULUMI_CONFIG_PASSPHRASE_FILE)"
+fi
+
+# --- SSH_PRIVATE_KEY_PATH: file must exist (CONTRACT_001 default ~/.ssh/id_rsa) ---
+ssh_key="${SSH_PRIVATE_KEY_PATH:-$HOME/.ssh/id_rsa}"
+# Expand a leading ~ if the operator exported it literally.
+case "$ssh_key" in
+  "~/"*) ssh_key="$HOME/${ssh_key#~/}" ;;
+  "~")   ssh_key="$HOME" ;;
+esac
+if [ -f "$ssh_key" ]; then
+  if [ -z "${SSH_PRIVATE_KEY_PATH:-}" ]; then
+    pf_pass "SSH private key found at default path: $ssh_key"
+  else
+    pf_pass "SSH private key found: $ssh_key"
+  fi
+  # Permission hygiene: warn (do not fail) on world/group-readable key.
+  perms=$(ls -l "$ssh_key" 2>/dev/null | cut -c1-10)
+  case "$perms" in
+    *------) : ;;  # owner-only-ish; fine
+    *) pf_warn "SSH key $ssh_key permissions look loose ($perms); 'chmod 600' recommended" ;;
+  esac
+else
+  pf_fail "SSH private key not found at '$ssh_key' (set SSH_PRIVATE_KEY_PATH or create ~/.ssh/id_rsa)"
+fi
+
+pf_summary "env"