Using caja to sanitize Javascript?

Question

I'd like to allow users of my application to write plugins in Javascript that extend its functionality, without allowing access to anything other than a plugin API object I provide. For example, a plugin might look like the following:

plugin.hookSomeUserAction(function() {
    plugin.doSomethingWickedAwesome();
    document.title = 'hacked!'; //shouldn't work
});

Caja looks like it should be able to get the job done, but the documentation is perhaps the worst of any open-source project I've seen (quite an accomplishment!). I need some help getting the system set up.

I've gotten the cajoler working on the command line, and I've cajoled one such plugin into some kind of hopefully sanitized Javascript. The cajoled Javascript looks like it's expecting an "IMPORTS___" object to be provided, which should contain all the stuff the plugin has access to. Pretty promising so far!

Unfortunately, getting that cajoled Javascript file to actually load and run has turned into a real mess. The source snippet in the docs is unfortunately completely wrong, as the function loadCaja doesn't actually appear anywhere in the current trunk of google-caja. I tracked down some code that at least does something:

<div id="plugin"></div>
<script>
    caja.configure({
        cajaServer: "/js/caja"
    }, function(frameGroup) {
        frameGroup.makeES5Frame(document.getElementById('plugin'),
            { /* No network access */ },
            function(frame) {
                frame.url('/js/plugins/test.js')
                    .run({});
            }
        );
    });
</script>

Unfortunately, what this does is attempt to get the cajoler to re-cajole the javascript that I've already cajoled. I definitely am not interested in having the server re-cajole every plugin on every request; I'll just cajole it upon upload and store it away ready to use.

I also can't find any documentation on how or where to specify what goes into IMPORTS___ (given that that's the whole security model, it seems like a strange oversight in documentation). Is that the object being passed into .run()?

Answer 1

Funnily enough my only knowledge of Caja comes from the angle of having read the sourcecode of SES only and having not knowledge of the context for its use. I found the source code to be incredibly well documented as opposed to whatever documentation does or doesn't exist externally.

http://code.google.com/p/es-lab/source/browse/trunk/src/ses/initSES.js