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]>

Cargo.toml

@@ -12,7 +12,7 @@ members = [
 ]
 
 [workspace.package]
-version = "0.6.2"
+version = "0.8.1"
 edition = "2021"
 rust-version = "1.95"
 license = "MIT OR Apache-2.0"
@@ -33,7 +33,7 @@ dhcproto = "0.15"
 socket2 = { version = "0.6", features = ["all"] }
 bytes = "1.7"
 
-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.9"
@@ -80,10 +80,8 @@ 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"
@@ -99,24 +97,19 @@ base64 = "0.22"
 # binary via rustls + bergshamra — so SFTP adds ZERO new C/crypto deps
 # and the static-musl build stays OpenSSL-free.
 #
-# CRITICAL #2 — pinned to EXACTLY 0.55.0, the newest russh that
+# CRITICAL #2 — history: this was pinned to =0.55.0 from v0.5.5 until
-# coexists with bergshamra-crypto (our SAML core). The RustCrypto
+# v0.6.3 because bergshamra-crypto pinned release-candidate RustCrypto
-# ecosystem is mid-transition: bergshamra-crypto pins a constellation of
+# crates that conflicted with the stable generation russh 0.56+ pulls.
-# release-CANDIDATE crates (`pkcs8 =0.11.0-rc.11` and its matching
+# bergshamra 0.5 (2026-06) moved to the stable generation (pkcs8 0.11),
-# pkcs5/spki RCs) that are API-incompatible with the STABLE versions of
+# lifting the pin. v0.6.3 bumps to 0.61+, which also closes a batch of
-# the same crates in the same semver bucket. russh 0.56+ pulls those
+# RUSTSEC advisories reachable from the SFTP *client* path (unbounded
-# stable crates (`pkcs5 0.8`), which silently replaces bergshamra's RC
+# allocations in packet parsing — CVE-2026-48110/-46702/-46673 et al.)
-# copies and breaks compilation. russh ≤0.55 stays on the previous stable
+# and drops mlock on non-secret buffers (~21% SSH throughput upstream).
-# generation (`pkcs5 0.7`, `ssh-key 0.6`), which unifies with bergshamra's
-# *stable* deps and leaves the RC bucket untouched — verified to compile.
-# 0.55 still has the merged `russh::keys` API (keys merged at 0.50).
-# IMPORTANT: do NOT bump russh past 0.55 until bergshamra-crypto adopts
-# the stable RustCrypto generation; 0.56+ will not compile in this tree.
 #
 # 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.55.0", default-features = false, features = ["ring"] }
+russh = { version = "0.61", default-features = false, features = ["ring"] }
 russh-sftp = "2.3"
 
 openpxe-core = { path = "crates/core" }

README.md

@@ -65,7 +65,10 @@ OpenPXE collapses that whole stack into **one statically-linked binary in one co
   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.
+- **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** —
@@ -88,6 +91,9 @@ OpenPXE collapses that whole stack into **one statically-linked binary in one co
 - **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
 
@@ -236,6 +242,8 @@ All settings have defaults and layer **defaults → TOML (`--config` / `OPENPXE_
 | `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
 

crates/core/Cargo.toml

@@ -27,13 +27,11 @@ 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
 

crates/core/src/api_key.rs

@@ -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);
+    }
+}

crates/core/src/arch.rs

@@ -23,13 +23,21 @@ pub enum ClientArch {
     Unknown(u16),
 }
 
-/// Which iPXE network backend to advertise to a client (v0.6.1).
+/// 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 only escalates a specific MAC to
+/// stack, via `snponly`/`undionly`) and escalates a specific MAC
-/// [`DriverMode::Builtin`] (iPXE's bundled NIC drivers) automatically, when a
+/// automatically when a boot never completes its handoff:
-/// firmware-net boot fails to chainload. There is no operator toggle — the
+/// `Firmware → Builtin → Shim`. There is no operator toggle — the DHCP
-/// DHCP proxy decides per client.
+/// 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 {
@@ -40,6 +48,9 @@ pub enum DriverMode {
     /// 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 {
@@ -88,20 +99,43 @@ impl ClientArch {
             // 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 either mode. Unknown arches likewise. Return
+            // 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 {
@@ -233,6 +267,51 @@ mod tests {
         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"));

crates/core/src/boot_rules.rs

@@ -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());
+    }
+}

crates/core/src/boot_tokens.rs

@@ -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);
+    }
+}

crates/core/src/lib.rs

@@ -2,9 +2,12 @@
 //! 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;
@@ -21,9 +24,12 @@ pub mod settings;
 pub mod sso;
 pub mod wol;
 
+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};

crates/dhcp-proxy/Cargo.toml

@@ -15,7 +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"

crates/dhcp-proxy/src/escalation.rs

@@ -1,24 +1,43 @@
-//! Automatic per-MAC NIC driver-mode escalation (v0.6.1).
+//! 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. A minority
+//! firmware just proved its network works by downloading the NBP. Two
-//! of NICs have a missing or buggy firmware UNDI/SNP stack; those clients
+//! classes of machine can't run it:
-//! TFTP the binary fine, but then iPXE can't bring the link up, so the
-//! tell-tale second DHCP DISCOVER carrying the `iPXE` user-class never arrives
-//! and the machine eventually re-PXE-boots.
 //!
-//! We detect exactly that: a *fresh* firmware DISCOVER from a MAC whose
+//! * a minority of NICs have a missing or buggy firmware UNDI/SNP stack —
-//! previous firmware attempt was never confirmed by an iPXE handoff means the
+//!   they TFTP the binary fine but iPXE can't bring the link up;
-//! firmware-net build failed → escalate that MAC to [`DriverMode::Builtin`]
+//! * Secure-Boot firmware downloads it fine but refuses to *execute* an
-//! (iPXE's own NIC drivers). The decision is sticky — once a MAC settles on a
+//!   unsigned image.
-//! mode that completes the handoff, later boots go straight to it. There is no
+//!
-//! operator toggle; it just works, and the default (firmware) path is
+//! Both look identical from here: the tell-tale second DHCP DISCOVER
-//! unchanged so hardware that already boots never regresses.
+//! 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
@@ -26,13 +45,14 @@ use std::time::{Duration, Instant};
 /// DISCOVER). They must not be mistaken for a failed-and-retried boot.
 const SAME_BOOT_DEBOUNCE: Duration = Duration::from_secs(8);
 
-/// Forget a MAC's state after this long with no activity, so a transient
+/// Forget an *unpinned* MAC's state after this long with no activity, so
-/// escalation doesn't pin a client to Builtin forever and the map stays
+/// a transient mid-walk state doesn't linger and the map stays bounded.
-/// bounded over a long-running deployment.
+/// 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 — escalation is best-effort, never a memory-growth vector.
+/// 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.
@@ -49,6 +69,8 @@ struct Entry {
     /// 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,
 }
 
@@ -72,14 +94,68 @@ impl Default for Inner {
 #[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
@@ -91,28 +167,32 @@ impl DriverEscalation {
 
     /// Record that `mac` completed the iPXE handoff (a DISCOVER carrying the
     /// `iPXE` user-class). The mode we last served worked, so stop awaiting
-    /// confirmation and keep it sticky for next time.
+    /// 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| now.duration_since(e.last_seen) < ENTRY_TTL);
+                    .retain(|_, e| e.pinned || now.duration_since(e.last_seen) < ENTRY_TTL);
                 g.last_prune = now;
             }
-        // Inline staleness check: a MAC whose entry outlived the TTL starts
+            // Inline staleness check: an unpinned MAC whose entry outlived
-        // fresh even when the amortized sweep above hasn't caught it yet.
+            // 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| now.duration_since(e.last_seen) >= ENTRY_TTL)
+                .is_some_and(|e| !e.pinned && now.duration_since(e.last_seen) >= ENTRY_TTL)
             {
                 g.map.remove(mac);
             }
 
-        match g.map.get_mut(mac) {
+            let mut newly_pinned = false;
+            let mode = match g.map.get_mut(mac) {
                 None => {
                     g.map.insert(
                         mac.to_owned(),
@@ -120,6 +200,7 @@ impl DriverEscalation {
                             mode: DriverMode::Firmware,
                             // Only the primary DISCOVER opens a confirmation window.
                             awaiting_confirm: primary,
+                            pinned: false,
                             last_seen: now,
                         },
                     );
@@ -131,37 +212,105 @@ impl DriverEscalation {
                 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
+                        // A genuinely new boot. If the previous attempt was
-                    // confirmed, the firmware-net build failed → escalate to
+                        // never confirmed, the build we served failed → climb
-                    // the all-drivers build. Builtin is the most capable build
+                        // one rung: Firmware (firmware NIC stack) → Builtin
-                    // we have, so it's the single escalation target (and a MAC
+                        // (iPXE's own drivers) → Shim (signed shim+GRUB —
-                    // already on Builtin simply stays there).
+                        // 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 = DriverMode::Builtin;
+                            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();
-        if let Some(e) = g.map.get_mut(mac) {
+            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>) {
-    if let Some(oldest) = map
+    // Prefer evicting an unpinned entry; only touch learned modes when
-        .iter()
+    // 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);
     }
 }
@@ -169,6 +318,7 @@ fn evict_oldest(map: &mut HashMap<String, Entry>) {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use tempfile::tempdir;
 
     #[test]
     fn firmware_first_then_escalates_on_unconfirmed_retry() {
@@ -222,7 +372,30 @@ mod tests {
     }
 
     #[test]
-    fn stale_entry_is_forgotten_and_resets_to_firmware() {
+    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);
@@ -230,8 +403,92 @@ mod tests {
             e.decide_at("dd", true, t0 + Duration::from_mins(1)),
             DriverMode::Builtin
         );
-        // After the TTL with no activity the entry is pruned → fresh firmware.
+        // 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());
+    }
 }

crates/dhcp-proxy/src/reply.rs

@@ -49,10 +49,13 @@ 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 => {
@@ -60,9 +63,12 @@ pub fn decide(ctx: &ReplyContext<'_>) -> BootDirective {
             // pointing at an EFI executable. We serve the iPXE EFI build for
             // the negotiated driver mode over HTTP; it'll then do the same
             // 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
-                .ipxe_bootfile_mode(ctx.driver_mode)
+                .bootfile_with_fallback(ctx.driver_mode)
                 .unwrap_or("snponly.efi");
             BootDirective::HttpScript {
                 url: format!(
@@ -72,7 +78,7 @@ pub fn decide(ctx: &ReplyContext<'_>) -> BootDirective {
                 ),
             }
         }
-        FirmwareClass::PxeClient => match ctx.arch.ipxe_bootfile_mode(ctx.driver_mode) {
+        FirmwareClass::PxeClient => match ctx.arch.bootfile_with_fallback(ctx.driver_mode) {
             Some(name) => BootDirective::TftpIpxe {
                 filename: name.to_string(),
             },

crates/dhcp-proxy/src/server.rs

@@ -5,7 +5,9 @@ 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, DriverMode, 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;
@@ -19,12 +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). Shared across
+    /// Automatic per-MAC NIC driver-mode escalation (v0.6.1; persistent
-    /// the :67 and :4011 listener tasks via the server `Arc`.
+    /// 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,
@@ -33,6 +42,8 @@ impl DhcpProxyServer {
         public_base_url: String,
         clients: Arc<ClientRegistry>,
         metrics: openpxe_core::Metrics,
+        escalation: DriverEscalation,
+        rules: BootRulesStore,
     ) -> Self {
         Self {
             bind,
@@ -42,7 +53,8 @@ impl DhcpProxyServer {
             public_base_url,
             clients,
             metrics,
-            escalation: DriverEscalation::new(),
+            escalation,
+            rules,
         }
     }
 
@@ -142,9 +154,17 @@ impl DhcpProxyServer {
                 self.escalation.mark_ipxe_success(&mac);
                 DriverMode::Firmware // unused: this path serves the HTTP script
             }
-            FirmwareClass::PxeClient | FirmwareClass::HttpClient => self
+            FirmwareClass::PxeClient | FirmwareClass::HttpClient => {
-                .escalation
+                // v0.7.1: an operator rule pin wins over (and bypasses)
-                .mode_for_firmware_attempt(&mac, label == "67"),
+                // 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,
         };

crates/http-api/Cargo.toml

@@ -25,11 +25,9 @@ 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
@@ -49,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

crates/http-api/src/app.rs

@@ -19,7 +19,6 @@ use crate::ipxe_script::{
     render_entry, render_family_menu, render_local_hdd, render_menu, render_nic_info,
     render_queue_entry, render_shell, render_tools_menu, render_util,
 };
-use crate::iso_fs;
 use crate::log_stream;
 use crate::state::AppState;
 use crate::terminal;
@@ -36,6 +35,7 @@ use openpxe_core::{
     LogoSlot, NotifyConfig, Settings, SsoConfig, ALLOWED_LOGO_MIMES, MAX_LOGO_BYTES,
 };
 use openpxe_ipxe_assets::asset_slice;
+use openpxe_iso_store::iso_fs;
 use openpxe_iso_store::{
     render_template, IsoCategory, IsoMeta, IsoSource, NfsAddRequest, SftpAddRequest, SmbAddRequest,
     SmbState, UnattendedKind, UnattendedMeta,
@@ -71,7 +71,7 @@ pub fn build_router(state: AppState) -> Router {
         .route("/branding/pxe-logo", get(ui_pxe_logo))
         // iPXE script endpoints.
         .route("/boot.ipxe", get(boot_top_menu))
-        .route("/boot/:filename", get(boot_sub))
+        .route("/boot/{filename}", get(boot_sub))
         // v0.5.2: unattended answer-file *serving* — public (like /iso),
         // because the booting installer fetches these with no session.
         // `/unattended/:id` serves a Kickstart/Preseed with `{{HOSTNAME}}`
@@ -80,12 +80,12 @@ pub fn build_router(state: AppState) -> Router {
         // autoinstall (`…/<ctx>/user-data` + `/meta-data`), where `<ctx>`
         // base64url-encodes the per-host hostname/ip/mac. Management
         // (upload/list/delete) lives under the gated `/api/unattended`.
-        .route("/unattended/:id", get(serve_unattended))
+        .route("/unattended/{id}", get(serve_unattended))
-        .route("/unattended/:id/:ctx/:sub", get(serve_unattended_seed))
+        .route("/unattended/{id}/{ctx}/{sub}", get(serve_unattended_seed))
         // Bundled binaries and raw ISO access.
-        .route("/ipxe/:name", get(ipxe_binary))
+        .route("/ipxe/{name}", get(ipxe_binary))
-        .route("/iso/:filename", get(iso_raw))
+        .route("/iso/{filename}", get(iso_raw))
-        .route("/iso/:id/*path", get(iso_file))
+        .route("/iso/{id}/{*path}", get(iso_file))
         // Container health/readiness probes. `/healthz` is always 200 OK
         // while the HTTP task is alive. `/readyz` additionally requires at
         // least one bundled iPXE binary (without one, no client can PXE).
@@ -93,23 +93,34 @@ pub fn build_router(state: AppState) -> Router {
         .route("/readyz", get(readyz))
         // JSON API.
         .route("/api/isos", get(api_list_isos).post(api_upload_iso))
-        .route("/api/isos/:id", delete(api_delete_iso))
+        .route("/api/isos/{id}", delete(api_delete_iso))
+        // v0.8.1: add ISO by URL — server-side streaming download + progress
+        // polling. Static `fetch` coexists with `{id}` above (matchit
+        // prioritizes the literal), same as `/api/queue/join` vs `{entry_id}`.
+        .route(
+            "/api/isos/fetch",
+            get(crate::fetch::api_iso_fetch_list).post(crate::fetch::api_iso_fetch_start),
+        )
+        .route(
+            "/api/isos/fetch/{id}",
+            delete(crate::fetch::api_iso_fetch_cancel),
+        )
         .route("/api/uploads", post(api_upload_begin))
         .route(
-            "/api/uploads/:upload_id",
+            "/api/uploads/{upload_id}",
             put(api_upload_chunk).delete(api_upload_abort),
         )
         // Per-ISO password prompt. PUT body `{ "password": "..." }`
         // sets, `{ "password": null }` (or DELETE) clears.
         .route(
-            "/api/isos/:id/password",
+            "/api/isos/{id}/password",
             axum::routing::put(api_set_iso_password).delete(api_clear_iso_password),
         )
         // v0.4.4: per-ISO menu category (Os / Tools). Drives whether the
         // image appears under Linux/Windows Installers (default) or in
         // the Tools submenu next to memtest / shell / NIC info.
         .route(
-            "/api/isos/:id/category",
+            "/api/isos/{id}/category",
             axum::routing::put(api_set_iso_category),
         )
         // v0.4.4: filesystem free-space telemetry for the ISO directory's
@@ -120,7 +131,7 @@ pub fn build_router(state: AppState) -> Router {
         // logo). v0.5.2: split into three slots — `light` / `dark` /
         // `client`. Multipart upload to POST; DELETE clears one slot.
         .route(
-            "/api/branding/logo/:slot",
+            "/api/branding/logo/{slot}",
             post(api_branding_upload).delete(api_branding_clear),
         )
         // v0.5.2: unattended-install answer-file management (gated).
@@ -130,7 +141,7 @@ pub fn build_router(state: AppState) -> Router {
             "/api/unattended",
             get(api_unattended_list).post(api_unattended_upload),
         )
-        .route("/api/unattended/:id", delete(api_unattended_delete))
+        .route("/api/unattended/{id}", delete(api_unattended_delete))
         // v0.4.4: self-rendered API reference, served as JSON so the UI
         // can format it consistently with the rest of the chrome. Lives
         // under the Settings tab — operators chasing an integration get
@@ -147,6 +158,14 @@ pub fn build_router(state: AppState) -> Router {
         .route("/api/logout", post(auth_api::api_logout))
         .route("/api/me", get(auth_api::api_me))
         .route("/api/me/credentials", put(auth_api::api_update_credentials))
+        // v0.8.0: operator API key surface (read current + regenerate).
+        // Gated by require_auth like the rest of /api/*; a logged-in
+        // operator or an x-api-key holder can read/rotate it.
+        .route("/api/api-key", get(auth_api::api_api_key_get))
+        .route(
+            "/api/api-key/regenerate",
+            post(auth_api::api_api_key_regenerate),
+        )
         // SAML SSO configuration (FleetDM-shaped). Gated behind auth — the
         // operator pastes their IdP metadata, Entity ID, and toggles here.
         .route("/api/sso", get(api_sso_get).put(api_sso_put))
@@ -161,12 +180,12 @@ pub fn build_router(state: AppState) -> Router {
         .route("/api/settings", get(api_get_settings).put(api_put_settings))
         .route("/api/queue", get(api_list_queue))
         .route("/api/queue/join", get(api_queue_join))
-        .route("/api/queue/poll/:entry_id", get(api_queue_poll))
+        .route("/api/queue/poll/{entry_id}", get(api_queue_poll))
         .route("/api/queue/assign", post(api_queue_assign))
         // v0.5.2: per-device deployment profile (auto hostname / IP /
         // unattended file) set from the queue "Profile" button.
-        .route("/api/queue/:entry_id/profile", put(api_queue_set_profile))
+        .route("/api/queue/{entry_id}/profile", put(api_queue_set_profile))
-        .route("/api/queue/:entry_id", delete(api_queue_release))
+        .route("/api/queue/{entry_id}", delete(api_queue_release))
         // v0.4.65: SMB share manager (userspace via smbclient). The
         // kernel-mount NFS routes that v0.4.64 shipped are gone — they
         // didn't work on hosts whose kernel lacked the nfs client
@@ -177,8 +196,8 @@ pub fn build_router(state: AppState) -> Router {
             "/api/smb-shares",
             get(api_smb_shares_list).post(api_smb_shares_add),
         )
-        .route("/api/smb-shares/:id", delete(api_smb_shares_remove))
+        .route("/api/smb-shares/{id}", delete(api_smb_shares_remove))
-        .route("/api/smb-shares/:id/scan", post(api_smb_shares_scan))
+        .route("/api/smb-shares/{id}/scan", post(api_smb_shares_scan))
         // v0.4.67: NFSv3 share manager (pure-Rust in-process client).
         // Ships alongside SMB. Routes are parallel so the UI can
         // reuse the same form/error/hint rendering for both.
@@ -186,8 +205,8 @@ pub fn build_router(state: AppState) -> Router {
             "/api/nfs-shares",
             get(api_nfs_shares_list).post(api_nfs_shares_add),
         )
-        .route("/api/nfs-shares/:id", delete(api_nfs_shares_remove))
+        .route("/api/nfs-shares/{id}", delete(api_nfs_shares_remove))
-        .route("/api/nfs-shares/:id/scan", post(api_nfs_shares_scan))
+        .route("/api/nfs-shares/{id}/scan", post(api_nfs_shares_scan))
         // v0.5.5: SFTP-over-SSH share manager (pure-Rust russh client).
         // Parallel to SMB/NFS so the UI reuses the same form/error/hint
         // rendering. Like NFS, SFTP-sourced ISOs support Range requests.
@@ -195,8 +214,8 @@ pub fn build_router(state: AppState) -> Router {
             "/api/sftp-shares",
             get(api_sftp_shares_list).post(api_sftp_shares_add),
         )
-        .route("/api/sftp-shares/:id", delete(api_sftp_shares_remove))
+        .route("/api/sftp-shares/{id}", delete(api_sftp_shares_remove))
-        .route("/api/sftp-shares/:id/scan", post(api_sftp_shares_scan))
+        .route("/api/sftp-shares/{id}/scan", post(api_sftp_shares_scan))
         // Phase 4: Network info (read-only) + DNS edit.
         .route("/api/network", get(api_network).put(api_network_put))
         // Phase 4: live-log stream + recent buffer for the Terminal tab.
@@ -208,10 +227,17 @@ pub fn build_router(state: AppState) -> Router {
         // Phase 5: per-MAC host bindings. Operator
         // pins a MAC to a boot entry; /boot.ipxe?mac=... chains directly.
         .route("/api/hosts", get(api_hosts_list).post(api_hosts_upsert))
-        .route("/api/hosts/:mac", delete(api_hosts_remove))
+        .route("/api/hosts/{mac}", delete(api_hosts_remove))
         // v0.5.0: Wake-on-LAN a bound host. Sends a magic packet to the
         // limited broadcast + the server's own subnet broadcast.
-        .route("/api/hosts/:mac/wol", post(api_hosts_wol))
+        .route("/api/hosts/{mac}/wol", post(api_hosts_wol))
+        // v0.7.0: ordered boot rules (MAC prefix / arch → target) + the
+        // boot-decision webhook. The UI saves the whole config at once
+        // because rule order is significant.
+        .route(
+            "/api/boot-rules",
+            get(api_boot_rules_get).put(api_boot_rules_put),
+        )
         // Rolling "host log" of boot events: what image actually
         // started installing on what MAC/IP, and when. Persisted to disk.
         .route("/api/boot-log", get(api_boot_log))
@@ -520,14 +546,15 @@ fn text_plain(body: String) -> Response {
 /// to the bound target instead of rendering the menu.
 async fn boot_top_menu(
     State(state): State<AppState>,
-    peer: Option<ConnectInfo<SocketAddr>>,
+    peer: Result<ConnectInfo<SocketAddr>, axum::extract::rejection::ExtensionRejection>,
     Query(p): Query<BootMenuParams>,
 ) -> Response {
     // `ConnectInfo` is only populated when axum was started with
     // `into_make_service_with_connect_info` (production path). Tests
     // call the router via `oneshot`, which skips that wiring — we
     // tolerate it by treating the peer as unknown rather than 500ing.
-    let peer_ip = peer.map(|c| c.0.ip());
+    // (axum 0.8: `Result<T, Rejection>` is the optional-extractor form.)
+    let peer_ip = peer.ok().map(|c| c.0.ip());
     state
         .metrics
         .record_http(openpxe_core::HttpRoute::BootScript);
@@ -569,17 +596,105 @@ async fn boot_top_menu(
             // `?mac=` so the per-entry handler can record the boot into
             // the Host log without depending on iPXE substitution at
             // this stage.
-            return text_plain(format!(
+            return text_plain(chain_script(base, &target, &bound_mac, "per-MAC binding"));
-                "#!ipxe\n\
+        }
-                 echo OpenPXE: per-MAC binding -> {target}\n\
+
-                 chain {base}/boot/{target}.ipxe?mac={bound_mac} || chain {base}/boot.ipxe\n"
+        // v0.7.0 step 2: ordered boot rules (MAC prefix / arch).
-            ));
+        let mac_norm = openpxe_core::normalize_mac(mac);
+        if let Some(target) = state.boot_rules.match_target(&mac_norm, p.arch.as_deref()) {
+            tracing::info!(
+                target: "openpxe::http",
+                mac = %mac_norm, target = %target, "boot rule matched"
+            );
+            record_pre_boot(&state, &isos, &mac_norm, peer_ip, &target);
+            return text_plain(chain_script(base, &target, &mac_norm, "boot rule"));
+        }
+
+        // v0.7.0 step 3: boot-decision webhook (fail-open — any error,
+        // timeout, or non-200 falls through to the menu so a dead
+        // automation endpoint can never block PXE for the network).
+        if let Some(url) = state.boot_rules.webhook_url() {
+            if let Some(target) = webhook_decide(&url, &mac_norm, p.arch.as_deref()).await {
+                tracing::info!(
+                    target: "openpxe::http",
+                    mac = %mac_norm, target = %target, "boot webhook decided"
+                );
+                record_pre_boot(&state, &isos, &mac_norm, peer_ip, &target);
+                return text_plain(chain_script(base, &target, &mac_norm, "boot webhook"));
+            }
         }
     }
 
     text_plain(render_menu(&isos, &settings, base))
 }
 
+/// The short-circuit script all three decision sources (binding, rule,
+/// webhook) emit: chain to the target's boot script, falling back to the
+/// interactive menu so a stale target can't lock a client out.
+fn chain_script(base: &str, target: &str, mac: &str, source: &str) -> String {
+    format!(
+        "#!ipxe\n\
+         echo OpenPXE: {source} -> {target}\n\
+         chain {base}/boot/{target}.ipxe?mac={mac} || chain {base}/boot.ipxe\n"
+    )
+}
+
+/// Pre-record a decision-driven boot into the Host log, mirroring what
+/// the per-MAC binding path does: reserved `_xxx` targets are operator
+/// conveniences, not imaging events, so they're skipped.
+fn record_pre_boot(
+    state: &AppState,
+    isos: &[openpxe_iso_store::IsoMeta],
+    mac: &str,
+    peer_ip: Option<std::net::IpAddr>,
+    target: &str,
+) {
+    if target.starts_with('_') {
+        return;
+    }
+    let title = lookup_entry_title(isos, target);
+    state.boot_log.record(&BootEvent {
+        timestamp: time::OffsetDateTime::now_utc(),
+        mac: Some(mac.to_string()),
+        ip: peer_ip,
+        target_id: target.to_string(),
+        target_title: title,
+    });
+}
+
+/// Ask the operator's boot-decision webhook for a target. `200` with
+/// `{"target": "<id>"}` chains to that target; anything else (including
+/// an empty target) means "no opinion". Two-second budget — a booting
+/// machine is sitting at a black screen while this runs.
+async fn webhook_decide(url: &str, mac: &str, arch: Option<&str>) -> Option<String> {
+    #[derive(Deserialize)]
+    struct Decision {
+        target: String,
+    }
+    let client = reqwest::Client::builder()
+        .timeout(std::time::Duration::from_secs(2))
+        .build()
+        .ok()?;
+    let resp = match client
+        .get(url)
+        .query(&[("mac", mac), ("arch", arch.unwrap_or(""))])
+        .send()
+        .await
+    {
+        Ok(r) => r,
+        Err(e) => {
+            tracing::warn!(target: "openpxe::http", "boot webhook unreachable: {e}");
+            return None;
+        }
+    };
+    if !resp.status().is_success() {
+        return None;
+    }
+    let d: Decision = resp.json().await.ok()?;
+    let t = d.target.trim().to_string();
+    (!t.is_empty()).then_some(t)
+}
+
 /// Best-effort human title for a boot entry id — falls back to the id
 /// itself if the ISO has been deleted between record-time and now.
 fn lookup_entry_title(isos: &[openpxe_iso_store::IsoMeta], target_id: &str) -> String {
@@ -602,6 +717,11 @@ struct BootMenuParams {
     /// `chain ${prefix}/boot.ipxe?mac=${mac}`. Optional — if absent we
     /// fall back to the menu unconditionally.
     mac: Option<String>,
+    /// v0.7.0: client architecture (`ClientArch::as_str()` form), baked
+    /// literally into the chain URL by the DHCP proxy, which knows it
+    /// from option 93. Lets boot rules select on architecture. Absent on
+    /// chains rendered by older binaries — arch rules simply don't match.
+    arch: Option<String>,
 }
 
 #[derive(Debug, Deserialize)]
@@ -619,11 +739,12 @@ struct BootSubParams {
 
 async fn boot_sub(
     State(state): State<AppState>,
-    peer: Option<ConnectInfo<SocketAddr>>,
+    peer: Result<ConnectInfo<SocketAddr>, axum::extract::rejection::ExtensionRejection>,
     AxumPath(filename): AxumPath<String>,
     Query(p): Query<BootSubParams>,
 ) -> Response {
-    let peer_ip = peer.map(|c| c.0.ip());
+    // axum 0.8: `Result<T, Rejection>` is the optional-extractor form.
+    let peer_ip = peer.ok().map(|c| c.0.ip());
     // `/boot/<name>.ipxe` where `<name>` is either one of our reserved
     // submenu names (prefixed `_`) or a boot entry id.
     let name = filename.strip_suffix(".ipxe").unwrap_or(&filename);
@@ -748,7 +869,13 @@ async fn boot_sub(
                                     .as_deref()
                                     .and_then(|fid| state.unattended.get(fid))
                                     .and_then(|meta| {
-                                        build_unattended_args(base, &meta, Some(m), &p)
+                                        build_unattended_args(
+                                            base,
+                                            &meta,
+                                            Some(m),
+                                            &p,
+                                            &state.boot_tokens,
+                                        )
                                     })
                             })
                         });
@@ -769,10 +896,19 @@ async fn boot_sub(
 
 // ─── bundled iPXE binaries (memtest lives here too) ───────────────────────
 
-async fn ipxe_binary(AxumPath(name): AxumPath<String>) -> Response {
+async fn ipxe_binary(State(state): State<AppState>, AxumPath(name): AxumPath<String>) -> Response {
     if name.contains('/') || name.contains('\\') {
         return (StatusCode::BAD_REQUEST, "invalid name").into_response();
     }
+    // v0.7.0: when the whole Secure Boot chain rides HTTP (native UEFI
+    // HTTP Boot), GRUB resolves `$prefix` to this directory and fetches
+    // its config from here — rendered live, same as the TFTP path.
+    if name == "grub.cfg" || name.starts_with("grub.cfg-") {
+        return text_plain(crate::grub_script::render_grub_menu(
+            &state.iso_store.list(),
+            &state.public_base_url,
+        ));
+    }
     let Some(data) = asset_slice(&name) else {
         return (StatusCode::NOT_FOUND, "no such ipxe asset").into_response();
     };
@@ -970,16 +1106,17 @@ async fn iso_file(
     State(state): State<AppState>,
     AxumPath((id, path)): AxumPath<(String, String)>,
 ) -> Response {
-    // In-ISO file extraction is only supported for local ISOs — it
+    let Some(meta) = state.iso_store.get(&id) else {
-    // needs random-access reads into the ISO9660 directory tree, which
+        return (StatusCode::NOT_FOUND, "no such iso").into_response();
-    // smbclient's whole-file streaming can't do efficiently. SMB-
+    };
-    // sourced ISOs use the raw streaming endpoint above instead.
+    let in_path = format!("/{path}");
-    let Some(iso_path) = state.iso_store.iso_path_for(&id) else {
+    match &meta.source {
+        IsoSource::Local => {
+            let Some(iso_path) = state.iso_store.local_path(&meta) else {
                 return (StatusCode::NOT_FOUND, "no such iso").into_response();
             };
             let p = iso_path.clone();
-    let in_path = format!("/{path}");
+            let loc = tokio::task::spawn_blocking(move || iso_fs::lookup_local(&p, &in_path))
-    let loc = tokio::task::spawn_blocking(move || iso_fs::lookup(&p, &in_path))
                 .await
                 .ok()
                 .flatten();
@@ -990,6 +1127,82 @@ async fn iso_file(
                 Ok(r) => r,
                 Err(e) => (StatusCode::INTERNAL_SERVER_ERROR, format!("{e}")).into_response(),
             }
+        }
+        // v0.7.4: remote ISOs serve in-ISO files too — the same ISO9660
+        // walk runs over NFS READ3 / SFTP seek-reads, then the located
+        // byte range streams through the share manager. This is what
+        // makes the verified kernel/initrd boot entries on share-hosted
+        // Linux ISOs actually bootable.
+        IsoSource::Nfs {
+            share_id,
+            relative_path,
+        } => {
+            match state
+                .nfs_shares
+                .locate_in_iso(share_id, relative_path, &in_path)
+                .await
+            {
+                Ok(Some(loc)) => {
+                    match state
+                        .nfs_shares
+                        .stream_iso(share_id, relative_path, loc.offset, Some(loc.length))
+                        .await
+                    {
+                        Ok(stream) => in_iso_stream_response(Body::from_stream(stream), loc.length),
+                        Err(e) => {
+                            (StatusCode::BAD_GATEWAY, format!("nfs stream: {e}")).into_response()
+                        }
+                    }
+                }
+                Ok(None) => (StatusCode::NOT_FOUND, "not found inside iso").into_response(),
+                Err(e) => (StatusCode::BAD_GATEWAY, format!("nfs lookup: {e}")).into_response(),
+            }
+        }
+        IsoSource::Sftp {
+            share_id,
+            relative_path,
+        } => {
+            match state
+                .sftp_shares
+                .locate_in_iso(share_id, relative_path, &in_path)
+                .await
+            {
+                Ok(Some(loc)) => {
+                    match state
+                        .sftp_shares
+                        .stream_iso(share_id, relative_path, loc.offset, Some(loc.length))
+                        .await
+                    {
+                        Ok(stream) => in_iso_stream_response(Body::from_stream(stream), loc.length),
+                        Err(e) => {
+                            (StatusCode::BAD_GATEWAY, format!("sftp stream: {e}")).into_response()
+                        }
+                    }
+                }
+                Ok(None) => (StatusCode::NOT_FOUND, "not found inside iso").into_response(),
+                Err(e) => (StatusCode::BAD_GATEWAY, format!("sftp lookup: {e}")).into_response(),
+            }
+        }
+        // smbclient streams sequentially — no seeks, no ISO9660 walk.
+        // SMB ISOs never emit kernel entries, so nothing requests this.
+        IsoSource::Smb { .. } => (
+            StatusCode::NOT_FOUND,
+            "in-ISO files are not available for SMB-sourced ISOs",
+        )
+            .into_response(),
+    }
+}
+
+/// 200 response wrapping an in-ISO byte-range stream from a share
+/// manager. Content-Length is the located file's length — the stream is
+/// already bounded to exactly that range.
+fn in_iso_stream_response(body: Body, length: u64) -> Response {
+    Response::builder()
+        .status(StatusCode::OK)
+        .header(header::CONTENT_TYPE, "application/octet-stream")
+        .header(header::CONTENT_LENGTH, length)
+        .body(body)
+        .unwrap()
 }
 
 async fn stream_file_range(
@@ -1380,17 +1593,54 @@ struct UnattendedServeQuery {
     hostname: Option<String>,
     #[serde(default)]
     ip: Option<String>,
+    /// v0.7.0: short-lived access token minted into the generated URL.
+    #[serde(default)]
+    t: Option<String>,
 }
 
-/// Public: serve a Kickstart/Preseed/answer file with `{{HOSTNAME}}` /
+/// v0.7.0: answer files routinely embed credentials, so once an admin
+/// account exists they're only served to (a) the boot that the URL was
+/// minted for — proven by the token OpenPXE put in that URL — or (b) a
+/// logged-in operator (browser testing). Pre-setup installs stay open,
+/// matching the auth middleware's bootstrap behavior.
+fn unattended_access_allowed(
+    state: &AppState,
+    headers: &HeaderMap,
+    token: Option<&str>,
+    file_id: &str,
+) -> bool {
+    if !state.admin.is_configured() {
+        return true;
+    }
+    if token.is_some_and(|t| state.boot_tokens.check(t, file_id)) {
+        return true;
+    }
+    crate::auth::session_authenticated(state, headers)
+}
+
+fn unattended_denied() -> Response {
+    (
+        StatusCode::UNAUTHORIZED,
+        "answer files require the boot-scoped token OpenPXE mints into \
+         generated URLs (or an operator session)",
+    )
+        .into_response()
+}
+
+/// Serve a Kickstart/Preseed/answer file with `{{HOSTNAME}}` /
 /// `{{IP}}` / `{{MAC}}` substituted from the query string. Returns
 /// `text/plain` so installers (anaconda, debian-installer, Windows setup
-/// fetching over HTTP) read it verbatim.
+/// fetching over HTTP) read it verbatim. Token-gated since v0.7.0 — see
+/// [`unattended_access_allowed`].
 async fn serve_unattended(
     State(state): State<AppState>,
     AxumPath(id): AxumPath<String>,
+    headers: HeaderMap,
     Query(q): Query<UnattendedServeQuery>,
 ) -> Response {
+    if !unattended_access_allowed(&state, &headers, q.t.as_deref(), &id) {
+        return unattended_denied();
+    }
     let Ok(bytes) = state.unattended.read(&id).await else {
         return (StatusCode::NOT_FOUND, "no such unattended file").into_response();
     };
@@ -1412,8 +1662,15 @@ async fn serve_unattended(
 async fn serve_unattended_seed(
     State(state): State<AppState>,
     AxumPath((id, ctx, sub)): AxumPath<(String, String, String)>,
+    headers: HeaderMap,
 ) -> Response {
-    let (mac, hostname, ip) = decode_seed_ctx(&ctx);
+    let (mac, hostname, ip, token) = decode_seed_ctx(&ctx);
+    // v0.7.0: the seed ctx carries the access token (the seedfrom URL
+    // can't take a query string). Same gate as the flat answer-file
+    // route — see `unattended_access_allowed`.
+    if !unattended_access_allowed(&state, &headers, token.as_deref(), &id) {
+        return unattended_denied();
+    }
     match sub.as_str() {
         "user-data" => {
             let Ok(bytes) = state.unattended.read(&id).await else {
@@ -1437,6 +1694,22 @@ async fn serve_unattended_seed(
     }
 }
 
+// ─── Boot rules (v0.7.0) ───────────────────────────────────────────────────
+
+async fn api_boot_rules_get(State(state): State<AppState>) -> Json<openpxe_core::BootRulesConfig> {
+    Json(state.boot_rules.snapshot())
+}
+
+async fn api_boot_rules_put(
+    State(state): State<AppState>,
+    Json(cfg): Json<openpxe_core::BootRulesConfig>,
+) -> StatusCode {
+    let n = cfg.rules.len();
+    state.boot_rules.replace(cfg);
+    tracing::info!(target: "openpxe::http", rules = n, "boot rules replaced");
+    StatusCode::NO_CONTENT
+}
+
 /// Resolve the deployment profile for a booting MAC: a host pin wins, else
 /// a queued device's Profile. `None` when neither carries one.
 fn resolve_profile(state: &AppState, mac: &str) -> Option<DeployProfile> {
@@ -1456,12 +1729,23 @@ fn build_unattended_args(
     meta: &UnattendedMeta,
     mac: Option<&str>,
     profile: &DeployProfile,
+    tokens: &openpxe_core::BootTokens,
 ) -> Option<String> {
     let base = base.trim_end_matches('/');
     let id = &meta.id;
     let host = profile.auto_hostname.as_deref();
     let ip = profile.auto_ip.as_deref();
-    let query = build_query(&[("mac", mac), ("hostname", host), ("ip", ip)]);
+    // v0.7.0: every generated answer-file URL carries a fresh boot-scoped
+    // token; the serving endpoint requires it. See `crate::auth` and
+    // `openpxe_core::boot_tokens` for the threat model (CVE-2026-0386-
+    // style credential harvesting from openly-served answer files).
+    let token = tokens.mint(id);
+    let query = build_query(&[
+        ("mac", mac),
+        ("hostname", host),
+        ("ip", ip),
+        ("t", Some(&token)),
+    ]);
     match meta.kind {
         UnattendedKind::Kickstart => Some(format!("inst.ks={base}/unattended/{id}{query}")),
         UnattendedKind::Preseed => {
@@ -1473,7 +1757,7 @@ fn build_unattended_args(
             Some(s)
         }
         UnattendedKind::Autoinstall => {
-            let ctx = encode_seed_ctx(mac, host, ip);
+            let ctx = encode_seed_ctx(mac, host, ip, &token);
             Some(format!(
                 "autoinstall ds=nocloud-net;s={base}/unattended/{id}/{ctx}/"
             ))
@@ -1498,12 +1782,19 @@ fn build_query(pairs: &[(&str, Option<&str>)]) -> String {
 
 // `pct_encode` lives in `openpxe_core::encoding` (v0.5.4) — imported above.
 
-/// Encode `(hostname, ip, mac)` into a single base64url path segment for
+/// Encode `(hostname, ip, mac, token)` into a single base64url path
-/// the cloud-init seed directory. Empty values become empty fields.
+/// segment for the cloud-init seed directory. Empty values become empty
-fn encode_seed_ctx(mac: Option<&str>, hostname: Option<&str>, ip: Option<&str>) -> String {
+/// fields. The access token rides in here (v0.7.0) because the
+/// `seedfrom` URL can't carry a query string.
+fn encode_seed_ctx(
+    mac: Option<&str>,
+    hostname: Option<&str>,
+    ip: Option<&str>,
+    token: &str,
+) -> String {
     use base64::Engine as _;
     let raw = format!(
-        "{}\n{}\n{}",
+        "{}\n{}\n{}\n{token}",
         hostname.unwrap_or(""),
         ip.unwrap_or(""),
         mac.unwrap_or("")
@@ -1511,21 +1802,30 @@ fn encode_seed_ctx(mac: Option<&str>, hostname: Option<&str>, ip: Option<&str>)
     base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(raw.as_bytes())
 }
 
-/// Inverse of [`encode_seed_ctx`]; returns `(mac, hostname, ip)`. A bad
+/// Inverse of [`encode_seed_ctx`]; returns `(mac, hostname, ip, token)`.
-/// or empty segment yields all-`None` so the seed still serves (just
+/// A bad or empty segment yields all-`None`; a pre-v0.7.0 three-field
-/// without per-host substitution).
+/// ctx decodes with `token: None` (and the gate then rejects it once an
-fn decode_seed_ctx(ctx: &str) -> (Option<String>, Option<String>, Option<String>) {
+/// admin exists — stale URLs are exactly what tokens invalidate).
+fn decode_seed_ctx(
+    ctx: &str,
+) -> (
+    Option<String>,
+    Option<String>,
+    Option<String>,
+    Option<String>,
+) {
     use base64::Engine as _;
     let Ok(bytes) = base64::engine::general_purpose::URL_SAFE_NO_PAD.decode(ctx.as_bytes()) else {
-        return (None, None, None);
+        return (None, None, None, None);
     };
     let s = String::from_utf8_lossy(&bytes).into_owned();
-    let mut it = s.splitn(3, '\n');
+    let mut it = s.splitn(4, '\n');
     let clean = |v: Option<&str>| v.map(str::to_string).filter(|x| !x.is_empty());
     let hostname = clean(it.next());
     let ip = clean(it.next());
     let mac = clean(it.next());
-    (mac, hostname, ip)
+    let token = clean(it.next());
+    (mac, hostname, ip, token)
 }
 
 // ─── API reference (Settings → bottom) ────────────────────────────────────
@@ -1560,14 +1860,20 @@ async fn api_docs() -> Json<serde_json::Value> {
                      "summary": "List ISOs (local + NFS) with size, family, boot entries, category."},
                     {"method": "POST", "path": "/api/isos",
                      "summary": "Legacy single-shot multipart upload. Prefer /api/uploads for big files."},
-                    {"method": "DELETE", "path": "/api/isos/:id",
+                    {"method": "DELETE", "path": "/api/isos/{id}",
                      "summary": "Delete a local ISO and its sidecar metadata."},
-                    {"method": "PUT", "path": "/api/isos/:id/password",
+                    {"method": "PUT", "path": "/api/isos/{id}/password",
                      "summary": "Set or update an ISO's boot password (bcrypt-hashed; plaintext never stored)."},
-                    {"method": "DELETE", "path": "/api/isos/:id/password",
+                    {"method": "DELETE", "path": "/api/isos/{id}/password",
                      "summary": "Clear an ISO's boot password."},
-                    {"method": "PUT", "path": "/api/isos/:id/category",
+                    {"method": "PUT", "path": "/api/isos/{id}/category",
                      "summary": "Set the menu category. Body: { \"category\": \"os\" | \"tools\" }."},
+                    {"method": "POST", "path": "/api/isos/fetch",
+                     "summary": "Add an ISO by URL. Body: { \"url\", \"filename\"? }. The server streams the .iso into storage and introspects it. Returns { fetch_id }."},
+                    {"method": "GET", "path": "/api/isos/fetch",
+                     "summary": "Poll URL-fetch progress — [{ id, filename, url, downloaded, total, state }]. Completed jobs are returned once."},
+                    {"method": "DELETE", "path": "/api/isos/fetch/{id}",
+                     "summary": "Cancel an in-flight URL fetch, or dismiss a finished/failed one."},
                 ],
             },
             {
@@ -1575,9 +1881,9 @@ async fn api_docs() -> Json<serde_json::Value> {
                 "endpoints": [
                     {"method": "POST", "path": "/api/uploads",
                      "summary": "Begin a chunked upload session. Body: { \"filename\", \"size_bytes\" }."},
-                    {"method": "PUT", "path": "/api/uploads/:upload_id",
+                    {"method": "PUT", "path": "/api/uploads/{upload_id}",
                      "summary": "Append a chunk. Headers: x-openpxe-upload-offset, x-openpxe-upload-complete."},
-                    {"method": "DELETE", "path": "/api/uploads/:upload_id",
+                    {"method": "DELETE", "path": "/api/uploads/{upload_id}",
                      "summary": "Abort a chunked upload session and remove the .partial file."},
                 ],
             },
@@ -1588,9 +1894,9 @@ async fn api_docs() -> Json<serde_json::Value> {
                      "summary": "List configured SMB shares with connection state and iso counts."},
                     {"method": "POST", "path": "/api/smb-shares",
                      "summary": "Register an SMB share. Body: { server, share, guest, username?, password?, port? }."},
-                    {"method": "DELETE", "path": "/api/smb-shares/:id",
+                    {"method": "DELETE", "path": "/api/smb-shares/{id}",
                      "summary": "Forget a share and drop its entries from the ISO store."},
-                    {"method": "POST", "path": "/api/smb-shares/:id/scan",
+                    {"method": "POST", "path": "/api/smb-shares/{id}/scan",
                      "summary": "Re-list a share for new ISOs."},
                 ],
             },
@@ -1601,9 +1907,9 @@ async fn api_docs() -> Json<serde_json::Value> {
                      "summary": "List configured NFSv3 shares with connection state and iso counts."},
                     {"method": "POST", "path": "/api/nfs-shares",
                      "summary": "Register an NFSv3 share. Body: { server, export, port? }. Auth is AUTH_SYS only; access control is by client IP on the server side."},
-                    {"method": "DELETE", "path": "/api/nfs-shares/:id",
+                    {"method": "DELETE", "path": "/api/nfs-shares/{id}",
                      "summary": "Forget a share and drop its entries from the ISO store."},
-                    {"method": "POST", "path": "/api/nfs-shares/:id/scan",
+                    {"method": "POST", "path": "/api/nfs-shares/{id}/scan",
                      "summary": "Re-list a share for new ISOs."},
                 ],
             },
@@ -1614,9 +1920,9 @@ async fn api_docs() -> Json<serde_json::Value> {
                      "summary": "List configured SFTP-over-SSH shares with connection state and iso counts."},
                     {"method": "POST", "path": "/api/sftp-shares",
                      "summary": "Register an SFTP share. Body: { server, export, username, port?, password? | private_key? + passphrase? }. The server's SSH host key is pinned trust-on-first-use."},
-                    {"method": "DELETE", "path": "/api/sftp-shares/:id",
+                    {"method": "DELETE", "path": "/api/sftp-shares/{id}",
                      "summary": "Forget a share, drop its entries from the ISO store, and scrub its credentials file."},
-                    {"method": "POST", "path": "/api/sftp-shares/:id/scan",
+                    {"method": "POST", "path": "/api/sftp-shares/{id}/scan",
                      "summary": "Re-list a share for new ISOs."},
                 ],
             },
@@ -1636,9 +1942,9 @@ async fn api_docs() -> Json<serde_json::Value> {
                      "summary": "Current runtime settings (Windows toggle, timeout, dns hint, …)."},
                     {"method": "PUT", "path": "/api/settings",
                      "summary": "Replace runtime settings. Guards against enabling Windows when wimboot isn't bundled."},
-                    {"method": "POST", "path": "/api/branding/logo/:slot",
+                    {"method": "POST", "path": "/api/branding/logo/{slot}",
                      "summary": "Upload a custom logo for a slot (light | dark | client). Multipart 'file', PNG/SVG/JPEG/WebP/GIF up to 2 MB. The client slot is raster-only."},
-                    {"method": "DELETE", "path": "/api/branding/logo/:slot",
+                    {"method": "DELETE", "path": "/api/branding/logo/{slot}",
                      "summary": "Remove the custom logo for a slot and revert to the bundled mark."},
                     {"method": "GET", "path": "/branding/pxe-logo",
                      "summary": "Raster form of the operator's 'client' logo for the iPXE menu's `console --picture`. Default background when unset/SVG."},
@@ -1663,6 +1969,10 @@ async fn api_docs() -> Json<serde_json::Value> {
                      "summary": "Auth status — { setup_required, authenticated, user }. Always 200."},
                     {"method": "PUT", "path": "/api/me/credentials",
                      "summary": "Rotate the admin's credentials. Body: { current_password, new_username?, new_password? }. Revokes all other sessions on success."},
+                    {"method": "GET", "path": "/api/api-key",
+                     "summary": "Return the operator API key + the header to send it in (x-api-key). That header authenticates API calls without a browser session — full operator access."},
+                    {"method": "POST", "path": "/api/api-key/regenerate",
+                     "summary": "Mint a fresh API key, invalidating the previous one immediately."},
                 ],
             },
             {
@@ -1679,9 +1989,9 @@ async fn api_docs() -> Json<serde_json::Value> {
                      "summary": "List uploaded answer files (Kickstart / Preseed / Autoinstall / Windows answer file)."},
                     {"method": "POST", "path": "/api/unattended",
                      "summary": "Upload an answer file (multipart 'file', .ks/.cfg/.seed/.yaml/.yml/.xml/user-data, up to 1 MB)."},
-                    {"method": "DELETE", "path": "/api/unattended/:id",
+                    {"method": "DELETE", "path": "/api/unattended/{id}",
                      "summary": "Delete an uploaded answer file."},
-                    {"method": "GET", "path": "/unattended/:id",
+                    {"method": "GET", "path": "/unattended/{id}",
                      "summary": "Public: serve an answer file with {{HOSTNAME}}/{{IP}}/{{MAC}} substituted from the query string."},
                 ],
             },
@@ -1692,9 +2002,9 @@ async fn api_docs() -> Json<serde_json::Value> {
                      "summary": "List queue entries (waiting + assigned, with any deployment profile)."},
                     {"method": "POST", "path": "/api/queue/assign",
                      "summary": "Assign a target image to queued clients. Body: { target, entry_ids }."},
-                    {"method": "PUT", "path": "/api/queue/:entry_id/profile",
+                    {"method": "PUT", "path": "/api/queue/{entry_id}/profile",
                      "summary": "Set a queued device's deployment profile. Body: { auto_hostname?, auto_ip?, unattended_file? }."},
-                    {"method": "DELETE", "path": "/api/queue/:entry_id",
+                    {"method": "DELETE", "path": "/api/queue/{entry_id}",
                      "summary": "Release a queue entry without assigning."},
                 ],
             },
@@ -1705,9 +2015,13 @@ async fn api_docs() -> Json<serde_json::Value> {
                      "summary": "List per-MAC boot bindings."},
                     {"method": "POST", "path": "/api/hosts",
                      "summary": "Pin a MAC to a boot target. Body: { mac, target, label, auto_hostname?, auto_ip?, unattended_file? }."},
-                    {"method": "DELETE", "path": "/api/hosts/:mac",
+                    {"method": "DELETE", "path": "/api/hosts/{mac}",
                      "summary": "Remove a binding."},
-                    {"method": "POST", "path": "/api/hosts/:mac/wol",
+                    {"method": "GET", "path": "/api/boot-rules",
+                     "summary": "Boot rules + decision-webhook config (v0.7.0)."},
+                    {"method": "PUT", "path": "/api/boot-rules",
+                     "summary": "Replace the whole boot-rules config (rules are ordered)."},
+                    {"method": "POST", "path": "/api/hosts/{mac}/wol",
                      "summary": "Send a Wake-on-LAN magic packet to a bound MAC (limited + subnet broadcast)."},
                     {"method": "GET", "path": "/api/boot-log",
                      "summary": "Ring of recent boot events (timestamp, mac, ip, target)."},
@@ -2536,6 +2850,7 @@ async fn api_network(State(state): State<AppState>) -> Json<serde_json::Value> {
             .strip_prefix("http://")
             .unwrap_or(&state.public_base_url),
         "nic_name":   state.nic_name,
+        "nic_link":   state.nic_link,
         "subnet_mask": state.subnet_mask,
         "gateway":     state.gateway,
         "dns_server":  state.settings.snapshot().dns_server,
@@ -2940,11 +3255,13 @@ mod tests {
             auto_ip: Some("10.0.0.7".into()),
             unattended_file: Some("ks1".into()),
         };
+        let tokens = openpxe_core::BootTokens::new();
         let a = build_unattended_args(
             "http://h",
             &meta(UnattendedKind::Kickstart),
             Some("aa:bb:cc:dd:ee:ff"),
             &p,
+            &tokens,
         )
         .unwrap();
         assert!(a.starts_with("inst.ks=http://h/unattended/ks1?"), "{a}");
@@ -2952,6 +3269,9 @@ mod tests {
         assert!(a.contains("ip=10.0.0.7"), "{a}");
         // MAC colons are percent-encoded.
         assert!(a.contains("mac=aa%3Abb%3Acc%3Add%3Aee%3Aff"), "{a}");
+        // v0.7.0: a live access token rides in the generated URL.
+        let tok = a.rsplit("t=").next().unwrap();
+        assert!(tokens.check(tok, "ks1"), "minted token must be live: {a}");
     }
 
     #[test]
@@ -2960,8 +3280,15 @@ mod tests {
             auto_hostname: Some("deb1".into()),
             ..Default::default()
         };
-        let a =
+        let tokens = openpxe_core::BootTokens::new();
-            build_unattended_args("http://h/", &meta(UnattendedKind::Preseed), None, &p).unwrap();
+        let a = build_unattended_args(
+            "http://h/",
+            &meta(UnattendedKind::Preseed),
+            None,
+            &p,
+            &tokens,
+        )
+        .unwrap();
         assert!(
             a.starts_with("auto=true priority=critical url=http://h/unattended/ks1"),
             "{a}"
@@ -2976,11 +3303,13 @@ mod tests {
             auto_ip: Some("10.1.1.5".into()),
             unattended_file: Some("ks1".into()),
         };
+        let tokens = openpxe_core::BootTokens::new();
         let a = build_unattended_args(
             "http://h",
             &meta(UnattendedKind::Autoinstall),
             Some("aa:bb"),
             &p,
+            &tokens,
         )
         .unwrap();
         assert!(
@@ -2990,10 +3319,12 @@ mod tests {
         assert!(a.ends_with('/'), "seed URL must end with '/': {a}");
         // The ctx segment round-trips back to the per-host values.
         let ctx = a.trim_end_matches('/').rsplit('/').next().unwrap();
-        let (mac, host, ip) = decode_seed_ctx(ctx);
+        let (mac, host, ip, token) = decode_seed_ctx(ctx);
         assert_eq!(mac.as_deref(), Some("aa:bb"));
         assert_eq!(host.as_deref(), Some("u1"));
         assert_eq!(ip.as_deref(), Some("10.1.1.5"));
+        // v0.7.0: the ctx carries a live access token for the file.
+        assert!(tokens.check(token.as_deref().unwrap(), "ks1"));
     }
 
     #[test]
@@ -3002,20 +3333,26 @@ mod tests {
             unattended_file: Some("ks1".into()),
             ..Default::default()
         };
-        assert!(
+        let tokens = openpxe_core::BootTokens::new();
-            build_unattended_args("http://h", &meta(UnattendedKind::AnswerFile), None, &p)
+        assert!(build_unattended_args(
-                .is_none()
+            "http://h",
-        );
+            &meta(UnattendedKind::AnswerFile),
+            None,
+            &p,
+            &tokens
+        )
+        .is_none());
     }
 
     #[test]
     fn seed_ctx_empty_segment_decodes_to_none() {
-        let ctx = encode_seed_ctx(None, None, None);
+        let ctx = encode_seed_ctx(None, None, None, "tok");
-        let (m, h, i) = decode_seed_ctx(&ctx);
+        let (m, h, i, t) = decode_seed_ctx(&ctx);
         assert!(m.is_none() && h.is_none() && i.is_none());
+        assert_eq!(t.as_deref(), Some("tok"));
         // Garbage decodes safely to all-None.
-        let (m2, h2, i2) = decode_seed_ctx("!!!not-base64!!!");
+        let (m2, h2, i2, t2) = decode_seed_ctx("!!!not-base64!!!");
-        assert!(m2.is_none() && h2.is_none() && i2.is_none());
+        assert!(m2.is_none() && h2.is_none() && i2.is_none() && t2.is_none());
     }
 
     #[test]

crates/http-api/src/auth.rs

@@ -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,
@@ -169,6 +175,13 @@ fn parse_cookie(headers: &axum::http::HeaderMap) -> Option<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
@@ -216,14 +229,19 @@ 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());
+    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,
         Json(json!({ "error": "authentication required" })),
@@ -440,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,

crates/http-api/src/fetch.rs

@@ -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);
+    }
+}

crates/http-api/src/grub_script.rs

@@ -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}");
+    }
+}

crates/http-api/src/iso_fs.rs

@@ -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
-    }
-}

crates/http-api/src/lib.rs

@@ -9,15 +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;

crates/http-api/src/state.rs

@@ -1,9 +1,10 @@
 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,
@@ -29,6 +30,14 @@ 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.
@@ -47,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
@@ -95,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.
@@ -108,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.

crates/http-api/tests/full_flow.rs

@@ -18,23 +18,16 @@ use openpxe_iso_store::{IsoStore, NfsShareManager, SftpShareManager, SmbShareMan
 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>) {
@@ -106,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 {
@@ -115,10 +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,
@@ -129,16 +126,121 @@ async fn build_state() -> (AppState, tempfile::TempDir) {
         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;
@@ -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",
@@ -2609,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)
+    );
+}

crates/ipxe-assets/Cargo.toml

@@ -13,4 +13,3 @@ workspace = true
 openpxe-core.workspace = true
 rust-embed.workspace = true
 tracing.workspace = true
-thiserror.workspace = true

crates/ipxe-assets/src/lib.rs

@@ -67,7 +67,7 @@ pub fn log_availability() {
         ClientArch::Arm64Uefi,
     ];
     for arch in arches {
-        for mode in [DriverMode::Firmware, DriverMode::Builtin] {
+        for mode in [DriverMode::Firmware, DriverMode::Builtin, DriverMode::Shim] {
             let Some(name) = arch.ipxe_bootfile_mode(mode) else {
                 continue;
             };
@@ -82,12 +82,18 @@ pub fn log_availability() {
                     "MISSING iPXE binary for {} [{mode:?}]: {name} — clients of this arch will not PXE boot",
                     arch.as_str()
                 );
-            } else {
+            } 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()
+                );
             }
         }
     }

crates/iso-store/Cargo.toml

@@ -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
@@ -49,3 +46,11 @@ 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 = []

crates/iso-store/src/introspect.rs

@@ -1,16 +1,33 @@
 //! 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, Default)]
@@ -30,18 +47,35 @@ pub enum DistroFamily {
 /// 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 — e.g. a Windows 11 ISO tagged `Unknown` by an older binary —
+/// metadata without the operator having to delete and re-upload.
-/// without the operator having to delete and re-upload it.
 ///
 /// rev 1 (v0.5.9): added El Torito boot-catalog detection + broadened
-/// Windows (UDF/UTF-16) detection becomes retroactive.
+/// Windows (UDF/UTF-16) detection.
-pub const INTROSPECT_REV: u32 = 1;
+/// 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>,
@@ -55,124 +89,245 @@ pub struct IntrospectionReport {
     /// 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. Old
+    /// Revision of the introspection logic that produced this report.
-    /// `meta.json` files without the field deserialize as 0, which is
+    /// `0` means "never introspected" (pre-v0.5.9 metadata, or a remote
-    /// below [`INTROSPECT_REV`], triggering a one-time re-introspect on
+    /// ISO whose probe hasn't run / can't run) — the entry generator
-    /// the next startup. v0.5.9.
+    /// 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 filename = path
+        .file_name()
+        .map(|s| s.to_string_lossy().into_owned())
+        .unwrap_or_default();
+    let Ok(f) = std::fs::File::open(path) else {
+        tracing::warn!(target: "openpxe::iso", "cannot open ISO for introspection: {}", path.display());
+        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()
     };
 
-    let Ok(mut f) = std::fs::File::open(path) else {
+    // Everything sector-shaped goes through one caching wrapper: the
-        tracing::warn!(target: "openpxe::iso", "cannot open ISO for introspection: {}", path.display());
+    // descriptor-set sectors are read once and shared between the label
-        return report;
+    // scan, the El Torito walk, and the namespace-root lookups; the
-    };
+    // probe table's repeated root/subdirectory reads collapse the same
-
+    // way — over NFS/SFTP that's the difference between ~6 and ~60+
-    // ISO9660 Primary Volume Descriptor at LBA 16 (offset 0x8000), 2048 bytes.
+    // round-trips per ISO.
-    // Bytes 40..72 are the Volume Identifier (space-padded, d-characters).
-    let mut pvd = [0u8; 2048];
-    if f.seek(SeekFrom::Start(0x8000)).is_ok() && f.read_exact(&mut pvd).is_ok() {
-        // Byte 0 must be 0x01 (primary descriptor), bytes 1..6 = "CD001".
-        if pvd[0] == 0x01 && &pvd[1..6] == b"CD001" {
-            let label_raw = &pvd[40..72];
-            let label = String::from_utf8_lossy(label_raw).trim().to_string();
-            if !label.is_empty() {
-                report.volume_label = Some(label.clone());
-                report.family = family_from_label(&label);
-            }
-        }
-    }
-
-    // Does the ISO have an El Torito boot catalog? This is what decides
-    // whether an ISO we *can't* otherwise classify is bootable at all —
-    // a bootable ISO sanboots; a data/appliance ISO (no catalog) can't.
-    report.el_torito = detect_el_torito(&mut f);
-
-    // Cheap content scan: read the first ~64 MiB, look for signature filenames.
-    // This is enough to identify `sources/boot.wim` (Windows) and common
-    // kernel/initrd paths for the major Linux distros.
-    let _ = f.seek(SeekFrom::Start(0));
-    let scan_bytes = 64 * 1024 * 1024;
-    let mut buf = vec![0u8; 1024 * 1024];
-    let mut read_total = 0usize;
-    // Size the haystack to what will actually be read — the scan cap or
-    // the file itself, whichever is smaller — so the fill never reallocs
-    // and a small ISO doesn't reserve the full 64 MiB.
-    let file_len = f.metadata().map_or(usize::MAX, |m| {
-        usize::try_from(m.len()).unwrap_or(usize::MAX)
-    });
-    let mut haystack = Vec::with_capacity(scan_bytes.min(file_len));
-    while read_total < scan_bytes {
-        let n = f.read(&mut buf).unwrap_or(0);
-        if n == 0 {
-            break;
-        }
-        haystack.extend_from_slice(&buf[..n]);
-        read_total += n;
-    }
-
-    // `sources/boot.wim` is the definitive Windows-install-media marker
-    // when the ISO exposes ASCII (ISO9660/Joliet) names. `contains_ascii`
-    // is case-insensitive, so one form covers BOOT.WIM / boot.wim and the
-    // backslash variant.
-    if contains_ascii(&haystack, b"sources/boot.wim")
-        || contains_ascii(&haystack, b"sources\\boot.wim")
     {
+        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.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;
+            }
+        }
     }
 
-    // v0.5.8: broaden Windows detection. Modern Windows 10/11 ISOs are
+    // Modern Windows 10/11 ISOs are UDF — their tree is invisible to the
-    // UDF — filenames are stored as UTF-16 (so the ASCII scan above misses
+    // ISO9660 walk and the volume label is a cryptic Microsoft string.
-    // them) and the volume label is a cryptic Microsoft string (so
+    // Scan the first 16 MiB for well-known markers, ASCII and UTF-16LE.
-    // `family_from_label` misses it too). Booting is via HTTP sanboot of
+    // Runs after the Linux probes so a Linux ISO that *contains* the
-    // the raw ISO (no boot.wim extraction), so we only need the *family*.
+    // string "bootmgr" (GRUB/syslinux chainload modules do) has already
-    // Catch the common cases: well-known Windows markers in either ASCII
+    // classified and never reaches this — that ordering is the v0.7.4
-    // or UTF-16LE within the first 16 MiB, plus a filename hint.
+    // gparted-misdetection fix.
-    if report.family == DistroFamily::Unknown {
+    if report.family == DistroFamily::Unknown && allow_bulk_scan {
-        let head = &haystack[..haystack.len().min(16 * 1024 * 1024)];
+        if let Some(win) = bulk_windows_scan(r, total_len).await {
-        let ascii_markers: [&[u8]; 4] = [
-            b"bootmgr",
-            b"sources/install.wim",
-            b"sources/install.esd",
-            b"efi/microsoft",
-        ];
-        let utf16_markers = ["bootmgr", "boot.wim", "install.wim", "microsoft"];
-        let looks_windows = ascii_markers.iter().any(|m| contains_ascii(head, m))
-            || utf16_markers.iter().any(|m| contains_utf16le_ci(head, m))
-            || filename_looks_windows(path);
-        if looks_windows {
             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") {
@@ -188,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
     }
 }
 
@@ -237,14 +466,10 @@ fn contains_utf16le_ci(haystack: &[u8], ascii: &str) -> bool {
 
 /// Filename heuristic: a stock Windows ISO almost always carries an obvious
 /// token in its name (e.g. `..._windows_11_...`, `Win10`, `winserver`).
-/// Used only as a last-resort family hint when the content scan and volume
+/// v0.7.4: takes the bare filename instead of a `Path` so the same check
-/// label are inconclusive. v0.5.8.
+/// runs against remote share listings.
-fn filename_looks_windows(path: &Path) -> bool {
+fn filename_looks_windows(filename: &str) -> bool {
-    let name = path
+    let name = filename.to_ascii_lowercase();
-        .file_name()
-        .and_then(|s| s.to_str())
-        .unwrap_or("")
-        .to_ascii_lowercase();
     const TOKENS: [&str; 6] = [
         "windows",
         "winpe",
@@ -263,32 +488,32 @@ 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 (offset 0x8000) and
+/// The ISO9660 Volume Descriptor Set starts at LBA 16 and runs one
-/// runs one 2048-byte descriptor per sector until a Set Terminator
+/// 2048-byte descriptor per sector; a Boot Record descriptor (type 0x00)
-/// (type 0xFF). A Boot Record descriptor (type 0x00) whose 32-byte boot
+/// whose 32-byte boot system identifier reads "EL TORITO SPECIFICATION"
-/// system identifier reads "EL TORITO SPECIFICATION" means the image
+/// means the image declares a boot catalog. We only confirm its presence
-/// declares an El Torito boot catalog. We only confirm its presence — we
+/// — we don't parse the catalog (sanboot/the firmware does that).
-/// don't parse the catalog (sanboot/the firmware does that). The walk is
+///
-/// capped so a malformed/huge image can't spin us. v0.5.9.
+/// v0.7.5: the walk no longer aborts at the first non-`CD001` sector or
-fn detect_el_torito(f: &mut std::fs::File) -> bool {
+/// stops at a Set Terminator. Sloppy mastering tools (appliance ISOs
-    let mut vd = [0u8; 2048];
+/// 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 {
-        if f.seek(SeekFrom::Start(lba * 2048)).is_err() || f.read_exact(&mut vd).is_err() {
+        let Ok(vd) = r.read_at(lba * SECTOR, 2048).await else {
+            // Past end of a tiny image — nothing more to examine.
             return false;
-        }
+        };
-        // Every descriptor in the set carries the "CD001" magic; once it's
-        // missing we've walked off the end of a valid set.
         if &vd[1..6] != b"CD001" {
-            return false;
+            continue; // filler/garbage sector — keep walking
         }
-        match vd[0] {
+        if vd[0] == 0x00 && vd[7..7 + EL_TORITO_ID.len()] == *EL_TORITO_ID {
-            // Boot Record descriptor carrying the El Torito signature.
+            return true;
-            0x00 if vd[7..7 + EL_TORITO_ID.len()] == *EL_TORITO_ID => return true,
-            // Volume Descriptor Set Terminator — nothing bootable found.
-            0xFF => return false,
-            // Any other descriptor (incl. a non-El-Torito boot record) —
-            // keep walking the set.
-            _ => {}
         }
     }
     false
@@ -297,6 +522,12 @@ fn detect_el_torito(f: &mut std::fs::File) -> bool {
 #[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() {
@@ -313,13 +544,158 @@ 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() {
-        // "boot.wim" encoded UTF-16LE, mixed case — UDF stores Windows
-        // filenames this way, which the ASCII scan can't see.
         let s = "BOOT.WIM";
         let utf16: Vec<u8> = s.bytes().flat_map(|b| [b, 0]).collect();
         let mut hay = vec![0u8; 8];
@@ -328,59 +704,108 @@ mod tests {
         assert!(contains_utf16le_ci(&hay, "boot.wim"));
         assert!(contains_utf16le_ci(&hay, "Boot.Wim"));
         assert!(!contains_utf16le_ci(&hay, "install.wim"));
-        // An ASCII (not UTF-16) occurrence must NOT match the UTF-16 scan.
         assert!(!contains_utf16le_ci(b"boot.wim plain ascii", "boot.wim"));
     }
 
     #[test]
-    fn el_torito_boot_catalog_detected() {
+    fn el_torito_detected_through_reader() {
-        let dir = tempfile::tempdir().unwrap();
+        let with = TestIsoBuilder::new("BOOTABLE").el_torito(true).build();
-        // Helper: stamp a 2048-byte descriptor at `lba` with type + magic.
+        let without = TestIsoBuilder::new("DATA").build();
-        let stamp = |img: &mut [u8], lba: usize, ty: u8| {
+        assert!(futures::executor::block_on(detect_el_torito(
-            let off = lba * 2048;
+            &mut MemReadAt(with)
-            img[off] = ty;
+        )));
-            img[off + 1..off + 6].copy_from_slice(b"CD001");
+        assert!(!futures::executor::block_on(detect_el_torito(
-        };
+            &mut MemReadAt(without)
+        )));
+    }
 
-        // Bootable image: PVD @16, El Torito Boot Record @17, terminator @18.
+    #[test]
-        let mut boot = vec![0u8; 2048 * 19];
+    fn el_torito_survives_filler_sector_in_descriptor_area() {
-        stamp(&mut boot, 16, 0x01);
+        // v0.7.5 tolerance test: sloppy appliance mastering leaves a
-        stamp(&mut boot, 17, 0x00);
+        // zeroed sector inside the Volume Descriptor Set. The old walk
-        boot[17 * 2048 + 7..17 * 2048 + 7 + EL_TORITO_ID.len()].copy_from_slice(EL_TORITO_ID);
+        // aborted at the first non-CD001 sector and flagged a genuinely
-        stamp(&mut boot, 18, 0xFF);
+        // bootable image as a data ISO.
-        let bp = dir.path().join("boot.iso");
+        let sector = SECTOR as usize;
-        std::fs::write(&bp, &boot).unwrap();
+        let mut img = TestIsoBuilder::new("GAPPY").el_torito(true).build();
-        let mut f = std::fs::File::open(&bp).unwrap();
+        // 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!(
-            detect_el_torito(&mut f),
+            futures::executor::block_on(detect_el_torito(&mut MemReadAt(img))),
-            "El Torito boot record should match"
+            "boot record behind a zeroed filler sector must still be found"
         );
+    }
 
-        // Data/appliance image: PVD @16, terminator @17, no boot record.
+    #[test]
-        let mut data = vec![0u8; 2048 * 18];
+    fn joliet_only_image_classifies_via_fallback() {
-        stamp(&mut data, 16, 0x01);
+        // Primary namespace bare, real tree only in Joliet — the v0.7.5
-        stamp(&mut data, 17, 0xFF);
+        // fallback must classify it (boot.wim probe) where v0.7.4 saw
-        let dp = dir.path().join("data.iso");
+        // "no installer files".
-        std::fs::write(&dp, &data).unwrap();
+        let img = TestIsoBuilder::new("WIN_APPLIANCE")
-        let mut f2 = std::fs::File::open(&dp).unwrap();
+            .el_torito(true)
-        assert!(!detect_el_torito(&mut f2), "data ISO has no boot catalog");
+            .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() {
-        use std::path::Path;
+        assert!(filename_looks_windows(
-        assert!(filename_looks_windows(Path::new(
             "en-us_windows_11_iot_enterprise_ltsc_2024_x64_dvd.iso"
-        )));
+        ));
-        assert!(filename_looks_windows(Path::new(
+        assert!(filename_looks_windows("Win10_22H2_English_x64.iso"));
-            "Win10_22H2_English_x64.iso"
+        assert!(filename_looks_windows("winserver2022.iso"));
-        )));
+        assert!(!filename_looks_windows("ubuntu-24.04-desktop.iso"));
-        assert!(filename_looks_windows(Path::new("winserver2022.iso")));
+        assert!(!filename_looks_windows("Rocky-9.4-x86_64-dvd.iso"));
-        assert!(!filename_looks_windows(Path::new(
+    }
-            "ubuntu-24.04-desktop.iso"
+
-        )));
+    #[test]
-        assert!(!filename_looks_windows(Path::new(
+    fn bulk_scan_catches_udf_windows_markers() {
-            "Rocky-9.4-x86_64-dvd.iso"
+        // 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");
     }
 }

crates/iso-store/src/iso_fs.rs

@@ -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());
+    }
+}

crates/iso-store/src/lib.rs

@@ -18,8 +18,15 @@
 
 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;
@@ -29,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

crates/iso-store/src/nfs_share.rs

@@ -57,7 +57,9 @@
 //! 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::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;
@@ -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"),
         }
     }
 
@@ -387,12 +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::default();
+            // registers a provisional filename-based report (so the scan
+            // returns fast) and queues a background probe that upgrades
+            // the entry in place.
+            let cached = self
+                .introspect_cache
+                .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(),
@@ -413,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,
@@ -490,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.

crates/iso-store/src/remote_cache.rs

@@ -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());
+    }
+}

crates/iso-store/src/sftp_share.rs

@@ -56,7 +56,9 @@
 //! hint}` error shape is shared so the storage tab renders all three
 //! protocols through one code path.
 
-use crate::introspect::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 openpxe_core::{Error, Result};
@@ -96,6 +98,18 @@ const READ_CHUNK_BYTES: usize = 64 * 1024;
 /// body stream. 16 * 64 KiB ≈ 1 MiB max buffer per stream.
 const STREAM_BUFFER_DEPTH: usize = 16;
 
+/// v0.7.4: per-ISO budget for a background introspection probe — one SSH
+/// connection plus a few dozen KiB-sized reads. SSH handshakes cost more
+/// than NFS mounts, but 30s still only trips on a wedged server.
+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,
+}
+
 /// Which credential the share authenticates with. The secret itself
 /// lives in the 0600 creds file, never here.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
@@ -209,6 +223,9 @@ pub struct SftpShareManager {
     /// Serializes scan operations on the same manager for predictable
     /// log output; each scan opens its own SSH connection.
     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 SftpShareManager {
@@ -222,6 +239,7 @@ impl SftpShareManager {
             inner: Arc::new(Mutex::new(Inner::default())),
             iso_store,
             op_lock: Arc::new(tokio::sync::Mutex::new(())),
+            introspect_cache: RemoteIntrospectCache::open(work_dir, "sftp_introspect_cache.json"),
         }
     }
 
@@ -474,13 +492,25 @@ impl SftpShareManager {
         };
 
         let mut count = 0u32;
+        let mut to_probe: Vec<ProbeJob> = Vec::new();
         for entry in listing {
             let iso_id = format!("sftp-{}-{}", share.id, slugify_str(&entry.filename));
-            // Same as NFS/SMB: no over-the-network introspection yet, so
+            // v0.7.4: real introspection over the share — SFTP file
-            // register `Unknown` and let the boot-entry generator fall
+            // handles are seekable, so the ISO9660 probes work remotely.
-            // back to filename-based detection. SFTP *could* do bounded
+            // Cache hit → full report now; miss → provisional filename-
-            // PVD reads (it has random access) — a follow-up can add it.
+            // based report (scan returns fast) + a queued background
-            let report = IntrospectionReport::default();
+            // probe that upgrades the entry in place.
+            let cached = self
+                .introspect_cache
+                .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::Sftp {
                 share_id: share.id.clone(),
@@ -506,11 +536,88 @@ impl SftpShareManager {
             target: "openpxe::sftp",
             id = %id, server = %share.server, export = %share.export,
             iso_count = count,
+            pending_introspection = to_probe.len(),
             "SFTP share scanned"
         );
+        if !to_probe.is_empty() {
+            self.spawn_introspection_pass(&share, &creds, to_probe);
+        }
         Ok(count)
     }
 
+    /// v0.7.4: probe each queued ISO over its own SSH connection and swap
+    /// the full introspection into the store as results land. Detached so
+    /// neither startup nor the share-add API call waits on a big library;
+    /// per-ISO failures leave the provisional entry, which still sanboots.
+    fn spawn_introspection_pass(&self, share: &SftpShare, creds: &SftpCreds, work: Vec<ProbeJob>) {
+        let store = self.iso_store.clone();
+        let cache = self.introspect_cache.clone();
+        let share_id = share.id.clone();
+        let params = ConnParams::from_share(share);
+        let creds = creds.clone();
+        let queued = work.len();
+        tokio::spawn(async move {
+            let mut upgraded = 0usize;
+            for job in work {
+                let probe = async {
+                    let mut reader = SftpReadAt::open(&params, &creds, &job.filename).await?;
+                    let report =
+                        introspect_reader(&mut reader, job.size, &job.filename, false).await;
+                    Ok::<_, SftpClientError>(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::sftp",
+                        share = %share_id, iso = %job.filename,
+                        "introspection failed: {e}"
+                    ),
+                    Err(_) => tracing::warn!(
+                        target: "openpxe::sftp",
+                        share = %share_id, iso = %job.filename,
+                        "introspection timed out after {}s", INTROSPECT_TIMEOUT.as_secs()
+                    ),
+                }
+            }
+            tracing::info!(
+                target: "openpxe::sftp",
+                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 SFTP share '{share_id}'")))?;
+        if filename.contains('/') || filename.contains('\\') || filename.contains("..") {
+            return Err(Error::Invalid(format!("invalid filename '{filename}'")));
+        }
+        let creds = self
+            .read_creds(share_id)
+            .await
+            .map_err(|e| Error::Invalid(format!("could not read credentials: {e}")))?;
+        let params = ConnParams::from_share(&share);
+        let mut reader = SftpReadAt::open(&params, &creds, filename)
+            .await
+            .map_err(|e| Error::Invalid(format!("sftp open '{filename}': {e}")))?;
+        Ok(iso_fs::lookup(&mut reader, in_iso_path).await)
+    }
+
     fn pin_fingerprint(&self, id: &str, fingerprint: String) {
         if fingerprint.is_empty() {
             return;
@@ -652,6 +759,43 @@ struct SftpConn {
     sftp: SftpSession,
 }
 
+/// v0.7.4: random-access reader over one SSH connection + open file
+/// handle — the [`IsoReadAt`] impl that lets the ISO9660 walker and
+/// introspection probes run against share-hosted images. Holds the
+/// `SftpConn` so the SSH session outlives every read.
+struct SftpReadAt {
+    _conn: SftpConn,
+    file: russh_sftp::client::fs::File,
+}
+
+impl SftpReadAt {
+    async fn open(
+        p: &ConnParams,
+        creds: &SftpCreds,
+        filename: &str,
+    ) -> std::result::Result<Self, SftpClientError> {
+        let (conn, _fp) = connect(p, creds).await?;
+        let full = format!("{}/{}", p.export.trim_end_matches('/'), filename);
+        let file = conn
+            .sftp
+            .open(full)
+            .await
+            .map_err(|e| SftpClientError::Sftp(e.to_string()))?;
+        Ok(Self { _conn: conn, file })
+    }
+}
+
+impl IsoReadAt for SftpReadAt {
+    async fn read_at(&mut self, offset: u64, len: u32) -> std::io::Result<Vec<u8>> {
+        self.file.seek(SeekFrom::Start(offset)).await?;
+        let mut buf = vec![0u8; len as usize];
+        // read_exact loops over the transport's short reads and fails
+        // with UnexpectedEof past end-of-file — exactly the contract.
+        self.file.read_exact(&mut buf).await?;
+        Ok(buf)
+    }
+}
+
 /// russh client handler implementing trust-on-first-use host-key
 /// verification. We never construct an `Err` from `check_server_key`;
 /// returning `Ok(false)` makes russh abort the handshake, and the

crates/iso-store/src/smb_share.rs

@@ -56,7 +56,7 @@
 //! streaming. A follow-up release can add libsmbclient-based seek if
 //! a real workload needs it.
 
-use crate::introspect::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;
@@ -455,15 +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::default();
             let boot_entries = generate_boot_entries_for(&iso_id, &entry.filename, &report);
             let source = IsoSource::Smb {
                 share_id: share.id.clone(),

crates/iso-store/src/store.rs

@@ -300,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 {
@@ -415,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
@@ -850,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(_))));
     }
 

crates/openpxe/Cargo.toml

@@ -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

crates/openpxe/src/main.rs

@@ -120,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();
 
@@ -184,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(),
@@ -191,10 +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(),
@@ -205,10 +245,12 @@ async fn main() -> anyhow::Result<()> {
         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,
     };
@@ -230,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());
 
@@ -248,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())
         }
@@ -421,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
@@ -481,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 {

crates/tftp/Cargo.toml

@@ -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

crates/tftp/src/lib.rs

@@ -14,4 +14,4 @@
 
 pub mod server;
 
-pub use server::TftpServer;
+pub use server::{DynamicAsset, TftpServer};

crates/tftp/src/server.rs

@@ -32,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 {
@@ -45,12 +53,14 @@ impl TftpServer {
         port: u16,
         clients: Arc<ClientRegistry>,
         metrics: openpxe_core::Metrics,
+        dynamic: Option<DynamicAsset>,
     ) -> Self {
         Self {
             bind,
             port,
             clients,
             metrics,
+            dynamic,
         }
     }
 
@@ -72,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}");
                 }
@@ -88,6 +101,7 @@ 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 —
@@ -117,7 +131,15 @@ async fn handle_rrq(
         return Ok(());
     }
 
-    let Some(file_bytes) = asset_slice(&filename) else {
+    // 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(

crates/webui/src/app.css

@@ -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; }

crates/webui/src/app.js

@@ -178,12 +178,14 @@
     if (iso.introspection.el_torito) {
       return { ok: true, warn: 'generic bootable ISO — boots via sanboot (emulated CD)' };
     }
-    // Remote-share ISOs aren't introspected (no random access over the
+    // v0.7.4: NFS/SFTP ISOs now introspect over the share, so a probed
-    // network), so el_torito is unknown — assume bootable and let sanboot
+    // remote ISO flows through the kernel/el_torito branches above like
-    // try rather than cry wolf.
+    // a local one. introspect_rev 0 means the probe hasn't landed yet
+    // (it runs in the background right after a scan) or never can (SMB —
+    // smbclient can't seek): stay optimistic and let sanboot try.
     const remote = iso.source && iso.source.kind && iso.source.kind !== 'local';
-    if (remote) {
+    if (remote && (iso.introspection.introspect_rev || 0) === 0) {
-      return { ok: true, warn: 'remote ISO — not introspected; sanboot is attempted at boot' };
+      return { ok: true, warn: 'remote ISO — awaiting introspection; sanboot is attempted at boot' };
     }
     // Local ISO with no Windows/Linux boot files and no El Torito catalog:
     // a data/appliance image (e.g. a VMware vCenter bundle), not a bootable
@@ -199,6 +201,51 @@
     })[k] || (k || 'Unknown');
   }
 
+  // v0.7.2: compact read-out of saved group rules — created from the
+  // unified "Pin MAC" form on the Hosts tab (a prefix or an architecture
+  // there saves a rule instead of a pin). First match wins, top to
+  // bottom. The boot-decision webhook remains available via the API
+  // (/api/boot-rules `webhook_url`) but no longer has a UI knob.
+  function groupRulesCard(cfg, targetOptions) {
+    const rules = (cfg && cfg.rules) || [];
+    if (!rules.length) return null;
+    const titleFor = id => {
+      const t = targetOptions.find(x => x.id === id);
+      return t ? t.title : id;
+    };
+    const modeLabel = {firmware:'Firmware NIC', builtin:'iPXE drivers', shim:'Secure Boot (shim)'};
+    const rows = rules.map((r, i) => el('tr', r.enabled === false ? {style:'opacity:.5'} : {}, [
+      el('td', {class:'mono'}, r.mac_prefix || el('span', {class:'tag'}, 'any MAC')),
+      el('td', {}, r.arch || el('span', {class:'tag'}, 'any arch')),
+      el('td', {}, r.target ? titleFor(r.target) : el('span', {class:'tag'}, '—')),
+      el('td', {}, r.driver_mode
+        ? el('span', {class:'tag accent'}, modeLabel[r.driver_mode] || r.driver_mode)
+        : el('span', {class:'tag'}, 'auto')),
+      el('td', {}, r.note || ''),
+      el('td', {style:'text-align:right'},
+        el('button', {class:'danger', onclick: async () => {
+          if (!confirm('Remove this group rule?')) return;
+          const fresh = await getJSON('/api/boot-rules').catch(() => ({rules: [], webhook_url: ''}));
+          (fresh.rules = fresh.rules || []).splice(i, 1);
+          await putJSON('/api/boot-rules', fresh);
+          render('hosts');
+        }}, 'Remove')),
+    ]));
+    return el('div', {class:'card'}, [
+      el('header', {}, [
+        el('h2', {}, 'Group rules'),
+        el('span', {class:'sub'}, 'first match wins · checked top to bottom'),
+      ]),
+      el('table', {}, [
+        el('thead', {}, el('tr', {}, [
+          el('th',{},'MAC prefix'), el('th',{},'Arch'), el('th',{},'Target'),
+          el('th',{},'Boot binary'), el('th',{},'Note'), el('th',{},''),
+        ])),
+        el('tbody', {}, rows),
+      ]),
+    ]);
+  }
+
   // v0.5.2: build the shared "deployment profile" field group — auto
   // hostname, auto IP, and an unattended-file picker — reused by the
   // Hosts pin form and the Queue "Profile" modal. `files` is the
@@ -222,7 +269,7 @@
       el('label', {class:'field'}, [
         el('span', {class:'name'}, 'Auto IP address (optional)'), ipInput]),
       el('label', {class:'field'}, [
-        el('span', {class:'name'}, 'Unattended file'), sel]),
+        el('span', {class:'name'}, 'Unattended file (in Storage → Advanced)'), sel]),
     ]);
     return {
       wrap,
@@ -400,6 +447,12 @@
             el('div', {class:'v'}, net.gateway || '?'),
             el('div', {class:'k'}, 'Public base URL'),
             el('div', {class:'v'}, net.public_base_url),
+            // v0.7.2: physical link details (operstate · speed · duplex ·
+            // port MAC) so the operator can confirm WHICH port answers PXE
+            // in multi-NIC / trunked environments. Kept last — the joined
+            // value runs long, so it wraps cleanly at the bottom of the list.
+            el('div', {class:'k'}, 'Link'),
+            el('div', {class:'v'}, net.nic_link || '—'),
           ]),
           el('p', {class:'msg'},
             'Server IP, NIC, mask, and gateway are auto-detected at startup. ' +
@@ -550,48 +603,40 @@
 
       // ── Upload card ──
       const drop = el('div', {class:'drop', id:'drop'}, [
-        el('div', {}, ['Drop an ', el('strong', {}, '.iso'), ' here, or click to choose.']),
+        el('div', {}, ['Drop one or more ', el('strong', {}, '.iso'), ' files here, or click to choose.']),
         el('div', {style:'font-size:12px;margin-top:6px'},
-           'Linux + Windows installers auto-detected on upload. Streaming, no 502s on big files.'),
+           'Linux + Windows installers auto-detected on upload. Multiple files upload at once. Streaming, no 502s on big files.'),
       ]);
       const file = el('input', {type:'file', accept:'.iso,application/octet-stream',
-                                style:'display:none', id:'file'});
+                                multiple:true, style:'display:none', id:'file'});
-      const prog = el('div', {class:'progress', id:'prog'}, el('div', {class:'bar', id:'bar'}));
+      // v0.8.0: one progress row per file, appended here. Replaces the
-      const upMsg = el('div', {class:'msg', id:'upmsg'});
+      // single shared bar/msg/cancel that a second concurrent upload used
-      // v0.5.8: cancel button — shown only while an upload is in flight.
+      // to clobber.
-      const cancelUpload = el('button', {class:'danger', type:'button',
+      const uploadsList = el('div', {id:'uploads', style:'display:grid;gap:12px'});
-        style:'display:none;margin-top:12px', id:'cancel-upload'}, 'Cancel upload');
 
-      drop.onclick = () => file.click();
+      // One page-leave guard + one tab-hide cleanup for the whole card,
-      drop.addEventListener('dragover', e => { e.preventDefault(); drop.classList.add('hover'); });
+      // registered only while ≥1 upload is in flight (added on 0→1, removed
-      drop.addEventListener('dragleave', () => drop.classList.remove('hover'));
+      // on 1→0) so listeners never pile up across re-renders.
-      drop.addEventListener('drop', e => {
+      let activeUploads = 0;
-        e.preventDefault(); drop.classList.remove('hover');
+      const activeIds = new Set();
-        if (e.dataTransfer.files[0]) upload(e.dataTransfer.files[0]);
+      const warnLeave = (e) => { if (activeUploads > 0) { e.preventDefault(); e.returnValue = ''; return ''; } };
-      });
+      const abortOnHide = () => {
-      file.onchange = () => { if (file.files[0]) upload(file.files[0]); };
+        // keepalive lets these DELETEs outlive the unload; the server also
-
+        // reclaims an orphaned .partial on the next upload, so best-effort
-      // Chunked upload telemetry. The old browser path posted one huge
+        // is fine here.
-      // multipart body, which left operators staring at 0% when a reverse
+        for (const id of activeIds) {
-      // proxy buffered or rejected the request before OpenPXE saw it. This
+          try { fetch('/api/uploads/' + encodeURIComponent(id), {method:'DELETE', keepalive:true}); } catch (_) {}
-      // path writes small raw chunks; each acknowledged chunk advances the
+        }
-      // bar and leaves a visible .partial file in the ISO directory.
-      async function upload(f) {
-        const started = Date.now();
-        const bar = $('#bar');
-        const setStatus = (text, cls) => { upMsg.textContent = text; upMsg.className = 'msg ' + (cls || ''); };
-        const update = (loaded, total, phase) => {
-          const pct = total > 0 ? Math.min(100, (loaded / total) * 100) : 100;
-          bar.style.width = pct.toFixed(1) + '%';
-          const elapsed = Math.max(0.001, (Date.now() - started) / 1000);
-          const rate = loaded > 0 ? loaded / elapsed : 0;
-          const remain = rate > 0 ? (total - loaded) / rate : 0;
-          setStatus(
-            phase + ' ' + f.name + ' - ' +
-            fmtBytes(loaded) + ' of ' + fmtBytes(total) +
-            ' (' + pct.toFixed(1) + '%, ' + fmtBytes(rate) + '/s' +
-            (remain > 0 ? ', ' + Math.ceil(remain) + 's left' : '') + ')');
       };
+      const addGuards = () => {
+        window.addEventListener('beforeunload', warnLeave);
+        window.addEventListener('pagehide', abortOnHide);
+      };
+      const removeGuards = () => {
+        window.removeEventListener('beforeunload', warnLeave);
+        window.removeEventListener('pagehide', abortOnHide);
+      };
+
       const failText = async (r) => {
         const text = (await r.text()).slice(0, 240);
         let hint = '';
@@ -602,19 +647,66 @@
         return 'HTTP ' + r.status + ' ' + text + hint;
       };
 
+      // Launch an upload per dropped/selected .iso. The browser's ~6
+      // connections-per-origin cap naturally bounds how many stream at
+      // once, so there's no hand-rolled queue. Non-.iso files are ignored.
+      const startMany = (fileList) => {
+        [...fileList].filter(f => /\.iso$/i.test(f.name)).forEach(uploadOne);
+      };
+
+      drop.onclick = () => file.click();
+      drop.addEventListener('dragover', e => { e.preventDefault(); drop.classList.add('hover'); });
+      drop.addEventListener('dragleave', () => drop.classList.remove('hover'));
+      drop.addEventListener('drop', e => {
+        e.preventDefault(); drop.classList.remove('hover');
+        startMany(e.dataTransfer.files);
+      });
+      // Reset value so re-selecting the same filename still fires onchange.
+      file.onchange = () => { startMany(file.files); file.value = ''; };
+
+      // One independent chunked upload with its own progress row. The old
+      // browser path posted one huge multipart body, which left operators
+      // staring at 0% when a reverse proxy buffered or rejected the request
+      // before OpenPXE saw it. This path writes small raw chunks; each
+      // acknowledged chunk advances the bar and leaves a visible .partial.
+      async function uploadOne(f) {
+        const started = Date.now();
+        const bar = el('div', {class:'bar'});
+        const prog = el('div', {class:'progress active'}, bar);
+        const rowMsg = el('div', {class:'msg'});
+        const cancelBtn = el('button', {class:'danger', type:'button', style:'margin-top:8px'}, 'Cancel');
+        const row = el('div', {}, [
+          el('div', {style:'font-weight:600;font-size:13px;margin-bottom:6px;word-break:break-all'}, f.name),
+          prog, rowMsg, cancelBtn,
+        ]);
+        uploadsList.appendChild(row);
+
+        const setStatus = (text, cls) => { rowMsg.textContent = text; rowMsg.className = 'msg ' + (cls || ''); };
+        const update = (loaded, total, phase) => {
+          const pct = total > 0 ? Math.min(100, (loaded / total) * 100) : 100;
+          bar.style.width = pct.toFixed(1) + '%';
+          const elapsed = Math.max(0.001, (Date.now() - started) / 1000);
+          const rate = loaded > 0 ? loaded / elapsed : 0;
+          const remain = rate > 0 ? (total - loaded) / rate : 0;
+          setStatus(
+            phase + ' - ' +
+            fmtBytes(loaded) + ' of ' + fmtBytes(total) +
+            ' (' + pct.toFixed(1) + '%, ' + fmtBytes(rate) + '/s' +
+            (remain > 0 ? ', ' + Math.ceil(remain) + 's left' : '') + ')');
+        };
+
         let uploadId = null;
-        // v0.5.8: cancel + leave-page guard. The AbortController stops the
+        // The AbortController stops this upload's in-flight chunk on Cancel.
-        // in-flight chunk; the beforeunload listener warns the operator
+        // The card-level beforeunload guard (added while activeUploads > 0)
-        // that navigating away aborts the upload (the server-side partial
+        // warns on navigation; the server reclaims an abandoned .partial on
-        // is then cleaned up by the DELETE in the catch below).
+        // the next upload either way.
         const ac = new AbortController();
         let canceled = false;
-        const warnLeave = (e) => { e.preventDefault(); e.returnValue = ''; return ''; };
+        cancelBtn.onclick = () => { canceled = true; ac.abort(); };
-        window.addEventListener('beforeunload', warnLeave);
+
-        cancelUpload.style.display = '';
+        activeUploads += 1;
-        cancelUpload.onclick = () => { canceled = true; ac.abort(); };
+        if (activeUploads === 1) addGuards();
-        setStatus('Preparing upload for ' + f.name + ' (' + fmtBytes(f.size) + ')');
+        setStatus('Preparing ' + f.name + ' (' + fmtBytes(f.size) + ')');
-        prog.classList.add('active');
         bar.style.width = '1%';
 
         try {
@@ -625,6 +717,7 @@
           if (!begin.ok) throw new Error(await failText(begin));
           const session = await begin.json();
           uploadId = session.upload_id;
+          activeIds.add(uploadId);
           const chunkSize = Math.max(1024 * 1024, Number(session.chunk_size || 8 * 1024 * 1024));
 
           let offset = Number(session.offset || 0);
@@ -649,25 +742,100 @@
           } while (!finished);
 
           setStatus('Uploaded and analyzed: ' + f.name + ' (' + fmtBytes(f.size) + ')', 'ok');
-          render('storage');
         } catch (err) {
           if (uploadId) {
             try { await fetch('/api/uploads/' + encodeURIComponent(uploadId), {method: 'DELETE'}); }
-            catch {}
+            catch (_) {}
           }
           if (canceled || (err && err.name === 'AbortError')) {
-            setStatus('Upload canceled — partial file discarded.', '');
+            setStatus('Canceled — partial file discarded.', '');
           } else {
             setStatus('Upload failed: ' + (err && err.message ? err.message : String(err)), 'err');
           }
         } finally {
-          window.removeEventListener('beforeunload', warnLeave);
+          if (uploadId) activeIds.delete(uploadId);
-          cancelUpload.style.display = 'none';
+          cancelBtn.style.display = 'none';
-          cancelUpload.onclick = null;
           prog.classList.remove('active');
-          if (!upMsg.className.includes('ok')) bar.style.width = '0';
+          activeUploads -= 1;
+          if (activeUploads === 0) {
+            removeGuards();
+            // Refresh the table to show the new image(s) — but only if the
+            // operator is still on Storage. isConnected goes false once
+            // render() swapped the view, so a mid-upload tab change won't
+            // yank them back here.
+            if (uploadsList.isConnected) render('storage');
           }
         }
+      }
+
+      // v0.8.1: add ISO by URL. Paste a link and the server streams it
+      // straight into the store and auto-detects it — no download-then-
+      // reupload. Progress polls /api/isos/fetch and shows rows below,
+      // mirroring uploads. On an air-gapped network, use the drop zone.
+      const urlInput = el('input', {type:'url', id:'iso-url', style:'flex:1',
+        placeholder:'https://example.com/systemrescue.iso'});
+      const fetchBtn = el('button', {class:'ghost', type:'button', style:'margin-left:8px'}, 'Fetch');
+      const fetchMsg = el('div', {class:'msg', style:'margin-top:6px'});
+      const fetchList = el('div', {id:'fetches', style:'display:grid;gap:12px;margin-top:12px'});
+      const urlRow = el('div', {style:'margin-top:14px'}, [
+        el('label', {class:'field', style:'margin-bottom:0'}, [
+          el('span', {class:'name'}, 'Or add by URL'),
+          el('div', {style:'display:flex;align-items:center'}, [urlInput, fetchBtn]),
+          el('span', {class:'hint'},
+            'The server downloads the .iso into storage and auto-detects it — same result as a drag-drop. Any http(s) .iso link works.'),
+        ]),
+        fetchMsg,
+      ]);
+
+      let fetchTimer = null;
+      const renderFetchRows = (jobs) => {
+        fetchList.replaceChildren(...jobs.map(j => {
+          const pct = j.total > 0 ? Math.min(100, (j.downloaded / j.total) * 100)
+                                  : (j.state === 'done' ? 100 : 0);
+          let text, cls = '';
+          if (j.state === 'downloading')
+            text = 'Downloading ' + fmtBytes(j.downloaded) +
+              (j.total ? ' of ' + fmtBytes(j.total) + ' (' + pct.toFixed(0) + '%)' : '');
+          else if (j.state === 'done') { text = 'Downloaded and analyzed.'; cls = 'ok'; }
+          else if (j.state === 'failed') { text = 'Failed: ' + (j.error || 'unknown error'); cls = 'err'; }
+          else text = 'Canceled — partial discarded.';
+          const btn = el('button', {class:'danger', type:'button', style:'margin-top:8px'},
+            j.state === 'downloading' ? 'Cancel' : 'Dismiss');
+          btn.onclick = async () => {
+            try { await fetch('/api/isos/fetch/' + encodeURIComponent(j.id), {method:'DELETE'}); } catch (_) {}
+            pollFetches();
+          };
+          return el('div', {}, [
+            el('div', {style:'font-weight:600;font-size:13px;margin-bottom:6px;word-break:break-all'},
+              j.filename + '  ·  ' + j.url),
+            el('div', {class:'progress' + (j.state === 'downloading' ? ' active' : '')},
+              el('div', {class:'bar', style:'width:' + pct.toFixed(1) + '%'})),
+            el('div', {class:'msg ' + cls}, text),
+            btn,
+          ]);
+        }));
+      };
+      async function pollFetches() {
+        if (fetchTimer) { clearTimeout(fetchTimer); fetchTimer = null; }
+        let jobs = [];
+        try { jobs = (await getJSON('/api/isos/fetch')).jobs || []; } catch (_) {}
+        renderFetchRows(jobs);
+        // A successful fetch is read-once on the server, so refreshing here
+        // shows the new image and won't re-trigger on the next poll. Keep
+        // polling only while a download is still in flight.
+        if (jobs.some(j => j.state === 'done')) { render('storage'); return; }
+        if (jobs.some(j => j.state === 'downloading')) fetchTimer = setTimeout(pollFetches, 1500);
+      }
+      async function startFetch() {
+        const url = urlInput.value.trim();
+        if (!url) return;
+        fetchMsg.textContent = 'Starting…'; fetchMsg.className = 'msg';
+        const r = await postJSON('/api/isos/fetch', { url });
+        if (r.ok) { urlInput.value = ''; fetchMsg.textContent = ''; pollFetches(); }
+        else { fetchMsg.textContent = 'Could not start: ' + (await r.text()).slice(0, 160); fetchMsg.className = 'msg err'; }
+      }
+      fetchBtn.onclick = startFetch;
+      urlInput.addEventListener('keydown', e => { if (e.key === 'Enter') { e.preventDefault(); startFetch(); } });
 
       // ── ISO table (mixed local + SMB) ──
       // Each row gets a "Password" cell that toggles a small inline
@@ -789,6 +957,12 @@
           render('storage');
         };
 
+        // v0.7.2: searchable haystack for the list filter — filename,
+        // detected family, category, and source all match.
+        const searchText = [
+          i.filename, familyLabel(i.introspection.family), i.category || '',
+          isSmb ? 'smb' : isNfs ? 'nfs' : 'local', i.id,
+        ].join(' ').toLowerCase();
         const tr = el('tr', b.ok ? {} : {class: 'unbootable'}, [
           el('td', {}, [
             el('div', {style:'display:flex;align-items:center;gap:8px'}, [
@@ -833,8 +1007,42 @@
                 }}, 'Remove'),
           ]),
         ]);
+        tr.dataset.search = searchText;
         rowsAndEditors.push(tr, editorRow);
       });
+
+      // v0.7.2: client-side filter over the image table; v0.7.4: paged
+      // 5 at a time so a 50-image library doesn't become a scroll wall.
+      // Rows travel in (row, password-editor) pairs. One view function
+      // applies filter-then-page; editors close on any view change.
+      const ISO_PAGE_SIZE = 5;
+      let isoPage = 0;
+      const pagerInfo = el('span', {});
+      const prevBtn = el('button', {class:'ghost', onclick: () => { isoPage -= 1; applyIsoListView(); }}, '‹ Prev');
+      const nextBtn = el('button', {class:'ghost', onclick: () => { isoPage += 1; applyIsoListView(); }}, 'Next ›');
+      function applyIsoListView() {
+        const q = isoSearch.value.trim().toLowerCase();
+        const visible = [];
+        for (let k = 0; k + 1 < rowsAndEditors.length; k += 2) {
+          const row = rowsAndEditors[k];
+          rowsAndEditors[k + 1].style.display = 'none';
+          row.style.display = 'none';
+          if (!q || (row.dataset.search || '').includes(q)) visible.push(row);
+        }
+        const pages = Math.max(1, Math.ceil(visible.length / ISO_PAGE_SIZE));
+        if (isoPage >= pages) isoPage = pages - 1;
+        if (isoPage < 0) isoPage = 0;
+        visible.slice(isoPage * ISO_PAGE_SIZE, (isoPage + 1) * ISO_PAGE_SIZE)
+          .forEach(r => { r.style.display = ''; });
+        pagerInfo.textContent = visible.length
+          ? 'Showing ' + (isoPage * ISO_PAGE_SIZE + 1) + '–' +
+            Math.min(visible.length, (isoPage + 1) * ISO_PAGE_SIZE) + ' of ' + visible.length
+          : 'No images match';
+        prevBtn.disabled = isoPage === 0;
+        nextBtn.disabled = isoPage >= pages - 1;
+      }
+      const isoSearch = el('input', {type:'search', placeholder:'Filter images by name, type, or source',
+        spellcheck:'false', oninput: () => { isoPage = 0; applyIsoListView(); }});
       const isoTable = isos.length
         ? el('table', {}, [
             el('thead', {}, el('tr', {}, [
@@ -846,6 +1054,13 @@
             el('tbody', {}, rowsAndEditors),
           ])
         : el('div', {class:'empty'}, 'No images yet. Upload an ISO or add an SMB share.');
+      // v0.7.4: pager footer, shown once the library outgrows one page.
+      const isoPager = isos.length > ISO_PAGE_SIZE
+        ? el('div', {class:'list-pager'}, [
+            pagerInfo, el('span', {class:'spacer'}), prevBtn, nextBtn,
+          ])
+        : null;
+      if (isos.length) applyIsoListView();
 
       // ── Remote shares section (v0.5.1) ──
       // SMB + NFS unified into one "Remote shares" card with a protocol
@@ -1172,7 +1387,10 @@
       unattFile.onchange = () => { if (unattFile.files[0]) uploadUnattended(unattFile.files[0]); };
 
       const unattRows = unattendedFiles.length
-        ? unattendedFiles.map(f => el('div', {class:'nfs-row'}, [
+        ? unattendedFiles.map(f => el('div', {
+            class:'nfs-row',
+            'data-search': (f.filename + ' ' + unattendedKindLabel(f.kind) + ' ' + f.id).toLowerCase(),
+          }, [
             el('span', {class:'dot ok'}),
             el('div', {}, [
               el('div', {class:'id'}, [
@@ -1191,6 +1409,36 @@
           ]))
         : [el('div', {class:'empty'}, 'No unattended files yet.')];
 
+      // v0.7.2: filter for big answer-file libraries; v0.7.5: paged 5 at
+      // a time, the same filter-then-page view the image table uses.
+      const UNATT_PAGE_SIZE = 5;
+      let unattPage = 0;
+      const unattPagerInfo = el('span', {});
+      const unattPrev = el('button', {class:'ghost', onclick: () => { unattPage -= 1; applyUnattListView(); }}, '‹ Prev');
+      const unattNext = el('button', {class:'ghost', onclick: () => { unattPage += 1; applyUnattListView(); }}, 'Next ›');
+      const unattSearch = el('input', {type:'search', placeholder:'Filter files by name or kind',
+        spellcheck:'false', oninput: () => { unattPage = 0; applyUnattListView(); }});
+      function applyUnattListView() {
+        if (!unattendedFiles.length) return; // empty-state div carries no dataset
+        const q = unattSearch.value.trim().toLowerCase();
+        const visible = unattRows.filter(r => {
+          r.style.display = 'none';
+          return !q || (r.dataset.search || '').includes(q);
+        });
+        const pages = Math.max(1, Math.ceil(visible.length / UNATT_PAGE_SIZE));
+        if (unattPage >= pages) unattPage = pages - 1;
+        if (unattPage < 0) unattPage = 0;
+        visible.slice(unattPage * UNATT_PAGE_SIZE, (unattPage + 1) * UNATT_PAGE_SIZE)
+          .forEach(r => { r.style.display = ''; });
+        unattPagerInfo.textContent = visible.length
+          ? 'Showing ' + (unattPage * UNATT_PAGE_SIZE + 1) + '–' +
+            Math.min(visible.length, (unattPage + 1) * UNATT_PAGE_SIZE) + ' of ' + visible.length
+          : 'No files match';
+        unattPrev.disabled = unattPage === 0;
+        unattNext.disabled = unattPage >= pages - 1;
+      }
+      applyUnattListView();
+
       const unattendedAdvanced = el('details', {class:'advanced-disclosure', style:'margin-top:18px'}, [
         el('summary', {class:'advanced-summary'}, 'Advanced'),
         el('div', {class:'card', style:'margin-top:14px'}, [
@@ -1200,7 +1448,15 @@
           ]),
           el('div', {class:'body'}, [
             unattDrop, unattFile, unattMsg,
+            unattendedFiles.length > 1
+              ? el('label', {class:'field', style:'margin-top:14px;margin-bottom:0'}, unattSearch)
+              : null,
             el('div', {style:'margin-top:16px;display:grid;gap:8px'}, unattRows),
+            unattendedFiles.length > UNATT_PAGE_SIZE
+              ? el('div', {class:'list-pager', style:'padding:12px 0 0'}, [
+                  unattPagerInfo, el('span', {class:'spacer'}), unattPrev, unattNext,
+                ])
+              : null,
             el('p', {class:'msg', style:'margin-top:14px'},
               'These answer files drive unattended installs. Attach one to a ' +
               'host pin (Hosts tab) or a queued device (Queue → Profile); on ' +
@@ -1210,11 +1466,11 @@
         ]),
       ]);
 
-      return el('div', {}, [el('div', {class:'grid'}, [
+      const root = el('div', {}, [el('div', {class:'grid'}, [
         diskCard,
         el('div', {class:'card'}, [
           el('header', {}, el('h2', {}, 'Upload ISO')),
-          el('div', {class:'body'}, [drop, file, prog, upMsg, cancelUpload]),
+          el('div', {class:'body'}, [drop, file, urlRow, uploadsList, fetchList]),
         ]),
         // v0.5.1: SMB + NFS unified into one "Remote shares" card with a
         // protocol dropdown. Backend endpoints are unchanged; this is a
@@ -1246,16 +1502,25 @@
             el('h2', {}, 'Available images'),
             el('span', {class:'sub'}, isos.length + ' image' + (isos.length === 1 ? '' : 's')),
           ]),
+          isos.length > 1
+            ? el('div', {class:'list-search'}, el('label', {class:'field', style:'margin-bottom:0'}, isoSearch))
+            : null,
           isoTable,
+          isoPager,
         ]),
       ]), unattendedAdvanced]);
+      // v0.8.1: resume/kick URL-fetch progress polling; stop it on view swap.
+      root._cleanup = () => { if (fetchTimer) clearTimeout(fetchTimer); };
+      pollFetches();
+      return root;
     },
 
     hosts: async () => {
-      const [{ hosts = [] }, isos, bootLogRes, unattRes] = await Promise.all([
+      const [{ hosts = [] }, isos, bootLogRes, unattRes, rulesCfg] = await Promise.all([
         getJSON('/api/hosts'), getJSON('/api/isos'),
         getJSON('/api/boot-log').catch(() => ({ events: [] })),
         getJSON('/api/unattended').catch(() => ({ files: [] })),
+        getJSON('/api/boot-rules').catch(() => ({ rules: [], webhook_url: '' })),
       ]);
       const bootEvents = bootLogRes.events || [];
       const unattendedFiles = unattRes.files || [];
@@ -1270,8 +1535,22 @@
         {id: '_tools_menu',   title: '↳ Tools menu (built-in)'},
       ];
 
-      const macInput   = el('input', {type:'text', placeholder:'aa:bb:cc:dd:ee:ff', spellcheck:'false'});
+      const macInput   = el('input', {type:'text', placeholder:'aa:bb:cc:dd:ee:ff or aa:bb:cc', spellcheck:'false'});
       const labelInput = el('input', {type:'text', placeholder:'optional, e.g. "rack-3 spine"'});
+      // v0.7.2: the former separate "Boot rules" card folded into this
+      // form. A full MAC with no architecture saves a per-host pin
+      // exactly as before; a MAC *prefix* and/or an architecture saves a
+      // first-match-wins group rule instead. Same form, one mental model.
+      const archSel = el('select', {}, [
+        ['', 'any (this exact MAC)'], ['bios', 'BIOS'], ['uefi-x64', 'UEFI x64'],
+        ['uefi-ia32', 'UEFI IA32'], ['uefi-arm64', 'UEFI ARM64'],
+      ].map(([v, t]) => el('option', {value: v}, t)));
+      // v0.7.1's boot-binary pin keeps its home here too (auto = let the
+      // escalation ladder learn; shim = known Secure Boot fleet).
+      const binSel = el('select', {}, [
+        ['', 'auto (learn per machine)'], ['firmware', 'Firmware NIC'],
+        ['builtin', 'iPXE drivers'], ['shim', 'Secure Boot (shim)'],
+      ].map(([v, t]) => el('option', {value: v}, t)));
       const targetSel = el('select', {},
         [el('option', {value:''}, '— choose a target —')]
         .concat(reserved.map(t => el('option', {value: t.id}, t.title)))
@@ -1284,21 +1563,40 @@
       // hostname/IP templated into the served answer file.
       const profileFields = buildProfileFields({}, unattendedFiles, 'form-row cols-3');
 
+      const FULL_MAC = /^([0-9a-f]{2}[:-]){5}[0-9a-f]{2}$/i;
       const upsertBtn = el('button', {onclick: async () => {
-        if (!macInput.value || !targetSel.value) {
+        const mac = macInput.value.trim();
+        const isGroup = !!archSel.value || !!binSel.value || (mac !== '' && !FULL_MAC.test(mac));
+        if (!isGroup) {
+          // Exact-MAC pin — unchanged behavior.
+          if (!mac || !targetSel.value) {
             msg.textContent = 'MAC and target are required.'; msg.className = 'msg err'; return;
           }
           const r = await postJSON('/api/hosts', Object.assign({
-          mac: macInput.value, target: targetSel.value, label: labelInput.value,
+            mac, target: targetSel.value, label: labelInput.value,
           }, profileFields.read()));
-        if (r.ok) {
+          if (r.ok) { msg.textContent = 'Saved.'; msg.className = 'msg ok'; render('hosts'); }
-          msg.textContent = 'Saved.'; msg.className = 'msg ok';
+          else { msg.textContent = 'Save failed: ' + await r.text(); msg.className = 'msg err'; }
-          render('hosts');
+          return;
-        } else {
-          const t = await r.text();
-          msg.textContent = 'Save failed: ' + t; msg.className = 'msg err';
         }
-      }}, 'Bind MAC to target');
+        // Group rule (prefix and/or architecture). Per-host profile
+        // fields don't apply to a group — they're per-machine values.
+        if (!targetSel.value && !binSel.value) {
+          msg.textContent = 'A group rule needs a target or a boot binary.'; msg.className = 'msg err'; return;
+        }
+        const p = profileFields.read();
+        if (p.auto_hostname || p.auto_ip || p.unattended_file) {
+          msg.textContent = 'Auto-deploy fields are per-machine — clear them, or use a full MAC.'; msg.className = 'msg err'; return;
+        }
+        const cfg = await getJSON('/api/boot-rules').catch(() => ({rules: [], webhook_url: ''}));
+        (cfg.rules = cfg.rules || []).push({
+          mac_prefix: mac, arch: archSel.value, target: targetSel.value,
+          driver_mode: binSel.value, enabled: true, note: labelInput.value,
+        });
+        const r = await putJSON('/api/boot-rules', cfg);
+        if (r.ok) { msg.textContent = 'Group rule saved.'; msg.className = 'msg ok'; render('hosts'); }
+        else { msg.textContent = 'Save failed: ' + await r.text(); msg.className = 'msg err'; }
+      }}, 'Bind to target');
 
       const rows = hosts.map(h => {
         // v0.5.0: Wake-on-LAN. Only shown for bound hosts (this whole
@@ -1355,23 +1653,32 @@
         el('div', {class:'card'}, [
           el('header', {}, el('h2', {}, 'Pin MAC to boot target')),
           el('div', {class:'body'}, [
+            // v0.7.3: MAC · Label · Architecture · Boot binary share one
+            // 4-up row so the controls line up across the page; the
+            // per-field guidance that used to sit under them moved into the
+            // note below to keep the inputs flush. Target spans full width
+            // on its own line beneath them.
             el('div', {class:'form-row'}, [
-              el('label', {class:'field'}, [el('span', {class:'name'}, 'MAC address'), macInput]),
+              el('label', {class:'field'}, [el('span', {class:'name'}, 'MAC address or prefix'), macInput]),
               el('label', {class:'field'}, [el('span', {class:'name'}, 'Label (optional)'), labelInput]),
-              el('label', {class:'field', style:'grid-column:1 / -1'}, [
+              el('label', {class:'field'}, [el('span', {class:'name'}, 'Architecture (optional)'), archSel]),
+              el('label', {class:'field'}, [el('span', {class:'name'}, 'Boot binary (optional)'), binSel]),
+            ]),
+            el('label', {class:'field', style:'margin-top:14px'}, [
               el('span', {class:'name'}, 'Target'),
               targetSel,
-                el('span', {class:'hint'},
-                  'Built-in shortcuts skip the menu entirely. Per-ISO entries chain straight to the boot script.'),
-              ]),
             ]),
             el('div', {style:'margin-top:16px'}, profileFields.wrap),
             upsertBtn, msg,
             el('p', {class:'msg', style:'margin-top:14px'},
-              'When a client with a bound MAC requests boot.ipxe, OpenPXE ' +
+              'A full MAC pins one machine; a MAC prefix (OUI) or an architecture ' +
-              'short-circuits past the interactive menu and chains directly. ' +
+              'saves a first-match group rule. Pin the boot binary to “shim” for ' +
-              'If an unattended file is selected, the matching kernel argument ' +
+              'Secure Boot racks — zero failed boot cycles. When a matching client ' +
-              'is injected and the hostname/IP are templated into the answer file.'),
+              'requests boot.ipxe, OpenPXE short-circuits past the interactive menu ' +
+              'and chains directly; decision order is exact MAC pin → first matching ' +
+              'group rule → menu. If an unattended file is selected on a pin, the ' +
+              'matching kernel argument is injected and the hostname/IP are templated ' +
+              'into the answer file.'),
           ]),
         ]),
         el('div', {class:'card'}, [
@@ -1381,6 +1688,7 @@
           ]),
           table,
         ]),
+        groupRulesCard(rulesCfg, reserved.concat(targets)),
         el('div', {class:'card'}, [
           el('header', {}, [
             el('h2', {}, 'Host log'),
@@ -1543,7 +1851,7 @@
     },
 
     settings: async () => {
-      const [status, me, sso, notify, docs] = await Promise.all([
+      const [status, me, sso, notify, docs, apiKey] = await Promise.all([
         getJSON('/api/status'),
         getJSON('/api/me').catch(() => ({})),
         getJSON('/api/sso').catch(() => ({
@@ -1553,6 +1861,7 @@
         // fetches the notify config + API docs it needs too.
         getJSON('/api/notify').catch(() => ({ enabled:false, kind:'slack' })),
         getJSON('/api/docs').catch(() => ({ groups: [] })),
+        getJSON('/api/api-key').catch(() => ({ key:'', header:'x-api-key' })),
       ]);
 
       // ── Account card (Forms admin credentials, v0.4.5).
@@ -1866,7 +2175,7 @@
       // into a collapsible disclosure beneath the core settings cards —
       // webhook/email notifications + the API reference. Keeps Settings
       // clean by default while leaving the knobs one click away.
-      const [notifyCard, apiCard] = views._advancedCards(notify, docs);
+      const [notifyCard, apiCard] = views._advancedCards(notify, docs, apiKey);
       const advanced = el('details', {class:'advanced-disclosure', style:'margin-top:18px'}, [
         el('summary', {class:'advanced-summary'}, 'Advanced'),
         el('div', {class:'grid', style:'margin-top:14px'}, [notifyCard, apiCard]),
@@ -1881,7 +2190,7 @@
     // and the API reference. There is no longer an Advanced sidebar tab;
     // the Settings view folds these into a collapsible disclosure and
     // passes in the pre-fetched `notify` + `docs` payloads.
-    _advancedCards: (notify, docs) => {
+    _advancedCards: (notify, docs, apiKey) => {
 
       // ── Notification config ──
       const nMsg = el('div', {class:'msg', style:'margin-top:12px'});
@@ -1996,14 +2305,47 @@
         ]),
       ]);
 
-      // ── API reference (relocated from Settings) ──
+      // ── API key + reference (relocated from Settings) ──
       const groups = docs.groups || [];
+
+      // v0.8.0: operator API key. Paste into the `x-api-key` request
+      // header to drive /api/* from Postman / scripts without a browser
+      // session (full operator access). Read + rotate via /api/api-key.
+      const keyHeader = (apiKey && apiKey.header) || 'x-api-key';
+      const keyField = el('input', {type:'text', readonly:true,
+        value: (apiKey && apiKey.key) || '(unavailable)',
+        style:'width:100%;font-family:var(--mono)'});
+      const keyMsg = el('span', {class:'hint', style:'margin-left:10px'});
+      const copyKey = el('button', {class:'ghost', type:'button', onclick: async () => {
+        try { await navigator.clipboard.writeText(keyField.value); keyMsg.textContent = 'Copied to clipboard.'; }
+        catch { keyField.select(); keyMsg.textContent = 'Select the field and copy.'; }
+      }}, 'Copy');
+      const regenKey = el('button', {class:'danger', type:'button', style:'margin-left:8px',
+        onclick: async () => {
+          if (!confirm('Regenerate the API key? The current key stops working immediately and any client using it must be updated.')) return;
+          const r = await postJSON('/api/api-key/regenerate', {});
+          if (r.ok) { const j = await r.json(); keyField.value = j.key || ''; keyMsg.textContent = 'New key generated.'; }
+          else { keyMsg.textContent = 'Regenerate failed: ' + (await r.text()).slice(0, 120); }
+        }}, 'Regenerate');
+      const apiKeyBlock = el('div', {style:'padding:16px;border-bottom:1px solid var(--border)'}, [
+        el('label', {class:'field', style:'margin-bottom:10px'}, [
+          el('span', {class:'name'}, 'API key'),
+          keyField,
+          el('span', {class:'hint'}, [
+            'Send as the ', el('code', {}, keyHeader),
+            ' request header to call the API from Postman or scripts — full operator access, so keep it secret.',
+          ]),
+        ]),
+        el('div', {}, [copyKey, regenKey, keyMsg]),
+      ]);
+
       const apiCard = el('div', {class:'card'}, [
         el('header', {}, [
-          el('h2', {}, 'API reference'),
+          el('h2', {}, 'API'),
           el('span', {class:'sub'},
             groups.reduce((n, g) => n + (g.endpoints || []).length, 0) + ' endpoints'),
         ]),
+        apiKeyBlock,
         el('div', {class:'api-ref'},
           groups.length
             ? groups.map(g => el('div', {class:'group'}, [
@@ -2057,9 +2399,24 @@
         el('div', {class:'about-hero'}, [
           el('h2', {}, 'OpenPXE'),
           el('p', {class:'lead'},
-            'Air-gapped network PXE boot, container-native, that anyone can run. ' +
+            'The network-boot platform for modern infrastructure. Drop in an ISO ' +
-            'No CDN calls, no telemetry, no surprise external dependencies — ship ' +
+            'and every machine on your network — BIOS, UEFI, Secure Boot — can ' +
-            'the image once, run it forever.'),
+            'boot it, image from it, and install unattended. One container, one ' +
+            'static binary, nothing installed on clients, nothing leaving your network.'),
+          el('div', {style:'display:grid;grid-template-columns:repeat(3,1fr);gap:14px;margin:18px 0'}, [
+            ['Boot anything', 'Linux, Windows, hypervisors, rescue tools — uploaded ' +
+              'ISOs become menu entries automatically, served on demand from local ' +
+              'disk or your existing NFS, SMB, or SFTP libraries.'],
+            ['Adapt to every machine', 'Per-machine boot intelligence: firmware quirks, ' +
+              'NIC driver fallback, and a Microsoft-signed Secure Boot chain are ' +
+              'negotiated automatically and remembered — no toggles, no client prep.'],
+            ['Run it in production', 'SAML single sign-on, token-scoped answer files, ' +
+              'fleet routing rules, Wake-on-LAN, queued mass deployment, Prometheus ' +
+              'metrics. Built in Rust for boot infrastructure that cannot flinch.'],
+          ].map(([h, body]) => el('div', {}, [
+            el('h3', {style:'margin:0 0 6px;font-size:13.5px'}, h),
+            el('p', {class:'msg', style:'font-size:12px;margin:0'}, body),
+          ]))),
           el('div', {class:'who'}, [
             el('span', {}, 'Developer: '), el('strong', {}, 'Miles Ward'), el('br'),
             el('span', {}, 'Version: '), el('strong', {}, status.version || '?'), el('br'),
@@ -2070,15 +2427,16 @@
           ]),
           el('div', {style:'margin-top:18px'}, [updBtn, updMsg]),
           el('p', {class:'msg', style:'margin-top:18px'},
-            'iPXE is an internal implementation detail. Everything the firmware ' +
+            'Private by design: no telemetry, no CDN calls, no runtime ' +
-            'executes is generated from the settings on these tabs — there is no ' +
+            'dependencies on the outside world. Air-gapped labs, customer sites ' +
-            'hand-written .ipxe path anywhere in this product.'),
+            'without internet, and locked-down OpenShift clusters run the same ' +
+            'image, the same way, indefinitely.'),
           el('p', {class:'msg'},
-            'Vision: a deployment-grade tool that works on first try in the most ' +
+            'Principled by default: OpenPXE never asks an operator to install ' +
-            'awkward environments — air-gapped labs, customer sites without ' +
+            'test-signed drivers, modify a client’s trust store, or weaken ' +
-            'internet, OpenShift clusters with strict SCCs — without ever asking ' +
+            'Secure Boot. Everything the firmware executes is generated from the ' +
-            'an operator to install drivers signed with test certificates or to ' +
+            'settings on these tabs — there are no hand-written boot scripts to ' +
-            'flip "testsigning" on a target machine.'),
+            'maintain and no internals to learn.'),
         ]),
       ]);
 

deploy/docker/Dockerfile

@@ -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

docker-compose.yml

@@ -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

scripts/fetch-shim.sh

@@ -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