Principal (security)

nsIPrincipal is Gecko's security identifier — the entity on whose behalf code is running. Every Document, Window, and Channel has a principal.

Kinds

Kind	Class	Meaning
Content principal	ContentPrincipal	A web origin (https://example.com)
Null principal	NullPrincipal	A unique opaque origin (e.g., data: URLs)
System principal	SystemPrincipal	Browser chrome — full privileges
Expanded principal	ExpandedPrincipal	Multi-origin (used by extensions for content scripts)

Source: caps/.

Why it matters

Same-origin policy, CSP enforcement, cookie scoping, storage partitioning, devtools access — all of these consult the principal. Mistakes here are security bugs. The static-analysis annotations and the careful testing under caps/tests/ reflect that.

Origin attributes

In addition to the URL, principals carry OriginAttributes (caps/OriginAttributes.h) that scope storage and identity:

• userContextId — Container Tabs.
• privateBrowsingId — private windows are 1, normal are 0.
• firstPartyDomain — first-party isolation key.
• partitionKey — Total Cookie Protection partition.

Two principals match only if both their URL origin AND their OriginAttributes match.

Common APIs

nsCOMPtr<nsIPrincipal> p;
NS_NewURI(getter_AddRefs(uri), "https://example.com");
NS_NewContentPrincipal(getter_AddRefs(p), uri, originAttributes);

// Same-origin check
bool sameOrigin = p1->Equals(p2);

// Check that we're privileged
if (p->IsSystemPrincipal()) { ... }

Related

• DOM
• Security