eligrey / jsandbox

A JavaScript sandboxing library that uses HTML5 web workers

This URL has Read+Write access

name age
history
message
file COPYING.md Mon Jul 20 09:48:05 -0700 2009 wording change [eligrey]
file README.md Fri Dec 18 21:22:16 -0800 2009 JSandbox v0.2.2 - see changelog [eligrey]
file changelog.md Fri Dec 18 21:22:16 -0800 2009 JSandbox v0.2.2 - see changelog [eligrey]
directory min/ Fri Dec 18 21:37:13 -0800 2009 Added "use strict"; to minified files and moved... [eligrey]
directory src/ Fri Dec 18 21:37:13 -0800 2009 Added "use strict"; to minified files and moved... [eligrey]
file test-suite.html Fri Dec 18 21:22:16 -0800 2009 JSandbox v0.2.2 - see changelog [eligrey]
README.md

JSandbox

Version 0.2.2

JSandbox is an open source JavaScript sandboxing library that makes use of HTML5 web workers. JSandbox makes it possible to run untrusted JavaScript without having to worry about any potential dangers.

Getting Started

  1. Download JSandbox.
  2. Include <link rel="jsandbox" href="path/to/jsandbox-worker.js" /> anywhere in your document. I recommend putting it in the document's <head>.
  3. Place <script type="text/javascript" src="path/to/jsandbox.js"></script> anywhere after the <link> tag.
  4. Read the API documentation below.

Example Code

This example code demonstrates the JSandbox API.

Tested Working Browsers

  • Firefox 3.5+
  • Google Chrome 4+

API

Worker script location

Instead of using a <link> tag, you may define JSandbox.url to specify the location of the JSandbox worker script.

Waiting for the json2.js API to load

In browsers that do not natively support the json2.js API, a modified version of json2.js is loaded. To support these browsers, use the following code:

JSandbox && JSandbox.ready(function () {
  // your code that uses JSandbox here
});

In browsers that natively support the json2.js API, the function passed to JSandbox.ready is immediately called. In other browsers, it is added to a queue which is processed after the API is loaded.

Methods

All of these methods can be accessed on the JSandbox constructor (in one-use sandboxes) and JSandbox instances:

eval(options)
eval()s options.data. If options.callback is a function, it is passed the results as long as no errors occur. If options.onerror is a function and an error occurs, it is passed the error object. The code is eval()ed in a top-level pseudo-function-scope. If you define a variable using a var statement, the variable is private to the eval. this is still the global object. If this method is called on jsandbox, the jsandbox object is returned. Otherwise, the ID of the request is returned.
exec(options)
Executes code in a faster method than eval, but does not pass a return value to the callback function (though the function is still called if defined). Unlike eval, the code is run in the global scope (var statements affect this).
load(options)
If options.data is a string, options.data will attempt to be loaded in the sandbox. If options.data is an array, every string it contains will attempt be loaded. If options.onerror is a function and an error is thrown while parsing a script or a script could not be resolved, options.onerror is passed the error object. Otherwise, options.callback is called when the scripts are finished loading.

Instance-only methods

These methods can only be on jsandbox instances:

abort(requestID)
Aborts a pending request with the ID, requestID.
terminate()
Terminates the worker thread and any pending requests are aborted. You cannot use the jsandbox instance on which you called this method after it is called.

options object

The following are all of the properties that may be included in an options object.

data [Required]
In the case of eval and exec, it is the code to execute. In the case of load, it is an array of the script(s) to load. If you only need to load one script, just pass a string instead.
input
The input data available to the code via the input variable. The input should be JSON-convertible.
callback
The callback to pass the return value of the executed code if no exceptions were thrown.
onerror
The callback to pass an exception if one is thrown upon executing the code.

Alternative syntax

Any method that takes an options object can also be called using the following positional-arguments syntax:

someMethod(data [, callback] [, input] [, onerror]);

The global JSandbox object can also be referenced as Sandbox.