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
This commit is contained in:
cflmy committed 2026-11-20 13:56:08 +08:00
1 parent 53cdea2325
commit faa6c95cfe
4 files changed
+394 -99

No files matched your search

+175 -55
View File
@@ -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<KernelInfo> {
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<String, ForeignError> {
}
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<String, ForeignError> {
use sha2::{Digest, Sha256};
use walkdir::WalkDir;
@@ -731,18 +780,23 @@ fn execute(request: &RunRequest, registry: &KernelRegistry) -> Result<RawRun, Fo
if !descriptor.builtin {
verify_descriptor(descriptor)?;
}
let program = resolve_program(descriptor).ok_or_else(|| ForeignError::KernelUnavailable {
language: descriptor.provider_id.clone(),
hint: if descriptor.builtin {
kernel_hint(&descriptor.provider_id).to_string()
} else {
format!(
"external kernel provider `{}` executable `{}` is missing or not executable",
descriptor.provider_id,
descriptor.entrypoint.display()
)
},
})?;
let program = resolve_program(descriptor)?;
if let Some(expected) = &descriptor.interpreter_version {
let actual = probe_version(&program).ok_or_else(|| ForeignError::Protocol {
message: format!(
"kernel provider `{}` declares interpreter_version `{expected}` but the interpreter could not report a version",
descriptor.provider_id
),
})?;
if !actual.contains(expected.trim()) {
return Err(ForeignError::Protocol {
message: format!(
"kernel provider `{}` interpreter version mismatch: declared `{expected}`, actual `{actual}`",
descriptor.provider_id
),
});
}
}
let extension = if descriptor.builtin {
if descriptor.provider_id == "python" {
@@ -762,19 +816,22 @@ fn execute(request: &RunRequest, registry: &KernelRegistry) -> Result<RawRun, Fo
.arg(&artifacts.program_path)
.current_dir(&artifacts.work_dir)
.env_clear();
if let Some(path) = std::env::var_os("PATH") {
if let Some(environment) = &descriptor.environment_dir {
// An environment-bound provider runs with exactly the environment's
// executable directory on PATH. Falling back to the host PATH would
// silently defeat the pin.
command.env("MARQDO_FOREIGN_ENV", environment);
command.env("PATH", environment_bin(environment));
} else if let Some(path) = std::env::var_os("PATH") {
command.env("PATH", path);
}
if let Some(environment) = &descriptor.environment_dir {
command.env("MARQDO_FOREIGN_ENV", environment);
let bin = environment.join("bin");
if bin.is_dir() {
let mut paths = vec![bin];
if let Some(existing) = std::env::var_os("PATH") {
paths.extend(std::env::split_paths(&existing));
}
if let Ok(joined) = std::env::join_paths(paths) {
command.env("PATH", joined);
#[cfg(windows)]
{
// Windows process creation and DLL loading require the system root;
// this is not a package-resolution path.
for name in ["SYSTEMROOT", "WINDIR"] {
if let Some(value) = std::env::var_os(name) {
command.env(name, value);
}
}
}
@@ -841,28 +898,91 @@ fn is_executable_file(path: &Path) -> bool {
}
}
fn resolve_program(descriptor: &KernelDescriptor) -> Option<PathBuf> {
/// 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<PathBuf, ForeignError> {
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<String> {
+129 -38
View File
@@ -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::<Vec<_>>()
.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::<Vec<_>>()
.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"), &registry).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"), &registry).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"), &registry).unwrap();
assert_eq!(result.status, RunStatus::Success);
}
@@ -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 `<env>/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.
+29 -6
View File
@@ -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 `<env>/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` (`<env>/bin`, or `<env>/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