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:
1 parent
53cdea2325
commit
faa6c95cfe
4 files changed
+394
-99
No files matched your search
@@ -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> {
|
||||
|
||||
@@ -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"), ®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);
|
||||
}
|
||||
@@ -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
@@ -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
|
||||
|
||||
|
||||
Reference in new issue
Block a user