enclave 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 11381633c48be0ee24ef5bdfa366b7e58d325bf565fd9e697ab315c678caeffd
+  data.tar.gz: 37486e208c3ddae94163d1f9ec44b5f3fbde8a52ff873451ca2e801e36764c0b
+SHA512:
+  metadata.gz: 8151f34e9b99b5ba5a7722ecc5199b7d6ee0965e59384f016ee10d6de73196b2170e9ba66c676a028dd2e2387c70e7ddce81d4bddf1f9c319dc75ce9acffd783
+  data.tar.gz: fb4163ec693b56c6d122a894974bf3f16c3ddfa95607dc30905d34e0fa42aa6562875ef7359fe5adb93a1b10f583a50f81e9cb5c06ee3a0f61f1cc311a2715b9

data/README.md

@@ -0,0 +1,182 @@
+# Enclave
+
+## Why this exists
+
+You're adding an AI agent to your Rails app. The agent needs to look up orders, update tickets, maybe change a customer's email. The standard approach is tool calling — you define discrete functions, the LLM picks which one to call, you execute it.
+
+That works. But it's limiting. If a customer asks "what's my total spend on shipped orders this year?", you either need a `total_spend_by_status_and_date_range` tool (which you didn't build) or the agent has to make multiple round-trips: fetch all orders, then… well, it can't do math. You need another tool for that. The tool list grows, each one is an LLM round-trip, and you're forever playing catch-up with the questions your users actually ask.
+
+The alternative is to let the agent write code. One `eval` tool replaces dozens of specialized tools. The agent fetches orders and filters them in a single call:
+
+```ruby
+orders().select { |o| o["status"] == "shipped" }.sum { |o| o["total"] }
+```
+
+The problem is obvious: `eval` in your Ruby process is catastrophic. The agent can do anything your app can do — `User.destroy_all`, `File.read("/etc/passwd")`, `ENV["SECRET_KEY_BASE"]`, `system("curl attacker.com")`. One prompt injection in a ticket body and you're done.
+
+Enclave gives you `eval` without the blast radius. It embeds a separate MRuby VM — an isolated Ruby interpreter with no file system, no network, no access to your CRuby runtime. You expose specific functions into it. The agent writes code against those functions and nothing else.
+
+```ruby
+class CustomerServiceTools
+  def initialize(user)
+    @user = user
+  end
+
+  def user_info
+    { name: @user.name, email: @user.email, plan: @user.plan,
+      created_at: @user.created_at.to_s }
+  end
+
+  def change_plan(new_plan)
+    @user.update!(plan: new_plan)
+    { success: true, plan: @user.reload.plan }
+  end
+
+  def recent_tickets
+    @user.support_tickets.order(created_at: :desc).limit(10).map do |t|
+      { id: t.id, subject: t.subject, status: t.status }
+    end
+  end
+end
+
+user = User.find(params[:user_id])
+enclave = Enclave.new(tools: CustomerServiceTools.new(user))
+```
+
+Inside the enclave, the agent sees these functions and nothing else:
+
+```ruby
+user_info()
+#=> {"name" => "Jane Doe", "email" => "jane@example.com", "plan" => "basic", ...}
+
+change_plan("premium")
+#=> {"success" => true, "plan" => "premium"}
+
+open_tickets = recent_tickets().select { |t| t["status"] == "open" }
+open_tickets.length
+#=> 3
+```
+
+There's no `User` class in the enclave. No ActiveRecord. No file system. No network. The agent can only call the methods you gave it, scoped to the user you passed in.
+
+### Do you actually need this?
+
+If your agent only needs to pick from a fixed menu of actions — "cancel order", "send refund", "update email" — standard tool calling is fine. Each tool is a function the LLM selects; you control the surface area; there's no code execution to worry about.
+
+Enclave becomes worth it when:
+
+- **The agent needs to reason over data.** Filter, sort, aggregate, compare. Instead of building a tool for every possible query, you expose the raw data and let the agent write the logic.
+- **You want fewer round-trips.** One eval can fetch data, process it, and return a result. That's one LLM turn instead of three or four.
+- **You can't predict the questions.** Customer service, data exploration, internal dashboards — anywhere users ask ad-hoc questions about their own data.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "enclave"
+```
+
+The gem builds MRuby from source on first compile, so the initial `bundle install` takes a moment.
+
+## Quick start
+
+There's a complete working example in [`examples/rails.rb`](examples/rails.rb) — a single-file app with SQLite, ActiveRecord, and an interactive chat loop. Run it with:
+
+```bash
+ruby examples/rails.rb
+```
+
+## Defining tools
+
+Write a class. Initialize it with whatever data the agent should have access to. Its public methods become the functions the agent can call.
+
+```ruby
+class OrderTools
+  def initialize(order)
+    @order = order
+  end
+
+  def details
+    { id: @order.id, total: @order.total.to_f, status: @order.status,
+      items: @order.line_items.map { |li| { name: li.name, qty: li.qty } } }
+  end
+
+  def apply_discount(percent)
+    raise "discount must be 1-50%" unless (1..50).cover?(percent)
+    @order.apply_discount!(percent)
+    { success: true, new_total: @order.reload.total.to_f }
+  end
+
+  def cancel
+    @order.cancel!
+    { success: true }
+  end
+end
+
+enclave = Enclave.new(tools: OrderTools.new(order))
+```
+
+### Multiple tool objects
+
+```ruby
+enclave = Enclave.new(tools: AccountTools.new(user))
+enclave.expose(BillingTools.new(user.billing_account))
+enclave.expose(NotificationTools.new(user))
+```
+
+All methods from all exposed objects are available as functions in the enclave.
+
+### Allowed types
+
+Values crossing the boundary must be one of:
+
+| Type | Notes |
+|------|-------|
+| `nil`, `true`, `false` | |
+| `Integer`, `Float` | |
+| `String` | |
+| `Symbol` | Converted to `String` automatically |
+| `Array` | Elements must be allowed types |
+| `Hash` | Keys and values must be allowed types |
+
+If a method returns something else, the agent gets a clear error:
+
+```
+TypeError: unsupported type for sandbox: User
+```
+
+This means you need to serialize your data into hashes — which is a feature, not a bug. It forces you to be explicit about what the agent can see.
+
+### Error handling
+
+Exceptions in your tool methods are caught and returned as errors. The enclave keeps running:
+
+```ruby
+# Inside the enclave:
+apply_discount(99)   #=> RuntimeError: discount must be 1-50%
+details()            # still works
+```
+
+## Safety
+
+If you run agent-generated code with `eval` in CRuby, the agent can do anything your app can do. Here's what happens when you try those same things inside the enclave:
+
+```ruby
+enclave.eval('File.read("/etc/passwd")')
+#=> NameError: uninitialized constant File
+
+enclave.eval('ENV["SECRET_KEY_BASE"]')
+#=> NameError: uninitialized constant ENV
+
+enclave.eval('`curl http://attacker.com`')
+#=> NotImplementedError: backquotes not implemented
+```
+
+These aren't runtime permission checks — the classes and methods simply don't exist. MRuby is a separate interpreter compiled without IO, network, or process modules. There's nothing to bypass.
+
+Each enclave instance is fully isolated from other instances.
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,30 @@
+require "bundler/gem_tasks"
+require "rake/extensiontask"
+require "rspec/core/rake_task"
+
+Rake::ExtensionTask.new("enclave") do |ext|
+  ext.lib_dir = "lib/enclave"
+end
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: [:compile, :spec]
+
+namespace :mruby do
+  desc "Update mruby to latest and rebuild"
+  task :update do
+    sh "git -C ext/enclave/mruby fetch origin"
+    sh "git -C ext/enclave/mruby checkout origin/master"
+    Rake::Task["mruby:clean"].invoke
+    puts "mruby updated. Run `rake compile` to rebuild."
+  end
+
+  desc "Clean mruby build artifacts"
+  task :clean do
+    rm_rf "ext/enclave/mruby/build"
+    rm_rf "tmp"
+    rm_f "lib/enclave/enclave.bundle"
+    rm_f "lib/enclave/enclave.so"
+    puts "mruby build artifacts cleaned."
+  end
+end

data/ext/enclave/enclave.c

@@ -0,0 +1,390 @@
+/*
+ * enclave.c — Ruby C extension wrapper
+ *
+ * This file ONLY includes ruby.h, never mruby.h.
+ * All mruby interaction goes through the opaque sandbox_core.h API.
+ */
+
+#include <ruby.h>
+#include "sandbox_core.h"
+
+/* ------------------------------------------------------------------ */
+/* sandbox_value_t <-> CRuby VALUE conversion                          */
+/* ------------------------------------------------------------------ */
+
+/* Convert sandbox_value_t -> CRuby VALUE */
+static VALUE
+sandbox_value_to_rb(const sandbox_value_t *val)
+{
+    switch (val->type) {
+    case SANDBOX_VALUE_NIL:
+        return Qnil;
+    case SANDBOX_VALUE_TRUE:
+        return Qtrue;
+    case SANDBOX_VALUE_FALSE:
+        return Qfalse;
+    case SANDBOX_VALUE_INTEGER:
+        return LL2NUM(val->as.i);
+    case SANDBOX_VALUE_FLOAT:
+        return DBL2NUM(val->as.f);
+    case SANDBOX_VALUE_STRING:
+        return rb_str_new(val->as.str.ptr, (long)val->as.str.len);
+    case SANDBOX_VALUE_ARRAY: {
+        VALUE ary = rb_ary_new_capa((long)val->as.arr.len);
+        for (size_t i = 0; i < val->as.arr.len; i++) {
+            rb_ary_push(ary, sandbox_value_to_rb(&val->as.arr.items[i]));
+        }
+        return ary;
+    }
+    case SANDBOX_VALUE_HASH: {
+        VALUE hash = rb_hash_new();
+        for (size_t i = 0; i < val->as.hash.len; i++) {
+            rb_hash_aset(hash,
+                sandbox_value_to_rb(&val->as.hash.keys[i]),
+                sandbox_value_to_rb(&val->as.hash.vals[i]));
+        }
+        return hash;
+    }
+    }
+    return Qnil;
+}
+
+/* Convert CRuby VALUE -> sandbox_value_t. Returns 0 on success, -1 on bad type. */
+static int
+rb_to_sandbox_value(VALUE v, sandbox_value_t *out, char *errbuf, size_t errbuf_size)
+{
+    memset(out, 0, sizeof(*out));
+
+    if (NIL_P(v)) {
+        out->type = SANDBOX_VALUE_NIL;
+        return 0;
+    }
+    if (v == Qtrue) {
+        out->type = SANDBOX_VALUE_TRUE;
+        return 0;
+    }
+    if (v == Qfalse) {
+        out->type = SANDBOX_VALUE_FALSE;
+        return 0;
+    }
+    if (FIXNUM_P(v) || RB_TYPE_P(v, T_BIGNUM)) {
+        out->type = SANDBOX_VALUE_INTEGER;
+        out->as.i = (int64_t)NUM2LL(v);
+        return 0;
+    }
+    if (RB_FLOAT_TYPE_P(v)) {
+        out->type = SANDBOX_VALUE_FLOAT;
+        out->as.f = NUM2DBL(v);
+        return 0;
+    }
+    if (RB_TYPE_P(v, T_STRING)) {
+        out->type = SANDBOX_VALUE_STRING;
+        out->as.str.len = (size_t)RSTRING_LEN(v);
+        out->as.str.ptr = malloc(out->as.str.len + 1);
+        memcpy(out->as.str.ptr, RSTRING_PTR(v), out->as.str.len);
+        out->as.str.ptr[out->as.str.len] = '\0';
+        return 0;
+    }
+    if (RB_TYPE_P(v, T_SYMBOL)) {
+        /* Symbol -> String */
+        VALUE s = rb_sym2str(v);
+        out->type = SANDBOX_VALUE_STRING;
+        out->as.str.len = (size_t)RSTRING_LEN(s);
+        out->as.str.ptr = malloc(out->as.str.len + 1);
+        memcpy(out->as.str.ptr, RSTRING_PTR(s), out->as.str.len);
+        out->as.str.ptr[out->as.str.len] = '\0';
+        return 0;
+    }
+    if (RB_TYPE_P(v, T_ARRAY)) {
+        long alen = RARRAY_LEN(v);
+        out->type = SANDBOX_VALUE_ARRAY;
+        out->as.arr.len = (size_t)alen;
+        out->as.arr.items = calloc((size_t)alen, sizeof(sandbox_value_t));
+        for (long i = 0; i < alen; i++) {
+            if (rb_to_sandbox_value(rb_ary_entry(v, i), &out->as.arr.items[i],
+                                    errbuf, errbuf_size) != 0) {
+                for (long j = 0; j < i; j++) {
+                    sandbox_value_free(&out->as.arr.items[j]);
+                }
+                free(out->as.arr.items);
+                out->as.arr.items = NULL;
+                return -1;
+            }
+        }
+        return 0;
+    }
+    if (RB_TYPE_P(v, T_HASH)) {
+        VALUE keys = rb_funcall(v, rb_intern("keys"), 0);
+        long hlen = RARRAY_LEN(keys);
+        out->type = SANDBOX_VALUE_HASH;
+        out->as.hash.len = (size_t)hlen;
+        out->as.hash.keys = calloc((size_t)hlen, sizeof(sandbox_value_t));
+        out->as.hash.vals = calloc((size_t)hlen, sizeof(sandbox_value_t));
+        for (long i = 0; i < hlen; i++) {
+            VALUE k = rb_ary_entry(keys, i);
+            VALUE val = rb_hash_aref(v, k);
+            if (rb_to_sandbox_value(k, &out->as.hash.keys[i], errbuf, errbuf_size) != 0 ||
+                rb_to_sandbox_value(val, &out->as.hash.vals[i], errbuf, errbuf_size) != 0) {
+                for (long j = 0; j <= i; j++) {
+                    sandbox_value_free(&out->as.hash.keys[j]);
+                    sandbox_value_free(&out->as.hash.vals[j]);
+                }
+                free(out->as.hash.keys);
+                free(out->as.hash.vals);
+                out->as.hash.keys = NULL;
+                out->as.hash.vals = NULL;
+                return -1;
+            }
+        }
+        return 0;
+    }
+
+    /* Unsupported type */
+    VALUE cls = rb_class_name(rb_obj_class(v));
+    snprintf(errbuf, errbuf_size, "TypeError: unsupported type for sandbox: %s",
+             StringValueCStr(cls));
+    return -1;
+}
+
+/* ------------------------------------------------------------------ */
+/* CRuby callback: dispatches tool calls to @tool_context              */
+/* ------------------------------------------------------------------ */
+
+typedef struct {
+    VALUE tool_context;  /* @tool_context object */
+    VALUE method_name;   /* Symbol for the method */
+    int   argc;
+    VALUE *argv;
+} cruby_call_args_t;
+
+static VALUE
+cruby_protected_call(VALUE arg)
+{
+    cruby_call_args_t *ca = (cruby_call_args_t *)arg;
+    return rb_funcallv(ca->tool_context, SYM2ID(ca->method_name), ca->argc, ca->argv);
+}
+
+static sandbox_callback_result_t
+sandbox_cruby_callback(const char *method_name,
+                       const sandbox_value_t *args,
+                       int argc,
+                       void *userdata)
+{
+    sandbox_callback_result_t result;
+    memset(&result, 0, sizeof(result));
+
+    VALUE self = (VALUE)userdata;
+
+    /* Convert sandbox args -> CRuby VALUEs */
+    VALUE *rb_args = NULL;
+    if (argc > 0) {
+        rb_args = ALLOCA_N(VALUE, argc);
+        for (int i = 0; i < argc; i++) {
+            rb_args[i] = sandbox_value_to_rb(&args[i]);
+        }
+    }
+
+    /* Call @tool_context.send(method_name, *args) via rb_protect */
+    VALUE tool_context = rb_ivar_get(self, rb_intern("@tool_context"));
+    VALUE method_sym = ID2SYM(rb_intern(method_name));
+
+    cruby_call_args_t ca;
+    ca.tool_context = tool_context;
+    ca.method_name = method_sym;
+    ca.argc = argc;
+    ca.argv = rb_args;
+
+    int state = 0;
+    VALUE ret = rb_protect(cruby_protected_call, (VALUE)&ca, &state);
+
+    if (state) {
+        /* Exception was raised -- capture message */
+        VALUE exc = rb_errinfo();
+        rb_set_errinfo(Qnil);
+        VALUE exc_str = rb_funcall(exc, rb_intern("inspect"), 0);
+        const char *msg = StringValueCStr(exc_str);
+        result.error = strdup(msg);
+        return result;
+    }
+
+    /* Convert CRuby return -> sandbox_value_t */
+    char errbuf[256];
+    errbuf[0] = '\0';
+    if (rb_to_sandbox_value(ret, &result.value, errbuf, sizeof(errbuf)) != 0) {
+        result.error = strdup(errbuf);
+        return result;
+    }
+
+    return result;
+}
+
+/* ------------------------------------------------------------------ */
+/* TypedData for Enclave                                               */
+/* ------------------------------------------------------------------ */
+
+typedef struct {
+    sandbox_state_t *state;
+    int              closed;
+} rb_enclave_t;
+
+static void
+rb_enclave_free(void *ptr)
+{
+    rb_enclave_t *sb = (rb_enclave_t *)ptr;
+    if (sb) {
+        if (sb->state) {
+            sandbox_state_free(sb->state);
+            sb->state = NULL;
+        }
+        free(sb);
+    }
+}
+
+static size_t
+rb_enclave_memsize(const void *ptr)
+{
+    return sizeof(rb_enclave_t);
+}
+
+static const rb_data_type_t enclave_data_type = {
+    "Enclave",
+    { NULL, rb_enclave_free, rb_enclave_memsize },
+    NULL, NULL,
+    RUBY_TYPED_FREE_IMMEDIATELY
+};
+
+static rb_enclave_t *
+get_enclave(VALUE self)
+{
+    rb_enclave_t *sb;
+    TypedData_Get_Struct(self, rb_enclave_t, &enclave_data_type, sb);
+    if (sb->closed) {
+        rb_raise(rb_eRuntimeError, "enclave is closed");
+    }
+    return sb;
+}
+
+/* ------------------------------------------------------------------ */
+/* Enclave#initialize                                                  */
+/* ------------------------------------------------------------------ */
+
+static VALUE
+enclave_alloc(VALUE klass)
+{
+    rb_enclave_t *sb = calloc(1, sizeof(rb_enclave_t));
+    return TypedData_Wrap_Struct(klass, &enclave_data_type, sb);
+}
+
+static VALUE
+enclave_initialize(VALUE self)
+{
+    rb_enclave_t *sb;
+    TypedData_Get_Struct(self, rb_enclave_t, &enclave_data_type, sb);
+
+    sb->state = sandbox_state_new();
+    if (!sb->state) {
+        rb_raise(rb_eRuntimeError, "failed to initialize mruby enclave");
+    }
+    sb->closed = 0;
+
+    /* Set up the callback so CRuby can handle tool calls */
+    sandbox_state_set_callback(sb->state, sandbox_cruby_callback, (void *)self);
+
+    return self;
+}
+
+/* ------------------------------------------------------------------ */
+/* Enclave#_define_function                                            */
+/* ------------------------------------------------------------------ */
+
+static VALUE
+enclave_define_function(VALUE self, VALUE rb_name)
+{
+    rb_enclave_t *sb = get_enclave(self);
+    const char *name = StringValueCStr(rb_name);
+
+    if (sandbox_state_define_function(sb->state, name) != 0) {
+        rb_raise(rb_eRuntimeError, "too many tool functions (max %d)", 64);
+    }
+
+    return self;
+}
+
+/* ------------------------------------------------------------------ */
+/* Enclave#_eval                                                       */
+/* ------------------------------------------------------------------ */
+
+static VALUE
+enclave_eval(VALUE self, VALUE rb_code)
+{
+    rb_enclave_t *sb = get_enclave(self);
+    const char *code = StringValueCStr(rb_code);
+
+    sandbox_result_t result = sandbox_state_eval(sb->state, code);
+
+    VALUE value = result.value ? rb_str_new_cstr(result.value) : Qnil;
+    VALUE output = result.output ? rb_str_new_cstr(result.output) : rb_str_new_cstr("");
+    VALUE error = result.error ? rb_str_new_cstr(result.error) : Qnil;
+
+    sandbox_result_free(&result);
+
+    return rb_ary_new_from_args(3, value, output, error);
+}
+
+/* ------------------------------------------------------------------ */
+/* Enclave#reset!                                                      */
+/* ------------------------------------------------------------------ */
+
+static VALUE
+enclave_reset(VALUE self)
+{
+    rb_enclave_t *sb = get_enclave(self);
+    sandbox_state_reset(sb->state);
+    return self;
+}
+
+/* ------------------------------------------------------------------ */
+/* Enclave#close                                                       */
+/* ------------------------------------------------------------------ */
+
+static VALUE
+enclave_close(VALUE self)
+{
+    rb_enclave_t *sb;
+    TypedData_Get_Struct(self, rb_enclave_t, &enclave_data_type, sb);
+
+    if (!sb->closed) {
+        if (sb->state) {
+            sandbox_state_free(sb->state);
+            sb->state = NULL;
+        }
+        sb->closed = 1;
+    }
+    return Qnil;
+}
+
+static VALUE
+enclave_closed_p(VALUE self)
+{
+    rb_enclave_t *sb;
+    TypedData_Get_Struct(self, rb_enclave_t, &enclave_data_type, sb);
+    return sb->closed ? Qtrue : Qfalse;
+}
+
+/* ------------------------------------------------------------------ */
+/* Init                                                                */
+/* ------------------------------------------------------------------ */
+
+void
+Init_enclave(void)
+{
+    VALUE cEnclave = rb_define_class("Enclave", rb_cObject);
+
+    rb_define_alloc_func(cEnclave, enclave_alloc);
+    rb_define_method(cEnclave, "_init",            enclave_initialize,      0);
+    rb_define_method(cEnclave, "_eval",            enclave_eval,            1);
+    rb_define_method(cEnclave, "_define_function", enclave_define_function, 1);
+    rb_define_method(cEnclave, "reset!",           enclave_reset,           0);
+    rb_define_method(cEnclave, "close",            enclave_close,           0);
+    rb_define_method(cEnclave, "closed?",          enclave_closed_p,        0);
+}

data/ext/enclave/extconf.rb

@@ -0,0 +1,33 @@
+require "mkmf"
+
+# Paths — must be absolute since rake-compiler changes cwd
+ext_dir = File.expand_path(File.dirname(__FILE__))
+mruby_dir = File.join(ext_dir, "mruby")
+build_config = File.join(ext_dir, "sandbox_build_config.rb")
+mruby_build_dir = File.join(mruby_dir, "build", "host")
+
+# Build mruby from source
+unless File.exist?(File.join(mruby_build_dir, "lib", "libmruby.a"))
+  puts "Building mruby..."
+  system("cd #{mruby_dir} && MRUBY_CONFIG=#{build_config} rake -f #{mruby_dir}/Rakefile -j1") || abort("mruby build failed")
+end
+
+# mruby headers (only used by sandbox_core.c, not enclave.c)
+$INCFLAGS << " -I#{File.join(mruby_dir, 'include')}"
+$INCFLAGS << " -I#{File.join(mruby_build_dir, 'include')}"
+
+# Include the ext dir for sandbox_core.h
+$INCFLAGS << " -I#{ext_dir}"
+
+# Both .c files in the extension directory
+$srcs = [
+  File.join(ext_dir, "enclave.c"),
+  File.join(ext_dir, "sandbox_core.c")
+]
+
+# Link libmruby.a statically
+$LDFLAGS << " -L#{File.join(mruby_build_dir, 'lib')}"
+$libs << " #{File.join(mruby_build_dir, 'lib', 'libmruby.a')}"
+$libs << " -lm"
+
+create_makefile("enclave/enclave")