1. Introduction

To enable the content policy:

require("content-policy");

2. content_policy_scheme_whitelist

This variable points to a structure whose keys are uri schemes to automatically whitelist. The default value contains 'about', 'chrome', 'data', 'javascript', and 'moz-icon', which prevents you from blacklisting urls of those schemes in your content_policy_hook. Some of these are there because they provide vital functionality to the program, so it would be an error to block them (about, chrome). Others are there because it is a sensible base case, and simplifies the writing of content policy hook funcions in the majority of cases. So while we document this variable here for completeness, for all practical purposes you can ignore it.

3. content_policy_hook

Content policy actions like blacklisting and whitelisting are implemented through content_policy_hook. This is a run-until-success hook, meaning that each function on the hook will be tried in turn until one of them returns a true value. If none of the hook functions return a true value, then the request is allowed. See below in the section on return values for details. The DOM may be in an inconsistent state when this hook is run, therefore functions in this hook must not modify the DOM, query DOM properties outside of context, or query DOM properties that depend on layout or style. If you need to modify the DOM, do so in a timeout or a later event.

3.1. Arguments

Hook functions are called with the following arguments.

content_type

integer (1: other, 2: script, 3: image, 4: stylesheet, 5: object, 6: document, 7: subdocument, 9: xbl, 10: ping, 11: xmlhttprequest, 12: object_subrequest, 13: dtd, 14: font, 15: media) Type 8 will never occur. If your content-policy is primarily dispatched on the content_type, your work can be simplified by using the provided content_policy_bytype function, described in the next section.

content_location

nsIURI

request_origin

nsIURI; what is this?

context

what is this?

mime_type_guess

string

extra

3.2. Return Values

The following constants are provided for such hook functions:

content_policy_reject

Blacklist (deny the request)

content_policy_accept

Whitelist (allow the request)

In summary, if you want to whitelist a request, have your function return content_policy_accept. If you want to stop a request, have your function return content_policy_reject. Otherwise return null and the next content_policy_hook function, if any, will be tried.

4. Provided Hook Functions

The content-policy module provides some pre-written filtering algorithms which abstract common patterns for easier configuration.

4.1. By Type Filtering

To enable by-type filtering:

add_hook("content_policy_hook", content_policy_bytype);

4.1.1. content_policy_bytype_table

By-type filtering is configured in content_policy_bytype_table. The table has 14 named slots for the 14 content types. Each slot can be set to a content_policy_hook function to be called by content_policy_bytype when a request of that type comes through. The 14 types are, (1: other, 2: script, 3: image, 4: stylesheet, 5: object, 6: document, 7: subdocument, 9: xbl, 10: ping, 11: xmlhttprequest, 12: object_subrequest, 13: dtd, 14: font, 15: media). Note the absence of number 8. It will never occur.

5. Interactive Commands

Application of the content-policy can be enabled and disabled with the two interactive commands content-policy-enable and content-policy-disable.

6. Examples

6.1. Block Flash, with Host Whitelist

In fact this blocks all plugin content, not just flash applets, but who's counting?

require("content-policy.js");

function block_flash (content_type, content_location) {
    var Y = content_policy_accept, N = content_policy_reject;
    var action = ({ "homestarrunner.com":Y }
                  [content_location.host] || N);
    if (action == N)
        dumpln("blocked flash: "+content_location.spec);
    return action;
}
content_policy_bytype_table.object = block_flash;
add_hook("content_policy_hook", content_policy_bytype);

6.2. Print Flash Video URLs to Console

Scrapers do not always work for downloading media whose origin is obfuscated by a Flash (or other plugin) wrapper, but you can use content-policy to obtain the URLs requested by plugins. This example uses a couple of regular expression filters to limit what URLs will be reported so-as not to flood the console with information; these filters can be easily adjusted.

Note, this will have no effect if you are also blocking flash per the previous example.

require("content-policy.js");

function watch_flash_requests (content_type, content_location) {
    var url = content_location.spec;
    //dumpln("FLASHREQUEST: "+content_location.spec);
    if (url.match(/[0-9a-f]{32,32}/) ||
        url.match(/avi|flv|mp4|wmv|start=/))
    {
        dumpln("VIDEO? "+content_location.spec);
        return content_policy_reject;
    }
    return content_policy_accept;
}
content_policy_bytype_table.object_subrequest = watch_flash_requests;
add_hook("content_policy_hook", content_policy_bytype);

6.3. Block Images

This is a very simple image blocker. If you use this, you can still navigate directly to an image to view it.

require("content-policy.js");

content_policy_bytype_table.image = function () content_policy_reject;
add_hook("content_policy_hook", content_policy_bytype);