hermetic 0.1.0

data/lib/hermetic/backends/hosted/e2b.rb

@@ -0,0 +1,96 @@
+require "json"
+
+module Hermetic
+  module Backends
+    module Hosted
+      # E2B (e2b.dev) — a vendor microVM per run. trust :vendor, off-host by
+      # construction: a guest escape lands in E2B's cloud, not next to the
+      # app's secrets.
+      #
+      # BEST-EFFORT WIRE SHAPE (spec §6.4): BASE_URL, the endpoint path, and
+      # the request/response bodies below are a design-time approximation of
+      # E2B's create-and-run API. Pin them against the live API via the
+      # :hosted smoke layer (spec §5) before first real use.
+      class E2B < Base
+        BASE_URL = "https://api.e2b.dev"
+
+        def initialize(api_key:, template: "base", base_url: BASE_URL, transport: nil, **opts)
+          raise ConfigError, "api_key is required for Hosted::E2B" if api_key.to_s.strip.empty?
+
+          super(trust: :vendor, **opts)
+          @api_key = api_key
+          @template = template
+          @base_url = base_url.to_s.chomp("/")
+          @transport = transport || Transport::Http.new
+        end
+
+        def backend_name = :e2b
+
+        # Pure: one run as an HTTP request spec — unit-testable with zero
+        # infra. Box credentials are already resolved into clean_env (:env
+        # mode), so the model-visible command never carries a raw token.
+        def create_and_run_spec(request)
+          {
+            method: :post,
+            url: "#{@base_url}/v1/sandboxes/exec",
+            headers: {
+              "X-API-Key" => @api_key,
+              "Content-Type" => "application/json",
+              "Idempotency-Key" => request.idempotency_key
+            },
+            body: JSON.generate(
+              template: @template,
+              command: request.exec_string,
+              stdin: request.stdin,
+              files: request.files,
+              env: request.clean_env,
+              network: { egress: request.network.egress },
+              timeout: request.timeout,
+              limits: request.limits.to_h
+            )
+          }
+        end
+
+        private
+
+        # In-doubt discipline (spec §7 risk 2, v1: no automatic retry):
+        # wire failure / 5xx -> the run may have executed vendor-side, raise
+        # in_doubt; 4xx -> the vendor refused before starting, plain failure.
+        # A guest failure is never an exception — it's a non-zero Result.
+        def execute(request)
+          response = begin
+            @transport.call(create_and_run_spec(request))
+          rescue TransportError => e
+            raise TransportError.new(
+              "E2B unreachable or response lost (in doubt, idempotency_key=#{request.idempotency_key}): #{e.message}",
+              in_doubt: true
+            )
+          end
+
+          unless response.success?
+            raise TransportError.new(
+              "E2B returned HTTP #{response.status} (idempotency_key=#{request.idempotency_key}): " \
+              "#{response.body.to_s[0, 200]}",
+              in_doubt: response.status >= 500
+            )
+          end
+
+          to_tuple(response.json)
+        rescue JSON::ParserError
+          raise TransportError.new(
+            "E2B returned unparseable JSON (in doubt, idempotency_key=#{request.idempotency_key})",
+            in_doubt: true
+          )
+        end
+
+        # Vendor payload -> the execute tuple Base assembles into a Result.
+        # Expected shape (best-effort, pinned with the endpoint):
+        #   { "stdout": "", "stderr": "", "exitCode": 0, "timedOut": false }
+        def to_tuple(payload)
+          [ payload["stdout"].to_s, payload["stderr"].to_s,
+            payload["exitCode"].to_i, !!payload["timedOut"] ]
+        end
+      end
+    end
+  end
+end

data/lib/hermetic/backends/hosted.rb

@@ -0,0 +1,27 @@
+require "hermetic/backends/hosted/e2b"
+
+module Hermetic
+  module Backends
+    # Factory for vendor-cloud sandboxes — off-host by construction (spec §3):
+    # the guest lives in the vendor's cloud and this process holds only an
+    # API key. E2B ships in v1; Daytona/Modal are named but deferred so the
+    # constructor fails with the roadmap, not a NameError.
+    module Hosted
+      PROVIDERS = { e2b: :E2B }.freeze
+      DEFERRED = %i[daytona modal].freeze
+
+      def self.build(provider, **opts)
+        key = provider.to_s.downcase.to_sym
+        if DEFERRED.include?(key)
+          raise ConfigError, "hosted provider #{key.inspect} is deferred (v1.1) — :e2b is the v1 provider"
+        end
+
+        const = PROVIDERS.fetch(key) do
+          raise ConfigError,
+                "unknown hosted provider #{provider.inspect} (known: #{PROVIDERS.keys.inspect}, deferred: #{DEFERRED.inspect})"
+        end
+        const_get(const).new(**opts)
+      end
+    end
+  end
+end

data/lib/hermetic/backends/null.rb

@@ -0,0 +1,19 @@
+module Hermetic
+  module Backends
+    # Disabled: code execution is off. Fails loud on run — a silent no-op
+    # would look like a sandbox while providing none.
+    class Null < Base
+      def initialize
+        super(trust: :none)
+      end
+
+      def enabled? = false
+
+      def run(*, **)
+        raise DisabledError,
+              "code execution is disabled (Null backend) — construct a real one: " \
+              "Hermetic.hosted / .gvisor / .firecracker / .docker"
+      end
+    end
+  end
+end

data/lib/hermetic/credentials.rb

@@ -0,0 +1,41 @@
+module Hermetic
+  # Named secrets injected into the guest at exec time — the model-visible
+  # command never contains a raw token. Values are callables resolved lazily
+  # per run, so short-lived tokens are minted fresh and never cached on the
+  # box. :env mode ships in v1; :proxy (guest gets no token at all) is v1.1.
+  class Credentials
+    MODES = %i[env proxy].freeze
+
+    attr_reader :mode
+
+    def self.build(value, mode: :env)
+      case value
+      when nil then new({}, mode: mode)
+      when Credentials then value
+      when Hash then new(value, mode: mode)
+      else raise ConfigError, "credentials must be a Hash of NAME => value-or-callable, got #{value.inspect}"
+      end
+    end
+
+    def initialize(map = {}, mode: :env)
+      raise ConfigError, "unknown credential_mode #{mode.inspect} (known: #{MODES.inspect})" unless MODES.include?(mode)
+      raise ConfigError, "credential_mode :proxy is deferred (v1.1) — use :env" if mode == :proxy
+
+      @map = map.to_h.transform_keys(&:to_s).freeze
+      @mode = mode
+    end
+
+    def names = @map.keys
+
+    def empty? = @map.empty?
+
+    # Fresh values for one run. Callables are invoked now, never memoized.
+    def resolve
+      @map.transform_values { |v| (v.respond_to?(:call) ? v.call : v).to_s }
+    end
+
+    # Values (and the closures that mint them) never appear in logs.
+    def inspect = "#<Hermetic::Credentials mode=#{@mode} names=#{names.inspect} [redacted]>"
+    alias to_s inspect
+  end
+end

data/lib/hermetic/errors.rb

@@ -0,0 +1,34 @@
+module Hermetic
+  class Error < StandardError; end
+
+  # A disabled (Null) sandbox was asked to run — fail loud, never no-op.
+  class DisabledError < Error; end
+
+  # Bad construction or a malformed run request: path traversal in files:,
+  # a non-integer timeout, an unknown credential mode, etc.
+  class ConfigError < Error; end
+
+  # The wire failed (socket error, missing binary) — distinct from the guest
+  # failing, which is a non-zero Result, not an exception. `in_doubt` is true
+  # when the run may have executed before the wire failed — the remote/hosted
+  # in-doubt window (spec §7 risk 2). Never blindly retry an in-doubt run:
+  # replay the same idempotency key against a deduping executor, or escalate.
+  class TransportError < Error
+    attr_reader :in_doubt
+
+    def initialize(message = nil, in_doubt: false)
+      super(message)
+      @in_doubt = in_doubt
+    end
+
+    def in_doubt? = !!@in_doubt
+  end
+
+  # Host-side wall-clock enforcement failed in a way that can't be expressed
+  # as the normal exit-124 Result (e.g. the reaper couldn't kill the guest).
+  class TimeoutError < Error; end
+
+  # Workspace materialization failed — files: couldn't be placed in the
+  # guest's workdir.
+  class WorkspaceError < Error; end
+end

data/lib/hermetic/limits.rb

@@ -0,0 +1,44 @@
+module Hermetic
+  # Resource ceilings for a run. Set on the box at construction, overridable
+  # per run via `limits:` (merged over the box defaults).
+  class Limits
+    DEFAULTS = { memory: "512m", cpus: "1", pids: 256 }.freeze
+
+    attr_reader :memory, :cpus, :pids
+
+    def self.build(value)
+      case value
+      when nil then new
+      when Limits then value
+      when Hash then new.merge(value)
+      else raise ConfigError, "limits must be a Hash or Hermetic::Limits, got #{value.inspect}"
+      end
+    end
+
+    def initialize(memory: DEFAULTS[:memory], cpus: DEFAULTS[:cpus], pids: DEFAULTS[:pids])
+      @memory = memory.to_s
+      @cpus = cpus.to_s
+      @pids = Integer(pids)
+      raise ConfigError, "pids must be positive, got #{pids.inspect}" unless @pids.positive?
+    rescue ArgumentError, TypeError
+      raise ConfigError, "pids must be an integer, got #{pids.inspect}"
+    end
+
+    def merge(overrides)
+      return self if overrides.nil?
+
+      overrides = overrides.to_h.transform_keys(&:to_sym)
+      unknown = overrides.keys - DEFAULTS.keys
+      raise ConfigError, "unknown limit(s) #{unknown.inspect} — known: #{DEFAULTS.keys.inspect}" unless unknown.empty?
+
+      self.class.new(**to_h.merge(overrides))
+    end
+
+    def to_h = { memory: memory, cpus: cpus, pids: pids }
+
+    def ==(other) = other.is_a?(Limits) && other.to_h == to_h
+    alias eql? ==
+
+    def hash = to_h.hash
+  end
+end

data/lib/hermetic/network_policy.rb

@@ -0,0 +1,52 @@
+module Hermetic
+  # Guest networking is default-deny (:none). Opting in means naming an
+  # egress allowlist — "host:port" entries — never "open". No inbound ever.
+  class NetworkPolicy
+    EGRESS_ENTRY = /\A[A-Za-z0-9*._-]+:\d{1,5}\z/
+
+    attr_reader :egress
+
+    def self.from(value)
+      case value
+      when NetworkPolicy then value
+      when :none, nil then NONE
+      else raise ConfigError, "network must be :none or a Hermetic::NetworkPolicy, got #{value.inspect}"
+      end
+    end
+
+    def initialize(egress: [])
+      @egress = Array(egress).map(&:to_s).freeze
+      @egress.each do |entry|
+        raise ConfigError, %(egress entries are "host:port", got #{entry.inspect}) unless entry.match?(EGRESS_ENTRY)
+      end
+    end
+
+    def none? = egress.empty?
+
+    def open? = !none?
+
+    # The docker/gvisor `--network` value. Default-deny stays "none"; an
+    # egress allowlist needs a bridge — enforcing the allowlist itself is the
+    # backend's job, this flag only stops it being silently unreachable.
+    def docker_flag = none? ? "none" : "bridge"
+
+    # The firecracker "network-interfaces" machine config. Default-deny
+    # attaches no NIC at all — the guest has no device to speak through.
+    # An egress allowlist attaches one tap iface; enforcing the allowlist on
+    # that tap (nftables) is the orchestration layer's job — same split of
+    # responsibility as docker_flag.
+    def firecracker_ifaces(iface_id: "eth0", host_dev_name: "tap0", guest_mac: "06:00:AC:10:00:02")
+      return [] if none?
+
+      [ { "iface_id" => iface_id, "host_dev_name" => host_dev_name, "guest_mac" => guest_mac } ]
+    end
+
+    def to_s = none? ? "none" : "egress:#{egress.join(',')}"
+
+    def inspect = "#<Hermetic::NetworkPolicy #{self}>"
+
+    def ==(other) = other.is_a?(NetworkPolicy) && other.egress == egress
+
+    NONE = new.freeze
+  end
+end

data/lib/hermetic/remote.rb

@@ -0,0 +1,96 @@
+require "json"
+
+module Hermetic
+  # Off-host executor CLIENT — the self-host trust boundary (spec §3). Wraps a
+  # local backend *kind* (:gvisor/:firecracker/:docker) and ships each run as
+  # JSON to a dedicated sandbox host that holds no database creds, no
+  # RAILS_MASTER_KEY, no ledger. This process keeps only the URL + token.
+  # EXECUTOR.md is the server side of this contract.
+  class Remote < Backends::Base
+    BACKENDS = %i[docker gvisor firecracker].freeze
+
+    attr_reader :executor, :backend
+
+    def initialize(executor:, token:, backend: :gvisor, backend_options: {}, transport: nil, **opts)
+      raise ConfigError, "executor URL is required" if executor.to_s.strip.empty?
+      raise ConfigError, "token is required — the executor only accepts authenticated runs" if token.to_s.strip.empty?
+      unless BACKENDS.include?(backend)
+        raise ConfigError, "unknown executor backend #{backend.inspect} (known: #{BACKENDS.inspect})"
+      end
+
+      super(trust: :remote, **opts)
+      @executor = executor.to_s.chomp("/")
+      @token = token
+      @backend = backend
+      @backend_options = backend_options.to_h
+      @transport = transport || Transport::Http.new
+    end
+
+    # Result#backend reports the isolation tech the executor runs; trust
+    # :remote carries the boundary — the two axes stay unconflated (spec §3).
+    def backend_name = @backend
+
+    # Pure: one run as an HTTP request spec. Idempotency-Key is deterministic
+    # for the same logical run — the executor-side dedup handle that makes a
+    # retry of an in-doubt run safe (spec §7 risk 2, EXECUTOR.md).
+    def run_spec(request)
+      {
+        method: :post,
+        url: "#{@executor}/run",
+        headers: {
+          "Authorization" => "Bearer #{@token}",
+          "Content-Type" => "application/json",
+          "Idempotency-Key" => request.idempotency_key
+        },
+        body: JSON.generate(
+          v: 1,
+          backend: @backend,
+          backend_options: @backend_options,
+          argv: request.exec_argv,
+          stdin: request.stdin,
+          files: request.files,
+          env: request.clean_env,
+          network: { egress: request.network.egress },
+          timeout: request.timeout,
+          limits: request.limits.to_h
+        )
+      }
+    end
+
+    private
+
+    # In-doubt discipline (v1: no automatic retry):
+    #   wire failure -> the POST may have executed guest-side: in_doubt
+    #   HTTP 4xx     -> the executor refused before starting the run: plain failure
+    #   HTTP 5xx     -> the executor broke mid-flight: in_doubt
+    # A caller that retries replays the SAME logical run; the stable
+    # idempotency key lets a deduping executor collapse it.
+    def execute(request)
+      response = begin
+        @transport.call(run_spec(request))
+      rescue TransportError => e
+        raise TransportError.new(
+          "executor unreachable or response lost (in doubt, idempotency_key=#{request.idempotency_key}): #{e.message}",
+          in_doubt: true
+        )
+      end
+
+      unless response.success?
+        raise TransportError.new(
+          "executor returned HTTP #{response.status} (idempotency_key=#{request.idempotency_key}): " \
+          "#{response.body.to_s[0, 200]}",
+          in_doubt: response.status >= 500
+        )
+      end
+
+      payload = response.json
+      [ payload["stdout"].to_s, payload["stderr"].to_s,
+        payload["exit_status"].to_i, !!payload["timed_out"] ]
+    rescue JSON::ParserError
+      raise TransportError.new(
+        "executor returned unparseable JSON (in doubt, idempotency_key=#{request.idempotency_key})",
+        in_doubt: true
+      )
+    end
+  end
+end

data/lib/hermetic/request.rb

@@ -0,0 +1,127 @@
+require "digest"
+require "json"
+require "shellwords"
+
+module Hermetic
+  # The normalized form of one `run` call. Backends never see raw kwargs —
+  # they see a Request whose invariants already hold: shell-vs-argv resolved,
+  # workdir-relative files only, clean default-deny env, integer host-enforced
+  # timeout, limits merged over box defaults.
+  class Request
+    SHELL = [ "/bin/sh", "-c" ].freeze
+
+    attr_reader :files, :stdin, :network, :timeout, :limits, :env_allowlist
+
+    def self.build(command, **kwargs) = new(command, **kwargs)
+
+    def initialize(command, files: {}, stdin: nil, env: {}, network: :none,
+                   timeout: 30, limits: nil, default_limits: Limits.new,
+                   credentials: nil, env_allowlist: [], host_env: ENV)
+      @command = normalize_command(command)
+      @files = normalize_files(files)
+      @stdin = stdin&.to_s
+      @explicit_env = normalize_env(env)
+      @network = NetworkPolicy.from(network)
+      @timeout = normalize_timeout(timeout)
+      @limits = default_limits.merge(limits)
+      @credentials = Credentials.build(credentials)
+      @env_allowlist = Array(env_allowlist).map(&:to_s).freeze
+      @host_env = host_env
+    end
+
+    def shell? = @command.is_a?(String)
+
+    # Full argv to exec. A String command runs under /bin/sh -c (matches
+    # Silas); an Array execs directly — no shell, no injection surface.
+    def exec_argv = shell? ? SHELL + [ @command ] : @command
+
+    # The command as a single shell string, for hosted APIs that take one.
+    def exec_string = shell? ? @command : Shellwords.join(@command)
+
+    # The guest environment: host env is default-deny. Precedence (low→high):
+    # allowlisted host vars < resolved credentials < explicit env:.
+    # Credentials resolve lazily, per call — never cached on the request.
+    def clean_env
+      allowlisted = @env_allowlist.each_with_object({}) do |name, acc|
+        acc[name] = @host_env[name].to_s if @host_env[name]
+      end
+      allowlisted.merge(@credentials.resolve).merge(@explicit_env)
+    end
+
+    def credential_names = @credentials.names
+
+    # Deterministic across retries of the same logical run — the executor-side
+    # dedup key for the remote in-doubt window (spec §7 risk 2). Credential and
+    # host-env VALUES are excluded: short-lived tokens must not change the key
+    # (and must never be digested at all).
+    def idempotency_key
+      @idempotency_key ||= Digest::SHA256.hexdigest(JSON.generate(canonical))[0, 32]
+    end
+
+    # Values are redacted; keys/command are the model-visible surface anyway.
+    def inspect
+      "#<Hermetic::Request cmd=#{exec_argv.inspect} files=#{files.keys.inspect} " \
+        "env=#{(@explicit_env.keys + credential_names).sort.inspect} " \
+        "network=#{@network} timeout=#{@timeout} [values redacted]>"
+    end
+    alias to_s inspect
+
+    private
+
+    def canonical
+      {
+        v: 1,
+        shell: shell?,
+        argv: exec_argv,
+        stdin: @stdin,
+        files: @files.sort.to_h,
+        env: @explicit_env.sort.to_h,
+        env_allowlist: @env_allowlist.sort,
+        credential_names: credential_names.sort,
+        egress: @network.egress,
+        timeout: @timeout,
+        limits: @limits.to_h
+      }
+    end
+
+    def normalize_command(command)
+      case command
+      when String
+        raise ConfigError, "command must not be empty" if command.strip.empty?
+
+        command
+      when Array
+        raise ConfigError, "argv must not be empty" if command.empty?
+        raise ConfigError, "argv must be an Array of Strings, got #{command.inspect}" unless command.all?(String)
+
+        command.dup.freeze
+      else
+        raise ConfigError, "command must be a String (/bin/sh -c) or an Array argv, got #{command.inspect}"
+      end
+    end
+
+    def normalize_files(files)
+      files.to_h.each_with_object({}) do |(path, contents), acc|
+        path = path.to_s
+        if path.empty? || path.start_with?("/") || path.split("/").include?("..")
+          raise ConfigError, "unsafe file path #{path.inspect} — workdir-relative only, no traversal"
+        end
+
+        acc[path] = contents.to_s
+      end.freeze
+    end
+
+    def normalize_env(env)
+      env.to_h.map { |k, v| [ k.to_s, v.to_s ] }.to_h.freeze
+    end
+
+    def normalize_timeout(timeout)
+      seconds = Integer(timeout)
+      raise ConfigError, "timeout must be positive, got #{timeout.inspect}" unless seconds.positive?
+
+      seconds
+    rescue ArgumentError, TypeError
+      raise ConfigError, "timeout must be an integer number of seconds, got #{timeout.inspect}"
+    end
+  end
+end

data/lib/hermetic/result.rb

@@ -0,0 +1,15 @@
+module Hermetic
+  # Superset of Silas::Sandbox::Result — the first three members are the ones
+  # Silas's run_code tool reads, so a Hermetic box drops into
+  # `config.sandbox = <object>` with zero Silas changes. trust/backend make
+  # the isolation posture legible on every result (see spec §3).
+  Result = Struct.new(
+    :stdout, :stderr, :exit_status,
+    :timed_out, :duration_ms, :backend, :trust,
+    keyword_init: true
+  ) do
+    def success? = exit_status.to_i.zero? && !timed_out
+
+    def timed_out? = !!timed_out
+  end
+end

data/lib/hermetic/silas.rb

@@ -0,0 +1,23 @@
+require "hermetic"
+
+module Hermetic
+  # OPTIONAL Silas shim — `require "hermetic/silas"` from an app that runs
+  # Silas (spec §4). A sandbox run is a non-replayable external effect, so it
+  # must never happen inside a ledger transaction: a rollback after the guest
+  # ran would replay it on retry. Silas's own Docker adapter carries this
+  # guard; prepending here gives every Hermetic backend the same fail-loud
+  # posture. Without Silas loaded the check no-ops, so requiring this file is
+  # always safe.
+  module SilasLedgerGuard
+    def run(...)
+      if defined?(::Silas::Ledger) && ::Silas::Ledger.in_transaction?
+        raise Error, "sandbox exec inside a ledger transaction — sandbox-backed tools " \
+                     "must be at_most_once!, never transactional!"
+      end
+
+      super
+    end
+  end
+
+  Backends::Base.prepend(SilasLedgerGuard)
+end

data/lib/hermetic/transport/http.rb

@@ -0,0 +1,52 @@
+require "net/http"
+require "json"
+require "uri"
+
+module Hermetic
+  module Transport
+    # Sends a backend-built request spec ({ method:, url:, headers:, body: })
+    # over net/http. The connection factory is injectable so unit tests never
+    # open a socket — fakes return canned responses or raise socket errors.
+    class Http
+      REQUESTS = { "GET" => Net::HTTP::Get, "POST" => Net::HTTP::Post }.freeze
+
+      Response = Struct.new(:status, :body, keyword_init: true) do
+        def json = JSON.parse(body)
+
+        def success? = (200..299).cover?(status)
+      end
+
+      def initialize(open_timeout: 5, read_timeout: 65, connector: nil)
+        @open_timeout = open_timeout
+        @read_timeout = read_timeout
+        @connector = connector || method(:default_connector)
+      end
+
+      def call(spec)
+        method = spec.fetch(:method) { raise ConfigError, "http spec needs :method" }.to_s.upcase
+        uri = URI(spec.fetch(:url) { raise ConfigError, "http spec needs :url" })
+        klass = REQUESTS.fetch(method) { raise ConfigError, "unsupported http method #{method.inspect}" }
+
+        request = klass.new(uri)
+        (spec[:headers] || {}).each { |name, value| request[name.to_s] = value.to_s }
+        request.body = spec[:body] if spec[:body]
+
+        raw = @connector.call(uri).request(request)
+        Response.new(status: raw.code.to_i, body: raw.body.to_s)
+      rescue SocketError, SystemCallError, IOError, EOFError,
+             Net::OpenTimeout, Net::ReadTimeout, OpenSSL::SSL::SSLError => e
+        raise TransportError, "#{method} #{uri}: #{e.class}: #{e.message}"
+      end
+
+      private
+
+      def default_connector(uri)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = @open_timeout
+        http.read_timeout = @read_timeout
+        http
+      end
+    end
+  end
+end