security_box 0.3.0 → 0.6.0

data/lib/security_box/configuration.rb

@@ -13,35 +13,74 @@ module SecurityBox
     DEFAULTS = {
       image_path: nil, # resolved dynamically (project's build/security_box.wasm)
       fuel: 10_000_000_000,
+      fuel_ms: nil, # rate-based fuel ergonomics (see FUEL_PER_MS); nil = use :fuel
       timeout_ms: 2_000,
       memory_size: 512 * 1024 * 1024,
       stdout_limit: 1 << 20,
       stderr_limit: 1 << 16,
       epoch_interval_ms: 25,
-      env: {}.freeze
+      env: {}.freeze,
+      mounts: [].freeze,
+      rpcs: {}.freeze
     }.freeze
 
-    attr_reader :image_path, :fuel, :timeout_ms, :memory_size,
-                :stdout_limit, :stderr_limit, :epoch_interval_ms, :env
+    # Fuel-per-ms conversion for #fuel_ms, from the stage-3 calibration table
+    # (docs/plan/stages/stage_3.md): compute workloads burn 3.2e9–8.4e9 fuel/s;
+    # 4e9/s is the conservative floor. The guest boot baseline (~9.1e8 fuel)
+    # is added on top so the budget covers boot even for trivial evals.
+    FUEL_PER_MS = 4_000_000
+    BOOT_FUEL_ALLOWANCE = 1_000_000_000
+
+    attr_reader :image_path, :fuel, :fuel_ms, :timeout_ms, :memory_size,
+                :stdout_limit, :stderr_limit, :epoch_interval_ms, :env, :mounts,
+                :rpcs
 
     def self.build(**options)
       new(**DEFAULTS.merge(options)).freeze
     end
 
-    def initialize(image_path: nil, fuel:, timeout_ms:, memory_size:,
-                   stdout_limit:, stderr_limit:, epoch_interval_ms:, env:)
+    def initialize(image_path: nil, fuel:, fuel_ms:, timeout_ms:, memory_size:,
+                   stdout_limit:, stderr_limit:, epoch_interval_ms:, env:, mounts:,
+                   rpcs:)
       @image_path = image_path || default_image_path
       @fuel = Integer(fuel)
+      @fuel_ms = fuel_ms.nil? ? nil : Integer(fuel_ms)
       @timeout_ms = Integer(timeout_ms)
       @memory_size = Integer(memory_size)
       @stdout_limit = Integer(stdout_limit)
       @stderr_limit = Integer(stderr_limit)
       @epoch_interval_ms = Integer(epoch_interval_ms)
       @env = env.freeze
+      @mounts = Mounts.normalize(mounts)
+      @rpcs = Rpcs.normalize(rpcs)
       freeze
     end
 
+    # The fuel budget actually applied to each evaluation. When :fuel_ms is
+    # set it takes precedence: an approximate millisecond-based budget
+    # (fuel_ms × FUEL_PER_MS + boot allowance) instead of a raw fuel count.
+    # The epoch timeout remains the mandatory wall-clock backstop either way.
+    def effective_fuel
+      return fuel unless fuel_ms
+
+      fuel_ms * FUEL_PER_MS + BOOT_FUEL_ALLOWANCE
+    end
+
+    # Derives a copy with `changes` applied (never mutates the receiver).
+    # Passing both :fuel and a non-nil :fuel_ms is ambiguous and rejected;
+    # overriding :fuel on a configuration that uses :fuel_ms is rejected too
+    # (pass fuel_ms: nil first to switch to a raw fuel budget).
     def with(**changes)
+      if changes.key?(:fuel_ms)
+        if changes[:fuel_ms] && changes.key?(:fuel)
+          raise InvalidConfiguration,
+                "fuel and fuel_ms are mutually exclusive overrides"
+        end
+      elsif changes.key?(:fuel) && @fuel_ms
+        raise InvalidConfiguration,
+              "configuration uses fuel_ms (#{fuel_ms}); override fuel_ms or clear it with fuel_ms: nil instead of fuel"
+      end
+
       self.class.build(**to_h.merge(changes))
     end
 
@@ -49,12 +88,15 @@ module SecurityBox
       {
         image_path: @image_path,
         fuel: @fuel,
+        fuel_ms: @fuel_ms,
         timeout_ms: @timeout_ms,
         memory_size: @memory_size,
         stdout_limit: @stdout_limit,
         stderr_limit: @stderr_limit,
         epoch_interval_ms: @epoch_interval_ms,
-        env: @env
+        env: @env,
+        mounts: @mounts,
+        rpcs: @rpcs
       }
     end
 
@@ -62,12 +104,16 @@ module SecurityBox
     # hash). Two configurations with equal settings — regardless of how they
     # were built — share the same fingerprint; any #with change produces a
     # different one. Used to key profiles and, later, cached artifacts.
+    #
+    # RPC handlers are deliberately excluded: they are host-side callables
+    # (Procs) with no stable serialized identity, and including them would
+    # make the fingerprint depend on object addresses.
     def fingerprint
       Digest::SHA256.hexdigest(JSON.generate(canonical))
     end
 
     def canonical
-      to_h.merge(env: @env.sort.to_h)
+      to_h.except(:rpcs).merge(env: @env.sort.to_h)
     end
 
     # Mutable collector for the register DSL. Setter names match the
@@ -87,9 +133,20 @@ module SecurityBox
       end
 
       def fuel(value)
+        raise InvalidConfiguration, "fuel and fuel_ms are mutually exclusive" if @changes.key?(:fuel_ms)
+
         @changes[:fuel] = value
       end
 
+      # Rate-based fuel ergonomics: sets fuel from an approximate millisecond
+      # budget (see Configuration#effective_fuel). Mutually exclusive with
+      # an explicit :fuel.
+      def fuel_ms(value)
+        raise InvalidConfiguration, "fuel and fuel_ms are mutually exclusive" if @changes.key?(:fuel)
+
+        @changes[:fuel_ms] = value
+      end
+
       def timeout_ms(value)
         @changes[:timeout_ms] = value
       end
@@ -114,6 +171,52 @@ module SecurityBox
       def env(value)
         @changes[:env] = value
       end
+
+      # Mounts a host directory into the guest, read-only by default:
+      #   c.mount "host/path" => "/data"
+      # Each call appends one mount; use #mount_rw for a writable mount.
+      def mount(mapping)
+        add_mount(mapping, :read_only)
+      end
+
+      # Opt-in writable mount — the only way to expose a writable host path
+      # besides the sandbox-private /work tmpdir:
+      #   c.mount_rw "host/path" => "/data"
+      def mount_rw(mapping)
+        add_mount(mapping, :read_write)
+      end
+
+      # Registers a guest-callable RPC handler (stage 6):
+      #   c.rpc "github.search" => ->(args) { ... }
+      #   c.rpc github_search: ->(args) { ... }
+      # Each call appends one handler; the per-call :rpcs override replaces
+      # the whole set. See SecurityBox::Rpcs for the validation rules.
+      def rpc(mapping = nil, **kwargs)
+        unless kwargs.empty?
+          raise InvalidConfiguration, 'rpc expects exactly one pair: c.rpc "name" => handler' unless kwargs.size == 1 && mapping.nil?
+
+          name, handler = kwargs.first
+          mapping = { name.to_s => handler }
+        end
+        unless mapping.is_a?(Hash) && mapping.size == 1
+          raise InvalidConfiguration,
+                'rpc expects exactly one pair: c.rpc "name" => handler'
+        end
+
+        @changes[:rpcs] = Array(@changes[:rpcs]) + [mapping]
+      end
+
+      private
+
+      def add_mount(mapping, mode)
+        unless mapping.is_a?(Hash) && mapping.size == 1
+          raise InvalidConfiguration,
+                'mount expects exactly one pair: c.mount "host/path" => "/data"'
+        end
+
+        host, guest = mapping.first
+        @changes[:mounts] = Array(@changes[:mounts]) + [{ host: host, guest: guest, mode: mode }]
+      end
     end
 
     private
@@ -135,4 +238,180 @@ module SecurityBox
             "or pass image_path in the configuration."
     end
   end
+
+  # Validated collection of host-folder mounts (stage 5). A mount is a frozen
+  # {host:, guest:, mode:} hash; `mounts` in a Configuration is a frozen array
+  # of these, so the value survives #with, #fingerprint and Ractor ports.
+  #
+  # Validation (InvalidConfiguration on any violation):
+  #   - mode is :read_only or :read_write (wasmtime silently accepts unknown
+  #     symbols, so the mode is checked here, never trusted to the runtime)
+  #   - host: non-empty string; relative paths are expanded against Dir.pwd
+  #     (existence/directory checks are per-eval, in EvalRun — dirs can vanish)
+  #   - guest: absolute, normalized path (no "..", no trailing slash), not "/"
+  #   - guest paths must not overlap /work, /usr or /src (exact or nested):
+  #     a collision with the embedded VFS is silently shadowed (stage-5 spike:
+  #     the mount content is invisible), a mount inside /usr even breaks the
+  #     guest boot, and inside /work it would create a read-only subtree
+  #   - duplicate guest paths are rejected (wasmtime's last-mount-wins is
+  #     silently surprising)
+  #   - at most MAX_MOUNTS mounts
+  module Mounts
+    MODES = %i[read_only read_write].freeze
+    RESERVED_GUEST_PATHS = %w[/work /usr /src].freeze
+    MAX_MOUNTS = 16
+
+    class << self
+      # Validates + normalizes `raw` (an array of {host:, guest:, mode:} hashes
+      # or nil) and returns a frozen array of frozen, normalized hashes.
+      def normalize(raw)
+        return [].freeze if raw.nil?
+
+        raise InvalidConfiguration,
+              "mounts must be an Array of {host:, guest:, mode:} hashes, got #{raw.class}" unless raw.is_a?(Array)
+
+        mounts = raw.map { |entry| normalize_entry(entry) }
+        check_duplicates(mounts)
+        check_reserved(mounts)
+        check_count(mounts)
+        mounts.freeze
+      end
+
+      private
+
+      def normalize_entry(entry)
+        unless entry.is_a?(Hash) && entry.keys.sort == %i[guest host mode]
+          raise InvalidConfiguration,
+                "each mount must be a Hash with exactly :host, :guest and :mode keys, got #{entry.inspect}"
+        end
+
+        mode = entry[:mode]
+        unless MODES.include?(mode)
+          raise InvalidConfiguration,
+                "mount mode must be one of #{MODES.map(&:inspect).join(' or ')}, got #{mode.inspect}"
+        end
+
+        { host: normalize_host(entry[:host]),
+          guest: normalize_guest(entry[:guest]),
+          mode: mode }.freeze
+      end
+
+      def normalize_host(host)
+        unless host.is_a?(String) && !host.empty?
+          raise InvalidConfiguration, "mount host path must be a non-empty String, got #{host.inspect}"
+        end
+
+        File.expand_path(host).freeze
+      end
+
+      def normalize_guest(guest)
+        unless guest.is_a?(String) && !guest.empty?
+          raise InvalidConfiguration, "mount guest path must be a non-empty String, got #{guest.inspect}"
+        end
+        unless guest.start_with?("/")
+          raise InvalidConfiguration, "mount guest path must be absolute, got #{guest.inspect}"
+        end
+
+        guest = guest.chomp("/")
+        if guest.empty? || File.expand_path(guest, "/") != guest
+          raise InvalidConfiguration,
+                "mount guest path must be a normalized absolute path (no '..', '.' or trailing '/'), got #{guest.inspect}"
+        end
+        raise InvalidConfiguration, "mount guest path contains a NUL byte" if guest.include?("\0")
+
+        guest.freeze
+      end
+
+      def check_duplicates(mounts)
+        guests = mounts.map { |mount| mount[:guest] }
+        duplicate = guests.find { |guest| guests.count(guest) > 1 }
+        return unless duplicate
+
+        raise InvalidConfiguration, "duplicate guest mount path #{duplicate.inspect}"
+      end
+
+      def check_reserved(mounts)
+        mounts.each do |mount|
+          guest = mount[:guest]
+          conflict = RESERVED_GUEST_PATHS.find do |reserved|
+            guest == reserved || guest.start_with?("#{reserved}/") || reserved.start_with?("#{guest}/")
+          end
+          next unless conflict
+
+          raise InvalidConfiguration,
+                "mount guest path #{guest.inspect} overlaps the reserved path #{conflict.inspect}"
+        end
+      end
+
+      def check_count(mounts)
+        return if mounts.size <= MAX_MOUNTS
+
+        raise InvalidConfiguration,
+              "too many mounts (#{mounts.size}); the limit is #{MAX_MOUNTS}"
+      end
+    end
+  end
+
+  # Validated collection of guest-callable RPC handlers (stage 6). A
+  # handler is a name => callable pair; `rpcs` in a Configuration is a
+  # frozen hash, so the value survives #with and #to_h.
+  #
+  # Handlers execute on the host (between guest steps, inside the RPC
+  # import) and are therefore host-only state: they are excluded from
+  # #fingerprint, and a Configuration carrying Procs is not
+  # Ractor-shareable — RactorPool rejects rpcs and strips them before a
+  # config crosses a Ractor boundary.
+  #
+  # Validation (InvalidConfiguration on any violation):
+  #   - raw is a Hash of name => handler, or an Array of one-pair hashes
+  #     (the register DSL appends one pair per c.rpc call)
+  #   - name: non-empty String, unique
+  #   - handler: anything responding to #call; it receives the
+  #     JSON-parsed request args and must return a JSON-serializable
+  #     value (non-serializable results surface as inspect strings)
+  #   - at most MAX_RPCS handlers
+  module Rpcs
+    MAX_RPCS = 64
+
+    class << self
+      # Validates + normalizes `raw` and returns a frozen
+      # name => handler hash.
+      def normalize(raw)
+        return {}.freeze if raw.nil?
+
+        pairs = case raw
+                when Hash then raw.entries
+                when Array
+                  unless raw.all? { |entry| entry.is_a?(Hash) && entry.size == 1 }
+                    raise InvalidConfiguration,
+                          "rpcs must be a Hash or an Array of one-pair hashes, " \
+                          "got #{raw.inspect[0, 80]}"
+                  end
+                  raw.flat_map(&:entries)
+                else
+                  raise InvalidConfiguration,
+                        "rpcs must be a Hash of name => handler, got #{raw.class}"
+                end
+
+        rpcs = {}
+        pairs.each do |name, handler|
+          unless name.is_a?(String) && !name.empty?
+            raise InvalidConfiguration, "rpc name must be a non-empty String, got #{name.inspect}"
+          end
+          unless handler.respond_to?(:call)
+            raise InvalidConfiguration,
+                  "rpc handler for #{name.inspect} must respond to #call, " \
+                  "got #{handler.inspect[0, 80]}"
+          end
+          raise InvalidConfiguration, "duplicate rpc name #{name.inspect}" if rpcs.key?(name)
+
+          rpcs[name] = handler
+        end
+        return rpcs.freeze if rpcs.size <= MAX_RPCS
+
+        raise InvalidConfiguration,
+              "too many rpcs (#{rpcs.size}); the limit is #{MAX_RPCS}"
+      end
+    end
+  end
 end

data/lib/security_box/errors.rb

@@ -6,4 +6,6 @@ module SecurityBox
   class ImageMissing < Error; end
 
   class InvalidConfiguration < Error; end
+
+  class PoolClosed < Error; end
 end

data/lib/security_box/eval_run.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "tmpdir"
+
+module SecurityBox
+  # One :oneshot evaluation against a pre-built runtime (Engine + Module +
+  # Linker). This is the shared core used by Sandbox (main Ractor, threads)
+  # and by RactorPool workers (one Ractor per worker) — both follow the same
+  # protocol: sandbox-exclusive tmpdir mounted as /work, per-eval token via
+  # ENV, envelope read back from /work/out.json (stdout sentinel fallback),
+  # fuel + epoch deadlines per evaluation, and explicit read-only-by-default
+  # host-folder mounts (stage 5) validated per eval.
+  #
+  # Everything here is self-contained per call: no shared mutable state, safe
+  # to run concurrently from multiple Ractors/threads as long as each caller
+  # owns its Engine/Module/Linker (Ractors) or shares them thread-safely
+  # (wasmtime Engine/Module/Linker are thread-safe).
+  module EvalRun
+    GUEST_ENTRYPOINT = "/src/main.rb"
+    CODE_FILE = "code.rb"
+    RESULT_FILE = "out.json"
+    TOKEN_ENV_VAR = "SB_TOKEN"
+
+    class << self
+      # Runs `code` once and returns a Result. `config` is a Configuration
+      # (read-only); `token` is the per-eval random token generated by the
+      # caller (SecureRandom is not guaranteed Ractor-safe, so workers
+      # receive it pre-generated).
+      def run(engine:, module_:, linker:, config:, code:, token:)
+        stdout = +""
+        stderr = +""
+        t0 = monotonic_ms
+
+        # Mounts reference host paths that can disappear between building the
+        # configuration and this eval; fail here with a clear note instead of
+        # letting Wasmtime::Store.new raise an opaque error mid-setup.
+        mount_errors = mount_errors(config)
+        unless mount_errors.empty?
+          return Result.new(status: :sandbox_error, stderr: mount_errors.join("\n") << "\n",
+                            duration_ms: monotonic_ms - t0)
+        end
+
+        Dir.mktmpdir("security_box") do |workdir|
+          File.write(File.join(workdir, CODE_FILE), code)
+          # Per-eval RPC state (stage 6): the /work tmpdir plus the
+          # configuration's handlers (nil when none are configured — the
+          # import is still defined, guest calls get a rescuable error).
+          # The calls array doubles as the Result transcript.
+          rpc_data = GuestRpc.store_data(
+            workdir, config.rpcs.empty? ? nil : config.rpcs
+          )
+          envelope = nil
+          status = nil
+          fuel_used = nil
+
+          store = nil
+          begin
+            store = Wasmtime::Store.new(
+              engine,
+              rpc_data,
+              wasi_p1_config: build_wasi(workdir, stdout, stderr, config, token),
+              limits: { memory_size: config.memory_size }
+            )
+            store.set_fuel(config.effective_fuel)
+            instance = linker.instantiate(store, module_)
+            store.set_epoch_deadline(epoch_ticks(config))
+            status = invoke_guest(instance, store)
+            fuel_used = config.effective_fuel - store.get_fuel unless status == :timeout
+            envelope = read_envelope(workdir, stdout, token)
+          rescue Wasmtime::Error => e
+            # Instantiation can fail before the guest ever runs (e.g. a
+            # memory_size below the module's declared minimum pages).
+            status = :sandbox_error
+            stderr << "security_box: #{e.class}: #{e.message}\n"
+          ensure
+            store&.close
+          end
+
+          build_result(status, envelope, stdout, stderr, fuel_used,
+                       monotonic_ms - t0, rpc_data[:rpc]&.fetch(:calls))
+        end
+      end
+
+      private
+
+      def build_wasi(workdir, stdout, stderr, config, token)
+        wasi = Wasmtime::WasiConfig.new
+                .set_stdin_string("")
+                .set_stdout_buffer(stdout, config.stdout_limit)
+                .set_stderr_buffer(stderr, config.stderr_limit)
+                .set_argv(["ruby", GUEST_ENTRYPOINT])
+                .set_env(config.env.merge(TOKEN_ENV_VAR => token))
+                .set_mapped_directory(workdir, "/work", :read_write)
+        # Explicit mounts come after /work; Configuration validation already
+        # guarantees no guest-path overlap with /work, /usr or /src.
+        config.mounts.reduce(wasi) do |wasi_config, mount|
+          wasi_config.set_mapped_directory(mount[:host], mount[:guest], mount[:mode])
+        end
+      end
+
+      # Host-side mount validation for this eval (configuration-level shape
+      # and collision rules are enforced in Configuration::Mounts).
+      def mount_errors(config)
+        config.mounts.reject { |mount| File.directory?(mount[:host]) }.map do |mount|
+          "security_box: mount #{mount[:host].inspect} (guest #{mount[:guest].inspect}): " \
+            "host path does not exist or is not a directory"
+        end
+      end
+
+      def epoch_ticks(config)
+        [config.timeout_ms / config.epoch_interval_ms + 1, 1].max
+      end
+
+      def invoke_guest(instance, store)
+        instance.invoke("_start")
+        :ok
+      rescue Wasmtime::WasiExit => e
+        handle_wasi_exit(e, store)
+      rescue Wasmtime::Trap => e
+        map_trap(e, store)
+      rescue Wasmtime::Error
+        # Unexpected runtime error (non-trap): treated as a sandbox failure.
+        :sandbox_error
+      end
+
+      def handle_wasi_exit(_exit_error, store)
+        # The guest rescues SystemExit; a WasiExit here means exit! or a guest
+        # crash before the envelope was written.
+        store.linear_memory_limit_hit? ? :memory_limit : :sandbox_error
+      end
+
+      def map_trap(trap, store)
+        case trap.code
+        when :interrupt then :timeout
+        when :out_of_fuel then :fuel_exhausted
+        when :memory_out_of_bounds then :memory_limit
+        else
+          store.linear_memory_limit_hit? ? :memory_limit : :sandbox_error
+        end
+      end
+
+      def read_envelope(workdir, stdout, token)
+        # Preferred channel: /work/out.json. Fallback: sentinel line on stdout.
+        # Both go through the same strict validation (schema + token).
+        Envelope.parse(read_result_file(workdir), token) ||
+          Envelope.from_stdout(stdout, token)
+      end
+
+      def read_result_file(workdir)
+        File.read(File.join(workdir, RESULT_FILE))
+      rescue SystemCallError
+        nil
+      end
+
+      def build_result(status, envelope, stdout, stderr, fuel_used, duration_ms, rpc_calls = nil)
+        rpcs = rpc_calls && !rpc_calls.empty? ? rpc_calls.each(&:freeze).freeze : nil
+        if envelope.nil?
+          status = :sandbox_error if status == :ok
+          return Result.new(
+            status: status, stdout: stdout, stderr: stderr,
+            fuel_used: fuel_used, duration_ms: duration_ms, rpcs: rpcs
+          )
+        end
+
+        guest_error = envelope["error"]
+        if envelope["ok"]
+          Result.new(
+            status: status, value: envelope["value"], stdout: stdout, stderr: stderr,
+            fuel_used: fuel_used, duration_ms: duration_ms,
+            guest_duration_ms: envelope["duration_ms"], rpcs: rpcs
+          )
+        elsif guest_memory_error?(guest_error)
+          # The guest hit the store memory limit through the Ruby interpreter
+          # (NoMemoryError instead of a wasm trap) — report it as a limit, not
+          # a user error.
+          Result.new(
+            status: :memory_limit, error: guest_error, stdout: stdout, stderr: stderr,
+            fuel_used: fuel_used, duration_ms: duration_ms,
+            guest_duration_ms: envelope["duration_ms"], rpcs: rpcs
+          )
+        else
+          Result.new(
+            status: :error, error: guest_error, stdout: stdout, stderr: stderr,
+            fuel_used: fuel_used, duration_ms: duration_ms,
+            guest_duration_ms: envelope["duration_ms"], rpcs: rpcs
+          )
+        end
+      end
+
+      def guest_memory_error?(guest_error)
+        guest_error.is_a?(Hash) && guest_error["class"] == "NoMemoryError"
+      end
+
+      def monotonic_ms
+        Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000
+      end
+    end
+  end
+end

data/lib/security_box/guest/main.rb

@@ -16,7 +16,6 @@ require_relative "prelude"
 module SB
   SENTINEL = "__SECURITY_BOX_RESULT__"
   WORK_DIR = "/work"
-
   module_function
 
   def run
@@ -97,4 +96,8 @@ module SB
   end
 end
 
+# Guest RPC bridge (SB.call + SB::ToolError) — reopens the SB module
+# above; must load after it.
+require_relative "rpc"
+
 SB.run

data/lib/security_box/guest/rpc.rb

@@ -0,0 +1,77 @@
+# Guest-side host RPC bridge (loaded by main.rb before user code).
+#
+# User code calls SB.call(name, args) and it behaves like a regular,
+# blocking Ruby function: the request is written to /work/rpc_req.json,
+# the wasm import (SBExt.call — the sb_rpc gem statically linked into
+# the image) is invoked, and the guest blocks while the host executes
+# the registered handler. The response is read back from
+# /work/rpc_resp.json.
+#
+# Handler failures never cross the wasm boundary: the host encodes them
+# as {"ok": false, "error": {"class", "message"}} responses, surfaced
+# here as SB::ToolError (SB::UnknownTool for unregistered names) so user
+# code can rescue them.
+module SB
+  # Raised when an RPC handler fails or its result is unusable.
+  class ToolError < StandardError; end
+
+  # Raised when the code calls a name the host did not register —
+  # including when the sandbox has no handlers configured at all.
+  class UnknownTool < ToolError; end
+
+  # Raised when the transport itself fails (image without the guest
+  # gems, broken /work channel).
+  class RpcUnavailable < StandardError; end
+
+  begin
+    # /bundle/setup.rb is generated by the image build; it adds the gem
+    # lib dirs to $LOAD_PATH. The gems are absent when the image was
+    # built without the guest_ext bundle; SB.call then reports it
+    # cleanly instead of crashing on NameError.
+    require "/bundle/setup.rb"
+    require "sb_rpc"
+  rescue LoadError
+    nil
+  end
+
+  module_function
+
+  # Calls a host-registered handler and returns its result. Behaves as a
+  # blocking function call; the LLM-facing contract is plain Ruby.
+  #
+  #   SB.call("github.search", q: "x")          # kwargs form
+  #   SB.call("github.search", { "q" => "x" })  # positional hash form
+  #
+  # `name` and `args` must be JSON-serializable; handlers receive the
+  # JSON-parsed args (string keys) and return a JSON-serializable value.
+  def call(name, args = nil, **kwargs)
+    unless name.is_a?(String) && !name.empty?
+      raise ArgumentError, "rpc name must be a non-empty String, got #{name.inspect}"
+    end
+    unless defined?(SBExt)
+      raise RpcUnavailable, "rpc support is not available in this image (sb_rpc gem missing)"
+    end
+
+    merged = args.nil? ? {} : args
+    merged = merged.merge(kwargs) unless kwargs.empty?
+    request = begin
+      JSON.generate({ name: name, args: merged })
+    rescue StandardError, TypeError => e
+      raise TypeError, "rpc arguments must be JSON-serializable: #{e.message}"
+    end
+
+    File.write(File.join(WORK_DIR, "rpc_req.json"), request)
+    status = SBExt.call
+    unless status.zero?
+      raise RpcUnavailable, "rpc transport failed (status #{status})"
+    end
+
+    response = JSON.parse(File.read(File.join(WORK_DIR, "rpc_resp.json")))
+    unless response["ok"]
+      error = response["error"] || {}
+      klass = error["class"] == "SB::UnknownTool" ? UnknownTool : ToolError
+      raise klass, error["message"].to_s
+    end
+    response["result"]
+  end
+end

data/lib/security_box/guest_ext/Gemfile

@@ -0,0 +1,10 @@
+source "https://rubygems.org"
+
+# Build tooling — excluded from the image by the packager (EXCLUDED_GEMS),
+# present here so `bundle exec rbwasm` works inside this bundle.
+gem "ruby_wasm", "~> 2.10.1"
+
+# Guest image gems (built into the wasm image by `rbwasm build`; see
+# Rakefile). Only guest-safe dependencies belong here — host-only gems
+# (wasmtime) must stay in the project Gemfile.
+gem "sb_rpc", path: "sb_rpc"