security_box 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 22aa6209552c4b4a4fbc60fa98b71e6f70448fb308e3c8f133515ef663c32d7c
+  data.tar.gz: a33ce5bc7a235946efbd283eb3a8f5a718dc87a971eeb3eff799c5b6701ed172
+SHA512:
+  metadata.gz: aa260831067c04ed120b56d082b068ffd606a060999921e5e4f21f925eb4b721cd37c6e786a646cf024e02a5eba05f4e8e0354311045df76d3d9fb99838aa0fd
+  data.tar.gz: 1d0f95de215b37537d2ba3ca638120599d0461d50b783e1e5b52c5c56375d5729f4c1978e815082dc8c824a0389c1f765147cdf5d06f29981ad05e0f99c7ebc3

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-09-13
+
+### Added
+
+- Initial gem release: `gem install security_box` includes the packed ruby.wasm
+  sandbox image (`lib/security_box/assets/security_box.wasm`), so it works out
+  of the box without network access or build tools.
+- `SecurityBox.eval`, `SecurityBox.warmup`, `SecurityBox::Sandbox` and the
+  immutable `SecurityBox::Configuration` with `#with`.
+- Limit enforcement: fuel, wall-clock (epoch interruption), memory and
+  output-size limits; structured `Result` statuses
+  (`:ok`, `:error`, `:timeout`, `:fuel_exhausted`, `:memory_limit`,
+  `:sandbox_error`).
+- The sandbox image is built with `rake security_box:build_image` from the
+  pinned ruby.wasm release (`2.10.1`) and only needs rebuilding when
+  `lib/security_box/guest/*.rb` changes or the pin is bumped.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcelo Junior
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,232 @@
+# security_box
+
+[![Gem Version](https://img.shields.io/gem/v/security_box)](https://rubygems.org/gems/security_box)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+A secure sandbox to run untrusted Ruby code, built on top of
+[ruby.wasm](https://github.com/ruby/ruby.wasm) and the
+[wasmtime](https://github.com/bytecodealliance/wasmtime-rb) gem.
+
+Guest code runs inside a WebAssembly module compiled to `wasm32-unknown-wasip1`, so it has
+no access to the host filesystem, no network, no processes, no threads and no sockets.
+The host controls CPU (fuel), wall-clock time (epoch interruption), memory and output size,
+and always gets a structured `Result` back — even when the guest code raises, times out or
+tries to escape.
+
+## How it works
+
+1. A `ruby.wasm` image is packed with the Ruby runtime + stdlib + a small guest
+   entrypoint (`lib/security_box/guest/main.rb`).
+2. On every `#eval`, the host creates an exclusive tmpdir, writes the user code to it, and
+   mounts it read-write as `/work` inside the sandbox.
+3. A fresh wasm instance boots, evaluates the code and serializes a JSON envelope to
+   `/work/out.json`.
+4. The host reads the envelope, maps any wasmtime trap to a `Result` status, closes the
+   store and discards the tmpdir.
+
+One wasm process per `#eval` means zero residual state between executions.
+
+## Requirements
+
+- Ruby >= 4.0 (host)
+- `wasmtime` gem (runtime) — the only runtime dependency
+- `ruby_wasm` gem (build-time only, needed to rebuild the sandbox image)
+
+## Setup
+
+Install from RubyGems:
+
+```bash
+gem install security_box
+```
+
+Or add to your `Gemfile`:
+
+```ruby
+gem "security_box"
+```
+
+The gem ships a prebuilt sandbox image (`lib/security_box/assets/security_box.wasm`,
+about 110MB), so no network access or build tools are needed at install or at
+runtime.
+
+### Rebuilding the image (development only)
+
+If you change `lib/security_box/guest/*.rb` or bump the pinned ruby.wasm
+release, repack the sandbox image:
+
+```bash
+bundle install
+bundle exec rake security_box:build_image
+```
+
+This downloads the pinned ruby.wasm release (`2.10.1`, see the `Rakefile`) and
+packs it with the guest script into `lib/security_box/assets/security_box.wasm`.
+The task skips repacking when the image is already fresh. The image is not
+committed to git.
+
+You can point the library at a different image with the `SECURITY_BOX_IMAGE`
+environment variable or by passing `image_path:` in the configuration — useful
+for custom-built images.
+
+## Usage
+
+### Quick start
+
+```ruby
+require "security_box"
+
+result = SecurityBox.eval("puts 'hello'; 40 + 2")
+
+result.status    # => :ok
+result.value     # => 42
+result.stdout    # => "hello\n"
+result.fuel_used # => > 0
+result.duration_ms # => 257.0 (approx; dominated by the ruby.wasm boot)
+```
+
+### Warming up
+
+The first `eval` in a process pays the cold WebAssembly compilation of the image
+(~15s) plus the engine setup. Call `SecurityBox.warmup` ahead of time (e.g., at
+boot) to pay that cost up front — every subsequent `eval` then only pays the
+~240ms guest boot:
+
+```ruby
+SecurityBox.warmup
+
+SecurityBox.eval("40 + 2").value # => 42 (~250ms, no cold compile)
+```
+
+`#eval` warms the same caches lazily on first use, so calling `warmup` is a pure
+optimization — behavior and results are identical without it. It accepts the same
+options as `Configuration.build` and is safe to call multiple times.
+
+### Multiple evaluations on the same sandbox
+
+```ruby
+sandbox = SecurityBox::Sandbox.new
+sandbox.eval("1 + 1").value # => 2
+sandbox.eval("3 * 3").value # => 9
+```
+
+### Per-call limits
+
+Options can be passed per call (derived from the configuration without mutating it):
+`timeout_ms`, `fuel`, `memory_size`, `stdout_limit`, `stderr_limit`.
+
+```ruby
+# Wall-clock limit via epoch interruption
+SecurityBox.eval("while true; end", timeout_ms: 500).status # => :timeout
+
+# Deterministic CPU budget
+SecurityBox.eval("while true; end", fuel: 1_000_000).status # => :fuel_exhausted
+
+# Memory limit
+SecurityBox.eval(
+  "a = []; loop { a << ('x' * 1024) }",
+  memory_size: 128 * 1024 * 1024,
+  timeout_ms: 15_000
+).status # => :memory_limit
+
+# Output truncation
+SecurityBox.eval('1000.times { print "x" * 1000 }', stdout_limit: 4096).stdout.bytesize # => <= 4096
+```
+
+### Errors from guest code
+
+Exceptions raised by guest code are a *result*, not a sandbox failure:
+
+```ruby
+result = SecurityBox.eval('raise ArgumentError, "boom"')
+
+result.status           # => :error
+result.error["class"]   # => "ArgumentError"
+result.error["message"] # => "boom"
+```
+
+### Configuration
+
+`SecurityBox::Configuration` is immutable; use `.build` to create and `#with` to derive:
+
+```ruby
+config = SecurityBox::Configuration.build(
+  fuel: 10_000_000_000,             # deterministic CPU budget
+  timeout_ms: 2_000,                # wall-clock limit (epoch interruption)
+  memory_size: 512 * 1024 * 1024,   # wasm linear memory limit
+  stdout_limit: 1 << 20,            # stdout capture capacity in bytes
+  stderr_limit: 1 << 16,            # stderr capture capacity in bytes
+  epoch_interval_ms: 25,            # epoch timer granularity
+  env: { "LANG" => "C" }            # guest environment (empty by default)
+)
+
+lean = config.with(timeout_ms: 500, fuel: 5_000_000)
+sandbox = SecurityBox::Sandbox.new(lean)
+```
+
+### Result statuses
+
+| Status | Meaning |
+|---|---|
+| `:ok` | guest code ran and returned a value |
+| `:error` | guest code raised an exception (see `#error`) |
+| `:timeout` | interrupted by the epoch deadline (wall clock) |
+| `:fuel_exhausted` | CPU budget exhausted |
+| `:memory_limit` | exceeded the store `memory_size` |
+| `:sandbox_error` | sandbox failure (unexpected trap, missing/invalid envelope) |
+
+Values are JSON-serialized; non-serializable objects are returned as their `inspect`
+string.
+
+## Isolation guarantees
+
+| Probe inside the guest | Result |
+|---|---|
+| `File.write("/etc/passwd", ...)` | `Errno::ENOENT` (guest does not see the host FS) |
+| `Dir["/*"]` | `[]` (empty root) |
+| `system("ls")` / backticks / `IO.popen` | no-op stubs / `ArgumentError` (nothing executes) |
+| `fork` | `NotImplementedError` |
+| `Thread.new` | `NotImplementedError` (WASI p1 has no threads) |
+| `require "socket"` | `LoadError` (no network) |
+| `ENV` | `{}` (sanitized) |
+| infinite loop | killed by epoch deadline or fuel budget |
+
+Notes:
+
+- The guest Ruby version is the one from ruby.wasm (4.0), not necessarily the host's.
+- Concurrency: `invoke` holds the GVL, so executions serialize per host process. Scale
+  horizontally with multiple processes (e.g., Puma workers); a stuck guest still can't
+  hang the process thanks to the epoch deadline.
+
+## Running the tests
+
+```bash
+bundle exec rspec spec/
+```
+
+The integration suite runs against the real ruby.wasm image. If the image at
+`lib/security_box/assets/security_box.wasm` is missing, the suite builds it
+automatically before running (this may take a few minutes the first time).
+
+## Releasing
+
+1. Rebuild the image if needed: `bundle exec rake security_box:build_image`
+   (also runs automatically before `rake build`/`rake release`).
+2. Verify it is fresh: `bundle exec rake security_box:verify_image`
+3. Run the suite: `bundle exec rake spec`
+4. Build and publish: `bundle exec rake release` (tags git and pushes the gem
+   to RubyGems.org)
+
+## Learning spike
+
+`bin/spike.rb` validates the feasibility questions (Q1–Q9) against the built image and
+prints a timing report:
+
+```bash
+bundle exec ruby bin/spike.rb
+```
+
+## Documentation
+
+- `docs/PLAN.md` — architecture, roadmap and threat model
+- `docs/plan/stages/stage_1.md` — stage 1 findings and measured numbers

data/lib/security_box/configuration.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module SecurityBox
+  # Immutable sandbox configuration. Use .build to create and #with to derive.
+  class Configuration
+    IMAGE_ENV_VAR = "SECURITY_BOX_IMAGE"
+    IMAGE_ASSET_RELATIVE = "assets/security_box.wasm"
+    IMAGE_DEV_RELATIVE = "../../build/security_box.wasm"
+
+    DEFAULTS = {
+      image_path: nil, # resolved dynamically (project's build/security_box.wasm)
+      fuel: 10_000_000_000,
+      timeout_ms: 2_000,
+      memory_size: 512 * 1024 * 1024,
+      stdout_limit: 1 << 20,
+      stderr_limit: 1 << 16,
+      epoch_interval_ms: 25,
+      env: {}.freeze
+    }.freeze
+
+    attr_reader :image_path, :fuel, :timeout_ms, :memory_size,
+                :stdout_limit, :stderr_limit, :epoch_interval_ms, :env
+
+    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:)
+      @image_path = image_path || default_image_path
+      @fuel = Integer(fuel)
+      @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
+      freeze
+    end
+
+    def with(**changes)
+      self.class.build(**to_h.merge(changes))
+    end
+
+    def to_h
+      {
+        image_path: @image_path,
+        fuel: @fuel,
+        timeout_ms: @timeout_ms,
+        memory_size: @memory_size,
+        stdout_limit: @stdout_limit,
+        stderr_limit: @stderr_limit,
+        epoch_interval_ms: @epoch_interval_ms,
+        env: @env
+      }
+    end
+
+    private
+
+    # Resolution order (first existing path wins):
+    #   1. SECURITY_BOX_IMAGE environment variable
+    #   2. the image packed inside this library (gem install or checkout)
+    #   3. legacy development output (build/security_box.wasm)
+    def default_image_path
+      candidates = [ENV[IMAGE_ENV_VAR],
+                    File.expand_path(IMAGE_ASSET_RELATIVE, __dir__),
+                    File.expand_path(IMAGE_DEV_RELATIVE, __dir__)].compact
+      path = candidates.find { |candidate| File.file?(candidate) }
+      return path if path
+
+      raise ImageMissing,
+            "Sandbox image not found. Tried: #{candidates.join(', ')}. " \
+            "Run `rake security_box:build_image`, set #{IMAGE_ENV_VAR}, " \
+            "or pass image_path in the configuration."
+    end
+  end
+end

data/lib/security_box/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SecurityBox
+  class Error < StandardError; end
+
+  class ImageMissing < Error; end
+
+  class InvalidConfiguration < Error; end
+end

data/lib/security_box/guest/main.rb

@@ -0,0 +1,62 @@
+# Guest entrypoint packed into the ruby.wasm image (/src/main.rb).
+#
+# Input: /work/code.rb (preferred) or ARGV[0].
+# Result: /work/out.json (JSON envelope); fallback: sentinel line on stdout.
+#
+# NOTE (stage 1): the result channel is reliable against accidents, not against
+# an active adversary (guest code can forge the envelope). Token mitigations and
+# schema validation land in Stage 2.
+require "json"
+
+module SB
+  SENTINEL = "__SECURITY_BOX_RESULT__"
+  WORK_DIR = "/work"
+
+  module_function
+
+  def run
+    code = fetch_code
+    return fatal("no code provided") unless code
+
+    t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    out = evaluate(code)
+    out[:duration_ms] = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1000).round(2)
+    emit(out)
+  end
+
+  def fetch_code
+    code_path = File.join(WORK_DIR, "code.rb")
+    return File.read(code_path) if File.exist?(code_path)
+
+    ARGV[0]
+  rescue StandardError, SystemCallError
+    ARGV[0]
+  end
+
+  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 } }
+  end
+
+  # Values must survive JSON; the round-trip normalizes what the host will read.
+  def jsonable(value)
+    JSON.parse(JSON.generate(value))
+  rescue StandardError, TypeError
+    value.inspect
+  end
+
+  # Preferred: /work/out.json. Fallback (no /work): sentinel on stdout.
+  def emit(out)
+    json = JSON.generate(out)
+    File.write(File.join(WORK_DIR, "out.json"), json)
+  rescue StandardError, SystemCallError
+    $stdout.puts "#{SENTINEL}:#{json}"
+  end
+
+  def fatal(message)
+    emit({ ok: false, value: nil, error: { "class" => "SecurityBox::Guest", "message" => message } })
+  end
+end
+
+SB.run

data/lib/security_box/result.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module SecurityBox
+  # Result of a sandbox execution. Possible statuses:
+  #   :ok             — guest code ran and returned a value
+  #   :error          — guest code raised an exception
+  #   :timeout        — interrupted by epoch (wall clock)
+  #   :fuel_exhausted — CPU budget exhausted
+  #   :memory_limit   — exceeded the store memory_size
+  #   :sandbox_error  — sandbox failure (unexpected trap, missing/invalid envelope)
+  class Result
+    attr_reader :status, :value, :error, :stdout, :stderr,
+                :fuel_used, :duration_ms, :guest_duration_ms
+
+    def initialize(status:, value: nil, error: nil, stdout: "", stderr: "",
+                   fuel_used: nil, duration_ms: nil, guest_duration_ms: nil)
+      @status = status
+      @value = value
+      @error = error
+      @stdout = stdout
+      @stderr = stderr
+      @fuel_used = fuel_used
+      @duration_ms = duration_ms
+      @guest_duration_ms = guest_duration_ms
+      freeze
+    end
+
+    def ok?
+      @status == :ok
+    end
+
+    def to_h
+      {
+        status: @status,
+        value: @value,
+        error: @error,
+        stdout: @stdout,
+        stderr: @stderr,
+        fuel_used: @fuel_used,
+        duration_ms: @duration_ms,
+        guest_duration_ms: @guest_duration_ms
+      }
+    end
+  end
+end

data/lib/security_box/runtime.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "wasmtime"
+
+module SecurityBox
+  # Registry of heavyweight artifacts shared across sandboxes:
+  # - Engine (one per runtime configuration; owns the epoch timer)
+  # - Compiled Module (one per engine+image)
+  #
+  # Module compilation is slow (~15s the first time per process); the disk cache
+  # (Module#serialize) lands in Stage 2.
+  module Runtime
+    MUTEX = Mutex.new
+
+    @engines = {}
+    @modules = {}
+
+    class << self
+      def engine(epoch_interval_ms:)
+        MUTEX.synchronize do
+          @engines[epoch_interval_ms] ||= build_engine(epoch_interval_ms)
+        end
+      end
+
+      def module_for(engine, image_path)
+        MUTEX.synchronize do
+          @modules[[engine.object_id, image_path]] ||=
+            Wasmtime::Module.from_file(engine, image_path)
+        end
+      end
+
+      def clear!
+        MUTEX.synchronize do
+          @engines.clear
+          @modules.clear
+        end
+      end
+
+      private
+
+      def build_engine(epoch_interval_ms)
+        engine = Wasmtime::Engine.new(consume_fuel: true, epoch_interruption: true)
+        if engine.respond_to?(:start_epoch_interval)
+          engine.start_epoch_interval(epoch_interval_ms)
+        else
+          timer = Thread.new do
+            loop do
+              sleep(epoch_interval_ms / 1000.0)
+              engine.increment_epoch
+            end
+          end
+          timer.name = "security_box-epoch-timer"
+        end
+        engine
+      end
+    end
+  end
+end

data/lib/security_box/sandbox.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "tmpdir"
+
+module SecurityBox
+  # :oneshot mode sandbox — one wasm instance per #eval.
+  #
+  # Flow:
+  #   1. exclusive tmpdir mounted as /work (read-write)
+  #   2. user code written to /work/code.rb
+  #   3. guest (/src/main.rb) evaluates it and writes /work/out.json
+  #   4. host reads the envelope and returns a Result
+  class Sandbox
+    GUEST_ENTRYPOINT = "/src/main.rb"
+    RESULT_FILE = "out.json"
+    CODE_FILE = "code.rb"
+
+    def initialize(configuration = Configuration.build)
+      @config = configuration
+      @engine = Runtime.engine(epoch_interval_ms: @config.epoch_interval_ms)
+      @module = Runtime.module_for(@engine, @config.image_path)
+    end
+
+    # Runs `code` in the sandbox and returns a Result.
+    # Per-call options (derived from the configuration without mutating it):
+    #   timeout_ms:, fuel:, memory_size:, stdout_limit:, stderr_limit:
+    def eval(code, **overrides)
+      raise ArgumentError, "code is required" if code.nil? || code.empty?
+
+      config = overrides.empty? ? @config : @config.with(**overrides)
+      stdout = +""
+      stderr = +""
+      t0 = monotonic_ms
+
+      Dir.mktmpdir("security_box") do |workdir|
+        File.write(File.join(workdir, CODE_FILE), code)
+        envelope = nil
+        status = nil
+        fuel_used = nil
+
+        store = Wasmtime::Store.new(
+          @engine,
+          wasi_p1_config: build_wasi(workdir, stdout, stderr, config),
+          limits: { memory_size: config.memory_size }
+        )
+        begin
+          store.set_fuel(config.fuel)
+          instance = build_linker.instantiate(store, @module)
+          store.set_epoch_deadline(epoch_ticks(config))
+          status = invoke_guest(instance, store)
+          fuel_used = config.fuel - store.get_fuel
+          envelope = read_envelope(workdir)
+        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)
+      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)
+        .set_mapped_directory(workdir, "/work", :read_write)
+    end
+
+    def build_linker
+      @linker ||= Wasmtime::Linker.new(@engine).tap do |linker|
+        Wasmtime::WASI::P1.add_to_linker_sync(linker)
+      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)
+      path = File.join(workdir, RESULT_FILE)
+      return nil unless File.exist?(path)
+
+      JSON.parse(File.read(path))
+    rescue JSON::ParserError
+      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"]
+        )
+      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 monotonic_ms
+      Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000
+    end
+  end
+end

data/lib/security_box/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SecurityBox
+  VERSION = "0.1.0"
+end

data/lib/security_box.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "security_box/version"
+require_relative "security_box/errors"
+require_relative "security_box/configuration"
+require_relative "security_box/result"
+require_relative "security_box/runtime"
+require_relative "security_box/sandbox"
+
+module SecurityBox
+  # Convenience shortcut:
+  #   SecurityBox.eval("1 + 1")            # => Result
+  #   SecurityBox.eval("1", fuel: 100)     # per-call overrides
+  def self.eval(code, **overrides)
+    Sandbox.new.eval(code, **overrides)
+  end
+
+  # Prepares the shared runtime artifacts (Engine + compiled Module) ahead of
+  # time so the first #eval skips the cold module compilation (~15s per
+  # process). #eval warms these caches lazily on first use, so calling
+  # warmup is a pure optimization: behavior and results are identical
+  # without it. Accepts the same options as Configuration.build (only
+  # image_path and epoch_interval_ms affect what gets warmed). Returns the
+  # warmed Sandbox; safe to call multiple times.
+  def self.warmup(**options)
+    Sandbox.new(Configuration.build(**options))
+  end
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: security_box
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Marcelo Junior
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: wasmtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: SecurityBox runs untrusted Ruby code inside a ruby.wasm (wasm32-unknown-wasip1)
+  module via the wasmtime gem. The guest has no filesystem, network, processes, threads
+  or sockets, and the host enforces CPU (fuel), wall-clock, memory and output-size
+  limits, always receiving a structured Result back.
+email:
+- marcelo.jr63@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/security_box.rb
+- lib/security_box/assets/security_box.wasm
+- lib/security_box/configuration.rb
+- lib/security_box/errors.rb
+- lib/security_box/guest/main.rb
+- lib/security_box/result.rb
+- lib/security_box/runtime.rb
+- lib/security_box/sandbox.rb
+- lib/security_box/version.rb
+homepage: https://github.com/juneira/security_box
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/juneira/security_box
+  source_code_uri: https://github.com/juneira/security_box
+  changelog_uri: https://github.com/juneira/security_box/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Run untrusted Ruby code inside a WebAssembly sandbox
+test_files: []