isolated-function 0.1.36 → 0.1.38

package/README.md

@@ -19,6 +19,7 @@
 - [Install](#install)
 - [Quickstart](#quickstart)
   - [Minimal privilege execution](#minimal-privilege-execution)
+  - [Granting specific permissions](#granting-specific-permissions)
   - [Auto install dependencies](#auto-install-dependencies)
   - [Execution profiling](#execution-profiling)
   - [Resource limits](#resource-limits)
@@ -32,6 +33,7 @@
       - [throwError](#throwerror)
       - [timeout](#timeout)
       - [tmpdir](#tmpdir)
+      - [allow](#allow)
   - [=\> (fn(\[...args\]), teardown())](#-fnargs-teardown)
     - [fn](#fn)
     - [teardown](#teardown)
@@ -89,6 +91,28 @@ If you exceed your limit, an error will occur. Any of the following interaction
 - File system access
 - WASI
 
+### Granting specific permissions
+
+You can grant specific permissions to the isolated function using the `allow` option:
+
+```js
+const [fn, teardown] = isolatedFunction(
+  () => {
+    const { execSync } = require('child_process')
+    return execSync('echo hello').toString().trim()
+  },
+  {
+    allow: ['child-process']
+  }
+)
+
+const { value } = await fn()
+console.log(value) // 'hello'
+await teardown()
+```
+
+See [#allow](#allow) to know more.
+
 ### Auto install dependencies
 
 The hosted code is parsed for detecting `require`/`import` calls and install these dependencies:
@@ -279,6 +303,38 @@ const tmpdir = async () => {
 }
 ```
 
+##### allow
+
+Type: `string[]`<br>
+Default: `[]`
+
+An array of permissions to grant to the isolated function based on [Node.js Options](https://nodejs.org/api/cli.html#options)
+
+When empty, the function runs with minimal privileges and will throw an error if it attempts to access restricted resources. Available permissions are:
+
+- `addons`
+- `child-process`
+- `fs-read`
+- `fs-write`
+- `inspector`
+- `net`
+- `wasi`
+- `worker`
+
+Example:
+
+```js
+const [fn, cleanup] = isolatedFunction(
+  async () => {
+    const http = require('node:http')
+    // Network request code here
+  },
+  {
+    allow: ['net']
+  }
+)
+```
+
 ### => (fn([...args]), teardown())
 
 #### fn

package/package.json

@@ -2,7 +2,8 @@
   "name": "isolated-function",
   "description": "Runs untrusted code in a Node.js v8 sandbox.",
   "homepage": "https://github.com/Kikobeats/isolated-function",
-  "version": "0.1.36",
+  "version": "0.1.38",
+  "types": "src/index.d.ts",
   "main": "src/index.js",
   "exports": {
     ".": "./src/index.js"
@@ -55,7 +56,8 @@
     "nano-staged": "latest",
     "simple-git-hooks": "latest",
     "standard": "latest",
-    "standard-version": "latest"
+    "standard-version": "latest",
+    "tsd": "latest"
   },
   "engines": {
     "node": ">= 20"
@@ -67,7 +69,7 @@
     "clean": "rm -rf node_modules",
     "contributors": "(npx git-authors-cli && npx finepack && git add package.json && git commit -m 'build: contributors' --no-verify) || true",
     "coverage": "c8 report --reporter=text-lcov > coverage/lcov.info",
-    "lint": "standard",
+    "lint": "standard && tsd",
     "postrelease": "npm run release:tags && npm run release:github && (ci-publish || npm publish --access=public)",
     "pretest": "npm run lint",
     "release": "standard-version -a",
@@ -101,5 +103,8 @@
   "simple-git-hooks": {
     "commit-msg": "npx commitlint --edit",
     "pre-commit": "npx nano-staged"
+  },
+  "tsd": {
+    "directory": "test"
   }
 }

package/src/compile/build.js

@@ -3,7 +3,7 @@
 const esbuild = require('esbuild')
 
 const MINIFY = (() => {
-  return process.env.ISOLATED_FUNCTIONS_MINIFY !== 'false'
+  return process.env.ISOLATED_FUNCTIONS_MINIFY === 'false'
     ? {}
     : {
         minifyWhitespace: true,

package/src/compile/index.js

@@ -4,35 +4,37 @@ const fs = require('fs/promises')
 const path = require('path')
 
 const transformDependencies = require('./transform-dependencies')
-const detectDependencies = require('./detect-dependencies')
 const installDependencies = require('./install-dependencies')
-const generateTemplate = require('../template')
-const { duration } = require('../debug')
+const detectDependencies = require('./detect-dependencies')
+const { debug, duration } = require('../debug')
+const template = require('../template')
 const build = require('./build')
 
 const tmpdirDefault = async () => {
+  const duration = debug.duration()
   const cwd = await fs.mkdtemp(path.join(require('os').tmpdir(), 'compile-'))
   await fs.mkdir(cwd, { recursive: true })
   const cleanup = () => fs.rm(cwd, { recursive: true, force: true })
+  duration('tmpdir', { cwd })
   return { cwd, cleanup }
 }
 
 module.exports = async (snippet, tmpdir = tmpdirDefault) => {
-  const compiledTemplate = generateTemplate(snippet)
-  const dependencies = detectDependencies(compiledTemplate)
-  let content = transformDependencies(compiledTemplate)
-  let cleanupPromise
+  let content = template(snippet)
+  const { cwd, cleanup } = await tmpdir()
 
+  const dependencies = detectDependencies(content)
   if (dependencies.length) {
-    const { cwd, cleanup } = await duration('tmpdir', tmpdir)
+    content = transformDependencies(content)
     await duration('npm:install', () => installDependencies({ dependencies, cwd }), {
       dependencies
     })
-    const result = await duration('esbuild', () => build({ content, cwd }))
-    content = result.outputFiles[0].text
-    cleanupPromise = duration('tmpDir:cleanup', cleanup)
   }
 
+  const result = await duration('esbuild', () => build({ content, cwd }))
+  content = result.outputFiles[0].text
+  const cleanupPromise = duration('tmpDir:cleanup', cleanup)
+
   return { content, cleanupPromise }
 }
 

package/src/compile/install-dependencies.js

@@ -1,9 +1,7 @@
 'use strict'
 
 const { execSync } = require('child_process')
-const { writeFile } = require('fs/promises')
 const $ = require('tinyspawn')
-const path = require('path')
 
 const install = (() => {
   try {
@@ -17,6 +15,5 @@ const install = (() => {
 })()
 
 module.exports = async ({ dependencies, cwd }) => {
-  await writeFile(path.join(cwd, 'package.json'), '{}')
   return $(`${install} ${dependencies.join(' ')}`, { cwd })
 }

package/src/compile/transform-dependencies.js

@@ -3,6 +3,24 @@
 const walk = require('acorn-walk')
 const acorn = require('acorn')
 
+/**
+ * Transforms dependency module names by removing version specifiers.
+ *
+ * Parses JavaScript code and walks through the AST to find all require() calls
+ * and import declarations. Extracts module names from strings that include
+ * version information (e.g., 'is-emoji@1.0.0' becomes 'is-emoji').
+ *
+ * Handles both:
+ * - Scoped packages: '@scope/package@1.0.0' → '@scope/package'
+ * - Regular packages: 'package@1.0.0' → 'package'
+ *
+ * This transformation is necessary because the dependency strings include
+ * version specifiers for installation tracking, but require/import statements
+ * should only reference the base module name.
+ *
+ * @param {string} code - JavaScript code containing require() or import statements
+ * @returns {string} Transformed code with version specifiers removed from dependencies
+ */
 module.exports = code => {
   const ast = acorn.parse(code, { ecmaVersion: 2023, sourceType: 'module' })
 

package/src/index.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Profiling information about the isolated function execution
+ */
+export interface Profiling {
+  /** Memory usage in bytes */
+  memory: number
+  /** Execution duration in milliseconds */
+  duration: number
+}
+
+/**
+ * Logging information captured from the isolated function
+ */
+export interface Logging {
+  log?: unknown[][]
+  info?: unknown[][]
+  debug?: unknown[][]
+  warn?: unknown[][]
+  error?: unknown[][]
+}
+
+/**
+ * Successful execution result
+ */
+export interface SuccessResult<T = unknown> {
+  isFulfilled: true
+  value: T
+  profiling: Profiling
+  logging: Logging
+}
+
+/**
+ * Failed execution result
+ */
+export interface FailureResult {
+  isFulfilled: false
+  value: Error
+  profiling: Profiling
+  logging: Logging
+}
+
+/**
+ * Execution result (success or failure)
+ */
+export type ExecutionResult<T = unknown> = SuccessResult<T> | FailureResult
+
+/**
+ * Options for creating an isolated function
+ */
+export interface IsolatedFunctionOptions {
+  /** Temporary directory configuration */
+  tmpdir?: () => Promise<{ cwd: string; cleanup: () => Promise<void> }>
+  /** Execution timeout in milliseconds */
+  timeout?: number
+  /** Memory limit in megabytes */
+  memory?: number
+  /** When false, errors are returned instead of thrown */
+  throwError?: boolean
+  /** Array of resources to allow access to */
+  allow?: string[]
+}
+
+/**
+ * Cleanup function to release resources
+ */
+export type Cleanup = () => Promise<void>
+
+/**
+ * Isolated function that can be executed with arguments
+ */
+export type IsolatedFn<T = unknown> = (
+  ...args: unknown[]
+) => Promise<SuccessResult<T> | FailureResult>
+
+/**
+ * Creates an isolated function that runs untrusted code in a separate Node.js process.
+ *
+ * @param snippet - The function or code string to run in isolation
+ * @param options - Configuration options for the isolated function
+ * @returns A tuple containing the isolated function and a cleanup function
+ *
+ * @example
+ * ```js
+ * const [sum, cleanup] = isolatedFunction((a, b) => a + b, {
+ *   memory: 128,
+ *   timeout: 10000
+ * })
+ *
+ * const { value } = await sum(3, 2)
+ * console.log(value) // 5
+ * await cleanup()
+ * ```
+ *
+ * @example
+ * ```js
+ * // With error handling
+ * const [fn, cleanup] = isolatedFunction(() => {
+ *   throw new Error('oh no!')
+ * }, { throwError: false })
+ *
+ * const result = await fn()
+ * if (!result.isFulfilled) {
+ *   console.error(result.value)
+ * }
+ * await cleanup()
+ * ```
+ */
+declare function isolatedFunction<T = unknown>(
+  snippet: Function | string,
+  options?: IsolatedFunctionOptions
+): [IsolatedFn<T>, Cleanup]
+
+export default isolatedFunction

package/src/index.js

@@ -49,8 +49,8 @@ module.exports = (snippet, { tmpdir, timeout, memory, throwError = true, allow =
       const { isFulfilled, value, profiling, logging } = JSON.parse(stdout)
       profiling.duration = duration()
       debug('node', {
-        duration: `${Math.round(profiling.duration / 100)}s`,
-        memory: `${Math.round(profiling.memory / (1024 * 1024))}MiB`
+        memory: `${Math.round(profiling.memory / (1024 * 1024))}MiB`,
+        duration: `${Math.round(profiling.duration / 100)}s`
       })
 
       return isFulfilled

package/src/template/index.js

@@ -2,23 +2,23 @@
 
 const SERIALIZE_ERROR = require('./serialize-error')
 
-module.exports = snippet => `
-  const args = JSON.parse(process.argv[2])
+module.exports = snippet => `;(send => {
+  process.stdout.write = function () {}
+  const respond = (isFulfilled, value, logs = {}) => send(JSON.stringify({isFulfilled, logging: logs, value, profiling: {memory: process.memoryUsage().rss}}))
 
-  /* https://github.com/Kikobeats/null-prototype-object */
-  const logging = new (/* @__PURE__ */ (() => { let e = function(){}; return e.prototype = Object.create(null), Object.freeze(e.prototype), e })());
+  return Promise.resolve().then(async () => {
+    const args = JSON.parse(process.argv[2])
 
-  for (const method of ['log', 'info', 'debug', 'warn', 'error']) {
-    console[method] = function (...args) {
-      logging[method] === undefined ? logging[method] = [args] : logging[method].push(args)
+    /* https://github.com/Kikobeats/null-prototype-object */
+    const logging = new (/* @__PURE__ */ (() => { let e = function(){}; return e.prototype = Object.create(null), Object.freeze(e.prototype), e })());
+    for (const method of ['log', 'info', 'debug', 'warn', 'error']) {
+      console[method] = function (...args) {
+        logging[method] === undefined ? logging[method] = [args] : logging[method].push(args)
+      }
     }
-  }
 
-  ;(async (send) => {
-    process.stdout.write = function () {}
     let value
     let isFulfilled
-
     try {
       value = await (${snippet.toString()})(...args)
       isFulfilled = true
@@ -26,11 +26,8 @@ module.exports = snippet => `
       value = ${SERIALIZE_ERROR}(error)
       isFulfilled = false
     } finally {
-      send(JSON.stringify({
-        isFulfilled,
-        logging,
-        value,
-        profiling: { memory: process.memoryUsage().rss }
-      }))
+      respond(isFulfilled, value, logging)
     }
-  })(process.stdout.write.bind(process.stdout))`
+  })
+  .catch(e => respond(false, ${SERIALIZE_ERROR}(e)))
+})(process.stdout.write.bind(process.stdout))`