From f3229ca6ff265f3e8ab6842b8f70480cf4a6ea2c Mon Sep 17 00:00:00 2001 From: Roman Sirokov Date: Wed, 11 Nov 2026 15:09:34 +0200 Subject: [PATCH 1/3] feat(engine): let a caller withhold an inherited endpoint key file MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit An engine plugin is a third-party binary. `rocm` spawns one with `endpoint_key_file: None`, which until now meant only "set no key" — so a `ROCM_SERVE_API_KEY_FILE` this process had inherited passed straight through to it, handing a third party the path to a mode-0600 file holding a live endpoint credential. Clearing it unconditionally on the `None` branch would have been wrong: the shared builder also serves `rocmd`, whose `None` means "this loopback service needs no key", not "this child may not see one" — those are its own children, and its `the_endpoint_key_file_reaches_the_child_only_when_it_holds_a_usable_key` expects a keyless child to inherit the ambient value. So the withholding is an explicit option the caller asks for. `rocm` sets it for plugin spawns; `rocmd` does not, and nothing about its behaviour changes — its test is untouched and still green. The test asserts CLEARED rather than absent, because `Command` records `env_remove` as an explicit `(key, None)` and a plain "is it present" check would pass with the clearing deleted. Both directions are pinned: a caller that asks gets the removal, one that does not gets no entry at all. Split out of #678 on review: it is hardening that stands on its own and is not part of ROCMAI-550. Signed-off-by: Roman Sirokov --- apps/rocm/src/engine_ipc.rs | 3 + apps/rocmd/src/engine_ipc.rs | 4 + .../rocm-engine-protocol/src/stdio_client.rs | 82 +++++++++++++++++++ 3 files changed, 89 insertions(+) diff --git a/apps/rocm/src/engine_ipc.rs b/apps/rocm/src/engine_ipc.rs index d36318c7a..bf25b2ee5 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, 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, From c12a8ab9d91b16aa49c677f66465df2469dd4826 Mon Sep 17 00:00:00 2001 From: Roman Sirokov Date: Wed, 11 Nov 2026 15:45:34 +0200 Subject: [PATCH 2/3] test(engine): pin that rocm asks to withhold the key file, not just that it can MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The protocol crate's test proves the flag causes the clearing, but it hand-builds the options — so flipping `rocm`'s own `withhold_inherited_key_file` to `false` re-opened the leak with every test still green. That is half a chain, and the untested half is the one a future edit would touch. Assert it at the call site. Verified by the mutation the test exists for: flipping the value turns it red. Over `stdio_options` rather than a built `Command`, because `engine_stdio_command` is private to the protocol crate and widening it for a test would trade a real API change for a marginally stronger assertion. Signed-off-by: Roman Sirokov --- apps/rocm/src/engine_ipc.rs | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/apps/rocm/src/engine_ipc.rs b/apps/rocm/src/engine_ipc.rs index bf25b2ee5..3c061bc26 100644 --- a/apps/rocm/src/engine_ipc.rs +++ b/apps/rocm/src/engine_ipc.rs @@ -388,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"); From bed02289f58e65ca6f5281af128c98d43b39da19 Mon Sep 17 00:00:00 2001 From: Roman Sirokov Date: Wed, 11 Nov 2026 18:30:32 +0200 Subject: [PATCH 3/3] docs(architecture): list the key-file withholding among EngineStdioOptions The `stdio_client.rs` entry enumerates the fields `EngineStdioOptions` threads to the child, and the field the two call sites deliberately differ on was missing from that list. `check-architecture-doc` reads no prose, so nothing would have caught it. Signed-off-by: Roman Sirokov --- docs/architecture.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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`