kobako 0.28.0 → 0.30.0

data/crates/kobako-runtime/src/mount.rs

@@ -0,0 +1,105 @@
+//! A Mount: the Grant handing a Filesystem to the guest at an absolute
+//! guest path, with the access it allows there and the Policy that may refuse
+//! more, which the VFS asks through its Cred, so a Filesystem of a third
+//! party's checks nothing.
+
+use std::fmt;
+use std::sync::Arc;
+
+use crate::filesystem::Filesystem;
+use crate::vfs::VfsMount;
+
+/// What a Mount allows a guest beneath it, and what a Policy is asked to allow
+/// for one path.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Access {
+    Read,
+    ReadWrite,
+}
+
+/// The Host App's decision for one path a guest opens or changes, made after
+/// a Mount's access allows it, so it can only refuse more.
+pub trait Policy: Send + Sync {
+    /// Whether the guest may reach `path`, the absolute guest path, with
+    /// `access`.
+    fn allows(&self, path: &str, access: Access) -> bool;
+}
+
+/// A Filesystem instance at an absolute guest path. Its path bounds what a
+/// Policy can allow either way.
+#[derive(Clone)]
+pub struct Mount {
+    at: String,
+    policy: Option<Arc<dyn Policy>>,
+    mnt: Arc<VfsMount>,
+}
+
+/// A path no Mount can stand at: one that is not an absolute guest path.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct MountPathError(String);
+
+impl fmt::Display for MountPathError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(
+            f,
+            "mount path must be an absolute guest path, got {:?}",
+            self.0
+        )
+    }
+}
+
+impl std::error::Error for MountPathError {}
+
+/// An absolute guest path has no empty, `.`, or `..` component; the root
+/// is `/` alone.
+fn is_guest_path(at: &str) -> bool {
+    at == "/"
+        || at.strip_prefix('/').is_some_and(|rest| {
+            rest.split('/')
+                .all(|part| !part.is_empty() && part != "." && part != "..")
+        })
+}
+
+impl Mount {
+    /// A Mount of `filesystem` at `at`, refused unless `at` is an absolute
+    /// guest path, which every path the Mount answers for is built on.
+    pub fn new(
+        at: impl Into<String>,
+        filesystem: Arc<Filesystem>,
+        access: Access,
+    ) -> Result<Self, MountPathError> {
+        let at = at.into();
+        if !is_guest_path(&at) {
+            return Err(MountPathError(at));
+        }
+        Ok(Self {
+            at,
+            mnt: VfsMount::new(filesystem, access == Access::Read),
+            policy: None,
+        })
+    }
+
+    /// This Mount with `policy` also judging each open and each change its
+    /// access allows; it can only refuse more, as an LSM can.
+    pub fn with_policy(self, policy: Arc<dyn Policy>) -> Self {
+        Self {
+            policy: Some(policy),
+            ..self
+        }
+    }
+
+    /// The Filesystem as the VFS walks it.
+    pub fn mnt(&self) -> &Arc<VfsMount> {
+        &self.mnt
+    }
+
+    /// The Policy deciding beneath this Mount, once one was given.
+    pub(crate) fn policy(&self) -> Option<&Arc<dyn Policy>> {
+        self.policy.as_ref()
+    }
+
+    /// The absolute guest path the Filesystem appears at.
+    pub fn at(&self) -> &str {
+        &self.at
+    }
+}

data/crates/kobako-runtime/src/profile.rs

@@ -6,13 +6,20 @@
 //! actually built, and the frontend refuses a declaration below the
 //! request — so the request is also the floor.
 
+use std::hash::{BuildHasher, RandomState};
+use std::sync::LazyLock;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use crate::vfs::{FileType, Identity, Kstat};
+
 /// The ordered isolation ladder a runtime builds one rung of.
 ///
 /// `Hermetic` is the full ambient-denial posture: ambient time and
-/// entropy denied at the WASI boundary, no filesystem / environment /
-/// network reachability, and no host import beyond the wire ABI's
-/// `__kobako_upcall`. `Permissive` differs in exactly one grant —
-/// live ambient time and entropy at the WASI boundary. Ordering
+/// entropy denied at the WASI boundary, no ambient filesystem /
+/// environment / network reachability, and no host import beyond the wire ABI's
+/// `__kobako_upcall`. `Permissive` differs only in the ambient
+/// authority it grants — live time and entropy at the WASI boundary — and in
+/// the times and inode numbers it shows of an entry. Ordering
 /// follows strength (`Permissive < Hermetic`), so a floor check is a
 /// plain comparison.
 ///
@@ -29,10 +36,139 @@ pub enum Profile {
     Hermetic,
 }
 
+impl Profile {
+    /// The inode number a guest on this posture sees for `identity`. A
+    /// hermetic guest sees none, as a Filesystem's device number depends on
+    /// how many were made before it in the process. Any other sees a hash of
+    /// it under a key the process draws once, so it can tell entries apart
+    /// and cannot work back to a host's inode number.
+    pub fn guest_ino(self, identity: Option<Identity>) -> u64 {
+        static KEY: LazyLock<RandomState> = LazyLock::new(RandomState::new);
+        match (self, identity) {
+            (Self::Hermetic, _) | (_, None) => 0,
+            (Self::Permissive, Some(identity)) => KEY.hash_one(identity),
+        }
+    }
+
+    /// `stat` as a guest on this posture sees it, whichever ABI a Wasm
+    /// Driver encodes it into. A Filesystem records the host's real time whatever
+    /// the invocation writing to it runs under, so one shared across
+    /// invocations keeps one record; a hermetic guest sees every time at the
+    /// Unix epoch, where its wall clock stands, so a time a write left behind
+    /// is no clock it can read. A link reports no size, so nothing of where it
+    /// points reaches the guest, and an entry is told apart only by what
+    /// `guest_ino` answers.
+    pub fn guest_kstat(self, stat: Kstat) -> Kstat {
+        let ino = self.guest_ino(Identity::of(&stat));
+        let masked = match self {
+            Self::Permissive => stat,
+            Self::Hermetic => {
+                let epoch = |time: Option<SystemTime>| time.map(|_| UNIX_EPOCH);
+                stat.with_times(epoch(stat.atime), epoch(stat.mtime), epoch(stat.ctime))
+            }
+        };
+        Kstat {
+            size: match masked.file_type {
+                FileType::Symlink => 0,
+                _ => masked.size,
+            },
+            ..masked.with_identity(0, ino)
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
 
+    // The Wasm Driver only encodes this, so another one shows the same, and a
+    // guest reads a link's size and a time here or nowhere.
+    // @behavior RT-173 RT-183
+    #[test]
+    fn a_guest_sees_no_size_for_a_link_and_only_what_its_posture_allows() {
+        let reported = Kstat::new(FileType::Symlink, 42)
+            .with_identity(7, 9)
+            .with_times(Some(SystemTime::now()), None, None);
+        let (hermetic, permissive) = (
+            Profile::Hermetic.guest_kstat(reported),
+            Profile::Permissive.guest_kstat(reported),
+        );
+        assert_eq!(
+            (hermetic.size, permissive.size, hermetic.ino, hermetic.atime),
+            (0, 0, 0, Some(UNIX_EPOCH)),
+            "Profile::guest_kstat of a link must report no size on any posture, and at the \
+             hermetic rung no inode number and every time at the Unix epoch"
+        );
+        assert!(
+            permissive.ino != 0 && permissive.ino != 9 && permissive.atime == reported.atime,
+            "Profile::guest_kstat at the permissive rung must hash the inode number and keep \
+             the time"
+        );
+    }
+
+    // A device number depends on how many Filesystems the process made before,
+    // so the inode number a guest reads folds it in and the device stays out.
+    // @behavior RT-283
+    #[test]
+    fn a_guest_sees_one_device_for_every_entry() {
+        let reported = Kstat::new(FileType::RegFile, 1).with_identity(7, 9);
+        assert_eq!(
+            [Profile::Hermetic, Profile::Permissive]
+                .map(|profile| profile.guest_kstat(reported).dev),
+            [0, 0],
+            "Profile::guest_kstat of an entry a Filesystem reports on device 7 must report \
+             device 0 on either posture"
+        );
+    }
+
+    // An unkeyed hash answers what anyone can compute from a host's numbers,
+    // so the hash a guest reads must differ from it.
+    // @behavior RT-194
+    #[test]
+    fn a_guest_cannot_compute_the_inode_number_it_reads() {
+        use std::collections::hash_map::DefaultHasher;
+        use std::hash::{Hash, Hasher};
+
+        let reported = Kstat::new(FileType::RegFile, 0).with_identity(7, 9);
+        let identity = Identity::of(&reported);
+        let mut unkeyed = DefaultHasher::new();
+        identity
+            .expect("an inode number names an identity")
+            .hash(&mut unkeyed);
+        let seen = Profile::Permissive.guest_ino(identity);
+        assert_eq!(
+            seen,
+            Profile::Permissive.guest_ino(identity),
+            "Profile::guest_ino of one identity must answer one number within a process"
+        );
+        assert_ne!(
+            seen,
+            unkeyed.finish(),
+            "Profile::guest_ino at the permissive rung must not answer a hash anyone can compute \
+             from the device and inode numbers"
+        );
+    }
+
+    // A guest reads the count on any ABI, so the count starts in the runtime
+    // rather than in what a Wasm Driver encodes.
+    // @behavior RT-193
+    #[test]
+    fn an_entry_whose_filesystem_keeps_no_count_is_named_once() {
+        let reported = Kstat::new(FileType::RegFile, 0);
+        assert_eq!(
+            (
+                Profile::Hermetic.guest_kstat(reported).nlink,
+                Profile::Permissive.guest_kstat(reported).nlink,
+                Profile::Permissive
+                    .guest_kstat(reported.with_nlink(3))
+                    .nlink,
+            ),
+            (1, 1, 3),
+            "Profile::guest_kstat of an entry reporting no count must show one name on each \
+             posture, and of one reporting three must show three"
+        );
+    }
+
     // @behavior RT-014
     #[test]
     fn a_declaration_satisfies_any_floor_at_or_below_it() {

data/crates/kobako-runtime/src/runtime.rs

@@ -13,6 +13,7 @@ use kobako_transport::envelope::Preamble;
 
 use crate::dispatch::DispatchHandler;
 use crate::error::InvokeError;
+use crate::grant::{Grant, GrantKind};
 use crate::profile::Profile;
 use crate::snapshot::Snapshot;
 
@@ -49,13 +50,24 @@ pub enum Entry<'a> {
 /// wrapper and GC-marking it; the runtime itself touches no frontend
 /// value.
 pub trait Runtime {
+    /// `grants` are this Invocation's, each of a kind `supports` declared;
+    /// the runtime presents them to the guest and keeps none afterwards.
     fn invoke(
         &self,
         entry: Entry<'_>,
         preamble: &Preamble,
         handler: Option<Arc<dyn DispatchHandler>>,
+        grants: &[Grant],
     ) -> Result<Snapshot, InvokeError>;
 
+    /// Whether this runtime presents a Grant of `kind` to the guest. A
+    /// frontend refuses to register one it does not, before any guest runs.
+    /// The default supports none, so an engine that has not learned Grants
+    /// still serves every invocation without one.
+    fn supports(&self, _kind: GrantKind) -> bool {
+        false
+    }
+
     /// The isolation profile this runtime provides. Deliberately
     /// without a default: every engine states its posture explicitly,
     /// and a frontend refuses construction when the declaration falls

data/crates/kobako-runtime/src/sched.rs

@@ -0,0 +1,210 @@
+//! Who is running and how it waits, beneath every lock, as Linux's
+//! `kernel/sched` is: a lock asks only for its wait to happen, so nothing
+//! above it knows what waiting means to the frontend. A run past its deadline,
+//! or one its frontend interrupted, stops waiting, as a fatal signal ends
+//! Linux's killable waits, so one Sandbox holding a lock never holds another's
+//! thread past that one's own end.
+
+use std::cell::RefCell;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, OnceLock};
+use std::thread::{self, ThreadId};
+use std::time::{Duration, Instant};
+
+/// How a thread waits for a lock another thread holds. A frontend whose
+/// threads share a lock of their own, as Ruby's threads share the GVL,
+/// gives that lock up for the wait, or a holder that needs it to finish
+/// never could.
+pub trait Blocking: Send + Sync {
+    /// Run `wait`, which returns once the lock is taken.
+    fn wait(&self, wait: &mut dyn FnMut());
+}
+
+static BLOCKING: OnceLock<Box<dyn Blocking>> = OnceLock::new();
+
+/// Have every thread of this process wait through `blocking`, as a frontend
+/// says once at startup; a later one is handed back, as
+/// `register_filesystem` refuses a second. Without one a thread just waits.
+pub fn register_blocking(blocking: Box<dyn Blocking>) -> Result<(), Box<dyn Blocking>> {
+    BLOCKING.set(blocking)
+}
+
+/// Run `wait` as this process's threads wait, as a lock's slow path calls
+/// `schedule`.
+pub(crate) fn schedule(wait: &mut dyn FnMut()) {
+    match BLOCKING.get() {
+        Some(blocking) => blocking.wait(wait),
+        None => wait(),
+    }
+}
+
+thread_local! {
+    static CURRENT: ThreadId = thread::current().id();
+}
+
+/// Who is running, as Linux's `current`.
+pub(crate) fn current() -> ThreadId {
+    CURRENT.with(|current| *current)
+}
+
+/// A thread as its frontend may interrupt it from another thread, as a signal
+/// reaches a Linux task.
+#[derive(Clone, Default)]
+pub struct Task {
+    interrupted: Arc<AtomicBool>,
+}
+
+impl Task {
+    /// The calling thread.
+    pub fn current() -> Self {
+        TASK.with(|task| task.borrow().task.clone())
+    }
+
+    /// Have every wait of the run this thread carries out stop, as a fatal
+    /// signal ends a killable wait; it holds until that run ends.
+    pub fn interrupt(&self) {
+        self.interrupted.store(true, Ordering::SeqCst);
+    }
+}
+
+/// The task this thread carries out, as Linux's `current`, and when its run is
+/// to stop.
+#[derive(Default)]
+struct Current {
+    task: Task,
+    deadline: Option<Instant>,
+    /// How many runs the thread is inside, one within another where a
+    /// Filesystem's own call starts another.
+    depth: usize,
+}
+
+thread_local! {
+    static TASK: RefCell<Current> = RefCell::default();
+}
+
+/// Run `run` as a run that stops waiting once `deadline` passes or its thread
+/// is interrupted, as a Linux task stops a killable wait on a fatal signal. A
+/// run within another keeps the outer one's interrupt.
+pub fn run_task<T>(deadline: Option<Instant>, run: impl FnOnce() -> T) -> T {
+    /// Puts back the deadline of the run around this one, however `run` ends,
+    /// and lets an interrupt go once no run is left.
+    struct Outer(Option<Instant>);
+
+    impl Drop for Outer {
+        fn drop(&mut self) {
+            TASK.with(|task| {
+                let mut running = task.borrow_mut();
+                running.deadline = self.0;
+                running.depth -= 1;
+                if running.depth == 0 {
+                    running.task.interrupted.store(false, Ordering::SeqCst);
+                }
+            });
+        }
+    }
+
+    let _outer = Outer(TASK.with(|task| {
+        let mut running = task.borrow_mut();
+        running.depth += 1;
+        std::mem::replace(&mut running.deadline, deadline)
+    }));
+    run()
+}
+
+/// Whether the calling thread's run is to stop waiting, as Linux's
+/// `fatal_signal_pending(current)` answers.
+pub(crate) fn fatal_signal_pending() -> bool {
+    TASK.with(|task| {
+        let running = task.borrow();
+        running.task.interrupted.load(Ordering::SeqCst)
+            || running.deadline.is_some_and(|at| Instant::now() >= at)
+    })
+}
+
+/// The most a wait sleeps before it looks again whether its run is to stop.
+const MAX_SLEEP: Duration = Duration::from_millis(10);
+
+/// How long a wait sleeps before it looks again whether its run is to stop:
+/// never past its deadline.
+pub(crate) fn sleep_slice() -> Duration {
+    TASK.with(|task| match task.borrow().deadline {
+        Some(at) => at.saturating_duration_since(Instant::now()).min(MAX_SLEEP),
+        None => MAX_SLEEP,
+    })
+}
+
+/// A process has one Blocking, so a test counts only the waits of the thread
+/// that asked to.
+#[cfg(test)]
+pub(crate) mod testing {
+    use std::cell::RefCell;
+    use std::sync::atomic::{AtomicUsize, Ordering};
+    use std::sync::Arc;
+    use std::time::{Duration, Instant};
+
+    /// The longest a test waits for another thread, so what never arrives fails
+    /// the test instead of hanging the suite.
+    pub(crate) const MAX_WAIT: Duration = Duration::from_secs(10);
+
+    /// Wait until `arrived`, failing the test with `what` past `MAX_WAIT`.
+    pub(crate) fn wait_until(what: &str, mut arrived: impl FnMut() -> bool) {
+        let started = Instant::now();
+        while !arrived() {
+            assert!(
+                started.elapsed() < MAX_WAIT,
+                "{what} did not happen within {MAX_WAIT:?}"
+            );
+            std::thread::yield_now();
+        }
+    }
+
+    /// What the thread `handle` runs answers, failing the test with `what` past
+    /// `MAX_WAIT`, so a thread stuck on a lock fails rather than hangs.
+    pub(crate) fn join<T>(what: &str, handle: std::thread::JoinHandle<T>) -> T {
+        wait_until(what, || handle.is_finished());
+        handle
+            .join()
+            .unwrap_or_else(|_| panic!("{what} must not panic"))
+    }
+
+    /// What the scoped thread `handle` runs answers, as `join` waits for one.
+    pub(crate) fn join_scoped<T>(what: &str, handle: std::thread::ScopedJoinHandle<'_, T>) -> T {
+        wait_until(what, || handle.is_finished());
+        handle
+            .join()
+            .unwrap_or_else(|_| panic!("{what} must not panic"))
+    }
+
+    /// What `run` answers, each wait for a lock in it ending past `MAX_WAIT`, so a
+    /// test thread waiting on a lock itself fails rather than hangs.
+    pub(crate) fn within_max_wait<T>(run: impl FnOnce() -> T) -> T {
+        super::run_task(Some(Instant::now() + MAX_WAIT), run)
+    }
+
+    use super::{Blocking, BLOCKING};
+
+    thread_local! {
+        static COUNTS: RefCell<Option<Arc<AtomicUsize>>> = const { RefCell::new(None) };
+    }
+
+    struct CountsWaits;
+
+    impl Blocking for CountsWaits {
+        fn wait(&self, wait: &mut dyn FnMut()) {
+            COUNTS.with(|counts| {
+                if let Some(counts) = counts.borrow().as_ref() {
+                    counts.fetch_add(1, Ordering::SeqCst);
+                }
+            });
+            wait();
+        }
+    }
+
+    /// Counts each wait this thread makes through the registered Blocking.
+    pub(crate) fn count_waits() -> Arc<AtomicUsize> {
+        BLOCKING.get_or_init(|| Box::new(CountsWaits));
+        let counts = Arc::<AtomicUsize>::default();
+        COUNTS.with(|held| *held.borrow_mut() = Some(counts.clone()));
+        counts
+    }
+}