security_box 0.2.0 → 0.5.0

data/lib/security_box/envelope.rb

@@ -55,11 +55,20 @@ module SecurityBox
           return false unless error.is_a?(Hash)
           return false unless error["class"].is_a?(String)
           return false unless error["message"].is_a?(String)
+          return false unless valid_backtrace?(error["backtrace"])
         end
 
         duration = envelope["duration_ms"]
         duration.nil? || duration.is_a?(Numeric)
       end
+
+      # Optional: an array of backtrace frame strings (guest-side errors).
+      def valid_backtrace?(backtrace)
+        return true if backtrace.nil?
+        return false unless backtrace.is_a?(Array)
+
+        backtrace.all?(String)
+      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,191 @@
+# 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)
+          envelope = nil
+          status = nil
+          fuel_used = nil
+
+          store = nil
+          begin
+            store = Wasmtime::Store.new(
+              engine,
+              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)
+        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)
+        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
+          )
+        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"]
+          )
+        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"]
+          )
+        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"]
+          )
+        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

@@ -43,7 +43,26 @@ module SB
   def evaluate(code)
     { ok: true, value: jsonable(eval(code, TOPLEVEL_BINDING, "sandbox")) } # rubocop:disable Security/Eval,Style/EvalWithLocation
   rescue Exception => e # rubocop:disable Lint/RescueException
-    { ok: false, value: nil, error: { "class" => e.class.name, "message" => e.message.to_s } }
+    {
+      ok: false, value: nil,
+      error: {
+        "class" => e.class.name,
+        "message" => e.message.to_s,
+        "backtrace" => guest_backtrace(e)
+      }
+    }
+  end
+
+  # Frames of the user code only: guest protocol internals (main.rb /
+  # prelude.rb) are stripped and the list is capped so a deep recursion
+  # cannot flood the result channel.
+  def guest_backtrace(exception)
+    frames = (exception.backtrace || []).reject do |frame|
+      frame.include?("main.rb") || frame.include?("prelude.rb")
+    end
+    frames.first(20)
+  rescue StandardError
+    []
   end
 
   # Values must survive JSON; the round-trip normalizes what the host will read.
@@ -55,11 +74,22 @@ module SB
 
   # Preferred: /work/out.json. Fallback (no /work): sentinel on stdout.
   # Both carry the sandbox token so the host can reject forged results.
+  # The write is verified by reading it back — a silent truncation or
+  # partial write falls through to the sentinel instead of losing the
+  # result.
   def emit(out, token)
     json = JSON.generate(out.merge(token: token))
-    File.write(File.join(WORK_DIR, "out.json"), json)
+    unless write_verified(json)
+      $stdout.puts "#{SENTINEL}:#{token}:#{json}"
+    end
+  end
+
+  def write_verified(json)
+    path = File.join(WORK_DIR, "out.json")
+    File.write(path, json)
+    File.read(path) == json
   rescue StandardError, SystemCallError
-    $stdout.puts "#{SENTINEL}:#{token}:#{json}"
+    false
   end
 
   def fatal(message, token)

data/lib/security_box/pool.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module SecurityBox
+  # Bounded pool of :oneshot Sandboxes.
+  #
+  # What it gives you:
+  # - a hard cap on concurrent sandbox evaluations (`size`);
+  # - cheap checkout/checkin of pre-built Sandbox objects;
+  # - basic metrics (evals, total/average wall time).
+  #
+  # What it does NOT give you (measured in stage 4, docs/plan/stages/stage_4.md):
+  # parallelism. `invoke` holds the GVL for the whole guest lifetime, so
+  # concurrent evals on threads serialize. For real parallelism use
+  # RactorPool, which runs workers on Ractors with a shared Engine+Module.
+  #
+  # Usage:
+  #   pool = SecurityBox::Pool.new(:lean, size: 4)
+  #   pool.eval("1 + 1")                # => Result (checks out a sandbox)
+  #   pool.checkout { |sandbox| ... }   # manual checkout block
+  #   pool.shutdown
+  class Pool
+    attr_reader :size
+
+    def initialize(profile = nil, size: 4, **options)
+      @size = Integer(size)
+      raise ArgumentError, "size must be >= 1" if @size < 1
+
+      @config = resolve_config(profile, options)
+      @sandboxes = Queue.new
+      @mutex = Mutex.new
+      @created = 0
+      @closed = false
+      @metrics = { evals: 0, total_ms: 0.0 }
+    end
+
+    # Checks a sandbox out of the pool for the duration of the block.
+    # Blocks while all `size` sandboxes are busy.
+    def checkout
+      raise PoolClosed, "pool is closed" if closed?
+
+      sandbox = acquire
+      begin
+        yield sandbox
+      ensure
+        release(sandbox)
+      end
+    end
+
+    # Checks a sandbox out and runs `code` on it. Per-call overrides are
+    # forwarded to Sandbox#eval.
+    def eval(code, **overrides)
+      t0 = monotonic_ms
+      result = checkout { |sandbox| sandbox.eval(code, **overrides) }
+      record(monotonic_ms - t0)
+      result
+    end
+
+    # Snapshot of the counters:
+    # {size:, created:, evals:, total_ms:, avg_ms:}.
+    def metrics
+      @mutex.synchronize do
+        evals = @metrics[:evals]
+        { size: @size, created: @created, evals: evals,
+          total_ms: @metrics[:total_ms].round(2),
+          avg_ms: evals.zero? ? 0.0 : (@metrics[:total_ms] / evals).round(2) }
+      end
+    end
+
+    def closed?
+      @mutex.synchronize { @closed }
+    end
+
+    # Closes the pool. Sandboxes currently checked out keep working until
+    # released; threads blocked on an empty pool keep waiting (callers must
+    # ensure they do not shut down while checkouts are still being awaited).
+    def shutdown
+      @mutex.synchronize { @closed = true }
+    end
+
+    private
+
+    def resolve_config(profile, options)
+      case profile
+      when nil then Configuration.build(**options)
+      when Symbol, String then Registry.resolve(profile).with(**options)
+      when Configuration then profile.with(**options)
+      else raise ArgumentError, "profile must be a registered name or a Configuration, got #{profile.class}"
+      end
+    end
+
+    # Hands out an existing sandbox, creates a new one while under `size`, or
+    # blocks until another caller releases one. Sandbox creation happens
+    # outside the mutex (it may raise, e.g. ImageMissing).
+    def acquire
+      create = false
+      @mutex.synchronize do
+        raise PoolClosed, "pool is closed" if @closed
+
+        if @created < @size
+          @created += 1
+          create = true
+        end
+      end
+
+      if create
+        begin
+          return Sandbox.new(@config)
+        rescue StandardError
+          @mutex.synchronize { @created -= 1 }
+          raise
+        end
+      end
+
+      # All created sandboxes are busy: block until one is released. (The
+      # closed check here mirrors checkout's — a shutdown racing an acquire
+      # is still resolved by the release that eventually unblocks this pop.)
+      sandbox = @sandboxes.pop
+      raise PoolClosed, "pool is closed" if closed?
+
+      sandbox
+    end
+
+    def release(sandbox)
+      @sandboxes << sandbox
+    end
+
+    def record(duration_ms)
+      @mutex.synchronize do
+        @metrics[:evals] += 1
+        @metrics[:total_ms] += duration_ms
+      end
+    end
+
+    def monotonic_ms
+      Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000
+    end
+  end
+end

data/lib/security_box/ractor_pool.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module SecurityBox
+  # Pool of Ractor workers sharing one Engine + compiled Module (stage-3 Q2
+  # "Plan C"): the pool builds a dedicated runtime pair, makes it
+  # Ractor-shareable, and N worker Ractors each keep a private Linker. Per
+  # eval a worker creates Store + Instance (~0.2ms), applies the request's
+  # fuel/epoch/memory limits (safe: the worker owns its store), and invokes.
+  #
+  # This is the only supported way to run evaluations in parallel: `invoke`
+  # holds the GVL for the whole guest lifetime (stage-4 Q1), so threads
+  # serialize (see Pool).
+  #
+  # Protocol (Ruby 3.4+/4.0 Ractor port model):
+  # - eval builds a request {id, code, token, config} and sends it to the
+  #   worker with the fewest in-flight requests (worker << request);
+  # - workers run the shared EvalRun core and push
+  #   {id, worker, result} back to the main Ractor (Ractor.main << ...);
+  # - a main-side collector thread receives from the main Ractor port and
+  #   routes each result to the Queue of the thread waiting for it (results
+  #   are matched by request id; this thread must be the only main-port
+  #   receiver in the process);
+  # - every request terminates (epoch + fuel), and a pop deadline converts a
+  #   dead worker into a :sandbox_error result instead of a hang.
+  #
+  # Trade-offs (measured, stage-3 Q2 / stage-4): one module deserialize per
+  # pool (~0.5s via the disk cache); each worker's eval still pays the
+  # ~240ms guest boot. Ratios at 2/4 Ractors on 6 cores: 0.56 / 0.28 wall vs
+  # serial, RSS ~111MB with the shared runtime.
+  #
+  # Usage:
+  #   pool = SecurityBox::RactorPool.new(:lean, size: 4)
+  #   pool.eval("1 + 1")     # => Result
+  #   pool.shutdown
+  class RactorPool
+    STOP = :security_box_stop
+    POP_SLACK_MS = 10_000
+
+    attr_reader :size
+
+    def initialize(profile = nil, size: 4, **options)
+      @size = Integer(size)
+      raise ArgumentError, "size must be >= 1" if @size < 1
+
+      @config = resolve_config(profile, options)
+      @mutex = Mutex.new
+      @pending = {} # request id => Queue
+      @in_flight = Array.new(@size, 0)
+      @closed = false
+      @next_id = 0
+      @metrics = { evals: 0, total_ms: 0.0, timeouts: 0 }
+
+      engine, module_ = Runtime.build_shareable(
+        image_path: @config.image_path,
+        epoch_interval_ms: @config.epoch_interval_ms
+      )
+      @workers = Array.new(@size) do |index|
+        build_worker(engine, module_, index)
+      end
+      start_collector_thread
+    end
+
+    # Runs `code` on one of the workers and blocks until its Result arrives.
+    # Per-call overrides follow Sandbox#eval (same Configuration#with rules).
+    def eval(code, **overrides)
+      raise PoolClosed, "pool is closed" if closed?
+
+      config = overrides.empty? ? @config : @config.with(**overrides)
+      request = {
+        id: next_id,
+        code: code,
+        token: SecureRandom.hex(16),
+        config: config
+      }
+      queue = Queue.new
+      worker_index = @mutex.synchronize do
+        @pending[request[:id]] = queue
+        index = @in_flight.each_with_index.min_by { |count, _| count }.last
+        @in_flight[index] += 1
+        index
+      end
+
+      begin
+        @workers[worker_index] << request
+        deadline_ms = config.timeout_ms + POP_SLACK_MS
+        result = queue.pop(timeout: deadline_ms / 1000.0)
+        raise ThreadError, "no result" if result.nil? # Queue#pop timeout
+        record(result)
+        result
+      rescue ThreadError, Ractor::ClosedError
+        # Worker died, stalled beyond the deadline, or was shut down mid-flight:
+        # report instead of hang or leak the error.
+        @mutex.synchronize { @metrics[:timeouts] += 1 }
+        Result.worker_unavailable(worker_index)
+      ensure
+        @mutex.synchronize do
+          @in_flight[worker_index] -= 1 if @in_flight[worker_index] > 0
+          @pending.delete(request[:id])
+        end
+      end
+    end
+
+    # Snapshot of the counters: {size:, evals:, total_ms:, avg_ms:, timeouts:}.
+    def metrics
+      @mutex.synchronize do
+        evals = @metrics[:evals]
+        { size: @size, evals: evals, total_ms: @metrics[:total_ms].round(2),
+          avg_ms: evals.zero? ? 0.0 : (@metrics[:total_ms] / evals).round(2),
+          timeouts: @metrics[:timeouts] }
+      end
+    end
+
+    def closed?
+      @mutex.synchronize { @closed }
+    end
+
+    # Asks all workers to stop. Evals already in flight finish; new evals
+    # raise PoolClosed.
+    def shutdown
+      @mutex.synchronize { @closed = true }
+      @workers.each { |worker| worker << STOP }
+    end
+
+    private
+
+    def resolve_config(profile, options)
+      case profile
+      when nil then Configuration.build(**options)
+      when Symbol, String then Registry.resolve(profile).with(**options)
+      when Configuration then profile.with(**options)
+      else raise ArgumentError, "profile must be a registered name or a Configuration, got #{profile.class}"
+      end
+    end
+
+    def build_worker(engine, module_, worker_index)
+      Ractor.new(engine, module_, worker_index, name: "security_box-worker-#{worker_index}") do |eng, mod, index|
+        linker = Wasmtime::Linker.new(eng).tap { |l| Wasmtime::WASI::P1.add_to_linker_sync(l) }
+        loop do
+          request = Ractor.receive
+          break if request == :security_box_stop
+
+          begin
+            result = SecurityBox::EvalRun.run(
+              engine: eng, module_: mod, linker: linker,
+              config: request[:config], code: request[:code], token: request[:token]
+            )
+          rescue StandardError => e
+            result = SecurityBox::Result.new(
+              status: :sandbox_error,
+              stderr: "security_box: worker #{index} crashed: #{e.class}: #{e.message}\n"
+            )
+          end
+          Ractor.main << { id: request[:id], worker: index, result: result }
+        end
+        Ractor.main << { type: :stopped, worker: index }
+      end
+    end
+
+    def start_collector_thread
+      @collector_thread = Thread.new do
+        stopped = 0
+        loop do
+          message = Ractor.receive
+          if message[:type] == :stopped
+            stopped += 1
+            break if stopped >= @size
+          else
+            route(message)
+          end
+        end
+      end
+      @collector_thread.name = "security_box-collector"
+    end
+
+    def route(message)
+      @mutex.synchronize do
+        @in_flight[message[:worker]] -= 1 if @in_flight[message[:worker]] > 0
+        queue = @pending.delete(message[:id])
+        queue << message[:result] if queue
+      end
+    end
+
+    def record(result)
+      @mutex.synchronize do
+        @metrics[:evals] += 1
+        @metrics[:total_ms] += result.duration_ms.to_f
+      end
+    end
+
+    def next_id
+      @mutex.synchronize do
+        @next_id += 1
+        @next_id
+      end
+    end
+  end
+end

data/lib/security_box/registry.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module SecurityBox
+  # Named, reusable profiles: `SecurityBox.register(:name, from: :base) { |c| ... }`
+  # stores an immutable Configuration built through the builder DSL; `spawn`
+  # resolves a profile and derives per-call overrides with `#with`.
+  #
+  # Profiles must be registered before they are referenced by `from:`, cannot
+  # be redefined (immutability avoids accidental shadowing) and live for the
+  # process lifetime; tests can reset the registry with `clear!`.
+  module Registry
+    MUTEX = Mutex.new
+
+    @profiles = {}
+
+    class << self
+      def register(name, from: nil, &block)
+        key = normalize(name)
+        MUTEX.synchronize do
+          raise InvalidConfiguration, "profile #{key.inspect} is already registered" if @profiles.key?(key)
+
+          builder = Configuration::Builder.new
+          block&.call(builder)
+          base = base_of(from)
+          if base[:fuel_ms] && builder.changes.key?(:fuel)
+            raise InvalidConfiguration,
+                  "base profile #{from.inspect} uses fuel_ms; override fuel_ms (or clear it with fuel_ms: nil) instead of fuel"
+          end
+          @profiles[key] = Configuration.build(**base, **builder.changes)
+        end
+      end
+
+      def resolve(name)
+        key = normalize(name)
+        MUTEX.synchronize do
+          @profiles.fetch(key) do
+            raise InvalidConfiguration, "unknown profile #{key.inspect}; register it first with SecurityBox.register"
+          end
+        end
+      end
+
+      def profiles
+        MUTEX.synchronize { @profiles.dup.freeze }
+      end
+
+      def clear!
+        MUTEX.synchronize { @profiles.clear }
+      end
+
+      private
+
+      def normalize(name)
+        unless name.is_a?(Symbol) || name.is_a?(String)
+          raise InvalidConfiguration, "profile name must be a Symbol or String, got #{name.class}"
+        end
+
+        name.to_sym
+      end
+
+      def base_of(from)
+        return {} if from.nil?
+
+        key = normalize(from)
+        @profiles.fetch(key) do
+          raise InvalidConfiguration, "unknown base profile #{key.inspect}; register it before deriving from it"
+        end.to_h
+      end
+    end
+  end
+end

data/lib/security_box/result.rb

@@ -29,6 +29,13 @@ module SecurityBox
       @status == :ok
     end
 
+    # Factory for the "the worker never answered" sandbox failure (dead or
+    # stalled Ractor worker, or the pop deadline elapsed).
+    def self.worker_unavailable(worker_index)
+      new(status: :sandbox_error,
+          stderr: "security_box: RactorPool worker #{worker_index} did not answer\n")
+    end
+
     def to_h
       {
         status: @status,