feat(sparsekernel): harden broker boundaries

Author: CharGrnmn

crates/sparsekernel-cli/src/lib.rs

@@ -431,6 +431,42 @@ fn base64_artifact_compat_disabled() -> bool {
     )
 }
 
+fn base64_artifact_compat_max_bytes() -> Option<usize> {
+    let raw = env::var("SPARSEKERNEL_ARTIFACT_BASE64_MAX_BYTES").ok();
+    let Some(value) = raw
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+    else {
+        return Some(1024 * 1024);
+    };
+    let normalized = value.to_ascii_lowercase();
+    if matches!(normalized.as_str(), "unlimited" | "none" | "off") {
+        return None;
+    }
+    value
+        .parse::<usize>()
+        .ok()
+        .map(Some)
+        .unwrap_or(Some(1024 * 1024))
+}
+
+fn enforce_base64_artifact_compat_size(
+    bytes_len: usize,
+    operation: &str,
+) -> Result<(), Box<dyn Error>> {
+    let Some(max_bytes) = base64_artifact_compat_max_bytes() else {
+        return Ok(());
+    };
+    if bytes_len <= max_bytes {
+        return Ok(());
+    }
+    Err(format!(
+        "base64 artifact {operation} is limited to {max_bytes} bytes; use /artifacts/import-file or /artifacts/export-file"
+    )
+    .into())
+}
+
 fn canonical_child_path(root: &Path, raw_path: &str) -> Result<PathBuf, Box<dyn Error>> {
     fs::create_dir_all(root)?;
     let canonical_root = root.canonicalize()?;
@@ -856,6 +892,9 @@ pub fn handle_api_request_with_artifact_root(
                 );
             }
             let bytes = decode_artifact_content(&input)?;
+            if input.content_base64.is_some() {
+                enforce_base64_artifact_compat_size(bytes.len(), "create")?;
+            }
             if let Some(subject) = &input.subject {
                 require_artifact_capability(db, subject, None, "write")?;
             }
@@ -928,11 +967,13 @@ pub fn handle_api_request_with_artifact_root(
                     subject.permission.as_deref().unwrap_or("read"),
                 )
             });
+            let artifact = db.get_artifact(&input.id)?;
+            enforce_base64_artifact_compat_size(artifact.size_bytes as usize, "read")?;
             let bytes = store.read(&input.id, subject)?;
             ApiReply {
                 status_code: 200,
                 body: json!({
-                    "artifact": db.get_artifact(&input.id)?,
+                    "artifact": artifact,
                     "content_base64": BASE64_STANDARD.encode(bytes),
                 }),
             }
@@ -1744,4 +1785,71 @@ mod tests {
             .to_string()
             .contains("base64 artifact read is disabled"));
     }
+
+    #[test]
+    fn artifact_api_limits_base64_compatibility_size() {
+        let _guard = env_lock();
+        let previous_limit = env::var("SPARSEKERNEL_ARTIFACT_BASE64_MAX_BYTES").ok();
+        let previous_disable = env::var("SPARSEKERNEL_DISABLE_BASE64_ARTIFACTS").ok();
+        let previous_mode = env::var("SPARSEKERNEL_ARTIFACT_BASE64").ok();
+        env::set_var("SPARSEKERNEL_ARTIFACT_BASE64_MAX_BYTES", "4");
+        env::remove_var("SPARSEKERNEL_DISABLE_BASE64_ARTIFACTS");
+        env::remove_var("SPARSEKERNEL_ARTIFACT_BASE64");
+        let mut db = SparseKernelDb::open(":memory:").unwrap();
+        let root = tempfile::tempdir().unwrap();
+        let create = handle_api_request_with_artifact_root(
+            &mut db,
+            "POST",
+            "/artifacts/create",
+            serde_json::to_string(&json!({
+                "content_base64": BASE64_STANDARD.encode(b"too large"),
+            }))
+            .unwrap()
+            .as_bytes(),
+            Some(root.path()),
+        );
+        let text = handle_api_request_with_artifact_root(
+            &mut db,
+            "POST",
+            "/artifacts/create",
+            serde_json::to_string(&json!({
+                "content_text": "too large for base64",
+                "mime_type": "text/plain",
+            }))
+            .unwrap()
+            .as_bytes(),
+            Some(root.path()),
+        )
+        .unwrap()
+        .body;
+        let read = handle_api_request_with_artifact_root(
+            &mut db,
+            "POST",
+            "/artifacts/read",
+            serde_json::to_string(&json!({ "id": text["id"] }))
+                .unwrap()
+                .as_bytes(),
+            Some(root.path()),
+        );
+        match previous_limit {
+            Some(value) => env::set_var("SPARSEKERNEL_ARTIFACT_BASE64_MAX_BYTES", value),
+            None => env::remove_var("SPARSEKERNEL_ARTIFACT_BASE64_MAX_BYTES"),
+        }
+        match previous_disable {
+            Some(value) => env::set_var("SPARSEKERNEL_DISABLE_BASE64_ARTIFACTS", value),
+            None => env::remove_var("SPARSEKERNEL_DISABLE_BASE64_ARTIFACTS"),
+        }
+        match previous_mode {
+            Some(value) => env::set_var("SPARSEKERNEL_ARTIFACT_BASE64", value),
+            None => env::remove_var("SPARSEKERNEL_ARTIFACT_BASE64"),
+        }
+        assert!(create
+            .unwrap_err()
+            .to_string()
+            .contains("base64 artifact create is limited"));
+        assert!(read
+            .unwrap_err()
+            .to_string()
+            .contains("base64 artifact read is limited"));
+    }
 }

crates/sparsekernel-core/src/lib.rs

@@ -2398,7 +2398,18 @@ fn run_hard_egress_helper(
         .ok()
         .map(|value| value.trim().to_string())
         .filter(|value| !value.is_empty())
+        .or_else(|| {
+            enforcement
+                .and_then(|value| value.get("helper"))
+                .and_then(Value::as_str)
+                .map(str::trim)
+                .filter(|value| !value.is_empty())
+                .map(str::to_string)
+        })
         .ok_or_else(|| SparseKernelError::Denied("missing hard egress helper".to_string()))?;
+    if is_builtin_hard_egress_helper(&helper) {
+        return run_builtin_hard_egress_helper(action, allocation_id, backend);
+    }
     let payload = json!({
         "protocol": "openclaw.sparsekernel.sandbox-egress.v1",
         "action": action,
@@ -2475,6 +2486,37 @@ fn run_hard_egress_helper(
     })))
 }
 
+fn is_builtin_hard_egress_helper(helper: &str) -> bool {
+    matches!(
+        helper.trim().to_ascii_lowercase().as_str(),
+        "builtin" | "sparsekernel:builtin" | "openclaw:sparsekernel:builtin"
+    )
+}
+
+fn run_builtin_hard_egress_helper(
+    action: &str,
+    allocation_id: &str,
+    backend: &str,
+) -> Result<Option<Value>> {
+    if action == "release" {
+        return Ok(None);
+    }
+    let description = match backend {
+        "bwrap" => "bubblewrap --unshare-all selected by the SparseKernel sandbox backend",
+        _ => {
+            return Err(SparseKernelError::Denied(format!(
+                "builtin hard egress only supports daemon-owned bwrap allocations, got {backend}"
+            )));
+        }
+    };
+    Ok(Some(json!({
+        "helper": "builtin",
+        "enforcementId": format!("builtin:{backend}:{allocation_id}"),
+        "boundary": "platform_enforcer",
+        "description": description,
+    })))
+}
+
 impl SandboxBroker for LocalSandboxBroker<'_> {
     fn allocate_sandbox(
         &self,
@@ -3124,4 +3166,49 @@ mod tests {
             .any(|entry| entry.action == "network_policy.hard_egress_enforced"));
         assert!(release_result.unwrap().unwrap());
     }
+
+    #[test]
+    fn sandbox_builtin_hard_egress_allows_backend_enforced_allocations() {
+        let _guard = env_lock();
+        let (_dir, db) = temp_db();
+        let previous = env::var("OPENCLAW_RUNTIME_SANDBOX_REQUIRE_HARD_EGRESS").ok();
+        let previous_helper = env::var("OPENCLAW_RUNTIME_SANDBOX_HARD_EGRESS_HELPER").ok();
+        let previous_helper_args =
+            env::var("OPENCLAW_RUNTIME_SANDBOX_HARD_EGRESS_HELPER_ARGS").ok();
+        env::set_var("OPENCLAW_RUNTIME_SANDBOX_REQUIRE_HARD_EGRESS", "1");
+        env::set_var("OPENCLAW_RUNTIME_SANDBOX_HARD_EGRESS_HELPER", "builtin");
+        env::remove_var("OPENCLAW_RUNTIME_SANDBOX_HARD_EGRESS_HELPER_ARGS");
+        let sandbox = LocalSandboxBroker { db: &db };
+        let allocation = sandbox.allocate_sandbox(None, None, "public_web", Some("bwrap"));
+        let release_result = allocation
+            .as_ref()
+            .ok()
+            .map(|allocation| sandbox.release_sandbox(&allocation.id));
+        let audit = db.list_audit(5).unwrap();
+        match previous {
+            Some(value) => env::set_var("OPENCLAW_RUNTIME_SANDBOX_REQUIRE_HARD_EGRESS", value),
+            None => env::remove_var("OPENCLAW_RUNTIME_SANDBOX_REQUIRE_HARD_EGRESS"),
+        }
+        match previous_helper {
+            Some(value) => env::set_var("OPENCLAW_RUNTIME_SANDBOX_HARD_EGRESS_HELPER", value),
+            None => env::remove_var("OPENCLAW_RUNTIME_SANDBOX_HARD_EGRESS_HELPER"),
+        }
+        match previous_helper_args {
+            Some(value) => env::set_var("OPENCLAW_RUNTIME_SANDBOX_HARD_EGRESS_HELPER_ARGS", value),
+            None => env::remove_var("OPENCLAW_RUNTIME_SANDBOX_HARD_EGRESS_HELPER_ARGS"),
+        }
+        let allocation = allocation.unwrap();
+        assert_eq!(allocation.backend, "bwrap");
+        assert!(audit.iter().any(|entry| {
+            entry.action == "network_policy.hard_egress_enforced"
+                && entry
+                    .payload
+                    .as_ref()
+                    .and_then(|payload| payload.get("enforcement"))
+                    .and_then(|enforcement| enforcement.get("boundary"))
+                    .and_then(Value::as_str)
+                    == Some("platform_enforcer")
+        }));
+        assert!(release_result.unwrap().unwrap());
+    }
 }

docs/architecture/artifact-store.md

@@ -26,6 +26,6 @@ Retention policies:
 
 Artifact reads and writes are capability-mediated where the caller is not the trusted runtime. Access grants are recorded in `artifact_access`.
 
-The local artifact store accepts bytes, streams, or file paths. File imports stream into a private temporary blob while computing sha256, then move into the content-addressed path, so downloads and snapshots do not need to be loaded fully into memory. The v0 `sparsekerneld` API exposes artifact create/read/metadata endpoints over local JSON. For small compatibility payloads, binary content can still be transported as base64. Hardened local deployments can set `SPARSEKERNEL_DISABLE_BASE64_ARTIFACTS=1` or `SPARSEKERNEL_ARTIFACT_BASE64=off` to reject base64 create/read calls and require staged file transfer instead. For large local payloads, use `/artifacts/import-file` with a file staged under the daemon-owned staging directory and `/artifacts/export-file` to copy content into the daemon-owned export directory without moving bytes through JSON. Node clients can use `@openclaw/sparsekernel-client/node-artifacts` to resolve the daemon-compatible staging directory, copy local files into it, and copy exported files to a caller destination without touching the base64 compatibility path.
+The local artifact store accepts bytes, streams, or file paths. File imports stream into a private temporary blob while computing sha256, then move into the content-addressed path, so downloads and snapshots do not need to be loaded fully into memory. The v0 `sparsekerneld` API exposes artifact create/read/metadata endpoints over local JSON. For small compatibility payloads, binary content can still be transported as base64, capped by `SPARSEKERNEL_ARTIFACT_BASE64_MAX_BYTES` and defaulting to 1 MiB. Hardened local deployments can set `SPARSEKERNEL_DISABLE_BASE64_ARTIFACTS=1` or `SPARSEKERNEL_ARTIFACT_BASE64=off` to reject base64 create/read calls and require staged file transfer instead; `SPARSEKERNEL_ARTIFACT_BASE64_MAX_BYTES=unlimited` restores uncapped compatibility when an operator explicitly accepts JSON transport. For large local payloads, use `/artifacts/import-file` with a file staged under the daemon-owned staging directory and `/artifacts/export-file` to copy content into the daemon-owned export directory without moving bytes through JSON. Node clients can use `@openclaw/sparsekernel-client/node-artifacts` to resolve the daemon-compatible staging directory, copy local files into it, and copy exported files to a caller destination without touching the base64 compatibility path.
 
 Browser broker adapters must route screenshots and downloads through this API. The TypeScript CDP broker uses staged local imports when the kernel client supports `/artifacts/import-file`, then falls back to base64 artifact create only for compatibility clients. The OpenClaw browser proxy exports screenshot/PDF artifacts back to local temp files through `/artifacts/export-file` instead of reading base64 payloads. Agents should receive artifact ids and metadata, not raw browser download paths or large binary payloads.

docs/architecture/browser-broker.md

@@ -21,7 +21,7 @@ Set `OPENCLAW_RUNTIME_BROWSER_BROKER=native` to let SparseKernel launch and supe
 
 Set `OPENCLAW_RUNTIME_BROWSER_REQUIRE_PROXY=1` when a trust zone must use a proxy-backed browser egress path. The trust zone's network policy must contain a loopback `proxy_ref`, and native browser pools launch Chromium with `--proxy-server=<proxy_ref>`. Static or externally managed CDP endpoints are rejected in this mode unless `OPENCLAW_RUNTIME_BROWSER_EXTERNAL_PROXY_OK=1` asserts that the external browser process is already proxy-controlled. This protects the SparseKernel-owned browser process path; it is not host-level egress enforcement for arbitrary host processes.
 
-Supported v0 actions (`status`, `doctor`, `profiles`, `tabs`, `open`, `navigate`, `focus`, `close`, `snapshot`, `console`, `screenshot`, `pdf`, direct file-input `upload`, `dialog`, and brokered `act`) operate against broker-owned targets inside the leased CDP context. Brokered `act` covers the OpenClaw action contract for click, coordinate click, type, press, hover, scroll, drag, select, fill, resize, wait, evaluate, close, and batch using CDP input events plus bounded DOM evaluation. Selector-backed actions retry inside the leased page until their action timeout and now require basic actionability before dispatch: visible connected target, stable bounding box, enabled form state where relevant, editable target for typing, and center-point hit testing. Selector click and hover resolve an actionable center point in the leased page and dispatch real CDP mouse events rather than handing raw DOM click events to page code; click and coordinate-click modifiers are translated to CDP input bitmasks. `wait --load networkidle` uses per-target CDP Network events plus a quiet window rather than only checking `document.readyState`. Actions that can change page state are followed by a broker-side navigation check: same-target navigations are accepted only when the resulting URL stays inside the context's allowed-origin policy, same-policy popups are attached as broker-owned targets, and disallowed popups are closed. When an allowed-origin policy is configured, the broker also enables CDP Fetch interception and fails requests outside that policy while recording `browser_network.blocked` observations; this is request control, not host isolation. Before opening or navigating, the ToolBroker checks the trust-zone network policy and denies unsupported schemes, private-network destinations when disallowed, literal denied CIDRs, and, when runtime policy enforcement is enabled, hostnames that resolve to denied/private addresses. Host-level browser egress control remains outside the broker unless the configured browser process or host platform provides it. Snapshots use a bounded CDP `Runtime.evaluate` DOM read, actions resolve refs from the latest brokered snapshot where needed, console output is captured from CDP runtime/log events per target, and screenshot/PDF output is captured as SparseKernel artifacts, read back through artifact access, and converted to existing tool result formats for compatibility. Closing a broker-owned target now closes that target; the full browser context is released only when the last target closes or broker cleanup runs.
+Supported v0 actions (`status`, `doctor`, `profiles`, `tabs`, `open`, `navigate`, `focus`, `close`, `snapshot`, `console`, `screenshot`, `pdf`, direct file-input `upload`, `dialog`, and brokered `act`) operate against broker-owned targets inside the leased CDP context. Brokered `act` covers the OpenClaw action contract for click, coordinate click, type, press, hover, scroll, drag, select, fill, resize, wait, evaluate, close, and batch using CDP input events plus bounded DOM evaluation. Selector-backed actions retry inside the leased page until their action timeout and now require basic actionability before dispatch: visible connected target, stable bounding box, enabled form state where relevant, editable target for typing, and center-point hit testing. Selector click and hover resolve an actionable center point in the leased page and dispatch real CDP mouse events rather than handing raw DOM click events to page code; click, coordinate-click, and press modifiers are translated to CDP input bitmasks. `wait --load networkidle` uses per-target CDP Network events plus a quiet window rather than only checking `document.readyState`. Actions that can change page state are followed by a broker-side navigation check: same-target navigations are accepted only when the resulting URL stays inside the context's allowed-origin policy, same-policy popups are attached as broker-owned targets, and disallowed popups are closed. When an allowed-origin policy is configured, the broker also enables CDP Fetch interception and fails requests outside that policy while recording `browser_network.blocked` observations; this is request control, not host isolation. Before opening or navigating, the ToolBroker checks the trust-zone network policy and denies unsupported schemes, private-network destinations when disallowed, literal denied CIDRs, and, when runtime policy enforcement is enabled, hostnames that resolve to denied/private addresses. Host-level browser egress control remains outside the broker unless the configured browser process or host platform provides it. Snapshots use a bounded CDP `Runtime.evaluate` DOM read, actions resolve refs from the latest brokered snapshot where needed, console output is captured from CDP runtime/log events per target, and screenshot/PDF output is captured as SparseKernel artifacts, read back through artifact access, and converted to existing tool result formats for compatibility. Closing a broker-owned target now closes that target; the full browser context is released only when the last target closes or broker cleanup runs.
 
 Use `openclaw sparsekernel browser-pools` to inspect durable ledger pools and currently materialized native browser process pools. Native pool snapshots include trust zone, profile, active refs, max context slots, idle timeout, endpoint, PID when available, last activity, start count, clean stop count, and crash count.