security_box 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22aa6209552c4b4a4fbc60fa98b71e6f70448fb308e3c8f133515ef663c32d7c
-  data.tar.gz: a33ce5bc7a235946efbd283eb3a8f5a718dc87a971eeb3eff799c5b6701ed172
+  metadata.gz: 9949a172b6bf1ddf1eddd9756c8dcbad273d8f2409669304227bb2f981c9fef6
+  data.tar.gz: 499c948e3fd57c221f8aef7f8ad6dd63757b36e9d5a4a62d8c8a70823908f86d
 SHA512:
-  metadata.gz: aa260831067c04ed120b56d082b068ffd606a060999921e5e4f21f925eb4b721cd37c6e786a646cf024e02a5eba05f4e8e0354311045df76d3d9fb99838aa0fd
-  data.tar.gz: 1d0f95de215b37537d2ba3ca638120599d0461d50b783e1e5b52c5c56375d5729f4c1978e815082dc8c824a0389c1f765147cdf5d06f29981ad05e0f99c7ebc3
+  metadata.gz: 1cf51781bb108aa6849ae24bd1db5b812c7e0a7e94f0d1876eb1a860cabc4a6b00241fdc19b4b142b88da8bdf86ed6e9c5dc53009237f36706a4ff637fe96d5f
+  data.tar.gz: 39dfd3af95bc8bfd2e3bd79ac57b118ee706b2f7da3aee98854aea832094b29342e751b2a41bf630c593fd07289ecf7ac041b1d416682924f276a29be4a7259b

data/CHANGELOG.md

@@ -5,6 +5,59 @@ 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.3.0] - 2026-09-14
+
+### Added
+
+- Named, reusable profiles: `SecurityBox.register(:name, from: :base) { |c| c.fuel 100 }`
+  and `SecurityBox.spawn(:name, **overrides)` (a `Configuration` or the defaults also
+  work). Profiles are immutable; duplicate/unknown names raise
+  `SecurityBox::InvalidConfiguration`.
+- `SecurityBox::Configuration#fingerprint`: a stable identity for equal settings
+  (SHA-256 of the canonical configuration), ready for artifact caches.
+- Guest error envelopes now carry a `backtrace`: user frames only, capped at 20,
+  sandbox-internal locations (no host paths). Surfaced via `Result#error["backtrace"]`;
+  malformed backtraces invalidate the envelope (`:sandbox_error`).
+- `Result#fuel_used` is now `nil` for `:timeout`: epoch traps restore fuel to the last
+  checkpoint, so the restored value understated consumption by orders of magnitude.
+  (Truthful on completion, fuel exhaustion and memory-limit traps.)
+
+### Changed
+
+- A guest `NoMemoryError` (interpreter OOM against the store limit) is reported as
+  `:memory_limit` instead of `:error`.
+- A `memory_size` below the image's declared minimum (1528 pages ≈ 95.5 MiB) now
+  returns a `:sandbox_error` Result with a `security_box:` note on stderr instead of
+  raising `Wasmtime::Error` out of `#eval`.
+- The sandbox image must be repacked (`rake security_box:build_image`) when
+  upgrading: the guest entrypoint protocol changed.
+
+## [0.2.0] - 2026-09-14
+
+### Added
+
+- Compiled-module disk cache (`~/.cache/security_box/modules`, override with
+  `SECURITY_BOX_CACHE_DIR`): new processes boot the runtime in ~0.5s instead
+  of ~15s by deserializing the compiled artifact instead of recompiling.
+  Best effort — misses, corruption or an unwritable directory fall back to a
+  normal compile.
+- Result-channel integrity: a per-eval random token is passed to the guest via
+  `SB_TOKEN`, captured and scrubbed by the hardening prelude, and embedded in
+  both the `/work/out.json` envelope and the stdout sentinel line. The host
+  validates the envelope schema and token; forged results (e.g. an `at_exit`
+  overwrite or a fake sentinel) become `:sandbox_error`.
+- Hardening prelude (`lib/security_box/guest/prelude.rb`): `system`, `exec`,
+  `Kernel#spawn`, backticks, `IO.popen`, `Process.spawn` and `Kernel#open` now
+  raise `SecurityError` inside the guest (they previously were misleading
+  WASI stubs); `ENV` is scrubbed before user code runs; `$stdout.sync = true`.
+
+### Changed
+
+- Guest result envelope carries a `token` field; `system(...)` inside guest
+  code raises `SecurityError` instead of returning a stub `true`.
+- The sandbox image must be repacked (`rake security_box:build_image`) when
+  upgrading: the guest entrypoint protocol changed.
+
 ## [0.1.0] - 2026-09-13
 
 ### Added

data/README.md

@@ -16,13 +16,16 @@ 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`).
+   entrypoint (`lib/security_box/guest/main.rb`) plus a hardening prelude
+   (`lib/security_box/guest/prelude.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.
+   mounts it read-write as `/work` inside the sandbox. It also generates a per-eval
+   random token and passes it to the guest via `SB_TOKEN`.
+3. A fresh wasm instance boots; the prelude captures the token, scrubs `ENV` and
+   neutralizes process-spawn APIs, then the guest evaluates the code and serializes a
+   token-signed JSON envelope to `/work/out.json` (stdout sentinel fallback).
+4. The host validates the envelope (schema + token — forged results are rejected),
+   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.
 
@@ -87,15 +90,18 @@ 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:
+The first `eval` in a process pays either the cold WebAssembly compilation of the image
+(~15s) or a fast deserialize from the compiled-module disk cache (~0.5s) plus the engine
+setup. The cache lives in `~/.cache/security_box/modules` (override with
+`SECURITY_BOX_CACHE_DIR`), is keyed by the image content, and is fully best effort —
+on any miss or corruption the module is simply recompiled. Call `SecurityBox.warmup`
+ahead of time (e.g., at boot) to pay that cost up front — every subsequent `eval` then
+only pays the ~260ms guest boot:
 
 ```ruby
 SecurityBox.warmup
 
-SecurityBox.eval("40 + 2").value # => 42 (~250ms, no cold compile)
+SecurityBox.eval("40 + 2").value # => 42 (~260ms, no cold compile)
 ```
 
 `#eval` warms the same caches lazily on first use, so calling `warmup` is a pure
@@ -138,13 +144,44 @@ SecurityBox.eval('1000.times { print "x" * 1000 }', stdout_limit: 4096).stdout.b
 Exceptions raised by guest code are a *result*, not a sandbox failure:
 
 ```ruby
-result = SecurityBox.eval('raise ArgumentError, "boom"')
+result = SecurityBox.eval("def boom; raise ArgumentError, 'boom'; end; boom")
 
-result.status           # => :error
-result.error["class"]   # => "ArgumentError"
-result.error["message"] # => "boom"
+result.status                    # => :error
+result.error["class"]            # => "ArgumentError"
+result.error["message"]          # => "boom"
+result.error["backtrace"]        # => ["sandbox:1:in 'Object#boom'", "sandbox:1:in '<main>'"]
 ```
 
+The backtrace contains guest frames only (sandbox-internal locations, capped at
+20 frames) — nothing from the host filesystem leaks.
+
+### Named profiles
+
+Reusable configurations registered once and spawned as often as needed:
+
+```ruby
+SecurityBox.register(:default) do |c|
+  c.fuel 10_000_000_000
+  c.timeout_ms 2_000
+end
+
+SecurityBox.register(:lean, from: :default) do |c|
+  c.fuel 2_000_000_000        # boot alone costs ~1e9; see the fuel notes below
+  c.timeout_ms 500
+end
+
+box = SecurityBox.spawn(:lean)               # Sandbox from the profile
+box.eval("40 + 2").value                     # => 42
+
+SecurityBox.spawn(:lean, timeout_ms: 100)    # per-call override (profile unchanged)
+SecurityBox.spawn                            # default configuration
+```
+
+Profiles are immutable: duplicate names and unknown names raise
+`SecurityBox::InvalidConfiguration`; overrides never mutate the profile.
+`SecurityBox::Configuration#fingerprint` gives every configuration a stable
+identity (equal settings → equal fingerprint), used to share runtime artifacts.
+
 ### Configuration
 
 `SecurityBox::Configuration` is immutable; use `.build` to create and `#with` to derive:
@@ -169,11 +206,11 @@ sandbox = SecurityBox::Sandbox.new(lean)
 | 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) |
+| `:error` | guest code raised an exception (see `#error`; includes `backtrace`) |
+| `:timeout` | interrupted by the epoch deadline (wall clock); `fuel_used` is `nil` (epoch traps restore fuel to the checkpoint) |
 | `:fuel_exhausted` | CPU budget exhausted |
-| `:memory_limit` | exceeded the store `memory_size` |
-| `:sandbox_error` | sandbox failure (unexpected trap, missing/invalid envelope) |
+| `:memory_limit` | exceeded the store `memory_size` (wasm trap or guest `NoMemoryError`) |
+| `:sandbox_error` | sandbox failure (unexpected trap, missing/invalid envelope, `memory_size` below the image's minimum) |
 
 Values are JSON-serialized; non-serializable objects are returned as their `inspect`
 string.
@@ -184,11 +221,13 @@ string.
 |---|---|
 | `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) |
+| `system("ls")` / backticks / `IO.popen` / `Process.spawn` | `SecurityError` (hardening prelude) |
+| `Kernel#open(...)` | `SecurityError` (pipe form; use `File.open`) |
 | `fork` | `NotImplementedError` |
 | `Thread.new` | `NotImplementedError` (WASI p1 has no threads) |
 | `require "socket"` | `LoadError` (no network) |
-| `ENV` | `{}` (sanitized) |
+| `ENV` | `{}` (token read and scrubbed by the prelude) |
+| forge `out.json` via `at_exit` / fake sentinel | rejected (token mismatch → `:sandbox_error`) |
 | infinite loop | killed by epoch deadline or fuel budget |
 
 Notes:
@@ -197,6 +236,17 @@ Notes:
 - 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.
+- Ractor note: wasmtime `Engine`/`Module` are Ractor-shareable and Ractors run wasm in
+  parallel (measured ≈3.6x with 4 Ractors on 6 cores); a supported Ractor pool is on
+  the roadmap (see `docs/plan/stages/stage_3.md`).
+- Memory: the packed image declares a 1528-page (~95.5 MiB) minimum; `memory_size`
+  below that fails instantiation (reported as `:sandbox_error`). Practical minimum is
+  ~128–144MB for small workloads; the 512MB default leaves comfortable headroom.
+- Fuel budgeting: compute workloads burn ~4–8e9 fuel/s (tight loops up to ~8.4e9/s)
+  and every eval costs ~1e9 fuel for boot — see the calibration table in
+  `docs/plan/stages/stage_3.md`. Consequently `fuel` below ~1e9 cannot even boot, and
+  `timeout_ms` below ~300ms times out during the guest boot (~500ms is a practical
+  floor).
 
 ## Running the tests
 
@@ -230,3 +280,7 @@ bundle exec ruby bin/spike.rb
 
 - `docs/PLAN.md` — architecture, roadmap and threat model
 - `docs/plan/stages/stage_1.md` — stage 1 findings and measured numbers
+- `docs/plan/stages/stage_2.md` — stage 2 findings (hardening prelude, result-channel
+  integrity, compiled-module disk cache)
+- `docs/plan/stages/stage_3.md` — stage 3 findings (named profiles, Ractor
+  parallelism, memory floor, fuel calibration, backtrace)

data/lib/security_box/configuration.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "digest"
+require "json"
+
 module SecurityBox
   # Immutable sandbox configuration. Use .build to create and #with to derive.
   class Configuration
@@ -55,6 +58,64 @@ module SecurityBox
       }
     end
 
+    # Stable identity of the configuration values (SHA-256 of the normalized
+    # 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.
+    def fingerprint
+      Digest::SHA256.hexdigest(JSON.generate(canonical))
+    end
+
+    def canonical
+      to_h.merge(env: @env.sort.to_h)
+    end
+
+    # Mutable collector for the register DSL. Setter names match the
+    # Configuration options (no `=`, e.g. `c.fuel 100`); only changed values
+    # are collected and merged over the base profile.
+    class Builder
+      def initialize
+        @changes = {}
+      end
+
+      def changes
+        @changes
+      end
+
+      def image_path(value)
+        @changes[:image_path] = value
+      end
+
+      def fuel(value)
+        @changes[:fuel] = value
+      end
+
+      def timeout_ms(value)
+        @changes[:timeout_ms] = value
+      end
+
+      def memory_size(value)
+        @changes[:memory_size] = value
+      end
+
+      def stdout_limit(value)
+        @changes[:stdout_limit] = value
+      end
+
+      def stderr_limit(value)
+        @changes[:stderr_limit] = value
+      end
+
+      def epoch_interval_ms(value)
+        @changes[:epoch_interval_ms] = value
+      end
+
+      # Replaces the guest environment (it is not merged with the base).
+      def env(value)
+        @changes[:env] = value
+      end
+    end
+
     private
 
     # Resolution order (first existing path wins):

data/lib/security_box/envelope.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SecurityBox
+  # Host-side validation of the guest result envelope.
+  #
+  # The guest reports its result either via /work/out.json or, when /work is
+  # unavailable, via a sentinel line on stdout (format:
+  # `__SECURITY_BOX_RESULT__:<token>:<json>`). Both embed the per-eval random
+  # token the host generated. An envelope is trusted only when it parses, the
+  # token matches and every field has the expected type; otherwise nil is
+  # returned and the execution is reported as a sandbox failure.
+  module Envelope
+    # Keep in sync with lib/security_box/guest/main.rb.
+    SENTINEL = "__SECURITY_BOX_RESULT__"
+
+    class << self
+      # Parses `raw` (JSON text) and validates it against `token`.
+      # Returns the envelope Hash or nil when invalid/untrusted.
+      def parse(raw, token)
+        return nil unless raw.is_a?(String) && token.is_a?(String) && !token.empty?
+
+        envelope = JSON.parse(raw)
+        return nil unless valid?(envelope, token)
+
+        envelope
+      rescue JSON::ParserError, TypeError, ArgumentError
+        nil
+      end
+
+      # Scans captured stdout for exactly one sentinel line carrying `token`.
+      # Zero or multiple sentinel lines (e.g. a guest forging an extra one)
+      # yield nil.
+      def from_stdout(stdout, token)
+        prefix = "#{SENTINEL}:"
+        lines = stdout.to_s.split("\n").select { |line| line.start_with?(prefix) }
+        return nil unless lines.size == 1
+
+        _sentinel, _embedded_token, json = lines.first.split(":", 3)
+        parse(json, token)
+      end
+
+      private
+
+      def valid?(envelope, token)
+        return false unless envelope.is_a?(Hash)
+        return false unless [true, false].include?(envelope["ok"])
+        return false unless envelope["token"] == token
+
+        if envelope["ok"]
+          return false unless envelope.key?("value")
+        else
+          error = envelope["error"]
+          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/guest/main.rb

@@ -3,11 +3,16 @@
 # 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.
+# Integrity: the host generates a per-eval random token and passes it via ENV;
+# the prelude captures it and scrubs ENV before user code runs. Both the
+# envelope and the sentinel line embed the token, and the host rejects any
+# result that does not carry the expected token (see lib/security_box/envelope.rb).
+# This hardens the channel against forged results (e.g. an at_exit handler
+# overwriting out.json); it is defense in depth, not a cryptographic guarantee.
 require "json"
 
+require_relative "prelude"
+
 module SB
   SENTINEL = "__SECURITY_BOX_RESULT__"
   WORK_DIR = "/work"
@@ -15,13 +20,15 @@ module SB
   module_function
 
   def run
+    token = SBPrelude.apply!
+
     code = fetch_code
-    return fatal("no code provided") unless code
+    return fatal("no code provided", token) 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)
+    emit(out, token)
   end
 
   def fetch_code
@@ -36,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.
@@ -47,15 +73,27 @@ module SB
   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)
+  # 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))
+    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}:#{json}"
+    false
   end
 
-  def fatal(message)
-    emit({ ok: false, value: nil, error: { "class" => "SecurityBox::Guest", "message" => message } })
+  def fatal(message, token)
+    emit({ ok: false, value: nil, error: { "class" => "SecurityBox::Guest", "message" => message } }, token)
   end
 end
 

data/lib/security_box/guest/prelude.rb

@@ -0,0 +1,71 @@
+# Hardening prelude — loaded before user code (defense in depth; WASI is the
+# primary isolation boundary).
+#
+# Responsibilities (in order):
+#   1. capture the per-eval sandbox token from ENV and hand it to the guest
+#      protocol exactly once (main.rb), erasing every other reference;
+#   2. scrub ENV so user code sees an empty environment;
+#   3. neutralize the process-spawn APIs that WASI leaves as misleading stubs
+#      (e.g. `system` returns true without running anything) by raising
+#      SecurityError instead;
+#   4. disable Kernel#open entirely (its pipe form executes processes; user
+#      code must use File.open/IO.read for plain files);
+#   5. set $stdout.sync so captured output is not lost on a hard kill.
+module SBPrelude
+  DENIED_MESSAGE = "process execution is not allowed inside the sandbox"
+
+  class << self
+    # Applies all hardening and returns the sandbox token (or nil). The token
+    # is removed from the prelude state; afterwards it exists only in the
+    # caller's local scope.
+    def apply!
+      capture_token
+      scrub_env
+      neutralize_process_apis
+      sync_stdout
+      take_token
+    end
+
+    # Returns the token captured by apply! and erases the stored reference.
+    def take_token
+      token = @token
+      remove_instance_variable(:@token) if instance_variable_defined?(:@token)
+      token
+    end
+
+    private
+
+    def capture_token
+      @token = ENV["SB_TOKEN"]
+    end
+
+    def scrub_env
+      ENV.each_key { |key| ENV.delete(key) }
+    end
+
+    def neutralize_process_apis
+      %w[system exec spawn `].each do |name|
+        neutralize_instance_method(Kernel, name)
+      end
+      neutralize_instance_method(Kernel, "open")
+      neutralize_singleton_method(IO, :popen)
+      neutralize_singleton_method(Process, :spawn)
+    end
+
+    def neutralize_instance_method(owner, name)
+      owner.module_eval do
+        define_method(name) { |*args, **kwargs| raise SecurityError, DENIED_MESSAGE }
+      end
+    end
+
+    def neutralize_singleton_method(owner, name)
+      owner.define_singleton_method(name) do |*args, **kwargs|
+        raise SecurityError, DENIED_MESSAGE
+      end
+    end
+
+    def sync_stdout
+      $stdout.sync = true
+    end
+  end
+end

data/lib/security_box/module_cache.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "wasmtime"
+
+module SecurityBox
+  # Content-addressed disk cache for compiled wasm modules.
+  #
+  # Compiling the ruby.wasm image costs ~15s per process. This cache stores the
+  # compiled artifact (Module#serialize) so later processes pay only a fast
+  # deserialize. Files live at <cache_dir>/modules/<key>.cwasm, where the key
+  # combines the image content digest with the wasmtime precompile compatibility
+  # key — a stored module is only reused when the running engine can consume it.
+  #
+  # Everything here is best effort: on any I/O or deserialization failure the
+  # caller falls back to a regular compile and the cache self-heals on the next
+  # successful store. Set SECURITY_BOX_CACHE_DIR to relocate the cache; the
+  # default is ~/.cache/security_box.
+  module ModuleCache
+    CACHE_DIR_ENV_VAR = "SECURITY_BOX_CACHE_DIR"
+
+    class << self
+      # Returns the cached module for this engine+image, or nil on cache miss,
+      # corrupted cache file or any cache error.
+      def load_module(engine, image_path)
+        path = cache_path(engine, image_path)
+        return nil unless path && File.file?(path)
+
+        Wasmtime::Module.deserialize_file(engine, path)
+      rescue Wasmtime::Error, TypeError, SystemCallError
+        nil
+      end
+
+      # Compiles the image and stores the serialized artifact in the cache
+      # (best effort). Returns the compiled module in all cases.
+      def compile_and_store(engine, image_path)
+        module_ = Wasmtime::Module.from_file(engine, image_path)
+        store(engine, image_path, module_)
+        module_
+      end
+
+      def store(engine, image_path, module_)
+        path = cache_path(engine, image_path)
+        return if path.nil?
+
+        dir = File.dirname(path)
+        FileUtils.mkdir_p(dir)
+        tmp = File.join(dir, ".#{File.basename(path)}.#{Process.pid}.tmp")
+        File.binwrite(tmp, module_.serialize)
+        File.rename(tmp, path)
+      rescue Wasmtime::Error, SystemCallError
+        File.delete(tmp) if defined?(tmp) && tmp && File.exist?(tmp)
+        nil
+      end
+
+      # Nil when no usable cache directory exists (cache disabled).
+      def cache_path(engine, image_path)
+        dir = modules_dir
+        return nil unless dir
+
+        File.join(dir, "#{cache_key(engine, image_path)}.cwasm")
+      end
+
+      def modules_dir
+        base = ENV[CACHE_DIR_ENV_VAR] || default_base_dir
+        return nil unless base
+
+        File.expand_path("modules", base)
+      end
+
+      private
+
+      def default_base_dir
+        home = ENV["HOME"]
+        home && File.join(home, ".cache", "security_box")
+      end
+
+      # Digest cost scales with the image size (~0.7s for the 110MB ruby.wasm
+      # image); memoized per file identity so it is paid once per process
+      # (and recomputed only if the file changes on disk).
+      def cache_key(engine, image_path)
+        @keys ||= {}
+        stat = File.stat(image_path)
+        key = @keys[[image_path, stat.size, stat.mtime]]
+        return key if key
+
+        image_digest = Digest::SHA256.file(image_path).hexdigest
+        @keys[[image_path, stat.size, stat.mtime]] =
+          Digest::SHA256.hexdigest("#{image_digest}:#{engine.precompile_compatibility_key}")
+      end
+    end
+  end
+end

data/lib/security_box/registry.rb

@@ -0,0 +1,65 @@
+# 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)
+          @profiles[key] = Configuration.build(**base_of(from), **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/runtime.rb

@@ -2,13 +2,16 @@
 
 require "wasmtime"
 
+require_relative "module_cache"
+
 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 compilation is slow (~15s the first time per process); the compiled
+  # artifact is persisted via ModuleCache so later processes deserialize it
+  # from disk instead of recompiling.
   module Runtime
     MUTEX = Mutex.new
 
@@ -24,8 +27,10 @@ module SecurityBox
 
       def module_for(engine, image_path)
         MUTEX.synchronize do
-          @modules[[engine.object_id, image_path]] ||=
-            Wasmtime::Module.from_file(engine, image_path)
+          @modules[[engine.object_id, image_path]] ||= begin
+            ModuleCache.load_module(engine, image_path) ||
+              ModuleCache.compile_and_store(engine, image_path)
+          end
         end
       end
 

data/lib/security_box/sandbox.rb

@@ -10,12 +10,17 @@ module SecurityBox
   # 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
+  #   3. a per-eval random token is passed via ENV (SB_TOKEN); the guest
+  #      prelude captures it and scrubs ENV before user code runs
+  #   4. guest (/src/main.rb) evaluates the code and writes /work/out.json,
+  #      embedding the token (stdout sentinel fallback does the same)
+  #   5. host reads the envelope, validates schema + token (untrusted results
+  #      become a sandbox failure) and returns a Result
   class Sandbox
     GUEST_ENTRYPOINT = "/src/main.rb"
     RESULT_FILE = "out.json"
     CODE_FILE = "code.rb"
+    TOKEN_ENV_VAR = "SB_TOKEN"
 
     def initialize(configuration = Configuration.build)
       @config = configuration
@@ -32,6 +37,7 @@ module SecurityBox
       config = overrides.empty? ? @config : @config.with(**overrides)
       stdout = +""
       stderr = +""
+      token = SecureRandom.hex(16)
       t0 = monotonic_ms
 
       Dir.mktmpdir("security_box") do |workdir|
@@ -42,7 +48,7 @@ module SecurityBox
 
         store = Wasmtime::Store.new(
           @engine,
-          wasi_p1_config: build_wasi(workdir, stdout, stderr, config),
+          wasi_p1_config: build_wasi(workdir, stdout, stderr, config, token),
           limits: { memory_size: config.memory_size }
         )
         begin
@@ -50,8 +56,13 @@ module SecurityBox
           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)
+          fuel_used = config.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
@@ -62,13 +73,13 @@ module SecurityBox
 
     private
 
-    def build_wasi(workdir, stdout, stderr, config)
+    def build_wasi(workdir, stdout, stderr, config, token)
       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_env(config.env.merge(TOKEN_ENV_VAR => token))
         .set_mapped_directory(workdir, "/work", :read_write)
     end
 
@@ -110,12 +121,16 @@ module SecurityBox
       end
     end
 
-    def read_envelope(workdir)
-      path = File.join(workdir, RESULT_FILE)
-      return nil unless File.exist?(path)
+    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
 
-      JSON.parse(File.read(path))
-    rescue JSON::ParserError
+    def read_result_file(workdir)
+      File.read(File.join(workdir, RESULT_FILE))
+    rescue SystemCallError
       nil
     end
 
@@ -135,6 +150,15 @@ module SecurityBox
           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,
@@ -144,6 +168,10 @@ module SecurityBox
       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

data/lib/security_box/version.rb

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

data/lib/security_box.rb

@@ -3,8 +3,11 @@
 require_relative "security_box/version"
 require_relative "security_box/errors"
 require_relative "security_box/configuration"
+require_relative "security_box/registry"
 require_relative "security_box/result"
+require_relative "security_box/module_cache"
 require_relative "security_box/runtime"
+require_relative "security_box/envelope"
 require_relative "security_box/sandbox"
 
 module SecurityBox
@@ -15,6 +18,33 @@ module SecurityBox
     Sandbox.new.eval(code, **overrides)
   end
 
+  # Registers a named, reusable profile (see Registry).
+  #   SecurityBox.register(:lean, from: :default) { |c| c.fuel 5_000_000 }
+  def self.register(name, from: nil, &block)
+    Registry.register(name, from: from, &block)
+  end
+
+  # Builds a Sandbox from a registered profile, a Configuration, or the
+  # defaults:
+  #   SecurityBox.spawn(:lean)                  # named profile
+  #   SecurityBox.spawn(:lean, fuel: 1_000)     # profile + per-call overrides
+  #   SecurityBox.spawn(my_config)              # explicit configuration
+  #   SecurityBox.spawn                         # default configuration
+  def self.spawn(profile = nil, **overrides)
+    config = case profile
+             when nil then Configuration.build(**overrides)
+             when Symbol, String
+               resolved = Registry.resolve(profile)
+               overrides.empty? ? resolved : resolved.with(**overrides)
+             when Configuration
+               overrides.empty? ? profile : profile.with(**overrides)
+             else
+               raise ArgumentError,
+                     "profile must be a registered name or a Configuration, got #{profile.class}"
+             end
+    Sandbox.new(config)
+  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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: security_box
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Marcelo Junior
@@ -39,8 +39,12 @@ files:
 - lib/security_box.rb
 - lib/security_box/assets/security_box.wasm
 - lib/security_box/configuration.rb
+- lib/security_box/envelope.rb
 - lib/security_box/errors.rb
 - lib/security_box/guest/main.rb
+- lib/security_box/guest/prelude.rb
+- lib/security_box/module_cache.rb
+- lib/security_box/registry.rb
 - lib/security_box/result.rb
 - lib/security_box/runtime.rb
 - lib/security_box/sandbox.rb