permission-manager.js

/**
 * A simple module to use the permission manager
 * @module permission-manager
 * @see {@link https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIPermissionManager}
 */
"use strict";

/**
 * @external nsISimpleEnumerator
 * @see {@link https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsISimpleEnumerator}
 */
/**
 * @external nsIPermission
 * @see {@link https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIPermission}
 */

const { Services: { perms: permissionManager } } = require("resource://gre/modules/Services.jsm");
const { Ci } = require("chrome");
const { NetUtil } = require("resource://gre/modules/NetUtil.jsm");

/*
 * Known Permission Types:
 * "popup": for showing pop-ups
 */

module.exports = {
  /**
   * Adds a permission
   * @argument {string} uri
   * @argument {string} type
   * @argument {number} permission
   * @argument {number} expireType
   * @argument {number} expireTime - A timestamp indicating the expiration time
   * @throws if uri is an invalid URI.
   * @see {@link https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIPermissionManager#add%28%29}
   */
  add(uri, type, permission, expireType, expireTime) {
    permissionManager.add(NetUtil.newURI(uri), type, permission, expireType, expireTime);
  },
  /**
   * Removes a permission
   * @argument {string} host
   * @argument {string} type
   * @see {@link https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIPermissionManager#remove%28%29}
   */
  remove(host, type) {
    permissionManager.remove(host, type);
  },
  /**
   * Removes all permissions.
   * @see {@link https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIPermissionManager#removeAll%28%29}
   */
  removeAll() {
    permissionManager.removeAll();
  },
  /**
   * Tests if the URI has the permission to do that, however it has to match exactly (including subdomain).
   * @argument {string} uri
   * @argument {string} type
   * @return {number} The permission the site has ({@link module:permission-manager.ACTION})
   * @throws if uri is an invalid URI.
   * @see {@link https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIPermissionManager#testExactPermission%28%29}
   */
  testExactPermission(uri, type) {
    return permissionManager.testExactPermission(NetUtil.newURI(uri), type);
  },
  /**
   * Test if a site has the permission to use something.
   * @argument {string} uri
   * @argument {string} type
   * @return {number} The permission the site has ({@link module:permission-manager.ACTION})
   * @throws if uri is an invalid URI.
   * @see {@link https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIPermissionManager#testPermission%28%29}
   */
  testPermission(uri, type) {
    return permissionManager.testPermission(NetUtil.newURI(uri), type);
  },
  /**
   * @type {external:nsISimpleEnumerator.<external:nsIPermission>}
   */
  get enumerator() {
    return permissionManager.enumerator;
  },
  /**
   * The kind of allowance a site has for a permission
   * @type {Object.<string, number>}
   */
  ACTION: Object.freeze({
    UNKNOWN: Ci.nsIPermissionManager.UNKNOWN_ACTION,
    ALLOW: Ci.nsIPermissionManager.ALLOW_ACTION,
    DENY: Ci.nsIPermissionManager.DENY_ACTION,
    PROMPT: Ci.nsIPermissionManager.PROMPT_ACTION
  }),
  /**
   * When the permission grant expires.
   * @type {Object.<string, number>}
   */
  EXPIRE: Object.freeze({
    NEVER: Ci.nsIPermissionManager.EXPIRE_NEVER,
    SESSION: Ci.nsIPermissionManager.EXPIRE_SESSION,
    TIME: Ci.nsIPermissionManager.EXPIRE_TIME
  })
};