fix(security): revoke execution-scoped capabilities

Author: chaliy

README.md

@@ -292,6 +292,10 @@ assert_eq!(bash.exec("greet Alice").await?.stdout, "hello Alice\n");
 # }
 ```
 
+Registry builtins get execution-scoped VFS/request handles by default. Only
+trusted host code that intentionally needs a session-lived VFS handle should
+use `registry.insert_trusted(...)`.
+
 Node (`@everruns/bashkit`):
 
 ```typescript

crates/bashkit-python/src/lib.rs

@@ -3963,7 +3963,7 @@ impl PyCustomBuiltinAdapter {
 #[async_trait]
 impl Builtin for PyCustomBuiltinAdapter {
     async fn execute(&self, ctx: BuiltinContext<'_>) -> bashkit::Result<RustExecResult> {
-        let session = ctx.execution_extension::<Arc<PyCallbackSession>>().cloned();
+        let session = ctx.execution_extension::<Arc<PyCallbackSession>>();
         let builtin_arg = Python::attach(|py| -> Result<Py<PyAny>, String> {
             let builtin_arg = make_py_builtin_context(py, &self.name, &ctx, &self.rt)
                 .map_err(|e| format!("{}: {}", self.name, e))?
@@ -3974,27 +3974,34 @@ impl Builtin for PyCustomBuiltinAdapter {
         });
         let callback_result = match builtin_arg {
             Ok(builtin_arg) if self.is_async => match session {
-                Some(session) => {
-                    call_python_callback_async(
-                        session,
-                        &self.name,
-                        &self.callback,
-                        vec![builtin_arg],
-                    )
-                    .await
-                }
+                Some(session) => match session.try_with(Clone::clone) {
+                    Ok(callback_session) => session
+                        .run(call_python_callback_async(
+                            callback_session,
+                            &self.name,
+                            &self.callback,
+                            vec![builtin_arg],
+                        ))
+                        .await
+                        .unwrap_or_else(|error| Err(format!("{}: {error}", self.name))),
+                    Err(error) => Err(format!("{}: {error}", self.name)),
+                },
                 None => Err(format!("{}: missing Python callback session", self.name)),
             },
             Ok(builtin_arg) => match session {
-                Some(session) => Python::attach(|py| {
-                    call_python_callback_sync(
-                        py,
-                        session.as_ref(),
-                        &self.name,
-                        &self.callback,
-                        vec![builtin_arg],
-                    )
-                }),
+                Some(session) => session
+                    .try_with(|session| {
+                        Python::attach(|py| {
+                            call_python_callback_sync(
+                                py,
+                                session.as_ref(),
+                                &self.name,
+                                &self.callback,
+                                vec![builtin_arg],
+                            )
+                        })
+                    })
+                    .unwrap_or_else(|error| Err(format!("{}: {error}", self.name))),
                 None => Err(format!("{}: missing Python callback session", self.name)),
             },
             Err(err) => Err(err),

crates/bashkit/docs/custom_builtins.md

@@ -1,9 +1,10 @@
 # Custom Builtins
 
 Bashkit supports registering custom builtin commands to extend the shell with
-domain-specific functionality. Custom builtins have full access to the execution
-context including arguments, environment variables, shell variables, and the
-virtual filesystem.
+domain-specific functionality. Custom builtins receive an execution-scoped
+context including arguments, environment variables, shell variables, and a
+revocable virtual-filesystem view. Retaining the VFS or extension handles is
+safe: access fails deterministically after that `exec*()` completes or is cancelled.
 
 **See also:**
 - [API Documentation](https://docs.rs/bashkit) - Full API reference
@@ -95,7 +96,7 @@ impl Builtin for RequestId {
     async fn execute(&self, ctx: BuiltinContext<'_>) -> bashkit::Result<ExecResult> {
         let req = ctx
             .execution_extension::<String>()
-            .cloned()
+            .and_then(|req| req.try_with(Clone::clone).ok())
             .unwrap_or_else(|| "missing".to_string());
         Ok(ExecResult::ok(format!("{req}\n")))
     }
@@ -247,6 +248,10 @@ The registry is host-owned: not part of interpreter state, so it survives
 `exec()` calls automatically and is not serialized by `Bash::snapshot()`.
 Re-attach the handle after restoring from a snapshot.
 
+`BuiltinRegistry::insert` uses the same execution-scoped facilities as builder
+builtins. A trusted embedder that deliberately needs a retained, session-lived
+VFS handle must opt in with `insert_trusted`; do not use it for tenant/plugin code.
+
 ### Arguments
 
 Arguments are passed as a slice of strings, excluding the command name itself:

crates/bashkit/docs/threat-model.md

@@ -507,7 +507,7 @@ echo $user_input
 | `$?` leaks into VFS subprocess (TM-ISO-024) | Parent `last_exit_code` visible in child, causing false `set -e` failures | Child resets `last_exit_code`, `nounset_error`, and traps | **MITIGATED** |
 | Wrapper rebuild drops constructor capabilities (TM-ISO-025) | A binding reset loses limits, policy files, callbacks, or network policy | Canonical capability matrix with executable evidence; rebuilds retain constructor config | **MITIGATED** |
 | Shared ToolRegistry request context (TM-ISO-026) | Concurrent shell/Python/TypeScript calls leak tenant identity or traces | Per-request `ExecutionExtensions`, task-local runtime routing, and callback-owned context | **MITIGATED** |
-| Stale request execution authority (TM-ISO-027) | A late runtime/transport/callback result crosses completion, cancellation, timeout, or reuse | Shared request budget, cancellation-aware awaits, post-await checks, and RAII closure/release | **MITIGATED** |
+| Stale request authority and retained host-extension handles (TM-ISO-027) | A late runtime/transport/callback result crosses completion, or a builtin/tool keeps VFS or request context past completion/cancellation | Shared request budget plus one revocable capability lease, cancellation-aware awaits, deterministic late-use failure, RAII closure/release, and explicit `insert_trusted` escape hatch | **MITIGATED** |
 
 Each [`Bash`] instance is fully isolated. For multi-tenant environments, create
 separate instances per tenant:

crates/bashkit/src/builtins/awk/mod.rs

@@ -562,10 +562,12 @@ impl Builtin for Awk {
         let program = parser.parse()?;
 
         let mut interp = AwkInterpreter::new();
-        interp.execution_budget = ctx.execution_budget().cloned();
+        interp.execution_budget = ctx
+            .execution_budget()
+            .and_then(|budget| budget.try_with(Clone::clone).ok());
         interp.max_loop_iterations = ctx
             .execution_extension::<ExecutionLimits>()
-            .map(|limits| limits.max_loop_iterations)
+            .and_then(|limits| limits.try_with(|limits| limits.max_loop_iterations).ok())
             .unwrap_or_else(|| ExecutionLimits::default().max_loop_iterations);
         interp.functions = program.functions.clone();
         interp.state.fs = Self::process_escape_sequences(&field_sep);

crates/bashkit/src/builtins/jq/mod.rs

@@ -349,7 +349,7 @@ async fn run_jq(ctx: Context<'_>, parsed: JqArgs<'_>) -> Result<ExecResult> {
     // periodically so a runaway filter aborts instead of wedging the host.
     let max_output_bytes = ctx
         .execution_extension::<ExecutionLimits>()
-        .map(|l| l.max_stdout_bytes)
+        .and_then(|limits| limits.try_with(|limits| limits.max_stdout_bytes).ok())
         .unwrap_or_else(|| ExecutionLimits::default().max_stdout_bytes);
     let deadline = ctx.execution_extension::<ExecutionDeadline>();
     let mut values_emitted: usize = 0;
@@ -431,7 +431,11 @@ async fn run_jq(ctx: Context<'_>, parsed: JqArgs<'_>) -> Result<ExecResult> {
                     }
                     values_emitted += 1;
                     if values_emitted.is_multiple_of(4096)
-                        && deadline.is_some_and(ExecutionDeadline::is_expired)
+                        && deadline.as_ref().is_some_and(|deadline| {
+                            deadline
+                                .try_with(ExecutionDeadline::is_expired)
+                                .unwrap_or(true)
+                        })
                     {
                         return Ok(ExecResult::err("jq: execution timed out\n".to_string(), 5));
                     }