From 6151a339db158d2ff4e2714d86c3947de359b796 Mon Sep 17 00:00:00 2001
From: Justin Schneck <j.schneck@peridio.com>
Date: Thu, 2 Jul 2026 17:32:06 -0400
Subject: [PATCH] overlay: opt-in build-time preprocessing of overlay files

Add `overlay: { preprocess: [globs] | true }` to run the existing
{{ env. }} / {{ config. }} / {{ avocado. }} interpolation over overlay file
*contents* at build time. This lets projects template a secret (such as a
claim token) into overlay files without an in-tree sed + restore dance that
risks leaving secrets in the working tree.

Overlay files are copied verbatim inside the SDK container, so a processed
copy is materialized on the host into `.avocado/overlay-staging/<label>/`
(gitignored scratch, inside the /opt/src bind mount) and the copy is pointed
there. Binary (non-UTF-8) files pass through verbatim; symlinks and mode bits
are preserved. Default off = byte-identical to today.

- interpolation: add preprocess_text (thin wrapper over interpolate_string)
- new utils/overlay_preprocess: PreprocessSpec, glob matcher, materializer,
  and a deterministic post-preprocess content digest
- wire into rootfs/initramfs (rootfs/install.rs) and sysext/confext
  (ext/build.rs) copy sites; local overlays only (remote-ext overlays warn+skip)
- stamps: fold the post-preprocess content digest into rootfs/initramfs/ext
  input hashes when preprocess is on, so a changed template value or an edited
  overlay file invalidates the build (verbatim overlays unchanged)
---
 src/commands/ext/build.rs       |  69 ++++-
 src/commands/rootfs/install.rs  |  45 ++-
 src/utils/interpolation/mod.rs  |  23 ++
 src/utils/mod.rs                |   1 +
 src/utils/overlay_preprocess.rs | 480 ++++++++++++++++++++++++++++++++
 src/utils/stamps.rs             | 141 +++++++++-
 6 files changed, 743 insertions(+), 16 deletions(-)
 create mode 100644 src/utils/overlay_preprocess.rs

diff --git a/src/commands/ext/build.rs b/src/commands/ext/build.rs
index 2da62140..18b2965a 100644
--- a/src/commands/ext/build.rs
+++ b/src/commands/ext/build.rs
@@ -21,6 +21,8 @@ use crate::utils::tui::{TaskId, TuiGuard};
 struct OverlayConfig {
     dir: String,
     mode: OverlayMode,
+    /// Opt-in `{{ }}` preprocessing of overlay file contents.
+    preprocess: crate::utils::overlay_preprocess::PreprocessSpec,
 }
 
 #[derive(Debug, Clone, PartialEq)]
@@ -554,12 +556,14 @@ impl ExtBuildCommand {
             })?;
 
         // Get overlay configuration
-        let overlay_config = ext_config.get("overlay").map(|v| {
+        let mut overlay_config = ext_config.get("overlay").map(|v| {
+            use crate::utils::overlay_preprocess::PreprocessSpec;
             if let Some(dir_str) = v.as_str() {
                 // Simple string format: overlay = "directory"
                 OverlayConfig {
                     dir: dir_str.to_string(),
                     mode: OverlayMode::Merge, // Default to merge mode
+                    preprocess: PreprocessSpec::None,
                 }
             } else if let Some(table) = v.as_mapping() {
                 // Table format: overlay = {dir = "directory", mode = "opaque"}
@@ -574,12 +578,17 @@ impl ExtBuildCommand {
                     _ => OverlayMode::Merge, // Default to merge mode
                 };
 
-                OverlayConfig { dir, mode }
+                OverlayConfig {
+                    dir,
+                    mode,
+                    preprocess: PreprocessSpec::from_overlay_value(v),
+                }
             } else {
                 // Fallback for invalid format
                 OverlayConfig {
                     dir: "overlay".to_string(),
                     mode: OverlayMode::Merge,
+                    preprocess: PreprocessSpec::None,
                 }
             }
         });
@@ -616,6 +625,58 @@ impl ExtBuildCommand {
             ExtensionLocation::Local { .. } => "/opt/src".to_string(),
         };
 
+        // Opt-in overlay preprocessing (local extensions only). Materialize an
+        // interpolated copy of the overlay on the host under
+        // `.avocado/overlay-staging/` and redirect the in-container copy to it,
+        // so `{{ ... }}` in overlay files is substituted without mutating the
+        // working tree. Remote-extension overlays live in the SDK volume (not on
+        // the host), so they can't be preprocessed here — warn and skip.
+        if let Some(oc) = overlay_config.as_mut() {
+            if oc.preprocess.is_enabled() {
+                match &extension_location {
+                    ExtensionLocation::Local { .. } => {
+                        let project_root = config.project_root(&self.config_path);
+                        let context = crate::utils::interpolation::AvocadoContext::from_main_config(
+                            parsed,
+                            Some(target.as_str()),
+                        );
+                        let label = format!(
+                            "ext-{}",
+                            self.extension
+                                .chars()
+                                .map(|c| if c.is_alphanumeric() || c == '-' || c == '_' {
+                                    c
+                                } else {
+                                    '_'
+                                })
+                                .collect::<String>()
+                        );
+                        if let Some(staging_rel_dir) =
+                            crate::utils::overlay_preprocess::materialize_preprocessed_overlay(
+                                &project_root,
+                                &oc.dir,
+                                &label,
+                                &oc.preprocess,
+                                parsed,
+                                &context,
+                            )?
+                        {
+                            oc.dir = staging_rel_dir;
+                        }
+                    }
+                    ExtensionLocation::Remote { name, .. } => {
+                        print_warning(
+                            &format!(
+                                "Overlay preprocessing is not supported for remote extension \
+                                 '{name}'; copying overlay verbatim."
+                            ),
+                            OutputLevel::Normal,
+                        );
+                    }
+                }
+            }
+        }
+
         // Run the post_build hook before sealing any .raw images. By this
         // point the ext sysroot has been populated by `avocado install` and
         // any compile-dep install scripts above, so the hook can freely
@@ -1913,6 +1974,7 @@ mod tests {
         let overlay_config = OverlayConfig {
             dir: "peridio".to_string(),
             mode: OverlayMode::Merge,
+            preprocess: crate::utils::overlay_preprocess::PreprocessSpec::None,
         };
         let script = cmd.create_sysext_build_script(
             "1.0",
@@ -1955,6 +2017,7 @@ mod tests {
         let overlay_config = OverlayConfig {
             dir: "peridio".to_string(),
             mode: OverlayMode::Merge,
+            preprocess: crate::utils::overlay_preprocess::PreprocessSpec::None,
         };
         let script = cmd.create_confext_build_script(
             "1.0",
@@ -1997,6 +2060,7 @@ mod tests {
         let overlay_config = OverlayConfig {
             dir: "peridio".to_string(),
             mode: OverlayMode::Opaque,
+            preprocess: crate::utils::overlay_preprocess::PreprocessSpec::None,
         };
         let script = cmd.create_sysext_build_script(
             "1.0",
@@ -2040,6 +2104,7 @@ mod tests {
         let overlay_config = OverlayConfig {
             dir: "peridio".to_string(),
             mode: OverlayMode::Opaque,
+            preprocess: crate::utils::overlay_preprocess::PreprocessSpec::None,
         };
         let script = cmd.create_confext_build_script(
             "1.0",
diff --git a/src/commands/rootfs/install.rs b/src/commands/rootfs/install.rs
index cb21bdbf..76d5f24a 100644
--- a/src/commands/rootfs/install.rs
+++ b/src/commands/rootfs/install.rs
@@ -656,21 +656,46 @@ pub async fn install_sysroot(params: &mut SysrootInstallParams<'_>) -> Result<()
 
     // Build optional overlay snippet — appended to the install command so it
     // runs in the same container invocation immediately after DNF finishes.
-    let overlay_snippet = params
-        .parsed
-        .and_then(|parsed| {
+    let overlay_snippet = {
+        let overlay_value = params.parsed.and_then(|parsed| {
             let key = match params.sysroot_type {
                 SysrootType::Rootfs => "rootfs",
                 SysrootType::Initramfs => "initramfs",
                 _ => return None,
             };
-            parsed.get(key)?.get("overlay")
-        })
-        .map(|v| {
-            let (dir, opaque) = parse_overlay_config(v);
-            build_overlay_script(&dir, opaque, sysroot_dir)
-        })
-        .unwrap_or_default();
+            parsed.get(key)?.get("overlay").cloned()
+        });
+        if let (Some(v), Some(parsed)) = (overlay_value, params.parsed) {
+            let (dir, opaque) = parse_overlay_config(&v);
+            // Opt-in preprocessing: materialize an interpolated copy of the
+            // overlay on the host under `.avocado/overlay-staging/` and copy
+            // from there, so `{{ ... }}` in overlay files is substituted without
+            // mutating the working tree.
+            let spec = crate::utils::overlay_preprocess::PreprocessSpec::from_overlay_value(&v);
+            let effective_dir = if spec.is_enabled() {
+                let context = crate::utils::interpolation::AvocadoContext::from_main_config(
+                    parsed,
+                    Some(params.target),
+                );
+                match crate::utils::overlay_preprocess::materialize_preprocessed_overlay(
+                    params.src_dir,
+                    &dir,
+                    sysroot_dir,
+                    &spec,
+                    parsed,
+                    &context,
+                )? {
+                    Some(staging_rel_dir) => staging_rel_dir,
+                    None => dir,
+                }
+            } else {
+                dir
+            };
+            build_overlay_script(&effective_dir, opaque, sysroot_dir)
+        } else {
+            String::new()
+        }
+    };
 
     let exclude_str = if off_kernel_excludes.is_empty() {
         String::new()
diff --git a/src/utils/interpolation/mod.rs b/src/utils/interpolation/mod.rs
index e555169f..899345ce 100644
--- a/src/utils/interpolation/mod.rs
+++ b/src/utils/interpolation/mod.rs
@@ -194,6 +194,29 @@ pub fn interpolate_config_with_context(
     Ok(())
 }
 
+/// Preprocess `{{ ... }}` templates inside arbitrary file contents (e.g. an
+/// overlay file), using the same `env.`/`config.`/`avocado.` resolution as the
+/// YAML interpolator.
+///
+/// `root` is the composed config tree (for `{{ config.* }}`); `context` carries
+/// the resolved target/board/distro values (for `{{ avocado.* }}`). Missing
+/// `env.*` variables warn and resolve to an empty string, identical to
+/// `avocado.yaml` interpolation. Input that contains no templates is returned
+/// unchanged.
+pub fn preprocess_text(input: &str, root: &Value, context: &AvocadoContext) -> Result<String> {
+    let mut resolving_stack = HashSet::new();
+    let path: Vec<String> = Vec::new();
+    Ok(interpolate_string(
+        input,
+        root,
+        context,
+        &mut resolving_stack,
+        &path,
+        &YamlLocation::Value,
+    )?
+    .unwrap_or_else(|| input.to_string()))
+}
+
 /// Represents where in the YAML structure a template was found.
 #[derive(Clone, Debug)]
 enum YamlLocation {
diff --git a/src/utils/mod.rs b/src/utils/mod.rs
index 13e41cbb..221a8edd 100644
--- a/src/utils/mod.rs
+++ b/src/utils/mod.rs
@@ -16,6 +16,7 @@ pub mod lockfile;
 pub mod nfs_server;
 pub mod output;
 pub mod output_format;
+pub mod overlay_preprocess;
 pub mod permissions;
 pub mod pkcs11_devices;
 pub mod prerequisites;
diff --git a/src/utils/overlay_preprocess.rs b/src/utils/overlay_preprocess.rs
new file mode 100644
index 00000000..b98a6511
--- /dev/null
+++ b/src/utils/overlay_preprocess.rs
@@ -0,0 +1,480 @@
+//! Host-side materialization of preprocessed overlay trees.
+//!
+//! Overlay files are normally copied verbatim into the rootfs / initramfs /
+//! extension sysroot by a shell `cp` that runs inside the SDK container,
+//! reading the project tree bind-mounted at `/opt/src`. When an overlay opts
+//! into preprocessing (`overlay: { dir, preprocess: ... }`), we must apply
+//! `{{ ... }}` substitution to file contents *without* mutating the user's
+//! working tree. To do that we materialize a processed copy on the host into a
+//! scratch dir under the project root (`.avocado/overlay-staging/<label>/`,
+//! already inside the `/opt/src` bind mount) and point the `cp` at that copy.
+//!
+//! Only local overlays (those living in the project tree on the host) can be
+//! preprocessed; remote-extension overlays live inside the SDK volume and are
+//! copied verbatim (callers warn + skip).
+
+use anyhow::{Context, Result};
+use serde_yaml::Value;
+use std::path::Path;
+
+use crate::utils::interpolation::{preprocess_text, AvocadoContext};
+
+/// Scratch directory (relative to the project root) that holds materialized,
+/// preprocessed overlay trees. Lives under `.avocado/`, which is gitignored
+/// scratch after the lock file moved to the top-level `avocado.lock`.
+const STAGING_SUBDIR: &str = ".avocado/overlay-staging";
+
+/// Which overlay files to run the `{{ }}` preprocessor over.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum PreprocessSpec {
+    /// No preprocessing — copy the overlay verbatim (default, today's behavior).
+    None,
+    /// Preprocess every UTF-8 file in the overlay.
+    All,
+    /// Preprocess only files whose overlay-relative path matches one of these
+    /// globs (`*` within a segment, `**` across segments, `?` a single char).
+    Globs(Vec<String>),
+}
+
+impl PreprocessSpec {
+    /// True when any preprocessing is requested.
+    pub fn is_enabled(&self) -> bool {
+        !matches!(self, PreprocessSpec::None)
+    }
+
+    /// Parse the `preprocess` key from an `overlay:` mapping value. A bare
+    /// overlay string (no mapping) or an absent/false `preprocess` yields
+    /// [`PreprocessSpec::None`].
+    pub fn from_overlay_value(overlay: &Value) -> Self {
+        let Some(table) = overlay.as_mapping() else {
+            return PreprocessSpec::None;
+        };
+        match table.get("preprocess") {
+            Some(Value::Bool(true)) => PreprocessSpec::All,
+            Some(Value::Sequence(seq)) => {
+                let globs: Vec<String> = seq
+                    .iter()
+                    .filter_map(|v| v.as_str().map(str::to_string))
+                    .collect();
+                if globs.is_empty() {
+                    PreprocessSpec::None
+                } else {
+                    PreprocessSpec::Globs(globs)
+                }
+            }
+            _ => PreprocessSpec::None,
+        }
+    }
+
+    /// Whether the file at `rel_path` (overlay-relative, forward slashes) should
+    /// be preprocessed.
+    fn matches(&self, rel_path: &str) -> bool {
+        match self {
+            PreprocessSpec::None => false,
+            PreprocessSpec::All => true,
+            PreprocessSpec::Globs(globs) => globs.iter().any(|g| glob_matches(g, rel_path)),
+        }
+    }
+}
+
+/// Minimal glob matcher against a forward-slash relative path.
+/// `**` matches across separators, `*` matches within a segment, `?` matches a
+/// single non-separator character; all other characters match literally.
+fn glob_matches(pattern: &str, path: &str) -> bool {
+    let mut re = String::from("^");
+    let mut chars = pattern.chars().peekable();
+    while let Some(c) = chars.next() {
+        match c {
+            '*' => {
+                if chars.peek() == Some(&'*') {
+                    chars.next();
+                    re.push_str(".*");
+                    // Swallow an immediately-following '/' so `**/x` also matches `x`.
+                    if chars.peek() == Some(&'/') {
+                        chars.next();
+                    }
+                } else {
+                    re.push_str("[^/]*");
+                }
+            }
+            '?' => re.push_str("[^/]"),
+            c if "\\.+()|[]{}^$".contains(c) => {
+                re.push('\\');
+                re.push(c);
+            }
+            c => re.push(c),
+        }
+    }
+    re.push('$');
+    regex::Regex::new(&re)
+        .map(|r| r.is_match(path))
+        .unwrap_or(false)
+}
+
+/// Bytes to emit for one overlay file: preprocessed when the spec selects it and
+/// the content is valid UTF-8, otherwise the raw bytes unchanged. Binary files
+/// (non-UTF-8) are never templated, so ELF/images/certs pass through intact.
+fn process_file_bytes(
+    rel_path: &str,
+    raw: Vec<u8>,
+    spec: &PreprocessSpec,
+    root: &Value,
+    context: &AvocadoContext,
+) -> Result<Vec<u8>> {
+    if !spec.matches(rel_path) {
+        return Ok(raw);
+    }
+    match std::str::from_utf8(&raw) {
+        Ok(text) => Ok(preprocess_text(text, root, context)
+            .with_context(|| format!("Failed to preprocess overlay file '{rel_path}'"))?
+            .into_bytes()),
+        // Selected but not UTF-8 → copy verbatim (can't safely template).
+        Err(_) => Ok(raw),
+    }
+}
+
+/// Walk `overlay_src`, invoking `visit(rel_path, entry)` for every file and
+/// symlink in a deterministic (sorted) order. Directories are visited via their
+/// contained entries only.
+fn sorted_entries(overlay_src: &Path) -> Vec<walkdir::DirEntry> {
+    let mut entries: Vec<_> = walkdir::WalkDir::new(overlay_src)
+        .sort_by_file_name()
+        .into_iter()
+        .filter_map(|e| e.ok())
+        .collect();
+    entries.sort_by(|a, b| a.path().cmp(b.path()));
+    entries
+}
+
+fn rel_str(overlay_src: &Path, path: &Path) -> Option<String> {
+    let rel = path.strip_prefix(overlay_src).ok()?;
+    if rel.as_os_str().is_empty() {
+        return None;
+    }
+    // Forward-slash, lossy is fine (overlay paths are ASCII in practice).
+    Some(rel.to_string_lossy().replace('\\', "/"))
+}
+
+/// Compute a deterministic digest of the overlay tree *after* preprocessing,
+/// without materializing it to disk. Returns `None` when preprocessing is
+/// disabled or the overlay dir does not exist (so stamps are unchanged for the
+/// verbatim path). Folded into the rootfs/initramfs/ext build input hashes so a
+/// changed template value (e.g. a new claim token) or an edited overlay file
+/// forces a rebuild. Only the SHA-256 is retained — never the plaintext.
+pub fn overlay_content_digest(
+    project_root: &Path,
+    overlay_rel_dir: &str,
+    spec: &PreprocessSpec,
+    root: &Value,
+    context: &AvocadoContext,
+) -> Result<Option<String>> {
+    if !spec.is_enabled() {
+        return Ok(None);
+    }
+    let overlay_src = project_root.join(overlay_rel_dir);
+    if !overlay_src.is_dir() {
+        return Ok(None);
+    }
+
+    use sha2::{Digest, Sha256};
+    let mut hasher = Sha256::new();
+    for entry in sorted_entries(&overlay_src) {
+        let Some(rel) = rel_str(&overlay_src, entry.path()) else {
+            continue;
+        };
+        let ft = entry.file_type();
+        if ft.is_symlink() {
+            let target = std::fs::read_link(entry.path())
+                .map(|p| p.to_string_lossy().into_owned())
+                .unwrap_or_default();
+            hasher.update(format!("L\0{rel}\0{target}\0").as_bytes());
+        } else if ft.is_file() {
+            // Propagate read/preprocess errors rather than silently dropping the
+            // digest, which would let a broken overlay skip rebuild invalidation.
+            let raw = std::fs::read(entry.path()).with_context(|| {
+                format!("Failed to read overlay file: {}", entry.path().display())
+            })?;
+            let mode = file_mode(entry.path());
+            let bytes = process_file_bytes(&rel, raw, spec, root, context)?;
+            let file_hash = Sha256::digest(&bytes);
+            hasher.update(format!("F\0{rel}\0{mode:o}\0").as_bytes());
+            hasher.update(file_hash);
+        }
+    }
+    let out = hasher.finalize();
+    let mut hex = String::with_capacity(out.len() * 2);
+    for b in out.iter() {
+        use std::fmt::Write;
+        let _ = write!(hex, "{b:02x}");
+    }
+    Ok(Some(format!("sha256:{hex}")))
+}
+
+#[cfg(unix)]
+fn file_mode(path: &Path) -> u32 {
+    use std::os::unix::fs::PermissionsExt;
+    std::fs::metadata(path)
+        .map(|m| m.permissions().mode())
+        .unwrap_or(0o644)
+}
+
+#[cfg(not(unix))]
+fn file_mode(_path: &Path) -> u32 {
+    0o644
+}
+
+/// Materialize a preprocessed copy of `overlay_rel_dir` under
+/// `.avocado/overlay-staging/<label>/` in the project root, returning the
+/// staging dir *relative to the project root* (forward slashes) to hand the
+/// in-container copy — joined onto `/opt/src`.
+///
+/// Returns `Ok(None)` when preprocessing is disabled or the overlay dir is
+/// absent — callers then fall back to copying the original overlay verbatim.
+/// The staging dir is recreated fresh on every call (previous contents are
+/// removed), bounding secret residency to the most recent build; `.avocado/` is
+/// gitignored scratch and cleared by `avocado clean`.
+pub fn materialize_preprocessed_overlay(
+    project_root: &Path,
+    overlay_rel_dir: &str,
+    label: &str,
+    spec: &PreprocessSpec,
+    root: &Value,
+    context: &AvocadoContext,
+) -> Result<Option<String>> {
+    if !spec.is_enabled() {
+        return Ok(None);
+    }
+    let overlay_src = project_root.join(overlay_rel_dir);
+    if !overlay_src.is_dir() {
+        // Missing overlay dir is reported by the copy script itself; nothing to stage.
+        return Ok(None);
+    }
+
+    // Sanitize the label to a single safe path component (defense-in-depth):
+    // the staging dir is later removed with `remove_dir_all`, so never let a
+    // label containing path separators, `..`, or an absolute path escape the
+    // staging root.
+    let safe_label: String = label
+        .chars()
+        .map(|c| {
+            if c.is_ascii_alphanumeric() || c == '-' || c == '_' {
+                c
+            } else {
+                '_'
+            }
+        })
+        .collect();
+    let rel_dir = format!("{STAGING_SUBDIR}/{safe_label}");
+    let staging_dir = project_root.join(&rel_dir);
+
+    // Fresh staging tree each build.
+    if staging_dir.exists() {
+        std::fs::remove_dir_all(&staging_dir).with_context(|| {
+            format!(
+                "Failed to clear overlay staging dir: {}",
+                staging_dir.display()
+            )
+        })?;
+    }
+    std::fs::create_dir_all(&staging_dir).with_context(|| {
+        format!(
+            "Failed to create overlay staging dir: {}",
+            staging_dir.display()
+        )
+    })?;
+
+    for entry in sorted_entries(&overlay_src) {
+        let Some(rel) = rel_str(&overlay_src, entry.path()) else {
+            continue;
+        };
+        let dest = staging_dir.join(&rel);
+        let ft = entry.file_type();
+
+        if ft.is_dir() {
+            std::fs::create_dir_all(&dest)
+                .with_context(|| format!("Failed to create staging dir: {}", dest.display()))?;
+        } else if ft.is_symlink() {
+            if let Some(parent) = dest.parent() {
+                std::fs::create_dir_all(parent).with_context(|| {
+                    format!("Failed to create staging dir: {}", parent.display())
+                })?;
+            }
+            let target = std::fs::read_link(entry.path()).with_context(|| {
+                format!("Failed to read overlay symlink: {}", entry.path().display())
+            })?;
+            recreate_symlink(&target, &dest)?;
+        } else if ft.is_file() {
+            if let Some(parent) = dest.parent() {
+                std::fs::create_dir_all(parent).with_context(|| {
+                    format!("Failed to create staging dir: {}", parent.display())
+                })?;
+            }
+            let raw = std::fs::read(entry.path()).with_context(|| {
+                format!("Failed to read overlay file: {}", entry.path().display())
+            })?;
+            let bytes = process_file_bytes(&rel, raw, spec, root, context)?;
+            std::fs::write(&dest, &bytes)
+                .with_context(|| format!("Failed to write staged file: {}", dest.display()))?;
+            copy_mode(entry.path(), &dest);
+        }
+    }
+
+    Ok(Some(rel_dir))
+}
+
+#[cfg(unix)]
+fn recreate_symlink(target: &Path, dest: &Path) -> Result<()> {
+    std::os::unix::fs::symlink(target, dest)
+        .with_context(|| format!("Failed to create staged symlink: {}", dest.display()))
+}
+
+#[cfg(not(unix))]
+fn recreate_symlink(_target: &Path, _dest: &Path) -> Result<()> {
+    anyhow::bail!("Overlay preprocessing with symlinks is only supported on unix")
+}
+
+#[cfg(unix)]
+fn copy_mode(src: &Path, dest: &Path) {
+    use std::os::unix::fs::PermissionsExt;
+    if let Ok(meta) = std::fs::metadata(src) {
+        let _ = std::fs::set_permissions(
+            dest,
+            std::fs::Permissions::from_mode(meta.permissions().mode()),
+        );
+    }
+}
+
+#[cfg(not(unix))]
+fn copy_mode(_src: &Path, _dest: &Path) {}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn ctx() -> AvocadoContext {
+        AvocadoContext::from_main_config(&Value::Null, Some("qemux86-64"))
+    }
+
+    #[test]
+    fn spec_parsing() {
+        let all: Value = serde_yaml::from_str("dir: overlay\npreprocess: true").unwrap();
+        assert_eq!(
+            PreprocessSpec::from_overlay_value(&all),
+            PreprocessSpec::All
+        );
+
+        let globs: Value =
+            serde_yaml::from_str("dir: overlay\npreprocess:\n  - etc/x.toml").unwrap();
+        assert_eq!(
+            PreprocessSpec::from_overlay_value(&globs),
+            PreprocessSpec::Globs(vec!["etc/x.toml".to_string()])
+        );
+
+        let off: Value = serde_yaml::from_str("dir: overlay").unwrap();
+        assert_eq!(
+            PreprocessSpec::from_overlay_value(&off),
+            PreprocessSpec::None
+        );
+
+        let bare: Value = serde_yaml::from_str("\"overlay\"").unwrap();
+        assert_eq!(
+            PreprocessSpec::from_overlay_value(&bare),
+            PreprocessSpec::None
+        );
+    }
+
+    #[test]
+    fn glob_matching() {
+        assert!(glob_matches(
+            "etc/avocado-conn/config.toml",
+            "etc/avocado-conn/config.toml"
+        ));
+        assert!(glob_matches("etc/*.toml", "etc/config.toml"));
+        assert!(!glob_matches("etc/*.toml", "etc/sub/config.toml"));
+        assert!(glob_matches("**/*.toml", "etc/sub/config.toml"));
+        assert!(glob_matches("**/config.toml", "config.toml"));
+        assert!(!glob_matches("etc/*.toml", "etc/config.yaml"));
+    }
+
+    #[test]
+    fn materialize_templates_selected_utf8_only_and_preserves_binary() {
+        std::env::set_var("OVL_TEST_TOKEN", "s3cret");
+        let tmp = tempfile::tempdir().unwrap();
+        let root = tmp.path();
+        let overlay = root.join("overlay/etc");
+        std::fs::create_dir_all(&overlay).unwrap();
+        std::fs::write(
+            overlay.join("config.toml"),
+            "token = \"{{ env.OVL_TEST_TOKEN }}\"\n",
+        )
+        .unwrap();
+        // A non-selected file keeps its literal braces.
+        std::fs::write(
+            overlay.join("keep.txt"),
+            "literal {{ env.OVL_TEST_TOKEN }}\n",
+        )
+        .unwrap();
+        // A "binary" (invalid UTF-8) file, even if selected, is copied verbatim.
+        std::fs::write(overlay.join("blob.bin"), [0xff, 0xfe, 0x00, 0x01]).unwrap();
+
+        let spec = PreprocessSpec::Globs(vec!["etc/config.toml".into(), "etc/blob.bin".into()]);
+        let out = materialize_preprocessed_overlay(
+            root,
+            "overlay",
+            "rootfs",
+            &spec,
+            &Value::Null,
+            &ctx(),
+        )
+        .unwrap()
+        .expect("staging produced");
+
+        let staged = root.join(&out);
+        assert_eq!(
+            std::fs::read_to_string(staged.join("etc/config.toml")).unwrap(),
+            "token = \"s3cret\"\n"
+        );
+        assert_eq!(
+            std::fs::read_to_string(staged.join("etc/keep.txt")).unwrap(),
+            "literal {{ env.OVL_TEST_TOKEN }}\n"
+        );
+        assert_eq!(
+            std::fs::read(staged.join("etc/blob.bin")).unwrap(),
+            vec![0xff, 0xfe, 0x00, 0x01]
+        );
+    }
+
+    #[test]
+    fn digest_changes_with_template_value() {
+        std::env::set_var("OVL_DIGEST_TOKEN", "aaa");
+        let tmp = tempfile::tempdir().unwrap();
+        let root = tmp.path();
+        std::fs::create_dir_all(root.join("overlay/etc")).unwrap();
+        std::fs::write(
+            root.join("overlay/etc/config.toml"),
+            "token = \"{{ env.OVL_DIGEST_TOKEN }}\"\n",
+        )
+        .unwrap();
+        let spec = PreprocessSpec::Globs(vec!["etc/config.toml".into()]);
+
+        let h1 = overlay_content_digest(root, "overlay", &spec, &Value::Null, &ctx())
+            .unwrap()
+            .unwrap();
+        std::env::set_var("OVL_DIGEST_TOKEN", "bbb");
+        let h2 = overlay_content_digest(root, "overlay", &spec, &Value::Null, &ctx())
+            .unwrap()
+            .unwrap();
+        assert_ne!(h1, h2, "digest must change when a templated value changes");
+
+        // Disabled spec yields no digest (verbatim path unchanged).
+        assert!(overlay_content_digest(
+            root,
+            "overlay",
+            &PreprocessSpec::None,
+            &Value::Null,
+            &ctx()
+        )
+        .unwrap()
+        .is_none());
+    }
+}
diff --git a/src/utils/stamps.rs b/src/utils/stamps.rs
index 9ca1090e..3f00392f 100644
--- a/src/utils/stamps.rs
+++ b/src/utils/stamps.rs
@@ -892,6 +892,52 @@ fn script_hash_value(project_root: &Path, rel_path: &str) -> serde_yaml::Value {
     serde_yaml::Value::Mapping(m)
 }
 
+/// Fold a digest of an overlay's post-preprocessing tree into `hash_data` under
+/// `key`, but only when the overlay opts into preprocessing
+/// (`overlay: { ..., preprocess: ... }`). For verbatim overlays this is a no-op,
+/// preserving today's hashing (which keys only on the overlay config value, not
+/// file contents). When enabled, a changed template value (e.g. a new claim
+/// token) or an edited overlay file changes the digest and forces a rebuild.
+/// Only the SHA-256 is stored — never the resolved plaintext.
+fn fold_overlay_content_hash(
+    hash_data: &mut serde_yaml::Mapping,
+    key: &str,
+    overlay: &serde_yaml::Value,
+    config: &serde_yaml::Value,
+    project_root: &Path,
+) -> Result<()> {
+    use crate::utils::overlay_preprocess::PreprocessSpec;
+    let spec = PreprocessSpec::from_overlay_value(overlay);
+    if !spec.is_enabled() {
+        return Ok(());
+    }
+    let dir = overlay
+        .get("dir")
+        .and_then(|d| d.as_str())
+        .unwrap_or("overlay");
+    // Target resolves from env/config here (CLI target is None). This matches
+    // between stamp-write and stamp-check, and the stamp is already keyed per
+    // target (see `Stamp::rootfs_install(target, …)`), so `{{ avocado.target }}`
+    // in an overlay is constant within a given stamp; env values are captured
+    // regardless of target.
+    let context = crate::utils::interpolation::AvocadoContext::from_main_config(config, None);
+    // Propagate digest errors rather than dropping the content hash, which would
+    // let a broken overlay silently skip rebuild invalidation.
+    if let Some(digest) = crate::utils::overlay_preprocess::overlay_content_digest(
+        project_root,
+        dir,
+        &spec,
+        config,
+        &context,
+    )? {
+        hash_data.insert(
+            serde_yaml::Value::String(key.to_string()),
+            serde_yaml::Value::String(digest),
+        );
+    }
+    Ok(())
+}
+
 /// Compute input hash for SDK install
 ///
 /// Includes only inputs that affect the SDK toolchain install itself:
@@ -1038,7 +1084,7 @@ pub fn compute_ext_build_input_hash(
     ext_name: &str,
     project_root: &Path,
 ) -> Result<StampInputs> {
-    let hash_data = ext_build_hash_data(config, ext_name, project_root);
+    let hash_data = ext_build_hash_data(config, ext_name, project_root)?;
     let config_hash = compute_config_hash(&serde_yaml::Value::Mapping(hash_data))?;
     Ok(StampInputs::new(config_hash))
 }
@@ -1053,7 +1099,7 @@ pub fn compute_ext_image_input_hash(
     filesystem: Option<&str>,
     project_root: &Path,
 ) -> Result<StampInputs> {
-    let mut hash_data = ext_build_hash_data(config, ext_name, project_root);
+    let mut hash_data = ext_build_hash_data(config, ext_name, project_root)?;
 
     if let Some(ext) = config.get("extensions").and_then(|e| e.get(ext_name)) {
         if let Some(var_files) = ext.get("var_files") {
@@ -1087,7 +1133,7 @@ fn ext_build_hash_data(
     config: &serde_yaml::Value,
     ext_name: &str,
     project_root: &Path,
-) -> serde_yaml::Mapping {
+) -> Result<serde_yaml::Mapping> {
     let mut hash_data = serde_yaml::Mapping::new();
 
     if let Some(ext) = config.get("extensions").and_then(|e| e.get(ext_name)) {
@@ -1123,6 +1169,13 @@ fn ext_build_hash_data(
                 serde_yaml::Value::String(format!("ext.{ext_name}.overlay")),
                 overlay.clone(),
             );
+            fold_overlay_content_hash(
+                &mut hash_data,
+                &format!("ext.{ext_name}.overlay_content"),
+                overlay,
+                config,
+                project_root,
+            )?;
         }
         if let Some(post_build) = ext.get("post_build").and_then(|v| v.as_str()) {
             hash_data.insert(
@@ -1132,7 +1185,7 @@ fn ext_build_hash_data(
         }
     }
 
-    hash_data
+    Ok(hash_data)
 }
 
 /// Compute input hash for **rootfs install**.
@@ -1160,6 +1213,13 @@ pub fn compute_rootfs_input_hash(
                 serde_yaml::Value::String("rootfs.overlay".to_string()),
                 overlay.clone(),
             );
+            fold_overlay_content_hash(
+                &mut hash_data,
+                "rootfs.overlay_content",
+                overlay,
+                config,
+                project_root,
+            )?;
         }
         if let Some(post_install) = rootfs.get("post_install").and_then(|v| v.as_str()) {
             hash_data.insert(
@@ -1202,6 +1262,13 @@ pub fn compute_initramfs_input_hash(
                 serde_yaml::Value::String("initramfs.overlay".to_string()),
                 overlay.clone(),
             );
+            fold_overlay_content_hash(
+                &mut hash_data,
+                "initramfs.overlay_content",
+                overlay,
+                config,
+                project_root,
+            )?;
         }
         if let Some(post_install) = initramfs.get("post_install").and_then(|v| v.as_str()) {
             hash_data.insert(
@@ -3525,6 +3592,72 @@ rootfs:
         assert_ne!(h1, h2);
     }
 
+    #[test]
+    fn rootfs_preprocessed_overlay_value_change_invalidates() {
+        let tmp = tempfile::TempDir::new().unwrap();
+        std::fs::create_dir_all(tmp.path().join("overlay/etc")).unwrap();
+        std::fs::write(
+            tmp.path().join("overlay/etc/config.toml"),
+            "token = \"{{ env.STAMP_OVL_TOKEN }}\"\n",
+        )
+        .unwrap();
+
+        let config: serde_yaml::Value = serde_yaml::from_str(
+            r#"
+rootfs:
+  packages:
+    avocado-pkg-rootfs: "*"
+  overlay:
+    dir: overlay
+    preprocess:
+      - etc/config.toml
+"#,
+        )
+        .unwrap();
+
+        std::env::set_var("STAMP_OVL_TOKEN", "aaa");
+        let h1 = compute_rootfs_input_hash(&config, tmp.path())
+            .unwrap()
+            .config_hash;
+        std::env::set_var("STAMP_OVL_TOKEN", "bbb");
+        let h2 = compute_rootfs_input_hash(&config, tmp.path())
+            .unwrap()
+            .config_hash;
+
+        // Changing a value referenced by a preprocessed overlay file must
+        // invalidate the rootfs install hash so the image rebuilds.
+        assert_ne!(h1, h2);
+    }
+
+    #[test]
+    fn rootfs_verbatim_overlay_ignores_file_contents() {
+        // Without `preprocess`, the hash keys only on the overlay config value,
+        // not file contents (today's behavior) — no content digest is folded in.
+        let tmp = tempfile::TempDir::new().unwrap();
+        std::fs::create_dir_all(tmp.path().join("overlay/etc")).unwrap();
+        std::fs::write(tmp.path().join("overlay/etc/f.txt"), "v1").unwrap();
+
+        let config: serde_yaml::Value = serde_yaml::from_str(
+            r#"
+rootfs:
+  packages:
+    avocado-pkg-rootfs: "*"
+  overlay:
+    dir: overlay
+"#,
+        )
+        .unwrap();
+
+        let h1 = compute_rootfs_input_hash(&config, tmp.path())
+            .unwrap()
+            .config_hash;
+        std::fs::write(tmp.path().join("overlay/etc/f.txt"), "v2-different").unwrap();
+        let h2 = compute_rootfs_input_hash(&config, tmp.path())
+            .unwrap()
+            .config_hash;
+        assert_eq!(h1, h2);
+    }
+
     #[test]
     fn stamp_version_bump_invalidates_old_stamps() {
         let inputs = StampInputs::new("sha256:abc".to_string());