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.

.. code:: 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.

.. code:: 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.

.. code:: js

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

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