From faa6c95cfe84c01c32b37236371d5e0f6757ba68 Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 20 Nov 2026 13:56:08 +0800 Subject: [PATCH] fix(foreign): bind pinned environments to the executed provider A verified environment_dir was only prepended to PATH, so built-in providers still ran the host interpreter and external entrypoints could live outside the verified tree. - external entrypoints must resolve inside environment_dir - built-in providers cannot be bound to an environment (fail closed) - bound children get exactly the environment bin on PATH, no host fallback - declared interpreter_version is verified against the resolved program - built-in descriptors now also run environment validation - ADR-0020 + spec/foreign.md document the binding and limitations - positive/negative tests for binding, outside-entrypoint, builtin binding and version drift --- crates/marqdo-foreign/src/lib.rs | 230 ++++++++++++++----- crates/marqdo-foreign/tests/provider.rs | 167 +++++++++++--- docs/adr/0020-foreign-environment-binding.md | 61 +++++ spec/foreign.md | 35 ++- 4 files changed, 394 insertions(+), 99 deletions(-) create mode 100644 docs/adr/0020-foreign-environment-binding.md diff --git a/crates/marqdo-foreign/src/lib.rs b/crates/marqdo-foreign/src/lib.rs index a8e2b85..f5d348c 100644 --- a/crates/marqdo-foreign/src/lib.rs +++ b/crates/marqdo-foreign/src/lib.rs @@ -239,17 +239,15 @@ impl KernelRegistry { }); } } - if !descriptor.builtin { - if !descriptor.entrypoint.is_absolute() { - return Err(ForeignError::Protocol { - message: format!( - "external kernel provider `{}` entrypoint must be absolute", - descriptor.provider_id - ), - }); - } - verify_descriptor(&descriptor)?; + if !descriptor.builtin && !descriptor.entrypoint.is_absolute() { + return Err(ForeignError::Protocol { + message: format!( + "external kernel provider `{}` entrypoint must be absolute", + descriptor.provider_id + ), + }); } + verify_descriptor(&descriptor)?; for language in &mut descriptor.languages { *language = language.trim().to_ascii_lowercase(); if language.is_empty() { @@ -285,7 +283,7 @@ impl KernelRegistry { /// Detect a provider's executable and version. pub fn detect(&self, language: &str) -> Option { let descriptor = self.descriptor(language)?; - let program = resolve_program(descriptor)?; + let program = resolve_program(descriptor).ok()?; let version = if descriptor.builtin { probe_version(&program).unwrap_or_else(|| "unknown".to_string()) } else { @@ -474,20 +472,30 @@ fn sha256_file(path: &Path) -> Result { } fn verify_descriptor(descriptor: &KernelDescriptor) -> Result<(), ForeignError> { - if descriptor.builtin { - return Ok(()); - } - if let Some(expected) = &descriptor.digest { - let actual = sha256_file(&descriptor.entrypoint)?; - if &actual != expected { - return Err(ForeignError::Integrity { - provider: descriptor.provider_id.clone(), - expected: expected.clone(), - actual, - }); + if !descriptor.builtin { + if let Some(expected) = &descriptor.digest { + let actual = sha256_file(&descriptor.entrypoint)?; + if &actual != expected { + return Err(ForeignError::Integrity { + provider: descriptor.provider_id.clone(), + expected: expected.clone(), + actual, + }); + } } } if let Some(environment) = &descriptor.environment_dir { + if descriptor.builtin { + return Err(ForeignError::Protocol { + message: format!( + "built-in provider `{}` cannot be bound to environment_dir; \ + register an external provider whose entrypoint is the pinned \ + interpreter inside that environment", + descriptor.provider_id + ), + }); + } + verify_entrypoint_is_inside_environment(descriptor, environment)?; if !environment.is_absolute() || !environment.is_dir() { return Err(ForeignError::Protocol { message: format!( @@ -525,6 +533,47 @@ fn verify_descriptor(descriptor: &KernelDescriptor) -> Result<(), ForeignError> Ok(()) } +/// Reject an external provider whose executable is not inside its pinned +/// environment. This is what makes `environment_dir` an execution binding +/// instead of a decorative PATH hint. +fn verify_entrypoint_is_inside_environment( + descriptor: &KernelDescriptor, + environment: &Path, +) -> Result<(), ForeignError> { + if !descriptor.entrypoint.is_absolute() { + return Err(ForeignError::Protocol { + message: format!( + "external kernel provider `{}` entrypoint must be absolute", + descriptor.provider_id + ), + }); + } + let environment = fs::canonicalize(environment).map_err(|error| ForeignError::Protocol { + message: format!( + "cannot resolve kernel provider `{}` environment_dir: {error}", + descriptor.provider_id + ), + })?; + let entrypoint = match fs::canonicalize(&descriptor.entrypoint) { + Ok(path) => path, + // A missing entrypoint is reported as unavailable at execution time + // with an install hint; the lexical check below still rejects a + // manifest that points outside the environment. + Err(_) => descriptor.entrypoint.clone(), + }; + if !entrypoint.starts_with(&environment) { + return Err(ForeignError::Protocol { + message: format!( + "external kernel provider `{}` entrypoint `{}` is outside its pinned environment `{}`", + descriptor.provider_id, + descriptor.entrypoint.display(), + environment.display() + ), + }); + } + Ok(()) +} + fn environment_digest(root: &Path) -> Result { use sha2::{Digest, Sha256}; use walkdir::WalkDir; @@ -731,18 +780,23 @@ fn execute(request: &RunRequest, registry: &KernelRegistry) -> Result Result bool { } } -fn resolve_program(descriptor: &KernelDescriptor) -> Option { +/// Directory that holds executables inside a pinned environment. +fn environment_bin(environment: &Path) -> PathBuf { + if cfg!(windows) { + let scripts = environment.join("Scripts"); + if scripts.is_dir() { + return scripts; + } + environment.to_path_buf() + } else { + environment.join("bin") + } +} + +fn resolve_program(descriptor: &KernelDescriptor) -> Result { + if let Some(environment) = &descriptor.environment_dir { + // Built-ins were rejected at registration/verification; this branch is + // defense in depth. + if descriptor.builtin { + return Err(ForeignError::Protocol { + message: format!( + "built-in provider `{}` cannot be bound to environment_dir", + descriptor.provider_id + ), + }); + } + let entrypoint = fs::canonicalize(&descriptor.entrypoint) + .unwrap_or_else(|_| descriptor.entrypoint.clone()); + if !entrypoint + .starts_with(fs::canonicalize(environment).unwrap_or_else(|_| environment.clone())) + { + return Err(ForeignError::Protocol { + message: format!( + "external kernel provider `{}` entrypoint is outside its pinned environment", + descriptor.provider_id + ), + }); + } + if is_executable_file(&entrypoint) { + return Ok(entrypoint); + } + return Err(ForeignError::KernelUnavailable { + language: descriptor.provider_id.clone(), + hint: format!( + "pinned environment `{}` does not contain an executable provider at `{}`", + environment.display(), + descriptor.entrypoint.display() + ), + }); + } if !descriptor.builtin { if !descriptor.entrypoint.is_absolute() { - return None; + return Err(ForeignError::KernelUnavailable { + language: descriptor.provider_id.clone(), + hint: "external provider entrypoints must be absolute paths".to_string(), + }); } - return descriptor - .entrypoint - .is_file() - .then(|| descriptor.entrypoint.clone()) - .filter(|path| is_executable_file(path)); + if descriptor.entrypoint.is_file() && is_executable_file(&descriptor.entrypoint) { + return Ok(descriptor.entrypoint.clone()); + } + return Err(ForeignError::KernelUnavailable { + language: descriptor.provider_id.clone(), + hint: format!( + "external kernel provider `{}` executable `{}` is missing or not executable", + descriptor.provider_id, + descriptor.entrypoint.display() + ), + }); } - let path_var = std::env::var_os("PATH")?; + let path_var = std::env::var_os("PATH").ok_or_else(|| ForeignError::KernelUnavailable { + language: descriptor.provider_id.clone(), + hint: kernel_hint(&descriptor.provider_id).to_string(), + })?; let candidates = program_candidates(&descriptor.provider_id); for name in candidates { for directory in std::env::split_paths(&path_var) { let candidate = directory.join(name); if is_executable_file(&candidate) { - return Some(candidate); + return Ok(candidate); } } } - None + Err(ForeignError::KernelUnavailable { + language: descriptor.provider_id.clone(), + hint: kernel_hint(&descriptor.provider_id).to_string(), + }) } fn probe_version(program: &Path) -> Option { diff --git a/crates/marqdo-foreign/tests/provider.rs b/crates/marqdo-foreign/tests/provider.rs index 412da1e..5a6202f 100644 --- a/crates/marqdo-foreign/tests/provider.rs +++ b/crates/marqdo-foreign/tests/provider.rs @@ -139,51 +139,67 @@ fn provider_digest_is_verified_at_registration_and_execution() { } #[cfg(unix)] -#[test] -fn pinned_environment_digest_is_verified_before_execution() { +fn environment_digest(root: &std::path::Path) -> String { use sha2::{Digest, Sha256}; + let mut files = Vec::new(); + for entry in walkdir::WalkDir::new(root) + .follow_links(false) + .sort_by_file_name() + { + let entry = entry.unwrap(); + if entry.file_type().is_dir() { + continue; + } + let relative = entry.path().strip_prefix(root).unwrap(); + let path = relative + .components() + .map(|component| component.as_os_str().to_str().unwrap()) + .collect::>() + .join("/"); + files.push((path, std::fs::read(entry.path()).unwrap())); + } + files.sort_by(|a, b| a.0.cmp(&b.0)); + let mut hasher = Sha256::new(); + hasher.update(b"marqdo.kernel-environment.v1\0"); + hasher.update((files.len() as u64).to_le_bytes()); + for (path, bytes) in &files { + hasher.update((path.len() as u64).to_le_bytes()); + hasher.update(path.as_bytes()); + hasher.update((bytes.len() as u64).to_le_bytes()); + hasher.update(bytes); + } + hex::encode(hasher.finalize()) +} - let dir = tempfile::tempdir().unwrap(); - let script = mock_provider(dir.path()); - let env = dir.path().join("venv"); +/// Write a provider executable inside `env` and return its path. +#[cfg(unix)] +fn provider_inside_environment(env: &std::path::Path) -> std::path::PathBuf { + use std::os::unix::fs::PermissionsExt; std::fs::create_dir_all(env.join("bin")).unwrap(); - std::fs::write(env.join("marker.txt"), "env-v1").unwrap(); - let env_digest = { - let root = &env; - let mut files = Vec::new(); - for entry in walkdir::WalkDir::new(root) - .follow_links(false) - .sort_by_file_name() - { - let entry = entry.unwrap(); - if entry.file_type().is_dir() { - continue; - } - let relative = entry.path().strip_prefix(root).unwrap(); - let path = relative - .components() - .map(|component| component.as_os_str().to_str().unwrap()) - .collect::>() - .join("/"); - files.push((path, std::fs::read(entry.path()).unwrap())); - } - files.sort_by(|a, b| a.0.cmp(&b.0)); - let mut hasher = Sha256::new(); - hasher.update(b"marqdo.kernel-environment.v1\0"); - hasher.update((files.len() as u64).to_le_bytes()); - for (path, bytes) in &files { - hasher.update((path.len() as u64).to_le_bytes()); - hasher.update(path.as_bytes()); - hasher.update((bytes.len() as u64).to_le_bytes()); - hasher.update(bytes); - } - hex::encode(hasher.finalize()) - }; + let script = env.join("bin").join("mocklang.sh"); + std::fs::write( + &script, + "#!/bin/sh\nif [ \"$1\" = \"--version\" ]; then echo 'mocklang 1.0.0'; exit 0; fi\ncat >/dev/null\nprintf '%s' '{\"type\":\"int\",\"decimal\":\"42\"}'\n", + ) + .unwrap(); + let mut permissions = std::fs::metadata(&script).unwrap().permissions(); + permissions.set_mode(0o700); + std::fs::set_permissions(&script, permissions).unwrap(); + script +} + +#[cfg(unix)] +#[test] +fn pinned_environment_binds_the_provider_and_is_verified_before_execution() { + let dir = tempfile::tempdir().unwrap(); + let env = dir.path().join("venv"); + let script = provider_inside_environment(&env); + let digest = environment_digest(&env); let mut registry = KernelRegistry::builtin(); let mut descriptor = KernelDescriptor::external("mocklang", &["mocklang"], &script); descriptor.environment_id = Some("env-test".to_string()); - descriptor.environment_digest = Some(env_digest); + descriptor.environment_digest = Some(digest); descriptor.environment_dir = Some(env.clone()); registry.register(descriptor).unwrap(); let result = call_with_registry(&request("mocklang", "ignored"), ®istry).unwrap(); @@ -196,3 +212,78 @@ fn pinned_environment_digest_is_verified_before_execution() { "{error:?}" ); } + +/// A provider outside its pinned environment is a manifest error: the +/// environment would otherwise be verified while a different program runs. +#[cfg(unix)] +#[test] +fn provider_outside_pinned_environment_is_rejected() { + let dir = tempfile::tempdir().unwrap(); + let env = dir.path().join("venv"); + std::fs::create_dir_all(&env).unwrap(); + let script = mock_provider(dir.path()); + + let mut registry = KernelRegistry::builtin(); + let mut descriptor = KernelDescriptor::external("mocklang", &["mocklang"], &script); + descriptor.environment_digest = Some("0".repeat(64)); + descriptor.environment_dir = Some(env); + let error = registry.register(descriptor).unwrap_err(); + assert!(matches!(error, ForeignError::Protocol { .. }), "{error:?}"); + assert!(error.to_string().contains("outside its pinned environment")); +} + +/// A built-in interpreter cannot be silently rebound to a verified environment; +/// a pinned interpreter must be an explicit external provider. +#[cfg(unix)] +#[test] +fn builtin_provider_cannot_be_bound_to_an_environment() { + let dir = tempfile::tempdir().unwrap(); + let env = dir.path().join("venv"); + std::fs::create_dir_all(&env).unwrap(); + let mut registry = KernelRegistry::builtin(); + let mut descriptor = KernelDescriptor::builtin("mockpython", &["mockpython"], "python3"); + descriptor.environment_digest = Some("0".repeat(64)); + descriptor.environment_dir = Some(env); + let error = registry.register(descriptor).unwrap_err(); + assert!( + error + .to_string() + .contains("cannot be bound to environment_dir"), + "{error}" + ); +} + +/// A declared interpreter version must match the program that actually runs; +/// environment pinning that ignores version drift is not reproducible. +#[cfg(unix)] +#[test] +fn declared_interpreter_version_must_match_the_resolved_program() { + let dir = tempfile::tempdir().unwrap(); + let env = dir.path().join("venv"); + let script = provider_inside_environment(&env); + let digest = environment_digest(&env); + let mut registry = KernelRegistry::builtin(); + let mut descriptor = KernelDescriptor::external("mocklang", &["mocklang"], &script); + descriptor.environment_digest = Some(digest); + descriptor.environment_dir = Some(env); + descriptor.interpreter_version = Some("9.9.9".to_string()); + registry.register(descriptor).unwrap(); + + let error = call_with_registry(&request("mocklang", "ignored"), ®istry).unwrap_err(); + assert!(matches!(error, ForeignError::Protocol { .. }), "{error:?}"); + assert!(error.to_string().contains("interpreter version mismatch")); + + // A matching prefix is accepted. + let dir = tempfile::tempdir().unwrap(); + let env = dir.path().join("venv"); + let script = provider_inside_environment(&env); + let digest = environment_digest(&env); + let mut registry = KernelRegistry::builtin(); + let mut descriptor = KernelDescriptor::external("mocklang", &["mocklang"], &script); + descriptor.environment_digest = Some(digest); + descriptor.environment_dir = Some(env); + descriptor.interpreter_version = Some("mocklang 1.0".to_string()); + registry.register(descriptor).unwrap(); + let result = call_with_registry(&request("mocklang", "ignored"), ®istry).unwrap(); + assert_eq!(result.status, RunStatus::Success); +} diff --git a/docs/adr/0020-foreign-environment-binding.md b/docs/adr/0020-foreign-environment-binding.md new file mode 100644 index 0000000..2bba3b8 --- /dev/null +++ b/docs/adr/0020-foreign-environment-binding.md @@ -0,0 +1,61 @@ +# ADR-0020: A pinned Foreign environment binds the executed provider + +Status: **Accepted** +Date: 2026-11-20 +Relates to: ADR-0012, `spec/foreign.md` §2/§6, stable-release spec §8.3 + +## Context + +`KernelDescriptor` can declare `environment_id`, `environment_digest`, +`environment_dir` and `interpreter_version`. Before this ADR the host verified +the environment tree digest and then prepended `/bin` to `PATH`, but the +executed program was still resolved from the host `PATH` for built-in providers, +and external entrypoints could live outside the verified environment. A +manifest could therefore pass integrity verification while a different +interpreter (or a host interpreter whose dependencies were not part of the +pinned tree) actually ran. + +## Decision + +1. `environment_dir` is an execution binding: + * an external provider's absolute `entrypoint` must resolve inside the + canonicalized environment; otherwise registration/execution fails with + `ForeignError::Protocol`; + * one of the built-in providers cannot be combined with + `environment_dir`; a pinned interpreter is registered as an explicit + external provider whose entrypoint is the interpreter itself. +2. A bound child receives `MARQDO_FOREIGN_ENV` and exactly the environment's + executable directory on `PATH`. The host `PATH` is not appended. On Windows + `SYSTEMROOT`/`WINDIR` are inherited for process creation, not for package + resolution. +3. `interpreter_version`, when declared, is checked against the resolved + program's `--version` output before the program source is executed. A + mismatch fails closed. +4. The profile-v1 environment digest keeps rejecting symlinks and special + files. A virtualenv whose interpreter is a symlink is not pin-able in this + release; this limitation is documented rather than silently resolved. +5. This does not make the child an OS sandbox. Host authorization and + `spec/security.md` still govern capabilities; strict mode remains refused + until its own ADR and security lane pass. + +## Consequences + +* A verified environment can no longer be decorative: either the program comes + from it, or the descriptor is rejected. +* Existing external descriptors that declared `environment_dir` while pointing + at a host binary must be corrected; this is an intentional fail-closed + behavior change, documented in the changelog. +* uv/npm environment *creation* remains out of scope; an external provisioner + may produce a directory that satisfies this contract. +* Built-in Python/Node without an environment keep their PATH lookup and + install hint. + +## Tests + +`crates/marqdo-foreign/tests/provider.rs`: + +* `pinned_environment_binds_the_provider_and_is_verified_before_execution` +* `provider_outside_pinned_environment_is_rejected` +* `builtin_provider_cannot_be_bound_to_an_environment` +* `declared_interpreter_version_must_match_the_resolved_program` +* existing digest/tamper/timeout/registration tests remain green. diff --git a/spec/foreign.md b/spec/foreign.md index a7a99b5..f621b94 100644 --- a/spec/foreign.md +++ b/spec/foreign.md @@ -71,9 +71,29 @@ hard-codes a language list. sorted relative paths with length-prefixed bytes; 10,000 files / 512 MiB caps; symlinks and special files rejected). The environment is verified at registration and again before every spawn; mismatch fails with -`ForeignError::EnvironmentIntegrity` before any child starts. On execution the -child receives `MARQDO_FOREIGN_ENV` and, when `/bin` exists, that directory -is prepended to `PATH`. +`ForeignError::EnvironmentIntegrity` before any child starts. + +`environment_dir` **binds the executed program**, it is not a PATH hint +(ADR-0020): + +* an external provider's `entrypoint` must resolve inside `environment_dir`; + a manifest whose executable lies outside it is rejected with + `ForeignError::Protocol` before any process starts; +* built-in Python/Node providers cannot be bound to `environment_dir`; a + pinned interpreter must be registered as an explicit external provider; +* the child receives `MARQDO_FOREIGN_ENV` and exactly the environment's + executable directory on `PATH` (`/bin`, or `/Scripts` on Windows). + The host `PATH` is not appended, so a missing environment executable cannot + silently fall back to the system interpreter; +* when `interpreter_version` is declared, the resolved program must report a + `--version` line containing that string before execution; a mismatch is a + `ForeignError::Protocol` failure, not a warning; +* a missing bound executable is `ForeignError::KernelUnavailable` with an + environment-specific hint. + +A pinned environment therefore has to contain a regular-file executable; a +virtualenv whose interpreter is only a symlink to the host Python must be +materialized as a regular file to be pinned in this release. The CLI does **not** materialize uv/npm environments or integrate them into lock v3; it verifies an explicitly pinned directory. A future materializer may @@ -172,7 +192,8 @@ foreign_result_map`) is: `crates/marqdo-foreign/src/lib.rs`: 1. normalize the language (unknown → `KernelUnavailable` with install hint); -2. find the interpreter on `PATH`; +2. resolve the interpreter: on the host `PATH` for an unbound built-in, or + strictly inside the pinned `environment_dir` for a bound provider; 3. create a **private unique temp working directory** (mode 0700 on Unix) and write the program to a private temp file (`.py`/`.js`, mode 0600); 4. spawn the interpreter **directly with `argv`** (no shell, no string @@ -191,8 +212,10 @@ detection timeout 5 s / 64 KiB. A kernel that ignores stdin and exits does not hang the host. `OutputTooLarge` drops the captured output and kills the child. Grandchild processes are not killed when the direct child is killed. -Environment: only `PATH` is inherited, so Marqdo secrets in other environment -variables do not leak by default. This is hygiene, not a security boundary. +Environment: unbound kernels inherit only `PATH`, so Marqdo secrets in other +environment variables do not leak by default. A bound kernel receives only the +environment's executable directory on `PATH` (plus `SYSTEMROOT`/`WINDIR` on +Windows for process creation). This is hygiene, not a security boundary. ## 7. Capability gating