If you're not familiar with the SecurableModule standard, please do so now by following the aforementioned link; it's an extremely short specification.
<b>Chrome Boosters</b> are a superset of the SecurableModule standard that solve some issues specific to the Mozilla platform, and are intended to be used from both Jetpack Features and XULRunner extensions (e.g., Firefox/Thunderbird add-ons). Our hope is that, aside from solving the aforementioned problems, this module system will enable code-sharing between Jetpack developers, Add-on developers, web developers, and the greater JavaScript community as a whole.
As their name implies, Chrome Boosters are can be created with either a content principal or the system (chrome-privileged and can use dependency injection ) principal. It's possible for Boosters with content principals to offer functionality to non-chrome-privileged Jetpacks—orimport Boosters with system principals, if used in a XULRunner extension, they can be used to provide functionality to other chrome-privileged codewhich case the appropriate XPConnect wrapping will automatically occur.
Once we have a substrate of Chrome Boosters available, we'll be able to create "Content Boosters" that consist solely of unprivileged functionality that itself relies on capabilities provided to them via Chrome Boosters. These modules essentially formalize the mechanism used within Jetpack to provide the <tt>jetpack</tt> namespace to Jetpacks. Chrome Boosters have the following characteristics:
* They are a superset of the CommonJS SecurableModule standard.
* They can be loaded and unloaded multiple times throughout the lifetime of their containing application (yes, leaks are an unfortunate possibility).
* They have If created with the ability to register callbacks that perform cleanup tasks when unloaded.* They system principal, they have full access to XPConnect's <tt>Components</tt> object, and all its sub-objects.
When used in a XULRunner extension, the Chrome Booster framework should have the following additional characteristics:
* Adding Chrome Booster functionality to an existing XULRunner extension should be as painless as possible; ideally, it should consist merely of adding a single script, <tt>booster.js</tt>, and any desired SecurableModule files.
* Using <tt>booster.js</tt> should be just as easy in both a chrome-privileged document and a [https://developer.mozilla.org/en/Using_JavaScript_code_modules JS module] (not to be confused with a SecurableModule).
For Note that for security purposes, Chrome Boosters can with chrome privileges should only be accessed either
* locally, through a containing addon, or
* over secure HTTP to a trusted host.
Additionally, to encourage good coding practices and documentation, Chrome The following are outside the scope of Boosters must have:
* A simple, straightforward mechanism for writing and executing test cases.
* An easy-to-learn documentation system capable of producing beautiful documentation.
* A mechanism for tracking objects of interest belonging to the Chrome Booster to aid in memory profiling and leak detection.
* Registering callbacks that perform cleanup tasks when modules are unloaded.
== Code Examples ==
This code doesn't necessarily work; it's just aspirational.
=== Jetpack Feature ===
Using Chrome Boosters from a Jetpack Feature is just like using them in any CommonJS-supported environment; the Jetpack runtime takes care of initializing the Chrome Booster framework when a Jetpack Feature is loaded, providing all necessary global functions to the Feature's global scope, and unloading the Chrome Boosters when the Feature is unloaded.
<pre class="brush:js;">
var foo = require('foo');
jetpack.notifications.show("Hello " + foo.bar());
</pre>
=== Chrome Booster, exporting to chrome-privileged code ===
Creating a chrome booster that exports its functionality to chrome-privileged code follows the CommonJS standard for SecurableModules.
<pre class="brush:js;">
exports.bar = function bar() {
return "hello there";
}
</pre>
=== XULRunner extension, in a chrome-privileged document ===
have any pressing reason to, since JS modules themselves are never
unloaded.
=== Chrome Booster, exporting to a Jetpack Feature ===
A Chrome Booster can use the forthcoming [[XPConnect Chrome Object Wrapper]] protocol to decide which properties it wants to export to untrusted or semi-trusted Jetpack code.
<pre class="brush:js;">
exports.foo = {
__exposedProps__ = {bar: 'r'},
bar: function bar() { /* ... */ },
baz: 5
};
</pre>
In the above case, <tt>foo.bar()</tt> will be readable (but not writable) from Jetpacks that import the above module via a call to <tt>require()</tt>, but <tt>foo.baz</tt> will not be accessible at all.
=== Chrome Booster, exporting to a Jetpack Feature with capabilities ===
If a Jetpack Feature has capabilities associated with it, a Chrome Booster should be able to introspect into them and provide attenuated functionality based on said capabilities:
<pre class="brush:js;">
var caps = require('capabilities');
exports.foo = {
__exposedProps__ = {bar: 'r'},
bar: function bar() {
if (caps.has('file:read')) {
var fileObj = getSomeFile();
if (caps.has('file:write')) {
return fileObj;
}
return fileObj.makeReadOnly();
}
throw new SecurityError('Permission denied.');
},
baz: 5
};
</pre>
Exactly how capabilities are specified for a Feature—e.g., whether done explicitly by Feature authors or implicitly via static analysis—is outside the scope of this document.
Exactly ''what'' capabilities are available in the Jetpack platform is also outside of the scope of this document, suffice to say that they will likely be developed organically: since the community will be creating Chrome Boosters that expose chrome functionality to semi-trusted content, we'll need to work together to figure out what the best capabilities are as the library of functionality is developed.
=== XULRunner extension, sandboxing code ===
It's possible to use the Chrome Booster framework API to load semi-trusted code the same way that Jetpack does. While this probably won't be needed in most cases for extensions, it's still a potentially nice way to sandbox an extension to follow the principle of least privilege. It's conceivable that this could also lead to quicker AMO reviews: if the vast majority of an extension runs in a sandbox and uses trusted, secure Chrome Boosters, then it should be easier for a reviewer to verify that the extension isn't insecure.
<pre class="brush:js;">
var SecurableModule = {};
Components.utils.import("resource://some_extension/content/booster.js",
SecurableModule);
var loader = SecurableModule.Loader({
rootPath: "chrome://some_extension/content/lib/"
});
loader.runScript({content: "require('foo').bar();",
capabilities: ["file:read"]});
</pre>
== Reference Implementation ==
