From 1099ed6160a6a2eb7f407256484429964db5cab8 Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 20 Nov 2026 13:12:47 +0800 Subject: [PATCH] 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 /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 --- Cargo.lock | 1 + crates/marqdo-foreign/Cargo.toml | 2 + crates/marqdo-foreign/src/lib.rs | 170 ++++++++++++++++++++++-- crates/marqdo-foreign/tests/provider.rs | 59 ++++++++ crates/marqdo-host/src/kernels.rs | 10 ++ docs/STATUS.md | 11 +- spec/foreign.md | 19 ++- 7 files changed, 251 insertions(+), 21 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index b9f85f0..7a504b0 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -370,6 +370,7 @@ dependencies = [ "sha2", "tempfile", "thiserror", + "walkdir", ] [[package]] diff --git a/crates/marqdo-foreign/Cargo.toml b/crates/marqdo-foreign/Cargo.toml index c840b43..b10418d 100644 --- a/crates/marqdo-foreign/Cargo.toml +++ b/crates/marqdo-foreign/Cargo.toml @@ -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 } diff --git a/crates/marqdo-foreign/src/lib.rs b/crates/marqdo-foreign/src/lib.rs index a496c09..a8e2b85 100644 --- a/crates/marqdo-foreign/src/lib.rs +++ b/crates/marqdo-foreign/src/lib.rs @@ -104,6 +104,9 @@ pub struct KernelDescriptor { /// Optional expected interpreter version string. #[serde(default, skip_serializing_if = "Option::is_none")] pub interpreter_version: Option, + /// Optional pinned environment directory (virtualenv, node_modules, ...). + #[serde(default, skip_serializing_if = "Option::is_none")] + pub environment_dir: Option, } 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 { 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 { + 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 Result>() + .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"), ®istry).unwrap(); + assert_eq!(result.status, RunStatus::Success); + + std::fs::write(env.join("marker.txt"), "tampered").unwrap(); + let error = call_with_registry(&request("mocklang", "ignored"), ®istry).unwrap_err(); + assert!( + matches!(error, ForeignError::EnvironmentIntegrity { .. }), + "{error:?}" + ); +} diff --git a/crates/marqdo-host/src/kernels.rs b/crates/marqdo-host/src/kernels.rs index a346a63..24b4eed 100644 --- a/crates/marqdo-host/src/kernels.rs +++ b/crates/marqdo-host/src/kernels.rs @@ -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"), diff --git a/docs/STATUS.md b/docs/STATUS.md index dc0d561..161372d 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -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 `/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 | diff --git a/spec/foreign.md b/spec/foreign.md index 4446e2e..a7a99b5 100644 --- a/spec/foreign.md +++ b/spec/foreign.md @@ -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 `/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