capacitor-wasm-agent-tools

Standalone Rust-backed Capacitor plugin for secure, sandboxed execution of WebAssembly, JavaScript, and Python on native mobile platforms. Powered by Wasmtime, QuickJS, and RustPython — all running inside WASM with strict resource limits.

Features

• WASM sandbox — execute raw WASM binaries or WAT text with fuel metering, memory limits, and timeout enforcement
• JavaScript runtime — run arbitrary JS code via embedded QuickJS engine (compiled to WASM)
• Python runtime — run Python code via embedded RustPython engine (compiled to WASM), with dangerous imports blocked
• Resource limits — configurable fuel budget, max memory, and timeout per execution
• Zero native code execution — all guest code runs inside WASM; no native eval
• Cross-platform — Android (arm64) and iOS (arm64 device + simulator)

Install

npm install capacitor-wasm-agent-tools
npx cap sync

Quick Start

WASM Sandbox

Execute a WebAssembly binary that implements the sandbox ABI (alloc, execute, memory exports):

import { WasmAgentTools } from 'capacitor-wasm-agent-tools'

await WasmAgentTools.createWasmSandbox()

const result = await WasmAgentTools.executeSandbox({
  wasmBase64: '<base64-encoded .wasm binary>',
  inputJson: '{"key":"value"}',
  config: { fuelLimit: 1_000_000, maxMemoryBytes: 16_777_216, timeoutSecs: 30 },
})
console.log(result.output)        // JSON string returned by the WASM module
console.log(result.fuelConsumed)  // instructions executed
console.log(result.durationMs)    // wall-clock time

Alternatively, use the WAT text format:

const result = await WasmAgentTools.executeWatSandbox({
  watText: `(module ...)`,
  inputJson: '{}',
})

JavaScript Runtime

await WasmAgentTools.createJsRuntime()

const result = await WasmAgentTools.executeJs({
  code: `
    const x = [1, 2, 3].map(n => n * 2)
    console.log(JSON.stringify(x))
  `,
  config: { timeoutSecs: 5 },
})
console.log(result.output)  // "[2,4,6]\n"
console.log(result.error)   // null (or error message if execution failed)

Python Runtime

await WasmAgentTools.createPythonRuntime()

const result = await WasmAgentTools.executePython({
  code: `
import json, math
data = {"pi": math.pi, "sqrt2": math.sqrt(2)}
print(json.dumps(data))
  `,
  config: { timeoutSecs: 5 },
})
console.log(result.output)  // '{"pi": 3.141592653589793, "sqrt2": 1.4142135623730951}\n'

Dangerous imports are blocked (subprocess, socket, ctypes). Standard library modules (math, json, re, etc.) are available.

API

WasmAgentToolsPlugin

| Method | Description | |--------|-------------| | createWasmSandbox() | Initialize the WASM sandbox engine | | executeSandbox({ wasmBase64, inputJson, config? }) | Execute a WASM binary (base64-encoded) | | executeWatSandbox({ watText, inputJson, config? }) | Execute a WAT text module | | createJsRuntime() | Initialize the QuickJS JavaScript runtime | | executeJs({ code, config? }) | Execute JavaScript code | | createPythonRuntime() | Initialize the RustPython runtime | | executePython({ code, config? }) | Execute Python code |

SandboxConfig / JsConfig / PythonConfig

| Field | Type | Default | Description | |-------|------|---------|-------------| | fuelLimit | number | 1,000,000 (WASM) / 1,000,000,000 (JS/Python) | Max instructions before abort | | maxMemoryBytes | number | 16,777,216 (WASM) / 33,554,432 (JS/Python) | Max guest memory in bytes | | timeoutSecs | number | 30 (WASM) / 5 (JS/Python) | Wall-clock timeout in seconds |

WASM Sandbox ABI

WASM modules must export:

| Export | Type | Description | |--------|------|-------------| | memory | Memory | Linear memory shared with host | | alloc(size: i32) -> i32 | Function | Allocate size bytes; returns pointer | | execute(ptr: i32, len: i32) -> i64 | Function | Run with input at [ptr, ptr+len). Returns (out_ptr << 32) \| out_len |

The sandbox reads the input JSON from guest memory and reads back the output JSON using the packed pointer/length return value.

E2E Tests

25/25 tests passing on Android and iOS — 9 WASM sandbox tests, 8 JavaScript tests, 8 Python tests:

| Suite | Tests | Coverage | |-------|-------|----------| | WASM Sandbox | 9 | create, echo, fuel limit, timeout, fuel tracking, invalid WASM, missing exports, WAT, memory limit | | JavaScript | 8 | create, expression, console.log, console.error, multi-statement, timeout, throw, no require | | Python | 8 | create, print, multi-print, math, json, timeout, blocked imports, raise |

Platforms

| Platform | Architecture | Binary | |----------|-------------|--------| | Android | arm64-v8a | libwasm_agent_tools_ffi.so | | iOS | arm64 (device) | WasmAgentToolsFFI.xcframework | | iOS | arm64 (Apple Silicon sim) | WasmAgentToolsFFI.xcframework |

Prebuilt native binaries are included in the npm package. No Rust toolchain required for consumers.

Building Native Binaries

For contributors modifying the Rust FFI code:

# Android
./scripts/build-android.sh

# iOS (run on macOS with Xcode)
./scripts/build-ios.sh

See CONTRIBUTING.md for full toolchain requirements.

Contributing

Contributions are welcome! Please read our Contributing Guide and Code of Conduct.

Security

To report vulnerabilities, see SECURITY.md.

License

MIT © 2025-present Techxagon