WebExtensionPolicy.webidl (11016B)
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 this extension has recommended state. 130 */ 131 [Cached, Pure] 132 readonly attribute boolean hasRecommendedState; 133 134 /** 135 * True if both e10s and webextensions.remote are enabled. This must be 136 * used instead of checking the remote pref directly since remote extensions 137 * require both to be enabled. 138 */ 139 static readonly attribute boolean useRemoteWebExtensions; 140 141 /** 142 * True if the calling process is an extension process. 143 */ 144 static readonly attribute boolean isExtensionProcess; 145 146 /** 147 * Whether the background.service_worker in the extension manifest.json file 148 * is enabled. 149 * 150 * NOTE: **do not use Services.prefs to retrieve the value of the undelying pref** 151 * 152 * It is defined in StaticPrefList.yaml as `mirror: once` and so checking 153 * its current value using Services.prefs doesn't guarantee that it does 154 * match the value as accessible from the C++ layers, and unexpected issue 155 * may be possible if different code has a different idea of its value. 156 */ 157 static readonly attribute boolean backgroundServiceWorkerEnabled; 158 159 /** 160 * Whether the Quarantined Domains feature is enabled. Use this as a single 161 * source of truth instead of checking extensions.QuarantinedDomains.enabled 162 * pref directly because the logic might change. 163 */ 164 static readonly attribute boolean quarantinedDomainsEnabled; 165 166 /** 167 * Set based on the manifest.incognito value: 168 * If "spanning" or "split" will be true. 169 * If "not_allowed" will be false. 170 */ 171 [Pure] 172 readonly attribute boolean privateBrowsingAllowed; 173 174 /** 175 * Returns true if the extension can access a window. Access is 176 * determined by matching the windows private browsing context 177 * with privateBrowsingMode. This does not, and is not meant to 178 * handle specific differences between spanning and split mode. 179 */ 180 [Affects=Nothing] 181 boolean canAccessWindow(WindowProxy window); 182 183 /** 184 * Returns true if the extension has cross-origin access to the given URI. 185 */ 186 boolean canAccessURI(URI uri, optional boolean explicit = false, 187 optional boolean checkRestricted = true, 188 optional boolean allowFilePermission = false); 189 190 /** 191 * Returns true if the extension currently has the given permission. 192 */ 193 boolean hasPermission(DOMString permission); 194 195 /** 196 * Returns true if the domain is on the Quarantined Domains list. 197 */ 198 static boolean isQuarantinedURI(URI uri); 199 200 /** 201 * Returns true if this extension is quarantined from the URI. 202 */ 203 boolean quarantinedFromURI(URI uri); 204 205 /** 206 * Returns true if the given path relative to the extension's moz-extension: 207 * URL root is listed as a web accessible path. Access checks on a path, such 208 * as performed in nsScriptSecurityManager, use sourceMayAccessPath below. 209 */ 210 boolean isWebAccessiblePath(UTF8String pathname); 211 212 /** 213 * Returns true if the given path relative to the extension's moz-extension: 214 * URL root may be accessed by web content at sourceURI. For Manifest V2, 215 * sourceURI is ignored and the path must merely be listed as web accessible. 216 */ 217 boolean sourceMayAccessPath(URI sourceURI, UTF8String pathname); 218 219 /** 220 * Replaces localization placeholders in the given string with localized 221 * text from the extension's currently active locale. 222 */ 223 DOMString localize(DOMString unlocalizedText); 224 225 /** 226 * Returns the moz-extension: URL for the given path. 227 */ 228 [Throws] 229 DOMString getURL(optional DOMString path = ""); 230 231 /** 232 * Register a new content script programmatically. 233 */ 234 [Throws] 235 undefined registerContentScript(WebExtensionContentScript script); 236 237 /** 238 * Unregister a content script. 239 */ 240 [Throws] 241 undefined unregisterContentScript(WebExtensionContentScript script); 242 243 /** 244 * Injects the extension's content script into all existing matching windows. 245 */ 246 [Throws] 247 undefined injectContentScripts(); 248 249 /** 250 * Returns the list of currently active extension policies. 251 */ 252 static sequence<WebExtensionPolicy> getActiveExtensions(); 253 254 /** 255 * Returns the currently-active policy for the extension with the given ID, 256 * or null if no policy is active for that ID. 257 */ 258 static WebExtensionPolicy? getByID(DOMString id); 259 260 /** 261 * Returns the currently-active policy for the extension with the given 262 * moz-extension: hostname, or null if no policy is active for that 263 * hostname. 264 */ 265 static WebExtensionPolicy? getByHostname(ByteString hostname); 266 267 /** 268 * Returns the currently-active policy for the extension URI, or 269 * null if the URI is not an extension URI, or no policy is currently active 270 * for it. 271 */ 272 static WebExtensionPolicy? getByURI(URI uri); 273 274 /** 275 * Returns true if the URI is restricted for any extension. 276 */ 277 static boolean isRestrictedURI(URI uri); 278 279 /** 280 * When present, the extension is not yet ready to load URLs. In that case, 281 * this policy object is a stub, and the attribute contains a promise which 282 * resolves to a new, non-stub policy object when the extension is ready. 283 * 284 * This may be used to delay operations, such as loading extension pages, 285 * which depend on extensions being fully initialized. 286 * 287 * Note: This will always be either a Promise<WebExtensionPolicy?> or null, 288 * but the WebIDL grammar does not allow us to specify a nullable Promise 289 * type. 290 * 291 * Note: This could resolve to null when the startup was interrupted. 292 */ 293 readonly attribute object? readyPromise; 294 295 /** 296 * Returns true if the given worker script URL matches the background 297 * service worker url declared in the extension manifest.json file. 298 */ 299 boolean isManifestBackgroundWorker(DOMString workerURL); 300 301 /** 302 * Get the unique BrowsingContextGroup ID which will be used for toplevel 303 * page loads from this extension. 304 * 305 * This method will raise an exception if called from outside of the parent 306 * process, or if the extension is inactive. 307 */ 308 [Throws] 309 readonly attribute unsigned long long browsingContextGroupId; 310 }; 311 312 dictionary WebAccessibleResourceInit { 313 required sequence<MatchGlobOrString> resources; 314 MatchPatternSetOrStringSequence? matches = null; 315 sequence<DOMString>? extension_ids = null; 316 }; 317 318 dictionary WebExtensionInit { 319 required DOMString id; 320 321 required ByteString mozExtensionHostname; 322 323 required DOMString baseURL; 324 325 DOMString name = ""; 326 327 DOMString type = ""; 328 329 boolean isPrivileged = false; 330 331 boolean ignoreQuarantine = false; 332 333 boolean hasRecommendedState = false; 334 335 boolean temporarilyInstalled = false; 336 337 required WebExtensionLocalizeCallback localizeCallback; 338 339 required MatchPatternSetOrStringSequence allowedOrigins; 340 341 sequence<DOMString> permissions = []; 342 343 sequence<WebAccessibleResourceInit> webAccessibleResources = []; 344 345 sequence<WebExtensionContentScriptInit> contentScripts = []; 346 347 // The use of a content script csp is determined by the manifest version. 348 unsigned long manifestVersion = 2; 349 DOMString? extensionPageCSP = null; 350 351 sequence<DOMString>? backgroundScripts = null; 352 DOMString? backgroundWorkerScript = null; 353 354 // Whether the background scripts should be loaded as ES modules. 355 boolean backgroundTypeModule = false; 356 357 Promise<WebExtensionPolicy?> readyPromise; 358 };