Build deterministic physical HID fixture and capture lab

.gitignore

@@ -80,6 +80,7 @@ run-tests-automated.sh
 .tmp/
 output/
 test-results/
+.keypath-lab/
 
 # Generated coverage reports (produced in CI; never commit)
 coverage/

Scripts/build-and-sign.sh

@@ -529,6 +529,11 @@ else
     create_sparkle_archive
 fi
 
+# A matrix build needs the exact signed artifact but must not replace or restart
+# the operator's installed app. Keep the normal release behavior as the default.
+if [ "${SKIP_DEPLOY:-0}" = "1" ]; then
+    echo "Skipping local deployment and restart (SKIP_DEPLOY=1)"
+else
 # Stop running KeyPath and kanata BEFORE replacing the app bundle.
 # Replacing binaries while the process is live causes macOS to detect
 # code page mismatches and kill the process with:
@@ -598,6 +603,8 @@ fi
 # Publish help content to website
 # ─────────────────────────────────────────────────────────────────────
 
+fi
+
 GHPAGES_DIR="$SCRIPT_DIR/../.worktrees/gh-pages"
 if [ -d "$GHPAGES_DIR" ] && [ "${SKIP_WEBSITE:-0}" != "1" ] && [ "${SKIP_NOTARIZE:-}" != "1" ]; then
     echo ""

Scripts/lab/assert-app-version

@@ -0,0 +1,24 @@
+#!/bin/zsh
+set -euo pipefail
+
+expected=${1:-}
+[[ -n "$expected" ]] || {
+  print -u2 "Usage: $0 EXPECTED_VERSION"
+  exit 2
+}
+
+app=/Applications/KeyPath.app
+plist="$app/Contents/Info.plist"
+[[ -d "$app" && -f "$plist" ]] || {
+  print -u2 "app version assertion: KeyPath is not installed"
+  exit 1
+}
+
+/usr/bin/codesign --verify --deep --strict "$app"
+actual=$(/usr/libexec/PlistBuddy -c 'Print :CFBundleShortVersionString' "$plist")
+[[ "$actual" == "$expected" ]] || {
+  print -u2 "app version assertion: expected $expected, found $actual"
+  exit 1
+}
+
+print "app_version\t$actual"

Scripts/lab/assert-runtime-state

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""Independently assert the installed KeyPath runtime is ready or degraded."""
+
+import json
+import os
+import subprocess
+import sys
+
+
+def run(command: list[str]) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(command, text=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+
+
+def main() -> int:
+    if len(sys.argv) not in {2, 4} or sys.argv[1] not in {"ready", "degraded"}:
+        print(
+            f"Usage: {sys.argv[0]} ready|degraded "
+            "[--managed-policy-manifest PATH]",
+            file=sys.stderr,
+        )
+        return 2
+    managed_manifest = None
+    if len(sys.argv) == 4:
+        if sys.argv[2] != "--managed-policy-manifest":
+            print("runtime assertion: invalid managed-policy option", file=sys.stderr)
+            return 2
+        managed_manifest = sys.argv[3]
+
+    expected = sys.argv[1]
+    cli = os.environ.get(
+        "KEYPATH_LAB_CLI",
+        "/Applications/KeyPath.app/Contents/MacOS/keypath-cli",
+    )
+    launchctl = os.environ.get("KEYPATH_LAB_LAUNCHCTL", "/bin/launchctl")
+    tcp_probe = os.environ.get(
+        "KEYPATH_LAB_TCP_PROBE",
+        os.path.join(os.path.dirname(__file__), "probe-kanata-tcp"),
+    )
+
+    status_result = run([cli, "service", "status", "--json"])
+    if status_result.returncode not in {0, 1}:
+        print(status_result.stderr, file=sys.stderr, end="")
+        return status_result.returncode
+    try:
+        payload = json.loads(status_result.stdout)
+    except json.JSONDecodeError as error:
+        print(f"runtime assertion: invalid service-status JSON: {error}", file=sys.stderr)
+        return 1
+    status = payload.get("data", payload)
+    if not isinstance(status, dict):
+        print("runtime assertion: service-status payload is not an object", file=sys.stderr)
+        return 1
+
+    launchd_result = run([launchctl, "print", "system/com.keypath.kanata"])
+    launchd_running = (
+        launchd_result.returncode == 0
+        and "state = running" in launchd_result.stdout
+    )
+
+    if expected == "degraded":
+        degraded = (
+            status.get("isOperational") is False
+            and status.get("kanataRunning") is False
+            and not launchd_running
+        )
+        if not degraded:
+            print(
+                "runtime assertion: expected a stopped Kanata service, "
+                f"got isOperational={status.get('isOperational')!r}, "
+                f"kanataRunning={status.get('kanataRunning')!r}, "
+                f"launchdRunning={launchd_running!r}",
+                file=sys.stderr,
+            )
+            return 1
+        print("runtime_state\tdegraded")
+        return 0
+
+    managed_accessibility_attested = False
+    if status.get("kanataAccessibility") is False and managed_manifest:
+        verify_lane = os.environ.get(
+            "KEYPATH_LAB_VERIFY_LANE",
+            os.path.join(os.path.dirname(__file__), "mdm", "verify-lane"),
+        )
+        managed_result = run(
+            [
+                verify_lane,
+                "managed-functional",
+                "--manifest",
+                managed_manifest,
+            ]
+        )
+        if managed_result.returncode != 0:
+            print(managed_result.stderr, file=sys.stderr, end="")
+            return managed_result.returncode
+        managed_accessibility_attested = True
+
+    required = [
+        "isOperational",
+        "helperInstalled",
+        "helperWorking",
+        "keyPathAccessibility",
+        "keyPathInputMonitoring",
+        "kanataInputMonitoring",
+        "kanataBinaryInstalled",
+        "karabinerDriverInstalled",
+        "vhidDeviceHealthy",
+        "kanataRunning",
+        "karabinerDaemonRunning",
+        "vhidHealthy",
+    ]
+    if not managed_accessibility_attested:
+        required.append("kanataAccessibility")
+    failed = [key for key in required if status.get(key) is not True]
+    if failed or not status.get("helperVersion") or not launchd_running:
+        print(
+            "runtime assertion: runtime is not ready; "
+            f"falseOrMissing={failed}, helperVersion={status.get('helperVersion')!r}, "
+            f"launchdRunning={launchd_running!r}",
+            file=sys.stderr,
+        )
+        return 1
+
+    tcp_result = run([tcp_probe])
+    if tcp_result.returncode != 0:
+        print(tcp_result.stderr, file=sys.stderr, end="")
+        return tcp_result.returncode
+    if managed_accessibility_attested:
+        print("kanata_accessibility_evidence\tmanaged-policy-profile")
+    print("runtime_state\tready")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

Scripts/lab/assert-uninstalled-state

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""Independently assert KeyPath-owned state is removed after uninstall."""
+
+import argparse
+import hashlib
+import os
+from pathlib import Path
+import subprocess
+import sys
+
+
+OWNED_SYSTEM_PATHS = (
+    "/Applications/KeyPath.app",
+    "/Library/PrivilegedHelperTools/com.keypath.helper",
+    "/Library/LaunchDaemons/com.keypath.kanata.plist",
+    "/Library/LaunchDaemons/com.keypath.karabiner-vhiddaemon.plist",
+    "/Library/LaunchDaemons/com.keypath.karabiner-vhidmanager.plist",
+    "/Library/LaunchDaemons/com.keypath.helper.plist",
+    "/Library/LaunchDaemons/com.keypath.logrotate.plist",
+    "/Library/KeyPath/bin/kanata",
+    "/usr/local/etc/kanata",
+    "/usr/local/bin/keypath-logrotate.sh",
+    "/etc/newsyslog.d/com.keypath.conf",
+)
+OWNED_LAUNCHD_LABELS = (
+    "system/com.keypath.kanata",
+    "system/com.keypath.helper",
+    "system/com.keypath.karabiner-vhiddaemon",
+    "system/com.keypath.karabiner-vhidmanager",
+    "system/com.keypath.logrotate",
+)
+SHARED_DRIVER_ID = "org.pqrs.Karabiner-DriverKit-VirtualHIDDevice"
+
+
+def run(command: list[str]) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(command, text=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+
+
+def rooted(root: Path, path: str) -> Path:
+    return root / path.removeprefix("/")
+
+
+def sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(65536), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--preserved-config", required=True, type=Path)
+    parser.add_argument("--expected-sha256", required=True)
+    args = parser.parse_args()
+
+    root = Path(os.environ.get("KEYPATH_LAB_ROOT", "/"))
+    home = Path(os.environ.get("KEYPATH_LAB_HOME", str(Path.home())))
+    launchctl = os.environ.get("KEYPATH_LAB_LAUNCHCTL", "/bin/launchctl")
+    pgrep = os.environ.get("KEYPATH_LAB_PGREP", "/usr/bin/pgrep")
+    systemextensionsctl = os.environ.get(
+        "KEYPATH_LAB_SYSTEMEXTENSIONSCTL", "/usr/bin/systemextensionsctl"
+    )
+
+    failures: list[str] = []
+    remaining_paths = [str(rooted(root, path)) for path in OWNED_SYSTEM_PATHS if rooted(root, path).exists()]
+    user_paths = (
+        home / "Library/Application Support/KeyPath",
+        home / "Library/Logs/KeyPath",
+    )
+    remaining_paths.extend(str(path) for path in user_paths if path.exists())
+    remaining_paths.extend(str(path) for path in (home / "Library/Preferences").glob("com.keypath*.plist"))
+    if remaining_paths:
+        failures.append("owned paths remain: " + ", ".join(sorted(remaining_paths)))
+
+    active_labels = [label for label in OWNED_LAUNCHD_LABELS if run([launchctl, "print", label]).returncode == 0]
+    if active_labels:
+        failures.append("owned launchd jobs remain: " + ", ".join(active_labels))
+
+    if run([pgrep, "-f", "/Applications/KeyPath.app"]).returncode == 0:
+        failures.append("a KeyPath application process is still running")
+
+    if not args.preserved_config.is_file():
+        failures.append(f"preserved configuration sentinel is missing: {args.preserved_config}")
+    elif sha256(args.preserved_config) != args.expected_sha256:
+        failures.append("preserved configuration sentinel changed during uninstall")
+
+    extensions = run([systemextensionsctl, "list"])
+    driver_lines = [line for line in extensions.stdout.splitlines() if SHARED_DRIVER_ID in line]
+    if extensions.returncode != 0:
+        failures.append("system extension inventory failed")
+    elif not any("activated enabled" in line for line in driver_lines):
+        failures.append("the shared VirtualHID driver was removed or is not activated and enabled")
+
+    if failures:
+        for failure in failures:
+            print(f"uninstall assertion: {failure}", file=sys.stderr)
+        return 1
+
+    print("keypath_owned_state\tremoved")
+    print("user_configuration\tpreserved")
+    print("shared_vhid_driver\tpreserved")
+    print("uninstall_state\tverified")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

Scripts/lab/assets/peekaboo-lab-host.c

@@ -0,0 +1,44 @@
+#include <errno.h>
+#include <limits.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/stat.h>
+#include <unistd.h>
+
+int main(void) {
+    const char *home = getenv("HOME");
+    char executable[PATH_MAX];
+    char support[PATH_MAX];
+    char socket_path[PATH_MAX];
+
+    if (home == NULL || home[0] != '/') {
+        return 64;
+    }
+    if (snprintf(executable, sizeof(executable), "%s/.local/bin/peekaboo", home) >=
+            (int)sizeof(executable) ||
+        snprintf(support, sizeof(support), "%s/Library/Application Support/Peekaboo", home) >=
+            (int)sizeof(support) ||
+        snprintf(socket_path, sizeof(socket_path), "%s/daemon.sock", support) >=
+            (int)sizeof(socket_path)) {
+        return 65;
+    }
+
+    if (mkdir(support, 0700) != 0 && errno != EEXIST) {
+        return 73;
+    }
+    unlink(socket_path);
+    execl(executable,
+          executable,
+          "daemon",
+          "run",
+          "--mode",
+          "manual",
+          "--bridge-socket",
+          socket_path,
+          "--idle-timeout-seconds",
+          "31536000",
+          "--input-strategy",
+          "actionFirst",
+          (char *)NULL);
+    return 127;
+}

Scripts/lab/capture-controller-state

@@ -0,0 +1,38 @@
+#!/bin/zsh
+set -euo pipefail
+
+output="$PWD/.keypath-lab/scenario-output/controller-capture"
+logs="$output/logs"
+service_logs="$output/service-logs"
+capture_home="${KEYPATH_CAPTURE_USER_HOME:-$HOME}"
+
+mkdir -p "$logs" "$service_logs"
+sw_vers > "$output/sw-vers.txt"
+date -u +%Y-%m-%dT%H:%M:%SZ > "$output/captured-at.txt"
+cp -R "$capture_home/Library/Logs/KeyPath/." "$logs/" 2>/dev/null || true
+
+/bin/launchctl print system/com.keypath.kanata > "$output/kanata-launchd.txt" 2>&1 || true
+/bin/ps -axo pid,ppid,user,state,lstart,command > "$output/processes.txt" 2>&1 || true
+/usr/bin/log show --last 10m --style compact \
+  --predicate 'process == "kanata" OR process == "kanata-launcher" OR eventMessage CONTAINS[c] "com.keypath.kanata"' \
+  > "$output/kanata-unified.log" 2>&1 || true
+
+for source in \
+  /var/log/com.keypath.kanata.stdout.log \
+  /var/log/com.keypath.kanata.stderr.log
+do
+  if [[ -r "$source" ]]; then
+    cp "$source" "$service_logs/${source:t}"
+  elif /usr/bin/sudo -n /usr/bin/test -r "$source" 2>/dev/null; then
+    /usr/bin/sudo -n /bin/cp "$source" "$service_logs/${source:t}" 2>/dev/null || true
+  fi
+done
+
+if [[ -x /Applications/KeyPath.app/Contents/MacOS/keypath-cli ]]; then
+  /Applications/KeyPath.app/Contents/MacOS/keypath-cli system inspect --json \
+    > "$output/system-inspect.json" 2>/dev/null || true
+fi
+
+if (( EUID == 0 )) && [[ -n "${KEYPATH_CAPTURE_OWNER:-}" ]]; then
+  /usr/sbin/chown -R "$KEYPATH_CAPTURE_OWNER":staff "$output" 2>/dev/null || true
+fi