docker*.sh scripts: add kvm support and missing authentication so that .docker_*.sh make BOARD=qemu* run launches kvm through gtk window as expected

.circleci/config.yml

@@ -48,7 +48,7 @@ commands:
 jobs:
   prep_env:
     docker:
-      - image: tlaurion/heads-dev-env:v0.2.5
+      - image: tlaurion/heads-dev-env:v0.2.7
     resource_class: large
     working_directory: ~/heads
     steps:
@@ -123,7 +123,7 @@ jobs:
 
   build_and_persist:
     docker:
-      - image: tlaurion/heads-dev-env:v0.2.5
+      - image: tlaurion/heads-dev-env:v0.2.7
     resource_class: large
     working_directory: ~/heads
     parameters:
@@ -151,7 +151,7 @@ jobs:
 
   build:
     docker:
-      - image: tlaurion/heads-dev-env:v0.2.5
+      - image: tlaurion/heads-dev-env:v0.2.7
     resource_class: large
     working_directory: ~/heads
     parameters:
@@ -172,7 +172,7 @@ jobs:
 
   save_cache:
     docker:
-      - image: tlaurion/heads-dev-env:v0.2.5
+      - image: tlaurion/heads-dev-env:v0.2.7
     resource_class: large
     working_directory: ~/heads
     steps:

COMMIT_MSG.txt

@@ -0,0 +1,86 @@
+Refactor Docker wrappers and add supply-chain safety mechanisms
+
+This commit consolidates Docker wrapper scripts by extracting common
+initialization logic into a shared `docker/common.sh` module, adds
+supply-chain safety features for Nix and Docker image pinning,
+improves developer UX with automatic dependency setup, and provides
+comprehensive documentation.
+
+Core improvements:
+
+1. Centralized Docker initialization (docker/common.sh - NEW)
+   - Extracted common device setup, X11, USB, and KVM handling
+   - Eliminated ~240 lines of duplication across wrapper scripts
+   - Added supply-chain safe Nix installer setup (HEADS_AUTO_INSTALL_NIX)
+   - Automatic flakes enablement (HEADS_AUTO_ENABLE_FLAKES)
+   - Disk-space preflight checks (HEADS_MIN_DISK_GB, default 50GB)
+   - USB token cleanup automation (detects scdaemon/pcscd, prompts on TTY)
+   - Image digest resolution with pinning support
+   - Fixed bash array expansion bug (${arr[@]} not ${arr[@]:-})
+   - Nix commands now sequential with proper output streaming
+
+2. Supply-chain safety helpers (NEW scripts)
+   - docker/fetch_nix_installer.sh: Download and verify Nix installer
+     SHA256 before execution; supports version or URL-based fetch
+   - docker/get_digest.sh: Obtain immutable Docker image digests
+     for pinning; queries local state or Docker Hub API
+   - docker/pin-and-run.sh: Wrap other scripts with image pinning
+     for reproducible CI/CD workflows
+   - docker/DOCKER_REPRO_DIGEST: Repository-level reproducible image pin
+
+3. Refactored wrapper scripts
+   - docker_repro.sh: Delegates to docker/common.sh; ~70 line reduction
+   - docker_local_dev.sh: Uses new maybe_rebuild_local_image() function;
+     ~93 line reduction; fixed array expansion bug; sequential Nix commands
+   - docker_latest.sh: Uses common device and image logic; ~78 line reduction
+   - All three now support environment variable pinning and configuration
+
+4. Comprehensive documentation (README.md)
+   - 183 new lines clarifying the three wrapper strategies
+   - "Wrapper options & environment variables" section documenting:
+     HEADS_DISABLE_USB, HEADS_X11_XAUTH, HEADS_SKIP_DOCKER_REBUILD,
+     HEADS_NIX_EXTRA_FLAGS, HEADS_NIX_VERBOSE, HEADS_AUTO_INSTALL_NIX,
+     HEADS_AUTO_ENABLE_FLAKES, HEADS_MIN_DISK_GB, HEADS_SKIP_DISK_CHECK,
+     DOCKER_REPRO_DIGEST
+   - Expanded "Using Nix local dev environment" with automation notes
+   - New "Using ./docker_local_dev.sh" subsection explaining preflight
+     checks, dirty-flake detection, and rebuild triggers
+   - Clarified three helpers and their use cases
+   - Example pinning workflows and digest resolution with get_digest.sh
+
+5. Improved targets/qemu.md (180 lines net change)
+   - Messaging update: QEMU/swtpm/tools are IN Docker images, not on host
+   - All example commands prefixed with ./docker_repro.sh
+   - Removed legacy host-side swtpm build instructions (Bullseye, Bookworm)
+   - New "Running via Docker wrappers" section with:
+     - Wrapper comparison table
+     - Feature breakdown (KVM, X11, USB, env forwarding)
+     - Environment variables reference table
+     - Usage examples and smoke tests
+     - Troubleshooting stub
+   - Clarified USB_TOKEN behavior and canokey-qemu default
+   - Documentation for hardlinks in QEMU disk management
+
+Technical highlights:
+
+- Supply-chain safety: HEADS_NIX_INSTALLER_SHA256 pinning prevents
+  auto-execution of unverified Nix installers
+- Reproducibility: DOCKER_REPRO_DIGEST and DOCKER_LATEST_DIGEST enable
+  pinning to immutable image digests
+- Developer experience: Automatic Nix/flakes setup, disk checks, live
+  output streaming, USB token cleanup, X11 GUI support
+- Code quality: Eliminated duplication; single source of truth for
+  device setup, image resolution, and environment handling
+- Bug fixes: Fixed bash array expansion in Nix commands; Nix commands
+  now run sequentially with proper output streaming (not in subshell)
+
+Testing notes (from PR author):
+- Tested on Ubuntu, Debian, Fedora with various installer flows
+- Smoke test: source docker/common.sh && build_docker_opts
+- Verified KVM passthrough detection and X11 GUI support
+- USB passthrough and token cleanup tested interactively
+
+Backward compatibility:
+- All wrapper scripts maintain existing behavior and argument forwarding
+- New environment variables are optional; defaults preserve current workflow
+- docker/common.sh is sourced, not executed standalone