Sylvestre Ledru
bded669825
Convert extensions/permissions/docs and extensions/spellcheck/docs RST files to MyST-flavored Markdown. Update write_a_patch :ref: target to the explicit (write-a-patch)= MyST anchor. Differential Revision: https://phabricator.services.mozilla.com/D304224
103 lines
3.5 KiB
Markdown
103 lines
3.5 KiB
Markdown
# 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");
|
|
```
|