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;

var sandbox = Cu.Sandbox("http://www.mozilla.org");
sandbox.foo = Cu.exposeToContent(function foo(x) { /* ... */ });
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(), and whatever is returned from foo() and placed in result is usually wrapped in a COW as well.