Note: This is the reference sheet version. The details and the big picture are covered in Understanding Web Security Checks in Firefox (Part 1).

Principals as a level of privilege

A security context is always using one of these four kinds of Principals:

• ContentPrincipal: This principal is used for typical web pages and can be serialized to an origin URL, e.g., https://example.com/.

• NullPrincipal: Some pages are never same-origin with anything else. E.g., <iframes sandbox> or documents loaded with a data: URI. The standard calls this an opaque origin.

• SystemPrincipal: The SystemPrincipal is used for the browser's user interface, commonly referred to as "browser chrome". Pages like about:preferences use the SystemPrincipal.

• ExpandedPrincipal: A browser extension is more privileged than normal web pages, but must also be able to assume the security context of a website. Hence, an ExpandedPrincipal is best understood as a list of principals to match the security needs for Content Scripts in Firefox Extensions. The security checks on the ExpandedPrincipal are then implemented as a loop through this allowlist of principals.

Principals to be considered during security checks

• loadingPrincipal: The principal of the document where the result of the load will be used.

• triggeringPrincipal: The security context that actually triggered the URL to load. In most cases the loadingPrincipal and the triggeringPrincipal are identical. But imagine a cross-origin CSS resource loading a background image. Here, the triggeringPrincipal is principal for the CSS file.

As an aside: There's also a StoragePrincipal: To adjust anti-tracking settings in Firefox, we can change the Principal that a document is using for storage (and related technologies) on the fly. This is achieved with a StoragePrincipal.