feat(capsule): read-only file-injection for sandboxed spawns

[joshuajbouw]

Linked Issue

Closes #881

Summary

Implements the generic, agent-neutral host primitive from #881: at process spawn, the host exposes host-verified, read-only bytes to a spawned child's existing OS sandbox (bwrap on Linux, Seatbelt on macOS). The motivating consumer is un-overridable per-spawn agent governance (a supervised agent reads a policy file a prompt-injected session cannot rewrite), but the host is content-opaque — it never parses the bytes, and it owns placement, so every agent-specific detail stays in the adapter and the kernel stays agent-neutral.

The capsule hands the host content bytes plus a placement describing how the child should find them. Two modes, both exposing the same verified bytes read-only:

• env-pointer(env-var) — the host materializes the snapshot at a host-owned path, exposes it read-only (Linux --ro-bind P P; macOS Seatbelt file-read* allow + a trailing file-write* deny on the literal), and sets the named env var on the child to that path. OS-agnostic (Linux + macOS); the host owns the path, so there's no caller-chosen target and no host write to a caller-named path. For agents whose un-overridable tier is reachable via an env-redirected file (Claude CLAUDE_CODE_MANAGED_SETTINGS_PATH, Gemini GEMINI_CLI_SYSTEM_SETTINGS_PATH).
• fixed-path(path) — the host --ro-binds the snapshot at an absolute in-sandbox path. Linux-only (bwrap remap); rejected on macOS with invalid-input (no remap; a host write to a caller-named path would be an escalation). For agents whose enforced tier is a fixed path with no env redirect (Codex /etc/codex/requirements.toml).

Changes

• astrid-workspace sandbox: RoInjection + ProcessSandboxConfig::with_ro_inject; Linux --ro-bind (after the writable bind, before --unshare-all); macOS Seatbelt (allow file-read* (literal target)) + trailing (deny file-write* (literal target)). SandboxCommand::wrap_with_injections (no-injection path byte-identical to wrap); non-empty injections on an unsandboxed platform fail secure.
• astrid-capsule host/process/inject.rs: BLAKE3-hash content, snapshot to a private TempDir (host-owned, outside every VFS mount), re-read and verify against the pin (closes the copy→expose TOCTOU); per placement, emit the sandbox bind spec and (for env-pointer) the host-set env var. RAII guard (the TempDir) cleans up on the child's lifetime owner: a local for spawn, the ManagedProcess for spawn-background, the registry entry (reaped by value) for spawn-persistent. The spawn audit records env:<var>=<hash> / path:<p>=<hash>. The host sets the env-pointer var authoritatively on the child (not via the inert guest spawn-request.env).
• WIT: the wit/ submodule is bumped to the file-injection commit and wit-staging is regenerated, so bindgen! produces SpawnRequest.file_injections, FileInjection { content, placement }, and InjectionPlacement.
• Validation: env-pointer var name non-empty / no = / no NUL; fixed-path absolute / no forbidden chars / no ..; per-injection content cap (1 MiB → too-large); empty file-injections is a zero-overhead no-op.

Test Plan

Automated

• cargo test --workspace passes
• No new clippy warnings (cargo clippy --workspace --all-features -- -D warnings)
• New unit tests: bwrap ro-bind positioning; macOS Seatbelt read-allow + trailing write-deny ordering; wrap_with_injections unsafe-path rejection; env-var-name and fixed-path (incl. ..) validation; write+verify roundtrip + integrity-mismatch detection; 0600 snapshot mode; empty-injections no-op.

Manual (optional)

Not applicable — no runtime behaviour change when file-injections is empty (every existing spawn); the injection path is exercised by the unit tests above.

Dependencies / merge order

Third leg of a contract-first change — merge in order:

1. RFC: Host ABI rfcs#22 (Host ABI RFC — "Read-only file injection")
2. feat(process): read-only file-injection in spawn-request wit#15 (canonical WIT)
3. Re-pin this PR's wit/ submodule from the pre-merge branch commit b8fdb6f to the wit@main merge commit, then merge this.

The CI submodule ↔ wit-staging dirty-check enforces the pin stays consistent.

Checklist

• Linked to an issue (host: generic per-spawn read-only file injection (hash-pinned, agent-neutral sandbox primitive) #881)
• CHANGELOG.md updated under [Unreleased]

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a secure, agent-neutral mechanism for injecting read-only files into sandboxed child processes. By snapshotting and verifying source files before exposing them within the sandbox, the host ensures that injected data remains immutable and protected from tampering by both the child process and the spawning principal's file system surface.

Highlights

• Read-only File Injection: Added support for host-verified, read-only file injection into sandboxed child processes, allowing for unmodifiable configuration or policy files.
• Security & Integrity: Implemented snapshotting, BLAKE3 hashing, and verification to close TOCTOU vulnerabilities, ensuring the injected bytes remain immutable.
• Platform Integration: Integrated with Linux bwrap via --ro-bind and macOS Seatbelt via read-allow and trailing write-deny rules.
• API Updates: Updated WIT definitions to include file-injections in the spawn-request, supporting all three process spawn tiers.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

---

A file is locked within the cage, A hash is checked upon the page. No write can touch the bytes inside, Where secrets and the policies hide.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces host-verified, read-only file injection for sandboxed child processes across Linux and macOS, updating the WIT definitions, sandbox configurations, and process spawning logic to support this feature. The review feedback highlights critical security improvements in the injection module, specifically addressing a potential symlink bypass on macOS due to uncanonicalized target paths, a symlink overwrite vulnerability when writing snapshots, and a potential Denial of Service (OOM) risk from reading unrestricted file sizes into memory.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The reject_target_within_vfs function checks if the target path starts with any of the VFS roots to prevent the capsule from modifying the injected file. However, it does not canonicalize the target path itself. If the target path contains symlinks that resolve to a location inside the VFS root, the prefix check can be bypassed, allowing the capsule to overwrite the injected file. Canonicalize the target path best-effort to resolve symlinks before performing the prefix check. Additionally, to prevent path traversal vulnerabilities, explicitly check for and reject paths containing parent directory components (..) before using Path::starts_with for validation, as starts_with does not normalize paths.

#[cfg(target_os = "macos")]
fn reject_target_within_vfs(state: &HostState, target: &str) -> Result<(), ErrorCode> {
    let target_path = std::path::Path::new(target);
    if target_path.components().any(|c| c == std::path::Component::ParentDir) {
        return Err(ErrorCode::BoundaryEscape);
    }
    let mut current = target_path.to_path_buf();
    let mut components = Vec::new();
    while !current.exists() {
        if let Some(parent) = current.parent() {
            if let Some(name) = current.file_name() {
                components.push(name.to_owned());
            }
            current = parent.to_path_buf();
        } else {
            break;
        }
    }
    let target_canon = if let Ok(canon) = current.canonicalize() {
        let mut r = canon;
        for c in components.into_iter().rev() {
            r.push(c);
        }
        r
    } else {
        target_path.to_path_buf()
    };

    let mut roots: Vec<std::path::PathBuf> = vec![state.workspace_root.clone()];
    if let Some(home) = state.effective_home() {
        roots.push(home.root.clone());
    }
    if let Some(tmp) = state.effective_tmp() {
        roots.push(tmp.root.clone());
    }
    for root in &roots {
        let canon = root.canonicalize().unwrap_or_else(|_| root.clone());
        if target_canon.starts_with(&canon) || target_canon.starts_with(root) {
            return Err(ErrorCode::BoundaryEscape);
        }
    }
    Ok(())
}

References

1. To prevent path traversal vulnerabilities, explicitly check for and reject paths containing parent directory components (..) before using Path::starts_with for validation, as starts_with does not normalize paths.

[gemini-code-assist]

When writing the injected file, write_private uses create(true).truncate(true). If the target path already exists as a symlink pointing to a critical system file, the host will follow the symlink and overwrite the target file. To prevent this, remove any existing file or symlink at the target path first, and use create_new(true) (which uses O_EXCL) to guarantee that a new file is created without following symlinks. Additionally, handle the result of the file system operations (such as removing the file) to prevent silent failures.

fn write_private(dest: &std::path::Path, bytes: &[u8]) -> Result<(), ErrorCode> {
    use std::io::Write as _;
    if let Err(e) = std::fs::remove_file(dest) {
        if e.kind() != std::io::ErrorKind::NotFound {
            return Err(ErrorCode::Unknown(format!("failed to remove existing file: {e}")));
        }
    }
    let mut opts = std::fs::OpenOptions::new();
    opts.write(true).create_new(true);
    #[cfg(unix)]
    {
        use std::os::unix::fs::OpenOptionsExt as _;
        opts.mode(0o600);
    }
    let mut f = opts
        .open(dest)
        .map_err(|e| ErrorCode::Unknown(format!("injection snapshot write failed: {e}")))?;
    f.write_all(bytes)
        .map_err(|e| ErrorCode::Unknown(format!("injection snapshot write failed: {e}")))?;
    Ok(())
}

References

1. Handle Result from file system operations to prevent silent failures or panics, especially in security-sensitive contexts such as creating sandbox profiles.

[gemini-code-assist]

The host reads the entire source file into memory using std::fs::read without checking its size. If a capsule specifies an extremely large file as the injection source, this can cause the host to run out of memory and crash. Enforce a reasonable file size limit (e.g., 4 MiB) before reading the file to prevent potential Out-Of-Memory errors and Denial of Service vulnerabilities.

Suggested change

	// Resolve + read-gate the source exactly as a `read-file` would.
	let physical =
	resolve_source_for_injection(state, &inj.source).map_err(|e| map_source_err(&e))?;
	let bytes = std::fs::read(&physical).map_err(|_| ErrorCode::InvalidInput)?;
	// Resolve + read-gate the source exactly as a `read-file` would.
	let physical =
	resolve_source_for_injection(state, &inj.source).map_err(|e| map_source_err(&e))?;
	let metadata = std::fs::metadata(&physical).map_err(|_| ErrorCode::InvalidInput)?;
	if metadata.len() > 4 * 1024 * 1024 {
	return Err(ErrorCode::TooLarge);
	}
	let bytes = std::fs::read(&physical).map_err(|_| ErrorCode::InvalidInput)?;

References

1. Before reading a file's entire content into memory, check its size against a reasonable limit to prevent potential Out-Of-Memory errors and Denial of Service vulnerabilities.

[joshuajbouw]

Addressed the review (61ac328): write_private now uses create_new (O_CREAT | O_EXCL) instead of create(truncate), so the snapshot write refuses any pre-existing entry or symlink at the destination rather than truncating through it — with a regression test. In practice the destination is always a fresh unique index under a host-private TempDir (unreachable by a guest), but this makes the freshness an enforced invariant.

The other two findings were already resolved in the amended commit: reject_target_within_vfs (macOS symlink bypass) is gone because non-Linux FixedPath is now rejected outright, and the unbounded-read/OOM concern doesn't apply — injected content is guest-supplied and capped at MAX_INJECTION_BYTES (1 MiB) before any fs work. Build + clippy + inject tests green.