XPConnect Chrome Object Wrappers

Introduction

Chrome Object Wrappers, or COWs for short, allow privileged code to securely expose some subset of its functionality to untrusted or semi-trusted content.

The COW is actually the final step in an epic quest to make the interaction between chrome and content as natural and secure as possible by encasing JavaScript objects in "membranes" that mediate access between their object and the outside world. Before reading the rest of this document, you should be familiar with the story so far, which is explained in detail at XPConnect wrappers.

Usage

COWs are always created automatically whenever an object passes through a trust boundary. For instance, assume the following chrome-privileged code:

const Cu = Components.utils;

function foo(obj) {
  /* Do something here that requires chrome privileges. */
}
foo.__callableByContent__ = true;

var sandbox = Cu.Sandbox("http://www.mozilla.org");
sandbox.foo = foo;
var result = Cu.evalInSandbox("foo({bar: 5});");

In the above example, foo() is wrapped by a COW when accessed by sandboxed code executed via Components.utils.evalInSandbox(). The object {bar: 5} is wrapped in an XPCSafeJSObjectWrapper before being passed into foo().

The metadata attached to foo(), __callableByContent__, is used to explicitly declare that the function its attached to can be called from content. This is necessary for security purposes; if a function that's only ever intended to be called from trusted code ever accidentally "falls into the wrong hands", we don't want untrusted code to be able to exploit it.