Quelle  nsIPermissionManager.idl

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

/**
 * This file contains an interface to the Permission Manager,
 * used to persistenly store permissions for different object types (cookies,
 * images etc) on a site-by-site basis.
 *
 * This service broadcasts the following notification when the permission list
 * is changed:
 *
 * topic  : "perm-changed" (PERM_CHANGE_NOTIFICATION)
 *          broadcast whenever the permission list changes in some way. there
 *          are four possible data strings for this notification; one
 *          notification will be broadcast for each change, and will involve
 *          a single permission.
 * subject: an nsIPermission interface pointer representing the permission object
 *          that changed.
 * data   : "deleted"
 *          a permission was deleted. the subject is the deleted permission.
 *          "added"
 *          a permission was added. the subject is the added permission.
 *          "changed"
 *          a permission was changed. the subject is the new permission.
 *          "cleared"
 *          the entire permission list was cleared. the subject is null.
 */

#include "nsISupports.idl"

interface nsIPrincipal;
interface nsIPermission;

[scriptable, builtinclass, uuid(4dcb3851-eba2-4e42-b236-82d2596fca22)]
interface nsIPermissionManager : nsISupports
{
  /**
   * Predefined return values for the testPermission method and for
   * the permission param of the add method
   * NOTES:
   *
   * UNKNOWN_ACTION (0) is reserved to represent the
   * default permission when no entry is found for a host, and
   * should not be used by consumers to indicate otherwise.
   * If no other entries are found, it translates into "prompt"
   * in the permissions.query() API.
   *
   * PROMPT_ACTION (3) is not persisted for most permissions.
   * Except for camera and microphone, where persisting it means
   * "Always Ask" (the user leaves "☐ Remember this decision"
   * unchecked in the permission grant). It translates into
   * "granted" in permissions.query() to prevent websites from
   * asking users to escalate permissions further.
   *
   * MAX_VALID_ACTION is the highest value (used to validate prefs)
   */
  const uint32_t UNKNOWN_ACTION = 0;
  const uint32_t ALLOW_ACTION = 1;
  const uint32_t DENY_ACTION = 2;
  const uint32_t PROMPT_ACTION = 3;
  const uint32_t MAX_VALID_ACTION = 3;

  /**
   * Predefined expiration types for permissions.  Permissions can be permanent
   * (never expire), expire at the end of the session, or expire at a specified
   * time. Permissions that expire at the end of a session may also have a
   * specified expiration time.
   *
   * EXPIRE_POLICY is a special expiration status. It is set when the permission
   * is set by reading an enterprise policy. These permissions cannot be overridden.
   */
  const uint32_t EXPIRE_NEVER = 0;
  const uint32_t EXPIRE_SESSION = 1;
  const uint32_t EXPIRE_TIME = 2;
  const uint32_t EXPIRE_POLICY = 3;
  const uint32_t EXPIRE_SESSION_TAB = 4;


  /**
   * Get all custom permissions for a given nsIPrincipal. This will return an
   * enumerator of all permissions which are not set to default and which
   * belong to the matching principal of the given nsIPrincipal.
   *
   * @param principal  the URI to get all permissions for
   */
  Array<nsIPermission> getAllForPrincipal(in nsIPrincipal principal);

  /**
   * Get all custom permissions of a specific type, specified with a prefix
   * string.  This will return an array of all permissions which are not set to
   * default.  Also the passed type argument is either equal to or a prefix of
   * the type of the returned permissions.
   *
   * @param prefix  the type prefix string
   */
  Array<nsIPermission> getAllWithTypePrefix(in ACString prefix);


  /**
   * Get all custom permissions whose type exactly match one of the types defined
   * in the passed array argument.
   * This will return an array of all permissions which are not set to default.
   *
   * @param types  an array of case-sensitive ASCII strings, identifying the
   *               permissions to be matched.
   */
  Array<nsIPermission> getAllByTypes(in Array<ACString> types);

  /**
   * Get all custom permissions of a specific type and that were modified after
   * the specified date. This will return an array of all permissions which are
   * not set to default.
   *
   * @param type    a case-sensitive ASCII string, identifying the permission.
   * @param since   a unix timestamp representing the number of milliseconds from
   *                Jan 1, 1970 00:00:00 UTC.
   */
  Array<nsIPermission> getAllByTypeSince(in ACString type, in int64_t since);

  /**
   * Add permission information for a given principal.
   * It is internally calling the other add() method using the nsIURI from the
   * principal.
   * Passing a system principal will be a no-op because they will always be
   * granted permissions.
   */
  void addFromPrincipal(in nsIPrincipal principal, in ACString type,
                        in uint32_t permission,
                        [optional] in uint32_t expireType,
                        [optional] in int64_t expireTime);

  /**
   * Test method to add a permission for a given principal with custom modification time.
   */
  void testAddFromPrincipalByTime(in nsIPrincipal principal, in ACString type,
    in uint32_t permission,
    in int64_t modificationTime
  );

  /**
   * Add permanent permission information for a given principal in private
   * browsing.
   *
   * Normally permissions in private browsing are cleared at the end of the
   * session, this method allows you to override this behavior and set
   * permanent permissions.
   *
   * WARNING: setting permanent permissions _will_ leak data in private
   * browsing. Only use if you understand the consequences and trade-offs. If
   * you are unsure, |addFromPrincipal| is very likely what you want to use
   * instead.
   */
  void addFromPrincipalAndPersistInPrivateBrowsing(in nsIPrincipal principal,
                                                   in ACString type,
                                                   in uint32_t permission);

  /**
   * Add temporary default permission information for a given principal.
   * This permission will be cleared at the end of the session, will not be
   * stored on disk, and will not be set if a conflicting (non-default)
   * permission already exists.
   *
   * This function shouldn't be used by regular permission manager consumers and
   * is only expected to be called by the RemotePermissionService.sys.mjs for
   * the purpose of importing default permissions from remote settings.
   */
  void addDefaultFromPrincipal(in nsIPrincipal principal,
                               in ACString type,
                               in uint32_t permission);

  /**
   * Remove permission information for a given principal.
   * This is internally calling remove() with the host from the principal's URI.
   * Passing system principal will be a no-op because we never add them to the
   * database.
   */
  void removeFromPrincipal(in nsIPrincipal principal, in ACString type);

  /**
   * Remove the given permission from the permission manager.
   *
   * @param perm   a permission obtained from the permission manager.
   */
  void removePermission(in nsIPermission perm);

  /**
   * Clear permission information for all websites.
   */
  void removeAll();

  /**
   * Clear all permission information added since the specified time.
   */
  void removeAllSince(in int64_t since);

  /**
   * Clear all permissions of the passed type.
   */
  void removeByType(in ACString type);

  /**
   * Clear all permissions not of the passed types.
   */
  void removeAllExceptTypes(in Array<ACString> typeExceptions);

  /**
   * Clear all permissions of the passed type added since the specified time.
   * @param type    a case-sensitive ASCII string, identifying the permission.
   * @param since   a unix timestamp representing the number of milliseconds from
   *                Jan 1, 1970 00:00:00 UTC.
   */
  void removeByTypeSince(in ACString type, in int64_t since);

  /**
   * Clear all permissions of the passed types added since the specified time.
   * @param since   a unix timestamp representing the number of milliseconds from
   *                Jan 1, 1970 00:00:00 UTC.
   * @param typeExceptions    a array of case-sensitive ASCII strings, identifying
   *                          the types to not remove.
   */
  void removeAllSinceWithTypeExceptions(in int64_t since, in Array<ACString> typeExceptions);

  /**
   * Test whether the principal has the permission to perform a given action.
   * System principals will always have permissions granted.
   * This function will perform a pref lookup to permissions.default.<type>
   * if the specific permission type is part of the whitelist for that functionality.
   */
  uint32_t testPermissionFromPrincipal(in nsIPrincipal principal,
                                       in ACString type);

  /**
   * Test whether the principal has the permission to perform a given action.
   * This requires an exact hostname match. Subdomain principals do not match
   * permissions of base domains.
   * System principals will always have permissions granted.
   * This function will perform a pref lookup to permissions.default.<type>
   * if the specific permission type is part of the whitelist for that functionality.
   */
  uint32_t testExactPermissionFromPrincipal(in nsIPrincipal principal,
                                            in ACString type);

  /**
   * Test whether a website has permission to perform the given action
   * ignoring active sessions.
   * System principals will always have permissions granted.
   * This function will perform a pref lookup to permissions.default.<type>
   * if the specific permission type is part of the whitelist for that functionality.
   *
   * @param principal the principal
   * @param type      a case-sensitive ASCII string, identifying the consumer
   * @param return    see add(), param permission. returns UNKNOWN_ACTION when
   *                  there is no stored permission for this uri and / or type.
   */
  uint32_t testExactPermanentPermission(in nsIPrincipal principal,
                                        in ACString type);

  /**
   * Get the permission object associated with the given principal and action.
   * @param principal The principal
   * @param type      A case-sensitive ASCII string identifying the consumer
   * @param exactHost If true, only the specific host will be matched.
   *                  If false, base domains of the principal will also
   *                  be searched.
   * @returns The matching permission object, or null if no matching object
   *          was found. No matching object is equivalent to UNKNOWN_ACTION.
   * @note Clients in general should prefer the test* methods unless they
   *       need to know the specific stored details.
   * @note This method will always return null for the system principal.
   */
  nsIPermission getPermissionObject(in nsIPrincipal principal,
                                    in ACString type,
                                    in boolean exactHost);

  /**
   * Returns all stored permissions.
   * @return an array of nsIPermission objects
   */
  readonly attribute Array<nsIPermission> all;

  /**
   * Remove all permissions that will match the origin pattern.
   * @param patternAsJSON    Origin pattern to match.
   * @param typeInclusions   Types to include in search. If empty, includes all types.
   * @param typeExceptions   Types to skip in search.
   */
  void removePermissionsWithAttributes(in AString patternAsJSON, in Array<ACString> typeInclusions, in Array<ACString> typeExceptions);

  /**
   * Update the last interaction time for a given principal's origin.
   * Used to track site activity for permission expiration.
   *
   * @param principal The principal representing the site the user interacted with.
   */
  void updateLastInteractionForPrincipal(in nsIPrincipal principal);

  /**
   * Remove interaction records from the moz_origin_interactions table
   * that no longer have corresponding permissions.
   *
   * Orphaned interaction records are automatically cleaned up on
   * idle-daily, so this method only needs to be called when cleanup
   * must happen immediately (e.g. data clearing via nsIClearDataService)
   * to ensure tracking data is removed before returning to the caller.
   *
   * Not needed after bulk removal methods (removeAll, removeByType, etc.)
   * which handle cleanup internally.
   */
  [implicit_jscontext]
  Promise removeOrphanedInteractionRecords();

  /**
   * Test-only method. Flush all pending background-thread writes and resolve
   * the returned promise once complete. This does not modify any data.
   */
  [implicit_jscontext]
  Promise testFlushPendingWrites();

  /**
   * Add a permission scoped to a specific browser (tab).
   * For DENY_ACTION, the permission is keyed by site (baseDomain).
   * For all other actions, keyed by origin.
   * expireTimeMS is milliseconds from now until expiry (not absolute timestamp).
   */
  void addFromPrincipalForBrowser(
      in nsIPrincipal principal,
      in ACString type,
      in uint32_t permission,
      in uint64_t browserId,
      [optional] in int64_t expireTimeMS);

  /**
   * Remove a browser-scoped permission for the given principal, type, and
   * browser. Tries both origin-scoped and site-scoped keys.
   *
   * @param principal   The principal for the permission.
   * @param type        The permission type string.
   * @param browserId   The id of the browser (tab).
   */
  void removeFromPrincipalForBrowser(
      in nsIPrincipal principal,
      in ACString type,
      in uint64_t browserId);

  /**
   * Remove all browser-scoped permissions for a given browser (tab).
   *
   * @param browserId   The id of the browser (tab).
   */
  void removeAllForBrowser(
      in uint64_t browserId);

  /**
   * Remove all browser-scoped permissions with the given action for a browser.
   *
   * @param browserId   The id of the browser (tab).
   * @param permission  The action (e.g. DENY_ACTION) to filter by.
   */
  void removeByActionForBrowser(
      in uint64_t browserId,
      in uint32_t permission);

  /**
   * Test for a browser-scoped permission. Returns the permission action
   * (e.g. ALLOW_ACTION, DENY_ACTION) or UNKNOWN_ACTION if not set.
   * Origin-scoped permissions are checked before site-scoped ones.
   *
   * @param principal   The principal to test.
   * @param type        The permission type string.
   * @param browserId   The id of the browser (tab).
   */
  uint32_t testForBrowser(
      in nsIPrincipal principal,
      in ACString type,
      in uint64_t browserId);

  /**
   * Get a browser-scoped permission as an nsIPermission object.
   * Returns null if not set. Origin-scoped permissions are checked before
   * site-scoped ones.
   *
   * @param principal   The principal to look up.
   * @param type        The permission type string.
   * @param browserId   The id of the browser (tab).
   */
  nsIPermission getForBrowser(
      in nsIPrincipal principal,
      in ACString type,
      in uint64_t browserId);

  /**
   * Get all browser-scoped permissions for a given principal and browser,
   * returned as an array of nsIPermission objects.
   *
   * @param principal   The principal to match.
   * @param browserId   The id of the browser (tab).
   */
  Array<nsIPermission> getAllForBrowser(
      in nsIPrincipal principal,
      in uint64_t browserId);

  /**
   * Copy all browser-scoped permissions from one browser to another.
   * Used during tab-swapping operations.
   *
   * @param srcBrowserId   The source BrowserId to copy from.
   * @param destBrowserId  The destination BrowserId to copy to.
   */
  void copyBrowserPermissions(
      in uint64_t srcBrowserId,
      in uint64_t destBrowserId);
};

%{ C++
#define NS_PERMISSIONMANAGER_CONTRACTID "@mozilla.org/permissionmanager;1"

#define PERM_CHANGE_NOTIFICATION "perm-changed"
#define BROWSER_PERM_CHANGE_NOTIFICATION "browser-perm-changed"
%}