# Permission Manager

The Firefox permission manager offers a simple way to store user preferences
(“permissions” or “exceptions”) on a per-origin basis. On the most basic level,
a permission consists of the following:

1. The **origin** for which the permission applicable. This could for example be
   <https://example.com>.
2. The permission **type**. This can be an arbitrary string, for example “geo”
   to allow geolocation access on the specified site.
3. The permission **value**. Unless specified otherwise, this value is either
   `0` (“Undefined”), `1` (“Allow”), `2` (“Deny”) or `3` (“Prompt the user”).

For storing arbitrary preferences per origin instead of just permission values,
the {searchfox}`content pref service <dom/interfaces/base/nsIContentPrefService2.idl>`
offers a good alternative to the permission manager.

The permission manager also supports {doc}`browser-scoped (per-tab) temporary
permissions <browser-scoped>` that are not stored to disk and are automatically
cleared when their tab is closed.

The {searchfox}`site permission manager <browser/modules/SitePermissions.sys.mjs>`
builds on top of both regular and browser-scoped permissions, and makes user
interfaces easier.

## Interfacing with the Permission Manager

The permission manager can be accessed through the `nsIPermissionManager`
interface. This interface is available through the
`@mozilla.org/permissionmanager;1` service, or through the quick
`Services.perms` getter in JavaScript. Below is a list of the most common
methods, and examples on how to use them with JavaScript. For a full list of
signatures, see {searchfox}`nsIPermissionManager.idl <netwerk/base/nsIPermissionManager.idl>`.

### `testExactPermissionFromPrincipal`

Returns any possible stored permission value for a given origin and permission
type. To also find permission values if the given origin is a subdomain of the
permission's origin, use the otherwise identical `testPermissionFromPrincipal`
method.

```js
// Only construct the principal yourself if you can't get from somewhere else
// (e.g. gBrowser.contentPrincipal) directly.
let principal = Services.scriptSecurityManager.createContentPrincipalFromOrigin(
  "https://example.org"
);

let perm = Services.perms.testExactPermissionFromPrincipal(principal, "geo");
if (perm == Services.perms.ALLOW_ACTION) {
  // Do things
}
```

### `addFromPrincipal`

Adds a permission to the permission manager for a given origin, permission type
and value. Optionally, the permission can be configured to expire after the
current browsing session ends, or to expire on a given UNIX timestamp in
milliseconds.

```js
let principal = Services.scriptSecurityManager.createContentPrincipalFromOrigin(
  "https://example.org"
);

// Never expires
Services.perms.addFromPrincipal(principal, "geo", Services.perms.ALLOW_ACTION);

// Expires after the current session
Services.perms.addFromPrincipal(
  principal,
  "geo",
  Services.perms.ALLOW_ACTION,
  Services.perms.EXPIRE_SESSION
);

// Expires in 24 hours
Services.perms.addFromPrincipal(
  principal,
  "geo",
  Services.perms.ALLOW_ACTION,
  Services.perms.EXPIRE_TIME,
  Date.now() + 1000 * 60 * 60 * 24
);
```

For per-tab temporary permissions, see {doc}`browser-scoped permissions
<browser-scoped>`.

### `removeFromPrincipal`

Removes a permission from the permission manager for a given origin and
permission type.

```js
let principal = Services.scriptSecurityManager.createContentPrincipalFromOrigin(
  "https://example.org"
);

Services.perms.removeFromPrincipal(principal, "geo");
```