=============================
About SpiderMonkey Playground
=============================

This is a simple C/C++ command-line program that experiments with the
SpiderMonkey JavaScript engine.

File Layout
-----------

pavement.py                    Paver [1] script to build binaries.

sample-module.js               Sample SecurableModule.

tcb.js                         Trusted Code Base script.

server-socket.cpp/h            Simple native implementation of a JS socket
                               object.

memory_profiler.cpp/h          Native memory profiling functionality.

memory_profiler_server.js      Script to provide a RESTful web service
                               exposing memory profiling data about another
                               JS runtime.

wrapper.cpp/h                  Native implementation of JS wrapper/membrane.

spidermonkey-playground.cpp/h  Main executable embedding SpiderMonkey and
                               implementing many global JS functions.

[1] http://www.blueskyonmars.com/projects/paver/

Usage
-----

(1) Modify pavement.py to your needs--it currently requires a full
    build of Mozilla somewhere on your system, which is unfortunate,
    but SpiderMonkey 1.8/1.8.1 hasn't yet been released as standalone.

(2) Build the binaries by running 'paver'.

(3) Run 'spidermonkey-playground'. Right now the executable just runs
    some tests and starts the memory profiling server at the very end.

Security Experimentation
------------------------

To experiment with security, we expose a number of the JSAPI's
functions [1] to a Trusted Code Base written in JS.  The goal here is
to provide developers with an easy way to explore and experiment with
JavaScript security models in a high-level language before actually
implementing one in C/C++.

The playground currently includes a highly experimental implementation
of SecurableModules [2] that allows for the exportation of
functionality to a module via require(). It also includes a "membrane"
or "wrapper" [3] implementation that allows secure membranes to be
implemented entirely in JavaScript.  It's really just an exposing of
SpiderMonkey's JSClass/JSExtendedClass [4] to JavaScript, but it
should allow for pretty flexible enforcement of any kind of desired
security characteristic, from an Object-Capability Model like that of
Google Caja [5] to a read-only representation of a DOM structure.

[1] https://developer.mozilla.org/en/SpiderMonkey
[2] https://wiki.mozilla.org/ServerJS/Modules/SecurableModules
[3] https://developer.mozilla.org/en/XPConnect_wrappers
[4] https://developer.mozilla.org/en/SpiderMonkey/JSAPI_Reference/JSClass
[5] http://code.google.com/p/google-caja/

Memory Profiling Experimentation
--------------------------------

A prototype implementation of a memory profiling web server providing
a REST API to the state of a frozen JS runtime is also provided.  The
actual server is written using JavaScript, and runs in a separate
JS runtime from the frozen one that it exposes.