envseal 0.3.8

//! Whitelist policy data model and the binary-path resolver.
//!
//! [`Policy`] is the in-memory rule set. Canonical persistence is
//! [`Policy::save_sealed`] / [`Policy::load_sealed`] — AES-256-GCM
//! encrypted blob keyed off the master key with HKDF domain
//! separation (`b"policy.v1"`). The plaintext rules are NEVER
//! written to disk in 0.3.0+; the v0.2.x plaintext-with-HMAC layout
//! is read for back-compat (`policy.toml` + `# hmac = ...` comment)
//! and silently rewritten to `policy.sealed` on the next save.
//!
//! The legacy HMAC framing lives in [`super::hmac`] and is only
//! consulted on the back-compat read path.

use std::fs;
use std::path::{Path, PathBuf};

use serde::{Deserialize, Serialize};

use super::hmac::{compute_hmac, split_hmac};
use crate::error::Error;
use crate::vault::sealed_blob;

/// Domain string for [`sealed_blob::seal`] / [`unseal`]. Stable —
/// changing it is a format break across releases.
const POLICY_SEAL_DOMAIN: &[u8] = b"policy.v1";

/// The scope of a whitelist rule.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
#[non_exhaustive]
pub enum RuleScope {
    /// Binary is authorized for a specific secret only.
    Key,
    /// Binary is authorized for all secrets.
    All,
}

/// A single whitelist rule.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Rule {
    /// Absolute path to the authorized binary.
    pub binary: String,
    /// Secret name, or `"*"` for all secrets.
    pub secret: String,
    /// Whether this grants access to one key or all keys.
    pub scope: RuleScope,
    /// SHA-256 hash of the binary at the time it was approved.
    /// Used to detect binary replacement / PATH poisoning.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub binary_hash: Option<String>,
    /// Optional argv-binding fingerprint (see
    /// [`crate::execution::command_fingerprint`]). When present,
    /// this rule authorizes only invocations whose argv produces the same
    /// fingerprint. When absent (legacy / unscoped rule), the rule
    /// authorizes only no-argument invocations — argumented invocations
    /// are denied so an attacker who got a no-args approval cannot reuse
    /// it to run the binary with arbitrary flags.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub args_fingerprint: Option<String>,
    /// Unix timestamp (seconds since epoch) at which this rule
    /// stops authorizing the binary. `None` = forever (the v0.2
    /// default). Set when the operator picks a finite duration in
    /// the approval popup, OR when the active `SecurityConfig`
    /// `default_rule_expiry_secs` is non-zero. Expired rules are
    /// filtered out by [`Policy::is_authorized_with_args`] and
    /// re-prompt on next access.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub expires_at: Option<u64>,
}

impl Rule {
    /// `true` iff this rule has expired relative to `now_unix_secs`.
    /// Rules with no expiry never expire.
    #[must_use]
    pub fn is_expired(&self, now_unix_secs: u64) -> bool {
        self.expires_at.is_some_and(|t| now_unix_secs >= t)
    }
}

/// The complete policy file.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct Policy {
    /// Whitelist rules.
    #[serde(default)]
    pub rules: Vec<Rule>,
    /// Monotonic generation counter incremented on every save.
    /// Detects rollback attacks where an attacker replaces the policy
    /// file with an older (revoked-rules) version.
    #[serde(default)]
    pub generation: u64,
}

impl Policy {
    /// Load policy from a file, or return an empty policy if the file
    /// doesn't exist.
    ///
    /// # Errors
    /// Returns [`Error::StorageIo`] / [`Error::PolicyParse`] on read or
    /// parse failure, [`Error::PolicyTampered`] if the path is a symlink.
    pub fn load(path: &Path) -> Result<Self, Error> {
        if !path.exists() {
            return Ok(Self::default());
        }
        crate::guard::verify_not_symlink(path)?;

        let content = fs::read_to_string(path)?;
        let (toml_content, stored_hmac) = split_hmac(&content);
        // SECURITY: If an HMAC is present, verify it. This prevents an
        // attacker from modifying a legacy policy.toml and having the
        // unsigned load path silently accept the tampered file.
        if stored_hmac.is_some() {
            // Load requires a master key for HMAC verification. Without
            // one we cannot verify, so we reject HMAC-signed files on
            // the unsigned load path to fail closed.
            return Err(Error::PolicyTampered(
                "legacy policy.toml contains an HMAC signature — use load_sealed instead"
                    .to_string(),
            ));
        }
        toml::from_str(toml_content).map_err(|e| Error::PolicyParse(e.to_string()))
    }

    /// Load policy from the sealed-blob file at `<dir>/policy.sealed`,
    /// falling back to a legacy plaintext-with-HMAC `<dir>/policy.toml`
    /// if no sealed file exists.
    ///
    /// `path` is the *legacy* path (`policy.toml`); this function
    /// derives the sealed-blob path as `path.with_extension("sealed")`
    /// so existing callers don't need to know about both names. Use
    /// [`sealed_path_for`] to compute the sealed path explicitly.
    ///
    /// # Errors
    /// `Error::PolicyTampered` for HMAC mismatch on the legacy path;
    /// `Error::CryptoFailure` for sealed-blob decrypt failure
    /// (wrong key / tampered ciphertext / version mismatch);
    /// `Error::PolicyParse` for malformed plaintext after a
    /// successful unseal / HMAC check.
    pub fn load_sealed(path: &Path, master_key: &[u8; 32]) -> Result<Self, Error> {
        let lock_path = path.with_extension("lock");
        crate::guard::verify_not_symlink(&lock_path)?;
        let _lock = advisory_lock::acquire(&lock_path, false)?;
        let sealed_path = sealed_path_for(path);
        if sealed_path.exists() {
            crate::guard::verify_not_symlink(&sealed_path)?;
            let blob = fs::read(&sealed_path)?;
            let plaintext = sealed_blob::unseal(&blob, master_key, POLICY_SEAL_DOMAIN)?;
            let s = std::str::from_utf8(&plaintext)
                .map_err(|e| Error::PolicyParse(format!("sealed policy not utf-8: {e}")))?;
            let policy: Policy =
                toml::from_str(s).map_err(|e| Error::PolicyParse(e.to_string()))?;
            return Ok(policy);
        }
        // Fall back to the v0.2.x plaintext + HMAC layout. On the
        // next save we'll rewrite as sealed and remove the legacy
        // file — see `save_sealed`.
        load_verified_legacy(path, master_key)
    }

    /// Back-compat alias for the v0.2.x name. Prefer
    /// [`Policy::load_sealed`] in new code.
    pub fn load_verified(path: &Path, master_key: &[u8; 32]) -> Result<Self, Error> {
        Self::load_sealed(path, master_key)
    }

    /// Save policy to a file (unsigned).
    ///
    /// # Errors
    /// Returns [`Error::PolicyParse`] / [`Error::StorageIo`] on serialization
    /// or write failure.
    pub fn save(&self, path: &Path) -> Result<(), Error> {
        let content =
            toml::to_string_pretty(self).map_err(|e| Error::PolicyParse(e.to_string()))?;
        fs::write(path, content)?;
        set_file_permissions(path)?;
        Ok(())
    }

    /// Save policy as an AES-256-GCM sealed blob at
    /// `path.with_extension("sealed")`. AEAD provides integrity AND
    /// confidentiality in one primitive — the file is opaque on disk,
    /// so an attacker who reads it learns nothing about which
    /// binaries / secrets are authorized.
    ///
    /// Migration: if a legacy `policy.toml` exists at `path`, this
    /// removes it AFTER the sealed write succeeds (atomic-ish — the
    /// new file is durable on disk before the old plaintext goes
    /// away). The next [`Policy::load_sealed`] call will find only
    /// the sealed file.
    ///
    /// # Errors
    /// [`Error::PolicyParse`] for serialization failure,
    /// [`Error::CryptoFailure`] for sealed-blob encrypt failure,
    /// [`Error::StorageIo`] for filesystem failure.
    pub fn save_sealed(&self, path: &Path, master_key: &[u8; 32]) -> Result<(), Error> {
        let lock_path = path.with_extension("lock");
        crate::guard::verify_not_symlink(&lock_path)?;
        let _lock = advisory_lock::acquire(&lock_path, true)?;
        let mut to_save = self.clone();
        // Drop expired rules before persisting — they don't authorize
        // anything (the auth check filters on read), and keeping them
        // in the file makes `envseal policy show` noisier than it
        // needs to be. Pruning at save time is the right place
        // because every save is a natural cleanup point.
        let _pruned = to_save.prune_expired();
        to_save.generation = to_save.generation.saturating_add(1);
        let raw =
            toml::to_string_pretty(&to_save).map_err(|e| Error::PolicyParse(e.to_string()))?;
        let blob = sealed_blob::seal(raw.as_bytes(), master_key, POLICY_SEAL_DOMAIN)?;
        let sealed_path = sealed_path_for(path);
        // Atomic write: temp file + rename so a crash or concurrent
        // writer never leaves a truncated policy on disk.
        let rnd = rand::random::<u64>();
        let tmp_path = sealed_path.with_extension(format!("sealed.{rnd:016x}.tmp"));
        #[cfg(unix)]
        {
            use std::io::Write;
            use std::os::unix::fs::OpenOptionsExt;
            let mut f = std::fs::OpenOptions::new()
                .create_new(true)
                .write(true)
                .mode(0o600)
                .open(&tmp_path)
                .map_err(Error::StorageIo)?;
            f.write_all(&blob).map_err(Error::StorageIo)?;
            f.sync_all().map_err(Error::StorageIo)?;
        }
        #[cfg(not(unix))]
        {
            fs::write(&tmp_path, &blob).map_err(Error::StorageIo)?;
            set_file_permissions(&tmp_path)?;
        }
        fs::rename(&tmp_path, &sealed_path)?;
        // Migration: delete legacy plaintext now that sealed is on
        // disk. Best-effort — a permissions error here doesn't lose
        // data because the sealed file is the canonical source from
        // here on.
        if path.exists() && path != sealed_path {
            let _ = fs::remove_file(path);
        }
        Ok(())
    }

    /// Back-compat alias for the v0.2.x name. Prefer
    /// [`Policy::save_sealed`] in new code.
    pub fn save_signed(&self, path: &Path, master_key: &[u8; 32]) -> Result<(), Error> {
        self.save_sealed(path, master_key)
    }

    /// Check whether a binary is authorized to access a specific secret,
    /// **without** considering argv binding.
    ///
    /// This is the legacy unscoped check. New code paths should prefer
    /// [`Policy::is_authorized_with_args`] so an approval for a specific
    /// command pattern (`wrangler deploy`) cannot be reused for a
    /// different one (`wrangler --shell evil.sh`).
    #[must_use]
    pub fn is_authorized(&self, binary_path: &str, secret_name: &str) -> bool {
        let now = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map_or(0, |d| d.as_secs());
        self.rules
            .iter()
            .any(|rule| !rule.is_expired(now) && rule_matches(rule, binary_path, secret_name, None))
    }

    /// Argv-bound authorization check.
    ///
    /// `args_fingerprint = None` means "the caller is invoking the binary
    /// with no arguments" — semantically equivalent to
    /// [`crate::execution::command_fingerprint`] returning `""`.
    /// `args_fingerprint = Some(fp)` means "the caller is invoking with
    /// argv that fingerprints to `fp`."
    ///
    /// Authorization rules:
    ///
    /// - A rule with `args_fingerprint = Some(stored)` matches if and
    ///   only if `stored == fp`. (`None` callers never match scoped rules.)
    /// - A rule with `args_fingerprint = None` (legacy / unscoped) is
    ///   conservative: it authorizes **only** the no-argument case.
    ///   Argumented invocations against a legacy rule are denied so users
    ///   who approved `wrangler` once can't have that approval transparently
    ///   apply to `wrangler --some-flag`.
    ///
    /// Argv-bound authorization check with optional binary-hash binding.
    ///
    /// `current_hash` should be the SHA-256 of the binary on disk right
    /// now. When `Some(hash)` is provided, any rule that has a stored
    /// `binary_hash` must match `hash` or it is rejected. This closes
    /// the swap attack where an attacker replaces an approved binary.
    #[must_use]
    pub fn is_authorized_with_hash_and_args(
        &self,
        binary_path: &str,
        secret_name: &str,
        args_fingerprint: Option<&str>,
        current_hash: Option<&str>,
    ) -> bool {
        let now = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map_or(0, |d| d.as_secs());
        self.rules.iter().any(|rule| {
            if rule.is_expired(now) {
                return false;
            }
            if !rule_matches(rule, binary_path, secret_name, current_hash) {
                return false;
            }
            match (rule.args_fingerprint.as_deref(), args_fingerprint) {
                (Some(stored), Some(fp)) => stored == fp,
                (None, None) => true,
                _ => false,
            }
        })
    }

    /// Convenience wrapper that authorizes without binary-hash binding.
    /// Production injection paths should prefer
    /// [`Self::is_authorized_with_hash_and_args`] so that tampered
    /// binaries are rejected.
    #[must_use]
    pub fn is_authorized_with_args(
        &self,
        binary_path: &str,
        secret_name: &str,
        args_fingerprint: Option<&str>,
    ) -> bool {
        self.is_authorized_with_hash_and_args(binary_path, secret_name, args_fingerprint, None)
    }

    /// Drop every expired rule from the policy. Returns the number
    /// removed so callers can decide whether to surface the cleanup
    /// (audit log, doctor report, etc.). Idempotent.
    pub fn prune_expired(&mut self) -> usize {
        let now = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map_or(0, |d| d.as_secs());
        let before = self.rules.len();
        self.rules.retain(|r| !r.is_expired(now));
        before - self.rules.len()
    }

    /// Get the stored hash for a binary, if any non-expired rule has one.
    #[must_use]
    pub fn binary_hash(&self, binary_path: &str) -> Option<String> {
        let now = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map_or(0, |d| d.as_secs());
        self.rules
            .iter()
            .find(|r| r.binary == binary_path && r.binary_hash.is_some() && !r.is_expired(now))
            .and_then(|r| r.binary_hash.clone())
    }

    /// Add a rule granting a binary access to a specific secret.
    ///
    /// Deduplicates: if an identical or broader rule exists, this is a no-op.
    pub fn allow_key(&mut self, binary_path: &str, secret_name: &str) {
        self.allow_key_with_hash(binary_path, secret_name, "");
    }

    /// Add a key-scoped rule with a verified binary hash. The rule has no
    /// argv-binding fingerprint (legacy / unscoped behavior — see
    /// [`Self::allow_key_with_hash_and_args`] for the bound variant).
    pub fn allow_key_with_hash(&mut self, binary_path: &str, secret_name: &str, hash: &str) {
        self.allow_key_with_hash_and_args(binary_path, secret_name, hash, None);
    }

    /// Add a key-scoped rule with both a verified binary hash and an
    /// argv-binding fingerprint.
    ///
    /// `args_fingerprint = None` records the rule as legacy/unscoped (the
    /// behavior of [`Self::allow_key_with_hash`]); `Some(fp)` scopes the
    /// approval to the exact argv pattern that produced `fp`.
    pub fn allow_key_with_hash_and_args(
        &mut self,
        binary_path: &str,
        secret_name: &str,
        hash: &str,
        args_fingerprint: Option<String>,
    ) {
        // Already authorized for this exact (binary, secret, args) combination?
        if self.is_authorized_with_hash_and_args(
            binary_path,
            secret_name,
            args_fingerprint.as_deref(),
            Some(hash).filter(|h| !h.is_empty()),
        ) {
            return;
        }

        let binary_hash = if hash.is_empty() {
            None
        } else {
            Some(hash.to_string())
        };

        self.rules.push(Rule {
            binary: binary_path.to_string(),
            secret: secret_name.to_string(),
            scope: RuleScope::Key,
            binary_hash,
            args_fingerprint,
            expires_at: None,
        });
    }

    /// Same as [`Self::allow_key_with_hash_and_args`] but stamps the
    /// rule with an expiry timestamp. Used by the popup path when
    /// the operator picks a finite duration ("Allow for 24h" /
    /// "Allow for 30 days") or when the active config sets a
    /// non-zero `default_rule_expiry_secs`.
    pub fn allow_key_with_expiry(
        &mut self,
        binary_path: &str,
        secret_name: &str,
        hash: &str,
        args_fingerprint: Option<String>,
        expires_at_unix_secs: u64,
    ) {
        if self.is_authorized_with_hash_and_args(
            binary_path,
            secret_name,
            args_fingerprint.as_deref(),
            Some(hash).filter(|h| !h.is_empty()),
        ) {
            return;
        }
        let binary_hash = if hash.is_empty() {
            None
        } else {
            Some(hash.to_string())
        };
        self.rules.push(Rule {
            binary: binary_path.to_string(),
            secret: secret_name.to_string(),
            scope: RuleScope::Key,
            binary_hash,
            args_fingerprint,
            expires_at: Some(expires_at_unix_secs),
        });
    }

    /// Add a rule granting a binary access to ALL secrets.
    ///
    /// Removes any per-key rules for this binary (they're now redundant).
    pub fn allow_all(&mut self, binary_path: &str) {
        self.allow_all_with_hash(binary_path, "");
    }

    /// Add an all-scope rule with a verified binary hash.
    pub fn allow_all_with_hash(&mut self, binary_path: &str, hash: &str) {
        // Remove per-key rules for this binary (now subsumed).
        self.rules
            .retain(|r| !(r.binary == binary_path && r.scope == RuleScope::Key));

        let has_all = self
            .rules
            .iter()
            .any(|r| r.binary == binary_path && r.scope == RuleScope::All);

        if !has_all {
            let binary_hash = if hash.is_empty() {
                None
            } else {
                Some(hash.to_string())
            };

            self.rules.push(Rule {
                binary: binary_path.to_string(),
                secret: "*".to_string(),
                scope: RuleScope::All,
                binary_hash,
                args_fingerprint: None,
                expires_at: None,
            });
        }
    }

    /// Remove all rules for a specific binary.
    pub fn revoke_binary(&mut self, binary_path: &str) {
        self.rules.retain(|r| r.binary != binary_path);
    }

    /// Remove all rules mentioning a specific secret.
    pub fn revoke_secret(&mut self, secret_name: &str) {
        self.rules
            .retain(|r| !(r.scope == RuleScope::Key && r.secret == secret_name));
    }
}

/// Whether `rule` matches `(binary_path, secret_name)` ignoring argv binding.
fn rule_matches(
    rule: &Rule,
    binary_path: &str,
    secret_name: &str,
    current_hash: Option<&str>,
) -> bool {
    if rule.binary != binary_path {
        return false;
    }
    if rule.scope != RuleScope::All && rule.scope == RuleScope::Key && rule.secret != secret_name {
        return false;
    }
    // SECURITY: If the rule was created with a binary hash, the current
    // binary MUST match that hash. Without this check, an attacker who
    // replaces an approved binary on disk retains authorization.
    if let (Some(stored), Some(current)) = (rule.binary_hash.as_deref(), current_hash) {
        return stored == current;
    }
    if current_hash.is_some() {
        return false;
    }
    true
}

/// Resolve a command name to its absolute binary path.
///
/// Uses `which`-style PATH lookup with two anti-poisoning rules baked in:
///
/// 1. **Relative PATH entries are ignored.** A `PATH` of `.:bin` is treated
///    as `bin` only — an attacker dropping `evil-tool` into the cwd
///    cannot get it picked up just because someone has `.` on their PATH.
/// 2. **Non-executable candidates are skipped** even if they exist with
///    the right name, so `~/bin/fake-tool` with mode 0644 doesn't shadow a
///    real binary later in the search order.
///
/// On Windows, each PATH dir is also searched with every `PATHEXT`
/// suffix (`.EXE`, `.CMD`, `.BAT`, `.PS1`, …) appended unless the
/// caller already supplied an extension. Without this, `python`,
/// `node`, `npm`, and every other executable that lives as `*.exe`
/// or `*.cmd` would resolve to "binary not found in PATH" even
/// though the operator can run them at any shell prompt.
///
/// # Errors
/// Returns [`Error::BinaryResolution`] if the command can't be found or
/// can't be canonicalized, or if the only candidate found is not executable.
pub fn resolve_binary(cmd: &str) -> Result<String, Error> {
    // Absolute-path fast-path — accepts both Unix `/usr/bin/foo` and
    // Windows `C:\path\foo.exe` / UNC `\\server\share\foo.exe`.
    // `cmd.starts_with('/')` was Unix-only and silently dropped
    // Windows callers into the PATH-lookup branch, where the
    // already-absolute path was then "joined" with each PATH dir
    // (a no-op on Windows since absolute beats relative in
    // `Path::join`) and could match by accident — confusing to
    // debug. Just check is_absolute once, properly.
    if std::path::Path::new(cmd).is_absolute() {
        if std::path::Path::new(cmd).exists() {
            return Ok(cmd.to_string());
        }
        return Err(Error::BinaryResolution(format!(
            "binary does not exist: {cmd}"
        )));
    }

    let path_var = std::env::var("PATH").unwrap_or_default();
    let separator = if cfg!(target_os = "windows") {
        ';'
    } else {
        ':'
    };

    // Build the list of name suffixes to try in each PATH dir. On
    // Unix, only the bare name. On Windows, the bare name first
    // (catches `python` if a literal `python` file exists) and then
    // each PATHEXT entry — without this, `envseal inject ... -- python`
    // fails on every Windows install because Python is on disk as
    // `python.exe`, not `python`.
    let suffix_candidates: Vec<String> = if cfg!(target_os = "windows") {
        let mut v = vec![String::new()];
        let pathext =
            std::env::var("PATHEXT").unwrap_or_else(|_| ".COM;.EXE;.BAT;.CMD;.PS1".to_string());
        // Skip extension append when the user already supplied one
        // (e.g. `python.exe`) so we don't search for `python.exe.exe`.
        let already_has_ext = std::path::Path::new(cmd).extension().is_some();
        if !already_has_ext {
            for ext in pathext.split(';') {
                let ext = ext.trim();
                if ext.is_empty() {
                    continue;
                }
                v.push(ext.to_string());
            }
        }
        v
    } else {
        vec![String::new()]
    };

    for dir in path_var.split(separator) {
        // Anti-poisoning: skip relative PATH entries. `.`, empty string, or
        // any non-absolute directory is ignored so cwd-based attacks fail.
        let dir_path = std::path::Path::new(dir);
        if dir.is_empty() || !dir_path.is_absolute() {
            continue;
        }
        for suffix in &suffix_candidates {
            let name = if suffix.is_empty() {
                cmd.to_string()
            } else {
                format!("{cmd}{suffix}")
            };
            let candidate = dir_path.join(&name);
            if candidate.exists() {
                if !is_executable(&candidate) {
                    // A non-executable hit early in PATH is suspicious
                    // (could be a name-collision attack), but it
                    // shouldn't lock out a legitimate later match.
                    // Skip and keep searching.
                    continue;
                }
                return candidate
                    .canonicalize()
                    .map(|p| p.to_string_lossy().to_string())
                    .map_err(|e| {
                        Error::BinaryResolution(format!("cannot canonicalize {cmd}: {e}"))
                    });
            }
        }
    }

    Err(Error::BinaryResolution(format!(
        "binary not found in PATH: {cmd}"
    )))
}

/// Whether `path` points at an executable file the current process can run.
///
/// On Unix this means the owner/group/other-execute bit applicable to the
/// running uid is set. On Windows it means the file extension is in the
/// `PATHEXT` set (`.exe`, `.bat`, `.cmd`, …) or `PATHEXT` is empty.
fn is_executable(path: &std::path::Path) -> bool {
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let Ok(meta) = std::fs::metadata(path) else {
            return false;
        };
        if !meta.is_file() {
            return false;
        }
        meta.permissions().mode() & 0o111 != 0
    }

    #[cfg(windows)]
    {
        let Some(ext) = path
            .extension()
            .and_then(|e| e.to_str())
            .map(str::to_ascii_uppercase)
        else {
            return false;
        };
        let pathext =
            std::env::var("PATHEXT").unwrap_or_else(|_| ".COM;.EXE;.BAT;.CMD;.PS1".to_string());
        if pathext.trim().is_empty() {
            return std::fs::metadata(path).is_ok_and(|m| m.is_file());
        }
        let needle = format!(".{ext}");
        pathext
            .split(';')
            .any(|entry| entry.eq_ignore_ascii_case(&needle))
    }

    #[cfg(not(any(unix, windows)))]
    {
        std::fs::metadata(path).is_ok_and(|m| m.is_file())
    }
}

/// Set file permissions to "owner only" — the equivalent of 0o600 on Unix.
///
/// On Unix: `chmod 0o600`.
/// On Windows: replace the file's DACL with a single ACE granting full
/// access to the current user's primary token SID, with `PROTECTED_DACL`
/// to block ACL inheritance from the parent directory. This is the NTFS
/// equivalent of "no group, no world, owner only" — the assumptions a
/// 0o600 keyfile relies on.
/// Compute the canonical sealed-blob path for a legacy plaintext
/// policy path. `<dir>/policy.toml` → `<dir>/policy.sealed`.
#[must_use]
pub fn sealed_path_for(legacy_path: &Path) -> PathBuf {
    legacy_path.with_extension("sealed")
}

/// Read the v0.2.x plaintext-with-HMAC layout from `path` for
/// back-compat during the migration window. Used only by
/// [`Policy::load_sealed`] when no sealed file exists at the
/// canonical location.
fn load_verified_legacy(path: &Path, master_key: &[u8; 32]) -> Result<Policy, Error> {
    if !path.exists() {
        return Ok(Policy::default());
    }
    crate::guard::verify_not_symlink(path)?;
    let content = fs::read_to_string(path)?;
    let (toml_content, stored_hmac) = split_hmac(&content);
    let stored_hmac = stored_hmac.ok_or_else(|| {
        Error::PolicyTampered(
            "policy.toml has no HMAC signature — it may have been \
             created or modified outside envseal."
                .to_string(),
        )
    })?;
    let computed = compute_hmac(toml_content.as_bytes(), master_key)?;
    if !crate::guard::constant_time_eq(computed.as_bytes(), stored_hmac.as_bytes()) {
        return Err(Error::PolicyTampered(
            "policy.toml HMAC mismatch".to_string(),
        ));
    }
    toml::from_str(toml_content).map_err(|e| Error::PolicyParse(e.to_string()))
}

fn set_file_permissions(path: &Path) -> Result<(), Error> {
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        fs::set_permissions(path, fs::Permissions::from_mode(0o600))?;
    }

    #[cfg(windows)]
    {
        crate::policy::windows_acl::set_owner_only_dacl(path)?;
    }

    Ok(())
}

/// Advisory file-locking helper — prevents lost-update races when
/// multiple envseal processes read-modify-write the policy file
/// concurrently. Uses `flock` on Unix and `LockFile` on Windows.
mod advisory_lock {
    use crate::error::Error;
    use std::fs::File;
    use std::path::Path;

    pub fn acquire(path: &Path, exclusive: bool) -> Result<LockGuard, Error> {
        let file = File::options()
            .create(true)
            .truncate(false)
            .read(true)
            .write(true)
            .open(path)
            .map_err(Error::StorageIo)?;

        #[cfg(unix)]
        {
            use std::os::unix::io::AsRawFd;
            let op = if exclusive {
                libc::LOCK_EX
            } else {
                libc::LOCK_SH
            };
            let rc = unsafe { libc::flock(file.as_raw_fd(), op) };
            if rc != 0 {
                return Err(Error::StorageIo(std::io::Error::last_os_error()));
            }
        }

        #[cfg(windows)]
        {
            use std::os::windows::io::AsRawHandle;
            use windows_sys::Win32::Storage::FileSystem::LockFile;
            unsafe {
                let handle = file.as_raw_handle();
                if LockFile(handle, 0, 0, 0xFFFF_FFFF, 0xFFFF_FFFF) == 0 {
                    return Err(Error::StorageIo(std::io::Error::last_os_error()));
                }
            }
            let _ = exclusive; // Windows LockFile is always exclusive for our range
        }

        #[cfg(not(any(unix, windows)))]
        {
            let _ = exclusive;
        }

        Ok(LockGuard(file))
    }

    pub struct LockGuard(File);

    impl Drop for LockGuard {
        fn drop(&mut self) {
            #[cfg(unix)]
            {
                use std::os::unix::io::AsRawFd;
                unsafe {
                    libc::flock(self.0.as_raw_fd(), libc::LOCK_UN);
                }
            }

            #[cfg(windows)]
            {
                use std::os::windows::io::AsRawHandle;
                use windows_sys::Win32::Storage::FileSystem::UnlockFile;
                unsafe {
                    let handle = self.0.as_raw_handle();
                    UnlockFile(handle, 0, 0, 0xFFFF_FFFF, 0xFFFF_FFFF);
                }
            }
        }
    }
}