Struct AdmittedTool 

pub struct AdmittedTool { /* private fields */ }

An executable with a retained byte identity and an admitted exact version.

Self::admit requires a consumer-supplied digest. Self::admit_version records the installed identity without authenticating it against a pin. Every execution rechecks digest/permission before spawning. Consumers must exclude concurrent writers to the executable and its parent directories: filesystem checks and exec are separate operations. This is not a file capability or verification of dynamic libraries, interpreters, or descendants.

Implementations

impl AdmittedTool

pub fn admit( spec: &ToolSpec<'_>, context: &ExecutionContext<'_>, limits: OutputLimits, ) -> Result<Self, ToolError>

Admit exact executable bytes before invoking the selected version command.

Errors

Rejects invalid inputs, non-executable files, digest/size mismatch, process failures, non-UTF-8 stdout, and a different successful version identity.

Examples found in repository

examples/inspect_git.rs (lines 62-72)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    use ic_host_process::provenance::{
        IgnoreSubmodules, StatusOptions, UntrackedFiles, capture_git,
    };
    use ic_host_process::tool::{AdmittedTool, ExecutionContext, OutputLimits, ToolSpec};

    use std::{ffi::OsString, io, path::PathBuf, time::Duration};

    let invalid = |message| io::Error::new(io::ErrorKind::InvalidInput, message);
    let mut args = std::env::args_os().skip(1);
    let mut required = || {
        args.next().ok_or_else(|| invalid(
        "usage: inspect_git TOOL SHA256 VERSION WORKDIR MAX_TOOL_BYTES MAX_STDOUT_BYTES MAX_STDERR_BYTES TIMEOUT_MS UNTRACKED SUBMODULES",
    ))
    };
    let executable = PathBuf::from(required()?);
    let digest = required()?
        .into_string()
        .map_err(|_| invalid("digest must be UTF-8"))?
        .parse()?;
    let version = required()?
        .into_string()
        .map_err(|_| invalid("version must be UTF-8"))?;
    let directory = PathBuf::from(required()?);
    let mut number = || -> Result<u64, Box<dyn std::error::Error>> {
        Ok(required()?
            .to_str()
            .ok_or_else(|| invalid("limits must be UTF-8"))?
            .parse()?)
    };
    let executable_bytes = number()?;
    let limits = OutputLimits {
        stdout: ic_host_process::tool::OutputLimit::Terminate(usize::try_from(number()?)?),
        stderr: ic_host_process::tool::OutputLimit::Terminate(usize::try_from(number()?)?),
        timeout: Some(Duration::from_millis(number()?)),
    };
    let untracked = match required()?.to_str() {
        Some("no") => UntrackedFiles::No,
        Some("normal") => UntrackedFiles::Normal,
        Some("all") => UntrackedFiles::All,
        _ => return Err(invalid("untracked must be no, normal or all").into()),
    };
    let ignore_submodules = match required()?.to_str() {
        Some("none") => IgnoreSubmodules::None,
        Some("untracked") => IgnoreSubmodules::Untracked,
        Some("dirty") => IgnoreSubmodules::Dirty,
        Some("all") => IgnoreSubmodules::All,
        _ => return Err(invalid("submodules must be none, untracked, dirty or all").into()),
    };
    if args.next().is_some() {
        return Err(invalid("unexpected argument").into());
    }
    // The example explicitly selects an empty environment; the library never
    // chooses environment exclusions or tool/version pins for a consumer.
    let context = ExecutionContext {
        current_dir: &directory,
        environment: &[],
    };
    let git = AdmittedTool::admit(
        &ToolSpec {
            executable: &executable,
            sha256: digest,
            executable_bytes,
            version_arguments: &[OsString::from("--version")],
            version_identity: &version,
        },
        &context,
        limits,
    )?;
    let observed = capture_git(
        &git,
        &context,
        StatusOptions {
            untracked,
            ignore_submodules,
        },
        limits,
    )?;
    println!("revision={}", observed.revision);
    println!("tree={}", observed.tree);
    println!("dirty={}", observed.is_dirty());
    println!("status_bytes={}", observed.status_identity.bytes);
    println!("status_sha256={}", observed.status_identity.sha256);
    Ok(())
}

pub fn admit_version( spec: &VersionSpec<'_>, context: &ExecutionContext<'_>, limits: OutputLimits, ) -> Result<Self, ToolError>

Admit an exact version and record the caller-trusted installed bytes.

For tools built locally, no portable published digest may exist. This entry hashes the executable within the supplied budget before running the version command. The resulting Self::identity is an observation, not a trusted published pin. All later runs reject changed bytes using the same verification and capture engine as Self::admit.

The caller must trust the installation before admission: the version command executes those bytes. Exact version output does not establish authenticity. No version ranges, tool installation or PATH search occur. The caller must exclude concurrent executable/directory writers.

Errors

Rejects invalid inputs, non-executable or oversized files, process failures, non-UTF-8 stdout and a different successful version identity.

pub fn path(&self) -> &Path

Canonical absolute path selected during admission.

pub const fn identity(&self) -> ArtifactIdentity

Retained raw executable identity.

With Self::admit_version, this is an observed identity, not proof of a published binary pin or trusted installation provenance.

pub fn version_identity(&self) -> &str

Successfully observed, trimmed version identity.

pub fn run( &self, arguments: &[OsString], context: &ExecutionContext<'_>, limits: OutputLimits, ) -> Result<ExecutionEvidence, ToolError>

Run once with a cleared, explicitly supplied environment and null stdin.

Stdout/stderr are drained fairly through nonblocking pipes without reader threads. On overflow/deadline the direct child is killed and reaped; pipe handles are closed without waiting for descendants to close their copies. Descendant processes remain caller-owned. This must not be interpreted as a rollback or safe automatic retry of a command with external effects.

Errors

Returns invalid-input or identity failures before execution, or an execution failure retaining bounded prefixes and cleanup outcomes.