vphone-cli/scripts/boot_host_preflight.sh

#!/bin/zsh
# boot_host_preflight.sh — Diagnose whether the host can launch the signed
# vphone-cli binary required for PV=3 virtualization boot/DFU flows.

set -euo pipefail

SCRIPT_DIR="${0:A:h}"
PROJECT_ROOT="${SCRIPT_DIR:h}"

ASSERT_BOOTABLE=0
QUIET=0

while [[ $# -gt 0 ]]; do
  case "$1" in
    --assert-bootable)
      ASSERT_BOOTABLE=1
      shift
      ;;
    --quiet)
      QUIET=1
      shift
      ;;
    *)
      echo "Unknown option: $1" >&2
      exit 2
      ;;
  esac
done

cd "$PROJECT_ROOT"

RELEASE_BIN="${PROJECT_ROOT}/.build/release/vphone-cli"
DEBUG_BIN="${PROJECT_ROOT}/.build/debug/vphone-cli"
ENTITLEMENTS="${PROJECT_ROOT}/sources/vphone.entitlements"
TMP_DIR="$(mktemp -d "${TMPDIR:-/tmp}/vphone-preflight.XXXXXX")"
TMP_SIGNED_DEBUG="${TMP_DIR}/vphone-cli.debug.signed"

cleanup() {
  rm -rf "$TMP_DIR"
}
trap cleanup EXIT

print_section() {
  (( QUIET == 0 )) || return 0
  echo ""
  echo "=== $1 ==="
}

run_capture() {
  local label="$1"
  shift

  local log_file="${TMP_DIR}/${label}.log"
  local rc=0
  "$@" >"$log_file" 2>&1 || rc=$?

  (( QUIET == 0 )) && echo "[${label}] exit=${rc}"
  if (( QUIET == 0 )) && [[ -s "$log_file" ]]; then
    sed -n '1,40p' "$log_file"
  fi
  return "$rc"
}

MODEL_NAME="$(system_profiler SPHardwareDataType 2>/dev/null | awk -F': ' '/Model Name/ {print $2; exit}')"
HV_VMM_PRESENT="$(sysctl -n kern.hv_vmm_present 2>/dev/null || true)"
SIP_STATUS="$(csrutil status)"
RESEARCH_GUEST_STATUS="$(csrutil allow-research-guests status)"
CURRENT_BOOT_ARGS="$(sysctl -n kern.bootargs 2>/dev/null || true)"
NEXT_BOOT_ARGS="$(nvram boot-args 2>/dev/null | sed 's/^boot-args[[:space:]]*//')"
ASSESSMENT_STATUS="$(spctl --status 2>/dev/null || true)"

print_section "Host"
sw_vers
echo "model: $MODEL_NAME"
echo "kern.hv_vmm_present: $HV_VMM_PRESENT"
echo "SIP: $SIP_STATUS"
echo "allow-research-guests: $RESEARCH_GUEST_STATUS"
echo "current kern.bootargs: $CURRENT_BOOT_ARGS"
echo "next-boot nvram boot-args: $NEXT_BOOT_ARGS"
echo "assessment: $ASSESSMENT_STATUS"

if (( ASSERT_BOOTABLE == 1 )); then
  if [[ "$HV_VMM_PRESENT" == "1" ]] || [[ "$MODEL_NAME" == "Apple Virtual Machine 1" ]]; then
    (( QUIET == 0 )) && {
      echo ""
      echo "Error: nested Apple VM host detected; Virtualization.framework guest boot is unavailable here." >&2
    }
    exit 3
  fi
fi

print_section "Entitlements"
if [[ -f "$RELEASE_BIN" ]]; then
  codesign -d --entitlements :- "$RELEASE_BIN" 2>/dev/null || true
else
  echo "missing release binary: $RELEASE_BIN"
fi

print_section "Policy"
if [[ -f "$RELEASE_BIN" ]]; then
  spctl --assess --type execute --verbose=4 "$RELEASE_BIN" 2>&1 || true
fi

print_section "Unsigned Debug Binary"
if [[ ! -f "$DEBUG_BIN" ]]; then
  echo "missing debug binary: $DEBUG_BIN"
  exit 1
fi
set +e
run_capture "debug_help" "$DEBUG_BIN" --help
DEBUG_HELP_RC=$?
set -e

print_section "Signed Release Binary"
if [[ ! -f "$RELEASE_BIN" ]]; then
  echo "missing release binary: $RELEASE_BIN"
  exit 1
fi
set +e
run_capture "release_help" "$RELEASE_BIN" --help
RELEASE_HELP_RC=$?
set -e

print_section "Signed Debug Control"
cp "$DEBUG_BIN" "$TMP_SIGNED_DEBUG"
codesign --force --sign - --entitlements "$ENTITLEMENTS" "$TMP_SIGNED_DEBUG" >/dev/null
set +e
run_capture "signed_debug_help" "$TMP_SIGNED_DEBUG" --help
SIGNED_DEBUG_HELP_RC=$?
set -e

print_section "Result"
echo "If unsigned debug runs but either signed binary exits 137 / signal 9,"
echo "the host is not currently permitting the required private virtualization entitlements."
echo "If the signed release binary exits 0 but the signed debug control still exits 137,"
echo "a path/CDHash-scoped amfidont bypass may already be active for this repo."
echo "Typical requirements for this project are:"
echo "  1. macOS 15+ with PV=3 support"
echo "  2. Host hardware must expose Virtualization.framework VM support (not a nested VM without virtualization availability)"
echo "  3. SIP disabled"
echo "  4. allow-research-guests enabled in Recovery OS"
echo "  5. AMFI / execution policy state that permits the private entitlements"
echo "  6. Gatekeeper / assessment configured so the signed binary is launchable"

if (( ASSERT_BOOTABLE == 1 )); then
  if (( RELEASE_HELP_RC != 0 )); then
    (( QUIET == 0 )) && {
      echo ""
      echo "Error: signed release vphone-cli is not launchable on this host (exit $RELEASE_HELP_RC)." >&2
    }
    exit "$RELEASE_HELP_RC"
  fi
fi