v0.8.1: add ISO by URL, zero-touch admin bootstrap

Ease-of-use pass inspired by Bootimus (Dnsmasq-PXE is a manual dnsmasq setup guide — nothing to adopt; OpenPXE already replaces that stack). Add ISO by URL: - New http-api `fetch` module: a small FetchJobs registry + a background streaming download (reqwest) that pipes a remote .iso through the same UploadHandle + introspection path as an upload, so a URL-fetched image classifies and gains boot entries identically. Progress is polled by the Storage view and rendered as rows, mirroring uploads. - Routes POST/GET/DELETE /api/isos/fetch. http/https only; .iso-only filename derived from Content-Disposition / URL basename with path traversal stripped; 16 GiB cap; cancel; credential-stripped URL display. Operator-gated, no boot-time outbound — offline boot is untouched. - Storage upload card gains an "Or add by URL" field with progress + cancel. Zero-touch admin bootstrap: - OPENPXE_ADMIN_USERNAME + OPENPXE_ADMIN_PASSWORD (or _PASSWORD_FILE for Docker/K8s secrets) auto-create the admin on first run, so a fresh container is usable with no setup wizard. Seeds the first run only — a lingering env var can't reset a rotated password. Tests: URL parse / filename / Content-Disposition unit tests + a wiremock end-to-end fetch-into-store integration test. clippy/fmt/node clean. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
v0.8.0: dep prune, memtest introspection fix, concurrent uploads, x-api-key
2026-07-16 15:56:27 -04:00 · 2026-06-21 23:35:42 -04:00 · 2026-06-14 08:15:43 -04:00 · 2026-06-12 17:04:01 -04:00 · 2026-06-12 15:21:14 -04:00 · 2026-06-09 22:44:19 -04:00
65 changed files with 10383 additions and 1852 deletions
@@ -11,3 +11,6 @@ data/work/
 .claude/settings.local.json
 .claude/worktrees/
 .claude/scheduled_tasks.lock
 # local editor / agent settings (not part of the project)
 .claude/
@@ -12,7 +12,7 @@ members = [
 ]
 [workspace.package]
-version = "0.5.3"
+version = "0.8.1"
 edition = "2021"
 rust-version = "1.95"
 license = "MIT OR Apache-2.0"
@@ -20,41 +20,45 @@ repository = "https://gitea.milesward.dev/mward4/OpenPXE"
 authors = ["OpenPXE contributors"]
 [workspace.dependencies]
-tokio = { version = "1.40", features = ["full"] }
+tokio = { version = "1.52", features = ["full"] }
 tokio-util = { version = "0.7", features = ["io"] }
 tokio-stream = { version = "0.1", features = ["sync"] }
 futures = "0.3"
 async-trait = "0.1"
-dhcproto = "0.12"
+# v0.6.2: dhcproto 0.15 drops the deprecated trust-dns-proto dependency
-socket2 = { version = "0.5", features = ["all"] }
+# (replaced by hickory-proto) and carries three releases of DHCP option
 # coverage accumulated upstream — both directly relevant to the proxy core.
 dhcproto = "0.15"
 socket2 = { version = "0.6", features = ["all"] }
 bytes = "1.7"
 nom = "7.1"
-axum = { version = "0.7", features = ["macros", "multipart", "http2"] }
+axum = { version = "0.8", features = ["macros", "multipart", "http2"] }
 tower = "0.5"
 tower-http = { version = "0.6", features = ["fs", "trace", "cors", "limit"] }
-hyper = "1.4"
+hyper = "1.9"
 reqwest = { version = "0.12", default-features = false, features = ["rustls-tls", "stream", "json"] }
 mime = "0.3"
 mime_guess = "2.0"
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 toml = "0.8"
 # v0.5.4: layered config (TOML file + env). Pure-Rust, no C deps; keeps the
 # static-musl build OpenSSL-free. Replaces the hand-rolled apply_env mapping.
 figment = { version = "0.10", features = ["toml", "env"] }
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
 anyhow = "1.0"
-thiserror = "1.0"
+thiserror = "2.0"
 clap = { version = "4.5", features = ["derive", "env"] }
 uuid = { version = "1.10", features = ["v4", "serde"] }
 time = { version = "0.3", features = ["serde", "serde-human-readable", "formatting", "macros"] }
 # sha2 stays 0.10 deliberately: bergshamra-crypto requires ^0.10, and
 # bumping to 0.11 would split the RustCrypto digest stack in the tree.
 sha2 = "0.10"
 hex = "0.4"
-bcrypt = "0.15"
+bcrypt = "0.19"
 once_cell = "1.19"
 parking_lot = "0.12"
 rust-embed = { version = "8.5", features = ["include-exclude"] }
@@ -76,15 +80,38 @@ lettre = { version = "0.11", default-features = false, features = ["smtp-transpo
 # C deps), so the static musl binary stays OpenSSL-free — samael was
 # rejected precisely because it hard-requires OpenSSL. We build the thin
 # SP layer (AuthnRequest, metadata parse, SAMLResponse semantics) on top.
-bergshamra = "0.4"
+bergshamra = "0.5"
 roxmltree = "0.21"
 quick-xml = "0.40"
 x509-parser = "0.18"
 # flate2 default backend is miniz_oxide (pure Rust) — do NOT enable the
 # zlib/zlib-ng C backends, which would break the musl-static build.
 flate2 = "1.1"
 base64 = "0.22"
 # v0.5.5: pure-Rust SSH/SFTP client for reading remote ISO libraries
 # over SFTP without a kernel mount.
 #
 # CRITICAL #1 — crypto backend: `default-features = false` +
 # `features = ["ring"]`. russh's *default* backend is `aws-lc-rs`, which
 # pulls `aws-lc-sys` (C code, fiddly under musl); the `ring` feature
 # instead reuses `ring 0.17` — the exact crate+version already in the
 # binary via rustls + bergshamra — so SFTP adds ZERO new C/crypto deps
 # and the static-musl build stays OpenSSL-free.
 #
 # CRITICAL #2 — history: this was pinned to =0.55.0 from v0.5.5 until
 # v0.6.3 because bergshamra-crypto pinned release-candidate RustCrypto
 # crates that conflicted with the stable generation russh 0.56+ pulls.
 # bergshamra 0.5 (2026-06) moved to the stable generation (pkcs8 0.11),
 # lifting the pin. v0.6.3 bumps to 0.61+, which also closes a batch of
 # RUSTSEC advisories reachable from the SFTP *client* path (unbounded
 # allocations in packet parsing — CVE-2026-48110/-46702/-46673 et al.)
 # and drops mlock on non-secret buffers (~21% SSH throughput upstream).
 #
 # SCP was deliberately rejected: the protocol is sequential-only (no
 # random access → no HTTP Range, unlike SFTP/NFS) and the mature SCP
 # crates wrap libssh2 (C + OpenSSL), which would break this build.
 russh = { version = "0.61", default-features = false, features = ["ring"] }
 russh-sftp = "2.3"
 openpxe-core = { path = "crates/core" }
 openpxe-dhcp-proxy = { path = "crates/dhcp-proxy" }
 openpxe-tftp = { path = "crates/tftp" }
@@ -1,301 +1,278 @@
-# OpenPXE
+<p align="center">
  <img src="docs/openpxe-logo.svg" alt="OpenPXE" width="104" height="104" />
 </p>
-Container-native PXE boot server. A Rust reimplementation of
+<h1 align="center">OpenPXE</h1>
 [iVentoy (ventoy/PXE)](https://github.com/ventoy/PXE), designed from scratch
 for Docker/OCI and OpenShift. Upload `.iso` files via the web UI; network
 clients PXE-boot them.
-> **Status:** v0.4.1 / pre-beta. Phases 1–5 complete: full PXE stack,
+<p align="center">
-> Queued Deployment queue, NFS-share ISO sources, live tracing log + an
+  <strong>Container-native network boot &amp; OS deployment — built in Rust.</strong>
-> operator terminal, per-MAC host bindings, Prometheus `/metrics`,
+</p>
 > light/dark theme toggle, animated OpenPXE imaging-progress widget,
 > chunked ISO uploads, and per-ISO boot passwords. The test suite and
 > clippy are part of the release checklist. Ready for real-hardware validation.
-## Design non-negotiables
+<p align="center">
  Drag in an ISO. PXE-boot and image an entire fleet from a browser.<br/>
  No iPXE scripting. No <code>dnsmasq</code> + <code>tftpd</code> + Samba glue. No glibc. No garbage collector.
 </p>
-1. **Fully offline / air-gap deployable.** Zero CDN assets. Zero external
+<p align="center">
-   HTTP calls from the server, the browser, or the generated iPXE scripts.
+  <img alt="release"   src="https://img.shields.io/badge/release-v0.6.0-2874d7" />
-   Build the container once, run forever disconnected.
+  <img alt="license"   src="https://img.shields.io/badge/license-MIT%20%7C%20Apache--2.0-59824f" />
-2. **iPXE is a backend implementation detail.** No `.ipxe` upload path, no
+  <img alt="rust"      src="https://img.shields.io/badge/built%20with-Rust-fb8841?logo=rust&logoColor=white" />
-   manual script editing, no iPXE terminology in the UI. Every knob in the
+  <img alt="container" src="https://img.shields.io/badge/container--native-OCI%20%C2%B7%20OpenShift-2496ED?logo=docker&logoColor=white" />
-   web UI maps to a specific script-generation behavior inside the binary.
+  <img alt="binary"    src="https://img.shields.io/badge/static-musl%20%C2%B7%20~18MB-330f1f" />
-3. **The client trust store is off-limits.** No test-signed drivers, no
+</p>
   `bcdedit /set testsigning on`, no certificates injected into WinPE or
   the target OS.
-## What it does
+---
-1. **DHCP proxy** (RFC 4578). Coexists with your existing DHCP server —
+OpenPXE turns bare-metal provisioning into a single container with a web UI. It's a
-   never assigns IPs. Listens on UDP 67 + UDP 4011.
+ground-up Rust reimplementation of [iVentoy (ventoy/PXE)](https://github.com/ventoy/PXE),
-2. **TFTP server** (RFC 1350 + RFC 2347/2348/2349/7440 option negotiation)
+designed for Docker/OCI and OpenShift instead of a Windows desktop — so it drops onto
-   that serves architecture-specific iPXE binaries to firmware PXE ROMs.
+an Unraid box, a Linux server, or a Kubernetes cluster and just runs.
 3. **HTTP server** that serves the web UI, the generated iPXE boot scripts,
   raw ISOs (with Range), and files inside ISOs without prior extraction.
 4. **ISO introspection**: auto-detects the distro family and generates the
   appropriate kernel+initrd or wimboot chain. No manual config.
 5. **Hierarchical PXE menu** mirroring the Phase 2 spec:
   ```
   Default        > Boot from Local HDD
   Installers     > Linux Installers  / Windows Installers
   Tools          > Utilities / OpenPXE Shell / Network Card Info
   Queued Deployment
   ```
 6. **Queued Deployment queue** — the coordinated launch flow. A client that
   selects *Queued Deployment* gets a numbered position and waits. The
   operator picks an ISO in the web UI and fires it to every waiting
   client simultaneously.
 7. **Web UI** (Netbox-style): sidebar nav (Dashboard / Network / Queue /
   Storage / Hosts / Terminal / About), light + dark themes
   (toggle top-right or press `T`), animated OpenPXE progress
   widget when devices are imaging. All assets served from the binary —
   no external requests.
 8. **Per-MAC host bindings.** Pin a MAC to a boot target and the client
   skips the menu, chains straight through.
 9. **Prometheus metrics** at `/metrics` — DHCP replies by arch, TFTP
   transfer counts and bytes, HTTP request counts by route, queue /
   imaging gauges, uptime, build info. Plain text exposition format,
   no external metrics framework dependency.
 8. **Settings API** lets you change the default boot-menu timeout (default
   600s), the timeout action (stay / Local HDD / Queued Deployment), and
   feature toggles like Windows ISO support. The iPXE scripts regenerate
   on every request using current settings.
-### Architectures supported on day one
+Upload `.iso` files (or point at a remote share), and any machine on the network boots
 them — Linux installers, live tools, or stock Windows setup — with **zero iPXE knowledge
 required by the operator.**
-| DHCP option 93 | Architecture    | Binary served           |
+> **Status — v0.6.0, late pre-beta.** The full PXE stack, web UI, remote ISO libraries
-|----------------|-----------------|-------------------------|
+> (SMB/NFS/SFTP), Windows deployment, queued fleet rollout, SAML SSO, and Prometheus
-| `0x0000`       | Legacy x86 BIOS | `undionly.kpxe`         |
+> metrics are implemented and test-covered. The release checklist gates every tag on the
-| `0x0006`       | IA32 UEFI       | `snponly-i386.efi`      |
+> full test suite + `clippy`. Currently in real-hardware validation.
 | `0x0007`/`0x0009` | x86_64 UEFI  | `snponly.efi`           |
 | `0x000B`       | ARM64 UEFI      | `snponly-arm64.efi`     |
-UEFI firmware that sends `HTTPClient` in option 60 is handled too — we
+## Why OpenPXE
 skip TFTP and respond with an HTTP URL.
-## Quick start — MVP container (recommended)
+Standing up network boot the traditional way means hand-wiring `dnsmasq`, a TFTP daemon,
 hand-written iPXE menu scripts, an HTTP server, and Samba — then keeping that fragile
 stack alive, and discovering none of it containerizes cleanly (kernel-mount NFS, raw
 sockets, `CAP_SYS_ADMIN`). iVentoy solved the UX beautifully, but it's a Windows GUI app.
 OpenPXE collapses that whole stack into **one statically-linked binary in one container**:
 - **A web UI does everything.** iPXE is an internal implementation detail — there is no
  script upload, no `.ipxe` editing, no PXE jargon in the interface.
 - **It runs anywhere a container runs.** No kernel modules, no privileged mode — proxy-mode
  DHCP + `NET_BIND_SERVICE` is the entire requirement. Verified on Unraid, plain Docker,
  and OpenShift's restricted SCC.
 - **It's air-gap native.** Zero CDN assets, zero outbound calls from the server, browser,
  or generated boot scripts. Build the image once, run it forever, disconnected.
 ## Highlights
 #### Boot stack
 - **DHCP proxy** (RFC 4578) that coexists with your existing DHCP — it never hands out IPs.
 - **TFTP** (RFC 1350 + 2347/2348/2349/7440 option negotiation) serving arch-correct iPXE firmware.
 - **HTTP** serving the UI, generated boot scripts, raw ISOs (with byte-range), and files
  *inside* ISOs with no prior extraction.
 - **Graphical iPXE boot menu** built from your uploads, with a PNG background and a clean
  hierarchy — generated fresh on every request from current settings.
 #### ISO management & remote libraries
 - **Drag-and-drop chunked uploads** that don't 502 on multi-GB images — drop several at once
  and they upload concurrently.
 - **Add by URL** — paste an ISO link and the server streams it straight into storage and
  auto-detects it, with progress; no download-then-reupload.
 - **Automatic introspection** — detects the distro family and generates the right
  kernel+initrd or Windows `wimboot` chain. No manual config.
 - **Remote ISO libraries, streamed on demand** (no local cache) over **SMB, NFS, or SFTP** —
  see the table below.
 #### Fleet deployment
 - **Queued Deployment** — clients join a queue and wait; the operator fires one image at
  every waiting machine simultaneously.
 - **Per-MAC host bindings** — pin a MAC straight to a target (with optional auto hostname,
  auto IP, and an unattended answer file); it skips the menu and chains through.
 - **Unattended installs** — upload Kickstart / Preseed / Autoinstall / Windows answer files;
  they're templated per-host (hostname / IP / MAC) and served only to booting clients.
 - **Windows deployment** from a stock Microsoft ISO — **every binary the client runs stays
  Microsoft-signed** (details below).
 #### Operations & access
 - **SAML 2.0 single sign-on** (pure-Rust SP, no OpenSSL/xmlsec) alongside local accounts.
 - **Custom branding** — light / dark / PXE-client logos and favicon.
 - **Notifications** — Slack / Teams / Discord webhooks and SMTP email on boot events.
 - **Prometheus `/metrics`**, a built-in operator **terminal**, live tracing log, and
  `/healthz` · `/readyz` probes.
 - **Layered config** — defaults → TOML file → `OPENPXE_*` env, in that order.
 - **Zero-touch first run** — set `OPENPXE_ADMIN_USERNAME` + `OPENPXE_ADMIN_PASSWORD` and a
  fresh container comes up with the admin already created, no setup wizard. Automate the rest
  from scripts/Postman with a per-install **API key** (`x-api-key`), shown in Settings → Advanced.
 ## Built in Rust
 Rust isn't a checkbox here — it's why OpenPXE deploys the way it does:
 - **One static binary, ~18 MB.** Compiled to `x86_64-unknown-linux-musl` — no glibc, no
  interpreter, no sidecar runtime. The runtime image is "binary + a few CLI tools."
 - **No garbage collector, async throughout.** A Tokio runtime drives DHCP, TFTP, HTTP, and
  many concurrent multi-GB ISO streams on a tiny, predictable memory footprint — it idles
  near-zero and never GC-pauses mid-transfer.
 - **Memory-safe by construction.** `unsafe` is **denied workspace-wide**; the only
  exceptions are two small, individually-audited FFI calls (`statvfs` for disk usage and a
  Samba `SIGHUP`).
 - **OpenSSL-free, pure-Rust crypto.** TLS via `rustls`/`ring`; the SAML Service Provider
  does XML-DSig verification with RustCrypto — no `xmlsec`, no `libxml2`, no C crypto to
  CVE-patch. Even the SMB/NFS/SFTP clients avoid C libraries.
 - **Sub-minute, reproducible container builds.** Cross-compiled with `cargo-zigbuild`
  (zig as the linker) — a full image builds in well under a minute on a warm cache, with
  no QEMU emulation.
 ## Quick start
 ### Run the container
 ```bash
-# 1. Pull bundled iPXE binaries (~2 MB, one-time).
+# Build the self-contained image (iPXE binaries are fetched + built inside the Dockerfile).
-./scripts/fetch-ipxe.sh
+docker build -f deploy/docker/Dockerfile -t openpxe:0.5.5 .
-# 2. Build the container image (~3 min first time).
+# Run it on the box plugged into your PXE network. Host networking is required in
-docker buildx build -f deploy/docker/Dockerfile -t openpxe:0.4.1 --load .
+# proxy mode so the container sees DHCPDISCOVER broadcasts; set PUBLIC_IP to this
-
+# host's LAN address so advertised boot URLs are reachable.
-# 3. Run it on the box plugged into your PXE network. Set PUBLIC_IP to
+docker run -d --name openpxe --network host \
 #    this host's LAN address so advertised iPXE URLs are reachable.
 docker run -d --name openpxe \
  --network host \
  -e OPENPXE_PUBLIC_IP=10.0.0.5 \
  -e OPENPXE_DHCP_MODE=proxy \
  -v $PWD/data/isos:/var/lib/openpxe/isos \
  -v $PWD/data/work:/var/lib/openpxe/work \
-  openpxe:0.4.1
+  openpxe:0.5.5
-# 4. Open the UI and drop an ISO in.
+# Open the UI and drop an ISO in.
 open http://10.0.0.5
 ```
-Host networking is required in proxy mode so the container sees DHCPDISCOVER
+> On macOS/Windows, Docker runs inside a Linux VM, so "host network" means the VM — use
-broadcasts from the PXE VLAN. On macOS/Windows hosts Docker runs in a Linux
+> the `openpxe-dev` service in `docker-compose.yml` for API-only testing on a laptop:
-VM, so "host" means the VM — use `openpxe-dev` in `docker-compose.yml` for
+> `OPENPXE_PUBLIC_IP=127.0.0.1 docker compose up openpxe-dev`.
 API-only testing on a laptop.
-### Quick start — docker compose
+### Build from source
 ```bash
-# MVP / API testing on a laptop (no DHCP, high ports):
+./scripts/fetch-ipxe.sh          # populate assets/ipxe/ (embedded at compile time)
-OPENPXE_PUBLIC_IP=127.0.0.1 docker compose up openpxe-dev
+cargo run --release              # needs root or CAP_NET_BIND_SERVICE for :80/:69
 # Real PXE deployment on a Linux host (host network, DHCP proxy on):
 OPENPXE_PUBLIC_IP=10.0.0.5  docker compose up openpxe
 ```
-### Multi-arch build + push
+### Pre-seed ISOs from a directory
 For deploying to x86_64 servers, build both arches in one manifest:
 ```bash
 # One-time: bootstrap a multi-arch builder.
 docker buildx create --name openpxe-multi --driver docker-container --use
 # Build + push both linux/amd64 and linux/arm64 under one tag.
 docker buildx build --builder openpxe-multi \
  --platform linux/amd64,linux/arm64 \
  -t ghcr.io/YOUR-ORG/openpxe:0.4.1 \
  --push \
  -f deploy/docker/Dockerfile .
 ```
 On an Apple Silicon host, the amd64 stage runs under QEMU emulation (~10-15 min for a cold cache). On a Linux x86_64 host, both arches build natively at normal speed. CI runners on GitHub Actions with `docker/build-push-action@v5` handle this cleanly.
 ### Build from source (no container)
 ```bash
 ./scripts/fetch-ipxe.sh
 cargo run --release            # needs NET_BIND_SERVICE or root for :80/:69
 ```
 ### Container health probes
 | Endpoint    | Purpose                                                       |
 |-------------|---------------------------------------------------------------|
 | `/healthz`  | Liveness — HTTP stack alive. Always 200.                      |
 | `/readyz`   | Readiness — 200 only if iPXE binaries bundled + ISO dir OK.   |
 | `/api/status` | Full JSON status: versions, assets, counts, live settings, SMB state. |
 ### Pre-seeding ISOs from a directory
 For CI, pre-baked homelab deployments, or a fresh PVC, the binary has a
 `seed` subcommand that imports every `*.iso` from a host path through the
 same pipeline the web UI uses (introspection + boot-entry generation):
 ```bash
 docker run --rm \
  -v /my/iso-library:/seed:ro \
  -v openpxe-data:/var/lib/openpxe/isos \
  -e OPENPXE_PUBLIC_IP=10.0.0.5 \
-  openpxe:0.4.1 seed --from /seed
+  openpxe:0.5.5 seed --from /seed          # add --dry-run to preview
 # Dry run first to see what would be imported:
 docker run --rm -v /my/iso-library:/seed:ro openpxe:0.4.1 seed --from /seed --dry-run
 ```
-### Environment overrides
+## Remote ISO libraries
-| Var                    | Default                     | Meaning                                |
+Point OpenPXE at a NAS and boot ISOs straight off it — **read on demand, no local copy**,
-|------------------------|-----------------------------|----------------------------------------|
+so a 50-ISO library costs zero disk on the OpenPXE host. All three clients are userspace
-| `OPENPXE_HTTP_PORT`   | `80`                        | Web UI + boot script HTTP port         |
+(no kernel mounts, no `CAP_SYS_ADMIN`); pick whichever your storage speaks.
 | `OPENPXE_TFTP_PORT`   | `69`                        | TFTP port                              |
 | `OPENPXE_DHCP_PORT`   | `67`                        | DHCP server-side port                  |
 | `OPENPXE_DHCP_MODE`   | `proxy`                     | `proxy` or `disabled`                  |
 | `OPENPXE_PUBLIC_IP`   | auto-detect                 | Advertised IP for clients. Startup **fails** if unset and auto-detect returns loopback. |
 | `OPENPXE_ISO_DIR`     | `/var/lib/openpxe/isos`    | Where uploaded ISOs live               |
 | `OPENPXE_WORK_DIR`    | `/var/lib/openpxe/work`    | Scratch + runtime settings             |
 | `OPENPXE_LOG`         | `info,openpxe=debug`       | `tracing` filter                       |
-## What the boot menu looks like on a real client
+| Protocol | Implementation | Auth | HTTP Range¹ |
 |----------|----------------|------|-------------|
 | **NFS** (v3) | Pure-Rust in-process client | Client-IP (server export list) | ✅ |
 | **SFTP** (SSH) | Pure-Rust in-process client (`russh`) | Password **or** SSH key · host-key TOFU | ✅ |
 | **SMB** / CIFS | Userspace `smbclient` | Guest or username/password | — |
 ¹ Range support lets clients seek into a multi-GB ISO without downloading what comes
 before it — needed for kernel/initrd extraction and `httpdisk`-style boots. NFS and SFTP
 expose explicit offsets; the SMB CLI streams sequentially, so SMB-sourced ISOs serve whole-file.
 ## Supported client architectures
 | DHCP option 93 | Architecture | Firmware served |
 |----------------|--------------|-----------------|
 | `0x0000` | Legacy x86 BIOS | `undionly.kpxe` |
 | `0x0006` | IA32 UEFI | `snponly-i386.efi` |
 | `0x0007` / `0x0009` | x86_64 UEFI | `snponly.efi` |
 | `0x000B` | ARM64 UEFI | `snponly-arm64.efi` |
 UEFI firmware that advertises `HTTPClient` (option 60) skips TFTP entirely and is handed an HTTP URL.
 ## The boot menu, on a real client
 ```
-                        OpenPXE - network boot menu
+                        OpenPXE — network boot menu
 ------------------------- Default -------------------------
 Boot from Local HDD
- ----------------------- Installers -----------------------
+ ----------------------- Installers ------------------------
 Linux Installers   >
 Windows Installers >                (only if enabled in Settings)
 -------------------------- Tools --------------------------
- Tools              >                Utilities / Shell /
+ Tools              >    Utilities / OpenPXE Shell / NIC Info / Reboot
                                     NIC Info / Reboot /
                                     Exit and continue BIOS
 ---------------------- Queued Deployment ------------------
 Queued Deployment   (join queue)
 ```
-Linux/Windows submenus show file sizes iVentoy-style:
+Linux/Windows submenus list images iVentoy-style with sizes:
 ```
-                   OpenPXE - Linux Installers
+                   OpenPXE — Linux Installers
 [  4376 MB]  CentOS-7-x86_64-DVD-1810
 [  2002 MB]  Fedora-Workstation-Live-x86_64-38-1.6
 [  4699 MB]  ubuntu-22.04.2-desktop-amd64
 [  2002 MB]  Fedora-Workstation-Live-x86_64-38-1.6
            < Back to main menu
 ```
-iPXE never appears in the UI — the whole hierarchy above is generated from
+The entire hierarchy is generated from what you upload and toggle — iPXE never surfaces.
-ISOs you upload via drag-and-drop in the web UI plus toggles in Settings.
+
 ## Windows deployment
 Enable **Windows ISO support** in Settings, then upload a **stock, unmodified** Microsoft ISO:
 1. On upload, OpenPXE uses `wimlib-imagex` to inject exactly two plain-text files into the
   WinPE image (`winpeshl.ini` + `startnet.cmd`) — no drivers, no certificates.
 2. The container's Samba `smbd` serves the extracted install tree on `:445`.
 3. The client chainloads `wimboot` → patched WinPE → Windows Setup running off the share.
 **Every executable the client runs is stock Microsoft-signed.** OpenPXE never ships
 drivers, never installs certificates into the client trust store, and never recommends
 `bcdedit /set testsigning on`. The SMB approach is adapted (re-implemented, not copied)
 from [Bootimus](https://github.com/garybowers/bootimus) (Apache-2.0). Port `445` must be
 directly reachable from clients; Windows 10/11 client SKUs are the tested target.
 ## Configuration
 All settings have defaults and layer **defaults → TOML (`--config` / `OPENPXE_CONFIG`) →
 `OPENPXE_*` env**. The common knobs:
 | Var | Default | Meaning |
 |-----|---------|---------|
 | `OPENPXE_PUBLIC_IP` | auto-detect | IP advertised to clients. **Startup fails** if unset and auto-detect yields loopback. |
 | `OPENPXE_DHCP_MODE` | `proxy` | `proxy` or `disabled` |
 | `OPENPXE_HTTP_PORT` | `80` | Web UI + boot-script HTTP port |
 | `OPENPXE_TFTP_PORT` | `69` | TFTP port |
 | `OPENPXE_DHCP_PORT` | `67` | DHCP server-side port |
 | `OPENPXE_ISO_DIR` | `/var/lib/openpxe/isos` | Uploaded ISOs |
 | `OPENPXE_WORK_DIR` | `/var/lib/openpxe/work` | Scratch, settings, share + branding state |
 | `OPENPXE_LOG` | `info,openpxe=info` | `tracing` filter |
 | `OPENPXE_ADMIN_USERNAME` | — | First-run only: with `OPENPXE_ADMIN_PASSWORD`, auto-creates the admin so no setup wizard is needed. Ignored once an admin exists. |
 | `OPENPXE_ADMIN_PASSWORD` | — | First-run admin password. Use `OPENPXE_ADMIN_PASSWORD_FILE` to read it from a file (Docker/K8s secret). |
 ## OpenShift
 ```bash
 oc apply -f deploy/openshift/
 oc -n openpxe get all
 oc -n openpxe get route openpxe -o jsonpath='{.spec.host}'
 ```
-### Why a custom SCC?
+The bundled `openpxe-scc` grants exactly `hostNetwork` (CNI overlays don't deliver L2
 broadcast into pod netns) and `NET_BIND_SERVICE` (to bind ports <1024) — nothing else.
 No raw sockets, no privileged mode. The Route covers `80/TCP`; PXE clients reach UDP
 67/69/4011 on the node's host IP directly.
-The default `restricted-v2` blocks `hostNetwork` and all capabilities. PXE
+## Health & observability
 cannot work without host network (CNI overlays don't deliver L2 broadcast
 into pod netns), and we need `NET_BIND_SERVICE` to bind <1024. The custom
 `openpxe-scc` grants exactly those two and nothing else. No raw sockets,
 no privileged mode — proxy-mode DHCP sidesteps the usual requirements.
-### What's on host ports
+| Endpoint | Purpose |
-
+|----------|---------|
-| Port     | Proto | Purpose                         |
+| `/healthz` | Liveness — always 200 if the HTTP stack is up. |
-|----------|-------|---------------------------------|
+| `/readyz` | Readiness — 200 only once iPXE firmware is bundled and the ISO dir is reachable. |
-| 67       | UDP   | DHCP server (proxy replies)     |
+| `/api/status` | Full JSON: version, assets, counts, live settings, share + SMB state. |
-| 69       | UDP   | TFTP                            |
+| `/metrics` | Prometheus text format — DHCP replies by arch, TFTP/HTTP counts, queue gauges, uptime. |
 | 4011     | UDP   | PXE Boot Server discovery       |
 | 80       | TCP   | Web UI + HTTP boot assets       |
 The OpenShift Route only covers 80/TCP. Clients on the PXE network talk to
 the node's host IP directly for UDP.
 ## Windows support
 Enabled by toggling **Windows ISO support** under Settings. The flow:
 1. Upload a stock Microsoft Windows install ISO (vanilla, no pre-processing).
 2. On upload, OpenPXE extracts the ISO and uses `wimlib-imagex` to rewrite
   image index 2 (WinPE) of `sources/boot.wim`. It injects exactly two
   plain-text files:
   - `Windows/System32/winpeshl.ini` — tells WinPE to run `startnet.cmd`.
   - `Windows/System32/startnet.cmd` — runs `wpeinit`, waits for the SMB
     host to be reachable, `net use Z: \\<server>\<share> /user:guest`,
     then `Z:\setup.exe`.
 3. The container's Samba `smbd` serves the extracted install tree on :445.
 4. The client gets chainloaded into wimboot → patched WinPE → Windows Setup
   running off the SMB share. **Every binary the client executes is stock
   Microsoft-signed.**
 ### What we never do
 - Ship drivers — signed, test-signed, or otherwise — that load on the client.
 - Install certificates into the target's trust store or WinPE boot policy.
 - Recommend `bcdedit /set testsigning on` or any equivalent signing-policy
  weakening.
 ### Credit & limitations
 The SMB-based approach is adapted from [Bootimus](https://github.com/garybowers/bootimus)
 (Apache-2.0). Re-implemented in Rust; no code was copied verbatim. Known
 operational constraints inherited from the design:
 - **Port 445 must be directly reachable from PXE clients.** `net use`
  ignores alternate ports. In OpenShift this means `hostPort: 445` on the
  deployment; on a host that already runs SMB it will collide.
 - Windows 10/11 client SKUs are the tested target. Server SKUs untested.
 - Hardware with NICs/storage controllers missing from WinPE's bundled
  drivers will need a driver-pack injection step (not yet implemented).
 ## Queued Deployment
 The coordinated launch flow, end to end:
 1. A client boots and picks **Queued Deployment** in the PXE menu (or falls
   through on timeout with the default `timeout_action`).
 2. The client joins the queue, gets a numbered queue position, and enters a
   long-poll loop (25s per request, auto-renewed).
 3. In the web UI's **Queued Deployment** tab, the operator sees each waiting
   client with its MAC, IP, arch, and position.
 4. The operator selects an image and clicks **Launch for all waiting**.
   The server broadcasts the assignment to every queued client via a
   `tokio::sync::Notify`; each client's next poll returns the boot script
   for the chosen image.
 5. Every client chains the same image at effectively the same moment. The
   queue stays visible until the operator releases entries, which keeps a
   useful audit trail during hardware testing.
 No user-facing iPXE anywhere in this flow. The client only ever runs
 scripts we generate; the operator only interacts with the web UI.
 ## Architecture
-See [`docs/architecture.md`](docs/architecture.md) for the protocol stack,
+Workspace of focused crates — `core`, `dhcp-proxy`, `tftp`, `http-api`, `iso-store`,
-crate layout, and the full decision log.
+`ipxe-assets`, `webui`, and the `openpxe` binary. See
 [`docs/architecture.md`](docs/architecture.md) for the protocol stack, crate layout, and
 the full decision log.
-## Licence
+## License
-MIT OR Apache-2.0.
+Dual-licensed under **MIT OR Apache-2.0** — use whichever fits your project.
@@ -13,6 +13,7 @@ workspace = true
 serde.workspace = true
 serde_json.workspace = true
 toml.workspace = true
 figment.workspace = true
 thiserror.workspace = true
 anyhow.workspace = true
 tracing.workspace = true
@@ -26,18 +27,19 @@ tokio = { workspace = true, features = ["sync", "rt", "macros", "time"] }
 bcrypt.workspace = true
 # v0.5.1: pure-Rust SAML 2.0 SP. bergshamra = XML-DSig verify + exclusive
-# c14n (no OpenSSL/C). roxmltree/quick-xml parse + build SAML XML;
+# c14n (no OpenSSL/C), plus IdP signing-cert extraction from metadata.
-# x509-parser pulls the IdP signing cert out of metadata; flate2+base64
+# roxmltree parses the SAML/metadata XML; flate2+base64 encode the
-# encode the HTTP-Redirect binding's SAMLRequest.
+# HTTP-Redirect binding's SAMLRequest.
 bergshamra.workspace = true
 roxmltree.workspace = true
 quick-xml.workspace = true
 x509-parser.workspace = true
 flate2.workspace = true
 base64.workspace = true
 [dev-dependencies]
 tempfile = "3.12"
 # v0.5.4: figment's `Jail` (hermetic env/file sandbox) for the config
 # loader tests lives behind the `test` feature.
 figment = { workspace = true, features = ["test"] }
 # v0.5.1: generate a throwaway self-signed signing cert/key so SAML
 # verification tests can produce genuinely signed SAMLResponses.
 rcgen = "0.13"
@@ -0,0 +1,158 @@
 //! Operator API key — a single persisted secret that authenticates
 //! programmatic `/api/*` callers (Postman, scripts, CI) via the
 //! `x-api-key` header, as an alternative to the browser session cookie.
 //!
 //! Generated on first load and persisted to `<work_dir>/api_key.json` so
 //! it survives restarts — an operator pastes it into their client once.
 //! Regenerable from Settings → Advanced; the previous key stops working
 //! the moment a new one is minted. Grants the same access as a logged-in
 //! operator (the middleware treats a valid key exactly like a session).
 use parking_lot::RwLock;
 use serde::{Deserialize, Serialize};
 use std::path::PathBuf;
 use std::sync::Arc;
 use uuid::Uuid;
 #[derive(Debug, Clone, Serialize, Deserialize)]
 struct ApiKeyFile {
    key: String,
 }
 /// Persisted operator API key. Cheap to clone (Arc-shared); contention is
 /// nil (read on every authenticated request, written only on regenerate).
 #[derive(Debug, Clone)]
 pub struct ApiKeyStore {
    path: Arc<PathBuf>,
    inner: Arc<RwLock<String>>,
 }
 impl ApiKeyStore {
    /// Load the stored key, minting + persisting a fresh one on first run
    /// (or when the file is missing / corrupt / empty).
    #[must_use]
    pub fn load_or_init(work_dir: &std::path::Path) -> Self {
        let path = work_dir.join("api_key.json");
        let key = match std::fs::read_to_string(&path) {
            Ok(text) => serde_json::from_str::<ApiKeyFile>(&text)
                .map(|f| f.key)
                .ok()
                .filter(|k| !k.is_empty())
                .unwrap_or_else(generate_key),
            Err(_) => generate_key(),
        };
        let store = Self {
            path: Arc::new(path),
            inner: Arc::new(RwLock::new(key)),
        };
        // Land a first-run (or repaired) key on disk immediately so it's
        // stable across the very next restart.
        store.persist();
        store
    }
    #[must_use]
    pub fn current(&self) -> String {
        self.inner.read().clone()
    }
    /// Constant-time comparison against the stored key. An empty candidate
    /// never matches, so a blank/absent header can't authenticate.
    #[must_use]
    pub fn verify(&self, candidate: &str) -> bool {
        if candidate.is_empty() {
            return false;
        }
        ct_eq(self.inner.read().as_bytes(), candidate.as_bytes())
    }
    /// Mint a fresh key, persist it, and return it. The previous key is
    /// invalid the instant this returns.
    #[must_use]
    pub fn regenerate(&self) -> String {
        let key = generate_key();
        self.inner.write().clone_from(&key);
        self.persist();
        tracing::info!(target: "openpxe::auth", "operator API key regenerated");
        key
    }
    fn persist(&self) {
        let body = match serde_json::to_vec_pretty(&ApiKeyFile {
            key: self.current(),
        }) {
            Ok(b) => b,
            Err(e) => {
                tracing::warn!(target: "openpxe::auth", "serialize api_key.json: {e}");
                return;
            }
        };
        if let Some(parent) = self.path.parent() {
            let _ = std::fs::create_dir_all(parent);
        }
        let tmp = self.path.with_extension("json.tmp");
        if let Err(e) = std::fs::write(&tmp, body) {
            tracing::warn!(target: "openpxe::auth", "write api_key.json tmp: {e}");
            return;
        }
        if let Err(e) = std::fs::rename(&tmp, self.path.as_path()) {
            tracing::warn!(target: "openpxe::auth", "rename api_key.json: {e}");
        }
    }
 }
 /// 128 random bits as 32 lowercase hex chars — unambiguous to copy-paste
 /// into an `x-api-key` header. UUID v4 is already our CSPRNG-backed source
 /// for session ids, so no new dependency.
 fn generate_key() -> String {
    Uuid::new_v4().simple().to_string()
 }
 /// Length-checked constant-time byte compare — keeps key verification from
 /// leaking the matched-prefix length via timing. A 128-bit random secret
 /// isn't practically timing-attackable over a network, but the check is
 /// four lines, so we keep it.
 fn ct_eq(a: &[u8], b: &[u8]) -> bool {
    if a.len() != b.len() {
        return false;
    }
    let mut diff = 0u8;
    for (x, y) in a.iter().zip(b.iter()) {
        diff |= x ^ y;
    }
    diff == 0
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    use tempfile::tempdir;
    #[test]
    fn generates_persists_and_reloads() {
        let dir = tempdir().unwrap();
        let s = ApiKeyStore::load_or_init(dir.path());
        let k = s.current();
        assert_eq!(k.len(), 32, "32 hex chars = 128 bits");
        assert!(s.verify(&k));
        assert!(!s.verify("wrong"));
        assert!(!s.verify(""), "blank header must not authenticate");
        // Reload from disk → same key (survives restart).
        let s2 = ApiKeyStore::load_or_init(dir.path());
        assert_eq!(s2.current(), k);
    }
    #[test]
    fn regenerate_invalidates_old() {
        let dir = tempdir().unwrap();
        let s = ApiKeyStore::load_or_init(dir.path());
        let old = s.current();
        let new = s.regenerate();
        assert_ne!(old, new);
        assert!(s.verify(&new));
        assert!(!s.verify(&old), "old key must stop working");
        // Persisted: a reload sees the new key.
        let s2 = ApiKeyStore::load_or_init(dir.path());
        assert_eq!(s2.current(), new);
    }
 }
@@ -23,6 +23,36 @@ pub enum ClientArch {
    Unknown(u16),
 }
 /// Which boot binary family to advertise to a client (v0.6.1, extended
 /// v0.7.0).
 ///
 /// OpenPXE serves [`DriverMode::Firmware`] first (the firmware's own NIC
 /// stack, via `snponly`/`undionly`) and escalates a specific MAC
 /// automatically when a boot never completes its handoff:
 /// `Firmware → Builtin → Shim`. There is no operator toggle — the DHCP
 /// proxy decides per client.
 ///
 /// The `Shim` rung (v0.7.0) covers Secure Boot: firmware with SB enabled
 /// downloads our unsigned iPXE fine but refuses to *execute* it, which
 /// looks exactly like a failed chainload. After both iPXE builds go
 /// unconfirmed, the client is offered the Microsoft-signed shim, which
 /// loads the signed GRUB, which fetches a server-rendered menu — a fully
 /// signed chain that boots signed distro kernels with SB still on.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
 pub enum DriverMode {
    /// Reuse the firmware UNDI/SNP NIC stack (`snponly.efi`, `undionly.kpxe`).
    /// Default, smallest, most reliable for chainloading.
    #[default]
    Firmware,
    /// iPXE's own bundled NIC drivers (`ipxe.efi`, `ipxe.pxe`). Fallback for
    /// hardware whose firmware NIC stack is missing or buggy.
    Builtin,
    /// Microsoft-signed shim + GRUB chain (`shimx64.efi`). Final fallback
    /// for Secure-Boot-enabled UEFI clients that refuse unsigned iPXE.
    Shim,
 }
 impl ClientArch {
    #[must_use]
    pub fn from_option_93(value: u16) -> Self {
@@ -39,21 +69,73 @@ impl ClientArch {
    /// Default iPXE binary filename to return via TFTP for this architecture.
    /// Uses `snponly` variants which reuse the firmware's UNDI/SNP network
    /// stack — smaller binaries and broader hardware compatibility than the
-    /// all-drivers-included `ipxe.efi`.
+    /// all-drivers-included `ipxe.efi`. Equivalent to
    /// [`Self::ipxe_bootfile_mode`] with [`DriverMode::Firmware`]; kept as a
    /// convenience for the common firmware-net path.
    #[must_use]
    pub fn ipxe_bootfile(self) -> Option<&'static str> {
-        Some(match self {
+        self.ipxe_bootfile_mode(DriverMode::Firmware)
-            Self::LegacyX86 => "undionly.kpxe",
+    }
-            Self::Ia32Uefi => "snponly-i386.efi",
+
-            Self::X64Uefi => "snponly.efi",
+    /// iPXE binary filename for this architecture under a given network
-            // ARM32 UEFI: upstream boot.ipxe.org does not publish a prebuilt
+    /// [`DriverMode`].
-            // snponly variant for this arch. We return None so the DHCP
+    ///
-            // proxy declines rather than advertising a file we can't serve.
+    /// * [`DriverMode::Firmware`] — the `snponly`/`undionly` builds that reuse
-            Self::Arm32Uefi | Self::Unknown(_) => return None,
+    ///   the firmware's UNDI/SNP NIC stack. Smallest, and the most reliable
-            Self::Arm64Uefi => "snponly-arm64.efi",
+    ///   choice for chainloading because the firmware just proved its network
    ///   works by downloading the NBP. This is the default first attempt.
    /// * [`DriverMode::Builtin`] — the all-drivers `ipxe.efi`/`ipxe.pxe`
    ///   builds that carry iPXE's *own* NIC drivers. The automatic fallback
    ///   for clients whose firmware NIC stack is missing or buggy (v0.6.1):
    ///   the DHCP proxy escalates a MAC to this mode when a firmware-net boot
    ///   never completes the iPXE handoff. iPXE still includes the `snp`
    ///   driver here too, so it degrades gracefully.
    #[must_use]
    pub fn ipxe_bootfile_mode(self, mode: DriverMode) -> Option<&'static str> {
        Some(match (self, mode) {
            // Legacy x86 BIOS: UNDI (firmware) vs full native-driver build.
            (Self::LegacyX86, DriverMode::Firmware) => "undionly.kpxe",
            (Self::LegacyX86, DriverMode::Builtin) => "ipxe.pxe",
            // IA32 UEFI.
            (Self::Ia32Uefi, DriverMode::Firmware) => "snponly-i386.efi",
            (Self::Ia32Uefi, DriverMode::Builtin) => "ipxe-i386.efi",
            // No signed Shim chain for BIOS (no Secure Boot there) or
            // IA32 UEFI (Fedora publishes no 32-bit shim; SB-on IA32
            // clients are vanishingly rare). Same outcome as the
            // no-binary arches below, listed separately for the comment.
            #[allow(clippy::match_same_arms)]
            (Self::LegacyX86 | Self::Ia32Uefi, DriverMode::Shim) => return None,
            // x86_64 UEFI — the overwhelmingly common modern client.
            (Self::X64Uefi, DriverMode::Firmware) => "snponly.efi",
            (Self::X64Uefi, DriverMode::Builtin) => "ipxe.efi",
            (Self::X64Uefi, DriverMode::Shim) => "shimx64.efi",
            // ARM64 UEFI.
            (Self::Arm64Uefi, DriverMode::Firmware) => "snponly-arm64.efi",
            (Self::Arm64Uefi, DriverMode::Builtin) => "ipxe-arm64.efi",
            (Self::Arm64Uefi, DriverMode::Shim) => "shimaa64.efi",
            // ARM32 UEFI: upstream boot.ipxe.org publishes no prebuilt binary
            // for this arch in any mode. Unknown arches likewise. Return
            // None so the DHCP proxy declines rather than advertising a file
            // we can't serve.
            (Self::Arm32Uefi | Self::Unknown(_), _) => return None,
        })
    }
    /// Like [`Self::ipxe_bootfile_mode`], but walks back down the
    /// escalation ladder (`Shim → Builtin → Firmware`) when the requested
    /// mode has no binary for this arch — e.g. a BIOS client whose
    /// escalation state reached `Shim` (BIOS has no Secure Boot) falls
    /// back to the all-drivers build instead of being ignored.
    #[must_use]
    pub fn bootfile_with_fallback(self, mode: DriverMode) -> Option<&'static str> {
        let ladder: &[DriverMode] = match mode {
            DriverMode::Shim => &[DriverMode::Shim, DriverMode::Builtin, DriverMode::Firmware],
            DriverMode::Builtin => &[DriverMode::Builtin, DriverMode::Firmware],
            DriverMode::Firmware => &[DriverMode::Firmware],
        };
        ladder.iter().find_map(|m| self.ipxe_bootfile_mode(*m))
    }
    #[must_use]
    pub fn as_str(self) -> &'static str {
        match self {
@@ -133,6 +215,103 @@ mod tests {
        assert_eq!(ClientArch::Unknown(0xFFFF).ipxe_bootfile(), None);
    }
    #[test]
    fn bootfile_default_is_firmware_mode() {
        // The convenience method must equal the explicit Firmware mode.
        for a in [
            ClientArch::LegacyX86,
            ClientArch::Ia32Uefi,
            ClientArch::X64Uefi,
            ClientArch::Arm64Uefi,
            ClientArch::Arm32Uefi,
            ClientArch::Unknown(0x99),
        ] {
            assert_eq!(
                a.ipxe_bootfile(),
                a.ipxe_bootfile_mode(DriverMode::Firmware)
            );
        }
    }
    #[test]
    fn builtin_mode_maps_to_all_drivers_binaries() {
        assert_eq!(
            ClientArch::LegacyX86.ipxe_bootfile_mode(DriverMode::Builtin),
            Some("ipxe.pxe")
        );
        assert_eq!(
            ClientArch::X64Uefi.ipxe_bootfile_mode(DriverMode::Builtin),
            Some("ipxe.efi")
        );
        assert_eq!(
            ClientArch::Ia32Uefi.ipxe_bootfile_mode(DriverMode::Builtin),
            Some("ipxe-i386.efi")
        );
        assert_eq!(
            ClientArch::Arm64Uefi.ipxe_bootfile_mode(DriverMode::Builtin),
            Some("ipxe-arm64.efi")
        );
        // No binary for ARM32 / unknown in either mode.
        assert_eq!(
            ClientArch::Arm32Uefi.ipxe_bootfile_mode(DriverMode::Builtin),
            None
        );
        assert_eq!(
            ClientArch::Unknown(0x99).ipxe_bootfile_mode(DriverMode::Builtin),
            None
        );
    }
    #[test]
    fn driver_mode_default_is_firmware() {
        assert_eq!(DriverMode::default(), DriverMode::Firmware);
    }
    #[test]
    fn shim_mode_maps_to_signed_chain_on_uefi_only() {
        assert_eq!(
            ClientArch::X64Uefi.ipxe_bootfile_mode(DriverMode::Shim),
            Some("shimx64.efi")
        );
        assert_eq!(
            ClientArch::Arm64Uefi.ipxe_bootfile_mode(DriverMode::Shim),
            Some("shimaa64.efi")
        );
        // No Secure Boot on BIOS, no published 32-bit shim.
        assert_eq!(
            ClientArch::LegacyX86.ipxe_bootfile_mode(DriverMode::Shim),
            None
        );
        assert_eq!(
            ClientArch::Ia32Uefi.ipxe_bootfile_mode(DriverMode::Shim),
            None
        );
    }
    #[test]
    fn fallback_walks_down_the_ladder() {
        // BIOS escalated to Shim → falls back to the all-drivers build.
        assert_eq!(
            ClientArch::LegacyX86.bootfile_with_fallback(DriverMode::Shim),
            Some("ipxe.pxe")
        );
        // UEFI x64 at Shim gets the real shim.
        assert_eq!(
            ClientArch::X64Uefi.bootfile_with_fallback(DriverMode::Shim),
            Some("shimx64.efi")
        );
        // Plain modes are unchanged.
        assert_eq!(
            ClientArch::X64Uefi.bootfile_with_fallback(DriverMode::Firmware),
            Some("snponly.efi")
        );
        // Arches with nothing stay None.
        assert_eq!(
            ClientArch::Arm32Uefi.bootfile_with_fallback(DriverMode::Shim),
            None
        );
    }
    #[test]
    fn firmware_class_detects_ipxe_over_pxeclient() {
        let c = FirmwareClass::classify(Some(b"PXEClient:Arch:00007"), Some(b"iPXE"));
@@ -125,9 +125,7 @@ impl AdminStore {
        {
            let mut g = self.inner.write();
            if g.admin.is_some() {
-                return Err(Error::Invalid(
+                return Err(Error::Invalid("admin account already configured".into()));
                    "admin account already configured".into(),
                ));
            }
            g.admin = Some(admin.clone());
        }
@@ -346,7 +344,7 @@ mod tests {
        assert!(s.bootstrap("", "hunter2hunter2").is_err());
        assert!(s.bootstrap("ad:min", "hunter2hunter2").is_err()); // ':' reserved
        assert!(s.bootstrap("admin", "short").is_err()); // <8 chars
-        // 65-char username is too long.
+                                                         // 65-char username is too long.
        let long = "a".repeat(65);
        assert!(s.bootstrap(&long, "hunter2hunter2").is_err());
    }
@@ -0,0 +1,369 @@
 //! Label-based boot rules + boot-decision webhook (v0.7.0).
 //!
 //! Generalizes [`crate::host_bindings::HostBindings`] (exact-MAC pins)
 //! into ordered, first-match-wins rules over what the boot chain knows
 //! about a client — MAC prefix (OUI or longer) and firmware
 //! architecture — plus an optional outbound webhook so external
 //! automation (CMDB, netbox, a shell script) can decide the boot target
 //! per machine, pixiecore-style.
 //!
 //! Decision order in the boot script handler, most-specific first:
 //!   1. exact per-MAC host binding (operator pin)
 //!   2. first matching enabled rule here
 //!   3. webhook, if configured (fail-open: timeout/error → menu)
 //!   4. interactive menu
 //!
 //! With no rules and no webhook configured the behavior is byte-for-byte
 //! what it was before this feature existed — no toggles to flip.
 //!
 //! Persisted to `<work_dir>/boot_rules.json` with the same "in-memory
 //! authoritative, disk is a crash cache, corruption falls back to empty"
 //! policy as the host bindings — a bad rules file must never block PXE.
 use crate::host_bindings::normalize_mac;
 use parking_lot::RwLock;
 use serde::{Deserialize, Serialize};
 use std::path::PathBuf;
 use std::sync::Arc;
 /// One ordered rule. All present (non-empty) selectors must match —
 /// empty selector fields match anything, so a rule with only `arch` set
 /// applies to every client of that architecture.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct BootRule {
    /// Case-insensitive MAC prefix, `:`-separated (e.g. `dc:a6:32` for
    /// an OUI, or longer). Empty = any MAC.
    #[serde(default)]
    pub mac_prefix: String,
    /// Client architecture selector — matches `ClientArch::as_str()`
    /// (`bios`, `uefi-x64`, `uefi-ia32`, `uefi-arm64`). Empty = any.
    #[serde(default)]
    pub arch: String,
    /// Boot entry id (a `BootEntry::id`) or reserved menu name
    /// (`_local`, `_queue`, …) to chain to when this rule matches.
    /// May be empty for a rule that only pins a driver mode.
    #[serde(default)]
    pub target: String,
    /// v0.7.1: optional first-boot binary pin — `""` (auto: let the
    /// escalation ladder decide), `"firmware"`, `"builtin"`, or
    /// `"shim"`. Lets an operator declare "this rack is all Secure
    /// Boot → serve the signed chain immediately", skipping the
    /// learn-by-failing walk entirely for known fleets.
    #[serde(default)]
    pub driver_mode: String,
    /// Rules can be parked without deleting them.
    #[serde(default = "default_true")]
    pub enabled: bool,
    /// Operator note shown in the UI (`"all Pi 4s"`, `"QA rack"`).
    #[serde(default)]
    pub note: String,
 }
 fn default_true() -> bool {
    true
 }
 /// The whole persisted config: ordered rules + optional webhook.
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(default)]
 pub struct BootRulesConfig {
    pub rules: Vec<BootRule>,
    /// Optional boot-decision webhook URL. When set, unmatched boots GET
    /// `<url>?mac=<mac>&arch=<arch>` and a `200 {"target": "<id>"}`
    /// reply chains to that target. Anything else (404, timeout, bad
    /// JSON) falls through to the menu. Empty = disabled.
    pub webhook_url: String,
 }
 /// Store for the rules config. Cheap to clone; locks held briefly.
 #[derive(Debug, Clone)]
 pub struct BootRulesStore {
    path: Arc<PathBuf>,
    inner: Arc<RwLock<BootRulesConfig>>,
 }
 impl BootRulesStore {
    /// Load from `work_dir/boot_rules.json`, or start empty if absent /
    /// unreadable.
    #[must_use]
    pub fn load_or_default(work_dir: &std::path::Path) -> Self {
        let path = work_dir.join("boot_rules.json");
        let inner = match std::fs::read_to_string(&path) {
            Ok(text) => match serde_json::from_str::<BootRulesConfig>(&text) {
                Ok(cfg) => cfg,
                Err(e) => {
                    tracing::warn!(
                        target: "openpxe::boot_rules",
                        "boot_rules.json present but unreadable ({e}); starting empty"
                    );
                    BootRulesConfig::default()
                }
            },
            Err(_) => BootRulesConfig::default(),
        };
        Self {
            path: Arc::new(path),
            inner: Arc::new(RwLock::new(inner)),
        }
    }
    /// Current config snapshot (for the API / UI).
    #[must_use]
    pub fn snapshot(&self) -> BootRulesConfig {
        self.inner.read().clone()
    }
    /// Replace the whole config (the UI saves the full table at once —
    /// rules are ordered, so partial updates would be ambiguous).
    pub fn replace(&self, mut cfg: BootRulesConfig) {
        for r in &mut cfg.rules {
            r.mac_prefix = normalize_mac(&r.mac_prefix);
            r.arch = r.arch.trim().to_ascii_lowercase();
            r.target = r.target.trim().to_string();
            r.driver_mode = r.driver_mode.trim().to_ascii_lowercase();
            r.note = r.note.trim().to_string();
        }
        cfg.webhook_url = cfg.webhook_url.trim().to_string();
        *self.inner.write() = cfg;
        self.persist();
    }
    /// Webhook URL, when configured.
    #[must_use]
    pub fn webhook_url(&self) -> Option<String> {
        let g = self.inner.read();
        if g.webhook_url.is_empty() {
            None
        } else {
            Some(g.webhook_url.clone())
        }
    }
    /// First enabled rule matching `(mac, arch)`, in stored order.
    /// `arch` is the `ClientArch::as_str()` form when the boot chain
    /// passed one along, `None` otherwise (older chains).
    #[must_use]
    pub fn match_target(&self, mac: &str, arch: Option<&str>) -> Option<String> {
        self.first_match(mac, arch, |r| {
            (!r.target.is_empty()).then(|| r.target.clone())
        })
    }
    /// v0.7.1: first enabled rule that pins a driver mode for `(mac,
    /// arch)`. Consulted by the DHCP proxy *before* the automatic
    /// escalation ladder — an operator who knows a rack is all Secure
    /// Boot pins it to `shim` and those machines never walk the ladder.
    /// Unknown mode strings are ignored (forward compatibility).
    #[must_use]
    pub fn driver_mode_hint(&self, mac: &str, arch: Option<&str>) -> Option<crate::DriverMode> {
        self.first_match(mac, arch, |r| match r.driver_mode.as_str() {
            "firmware" => Some(crate::DriverMode::Firmware),
            "builtin" => Some(crate::DriverMode::Builtin),
            "shim" => Some(crate::DriverMode::Shim),
            _ => None,
        })
    }
    /// Shared rule-matching walk: returns the first `extract` result from
    /// an enabled rule whose selectors match. Rules that match but yield
    /// `None` from `extract` (e.g. no target set, or no driver mode set)
    /// don't stop the walk — target rules and mode-pin rules coexist.
    fn first_match<T>(
        &self,
        mac: &str,
        arch: Option<&str>,
        extract: impl Fn(&BootRule) -> Option<T>,
    ) -> Option<T> {
        let mac = normalize_mac(mac);
        let g = self.inner.read();
        for r in &g.rules {
            if !r.enabled {
                continue;
            }
            if !r.mac_prefix.is_empty() && !mac.starts_with(r.mac_prefix.as_str()) {
                continue;
            }
            if !r.arch.is_empty() {
                // An arch-selective rule can only match when the chain
                // told us the client's arch.
                match arch {
                    Some(a) if a.eq_ignore_ascii_case(&r.arch) => {}
                    _ => continue,
                }
            }
            if let Some(v) = extract(r) {
                return Some(v);
            }
        }
        None
    }
    fn persist(&self) {
        let snap = self.inner.read().clone();
        let body = match serde_json::to_vec_pretty(&snap) {
            Ok(b) => b,
            Err(e) => {
                tracing::warn!(target: "openpxe::boot_rules", "serialize boot_rules.json: {e}");
                return;
            }
        };
        if let Some(parent) = self.path.parent() {
            let _ = std::fs::create_dir_all(parent);
        }
        let tmp = self.path.with_extension("json.tmp");
        if let Err(e) = std::fs::write(&tmp, body) {
            tracing::warn!(target: "openpxe::boot_rules", "write boot_rules.json tmp: {e}");
            return;
        }
        if let Err(e) = std::fs::rename(&tmp, self.path.as_path()) {
            tracing::warn!(target: "openpxe::boot_rules", "rename boot_rules.json: {e}");
        }
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    use tempfile::tempdir;
    fn rule(mac_prefix: &str, arch: &str, target: &str) -> BootRule {
        BootRule {
            mac_prefix: mac_prefix.into(),
            arch: arch.into(),
            target: target.into(),
            driver_mode: String::new(),
            enabled: true,
            note: String::new(),
        }
    }
    #[test]
    fn driver_mode_hint_pins_known_modes_and_ignores_unknown() {
        let dir = tempdir().unwrap();
        let s = BootRulesStore::load_or_default(dir.path());
        let mut sb_rack = rule("aa:bb:cc", "", "");
        sb_rack.driver_mode = "SHIM".into(); // normalized on replace
        let mut weird = rule("11:22:33", "", "");
        weird.driver_mode = "quantum".into(); // unknown → ignored
        s.replace(BootRulesConfig {
            rules: vec![sb_rack, weird],
            webhook_url: String::new(),
        });
        assert_eq!(
            s.driver_mode_hint("aa:bb:cc:00:00:01", None),
            Some(crate::DriverMode::Shim)
        );
        assert_eq!(s.driver_mode_hint("11:22:33:00:00:01", None), None);
        assert_eq!(s.driver_mode_hint("99:99:99:00:00:01", None), None);
    }
    #[test]
    fn mode_pin_rule_does_not_shadow_later_target_rule() {
        // A mode-only rule and a target rule can both apply to the same
        // client: the mode pin must not consume the target walk.
        let dir = tempdir().unwrap();
        let s = BootRulesStore::load_or_default(dir.path());
        let mut pin = rule("aa:bb", "", "");
        pin.driver_mode = "builtin".into();
        s.replace(BootRulesConfig {
            rules: vec![pin, rule("aa:bb", "", "rack-image")],
            webhook_url: String::new(),
        });
        assert_eq!(
            s.driver_mode_hint("aa:bb:00:00:00:01", None),
            Some(crate::DriverMode::Builtin)
        );
        assert_eq!(
            s.match_target("aa:bb:00:00:00:01", None).as_deref(),
            Some("rack-image")
        );
    }
    #[test]
    fn empty_config_matches_nothing() {
        let dir = tempdir().unwrap();
        let s = BootRulesStore::load_or_default(dir.path());
        assert!(s
            .match_target("aa:bb:cc:dd:ee:ff", Some("uefi-x64"))
            .is_none());
        assert!(s.webhook_url().is_none());
    }
    #[test]
    fn first_match_wins_in_order() {
        let dir = tempdir().unwrap();
        let s = BootRulesStore::load_or_default(dir.path());
        s.replace(BootRulesConfig {
            rules: vec![
                rule("aa:bb:cc", "", "rack-image"),
                rule("", "", "catch-all"),
            ],
            webhook_url: String::new(),
        });
        assert_eq!(
            s.match_target("AA-BB-CC-00-00-01", None).as_deref(),
            Some("rack-image")
        );
        assert_eq!(
            s.match_target("11:22:33:44:55:66", None).as_deref(),
            Some("catch-all")
        );
    }
    #[test]
    fn arch_selector_requires_known_arch() {
        let dir = tempdir().unwrap();
        let s = BootRulesStore::load_or_default(dir.path());
        s.replace(BootRulesConfig {
            rules: vec![rule("", "uefi-arm64", "arm-image")],
            webhook_url: String::new(),
        });
        assert_eq!(
            s.match_target("aa:bb:cc:00:00:01", Some("uefi-arm64"))
                .as_deref(),
            Some("arm-image")
        );
        // Wrong arch, or arch unknown to the chain → no match.
        assert!(s.match_target("aa:bb:cc:00:00:01", Some("bios")).is_none());
        assert!(s.match_target("aa:bb:cc:00:00:01", None).is_none());
    }
    #[test]
    fn disabled_rules_are_skipped() {
        let dir = tempdir().unwrap();
        let s = BootRulesStore::load_or_default(dir.path());
        let mut r = rule("", "", "x");
        r.enabled = false;
        s.replace(BootRulesConfig {
            rules: vec![r],
            webhook_url: String::new(),
        });
        assert!(s.match_target("aa:bb:cc:00:00:01", None).is_none());
    }
    #[test]
    fn config_round_trips_to_disk() {
        let dir = tempdir().unwrap();
        let s = BootRulesStore::load_or_default(dir.path());
        s.replace(BootRulesConfig {
            rules: vec![rule("DC-A6-32", "", "pi-image")],
            webhook_url: "  http://automation/boot  ".into(),
        });
        drop(s);
        let s2 = BootRulesStore::load_or_default(dir.path());
        // Prefix was normalized on replace, webhook trimmed.
        assert_eq!(
            s2.match_target("dc:a6:32:01:02:03", None).as_deref(),
            Some("pi-image")
        );
        assert_eq!(s2.webhook_url().as_deref(), Some("http://automation/boot"));
    }
    #[test]
    fn corrupt_file_falls_back_to_empty() {
        let dir = tempdir().unwrap();
        std::fs::write(dir.path().join("boot_rules.json"), b"{nope").unwrap();
        let s = BootRulesStore::load_or_default(dir.path());
        assert!(s.snapshot().rules.is_empty());
    }
 }
@@ -0,0 +1,138 @@
 //! One-time(ish) access tokens for unattended answer files (v0.7.0).
 //!
 //! Why: answer files routinely embed credentials (local admin passwords,
 //! domain-join accounts, root hashes). Serving them to anyone who can
 //! GET `/unattended/<id>` is exactly the exposure that got WDS
 //! hands-free deployment disabled upstream (CVE-2026-0386 hardening
 //! guidance). OpenPXE generates every answer-file URL it injects into a
 //! boot chain, so it can scope each URL to the boot that requested it:
 //! when a boot script is rendered, a short-lived token is minted and
 //! appended; the serving endpoint requires it (or a logged-in operator
 //! session, so browser testing keeps working).
 //!
 //! Deliberately multi-use within the TTL rather than strictly one-shot:
 //! real installers fetch the same file more than once (initramfs +
 //! installer stage, cloud-init retries), and the token's job is to stop
 //! *unrelated* hosts from harvesting credentials, not to count fetches.
 //!
 //! In-memory only. A server restart invalidates outstanding tokens —
 //! acceptable because a restart also interrupts the ISO streaming an
 //! in-flight install depends on, and the next boot mints fresh ones.
 use parking_lot::Mutex;
 use std::collections::HashMap;
 use std::time::{Duration, Instant};
 use uuid::Uuid;
 /// Long enough to cover a slow OS install end-to-end (the answer file is
 /// fetched early, but cloud-init can re-read late), short enough that a
 /// leaked URL goes stale the same afternoon.
 const TOKEN_TTL: Duration = Duration::from_hours(4);
 /// Hard cap on outstanding tokens; past it the oldest is evicted. Tokens
 /// are minted once per boot-script render, so this only matters under
 /// abuse, and serving must never become a memory-growth vector.
 const MAX_TOKENS: usize = 4096;
 #[derive(Debug, Clone)]
 struct Grant {
    file_id: String,
    issued: Instant,
 }
 /// In-memory token table. Cheap to clone (`Arc`-shared).
 #[derive(Debug, Clone, Default)]
 pub struct BootTokens {
    inner: std::sync::Arc<Mutex<HashMap<String, Grant>>>,
 }
 impl BootTokens {
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }
    /// Mint a token granting access to unattended file `file_id` for the
    /// next [`TOKEN_TTL`]. Returns the opaque token value to embed in the
    /// generated URL.
    #[must_use]
    pub fn mint(&self, file_id: &str) -> String {
        self.mint_at(file_id, Instant::now())
    }
    /// Is `token` a live grant for `file_id`?
    #[must_use]
    pub fn check(&self, token: &str, file_id: &str) -> bool {
        self.check_at(token, file_id, Instant::now())
    }
    fn mint_at(&self, file_id: &str, now: Instant) -> String {
        let token = Uuid::new_v4().simple().to_string();
        let mut g = self.inner.lock();
        g.retain(|_, gr| now.duration_since(gr.issued) < TOKEN_TTL);
        if g.len() >= MAX_TOKENS {
            if let Some(oldest) = g
                .iter()
                .min_by_key(|(_, gr)| gr.issued)
                .map(|(k, _)| k.clone())
            {
                g.remove(&oldest);
            }
        }
        g.insert(
            token.clone(),
            Grant {
                file_id: file_id.to_string(),
                issued: now,
            },
        );
        token
    }
    fn check_at(&self, token: &str, file_id: &str, now: Instant) -> bool {
        let g = self.inner.lock();
        g.get(token)
            .is_some_and(|gr| gr.file_id == file_id && now.duration_since(gr.issued) < TOKEN_TTL)
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    #[test]
    fn mint_then_check_round_trip() {
        let t = BootTokens::new();
        let tok = t.mint("ks-1");
        assert!(t.check(&tok, "ks-1"));
        // Multi-use within TTL: a second fetch still passes.
        assert!(t.check(&tok, "ks-1"));
        // Wrong file id never passes, even with a live token.
        assert!(!t.check(&tok, "ks-2"));
        // Unknown token never passes.
        assert!(!t.check("nope", "ks-1"));
    }
    #[test]
    fn token_expires_after_ttl() {
        let t = BootTokens::new();
        let now = Instant::now();
        let tok = t.mint_at("ks-1", now);
        let just_before = TOKEN_TTL.checked_sub(Duration::from_secs(1)).unwrap();
        assert!(t.check_at(&tok, "ks-1", now + just_before));
        assert!(!t.check_at(&tok, "ks-1", now + TOKEN_TTL + Duration::from_secs(1)));
    }
    #[test]
    fn table_is_capped() {
        let t = BootTokens::new();
        let now = Instant::now();
        let first = t.mint_at("f", now);
        for i in 0..MAX_TOKENS {
            let _ = t.mint_at(&format!("f{i}"), now + Duration::from_secs(1));
        }
        // The oldest grant was evicted to stay within the cap.
        assert!(!t.check_at(&first, "f", now + Duration::from_secs(2)));
        assert!(t.inner.lock().len() <= MAX_TOKENS);
    }
 }
@@ -12,11 +12,9 @@ use time::OffsetDateTime;
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub enum ClientEvent {
    DhcpDiscover,
    DhcpRequest,
    PxeBootServerRequest,
    TftpRead { file: String },
    HttpScriptFetch { target: String },
    HttpIsoAsset { file: String },
 }
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -32,8 +30,6 @@ pub struct ClientSnapshot {
    // Events are left with default serialization (9-tuple) — they're
    // diagnostic only and not consumed by the UI today.
    pub events: Vec<(OffsetDateTime, ClientEvent)>,
    /// The boot target (ISO id) last selected via the iPXE menu, if any.
    pub selected_target: Option<String>,
 }
 #[derive(Debug, Default)]
@@ -66,7 +62,6 @@ impl ClientRegistry {
                first_seen: now,
                last_seen: now,
                events: Vec::new(),
                selected_target: None,
            });
        entry.last_seen = now;
        if ip.is_some() {
@@ -84,13 +79,6 @@ impl ClientRegistry {
        }
    }
    pub fn set_selected_target(&self, mac: &str, target: Option<String>) {
        let mut guard = self.inner.write();
        if let Some(c) = guard.get_mut(mac) {
            c.selected_target = target;
        }
    }
    #[must_use]
    pub fn list(&self) -> Vec<ClientSnapshot> {
        let guard = self.inner.read();
@@ -99,9 +87,4 @@ impl ClientRegistry {
        v.sort_by_key(|c| std::cmp::Reverse(c.last_seen));
        v
    }
    #[must_use]
    pub fn get(&self, mac: &str) -> Option<ClientSnapshot> {
        self.inner.read().get(mac).cloned()
    }
 }
@@ -1,3 +1,5 @@
 use figment::providers::{Env, Format, Serialized, Toml};
 use figment::Figment;
 use serde::{Deserialize, Serialize};
 use std::net::{IpAddr, Ipv4Addr};
 use std::path::{Path, PathBuf};
@@ -38,10 +40,6 @@ pub struct NetworkConfig {
    pub dhcp_port: u16,
    /// UDP port for PXE Boot Server discovery. Standard is 4011.
    pub pxe_port: u16,
    /// Optional allowlist of client MAC prefixes (OUI). Empty = serve everyone.
    pub mac_allowlist: Vec<String>,
    /// Optional allowlist of subnets (CIDR). Empty = serve everyone.
    pub subnet_allowlist: Vec<String>,
 }
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
@@ -56,6 +54,9 @@ pub enum DhcpMode {
    /// Disabled — rely on an external DHCP server that has been manually
    /// configured with `next-server` / `filename`. OpenPXE only serves TFTP
    /// + HTTP in this mode. Useful for home routers that can be pre-set.
    // `off`/`none` are accepted as aliases for backward-compat with the old
    // hand-rolled `apply_env`, which mapped them to Disabled.
    #[serde(alias = "off", alias = "none")]
    Disabled,
 }
@@ -100,8 +101,6 @@ impl Default for NetworkConfig {
            dhcp_bind: IpAddr::V4(Ipv4Addr::UNSPECIFIED),
            dhcp_port: 67,
            pxe_port: 4011,
            mac_allowlist: Vec::new(),
            subnet_allowlist: Vec::new(),
        }
    }
 }
@@ -129,48 +128,162 @@ impl Config {
        toml::from_str(&text).map_err(|e| crate::Error::Config(e.to_string()))
    }
-    /// Apply environment variable overrides. Env var names follow the pattern
+    /// Load configuration with layered precedence (v0.5.4, via `figment`):
-    /// `OPENPXE_<SECTION>_<FIELD>`, uppercase. Unknown vars are ignored.
+    /// built-in [`Default`] → optional TOML file → `OPENPXE_*` environment
-    /// Call this after loading the TOML file so env takes precedence.
+    /// (highest). Replaces the old `from_toml_file` + `apply_env` two-step
-    pub fn apply_env(&mut self) {
+    /// and now covers **every** field automatically (the previous hand-rolled
-        if let Ok(v) = std::env::var("OPENPXE_HTTP_PORT") {
+    /// mapping silently skipped `unattended_dir`, the bind addresses, etc.).
-            if let Ok(p) = v.parse() {
+    ///
-                self.server.http_port = p;
+    /// The env layer preserves the historical flat names
    /// (`OPENPXE_HTTP_PORT`, `OPENPXE_ISO_DIR`, …) so existing deployments
    /// (the Unraid template, `entrypoint.sh`) keep working unchanged, and
    /// additionally accepts the explicit nested form
    /// `OPENPXE_<SECTION>__<FIELD>` (double underscore).
    pub fn load(path: Option<&Path>) -> crate::Result<Self> {
        let mut fig = Figment::from(Serialized::defaults(Config::default()));
        if let Some(p) = path {
            if p.exists() {
                fig = fig.merge(Toml::file(p));
            }
        }
-        if let Ok(v) = std::env::var("OPENPXE_TFTP_PORT") {
+        fig = fig.merge(env_provider());
-            if let Ok(p) = v.parse() {
+        fig.extract()
-                self.server.tftp_port = p;
+            .map_err(|e| crate::Error::Config(e.to_string()))
-            }
+    }
-        }
+}
-        if let Ok(v) = std::env::var("OPENPXE_DHCP_PORT") {
+
-            if let Ok(p) = v.parse() {
+/// The `OPENPXE_*` environment provider. Maps the historical flat variable
-                self.network.dhcp_port = p;
+/// names onto the nested [`Config`] fields, and also accepts the explicit
-            }
+/// `OPENPXE_SECTION__FIELD` nested form. Keys that match nothing (e.g.
-        }
+/// `OPENPXE_CONFIG`, `OPENPXE_UID` from the entrypoint) become stray
-        if let Ok(v) = std::env::var("OPENPXE_PUBLIC_IP") {
+/// top-level keys that `Config` ignores on extract.
-            if let Ok(ip) = v.parse() {
+fn env_provider() -> Env {
-                self.server.public_ip = Some(ip);
+    Env::prefixed("OPENPXE_")
-            }
+        .map(|key| {
-        }
+            // Lowercase so the match is robust regardless of how the OS
-        if let Ok(v) = std::env::var("OPENPXE_DHCP_MODE") {
+            // reports the var's case.
-            self.network.dhcp_mode = match v.to_ascii_lowercase().as_str() {
+            let k = key.as_str().to_ascii_lowercase();
-                "proxy" => DhcpMode::Proxy,
+            let mapped = match k.as_str() {
-                "disabled" | "off" | "none" => DhcpMode::Disabled,
+                "http_port" => "server.http_port",
-                _ => self.network.dhcp_mode,
+                "http_bind" => "server.http_bind",
                "tftp_port" => "server.tftp_port",
                "tftp_bind" => "server.tftp_bind",
                "public_ip" => "server.public_ip",
                "dhcp_port" => "network.dhcp_port",
                "dhcp_bind" => "network.dhcp_bind",
                "dhcp_mode" => "network.dhcp_mode",
                "pxe_port" => "network.pxe_port",
                "iso_dir" => "paths.iso_dir",
                "work_dir" => "paths.work_dir",
                "ipxe_dir" => "paths.ipxe_dir",
                "smb_dir" => "paths.smb_dir",
                "wimboot_path" => "paths.wimboot_path",
                "unattended_dir" => "paths.unattended_dir",
                // Unknown: support the explicit nested form
                // (OPENPXE_SERVER__HTTP_PORT). `replace` is a no-op for the
                // already-handled flat names above.
                other => return other.replace("__", ".").into(),
            };
-        }
+            mapped.into()
-        if let Ok(v) = std::env::var("OPENPXE_ISO_DIR") {
+        })
-            self.paths.iso_dir = PathBuf::from(v);
+        .split(".")
-        }
+}
-        if let Ok(v) = std::env::var("OPENPXE_WORK_DIR") {
+
-            self.paths.work_dir = PathBuf::from(v);
+#[cfg(test)]
-        }
+mod tests {
-        if let Ok(v) = std::env::var("OPENPXE_IPXE_DIR") {
+    // figment's `Jail::expect_with` closure returns `Result<(), figment::Error>`
-            self.paths.ipxe_dir = PathBuf::from(v);
+    // and `figment::Error` is large; that's the library's API, not ours.
-        }
+    #![allow(clippy::result_large_err)]
-        if let Ok(v) = std::env::var("OPENPXE_SMB_DIR") {
+    use super::*;
-            self.paths.smb_dir = PathBuf::from(v);
+
-        }
+    #[test]
    fn defaults_load_when_no_file_or_env() {
        figment::Jail::expect_with(|_jail| {
            let c = Config::load(None).expect("load defaults");
            assert_eq!(c.server.http_port, 80);
            assert_eq!(c.network.dhcp_mode, DhcpMode::Proxy);
            assert_eq!(c.paths.iso_dir, PathBuf::from("/var/lib/openpxe/isos"));
            Ok(())
        });
    }
    #[test]
    fn legacy_flat_env_vars_still_apply() {
        figment::Jail::expect_with(|jail| {
            jail.set_env("OPENPXE_HTTP_PORT", "8123");
            jail.set_env("OPENPXE_TFTP_PORT", "6900");
            jail.set_env("OPENPXE_DHCP_PORT", "6767");
            jail.set_env("OPENPXE_PXE_PORT", "4444");
            jail.set_env("OPENPXE_PUBLIC_IP", "10.20.30.40");
            jail.set_env("OPENPXE_DHCP_MODE", "disabled");
            jail.set_env("OPENPXE_ISO_DIR", "/data/isos");
            jail.set_env("OPENPXE_WORK_DIR", "/data/work");
            jail.set_env("OPENPXE_IPXE_DIR", "/data/ipxe");
            jail.set_env("OPENPXE_SMB_DIR", "/data/smb");
            // v0.5.4: a field the old apply_env never covered.
            jail.set_env("OPENPXE_UNATTENDED_DIR", "/data/unattended");
            let c = Config::load(None).expect("load with env");
            assert_eq!(c.server.http_port, 8123);
            assert_eq!(c.server.tftp_port, 6900);
            assert_eq!(c.network.dhcp_port, 6767);
            assert_eq!(c.network.pxe_port, 4444);
            assert_eq!(c.server.public_ip, Some("10.20.30.40".parse().unwrap()));
            assert_eq!(c.network.dhcp_mode, DhcpMode::Disabled);
            assert_eq!(c.paths.iso_dir, PathBuf::from("/data/isos"));
            assert_eq!(c.paths.work_dir, PathBuf::from("/data/work"));
            assert_eq!(c.paths.ipxe_dir, PathBuf::from("/data/ipxe"));
            assert_eq!(c.paths.smb_dir, PathBuf::from("/data/smb"));
            assert_eq!(c.paths.unattended_dir, PathBuf::from("/data/unattended"));
            Ok(())
        });
    }
    #[test]
    fn dhcp_mode_off_alias_maps_to_disabled() {
        figment::Jail::expect_with(|jail| {
            jail.set_env("OPENPXE_DHCP_MODE", "off");
            let c = Config::load(None).unwrap();
            assert_eq!(c.network.dhcp_mode, DhcpMode::Disabled);
            Ok(())
        });
    }
    #[test]
    fn nested_double_underscore_form_also_works() {
        figment::Jail::expect_with(|jail| {
            jail.set_env("OPENPXE_SERVER__HTTP_PORT", "9001");
            let c = Config::load(None).unwrap();
            assert_eq!(c.server.http_port, 9001);
            Ok(())
        });
    }
    #[test]
    fn env_overrides_toml_file() {
        figment::Jail::expect_with(|jail| {
            jail.create_file(
                "openpxe.toml",
                "[server]\nhttp_port = 8080\n[paths]\niso_dir = \"/from/toml\"\n",
            )?;
            jail.set_env("OPENPXE_HTTP_PORT", "8443");
            let c = Config::load(Some(Path::new("openpxe.toml"))).unwrap();
            // env wins over TOML…
            assert_eq!(c.server.http_port, 8443);
            // …but TOML-only values still apply.
            assert_eq!(c.paths.iso_dir, PathBuf::from("/from/toml"));
            Ok(())
        });
    }
    #[test]
    fn unrelated_openpxe_env_vars_are_ignored() {
        figment::Jail::expect_with(|jail| {
            // entrypoint.sh sets these; they must not break config load.
            jail.set_env("OPENPXE_UID", "10001");
            jail.set_env("OPENPXE_CONFIG", "/etc/openpxe.toml");
            let c = Config::load(None).expect("stray vars ignored");
            assert_eq!(c.server.http_port, 80);
            Ok(())
        });
    }
 }
@@ -0,0 +1,65 @@
 //! Small, dependency-free encoding helpers shared across crates.
 //!
 //! v0.5.4: `pct_encode` and `xml_escape` were duplicated in the SAML
 //! modules and the HTTP layer; they live here now. They're deliberately
 //! hand-rolled rather than pulling in `percent-encoding` / `url`: the
 //! unreserved set below is exactly the RFC 3986 set that iPXE's
 //! `:uristring` modifier and the SAML HTTP-Redirect binding both expect,
 //! and a general-purpose URL crate escapes a different set.
 use std::fmt::Write as _;
 /// Percent-encode `s` per RFC 3986: the unreserved set
 /// (`A-Z` `a-z` `0-9` `-` `_` `.` `~`) passes through unchanged; every
 /// other byte becomes `%XX` (uppercase hex).
 #[must_use]
 pub fn pct_encode(s: &str) -> String {
    let mut out = String::with_capacity(s.len());
    for b in s.bytes() {
        match b {
            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => {
                out.push(b as char);
            }
            _ => {
                let _ = write!(out, "%{b:02X}");
            }
        }
    }
    out
 }
 /// Escape the five XML predefined entities so `s` is safe inside element
 /// text or a double-quoted attribute value.
 #[must_use]
 pub fn xml_escape(s: &str) -> String {
    let mut out = String::with_capacity(s.len());
    for c in s.chars() {
        match c {
            '&' => out.push_str("&amp;"),
            '<' => out.push_str("&lt;"),
            '>' => out.push_str("&gt;"),
            '"' => out.push_str("&quot;"),
            '\'' => out.push_str("&apos;"),
            _ => out.push(c),
        }
    }
    out
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    #[test]
    fn pct_encode_unreserved_passthrough_else_hex() {
        assert_eq!(pct_encode("node-7.lab_1~"), "node-7.lab_1~");
        assert_eq!(pct_encode("aa:bb cc/?&="), "aa%3Abb%20cc%2F%3F%26%3D");
        assert_eq!(pct_encode(""), "");
    }
    #[test]
    fn xml_escape_all_five_entities() {
        assert_eq!(xml_escape("a&b<c>\"d'e"), "a&amp;b&lt;c&gt;&quot;d&apos;e");
        assert_eq!(xml_escape("plain text"), "plain text");
    }
 }
@@ -2,12 +2,16 @@
 //! runtime settings, and the Queued Deployment queue.
 #![forbid(unsafe_code)]
 pub mod api_key;
 pub mod arch;
 pub mod auth;
 pub mod boot_log;
 pub mod boot_rules;
 pub mod boot_tokens;
 pub mod branding;
 pub mod client;
 pub mod config;
 pub mod encoding;
 pub mod error;
 pub mod host_bindings;
 pub mod log_bus;
@@ -20,9 +24,12 @@ pub mod settings;
 pub mod sso;
 pub mod wol;
-pub use arch::{ClientArch, FirmwareClass};
+pub use api_key::ApiKeyStore;
 pub use arch::{ClientArch, DriverMode, FirmwareClass};
 pub use auth::{AdminAccount, AdminPublic, AdminStore};
 pub use boot_log::{BootEvent, BootLog};
 pub use boot_rules::{BootRule, BootRulesConfig, BootRulesStore};
 pub use boot_tokens::BootTokens;
 pub use branding::{ext_for_mime, BrandingStore, LogoSlot, ALLOWED_LOGO_MIMES, MAX_LOGO_BYTES};
 pub use client::{ClientEvent, ClientRegistry, ClientSnapshot};
 pub use config::{Config, DhcpMode, NetworkConfig, Paths, ServerConfig};
@@ -35,4 +42,4 @@ pub use profile::DeployProfile;
 pub use queue::{DeploymentQueue, QueueEntry};
 pub use saml::{IdpMetadata, SamlError, SpParams, VerifiedPrincipal, VerifiedResponse};
 pub use settings::{Settings, SettingsStore, TimeoutAction};
-pub use sso::{SsoConfig, SsoStore};
+pub use sso::{SsoConfig, SsoLoginInfo, SsoStore};
@@ -303,7 +303,10 @@ mod tests {
            smtp_host: "smtp.example.com".into(),
            ..Default::default()
        });
-        assert!(matches!(r, Err(Error::Invalid(_))), "missing recipient should reject");
+        assert!(
            matches!(r, Err(Error::Invalid(_))),
            "missing recipient should reject"
        );
        s.replace(NotifyConfig {
            enabled: true,
            kind: NotifyKind::Smtp,
@@ -5,7 +5,6 @@
 //! appended as the `SAMLRequest` query parameter. AuthnRequests are sent
 //! unsigned in this release (the IdP must not require client signatures).
 use std::fmt::Write as _;
 use std::io::Write as _;
 use base64::Engine;
@@ -15,6 +14,7 @@ use time::format_description::well_known::Rfc3339;
 use time::OffsetDateTime;
 use super::{SamlError, SpParams};
 use crate::encoding::{pct_encode, xml_escape};
 const NS_PROTOCOL: &str = "urn:oasis:names:tc:SAML:2.0:protocol";
 const NS_ASSERTION: &str = "urn:oasis:names:tc:SAML:2.0:assertion";
@@ -79,37 +79,8 @@ fn deflate_base64(xml: &str) -> Result<String, SamlError> {
    Ok(base64::engine::general_purpose::STANDARD.encode(compressed))
 }
-/// Percent-encode a query-string component (RFC 3986 unreserved set passes
+// `pct_encode` + `xml_escape` now live in `openpxe_core::encoding` (v0.5.4)
-/// through; everything else is `%XX`).
+// — imported above.
 fn pct_encode(s: &str) -> String {
    let mut out = String::with_capacity(s.len() * 3);
    for b in s.bytes() {
        match b {
            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => {
                out.push(b as char);
            }
            _ => {
                let _ = write!(out, "%{b:02X}");
            }
        }
    }
    out
 }
 fn xml_escape(s: &str) -> String {
    let mut out = String::with_capacity(s.len());
    for c in s.chars() {
        match c {
            '&' => out.push_str("&amp;"),
            '<' => out.push_str("&lt;"),
            '>' => out.push_str("&gt;"),
            '"' => out.push_str("&quot;"),
            '\'' => out.push_str("&apos;"),
            _ => out.push(c),
        }
    }
    out
 }
 #[cfg(test)]
 mod tests {
@@ -7,6 +7,7 @@
 use base64::Engine;
 use super::{SamlError, SpParams};
 use crate::encoding::xml_escape;
 /// SAML 2.0 binding URIs.
 pub const BINDING_REDIRECT: &str = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect";
@@ -148,21 +149,7 @@ fn node_text(n: &roxmltree::Node<'_, '_>) -> String {
        .collect()
 }
-/// Minimal XML attribute/text escaping for the values we interpolate.
+// `xml_escape` now lives in `openpxe_core::encoding` (v0.5.4) — imported above.
 fn xml_escape(s: &str) -> String {
    let mut out = String::with_capacity(s.len());
    for c in s.chars() {
        match c {
            '&' => out.push_str("&amp;"),
            '<' => out.push_str("&lt;"),
            '>' => out.push_str("&gt;"),
            '"' => out.push_str("&quot;"),
            '\'' => out.push_str("&apos;"),
            _ => out.push(c),
        }
    }
    out
 }
 #[cfg(test)]
 mod tests {
@@ -73,6 +73,23 @@ impl SsoConfig {
    }
 }
 /// The minimal, non-sensitive slice of the SSO config that the **pre-auth**
 /// login screen needs to render the "Sign in with …" button. Carries only
 /// the display affordances — never the metadata XML/URL or entity ID, which
 /// stay behind the auth-gated `/api/sso`. Served as part of the public
 /// `/api/me` so the button renders reliably whether or not anyone is signed
 /// in (v0.5.9: fixes the button vanishing because `/api/sso` 401s pre-auth).
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
 pub struct SsoLoginInfo {
    /// True only when SSO is *usable* (enabled AND a metadata source is
    /// present) — i.e. clicking the button will actually reach an IdP.
    pub enabled: bool,
    /// Button label, e.g. "STC AD". Empty falls back to "SSO" in the UI.
    pub idp_name: String,
    /// Optional IdP logo rendered on the button. Empty = no image.
    pub idp_logo_url: String,
 }
 /// In-memory + on-disk SSO settings registry.
 #[derive(Debug, Clone)]
 pub struct SsoStore {
@@ -111,6 +128,19 @@ impl SsoStore {
        self.inner.read().clone()
    }
    /// Public, non-sensitive descriptor for the login screen. Safe to
    /// expose pre-auth — it's exactly what the "Sign in with …" button
    /// keys off, with no metadata/entity-ID leakage. v0.5.9.
    #[must_use]
    pub fn login_info(&self) -> SsoLoginInfo {
        let cfg = self.inner.read();
        SsoLoginInfo {
            enabled: cfg.is_usable(),
            idp_name: cfg.idp_name.clone(),
            idp_logo_url: cfg.idp_logo_url.clone(),
        }
    }
    /// Replace the whole config in one shot. Light validation: metadata
    /// XML and URL are length-capped so an operator can't OOM us by
    /// pasting a 10 GiB blob; the IdP UI tab clamps the input visually,
@@ -181,10 +181,7 @@ mod tests {
            Ipv4Addr::new(192, 168, 1, 255)
        );
        assert_eq!(
-            subnet_broadcast(
+            subnet_broadcast(Ipv4Addr::new(10, 5, 3, 7), Ipv4Addr::new(255, 255, 0, 0)),
                Ipv4Addr::new(10, 5, 3, 7),
                Ipv4Addr::new(255, 255, 0, 0)
            ),
            Ipv4Addr::new(10, 5, 255, 255)
        );
    }
@@ -196,7 +193,8 @@ mod tests {
        // and confirm send_magic transmits the exact 102-byte packet.
        let rx = UdpSocket::bind(SocketAddrV4::new(Ipv4Addr::LOCALHOST, 0)).unwrap();
        let port = rx.local_addr().unwrap().port();
-        rx.set_read_timeout(Some(std::time::Duration::from_secs(2))).unwrap();
+        rx.set_read_timeout(Some(std::time::Duration::from_secs(2)))
            .unwrap();
        let packet = magic_packet([0x0a, 0x1b, 0x2c, 0x3d, 0x4e, 0x5f]);
        let sent = send_magic(&packet, &[Ipv4Addr::LOCALHOST], port).unwrap();
@@ -15,6 +15,10 @@ tokio.workspace = true
 socket2.workspace = true
 dhcproto.workspace = true
 tracing.workspace = true
 thiserror.workspace = true
 anyhow.workspace = true
-bytes.workspace = true
+parking_lot.workspace = true
 # v0.7.1: learned driver modes persist to <work_dir>/driver_modes.json.
 serde_json.workspace = true
 [dev-dependencies]
 tempfile = "3.12"
@@ -0,0 +1,494 @@
 //! Automatic per-MAC boot-binary escalation (v0.6.1, extended v0.7.x).
 //!
 //! OpenPXE serves the firmware-net iPXE build (`snponly`/`undionly`) by
 //! default — it's the most reliable choice for chainloading because the
 //! firmware just proved its network works by downloading the NBP. Two
 //! classes of machine can't run it:
 //!
 //! * a minority of NICs have a missing or buggy firmware UNDI/SNP stack —
 //!   they TFTP the binary fine but iPXE can't bring the link up;
 //! * Secure-Boot firmware downloads it fine but refuses to *execute* an
 //!   unsigned image.
 //!
 //! Both look identical from here: the tell-tale second DHCP DISCOVER
 //! carrying the `iPXE` user-class never arrives and the machine
 //! re-PXE-boots. So a fresh firmware DISCOVER from a MAC whose previous
 //! attempt was never confirmed climbs one rung:
 //! `Firmware → Builtin → Shim` (the signed shim+GRUB chain). The decision
 //! is sticky; there is no operator toggle; the default path is unchanged
 //! so hardware that already boots never regresses.
 //!
 //! v0.7.1 — **learned modes persist**. Walking the ladder costs one or
 //! two failed boot cycles, so a machine should pay it once *ever*, not
 //! once per idle window or server restart. Two events pin a MAC's mode
 //! to disk (`<work_dir>/driver_modes.json`):
 //!
 //! * a confirmed iPXE handoff at a non-default mode (Builtin proved to
 //!   work — also Shim, via the GRUB→iPXE same-boot chainload);
 //! * reaching the terminal Shim rung (Secure-Boot machines never produce
 //!   an iPXE handoff from the signed menu, so escalation itself is the
 //!   best knowledge we'll ever have).
 //!
 //! Pinned entries are immune to the TTL and reload at startup. The
 //! operator escape hatch is a rules-level driver-mode pin (which
 //! overrides this table entirely) or deleting `driver_modes.json`.
 use openpxe_core::DriverMode;
 use parking_lot::Mutex;
 use std::collections::HashMap;
 use std::path::{Path, PathBuf};
 use std::sync::Arc;
 use std::time::{Duration, Instant};
 /// Multiple DISCOVERs within this window belong to the *same* boot (DHCP
 /// retransmits, plus the :4011 PXE Boot Server query that follows the :67
 /// DISCOVER). They must not be mistaken for a failed-and-retried boot.
 const SAME_BOOT_DEBOUNCE: Duration = Duration::from_secs(8);
 /// Forget an *unpinned* MAC's state after this long with no activity, so
 /// a transient mid-walk state doesn't linger and the map stays bounded.
 /// Pinned (learned) entries are exempt — that's their whole point.
 const ENTRY_TTL: Duration = Duration::from_mins(30);
 /// Hard cap on tracked MACs. Past this we evict the least-recently-seen
 /// entry (unpinned first) — escalation is best-effort, never a
 /// memory-growth vector.
 const MAX_ENTRIES: usize = 4096;
 /// How often (at most) the whole map is swept for expired entries.
 /// Correctness doesn't depend on the sweep — a stale entry is also
 /// detected inline when its MAC next appears — so the sweep only bounds
 /// memory for MACs that never return, and amortizing it keeps the
 /// per-packet path O(1) instead of O(map).
 const PRUNE_INTERVAL: Duration = Duration::from_mins(1);
 #[derive(Debug, Clone, Copy)]
 struct Entry {
    mode: DriverMode,
    /// True once we've served `mode` and are waiting for the iPXE handoff to
    /// confirm it worked. A *new* boot arriving while this is still true means
    /// the previous attempt failed and we should escalate.
    awaiting_confirm: bool,
    /// Learned mode (v0.7.1): persisted to disk, exempt from the TTL.
    pinned: bool,
    last_seen: Instant,
 }
 #[derive(Debug)]
 struct Inner {
    map: HashMap<String, Entry>,
    /// When the last full TTL sweep ran — see [`PRUNE_INTERVAL`].
    last_prune: Instant,
 }
 impl Default for Inner {
    fn default() -> Self {
        Self {
            map: HashMap::new(),
            last_prune: Instant::now(),
        }
    }
 }
 /// Tracks per-MAC driver-mode escalation. Cheap to share via `Arc`.
 #[derive(Debug, Default)]
 pub struct DriverEscalation {
    inner: Mutex<Inner>,
    /// Persistence target for learned modes; `None` = ephemeral (tests).
    path: Option<Arc<PathBuf>>,
 }
 impl DriverEscalation {
    /// Ephemeral instance (no persistence) — used by tests.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }
    /// Instance backed by `<work_dir>/driver_modes.json`. Learned modes
    /// from previous runs are reloaded as pinned entries; a missing or
    /// corrupt file starts empty (same crash-cache policy as every other
    /// store — a bad file must never block PXE).
    #[must_use]
    pub fn load_or_default(work_dir: &Path) -> Self {
        let path = work_dir.join("driver_modes.json");
        let mut map = HashMap::new();
        if let Ok(text) = std::fs::read_to_string(&path) {
            match serde_json::from_str::<HashMap<String, DriverMode>>(&text) {
                Ok(loaded) => {
                    let now = Instant::now();
                    for (mac, mode) in loaded {
                        // Firmware is the default — persisting it would be
                        // noise; tolerate it in the file but don't track it.
                        if mode == DriverMode::Firmware {
                            continue;
                        }
                        map.insert(
                            mac,
                            Entry {
                                mode,
                                awaiting_confirm: false,
                                pinned: true,
                                last_seen: now,
                            },
                        );
                    }
                    tracing::info!(
                        target: "openpxe::dhcp",
                        learned = map.len(),
                        "loaded learned driver modes"
                    );
                }
                Err(e) => {
                    tracing::warn!(
                        target: "openpxe::dhcp",
                        "driver_modes.json present but unreadable ({e}); starting empty"
                    );
                }
            }
        }
        Self {
            inner: Mutex::new(Inner {
                map,
                last_prune: Instant::now(),
            }),
            path: Some(Arc::new(path)),
        }
    }
    /// Decide the driver mode for a firmware (PXEClient/HTTPClient) boot from
    /// `mac`. `primary` is true for the main DHCP DISCOVER (:67) and false for
    /// the PXE Boot Server query (:4011); only the primary path drives
    /// escalation, and only when it's clearly a *new* boot (outside the
    /// same-boot debounce). The :4011 path just echoes the current mode.
    pub fn mode_for_firmware_attempt(&self, mac: &str, primary: bool) -> DriverMode {
        self.decide_at(mac, primary, Instant::now())
    }
    /// Record that `mac` completed the iPXE handoff (a DISCOVER carrying the
    /// `iPXE` user-class). The mode we last served worked, so stop awaiting
    /// confirmation, keep it sticky, and — for non-default modes — pin it to
    /// disk so the machine never re-walks the ladder (v0.7.1).
    pub fn mark_ipxe_success(&self, mac: &str) {
        self.confirm_at(mac, Instant::now());
    }
    fn decide_at(&self, mac: &str, primary: bool, now: Instant) -> DriverMode {
        let (mode, snapshot) = {
            let mut g = self.inner.lock();
            if now.duration_since(g.last_prune) >= PRUNE_INTERVAL {
                g.map
                    .retain(|_, e| e.pinned || now.duration_since(e.last_seen) < ENTRY_TTL);
                g.last_prune = now;
            }
            // Inline staleness check: an unpinned MAC whose entry outlived
            // the TTL starts fresh even when the amortized sweep above
            // hasn't caught it yet. Pinned entries never go stale.
            if g.map
                .get(mac)
                .is_some_and(|e| !e.pinned && now.duration_since(e.last_seen) >= ENTRY_TTL)
            {
                g.map.remove(mac);
            }
            let mut newly_pinned = false;
            let mode = match g.map.get_mut(mac) {
                None => {
                    g.map.insert(
                        mac.to_owned(),
                        Entry {
                            mode: DriverMode::Firmware,
                            // Only the primary DISCOVER opens a confirmation window.
                            awaiting_confirm: primary,
                            pinned: false,
                            last_seen: now,
                        },
                    );
                    if g.map.len() > MAX_ENTRIES {
                        evict_oldest(&mut g.map);
                    }
                    DriverMode::Firmware
                }
                Some(entry) => {
                    let recent = now.duration_since(entry.last_seen) < SAME_BOOT_DEBOUNCE;
                    if primary && !recent {
                        // A genuinely new boot. If the previous attempt was
                        // never confirmed, the build we served failed → climb
                        // one rung: Firmware (firmware NIC stack) → Builtin
                        // (iPXE's own drivers) → Shim (signed shim+GRUB —
                        // covers Secure Boot firmware that downloads our
                        // unsigned iPXE but refuses to execute it). Shim is
                        // terminal and pins to disk: SB machines never emit
                        // an iPXE handoff from the signed menu, so reaching
                        // the rung *is* the durable knowledge.
                        if entry.awaiting_confirm {
                            entry.mode = match entry.mode {
                                DriverMode::Firmware => DriverMode::Builtin,
                                DriverMode::Builtin | DriverMode::Shim => DriverMode::Shim,
                            };
                            if entry.mode == DriverMode::Shim && !entry.pinned {
                                entry.pinned = true;
                                newly_pinned = true;
                            }
                        }
                        entry.awaiting_confirm = true;
                    }
                    entry.last_seen = now;
                    entry.mode
                }
            };
            (mode, newly_pinned.then(|| pinned_snapshot(&g.map)))
        };
        if let Some(s) = snapshot {
            self.persist(&s);
        }
        mode
    }
    fn confirm_at(&self, mac: &str, now: Instant) {
        let snapshot = {
            let mut g = self.inner.lock();
            let Some(e) = g.map.get_mut(mac) else {
                return;
            };
            e.awaiting_confirm = false;
            e.last_seen = now;
            // A proven non-default mode is worth remembering forever —
            // the machine demonstrably can't use the default path.
            if e.mode != DriverMode::Firmware && !e.pinned {
                e.pinned = true;
                Some(pinned_snapshot(&g.map))
            } else {
                None
            }
        };
        if let Some(s) = snapshot {
            self.persist(&s);
        }
    }
    /// Best-effort atomic write of the learned-mode table. No-op for
    /// ephemeral instances. Failure logs and moves on — persistence is an
    /// optimization, never a correctness requirement.
    fn persist(&self, snapshot: &HashMap<String, DriverMode>) {
        let Some(path) = &self.path else { return };
        let body = match serde_json::to_vec_pretty(snapshot) {
            Ok(b) => b,
            Err(e) => {
                tracing::warn!(target: "openpxe::dhcp", "serialize driver_modes.json: {e}");
                return;
            }
        };
        if let Some(parent) = path.parent() {
            let _ = std::fs::create_dir_all(parent);
        }
        let tmp = path.with_extension("json.tmp");
        if let Err(e) = std::fs::write(&tmp, body) {
            tracing::warn!(target: "openpxe::dhcp", "write driver_modes.json tmp: {e}");
            return;
        }
        if let Err(e) = std::fs::rename(&tmp, path.as_path()) {
            tracing::warn!(target: "openpxe::dhcp", "rename driver_modes.json: {e}");
        }
    }
 }
 fn pinned_snapshot(map: &HashMap<String, Entry>) -> HashMap<String, DriverMode> {
    map.iter()
        .filter(|(_, e)| e.pinned)
        .map(|(k, e)| (k.clone(), e.mode))
        .collect()
 }
 fn evict_oldest(map: &mut HashMap<String, Entry>) {
    // Prefer evicting an unpinned entry; only touch learned modes when
    // the whole table is pinned (4096 learned machines — at that point
    // the operator has bigger questions than our memory bound).
    let pick = |pinned: bool| {
        map.iter()
            .filter(|(_, e)| e.pinned == pinned)
            .min_by_key(|(_, e)| e.last_seen)
            .map(|(k, _)| k.clone())
    };
    if let Some(oldest) = pick(false).or_else(|| pick(true)) {
        map.remove(&oldest);
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    use tempfile::tempdir;
    #[test]
    fn firmware_first_then_escalates_on_unconfirmed_retry() {
        let e = DriverEscalation::new();
        let t0 = Instant::now();
        // Boot 1, primary DISCOVER: firmware.
        assert_eq!(e.decide_at("aa", true, t0), DriverMode::Firmware);
        // Same boot's :4011 query (+1s, within debounce): still firmware, no escalation.
        assert_eq!(
            e.decide_at("aa", false, t0 + Duration::from_secs(1)),
            DriverMode::Firmware
        );
        // Firmware net failed → no iPXE handoff → machine re-PXE-boots much
        // later: escalate to builtin drivers.
        assert_eq!(
            e.decide_at("aa", true, t0 + Duration::from_mins(1)),
            DriverMode::Builtin
        );
    }
    #[test]
    fn builtin_is_sticky_after_success() {
        let e = DriverEscalation::new();
        let t0 = Instant::now();
        assert_eq!(e.decide_at("bb", true, t0), DriverMode::Firmware);
        assert_eq!(
            e.decide_at("bb", true, t0 + Duration::from_mins(1)),
            DriverMode::Builtin
        );
        // Builtin worked this time — confirm the handoff.
        e.confirm_at("bb", t0 + Duration::from_secs(61));
        // Next cold boot goes straight to builtin (no wasted firmware attempt).
        assert_eq!(
            e.decide_at("bb", true, t0 + Duration::from_mins(2)),
            DriverMode::Builtin
        );
    }
    #[test]
    fn confirmed_firmware_never_escalates() {
        let e = DriverEscalation::new();
        let t0 = Instant::now();
        assert_eq!(e.decide_at("cc", true, t0), DriverMode::Firmware);
        // snponly worked: handoff confirmed.
        e.confirm_at("cc", t0 + Duration::from_secs(2));
        // A later boot stays on firmware — no spurious escalation.
        assert_eq!(
            e.decide_at("cc", true, t0 + Duration::from_mins(5)),
            DriverMode::Firmware
        );
    }
    #[test]
    fn third_unconfirmed_attempt_escalates_to_shim_and_stays() {
        // v0.7.0: a Secure-Boot client downloads-but-refuses both unsigned
        // iPXE builds; the third boot gets the signed shim chain, and the
        // MAC stays there for subsequent boots.
        let e = DriverEscalation::new();
        let t0 = Instant::now();
        assert_eq!(e.decide_at("ee", true, t0), DriverMode::Firmware);
        assert_eq!(
            e.decide_at("ee", true, t0 + Duration::from_mins(1)),
            DriverMode::Builtin
        );
        assert_eq!(
            e.decide_at("ee", true, t0 + Duration::from_mins(2)),
            DriverMode::Shim
        );
        // Shim is terminal — a fourth unconfirmed boot stays on Shim.
        assert_eq!(
            e.decide_at("ee", true, t0 + Duration::from_mins(3)),
            DriverMode::Shim
        );
    }
    #[test]
    fn stale_unpinned_entry_is_forgotten_and_resets_to_firmware() {
        let e = DriverEscalation::new();
        let t0 = Instant::now();
        assert_eq!(e.decide_at("dd", true, t0), DriverMode::Firmware);
        assert_eq!(
            e.decide_at("dd", true, t0 + Duration::from_mins(1)),
            DriverMode::Builtin
        );
        // After the TTL with no activity the (unpinned) Builtin walk is
        // pruned → fresh firmware. (A *confirmed* Builtin would be pinned
        // and survive — see learned_builtin_survives_ttl.)
        let later = t0 + Duration::from_mins(1) + ENTRY_TTL + Duration::from_secs(1);
        assert_eq!(e.decide_at("dd", true, later), DriverMode::Firmware);
    }
    #[test]
    fn shim_pin_survives_ttl() {
        // v0.7.1: reaching the Shim rung is durable knowledge — the
        // machine must NOT re-walk the ladder after an idle period.
        let e = DriverEscalation::new();
        let t0 = Instant::now();
        let _ = e.decide_at("ff", true, t0);
        let _ = e.decide_at("ff", true, t0 + Duration::from_mins(1));
        assert_eq!(
            e.decide_at("ff", true, t0 + Duration::from_mins(2)),
            DriverMode::Shim
        );
        let much_later = t0 + Duration::from_mins(2) + ENTRY_TTL + Duration::from_mins(5);
        assert_eq!(e.decide_at("ff", true, much_later), DriverMode::Shim);
    }
    #[test]
    fn learned_builtin_survives_ttl() {
        let e = DriverEscalation::new();
        let t0 = Instant::now();
        let _ = e.decide_at("gg", true, t0);
        assert_eq!(
            e.decide_at("gg", true, t0 + Duration::from_mins(1)),
            DriverMode::Builtin
        );
        // The handoff confirms Builtin → pinned.
        e.confirm_at("gg", t0 + Duration::from_secs(61));
        let much_later = t0 + ENTRY_TTL + Duration::from_mins(10);
        assert_eq!(e.decide_at("gg", true, much_later), DriverMode::Builtin);
    }
    #[test]
    fn learned_modes_persist_across_restart() {
        let dir = tempdir().unwrap();
        let t0 = Instant::now();
        {
            let e = DriverEscalation::load_or_default(dir.path());
            // Walk one MAC to Shim (pins on escalation)...
            let _ = e.decide_at("aa:01", true, t0);
            let _ = e.decide_at("aa:01", true, t0 + Duration::from_mins(1));
            assert_eq!(
                e.decide_at("aa:01", true, t0 + Duration::from_mins(2)),
                DriverMode::Shim
            );
            // ...and another to a confirmed Builtin (pins on handoff).
            let _ = e.decide_at("aa:02", true, t0);
            let _ = e.decide_at("aa:02", true, t0 + Duration::from_mins(1));
            e.confirm_at("aa:02", t0 + Duration::from_secs(61));
        }
        // "Restart": a fresh instance from the same work_dir knows both.
        let e2 = DriverEscalation::load_or_default(dir.path());
        assert_eq!(e2.decide_at("aa:01", true, t0), DriverMode::Shim);
        assert_eq!(e2.decide_at("aa:02", true, t0), DriverMode::Builtin);
        // Unlearned MACs still start at the default.
        assert_eq!(e2.decide_at("aa:03", true, t0), DriverMode::Firmware);
    }
    #[test]
    fn corrupt_persistence_file_starts_empty() {
        let dir = tempdir().unwrap();
        std::fs::write(dir.path().join("driver_modes.json"), b"{broken").unwrap();
        let e = DriverEscalation::load_or_default(dir.path());
        assert_eq!(
            e.decide_at("aa:bb", true, Instant::now()),
            DriverMode::Firmware
        );
    }
    #[test]
    fn confirmed_firmware_is_not_persisted() {
        // The default mode is never written — the file only carries
        // exceptions, so a healthy fleet leaves it absent/empty.
        let dir = tempdir().unwrap();
        let t0 = Instant::now();
        {
            let e = DriverEscalation::load_or_default(dir.path());
            let _ = e.decide_at("aa:09", true, t0);
            e.confirm_at("aa:09", t0 + Duration::from_secs(2));
        }
        assert!(!dir.path().join("driver_modes.json").exists());
    }
 }
@@ -17,7 +17,9 @@
 //!   clients silently drop them.
 #![forbid(unsafe_code)]
 pub mod escalation;
 pub mod reply;
 pub mod server;
 pub use escalation::DriverEscalation;
 pub use server::DhcpProxyServer;
@@ -9,7 +9,7 @@
 //!     pass, or the HTTP URL of the boot script once iPXE has chained.
 use dhcproto::v4::{DhcpOption, Message, MessageType, Opcode, OptionCode};
-use openpxe_core::{ClientArch, FirmwareClass};
+use openpxe_core::{ClientArch, DriverMode, FirmwareClass};
 use std::net::Ipv4Addr;
 /// Where the reply directs the client next.
@@ -31,6 +31,11 @@ pub struct ReplyContext<'a> {
    pub our_ip: Ipv4Addr,
    pub arch: ClientArch,
    pub class: FirmwareClass,
    /// Which iPXE network backend to advertise for this client. The DHCP
    /// proxy fills this from the automatic per-MAC escalation state: normally
    /// [`DriverMode::Firmware`], escalated to [`DriverMode::Builtin`] for a
    /// MAC whose firmware-net boot failed to chainload (v0.6.1).
    pub driver_mode: DriverMode,
    /// Public base URL (scheme://host[:port]) used in HTTP directives.
    pub public_base_url: &'a str,
 }
@@ -44,17 +49,27 @@ pub fn decide(ctx: &ReplyContext<'_>) -> BootDirective {
            // Pass the client's MAC in the query string so the HTTP
            // layer can short-circuit to a per-MAC binding when one
            // exists. iPXE substitutes `${mac}` literally before issuing
-            // the GET, so this stays static across firmwares.
+            // the GET, so this stays static across firmwares. The arch is
            // known *here* from option 93, so it's baked in literally
            // (v0.7.0) — it lets boot rules select on architecture.
            url: format!(
-                "{}/boot.ipxe?mac=${{mac}}",
+                "{}/boot.ipxe?mac=${{mac}}&arch={}",
-                ctx.public_base_url.trim_end_matches('/')
+                ctx.public_base_url.trim_end_matches('/'),
                ctx.arch.as_str()
            ),
        },
        FirmwareClass::HttpClient => {
            // UEFI HTTP boot: client wants an http:// URL in option 67
-            // pointing at an EFI executable. We serve ipxe.efi over HTTP;
+            // pointing at an EFI executable. We serve the iPXE EFI build for
-            // it'll then do the same script-fetch the iPXE path does.
+            // the negotiated driver mode over HTTP; it'll then do the same
-            let name = ctx.arch.ipxe_bootfile().unwrap_or("snponly.efi");
+            // script-fetch the iPXE path does.
            // `bootfile_with_fallback` (v0.7.0) walks back down the
            // escalation ladder when the negotiated mode has no binary
            // for this arch (e.g. Shim on an arch with no signed chain).
            let name = ctx
                .arch
                .bootfile_with_fallback(ctx.driver_mode)
                .unwrap_or("snponly.efi");
            BootDirective::HttpScript {
                url: format!(
                    "{}/ipxe/{}",
@@ -63,7 +78,7 @@ pub fn decide(ctx: &ReplyContext<'_>) -> BootDirective {
                ),
            }
        }
-        FirmwareClass::PxeClient => match ctx.arch.ipxe_bootfile() {
+        FirmwareClass::PxeClient => match ctx.arch.bootfile_with_fallback(ctx.driver_mode) {
            Some(name) => BootDirective::TftpIpxe {
                filename: name.to_string(),
            },
@@ -1,10 +1,13 @@
 //! UDP listener loop for the DHCP proxy. Accepts on :67 (and :4011 on a
 //! second socket) and dispatches each datagram through the pure reply logic.
 use crate::escalation::DriverEscalation;
 use crate::reply::{build_reply, decide, BootDirective, ReplyContext};
 use dhcproto::v4::{DhcpOption, Message, OptionCode};
 use dhcproto::{Decodable, Decoder, Encodable, Encoder};
-use openpxe_core::{ClientArch, ClientEvent, ClientRegistry, FirmwareClass};
+use openpxe_core::{
    BootRulesStore, ClientArch, ClientEvent, ClientRegistry, DriverMode, FirmwareClass,
 };
 use socket2::{Domain, Protocol, Socket, Type};
 use std::net::{IpAddr, Ipv4Addr, SocketAddr, SocketAddrV4};
 use std::sync::Arc;
@@ -18,9 +21,19 @@ pub struct DhcpProxyServer {
    public_base_url: String,
    clients: Arc<ClientRegistry>,
    metrics: openpxe_core::Metrics,
    /// Automatic per-MAC NIC driver-mode escalation (v0.6.1; persistent
    /// learned modes since v0.7.1). Shared across the :67 and :4011
    /// listener tasks via the server `Arc`. Built by the caller so the
    /// persistence path comes from the configured work dir.
    escalation: DriverEscalation,
    /// v0.7.1: boot rules — consulted for an operator driver-mode pin
    /// (e.g. "this OUI is all Secure Boot → serve shim immediately")
    /// before the automatic escalation ladder.
    rules: BootRulesStore,
 }
 impl DhcpProxyServer {
    #[allow(clippy::too_many_arguments)]
    pub fn new(
        bind: IpAddr,
        dhcp_port: u16,
@@ -29,6 +42,8 @@ impl DhcpProxyServer {
        public_base_url: String,
        clients: Arc<ClientRegistry>,
        metrics: openpxe_core::Metrics,
        escalation: DriverEscalation,
        rules: BootRulesStore,
    ) -> Self {
        Self {
            bind,
@@ -38,6 +53,8 @@ impl DhcpProxyServer {
            public_base_url,
            clients,
            metrics,
            escalation,
            rules,
        }
    }
@@ -126,11 +143,38 @@ impl DhcpProxyServer {
            },
        );
        // Automatic NIC driver-mode selection (v0.6.1). The default is
        // firmware-net (snponly/undionly). A successful iPXE handoff confirms
        // the current mode works for this MAC; a fresh firmware boot whose
        // predecessor never handed off escalates the MAC to iPXE's built-in
        // NIC drivers. No operator toggle — the firmware path is unchanged so
        // hardware that already boots never regresses.
        let driver_mode = match class {
            FirmwareClass::IpxeUserClass => {
                self.escalation.mark_ipxe_success(&mac);
                DriverMode::Firmware // unused: this path serves the HTTP script
            }
            FirmwareClass::PxeClient | FirmwareClass::HttpClient => {
                // v0.7.1: an operator rule pin wins over (and bypasses)
                // the automatic escalation ladder — known Secure-Boot
                // fleets boot the signed chain on the very first cycle.
                if let Some(pinned) = self.rules.driver_mode_hint(&mac, Some(arch.as_str())) {
                    pinned
                } else {
                    self.escalation
                        .mode_for_firmware_attempt(&mac, label == "67")
                }
            }
            // Unreachable: FirmwareClass::Other returned above.
            FirmwareClass::Other => DriverMode::Firmware,
        };
        let ctx = ReplyContext {
            request: &request,
            our_ip: self.our_ip,
            arch,
            class,
            driver_mode,
            public_base_url: &self.public_base_url,
        };
        let directive = decide(&ctx);
@@ -154,7 +198,7 @@ impl DhcpProxyServer {
        sock.send_to(&out, dest).await?;
        tracing::info!(
            target: "openpxe::dhcp",
-            mac=%mac, arch=arch.as_str(), class=?class, dest=%dest, directive=?directive,
+            mac=%mac, arch=arch.as_str(), class=?class, driver=?driver_mode, dest=%dest, directive=?directive,
            "PXE reply sent"
        );
        Ok(())
@@ -213,11 +257,16 @@ fn bind_udp(bind: IpAddr, port: u16, broadcast: bool) -> anyhow::Result<UdpSocke
 }
 fn format_mac(chaddr: &[u8]) -> String {
-    let take = chaddr.iter().take(6).copied().collect::<Vec<_>>();
+    use std::fmt::Write;
-    take.iter()
+    // One allocation — this runs for every PXE datagram we answer.
-        .map(|b| format!("{b:02x}"))
+    let mut s = String::with_capacity(17);
-        .collect::<Vec<_>>()
+    for (i, b) in chaddr.iter().take(6).enumerate() {
-        .join(":")
+        if i > 0 {
            s.push(':');
        }
        let _ = write!(s, "{b:02x}");
    }
    s
 }
 /// Walk raw DHCP options looking for option 93 (Client System Architecture)
@@ -25,16 +25,12 @@ time.workspace = true
 axum.workspace = true
 tower.workspace = true
 tower-http.workspace = true
 hyper.workspace = true
 serde.workspace = true
 serde_json.workspace = true
 tracing.workspace = true
 thiserror.workspace = true
 anyhow.workspace = true
 bytes.workspace = true
 futures.workspace = true
 mime.workspace = true
 mime_guess.workspace = true
 uuid.workspace = true
 # v0.4.5 Forms auth: lock-free session store and cookie helpers.
 parking_lot.workspace = true
@@ -51,6 +47,10 @@ base64.workspace = true
 tokio = { workspace = true, features = ["macros", "rt", "rt-multi-thread", "time"] }
 tower = { workspace = true }
 tempfile = "3.12"
 # v0.7.4: probe-based introspection verifies kernel paths against the
 # real ISO9660 tree, so the full-flow tests synthesize images with the
 # shared test builder instead of label-only blobs.
 openpxe-iso-store = { workspace = true, features = ["test-image"] }
 serde_json = { workspace = true }
 time = { workspace = true }
 # v0.4.61: integration tests need to generate real PNG bytes for the
@@ -61,3 +61,9 @@ image = { version = "0.25", default-features = false, features = ["png"] }
 # replay, and IdP-initiated-gating flows exercise real signatures.
 rcgen = "0.13"
 bergshamra = { workspace = true }
 # v0.5.4: snapshot the generated iPXE menu so any unintended drift (a
 # dropped line, reordered item) is caught and reviewed, not silently shipped.
 insta = "1.40"
 # v0.5.4: stand up a mock HTTP server to exercise the SAML metadata-URL
 # fetch path (previously untested because it did a real network GET).
 wiremock = "0.6"
@@ -52,6 +52,12 @@ const SESSION_TTL: Duration = Duration::from_hours(24);
 /// to avoid collisions with anything else sharing the host.
 pub const SESSION_COOKIE: &str = "openpxe_session";
 /// Header an API client sends to authenticate without a browser session.
 /// Matches the de-facto `x-api-key` convention operators already use with
 /// other appliances. A valid key grants the same access as a logged-in
 /// operator. See [`crate::state::AppState::api_key`].
 pub const API_KEY_HEADER: &str = "x-api-key";
 #[derive(Debug, Clone)]
 struct Session {
    username: String,
@@ -154,16 +160,28 @@ pub fn session_cookie(session: &str) -> String {
 fn parse_cookie(headers: &axum::http::HeaderMap) -> Option<String> {
    // `Cookie: a=b; c=d` parsing — small enough not to drag in a crate.
    // Two-step strip (name, then '=') keeps this allocation-free per
    // candidate and can't match a longer cookie name sharing the prefix.
    let raw = headers.get(header::COOKIE)?.to_str().ok()?;
    for part in raw.split(';') {
        let part = part.trim();
-        if let Some(v) = part.strip_prefix(&format!("{SESSION_COOKIE}=")) {
+        if let Some(v) = part
            .strip_prefix(SESSION_COOKIE)
            .and_then(|rest| rest.strip_prefix('='))
        {
            return Some(v.to_string());
        }
    }
    None
 }
 /// Does this request carry a live operator session? Used by endpoints
 /// outside the `/api/*` middleware that still want to honor a logged-in
 /// operator (e.g. browser-testing a token-gated answer file, v0.7.0).
 pub(crate) fn session_authenticated(state: &AppState, headers: &axum::http::HeaderMap) -> bool {
    parse_cookie(headers).is_some_and(|t| state.sessions.touch(&t).is_some())
 }
 // ── Middleware ────────────────────────────────────────────────────────────
 /// Return `true` if `path` is on the allowlist and should bypass the
@@ -211,13 +229,18 @@ pub async fn require_auth(
    if is_public_path(path) {
        return next.run(req).await;
    }
-    // Authenticated path. The cookie must be present, map to a live
+    // Authenticated path: either a live operator session cookie (the
-    // session, and the TTL refresh happens as a side-effect.
+    // browser) or the x-api-key header (scripts / Postman). Touching the
-    let token = parse_cookie(req.headers());
+    // cookie refreshes its idle TTL as a side-effect.
-    if let Some(t) = token {
+    let session_ok =
-        if state.sessions.touch(&t).is_some() {
+        parse_cookie(req.headers()).is_some_and(|t| state.sessions.touch(&t).is_some());
-            return next.run(req).await;
+    let key_ok = req
-        }
+        .headers()
        .get(API_KEY_HEADER)
        .and_then(|v| v.to_str().ok())
        .is_some_and(|k| state.api_key.verify(k));
    if session_ok || key_ok {
        return next.run(req).await;
    }
    (
        StatusCode::UNAUTHORIZED,
@@ -246,7 +269,14 @@ pub async fn api_setup(State(state): State<AppState>, Json(body): Json<SetupBody
        )
            .into_response();
    }
-    match state.admin.bootstrap(&body.username, &body.password) {
+    // bcrypt hashing is ~100-200 ms of pure CPU (and `bootstrap` also
    // persists to disk synchronously) — keep it off the async workers.
    let admin = state.admin.clone();
    let result =
        tokio::task::spawn_blocking(move || admin.bootstrap(&body.username, &body.password))
            .await
            .unwrap_or_else(|e| Err(openpxe_core::Error::Other(e.into())));
    match result {
        Ok(pub_) => {
            let session = state.sessions.create(&pub_.username);
            login_response(StatusCode::CREATED, &pub_, &session)
@@ -271,8 +301,13 @@ pub struct LoginBody {
 pub async fn api_login(State(state): State<AppState>, Json(body): Json<LoginBody>) -> Response {
    // Brief, deliberately vague — "invalid credentials" rather than
    // "no such user" / "wrong password". Same anti-enumeration posture
-    // as Sonarr/Radarr.
+    // as Sonarr/Radarr. The bcrypt verify is ~100-200 ms of pure CPU on
-    let pub_ = match state.admin.verify(&body.username, &body.password) {
+    // an unauthenticated endpoint, so it runs on the blocking pool.
    let admin = state.admin.clone();
    let verdict = tokio::task::spawn_blocking(move || admin.verify(&body.username, &body.password))
        .await
        .unwrap_or_else(|e| Err(openpxe_core::Error::Other(e.into())));
    let pub_ = match verdict {
        Ok(Some(u)) => u,
        Ok(None) => {
            return (
@@ -319,6 +354,12 @@ pub async fn api_me(State(state): State<AppState>, headers: axum::http::HeaderMa
    // and the logo asset is public, so this leaks nothing sensitive.
    let has_custom_logo = state.branding.has_any_web_logo();
    let logo_rev = state.branding.logo_rev();
    // v0.5.9: ship the non-sensitive SSO descriptor with every /api/me so
    // the pre-auth login screen can render the "Sign in with …" button
    // reliably. Previously the button keyed off the auth-gated /api/sso,
    // which 401s when logged out — the button only survived on a stale
    // in-memory config and vanished on any fresh login-page load.
    let sso = state.sso.login_info();
    if !state.admin.is_configured() {
        return (
            StatusCode::OK,
@@ -327,6 +368,7 @@ pub async fn api_me(State(state): State<AppState>, headers: axum::http::HeaderMa
                "authenticated": false,
                "has_custom_logo": has_custom_logo,
                "logo_rev": logo_rev,
                "sso": sso,
            })),
        )
            .into_response();
@@ -343,6 +385,7 @@ pub async fn api_me(State(state): State<AppState>, headers: axum::http::HeaderMa
                "session_user": u,
                "has_custom_logo": has_custom_logo,
                "logo_rev": logo_rev,
                "sso": sso,
            })),
        )
            .into_response(),
@@ -353,6 +396,7 @@ pub async fn api_me(State(state): State<AppState>, headers: axum::http::HeaderMa
                "authenticated": false,
                "has_custom_logo": has_custom_logo,
                "logo_rev": logo_rev,
                "sso": sso,
            })),
        )
            .into_response(),
@@ -385,11 +429,18 @@ pub async fn api_update_credentials(
        )
            .into_response();
    }
-    let result = state.admin.update_credentials(
+    // Two bcrypt operations (verify current + hash new) plus a sync disk
-        &body.current_password,
+    // persist — run the lot on the blocking pool.
-        body.new_username.as_deref(),
+    let admin = state.admin.clone();
-        body.new_password.as_deref(),
+    let result = tokio::task::spawn_blocking(move || {
-    );
+        admin.update_credentials(
            &body.current_password,
            body.new_username.as_deref(),
            body.new_password.as_deref(),
        )
    })
    .await
    .unwrap_or_else(|e| Err(openpxe_core::Error::Other(e.into())));
    match result {
        Ok(pub_) => {
            state.sessions.revoke_all();
@@ -407,6 +458,28 @@ pub async fn api_update_credentials(
    }
 }
 /// Return the current operator API key plus the header to send it in.
 /// Gated by the auth middleware, so only a logged-in operator (or a
 /// caller already holding the key) can read it.
 pub async fn api_api_key_get(State(state): State<AppState>) -> Response {
    (
        StatusCode::OK,
        Json(json!({ "key": state.api_key.current(), "header": API_KEY_HEADER })),
    )
        .into_response()
 }
 /// Mint a fresh operator API key, invalidating the previous one, and
 /// return it. Same gating as the GET.
 pub async fn api_api_key_regenerate(State(state): State<AppState>) -> Response {
    let key = state.api_key.regenerate();
    (
        StatusCode::OK,
        Json(json!({ "key": key, "header": API_KEY_HEADER })),
    )
        .into_response()
 }
 #[derive(Debug, Serialize)]
 struct LoginPayload<'a> {
    user: &'a AdminPublic,
@@ -0,0 +1,92 @@
 //! Uniform HTTP error mapping for the API layer (v0.5.4).
 //!
 //! Before this, ~40 handlers in `app.rs` hand-wrote
 //! `match … { Err(e) => (StatusCode::…, format!("{e}")).into_response() }`,
 //! and the `openpxe_core::Error` → status mapping drifted between them
 //! (e.g. `Invalid` → 400 in most places, 404 in one). [`AppError`] wraps
 //! `openpxe_core::Error` so a handler can return `Result<T, AppError>` and
 //! `?` its way out, getting one consistent status + body. The body stays
 //! plain-text (matching the previous `(StatusCode, String)` responses) so
 //! existing clients and tests see no shape change; 5xx detail is logged
 //! and returned verbatim exactly as before.
 //!
 //! Handlers with *intentional* domain-specific statuses (e.g. a duplicate
 //! share → 409, a still-open chunked upload → 409) keep their explicit
 //! returns — `AppError` is for the common case, not a straitjacket.
 use axum::http::StatusCode;
 use axum::response::{IntoResponse, Response};
 use openpxe_core::Error as CoreError;
 /// Newtype over [`openpxe_core::Error`] with a uniform [`IntoResponse`].
 #[derive(Debug)]
 pub struct AppError(pub CoreError);
 impl From<CoreError> for AppError {
    fn from(e: CoreError) -> Self {
        AppError(e)
    }
 }
 impl From<std::io::Error> for AppError {
    fn from(e: std::io::Error) -> Self {
        AppError(CoreError::Io(e))
    }
 }
 impl AppError {
    /// The HTTP status this error maps to. Public so handlers (and tests)
    /// can reason about the mapping in one place.
    #[must_use]
    pub fn status(&self) -> StatusCode {
        match self.0 {
            CoreError::NotFound(_) => StatusCode::NOT_FOUND,
            CoreError::Invalid(_) => StatusCode::BAD_REQUEST,
            CoreError::Config(_) | CoreError::Io(_) | CoreError::Other(_) => {
                StatusCode::INTERNAL_SERVER_ERROR
            }
        }
    }
 }
 impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        let status = self.status();
        // Match the prior hand-written responses: the 4xx arms returned the
        // bare inner message (not the `Display` prefix), so a UI showing
        // `await r.text()` reads "metadata too long", not "invalid input:
        // metadata too long". 5xx keeps the full `Display` string.
        let body = match &self.0 {
            CoreError::Invalid(m) | CoreError::NotFound(m) => m.clone(),
            other => other.to_string(),
        };
        if status.is_server_error() {
            // Log the full detail server-side; the body still carries it
            // (unchanged from the prior `format!("{e}")` behaviour), but the
            // log line is what an operator greps for.
            tracing::error!(target: "openpxe::http", error = %self.0, "request failed");
        }
        (status, body).into_response()
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    #[test]
    fn status_mapping_is_consistent() {
        assert_eq!(
            AppError(CoreError::NotFound("x".into())).status(),
            StatusCode::NOT_FOUND
        );
        assert_eq!(
            AppError(CoreError::Invalid("x".into())).status(),
            StatusCode::BAD_REQUEST
        );
        assert_eq!(
            AppError(CoreError::Config("x".into())).status(),
            StatusCode::INTERNAL_SERVER_ERROR
        );
    }
 }
@@ -0,0 +1,485 @@
 //! Server-side "add ISO by URL" — stream a remote `.iso` straight into the
 //! store, reusing the chunked-upload handle + introspection pipeline so a
 //! URL-fetched image classifies and gains boot entries exactly like an
 //! uploaded one. A small in-memory job registry tracks progress; the web UI
 //! polls it and renders rows just like browser uploads.
 //!
 //! This is operator-initiated and auth-gated (`/api/*`), never runs at boot,
 //! and adds no CDN assets — so it doesn't touch OpenPXE's offline-boot
 //! guarantee. On an air-gapped network it simply goes unused (upload
 //! instead). It's the same class of optional outbound the server already
 //! makes for webhooks and the update check.
 use crate::state::AppState;
 use axum::{
    extract::{Path, State},
    http::{header, StatusCode},
    response::{IntoResponse, Response},
    Json,
 };
 use futures::StreamExt;
 use openpxe_core::{Error, Result};
 use openpxe_iso_store::IsoStore;
 use parking_lot::Mutex;
 use serde::{Deserialize, Serialize};
 use serde_json::json;
 use std::collections::HashMap;
 use std::sync::Arc;
 use std::time::{Duration, Instant};
 use uuid::Uuid;
 /// Hard ceiling on a URL-fetched image — matches the HTTP upload body cap
 /// (`DefaultBodyLimit` in `app.rs`).
 const MAX_ISO_BYTES: u64 = 16 * 1024 * 1024 * 1024;
 /// How long a finished-with-error job lingers so the operator can read the
 /// failure before it's swept. Successful jobs are read-once (see
 /// [`FetchJobs::snapshot`]).
 const FAILED_TTL: Duration = Duration::from_mins(10);
 #[derive(Clone)]
 enum Phase {
    Downloading,
    Done { iso_id: String },
    Failed { error: String },
    Canceled,
 }
 struct Job {
    /// Best-known target filename (provisional from the URL, refined once
    /// the response headers arrive).
    filename: String,
    /// Display-safe source URL — any `user:pass@` userinfo is stripped so
    /// the UI/logs never echo embedded credentials.
    url: String,
    downloaded: u64,
    /// Total bytes from `Content-Length`, or `0` when the server didn't
    /// send one (progress then shows bytes-so-far without a percentage).
    total: u64,
    phase: Phase,
    cancel: bool,
    finished_at: Option<Instant>,
 }
 /// One row in the fetch-progress list the UI polls.
 #[derive(Serialize)]
 pub struct JobDto {
    id: String,
    filename: String,
    url: String,
    downloaded: u64,
    total: u64,
    /// `downloading` | `done` | `failed` | `canceled`.
    state: &'static str,
    #[serde(skip_serializing_if = "Option::is_none")]
    iso_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    error: Option<String>,
 }
 /// In-memory registry of in-flight and recently-finished URL fetches.
 /// Cheap to clone (Arc-shared); contention is nil (a handful of jobs, brief
 /// per-chunk progress bumps).
 #[derive(Clone, Default)]
 pub struct FetchJobs {
    inner: Arc<Mutex<HashMap<String, Arc<Mutex<Job>>>>>,
 }
 impl FetchJobs {
    /// Validate the URL, register a job, and spawn the background download.
    /// Returns the job id. Fails fast on a bad/unsupported URL so the POST
    /// gets an immediate error instead of a job that dies a moment later.
    pub fn start(
        &self,
        store: IsoStore,
        raw_url: &str,
        filename_hint: Option<&str>,
    ) -> Result<String> {
        let (url, display) = parse_and_sanitize(raw_url)?;
        // Provisional filename for the first render; the task refines it
        // from Content-Disposition / the post-redirect URL.
        let provisional = filename_hint
            .map(sanitize_filename)
            .or_else(|| basename(&url))
            .unwrap_or_else(|| "download.iso".to_string());
        let id = Uuid::new_v4().simple().to_string();
        let job = Arc::new(Mutex::new(Job {
            filename: provisional,
            url: display,
            downloaded: 0,
            total: 0,
            phase: Phase::Downloading,
            cancel: false,
            finished_at: None,
        }));
        self.inner.lock().insert(id.clone(), job.clone());
        let hint = filename_hint.map(str::to_string);
        tokio::spawn(async move {
            if let Err(e) = download(&store, &job, url, hint).await {
                let mut g = job.lock();
                // A cancel flips the phase itself; don't overwrite it.
                if !matches!(g.phase, Phase::Canceled) {
                    g.phase = Phase::Failed {
                        error: format!("{e}"),
                    };
                }
                g.finished_at = Some(Instant::now());
            }
        });
        Ok(id)
    }
    /// Snapshot every job for the UI, then sweep the terminal ones:
    /// `Done`/`Canceled` are **read-once** (removed after this call, so the
    /// UI reacts to completion exactly once and never loops on a lingering
    /// "done" row), while `Failed` is retained until [`FAILED_TTL`] so the
    /// error stays visible.
    pub fn snapshot(&self) -> Vec<JobDto> {
        let mut g = self.inner.lock();
        let mut out = Vec::with_capacity(g.len());
        for (id, job) in g.iter() {
            let j = job.lock();
            let (state, iso_id, error) = match &j.phase {
                Phase::Downloading => ("downloading", None, None),
                Phase::Done { iso_id } => ("done", Some(iso_id.clone()), None),
                Phase::Failed { error } => ("failed", None, Some(error.clone())),
                Phase::Canceled => ("canceled", None, None),
            };
            out.push(JobDto {
                id: id.clone(),
                filename: j.filename.clone(),
                url: j.url.clone(),
                downloaded: j.downloaded,
                total: j.total,
                state,
                iso_id,
                error,
            });
        }
        let now = Instant::now();
        g.retain(|_, job| {
            let j = job.lock();
            match &j.phase {
                Phase::Downloading => true,
                Phase::Done { .. } | Phase::Canceled => false, // read-once
                Phase::Failed { .. } => j
                    .finished_at
                    .is_none_or(|t| now.duration_since(t) < FAILED_TTL),
            }
        });
        out
    }
    /// Cancel an in-flight download, or dismiss a terminal one. Returns
    /// `true` if a job with that id existed.
    pub fn cancel(&self, id: &str) -> bool {
        let g = self.inner.lock();
        let Some(job) = g.get(id) else { return false };
        let mut j = job.lock();
        if matches!(j.phase, Phase::Downloading) {
            j.cancel = true; // the download loop checks this each chunk
        } else {
            drop(j);
            drop(g);
            self.inner.lock().remove(id);
        }
        true
    }
 }
 /// The background download: GET the URL, derive + validate the filename,
 /// then stream the body through an `UploadHandle` (which hashes, writes the
 /// `.partial`, and on `finish` renames + introspects).
 async fn download(
    store: &IsoStore,
    job: &Arc<Mutex<Job>>,
    url: reqwest::Url,
    filename_hint: Option<String>,
 ) -> Result<()> {
    let client = reqwest::Client::builder()
        .connect_timeout(Duration::from_secs(15))
        .user_agent(concat!("OpenPXE/", env!("CARGO_PKG_VERSION")))
        .build()
        .map_err(|e| Error::Other(e.into()))?;
    let resp = client
        .get(url)
        .send()
        .await
        .map_err(|e| Error::Invalid(format!("request failed: {e}")))?;
    if !resp.status().is_success() {
        return Err(Error::Invalid(format!("server returned {}", resp.status())));
    }
    let cd = resp
        .headers()
        .get(header::CONTENT_DISPOSITION)
        .and_then(|v| v.to_str().ok());
    let filename = pick_filename(filename_hint.as_deref(), cd, resp.url())?;
    let total = resp.content_length().unwrap_or(0);
    if total > MAX_ISO_BYTES {
        return Err(Error::Invalid(format!(
            "declared size {total} exceeds the {MAX_ISO_BYTES}-byte cap"
        )));
    }
    {
        let mut g = job.lock();
        g.filename.clone_from(&filename);
        g.total = total;
    }
    let mut handle = store.begin_upload(&filename).await?;
    let mut stream = resp.bytes_stream();
    let mut received: u64 = 0;
    while let Some(item) = stream.next().await {
        if job.lock().cancel {
            let _ = handle.abort().await;
            job.lock().phase = Phase::Canceled;
            job.lock().finished_at = Some(Instant::now());
            return Ok(());
        }
        let chunk = item.map_err(|e| Error::Invalid(format!("transfer error: {e}")))?;
        received += chunk.len() as u64;
        if received > MAX_ISO_BYTES {
            let _ = handle.abort().await;
            return Err(Error::Invalid(format!(
                "download exceeded the {MAX_ISO_BYTES}-byte cap"
            )));
        }
        if let Err(e) = handle.write_chunk(&chunk).await {
            let _ = handle.abort().await;
            return Err(e);
        }
        job.lock().downloaded = received;
    }
    let meta = handle.finish(store).await?;
    tracing::info!(
        target: "openpxe::http::fetch",
        filename = %filename, bytes = received, family = ?meta.introspection.family,
        "fetched ISO from URL"
    );
    let mut g = job.lock();
    g.downloaded = received;
    g.phase = Phase::Done { iso_id: meta.id };
    g.finished_at = Some(Instant::now());
    Ok(())
 }
 /// Parse the URL, require an `http`/`https` scheme (no `file:`/`gopher:`/…),
 /// and return it alongside a credential-stripped display form.
 fn parse_and_sanitize(raw: &str) -> Result<(reqwest::Url, String)> {
    let url = reqwest::Url::parse(raw.trim())
        .map_err(|_| Error::Invalid("not a valid URL".to_string()))?;
    if !matches!(url.scheme(), "http" | "https") {
        return Err(Error::Invalid(
            "only http:// and https:// URLs are accepted".to_string(),
        ));
    }
    let mut display = url.clone();
    let _ = display.set_username("");
    let _ = display.set_password(None);
    Ok((url, display.to_string()))
 }
 /// Choose the target filename: explicit hint > `Content-Disposition` >
 /// post-redirect URL basename. Must end in `.iso` (case-insensitive).
 fn pick_filename(
    explicit: Option<&str>,
    content_disposition: Option<&str>,
    final_url: &reqwest::Url,
 ) -> Result<String> {
    let candidate = explicit
        .map(sanitize_filename)
        .or_else(|| content_disposition.and_then(filename_from_disposition))
        .or_else(|| basename(final_url))
        .ok_or_else(|| Error::Invalid("could not determine a filename".to_string()))?;
    if !candidate.to_ascii_lowercase().ends_with(".iso") {
        return Err(Error::Invalid(format!(
            "URL does not point at an .iso (got '{candidate}')"
        )));
    }
    Ok(candidate)
 }
 /// Last path segment of a URL, percent-decoded and reduced to a bare
 /// filename. `None` for a pathless URL.
 fn basename(url: &reqwest::Url) -> Option<String> {
    let seg = url.path_segments()?.next_back()?;
    if seg.is_empty() {
        return None;
    }
    let decoded = percent_decode(seg);
    Some(sanitize_filename(&decoded))
 }
 /// Pull `filename="x.iso"` (or bare `filename=x.iso`) out of a
 /// `Content-Disposition` header. RFC 5987 `filename*` is ignored — the
 /// common case is enough, and the URL basename is the fallback.
 fn filename_from_disposition(cd: &str) -> Option<String> {
    let idx = cd.to_ascii_lowercase().find("filename=")?;
    let rest = &cd[idx + "filename=".len()..];
    let val = rest.trim_start().trim_start_matches('"');
    let end = val.find(['"', ';']).unwrap_or(val.len());
    let name = val[..end].trim();
    if name.is_empty() {
        None
    } else {
        Some(sanitize_filename(name))
    }
 }
 /// Reduce any path-ish string to a safe bare filename: last component only,
 /// no `/`, `\`, or NULs. Prevents a crafted `Content-Disposition`/URL from
 /// escaping the ISO directory.
 fn sanitize_filename(s: &str) -> String {
    s.rsplit(['/', '\\'])
        .next()
        .unwrap_or(s)
        .replace('\0', "")
        .trim()
        .to_string()
 }
 /// Minimal percent-decoding for a single path segment (enough for `%20`
 /// spaces in an ISO name); leaves malformed escapes untouched.
 fn percent_decode(s: &str) -> String {
    let bytes = s.as_bytes();
    let mut out = Vec::with_capacity(bytes.len());
    let mut i = 0;
    while i < bytes.len() {
        if bytes[i] == b'%' && i + 2 < bytes.len() {
            if let (Some(h), Some(l)) = (hexval(bytes[i + 1]), hexval(bytes[i + 2])) {
                out.push(h << 4 | l);
                i += 3;
                continue;
            }
        }
        out.push(bytes[i]);
        i += 1;
    }
    String::from_utf8_lossy(&out).into_owned()
 }
 fn hexval(b: u8) -> Option<u8> {
    match b {
        b'0'..=b'9' => Some(b - b'0'),
        b'a'..=b'f' => Some(b - b'a' + 10),
        b'A'..=b'F' => Some(b - b'A' + 10),
        _ => None,
    }
 }
 // ── Handlers ──────────────────────────────────────────────────────────────
 #[derive(Deserialize)]
 pub struct FetchBody {
    pub url: String,
    #[serde(default)]
    pub filename: Option<String>,
 }
 /// `POST /api/isos/fetch` — start a URL download.
 pub async fn api_iso_fetch_start(
    State(state): State<AppState>,
    Json(body): Json<FetchBody>,
 ) -> Response {
    match state
        .fetch_jobs
        .start(state.iso_store.clone(), &body.url, body.filename.as_deref())
    {
        Ok(id) => (StatusCode::ACCEPTED, Json(json!({ "fetch_id": id }))).into_response(),
        Err(Error::Invalid(msg)) => {
            (StatusCode::BAD_REQUEST, Json(json!({ "error": msg }))).into_response()
        }
        Err(e) => (
            StatusCode::INTERNAL_SERVER_ERROR,
            Json(json!({ "error": format!("{e}") })),
        )
            .into_response(),
    }
 }
 /// `GET /api/isos/fetch` — poll progress. Successful jobs appear once.
 pub async fn api_iso_fetch_list(State(state): State<AppState>) -> Response {
    (
        StatusCode::OK,
        Json(json!({ "jobs": state.fetch_jobs.snapshot() })),
    )
        .into_response()
 }
 /// `DELETE /api/isos/fetch/{id}` — cancel an in-flight download or dismiss a
 /// finished/failed row.
 pub async fn api_iso_fetch_cancel(
    State(state): State<AppState>,
    Path(id): Path<String>,
 ) -> Response {
    if state.fetch_jobs.cancel(&id) {
        StatusCode::NO_CONTENT.into_response()
    } else {
        (
            StatusCode::NOT_FOUND,
            Json(json!({ "error": "no such fetch job" })),
        )
            .into_response()
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    #[test]
    fn scheme_is_restricted_and_credentials_are_stripped() {
        assert!(parse_and_sanitize("file:///etc/passwd").is_err());
        assert!(parse_and_sanitize("gopher://x/1").is_err());
        assert!(parse_and_sanitize("not a url").is_err());
        let (_, display) = parse_and_sanitize("https://user:[email protected]/a.iso").unwrap();
        assert!(
            !display.contains("secret"),
            "credentials must be stripped: {display}"
        );
        assert!(display.starts_with("https://example.com/"));
    }
    #[test]
    fn filename_prefers_explicit_then_disposition_then_url() {
        let u = reqwest::Url::parse("https://example.com/path/final.iso").unwrap();
        // Explicit wins, and path traversal is stripped.
        assert_eq!(
            pick_filename(Some("../../evil/custom.iso"), None, &u).unwrap(),
            "custom.iso"
        );
        // Content-Disposition next.
        assert_eq!(
            pick_filename(None, Some(r#"attachment; filename="rescue.iso""#), &u).unwrap(),
            "rescue.iso"
        );
        // URL basename fallback (with percent-decoding).
        let sp = reqwest::Url::parse("https://example.com/System%20Rescue.iso").unwrap();
        assert_eq!(pick_filename(None, None, &sp).unwrap(), "System Rescue.iso");
        // Non-.iso is rejected.
        assert!(pick_filename(
            None,
            None,
            &reqwest::Url::parse("https://x/y.tar.gz").unwrap()
        )
        .is_err());
    }
    #[test]
    fn disposition_parsing_handles_quotes_and_bare() {
        assert_eq!(
            filename_from_disposition(r#"attachment; filename="a.iso"; size=1"#).as_deref(),
            Some("a.iso")
        );
        assert_eq!(
            filename_from_disposition("inline; filename=b.iso").as_deref(),
            Some("b.iso")
        );
        assert_eq!(filename_from_disposition("attachment").as_deref(), None);
    }
 }
@@ -0,0 +1,192 @@
 //! GRUB menu rendering for the Secure Boot chain (v0.7.0).
 //!
 //! Secure-Boot-enabled firmware refuses our unsigned iPXE, so those
 //! clients are automatically escalated (see `openpxe_dhcp_proxy::
 //! escalation`) to the Microsoft-signed Fedora `shim` → signed `grub`
 //! chain. GRUB then fetches `grub.cfg` from this server (TFTP `$prefix`
 //! resolution, or HTTP when the whole chain came over HTTP Boot) — and
 //! this module renders that config from the same boot-entry model that
 //! renders `boot.ipxe`.
 //!
 //! Scope: **Linux kernel entries only.** A signed GRUB will only execute
 //! kernels that pass shim verification — i.e. distro-signed kernels —
 //! which is exactly what `LinuxKernel` boot entries point at. `sanboot`
 //! ISO emulation and `wimboot` are iPXE mechanisms with no signed
 //! equivalent; those entries are omitted here, and the menu says so.
 //! (Windows deployment under Secure Boot has no legitimate unsigned
 //! path — per project policy we never ship test-signed binaries or touch
 //! client trust stores.)
 //!
 //! The kernel/initrd lines use GRUB's `(http,host:port)` device syntax;
 //! Fedora's signed netboot GRUB carries the `http`, `tftp` and `efinet`
 //! modules built in, so no unsigned module loading is required.
 use openpxe_iso_store::{BootKind, IsoMeta};
 use std::fmt::Write as _;
 /// Render the full `grub.cfg` for the signed-GRUB menu.
 ///
 /// `base_url` is the public HTTP base (`http://10.0.0.5` or
 /// `http://10.0.0.5:8080`) — converted to GRUB's `(http,host:port)`
 /// device prefix for kernel/initrd fetches.
 #[must_use]
 pub fn render_grub_menu(isos: &[IsoMeta], base_url: &str) -> String {
    let base = base_url.trim_end_matches('/');
    let dev = grub_http_device(base);
    let mut s = String::new();
    let _ = writeln!(s, "# OpenPXE — Secure Boot menu (signed shim+GRUB chain)");
    // v0.7.1: before showing the limited signed menu, try to hand the
    // boot back to full iPXE *in this same boot cycle*. With Secure Boot
    // OFF the chainload succeeds and the client gets the complete iPXE
    // feature set (sanboot, wimboot, the full menu) despite having been
    // escalated here. With Secure Boot ON, shim's verifier refuses the
    // unsigned image INLINE — no reboot, no failed cycle — and execution
    // falls through to the signed menu below. The all-drivers build is
    // used because a MAC only lands here after the firmware-net build
    // already failed once.
    let _ = writeln!(s, "if [ \"$grub_cpu\" = \"arm64\" ]; then");
    let _ = writeln!(s, "    set openpxe_ipxe=ipxe-arm64.efi");
    let _ = writeln!(s, "else");
    let _ = writeln!(s, "    set openpxe_ipxe=ipxe.efi");
    let _ = writeln!(s, "fi");
    let _ = writeln!(s, "if chainloader {dev}/ipxe/$openpxe_ipxe ; then");
    let _ = writeln!(s, "    boot");
    let _ = writeln!(s, "fi");
    let _ = writeln!(s);
    let _ = writeln!(s, "set timeout=30");
    let _ = writeln!(s, "set default=0");
    let _ = writeln!(s);
    let mut entries = 0usize;
    for iso in isos {
        for entry in &iso.boot_entries {
            let BootKind::LinuxKernel {
                kernel_url,
                initrd_urls,
                args,
            } = &entry.kind
            else {
                continue;
            };
            // GRUB menu titles: keep quotes out of the label.
            let title = entry.title.replace('"', "'");
            let cmdline = args.cmdline.replace("${base-url}", base);
            let _ = writeln!(s, "menuentry \"{} — {title}\" {{", iso.filename);
            let _ = writeln!(s, "    linux {dev}/{kernel_url} {cmdline}");
            if !initrd_urls.is_empty() {
                let _ = write!(s, "    initrd");
                for u in initrd_urls {
                    let _ = write!(s, " {dev}/{u}");
                }
                let _ = writeln!(s);
            }
            let _ = writeln!(s, "}}");
            let _ = writeln!(s);
            entries += 1;
        }
    }
    if entries == 0 {
        let _ = writeln!(
            s,
            "menuentry \"No Secure-Boot-bootable images on this server yet\" {{ true }}"
        );
        let _ = writeln!(s);
    }
    // Always give the operator a way off this screen.
    let _ = writeln!(s, "menuentry \"Boot from local disk\" {{");
    let _ = writeln!(s, "    exit");
    let _ = writeln!(s, "}}");
    s
 }
 /// `http://10.0.0.5:8080` → `(http,10.0.0.5:8080)`. GRUB wants the
 /// scheme as the device type and host[:port] as the device address.
 fn grub_http_device(base: &str) -> String {
    let host = base
        .trim_start_matches("http://")
        .trim_start_matches("https://");
    format!("(http,{host})")
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    use openpxe_iso_store::{BootEntry, IsoSource, KernelArgs};
    fn linux_iso() -> IsoMeta {
        IsoMeta {
            id: "alp".into(),
            filename: "alpine.iso".into(),
            size_bytes: 1,
            sha256_hex: None,
            uploaded_at: time::OffsetDateTime::UNIX_EPOCH,
            source: IsoSource::Local,
            introspection: openpxe_iso_store::IntrospectionReport::default(),
            boot_entries: vec![BootEntry {
                id: "alp-linux".into(),
                title: "Linux installer".into(),
                kind: BootKind::LinuxKernel {
                    kernel_url: "iso/alp/boot/vmlinuz".into(),
                    initrd_urls: vec!["iso/alp/boot/initrd".into()],
                    args: KernelArgs {
                        cmdline: "quiet repo=${base-url}/iso/alp.iso".into(),
                    },
                },
            }],
            category: openpxe_iso_store::IsoCategory::default(),
            password_hash: None,
        }
    }
    #[test]
    fn renders_linux_entries_with_http_device_urls() {
        let cfg = render_grub_menu(&[linux_iso()], "http://10.0.0.5:8080/");
        assert!(
            cfg.contains("menuentry \"alpine.iso — Linux installer\""),
            "{cfg}"
        );
        assert!(
            cfg.contains("linux (http,10.0.0.5:8080)/iso/alp/boot/vmlinuz quiet repo=http://10.0.0.5:8080/iso/alp.iso"),
            "{cfg}"
        );
        assert!(
            cfg.contains("initrd (http,10.0.0.5:8080)/iso/alp/boot/initrd"),
            "{cfg}"
        );
        assert!(cfg.contains("Boot from local disk"), "{cfg}");
    }
    #[test]
    fn config_tries_ipxe_chainload_before_menu() {
        // v0.7.1: SB-off machines recover full iPXE in the same boot;
        // SB-on machines fail the chainload inline and reach the menu.
        let cfg = render_grub_menu(&[linux_iso()], "http://10.0.0.5:8080");
        let chain_pos = cfg
            .find("if chainloader (http,10.0.0.5:8080)/ipxe/$openpxe_ipxe ; then")
            .expect("chainload attempt missing");
        let menu_pos = cfg.find("menuentry").expect("menu missing");
        assert!(
            chain_pos < menu_pos,
            "chainload must precede the menu:\n{cfg}"
        );
        // Arch-conditional binary selection via GRUB's $grub_cpu.
        assert!(cfg.contains("set openpxe_ipxe=ipxe-arm64.efi"), "{cfg}");
        assert!(cfg.contains("set openpxe_ipxe=ipxe.efi"), "{cfg}");
    }
    #[test]
    fn sanboot_and_wimboot_entries_are_omitted() {
        let mut iso = linux_iso();
        iso.boot_entries = vec![BootEntry {
            id: "win".into(),
            title: "Windows".into(),
            kind: BootKind::SanBootIso {
                iso_url: "iso/win.iso".into(),
            },
        }];
        let cfg = render_grub_menu(&[iso], "http://10.0.0.5");
        assert!(!cfg.contains("Windows"), "{cfg}");
        assert!(cfg.contains("No Secure-Boot-bootable images"), "{cfg}");
    }
 }
@@ -61,16 +61,24 @@ pub fn render_menu(isos: &[IsoMeta], settings: &Settings, base_url: &str) -> Str
    // returns a full-screen 1024×768 PNG now — the operator's logo on a
    // dark field, or a default OpenPXE mark when none is uploaded. The
    // `--top 290` reserves the top band (where the logo paints) so the
-    // menu text lands below it. On an iPXE build *with* `IMAGE_PNG` +
+    // menu text lands below it.
-    // `CONSOLE_FRAMEBUFFER` (our x86_64 UEFI binaries, built from source
+    //
-    // — see deploy/docker/Dockerfile) this paints the background and
+    // v0.5.7: gate the whole command behind `iseq ${platform} efi`.
-    // overlays the menu. On a build *without* PNG support (the fetched
+    // `console --picture` needs IMAGE_PNG + CONSOLE_FRAMEBUFFER, which
-    // BIOS/i386/arm64 binaries) the whole `console --picture …` command
+    // only our from-source UEFI binaries carry (x86_64/arm64 UEFI — see
-    // fails and the `|| console` resets to a clean full-screen text
+    // deploy/docker/Dockerfile). The fetched BIOS `undionly.kpxe` has
-    // menu. Either way there's no ASCII placeholder anymore.
+    // neither, and on legacy BIOS the `--picture` attempt misbehaves
    // *before* the trailing `|| console` fallback can recover (it tries
    // to set a framebuffer mode the BIOS console can't honour). Guarding
    // on platform means BIOS clients never issue the command at all —
    // they drop straight to the plain text menu — while UEFI clients
    // still get the graphical background. A PNG-less UEFI build (e.g. the
    // upstream i386-efi baseline) still falls back gracefully through the
    // same `|| console`. No operator toggle needed; mixed BIOS+UEFI
    // fleets each get the right treatment automatically.
    let _ = writeln!(
        s,
-        "console --picture {base}/branding/pxe-logo --top 290 || console"
+        "iseq ${{platform}} efi && console --picture {base}/branding/pxe-logo --top 290 || console"
    );
    // Map iPXE's ${{buildarch}} + ${{platform}} into the human form the
    // user asked for (e.g. "x86 BIOS", "x86_64 UEFI", "arm64 UEFI").
@@ -101,12 +109,13 @@ pub fn render_menu(isos: &[IsoMeta], settings: &Settings, base_url: &str) -> Str
    } else {
        let _ = writeln!(s, "item --gap -- (no Linux ISOs uploaded)");
    }
-    if settings.windows_enabled && has_family(isos, is_windows_family) {
+    // v0.5.8: Windows just works — no Settings toggle. Show the Windows
    // installers submenu whenever a Windows ISO is present; entries boot
    // via HTTP sanboot of the raw ISO, so no SMB/extraction is required.
    if has_family(isos, is_windows_family) {
        let _ = writeln!(s, "item windows          Windows Installers  >");
    } else if settings.windows_enabled {
        let _ = writeln!(s, "item --gap -- (no Windows ISOs uploaded)");
    } else {
-        let _ = writeln!(s, "item --gap -- (Windows support disabled in Settings)");
+        let _ = writeln!(s, "item --gap -- (no Windows ISOs uploaded)");
    }
    let _ = writeln!(
        s,
@@ -693,6 +702,22 @@ mod password_tests {
        assert!(s.contains("arm64 UEFI"), "{s}");
    }
    // v0.5.4: a full snapshot of the rendered top menu. The fragment
    // `assert!`s above check specific invariants; this catches *any* other
    // drift (a reordered item, a dropped line, changed spacing) so it's
    // reviewed deliberately. The OpenPXE version is filtered out so the
    // snapshot doesn't churn on every release bump.
    #[test]
    fn render_menu_snapshot() {
        // Normalize the compile-time version so the snapshot doesn't churn
        // on every release bump (no insta `filters` feature needed).
        let rendered = render_menu(&[], &Settings::default(), "http://10.0.0.5").replace(
            concat!("OpenPXE v", env!("CARGO_PKG_VERSION")),
            "OpenPXE vX.Y.Z",
        );
        insta::assert_snapshot!(rendered);
    }
    #[test]
    fn generated_scripts_do_not_emit_bare_or_trailing_fallbacks() {
        let settings = Settings::default();
@@ -1,135 +0,0 @@
 //! Minimal read-only ISO9660 lookup. Given an uploaded ISO file and an
 //! in-ISO path (e.g. `/casper/vmlinuz`), locate the file and return a
 //! `(start_byte, length_bytes)` pair so the HTTP handler can stream just
 //! that range from the on-disk ISO without full extraction.
 //!
 //! We only implement what we need: the Primary Volume Descriptor and Rock
 //! Ridge / Joliet extensions are ignored. Paths are matched case-insensitive
 //! against plain ISO9660 filenames (uppercase, `;1` version suffix stripped).
 //! This is sufficient for the kernel/initrd and wimboot files we serve;
 //! if a requested path isn't found, the handler returns 404 and the user
 //! can still download the whole ISO via `/iso/<id>.iso`.
 use std::io::{Read, Seek, SeekFrom};
 use std::path::Path;
 const SECTOR: u64 = 2048;
 #[derive(Debug, Clone)]
 pub struct FileLocation {
    pub offset: u64,
    pub length: u64,
 }
 /// Look up `in_iso_path` (leading slash optional, case-insensitive) in the
 /// ISO at `iso_path`. Returns None on any parsing or IO failure.
 pub fn lookup(iso_path: &Path, in_iso_path: &str) -> Option<FileLocation> {
    let mut f = std::fs::File::open(iso_path).ok()?;
    let root = read_root_directory(&mut f)?;
    let components: Vec<&str> = in_iso_path
        .trim_start_matches('/')
        .split('/')
        .filter(|c| !c.is_empty())
        .collect();
    if components.is_empty() {
        return None;
    }
    walk(&mut f, root.offset, root.length, &components)
 }
 fn read_root_directory(f: &mut std::fs::File) -> Option<FileLocation> {
    // Primary Volume Descriptor at LBA 16.
    let mut pvd = [0u8; 2048];
    f.seek(SeekFrom::Start(16 * SECTOR)).ok()?;
    f.read_exact(&mut pvd).ok()?;
    if pvd[0] != 0x01 || &pvd[1..6] != b"CD001" {
        return None;
    }
    // Root directory record is at offset 156, length 34.
    let rec = &pvd[156..156 + 34];
    let (offset, length) = parse_dir_record_ext(rec)?;
    Some(FileLocation {
        offset: offset * SECTOR,
        length,
    })
 }
 /// Walk components down the directory tree starting at `dir_offset`.
 fn walk(
    f: &mut std::fs::File,
    dir_offset: u64,
    dir_len: u64,
    components: &[&str],
 ) -> Option<FileLocation> {
    let mut dir = vec![0u8; dir_len as usize];
    f.seek(SeekFrom::Start(dir_offset)).ok()?;
    f.read_exact(&mut dir).ok()?;
    let target = components[0];
    let rest = &components[1..];
    let mut i = 0;
    while i < dir.len() {
        let len = dir[i] as usize;
        if len == 0 {
            // Padding to sector boundary.
            let next = (i / SECTOR as usize + 1) * SECTOR as usize;
            if next <= i {
                break;
            }
            i = next;
            continue;
        }
        if i + len > dir.len() {
            break;
        }
        let rec = &dir[i..i + len];
        let name = dir_record_name(rec);
        let is_dir = (rec.get(25).copied().unwrap_or(0) & 0x02) != 0;
        // Skip "." (0x00) and ".." (0x01) pseudo-entries.
        let is_pseudo = matches!(rec.get(32).copied(), Some(1))
            && rec.get(33).copied() == Some(0x00)
            || matches!(rec.get(32).copied(), Some(1)) && rec.get(33).copied() == Some(0x01);
        if !is_pseudo && name.eq_ignore_ascii_case(target) {
            let (child_off, child_len) = parse_dir_record_ext(rec)?;
            if rest.is_empty() && !is_dir {
                return Some(FileLocation {
                    offset: child_off * SECTOR,
                    length: child_len,
                });
            } else if !rest.is_empty() && is_dir {
                return walk(f, child_off * SECTOR, child_len, rest);
            }
        }
        i += len;
    }
    None
 }
 /// Extract (extent LBA, data length in bytes) from a directory record.
 /// Layout per ISO9660: bytes 2..10 extent LBA (LE+BE duplicate), 10..18
 /// data length (LE+BE duplicate). We trust the little-endian copy.
 fn parse_dir_record_ext(rec: &[u8]) -> Option<(u64, u64)> {
    if rec.len() < 34 {
        return None;
    }
    let lba = u32::from_le_bytes(rec[2..6].try_into().ok()?) as u64;
    let len = u32::from_le_bytes(rec[10..14].try_into().ok()?) as u64;
    Some((lba, len))
 }
 /// Extract the identifier from a directory record, stripping ISO9660's
 /// `;1` version suffix.
 fn dir_record_name(rec: &[u8]) -> String {
    let name_len = *rec.get(32).unwrap_or(&0) as usize;
    if name_len == 0 || rec.len() < 33 + name_len {
        return String::new();
    }
    let raw = &rec[33..33 + name_len];
    let s = String::from_utf8_lossy(raw).to_string();
    // Strip `;N` version suffix.
    if let Some(i) = s.rfind(';') {
        s[..i].to_string()
    } else {
        s
    }
 }
@@ -9,14 +9,17 @@
 //!     and Linux kernel/initrd, without having to
 //!     re-extract on every request)
 //!
-//! The `<id>/<path>` handler uses a read-only ISO9660 shim (see `iso_fs`)
+//! The `<id>/<path>` handler uses the read-only ISO9660 walker from
-//! that lseeks into the ISO on disk — so we never keep extracted copies.
+//! `openpxe_iso_store::iso_fs` — seeking into the image wherever it
 //! lives (local disk, NFS, SFTP), so we never keep extracted copies.
 #![forbid(unsafe_code)]
 pub mod app;
 pub mod auth;
 pub mod error;
 pub mod fetch;
 pub mod grub_script;
 pub mod ipxe_script;
 pub mod iso_fs;
 pub mod log_stream;
 pub mod notify;
 pub mod saml_routes;
@@ -105,7 +105,11 @@ async fn send_email(cfg: &NotifyConfig, subject: &str, body: &str) -> Result<(),
            .trim()
            .parse()
            .map_err(|e| format!("invalid To address '{}': {e}", cfg.smtp_to))?)
-        .subject(if subject.is_empty() { "OpenPXE" } else { subject })
+        .subject(if subject.is_empty() {
            "OpenPXE"
        } else {
            subject
        })
        .body(body.to_string())
        .map_err(|e| format!("could not build email: {e}"))?;
@@ -336,3 +336,35 @@ fn redirect_with_session(location: &str, session: &str) -> Response {
            IntoResponse::into_response,
        )
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    use wiremock::matchers::method;
    use wiremock::{Mock, MockServer, ResponseTemplate};
    // v0.5.4: exercise the SAML metadata-URL fetch against a mock server —
    // previously this path did a real network GET and had no coverage.
    #[tokio::test]
    async fn fetch_metadata_returns_body_on_200() {
        let server = MockServer::start().await;
        let xml = "<EntityDescriptor>idp</EntityDescriptor>";
        Mock::given(method("GET"))
            .respond_with(ResponseTemplate::new(200).set_body_string(xml))
            .mount(&server)
            .await;
        let got = fetch_metadata(&server.uri()).await.expect("fetch ok");
        assert_eq!(got, xml);
    }
    #[tokio::test]
    async fn fetch_metadata_errors_on_non_2xx() {
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .respond_with(ResponseTemplate::new(503))
            .mount(&server)
            .await;
        let err = fetch_metadata(&server.uri()).await.unwrap_err();
        assert!(matches!(err, SamlError::Metadata(_)), "got {err:?}");
    }
 }
@@ -0,0 +1,36 @@
 ---
 source: crates/http-api/src/ipxe_script.rs
 expression: rendered
 ---
 #!ipxe
 # OpenPXE top-level menu - auto-generated, do not edit
 set base-url http://10.0.0.5
 set esc:hex 1b
 set cls ${esc:string}[2J
 iseq ${platform} efi && console --picture http://10.0.0.5/branding/pxe-logo --top 290 || console
 set arch-label ${buildarch} ${platform}
 iseq ${buildarch} i386   && iseq ${platform} pcbios && set arch-label x86 BIOS         || iseq ${buildarch} x86_64 && iseq ${platform} efi    && set arch-label x86_64 UEFI      || iseq ${buildarch} arm64  && iseq ${platform} efi    && set arch-label arm64 UEFI       || true
 :menu
 menu OpenPXE - network boot menu
 item --gap
 item --gap -- ------------------------- Default -------------------------
 item local            Boot from Local HDD
 item --gap -- ----------------------- Installers -----------------------
 item --gap -- (no Linux ISOs uploaded)
 item --gap -- (no Windows ISOs uploaded)
 item --gap -- -------------------------- Tools --------------------------
 item tools            Tools  >
 item --gap -- ---------------------- Queued Deployment ---------------------
 item queue            Queued Deployment  (join queue)
 item --gap
 item --key x exit     Exit iPXE
 item --gap
 item --gap --                 OpenPXE vX.Y.Z  -  ${arch-label}
 choose --default queue --timeout 600000 target || goto menu
 iseq ${target} local   && chain http://10.0.0.5/boot/_local.ipxe        || goto menu
 iseq ${target} linux   && chain http://10.0.0.5/boot/_linux_menu.ipxe   || goto menu
 iseq ${target} windows && chain http://10.0.0.5/boot/_windows_menu.ipxe || goto menu
 iseq ${target} tools   && chain http://10.0.0.5/boot/_tools_menu.ipxe   || goto menu
 iseq ${target} queue   && chain http://10.0.0.5/boot/_queue.ipxe         || goto menu
 iseq ${target} exit    && exit                                 || goto menu
 goto menu
@@ -1,14 +1,21 @@
 use crate::auth::SessionStore;
 use crate::fetch::FetchJobs;
 use crate::saml_routes::SamlRuntime;
 use crate::uploads::UploadSessions;
 use openpxe_core::{
-    AdminStore, BootLog, BrandingStore, ClientRegistry, DeploymentQueue, HostBindings, LogBus,
+    AdminStore, ApiKeyStore, BootLog, BootRulesStore, BootTokens, BrandingStore, ClientRegistry,
-    Metrics, NotifyStore, SettingsStore, SsoStore,
+    DeploymentQueue, HostBindings, LogBus, Metrics, NotifyStore, SettingsStore, SsoStore,
 };
 use openpxe_iso_store::{
    IsoStore, NfsShareManager, SftpShareManager, SmbManager, SmbShareManager, UnattendedStore,
 };
 use openpxe_iso_store::{IsoStore, NfsShareManager, SmbManager, SmbShareManager, UnattendedStore};
 use std::sync::Arc;
 use time::OffsetDateTime;
 /// Cached composited PXE boot-menu background: `(logo_rev, encoded PNG)`.
 /// See `AppState::pxe_bg_cache`.
 pub type PxeBgCache = Arc<parking_lot::Mutex<Option<(u64, bytes::Bytes)>>>;
 #[derive(Clone)]
 pub struct AppState {
    pub iso_store: IsoStore,
@@ -23,10 +30,24 @@ pub struct AppState {
    /// every `/boot/<entry>.ipxe` chain that goes on to serve a script
    /// (i.e. an image actually starting to install on a machine).
    pub boot_log: BootLog,
    /// v0.7.0: ordered label-based boot rules (MAC prefix / arch →
    /// target) plus the optional boot-decision webhook. Consulted by the
    /// top-level boot script after exact host bindings, before the menu.
    pub boot_rules: BootRulesStore,
    /// v0.7.0: short-lived access tokens for unattended answer files.
    /// Minted into every generated answer-file URL; the serving endpoint
    /// requires one (or an operator session) once an admin exists.
    pub boot_tokens: BootTokens,
    /// Operator-controlled UI overrides (custom logo). When the
    /// operator hasn't uploaded anything, the WebUI serves the bundled
    /// rainbow-horizon mark.
    pub branding: BrandingStore,
    /// v0.6.2: cache of the composited PXE boot-menu background PNG,
    /// keyed on the branding logo revision. Composing costs ~50-200 ms
    /// of image decode/encode and **every** booting client fetches it
    /// for `console --picture` — caching makes that one compose per
    /// logo change instead of one per boot.
    pub pxe_bg_cache: PxeBgCache,
    /// Forms-auth admin record + first-run bootstrap state. When
    /// `admin.is_configured() == false`, the auth middleware passes
    /// every request through and `/api/me` reports `setup_required`.
@@ -35,6 +56,11 @@ pub struct AppState {
    /// process restart (sessions are tied to UI state, not persisted —
    /// matches Sonarr/Radarr behaviour).
    pub sessions: SessionStore,
    /// v0.8.0: persisted operator API key. A request carrying a matching
    /// `x-api-key` header authenticates exactly like an operator session,
    /// so scripts / Postman can drive `/api/*` without a browser login.
    /// Generated on first run; regenerable from Settings → Advanced.
    pub api_key: ApiKeyStore,
    /// SAML SSO configuration (persisted IdP metadata, Entity ID, toggles).
    pub sso: SsoStore,
    /// v0.5.1: in-memory SAML runtime state — outstanding AuthnRequest IDs
@@ -67,6 +93,13 @@ pub struct AppState {
    /// In-process (no subprocess); supports HTTP Range requests on
    /// NFS-sourced ISOs because NFSv3 READ3 takes an explicit offset.
    pub nfs_shares: NfsShareManager,
    /// v0.5.5: SFTP-over-SSH share manager — pure-Rust userspace
    /// consumer via `russh` + `russh-sftp` (ring backend, no OpenSSL).
    /// Ships alongside SMB/NFS as the third remote-library protocol.
    /// In-process (no subprocess, no kernel mount); supports HTTP Range
    /// requests because SFTP opens a seekable file handle. Authenticates
    /// the server's SSH host key on a trust-on-first-use basis.
    pub sftp_shares: SftpShareManager,
    /// v0.5.2: uploaded unattended-install answer files (Kickstart /
    /// Preseed / Autoinstall / Windows answer files). Served on demand to
    /// booting clients with per-host hostname/IP/MAC templating; lives in
@@ -76,6 +109,10 @@ pub struct AppState {
    /// through `IsoStore`, but the UI uses sessions so large ISO transfers
    /// can show deterministic progress and leave visible partial files.
    pub uploads: UploadSessions,
    /// v0.8.1: server-side "add ISO by URL" jobs. Background downloads
    /// streamed straight into the store (reusing the upload handle +
    /// introspection); the Storage view polls their progress.
    pub fetch_jobs: FetchJobs,
    /// Live log bus consumed by the Terminal tab via SSE. Operator-issued
    /// terminal commands also push synthetic lines onto it so the tail
    /// shows them inline.
@@ -89,6 +126,10 @@ pub struct AppState {
    /// `enp1s0`). Surfaced read-only on the Network tab. Empty if the
    /// interface couldn't be identified.
    pub nic_name: String,
    /// v0.7.2: physical link summary for that NIC (operstate, speed,
    /// duplex, port MAC) — read from sysfs at startup; empty where
    /// unavailable. Helps confirm which port answers PXE.
    pub nic_link: String,
    /// Subnet mask of the public interface in dotted-quad form.
    pub subnet_mask: String,
    /// Default gateway IPv4 address.
@@ -96,6 +96,8 @@ async fn dispatch(state: &AppState, argv: &[String]) -> Result<String, String> {
        "share" | "smb-share" => smb_share_command(state, tail).await,
        "smb" => smb_command(state, tail).await,
        "nfs" => nfs_share_command(state, tail).await,
        // v0.5.5: SFTP-over-SSH remote shares (in-process russh client).
        "sftp" => sftp_share_command(state, tail).await,
        "log" => log_command(state, tail),
        "whoami" => Ok("operator".to_string()),
        "echo" => Ok(tail.join(" ")),
@@ -118,17 +120,21 @@ fn status_text(s: &AppState) -> String {
    // v0.4.67: NFSv3 sources too.
    let nfs_shares = s.nfs_shares.list();
    let nfs_reachable = nfs_shares.iter().filter(|m| m.reachable).count();
    // v0.5.5: SFTP-over-SSH sources too.
    let sftp_shares = s.sftp_shares.list();
    let sftp_reachable = sftp_shares.iter().filter(|m| m.reachable).count();
    format!(
        "OpenPXE {ver}\n\
         base url:     {base}\n\
         interface:    {nic}\n\
         uptime:       {up}\n\
-         isos:         {n_isos}  (local: {n_local}, smb: {n_smb}, nfs: {n_nfs})\n\
+         isos:         {n_isos}  (local: {n_local}, smb: {n_smb}, nfs: {n_nfs}, sftp: {n_sftp})\n\
         clients:      {n_clients}\n\
         queue:        {n_entries}\n\
         smb server:   {smb}\n\
         smb shares:   {n_smb_total} configured ({n_smb_active} reachable)\n\
-         nfs shares:   {n_nfs_total} configured ({n_nfs_active} reachable)\n",
+         nfs shares:   {n_nfs_total} configured ({n_nfs_active} reachable)\n\
         sftp shares:  {n_sftp_total} configured ({n_sftp_active} reachable)\n",
        ver = env!("CARGO_PKG_VERSION"),
        base = s.public_base_url,
        nic = if s.nic_name.is_empty() {
@@ -150,6 +156,10 @@ fn status_text(s: &AppState) -> String {
            .iter()
            .filter(|i| matches!(i.source, openpxe_iso_store::IsoSource::Nfs { .. }))
            .count(),
        n_sftp = isos
            .iter()
            .filter(|i| matches!(i.source, openpxe_iso_store::IsoSource::Sftp { .. }))
            .count(),
        n_clients = clients.len(),
        n_entries = queue_entries.len(),
        smb = smb.map_or_else(|| "(disabled)".into(), |s| format!("{s:?}")),
@@ -157,6 +167,8 @@ fn status_text(s: &AppState) -> String {
        n_smb_active = smb_reachable,
        n_nfs_total = nfs_shares.len(),
        n_nfs_active = nfs_reachable,
        n_sftp_total = sftp_shares.len(),
        n_sftp_active = sftp_reachable,
    )
 }
@@ -177,6 +189,8 @@ fn isos_text(s: &AppState) -> String {
            openpxe_iso_store::IsoSource::Smb { share_id, .. } => format!("smb:{share_id}"),
            // v0.4.67: NFSv3 via in-process nfs3_client.
            openpxe_iso_store::IsoSource::Nfs { share_id, .. } => format!("nfs:{share_id}"),
            // v0.5.5: SFTP-over-SSH via in-process russh.
            openpxe_iso_store::IsoSource::Sftp { share_id, .. } => format!("sftp:{share_id}"),
        };
        let _ = writeln!(
            out,
@@ -321,11 +335,9 @@ async fn smb_share_command(s: &AppState, args: &[String]) -> Result<String, Stri
        }
        Some("add") => {
            // share add //server/share [guest|user:password]
-            let target = args
+            let target = args.get(1).ok_or_else(|| {
-                .get(1)
+                "usage: share add //server/share [guest|user:password]".to_string()
-                .ok_or_else(|| {
+            })?;
                    "usage: share add //server/share [guest|user:password]".to_string()
                })?;
            // Accept either `//server/share` (UNC-style) or
            // `server:share` (shorter to type).
            let stripped = target.trim_start_matches('/').trim_start_matches('\\');
@@ -401,11 +413,7 @@ async fn nfs_share_command(s: &AppState, args: &[String]) -> Result<String, Stri
                return Ok("(no NFS shares configured)".into());
            }
            let mut out = String::new();
-            let _ = writeln!(
+            let _ = writeln!(out, "{:<24} {:<7} {:<6} TARGET", "ID", "STATUS", "ISOS");
                out,
                "{:<24} {:<7} {:<6} TARGET",
                "ID", "STATUS", "ISOS"
            );
            for m in shares {
                let status = if m.reachable { "ok" } else { "down" };
                let _ = writeln!(
@@ -476,6 +484,104 @@ async fn nfs_share_command(s: &AppState, args: &[String]) -> Result<String, Stri
    }
 }
 // ── sftp (v0.5.5) ────────────────────────────────────────────────────────
 //
 // Parallel to nfs_share_command. The terminal `add` only supports
 // password auth — pasting a multiline PEM private key through the
 // terminal is impractical, so key-based shares are added via the WebUI.
 async fn sftp_share_command(s: &AppState, args: &[String]) -> Result<String, String> {
    match args.first().map(String::as_str) {
        None | Some("list") => {
            let shares = s.sftp_shares.list();
            if shares.is_empty() {
                return Ok("(no SFTP shares configured)".into());
            }
            let mut out = String::new();
            let _ = writeln!(out, "{:<24} {:<7} {:<6} TARGET", "ID", "STATUS", "ISOS");
            for m in shares {
                let status = if m.reachable { "ok" } else { "down" };
                let _ = writeln!(
                    out,
                    "{:<24} {:<7} {:<6} {}@{}:{}",
                    truncate(&m.id, 24),
                    status,
                    m.iso_count,
                    m.username,
                    m.server,
                    m.export,
                );
                if let Some(e) = m.last_error {
                    let _ = writeln!(out, "    error: {e}");
                }
                if let Some(h) = m.last_hint {
                    let _ = writeln!(out, "    hint:  {h}");
                }
            }
            Ok(out)
        }
        Some("add") => {
            // sftp add <user>@<server>:<export> <password> [port]
            let target = args.get(1).ok_or_else(|| {
                "usage: sftp add <user>@<server>:<export> <password> [port] \
                 (key auth: use the WebUI)"
                    .to_string()
            })?;
            let password = args
                .get(2)
                .ok_or_else(|| "a password is required (key auth: use the WebUI)".to_string())?;
            let (user, rest) = target
                .split_once('@')
                .ok_or_else(|| "target must be 'user@server:/export'".to_string())?;
            let (server, export) = rest
                .split_once(':')
                .ok_or_else(|| "target must be 'user@server:/export'".to_string())?;
            let port = args.get(3).and_then(|s| s.parse::<u16>().ok());
            let req = openpxe_iso_store::SftpAddRequest {
                server: server.to_string(),
                export: export.to_string(),
                username: Some(user.to_string()),
                port,
                password: Some(password.clone()),
                private_key: None,
                passphrase: None,
            };
            match s.sftp_shares.add(req).await {
                Ok(m) => Ok(format!("added {} ({} isos)", m.id, m.iso_count)),
                Err(e) => {
                    let mut out = format!("add failed: {}", e.error);
                    if let Some(h) = e.hint {
                        out.push_str("\nhint: ");
                        out.push_str(&h);
                    }
                    Err(out)
                }
            }
        }
        Some("remove") => {
            let id = args
                .get(1)
                .ok_or_else(|| "usage: sftp remove <id>".to_string())?;
            match s.sftp_shares.remove(id).await {
                Ok(()) => Ok(format!("removed {id}")),
                Err(e) => Err(format!("remove failed: {e}")),
            }
        }
        Some("scan") => {
            let id = args
                .get(1)
                .ok_or_else(|| "usage: sftp scan <id>".to_string())?;
            match s.sftp_shares.rescan(id).await {
                Ok(n) => Ok(format!("re-scanned {id}: {n} isos")),
                Err(e) => Err(format!("scan failed: {e}")),
            }
        }
        Some(other) => Err(format!(
            "unknown sftp subcommand: {other}\ntry: sftp [list|add|remove|scan]"
        )),
    }
 }
 // ── smb ────────────────────────────────────────────────────────────────
 #[allow(clippy::unused_async)]
@@ -622,6 +728,11 @@ OpenPXE terminal — available commands:
  nfs remove <id>                   forget an NFS share
  nfs scan <id>                     re-list an NFS share for new ISOs
  sftp list                         list configured SFTP-over-SSH shares
  sftp add <user>@<srv>:<export> <pass> [port]   add an SFTP share (key auth: WebUI)
  sftp remove <id>                  forget an SFTP share
  sftp scan <id>                    re-list an SFTP share for new ISOs
  smb status                        outbound Samba state (Windows install media)
  smb start | stop | reload         control the outbound smbd
@@ -9,6 +9,7 @@
 use bytes::Bytes;
 use openpxe_core::{Error, Result};
 use openpxe_iso_store::{IsoMeta, IsoStore, UploadHandle};
 use parking_lot::RwLock;
 use serde::Serialize;
 use std::collections::HashMap;
 use std::sync::Arc;
@@ -19,7 +20,11 @@ const DEFAULT_CHUNK_SIZE: u64 = 8 * 1024 * 1024;
 #[derive(Clone, Default)]
 pub struct UploadSessions {
-    inner: Arc<Mutex<HashMap<String, Arc<Mutex<UploadSession>>>>>,
+    // v0.5.4: the registry is a sync `parking_lot::RwLock` — it's only ever
    // briefly read/inserted/removed to look up a session, never held across
    // an `.await`. The per-session lock below stays a `tokio::sync::Mutex`
    // because `write_chunk` / `finish` are awaited while it's held.
    inner: Arc<RwLock<HashMap<String, Arc<Mutex<UploadSession>>>>>,
 }
 struct UploadSession {
@@ -67,8 +72,7 @@ impl UploadSessions {
        };
        self.inner
-            .lock()
+            .write()
            .await
            .insert(upload_id.clone(), Arc::new(Mutex::new(session)));
        Ok(UploadStarted {
@@ -88,7 +92,7 @@ impl UploadSessions {
        chunk: Bytes,
        complete: bool,
    ) -> Result<UploadAppend> {
-        let Some(session_lock) = self.inner.lock().await.get(upload_id).cloned() else {
+        let Some(session_lock) = self.inner.read().get(upload_id).cloned() else {
            return Err(Error::Invalid(format!("no such upload '{upload_id}'")));
        };
@@ -119,7 +123,7 @@ impl UploadSessions {
        if let Err(e) = handle.write_chunk(&chunk).await {
            let handle = session.handle.take();
            drop(session);
-            self.inner.lock().await.remove(upload_id);
+            self.inner.write().remove(upload_id);
            if let Some(handle) = handle {
                let _ = handle.abort().await;
            }
@@ -156,11 +160,11 @@ impl UploadSessions {
        let meta = match handle.finish(store).await {
            Ok(meta) => meta,
            Err(e) => {
-                self.inner.lock().await.remove(upload_id);
+                self.inner.write().remove(upload_id);
                return Err(e);
            }
        };
-        self.inner.lock().await.remove(upload_id);
+        self.inner.write().remove(upload_id);
        Ok(UploadAppend::Complete {
            offset: new_offset,
            iso: Box::new(meta),
@@ -168,7 +172,7 @@ impl UploadSessions {
    }
    pub async fn abort(&self, upload_id: &str) -> Result<()> {
-        let Some(session_lock) = self.inner.lock().await.remove(upload_id) else {
+        let Some(session_lock) = self.inner.write().remove(upload_id) else {
            return Err(Error::Invalid(format!("no such upload '{upload_id}'")));
        };
        let mut session = session_lock.lock().await;
@@ -14,27 +14,20 @@ use axum::body::Body;
 use axum::http::{header, Request, StatusCode};
 use openpxe_core::{ClientRegistry, DeploymentQueue, HostBindings, LogBus, Metrics, SettingsStore};
 use openpxe_http_api::{build_router, AppState};
-use openpxe_iso_store::{IsoStore, NfsShareManager, SmbShareManager};
+use openpxe_iso_store::{IsoStore, NfsShareManager, SftpShareManager, SmbShareManager};
 use tempfile::tempdir;
 use tower::ServiceExt;
-/// Build a tiny valid ISO9660 blob with volume label "ALPINE-TEST" so
+/// Build a tiny Alpine-shaped ISO9660 image: volume label "ALPINE-TEST"
-/// introspection identifies it as Alpine.
+/// plus the real `/boot/vmlinuz-lts` + `/boot/initramfs-lts` tree.
 /// v0.7.4's probe-based introspection verifies those paths exist before
 /// emitting a kernel boot entry — a label-only blob no longer counts.
 fn fake_alpine_iso() -> Vec<u8> {
-    let mut buf = vec![0u8; 32 * 2048];
+    openpxe_iso_store::iso_fs::testiso::TestIsoBuilder::new("ALPINE-TEST")
-    let off = 16 * 2048;
+        .el_torito(true)
-    buf[off] = 0x01;
+        .file("/boot/vmlinuz-lts", b"fake-kernel-bytes")
-    buf[off + 1..off + 6].copy_from_slice(b"CD001");
+        .file("/boot/initramfs-lts", b"fake-initramfs-bytes")
-    buf[off + 6] = 0x01;
+        .build()
    let label = b"ALPINE-TEST".to_vec();
    let mut padded = label.clone();
    padded.resize(32, b' ');
    buf[off + 40..off + 40 + 32].copy_from_slice(&padded);
    let term = 17 * 2048;
    buf[term] = 0xFF;
    buf[term + 1..term + 6].copy_from_slice(b"CD001");
    buf[term + 6] = 0x01;
    buf
 }
 fn multipart_iso_body(filename: &str, bytes: &[u8]) -> (String, Vec<u8>) {
@@ -96,6 +89,7 @@ async fn build_state() -> (AppState, tempfile::TempDir) {
    let settings = SettingsStore::load_or_default(dir.path());
    let smb_shares = SmbShareManager::new(dir.path(), iso_store.clone());
    let nfs_shares = NfsShareManager::new(dir.path(), iso_store.clone());
    let sftp_shares = SftpShareManager::new(dir.path(), iso_store.clone());
    let unattended = openpxe_iso_store::UnattendedStore::new(dir.path().join("unattended"));
    unattended.ensure_dir().await.unwrap();
    let log_bus = LogBus::new(64);
@@ -105,6 +99,7 @@ async fn build_state() -> (AppState, tempfile::TempDir) {
    let admin = openpxe_core::AdminStore::load_or_default(dir.path());
    let sso = openpxe_core::SsoStore::load_or_default(dir.path());
    let notify = openpxe_core::NotifyStore::load_or_default(dir.path());
    let api_key = openpxe_core::ApiKeyStore::load_or_init(dir.path());
    let sessions = openpxe_http_api::auth::SessionStore::default();
    let metrics = Metrics::new();
    let state = AppState {
@@ -114,9 +109,13 @@ async fn build_state() -> (AppState, tempfile::TempDir) {
        settings,
        hosts,
        boot_log,
        boot_rules: openpxe_core::BootRulesStore::load_or_default(dir.path()),
        boot_tokens: openpxe_core::BootTokens::new(),
        branding,
        pxe_bg_cache: openpxe_http_api::state::PxeBgCache::default(),
        admin,
        sessions,
        api_key,
        sso,
        saml: openpxe_http_api::saml_routes::SamlRuntime::default(),
        notify,
@@ -124,18 +123,124 @@ async fn build_state() -> (AppState, tempfile::TempDir) {
        smb: None,
        smb_shares,
        nfs_shares,
        sftp_shares,
        unattended,
        uploads: openpxe_http_api::uploads::UploadSessions::default(),
        fetch_jobs: openpxe_http_api::fetch::FetchJobs::default(),
        log_bus,
        started_at: time::OffsetDateTime::now_utc(),
        public_base_url: "http://127.0.0.1".into(),
        nic_name: "lo".into(),
        nic_link: String::new(),
        subnet_mask: "255.0.0.0".into(),
        gateway: "127.0.0.1".into(),
    };
    (state, dir)
 }
 #[tokio::test]
 async fn api_key_authenticates_gated_endpoints() {
    // v0.8.0: the x-api-key header authenticates /api/* like an operator
    // session. The middleware only enforces once an admin is configured
    // (before that everything is open), so bootstrap one first.
    let (state, _dir) = build_state().await;
    state
        .admin
        .bootstrap("admin", "correct-horse-battery-staple")
        .unwrap();
    let key = state.api_key.current();
    let app = build_router(state);
    // No credentials → 401.
    let res = app
        .clone()
        .oneshot(
            Request::builder()
                .uri("/api/isos")
                .body(Body::empty())
                .unwrap(),
        )
        .await
        .unwrap();
    assert_eq!(res.status(), StatusCode::UNAUTHORIZED, "no auth must 401");
    // Wrong key → 401.
    let res = app
        .clone()
        .oneshot(
            Request::builder()
                .uri("/api/isos")
                .header("x-api-key", "not-the-key")
                .body(Body::empty())
                .unwrap(),
        )
        .await
        .unwrap();
    assert_eq!(res.status(), StatusCode::UNAUTHORIZED, "wrong key must 401");
    // Correct key → 200 (operator-equivalent access).
    let res = app
        .oneshot(
            Request::builder()
                .uri("/api/isos")
                .header("x-api-key", key)
                .body(Body::empty())
                .unwrap(),
        )
        .await
        .unwrap();
    assert_eq!(res.status(), StatusCode::OK, "valid key must authenticate");
 }
 #[tokio::test]
 async fn fetch_iso_by_url_downloads_into_store() {
    // v0.8.1: add-ISO-by-URL. Serve a real ISO over HTTP, POST its URL, poll
    // the fetch registry until the background download finishes, then assert
    // the image landed in the store (classified like an upload).
    use wiremock::matchers::{method, path};
    use wiremock::{Mock, MockServer, ResponseTemplate};
    let (state, _dir) = build_state().await;
    let app = build_router(state);
    let iso = fake_alpine_iso();
    let server = MockServer::start().await;
    Mock::given(method("GET"))
        .and(path("/rescue.iso"))
        .respond_with(ResponseTemplate::new(200).set_body_bytes(iso))
        .mount(&server)
        .await;
    let url = format!("{}/rescue.iso", server.uri());
    let (code, _) = post_json(&app, "/api/isos/fetch", &format!(r#"{{"url":"{url}"}}"#)).await;
    assert_eq!(code, StatusCode::ACCEPTED, "fetch should start");
    // Bounded poll for completion (the download runs on a spawned task).
    let mut done = false;
    for _ in 0..100 {
        let (_, body) = get(&app, "/api/isos/fetch").await;
        let v: serde_json::Value = serde_json::from_slice(&body).unwrap();
        let jobs = v["jobs"].as_array().cloned().unwrap_or_default();
        assert!(
            !jobs.iter().any(|j| j["state"] == "failed"),
            "fetch failed: {jobs:?}"
        );
        if jobs.iter().any(|j| j["state"] == "done") {
            done = true;
            break;
        }
        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
    }
    assert!(done, "fetch did not complete in time");
    // The fetched ISO is now in the store under the URL basename.
    let (_, body) = get(&app, "/api/isos").await;
    assert!(
        String::from_utf8_lossy(&body).contains("rescue.iso"),
        "fetched ISO should appear in /api/isos"
    );
 }
 #[tokio::test]
 async fn health_and_ready_endpoints() {
    let (state, _dir) = build_state().await;
@@ -691,7 +796,7 @@ async fn log_recent_returns_buffered_lines() {
 }
 #[tokio::test]
-async fn windows_iso_renders_clean_wimboot_script_with_no_trust_store_writes() {
+async fn windows_iso_renders_clean_sanboot_script_with_no_trust_store_writes() {
    // Synthesize an ISO with a Windows volume label + the sources/boot.wim
    // sentinel so introspection labels it WindowsPe with has_boot_wim.
    let mut buf = vec![0u8; 32 * 2048];
@@ -761,38 +866,35 @@ async fn windows_iso_renders_clean_wimboot_script_with_no_trust_store_writes() {
        "introspection should detect sources/boot.wim sentinel"
    );
-    // The boot entry should be a wimboot kind with the canonical 5-file
+    // v0.5.8: Windows boots via iPXE HTTP sanboot of the raw ISO — no SMB,
-    // chain documented in the LinusTechTips iPXE-Windows guide.
+    // no extraction, no in-ISO file serving, no operator toggle. The boot
    // entry is a `san_boot_iso` kind pointing at the raw image.
    let entry = &meta["boot_entries"][0];
-    assert_eq!(entry["kind"]["kind"], "wimboot");
+    assert_eq!(entry["kind"]["kind"], "san_boot_iso");
-    let files = entry["kind"]["files"].as_array().unwrap();
+    let iso_url = entry["kind"]["iso_url"].as_str().unwrap();
-    let names: Vec<&str> = files.iter().map(|f| f[0].as_str().unwrap()).collect();
+    assert!(
-    assert!(names.contains(&"bootmgr"));
+        std::path::Path::new(iso_url)
-    assert!(names.contains(&"bootmgr.efi"));
+            .extension()
-    assert!(names.contains(&"bcd"));
+            .is_some_and(|e| e.eq_ignore_ascii_case("iso")),
-    assert!(names.contains(&"boot.sdi"));
+        "sanboot should target the raw ISO, got: {iso_url}"
-    assert!(names.contains(&"boot.wim"));
+    );
    // Render the entry script and verify:
-    //   1. It uses wimboot
+    //   1. It uses `sanboot` against the raw ISO over HTTP
-    //   2. All 5 files are referenced via `initrd --name`
+    //   2. NO trust-store / driver / testsigning operations slip in
    //   3. NO trust-store / driver / testsigning operations slip in
    let entry_id = entry["id"].as_str().unwrap();
    let url = format!("/boot/{entry_id}.ipxe");
    let (s, body) = get(&app, &url).await;
    assert_eq!(s, StatusCode::OK);
    let script = String::from_utf8(body).unwrap();
    assert!(script.contains("kernel "), "missing kernel line:\n{script}");
    assert!(
-        script.contains("ipxe/wimboot"),
+        script.contains("sanboot"),
-        "missing wimboot loader:\n{script}"
+        "missing sanboot line:\n{script}"
    );
    assert!(
        script.contains(&format!("/{iso_url}")),
        "sanboot should reference the raw ISO url:\n{script}"
    );
    for tag in ["bootmgr", "bootmgr.efi", "bcd", "boot.sdi", "boot.wim"] {
        assert!(
            script.contains(&format!("initrd --name {tag}")),
            "missing `initrd --name {tag}` line:\n{script}"
        );
    }
    // Hard guarantees we never want to see in any client-facing script.
    let lower = script.to_lowercase();
    for forbidden in [
@@ -1245,9 +1347,10 @@ async fn chunked_upload_writes_progressively_and_finishes_iso() {
                .method("POST")
                .uri("/api/uploads")
                .header("content-type", "application/json")
-                .body(Body::from(
+                .body(Body::from(format!(
-                    r#"{"filename":"chunked-alpine.iso","size_bytes":65536}"#,
+                    r#"{{"filename":"chunked-alpine.iso","size_bytes":{}}}"#,
-                ))
+                    iso.len()
                )))
                .unwrap(),
        )
        .await
@@ -1489,9 +1592,10 @@ async fn api_docs_lists_known_endpoints() {
    }
    for needle in [
        "/api/isos",
-        "/api/isos/:id/category",
+        // v0.6.3: docs use axum 0.8's `{param}` capture syntax.
        "/api/isos/{id}/category",
        "/api/storage/disk",
-        "/api/branding/logo/:slot",
+        "/api/branding/logo/{slot}",
        "/api/unattended",
        "/api/boot-log",
        "/metrics",
@@ -1536,6 +1640,60 @@ async fn status_exposes_custom_logo_flag() {
    );
 }
 /// v0.5.4 guard: the typed `StatusResponse` must keep every key the WebUI
 /// (`crates/webui/src/app.js`) reads off `/api/status`. If a refactor drops
 /// or renames one, the dashboard silently breaks — this catches it.
 #[tokio::test]
 async fn status_contract_has_all_ui_keys() {
    let (state, _dir) = build_state().await;
    let app = build_router(state);
    let (s, body) = get(&app, "/api/status").await;
    assert_eq!(s, StatusCode::OK);
    let v: serde_json::Value = serde_json::from_slice(&body).unwrap();
    for key in [
        "version",
        "public_base_url",
        "iso_count",
        "client_count",
        "queue_count",
        "imaging_count",
        "waiting_count",
        "ipxe_assets",
        "settings",
        "smb_share_count",
        "smb_share_reachable",
        "nfs_share_count",
        "nfs_share_reachable",
        "host_bindings",
        "custom_logo",
        "branding",
        "unattended_count",
        "uptime_secs",
        "started_at",
        "nic_name",
        "subnet_mask",
        "gateway",
    ] {
        assert!(
            v.get(key).is_some(),
            "/api/status missing UI key '{key}': {v}"
        );
    }
    // Nested branding presence the Settings tab reads.
    for key in ["light", "dark", "client", "rev"] {
        assert!(
            v["branding"].get(key).is_some(),
            "/api/status branding missing '{key}': {v}"
        );
    }
    // started_at must remain an RFC3339 string (the UI does fmtUptime on
    // uptime_secs but renders started_at as text), not a serialized struct.
    assert!(
        v["started_at"].is_string(),
        "started_at should serialize as a string: {v}"
    );
 }
 async fn put_json(router: &axum::Router, path: &str, body: &str) -> (StatusCode, Vec<u8>) {
    let res = router
        .clone()
@@ -2555,3 +2713,162 @@ async fn acs_garbage_is_rejected_without_500() {
    assert!(location(&resp).contains("sso_error"));
    assert!(!has_session_cookie(&resp));
 }
 // ─── v0.7.0: tokenized answer files + boot rules ────────────────────────────
 #[tokio::test]
 async fn unattended_requires_token_once_admin_exists() {
    let (state, _dir) = build_state().await;
    let app = build_router(state.clone());
    // Upload an answer file while in setup mode (everything open).
    let (ct, body) =
        multipart_iso_body("ks.ks", b"install\nrootpw s3cret\n%packages\n@core\n%end\n");
    let (s, b) = post_multipart(&app, "/api/unattended", &ct, body).await;
    assert_eq!(s, StatusCode::CREATED);
    let id = serde_json::from_slice::<serde_json::Value>(&b).unwrap()["id"]
        .as_str()
        .unwrap()
        .to_string();
    // Pre-setup, the file serves openly (bootstrap parity with the
    // auth middleware).
    let (s, _) = get(&app, &format!("/unattended/{id}")).await;
    assert_eq!(s, StatusCode::OK);
    // Create the admin → the gate arms.
    let (s, _, cookies) = post_collect(
        &app,
        "/api/setup",
        r#"{"username":"admin","password":"hunter2hunter2"}"#,
    )
    .await;
    assert_eq!(s, StatusCode::CREATED);
    let session = session_value(&cookies).unwrap();
    // Bare fetch (the CVE-2026-0386 harvesting pattern) is refused.
    let (s, _) = get(&app, &format!("/unattended/{id}")).await;
    assert_eq!(s, StatusCode::UNAUTHORIZED);
    // Garbage token is refused.
    let (s, _) = get(&app, &format!("/unattended/{id}?t=bogus")).await;
    assert_eq!(s, StatusCode::UNAUTHORIZED);
    // A token minted for a *different* file is refused.
    let other = state.boot_tokens.mint("some-other-file");
    let (s, _) = get(&app, &format!("/unattended/{id}?t={other}")).await;
    assert_eq!(s, StatusCode::UNAUTHORIZED);
    // The boot-scoped token OpenPXE mints into generated URLs passes.
    let tok = state.boot_tokens.mint(&id);
    let (s, b) = get(&app, &format!("/unattended/{id}?t={tok}")).await;
    assert_eq!(s, StatusCode::OK);
    assert!(String::from_utf8_lossy(&b).contains("rootpw"));
    // A logged-in operator (browser testing) passes too.
    let (s, _) = get_with_cookie(&app, &format!("/unattended/{id}"), &session).await;
    assert_eq!(s, StatusCode::OK);
 }
 #[tokio::test]
 async fn boot_script_for_pinned_unattended_carries_live_token() {
    let (state, _dir) = build_state().await;
    let app = build_router(state.clone());
    let (ct, body) = multipart_iso_body("fake-alpine.iso", &fake_alpine_iso());
    let (s, _) = post_multipart(&app, "/api/isos", &ct, body).await;
    assert_eq!(s, StatusCode::CREATED);
    let (ct, body) = multipart_iso_body("ks.ks", b"install\n%packages\n@core\n%end\n");
    let (s, b) = post_multipart(&app, "/api/unattended", &ct, body).await;
    assert_eq!(s, StatusCode::CREATED);
    let ks_id = serde_json::from_slice::<serde_json::Value>(&b).unwrap()["id"]
        .as_str()
        .unwrap()
        .to_string();
    let mac = "aa:bb:cc:dd:ee:71";
    let pin =
        format!(r#"{{"mac":"{mac}","target":"fake-alpine-linux","unattended_file":"{ks_id}"}}"#);
    let (s, _) = post_json(&app, "/api/hosts", &pin).await;
    assert_eq!(s, StatusCode::CREATED);
    let (s, b) = get(&app, &format!("/boot/fake-alpine-linux.ipxe?mac={mac}")).await;
    assert_eq!(s, StatusCode::OK);
    let script = String::from_utf8_lossy(&b).into_owned();
    // The injected inst.ks URL ends with a token that is live for the file.
    let tok = script
        .split("t=")
        .nth(1)
        .and_then(|rest| rest.split_whitespace().next())
        .expect("kernel arg should carry t=<token>");
    assert!(
        state.boot_tokens.check(tok, &ks_id),
        "token in boot script must be live:\n{script}"
    );
 }
 #[tokio::test]
 async fn boot_rules_match_and_persist_via_api() {
    let (state, _dir) = build_state().await;
    let app = build_router(state);
    let (ct, body) = multipart_iso_body("fake-alpine.iso", &fake_alpine_iso());
    let (s, _) = post_multipart(&app, "/api/isos", &ct, body).await;
    assert_eq!(s, StatusCode::CREATED);
    // Save a rule: any MAC under aa:bb:cc, any arch → the Linux entry.
    let cfg = r#"{"rules":[{"mac_prefix":"AA-BB-CC","arch":"","target":"fake-alpine-linux","enabled":true,"note":"rack"}],"webhook_url":""}"#;
    let (s, _) = put_json(&app, "/api/boot-rules", cfg).await;
    assert_eq!(s, StatusCode::NO_CONTENT);
    // The config reads back (prefix normalized to colons).
    let (s, b) = get(&app, "/api/boot-rules").await;
    assert_eq!(s, StatusCode::OK);
    let v: serde_json::Value = serde_json::from_slice(&b).unwrap();
    assert_eq!(v["rules"][0]["mac_prefix"], "aa:bb:cc");
    // A matching client short-circuits to the target...
    let (s, b) = get(&app, "/boot.ipxe?mac=aa:bb:cc:00:00:09&arch=uefi-x64").await;
    assert_eq!(s, StatusCode::OK);
    let script = String::from_utf8_lossy(&b);
    assert!(
        script.contains("boot rule -> fake-alpine-linux"),
        "rule did not chain:\n{script}"
    );
    // ...while a non-matching one still gets the menu.
    let (s, b) = get(&app, "/boot.ipxe?mac=11:22:33:00:00:09&arch=uefi-x64").await;
    assert_eq!(s, StatusCode::OK);
    assert!(
        String::from_utf8_lossy(&b).contains("menu"),
        "non-matching client should see the menu"
    );
 }
 #[tokio::test]
 async fn arch_selective_rule_ignores_other_arches() {
    let (state, _dir) = build_state().await;
    let app = build_router(state);
    let (ct, body) = multipart_iso_body("fake-alpine.iso", &fake_alpine_iso());
    let (s, _) = post_multipart(&app, "/api/isos", &ct, body).await;
    assert_eq!(s, StatusCode::CREATED);
    let cfg = r#"{"rules":[{"mac_prefix":"","arch":"uefi-arm64","target":"fake-alpine-linux","enabled":true,"note":""}],"webhook_url":""}"#;
    let (s, _) = put_json(&app, "/api/boot-rules", cfg).await;
    assert_eq!(s, StatusCode::NO_CONTENT);
    // x64 client: no match → menu.
    let (s, b) = get(&app, "/boot.ipxe?mac=aa:bb:cc:00:00:01&arch=uefi-x64").await;
    assert_eq!(s, StatusCode::OK);
    assert!(!String::from_utf8_lossy(&b).contains("boot rule ->"));
    // arm64 client: match.
    let (s, b) = get(&app, "/boot.ipxe?mac=aa:bb:cc:00:00:01&arch=uefi-arm64").await;
    assert_eq!(s, StatusCode::OK);
    assert!(String::from_utf8_lossy(&b).contains("boot rule -> fake-alpine-linux"));
 }
 #[tokio::test]
 async fn boot_rule_driver_mode_pin_round_trips_via_api() {
    // v0.7.1: a rule may pin only a boot binary (no target) — the API
    // must persist and return it for the DHCP proxy to consult.
    let (state, _dir) = build_state().await;
    let app = build_router(state.clone());
    let cfg = r#"{"rules":[{"mac_prefix":"aa:bb:cc","arch":"","target":"","driver_mode":"shim","enabled":true,"note":"SB rack"}],"webhook_url":""}"#;
    let (s, _) = put_json(&app, "/api/boot-rules", cfg).await;
    assert_eq!(s, StatusCode::NO_CONTENT);
    let (s, b) = get(&app, "/api/boot-rules").await;
    assert_eq!(s, StatusCode::OK);
    let v: serde_json::Value = serde_json::from_slice(&b).unwrap();
    assert_eq!(v["rules"][0]["driver_mode"], "shim");
    // And the store the DHCP proxy shares resolves the pin.
    assert_eq!(
        state.boot_rules.driver_mode_hint("aa:bb:cc:00:00:07", None),
        Some(openpxe_core::DriverMode::Shim)
    );
 }
@@ -13,4 +13,3 @@ workspace = true
 openpxe-core.workspace = true
 rust-embed.workspace = true
 tracing.workspace = true
 thiserror.workspace = true
@@ -6,43 +6,40 @@
 //! missing, that architecture simply won't have PXE support — we log at
 //! startup and serve what we have.
 //!
-//! Filename convention (matches `ClientArch::ipxe_bootfile`):
+//! Filename convention (matches `ClientArch::ipxe_bootfile_mode`):
 //!
 //! DriverMode::Firmware (default — reuse the firmware UNDI/SNP NIC stack):
 //!   - `undionly.kpxe`       — Legacy x86 BIOS
 //!   - `snponly-i386.efi`    — IA32 UEFI
 //!   - `snponly.efi`         — x86_64 UEFI
 //!   - `snponly-arm32.efi`   — ARM32 UEFI
 //!   - `snponly-arm64.efi`   — ARM64 UEFI
-//!   - `ipxe.efi` (fallback) — UEFI with bundled drivers, if snponly fails on a NIC
+//!
 //! DriverMode::Builtin (v0.6.1 automatic fallback — iPXE's own NIC drivers,
 //! advertised when a firmware-net boot fails to chainload):
 //!   - `ipxe.pxe`            — Legacy x86 BIOS
 //!   - `ipxe-i386.efi`       — IA32 UEFI
 //!   - `ipxe.efi`            — x86_64 UEFI (built from source with PNG)
 //!   - `ipxe-arm64.efi`      — ARM64 UEFI
 //!
 //!   - `wimboot`             — Windows boot shim (fetched separately for WIM chains)
 #![forbid(unsafe_code)]
-use openpxe_core::ClientArch;
+use openpxe_core::{ClientArch, DriverMode};
 use rust_embed::Embed;
 #[derive(Embed)]
 #[folder = "../../assets/ipxe/"]
 #[include = "*.kpxe"]
 #[include = "*.efi"]
 #[include = "*.pxe"]
 #[include = "wimboot"]
 pub struct IpxeAssets;
-/// Return the embedded iPXE binary for `arch`, or `None` if we didn't bundle
+/// Return a named embedded asset (e.g. `snponly.efi`, `wimboot`) as a
-/// one for that architecture.
+/// `Cow` over the embedded bytes. In release builds the data is borrowed
-#[must_use]
+/// straight from the binary's rodata — **zero copy** — which matters
-pub fn bootfile_bytes(arch: ClientArch) -> Option<Vec<u8>> {
+/// because the TFTP and HTTP serving paths hit this for every boot
-    let name = arch.ipxe_bootfile()?;
+/// (`ipxe.efi` is ~1 MiB). Debug builds read from disk and return Owned.
    IpxeAssets::get(name).map(|f| f.data.into_owned())
 }
 /// Return a named asset directly (e.g. `wimboot`, or a fallback `ipxe.efi`).
 #[must_use]
 pub fn asset_bytes(name: &str) -> Option<Vec<u8>> {
    IpxeAssets::get(name).map(|f| f.data.into_owned())
 }
 /// Same as [`asset_bytes`] but returns the embedded slice directly,
 /// avoiding the heap copy when the caller only needs to read the
 /// payload. Falls back to None for unknown names.
 #[must_use]
 pub fn asset_slice(name: &str) -> Option<std::borrow::Cow<'static, [u8]>> {
    IpxeAssets::get(name).map(|f| f.data)
@@ -56,25 +53,48 @@ pub fn list_assets() -> Vec<String> {
        .collect()
 }
-/// Log at startup which iPXE binaries are present and which are missing.
+/// Log at startup which iPXE binaries are present and which are missing, for
 /// both driver modes. The Firmware-mode binaries are required for PXE on each
 /// arch; the Builtin-mode binaries are the optional automatic NIC-driver
 /// fallback (v0.6.1) — without one, escalation simply can't help that arch.
 pub fn log_availability() {
    let have: std::collections::HashSet<String> = list_assets().into_iter().collect();
-    let needed = [
+    let arches = [
-        (ClientArch::LegacyX86, "undionly.kpxe"),
+        ClientArch::LegacyX86,
-        (ClientArch::Ia32Uefi, "snponly-i386.efi"),
+        ClientArch::Ia32Uefi,
-        (ClientArch::X64Uefi, "snponly.efi"),
+        ClientArch::X64Uefi,
-        // ARM32 UEFI deferred — no upstream snponly binary published.
+        // ARM32 UEFI deferred — no upstream binary published in either mode.
-        (ClientArch::Arm64Uefi, "snponly-arm64.efi"),
+        ClientArch::Arm64Uefi,
    ];
-    for (arch, name) in needed {
+    for arch in arches {
-        if have.contains(name) {
+        for mode in [DriverMode::Firmware, DriverMode::Builtin, DriverMode::Shim] {
-            tracing::info!(target: "openpxe::ipxe", "bundled iPXE for {}: {}", arch.as_str(), name);
+            let Some(name) = arch.ipxe_bootfile_mode(mode) else {
-        } else {
+                continue;
-            tracing::warn!(
+            };
-                target: "openpxe::ipxe",
+            if have.contains(name) {
-                "MISSING iPXE binary for {}: {} — clients of this arch will not PXE boot",
+                tracing::info!(
-                arch.as_str(), name
+                    target: "openpxe::ipxe",
-            );
+                    "bundled iPXE for {} [{mode:?}]: {name}", arch.as_str()
                );
            } else if mode == DriverMode::Firmware {
                tracing::warn!(
                    target: "openpxe::ipxe",
                    "MISSING iPXE binary for {} [{mode:?}]: {name} — clients of this arch will not PXE boot",
                    arch.as_str()
                );
            } else if mode == DriverMode::Builtin {
                tracing::info!(
                    target: "openpxe::ipxe",
                    "no built-in-driver fallback for {} [{mode:?}]: {name} — auto NIC driver escalation unavailable for this arch",
                    arch.as_str()
                );
            } else {
                tracing::info!(
                    target: "openpxe::ipxe",
                    "no signed shim chain for {} [{mode:?}]: {name} — Secure Boot clients of this arch can't be served",
                    arch.as_str()
                );
            }
        }
    }
 }
@@ -12,16 +12,13 @@ workspace = true
 [dependencies]
 openpxe-core.workspace = true
 tokio = { workspace = true }
 tokio-util = { workspace = true }
 serde.workspace = true
 serde_json.workspace = true
 tracing.workspace = true
 thiserror.workspace = true
 anyhow.workspace = true
 sha2.workspace = true
 hex.workspace = true
 bcrypt.workspace = true
 uuid.workspace = true
 time.workspace = true
 parking_lot.workspace = true
 bytes.workspace = true
@@ -39,9 +36,21 @@ image = { version = "0.25", default-features = false, features = ["png", "jpeg",
 # kernel mount. See crates/iso-store/src/nfs_share.rs for usage.
 nfs3_client = { workspace = true }
 nfs3_types = { workspace = true }
 # v0.5.5: pure-Rust SSH/SFTP client (ring backend) for the SFTP remote
 # share path. See crates/iso-store/src/sftp_share.rs for usage.
 russh = { workspace = true }
 russh-sftp = { workspace = true }
 # Needed for the Stream trait that wraps the mpsc receiver feeding
 # NFS read-loop bytes into axum's Body::from_stream.
 futures = { workspace = true }
 [dev-dependencies]
 tempfile = "3.12"
 [features]
 # v0.7.4: exposes the in-memory ISO9660 test-image builder
 # (`iso_fs::testiso`) to other crates' integration tests, so http-api's
 # full-flow tests can synthesize ISOs with real directory trees — the
 # probe-based introspection no longer classifies label-only blobs.
 # Never enabled in production builds.
 test-image = []
@@ -25,9 +25,11 @@ pub enum BootKind {
        wimboot_url: String,
        files: Vec<(String, String)>,
    },
-    /// Last-resort: SAN-boot the ISO as an emulated CD. Only works for small
+    /// SAN-boot the raw ISO as an emulated CD (iPXE `sanboot`). The emulated
-    /// ISOs (<~1 GiB) and older distros. Kept for completeness, not the
+    /// CD is backed by on-demand HTTP range reads, so ISO size is *not* a
-    /// default.
+    /// constraint — this is the primary path for Windows (v0.5.8) and for any
    /// El Torito-bootable image we don't special-case: ESXi/VMvisor
    /// installers, BSDs, firmware/diagnostic tools, custom spins (v0.6.0).
    SanBootIso { iso_url: String },
 }
@@ -1,19 +1,36 @@
 //! ISO introspection — identify the distro family and locate kernel/initrd.
 //!
-//! We avoid a full ISO9660/Joliet/Rock-Ridge parser by reading a small number
+//! v0.7.4 rewrite: detection is **probe-based**. Instead of grepping raw
-//! of well-known files via `isoinfo` (from cdrtools/genisoimage) when it's on
+//! sectors for filename strings (which false-positived — any Linux ISO
-//! the path. As a pure-Rust fallback we do a crude scan: read the volume
+//! shipping GRUB/syslinux chainload modules contains the literal
-//! descriptor at offset 0x8000 to grab the volume label, and grep for known
+//! "bootmgr", so gparted-live classified as Windows), we walk the
-//! filenames by scanning raw sectors — good enough to tell Debian from RHEL
+//! ISO9660 directory tree via [`crate::iso_fs`] and check whether the
-//! most of the time, without shelling out.
+//! well-known boot files actually exist. The same probes run over local
 //! files and remote NFS/SFTP shares — remote ISOs finally classify
 //! instead of registering as `Unknown`.
 //!
-//! The returned `IntrospectionReport` is what `BootEntry`s get generated from.
+//! Layered, first-decisive-answer-wins:
 //!   1. PVD volume label → family hint.
 //!   2. El Torito boot-catalog presence (the "bootable at all" signal).
 //!   3. `/sources/boot.wim` directory probe → Windows install media.
 //!   4. Linux probe table → verified kernel+initrd paths. A probe match
 //!      both classifies the family and (for the families whose boot
 //!      arguments we render) yields kernel paths that are *known to
 //!      exist* — no more guessed paths that 404 at boot.
 //!   5. Bulk byte scan for UDF Windows markers — local images only
 //!      (modern Windows ISOs hide their tree from ISO9660; remote scans
 //!      skip this so a share rescan doesn't stream 16 MiB per ISO).
 //!   6. Filename tokens — the last-resort hint, and the only signal
 //!      available for SMB shares (smbclient cannot seek).
 //!
 //! The returned `IntrospectionReport` is what `BootEntry`s get generated
 //! from.
 use crate::iso_fs::{self, CachingReadAt, FileReadAt, IsoReadAt, SECTOR};
 use serde::{Deserialize, Serialize};
 use std::io::{Read, Seek, SeekFrom};
 use std::path::Path;
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
 #[serde(rename_all = "snake_case")]
 pub enum DistroFamily {
    DebianUbuntu,
@@ -22,98 +39,295 @@ pub enum DistroFamily {
    Arch,
    Alpine,
    WindowsPe,
    #[default]
    Unknown,
 }
-#[derive(Debug, Clone, Serialize, Deserialize)]
+/// Bumped whenever the introspection logic changes in a way that should
 /// re-classify already-uploaded ISOs. On startup the store re-runs
 /// `introspect` on any *local* ISO whose persisted report predates this
 /// revision (see `IsoStore::load_from_disk`), so an upgrade fixes stale
 /// metadata without the operator having to delete and re-upload.
 ///
 /// rev 1 (v0.5.9): added El Torito boot-catalog detection + broadened
 /// Windows (UDF/UTF-16) detection.
 /// rev 2 (v0.7.4): probe-based detection. Fixes Linux live ISOs that
 /// classified as Windows via the raw "bootmgr" byte grep, verifies
 /// kernel/initrd paths exist before emitting them, and adds the Debian
 /// live / netinst / CoreOS shapes. Remote (NFS/SFTP) introspection
 /// caches key off this rev too, so the cache self-invalidates.
 /// rev 3 (v0.7.5): Joliet namespace fallback + gap-tolerant El Torito /
 /// descriptor scans. Without this bump, images the rev-2 logic flagged
 /// as data ISOs (mangled-primary appliance images, filler-sector boot
 /// records) would never re-probe and stay mislabeled.
 /// rev 4 (v0.8.0): dropped the over-broad "microsoft" UTF-16 bulk-scan
 /// marker that classified any Secure-Boot-signed non-Windows bootable
 /// (memtest86, signed BSDs, firmware tools) as Windows — the string
 /// lives in the FAT long-filename entries of their MS-signed EFI loader.
 /// The bump re-probes those so they drop the bogus Windows label.
 pub const INTROSPECT_REV: u32 = 4;
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
 pub struct IntrospectionReport {
    pub family: DistroFamily,
    pub volume_label: Option<String>,
-    /// Kernel path inside the ISO (e.g. `/casper/vmlinuz`, `/isolinux/vmlinuz`).
+    /// Kernel path inside the ISO (e.g. `/casper/vmlinuz`). v0.7.4: only
    /// set when the path was verified to exist *and* the family's boot
    /// arguments are known-good for direct kernel boot; families we can
    /// only classify (Debian live, CoreOS live) leave it `None` so the
    /// entry generator falls back to sanboot instead of a broken boot.
    pub kernel_path: Option<String>,
    /// Initrd path(s) inside the ISO. May be multiple for multi-initrd setups.
    pub initrd_paths: Vec<String>,
    /// True if `sources/boot.wim` present — Windows install media.
    pub has_boot_wim: bool,
    /// True if the ISO carries an El Torito boot catalog — i.e. it is
    /// bootable by BIOS/UEFI firmware and therefore by iPXE `sanboot`
    /// (emulated CD). This is the authoritative "can this boot at all?"
    /// signal for ISOs we can't classify as Linux or Windows (BSDs, ESXi,
    /// firmware tools, custom spins). A *data* ISO (e.g. a VMware vCenter
    /// appliance bundle) has no boot catalog and reports `false`. v0.5.9.
    #[serde(default)]
    pub el_torito: bool,
    /// Revision of the introspection logic that produced this report.
    /// `0` means "never introspected" (pre-v0.5.9 metadata, or a remote
    /// ISO whose probe hasn't run / can't run) — the entry generator
    /// treats those optimistically (sanboot) and the UI labels them.
    #[serde(default)]
    pub introspect_rev: u32,
 }
-/// Probe an ISO file on disk. Never fails — on unrecoverable IO error we log
+/// One row of the Linux detection table.
-/// and return an `Unknown` family so the uploader still sees a record.
+///
 /// `emit_kernel` distinguishes "we can boot this directly" from "we can
 /// only classify it". Families marked `false` have boot protocols our
 /// cmdline renderer doesn't speak yet (Debian-live `boot=live fetch=`,
 /// d-i netinst, CoreOS `coreos.live.rootfs_url=`) — for those the probe
 /// sets the family for the UI/menu but leaves `kernel_path` unset so the
 /// ISO keeps its (working) sanboot entry instead of gaining a broken
 /// kernel one. Strictly fewer broken boots than guessing.
 struct LinuxProbe {
    family: DistroFamily,
    kernel: &'static str,
    initrd_candidates: &'static [&'static str],
    emit_kernel: bool,
 }
 const LINUX_PROBES: &[LinuxProbe] = &[
    // Ubuntu and friends (casper) — the classic direct-boot shape.
    LinuxProbe {
        family: DistroFamily::DebianUbuntu,
        kernel: "/casper/vmlinuz",
        initrd_candidates: &["/casper/initrd", "/casper/initrd.lz", "/casper/initrd.gz"],
        emit_kernel: true,
    },
    // Debian-live derivatives: gparted-live, Clonezilla, Kali live, tails.
    // Classification only — live-boot needs `boot=live fetch=<squashfs>`
    // which we don't render yet; sanboot of these images works today.
    LinuxProbe {
        family: DistroFamily::DebianUbuntu,
        kernel: "/live/vmlinuz",
        initrd_candidates: &["/live/initrd.img", "/live/initrd"],
        emit_kernel: false,
    },
    // Debian installer (netinst/DVD). Classification only for the same
    // reason — d-i sanboots fine.
    LinuxProbe {
        family: DistroFamily::DebianUbuntu,
        kernel: "/install.amd/vmlinuz",
        initrd_candidates: &["/install.amd/initrd.gz"],
        emit_kernel: false,
    },
    // Anaconda family: RHEL, CentOS, Alma, Rocky, Fedora — and their
    // many derivatives (Cisco ISE, Nagios appliances, …). The CoreOS
    // variant of this shape is special-cased after the table.
    LinuxProbe {
        family: DistroFamily::RhelFedora,
        kernel: "/images/pxeboot/vmlinuz",
        initrd_candidates: &["/images/pxeboot/initrd.img"],
        emit_kernel: true,
    },
    LinuxProbe {
        family: DistroFamily::OpenSuse,
        kernel: "/boot/x86_64/loader/linux",
        initrd_candidates: &["/boot/x86_64/loader/initrd"],
        emit_kernel: true,
    },
    LinuxProbe {
        family: DistroFamily::Arch,
        kernel: "/arch/boot/x86_64/vmlinuz-linux",
        initrd_candidates: &["/arch/boot/x86_64/initramfs-linux.img"],
        emit_kernel: true,
    },
    LinuxProbe {
        family: DistroFamily::Alpine,
        kernel: "/boot/vmlinuz-lts",
        initrd_candidates: &["/boot/initramfs-lts"],
        emit_kernel: true,
    },
 ];
 /// CoreOS-style live images (RHCOS, FCOS, OpenShift agent ISOs) carry
 /// the anaconda pxeboot layout *plus* a rootfs image. Direct kernel boot
 /// of those requires `coreos.live.rootfs_url=` (and for agent ISOs, the
 /// ignition config embedded in the ISO device) — neither of which a
 /// plain `inst.repo=` cmdline provides. Their sanboot path works, so
 /// they classify as RHEL-family but keep the sanboot entry.
 const COREOS_ROOTFS: &str = "/images/pxeboot/rootfs.img";
 /// Probe an ISO file on disk. Never fails — on unrecoverable IO error we
 /// log and return an `Unknown` family so the uploader still sees a record.
 pub fn introspect(path: &Path) -> IntrospectionReport {
-    let mut report = IntrospectionReport {
+    let filename = path
-        family: DistroFamily::Unknown,
+        .file_name()
-        volume_label: None,
+        .map(|s| s.to_string_lossy().into_owned())
-        kernel_path: None,
+        .unwrap_or_default();
-        initrd_paths: Vec::new(),
+    let Ok(f) = std::fs::File::open(path) else {
        has_boot_wim: false,
    };
    let Ok(mut f) = std::fs::File::open(path) else {
        tracing::warn!(target: "openpxe::iso", "cannot open ISO for introspection: {}", path.display());
-        return report;
+        return IntrospectionReport {
            introspect_rev: INTROSPECT_REV,
            ..Default::default()
        };
    };
    let len = f.metadata().map_or(0, |m| m.len());
    // `FileReadAt` completes every read inline (no real awaits), so this
    // light-weight block_on never parks; callers already run us on the
    // blocking pool.
    futures::executor::block_on(introspect_reader(
        &mut FileReadAt::new(f),
        len,
        &filename,
        true,
    ))
 }
 /// The detection core, generic over any random-access source. `total_len`
 /// is the image size (every caller knows it — file metadata locally, the
 /// share listing remotely) and bounds the bulk scan, since `IsoReadAt`
 /// reads are exact-or-error. `filename` feeds the last-resort token
 /// heuristics; `allow_bulk_scan` gates the 16 MiB UDF-Windows byte scan
 /// (local files only — remote shares would stream that much per ISO per
 /// rescan).
 pub async fn introspect_reader<R: IsoReadAt + Send>(
    r: &mut R,
    total_len: u64,
    filename: &str,
    allow_bulk_scan: bool,
 ) -> IntrospectionReport {
    let mut report = IntrospectionReport {
        introspect_rev: INTROSPECT_REV,
        ..Default::default()
    };
-    // ISO9660 Primary Volume Descriptor at LBA 16 (offset 0x8000), 2048 bytes.
+    // Everything sector-shaped goes through one caching wrapper: the
-    // Bytes 40..72 are the Volume Identifier (space-padded, d-characters).
+    // descriptor-set sectors are read once and shared between the label
-    let mut pvd = [0u8; 2048];
+    // scan, the El Torito walk, and the namespace-root lookups; the
-    if f.seek(SeekFrom::Start(0x8000)).is_ok() && f.read_exact(&mut pvd).is_ok() {
+    // probe table's repeated root/subdirectory reads collapse the same
-        // Byte 0 must be 0x01 (primary descriptor), bytes 1..6 = "CD001".
+    // way — over NFS/SFTP that's the difference between ~6 and ~60+
-        if pvd[0] == 0x01 && &pvd[1..6] == b"CD001" {
+    // round-trips per ISO.
-            let label_raw = &pvd[40..72];
+    {
-            let label = String::from_utf8_lossy(label_raw).trim().to_string();
+        let mut cr = CachingReadAt::new(r);
        // ISO9660 Primary Volume Descriptor: bytes 40..72 are the volume
        // identifier (space-padded). v0.7.5: located by scanning the
        // descriptor set (tolerating filler sectors) instead of assuming
        // a pristine sector 16.
        if let Some(pvd) = iso_fs::find_descriptor(&mut cr, false).await {
            let label = String::from_utf8_lossy(&pvd[40..72]).trim().to_string();
            if !label.is_empty() {
                report.volume_label = Some(label.clone());
                report.family = family_from_label(&label);
                report.volume_label = Some(label);
            }
        }
        report.el_torito = detect_el_torito(&mut cr).await;
        if iso_fs::exists(&mut cr, "/sources/boot.wim").await {
            report.has_boot_wim = true;
            report.family = DistroFamily::WindowsPe;
        } else {
            for probe in LINUX_PROBES {
                if !iso_fs::exists(&mut cr, probe.kernel).await {
                    continue;
                }
                let mut initrd = None;
                for cand in probe.initrd_candidates {
                    if iso_fs::exists(&mut cr, cand).await {
                        initrd = Some((*cand).to_string());
                        break;
                    }
                }
                let Some(initrd) = initrd else { continue };
                // Content beats label: a rebadged derivative (volume
                // label "ISE-3.2") with the anaconda layout is
                // RHEL-family no matter what the label says.
                report.family = probe.family;
                let coreos = probe.family == DistroFamily::RhelFedora
                    && iso_fs::exists(&mut cr, COREOS_ROOTFS).await;
                if probe.emit_kernel && !coreos {
                    report.kernel_path = Some(probe.kernel.to_string());
                    report.initrd_paths = vec![initrd];
                }
                break;
            }
        }
    }
-    // Cheap content scan: read the first ~64 MiB, look for signature filenames.
+    // Modern Windows 10/11 ISOs are UDF — their tree is invisible to the
-    // This is enough to identify `sources/boot.wim` (Windows) and common
+    // ISO9660 walk and the volume label is a cryptic Microsoft string.
-    // kernel/initrd paths for the major Linux distros.
+    // Scan the first 16 MiB for well-known markers, ASCII and UTF-16LE.
-    let _ = f.seek(SeekFrom::Start(0));
+    // Runs after the Linux probes so a Linux ISO that *contains* the
-    let scan_bytes = 64 * 1024 * 1024;
+    // string "bootmgr" (GRUB/syslinux chainload modules do) has already
-    let mut buf = vec![0u8; 1024 * 1024];
+    // classified and never reaches this — that ordering is the v0.7.4
-    let mut read_total = 0usize;
+    // gparted-misdetection fix.
-    let mut haystack = Vec::with_capacity(scan_bytes.min(32 * 1024 * 1024));
+    if report.family == DistroFamily::Unknown && allow_bulk_scan {
-    while read_total < scan_bytes {
+        if let Some(win) = bulk_windows_scan(r, total_len).await {
        let n = f.read(&mut buf).unwrap_or(0);
        if n == 0 {
            break;
        }
        haystack.extend_from_slice(&buf[..n]);
        read_total += n;
    }
    if contains_ascii(&haystack, b"sources/boot.wim")
        || contains_ascii(&haystack, b"SOURCES/BOOT.WIM")
        || contains_ascii(&haystack, b"SOURCES\\BOOT.WIM")
    {
        report.has_boot_wim = true;
        if report.family == DistroFamily::Unknown {
            report.family = DistroFamily::WindowsPe;
            report.has_boot_wim = win;
        }
    }
-    // Best-effort kernel/initrd path guess from family. These paths are what
+    // Last resort: filename tokens. The only signal for SMB-sourced ISOs
-    // distro ISOs conventionally ship at — we don't verify extraction here;
+    // and renamed/UDF images that defeated everything above.
-    // that happens in the store after introspection.
+    if report.family == DistroFamily::Unknown {
-    let (k, i) = guess_kernel_initrd(report.family);
+        report.family = family_from_filename(filename);
-    report.kernel_path = k.map(str::to_string);
+    }
    report.initrd_paths = i.iter().map(std::string::ToString::to_string).collect();
    report
 }
 /// Provisional report for a remote ISO that hasn't been (or can't be)
 /// content-probed yet: family from the filename, `introspect_rev` left
 /// at 0 so the entry generator keeps the optimistic sanboot entry and
 /// the UI shows it as awaiting introspection. Used by all three share
 /// managers at registration; NFS/SFTP upgrade it in the background.
 #[must_use]
 pub fn provisional_report(filename: &str) -> IntrospectionReport {
    IntrospectionReport {
        family: family_from_filename(filename),
        ..Default::default()
    }
 }
 fn family_from_label(label: &str) -> DistroFamily {
    let l = label.to_ascii_lowercase();
-    if l.contains("ubuntu") || l.contains("debian") || l.contains("mint") {
+    if l.contains("ubuntu")
        || l.contains("debian")
        || l.contains("mint")
        || l.contains("kali")
        || l.contains("gparted")
        || l.contains("clonezilla")
    {
        DistroFamily::DebianUbuntu
    } else if l.contains("rhel")
        || l.contains("centos")
        || l.contains("fedora")
        || l.contains("rocky")
        || l.contains("alma")
        || l.contains("rhcos")
        || l.contains("coreos")
        || l.contains("openshift")
        || l.contains("okd")
    {
        DistroFamily::RhelFedora
    } else if l.contains("suse") || l.contains("opensuse") {
@@ -129,23 +343,97 @@ fn family_from_label(label: &str) -> DistroFamily {
    }
 }
-fn guess_kernel_initrd(family: DistroFamily) -> (Option<&'static str>, Vec<&'static str>) {
+/// Filename token heuristic — `AlmaLinux-9.5-x86_64-dvd.iso` says what
-    match family {
+/// it is even when we can't read a byte of it. Tokens are the filename
-        DistroFamily::DebianUbuntu => (Some("/casper/vmlinuz"), vec!["/casper/initrd"]),
+/// split on every non-alphanumeric character, so "almalinux", "rhel",
-        DistroFamily::RhelFedora => (
+/// "win11" match without "search" tripping the "arch" token.
-            Some("/images/pxeboot/vmlinuz"),
+pub fn family_from_filename(filename: &str) -> DistroFamily {
-            vec!["/images/pxeboot/initrd.img"],
+    if filename_looks_windows(filename) {
-        ),
+        return DistroFamily::WindowsPe;
-        DistroFamily::OpenSuse => (
+    }
-            Some("/boot/x86_64/loader/linux"),
+    let lower = filename.to_ascii_lowercase();
-            vec!["/boot/x86_64/loader/initrd"],
+    let tokens: Vec<&str> = lower
-        ),
+        .split(|c: char| !c.is_ascii_alphanumeric())
-        DistroFamily::Arch => (
+        .filter(|t| !t.is_empty())
-            Some("/arch/boot/x86_64/vmlinuz-linux"),
+        .collect();
-            vec!["/arch/boot/x86_64/initramfs-linux.img"],
+    let has = |t: &str| tokens.contains(&t);
-        ),
+    if has("ubuntu")
-        DistroFamily::Alpine => (Some("/boot/vmlinuz-lts"), vec!["/boot/initramfs-lts"]),
+        || has("debian")
-        DistroFamily::WindowsPe | DistroFamily::Unknown => (None, Vec::new()),
+        || has("mint")
        || has("kali")
        || has("gparted")
        || has("clonezilla")
        || has("tails")
    {
        DistroFamily::DebianUbuntu
    } else if has("rhel")
        || has("centos")
        || has("almalinux")
        || has("alma")
        || has("rocky")
        || has("rockylinux")
        || has("fedora")
        || has("rhcos")
        || has("coreos")
        || has("openshift")
        || has("okd")
    {
        DistroFamily::RhelFedora
    } else if has("opensuse") || has("suse") || has("sles") {
        DistroFamily::OpenSuse
    } else if has("arch") || has("archlinux") || has("manjaro") {
        DistroFamily::Arch
    } else if has("alpine") {
        DistroFamily::Alpine
    } else {
        DistroFamily::Unknown
    }
 }
 /// Scan the first 16 MiB (or the whole image when smaller) for Windows
 /// markers. Returns `Some(has_boot_wim)` on a hit, `None` when nothing
 /// Windows-shaped is found.
 async fn bulk_windows_scan<R: IsoReadAt + Send>(r: &mut R, total_len: u64) -> Option<bool> {
    const SCAN_BYTES: u64 = 16 * 1024 * 1024;
    const CHUNK: u64 = 1024 * 1024;
    let budget = SCAN_BYTES.min(total_len);
    let mut haystack = Vec::with_capacity(usize::try_from(budget).unwrap_or(0));
    let mut offset = 0u64;
    while offset < budget {
        // Reads are exact-or-error, so clamp the final chunk to what the
        // image actually has — netboot.xyz is 2.3 MB, not 16.
        let want = u32::try_from(CHUNK.min(budget - offset)).unwrap_or(u32::MAX);
        let Ok(chunk) = r.read_at(offset, want).await else {
            break; // read error: scan what we have
        };
        offset += chunk.len() as u64;
        haystack.extend_from_slice(&chunk);
    }
    if haystack.is_empty() {
        return None;
    }
    let boot_wim = contains_ascii(&haystack, b"sources/boot.wim")
        || contains_ascii(&haystack, b"sources\\boot.wim")
        || contains_utf16le_ci(&haystack, "boot.wim");
    if boot_wim {
        return Some(true);
    }
    let ascii_markers: [&[u8]; 3] = [b"bootmgr", b"sources/install.wim", b"sources/install.esd"];
    // v0.8.0: dropped the bare "microsoft" marker. It matched the
    // Microsoft-signed Secure-Boot EFI loader that memtest86 (and signed
    // BSDs / firmware tools) ship — the string lives in the loader's FAT
    // long-filename entries — so any signed non-Windows bootable
    // false-classified as Windows. The remaining markers are all
    // Windows-exclusive filenames.
    let utf16_markers = ["bootmgr", "install.wim"];
    let hit = ascii_markers.iter().any(|m| contains_ascii(&haystack, m))
        || utf16_markers
            .iter()
            .any(|m| contains_utf16le_ci(&haystack, m));
    if hit {
        Some(false)
    } else {
        None
    }
 }
@@ -158,9 +446,88 @@ fn contains_ascii(haystack: &[u8], needle: &[u8]) -> bool {
        .any(|w| w.eq_ignore_ascii_case(needle))
 }
 /// Case-insensitive search for an ASCII string encoded as UTF-16LE — the
 /// way UDF (and thus modern Windows ISOs) store filenames. Each character
 /// is two bytes: the ASCII low byte (compared case-insensitively) followed
 /// by a 0 high byte. v0.5.8.
 fn contains_utf16le_ci(haystack: &[u8], ascii: &str) -> bool {
    let n = ascii.len();
    if n == 0 || haystack.len() < n * 2 {
        return false;
    }
    let lower: Vec<u8> = ascii.bytes().map(|b| b.to_ascii_lowercase()).collect();
    haystack.windows(n * 2).any(|w| {
        lower
            .iter()
            .enumerate()
            .all(|(i, &c)| w[i * 2 + 1] == 0 && w[i * 2].to_ascii_lowercase() == c)
    })
 }
 /// Filename heuristic: a stock Windows ISO almost always carries an obvious
 /// token in its name (e.g. `..._windows_11_...`, `Win10`, `winserver`).
 /// v0.7.4: takes the bare filename instead of a `Path` so the same check
 /// runs against remote share listings.
 fn filename_looks_windows(filename: &str) -> bool {
    let name = filename.to_ascii_lowercase();
    const TOKENS: [&str; 6] = [
        "windows",
        "winpe",
        "win10",
        "win11",
        "winserver",
        "win-server",
    ];
    TOKENS.iter().any(|t| name.contains(t))
 }
 /// The boot-system identifier string in an El Torito Boot Record Volume
 /// Descriptor (offset 7, NUL-padded to 32 bytes).
 const EL_TORITO_ID: &[u8] = b"EL TORITO SPECIFICATION";
 /// Detect an El Torito boot catalog — the marker that an ISO is bootable
 /// by BIOS/UEFI firmware (and thus by iPXE `sanboot`).
 ///
 /// The ISO9660 Volume Descriptor Set starts at LBA 16 and runs one
 /// 2048-byte descriptor per sector; a Boot Record descriptor (type 0x00)
 /// whose 32-byte boot system identifier reads "EL TORITO SPECIFICATION"
 /// means the image declares a boot catalog. We only confirm its presence
 /// — we don't parse the catalog (sanboot/the firmware does that).
 ///
 /// v0.7.5: the walk no longer aborts at the first non-`CD001` sector or
 /// stops at a Set Terminator. Sloppy mastering tools (appliance ISOs
 /// especially) leave zeroed filler sectors inside the descriptor area or
 /// odd descriptor ordering, which used to hide a real boot record and
 /// flag a bootable image as a data ISO. All 16 sectors are examined —
 /// the signature is 25 exact bytes, so scanning past the terminator
 /// (into e.g. a UDF volume recognition sequence) cannot false-positive.
 /// The cap keeps a malformed image from spinning us. v0.5.9 originally;
 /// reader-generic since v0.7.4.
 async fn detect_el_torito<R: IsoReadAt + Send>(r: &mut R) -> bool {
    for lba in 16u64..32 {
        let Ok(vd) = r.read_at(lba * SECTOR, 2048).await else {
            // Past end of a tiny image — nothing more to examine.
            return false;
        };
        if &vd[1..6] != b"CD001" {
            continue; // filler/garbage sector — keep walking
        }
        if vd[0] == 0x00 && vd[7..7 + EL_TORITO_ID.len()] == *EL_TORITO_ID {
            return true;
        }
    }
    false
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    use crate::iso_fs::testiso::{MemReadAt, TestIsoBuilder};
    fn introspect_mem(img: Vec<u8>, filename: &str, bulk: bool) -> IntrospectionReport {
        let len = img.len() as u64;
        futures::executor::block_on(introspect_reader(&mut MemReadAt(img), len, filename, bulk))
    }
    #[test]
    fn label_matching() {
@@ -177,6 +544,268 @@ mod tests {
            DistroFamily::OpenSuse
        );
        assert_eq!(family_from_label("ARCH_202604"), DistroFamily::Arch);
        assert_eq!(
            family_from_label("GParted-live"),
            DistroFamily::DebianUbuntu
        );
        assert_eq!(family_from_label("rhcos-417"), DistroFamily::RhelFedora);
        assert_eq!(family_from_label("weird-custom"), DistroFamily::Unknown);
    }
    #[test]
    fn gparted_shape_is_not_windows() {
        // The v0.7.4 regression test: a Debian-live image whose payload
        // contains the literal string "bootmgr" (as GRUB/syslinux
        // chainload modules do). The old byte-grep classified this as
        // WindowsPe; the probe order must classify Debian first.
        let img = TestIsoBuilder::new("GParted-live")
            .el_torito(true)
            .file("/live/vmlinuz", b"KERNEL")
            .file("/live/initrd.img", b"INITRD")
            .file("/boot/grub/chain.mod", b"xxx bootmgr xxx")
            .build();
        let r = introspect_mem(img, "gparted-live-1.8.1-3-amd64.iso", true);
        assert_eq!(r.family, DistroFamily::DebianUbuntu);
        // Classification only — live-boot args aren't rendered yet, so no
        // kernel entry; sanboot (via el_torito) keeps working.
        assert!(r.kernel_path.is_none());
        assert!(r.el_torito);
        assert_eq!(r.introspect_rev, INTROSPECT_REV);
    }
    #[test]
    fn casper_shape_verifies_kernel_and_initrd() {
        let img = TestIsoBuilder::new("Ubuntu-Server 24.04.1 LTS amd64")
            .el_torito(true)
            .file("/casper/vmlinuz", b"K")
            .file("/casper/initrd", b"I")
            .build();
        let r = introspect_mem(img, "ubuntu-24.04.1-live-server-amd64.iso", true);
        assert_eq!(r.family, DistroFamily::DebianUbuntu);
        assert_eq!(r.kernel_path.as_deref(), Some("/casper/vmlinuz"));
        assert_eq!(r.initrd_paths, vec!["/casper/initrd".to_string()]);
    }
    #[test]
    fn anaconda_shape_emits_verified_paths() {
        let img = TestIsoBuilder::new("AlmaLinux-9-5-x86_64-dvd")
            .el_torito(true)
            .file("/images/pxeboot/vmlinuz", b"K")
            .file("/images/pxeboot/initrd.img", b"I")
            .build();
        let r = introspect_mem(img, "AlmaLinux-9.5-x86_64-dvd.iso", true);
        assert_eq!(r.family, DistroFamily::RhelFedora);
        assert_eq!(r.kernel_path.as_deref(), Some("/images/pxeboot/vmlinuz"));
    }
    #[test]
    fn coreos_shape_classifies_but_keeps_sanboot() {
        // RHCOS / OpenShift agent ISOs: anaconda layout + rootfs.img.
        // Direct kernel boot needs coreos.live.rootfs_url (and agent
        // ISOs their embedded ignition), so kernel_path must stay None.
        let img = TestIsoBuilder::new("rhcos-417.94.202501")
            .el_torito(true)
            .file("/images/pxeboot/vmlinuz", b"K")
            .file("/images/pxeboot/initrd.img", b"I")
            .file("/images/pxeboot/rootfs.img", b"R")
            .build();
        let r = introspect_mem(img, "rhcos-live.x86_64.iso", true);
        assert_eq!(r.family, DistroFamily::RhelFedora);
        assert!(
            r.kernel_path.is_none(),
            "CoreOS must not get a kernel entry"
        );
        assert!(r.el_torito);
    }
    #[test]
    fn boot_wim_probe_classifies_windows() {
        let img = TestIsoBuilder::new("CCCOMA_X64FRE_EN-US_DV9")
            .el_torito(true)
            .file("/sources/boot.wim", b"MSWIMMSWIM")
            .build();
        let r = introspect_mem(img, "whatever.iso", false);
        assert_eq!(r.family, DistroFamily::WindowsPe);
        assert!(r.has_boot_wim);
    }
    #[test]
    fn label_only_linux_without_verified_kernel_gets_no_kernel_path() {
        // Label says RHEL but the tree has no pxeboot files — the old
        // code guessed `/images/pxeboot/vmlinuz` and emitted an entry
        // that 404'd at boot. Now: family yes, kernel paths no.
        let img = TestIsoBuilder::new("RHEL-9-5-CUSTOM")
            .el_torito(true)
            .file("/readme.txt", b"hi")
            .build();
        let r = introspect_mem(img, "rhel-custom.iso", true);
        assert_eq!(r.family, DistroFamily::RhelFedora);
        assert!(r.kernel_path.is_none());
        assert!(r.initrd_paths.is_empty());
    }
    #[test]
    fn remote_skips_bulk_scan_but_filename_still_hints() {
        // No ISO9660 signatures at all (e.g. pure-UDF image read over a
        // share), bulk scan off: filename is the only signal.
        let img = vec![0u8; 64 * 1024];
        let r = introspect_mem(img.clone(), "Win11_24H2_English_x64.iso", false);
        assert_eq!(r.family, DistroFamily::WindowsPe);
        let r2 = introspect_mem(img, "mystery.iso", false);
        assert_eq!(r2.family, DistroFamily::Unknown);
    }
    #[test]
    fn filename_family_table() {
        use DistroFamily::*;
        let cases = [
            ("AlmaLinux-9.5-x86_64-dvd.iso", RhelFedora),
            ("CentOS-Stream-10-latest-x86_64-dvd1.iso", RhelFedora),
            ("rhel-9.0-x86_64-boot.iso", RhelFedora),
            ("rhcos-live.x86_64.iso", RhelFedora),
            ("openshift-4-21-9.agent.x86_64.iso", RhelFedora),
            ("ubuntu-24.04-desktop.iso", DebianUbuntu),
            ("gparted-live-1.8.1-3-amd64.iso", DebianUbuntu),
            ("archlinux-2026.05.01-x86_64.iso", Arch),
            ("arch-2026.05.01.iso", Arch),
            ("alpine-standard-3.21.0-x86_64.iso", Alpine),
            ("openSUSE-Leap-15.6-DVD-x86_64.iso", OpenSuse),
            ("en-us_windows_11_iot_enterprise.iso", WindowsPe),
            ("Win10_22H2_English_x64.iso", WindowsPe),
            ("netboot.xyz.iso", Unknown),
            ("ise-3.2.0.542a.SPA.x86_64.iso", Unknown),
            ("Macrium_5860_v2.iso", Unknown),
            // "search" must not trip the "arch" token.
            ("research-data.iso", Unknown),
        ];
        for (name, want) in cases {
            assert_eq!(family_from_filename(name), want, "{name}");
        }
    }
    #[test]
    fn provisional_report_keeps_rev_zero() {
        let r = provisional_report("rhel-9.0-x86_64-dvd.iso");
        assert_eq!(r.family, DistroFamily::RhelFedora);
        assert_eq!(
            r.introspect_rev, 0,
            "provisional must keep optimistic sanboot"
        );
        assert!(!r.el_torito);
    }
    #[test]
    fn utf16le_marker_matches_case_insensitively() {
        let s = "BOOT.WIM";
        let utf16: Vec<u8> = s.bytes().flat_map(|b| [b, 0]).collect();
        let mut hay = vec![0u8; 8];
        hay.extend_from_slice(&utf16);
        hay.extend_from_slice(&[1, 2, 3]);
        assert!(contains_utf16le_ci(&hay, "boot.wim"));
        assert!(contains_utf16le_ci(&hay, "Boot.Wim"));
        assert!(!contains_utf16le_ci(&hay, "install.wim"));
        assert!(!contains_utf16le_ci(b"boot.wim plain ascii", "boot.wim"));
    }
    #[test]
    fn el_torito_detected_through_reader() {
        let with = TestIsoBuilder::new("BOOTABLE").el_torito(true).build();
        let without = TestIsoBuilder::new("DATA").build();
        assert!(futures::executor::block_on(detect_el_torito(
            &mut MemReadAt(with)
        )));
        assert!(!futures::executor::block_on(detect_el_torito(
            &mut MemReadAt(without)
        )));
    }
    #[test]
    fn el_torito_survives_filler_sector_in_descriptor_area() {
        // v0.7.5 tolerance test: sloppy appliance mastering leaves a
        // zeroed sector inside the Volume Descriptor Set. The old walk
        // aborted at the first non-CD001 sector and flagged a genuinely
        // bootable image as a data ISO.
        let sector = SECTOR as usize;
        let mut img = TestIsoBuilder::new("GAPPY").el_torito(true).build();
        // Builder layout: PVD @16, Boot Record @17, terminator @18.
        // Move the BR to 18 (over the terminator) and zero out 17.
        img.copy_within(17 * sector..18 * sector, 18 * sector);
        img[17 * sector..18 * sector].fill(0);
        assert!(
            futures::executor::block_on(detect_el_torito(&mut MemReadAt(img))),
            "boot record behind a zeroed filler sector must still be found"
        );
    }
    #[test]
    fn joliet_only_image_classifies_via_fallback() {
        // Primary namespace bare, real tree only in Joliet — the v0.7.5
        // fallback must classify it (boot.wim probe) where v0.7.4 saw
        // "no installer files".
        let img = TestIsoBuilder::new("WIN_APPLIANCE")
            .el_torito(true)
            .joliet_only(true)
            .file("/sources/boot.wim", b"WIMWIM")
            .build();
        let r = introspect_mem(img, "appliance.iso", false);
        assert_eq!(r.family, DistroFamily::WindowsPe);
        assert!(r.has_boot_wim);
        assert!(r.el_torito);
        // Same for a Linux shape: verified kernel paths via Joliet.
        let img2 = TestIsoBuilder::new("CUSTOM-EL9")
            .el_torito(true)
            .joliet_only(true)
            .file("/images/pxeboot/vmlinuz", b"K")
            .file("/images/pxeboot/initrd.img", b"I")
            .build();
        let r2 = introspect_mem(img2, "custom-el9.iso", false);
        assert_eq!(r2.family, DistroFamily::RhelFedora);
        assert_eq!(r2.kernel_path.as_deref(), Some("/images/pxeboot/vmlinuz"));
    }
    #[test]
    fn filename_hint_catches_windows_isos() {
        assert!(filename_looks_windows(
            "en-us_windows_11_iot_enterprise_ltsc_2024_x64_dvd.iso"
        ));
        assert!(filename_looks_windows("Win10_22H2_English_x64.iso"));
        assert!(filename_looks_windows("winserver2022.iso"));
        assert!(!filename_looks_windows("ubuntu-24.04-desktop.iso"));
        assert!(!filename_looks_windows("Rocky-9.4-x86_64-dvd.iso"));
    }
    #[test]
    fn bulk_scan_catches_udf_windows_markers() {
        // A blob with no ISO9660 tree but a UTF-16 "install.wim" — the
        // UDF Windows shape after every probe missed.
        let mut img = vec![0u8; 256 * 1024];
        let marker: Vec<u8> = "install.wim".bytes().flat_map(|b| [b, 0]).collect();
        img[100_000..100_000 + marker.len()].copy_from_slice(&marker);
        let r = introspect_mem(img, "renamed.iso", true);
        assert_eq!(r.family, DistroFamily::WindowsPe);
        assert!(!r.has_boot_wim);
    }
    #[test]
    fn memtest_signed_efi_is_not_windows() {
        // v0.8.0 regression: PassMark MemTest86 ships a Microsoft-signed
        // Secure-Boot EFI loader, and "Microsoft" appears in its FAT
        // long-filename entries as UTF-16LE. The old bulk-scan "microsoft"
        // marker classified it (and any signed BSD / firmware tool) as
        // Windows. It must now classify as a generic bootable (sanboot).
        let mut img = TestIsoBuilder::new("MEMTEST86")
            .el_torito(true)
            .file("/EFI/BOOT/BOOTX64.EFI", b"signed-efi-app")
            .build();
        let marker: Vec<u8> = "Microsoft".bytes().flat_map(|b| [b, 0]).collect();
        img.extend_from_slice(&marker);
        let r = introspect_mem(img, "memtest86-iso.iso", true);
        assert_ne!(
            r.family,
            DistroFamily::WindowsPe,
            "a Microsoft-signed EFI loader is not Windows media"
        );
        assert!(r.el_torito, "still a bootable image");
    }
 }
@@ -0,0 +1,761 @@
 //! Read-only ISO9660 lookup over any random-access byte source.
 //!
 //! v0.7.4: generalized from the http-api crate's local-file-only walker so
 //! the same directory walk drives three consumers:
 //!
 //!   1. `iso_file` HTTP serving — locate `/casper/vmlinuz` inside a local
 //!      *or remote* (NFS/SFTP) ISO and stream just that byte range.
 //!   2. Introspection — probe for well-known kernel/initrd/boot.wim paths
 //!      instead of grepping raw sectors for filename strings (which
 //!      false-positived: any Linux ISO shipping GRUB/syslinux chainload
 //!      modules contains the literal "bootmgr" and used to classify as
 //!      Windows).
 //!   3. Remote introspection — the same probes over an NFSv3 READ3 /
 //!      SFTP seek-read connection, which is what finally classifies
 //!      share-sourced ISOs instead of registering them all as `Unknown`.
 //!
 //! Namespaces: the primary ISO9660 tree is tried first; on a miss the
 //! walk falls back to the **Joliet** supplementary namespace (v0.7.5) —
 //! Windows-oriented mastering tools often write a minimal/mangled
 //! primary tree with the real names only in Joliet. Rock Ridge stays
 //! ignored. Matching is case-insensitive with the `;1` version suffix
 //! and the trailing dot of extension-less strict-mastered names
 //! stripped.
 use std::collections::HashMap;
 use std::future::Future;
 use std::io::{Read, Seek, SeekFrom};
 use std::path::Path;
 pub const SECTOR: u64 = 2048;
 /// Upper bound on a single directory extent we'll buffer. Real distro ISO
 /// directories are a handful of KiB; the cap keeps a malformed or hostile
 /// image from asking us to allocate gigabytes.
 const MAX_DIR_BYTES: u64 = 4 * 1024 * 1024;
 /// Byte range of one file inside the ISO image.
 #[derive(Debug, Clone)]
 pub struct FileLocation {
    pub offset: u64,
    pub length: u64,
 }
 /// Random-access reads into an ISO image. Implemented by a local
 /// `std::fs::File`, the NFS and SFTP share readers, and the in-memory
 /// test image.
 ///
 /// The contract is `read_exact`-like: the returned buffer is exactly
 /// `len` bytes or the call errors. The future must be `Send` because
 /// remote introspection runs inside spawned tokio tasks.
 pub trait IsoReadAt {
    fn read_at(
        &mut self,
        offset: u64,
        len: u32,
    ) -> impl Future<Output = std::io::Result<Vec<u8>>> + Send;
 }
 /// Local-file reader. The reads are synchronous inside an async fn —
 /// callers run it either on the blocking pool (introspection at upload)
 /// or through [`lookup_local`]'s `block_on`, never on a hot runtime
 /// worker with real awaits pending.
 pub struct FileReadAt(std::fs::File);
 impl FileReadAt {
    #[must_use]
    pub fn new(f: std::fs::File) -> Self {
        Self(f)
    }
 }
 impl IsoReadAt for FileReadAt {
    async fn read_at(&mut self, offset: u64, len: u32) -> std::io::Result<Vec<u8>> {
        self.0.seek(SeekFrom::Start(offset))?;
        let mut buf = vec![0u8; len as usize];
        self.0.read_exact(&mut buf)?;
        Ok(buf)
    }
 }
 /// Exact-key read cache for the probe phase of introspection. The probe
 /// table looks up ~20 paths and every one of them re-reads the root
 /// directory (and usually one shared subdirectory); over NFS/SFTP that
 /// would be 20 identical round-trips. Directory reads repeat with the
 /// exact same `(offset, len)`, so a plain map keyed on the pair hits
 /// every time. Large data reads bypass the cache.
 pub struct CachingReadAt<'a, R: IsoReadAt + Send> {
    inner: &'a mut R,
    cache: HashMap<(u64, u32), Vec<u8>>,
 }
 /// Don't cache reads bigger than this (file payloads, bulk scans).
 const CACHE_MAX_READ: u32 = 256 * 1024;
 /// Bound the cache so a pathological image can't grow it unbounded.
 const CACHE_MAX_ENTRIES: usize = 256;
 impl<'a, R: IsoReadAt + Send> CachingReadAt<'a, R> {
    pub fn new(inner: &'a mut R) -> Self {
        Self {
            inner,
            cache: HashMap::new(),
        }
    }
 }
 impl<R: IsoReadAt + Send> IsoReadAt for CachingReadAt<'_, R> {
    async fn read_at(&mut self, offset: u64, len: u32) -> std::io::Result<Vec<u8>> {
        let key = (offset, len);
        if let Some(hit) = self.cache.get(&key) {
            return Ok(hit.clone());
        }
        let buf = self.inner.read_at(offset, len).await?;
        if len <= CACHE_MAX_READ && self.cache.len() < CACHE_MAX_ENTRIES {
            self.cache.insert(key, buf.clone());
        }
        Ok(buf)
    }
 }
 /// Look up `in_iso_path` (leading slash optional, case-insensitive) in
 /// the image behind `r`. Returns `None` on any parsing or IO failure —
 /// "not found" and "couldn't read" are the same answer to a prober.
 ///
 /// v0.7.5: tries the primary ISO9660 namespace first, then falls back
 /// to the **Joliet** supplementary namespace. Windows-oriented mastering
 /// tools (common for appliance ISOs) often write a minimal or mangled
 /// primary tree and keep the real filenames only in Joliet — without the
 /// fallback those images probed as "no installer files" and their in-ISO
 /// kernel fetches 404'd.
 pub async fn lookup<R: IsoReadAt + Send>(r: &mut R, in_iso_path: &str) -> Option<FileLocation> {
    let components: Vec<&str> = in_iso_path
        .trim_start_matches('/')
        .split('/')
        .filter(|c| !c.is_empty())
        .collect();
    if components.is_empty() {
        return None;
    }
    if let Some(root) = find_root(r, false).await {
        if let Some(loc) = walk_namespace(r, root, &components, false).await {
            return Some(loc);
        }
    }
    if let Some(root) = find_root(r, true).await {
        if let Some(loc) = walk_namespace(r, root, &components, true).await {
            return Some(loc);
        }
    }
    None
 }
 /// Find the namespace root: the Primary Volume Descriptor (`joliet =
 /// false`) or the Joliet Supplementary Volume Descriptor (`joliet =
 /// true`, identified by its UCS-2 escape sequence). Scans the whole
 /// descriptor area rather than assuming fixed sectors, skipping any
 /// non-`CD001` sector — sloppy mastering tools leave gaps. Returns the
 /// root directory's `(lba, len)`.
 async fn find_root<R: IsoReadAt + Send>(r: &mut R, joliet: bool) -> Option<(u64, u64)> {
    let vd = find_descriptor(r, joliet).await?;
    // Root directory record at descriptor offset 156, 34 bytes.
    parse_dir_record_ext(&vd[156..156 + 34])
 }
 /// Scan the Volume Descriptor Set (LBA 16..32) for the wanted
 /// descriptor: PVD (type 0x01) or Joliet SVD (type 0x02 carrying a
 /// UCS-2 level 1/2/3 escape sequence at offset 88). Tolerant of
 /// non-`CD001` filler sectors; stops at the Set Terminator.
 pub(crate) async fn find_descriptor<R: IsoReadAt + Send>(
    r: &mut R,
    joliet: bool,
 ) -> Option<Vec<u8>> {
    for lba in 16u64..32 {
        let Ok(vd) = r.read_at(lba * SECTOR, 2048).await else {
            return None;
        };
        if &vd[1..6] != b"CD001" {
            continue;
        }
        match vd[0] {
            0x01 if !joliet => return Some(vd),
            0x02 if joliet && has_joliet_escape(&vd) => return Some(vd),
            0xFF => return None,
            _ => {}
        }
    }
    None
 }
 /// Joliet SVDs declare a UCS-2 escape sequence at offset 88: `%/@`,
 /// `%/C`, or `%/E` (levels 1–3).
 fn has_joliet_escape(vd: &[u8]) -> bool {
    matches!(vd.get(88..91), Some([0x25, 0x2F, 0x40 | 0x43 | 0x45]))
 }
 /// Walk path components down one namespace's directory tree. The
 /// original walk was tail-recursive; iterate instead so the future
 /// stays a plain (non-boxed) state machine.
 async fn walk_namespace<R: IsoReadAt + Send>(
    r: &mut R,
    root: (u64, u64),
    components: &[&str],
    joliet: bool,
 ) -> Option<FileLocation> {
    let (mut lba, mut len) = root;
    for (idx, comp) in components.iter().enumerate() {
        if len == 0 || len > MAX_DIR_BYTES {
            return None;
        }
        let dir = r.read_at(lba * SECTOR, len as u32).await.ok()?;
        let hit = scan_dir(&dir, comp, joliet)?;
        let last = idx + 1 == components.len();
        match (last, hit.is_dir) {
            (true, false) => {
                return Some(FileLocation {
                    offset: hit.lba * SECTOR,
                    length: hit.len,
                })
            }
            (false, true) => {
                lba = hit.lba;
                len = hit.len;
            }
            _ => return None,
        }
    }
    None
 }
 /// Convenience probe: does `in_iso_path` exist as a file?
 pub async fn exists<R: IsoReadAt + Send>(r: &mut R, in_iso_path: &str) -> bool {
    lookup(r, in_iso_path).await.is_some()
 }
 /// Synchronous wrapper for local files — the shape the HTTP handler's
 /// `spawn_blocking` call site wants. `block_on` is safe here because
 /// `FileReadAt`'s reads never actually await (they complete inline), so
 /// the executor never parks.
 #[must_use]
 pub fn lookup_local(iso_path: &Path, in_iso_path: &str) -> Option<FileLocation> {
    let f = std::fs::File::open(iso_path).ok()?;
    futures::executor::block_on(lookup(&mut FileReadAt::new(f), in_iso_path))
 }
 struct DirHit {
    lba: u64,
    len: u64,
    is_dir: bool,
 }
 /// Scan one directory extent for an identifier. Pure function over the
 /// buffered extent — all protocol/IO concerns live in the caller.
 /// `joliet` switches the identifier decoding (UCS-2 big-endian vs
 /// d-characters); the record layout is otherwise identical.
 fn scan_dir(dir: &[u8], target: &str, joliet: bool) -> Option<DirHit> {
    let mut i = 0;
    while i < dir.len() {
        let len = dir[i] as usize;
        if len == 0 {
            // Records never span sectors; a zero length byte means the
            // rest of this sector is padding. Hop to the next one.
            let next = (i / SECTOR as usize + 1) * SECTOR as usize;
            if next <= i {
                break;
            }
            i = next;
            continue;
        }
        if i + len > dir.len() {
            break;
        }
        let rec = &dir[i..i + len];
        let name = dir_record_name(rec, joliet);
        let is_dir = (rec.get(25).copied().unwrap_or(0) & 0x02) != 0;
        // Skip "." (0x00) and ".." (0x01) pseudo-entries.
        let is_pseudo =
            rec.get(32).copied() == Some(1) && matches!(rec.get(33).copied(), Some(0x00 | 0x01));
        if !is_pseudo && name.eq_ignore_ascii_case(target) {
            let (lba, dlen) = parse_dir_record_ext(rec)?;
            return Some(DirHit {
                lba,
                len: dlen,
                is_dir,
            });
        }
        i += len;
    }
    None
 }
 /// Extract (extent LBA, data length in bytes) from a directory record.
 /// Layout per ISO9660: bytes 2..10 extent LBA (LE+BE duplicate), 10..18
 /// data length (LE+BE duplicate). We trust the little-endian copy.
 fn parse_dir_record_ext(rec: &[u8]) -> Option<(u64, u64)> {
    if rec.len() < 34 {
        return None;
    }
    let lba = u64::from(u32::from_le_bytes(rec[2..6].try_into().ok()?));
    let len = u64::from(u32::from_le_bytes(rec[10..14].try_into().ok()?));
    Some((lba, len))
 }
 /// Extract the identifier from a directory record, normalizing ISO9660
 /// quirks: the `;N` version suffix and the trailing dot that strict
 /// mastering appends to extension-less names (`VMLINUZ.;1`). Without the
 /// dot strip, level-1 images' kernels never matched `/casper/vmlinuz`.
 /// Joliet identifiers are UCS-2 big-endian; decode then normalize the
 /// same way (the `;1` suffix is two UCS-2 characters there).
 fn dir_record_name(rec: &[u8], joliet: bool) -> String {
    if joliet {
        let name_len = *rec.get(32).unwrap_or(&0) as usize;
        if name_len < 2 || rec.len() < 33 + name_len {
            return String::new();
        }
        let raw = &rec[33..33 + name_len];
        let units: Vec<u16> = raw
            .chunks_exact(2)
            .map(|p| u16::from_be_bytes([p[0], p[1]]))
            .collect();
        let s = String::from_utf16_lossy(&units);
        let s = s.rfind(';').map_or_else(|| s.as_str(), |i| &s[..i]);
        return s.strip_suffix('.').unwrap_or(s).to_string();
    }
    primary_record_name(rec)
 }
 fn primary_record_name(rec: &[u8]) -> String {
    let name_len = *rec.get(32).unwrap_or(&0) as usize;
    if name_len == 0 || rec.len() < 33 + name_len {
        return String::new();
    }
    let raw = &rec[33..33 + name_len];
    let s = String::from_utf8_lossy(raw);
    let s = s.rfind(';').map_or_else(|| s.as_ref(), |i| &s[..i]);
    s.strip_suffix('.').unwrap_or(s).to_string()
 }
 // ── test support ─────────────────────────────────────────────────────
 //
 // A tiny ISO9660 image builder used by this module's tests, the
 // introspection tests, and (behind the `test-image` feature) other
 // crates' integration tests. Lays out: PVD @ LBA 16, optional El Torito
 // boot record @ 17, set terminator @ 18, directories from LBA 20, file
 // data after. Only what `lookup`/introspection read is populated.
 #[cfg(any(test, feature = "test-image"))]
 #[doc(hidden)]
 pub mod testiso {
    use super::SECTOR;
    use std::collections::BTreeMap;
    #[derive(Default)]
    struct Node {
        children: BTreeMap<String, Node>,
        content: Option<Vec<u8>>,
    }
    pub struct TestIsoBuilder {
        root: Node,
        volume_label: String,
        el_torito: bool,
        joliet_only: bool,
    }
    impl TestIsoBuilder {
        pub fn new(volume_label: &str) -> Self {
            Self {
                root: Node::default(),
                volume_label: volume_label.to_string(),
                el_torito: false,
                joliet_only: false,
            }
        }
        #[must_use]
        pub fn el_torito(mut self, on: bool) -> Self {
            self.el_torito = on;
            self
        }
        /// Model the Windows-mastering worst case: the primary ISO9660
        /// tree is empty (just `.`/`..` in the root) and every real name
        /// lives only in the Joliet supplementary namespace. Exercises
        /// the v0.7.5 Joliet fallback end to end.
        #[must_use]
        pub fn joliet_only(mut self, on: bool) -> Self {
            self.joliet_only = on;
            self
        }
        /// Add a file at `path` (e.g. "/casper/vmlinuz") with `content`.
        #[must_use]
        pub fn file(mut self, path: &str, content: &[u8]) -> Self {
            let mut node = &mut self.root;
            let comps: Vec<&str> = path
                .trim_start_matches('/')
                .split('/')
                .filter(|c| !c.is_empty())
                .collect();
            for (i, c) in comps.iter().enumerate() {
                node = node.children.entry((*c).to_string()).or_default();
                if i + 1 == comps.len() {
                    node.content = Some(content.to_vec());
                }
            }
            self
        }
        pub fn build(self) -> Vec<u8> {
            // Pass 1: allocate extents. Primary directories first (1
            // sector each), then an optional parallel set of Joliet
            // directory extents, then file contents (shared by both
            // namespaces — only the directory trees differ).
            let mut next_lba: u64 = 20;
            let mut dirs: Vec<(*const Node, u64)> = Vec::new();
            fn alloc_dirs(n: &Node, next: &mut u64, out: &mut Vec<(*const Node, u64)>) {
                out.push((std::ptr::from_ref(n), *next));
                *next += 1;
                for child in n.children.values() {
                    if child.content.is_none() {
                        alloc_dirs(child, next, out);
                    }
                }
            }
            alloc_dirs(&self.root, &mut next_lba, &mut dirs);
            let lba_of = |n: &Node| -> u64 {
                dirs.iter()
                    .find(|(p, _)| std::ptr::eq(*p, n))
                    .map(|(_, l)| *l)
                    .expect("dir allocated")
            };
            let mut jdirs: Vec<(*const Node, u64)> = Vec::new();
            if self.joliet_only {
                alloc_dirs(&self.root, &mut next_lba, &mut jdirs);
            }
            let jlba_of = |n: &Node| -> u64 {
                jdirs
                    .iter()
                    .find(|(p, _)| std::ptr::eq(*p, n))
                    .map(|(_, l)| *l)
                    .expect("joliet dir allocated")
            };
            let mut file_lbas: Vec<(*const Node, u64, usize)> = Vec::new();
            fn alloc_files(n: &Node, next: &mut u64, out: &mut Vec<(*const Node, u64, usize)>) {
                for child in n.children.values() {
                    if let Some(c) = &child.content {
                        out.push((std::ptr::from_ref(child), *next, c.len()));
                        *next += c.len().div_ceil(SECTOR as usize).max(1) as u64;
                    } else {
                        alloc_files(child, next, out);
                    }
                }
            }
            alloc_files(&self.root, &mut next_lba, &mut file_lbas);
            let file_lba_of = |n: &Node| -> u64 {
                file_lbas
                    .iter()
                    .find(|(p, _, _)| std::ptr::eq(*p, n))
                    .map(|(_, l, _)| *l)
                    .expect("file allocated")
            };
            let total = next_lba as usize * SECTOR as usize;
            let mut img = vec![0u8; total];
            // Directory record encoder.
            fn record(name_bytes: &[u8], lba: u64, len: u64, is_dir: bool) -> Vec<u8> {
                let mut rec_len = 33 + name_bytes.len();
                if rec_len % 2 == 1 {
                    rec_len += 1; // pad to even
                }
                let rec_len = rec_len.max(34);
                let mut r = vec![0u8; rec_len];
                r[0] = rec_len as u8;
                r[2..6].copy_from_slice(&(lba as u32).to_le_bytes());
                r[6..10].copy_from_slice(&(lba as u32).to_be_bytes());
                r[10..14].copy_from_slice(&(len as u32).to_le_bytes());
                r[14..18].copy_from_slice(&(len as u32).to_be_bytes());
                if is_dir {
                    r[25] = 0x02;
                }
                r[32] = name_bytes.len() as u8;
                r[33..33 + name_bytes.len()].copy_from_slice(name_bytes);
                r
            }
            // Pass 2: write each directory extent. `joliet` switches the
            // identifier encoding; `skip_children` writes a bare ./..
            // directory (the mangled-primary worst case).
            #[allow(clippy::too_many_arguments)]
            fn write_dir(
                img: &mut [u8],
                n: &Node,
                self_lba: u64,
                parent_lba: u64,
                dir_lba_of: &dyn Fn(&Node) -> u64,
                file_lba_of: &dyn Fn(&Node) -> u64,
                joliet: bool,
                skip_children: bool,
            ) {
                let base = self_lba as usize * SECTOR as usize;
                let mut off = 0usize;
                let mut put = |rec: Vec<u8>, off: &mut usize| {
                    img[base + *off..base + *off + rec.len()].copy_from_slice(&rec);
                    *off += rec.len();
                };
                put(record(&[0x00], self_lba, SECTOR, true), &mut off);
                put(record(&[0x01], parent_lba, SECTOR, true), &mut off);
                if skip_children {
                    return;
                }
                let encode = |name: &str, file: bool| -> Vec<u8> {
                    if joliet {
                        // Joliet preserves case; files still carry `;1`.
                        let s = if file {
                            format!("{name};1")
                        } else {
                            name.to_string()
                        };
                        s.encode_utf16().flat_map(u16::to_be_bytes).collect()
                    } else if file {
                        // Primary gets the ISO9660 uppercase `;1` treatment
                        // so case-insensitive + version-strip matching is
                        // what the tests actually exercise.
                        format!("{};1", name.to_ascii_uppercase()).into_bytes()
                    } else {
                        name.to_ascii_uppercase().into_bytes()
                    }
                };
                for (name, child) in &n.children {
                    if let Some(c) = &child.content {
                        put(
                            record(
                                &encode(name, true),
                                file_lba_of(child),
                                c.len() as u64,
                                false,
                            ),
                            &mut off,
                        );
                    } else {
                        put(
                            record(&encode(name, false), dir_lba_of(child), SECTOR, true),
                            &mut off,
                        );
                    }
                }
                for child in n.children.values() {
                    if child.content.is_none() {
                        write_dir(
                            img,
                            child,
                            dir_lba_of(child),
                            self_lba,
                            dir_lba_of,
                            file_lba_of,
                            joliet,
                            false,
                        );
                    } else if let Some(c) = &child.content {
                        let b = file_lba_of(child) as usize * SECTOR as usize;
                        img[b..b + c.len()].copy_from_slice(c);
                    }
                }
            }
            let root_lba = lba_of(&self.root);
            write_dir(
                &mut img,
                &self.root,
                root_lba,
                root_lba,
                &lba_of,
                &file_lba_of,
                false,
                self.joliet_only,
            );
            let jroot_lba = if self.joliet_only {
                let jroot = jlba_of(&self.root);
                write_dir(
                    &mut img,
                    &self.root,
                    jroot,
                    jroot,
                    &jlba_of,
                    &file_lba_of,
                    true,
                    false,
                );
                Some(jroot)
            } else {
                None
            };
            // PVD @ 16.
            let pvd = 16 * SECTOR as usize;
            img[pvd] = 0x01;
            img[pvd + 1..pvd + 6].copy_from_slice(b"CD001");
            let label = self.volume_label.as_bytes();
            let label_field = &mut img[pvd + 40..pvd + 72];
            label_field.fill(b' ');
            label_field[..label.len().min(32)].copy_from_slice(&label[..label.len().min(32)]);
            let root_rec = record(&[0x00], root_lba, SECTOR, true);
            img[pvd + 156..pvd + 156 + 34].copy_from_slice(&root_rec[..34]);
            // Optional El Torito boot record @ 17, then the optional
            // Joliet SVD, then the set terminator.
            let mut vd = 17 * SECTOR as usize;
            if self.el_torito {
                img[vd] = 0x00;
                img[vd + 1..vd + 6].copy_from_slice(b"CD001");
                let id = b"EL TORITO SPECIFICATION";
                img[vd + 7..vd + 7 + id.len()].copy_from_slice(id);
                vd += SECTOR as usize;
            }
            if let Some(jroot) = jroot_lba {
                img[vd] = 0x02;
                img[vd + 1..vd + 6].copy_from_slice(b"CD001");
                // Joliet level-3 UCS-2 escape sequence.
                img[vd + 88..vd + 91].copy_from_slice(&[0x25, 0x2F, 0x45]);
                let jroot_rec = record(&[0x00], jroot, SECTOR, true);
                img[vd + 156..vd + 156 + 34].copy_from_slice(&jroot_rec[..34]);
                vd += SECTOR as usize;
            }
            img[vd] = 0xFF;
            img[vd + 1..vd + 6].copy_from_slice(b"CD001");
            img
        }
    }
    /// In-memory `IsoReadAt` over a built test image.
    pub struct MemReadAt(pub Vec<u8>);
    impl super::IsoReadAt for MemReadAt {
        async fn read_at(&mut self, offset: u64, len: u32) -> std::io::Result<Vec<u8>> {
            let start = usize::try_from(offset).unwrap_or(usize::MAX);
            let end = start.saturating_add(len as usize);
            if end > self.0.len() {
                return Err(std::io::Error::new(
                    std::io::ErrorKind::UnexpectedEof,
                    "read past end of test image",
                ));
            }
            Ok(self.0[start..end].to_vec())
        }
    }
 }
 #[cfg(test)]
 mod tests {
    use super::testiso::{MemReadAt, TestIsoBuilder};
    use super::*;
    fn block_on<T>(f: impl Future<Output = T>) -> T {
        futures::executor::block_on(f)
    }
    #[test]
    fn lookup_finds_nested_file_case_insensitively() {
        let img = TestIsoBuilder::new("UBUNTU 24.04")
            .file("/casper/vmlinuz", b"KERNELDATA")
            .file("/casper/initrd", b"INITRDDATA")
            .build();
        let mut r = MemReadAt(img);
        let loc = block_on(lookup(&mut r, "/CASPER/VMLINUZ")).expect("found");
        assert_eq!(loc.length, 10);
        let bytes = block_on(r.read_at(loc.offset, 10)).unwrap();
        assert_eq!(&bytes, b"KERNELDATA");
        // Missing file and missing dir both miss cleanly.
        assert!(block_on(lookup(&mut r, "/casper/missing")).is_none());
        assert!(block_on(lookup(&mut r, "/nodir/vmlinuz")).is_none());
        // A directory path that resolves to a directory is not a file hit.
        assert!(block_on(lookup(&mut r, "/casper")).is_none());
    }
    #[test]
    fn strict_mastered_extensionless_names_match() {
        // Strict level-1 mastering stores "VMLINUZ" as "VMLINUZ.;1" — the
        // trailing dot must be normalized away or kernels never match.
        let img = TestIsoBuilder::new("STRICT")
            .file("/boot/vmlinuz.", b"K") // builder stores "VMLINUZ.;1"
            .build();
        let mut r = MemReadAt(img);
        assert!(
            block_on(lookup(&mut r, "/boot/vmlinuz")).is_some(),
            "trailing-dot ISO9660 name must match the dotless path"
        );
    }
    #[test]
    fn lookup_three_levels_deep() {
        let img = TestIsoBuilder::new("DEEP")
            .file("/images/pxeboot/vmlinuz", b"ANACONDA")
            .build();
        let mut r = MemReadAt(img);
        let loc = block_on(lookup(&mut r, "images/pxeboot/vmlinuz")).expect("no leading slash ok");
        assert_eq!(loc.length, 8);
    }
    #[test]
    fn caching_reader_dedupes_repeated_directory_reads() {
        struct Counting<'a> {
            inner: &'a mut MemReadAt,
            calls: usize,
        }
        impl IsoReadAt for Counting<'_> {
            async fn read_at(&mut self, offset: u64, len: u32) -> std::io::Result<Vec<u8>> {
                self.calls += 1;
                self.inner.read_at(offset, len).await
            }
        }
        let img = TestIsoBuilder::new("CACHE")
            .file("/a/one", b"1")
            .file("/a/two", b"2")
            .build();
        let mut mem = MemReadAt(img);
        let mut counting = Counting {
            inner: &mut mem,
            calls: 0,
        };
        let mut cr = CachingReadAt::new(&mut counting);
        assert!(block_on(exists(&mut cr, "/a/one")));
        assert!(block_on(exists(&mut cr, "/a/two")));
        assert!(!block_on(exists(&mut cr, "/a/three")));
        drop(cr);
        // 3 probes × (PVD + root dir + subdir) collapse to the 3 distinct
        // extents, plus one: the "/a/three" miss falls back to the Joliet
        // namespace search (v0.7.5), which reads the terminator sector
        // once before concluding there is no SVD.
        assert_eq!(counting.calls, 4, "all repeat reads must hit the cache");
    }
    #[test]
    fn joliet_fallback_finds_names_missing_from_primary() {
        // Windows-mastering worst case: primary tree is bare (./.. only),
        // real names live only in the Joliet SVD. The lookup must fall
        // back and still resolve nested paths case-insensitively.
        let img = TestIsoBuilder::new("APPLIANCE")
            .joliet_only(true)
            .file("/images/pxeboot/vmlinuz", b"JKERNEL")
            .file("/sources/boot.wim", b"JWIM")
            .build();
        let mut r = MemReadAt(img);
        let loc = block_on(lookup(&mut r, "/images/pxeboot/vmlinuz")).expect("joliet fallback");
        let bytes = block_on(r.read_at(loc.offset, loc.length as u32)).unwrap();
        assert_eq!(&bytes, b"JKERNEL");
        assert!(block_on(lookup(&mut r, "/SOURCES/BOOT.WIM")).is_some());
        assert!(block_on(lookup(&mut r, "/images/pxeboot/missing")).is_none());
    }
    #[test]
    fn lookup_local_reads_a_real_file() {
        let dir = tempfile::tempdir().unwrap();
        let p = dir.path().join("t.iso");
        let img = TestIsoBuilder::new("LOCAL")
            .file("/sources/boot.wim", b"WIMWIM")
            .build();
        std::fs::write(&p, &img).unwrap();
        let loc = lookup_local(&p, "/sources/boot.wim").expect("found");
        assert_eq!(loc.length, 6);
        assert!(lookup_local(&p, "/sources/none").is_none());
    }
 }
@@ -18,8 +18,16 @@
 pub mod entry;
 pub mod introspect;
 // v0.7.4: read-only ISO9660 walker generic over any random-access byte
 // source (local file, NFS READ3, SFTP seek-read). Powers both in-ISO
 // HTTP serving and the probe-based introspection.
 pub mod iso_fs;
 pub mod nfs_share;
 pub mod pxe_logo;
 // v0.7.4: persisted cache of remote-share introspection results so a
 // container restart doesn't re-probe an unchanged 40-ISO library.
 pub mod remote_cache;
 pub mod sftp_share;
 pub mod smb;
 pub mod smb_share;
 pub mod store;
@@ -28,6 +36,7 @@ pub mod windows;
 pub use entry::{BootEntry, BootKind, KernelArgs};
 pub use introspect::{DistroFamily, IntrospectionReport};
 pub use iso_fs::FileLocation;
 // v0.4.65: kernel-mount NFS is gone. SMB shares via Samba's userspace
 // `smbclient` CLI replaced it — works in any container (no
 // CAP_SYS_ADMIN, no host kernel modules), matching how Bootimus and
@@ -40,6 +49,13 @@ pub use smb_share::{SmbAddRequest, SmbShare, SmbShareError, SmbShareManager, Smb
 // "works in any container" property as SMB, plus support for HTTP
 // Range requests because NFSv3 READ3 takes an explicit offset.
 pub use nfs_share::{NfsAddRequest, NfsShare, NfsShareError, NfsShareManager, NfsStream};
 // v0.5.5: SFTP-over-SSH remote shares via the pure-Rust `russh` +
 // `russh-sftp` crates (ring backend — no OpenSSL, no new C deps). Like
 // NFS, supports HTTP Range requests because SFTP opens a seekable file
 // handle. See crates/iso-store/src/sftp_share.rs.
 pub use sftp_share::{
    SftpAddRequest, SftpAuthKind, SftpShare, SftpShareError, SftpShareManager, SftpStream,
 };
 pub use store::{
    generate_boot_entries_for, slugify_str, IsoCategory, IsoMeta, IsoSource, IsoStore, UploadHandle,
 };
@@ -57,14 +57,16 @@
 //! UI to ask for. (If a future server needs Kerberos or non-default
 //! uid mapping we can add those, but for ISO read access nobody does.)
-use crate::introspect::{DistroFamily, IntrospectionReport};
+use crate::introspect::{introspect_reader, provisional_report};
 use crate::iso_fs::{self, FileLocation, IsoReadAt};
 use crate::remote_cache::RemoteIntrospectCache;
 use crate::store::{generate_boot_entries_for, slugify_str, IsoSource, IsoStore};
 use bytes::Bytes;
 use nfs3_client::tokio::TokioConnector;
 use nfs3_client::Nfs3ConnectionBuilder;
 use nfs3_types::nfs3::{
-    self as nfs3, diropargs3, entry3, filename3, nfs_fh3, GETATTR3args, LOOKUP3args,
+    self as nfs3, diropargs3, entry3, filename3, nfs_fh3, GETATTR3args, LOOKUP3args, Nfs3Result,
-    Nfs3Result, READ3args, READDIR3args,
+    READ3args, READDIR3args,
 };
 use nfs3_types::rpc::{auth_unix, opaque_auth};
 use nfs3_types::xdr_codec::Opaque;
@@ -100,6 +102,18 @@ const READ_CHUNK_BYTES: u32 = 64 * 1024;
 /// client park gigabytes of decoded ISO in RAM.
 const STREAM_BUFFER_DEPTH: usize = 16;
 /// v0.7.4: per-ISO budget for a background introspection probe. A probe
 /// is one connection plus a few dozen KiB-sized reads — sub-second on a
 /// LAN — so anything past this is a wedged server, not a slow one.
 const INTROSPECT_TIMEOUT: Duration = Duration::from_secs(30);
 /// One queued background-introspection unit (v0.7.4).
 struct ProbeJob {
    iso_id: String,
    filename: String,
    size: u64,
 }
 /// One configured NFS share. The id is derived from server+export so
 /// re-adding the same coordinates is idempotent.
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -177,6 +191,9 @@ pub struct NfsShareManager {
    /// opens its own NFS connection so concurrency isn't a hard
    /// requirement, but serializing keeps log output predictable.
    op_lock: Arc<tokio::sync::Mutex<()>>,
    /// v0.7.4: persisted introspection results keyed `share/path@size`,
    /// so a restart re-probes only new or replaced ISOs.
    introspect_cache: RemoteIntrospectCache,
 }
 impl NfsShareManager {
@@ -190,6 +207,7 @@ impl NfsShareManager {
            inner: Arc::new(Mutex::new(Inner::default())),
            iso_store,
            op_lock: Arc::new(tokio::sync::Mutex::new(())),
            introspect_cache: RemoteIntrospectCache::open(work_dir, "nfs_introspect_cache.json"),
        }
    }
@@ -220,10 +238,7 @@ impl NfsShareManager {
    /// Register an NFS share. Validates, probes connectivity by
    /// performing a real MOUNT3 + READDIR3, and registers the
    /// resulting ISOs with the store.
-    pub async fn add(
+    pub async fn add(&self, req: NfsAddRequest) -> std::result::Result<NfsShare, NfsShareError> {
        &self,
        req: NfsAddRequest,
    ) -> std::result::Result<NfsShare, NfsShareError> {
        let server = normalize_server(&req.server);
        let export = req.export.trim().to_string();
        if server.is_empty() {
@@ -258,7 +273,9 @@ impl NfsShareManager {
        if let Err(e) = self.rescan_inner(&id).await {
            let m = self.get(&id);
            return Err(NfsShareError {
-                error: m.as_ref().and_then(|m| m.last_error.clone())
+                error: m
                    .as_ref()
                    .and_then(|m| m.last_error.clone())
                    .unwrap_or_else(|| e.to_string()),
                stderr: String::new(),
                hint: m.and_then(|m| m.last_hint),
@@ -333,8 +350,7 @@ impl NfsShareManager {
            return Err(Error::Invalid(format!("invalid filename '{filename}'")));
        }
-        let (tx, rx) =
+        let (tx, rx) = tokio::sync::mpsc::channel::<std::io::Result<Bytes>>(STREAM_BUFFER_DEPTH);
            tokio::sync::mpsc::channel::<std::io::Result<Bytes>>(STREAM_BUFFER_DEPTH);
        let server = share.server.clone();
        let export = share.export.clone();
        let port = share.port;
@@ -358,16 +374,11 @@ impl NfsShareManager {
            if let Err(e) = result {
                // Best-effort signal of the error to the consumer.
                // If the receiver has already dropped we just exit.
-                let _ = tx
+                let _ = tx.send(Err(std::io::Error::other(e.to_string()))).await;
                    .send(Err(std::io::Error::other(e.to_string())))
                    .await;
            }
        });
-        Ok(NfsStream {
+        Ok(NfsStream { rx, _task: task })
            rx,
            _task: task,
        })
    }
    // ── internals ─────────────────────────────────────────────────────
@@ -394,18 +405,26 @@ impl NfsShareManager {
        };
        let mut count = 0u32;
        let mut to_probe: Vec<ProbeJob> = Vec::new();
        for entry in listing {
            let iso_id = format!("nfs-{}-{}", share.id, slugify_str(&entry.filename));
-            // Same approach as SMB: no real introspection over the
+            // v0.7.4: real introspection over the share — NFSv3 READ3
-            // network in v0.4.67. The boot-entry generator falls back
+            // takes an offset, so the ISO9660 probes work remotely. A
-            // to filename-based sanboot detection.
+            // cache hit registers the full report immediately; a miss
-            let report = IntrospectionReport {
+            // registers a provisional filename-based report (so the scan
-                family: DistroFamily::Unknown,
+            // returns fast) and queues a background probe that upgrades
-                volume_label: None,
+            // the entry in place.
-                kernel_path: None,
+            let cached = self
-                initrd_paths: Vec::new(),
+                .introspect_cache
-                has_boot_wim: false,
+                .get(&share.id, &entry.filename, entry.size);
-            };
+            let report = cached.unwrap_or_else(|| {
                to_probe.push(ProbeJob {
                    iso_id: iso_id.clone(),
                    filename: entry.filename.clone(),
                    size: entry.size,
                });
                provisional_report(&entry.filename)
            });
            let boot_entries = generate_boot_entries_for(&iso_id, &entry.filename, &report);
            let source = IsoSource::Nfs {
                share_id: share.id.clone(),
@@ -426,11 +445,88 @@ impl NfsShareManager {
            target: "openpxe::nfs",
            id = %id, server = %share.server, export = %share.export,
            iso_count = count,
            pending_introspection = to_probe.len(),
            "NFS share scanned"
        );
        if !to_probe.is_empty() {
            self.spawn_introspection_pass(&share, to_probe);
        }
        Ok(count)
    }
    /// v0.7.4: probe each queued ISO over its own NFS connection and swap
    /// the full introspection into the store as results land. Runs
    /// detached so neither startup nor the share-add API call waits on a
    /// 40-ISO library; per-ISO failures (or a share removed mid-pass)
    /// leave the provisional entry in place, which still sanboots.
    fn spawn_introspection_pass(&self, share: &NfsShare, work: Vec<ProbeJob>) {
        let store = self.iso_store.clone();
        let cache = self.introspect_cache.clone();
        let share_id = share.id.clone();
        let server = share.server.clone();
        let export = share.export.clone();
        let port = share.port;
        let queued = work.len();
        tokio::spawn(async move {
            let mut upgraded = 0usize;
            for job in work {
                let probe = async {
                    let mut reader = NfsReadAt::open(&server, &export, port, &job.filename).await?;
                    let report =
                        introspect_reader(&mut reader, job.size, &job.filename, false).await;
                    reader.finish().await;
                    Ok::<_, NfsClientError>(report)
                };
                match tokio::time::timeout(INTROSPECT_TIMEOUT, probe).await {
                    Ok(Ok(report)) => {
                        cache.put(&share_id, &job.filename, job.size, report.clone());
                        if store.update_external_introspection(&job.iso_id, report) {
                            upgraded += 1;
                        }
                    }
                    Ok(Err(e)) => tracing::warn!(
                        target: "openpxe::nfs",
                        share = %share_id, iso = %job.filename,
                        "introspection failed: {e}"
                    ),
                    Err(_) => tracing::warn!(
                        target: "openpxe::nfs",
                        share = %share_id, iso = %job.filename,
                        "introspection timed out after {}s", INTROSPECT_TIMEOUT.as_secs()
                    ),
                }
            }
            tracing::info!(
                target: "openpxe::nfs",
                share = %share_id, queued, upgraded,
                "remote introspection pass complete"
            );
        });
    }
    /// v0.7.4: locate `in_iso_path` inside a share-hosted ISO. Returns the
    /// byte range so the HTTP layer can serve kernel/initrd files out of
    /// remote ISOs with a follow-up ranged [`Self::stream_iso`].
    pub async fn locate_in_iso(
        &self,
        share_id: &str,
        filename: &str,
        in_iso_path: &str,
    ) -> Result<Option<FileLocation>> {
        let share = self
            .get(share_id)
            .ok_or_else(|| Error::Invalid(format!("no such NFS share '{share_id}'")))?;
        if filename.contains('/') || filename.contains('\\') || filename.contains("..") {
            return Err(Error::Invalid(format!("invalid filename '{filename}'")));
        }
        let mut reader = NfsReadAt::open(&share.server, &share.export, share.port, filename)
            .await
            .map_err(|e| Error::Invalid(format!("nfs open '{filename}': {e}")))?;
        let loc = iso_fs::lookup(&mut reader, in_iso_path).await;
        reader.finish().await;
        Ok(loc)
    }
    fn update_status(
        &self,
        id: &str,
@@ -503,6 +599,96 @@ struct NfsListEntry {
    size: u64,
 }
 /// The connection type [`build_connection`] yields.
 type NfsConn = nfs3_client::Nfs3Connection<nfs3_client::tokio::TokioIo<tokio::net::TcpStream>>;
 /// v0.7.4: random-access reader over one NFS connection + file handle —
 /// the [`IsoReadAt`] impl that lets the ISO9660 walker and introspection
 /// probes run against share-hosted images.
 struct NfsReadAt {
    conn: NfsConn,
    fh: nfs_fh3,
 }
 impl NfsReadAt {
    /// Connect, mount, and LOOKUP `filename` at the export root.
    async fn open(
        server: &str,
        export: &str,
        port: u16,
        filename: &str,
    ) -> std::result::Result<Self, NfsClientError> {
        let mut conn = build_connection(server, export, port).await?;
        let root = conn.root_nfs_fh3();
        let lookup = conn
            .lookup(&LOOKUP3args {
                what: diropargs3 {
                    dir: root,
                    name: filename3(Opaque::borrowed(filename.as_bytes())),
                },
            })
            .await
            .map_err(NfsClientError::Rpc)?;
        let fh = match lookup {
            Nfs3Result::Ok(o) => o.object,
            Nfs3Result::Err((status, _)) => {
                return Err(NfsClientError::Nfsstat(status_label(status)));
            }
        };
        Ok(Self { conn, fh })
    }
    /// Best-effort unmount. Consumes the reader — it's done.
    async fn finish(self) {
        let _ = self.conn.unmount().await;
    }
 }
 impl IsoReadAt for NfsReadAt {
    async fn read_at(&mut self, offset: u64, len: u32) -> std::io::Result<Vec<u8>> {
        let mut out: Vec<u8> = Vec::with_capacity(len as usize);
        let mut off = offset;
        // READ3 may legally return fewer bytes than asked (server cap);
        // loop until the exact-read contract is satisfied or the file
        // genuinely ends short.
        while (out.len() as u32) < len {
            let want = (len - out.len() as u32).min(READ_CHUNK_BYTES);
            let res = self
                .conn
                .read(&READ3args {
                    file: self.fh.clone(),
                    offset: off,
                    count: want,
                })
                .await
                .map_err(|e| std::io::Error::other(e.to_string()))?;
            let ok = match res {
                Nfs3Result::Ok(o) => o,
                Nfs3Result::Err((status, _)) => {
                    return Err(std::io::Error::other(status_label(status)));
                }
            };
            let data = ok.data.as_ref();
            if data.is_empty() {
                return Err(std::io::Error::new(
                    std::io::ErrorKind::UnexpectedEof,
                    "NFS read past end of file",
                ));
            }
            out.extend_from_slice(data);
            off += data.len() as u64;
            if ok.eof && (out.len() as u32) < len {
                return Err(std::io::Error::new(
                    std::io::ErrorKind::UnexpectedEof,
                    "NFS read past end of file",
                ));
            }
        }
        out.truncate(len as usize);
        Ok(out)
    }
 }
 /// Connect, READDIR the export root, look up each `*.iso` to get its
 /// size + file handle. Returns a flat list. Errors are returned with
 /// a human-readable message; the caller decides how to surface them.
@@ -988,8 +1174,14 @@ mod tests {
        // the allow-list and the secure/insecure angle.
        let h = hint_for("connect failed: MNT3ERR_ACCES").unwrap();
        let lc = h.to_lowercase();
-        assert!(lc.contains("insecure") || lc.contains("privileged"), "got: {h}");
+        assert!(
-        assert!(lc.contains("allow") || lc.contains("permission"), "got: {h}");
+            lc.contains("insecure") || lc.contains("privileged"),
            "got: {h}"
        );
        assert!(
            lc.contains("allow") || lc.contains("permission"),
            "got: {h}"
        );
    }
    #[test]
@@ -0,0 +1,142 @@
 //! Persisted cache of remote-share introspection results.
 //!
 //! NFS/SFTP introspection costs a connection plus a few dozen small
 //! reads per ISO. Shares are rescanned on every startup and share-add,
 //! so without a cache a 40-ISO library would re-probe 40 ISOs on every
 //! container restart. The cache keys on `share/path@size` — a replaced
 //! file (new size) re-probes, an untouched one is free — and entries
 //! only count as hits when their `introspect_rev` matches the current
 //! logic, so an upgrade that changes detection re-probes everything
 //! exactly once.
 //!
 //! One file per protocol (`nfs_introspect_cache.json`,
 //! `sftp_introspect_cache.json`) so the two managers never contend over
 //! one writer.
 use crate::introspect::{IntrospectionReport, INTROSPECT_REV};
 use parking_lot::Mutex;
 use std::collections::HashMap;
 use std::path::{Path, PathBuf};
 use std::sync::Arc;
 /// Hard cap on cached entries; beyond it the cache resets rather than
 /// growing unbounded (a cache wipe only costs one re-probe pass).
 const MAX_ENTRIES: usize = 4096;
 #[derive(Clone, Debug)]
 pub struct RemoteIntrospectCache {
    path: Arc<PathBuf>,
    map: Arc<Mutex<HashMap<String, IntrospectionReport>>>,
 }
 impl RemoteIntrospectCache {
    /// Open (or start empty) the cache at `<work_dir>/<file_name>`.
    /// A corrupt or missing file is an empty cache, never an error.
    #[must_use]
    pub fn open(work_dir: &Path, file_name: &str) -> Self {
        let path = work_dir.join(file_name);
        let map = std::fs::read_to_string(&path)
            .ok()
            .and_then(|text| {
                serde_json::from_str::<HashMap<String, IntrospectionReport>>(&text).ok()
            })
            .unwrap_or_default();
        Self {
            path: Arc::new(path),
            map: Arc::new(Mutex::new(map)),
        }
    }
    fn key(share_id: &str, relative_path: &str, size: u64) -> String {
        format!("{share_id}/{relative_path}@{size}")
    }
    /// A hit requires the entry to have been produced by the *current*
    /// introspection logic — stale-rev entries are misses, which is how
    /// the cache self-invalidates across upgrades.
    #[must_use]
    pub fn get(
        &self,
        share_id: &str,
        relative_path: &str,
        size: u64,
    ) -> Option<IntrospectionReport> {
        self.map
            .lock()
            .get(&Self::key(share_id, relative_path, size))
            .filter(|r| r.introspect_rev == INTROSPECT_REV)
            .cloned()
    }
    pub fn put(&self, share_id: &str, relative_path: &str, size: u64, report: IntrospectionReport) {
        let snapshot = {
            let mut g = self.map.lock();
            if g.len() >= MAX_ENTRIES {
                g.clear();
            }
            g.insert(Self::key(share_id, relative_path, size), report);
            g.clone()
        };
        // Persist outside the lock; tmp+rename so a crash mid-write
        // leaves the previous cache intact.
        let path = self.path.as_path();
        let tmp = path.with_extension("json.tmp");
        let Ok(body) = serde_json::to_vec_pretty(&snapshot) else {
            return;
        };
        if let Some(parent) = path.parent() {
            let _ = std::fs::create_dir_all(parent);
        }
        if std::fs::write(&tmp, body).is_ok() {
            let _ = std::fs::rename(&tmp, path);
        }
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    use crate::introspect::DistroFamily;
    #[test]
    fn round_trips_across_reopen_and_rev_gates() {
        let dir = tempfile::tempdir().unwrap();
        let cache = RemoteIntrospectCache::open(dir.path(), "t.json");
        assert!(cache.get("s1", "a.iso", 100).is_none());
        let fresh = IntrospectionReport {
            family: DistroFamily::RhelFedora,
            introspect_rev: INTROSPECT_REV,
            el_torito: true,
            ..Default::default()
        };
        cache.put("s1", "a.iso", 100, fresh.clone());
        assert_eq!(
            cache.get("s1", "a.iso", 100).unwrap().family,
            DistroFamily::RhelFedora
        );
        // Different size = different file = miss.
        assert!(cache.get("s1", "a.iso", 101).is_none());
        // Survives a reopen.
        let cache2 = RemoteIntrospectCache::open(dir.path(), "t.json");
        assert!(cache2.get("s1", "a.iso", 100).is_some());
        // Stale-rev entries never hit.
        let stale = IntrospectionReport {
            family: DistroFamily::Arch,
            introspect_rev: INTROSPECT_REV - 1,
            ..Default::default()
        };
        cache2.put("s1", "b.iso", 7, stale);
        assert!(cache2.get("s1", "b.iso", 7).is_none());
    }
    #[test]
    fn corrupt_cache_file_starts_empty() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(dir.path().join("t.json"), b"{nope").unwrap();
        let cache = RemoteIntrospectCache::open(dir.path(), "t.json");
        assert!(cache.get("s", "x.iso", 1).is_none());
    }
 }
@@ -56,7 +56,7 @@
 //! streaming. A follow-up release can add libsmbclient-based seek if
 //! a real workload needs it.
-use crate::introspect::{DistroFamily, IntrospectionReport};
+use crate::introspect::provisional_report;
 use crate::store::{generate_boot_entries_for, slugify_str, IsoSource, IsoStore};
 use openpxe_core::{Error, Result};
 use parking_lot::Mutex;
@@ -231,10 +231,7 @@ impl SmbShareManager {
    /// Add or refresh a share. Validates the input, writes a creds
    /// file, probes connectivity, and scans for ISOs.
-    pub async fn add(
+    pub async fn add(&self, req: SmbAddRequest) -> std::result::Result<SmbShare, SmbShareError> {
        &self,
        req: SmbAddRequest,
    ) -> std::result::Result<SmbShare, SmbShareError> {
        let server = normalize_server(&req.server);
        let share = req.share.trim().trim_start_matches('/').to_string();
        if server.is_empty() {
@@ -309,7 +306,9 @@ impl SmbShareManager {
        if let Err(e) = self.rescan_inner(&id).await {
            let m = self.get(&id);
            return Err(SmbShareError {
-                error: m.as_ref().and_then(|m| m.last_error.clone())
+                error: m
                    .as_ref()
                    .and_then(|m| m.last_error.clone())
                    .unwrap_or_else(|| e.to_string()),
                stderr: String::new(),
                hint: m.and_then(|m| m.last_hint),
@@ -365,11 +364,7 @@ impl SmbShareManager {
    /// throttling concurrent smbclients) would need to await without
    /// changing the call sites.
    #[allow(clippy::unused_async)]
-    pub async fn stream_iso(
+    pub async fn stream_iso(&self, share_id: &str, filename: &str) -> Result<SmbStream> {
        &self,
        share_id: &str,
        filename: &str,
    ) -> Result<SmbStream> {
        let share = self
            .get(share_id)
            .ok_or_else(|| Error::Invalid(format!("no such SMB share '{share_id}'")))?;
@@ -377,9 +372,7 @@ impl SmbShareManager {
        // share root. smbclient itself accepts only filenames at the
        // share root in our `get` form, but belt-and-suspenders.
        if filename.contains('/') || filename.contains('\\') || filename.contains("..") {
-            return Err(Error::Invalid(format!(
+            return Err(Error::Invalid(format!("invalid filename '{filename}'")));
                "invalid filename '{filename}'"
            )));
        }
        let creds = share
            .creds_path
@@ -462,21 +455,14 @@ impl SmbShareManager {
        let mut count = 0u32;
        for entry in listing {
            let iso_id = format!("smb-{}-{}", share.id, slugify_str(&entry.filename));
-            // SMB sources don't get a real introspection pass — that
+            // SMB sources can't get the content-probe pass NFS/SFTP got
-            // would require seeking into the ISO9660 PVD over the
+            // in v0.7.4 — the ISO9660 probes need seeks, and smbclient's
-            // network, and smbclient CLI doesn't seek. We register an
+            // CLI streaming doesn't seek. The provisional filename-token
-            // `Unknown` family so the boot-entry generator falls back
+            // report is as far as SMB detection goes: family for the UI
-            // to generic sanboot/wimboot detection from the filename
+            // when the name says it ("rhel-9.0…", "Win11_…"), and
-            // and the operator gets *something* bootable. A follow-up
+            // `introspect_rev = 0` so the entry generator keeps the
-            // release can do a bounded `smbclient get` of the first
+            // optimistic sanboot entry.
-            // 64 KiB for real detection.
+            let report = provisional_report(&entry.filename);
            let report = IntrospectionReport {
                family: DistroFamily::Unknown,
                volume_label: None,
                kernel_path: None,
                initrd_paths: Vec::new(),
                has_boot_wim: false,
            };
            let boot_entries = generate_boot_entries_for(&iso_id, &entry.filename, &report);
            let source = IsoSource::Smb {
                share_id: share.id.clone(),
@@ -543,10 +529,7 @@ impl SmbShareManager {
                } else {
                    String::new()
                };
-                return Err((
+                return Err((format!("could not exec smbclient: {e}"), stderr));
                    format!("could not exec smbclient: {e}"),
                    stderr,
                ));
            }
        };
        if !output.status.success() {
@@ -757,10 +740,7 @@ fn parse_ls_iso(out: &str) -> Vec<SmbListEntry> {
 /// Pre-flight TCP probe to `server:port`. Format matches v0.4.64 NFS
 /// probe so the UI banner reads consistently.
-async fn tcp_probe(
+async fn tcp_probe(server: &str, port: u16) -> std::result::Result<(), (String, String)> {
    server: &str,
    port: u16,
 ) -> std::result::Result<(), (String, String)> {
    use tokio::net::TcpStream;
    let addr = format!("{server}:{port}");
    match tokio::time::timeout(PROBE_TIMEOUT, TcpStream::connect(&addr)).await {
@@ -937,8 +917,8 @@ mod tests {
        // exec error in `error` plus an empty `stderr`. The
        // SmbShareError constructor's hint_for fallback checks error
        // too, so this pattern needs to translate as well.
-        let h2 = hint_for("could not exec smbclient: No such file or directory (os error 2)")
+        let h2 =
-            .unwrap();
+            hint_for("could not exec smbclient: No such file or directory (os error 2)").unwrap();
        assert!(h2.contains("smbclient"));
    }
@@ -24,6 +24,10 @@ use tokio::io::AsyncWriteExt;
 /// `nfs3_client` crate (in-process, no subprocess). Same "works in
 /// any container" property as SMB, plus Range requests work because
 /// NFSv3 READ3 takes an explicit offset.
 /// `Sftp` (v0.5.5) — remote SFTP-over-SSH share, streamed via the
 /// pure-Rust `russh` + `russh-sftp` crates (in-process). Like NFS it
 /// supports HTTP Range requests because SFTP opens a seekable file
 /// handle (`SSH_FXP_READ` at offset).
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(tag = "kind", rename_all = "snake_case")]
 pub enum IsoSource {
@@ -42,6 +46,13 @@ pub enum IsoSource {
        /// Filename at the export root.
        relative_path: String,
    },
    /// v0.5.5: SFTP-over-SSH via the in-process `russh` + `russh-sftp`
    /// crates.
    Sftp {
        share_id: String,
        /// Filename at the export root.
        relative_path: String,
    },
 }
 /// Where the ISO lands in the PXE menu hierarchy.
@@ -212,7 +223,8 @@ impl IsoStore {
                continue;
            }
            if let Ok(text) = tokio::fs::read_to_string(&p).await {
-                if let Ok(meta) = serde_json::from_str::<IsoMeta>(&text) {
+                if let Ok(mut meta) = serde_json::from_str::<IsoMeta>(&text) {
                    self.reintrospect_if_stale(&mut meta).await;
                    self.insert(meta);
                }
            }
@@ -220,6 +232,46 @@ impl IsoStore {
        Ok(())
    }
    /// v0.5.9: re-run introspection on a *local* ISO whose persisted report
    /// predates the current logic. ISOs uploaded by an older binary carry a
    /// stale family/boot profile — most visibly a Windows 11 ISO tagged
    /// `Unknown` before the UDF/El-Torito detection landed, which then shows
    /// as "won't boot" forever. Re-probing on startup fixes them in place,
    /// no delete-and-re-upload. Bounded: only `Local` sources (we have the
    /// bytes locally) below [`introspect::INTROSPECT_REV`], so it runs at
    /// most once per ISO per upgrade. The probe reads up to ~64 MiB, so we
    /// push it onto the blocking pool to keep the async runtime responsive.
    async fn reintrospect_if_stale(&self, meta: &mut IsoMeta) {
        if !matches!(meta.source, IsoSource::Local)
            || meta.introspection.introspect_rev >= crate::introspect::INTROSPECT_REV
        {
            return;
        }
        let path = self.iso_path(&meta.id);
        if !path.exists() {
            return;
        }
        let Ok(fresh) = tokio::task::spawn_blocking(move || introspect(&path)).await else {
            tracing::warn!(target: "openpxe::iso", id = %meta.id, "re-introspect task failed");
            return;
        };
        let before = meta.introspection.family;
        meta.introspection = fresh;
        meta.boot_entries = generate_boot_entries(&meta.id, &meta.filename, &meta.introspection);
        if let Err(e) = self.persist_meta(meta).await {
            tracing::warn!(target: "openpxe::iso", id = %meta.id, "re-introspect persist: {e}");
            return;
        }
        tracing::info!(
            target: "openpxe::iso",
            id = %meta.id,
            from = ?before,
            to = ?meta.introspection.family,
            el_torito = meta.introspection.el_torito,
            "re-introspected stale ISO metadata"
        );
    }
    fn insert(&self, meta: IsoMeta) {
        self.inner.write().isos.insert(meta.id.clone(), meta);
    }
@@ -248,7 +300,19 @@ impl IsoStore {
        }
        let partial_path = self.iso_dir.join(format!("{id}.partial"));
        if partial_path.exists() {
-            return Err(Error::Invalid(format!("iso '{id}' is already uploading")));
+            // A leftover .partial is an upload abandoned mid-flight (browser
            // refresh, tab close, dropped connection) — nothing reaps it
            // otherwise, and the operator hits a bogus "already uploading"
            // on retry. The chunked protocol can't resume it anyway (a
            // fresh session restarts at offset 0), so reclaim it.
            // ponytail: two tabs uploading the *same filename* at once would
            // race here — last writer wins, and the truncating create below
            // keeps that from corrupting a half-written file.
            tracing::info!(
                target: "openpxe::iso", %id,
                "reclaiming abandoned .partial from a prior upload attempt"
            );
            tokio::fs::remove_file(&partial_path).await.ok();
        }
        let file = tokio::fs::File::create(&partial_path).await?;
        Ok(UploadHandle {
@@ -290,20 +354,29 @@ impl IsoStore {
    /// SMB sources or when the file is missing.
    pub fn iso_path_for(&self, id: &str) -> Option<PathBuf> {
        let meta = self.get(id)?;
        self.local_path(&meta)
    }
    /// Same resolution as [`Self::iso_path_for`], but for a meta the
    /// caller already holds — skips the second registry lock + deep
    /// clone, which matters on the per-range-request ISO serving path
    /// (a sanboot install issues hundreds of those).
    #[must_use]
    pub fn local_path(&self, meta: &IsoMeta) -> Option<PathBuf> {
        match &meta.source {
            IsoSource::Local => {
-                let path = self.iso_path(id);
+                let path = self.iso_path(&meta.id);
                if path.exists() {
                    Some(path)
                } else {
                    None
                }
            }
-            // SMB and NFS sources have no local path — they're
+            // SMB, NFS, and SFTP sources have no local path — they're
            // streamed in-process. Callers must inspect the source
            // kind first and dispatch to the appropriate share
            // manager.
-            IsoSource::Smb { .. } | IsoSource::Nfs { .. } => None,
+            IsoSource::Smb { .. } | IsoSource::Nfs { .. } | IsoSource::Sftp { .. } => None,
        }
    }
@@ -354,6 +427,28 @@ impl IsoStore {
        self.inner.write().isos.insert(id, meta);
    }
    /// v0.7.4: swap in a completed introspection for an external ISO and
    /// regenerate its boot entries. Used by the NFS/SFTP managers'
    /// background probe pass — the scan registers a provisional
    /// (filename-only) report immediately so startup and share-add stay
    /// fast, then this upgrades each entry as its probe finishes.
    /// Operator-set fields (category, password) are preserved; returns
    /// `false` when the id is gone (share removed or re-scanned away
    /// mid-probe), which callers treat as a benign no-op.
    pub fn update_external_introspection(
        &self,
        id: &str,
        introspection: IntrospectionReport,
    ) -> bool {
        let mut g = self.inner.write();
        let Some(m) = g.isos.get_mut(id) else {
            return false;
        };
        m.boot_entries = generate_boot_entries(&m.id, &m.filename, &introspection);
        m.introspection = introspection;
        true
    }
    /// Drop every entry that belongs to `share_id`. Used by the SMB
    /// and NFS share managers when an operator removes a share, or
    /// before re-scanning to clean out stale entries. The same id
@@ -363,9 +458,9 @@ impl IsoStore {
    pub fn drop_external_source(&self, share_id: &str) {
        let mut g = self.inner.write();
        g.isos.retain(|_, m| match &m.source {
-            IsoSource::Smb { share_id: sid, .. } | IsoSource::Nfs { share_id: sid, .. } => {
+            IsoSource::Smb { share_id: sid, .. }
-                sid != share_id
+            | IsoSource::Nfs { share_id: sid, .. }
-            }
+            | IsoSource::Sftp { share_id: sid, .. } => sid != share_id,
            IsoSource::Local => true,
        });
    }
@@ -546,22 +641,22 @@ fn generate_boot_entries(id: &str, filename: &str, r: &IntrospectionReport) -> V
        .clone()
        .unwrap_or_else(|| filename.to_string());
    match r.family {
-        DistroFamily::WindowsPe if r.has_boot_wim => {
+        DistroFamily::WindowsPe => {
-            // Standard wimboot chain. Paths are in-ISO; the HTTP layer maps
+            // v0.5.8: boot Windows directly via iPXE HTTP sanboot. iPXE
-            // `iso/<id>/<path>` to on-disk extraction via ISO9660 lookup.
+            // exposes the raw ISO as an emulated CD backed by on-demand
-            let base = format!("iso/{id}");
+            // HTTP range reads, and Windows Setup boots from it. This
            // replaces the old wimboot+SMB chain, which (a) needed an SMB
            // server the host often can't provide (port 445 collisions),
            // (b) served in-ISO files via an ISO9660 lookup that failed on
            // UDF-only Windows 11 ISOs, and (c) required an operator
            // toggle. sanboot needs none of that — just the HTTP port,
            // which works in any environment. The unmodified, stock ISO is
            // served at iso/<id>.iso; nothing is injected into Windows.
            vec![BootEntry {
-                id: format!("{id}-winpe"),
+                id: format!("{id}-windows"),
-                title: format!("{title} (Windows / wimboot)"),
+                title: format!("{title} (Windows)"),
-                kind: BootKind::Wimboot {
+                kind: BootKind::SanBootIso {
-                    wimboot_url: "ipxe/wimboot".to_string(),
+                    iso_url: format!("iso/{id}.iso"),
                    files: vec![
                        ("bootmgr".into(), format!("{base}/bootmgr")),
                        ("bootmgr.efi".into(), format!("{base}/bootmgr.efi")),
                        ("bcd".into(), format!("{base}/boot/bcd")),
                        ("boot.sdi".into(), format!("{base}/boot/boot.sdi")),
                        ("boot.wim".into(), format!("{base}/sources/boot.wim")),
                    ],
                },
            }]
        }
@@ -587,15 +682,33 @@ fn generate_boot_entries(id: &str, filename: &str, r: &IntrospectionReport) -> V
            }]
        }
        _ => {
-            // Last-resort SAN boot. Won't work for large modern ISOs, but
+            // No Windows-install media and no Linux kernel/initrd. Decide
-            // lets the ISO at least appear in the menu.
+            // whether the ISO is bootable at all (v0.6.0):
-            vec![BootEntry {
+            //   * `el_torito` — it carries a boot catalog, so iPXE sanboots
-                id: format!("{id}-sanboot"),
+            //     the raw image as an emulated CD: BSDs, ESXi/VMvisor
-                title: format!("{title} (SAN boot — may fail for >1GiB ISOs)"),
+            //     installers, firmware tools, custom spins. The emulated CD
-                kind: BootKind::SanBootIso {
+            //     is backed by HTTP range reads, so ISO size is a non-issue
-                    iso_url: format!("iso/{id}.iso"),
+            //     (this is the same path Windows uses since v0.5.8) — hence
-                },
+            //     no more "may fail for >1GiB ISOs" disclaimer.
-            }]
+            //   * `introspect_rev == 0` — a remote-share ISO we couldn't
            //     introspect (SMB/NFS/SFTP listings don't seek into the ISO).
            //     Offer sanboot optimistically rather than hide a
            //     likely-bootable installer.
            // Otherwise it's a local image we *did* introspect and found to
            // carry no boot catalog — a data/appliance ISO (e.g. a VMware
            // vCenter Server Appliance bundle). It genuinely cannot boot, so
            // we expose no menu entry; the dashboard flags it instead.
            if r.el_torito || r.introspect_rev == 0 {
                vec![BootEntry {
                    id: format!("{id}-sanboot"),
                    title,
                    kind: BootKind::SanBootIso {
                        iso_url: format!("iso/{id}.iso"),
                    },
                }]
            } else {
                Vec::new()
            }
        }
    }
 }
@@ -659,13 +772,59 @@ mod tests {
        // good.
        let s = linux_cmdline(DistroFamily::DebianUbuntu, "ubuntu-24-04");
        assert!(s.contains("boot=casper"), "{s}");
-        assert!(s.contains("iso-url=${base-url}/iso/ubuntu-24-04.iso"), "{s}");
+        assert!(
            s.contains("iso-url=${base-url}/iso/ubuntu-24-04.iso"),
            "{s}"
        );
        assert!(s.contains("ds=nocloud"), "{s}");
        assert!(s.contains("ip=dhcp"), "{s}");
        assert!(!s.contains("netboot=url"), "legacy option leaked: {s}");
        assert!(!s.contains(" --- "), "stray ---: {s}");
    }
    #[test]
    fn boot_entries_respect_el_torito_and_source() {
        use crate::introspect::INTROSPECT_REV;
        // ESXi / VMvisor installer shape: bootable (carries an El Torito
        // catalog) but not classifiable as Windows or Linux. Must yield a
        // single sanboot entry so it's selectable + boots via emulated CD.
        let esxi = IntrospectionReport {
            family: DistroFamily::Unknown,
            volume_label: Some("ESXI-7.0U3".into()),
            el_torito: true,
            introspect_rev: INTROSPECT_REV,
            ..Default::default()
        };
        let e = generate_boot_entries("esxi", "VMware-VMvisor-Installer-7.0U3n.iso", &esxi);
        assert_eq!(e.len(), 1, "ESXi should get exactly one boot entry");
        assert!(matches!(e[0].kind, BootKind::SanBootIso { .. }));
        // Clean title — no stale ">1GiB may fail" disclaimer.
        assert!(!e[0].title.contains("may fail"), "title: {}", e[0].title);
        // VCSA / data-appliance shape: locally introspected (rev set), no
        // boot catalog, not Windows/Linux. Genuinely unbootable → no entry,
        // so it stays out of the iPXE menu (the dashboard flags it instead).
        let vcsa = IntrospectionReport {
            family: DistroFamily::Unknown,
            el_torito: false,
            introspect_rev: INTROSPECT_REV,
            ..Default::default()
        };
        assert!(
            generate_boot_entries("vcsa", "VMware-VCSA-all-8.0.iso", &vcsa).is_empty(),
            "data/appliance ISO must produce no boot entry"
        );
        // Remote-share ISO: never introspected (rev 0, no random access over
        // SMB/NFS/SFTP). Assume bootable and offer sanboot rather than hide a
        // likely-bootable installer.
        let remote = IntrospectionReport::default();
        let r = generate_boot_entries("remote", "unknown-remote.iso", &remote);
        assert_eq!(r.len(), 1, "remote (uninspected) ISO keeps a sanboot entry");
        assert!(matches!(r[0].kind, BootKind::SanBootIso { .. }));
    }
    fn fake_meta(id: &str) -> IsoMeta {
        IsoMeta {
            id: id.into(),
@@ -673,13 +832,7 @@ mod tests {
            size_bytes: 0,
            sha256_hex: None,
            uploaded_at: OffsetDateTime::now_utc(),
-            introspection: IntrospectionReport {
+            introspection: IntrospectionReport::default(),
                family: DistroFamily::Unknown,
                volume_label: None,
                kernel_path: None,
                initrd_paths: vec![],
                has_boot_wim: false,
            },
            boot_entries: vec![],
            source: IsoSource::Local,
            password_hash: None,
@@ -731,15 +884,39 @@ mod tests {
    }
    #[tokio::test]
-    async fn begin_upload_rejects_existing_partial_file() {
+    async fn begin_upload_reclaims_stale_partial_file() {
        // v0.8.0: an abandoned .partial (browser refresh / crash / dropped
        // connection) must not block a re-upload with a bogus "already
        // uploading" — begin_upload reclaims it and starts fresh, since the
        // chunked protocol can't resume a dead session anyway.
        let dir = tempdir().unwrap();
        let store = IsoStore::new(dir.path().to_path_buf());
        store.ensure_dirs().await.unwrap();
-        tokio::fs::write(dir.path().join("ubuntu.partial"), b"in-flight")
+        let partial = dir.path().join("ubuntu.partial");
        tokio::fs::write(&partial, b"in-flight").await.unwrap();
        let handle = store
            .begin_upload("ubuntu.iso")
            .await
            .expect("stale .partial is reclaimed, not rejected");
        assert_eq!(handle.id, "ubuntu");
        // Reclaimed: the leftover bytes are gone (fresh, empty file).
        let meta = tokio::fs::metadata(&partial).await.unwrap();
        assert_eq!(meta.len(), 0, "stale .partial must be truncated on reclaim");
    }
    #[tokio::test]
    async fn begin_upload_still_rejects_completed_iso() {
        // A finished upload (final .iso on disk) is a genuine duplicate, not
        // an abandoned attempt — that case must still be refused.
        let dir = tempdir().unwrap();
        let store = IsoStore::new(dir.path().to_path_buf());
        store.ensure_dirs().await.unwrap();
        tokio::fs::write(dir.path().join("rocky.iso"), b"done")
            .await
            .unwrap();
-        let r = store.begin_upload("ubuntu.iso").await;
+        let r = store.begin_upload("rocky.iso").await;
        assert!(matches!(r, Err(Error::Invalid(_))));
    }
@@ -26,7 +26,5 @@ tracing.workspace = true
 tracing-subscriber.workspace = true
 anyhow.workspace = true
 clap.workspace = true
 serde.workspace = true
 toml.workspace = true
 bytes.workspace = true
 time.workspace = true
@@ -9,7 +9,7 @@ use openpxe_core::{
 };
 use openpxe_dhcp_proxy::DhcpProxyServer;
 use openpxe_http_api::{build_router, AppState};
-use openpxe_iso_store::{IsoStore, NfsShareManager, SmbManager, SmbShareManager};
+use openpxe_iso_store::{IsoStore, NfsShareManager, SftpShareManager, SmbManager, SmbShareManager};
 use openpxe_tftp::TftpServer;
 use std::net::{Ipv4Addr, SocketAddr};
 use std::path::PathBuf;
@@ -59,11 +59,10 @@ async fn main() -> anyhow::Result<()> {
    init_tracing(log_bus.clone());
    let cli = Cli::parse();
-    let mut config = match &cli.config {
+    // v0.5.4: layered load via figment — defaults → optional TOML → env.
-        Some(p) if p.exists() => Config::from_toml_file(p)?,
+    // The OPENPXE_* env layer keeps the historical flat names (see
-        _ => Config::default(),
+    // `Config::load`), so existing deployments are unaffected.
-    };
+    let config = Config::load(cli.config.as_deref())?;
    config.apply_env();
    // Dispatch subcommands before bringing up the server.
    if let Some(cmd) = cli.command {
@@ -95,14 +94,19 @@ async fn main() -> anyhow::Result<()> {
            }
        },
    };
-    let public_base_url = format!("http://{our_ip}");
+    // v0.5.6: the advertised base URL must carry the HTTP port. Every
    // client-facing URL (the DHCP-proxy iPXE filename, UEFI HTTP boot,
    // and the menu's kernel/initrd/ISO links) is derived from this one
    // string, so omitting the port silently pointed PXE clients at :80 —
    // breaking every non-80 deployment (e.g. the Unraid template's 4200,
    // chosen to dodge the webGUI). See `build_public_base_url`.
    let public_base_url = build_public_base_url(our_ip, config.server.http_port);
    let iso_store = IsoStore::new(config.paths.iso_dir.clone());
    iso_store.load_from_disk().await?;
    // v0.5.2: unattended answer-file store (Kickstart/Preseed/Autoinstall/
    // Windows answer files). Separate directory from the ISO store.
-    let unattended =
+    let unattended = openpxe_iso_store::UnattendedStore::new(config.paths.unattended_dir.clone());
        openpxe_iso_store::UnattendedStore::new(config.paths.unattended_dir.clone());
    if let Err(e) = unattended.load_from_disk().await {
        tracing::warn!(
            target: "openpxe::unattended",
@@ -116,8 +120,41 @@ async fn main() -> anyhow::Result<()> {
    let boot_log = openpxe_core::BootLog::load_or_default(&config.paths.work_dir);
    let branding = openpxe_core::BrandingStore::load_or_default(&config.paths.work_dir);
    let admin = openpxe_core::AdminStore::load_or_default(&config.paths.work_dir);
    // v0.8.1: zero-touch first-run bootstrap. If no admin exists yet and the
    // operator supplied OPENPXE_ADMIN_USERNAME + OPENPXE_ADMIN_PASSWORD (or
    // …_PASSWORD_FILE, for Docker/K8s secrets), create the admin now so a
    // fresh container is usable without the web setup wizard. Seeds the
    // first run only — once an admin exists (including one made in the UI)
    // this is a no-op, so a lingering env var can't reset a rotated password.
    if !admin.is_configured() {
        if let Ok(username) = std::env::var("OPENPXE_ADMIN_USERNAME") {
            let password = std::env::var("OPENPXE_ADMIN_PASSWORD_FILE")
                .ok()
                .and_then(|p| std::fs::read_to_string(p).ok())
                .map(|s| s.trim_end_matches(['\n', '\r']).to_string())
                .or_else(|| std::env::var("OPENPXE_ADMIN_PASSWORD").ok());
            if let Some(password) = password {
                match admin.bootstrap(&username, &password) {
                    Ok(p) => tracing::info!(
                        target: "openpxe::auth", username = %p.username,
                        "admin bootstrapped from environment"
                    ),
                    Err(e) => tracing::warn!(
                        target: "openpxe::auth",
                        "env admin bootstrap failed ({e}); use the web setup wizard"
                    ),
                }
            } else {
                tracing::warn!(
                    target: "openpxe::auth",
                    "OPENPXE_ADMIN_USERNAME set without OPENPXE_ADMIN_PASSWORD[_FILE]; skipping bootstrap"
                );
            }
        }
    }
    let sso = openpxe_core::SsoStore::load_or_default(&config.paths.work_dir);
    let notify = openpxe_core::NotifyStore::load_or_default(&config.paths.work_dir);
    let api_key = openpxe_core::ApiKeyStore::load_or_init(&config.paths.work_dir);
    let sessions = openpxe_http_api::auth::SessionStore::default();
    let metrics = Metrics::new();
@@ -156,6 +193,19 @@ async fn main() -> anyhow::Result<()> {
        );
    }
    // v0.5.5: SFTP-over-SSH share manager — pure-Rust in-process
    // consumer via `russh` + `russh-sftp` (ring backend, no OpenSSL).
    // The third remote-library protocol alongside SMB/NFS; like NFS it
    // works in any container (no subprocess, no kernel mount) and
    // supports HTTP Range requests because SFTP file handles seek.
    let sftp_shares = SftpShareManager::new(&config.paths.work_dir, iso_store.clone());
    if let Err(e) = sftp_shares.load_and_rescan().await {
        tracing::warn!(
            target: "openpxe::sftp",
            "could not reload SFTP shares on startup: {e}"
        );
    }
    // Sniff network details for the Network tab. None of these are
    // required for PXE to work — they're informational, surfaced in the
    // UI so an operator doesn't have to drop to a shell to find their
@@ -167,6 +217,10 @@ async fn main() -> anyhow::Result<()> {
        "network info"
    );
    // v0.7.1: boot rules are shared between the HTTP layer (target rules,
    // webhook, the editor API) and the DHCP proxy (driver-mode pins).
    let boot_rules = openpxe_core::BootRulesStore::load_or_default(&config.paths.work_dir);
    let state = AppState {
        iso_store: iso_store.clone(),
        clients: clients.clone(),
@@ -174,9 +228,13 @@ async fn main() -> anyhow::Result<()> {
        queue: queue.clone(),
        hosts: hosts.clone(),
        boot_log: boot_log.clone(),
        boot_rules: boot_rules.clone(),
        boot_tokens: openpxe_core::BootTokens::new(),
        branding: branding.clone(),
        pxe_bg_cache: openpxe_http_api::state::PxeBgCache::default(),
        admin: admin.clone(),
        sessions: sessions.clone(),
        api_key,
        sso: sso.clone(),
        saml: openpxe_http_api::saml_routes::SamlRuntime::default(),
        notify: notify.clone(),
@@ -184,12 +242,15 @@ async fn main() -> anyhow::Result<()> {
        smb: Some(smb.clone()),
        smb_shares: smb_shares.clone(),
        nfs_shares: nfs_shares.clone(),
        sftp_shares: sftp_shares.clone(),
        unattended: unattended.clone(),
        uploads: openpxe_http_api::uploads::UploadSessions::default(),
        fetch_jobs: openpxe_http_api::fetch::FetchJobs::default(),
        log_bus: log_bus.clone(),
        started_at: time::OffsetDateTime::now_utc(),
        public_base_url: public_base_url.clone(),
        nic_name: net.nic_name,
        nic_link: net.nic_link,
        subnet_mask: net.subnet_mask,
        gateway: net.gateway,
    };
@@ -211,11 +272,28 @@ async fn main() -> anyhow::Result<()> {
        Ok::<_, anyhow::Error>(())
    });
    // v0.7.0: TFTP names that aren't embedded assets get a dynamic
    // renderer — `grub.cfg` for the Secure Boot shim+GRUB chain is
    // generated from the live boot-entry list on every fetch, so menu
    // changes apply without restart.
    let grub_isos = iso_store.clone();
    let grub_base = public_base_url.clone();
    let tftp_dynamic: openpxe_tftp::DynamicAsset = std::sync::Arc::new(move |name: &str| {
        if name == "grub.cfg" || name.starts_with("grub.cfg-") {
            Some(
                openpxe_http_api::grub_script::render_grub_menu(&grub_isos.list(), &grub_base)
                    .into_bytes(),
            )
        } else {
            None
        }
    });
    let tftp = TftpServer::new(
        config.server.tftp_bind,
        config.server.tftp_port,
        clients.clone(),
        metrics.clone(),
        Some(tftp_dynamic),
    );
    let tftp_task = tokio::spawn(tftp.run());
@@ -229,6 +307,10 @@ async fn main() -> anyhow::Result<()> {
                public_base_url.clone(),
                clients.clone(),
                metrics.clone(),
                // v0.7.1: learned driver modes persist next to the other
                // state files, so a machine walks the ladder once *ever*.
                openpxe_dhcp_proxy::DriverEscalation::load_or_default(&config.paths.work_dir),
                boot_rules.clone(),
            );
            tokio::spawn(s.run())
        }
@@ -333,6 +415,20 @@ async fn seed_from_dir(
 /// a loopback address (which would give every PXE client an unreachable
 /// `http://127.0.0.1/...`). Users in multi-homed setups should set
 /// `OPENPXE_PUBLIC_IP` explicitly.
 /// Build the base URL advertised to PXE clients. The port is included
 /// unless it's the HTTP default (80), keeping the common case clean
 /// (`http://10.0.0.5`) while a remapped port (`http://10.0.0.5:4200`)
 /// stays reachable. This is the single source of truth for every
 /// client-facing URL — the DHCP-proxy iPXE filename, UEFI HTTP boot, and
 /// the boot menu's kernel/initrd/ISO links all derive from it.
 fn build_public_base_url(ip: Ipv4Addr, http_port: u16) -> String {
    if http_port == 80 {
        format!("http://{ip}")
    } else {
        format!("http://{ip}:{http_port}")
    }
 }
 fn detect_primary_ipv4() -> Option<Ipv4Addr> {
    // First try: route to the public internet. `UdpSocket::connect` to a
    // well-known external address causes the OS to populate `local_addr`
@@ -388,6 +484,12 @@ struct NetworkInfo {
    nic_name: String,
    subnet_mask: String,
    gateway: String,
    /// v0.7.2: physical link summary for the Network tab — operstate,
    /// negotiated speed/duplex, and the port's own MAC. Helps operators
    /// in multi-NIC / trunked environments confirm *which* port the PXE
    /// server actually answers on. Empty when sysfs isn't available
    /// (non-Linux dev builds) or the NIC wasn't identified.
    nic_link: String,
 }
 /// Best-effort population of the Network tab's read-only fields. We shell
@@ -448,9 +550,44 @@ fn detect_network_info(our_ip: Ipv4Addr) -> NetworkInfo {
        }
    }
    info.nic_link = detect_link_info(&info.nic_name);
    info
 }
 /// v0.7.2: read the NIC's physical link details from sysfs. Every field
 /// is optional — virtual NICs report no speed (`-1` or absent), and
 /// non-Linux dev machines have no `/sys/class/net` at all — so the
 /// result is whatever could be read, joined human-readably, or empty.
 fn detect_link_info(nic: &str) -> String {
    if nic.is_empty() {
        return String::new();
    }
    let read = |file: &str| {
        std::fs::read_to_string(format!("/sys/class/net/{nic}/{file}"))
            .map(|s| s.trim().to_string())
            .unwrap_or_default()
    };
    let mut parts: Vec<String> = Vec::new();
    let state = read("operstate");
    if !state.is_empty() {
        parts.push(format!("link {state}"));
    }
    let speed = read("speed");
    if !speed.is_empty() && speed != "-1" {
        parts.push(format!("{speed} Mb/s"));
    }
    let duplex = read("duplex");
    if !duplex.is_empty() && duplex != "unknown" {
        parts.push(format!("{duplex} duplex"));
    }
    let mac = read("address");
    if !mac.is_empty() {
        parts.push(format!("port {mac}"));
    }
    parts.join(" · ")
 }
 fn prefix_to_dotted(prefix: u8) -> String {
    let prefix = prefix.min(32);
    let mask: u32 = if prefix == 0 {
@@ -466,3 +603,26 @@ fn prefix_to_dotted(prefix: u8) -> String {
        mask & 0xff
    )
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    #[test]
    fn public_base_url_includes_non_default_port() {
        // The v0.5.6 regression guard: a remapped HTTP port (e.g. the
        // Unraid template's 4200) MUST appear in the advertised URL, or
        // PXE clients fetch :80 — the wrong service — and boot fails.
        let ip: Ipv4Addr = "192.168.1.49".parse().unwrap();
        assert_eq!(build_public_base_url(ip, 4200), "http://192.168.1.49:4200");
        assert_eq!(build_public_base_url(ip, 8080), "http://192.168.1.49:8080");
    }
    #[test]
    fn public_base_url_omits_default_port() {
        // Port 80 stays clean (no `:80`) so the common case reads nicely
        // and matches what every browser/iPXE assumes by default.
        let ip: Ipv4Addr = "10.0.0.5".parse().unwrap();
        assert_eq!(build_public_base_url(ip, 80), "http://10.0.0.5");
    }
 }
@@ -15,6 +15,4 @@ openpxe-ipxe-assets.workspace = true
 tokio.workspace = true
 socket2.workspace = true
 tracing.workspace = true
 thiserror.workspace = true
 anyhow.workspace = true
 bytes.workspace = true
@@ -14,4 +14,4 @@
 pub mod server;
-pub use server::TftpServer;
+pub use server::{DynamicAsset, TftpServer};
@@ -7,12 +7,12 @@
 //! `tftpd`/`in.tftpd` works and is why TFTP is awkward behind stateful NAT:
 //! the ephemeral ports must be reachable from the client.
 //!
-//! We only serve files from `openpxe_ipxe_assets::asset_bytes` — that is,
+//! We only serve files from `openpxe_ipxe_assets::asset_slice` — that is,
 //! the bundled iPXE binaries and wimboot. No filesystem is ever opened, so
 //! `../` path traversal attempts simply return ENOENT.
 use openpxe_core::{ClientEvent, ClientRegistry};
-use openpxe_ipxe_assets::asset_bytes;
+use openpxe_ipxe_assets::asset_slice;
 use socket2::{Domain, Protocol, Socket, Type};
 use std::net::{IpAddr, SocketAddr};
 use std::sync::Arc;
@@ -21,6 +21,7 @@ use tokio::net::UdpSocket;
 // TFTP opcodes.
 const OP_RRQ: u16 = 1;
 const OP_WRQ: u16 = 2;
 const OP_DATA: u16 = 3;
 const OP_ACK: u16 = 4;
 const OP_ERROR: u16 = 5;
@@ -31,11 +32,19 @@ const ERR_NOT_DEFINED: u16 = 0;
 const ERR_FILE_NOT_FOUND: u16 = 1;
 const ERR_ILLEGAL_OP: u16 = 4;
 /// Server-rendered TFTP content for names that aren't embedded assets —
 /// e.g. `grub.cfg` for the signed shim+GRUB Secure Boot chain (v0.7.0),
 /// which is generated from the live boot-entry list per fetch. Kept as a
 /// closure so this crate stays decoupled from the ISO store; the binary
 /// wires it up in `main`.
 pub type DynamicAsset = Arc<dyn Fn(&str) -> Option<Vec<u8>> + Send + Sync>;
 pub struct TftpServer {
    bind: IpAddr,
    port: u16,
    clients: Arc<ClientRegistry>,
    metrics: openpxe_core::Metrics,
    dynamic: Option<DynamicAsset>,
 }
 impl TftpServer {
@@ -44,12 +53,14 @@ impl TftpServer {
        port: u16,
        clients: Arc<ClientRegistry>,
        metrics: openpxe_core::Metrics,
        dynamic: Option<DynamicAsset>,
    ) -> Self {
        Self {
            bind,
            port,
            clients,
            metrics,
            dynamic,
        }
    }
@@ -71,8 +82,11 @@ impl TftpServer {
            let clients = clients.clone();
            let metrics = metrics.clone();
            let bind_ip = self.bind;
            let dynamic = self.dynamic.clone();
            tokio::spawn(async move {
-                if let Err(e) = handle_rrq(data, from, bind_ip, clients, metrics.clone()).await {
+                if let Err(e) =
                    handle_rrq(data, from, bind_ip, clients, metrics.clone(), dynamic).await
                {
                    metrics.record_tftp_err();
                    tracing::warn!(target: "openpxe::tftp", peer=%from, "handler error: {e}");
                }
@@ -87,18 +101,45 @@ async fn handle_rrq(
    bind_ip: IpAddr,
    clients: Arc<ClientRegistry>,
    metrics: openpxe_core::Metrics,
    dynamic: Option<DynamicAsset>,
 ) -> anyhow::Result<()> {
    let Some(req) = parse_rrq(&packet) else {
        // Not a well-formed RRQ. A WRQ deserves an explicit refusal —
        // legacy clients retry a silently-dropped write until they time
        // out; an ERROR packet fails them fast with a readable reason.
        if packet.len() >= 2 && u16::from_be_bytes([packet[0], packet[1]]) == OP_WRQ {
            let sock = bind_udp(bind_ip, 0)?;
            let _ = send_error(&sock, peer, ERR_ILLEGAL_OP, "writes not supported").await;
        }
        return Ok(());
    };
    let Request {
-        filename, options, ..
+        filename,
        mode,
        options,
    } = req;
    // Per-transfer ephemeral socket.
    let sock = bind_udp(bind_ip, 0)?;
-    let Some(file_bytes) = asset_bytes(&filename) else {
+    // We serve binary boot artifacts; netascii line-ending translation
    // would corrupt them. Refuse loudly instead of timing out silently —
    // matters for legacy clients that default to netascii.
    if !mode.eq_ignore_ascii_case("octet") {
        let _ = send_error(&sock, peer, ERR_NOT_DEFINED, "only octet mode is supported").await;
        tracing::info!(target: "openpxe::tftp", peer=%peer, %mode, "rejected non-octet transfer");
        return Ok(());
    }
    // Embedded assets first; otherwise the dynamic renderer (server-
    // generated content like the Secure Boot chain's grub.cfg, v0.7.0).
    let resolved = asset_slice(&filename).or_else(|| {
        dynamic
            .as_ref()
            .and_then(|f| f(&filename))
            .map(std::borrow::Cow::Owned)
    });
    let Some(file_bytes) = resolved else {
        let _ = send_error(&sock, peer, ERR_FILE_NOT_FOUND, "no such file").await;
        tracing::info!(target: "openpxe::tftp", peer=%peer, file=%filename, "404");
        clients.record(
@@ -262,7 +303,6 @@ async fn handle_rrq(
 #[derive(Debug)]
 struct Request {
    filename: String,
    #[allow(dead_code)]
    mode: String,
    options: Vec<(String, String)>,
 }
@@ -393,17 +433,13 @@ fn bind_udp(bind: IpAddr, port: u16) -> anyhow::Result<UdpSocket> {
    Ok(UdpSocket::from_std(std_sock)?)
 }
-#[allow(dead_code)]
+/// Pure-logic mirror of `handle_rrq`'s windowing math, exercised by the
-const _UNUSED: (u16, u16) = (ERR_NOT_DEFINED, ERR_ILLEGAL_OP);
+/// unit tests below. Given a position in the file and the window, return
-
+/// the (block_no, chunk_len) list this window will emit — tested against
-/// Pure-logic helper used by the unit tests below and (in a refactor) by
+/// edge cases (exact-blksize tail, short tail, single-block window,
-/// `handle_rrq`. Given a position in the file and the window, return the
+/// block-number wraparound).
-/// (block_no, chunk_len) list this window will emit. Useful as a sanity
+#[cfg(test)]
-/// check that our windowing math matches the wire behavior the spec
+fn plan_window(
 /// requires — tested against edge cases (exact-blksize tail, short tail,
 /// single-block window).
 #[must_use]
 pub fn plan_window(
    total: usize,
    offset: usize,
    blksize: usize,
@@ -912,3 +912,28 @@ tr.unbootable td:first-child { border-left: 3px solid var(--warn); }
  display: flex; justify-content: flex-end; gap: 10px; margin-top: 18px;
 }
 .modal-actions .submit { width: auto; padding: 8px 18px; }
 /* v0.7.2: a label.field directly followed by the card's action button
   stacked its own 14px bottom margin onto the button's 16px top margin
   (30px total) — visible on Queue "Launch for all waiting" and the
   Network "Save". Collapse the doubled gap so every primary action sits
   the same 16px below its form. */
 .card .body > label.field:has(+ button) { margin-bottom: 0; }
 /* v0.7.2: inline list filter above a table (Available images). The input
   is wrapped in a label.field so it borrows the standard text-field chrome
   and matches every other input in the app; this wrapper just insets it
   from the card edges so it lines up with the header text above. */
 .list-search { padding: 14px 16px; }
 /* v0.7.4: pager footer under the Available-images table — quiet status
   text on the left, ghost Prev/Next on the right. */
 .list-pager {
  display: flex; align-items: center; gap: 8px;
  padding: 12px 16px;
  color: var(--fg-dim); font-size: 12px;
  font-variant-numeric: tabular-nums;
 }
 .list-pager .spacer { flex: 1; }
 .list-pager button { padding: 4px 12px; font-size: 12px; }
 .list-pager button:disabled { opacity: 0.45; cursor: default; }
@@ -23,11 +23,19 @@ ARG RUST_VERSION=1.95
 # and serve as the baseline that the PNG-enabled x86_64/arm64 UEFI
 # binaries from the `ipxe-build` stage overlay on top of.
 FROM debian:12-slim AS fetch
-RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates \
+# rpm2cpio + cpio: extract Fedora's Microsoft-signed shim/GRUB RPMs for
 # the Secure Boot chain (v0.7.0, scripts/fetch-shim.sh).
 RUN apt-get update && apt-get install -y --no-install-recommends \
        curl ca-certificates rpm2cpio cpio \
 && rm -rf /var/lib/apt/lists/*
 WORKDIR /src
 COPY scripts/fetch-ipxe.sh scripts/fetch-ipxe.sh
 COPY scripts/fetch-shim.sh scripts/fetch-shim.sh
 RUN mkdir -p assets/ipxe && bash scripts/fetch-ipxe.sh
 # Signed shim+GRUB (Secure Boot escalation rung). Redistributed
 # unmodified from the official Fedora packages — see fetch-shim.sh for
 # the trust model.
 RUN bash scripts/fetch-shim.sh /src/assets/ipxe
 ########## build PNG-enabled iPXE from source ##########
 # v0.4.69: THE graphical-boot-menu unlock. iVentoy paints a PNG
@@ -1,66 +1,42 @@
-# docker-compose for local / homelab deployment.
+# OpenPXE — single-host / homelab deployment.
 #
-# Two usage patterns:
+# One container: DHCP proxy + TFTP + iPXE chainload + HTTP (web UI, boot
 # scripts, and ISO range streaming).
 #
-#   1. Local MVP test — host network, proxy-DHCP off (don't fight your
+#   OPENPXE_PUBLIC_IP=192.168.1.49 docker compose up -d
 #      existing DHCP server on the LAN), TFTP + HTTP exposed on the host:
 #
-#         docker compose up openpxe-dev
+# (or put OPENPXE_PUBLIC_IP in a .env file beside this one). That's this
 # host's LAN IP, advertised to PXE clients so the iPXE URLs resolve —
 # OpenPXE refuses to start rather than advertise an address clients can't
 # reach, so compose errors out below if it's unset.
 #
-#   2. Real PXE deployment — host network, proxy-DHCP on, runs on a box
+# Host networking is REQUIRED: DHCPDISCOVER is a broadcast, and Docker
-#      plugged into the PXE network:
+# bridges / CNI overlays don't forward it into containers. In host mode
 # the container binds these ports directly on the host:
 #
-#         # First set OPENPXE_PUBLIC_IP to this host's LAN address in .env
+#   udp/67    DHCP proxy          udp/4011  PXE Boot Server
-#         docker compose up openpxe
+#   udp/69    TFTP                tcp/4200  web UI + HTTP boot assets
 #
-# On Linux hosts, `network_mode: host` gives the container direct access to
+# Web UI:  http://<this-host>:4200/
 # the physical NIC — required for DHCP proxy because CNI overlays and Docker
 # bridges do not forward DHCPDISCOVER broadcasts into containers.
 #
 # On macOS / Windows hosts, `network_mode: host` is limited — the daemon
 # runs in a Linux VM (Colima/Docker Desktop) so the "host" network is the
 # VM, not your Mac. Proxy-DHCP is not feasible on macOS; use `openpxe-dev`
 # with published ports and set DHCP-MODE=disabled.
 services:
  # Real PXE deployment (Linux hosts).
  openpxe:
-    image: openpxe:0.1.0
+    image: gitea.milesward.dev/mward4/openpxe:latest
-    build:
+    container_name: openpxe
      context: .
      dockerfile: deploy/docker/Dockerfile
    restart: unless-stopped
    network_mode: host
    # The binary carries cap_net_bind_service as a file capability, so it
    # binds the low DHCP/TFTP ports as a non-root user — no privileged mode.
    cap_add:
      - NET_BIND_SERVICE
    environment:
-      # REQUIRED on multi-homed hosts. Set to this machine's LAN IP so the
+      OPENPXE_PUBLIC_IP: ${OPENPXE_PUBLIC_IP:?set this to the host LAN IP, e.g. 192.168.1.49}
-      # advertised iPXE URLs actually resolve from the PXE clients. Without
+      # Web UI + HTTP boot assets. 4200 keeps clear of anything on :80
-      # this, OpenPXE will refuse to start rather than advertise a
+      # (an Unraid webGUI, a reverse proxy, …).
-      # loopback address that can't be reached.
+      OPENPXE_HTTP_PORT: "4200"
-      OPENPXE_PUBLIC_IP: ${OPENPXE_PUBLIC_IP:?set this to the host LAN IP}
+      # proxy = coexist with the LAN's existing DHCP server (recommended).
      OPENPXE_DHCP_MODE: proxy
      OPENPXE_LOG: info
    volumes:
-      - ./data/isos:/var/lib/openpxe/isos
+      - ./data/isos:/var/lib/openpxe/isos   # uploaded / seeded .iso files
-      - ./data/work:/var/lib/openpxe/work
+      - ./data/work:/var/lib/openpxe/work   # settings, share state, scratch
  # Dev / MVP container: published ports, DHCP disabled, HTTP on 8080.
  # Use this on laptops where you want to curl the API or UI without
  # running an actual PXE chain.
  openpxe-dev:
    image: openpxe:0.1.0
    build:
      context: .
      dockerfile: deploy/docker/Dockerfile
    environment:
      OPENPXE_PUBLIC_IP: ${OPENPXE_PUBLIC_IP:-127.0.0.1}
      OPENPXE_DHCP_MODE: disabled
      OPENPXE_HTTP_PORT: "8080"
      OPENPXE_TFTP_PORT: "6969"
      OPENPXE_DHCP_PORT: "6767"
      OPENPXE_LOG: info,openpxe=debug
    ports:
      - "8080:8080/tcp"
      - "6969:6969/udp"
    volumes:
      - ./data/isos:/var/lib/openpxe/isos
      - ./data/work:/var/lib/openpxe/work
@@ -0,0 +1,21 @@
 <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="OpenPXE">
  <title>OpenPXE</title>
  <!-- Static README mark: the "rainbow-horizon" medallion from the web UI,
       with the SMIL animation removed so it renders reliably as an <img>
       on Gitea/GitHub. -->
  <defs>
    <linearGradient id="opxRainbow" x1="0" y1="0" x2="1" y2="0">
      <stop offset="0%"     stop-color="#330f1f"/>
      <stop offset="12.56%" stop-color="#c83228"/>
      <stop offset="25.06%" stop-color="#fb8841"/>
      <stop offset="37.56%" stop-color="#d3dd92"/>
      <stop offset="50.06%" stop-color="#59824f"/>
      <stop offset="62.06%" stop-color="#002414"/>
      <stop offset="74.06%" stop-color="#00143d"/>
      <stop offset="86.06%" stop-color="#2874d7"/>
      <stop offset="100%"   stop-color="#99c2ff"/>
    </linearGradient>
  </defs>
  <circle cx="12" cy="12" r="10.5" fill="url(#opxRainbow)"
          stroke="rgba(0,0,0,0.18)" stroke-width="0.6"/>
 </svg>
@@ -41,15 +41,31 @@ DEST="${1:-$ROOT/assets/ipxe}"
 WORK="$(mktemp -d)"
 trap 'rm -rf "$WORK"' EXIT
-# Pinned upstream iPXE. Rolling master is fine functionally, but a pin
+# Pinned upstream iPXE. Rolling master is fine functionally, but a pin keeps
-# keeps builds reproducible and protects against a transient master
+# builds reproducible, protects against a transient master breakage, and —
-# breakage. Bump deliberately.
+# crucially for the Docker image — busting this value invalidates the cached
 # ipxe-build layer so an "update iPXE" release actually recompiles from the
 # new upstream. Bump deliberately to a recent master commit.
 #
 # v0.6.1: ipxe/ipxe master @ 2026-06-09 (newer NIC drivers + EFI fixes;
 # mirrors iVentoy 1.0.35 "Update iPXE").
 IPXE_REPO="https://github.com/ipxe/ipxe.git"
-IPXE_REF="${IPXE_REF:-master}"
+IPXE_REF="${IPXE_REF:-95ffbf4745553e8a207922389929e1943c0237c0}"
-echo ">> cloning iPXE ($IPXE_REF)"
+echo ">> fetching iPXE ($IPXE_REF)"
-git clone --depth 1 --branch "$IPXE_REF" "$IPXE_REPO" "$WORK/ipxe" 2>/dev/null \
+# Shallow-fetch the exact ref: works for a full commit SHA (GitHub allows
-  || git clone "$IPXE_REPO" "$WORK/ipxe"
+# reachable-SHA1-in-want) and for branch/tag names. Fall back to a full
 # clone + checkout if the server refuses a direct fetch of this ref.
 git init -q "$WORK/ipxe"
 git -C "$WORK/ipxe" remote add origin "$IPXE_REPO"
 if git -C "$WORK/ipxe" fetch -q --depth 1 origin "$IPXE_REF"; then
  git -C "$WORK/ipxe" checkout -q FETCH_HEAD
 else
  echo "   direct fetch failed; falling back to full clone + checkout"
  rm -rf "$WORK/ipxe"
  git clone -q "$IPXE_REPO" "$WORK/ipxe"
  git -C "$WORK/ipxe" checkout -q "$IPXE_REF"
 fi
 SRC="$WORK/ipxe/src"
 echo ">> applying OpenPXE config overrides (PNG + framebuffer + console cmd)"
@@ -29,11 +29,19 @@ mkdir -p "$DEST"
 # Upstream uses arch-scoped subdirectories; we flatten to the names our
 # ClientArch::ipxe_bootfile() expects.
 declare -a MAP=(
  # DriverMode::Firmware (default) — reuse the firmware UNDI/SNP NIC stack.
  "undionly.kpxe=undionly.kpxe"
  "snponly.efi=x86_64-efi/snponly.efi"
  "snponly-i386.efi=i386-efi/snponly.efi"
  "snponly-arm64.efi=arm64-efi/snponly.efi"
-  "ipxe.efi=x86_64-efi/ipxe.efi"          # fallback with bundled drivers
+  # DriverMode::Builtin (v0.6.1 automatic fallback) — iPXE's own all-drivers
  # builds, advertised by the DHCP proxy to a MAC whose firmware NIC stack
  # failed to chainload. (x86_64 ipxe.efi is rebuilt from source with PNG in
  # build-ipxe.sh and overlaid on top of this fetched baseline.)
  "ipxe.efi=x86_64-efi/ipxe.efi"
  "ipxe.pxe=ipxe.pxe"
  "ipxe-i386.efi=i386-efi/ipxe.efi"
  "ipxe-arm64.efi=arm64-efi/ipxe.efi"
 )
 BASE="https://boot.ipxe.org"
@@ -0,0 +1,96 @@
 #!/usr/bin/env bash
 # Fetch Fedora's Microsoft-signed Secure Boot chain — shim + GRUB — and
 # place the EFI binaries under assets/ipxe/ with the filenames OpenPXE's
 # DriverMode::Shim mapping expects:
 #
 #   shimx64.efi    x86_64: Microsoft-signed shim (first stage)
 #   grubx64.efi    x86_64: Fedora-signed GRUB (loaded by shim, fetches
 #                  the server-rendered grub.cfg over TFTP/HTTP)
 #   shimaa64.efi   arm64 equivalents (best-effort — see below)
 #   grubaa64.efi
 #
 # Why Fedora: a supply-chain decision made deliberately (v0.7.0) — one
 # vendor, fast security turnaround, and the same chain most netboot
 # projects redistribute. The binaries are extracted from the official
 # distro RPMs and shipped BYTE-FOR-BYTE UNMODIFIED; their signatures are
 # what make the chain work, and modifying them would break it. This is
 # the standard documented netboot path for Secure Boot (Red Hat
 # Satellite, SUSE HTTPBoot) and involves no test certificates and no
 # client trust-store changes.
 #
 # Trust model matches fetch-ipxe.sh: HTTPS to the official distribution
 # point, no sha pinning because we track the latest signed build (which
 # rotates on SBAT revocations — pinning would mean shipping revoked
 # shims). Mirror to your own artifact store for deterministic builds.
 set -euo pipefail
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 DEST="${1:-$ROOT/assets/ipxe}"
 mkdir -p "$DEST"
 FEDORA_RELEASE="${FEDORA_RELEASE:-43}"
 BASE="${FEDORA_MIRROR:-https://dl.fedoraproject.org/pub/fedora/linux/releases/$FEDORA_RELEASE/Everything}"
 WORK="$(mktemp -d)"
 trap 'rm -rf "$WORK"' EXIT
 # Find the newest RPM in a repo directory whose name starts with
 # `$pattern` followed by a version digit (anchoring on the digit keeps
 # `grub2-efi-x64` from matching `grub2-efi-x64-cdboot`).
 latest_rpm() {
  local dir_url="$1" pattern="$2"
  curl -fsSL "$dir_url/" \
    | grep -oE "href=\"${pattern}-[0-9][^\"]*\.rpm\"" \
    | sed 's/^href="//; s/"$//' \
    | sort -V | tail -1
 }
 # fetch_chain <repo-arch> <shim-pkg> <grub-pkg> <shim-out> <grub-out> <hard|soft>
 fetch_chain() {
  local arch="$1" shim_pkg="$2" grub_pkg="$3" shim_out="$4" grub_out="$5" mode="$6"
  local pkg_base="$BASE/$arch/os/Packages"
  local sdir="$pkg_base/${shim_pkg:0:1}" gdir="$pkg_base/${grub_pkg:0:1}"
  local shim_rpm grub_rpm
  shim_rpm="$(latest_rpm "$sdir" "$shim_pkg" || true)"
  grub_rpm="$(latest_rpm "$gdir" "$grub_pkg" || true)"
  if [ -z "$shim_rpm" ] || [ -z "$grub_rpm" ]; then
    echo "!! could not locate $shim_pkg/$grub_pkg RPMs under $pkg_base"
    [ "$mode" = "hard" ] && exit 2
    echo "   skipping $arch Secure Boot chain (best-effort)"
    return 0
  fi
  echo ">> $arch: $shim_rpm + $grub_rpm"
  local exdir="$WORK/$arch"
  mkdir -p "$exdir"
  curl -fsSL -o "$exdir/shim.rpm" "$sdir/$shim_rpm"
  curl -fsSL -o "$exdir/grub.rpm" "$gdir/$grub_rpm"
  ( cd "$exdir" \
    && rpm2cpio shim.rpm | cpio -idm --quiet "./boot/efi/EFI/*/$shim_out" \
    && rpm2cpio grub.rpm | cpio -idm --quiet "./boot/efi/EFI/*/$grub_out" )
  local shim_path grub_path
  shim_path="$(find "$exdir/boot" -name "$shim_out" | head -1)"
  grub_path="$(find "$exdir/boot" -name "$grub_out" | head -1)"
  if [ -z "$shim_path" ] || [ -z "$grub_path" ]; then
    echo "!! RPM layout changed — $shim_out/$grub_out not found inside the packages"
    [ "$mode" = "hard" ] && exit 2
    return 0
  fi
  cp "$shim_path" "$DEST/$shim_out"
  cp "$grub_path" "$DEST/$grub_out"
  echo "   installed $shim_out + $grub_out"
 }
 # x86_64 is the headline Secure Boot audience — fail the build if it
 # can't be assembled so a regression is loud, not silent.
 fetch_chain x86_64 shim-x64 grub2-efi-x64 shimx64.efi grubx64.efi hard
 # arm64 is best-effort: skipping just means no Shim escalation rung for
 # that arch (logged at startup by ipxe-assets::log_availability).
 fetch_chain aarch64 shim-aa64 grub2-efi-aa64 shimaa64.efi grubaa64.efi soft
 echo
 echo "Secure Boot chain assets now in $DEST:"
 ls -lh "$DEST"/shim*.efi "$DEST"/grub*.efi 2>/dev/null || true
`@@ -14,4 +14,4 @@`

	`pub mod server;`	`pub mod server;`

	`pub use server::TftpServer;`	`pub use server::{DynamicAsset, TftpServer};`