wasm-sandbox 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 N-API for Rust
+
+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.

package/README.md

@@ -0,0 +1,94 @@
+# wasm-sandbox
+
+Node.js WebAssembly sandbox CLI tool built on [@wasm-sandbox/runtime](https://www.npmjs.com/package/@wasm-sandbox/runtime).
+
+> **Note:** This CLI tool does not support running a **Core WebAssembly module** directly. You can use [`wasm-tools`](https://github.com/bytecodealliance/wasm-tools) to convert a Core wasm module into a **WebAssembly Component**.
+
+## Installation
+
+```bash
+npm install -g wasm-sandbox
+# or use npx
+npx wasm-sandbox <command>
+```
+
+## Usage
+
+### Run WebAssembly Component
+
+```bash
+# Basic run
+wasm-sandbox run example.wasm
+
+# Pass arguments
+wasm-sandbox run example.wasm arg1 arg2 arg3
+
+# Invoke specific function
+wasm-sandbox run example.wasm 1 2 --invoke add 
+
+# Set working directory
+wasm-sandbox run example.wasm --work-dir ./ 
+
+# Map directory
+wasm-sandbox run example.wasm --map-dir ./host/path::/guest/path
+
+# Set environment variables
+wasm-sandbox run  example.wasm --env FOO=BAR --env BAZ=QUX
+
+# Limit resources
+wasm-sandbox run example.wasm --wasm-timeout 10 --wasm-max-memory-size 1073741824
+```
+
+### Start HTTP Server
+
+```bash
+# Basic server
+wasm-sandbox serve example.wasm
+
+# Specify port and IP
+wasm-sandbox serve example.wasm --ip 127.0.0.1 --port 3000 
+
+# Configure network access
+wasm-sandbox serve example.wasm --allowed-outbound-hosts https://*.github.com
+
+# Set config variables
+wasm-sandbox serve example.wasm --config-var KEY=VALUE --keyvalue-var DATA=VALUE 
+```
+
+## Command Options
+
+### run Command
+
+| Option | Description |
+|--------|-------------|
+| `--program-name <name>` | Override argv[0] value |
+| `--invoke <function>` | Invoke specific function |
+| `--work-dir <dir>` | Grant host directory access |
+| `--map-dir <mapping>` | Map host directory to guest, format: `host::guest` |
+| `--env <var>` | Pass environment variable, format: `NAME=VALUE` |
+| `--allowed-outbound-hosts <host>` | Allowed network destinations |
+| `--block-networks <network>` | Blocked IP networks |
+| `--wasm-timeout <seconds>` | Maximum execution time (seconds) |
+| `--wasm-max-memory-size <bytes>` | Maximum memory size (bytes) |
+| `--wasm-max-stack <bytes>` | Maximum stack size (bytes) |
+| `--wasm-fuel <units>` | Execution fuel units |
+| `--wasm-cache-dir <dir>` | Precompiled Wasm Component cache directory |
+
+### serve Command
+
+| Option | Description |
+|--------|-------------|
+| `-i, --ip <ip>` | Bind IP address |
+| `-p, --port <port>` | Bind port |
+| `--config-var <var>` | WASI config variable, format: `NAME=VALUE` |
+| `--keyvalue-var <var>` | WASI key-value API preset data |
+
+Other options are same as `run` command.
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+**Repository**: [https://github.com/guyoung/wasm-sandbox-node](https://github.com/guyoung/wasm-sandbox-node)

package/cli.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'fs'
+import { fileURLToPath } from 'url'
+import { dirname, join } from 'path'
+
+import { Command } from 'commander';
+import wasm_sandbox from '@wasm-sandbox/runtime';
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const { name, version, description } = JSON.parse(readFileSync(join(__dirname, 'package.json'), 'utf8'))
+
+const program = new Command();
+
+program
+  .name(name)
+  .version(version)
+  .description("Wasm Sandbox CLI tool.\n\n Wasm Sandbox Built on the `WebAssembly Component Model` and `WASI (WebAssembly System Interface)`, it provides `Capability-based security` to ensure your host environment remains protected.\nAllows to execute WebAssembly components in a restricted environment with granular control over file system access, network requests, environment variables, and computational resources (memory, CPU fuel, and execution time).\n\n Note: Wasm Sandbox does not support running a `Core WebAssembly module` directly. You can use `wasm-tools`(https://github.com/bytecodealliance/wasm-tools) to convert a Core wasm module into a `WebAssembly Component`")
+
+program
+  .command("run")
+  .argument("<args...>", "WebAssembly Component file and arguments.")
+  .option('--program-name <name>', "Override the value of `argv[0]`, typically the name of the executable of the application being run.")
+  .option('--invoke <function>', "The name of the function to run ")
+  .option('--work-dir <dir>', "Grant access of a host directory to guest root dir.\nExample: `--work-dir ./`")
+  .option('--map-dir <mapping...>', "Grant access of a host directory to a guest.\nExample: `--map-dir ./usr/hello::/hello`")
+  .option('--env <var...>', "Pass an environment variable to the program.\nExample: `--env FOO=BAR`")
+  .option('--allowed-outbound-hosts <host...>', "The network destinations which the component is allowed to access.\nExample: `--allowed-outbound-hosts https://*.github.net`")
+  .option('--block-networks <network...>', "Set of IP networks to be blocked.\nExample: `--block-networks 1.1.1.1/32  --block-networks private`")
+  .option('--wasm-timeout <seconds>', "Maximum execution time of wasm code before timing out (seconds).", parseInt)
+  .option('--wasm-max-memory-size <bytes>', "Maximum size, in bytes, that a linear memory is allowed to reach.", parseInt)
+  .option('--wasm-max-stack <bytes>', "Maximum stack size, in bytes, that wasm is allowed to consume before a stack overflow is reported.", parseInt)
+  .option('--wasm-fuel <units>', "Enable execution fuel with N units fuel, trapping after running out of fuel.", parseInt)
+  .option('--wasm-cache-dir <dir>', "Precompiled WebAssembly Component as `*.cwasm` files cache dir. ")
+
+  .action(async (args, opts) => {
+    wasm_sandbox.run({
+      wasmFile: args.shift(),
+      args: args || [],
+      programName: opts.programName,
+      invoke: opts.invoke,
+      workDir: opts.workDir,
+      mapDirs: opts.mapDir?.map(m => {
+        const [key, value] = m.split('::');
+        return { key, value: value || key };
+      }),
+      envVars: opts.env?.map(e => {
+        const [key, value] = e.split('=');
+        return { key, value };
+      }),
+      allowedOutboundHosts: opts.allowedOutboundHosts,
+      blockNetworks: opts.blockNetworks,
+      wasmTimeout: opts.wasmTimeout,
+      wasmMaxMemorySize: opts.wasmMaxMemorySize,
+      wasmMaxWasmStack: opts.wasmMaxStack,
+      wasmFuel: opts.wasmFuel,
+      wasmCacheDir: opts.wasmCacheDir
+    });
+  });
+
+program
+  .command("serve")
+  .description("Start http server from a WebAssembly Component.")
+  .argument("<wasm>", "WebAssembly Component file.")
+  .option('-i, --ip <ip>', "Socket ip for the web server to bind to.")
+  .option('-p, --port <port>', "Socket port for the web server to bind to. ", parseInt)
+  .option('--work-dir <dir>', "Grant access of a host directory to guest root dir.\nExample: `--work-dir ./`")
+  .option('--map-dir <mapping...>', "Grant access of a host directory to a guest.\nExample: `--map-dir ./usr/hello::/hello`")
+  .option('--env <var...>', "Pass an environment variable to the program.\nExample: `--env FOO=BAR`")
+  .option('--allowed-outbound-hosts <host...>', "The network destinations which the component is allowed to access.\nExample: `--allowed-outbound-hosts https://*.github.net`")
+  .option('--block-networks <network...>', "Set of IP networks to be blocked.\nExample: `--block-networks 1.1.1.1/32  --block-networks private`")
+  .option('--config-var <var...>', "Pass a wasi config variable to the program.\nExample: `--config-var FOO=BAR`")
+  .option('--keyvalue-var <var...>', "Preset data for the In-Memory provider of WASI key-value API.\nExample: `--keyvalue-var FOO=BAR`")
+  .option('--wasm-timeout <seconds>', "Maximum execution time of wasm code before timing out (seconds).", parseInt)
+  .option('--wasm-max-memory-size <bytes>', "Maximum size, in bytes, that a linear memory is allowed to reach.", parseInt)
+  .option('--wasm-max-stack <bytes>', "Maximum stack size, in bytes, that wasm is allowed to consume before a stack overflow is reported.", parseInt)
+  .option('--wasm-fuel <units>', "Enable execution fuel with N units fuel, trapping after running out of fuel.", parseInt)
+  .option('--wasm-cache-dir <dir>', "Precompiled WebAssembly Component as `*.cwasm` files cache dir. ")
+  .action(async (wasm, opts) => {
+    const mapDirs = {};
+    opts.mapDir?.forEach(m => {
+      const [key, value] = m.split('::');
+      mapDirs[key] = value || key;
+    });
+
+    const envVars = {};
+    opts.env?.forEach(e => {
+      const [key, value] = e.split('=');
+      envVars[key] = value;
+    });
+
+    const configVars = opts.configVar?.map(v => {
+      const [key, value] = v.split('=');
+      return { key, value };
+    });
+
+    const keyvalueVars = opts.keyvalueVar?.map(v => {
+      const [key, value] = v.split('=');
+      return { key, value };
+    });
+
+    wasm_sandbox.serve({
+      wasmFile: wasm,
+      ip: opts.ip,
+      port: opts.port,
+      workDir: opts.workDir,
+      mapDirs,
+      envVars,
+      allowedOutboundHosts: opts.allowedOutboundHosts,
+      blockNetworks: opts.blockNetworks,
+      configVars,
+      keyvalueVars,
+      wasmTimeout: opts.wasmTimeout,
+      wasmMaxMemorySize: opts.wasmMaxMemorySize,
+      wasmMaxWasmStack: opts.wasmMaxStack,
+      wasmFuel: opts.wasmFuel,
+      wasmCacheDir: opts.wasmCacheDir
+    });
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "wasm-sandbox",
+  "version": "1.1.0",
+  "description": "wasm-sandbox CLI tool",
+  "author": "guyoung",
+  "homepage": "https://github.com/guyoung/wasm-sandbox-node/tree/main/cli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/guyoung/wasm-sandbox-node.git"
+  },
+  "license": "MIT",
+  "keywords": [
+    "wasm",
+    "webassembly",
+    "wasi",
+    "sandbox",
+    "cli"
+  ],
+  "files": [
+    "cli.js",
+    "README.md",
+    "README_zh-CN.md"
+  ],
+  "type": "module",
+  "bin": {
+    "wasm-sandbox": "cli.js"
+  },
+  "dependencies": {
+    "@wasm-sandbox/runtime": "^1.1.0",
+    "commander": "^14.0.3"
+  }
+}