Sandbox node.js code like a boss
JavaScript
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
jsdoc2md
lib
test
.eslintrc.js
.gitignore
.npmignore
.npmrc
LICENSE
README.md
docs.md
index.d.ts
index.js
jsconfig.json
package.json

README.md

sandboxjs

Sandbox node.js code like a boss.

Key Features

  • Runs code on the public webtask.io cluster.
  • Your code is totally sandboxed from everyone else's.
  • Integrated with your wt-cli profiles.
  • Supports returning Promises and/or invoking node-style callbacks.

Installing it

npm install sandboxjs

# Optionally configure a default wt-cli profile

Using it

First, get a webtask token using wt-cli:

# Create a new wt-cli profile
npm install -g wt-cli
wt init

# Or, if you already use wt-cli:
wt profile ls
var Assert = require('assert');
var Sandbox = require('sandboxjs');

// You can get your webtask token using the steps above
var code = 'module.exports = function (ctx, cb) { cb(null, "hello world"); }';
var profile = Sandbox.fromToken(process.env.WEBTASK_TOKEN);

// This library lets you create a webtask and run it in one step as a shortcut:
profile.run(code, function (err, res, body) {
    Assert.ifError(err);
    Assert.equal(res.statusCode, 200, 'The webtask executed as expected');
    Assert.equal(body, 'hello world', 'The webtask returned the expected string');
});

// Alternatively, your application might want to to create a webtask url
// with your (or your users') custom code and secrets.
profile.create(code, { secrets: { auth0: 'rocks' } }, function (err, webtask) {
    Assert.ifError(err);
    
    // Making requests to this url will run the specified custom code in a
    // node.js sandbox and will give it access to your secrets in the first
    // argument (`ctx`) of your exported webtask function.
    // For more information on the different styles of webtask functions that
    // are supported, see: https://webtask.io/docs/model
    console.log(webtask.url);
});

Examples

Update the code of an existing named webtask

var Sandbox = require('sandboxjs');

var sandbox = Sandbox.init({ /* ... */ });
var webtaskName = 'my_webtask';
var webtaskCode = 'module.exports = ...';

sandbox.inspectWebtask({
    name: webtaskName,
    // We need to decrypt embedded secrets so that we can set them on the
    // replacement named webtask
    decrypt: true,
    // No need to fetch code since we will be updating it anyway
    fetch_code: false,
}).then(handleClaims);

function handleClaims(claims) {
    // We will pull any claims from the existing webtask that are user-defined
    // and set them on a new claims object. Note that some claims are *NOT*
    // copied over because they are read-only claims generated by the platform.
    // Common examples include: `ca`, `jti` and `iat`.
    var newClaims = {
        jtn: webtaskName,
        dd: claims.dd,
        mb: claims.mb,
        pb: claims.pb,
        // Instead of being an opaque, encrypted blob, this will be a javascript
        // Object mapping secret key to value because we set the `decrypt`
        // option on the call to `inspectWebtask`.
        ectx: claims.ectx,
        pctx: claims.pctx,
        code: webtaskCode,
    };
    
    // Create a replacement webtask from raw claims. We use `createRaw` instead
    // of `create` so that we can deal directly with the platform's claims
    // instead of the more human-friendly aliases in `create`.
    // This method will make a token issue request with the updated claims
    // and resolve the Promise with a new `Webtask` instance based on that
    // token.
    return sandbox.createRaw(newClaims);
}

API

Modules

sandboxjs

Sandbox node.js code.

Classes

CronJob
Webtask

sandboxjs

Sandbox node.js code.

Sandbox.fromToken(token, options) ⇒ Sandbox

Create a Sandbox instance from a webtask token

Kind: static method of sandboxjs
Returns: Sandbox - A {@see Sandbox} instance whose url, token and container were derived from the given webtask token.

Param Type Description
token String The webtask token from which the Sandbox profile will be derived.
options Object The options for creating the Sandbox instance that override the derived values from the token.
[options.url] String The url of the webtask cluster. Defaults to the public 'sandbox.auth0-extend.com' cluster.
options.container String The container with which this Sandbox instance should be associated. Note that your Webtask token must give you access to that container or all operations will fail.
options.token String The Webtask Token. See: https://webtask.io/docs/api_issue.

Sandbox.init(options) ⇒ Sandbox

Create a Sandbox instance

Kind: static method of sandboxjs
Returns: Sandbox - A {@see Sandbox} instance.

Param Type Description
options Object The options for creating the Sandbox instance.
[options.url] String The url of the webtask cluster. Defaults to the public 'sandbox.auth0-extend.com' cluster.
options.container String The container with which this Sandbox instance should be associated. Note that your Webtask token must give you access to that container or all operations will fail.
options.token String The Webtask Token. See: https://webtask.io/docs/api_issue.

Sandbox~Sandbox

Kind: inner class of sandboxjs

new Sandbox(options)

Creates an object representing a user's webtask.io credentials

Param Type Description
options Object Options used to configure the profile
options.url String The url of the webtask cluster where code will run
options.container String The name of the container in which code will run
options.token String The JWT (see: http://jwt.io) issued by webtask.io that grants rights to run code in the indicated container
[options.onBeforeRequest] String An array of hook functions to be invoked with a prepared request

sandbox.clone(options)

Create a clone of this sandbox instances with one or more different parameters

Kind: instance method of Sandbox

Param Type Description
options Object Options used to configure the profile
[options.url] String The url of the webtask cluster where code will run
[options.container] String The name of the container in which code will run
[options.token] String The JWT (see: http://jwt.io) issued by webtask.io that grants rights to run code in the indicated container
[options.onBeforeRequest] String An array of hook functions to be invoked with a prepared request

sandbox.create([codeOrUrl], [options], [cb]) ⇒ Promise

Create a Webtask from the given options

Kind: instance method of Sandbox
Returns: Promise - A Promise that will be fulfilled with the token

Param Type Description
[codeOrUrl] String The code for the webtask or a url starting with http:// or https://
[options] Object Options for creating the webtask
[cb] function Optional callback function for node-style callbacks

sandbox.createRaw(claims, [cb]) ⇒ Promise

Create a Webtask from the given claims

Kind: instance method of Sandbox
Returns: Promise - A Promise that will be fulfilled with the token

Param Type Description
claims Object Options for creating the webtask
[cb] function Optional callback function for node-style callbacks

sandbox.createUrl(options, [cb]) ⇒ Promise

Shortcut to create a Webtask and get its url from the given options

Kind: instance method of Sandbox
Returns: Promise - A Promise that will be fulfilled with the token

Param Type Description
options Object Options for creating the webtask
[cb] function Optional callback function for node-style callbacks

sandbox.run([codeOrUrl], [options], [cb]) ⇒ Promise

Shortcut to create and run a Webtask from the given options

Kind: instance method of Sandbox
Returns: Promise - A Promise that will be fulfilled with the token

Param Type Description
[codeOrUrl] String The code for the webtask or a url starting with http:// or https://
[options] Object Options for creating the webtask
[cb] function Optional callback function for node-style callbacks

sandbox.createToken(options, [cb]) ⇒ Promise

Create a webtask token - A JWT (see: http://jwt.io) with the supplied options

Kind: instance method of Sandbox
Returns: Promise - A Promise that will be fulfilled with the token

Param Type Description
options Object Claims to make for this token (see: https://webtask.io/docs/api_issue)
[cb] function Optional callback function for node-style callbacks

sandbox.issueRequest(request, [cb]) ⇒ Promise

Run a prepared Superagent request through any configured onBeforeRequest hooks.

This can be useful for enablying proxies for server-side consumers of sandboxjs.

Kind: instance method of Sandbox
Returns: Promise - - A promise representing the fulfillment of the request

Param Type Description
request Superagent.Request Instance of a superagent request
[cb] function Node-style callback function

sandbox.createTokenRaw(claims, [options], [cb]) ⇒ Promise

Create a webtask token - A JWT (see: http://jwt.io) with the supplied claims

Kind: instance method of Sandbox
Returns: Promise - A Promise that will be fulfilled with the token

Param Type Description
claims Object Claims to make for this token (see: https://webtask.io/docs/api_issue)
[options] Object Optional options. Currently only options.include_webtask_url is supported.
[cb] function Optional callback function for node-style callbacks

sandbox.createLogStream(options) ⇒ Stream

Create a stream of logs from the webtask container

Note that the logs will include messages from our infrastructure.

Kind: instance method of Sandbox
Returns: Stream - A stream that will emit 'data' events with container logs

Param Type Description
options Object Streaming options overrides
[options.container] String The container for which you would like to stream logs. Defaults to the current profile's container.

sandbox.getWebtask(options, [cb]) ⇒ Promise

Read a named webtask

Kind: instance method of Sandbox
Returns: Promise - A Promise that will be fulfilled with an array of Webtasks

Param Type Description
options Object Options
[options.container] String Set the webtask container. Defaults to the profile's container.
options.name String The name of the webtask.
[options.decrypt] Boolean Decrypt the webtask's secrets.
[options.fetch_code] Boolean Fetch the code associated with the webtask.
[cb] function Optional callback function for node-style callbacks.

sandbox.createWebtask(options, [cb]) ⇒ Promise

Create a named webtask

Kind: instance method of Sandbox
Returns: Promise - A Promise that will be fulfilled with an array of Webtasks

Param Type Description
options Object Options
[options.container] String Set the webtask container. Defaults to the profile's container.
options.name String The name of the webtask.
[options.secrets] String Set the webtask secrets.
[options.meta] String Set the webtask metadata.
[options.host] String Set the webtask hostname.
[cb] function Optional callback function for node-style callbacks.

sandbox.removeWebtask(options, [cb]) ⇒ Promise

Remove a named webtask from the webtask container

Kind: instance method of Sandbox
Returns: Promise - A Promise that will be fulfilled with an array of Webtasks

Param Type Description
options Object Options
[options.container] String Set the webtask container. Defaults to the profile's container.
options.name String The name of the cron job.
[cb] function Optional callback function for node-style callbacks.

sandbox.updateWebtask(options, [cb]) ⇒ Promise

Update an existing webtask's code, secrets or other claims

Note that this method should be used with caution as there is the potential for a race condition where another agent updates the webtask between the time that the webtask details and claims are resolved and when the webtask update is issued.

Kind: instance method of Sandbox
Returns: Promise - A Promise that will be fulfilled with an instance of Webtask representing the updated webtask

Param Type Description
options Object Options
options.name String Name of the webtask to update
[options.code] String Updated code for the webtask
[options.url] String Updated code URL for the webtask
[options.secrets] String If false, remove existing secrets, if an object update secrets, otherwise preserve
[options.params] String If false, remove existing params, if an object update params, otherwise preserve
[options.host] String If false, remove existing host, if a string update host, otherwise preserve
[cb] function Optional callback function for node-style callbacks.

sandbox.listWebtasks(options, [cb]) ⇒ Promise

List named webtasks from the webtask container

Kind: instance method of Sandbox
Returns: Promise - A Promise that will be fulfilled with an array of Webtasks

Param Type Description
options Object Options
[options.container] String Set the webtask container. Defaults to the profile's container.
[cb] function Optional callback function for node-style callbacks.

sandbox.createCronJob(options, [cb]) ⇒ Promise

Create a cron job from an already-existing webtask

Kind: instance method of Sandbox
Returns: Promise - A Promise that will be fulfilled with a {@see CronJob} instance.

Param Type Description
options Object Options for creating a cron job
[options.container] String The container in which the job will run. Defaults to the current profile's container.
options.name String The name of the cron job.
[options.token] String The webtask token that will be used to run the job.
options.schedule String The cron schedule that will be used to determine when the job will be run.
options.tz String The cron timezone (IANA timezone).
options.meta String The cron metadata (set of string key value pairs).
[cb] function Optional callback function for node-style callbacks.

sandbox.removeCronJob(options, [cb]) ⇒ Promise

Remove an existing cron job

Kind: instance method of Sandbox
Returns: Promise - A Promise that will be fulfilled with the response from removing the job.

Param Type Description
options Object Options for removing the cron job
[options.container] String The container in which the job will run. Defaults to the current profile's container.
options.name String The name of the cron job.
[cb] function Optional callback function for node-style callbacks.

sandbox.setCronJobState(options, [cb]) ⇒ Promise

Set an existing cron job's state

Kind: instance method of Sandbox
Returns: Promise - A Promise that will be fulfilled with the response from removing the job.

Param Type Description
options Object Options for updating the cron job's state
[options.container] String The container in which the job will run. Defaults to the current profile's container.
options.name String The name of the cron job.
options.state String The new state of the cron job.
[cb] function Optional callback function for node-style callbacks.

sandbox.listCronJobs([options], [cb]) ⇒ Promise

List cron jobs associated with this profile

Kind: instance method of Sandbox
Returns: Promise - A Promise that will be fulfilled with an Array of {@see CronJob} instances.

Param Type Description
[options] Object Options for listing cron jobs.
[options.container] String The container in which the job will run. Defaults to the current profile's container.
[cb] function Optional callback function for node-style callbacks.

sandbox.getCronJob(options, [cb]) ⇒ Promise

Get a CronJob instance associated with an existing cron job

Kind: instance method of Sandbox
Returns: Promise - A Promise that will be fulfilled with a {@see CronJob} instance.

Param Type Description
options Object Options for retrieving the cron job.
[options.container] String The container in which the job will run. Defaults to the current profile's container.
options.name String The name of the cron job.
[cb] function Optional callback function for node-style callbacks.

sandbox.getCronJobHistory(options, [cb]) ⇒ Promise

Get the historical results of executions of an existing cron job.

Kind: instance method of Sandbox
Returns: Promise - A Promise that will be fulfilled with an Array of cron job results.

Param Type Description
options Object Options for retrieving the cron job.
[options.container] String The container in which the job will run. Defaults to the current profile's container.
options.name String The name of the cron job.
[options.offset] String The offset to use when paging through results.
[options.limit] String The limit to use when paging through results.
[cb] function Optional callback function for node-style callbacks.

sandbox.inspectToken(options, [cb]) ⇒ Promise

Inspect an existing webtask token to resolve code and/or secrets

Kind: instance method of Sandbox
Returns: Promise - A Promise that will be fulfilled with the resolved webtask data.

Param Type Description
options Object Options for inspecting the webtask.
options.token Boolean The token that you would like to inspect.
[options.decrypt] Boolean Decrypt the webtask's secrets.
[options.fetch_code] Boolean Fetch the code associated with the webtask.
[cb] function Optional callback function for node-style callbacks.

sandbox.inspectWebtask(options, [cb]) ⇒ Promise

Inspect an existing named webtask to resolve code and/or secrets

Kind: instance method of Sandbox
Returns: Promise - A Promise that will be fulfilled with the resolved webtask data.

Param Type Description
options Object Options for inspecting the webtask.
options.name Boolean The named webtask that you would like to inspect.
[options.decrypt] Boolean Decrypt the webtask's secrets.
[options.fetch_code] Boolean Fetch the code associated with the webtask.
[cb] function Optional callback function for node-style callbacks.

sandbox.revokeToken(token, [cb]) ⇒ Promise

Revoke a webtask token

Kind: instance method of Sandbox
Returns: Promise - A Promise that will be fulfilled with the token
See: https://webtask.io/docs/api_revoke

Param Type Description
token String The token that should be revoked
[cb] function Optional callback function for node-style callbacks

sandbox.listNodeModuleVersions(options, [cb]) ⇒ Promise

List versions of a given node module that are available on the platform

Kind: instance method of Sandbox
Returns: Promise - A Promise that will be fulfilled with the token

Param Type Description
options Object Options
options.name String Name of the node module
[cb] function Optional callback function for node-style callbacks

sandbox.ensureNodeModules(options, [cb]) ⇒ Promise

Ensure that a set of modules are available on the platform

Kind: instance method of Sandbox
Returns: Promise - A Promise that will be fulfilled with an array of { name, version, state } objects

Param Type Description
options Object Options
options.modules Array Array of { name, version } pairs
options.reset Boolean Trigger a rebuild of the modules (Requires administrative token)
[cb] function Optional callback function for node-style callbacks

sandbox.updateStorage(options, storage, [cb]) ⇒ Promise

Update the storage associated to the a webtask

Kind: instance method of Sandbox
Returns: Promise - A Promise that will be fulfilled with an array of Webtasks

Param Type Description
options Object Options
[options.container] String Set the webtask container. Defaults to the profile's container.
options.name String The name of the webtask.
storage Object storage
storage.data Object The data to be stored
storage.etag String Pass in an optional string to be used for optimistic concurrency control to prevent simultaneous updates of the same data.
[cb] function Optional callback function for node-style callbacks.

sandbox.getStorage(options, [cb]) ⇒ Promise

Read the storage associated to the a webtask

Kind: instance method of Sandbox
Returns: Promise - A Promise that will be fulfilled with an array of Webtasks

Param Type Description
options Object Options
[options.container] String Set the webtask container. Defaults to the profile's container.
options.name String The name of the webtask.
[cb] function Optional callback function for node-style callbacks.

CronJob

Kind: global class

new CronJob()

Creates an object representing a CronJob

cronJob.sandbox

Kind: instance property of CronJob
Properties

Name Description
sandbox The {@see Sandbox} instance used to create this Webtask instance

cronJob.refresh([cb]) ⇒ Promise

Refresh this job's metadata

Kind: instance method of CronJob
Returns: Promise - A Promise that will be fulfilled with the this cron job instance

Param Type Description
[cb] function Optional callback function for node-style callbacks

cronJob.remove([cb]) ⇒ Promise

Remove this cron job from the webtask cluster

Note that this will not revoke the underlying webtask token, so the underlying webtask will remain functional.

Kind: instance method of CronJob
Returns: Promise - A Promise that will be fulfilled with the token

Param Type Description
[cb] function Optional callback function for node-style callbacks

cronJob.getHistory(options, [cb]) ⇒ Promise

Get the history of this cron job

Kind: instance method of CronJob
Returns: Promise - A Promise that will be fulfilled with an Array of cron job results.

Param Type Description
options Object Options for retrieving the cron job.
[options.offset] String The offset to use when paging through results.
[options.limit] String The limit to use when paging through results.
[cb] function Optional callback function for node-style callbacks.

cronJob.inspect(options, [cb]) ⇒ Promise

Inspect an existing webtask to optionally get code and/or secrets

Kind: instance method of CronJob
Returns: Promise - A Promise that will be fulfilled with an Array of cron job results.

Param Type Description
options Object Options for inspecting the webtask.
[options.fetch_code] Boolean Fetch the code associated with the webtask.
[options.decrypt] Boolean Decrypt the webtask's secrets.
[cb] function Optional callback function for node-style callbacks.

cronJob.setJobState(options, [cb]) ⇒ Promise

Set the cron job's state

Kind: instance method of CronJob
Returns: Promise - A Promise that will be fulfilled with an Array of cron job results.

Param Type Description
options Object Options for updating the webtask.
options.state Boolean Set the cron job's state to this.
[cb] function Optional callback function for node-style callbacks.

Webtask

Kind: global class

new Webtask()

Creates an object representing a Webtask

webtask.claims

Kind: instance property of Webtask
Properties

Name Description
claims The claims embedded in the Webtask's token

webtask.token

Kind: instance property of Webtask
Properties

Name Description
token The token associated with this webtask

webtask.sandbox

Kind: instance property of Webtask
Properties

Name Description
sandbox The {@see Sandbox} instance used to create this Webtask instance

webtask.meta

Kind: instance property of Webtask
Properties

Name Description
meta The metadata associated with this webtask

webtask.secrets

Kind: instance property of Webtask
Properties

Name Description
secrets The secrets associated with this webtask if decrypt=true

webtask.code

Kind: instance property of Webtask
Properties

Name Description
code The code associated with this webtask if fetch_code=true

webtask.createLogStream(options) ⇒ Stream

Create a stream of logs from the webtask container

Note that the logs will include messages from our infrastructure.

Kind: instance method of Webtask
Returns: Stream - A stream that will emit 'data' events with container logs

Param Type Description
options Object Streaming options overrides
[options.container] String The container for which you would like to stream logs. Defaults to the current profile's container.

webtask.run(options, [cb]) ⇒ Promise

Run the webtask and return the result of execution

Kind: instance method of Webtask
Returns: Promise - - A Promise that will be resolved with the response from the server.

Param Type Description
options Object Options used to tweak how the webtask will be invoked
[cb] function Optional node-style callback that will be invoked upon completion

webtask.createCronJob(options, [cb]) ⇒ Promise

Schedule the webtask to run periodically

Kind: instance method of Webtask
Returns: Promise - - A Promise that will be resolved with a {@see CronJob} instance.

Param Type Description
options Object Options for creating the webtask
options.schedule Object Cron-string-formatted schedule
[options.name] Object The name for the cron job
[options.tz] Object The timezone for the cron job (IANA timezone)
[cb] function Optional node-style callback that will be invoked upon completion

webtask.inspect(options, [cb]) ⇒ Promise

Inspect an existing webtask to optionally get code and/or secrets

Kind: instance method of Webtask
Returns: Promise - A Promise that will be fulfilled with the result of inspecting the token.

Param Type Description
options Object Options for inspecting the webtask.
[options.decrypt] Boolean Decrypt the webtask's secrets.
[options.fetch_code] Boolean Fetch the code associated with the webtask.
[cb] function Optional callback function for node-style callbacks.

webtask.remove([cb]) ⇒ Promise

Remove the named webtask

Kind: instance method of Webtask
Returns: Promise - A Promise that will be fulfilled with the result of inspecting the token.

Param Type Description
[cb] function Optional callback function for node-style callbacks.

webtask.revoke([cb]) ⇒ Promise

Revoke the webtask's token

Kind: instance method of Webtask
Returns: Promise - A Promise that will be fulfilled with the result of revoking the token.

Param Type Description
[cb] function Optional callback function for node-style callbacks.

webtask.update([options], [cb]) ⇒ Promise

Update a webtask

Kind: instance method of Webtask
Returns: Promise - A Promise that will be fulfilled with the result of revoking the token.

Param Type Description
[options] Object Options for updating a webtask (@see: Sandbox.updateWebtask)
[cb] function Optional callback function for node-style callbacks.

webtask.updateStorage(options, storage, [cb]) ⇒ Promise

Update the storage associated to the a webtask

Kind: instance method of Webtask
Returns: Promise - A Promise that will be fulfilled with an array of Webtasks

Param Type Description
options Object Options
[options.container] String Set the webtask container. Defaults to the profile's container.
options.name String The name of the webtask.
storage Object storage
storage.data Object The data to be stored
storage.etag String Pass in an optional string to be used for optimistic concurrency control to prevent simultaneous updates of the same data.
[cb] function Optional callback function for node-style callbacks.

webtask.getStorage(options, [cb]) ⇒ Promise

Read the storage associated to the a webtask

Kind: instance method of Webtask
Returns: Promise - A Promise that will be fulfilled with an array of Webtasks

Param Type Description
options Object Options
[options.container] String Set the webtask container. Defaults to the profile's container.
options.name String The name of the webtask.
[cb] function Optional callback function for node-style callbacks.

Usages

This library will be used in wt-cli.

Contributing

Just clone the repo, run npm install and then hack away.

Issue reporting

If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.

License

MIT

What is Auth0?

Auth0 helps you to:

  • Add authentication with multiple authentication sources, either social like Google, Facebook, Microsoft Account, LinkedIn, GitHub, Twitter, Box, Salesforce, amont others, or enterprise identity systems like Windows Azure AD, Google Apps, Active Directory, ADFS or any SAML Identity Provider.
  • Add authentication through more traditional username/password databases.
  • Add support for linking different user accounts with the same user.
  • Support for generating signed Json Web Tokens to call your APIs and flow the user identity securely.
  • Analytics of how, when and where users are logging in.
  • Pull data from other sources and add it to the user profile, through JavaScript rules.

Create a free account in Auth0

  1. Go to Auth0 and click Sign Up.
  2. Use Google, GitHub or Microsoft Account to login.