isolated-function 0.0.6 → 0.1.1

package/README.md

@@ -1,18 +1,37 @@
 <h3 align="center">
-  <img src="https://github.com/Kikobeats/isolated-function/blob/master/logo.png?raw=true" width="200">
+  <img
+    src="https://github.com/Kikobeats/isolated-function/blob/master/logo.png?raw=true"
+    width="200">
   <br>
-  <p>isolated-functions</p>
-  <a target="_blank" rel="noopener noreferrer nofollow"><img src="https://img.shields.io/github/tag/Kikobeats/isolated-function.svg?style=flat-square" style="max-width: 100%;"></a>
-<a href="https://coveralls.io/github/Kikobeats/isolated-function" rel="nofollow"><img src="https://img.shields.io/coveralls/Kikobeats/isolated-function.svg?style=flat-square" alt="Coverage Status" style="max-width: 100%;"></a>
-<a href="https://www.npmjs.org/package/isolated-function" rel="nofollow"><img src="https://img.shields.io/npm/dm/isolated-function.svg?style=flat-square" alt="NPM Status" style="max-width: 100%;"></a>
+  <p>isolated-function</p>
+  <a target="_blank" rel="noopener noreferrer nofollow"><img
+      src="https://img.shields.io/github/tag/Kikobeats/isolated-function.svg?style=flat-square"
+      style="max-width: 100%;"></a>
+  <a href="https://coveralls.io/github/Kikobeats/isolated-function"
+    rel="nofollow"><img
+      src="https://img.shields.io/coveralls/Kikobeats/isolated-function.svg?style=flat-square"
+      alt="Coverage Status" style="max-width: 100%;"></a>
+  <a href="https://www.npmjs.org/package/isolated-function" rel="nofollow"><img
+      src="https://img.shields.io/npm/dm/isolated-function.svg?style=flat-square"
+      alt="NPM Status" style="max-width: 100%;"></a>
 </h3>
 
-## Highlights
-
-- Based in [Node.js Permission Model](https://nodejs.org/api/permissions.html#permission-model)
-- Auto install npm dependencies.
-- Memory limit support.
-- Timeout support.
+- [Install](#install)
+- [Quickstart](#quickstart)
+  - [Minimal privilege execution](#minimal-privilege-execution)
+  - [Auto install dependencies](#auto-install-dependencies)
+  - [Execution profiling](#execution-profiling)
+  - [Resource limits](#resource-limits)
+- [API](#api)
+  - [isolatedFunction(code, \[options\])](#isolatedfunctioncode-options)
+    - [code](#code)
+    - [options](#options)
+      - [timeout](#timeout)
+      - [timeout](#timeout-1)
+  - [=\> (fn(\[...args\]), teardown())](#-fnargs-teardown)
+    - [fn](#fn)
+    - [teardown](#teardown)
+- [License](#license)
 
 ## Install
 
@@ -20,55 +39,169 @@
 npm install isolated-function --save
 ```
 
-## Usage
+## Quickstart
+
+**isolated-function** is a modern solution for running untrusted code in Node.js.
 
 ```js
 const isolatedFunction = require('isolated-function')
 
-/* This function will run in a sandbox, in a separate process */
-const sum = isolatedFunction((y, z) => y + z)
+/* create an isolated-function, with resources limitation */
+const [sum, teardown] = isolatedFunction((y, z) => y + z, {
+  memory: 128, // in MB
+  timeout: 10000 // in milliseconds
+})
 
-/* Interact with it as usual from your main code */
-const result = await sum(3, 2)
+/* interact with the isolated-function */
+const [value, profiling] = await sum(3, 2)
+console.log({ value, profiling })
 
-console.log(result)
+/* close resources associated with the isolated-function initialization */
+await teardown()
 ```
 
-You can also use `require' for external dependencies:
+### Minimal privilege execution
+
+The hosted code runs in a separate process, with minimal privilege, using [Node.js permission model API](https://nodejs.org/api/permissions.html#permission-model).
 
 ```js
-const isEmoji = isolatedFunction(emoji => {
-  const isEmoji = require('is-standard-emoji')
+const [fn, teardown] = isolatedFunction(() => {
+  const fs = require('fs')
+  fs.writeFileSync('/etc/passwd', 'foo')
+})
+
+await fn()
+// => PermissionError: Access to 'FileSystemWrite' has been restricted.
+```
+
+If you exceed your limit, an error will occur. Any of the following interaction will throw an error:
+
+- Native modules
+- Child process
+- Worker Threads
+- Inspector protocol
+- File system access
+- WASI
+
+### Auto install dependencies
+
+The hosted code is parsed for detecting `require`/`import` calls and install these dependencies:
+
+```js
+const [isEmoji, teardown] = isolatedFunction(emoji => {
+  /* this dependency only exists inside the isolated function */
+  const isEmoji = require('is-standard-emoji@1.0.0') // default is latest
   return isEmoji(emoji)
 })
 
 await isEmoji('🙌') // => true
 await isEmoji('foo') // => false
+await teardown()
+```
+
+The dependencies, along with the hosted code, are bundled by [esbuild](https://esbuild.github.io/) into a single file that will be evaluated at runtime.
+
+### Execution profiling
+
+Any hosted code execution will be run in their own separate process:
+
+```js
+/** make a function to consume ~128MB */
+const [fn, teardown] = isolatedFunction(() => {
+  const storage = []
+  const oneMegabyte = 1024 * 1024
+  while (storage.length < 78) {
+    const array = new Uint8Array(oneMegabyte)
+    for (let ii = 0; ii < oneMegabyte; ii += 4096) {
+      array[ii] = 1
+    }
+    storage.push(array)
+  }
+})
+t.teardown(cleanup)
+
+const [value, profiling] = await fn()
+console.log(profiling)
+// {
+//   memory: 128204800,
+//   duration: 54.98325
+// }
+```
+
+Each execution has a profile, which helps understand what happened.
+
+### Resource limits
+
+You can limit a **isolated-function** by memory:
+
+```js
+const [fn, teardown] = isolatedFunction(() => {
+  const storage = []
+  const oneMegabyte = 1024 * 1024
+  while (storage.length < 78) {
+    const array = new Uint8Array(oneMegabyte)
+    for (let ii = 0; ii < oneMegabyte; ii += 4096) {
+      array[ii] = 1
+    }
+    storage.push(array)
+  }
+}, { memory: 64 })
+
+await fn()
+// =>  MemoryError: Out of memory
 ```
 
-The dependencies are bundled with the source code into a single file that is executed in the sandbox.
+or by execution duration:
 
-It's intentionally not possible to expose any Node.js objects or functions directly to the sandbox (such as `process`, or filesystem). This makes it slightly harder to integrate into a project, but has the benefit of guaranteed isolation.
+```js
+const [fn, teardown] = isolatedFunction(() => {
+  const delay = ms => new Promise(resolve => setTimeout(resolve, ms))
+  await delay(duration)
+  return 'done'
+}, { timeout: 50 })
+
+await fn(100)
+// =>  TimeoutError: Execution timed out
+```
 
 ## API
 
-### isolatedFunction(snippet, [options])
+### isolatedFunction(code, [options])
 
-#### snippet
+#### code
 
-*Required*<br>
-Type: `string`
+_Required_<br>
+Type: `function`
 
-The source code to run.
+The hosted function to run.
 
 #### options
 
-##### foo
+##### timeout
+
+Type: `number`
+
+Timeout after a specified amount of time, in milliseconds.
+
+##### timeout
+
+Type: `number`
+
+Set the functino memory limit, in megabytes.
+
+### => (fn([...args]), teardown())
+
+#### fn
+
+Type: `function`
+
+The isolated function to execute. You can pass arguments over it.
+
+#### teardown
 
-Type: `boolean`<br>
-Default: `false`
+Type: `function`
 
-Lorem ipsum.
+A function to be called to release resources associated with the **isolated-function**.
 
 ## License
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "isolated-function",
   "description": "Runs untrusted code in a Node.js v8 sandbox.",
   "homepage": "https://github.com/Kikobeats/isolated-function",
-  "version": "0.0.6",
+  "version": "0.1.1",
   "main": "src/index.js",
   "exports": {
     ".": "./src/index.js"

package/src/compile.js

@@ -37,17 +37,74 @@ const detectDependencies = code => {
         node.arguments.length === 1 &&
         node.arguments[0].type === 'Literal'
       ) {
-        dependencies.add(node.arguments[0].value)
+        const dependency = node.arguments[0].value
+        // Check if the dependency string contains '@' symbol for versioning
+        if (dependency.includes('@')) {
+          // Split by '@' to separate module name and version
+          const parts = dependency.split('@')
+          // Handle edge case where module name might also contain '@' (scoped packages)
+          const moduleName = parts.length > 2 ? `${parts[0]}@${parts[1]}` : parts[0]
+          const version = parts[parts.length - 1]
+          dependencies.add(`${moduleName}@${version}`)
+        } else {
+          dependencies.add(`${dependency}@latest`)
+        }
       }
     },
     ImportDeclaration (node) {
-      dependencies.add(node.source.value)
+      const source = node.source.value
+      if (source.includes('@')) {
+        const parts = source.split('@')
+        const moduleName = parts.length > 2 ? `${parts[0]}@${parts[1]}` : parts[0]
+        const version = parts[parts.length - 1]
+        dependencies.add(`${moduleName}@${version}`)
+      } else {
+        dependencies.add(`${source}@latest`)
+      }
     }
   })
 
   return Array.from(dependencies)
 }
 
+const transformDependencies = code => {
+  const ast = acorn.parse(code, { ecmaVersion: 2020, sourceType: 'module' })
+
+  let newCode = ''
+  let lastIndex = 0
+
+  // Helper function to process and transform nodes
+  const processNode = node => {
+    if (node.type === 'Literal' && node.value.includes('@')) {
+      // Extract module name without version
+      const [moduleName] = node.value.split('@')
+      // Append code before this node
+      newCode += code.substring(lastIndex, node.start)
+      // Append transformed dependency
+      newCode += `'${moduleName}'`
+      // Update lastIndex to end of current node
+      lastIndex = node.end
+    }
+  }
+
+  // Traverse the AST to find require and import declarations
+  walk.simple(ast, {
+    CallExpression (node) {
+      if (node.callee.name === 'require' && node.arguments.length === 1) {
+        processNode(node.arguments[0])
+      }
+    },
+    ImportDeclaration (node) {
+      processNode(node.source)
+    }
+  })
+
+  // Append remaining code after last modified dependency
+  newCode += code.substring(lastIndex)
+
+  return newCode
+}
+
 const getTmp = async content => {
   const cwd = await fs.mkdtemp(path.join(tmpdir(), 'compile-'))
   await fs.mkdir(cwd, { recursive: true })
@@ -60,8 +117,10 @@ const getTmp = async content => {
 }
 
 module.exports = async snippet => {
-  const tmp = await getTmp(generateTemplate(snippet))
-  const dependencies = detectDependencies(tmp.content)
+  const compiledTemplate = generateTemplate(snippet)
+  const dependencies = detectDependencies(compiledTemplate)
+  const tmp = await getTmp(transformDependencies(compiledTemplate))
+
   await $(packageManager.init, { cwd: tmp.cwd })
   await $(`${packageManager.install} ${dependencies.join(' ')}`, {
     cwd: tmp.cwd