kobako 0.6.2 → 0.8.0

data/README.md

@@ -283,6 +283,29 @@ sandbox.run(:Greeter, name: "world") # => "hello, world"
 
 Use the source form for snippets authored in your repo (compile errors fail fast at `#preload`); use the bytecode form when snippets ship as build artifacts from a separate `mrbc` pipeline. Both replay through the same per-invocation path.
 
+## Security
+
+kobako isolates the guest, but **what it may reach is whatever you `bind`** — and `bind`
+exposes *every* public method of the object. So bind a purpose-built object scoped to the
+task, not a capable one whose other methods leak more than you intend.
+
+```ruby
+class ThemeReader          # only #color is reachable; AppConfig.secret_key is not
+  def color = AppConfig.theme.color
+end
+
+sandbox = Kobako::Sandbox.new
+sandbox.define(:Cfg).bind(:Settings, ThemeReader.new)  # not: bind(:Settings, AppConfig)
+
+sandbox.eval('Cfg::Settings.color')  # => "#3366ff"  — every other method raises NoMethodError
+```
+
+Guest code can name any `<Namespace>::<Member>` path, but a forged name only resolves to
+something you bound — the real authorization gate is this host-side allowlist. Give each
+trust context its own Sandbox, and see [`docs/security.md`](docs/security.md) for the rest
+as security-design concerns: validating untrusted input, default-deny external effects,
+and controlling the return surface.
+
 ## Performance
 
 Order-of-magnitude figures on macOS arm64, Ruby 3.4.7, YJIT off. Absolute values vary by hardware but ratios are stable across machines. Full numbers, methodology, and the +10%-regression gate live in [`benchmark/README.md`](benchmark/README.md).

data/ext/kobako/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "kobako"
-version = "0.6.2"
+version = "0.8.0"
 edition = "2021"
 authors = ["Aotokitsuruya <contact@aotoki.me>"]
 license = "Apache-2.0"
@@ -19,7 +19,7 @@ magnus = { version = "0.8.2" }
 # later via `wasmtime-wasi` once stdin/stdout wiring is needed (item #16).
 # `cache` / `parallel-compilation` / `pooling` / `component-model` / `async`
 # are intentionally off — kobako runs short-lived synchronous sandboxes.
-wasmtime = { version = "44.0.1", default-features = false, features = [
+wasmtime = { version = "45.0.0", default-features = false, features = [
     "cranelift",
     "runtime",
     "gc",
@@ -33,4 +33,4 @@ wasmtime = { version = "44.0.1", default-features = false, features = [
 # WasiCtxBuilder + preview1 adapter which wires fd 1/2 to pipes. We omit
 # `p2` (component-model) and `p0`/`p3` (async) because kobako runs
 # synchronous sandboxes only.
-wasmtime-wasi = { version = "44.0.1", default-features = false, features = ["p1"] }
+wasmtime-wasi = { version = "45.0.0", default-features = false, features = ["p1"] }

data/ext/kobako/src/runtime/trap.rs

@@ -76,8 +76,9 @@ fn classify_trap(err: &wasmtime::Error) -> TrapClass {
 /// `"linear memory growth exceeded memory_limit: ..."`). The wasmtime
 /// outer wrapper at `format!("{}", err)` would otherwise surface only
 /// the `"error while executing at wasm backtrace: ..."` framing, which
-/// is operator noise on a cap trap. For `TrapClass::Other` the
-/// wasmtime wrapper IS the diagnostic (real script trap) so it stays.
+/// is operator noise on a cap trap. For `TrapClass::Other` the framing
+/// is kept but the chain's root cause is appended (see
+/// `other_trap_message`) so the real trap reason survives.
 pub(super) fn call_err(ruby: &Ruby, err: wasmtime::Error) -> MagnusError {
     match classify_trap(&err) {
         TrapClass::Timeout => {
@@ -94,7 +95,24 @@ pub(super) fn call_err(ruby: &Ruby, err: wasmtime::Error) -> MagnusError {
                 .unwrap_or_else(|| format!("{}", err));
             memory_limit_err(ruby, msg)
         }
-        TrapClass::Other => trap_err(ruby, format!("{}", err)),
+        TrapClass::Other => trap_err(ruby, other_trap_message(&err)),
+    }
+}
+
+/// Compose the message for a non-cap trap. wasmtime's `Display` surfaces only
+/// the `"error while executing at wasm backtrace: ..."` framing; the actual
+/// trap reason (e.g. `"wasm trap: indirect call type mismatch"`) is the
+/// chain's root cause and would otherwise be dropped, making real guest
+/// faults undiagnosable. Append the root cause unless the framing already
+/// carries it. Pure so it can be exercised from `cargo test` without the
+/// magnus surface.
+fn other_trap_message(err: &wasmtime::Error) -> String {
+    let display = format!("{}", err);
+    let root = err.root_cause().to_string();
+    if display.contains(&root) {
+        display
+    } else {
+        format!("{display}\n\n{root}")
     }
 }
 
@@ -111,7 +129,7 @@ pub(super) fn instantiate_err(ruby: &Ruby, err: wasmtime::Error) -> MagnusError
 
 #[cfg(test)]
 mod tests {
-    use super::{classify_trap, TrapClass};
+    use super::{classify_trap, other_trap_message, TrapClass};
     use crate::runtime::invocation::{MemoryLimitTrap, TimeoutTrap};
 
     #[test]
@@ -131,4 +149,30 @@ mod tests {
         let err = wasmtime::Error::msg("some other wasmtime fault");
         assert_eq!(classify_trap(&err), TrapClass::Other);
     }
+
+    // A guest hard trap reaches the host as a wasmtime error whose Display is
+    // only the backtrace framing, with the trap reason buried as the chain's
+    // root cause. The named-capture regex bug surfaced as exactly this shape.
+    #[test]
+    fn other_trap_message_surfaces_buried_trap_reason() {
+        let err = wasmtime::Error::msg("wasm trap: indirect call type mismatch")
+            .context("error while executing at wasm backtrace:\n  0: 0x1 - <unknown>");
+        let msg = other_trap_message(&err);
+        assert!(
+            msg.contains("indirect call type mismatch"),
+            "a non-cap trap surfaced through Kobako::TrapError must carry the root trap reason, not only the backtrace framing; got: {msg}"
+        );
+        assert!(
+            msg.contains("error while executing"),
+            "a non-cap trap surfaced through Kobako::TrapError must keep the wasm backtrace framing; got: {msg}"
+        );
+    }
+
+    // A flat error (no cause chain) is its own root_cause; appending it would
+    // duplicate the whole message.
+    #[test]
+    fn other_trap_message_does_not_duplicate_a_flat_error() {
+        let err = wasmtime::Error::msg("plain fault");
+        assert_eq!(other_trap_message(&err), "plain fault");
+    }
 }

data/ext/kobako/src/runtime.rs

@@ -65,6 +65,12 @@ use self::config::Config;
 use self::exports::Exports;
 use self::invocation::{Invocation, StoreCell};
 
+/// The wire ABI version this host implements (docs/wire-codec.md § ABI
+/// Version). A Guest Binary is accepted only when its
+/// `__kobako_abi_version` export reports the same value (B-40 / E-42);
+/// the guest-side mirror is `kobako_core::abi::ABI_VERSION`.
+const ABI_VERSION: u32 = 1;
+
 /// Copy the bytes of +s+ into a fresh `Vec<u8>`. Single safe entry to
 /// what would otherwise be an inline +unsafe { rstring.as_slice() }
 /// .to_vec()+ duplicated at every host-↔-guest boundary. The borrow
@@ -349,6 +355,8 @@ impl Runtime {
                 .map_err(|e| trap::instantiate_err(&ruby, e))?
         };
 
+        Self::validate_abi_version(&instance, &store_cell, &ruby)?;
+
         let exports = Exports::resolve(&instance, &store_cell);
 
         Ok(Self {
@@ -364,6 +372,48 @@ impl Runtime {
         })
     }
 
+    /// Probe the guest's `__kobako_abi_version` export once at
+    /// construction and require equality with `ABI_VERSION`
+    /// (docs/behavior.md B-40). An absent export or a non-equal value is
+    /// E-42 — a deterministic artifact fault raised as
+    /// `Kobako::SetupError`.
+    fn validate_abi_version(
+        instance: &WtInstance,
+        store: &StoreCell,
+        ruby: &Ruby,
+    ) -> Result<(), MagnusError> {
+        let mut store_ref = store.borrow_mut();
+        let mut ctx = store_ref.as_context_mut();
+        let probe = instance
+            .get_typed_func::<(), u32>(&mut ctx, "__kobako_abi_version")
+            .map_err(|_| {
+                setup_err(
+                    ruby,
+                    format!(
+                        "the Guest Binary does not export __kobako_abi_version; \
+                         rebuild it against ABI version {ABI_VERSION}"
+                    ),
+                )
+            })?;
+        let reported = probe.call(&mut ctx, ()).map_err(|e| {
+            setup_err(
+                ruby,
+                format!("failed to read the Guest Binary's ABI version: {e}"),
+            )
+        })?;
+        if reported != ABI_VERSION {
+            return Err(setup_err(
+                ruby,
+                format!(
+                    "the Guest Binary reports ABI version {reported}, but this host \
+                     implements ABI version {ABI_VERSION}; rebuild the Guest Binary \
+                     against the host's version"
+                ),
+            ));
+        }
+        Ok(())
+    }
+
     /// Register the Ruby-side dispatch +Proc+ on the active Invocation.
     /// Bound to Ruby as +Kobako::Runtime#on_dispatch=+. From this point on,
     /// every +__kobako_dispatch+ host import invocation calls the Proc

data/lib/kobako/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kobako
-  VERSION = "0.6.2"
+  VERSION = "0.8.0"
 end

data/release-please-config.json

@@ -7,6 +7,17 @@
       "component": "kobako",
       "include-component-in-tag": false,
       "release-type": "ruby"
+    },
+    "wasm/kobako-core": {
+      "component": "kobako-core",
+      "release-type": "rust",
+      "extra-files": [
+        {
+          "type": "toml",
+          "path": "/wasm/Cargo.lock",
+          "jsonpath": "$.package[?(@.name=='kobako-core')].version"
+        }
+      ]
     }
   },
   "extra-files": [

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kobako
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.8.0
 platform: ruby
 authors:
 - Aotokitsuruya