diff --git a/apps/rocm/src/engine_ipc.rs b/apps/rocm/src/engine_ipc.rs index d36318c7a..3c061bc26 100644 --- a/apps/rocm/src/engine_ipc.rs +++ b/apps/rocm/src/engine_ipc.rs @@ -177,6 +177,9 @@ const fn stdio_options<'a>( app_paths: paths, env_root, endpoint_key_file: None, + // An external plugin is a third-party binary: never hand it a path to + // a live endpoint credential, including one we inherited ourselves. + withhold_inherited_key_file: true, request_progress: stream_progress, forward_stderr: true, note_failing_exit_after_answer: false, @@ -385,6 +388,30 @@ mod tests { use super::*; use crate::tests::test_paths; + /// `rocm` must actually ASK for the withholding, not merely be able to. + /// + /// The protocol crate's own test proves the flag causes the clearing; this + /// is the other half of the chain, and without it flipping the value here + /// to `false` would re-open the leak with every test still green. Asserted + /// on `stdio_options` rather than on a built `Command` because + /// `engine_stdio_command` is private to the protocol crate. + #[test] + fn every_external_plugin_spawn_asks_to_withhold_the_endpoint_key_file() { + for stream_progress in [false, true] { + let options = stdio_options(None, None, stream_progress); + assert!( + options.withhold_inherited_key_file, + "an engine plugin is a third-party binary: `rocm` must withhold \ + an inherited key-file path from it, whatever else this request \ + asks for" + ); + assert!( + options.endpoint_key_file.is_none(), + "and it must never hand one over either" + ); + } + } + #[test] fn engine_plugin_discovery_finds_runtime_binary() -> Result<()> { let (root, paths) = test_paths("engine-plugin"); diff --git a/apps/rocmd/src/engine_ipc.rs b/apps/rocmd/src/engine_ipc.rs index f4749c3eb..eda8243ac 100644 --- a/apps/rocmd/src/engine_ipc.rs +++ b/apps/rocmd/src/engine_ipc.rs @@ -211,6 +211,10 @@ const fn stdio_options<'a>( app_paths: Some(paths), env_root: None, endpoint_key_file, + // `None` here means "this loopback service needs no key", not "this + // child may not see one" — these are the daemon's own children, and + // clearing would change what they inherit. + withhold_inherited_key_file: false, request_progress: false, forward_stderr: false, note_failing_exit_after_answer: true, diff --git a/crates/rocm-engine-protocol/src/stdio_client.rs b/crates/rocm-engine-protocol/src/stdio_client.rs index 5a8989e5a..2dd776d15 100644 --- a/crates/rocm-engine-protocol/src/stdio_client.rs +++ b/crates/rocm-engine-protocol/src/stdio_client.rs @@ -108,6 +108,15 @@ pub struct EngineStdioOptions<'a> { /// its HTTP probe of a protected endpoint authenticates. The caller decides /// whether a file holds a usable key; this only carries it. pub endpoint_key_file: Option<&'a Path>, + /// With no `endpoint_key_file`, also CLEAR [`ENDPOINT_API_KEY_FILE_ENV`] + /// rather than leave whatever this process inherited to pass through. + /// + /// For a child that must not see a credential path at all — `rocm`'s + /// external engine plugins are third-party binaries. Off by default, + /// because "no key file for this request" and "this child may not have one" + /// are different statements: `rocmd` passes `None` for a loopback service + /// that simply needs no key, and its children are its own. + pub withhold_inherited_key_file: bool, /// Ask the engine for progress on stderr ([`ENGINE_PROGRESS_STDERR_ENV`]). pub request_progress: bool, /// Write the child's stderr to this process's stderr as it arrives, so a @@ -155,6 +164,14 @@ where } if let Some(key_file) = options.endpoint_key_file { command.env(ENDPOINT_API_KEY_FILE_ENV, key_file); + } else if options.withhold_inherited_key_file { + // Cleared, not merely left unset: a value this process inherited must + // not reach a third-party plugin binary just because nothing + // overwrote it. Only for callers that ask — `rocmd` passes `None` for + // a loopback service that needs no key, and clearing there would + // change what its own children see. See + // `an_external_plugin_child_is_not_handed_the_endpoint_key_file`. + command.env_remove(ENDPOINT_API_KEY_FILE_ENV); } if options.request_progress { command.env(ENGINE_PROGRESS_STDERR_ENV, "1"); @@ -675,6 +692,68 @@ mod tests { assert!(added_env(&command).is_empty(), "{:?}", added_env(&command)); } + /// A child told it gets no endpoint key must have the variable CLEARED, + /// not merely left unset. + /// + /// `rocm` passes `endpoint_key_file: None` for every external engine + /// plugin — a third-party binary — and the path it would otherwise carry + /// points at a mode-0600 file holding a live endpoint credential. Merely + /// not setting it would still hand the value through whenever this process + /// inherited one. + /// + /// Asserts the distinction directly: `Command` records `env_remove` as an + /// explicit `(key, None)` entry, so a plain "is it absent" check would pass + /// even with the clearing deleted. + #[test] + fn an_external_plugin_child_is_not_handed_the_endpoint_key_file() { + let key_var = std::ffi::OsStr::new(ENDPOINT_API_KEY_FILE_ENV); + let command = engine_stdio_command( + Path::new("/an/engine"), + ["stdio"], + &EngineStdioOptions { + app_paths: None, + env_root: None, + endpoint_key_file: None, + withhold_inherited_key_file: true, + request_progress: false, + forward_stderr: false, + note_failing_exit_after_answer: false, + }, + ); + + let entry = command + .get_envs() + .find(|(key, _)| *key == key_var) + .map(|(_, value)| value); + assert_eq!( + entry, + Some(None), + "the key-file variable must be explicitly CLEARED when no key file \ + is passed, not merely left unset" + ); + + // The other direction, which is what keeps this scoped: a caller that + // did not ask (`rocmd`, for a loopback service that simply needs no + // key) must leave the child's inherited value alone. + let kept = engine_stdio_command( + Path::new("/an/engine"), + ["stdio"], + &EngineStdioOptions { + app_paths: None, + env_root: None, + endpoint_key_file: None, + withhold_inherited_key_file: false, + request_progress: false, + forward_stderr: false, + note_failing_exit_after_answer: false, + }, + ); + assert!( + kept.get_envs().all(|(key, _)| key != key_var), + "a caller that did not ask to withhold must not touch the variable" + ); + } + #[test] fn each_option_sets_exactly_its_own_variable() { let paths = AppPaths { @@ -689,6 +768,7 @@ mod tests { app_paths: Some(&paths), env_root: Some(Path::new("/envs")), endpoint_key_file: Some(Path::new("/keys/svc.endpoint-key")), + withhold_inherited_key_file: false, request_progress: true, forward_stderr: true, note_failing_exit_after_answer: false, @@ -722,6 +802,7 @@ mod tests { "ROCM_SERVE_API_KEY_FILE", EngineStdioOptions { endpoint_key_file: Some(Path::new("/keys/k")), + withhold_inherited_key_file: false, ..EngineStdioOptions::default() }, ), @@ -1143,6 +1224,7 @@ mod tests { app_paths: Some(&paths), env_root: Some(Path::new("/envs")), endpoint_key_file: Some(Path::new("/keys/k")), + withhold_inherited_key_file: false, request_progress: true, forward_stderr: false, note_failing_exit_after_answer: false, diff --git a/docs/architecture.md b/docs/architecture.md index fbd94b875..b020a6588 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -606,7 +606,7 @@ A contract surface: verify all impacted engines after any protocol change here ( | --- | --- | --- | | [`lib.rs`](../crates/rocm-engine-protocol/src/lib.rs) | The protocol contract: protocol versions, the request/response envelopes and per-method types, device and GPU-selection policy, engine-plugin discovery, the endpoint API key file carrier shared by `rocm` and `rocmd`, and `optional_arg`, the `flag value` argument helper both binaries build child command lines with. | flat | | [`fake_engine.rs`](../crates/rocm-engine-protocol/src/fake_engine.rs) | Test-only, behind the `test-support` feature the `rocm` and `rocmd` dev-dependencies turn on: a shell-script stand-in for an engine child that records its argv, environment and stdin and answers (or crashes) as a test asks, so both callers' tests run against the same fake. | flat | -| [`stdio_client.rs`](../crates/rocm-engine-protocol/src/stdio_client.rs) | The client side of the engine stdio protocol, the one implementation `rocm` and `rocmd` both run an engine child through: the request line, the child's environment (`EngineStdioOptions`: app paths, engine environments root, endpoint key file, progress request), stderr handling (kept for the error, optionally forwarded as it arrives), the SIGPIPE guard around the write and around each forward of the child's stderr, killing and reaping the child when its request cannot be written (the error then carries what it wrote to stderr) or its answer cannot be read, what a failing exit status or an unusable answer is reported as, and `decode_engine_response`. It sets no timeout, and does not bound the wait for the child's pipes after it exits (a grandchild holding one makes the request wait); its module comment states that limit. Each caller still chooses which program to run: `rocm` the resolved engine binary with `stdio` (or the built-in handler, with no child), `rocmd` the `rocm` executable with `__engine-stdio `. It adds no wire format; the envelope types are the ones in [`lib.rs`](../crates/rocm-engine-protocol/src/lib.rs). | flat | +| [`stdio_client.rs`](../crates/rocm-engine-protocol/src/stdio_client.rs) | The client side of the engine stdio protocol, the one implementation `rocm` and `rocmd` both run an engine child through: the request line, the child's environment (`EngineStdioOptions`: app paths, engine environments root, endpoint key file, whether to withhold an inherited key file from a child that is handed none, progress request), stderr handling (kept for the error, optionally forwarded as it arrives), the SIGPIPE guard around the write and around each forward of the child's stderr, killing and reaping the child when its request cannot be written (the error then carries what it wrote to stderr) or its answer cannot be read, what a failing exit status or an unusable answer is reported as, and `decode_engine_response`. It sets no timeout, and does not bound the wait for the child's pipes after it exits (a grandchild holding one makes the request wait); its module comment states that limit. Each caller still chooses which program to run: `rocm` the resolved engine binary with `stdio` (or the built-in handler, with no child), `rocmd` the `rocm` executable with `__engine-stdio `. It adds no wire format; the envelope types are the ones in [`lib.rs`](../crates/rocm-engine-protocol/src/lib.rs). | flat | ### `crates/rocm-deps`