kobako 0.28.0 → 0.30.0

data/crates/kobako-wasmtime/src/descriptors.rs

@@ -0,0 +1,200 @@
+//! The guest's descriptor table: what each preview1 file descriptor
+//! stands for within one invocation.
+//!
+//! kobako answers every preview1 call that reads this table, so the guest
+//! sees one table and no call falls through to a second one that
+//! disagrees. Numbering follows Linux's `alloc_fd`: the lowest closed number
+//! is reused before a fresh one is taken.
+
+use std::collections::{BTreeMap, BTreeSet};
+use std::sync::Arc;
+
+use kobako_runtime::filesystem::FilesystemError;
+use kobako_runtime::mount::Mount;
+use kobako_runtime::profile::Profile;
+use kobako_runtime::security::{restrict_self, WalkGuard};
+use kobako_runtime::vfs::{Cred, File};
+
+/// What one descriptor stands for, as Linux's fd table holds a `struct file`.
+pub(crate) struct Descriptor {
+    pub(crate) file: File,
+    /// The guest path a preopen names; a Mount's own root has one.
+    pub(crate) preopen_path: Option<String>,
+}
+
+impl Descriptor {
+    /// The descriptor of `file`, naming no preopen.
+    pub(crate) fn for_file(file: File) -> Self {
+        Self {
+            file,
+            preopen_path: None,
+        }
+    }
+}
+
+pub(crate) struct Descriptors {
+    used: BTreeMap<u32, Descriptor>,
+    free: BTreeSet<u32>,
+    limit: Option<usize>,
+    /// Who the guest's calls are made for, as a task holds its `cred`.
+    cred: Arc<Cred>,
+    /// What a descriptor's call asks before it starts.
+    walk_guard: WalkGuard,
+    /// The isolation the guest runs under, which decides what it sees of
+    /// the times a Filesystem reports.
+    profile: Profile,
+}
+
+impl Descriptors {
+    /// The table every invocation starts from: stdin, then the two
+    /// Channels, then one preopen per Mount from descriptor 3. It holds at
+    /// most `limit` descriptors, those included, as a process's
+    /// `RLIMIT_NOFILE` counts every one it holds. Each Mount's root opens as
+    /// `opener`, the Cred the Driver prepared, before its Policy applies.
+    pub(crate) fn new(
+        stdin: File,
+        stdout: File,
+        stderr: File,
+        mounts: Vec<Mount>,
+        limit: Option<usize>,
+        opener: Arc<Cred>,
+        profile: Profile,
+    ) -> Result<Self, FilesystemError> {
+        let mut used = BTreeMap::from([
+            (0, Descriptor::for_file(stdin)),
+            (1, Descriptor::for_file(stdout)),
+            (2, Descriptor::for_file(stderr)),
+        ]);
+        // Each Mount's root opens before its Policy applies, as a Linux task
+        // opens what it keeps and then calls `landlock_restrict_self`, so a
+        // Policy judges only what the guest asks for.
+        for (fd, mount) in (3..).zip(&mounts) {
+            used.insert(
+                fd,
+                Descriptor {
+                    file: File::root(mount.mnt(), &opener)?,
+                    preopen_path: Some(mount.at().to_string()),
+                },
+            );
+        }
+        let cred = restrict_self(&opener, &mounts);
+        let walk_guard = WalkGuard::new(&mounts);
+        Ok(Self {
+            used,
+            free: BTreeSet::new(),
+            limit,
+            cred,
+            walk_guard,
+            profile,
+        })
+    }
+
+    /// Who the guest's calls are made for.
+    pub(crate) fn cred(&self) -> &Arc<Cred> {
+        &self.cred
+    }
+
+    /// What every call through a descriptor asks first, so a Policy judges the
+    /// path it stands at.
+    pub(crate) fn walk_guard(&self) -> &WalkGuard {
+        &self.walk_guard
+    }
+
+    /// The isolation the guest runs under.
+    pub(crate) fn profile(&self) -> Profile {
+        self.profile
+    }
+
+    pub(crate) fn get(&self, fd: u32) -> Option<&Descriptor> {
+        self.used.get(&fd)
+    }
+
+    pub(crate) fn get_mut(&mut self, fd: u32) -> Option<&mut Descriptor> {
+        self.used.get_mut(&fd)
+    }
+
+    /// Take `fd` out of the table, freeing its number for reuse.
+    pub(crate) fn remove(&mut self, fd: u32) -> Option<Descriptor> {
+        let descriptor = self.used.remove(&fd)?;
+        self.free.insert(fd);
+        Some(descriptor)
+    }
+
+    /// Place `descriptor` at `fd`, a number the caller has just freed or
+    /// `lowest_unused` found, as Linux's `fd_install` does.
+    pub(crate) fn place(&mut self, fd: u32, descriptor: Descriptor) {
+        self.free.remove(&fd);
+        self.used.insert(fd, descriptor);
+    }
+
+    /// The number the next descriptor takes, the lowest freed one or the one
+    /// past the highest in use, as Linux's `get_unused_fd_flags` finds it;
+    /// `None` when the table holds as many as it may. Nothing is placed
+    /// until `place`, as `fd_install` fills what was found.
+    pub(crate) fn lowest_unused(&self) -> Option<u32> {
+        if self.limit.is_some_and(|limit| self.used.len() >= limit) {
+            return None;
+        }
+        match self.free.first() {
+            Some(fd) => Some(*fd),
+            None => match self.used.last_key_value() {
+                Some((last, _)) => last.checked_add(1),
+                None => Some(0),
+            },
+        }
+    }
+
+    /// Add `descriptor` under the number `lowest_unused` finds; `None` when
+    /// the table is full.
+    #[cfg(test)]
+    pub(crate) fn push(&mut self, descriptor: Descriptor) -> Option<u32> {
+        let fd = self.lowest_unused()?;
+        self.place(fd, descriptor);
+        Some(fd)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use kobako_runtime::filesystem::{create_pipe_files, PipeInodeInfo};
+    use kobako_runtime::security::prepare_creds_within;
+
+    fn pipe_end() -> File {
+        create_pipe_files(&PipeInodeInfo::new(1), &prepare_creds_within(&[], None)).1
+    }
+
+    // @behavior RT-189
+    #[test]
+    fn a_new_descriptor_takes_the_lowest_closed_number() {
+        let mut table = Descriptors::new(
+            pipe_end(),
+            pipe_end(),
+            pipe_end(),
+            Vec::new(),
+            None,
+            prepare_creds_within(&[], None),
+            Profile::Hermetic,
+        )
+        .unwrap_or_else(|_| panic!("a table holding no Mount must make"));
+        let mut open = || {
+            table
+                .push(Descriptor::for_file(pipe_end()))
+                .expect("a table with no limit takes every descriptor")
+        };
+        let numbers = [open(), open(), open()];
+        assert_eq!(numbers, [3, 4, 5], "descriptors must number from 3");
+        table.remove(3);
+        table.remove(4);
+        assert_eq!(
+            (
+                table.push(Descriptor::for_file(pipe_end())),
+                table.push(Descriptor::for_file(pipe_end())),
+                table.push(Descriptor::for_file(pipe_end())),
+            ),
+            (Some(3), Some(4), Some(6)),
+            "path_open's descriptors must take the lowest closed number first, as Linux's alloc_fd \
+             does, and then the one past the highest"
+        );
+    }
+}

data/crates/kobako-wasmtime/src/driver.rs

@@ -9,29 +9,32 @@
 
 use std::path::Path;
 use std::sync::Arc;
-use std::time::Instant;
 
 use wasmtime::{
     AsContextMut, InstancePre as WtInstancePre, ResourceLimiter, Store as WtStore, TypedFunc,
 };
 
-use crate::cache::shared_engine;
+use crate::cache::load_engine;
 use crate::config::Config;
 use crate::exports::{self, Exports};
+use crate::guest::Guest;
 use crate::invocation::Invocation;
-use crate::{capture, guest_mem, instance_pre, io, trap};
+use crate::wasi::Wasi;
+use crate::{instance_pre, trap};
 use kobako_runtime::dispatch::DispatchHandler;
+use kobako_runtime::endpoint;
 use kobako_runtime::error::{InvokeError, SetupError, Trap};
+use kobako_runtime::grant::{Grant, GrantKind};
 use kobako_runtime::profile::Profile;
 use kobako_runtime::runtime::{Entry, Runtime as ContractRuntime};
 use kobako_runtime::snapshot::{Capture, Completion, Snapshot, Usage};
-use kobako_transport::envelope::{CompileReply, Downcall, Preamble, Run, Snippet};
+use kobako_transport::envelope::Preamble;
 
 /// The wasmtime execution unit behind one sandbox runtime.
 pub struct Driver {
     // Pre-linked instantiation template (import wiring, type checks,
     // and the ABI version check done once in
-    // `instance_pre::cached_instance_pre`). Every invocation
+    // `instance_pre::load_instance_pre`). Every invocation
     // instantiates a fresh instance from it and discards the whole
     // Store afterwards — the per-invocation instance discipline.
     instance_pre: WtInstancePre<Invocation>,
@@ -45,15 +48,22 @@ impl Driver {
     /// neither leaves the driver.
     pub fn new(path: &Path, config: Config) -> Result<Self, SetupError> {
         Ok(Self {
-            instance_pre: instance_pre::cached_instance_pre(path)?,
+            instance_pre: instance_pre::load_instance_pre(path, config.setup_timeout)?,
             config,
         })
     }
 
-    fn new_store(&self) -> Result<WtStore<Invocation>, SetupError> {
-        let mut store = WtStore::new(shared_engine()?, Invocation::new(self.config.memory_limit));
+    /// The deadline and the `wall_time` bracket open with the Store, so
+    /// instantiating the guest and writing its request count against the
+    /// `timeout` as the export call does.
+    fn new_store(&self, wasi: Wasi) -> Result<WtStore<Invocation>, SetupError> {
+        let mut store = WtStore::new(
+            load_engine()?,
+            Invocation::new(self.config.memory_limit, wasi),
+        );
         store.limiter(|state: &mut Invocation| -> &mut dyn ResourceLimiter { state.limiter_mut() });
-        store.epoch_deadline_callback(trap::epoch_deadline_callback);
+        trap::arm_deadline(&mut store, self.config.timeout);
+        store.data_mut().start_wall_clock();
         Ok(store)
     }
 
@@ -63,7 +73,11 @@ impl Driver {
         let instance = self
             .instance_pre
             .instantiate(store.as_context_mut())
-            .map_err(|e| Trap::Other(format!("failed to instantiate the Sandbox runtime: {e}")))?;
+            .map_err(|e| {
+                trap::cap_trap(&e).unwrap_or_else(|| {
+                    Trap::Other(format!("failed to instantiate the Sandbox runtime: {e}"))
+                })
+            })?;
         let exports = Exports::resolve(&instance, store.as_context_mut());
         store.data_mut().set_exports(exports.clone());
         Ok(exports)
@@ -83,58 +97,46 @@ impl Driver {
         Params: wasmtime::WasmParams,
         Results: wasmtime::WasmResults,
     {
-        self.prime_caps(store, exports);
-        let result = export.call(store.as_context_mut(), params);
+        self.arm_memory_cap(store, exports);
+        // A wait for a lock the call meets ends at the same deadline the guest's
+        // code does, so another Sandbox holding it cannot keep this one past it.
+        let deadline = store.data().deadline();
+        let result = kobako_runtime::sched::run_task(deadline, || {
+            export.call(store.as_context_mut(), params)
+        });
         disarm_caps(store);
         result
     }
 
     /// The pre-initialized image's allocation is folded into the memory
-    /// baseline rather than the budget.
-    fn prime_caps(&self, store: &mut WtStore<Invocation>, exports: &Exports) {
-        match self.config.timeout {
-            Some(timeout) => {
-                let deadline = Instant::now() + timeout;
-                store.data_mut().set_deadline(Some(deadline));
-                store.set_epoch_deadline(1);
-            }
-            None => {
-                store.data_mut().set_deadline(None);
-                store.set_epoch_deadline(trap::NO_TIMEOUT_EPOCH_DELTA);
-            }
-        }
+    /// baseline rather than the budget, so the cap arms only once the
+    /// image is in place.
+    fn arm_memory_cap(&self, store: &mut WtStore<Invocation>, exports: &Exports) {
         let baseline = match exports.memory {
             Some(m) => m.data_size(store.as_context_mut()),
             None => 0,
         };
         store.data_mut().arm_memory_cap(baseline);
-        store.data_mut().start_wall_clock();
     }
 
     /// Built the same for every `completion`: captures and usage must
     /// survive a trap just as they do an outcome.
     fn build_snapshot(&self, store: &WtStore<Invocation>, completion: Completion) -> Snapshot {
         let data = store.data();
-        let usage = Usage {
-            wall_time: data.wall_time().as_secs_f64(),
-            memory_peak: data.memory_peak(),
+        let mut usage = Usage::default();
+        usage.wall_time = data.wall_time().as_secs_f64();
+        usage.memory_peak = data.memory_peak();
+        let clip = |bytes, limit| {
+            let mut capture = Capture::default();
+            (capture.bytes, capture.truncated) = endpoint::clip_capture(bytes, limit);
+            capture
         };
-        let (stdout_bytes, stdout_truncated) =
-            capture::clip_capture(data.stdout_bytes(), self.config.stdout_limit);
-        let (stderr_bytes, stderr_truncated) =
-            capture::clip_capture(data.stderr_bytes(), self.config.stderr_limit);
-        Snapshot {
+        Snapshot::new(
             completion,
-            stdout: Capture {
-                bytes: stdout_bytes,
-                truncated: stdout_truncated,
-            },
-            stderr: Capture {
-                bytes: stderr_bytes,
-                truncated: stderr_truncated,
-            },
+            clip(data.wasi().stdout_bytes(), self.config.stdout_limit),
+            clip(data.wasi().stderr_bytes(), self.config.stderr_limit),
             usage,
-        }
+        )
     }
 }
 
@@ -148,135 +150,68 @@ impl ContractRuntime for Driver {
         entry: Entry<'_>,
         preamble: &Preamble,
         handler: Option<Arc<dyn DispatchHandler>>,
+        grants: &[Grant],
     ) -> Result<Snapshot, InvokeError> {
-        let mut store = self.new_store()?;
+        let stdin =
+            endpoint::stdin_content(preamble).map_err(|msg| Trap::Other(msg.to_string()))?;
+        let wasi = Wasi::for_invocation(&self.config, stdin, grants)?;
+        let mut store = self.new_store(wasi)?;
         if let Some(handler) = handler {
             store.data_mut().bind_on_dispatch(handler);
         }
-        io::install_wasi(&mut store, &self.config, &preamble.encode())?;
         let exports = self.instantiate(&mut store)?;
         let downcall = exports::require(exports.downcall.as_ref())?;
-        let request = match entry {
-            Entry::Eval { source } => Downcall::Eval(source.to_vec()),
-            Entry::Run {
-                entrypoint,
-                payload,
-            } => Downcall::Run(Run {
-                entrypoint: entrypoint.to_owned(),
-                payload,
-            }),
-        }
-        .encode();
-        let (ptr, len) = io::write_request(&mut store, &exports, &request)?;
+        let request = endpoint::request_of(entry);
+        let (ptr, len) = endpoint::write_request(&mut guest_of(&mut store), &request)?;
         let called = self.call_with_caps(&mut store, &exports, downcall, (ptr, len));
         let completion = match called {
-            Ok(packed) => match io::read_outcome(&store, &exports, packed) {
+            Ok(packed) => match endpoint::read_outcome(&mut guest_of(&mut store), packed) {
                 Ok(outcome) => Completion::Outcome(outcome),
                 Err(t) => Completion::Trap(t),
             },
-            Err(e) => Completion::Trap(trap::trap_from(e)),
+            Err(e) => Completion::Trap(trap::to_trap(e)),
         };
         Ok(self.build_snapshot(&store, completion))
     }
 
     /// Exactly the rung `Config` requested. `Hermetic` freezes ambient time
-    /// and entropy; both rungs wire no filesystem, environment, or network,
+    /// and entropy; both rungs wire no ambient filesystem, environment, or network,
     /// and the linker adds only `__kobako_upcall` beyond that WASI surface.
     fn profile(&self) -> Profile {
         self.config.profile
     }
 
+    /// A Mount becomes a preopen of kobako's own descriptor table, which
+    /// answers every preview1 call beneath it.
+    fn supports(&self, kind: GrantKind) -> bool {
+        matches!(kind, GrantKind::Mount)
+    }
+
     /// Bounded by the same caps as an invocation, on an instance of its
     /// own that no script ever runs on, so what it answers carries
     /// nothing a script could have written.
     fn compile(&self, preamble: &Preamble) -> Option<Vec<Vec<u8>>> {
-        let mut store = self.new_store().ok()?;
-        io::install_wasi(&mut store, &self.config, &preamble.encode()).ok()?;
+        let wasi = Wasi::for_compile(&self.config, endpoint::stdin_content(preamble).ok()?).ok()?;
+        let mut store = self.new_store(wasi).ok()?;
         let exports = self.instantiate(&mut store).ok()?;
         let downcall = exports::require(exports.downcall.as_ref()).ok()?;
         let (ptr, len) =
-            io::write_request(&mut store, &exports, &Downcall::Compile.encode()).ok()?;
+            endpoint::write_request(&mut guest_of(&mut store), &endpoint::compile_request())
+                .ok()?;
         let packed = self
             .call_with_caps(&mut store, &exports, downcall, (ptr, len))
             .ok()?;
-        match io::read_compile_reply(&store, &exports, packed).ok()? {
-            CompileReply::Ok(bytecodes) => one_per_source(preamble, bytecodes)
-                .filter(|bytecodes| replay_fits(preamble, bytecodes)),
-            CompileReply::Error(_) | CompileReply::Unsupported(_) => None,
-        }
-    }
-}
-
-/// Each invocation sends the Preamble with every bytecode in place of its
-/// source, so an answer that would carry it past the payload cap would trap
-/// every invocation the source alone fits.
-fn replay_fits(preamble: &Preamble, bytecodes: &[Vec<u8>]) -> bool {
-    let mut replay = preamble.clone();
-    let sources = replay
-        .snippets
-        .entries
-        .iter_mut()
-        .filter(|entry| matches!(entry, Snippet::Source { .. }));
-    for (entry, body) in sources.zip(bytecodes) {
-        *entry = Snippet::Bytecode { body: body.clone() };
+        let reply = endpoint::read_compile_reply(&mut guest_of(&mut store), packed).ok()?;
+        endpoint::compiled_bytecodes(preamble, reply)
     }
-    guest_mem::checked_payload_len(replay.encode().len()).is_ok()
 }
 
-/// A frontend replays each bytecode in place of one source snippet, in
-/// order, so an answer of any other length leaves nothing to replay.
-fn one_per_source(preamble: &Preamble, bytecodes: Vec<Vec<u8>>) -> Option<Vec<Vec<u8>>> {
-    let sources = preamble
-        .snippets
-        .entries
-        .iter()
-        .filter(|entry| matches!(entry, Snippet::Source { .. }))
-        .count();
-    (bytecodes.len() == sources).then_some(bytecodes)
+/// The instance the runtime's host ABI endpoint drives, through `store`.
+fn guest_of(store: &mut WtStore<Invocation>) -> Guest<'_> {
+    Guest(store.as_context_mut())
 }
 
 fn disarm_caps(store: &mut WtStore<Invocation>) {
     store.data_mut().stop_wall_clock();
     store.data_mut().disarm_memory_cap();
 }
-
-#[cfg(test)]
-mod tests {
-    use kobako_transport::envelope::Snippets;
-
-    use super::*;
-
-    /// One source between two bytecode snippets: a compile answers one
-    /// bytecode for it.
-    fn one_source() -> Preamble {
-        let mut preamble = Preamble::default();
-        preamble.snippets = Snippets {
-            entries: vec![
-                Snippet::Bytecode { body: vec![0xaa] },
-                Snippet::Source {
-                    name: "Only".into(),
-                    body: "1".into(),
-                },
-                Snippet::Bytecode { body: vec![0xbb] },
-            ],
-        };
-        preamble
-    }
-
-    // @behavior WE-089
-    #[test]
-    fn a_compiled_answer_of_another_length_leaves_nothing_compiled() {
-        let preamble = one_source();
-
-        assert_eq!(
-            [
-                one_per_source(&preamble, Vec::new()),
-                one_per_source(&preamble, vec![vec![0x01], vec![0x02]]),
-                one_per_source(&preamble, vec![vec![0x01]]),
-            ],
-            [None, None, Some(vec![vec![0x01]])],
-            "a compiled answer through Driver#compile must be kept only when it carries one \
-             bytecode per source snippet"
-        );
-    }
-}

data/crates/kobako-wasmtime/src/exports.rs

@@ -10,19 +10,13 @@
 
 use wasmtime::{AsContextMut, Instance as WtInstance, Memory, TypedFunc};
 
-use crate::guest_mem::SANDBOX_RUNTIME_NOT_KOBAKO;
+use kobako_runtime::endpoint::RUNTIME_INCOMPATIBLE;
 use kobako_runtime::error::Trap;
 
-/// For a required guest export that is absent or mistyped, wherever it is
-/// looked up. Names neither the export nor a frontend's artifact path;
-/// what a caller can do is rebuild the runtime.
-pub(crate) const RUNTIME_INCOMPATIBLE: &str =
-    "the Sandbox runtime is incompatible; rebuild it against the kobako version in use";
-
 /// The resolved host-driven export handles. Each is `Option` because test
 /// fixtures (a minimal "ping" module) need not provide them; real
-/// `kobako.wasm` always does, and the run path surfaces a `Trap` (via
-/// `require` / `Exports::require_memory`) when a handle is `None`.
+/// `kobako.wasm` always does, and the run path surfaces a `Trap` when a
+/// handle is `None`.
 ///
 /// The handles are indices into the owning Store, not borrows of the
 /// `Instance` — they stay valid for the Store's lifetime, which is why
@@ -49,11 +43,6 @@ impl Exports {
             memory: instance.get_memory(&mut ctx, "memory"),
         }
     }
-
-    pub(crate) fn require_memory(&self) -> Result<Memory, Trap> {
-        self.memory
-            .ok_or_else(|| Trap::Other(SANDBOX_RUNTIME_NOT_KOBAKO.to_string()))
-    }
 }
 
 pub(crate) fn require<Params, Results>(
@@ -77,7 +66,7 @@ mod tests {
 
     use wasmtime::ExternType;
 
-    use crate::cache::cached_module;
+    use crate::cache::load_module;
 
     const WASM: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/../../data/kobako.wasm");
 
@@ -98,7 +87,7 @@ mod tests {
             );
             return;
         }
-        let module = cached_module(path).expect("the Guest Binary must load");
+        let module = load_module(path).expect("the Guest Binary must load");
 
         let mut functions: Vec<&str> = module
             .exports()

data/crates/kobako-wasmtime/src/guest.rs

@@ -0,0 +1,38 @@
+//! One wasmtime instance as the runtime's host ABI endpoint drives it, from the
+//! invocation body's `Store` and from a host import's `Caller` alike.
+
+use kobako_runtime::endpoint::{Calls, GuestInstance};
+use kobako_runtime::error::Trap;
+use wasmtime::StoreContextMut;
+
+use crate::invocation::Invocation;
+use crate::trap;
+
+pub(crate) struct Guest<'a>(pub(crate) StoreContextMut<'a, Invocation>);
+
+impl GuestInstance for Guest<'_> {
+    type Fault = wasmtime::Error;
+
+    fn calls(&mut self) -> &mut Calls<wasmtime::Error> {
+        self.0.data_mut().calls_mut()
+    }
+
+    fn memory(&mut self) -> Option<&mut [u8]> {
+        let memory = self.0.data().exports()?.memory?;
+        Some(memory.data_mut(&mut self.0))
+    }
+
+    fn alloc(&mut self, len: u32) -> Option<wasmtime::Result<u32>> {
+        let alloc = self.0.data().exports()?.alloc?;
+        Some(alloc.call(&mut self.0, len))
+    }
+
+    fn downcall(&mut self, ptr: i32, len: i32) -> Option<wasmtime::Result<u64>> {
+        let downcall = self.0.data().exports()?.downcall?;
+        Some(downcall.call(&mut self.0, (ptr, len)))
+    }
+
+    fn cap_trap(fault: &wasmtime::Error) -> Option<Trap> {
+        trap::cap_trap(fault)
+    }
+}

data/crates/kobako-wasmtime/src/imports.rs

@@ -0,0 +1,52 @@
+//! The host imports a Guest Binary resolves: the WASI preview1 set and
+//! the wire ABI's `__kobako_upcall`.
+//!
+//! Both closures read all their state from the `Invocation` inside the
+//! calling Store, never from a Runtime, so the wiring is the same for
+//! every Sandbox and `crate::instance_pre` can cache what it resolves.
+
+use wasmtime::{AsContextMut, Caller, Linker};
+use wasmtime_wasi::p1;
+
+use crate::cache::load_engine;
+use crate::guest::Guest;
+use crate::invocation::Invocation;
+use crate::preview1;
+use kobako_runtime::endpoint::{self, UpcallEnd, ABANDONED};
+use kobako_runtime::error::SetupError;
+
+pub(crate) fn linker() -> Result<Linker<Invocation>, SetupError> {
+    let mut linker: Linker<Invocation> = Linker::new(load_engine()?);
+
+    // Wire the wasmtime-wasi preview1 WASI imports against each
+    // invocation's own `Wasi` context, then answer every call that reads
+    // a descriptor from kobako's own table, which routes guest fd 1/2 to
+    // its capture pipes.
+    p1::add_to_linker_sync(&mut linker, |state: &mut Invocation| {
+        state.wasi_mut().ctx_mut()
+    })
+    .and_then(|_| preview1::shadow(&mut linker))
+    .map_err(|e| SetupError::Dead(format!("failed to set up the WASI runtime: {e}")))?;
+
+    // `__kobako_upcall`, `(ptr: i32, len: i32) -> i64` in the ABI;
+    // `endpoint::handle` owns what it answers.
+    linker
+        .func_wrap(
+            "env",
+            "__kobako_upcall",
+            |mut caller: Caller<'_, Invocation>,
+             req_ptr: i32,
+             req_len: i32|
+             -> wasmtime::Result<i64> {
+                let mut guest = Guest(caller.as_context_mut());
+                endpoint::handle(&mut guest, req_ptr, req_len).map_err(|end| match end {
+                    UpcallEnd::Fault(trap) => trap,
+                    UpcallEnd::Abandoned => wasmtime::Error::msg(ABANDONED),
+                    UpcallEnd::Unwritable(reason) => wasmtime::Error::msg(reason),
+                })
+            },
+        )
+        .map_err(|e| SetupError::Dead(format!("failed to set up the host callback bridge: {e}")))?;
+
+    Ok(linker)
+}