dom/chrome-webidl/WebExtensionPolicy.webidl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 interface URI;
   6 interface WindowProxy;
   7
   8 callback WebExtensionLocalizeCallback = DOMString (DOMString unlocalizedText);
   9
  10 /**
  11  * Defines the platform-level policies for a WebExtension, including its
  12  * permissions and the characteristics of its moz-extension: URLs.
  13  */
  14 [ChromeOnly, Exposed=Window]
  15 interface WebExtensionPolicy {
  16   [Throws]
  17   constructor(WebExtensionInit options);
  18
  19   /**
  20    * The add-on's internal ID, as specified in its manifest.json file or its
  21    * XPI signature.
  22    */
  23   [Constant, StoreInSlot]
  24   readonly attribute DOMString id;
  25
  26   /**
  27    * The hostname part of the extension's moz-extension: URLs. This value is
  28    * generated randomly at install time.
  29    */
  30   [Constant, StoreInSlot]
  31   readonly attribute ByteString mozExtensionHostname;
  32
  33   /**
  34    * The file: or jar: URL to use for the base of the extension's
  35    * moz-extension: URL root.
  36    */
  37   [Constant]
  38   readonly attribute ByteString baseURL;
  39
  40   /**
  41    * The extension's user-visible name.
  42    */
  43   [Constant]
  44   readonly attribute DOMString name;
  45
  46   /**
  47    * The add-on's internal type as determined by parsing the manifest.json file.
  48    */
  49   [Constant]
  50   readonly attribute DOMString type;
  51
  52   /**
  53    * Whether the extension has access to privileged features
  54    */
  55   [Constant]
  56   readonly attribute boolean isPrivileged;
  57
  58   /**
  59    * Whether the extension is installed temporarily
  60    */
  61   [Constant]
  62   readonly attribute boolean temporarilyInstalled;
  63
  64   /**
  65    * The manifest version in use by the extension.
  66    */
  67   [Constant]
  68   readonly attribute unsigned long manifestVersion;
  69
  70   /**
  71    * The base content security policy string to apply on extension
  72    * pages for this extension.  The baseCSP is specific to the
  73    * manifest version.  If the manifest version is 3 or higher it
  74    * is also applied to content scripts.
  75    */
  76   [Constant]
  77   readonly attribute DOMString baseCSP;
  78
  79   /**
  80    * The content security policy string to apply to all pages loaded from the
  81    * extension's moz-extension: protocol.  If one is not provided by the
  82    * extension the default value from preferences is used.
  83    * See extensions.webextensions.default-content-security-policy.
  84    */
  85   [Constant]
  86   readonly attribute DOMString extensionPageCSP;
  87
  88   /**
  89    * The list of currently-active permissions for the extension, as specified
  90    * in its manifest.json file. May be updated to reflect changes in the
  91    * extension's optional permissions.
  92    */
  93   [Cached, Frozen, Pure]
  94   attribute sequence<DOMString> permissions;
  95
  96   /**
  97    * Match patterns for the set of web origins to which the extension is
  98    * currently allowed access. May be updated to reflect changes in the
  99    * extension's optional permissions.
 100    */
 101   [Pure]
 102   attribute MatchPatternSet allowedOrigins;
 103
 104   /**
 105    * The set of content scripts active for this extension.
 106    */
 107   [Cached, Frozen, Pure]
 108   readonly attribute sequence<WebExtensionContentScript> contentScripts;
 109
 110   /**
 111    * True if the extension is currently active, false otherwise. When active,
 112    * the extension's moz-extension: protocol will point to the given baseURI,
 113    * and the set of policies for this object will be active for its ID.
 114    *
 115    * Only one extension policy with a given ID or hostname may be active at a
 116    * time. Attempting to activate a policy while a conflicting policy is
 117    * active will raise an error.
 118    */
 119   [Affects=Everything, SetterThrows]
 120   attribute boolean active;
 121
 122   /**
 123    * True if this extension is exempt from quarantine.
 124    */
 125   [Cached, Pure]
 126   attribute boolean ignoreQuarantine;
 127
 128   /**
 129    * True if both e10s and webextensions.remote are enabled.  This must be
 130    * used instead of checking the remote pref directly since remote extensions
 131    * require both to be enabled.
 132    */
 133   static readonly attribute boolean useRemoteWebExtensions;
 134
 135   /**
 136    * True if the calling process is an extension process.
 137    */
 138   static readonly attribute boolean isExtensionProcess;
 139
 140   /**
 141    * Whether the background.service_worker in the extension manifest.json file
 142    * is enabled.
 143    *
 144    * NOTE: **do not use Services.prefs to retrieve the value of the undelying pref**
 145    *
 146    * It is defined in StaticPrefList.yaml as `mirror: once` and so checking
 147    * its current value using Services.prefs doesn't guarantee that it does
 148    * match the value as accessible from the C++ layers, and unexpected issue
 149    * may be possible if different code has a different idea of its value.
 150    */
 151   static readonly attribute boolean backgroundServiceWorkerEnabled;
 152
 153   /**
 154    * Whether the Quarantined Domains feature is enabled.  Use this as a single
 155    * source of truth instead of checking extensions.QuarantinedDomains.enabled
 156    * pref directly because the logic might change.
 157    */
 158   static readonly attribute boolean quarantinedDomainsEnabled;
 159
 160   /**
 161    * Set based on the manifest.incognito value:
 162    * If "spanning" or "split" will be true.
 163    * If "not_allowed" will be false.
 164    */
 165   [Pure]
 166   readonly attribute boolean privateBrowsingAllowed;
 167
 168   /**
 169    * Returns true if the extension can access a window.  Access is
 170    * determined by matching the windows private browsing context
 171    * with privateBrowsingMode.  This does not, and is not meant to
 172    * handle specific differences between spanning and split mode.
 173    */
 174   [Affects=Nothing]
 175   boolean canAccessWindow(WindowProxy window);
 176
 177   /**
 178    * Returns true if the extension has cross-origin access to the given URI.
 179    */
 180   boolean canAccessURI(URI uri, optional boolean explicit = false);
 181
 182   /**
 183    * Returns true if the extension currently has the given permission.
 184    */
 185   boolean hasPermission(DOMString permission);
 186
 187   /**
 188    * Returns true if the domain is on the Quarantined Domains list.
 189    */
 190   static boolean isQuarantinedURI(URI uri);
 191
 192   /**
 193    * Returns true if this extension is quarantined from the URI.
 194    */
 195   boolean quarantinedFromURI(URI uri);
 196
 197   /**
 198    * Returns true if the given path relative to the extension's moz-extension:
 199    * URL root is listed as a web accessible path. Access checks on a path, such
 200    * as performed in nsScriptSecurityManager, use sourceMayAccessPath below.
 201    */
 202   boolean isWebAccessiblePath(UTF8String pathname);
 203
 204   /**
 205    * Returns true if the given path relative to the extension's moz-extension:
 206    * URL root may be accessed by web content at sourceURI.  For Manifest V2,
 207    * sourceURI is ignored and the path must merely be listed as web accessible.
 208    */
 209   boolean sourceMayAccessPath(URI sourceURI, UTF8String pathname);
 210
 211   /**
 212    * Replaces localization placeholders in the given string with localized
 213    * text from the extension's currently active locale.
 214    */
 215   DOMString localize(DOMString unlocalizedText);
 216
 217   /**
 218    * Returns the moz-extension: URL for the given path.
 219    */
 220   [Throws]
 221   DOMString getURL(optional DOMString path = "");
 222
 223   /**
 224    * Register a new content script programmatically.
 225    */
 226   [Throws]
 227   undefined registerContentScript(WebExtensionContentScript script);
 228
 229   /**
 230    * Unregister a content script.
 231    */
 232   [Throws]
 233   undefined unregisterContentScript(WebExtensionContentScript script);
 234
 235   /**
 236    * Injects the extension's content script into all existing matching windows.
 237    */
 238   [Throws]
 239   undefined injectContentScripts();
 240
 241   /**
 242    * Returns the list of currently active extension policies.
 243    */
 244   static sequence<WebExtensionPolicy> getActiveExtensions();
 245
 246   /**
 247    * Returns the currently-active policy for the extension with the given ID,
 248    * or null if no policy is active for that ID.
 249    */
 250   static WebExtensionPolicy? getByID(DOMString id);
 251
 252   /**
 253    * Returns the currently-active policy for the extension with the given
 254    * moz-extension: hostname, or null if no policy is active for that
 255    * hostname.
 256    */
 257   static WebExtensionPolicy? getByHostname(ByteString hostname);
 258
 259   /**
 260    * Returns the currently-active policy for the extension extension URI, or
 261    * null if the URI is not an extension URI, or no policy is currently active
 262    * for it.
 263    */
 264   static WebExtensionPolicy? getByURI(URI uri);
 265
 266   /**
 267    * Returns true if the URI is restricted for any extension.
 268    */
 269   static boolean isRestrictedURI(URI uri);
 270
 271   /**
 272    * When present, the extension is not yet ready to load URLs. In that case,
 273    * this policy object is a stub, and the attribute contains a promise which
 274    * resolves to a new, non-stub policy object when the extension is ready.
 275    *
 276    * This may be used to delay operations, such as loading extension pages,
 277    * which depend on extensions being fully initialized.
 278    *
 279    * Note: This will always be either a Promise<WebExtensionPolicy?> or null,
 280    * but the WebIDL grammar does not allow us to specify a nullable Promise
 281    * type.
 282    *
 283    * Note: This could resolve to null when the startup was interrupted.
 284    */
 285   readonly attribute object? readyPromise;
 286
 287   /**
 288    * Returns true if the given worker script URL matches the background
 289    * service worker url declared in the extension manifest.json file.
 290    */
 291   boolean isManifestBackgroundWorker(DOMString workerURL);
 292
 293   /**
 294    * Get the unique BrowsingContextGroup ID which will be used for toplevel
 295    * page loads from this extension.
 296    *
 297    * This method will raise an exception if called from outside of the parent
 298    * process, or if the extension is inactive.
 299    */
 300   [Throws]
 301   readonly attribute unsigned long long browsingContextGroupId;
 302 };
 303
 304 dictionary WebAccessibleResourceInit {
 305   required sequence<MatchGlobOrString> resources;
 306   MatchPatternSetOrStringSequence? matches = null;
 307   sequence<DOMString>? extension_ids = null;
 308 };
 309
 310 dictionary WebExtensionInit {
 311   required DOMString id;
 312
 313   required ByteString mozExtensionHostname;
 314
 315   required DOMString baseURL;
 316
 317   DOMString name = "";
 318
 319   DOMString type = "";
 320
 321   boolean isPrivileged = false;
 322
 323   boolean ignoreQuarantine = false;
 324
 325   boolean temporarilyInstalled = false;
 326
 327   required WebExtensionLocalizeCallback localizeCallback;
 328
 329   required MatchPatternSetOrStringSequence allowedOrigins;
 330
 331   sequence<DOMString> permissions = [];
 332
 333   sequence<WebAccessibleResourceInit> webAccessibleResources = [];
 334
 335   sequence<WebExtensionContentScriptInit> contentScripts = [];
 336
 337   // The use of a content script csp is determined by the manifest version.
 338   unsigned long manifestVersion = 2;
 339   DOMString? extensionPageCSP = null;
 340
 341   sequence<DOMString>? backgroundScripts = null;
 342   DOMString? backgroundWorkerScript = null;
 343
 344   // Whether the background scripts should be loaded as ES modules.
 345   boolean backgroundTypeModule = false;
 346
 347   Promise<WebExtensionPolicy?> readyPromise;
 348 };