feat(foreign): verify pinned environment directories (B-12)

- add environment_dir to KernelDescriptor and verify its deterministic
  file-set digest at registration and immediately before every spawn
- reject missing digests, relative/missing dirs, symlinks, special files and
  oversized environments; tampering fails with EnvironmentIntegrity
- inject MARQDO_FOREIGN_ENV and prepend <env>/bin to PATH for the child
- add a real provider test covering success and post-registration tampering
- document that uv/npm environment generation and lock-v3 integration remain
  open
This commit is contained in:
cflmy committed 2026-11-20 13:12:47 +08:00
1 parent f69c563afd
commit 1099ed6160
7 files changed
+251 -21

No files matched your search

Generated
+1
View File
@@ -370,6 +370,7 @@ dependencies = [
"sha2",
"tempfile",
"thiserror",
"walkdir",
]
[[package]]
+2
View File
@@ -12,6 +12,7 @@ authors.workspace = true
tempfile = { workspace = true }
sha2 = { workspace = true }
hex = { workspace = true }
walkdir = { workspace = true }
[dependencies]
marqdo-span = { workspace = true }
@@ -21,6 +22,7 @@ serde_json = { workspace = true }
thiserror = { workspace = true }
sha2 = { workspace = true }
hex = { workspace = true }
walkdir = { workspace = true }
[target.'cfg(unix)'.dependencies]
libc = { workspace = true }
+158 -12
View File
@@ -104,6 +104,9 @@ pub struct KernelDescriptor {
/// Optional expected interpreter version string.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub interpreter_version: Option<String>,
/// Optional pinned environment directory (virtualenv, node_modules, ...).
#[serde(default, skip_serializing_if = "Option::is_none")]
pub environment_dir: Option<PathBuf>,
}
impl KernelDescriptor {
@@ -123,6 +126,7 @@ impl KernelDescriptor {
environment_id: None,
environment_digest: None,
interpreter_version: None,
environment_dir: None,
}
}
@@ -146,6 +150,7 @@ impl KernelDescriptor {
environment_id: None,
environment_digest: None,
interpreter_version: None,
environment_dir: None,
}
}
}
@@ -243,7 +248,7 @@ impl KernelRegistry {
),
});
}
verify_provider(&descriptor)?;
verify_descriptor(&descriptor)?;
}
for language in &mut descriptor.languages {
*language = language.trim().to_ascii_lowercase();
@@ -432,6 +437,16 @@ pub enum ForeignError {
/// Actual digest.
actual: String,
},
/// The pinned foreign environment no longer matches its declared digest.
#[error("foreign kernel environment `{environment}` failed integrity verification: expected {expected}, got {actual}")]
EnvironmentIntegrity {
/// Environment directory.
environment: String,
/// Declared digest.
expected: String,
/// Actual digest.
actual: String,
},
/// Captured stdout/stderr exceeded `max_output_bytes`; the child was
/// killed and the partial output dropped.
#[error("foreign kernel output exceeded the {limit} byte limit")]
@@ -458,24 +473,142 @@ fn sha256_file(path: &Path) -> Result<String, ForeignError> {
Ok(hex::encode(hasher.finalize()))
}
fn verify_provider(descriptor: &KernelDescriptor) -> Result<(), ForeignError> {
fn verify_descriptor(descriptor: &KernelDescriptor) -> Result<(), ForeignError> {
if descriptor.builtin {
return Ok(());
}
let Some(expected) = &descriptor.digest else {
return Ok(());
};
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(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 !environment.is_absolute() || !environment.is_dir() {
return Err(ForeignError::Protocol {
message: format!(
"kernel provider `{}` environment_dir must be an absolute existing directory",
descriptor.provider_id
),
});
}
let expected =
descriptor
.environment_digest
.as_ref()
.ok_or_else(|| ForeignError::Protocol {
message: format!(
"kernel provider `{}` declares environment_dir without environment_digest",
descriptor.provider_id
),
})?;
let actual = environment_digest(environment)?;
if &actual != expected {
return Err(ForeignError::EnvironmentIntegrity {
environment: environment.display().to_string(),
expected: expected.clone(),
actual,
});
}
} else if descriptor.environment_digest.is_some() {
return Err(ForeignError::Protocol {
message: format!(
"kernel provider `{}` declares environment_digest without environment_dir",
descriptor.provider_id
),
});
}
Ok(())
}
fn environment_digest(root: &Path) -> Result<String, ForeignError> {
use sha2::{Digest, Sha256};
use walkdir::WalkDir;
let mut files = Vec::new();
let mut total = 0u64;
for entry in WalkDir::new(root).follow_links(false).sort_by_file_name() {
let entry = entry.map_err(|error| ForeignError::Io {
message: format!("cannot walk foreign environment: {error}"),
})?;
if entry.depth() == 0 {
continue;
}
if entry.file_type().is_symlink() {
return Err(ForeignError::Protocol {
message: format!(
"foreign environment contains symlink `{}`",
entry.path().display()
),
});
}
if entry.file_type().is_dir() {
continue;
}
if !entry.file_type().is_file() {
return Err(ForeignError::Protocol {
message: format!(
"foreign environment contains special file `{}`",
entry.path().display()
),
});
}
if files.len() >= 10_000 {
return Err(ForeignError::Protocol {
message: "foreign environment exceeds 10,000 files".to_string(),
});
}
let relative = entry
.path()
.strip_prefix(root)
.map_err(|_| ForeignError::Io {
message: "foreign environment path escaped its root".to_string(),
})?;
let mut parts = Vec::new();
for component in relative.components() {
match component {
std::path::Component::Normal(part) => parts.push(
part.to_str()
.ok_or_else(|| ForeignError::Protocol {
message: "foreign environment path is not UTF-8".to_string(),
})?
.to_string(),
),
_ => {
return Err(ForeignError::Protocol {
message: "foreign environment path is not normalized".to_string(),
})
}
}
}
let bytes = fs::read(entry.path()).map_err(|error| ForeignError::Io {
message: format!("cannot read foreign environment file: {error}"),
})?;
total = total.saturating_add(bytes.len() as u64);
if total > 512 * 1024 * 1024 {
return Err(ForeignError::Protocol {
message: "foreign environment exceeds 512 MiB".to_string(),
});
}
files.push((parts.join("/"), bytes));
}
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);
}
Ok(hex::encode(hasher.finalize()))
}
/// Detect a kernel for `language` by scanning `PATH`.
///
/// Candidates are `python3`, then `python` for Python, and `node` for
@@ -596,7 +729,7 @@ fn execute(request: &RunRequest, registry: &KernelRegistry) -> Result<RawRun, Fo
),
})?;
if !descriptor.builtin {
verify_provider(descriptor)?;
verify_descriptor(descriptor)?;
}
let program = resolve_program(descriptor).ok_or_else(|| ForeignError::KernelUnavailable {
language: descriptor.provider_id.clone(),
@@ -632,6 +765,19 @@ fn execute(request: &RunRequest, registry: &KernelRegistry) -> Result<RawRun, Fo
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);
}
}
}
let captured = spawn_and_capture(
&mut command,
+59
View File
@@ -137,3 +137,62 @@ fn provider_digest_is_verified_at_registration_and_execution() {
bad.digest = Some("not-a-digest".to_string());
assert!(registry.register(bad).is_err());
}
#[cfg(unix)]
#[test]
fn pinned_environment_digest_is_verified_before_execution() {
use sha2::{Digest, Sha256};
let dir = tempfile::tempdir().unwrap();
let script = mock_provider(dir.path());
let env = dir.path().join("venv");
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 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_dir = Some(env.clone());
registry.register(descriptor).unwrap();
let result = call_with_registry(&request("mocklang", "ignored"), &registry).unwrap();
assert_eq!(result.status, RunStatus::Success);
std::fs::write(env.join("marker.txt"), "tampered").unwrap();
let error = call_with_registry(&request("mocklang", "ignored"), &registry).unwrap_err();
assert!(
matches!(error, ForeignError::EnvironmentIntegrity { .. }),
"{error:?}"
);
}
+10
View File
@@ -278,6 +278,16 @@ fn foreign_error(
"foreign kernel `{provider}` failed integrity verification: expected {expected}, got {actual}"
),
),
ForeignError::EnvironmentIntegrity {
environment,
expected,
actual,
} => (
ErrorCategory::KernelUnavailable,
format!(
"foreign kernel environment `{environment}` failed integrity verification: expected {expected}, got {actual}"
),
),
ForeignError::OutputTooLarge { limit } => (
ErrorCategory::ResourceExhausted,
format!("foreign kernel exceeded the {limit} byte output limit"),
+7 -4
View File
@@ -203,9 +203,12 @@ Foreign provider integrity and environment metadata:
starting a process. Malformed digests and relative external paths fail closed.
* The example provider pins its digest; tests cover success, post-registration
tampering and malformed descriptors.
* The environment fields are metadata only. uv/npm environment materialization,
environment-directory hashing and lock-v3 integration are **not**
implemented.
* `environment_dir` is a pinned absolute directory whose profile-v1 tree digest
is verified at registration and before every spawn; the child receives
`MARQDO_FOREIGN_ENV` and a prepended `<env>/bin` on `PATH`. Tampering fails
with `EnvironmentIntegrity` before spawn.
* uv/npm environment **generation** and lock-v3 integration are still not
implemented; this build verifies an explicitly provisioned directory.
* H3-A is **implemented for `fs.read`**: both native and worker plugins can
request a granted `fs.read` through the broker; it executes via `ProjectFs`,
returns real bytes, and records an audit decision. Unsupported capabilities
@@ -228,7 +231,7 @@ Foreign provider integrity and environment metadata:
| S2-C/H2-B Trace v2 | **Done** | logical root/digest, module-owned events, bounded/truncated trace, independent consumer, hardened worker frames (see §S2-C/H2-B) |
| S3-A/H2-C Tool protocol | **Done** | SemVer negotiation at install+dispatch, whole-bundle manifest/digest verification, atomic install/remove, reserved record file (see §S3-A/H2-C) |
| S4-A/B-13 B-14 quality gates | **Partial** | real schema instance validation + negative mutations in CI; Windows/macOS runtime tests for core/Analysis/Trace and strict refusal. Tool/C-ABI/worker runtime evidence remains Unix-only (see §S4-A) |
| S5-A/B-12 foreign integrity | **Done for metadata/integrity** | provider digest verified at registration and before spawn; environment descriptor fields; full uv/npm materialization and H3-A/B remain open (see §S5-A/B-12) |
| S5-A/B-12 foreign integrity | **Done for pinned provider+environment** | provider and environment-directory digests verified at registration and before spawn; environment bin/PATH injection. uv/npm environment generation, lock-v3 integration and H3-B remain open (see §S5-A/B-12) |
| S5-B/H3-A broker execution | **Done for fs.read (native+worker)** | registered plugin capability requests execute `fs.read` through `ProjectFs` with audit; unsupported capabilities fail unavailable. Session identity breadth and H3-B OS isolation remain open and are not claimed (ADR-0018) |
| R0 baseline + ADRs | **Done** | this section; `docs/adr/0008`–`0012`; full workspace gate |
| R1 package-aware identity + callable registry | **Done for statics; superseded by S1 lock v3** | `ModuleId { instance, relative_path }`; `PackageResolver` path sources; lock v3 transitive graph (ADR-0016) replaces the flat v2 lock; `CallableRegistry` for builtins/marqdo/declared ABI exports; external manifest wiring is R2 |
+14 -5
View File
@@ -64,11 +64,20 @@ versions are rejected at registration. The host owns a registry
(`StdHost::kernel_registry`, `StdHost::register_kernel`); the interpreter never
hard-codes a language list.
`environment_id`, `environment_digest` and `interpreter_version` record the
intended reproducible environment. This build validates their shape and echoes
`environment_id` through `KernelInfo`; it does **not** materialize uv/npm
environments or integrate them into lock v3. A production descriptor should pin
all three once a materializer exists.
`environment_id`, `environment_digest`, `interpreter_version` and
`environment_dir` describe the intended reproducible environment. When
`environment_dir` is present it must be an absolute existing directory and
`environment_digest` must pin the profile-v1 tree digest (regular files only;
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`.
The CLI does **not** materialize uv/npm environments or integrate them into
lock v3; it verifies an explicitly pinned directory. A future materializer may
fill `environment_dir`/`environment_digest`, but must not weaken verification.
A `Code` value for an unregistered label is still valid inert data. Only an
explicit `foreign.run`/`foreign.call` lookup can fail with