janet_sandbox 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 37d030736271dabc94ac931ad2cd3af8c5cfc1ccf8570b47cba5ab1c5c9c3907
+  data.tar.gz: fbd1407297ff9a11c2c561e262c368d404363c6097e936e76940d6b5dff6ec4f
+SHA512:
+  metadata.gz: 4fcf025e8c2f3ae4b40db1e459d15ffa6e07188a758eb0c98c9254ad043aef99aa406b4e7539b521afd2cd221550fd5cfbba85d14eceee2226a2de67be7424fc
+  data.tar.gz: c2b3a8624af767fbeff5bf457008337b999b6a1c0a542d22f3a85ceac8bdc3a6cec762de22360ca4cc66026652a3a59241289e7d6fa9050c55d73cf0f3220ac9

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Your Name
+
+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,316 @@
+# JanetSandbox
+
+Safely embed [Janet](https://janet-lang.org) scripting in your Ruby application via WebAssembly. Execute user-authored scripts with configurable sandboxing, resource limits, and pluggable DSL modules.
+
+Note that janet.c in `wasm/build/janet` is pulled from the [Janet Repo](https://github.com/janet-lang/janet). The JSON module (`wasm/json.c`) is pulled from [spork](https://github.com/janet-lang/spork) to provide `json/encode` and `json/decode` for Ruby/Janet interop.
+
+## Features
+
+- **Secure sandboxing** via WebAssembly isolation
+- **Resource limits** - fuel-based execution limits prevent infinite loops
+- **Memory caps** - bounded WASM linear memory
+- **Pluggable DSLs** - register domain-specific Janet functions for your use case
+- **Rails integration** - optional Railtie and ActiveRecord concern
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'janet_sandbox'
+```
+
+The gem ships with a prebuilt `janet.wasm` binary, so it works out of the box.
+
+## Quick Start
+
+```ruby
+require 'janet_sandbox'
+
+# Simple evaluation
+result = JanetSandbox.evaluate(
+  source: '(+ 1 2 3)',
+  context: {}
+)
+result.raw  #=> 6
+
+# With context
+result = JanetSandbox.evaluate(
+  source: '(* (get ctx :quantity) (get ctx :price))',
+  context: { quantity: 5, price: 10 }
+)
+result.raw  #=> 50
+```
+
+## Configurable DSLs
+
+Unlike traditional embedded scripting, JanetSandbox doesn't impose a fixed DSL. Instead, you register your own domain-specific functions:
+
+```ruby
+JanetSandbox.configure do |config|
+  # Register a DSL module
+  config.register_dsl(:form_helpers, <<~'JANET')
+    (defn get-field [name]
+      (get-in ctx [:values (keyword name)]))
+
+    (defn show [field]
+      {:action :show :field (keyword field)})
+
+    (defn hide [field]
+      {:action :hide :field (keyword field)})
+  JANET
+
+  # Enable it by default
+  config.enable_dsl(:form_helpers)
+end
+
+# Now use it
+result = JanetSandbox.evaluate(
+  source: '(if (= (get-field "role") "admin") (show "budget") (hide "budget"))',
+  context: { values: { role: "admin" } }
+)
+```
+
+### Per-Evaluation DSL Override
+
+```ruby
+# Use specific DSLs for this evaluation
+result = JanetSandbox.evaluate(
+  source: code,
+  context: ctx,
+  dsls: [:form_helpers, :validation_helpers]
+)
+
+# Or disable all DSLs
+result = JanetSandbox.evaluate(
+  source: '(+ 1 2)',
+  context: {},
+  dsls: []
+)
+```
+
+## Example DSLs
+
+The gem includes example DSLs in `examples/dsls/`:
+
+- **form_helpers.janet** - Form visibility, validation, computed fields
+- **validation_helpers.janet** - Email, phone, length validators
+- **math_helpers.janet** - Safe arithmetic, tax/discount calculations
+
+Copy these to your project and customize as needed.
+
+## Configuration
+
+```ruby
+JanetSandbox.configure do |config|
+  # Execution limits (apply only to user code, not setup/DSL loading)
+  config.fuel_limit      = 10_000_000   # Instruction budget for user code
+  config.epoch_interval  = 100          # Wall-clock check interval (ms)
+  config.epoch_deadline  = 10           # Max intervals (~1 second timeout)
+  config.max_result_size = 64 * 1024    # 64KB max JSON output
+
+  # Path to WASM binary
+  config.wasm_path = '/path/to/janet.wasm'
+
+  # Block additional symbols
+  config.blocked_symbols << 'some/dangerous-fn'
+
+  # Register DSLs
+  config.register_dsl(:my_dsl, janet_source, description: "My custom DSL")
+  config.enable_dsl(:my_dsl)
+end
+```
+
+### Execution Limits
+
+JanetSandbox uses two complementary limits:
+
+- **Fuel** (instruction counting) - Catches CPU-intensive computation
+- **Epochs** (wall-clock time) - Catches blocking operations like sleep
+
+Set `epoch_interval` to `nil` to disable wall-clock timeouts.
+
+## Result Object
+
+Evaluations return a `JanetSandbox::Result`:
+
+```ruby
+result = JanetSandbox.evaluate(
+  source: '{:status "ok" :total 150 :items [{:name "A"} {:name "B"}]}',
+  context: {}
+)
+
+result.raw          #=> {status: "ok", total: 150, items: [{name: "A"}, {name: "B"}]}
+result[:status]     #=> "ok"
+result[:total]      #=> 150
+result.to_h         #=> Same as raw for hashes, or {value: raw} for primitives
+result.to_json      #=> JSON string
+```
+
+The Result object is intentionally minimal - your DSL defines the structure, not the gem.
+
+## Rails Integration
+
+### Setup
+
+The gem auto-loads Rails integration when Rails is detected.
+
+```ruby
+# config/initializers/janet_sandbox.rb
+JanetSandbox.configure do |config|
+  config.register_dsl(:form_helpers, File.read(Rails.root.join('lib/janet_dsls/form_helpers.janet')))
+  config.enable_dsl(:form_helpers)
+end
+```
+
+### Model Concern
+
+```ruby
+class ScriptRule < ApplicationRecord
+  include JanetSandbox::Rails::ScriptConcern
+
+  # Specify DSLs for this model
+  janet_dsls :form_helpers, :validation_helpers
+
+  belongs_to :form
+end
+```
+
+Expected schema:
+
+- `janet_source` (text) - Required
+- `active` (boolean) - Optional, for scoping
+- `priority` (integer) - Optional, for ordering
+
+### Usage
+
+```ruby
+# Single rule
+rule = ScriptRule.find(1)
+result = rule.evaluate({ values: params, user: current_user.attributes })
+
+# All rules for a form, merged
+result = ScriptRule.evaluate_all(
+  form.script_rules,
+  context: { values: params, user: current_user.attributes }
+)
+
+render json: result.to_h
+```
+
+## Security
+
+Scripts run in a WASM sandbox with:
+
+- **No filesystem access** - `file/*` functions removed
+- **No network access** - `net/*` functions removed
+- **No process spawning** - `os/execute`, `os/spawn` removed
+- **No eval/compile** - Prevents meta-evaluation escapes
+- **Fuel-limited execution** - Instruction budget terminates runaway computation
+- **Epoch-limited execution** - Wall-clock timeout catches blocking operations
+- **Memory-capped** - WASM linear memory has a hard ceiling
+- **Result size limit** - Prevents memory bombs via output
+
+## Error Handling
+
+```ruby
+begin
+  result = JanetSandbox.evaluate(source: user_code, context: ctx)
+rescue JanetSandbox::TimeoutError
+  # Script exceeded fuel limit
+rescue JanetSandbox::MemoryError
+  # Script exceeded memory limit
+rescue JanetSandbox::EvaluationError => e
+  # Script had a syntax or runtime error
+  puts e.janet_error
+rescue JanetSandbox::ResultError
+  # Result was too large or couldn't be parsed
+rescue JanetSandbox::DSLNotFoundError => e
+  # Referenced DSL is not registered
+end
+```
+
+## Custom WASM Binary
+
+To use a different janet.wasm (e.g., a custom build or newer version):
+
+```ruby
+JanetSandbox.configure do |config|
+  config.wasm_path = '/custom/path/janet.wasm'
+end
+```
+
+## Development
+
+### Rebuilding janet.wasm
+
+The gem ships with a prebuilt janet.wasm, but you can rebuild it to update Janet or modify the build.
+
+**Dependencies:**
+
+- [wasi-sdk](https://github.com/WebAssembly/wasi-sdk) - WASI-enabled Clang/LLVM toolchain
+- `curl` - for downloading Janet source files
+
+**Setup:**
+
+1. Download wasi-sdk from the [releases page](https://github.com/WebAssembly/wasi-sdk/releases)
+2. Extract it and set the environment variable:
+
+```bash
+export WASI_SDK_PATH=~/wasi-sdk-22.0
+```
+
+**Build:**
+
+```bash
+cd wasm
+./build.sh
+```
+
+Or via rake:
+
+```bash
+rake janet_sandbox:build_wasm
+```
+
+The build script downloads Janet source files automatically if not present.
+
+## Thread Safety
+
+- `Engine` is thread-safe and should be shared (one per app)
+- `Sandbox` is per-evaluation with isolated WASM memory
+- Configuration should be set at boot time
+
+## API Reference
+
+### `JanetSandbox.evaluate(source:, context:, dsls: nil, **opts)`
+
+Evaluate Janet code. Returns `Result`.
+
+### `JanetSandbox.configure { |config| }`
+
+Configure the gem.
+
+### `JanetSandbox.register_dsl(name, source, description: nil)`
+
+Register a DSL module.
+
+### `JanetSandbox::Configuration`
+
+- `#register_dsl(name, source)` - Register a DSL
+- `#unregister_dsl(name)` - Remove a DSL
+- `#enable_dsl(name)` - Enable by default
+- `#disable_dsl(name)` - Disable from defaults
+- `#dsl_registered?(name)` - Check if registered
+- `#dsl_names` - List all registered DSLs
+
+### `JanetSandbox::Result`
+
+- `#raw` - Full parsed result
+- `#[key]` - Bracket access to hash keys (symbol or string)
+- `#to_h` - Hash representation
+- `#to_json` - JSON string
+
+## License
+
+MIT License. See LICENSE.txt.

data/examples/dsls/form_helpers.janet

@@ -0,0 +1,90 @@
+# Form DSL Helpers
+#
+# This DSL provides functions for building dynamic form rules.
+# Register it in your application:
+#
+#   JanetSandbox.configure do |config|
+#     config.register_dsl(:form_helpers, File.read("path/to/form_helpers.janet"))
+#     config.enable_dsl(:form_helpers)
+#   end
+#
+# Expected context structure:
+#   {
+#     values: { field_name: value, ... },
+#     user: { role: "admin", id: 1, ... },
+#     meta: { form_id: 123, ... }
+#   }
+
+(defn get-field [name]
+  "Get the current value of a form field"
+  (get-in ctx [:values (keyword name)]))
+
+(defn get-user [key]
+  "Get a property from the current user context"
+  (get-in ctx [:user (keyword key)]))
+
+(defn get-meta [key]
+  "Get form metadata"
+  (get-in ctx [:meta (keyword key)]))
+
+(defn show [field]
+  "Mark a field as visible"
+  {:action :show :field (keyword field)})
+
+(defn hide [field]
+  "Mark a field as hidden"
+  {:action :hide :field (keyword field)})
+
+(defn require-field [field message]
+  "Add a required validation to a field"
+  {:action :require :field (keyword field) :message message})
+
+(defn set-value [field value]
+  "Set a computed value for a field"
+  {:action :set-value :field (keyword field) :value value})
+
+(defn add-error [field message]
+  "Add a validation error to a field"
+  {:action :error :field (keyword field) :message message})
+
+(defn add-warning [field message]
+  "Add a validation warning to a field"
+  {:action :warning :field (keyword field) :message message})
+
+(defn validate [field pred message]
+  "Conditionally add an error if pred is falsy"
+  (when (not pred)
+    (add-error field message)))
+
+(defn field-present? [name]
+  "Check if a field has a non-nil, non-empty value"
+  (let [v (get-field name)]
+    (and (not (nil? v)) (not= v ""))))
+
+(defn field-matches? [name pattern]
+  "Check if a field value matches a PEG pattern"
+  (not (nil? (peg/find pattern (or (get-field name) "")))))
+
+(defn when-field [name value body-fn]
+  "Execute body-fn when field equals value"
+  (when (= (get-field name) value) (body-fn)))
+
+(defn one-of? [value options]
+  "Check if value is one of the given options"
+  (not (nil? (find |(= $ value) options))))
+
+(defn collect-actions [& forms]
+  "Collect all non-nil action results into categorized maps"
+  (def actions (filter truthy? (flatten forms)))
+  (def result {:visibility {} :validation {} :computed {}})
+  (each a actions
+    (case (a :action)
+      :show     (put-in result [:visibility (a :field)] true)
+      :hide     (put-in result [:visibility (a :field)] false)
+      :error    (put-in result [:validation (a :field)] (a :message))
+      :warning  (put-in result [:validation (a :field)]
+                  (string "Warning: " (a :message)))
+      :require  (when (not (field-present? (string (a :field))))
+                  (put-in result [:validation (a :field)] (a :message)))
+      :set-value (put-in result [:computed (a :field)] (a :value))))
+  result)

data/examples/dsls/math_helpers.janet

@@ -0,0 +1,71 @@
+# Math DSL Helpers
+#
+# This DSL provides utility functions for calculations and aggregations.
+# Useful for computed fields, pricing calculations, etc.
+#
+# Register it in your application:
+#
+#   JanetSandbox.configure do |config|
+#     config.register_dsl(:math_helpers, File.read("path/to/math_helpers.janet"))
+#     config.enable_dsl(:math_helpers)
+#   end
+
+(defn safe-number [value &opt default]
+  "Convert value to number, returning default (0) if nil or not a number"
+  (default default 0)
+  (if (number? value)
+    value
+    (if (and (string? value) (not= value ""))
+      (or (scan-number value) default)
+      default)))
+
+(defn sum [& values]
+  "Sum all values, treating nil as 0"
+  (reduce + 0 (map |(safe-number $) values)))
+
+(defn product [& values]
+  "Multiply all values, treating nil as 1"
+  (reduce * 1 (map |(safe-number $ 1) values)))
+
+(defn average [& values]
+  "Calculate average of values, ignoring nil"
+  (def nums (filter number? values))
+  (if (empty? nums)
+    0
+    (/ (sum ;nums) (length nums))))
+
+(defn percentage [value total]
+  "Calculate percentage (value / total * 100)"
+  (def t (safe-number total 1))
+  (if (= t 0)
+    0
+    (* (/ (safe-number value) t) 100)))
+
+(defn round-to [value decimals]
+  "Round value to specified decimal places"
+  (def multiplier (math/pow 10 decimals))
+  (/ (math/round (* (safe-number value) multiplier)) multiplier))
+
+(defn clamp [value min-val max-val]
+  "Clamp value to be within min and max"
+  (max min-val (min max-val (safe-number value))))
+
+(defn lerp [a b t]
+  "Linear interpolation between a and b by factor t (0-1)"
+  (+ a (* (- b a) (clamp t 0 1))))
+
+(defn tax [amount rate]
+  "Calculate tax amount"
+  (* (safe-number amount) (/ (safe-number rate) 100)))
+
+(defn with-tax [amount rate]
+  "Add tax to amount"
+  (+ (safe-number amount) (tax amount rate)))
+
+(defn discount [amount percent]
+  "Calculate discount amount"
+  (* (safe-number amount) (/ (safe-number percent) 100)))
+
+(defn with-discount [amount percent]
+  "Apply percentage discount to amount"
+  (- (safe-number amount) (discount amount percent)))

data/examples/dsls/validation_helpers.janet

@@ -0,0 +1,86 @@
+# Validation DSL Helpers
+#
+# This DSL provides common validation functions.
+# Can be used standalone or combined with form_helpers.
+#
+# Register it in your application:
+#
+#   JanetSandbox.configure do |config|
+#     config.register_dsl(:validation_helpers, File.read("path/to/validation_helpers.janet"))
+#     config.enable_dsl(:validation_helpers)
+#   end
+
+# Email validation pattern
+(def email-pattern
+  ~{:main (* :start (some :local) "@" (some :domain) "." (between 2 10 :alpha) :end)
+    :start (if-not :s 0)
+    :end (if-not :s -1)
+    :local (+ :w (set "._+-"))
+    :domain (+ :w (set ".-"))})
+
+(defn valid-email? [value]
+  "Check if value is a valid email address"
+  (if (nil? value)
+    false
+    (not (nil? (peg/match email-pattern value)))))
+
+# Phone validation (basic - digits, spaces, dashes, parens)
+(def phone-pattern
+  ~{:main (* :start (between 10 20 :phone-char) :end)
+    :start (if-not :s 0)
+    :end (if-not :s -1)
+    :phone-char (+ :d (set " ()-+"))})
+
+(defn valid-phone? [value]
+  "Check if value looks like a phone number"
+  (if (nil? value)
+    false
+    (not (nil? (peg/match phone-pattern value)))))
+
+(defn min-length? [value min]
+  "Check if string has at least min characters"
+  (if (nil? value)
+    false
+    (>= (length value) min)))
+
+(defn max-length? [value max]
+  "Check if string has at most max characters"
+  (if (nil? value)
+    true
+    (<= (length value) max)))
+
+(defn in-range? [value min max]
+  "Check if numeric value is within range (inclusive)"
+  (and (not (nil? value))
+       (>= value min)
+       (<= value max)))
+
+(defn positive? [value]
+  "Check if value is a positive number"
+  (and (number? value) (> value 0)))
+
+(defn non-negative? [value]
+  "Check if value is zero or positive"
+  (and (number? value) (>= value 0)))
+
+(defn matches-pattern? [value pattern]
+  "Check if value matches a PEG pattern"
+  (if (nil? value)
+    false
+    (not (nil? (peg/match pattern value)))))
+
+(defn not-blank? [value]
+  "Check if value is not nil and not an empty string"
+  (and (not (nil? value))
+       (not= value "")
+       (if (string? value)
+         (not= (string/trim value) "")
+         true)))
+
+(defn all-valid? [& predicates]
+  "Return true only if all predicates are truthy"
+  (all truthy? predicates))
+
+(defn any-valid? [& predicates]
+  "Return true if any predicate is truthy"
+  (some truthy? predicates))

data/examples/initializers/janet_sandbox.rb

@@ -0,0 +1,74 @@
+# config/initializers/janet_sandbox.rb
+#
+# Example Rails initializer for JanetSandbox
+# Copy and customize for your application.
+
+JanetSandbox.configure do |config|
+  # Execution limits
+  config.fuel_limit    = 100_000   # ~100ms of computation
+  config.memory_limit  = 4 * 1024 * 1024  # 4MB
+  config.max_result_size = 64 * 1024  # 64KB
+
+  # Optional: Override WASM path if you vendor it
+  # config.wasm_path = Rails.root.join("vendor", "wasm", "janet.wasm").to_s
+
+  # Register your DSLs
+  # You can load from files or define inline
+
+  # Option 1: Load from file
+  # config.register_dsl(
+  #   :form_helpers,
+  #   File.read(Rails.root.join("lib", "janet_dsls", "form_helpers.janet")),
+  #   description: "Form field helpers for visibility and validation"
+  # )
+
+  # Option 2: Define inline
+  config.register_dsl(:form_helpers, <<~'JANET', description: "Form field helpers")
+    (defn get-field [name]
+      "Get the current value of a form field"
+      (get-in ctx [:values (keyword name)]))
+
+    (defn get-user [key]
+      "Get a property from the current user context"
+      (get-in ctx [:user (keyword key)]))
+
+    (defn show [field]
+      "Mark a field as visible"
+      {:action :show :field (keyword field)})
+
+    (defn hide [field]
+      "Mark a field as hidden"
+      {:action :hide :field (keyword field)})
+
+    (defn add-error [field message]
+      "Add a validation error to a field"
+      {:action :error :field (keyword field) :message message})
+
+    (defn set-value [field value]
+      "Set a computed value for a field"
+      {:action :set-value :field (keyword field) :value value})
+
+    (defn field-present? [name]
+      "Check if a field has a non-nil, non-empty value"
+      (let [v (get-field name)]
+        (and (not (nil? v)) (not= v ""))))
+
+    (defn collect-actions [& forms]
+      "Collect all non-nil action results into categorized maps"
+      (def actions (filter truthy? (flatten forms)))
+      (def result {:visibility {} :validation {} :computed {}})
+      (each a actions
+        (case (a :action)
+          :show     (put-in result [:visibility (a :field)] true)
+          :hide     (put-in result [:visibility (a :field)] false)
+          :error    (put-in result [:validation (a :field)] (a :message))
+          :set-value (put-in result [:computed (a :field)] (a :value))))
+      result)
+  JANET
+
+  # Enable DSLs by default for all evaluations
+  config.enable_dsl(:form_helpers)
+
+  # Block additional symbols if needed
+  # config.blocked_symbols << "some/dangerous-fn"
+end

data/lib/janet_sandbox/builtin_dsls.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module JanetSandbox
+  # Built-in DSLs provided by the janet_sandbox gem.
+  #
+  # These DSLs can be registered and enabled in your configuration:
+  #
+  #   JanetSandbox.configure do |config|
+  #     config.register_dsl(:code_inspector, JanetSandbox::BuiltinDsls::CODE_INSPECTOR)
+  #     config.enable_dsl(:code_inspector)
+  #   end
+  #
+  module BuiltinDsls
+    DSL_DIR = File.expand_path("dsls", __dir__)
+
+    # Code Inspector DSL - Parse and inspect Janet code structure without execution.
+    #
+    # Provides functions:
+    # - parse-to-tree: Parse code string into a structured tree
+    # - parse-all-to-tree: Parse multiple expressions into array of trees
+    # - to-tree: Convert a parsed Janet value into a tree representation
+    # - extract-symbols: Get all symbol names from an expression
+    # - extract-calls: Get all function/macro call names from an expression
+    # - validate-syntax: Check if code is syntactically valid
+    #
+    # @example
+    #   JanetSandbox.register_dsl(:code_inspector, JanetSandbox::BuiltinDsls::CODE_INSPECTOR)
+    #   result = JanetSandbox.evaluate(
+    #     source: '(parse-to-tree "(if (> x 3) (foo) (bar))")',
+    #     context: {},
+    #     dsls: [:code_inspector]
+    #   )
+    #   result.raw
+    #   # => { type: "call", op: "if", args: [...] }
+    #
+    CODE_INSPECTOR = File.read(File.join(DSL_DIR, "code_inspector.janet")).freeze
+  end
+end