summaryrefslogtreecommitdiffstats
path: root/toolkit/components/extensions/Schemas.sys.mjs
diff options
context:
space:
mode:
Diffstat (limited to 'toolkit/components/extensions/Schemas.sys.mjs')
-rw-r--r--toolkit/components/extensions/Schemas.sys.mjs3942
1 files changed, 3942 insertions, 0 deletions
diff --git a/toolkit/components/extensions/Schemas.sys.mjs b/toolkit/components/extensions/Schemas.sys.mjs
new file mode 100644
index 0000000000..9107e6a347
--- /dev/null
+++ b/toolkit/components/extensions/Schemas.sys.mjs
@@ -0,0 +1,3942 @@
+/* -*- Mode: indent-tabs-mode: nil; js-indent-level: 2 -*- */
+/* vim: set sts=2 sw=2 et tw=80: */
+/* 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/. */
+
+import { AppConstants } from "resource://gre/modules/AppConstants.sys.mjs";
+import { XPCOMUtils } from "resource://gre/modules/XPCOMUtils.sys.mjs";
+
+import { ExtensionUtils } from "resource://gre/modules/ExtensionUtils.sys.mjs";
+
+var { DefaultMap, DefaultWeakMap } = ExtensionUtils;
+
+const lazy = {};
+
+ChromeUtils.defineESModuleGetters(lazy, {
+ ExtensionParent: "resource://gre/modules/ExtensionParent.sys.mjs",
+ NetUtil: "resource://gre/modules/NetUtil.sys.mjs",
+ ShortcutUtils: "resource://gre/modules/ShortcutUtils.sys.mjs",
+});
+
+XPCOMUtils.defineLazyServiceGetter(
+ lazy,
+ "contentPolicyService",
+ "@mozilla.org/addons/content-policy;1",
+ "nsIAddonContentPolicy"
+);
+
+ChromeUtils.defineLazyGetter(
+ lazy,
+ "StartupCache",
+ () => lazy.ExtensionParent.StartupCache
+);
+
+XPCOMUtils.defineLazyPreferenceGetter(
+ lazy,
+ "treatWarningsAsErrors",
+ "extensions.webextensions.warnings-as-errors",
+ false
+);
+
+const KEY_CONTENT_SCHEMAS = "extensions-framework/schemas/content";
+const KEY_PRIVILEGED_SCHEMAS = "extensions-framework/schemas/privileged";
+
+const MIN_MANIFEST_VERSION = 2;
+const MAX_MANIFEST_VERSION = 3;
+
+const { DEBUG } = AppConstants;
+
+const isParentProcess =
+ Services.appinfo.processType === Services.appinfo.PROCESS_TYPE_DEFAULT;
+
+function readJSON(url) {
+ return new Promise((resolve, reject) => {
+ lazy.NetUtil.asyncFetch(
+ { uri: url, loadUsingSystemPrincipal: true },
+ (inputStream, status) => {
+ if (!Components.isSuccessCode(status)) {
+ // Convert status code to a string
+ let e = Components.Exception("", status);
+ reject(new Error(`Error while loading '${url}' (${e.name})`));
+ return;
+ }
+ try {
+ let text = lazy.NetUtil.readInputStreamToString(
+ inputStream,
+ inputStream.available()
+ );
+
+ // Chrome JSON files include a license comment that we need to
+ // strip off for this to be valid JSON. As a hack, we just
+ // look for the first '[' character, which signals the start
+ // of the JSON content.
+ let index = text.indexOf("[");
+ text = text.slice(index);
+
+ resolve(JSON.parse(text));
+ } catch (e) {
+ reject(e);
+ }
+ }
+ );
+ });
+}
+
+function stripDescriptions(json, stripThis = true) {
+ if (Array.isArray(json)) {
+ for (let i = 0; i < json.length; i++) {
+ if (typeof json[i] === "object" && json[i] !== null) {
+ json[i] = stripDescriptions(json[i]);
+ }
+ }
+ return json;
+ }
+
+ let result = {};
+
+ // Objects are handled much more efficiently, both in terms of memory and
+ // CPU, if they have the same shape as other objects that serve the same
+ // purpose. So, normalize the order of properties to increase the chances
+ // that the majority of schema objects wind up in large shape groups.
+ for (let key of Object.keys(json).sort()) {
+ if (stripThis && key === "description" && typeof json[key] === "string") {
+ continue;
+ }
+
+ if (typeof json[key] === "object" && json[key] !== null) {
+ result[key] = stripDescriptions(json[key], key !== "properties");
+ } else {
+ result[key] = json[key];
+ }
+ }
+
+ return result;
+}
+
+function blobbify(json) {
+ // We don't actually use descriptions at runtime, and they make up about a
+ // third of the size of our structured clone data, so strip them before
+ // blobbifying.
+ json = stripDescriptions(json);
+
+ return new StructuredCloneHolder("Schemas/blobbify", null, json);
+}
+
+async function readJSONAndBlobbify(url) {
+ let json = await readJSON(url);
+
+ return blobbify(json);
+}
+
+/**
+ * Defines a lazy getter for the given property on the given object. Any
+ * security wrappers are waived on the object before the property is
+ * defined, and the getter and setter methods are wrapped for the target
+ * scope.
+ *
+ * The given getter function is guaranteed to be called only once, even
+ * if the target scope retrieves the wrapped getter from the property
+ * descriptor and calls it directly.
+ *
+ * @param {object} object
+ * The object on which to define the getter.
+ * @param {string | symbol} prop
+ * The property name for which to define the getter.
+ * @param {Function} getter
+ * The function to call in order to generate the final property
+ * value.
+ */
+function exportLazyGetter(object, prop, getter) {
+ object = ChromeUtils.waiveXrays(object);
+
+ let redefine = value => {
+ if (value === undefined) {
+ delete object[prop];
+ } else {
+ Object.defineProperty(object, prop, {
+ enumerable: true,
+ configurable: true,
+ writable: true,
+ value,
+ });
+ }
+
+ getter = null;
+
+ return value;
+ };
+
+ Object.defineProperty(object, prop, {
+ enumerable: true,
+ configurable: true,
+
+ get: Cu.exportFunction(function () {
+ return redefine(getter.call(this));
+ }, object),
+
+ set: Cu.exportFunction(value => {
+ redefine(value);
+ }, object),
+ });
+}
+
+/**
+ * Defines a lazily-instantiated property descriptor on the given
+ * object. Any security wrappers are waived on the object before the
+ * property is defined.
+ *
+ * The given getter function is guaranteed to be called only once, even
+ * if the target scope retrieves the wrapped getter from the property
+ * descriptor and calls it directly.
+ *
+ * @param {object} object
+ * The object on which to define the getter.
+ * @param {string | symbol} prop
+ * The property name for which to define the getter.
+ * @param {Function} getter
+ * The function to call in order to generate the final property
+ * descriptor object. This will be called, and the property
+ * descriptor installed on the object, the first time the
+ * property is written or read. The function may return
+ * undefined, which will cause the property to be deleted.
+ */
+function exportLazyProperty(object, prop, getter) {
+ object = ChromeUtils.waiveXrays(object);
+
+ let redefine = obj => {
+ let desc = getter.call(obj);
+ getter = null;
+
+ delete object[prop];
+ if (desc) {
+ let defaults = {
+ configurable: true,
+ enumerable: true,
+ };
+
+ if (!desc.set && !desc.get) {
+ defaults.writable = true;
+ }
+
+ Object.defineProperty(object, prop, Object.assign(defaults, desc));
+ }
+ };
+
+ Object.defineProperty(object, prop, {
+ enumerable: true,
+ configurable: true,
+
+ get: Cu.exportFunction(function () {
+ redefine(this);
+ return object[prop];
+ }, object),
+
+ set: Cu.exportFunction(function (value) {
+ redefine(this);
+ object[prop] = value;
+ }, object),
+ });
+}
+
+const POSTPROCESSORS = {
+ convertImageDataToURL(imageData, context) {
+ let document = context.cloneScope.document;
+ let canvas = document.createElementNS(
+ "http://www.w3.org/1999/xhtml",
+ "canvas"
+ );
+ canvas.width = imageData.width;
+ canvas.height = imageData.height;
+ canvas.getContext("2d").putImageData(imageData, 0, 0);
+
+ return canvas.toDataURL("image/png");
+ },
+ webRequestBlockingPermissionRequired(string, context) {
+ if (string === "blocking" && !context.hasPermission("webRequestBlocking")) {
+ throw new context.cloneScope.Error(
+ "Using webRequest.addListener with the " +
+ "blocking option requires the 'webRequestBlocking' permission."
+ );
+ }
+
+ return string;
+ },
+ requireBackgroundServiceWorkerEnabled(value, context) {
+ if (WebExtensionPolicy.backgroundServiceWorkerEnabled) {
+ return value;
+ }
+
+ // Add an error to the manifest validations and throw the
+ // same error.
+ const msg = "background.service_worker is currently disabled";
+ context.logError(context.makeError(msg));
+ throw new Error(msg);
+ },
+
+ manifestVersionCheck(value, context) {
+ if (
+ value == 2 ||
+ (value == 3 &&
+ Services.prefs.getBoolPref("extensions.manifestV3.enabled", false))
+ ) {
+ return value;
+ }
+ const msg = `Unsupported manifest version: ${value}`;
+ context.logError(context.makeError(msg));
+ throw new Error(msg);
+ },
+
+ webAccessibleMatching(value, context) {
+ // Ensure each object has at least one of matches or extension_ids array.
+ for (let obj of value) {
+ if (!obj.matches && !obj.extension_ids) {
+ const msg = `web_accessible_resources requires one of "matches" or "extension_ids"`;
+ context.logError(context.makeError(msg));
+ throw new Error(msg);
+ }
+ }
+ return value;
+ },
+};
+
+// Parses a regular expression, with support for the Python extended
+// syntax that allows setting flags by including the string (?im)
+function parsePattern(pattern) {
+ let flags = "";
+ let match = /^\(\?([im]*)\)(.*)/.exec(pattern);
+ if (match) {
+ [, flags, pattern] = match;
+ }
+ return new RegExp(pattern, flags);
+}
+
+function getValueBaseType(value) {
+ let type = typeof value;
+ switch (type) {
+ case "object":
+ if (value === null) {
+ return "null";
+ }
+ if (Array.isArray(value)) {
+ return "array";
+ }
+ break;
+
+ case "number":
+ if (value % 1 === 0) {
+ return "integer";
+ }
+ }
+ return type;
+}
+
+// Methods of Context that are used by Schemas.normalize. These methods can be
+// overridden at the construction of Context.
+const CONTEXT_FOR_VALIDATION = ["checkLoadURL", "hasPermission", "logError"];
+
+// Methods of Context that are used by Schemas.inject.
+// Callers of Schemas.inject should implement all of these methods.
+const CONTEXT_FOR_INJECTION = [
+ ...CONTEXT_FOR_VALIDATION,
+ "getImplementation",
+ "isPermissionRevokable",
+ "shouldInject",
+];
+
+// If the message is a function, call it and return the result.
+// Otherwise, assume it's a string.
+function forceString(msg) {
+ if (typeof msg === "function") {
+ return msg();
+ }
+ return msg;
+}
+
+/**
+ * A context for schema validation and error reporting. This class is only used
+ * internally within Schemas.
+ */
+class Context {
+ /**
+ * @param {object} params Provides the implementation of this class.
+ * @param {Array<string>} overridableMethods
+ */
+ constructor(params, overridableMethods = CONTEXT_FOR_VALIDATION) {
+ this.params = params;
+
+ if (typeof params.manifestVersion !== "number") {
+ throw new Error(
+ `Unexpected params.manifestVersion value: ${params.manifestVersion}`
+ );
+ }
+
+ this.path = [];
+ this.preprocessors = {
+ localize(value, context) {
+ return value;
+ },
+ ...params.preprocessors,
+ };
+
+ this.postprocessors = POSTPROCESSORS;
+ this.isChromeCompat = params.isChromeCompat ?? false;
+ this.manifestVersion = params.manifestVersion;
+
+ this.currentChoices = new Set();
+ this.choicePathIndex = 0;
+
+ for (let method of overridableMethods) {
+ if (method in params) {
+ this[method] = params[method].bind(params);
+ }
+ }
+ }
+
+ get choicePath() {
+ let path = this.path.slice(this.choicePathIndex);
+ return path.join(".");
+ }
+
+ get cloneScope() {
+ return this.params.cloneScope || undefined;
+ }
+
+ get url() {
+ return this.params.url;
+ }
+
+ get principal() {
+ return (
+ this.params.principal ||
+ Services.scriptSecurityManager.createNullPrincipal({})
+ );
+ }
+
+ /**
+ * Checks whether `url` may be loaded by the extension in this context.
+ *
+ * @param {string} url The URL that the extension wished to load.
+ * @returns {boolean} Whether the context may load `url`.
+ */
+ checkLoadURL(url) {
+ let ssm = Services.scriptSecurityManager;
+ try {
+ ssm.checkLoadURIWithPrincipal(
+ this.principal,
+ Services.io.newURI(url),
+ ssm.DISALLOW_INHERIT_PRINCIPAL
+ );
+ } catch (e) {
+ return false;
+ }
+ return true;
+ }
+
+ /**
+ * Checks whether this context has the given permission.
+ *
+ * @param {string} permission
+ * The name of the permission to check.
+ *
+ * @returns {boolean} True if the context has the given permission.
+ */
+ hasPermission(permission) {
+ return false;
+ }
+
+ /**
+ * Checks whether the given permission can be dynamically revoked or
+ * granted.
+ *
+ * @param {string} permission
+ * The name of the permission to check.
+ *
+ * @returns {boolean} True if the given permission is revokable.
+ */
+ isPermissionRevokable(permission) {
+ return false;
+ }
+
+ /**
+ * Returns an error result object with the given message, for return
+ * by Type normalization functions.
+ *
+ * If the context has a `currentTarget` value, this is prepended to
+ * the message to indicate the location of the error.
+ *
+ * @param {string | Function} errorMessage
+ * The error message which will be displayed when this is the
+ * only possible matching schema. If a function is passed, it
+ * will be evaluated when the error string is first needed, and
+ * must return a string.
+ * @param {string | Function} choicesMessage
+ * The message describing the valid what constitutes a valid
+ * value for this schema, which will be displayed when multiple
+ * schema choices are available and none match.
+ *
+ * A caller may pass `null` to prevent a choice from being
+ * added, but this should *only* be done from code processing a
+ * choices type.
+ * @param {boolean} [warning = false]
+ * If true, make message prefixed `Warning`. If false, make message
+ * prefixed `Error`
+ * @returns {object}
+ */
+ error(errorMessage, choicesMessage = undefined, warning = false) {
+ if (choicesMessage !== null) {
+ let { choicePath } = this;
+ if (choicePath) {
+ choicesMessage = `.${choicePath} must ${choicesMessage}`;
+ }
+
+ this.currentChoices.add(choicesMessage);
+ }
+
+ if (this.currentTarget) {
+ let { currentTarget } = this;
+ return {
+ error: () =>
+ `${
+ warning ? "Warning" : "Error"
+ } processing ${currentTarget}: ${forceString(errorMessage)}`,
+ };
+ }
+ return { error: errorMessage };
+ }
+
+ /**
+ * Creates an `Error` object belonging to the current unprivileged
+ * scope. If there is no unprivileged scope associated with this
+ * context, the message is returned as a string.
+ *
+ * If the context has a `currentTarget` value, this is prepended to
+ * the message, in the same way as for the `error` method.
+ *
+ * @param {string} message
+ * @param {object} [options]
+ * @param {boolean} [options.warning = false]
+ * @returns {Error}
+ */
+ makeError(message, { warning = false } = {}) {
+ let error = forceString(this.error(message, null, warning).error);
+ if (this.cloneScope) {
+ return new this.cloneScope.Error(error);
+ }
+ return error;
+ }
+
+ /**
+ * Logs the given error to the console. May be overridden to enable
+ * custom logging.
+ *
+ * @param {Error|string} error
+ */
+ logError(error) {
+ if (this.cloneScope) {
+ Cu.reportError(
+ // Error objects logged using Cu.reportError are not associated
+ // to the related innerWindowID. This results in a leaked docshell
+ // since consoleService cannot release the error object when the
+ // extension global is destroyed.
+ typeof error == "string" ? error : String(error),
+ // Report the error with the appropriate stack trace when the
+ // is related to an actual extension global (instead of being
+ // related to a manifest validation).
+ this.principal && ChromeUtils.getCallerLocation(this.principal)
+ );
+ } else {
+ Cu.reportError(error);
+ }
+ }
+
+ /**
+ * Logs a warning. An error might be thrown when we treat warnings as errors.
+ *
+ * @param {string} warningMessage
+ */
+ logWarning(warningMessage) {
+ let error = this.makeError(warningMessage, { warning: true });
+ this.logError(error);
+
+ if (lazy.treatWarningsAsErrors) {
+ // This pref is false by default, and true by default in tests to
+ // discourage the use of deprecated APIs in our unit tests.
+ // If a warning is an expected part of a test, temporarily set the pref
+ // to false, e.g. with the ExtensionTestUtils.failOnSchemaWarnings helper.
+ Services.console.logStringMessage(
+ "Treating warning as error because the preference " +
+ "extensions.webextensions.warnings-as-errors is set to true"
+ );
+ if (typeof error === "string") {
+ error = new Error(error);
+ }
+ throw error;
+ }
+ }
+
+ /**
+ * Returns the name of the value currently being normalized. For a
+ * nested object, this is usually approximately equivalent to the
+ * JavaScript property accessor for that property. Given:
+ *
+ * { foo: { bar: [{ baz: x }] } }
+ *
+ * When processing the value for `x`, the currentTarget is
+ * 'foo.bar.0.baz'
+ */
+ get currentTarget() {
+ return this.path.join(".");
+ }
+
+ /**
+ * Executes the given callback, and returns an array of choice strings
+ * passed to {@see #error} during its execution.
+ *
+ * @param {Function} callback
+ * @returns {object}
+ * An object with a `result` property containing the return
+ * value of the callback, and a `choice` property containing
+ * an array of choices.
+ */
+ withChoices(callback) {
+ let { currentChoices, choicePathIndex } = this;
+
+ let choices = new Set();
+ this.currentChoices = choices;
+ this.choicePathIndex = this.path.length;
+
+ try {
+ let result = callback();
+
+ return { result, choices };
+ } finally {
+ this.currentChoices = currentChoices;
+ this.choicePathIndex = choicePathIndex;
+
+ if (choices.size == 1) {
+ for (let choice of choices) {
+ currentChoices.add(choice);
+ }
+ } else if (choices.size) {
+ this.error(null, () => {
+ let array = Array.from(choices, forceString);
+ let n = array.length - 1;
+ array[n] = `or ${array[n]}`;
+
+ return `must either [${array.join(", ")}]`;
+ });
+ }
+ }
+ }
+
+ /**
+ * Appends the given component to the `currentTarget` path to indicate
+ * that it is being processed, calls the given callback function, and
+ * then restores the original path.
+ *
+ * This is used to identify the path of the property being processed
+ * when reporting type errors.
+ *
+ * @param {string} component
+ * @param {Function} callback
+ * @returns {*}
+ */
+ withPath(component, callback) {
+ this.path.push(component);
+ try {
+ return callback();
+ } finally {
+ this.path.pop();
+ }
+ }
+
+ matchManifestVersion(entry) {
+ let { manifestVersion } = this;
+ return (
+ manifestVersion >= entry.min_manifest_version &&
+ manifestVersion <= entry.max_manifest_version
+ );
+ }
+}
+
+/**
+ * Represents a schema entry to be injected into an object. Handles the
+ * injection, revocation, and permissions of said entry.
+ *
+ * @param {InjectionContext} context
+ * The injection context for the entry.
+ * @param {Entry} entry
+ * The entry to inject.
+ * @param {object} parentObject
+ * The object into which to inject this entry.
+ * @param {string} name
+ * The property name at which to inject this entry.
+ * @param {Array<string>} path
+ * The full path from the root entry to this entry.
+ * @param {Entry} parentEntry
+ * The parent entry for the injected entry.
+ */
+class InjectionEntry {
+ constructor(context, entry, parentObj, name, path, parentEntry) {
+ this.context = context;
+ this.entry = entry;
+ this.parentObj = parentObj;
+ this.name = name;
+ this.path = path;
+ this.parentEntry = parentEntry;
+
+ this.injected = null;
+ this.lazyInjected = null;
+ }
+
+ /**
+ * @property {Array<string>} allowedContexts
+ * The list of allowed contexts into which the entry may be
+ * injected.
+ */
+ get allowedContexts() {
+ let { allowedContexts } = this.entry;
+ if (allowedContexts.length) {
+ return allowedContexts;
+ }
+ return this.parentEntry.defaultContexts;
+ }
+
+ /**
+ * @property {boolean} isRevokable
+ * Returns true if this entry may be dynamically injected or
+ * revoked based on its permissions.
+ */
+ get isRevokable() {
+ return (
+ this.entry.permissions &&
+ this.entry.permissions.some(perm =>
+ this.context.isPermissionRevokable(perm)
+ )
+ );
+ }
+
+ /**
+ * @property {boolean} hasPermission
+ * Returns true if the injection context currently has the
+ * appropriate permissions to access this entry.
+ */
+ get hasPermission() {
+ return (
+ !this.entry.permissions ||
+ this.entry.permissions.some(perm => this.context.hasPermission(perm))
+ );
+ }
+
+ /**
+ * @property {boolean} shouldInject
+ * Returns true if this entry should be injected in the given
+ * context, without respect to permissions.
+ */
+ get shouldInject() {
+ return (
+ this.context.matchManifestVersion(this.entry) &&
+ this.context.shouldInject(
+ this.path.join("."),
+ this.name,
+ this.allowedContexts
+ )
+ );
+ }
+
+ /**
+ * Revokes this entry, removing its property from its parent object,
+ * and invalidating its wrappers.
+ */
+ revoke() {
+ if (this.lazyInjected) {
+ this.lazyInjected = false;
+ } else if (this.injected) {
+ if (this.injected.revoke) {
+ this.injected.revoke();
+ }
+
+ try {
+ let unwrapped = ChromeUtils.waiveXrays(this.parentObj);
+ delete unwrapped[this.name];
+ } catch (e) {
+ Cu.reportError(e);
+ }
+
+ let { value } = this.injected.descriptor;
+ if (value) {
+ this.context.revokeChildren(value);
+ }
+
+ this.injected = null;
+ }
+ }
+
+ /**
+ * Returns a property descriptor object for this entry, if it should
+ * be injected, or undefined if it should not.
+ *
+ * @returns {object?}
+ * A property descriptor object, or undefined if the property
+ * should be removed.
+ */
+ getDescriptor() {
+ this.lazyInjected = false;
+
+ if (this.injected) {
+ let path = [...this.path, this.name];
+ throw new Error(
+ `Attempting to re-inject already injected entry: ${path.join(".")}`
+ );
+ }
+
+ if (!this.shouldInject) {
+ return;
+ }
+
+ if (this.isRevokable) {
+ this.context.pendingEntries.add(this);
+ }
+
+ if (!this.hasPermission) {
+ return;
+ }
+
+ this.injected = this.entry.getDescriptor(this.path, this.context);
+ if (!this.injected) {
+ return undefined;
+ }
+
+ return this.injected.descriptor;
+ }
+
+ /**
+ * Injects a lazy property descriptor into the parent object which
+ * checks permissions and eligibility for injection the first time it
+ * is accessed.
+ */
+ lazyInject() {
+ if (this.lazyInjected || this.injected) {
+ let path = [...this.path, this.name];
+ throw new Error(
+ `Attempting to re-lazy-inject already injected entry: ${path.join(".")}`
+ );
+ }
+
+ this.lazyInjected = true;
+ exportLazyProperty(this.parentObj, this.name, () => {
+ if (this.lazyInjected) {
+ return this.getDescriptor();
+ }
+ });
+ }
+
+ /**
+ * Injects or revokes this entry if its current state does not match
+ * the context's current permissions.
+ */
+ permissionsChanged() {
+ if (this.injected) {
+ this.maybeRevoke();
+ } else {
+ this.maybeInject();
+ }
+ }
+
+ maybeInject() {
+ if (!this.injected && !this.lazyInjected) {
+ this.lazyInject();
+ }
+ }
+
+ maybeRevoke() {
+ if (this.injected && !this.hasPermission) {
+ this.revoke();
+ }
+ }
+}
+
+/**
+ * Holds methods that run the actual implementation of the extension APIs. These
+ * methods are only called if the extension API invocation matches the signature
+ * as defined in the schema. Otherwise an error is reported to the context.
+ */
+class InjectionContext extends Context {
+ constructor(params, schemaRoot) {
+ super(params, CONTEXT_FOR_INJECTION);
+
+ this.schemaRoot = schemaRoot;
+
+ this.pendingEntries = new Set();
+ this.children = new DefaultWeakMap(() => new Map());
+
+ this.injectedRoots = new Set();
+
+ if (params.setPermissionsChangedCallback) {
+ params.setPermissionsChangedCallback(this.permissionsChanged.bind(this));
+ }
+ }
+
+ /**
+ * Check whether the API should be injected.
+ *
+ * @abstract
+ * @param {string} namespace The namespace of the API. This may contain dots,
+ * e.g. in the case of "devtools.inspectedWindow".
+ * @param {string?} name The name of the property in the namespace.
+ * `null` if we are checking whether the namespace should be injected.
+ * @param {Array<string>} allowedContexts A list of additional contexts in
+ * which this API should be available. May include any of:
+ * "main" - The main chrome browser process.
+ * "addon" - An addon process.
+ * "content" - A content process.
+ * @returns {boolean} Whether the API should be injected.
+ */
+ shouldInject(namespace, name, allowedContexts) {
+ throw new Error("Not implemented");
+ }
+
+ /**
+ * Generate the implementation for `namespace`.`name`.
+ *
+ * @abstract
+ * @param {string} namespace The full path to the namespace of the API, minus
+ * the name of the method or property. E.g. "storage.local".
+ * @param {string} name The name of the method, property or event.
+ * @returns {SchemaAPIInterface} The implementation of the API.
+ */
+ getImplementation(namespace, name) {
+ throw new Error("Not implemented");
+ }
+
+ /**
+ * Updates all injection entries which may need to be updated after a
+ * permission change, revoking or re-injecting them as necessary.
+ */
+ permissionsChanged() {
+ for (let entry of this.pendingEntries) {
+ try {
+ entry.permissionsChanged();
+ } catch (e) {
+ Cu.reportError(e);
+ }
+ }
+ }
+
+ /**
+ * Recursively revokes all child injection entries of the given
+ * object.
+ *
+ * @param {object} object
+ * The object for which to invoke children.
+ */
+ revokeChildren(object) {
+ if (!this.children.has(object)) {
+ return;
+ }
+
+ let children = this.children.get(object);
+ for (let [name, entry] of children.entries()) {
+ try {
+ entry.revoke();
+ } catch (e) {
+ Cu.reportError(e);
+ }
+ children.delete(name);
+
+ // When we revoke children for an object, we consider that object
+ // dead. If the entry is ever reified again, a new object is
+ // created, with new child entries.
+ this.pendingEntries.delete(entry);
+ }
+ this.children.delete(object);
+ }
+
+ _getInjectionEntry(entry, dest, name, path, parentEntry) {
+ let injection = new InjectionEntry(
+ this,
+ entry,
+ dest,
+ name,
+ path,
+ parentEntry
+ );
+
+ this.children.get(dest).set(name, injection);
+
+ return injection;
+ }
+
+ /**
+ * Returns the property descriptor for the given entry.
+ *
+ * @param {Entry} entry
+ * The entry instance to return a descriptor for.
+ * @param {object} dest
+ * The object into which this entry is being injected.
+ * @param {string} name
+ * The property name on the destination object where the entry
+ * will be injected.
+ * @param {Array<string>} path
+ * The full path from the root injection object to this entry.
+ * @param {Partial<Entry>} parentEntry
+ * The parent entry for this entry.
+ *
+ * @returns {object?}
+ * A property descriptor object, or null if the entry should
+ * not be injected.
+ */
+ getDescriptor(entry, dest, name, path, parentEntry) {
+ let injection = this._getInjectionEntry(
+ entry,
+ dest,
+ name,
+ path,
+ parentEntry
+ );
+
+ return injection.getDescriptor();
+ }
+
+ /**
+ * Lazily injects the given entry into the given object.
+ *
+ * @param {Entry} entry
+ * The entry instance to lazily inject.
+ * @param {object} dest
+ * The object into which to inject this entry.
+ * @param {string} name
+ * The property name at which to inject the entry.
+ * @param {Array<string>} path
+ * The full path from the root injection object to this entry.
+ * @param {Entry} parentEntry
+ * The parent entry for this entry.
+ */
+ injectInto(entry, dest, name, path, parentEntry) {
+ let injection = this._getInjectionEntry(
+ entry,
+ dest,
+ name,
+ path,
+ parentEntry
+ );
+
+ injection.lazyInject();
+ }
+}
+
+/**
+ * The methods in this singleton represent the "format" specifier for
+ * JSON Schema string types.
+ *
+ * Each method either returns a normalized version of the original
+ * value, or throws an error if the value is not valid for the given
+ * format.
+ */
+const FORMATS = {
+ hostname(string, context) {
+ // TODO bug 1797376: Despite the name, this format is NOT a "hostname",
+ // but hostname + port and may fail with IPv6. Use canonicalDomain instead.
+ let valid = true;
+
+ try {
+ valid = new URL(`http://${string}`).host === string;
+ } catch (e) {
+ valid = false;
+ }
+
+ if (!valid) {
+ throw new Error(`Invalid hostname ${string}`);
+ }
+
+ return string;
+ },
+
+ canonicalDomain(string, context) {
+ let valid;
+
+ try {
+ valid = new URL(`http://${string}`).hostname === string;
+ } catch (e) {
+ valid = false;
+ }
+
+ if (!valid) {
+ // Require the input to be a canonical domain.
+ // Rejects obvious non-domains such as URLs,
+ // but also catches non-IDN (punycode) domains.
+ throw new Error(`Invalid domain ${string}`);
+ }
+
+ return string;
+ },
+
+ url(string, context) {
+ let url = new URL(string).href;
+
+ if (!context.checkLoadURL(url)) {
+ throw new Error(`Access denied for URL ${url}`);
+ }
+ return url;
+ },
+
+ origin(string, context) {
+ let url;
+ try {
+ url = new URL(string);
+ } catch (e) {
+ throw new Error(`Invalid origin: ${string}`);
+ }
+ if (!/^https?:/.test(url.protocol)) {
+ throw new Error(`Invalid origin must be http or https for URL ${string}`);
+ }
+ // url.origin is punycode so a direct check against string wont work.
+ // url.href appends a slash even if not in the original string, we we
+ // additionally check that string does not end in slash.
+ if (string.endsWith("/") || url.href != new URL(url.origin).href) {
+ throw new Error(
+ `Invalid origin for URL ${string}, replace with origin ${url.origin}`
+ );
+ }
+ if (!context.checkLoadURL(url.origin)) {
+ throw new Error(`Access denied for URL ${url}`);
+ }
+ return url.origin;
+ },
+
+ relativeUrl(string, context) {
+ if (!context.url) {
+ // If there's no context URL, return relative URLs unresolved, and
+ // skip security checks for them.
+ try {
+ new URL(string);
+ } catch (e) {
+ return string;
+ }
+ }
+
+ let url = new URL(string, context.url).href;
+
+ if (!context.checkLoadURL(url)) {
+ throw new Error(`Access denied for URL ${url}`);
+ }
+ return url;
+ },
+
+ strictRelativeUrl(string, context) {
+ void FORMATS.unresolvedRelativeUrl(string, context);
+ return FORMATS.relativeUrl(string, context);
+ },
+
+ unresolvedRelativeUrl(string, context) {
+ if (!string.startsWith("//")) {
+ try {
+ new URL(string);
+ } catch (e) {
+ return string;
+ }
+ }
+
+ throw new SyntaxError(
+ `String ${JSON.stringify(string)} must be a relative URL`
+ );
+ },
+
+ homepageUrl(string, context) {
+ // Pipes are used for separating homepages, but we only allow extensions to
+ // set a single homepage. Encoding any pipes makes it one URL.
+ return FORMATS.relativeUrl(
+ string.replace(new RegExp("\\|", "g"), "%7C"),
+ context
+ );
+ },
+
+ imageDataOrStrictRelativeUrl(string, context) {
+ // Do not accept a string which resolves as an absolute URL, or any
+ // protocol-relative URL, except PNG or JPG data URLs
+ if (
+ !string.startsWith("data:image/png;base64,") &&
+ !string.startsWith("data:image/jpeg;base64,")
+ ) {
+ try {
+ return FORMATS.strictRelativeUrl(string, context);
+ } catch (e) {
+ throw new SyntaxError(
+ `String ${JSON.stringify(
+ string
+ )} must be a relative or PNG or JPG data:image URL`
+ );
+ }
+ }
+ return string;
+ },
+
+ contentSecurityPolicy(string, context) {
+ // Manifest V3 extension_pages allows WASM. When sandbox is
+ // implemented, or any other V3 or later directive, the flags
+ // logic will need to be updated.
+ let flags =
+ context.manifestVersion < 3
+ ? Ci.nsIAddonContentPolicy.CSP_ALLOW_ANY
+ : Ci.nsIAddonContentPolicy.CSP_ALLOW_WASM;
+ let error = lazy.contentPolicyService.validateAddonCSP(string, flags);
+ if (error != null) {
+ // The CSP validation error is not reported as part of the "choices" error message,
+ // we log the CSP validation error explicitly here to make it easier for the addon developers
+ // to see and fix the extension CSP.
+ context.logError(`Error processing ${context.currentTarget}: ${error}`);
+ return null;
+ }
+ return string;
+ },
+
+ date(string, context) {
+ // A valid ISO 8601 timestamp.
+ const PATTERN =
+ /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d{3})?(Z|([-+]\d{2}:?\d{2})))?$/;
+ if (!PATTERN.test(string)) {
+ throw new Error(`Invalid date string ${string}`);
+ }
+ // Our pattern just checks the format, we could still have invalid
+ // values (e.g., month=99 or month=02 and day=31). Let the Date
+ // constructor do the dirty work of validating.
+ if (isNaN(Date.parse(string))) {
+ throw new Error(`Invalid date string ${string}`);
+ }
+ return string;
+ },
+
+ manifestShortcutKey(string, context) {
+ if (lazy.ShortcutUtils.validate(string) == lazy.ShortcutUtils.IS_VALID) {
+ return string;
+ }
+ let errorMessage =
+ `Value "${string}" must consist of ` +
+ `either a combination of one or two modifiers, including ` +
+ `a mandatory primary modifier and a key, separated by '+', ` +
+ `or a media key. For details see: ` +
+ `https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/commands#Key_combinations`;
+ throw new Error(errorMessage);
+ },
+
+ manifestShortcutKeyOrEmpty(string, context) {
+ return string === "" ? "" : FORMATS.manifestShortcutKey(string, context);
+ },
+
+ versionString(string, context) {
+ const parts = string.split(".");
+
+ if (
+ // We accept up to 4 numbers.
+ parts.length > 4 ||
+ // Non-zero values cannot start with 0 and we allow numbers up to 9 digits.
+ parts.some(part => !/^(0|[1-9][0-9]{0,8})$/.test(part))
+ ) {
+ context.logWarning(
+ `version must be a version string consisting of at most 4 integers ` +
+ `of at most 9 digits without leading zeros, and separated with dots`
+ );
+ }
+
+ // The idea is to only emit a warning when the version string does not
+ // match the simple format we want to encourage developers to use. Given
+ // the version is required, we always accept the value as is.
+ return string;
+ },
+};
+
+// Schema files contain namespaces, and each namespace contains types,
+// properties, functions, and events. An Entry is a base class for
+// types, properties, functions, and events.
+class Entry {
+ constructor(schema = {}) {
+ /**
+ * If set to any value which evaluates as true, this entry is
+ * deprecated, and any access to it will result in a deprecation
+ * warning being logged to the browser console.
+ *
+ * If the value is a string, it will be appended to the deprecation
+ * message. If it contains the substring "${value}", it will be
+ * replaced with a string representation of the value being
+ * processed.
+ *
+ * If the value is any other truthy value, a generic deprecation
+ * message will be emitted.
+ */
+ this.deprecated = false;
+ if ("deprecated" in schema) {
+ this.deprecated = schema.deprecated;
+ }
+
+ /**
+ * @property {string} [preprocessor]
+ * If set to a string value, and a preprocessor of the same is
+ * defined in the validation context, it will be applied to this
+ * value prior to any normalization.
+ */
+ this.preprocessor = schema.preprocess || null;
+
+ /**
+ * @property {string} [postprocessor]
+ * If set to a string value, and a postprocessor of the same is
+ * defined in the validation context, it will be applied to this
+ * value after any normalization.
+ */
+ this.postprocessor = schema.postprocess || null;
+
+ /**
+ * @property {Array<string>} allowedContexts A list of allowed contexts
+ * to consider before generating the API.
+ * These are not parsed by the schema, but passed to `shouldInject`.
+ */
+ this.allowedContexts = schema.allowedContexts || [];
+
+ this.min_manifest_version =
+ schema.min_manifest_version ?? MIN_MANIFEST_VERSION;
+ this.max_manifest_version =
+ schema.max_manifest_version ?? MAX_MANIFEST_VERSION;
+ }
+
+ /**
+ * Preprocess the given value with the preprocessor declared in
+ * `preprocessor`.
+ *
+ * @param {*} value
+ * @param {Context} context
+ * @returns {*}
+ */
+ preprocess(value, context) {
+ if (this.preprocessor) {
+ return context.preprocessors[this.preprocessor](value, context);
+ }
+ return value;
+ }
+
+ /**
+ * Postprocess the given result with the postprocessor declared in
+ * `postprocessor`.
+ *
+ * @param {object} result
+ * @param {Context} context
+ * @returns {object}
+ */
+ postprocess(result, context) {
+ if (result.error || !this.postprocessor) {
+ return result;
+ }
+
+ let value = context.postprocessors[this.postprocessor](
+ result.value,
+ context
+ );
+ return { value };
+ }
+
+ /**
+ * Logs a deprecation warning for this entry, based on the value of
+ * its `deprecated` property.
+ *
+ * @param {Context} context
+ * @param {any} [value]
+ */
+ logDeprecation(context, value = null) {
+ let message = "This property is deprecated";
+ if (typeof this.deprecated == "string") {
+ message = this.deprecated;
+ if (message.includes("${value}")) {
+ try {
+ value = JSON.stringify(value);
+ } catch (e) {
+ value = String(value);
+ }
+ message = message.replace(/\$\{value\}/g, () => value);
+ }
+ }
+
+ context.logWarning(message);
+ }
+
+ /**
+ * Checks whether the entry is deprecated and, if so, logs a
+ * deprecation message.
+ *
+ * @param {Context} context
+ * @param {any} [value]
+ */
+ checkDeprecated(context, value = null) {
+ if (this.deprecated) {
+ this.logDeprecation(context, value);
+ }
+ }
+
+ /**
+ * Returns an object containing property descriptor for use when
+ * injecting this entry into an API object.
+ *
+ * @param {Array<string>} path The API path, e.g. `["storage", "local"]`.
+ * @param {InjectionContext} context
+ *
+ * @returns {object?}
+ * An object containing a `descriptor` property, specifying the
+ * entry's property descriptor, and an optional `revoke`
+ * method, to be called when the entry is being revoked.
+ */
+ getDescriptor(path, context) {
+ return undefined;
+ }
+}
+
+// Corresponds either to a type declared in the "types" section of the
+// schema or else to any type object used throughout the schema.
+class Type extends Entry {
+ /**
+ * @property {Array<string>} EXTRA_PROPERTIES
+ * An array of extra properties which may be present for
+ * schemas of this type.
+ */
+ static get EXTRA_PROPERTIES() {
+ return [
+ "description",
+ "deprecated",
+ "preprocess",
+ "postprocess",
+ "privileged",
+ "allowedContexts",
+ "min_manifest_version",
+ "max_manifest_version",
+ ];
+ }
+
+ /**
+ * Parses the given schema object and returns an instance of this
+ * class which corresponds to its properties.
+ *
+ * @param {SchemaRoot} root
+ * The root schema for this type.
+ * @param {object} schema
+ * A JSON schema object which corresponds to a definition of
+ * this type.
+ * @param {Array<string>} path
+ * The path to this schema object from the root schema,
+ * corresponding to the property names and array indices
+ * traversed during parsing in order to arrive at this schema
+ * object.
+ * @param {Array<string>} [extraProperties]
+ * An array of extra property names which are valid for this
+ * schema in the current context.
+ * @returns {Type}
+ * An instance of this type which corresponds to the given
+ * schema object.
+ * @static
+ */
+ static parseSchema(root, schema, path, extraProperties = []) {
+ this.checkSchemaProperties(schema, path, extraProperties);
+
+ return new this(schema);
+ }
+
+ /**
+ * Checks that all of the properties present in the given schema
+ * object are valid properties for this type, and throws if invalid.
+ *
+ * @param {object} schema
+ * A JSON schema object.
+ * @param {Array<string>} path
+ * The path to this schema object from the root schema,
+ * corresponding to the property names and array indices
+ * traversed during parsing in order to arrive at this schema
+ * object.
+ * @param {Iterable<string>} [extra]
+ * An array of extra property names which are valid for this
+ * schema in the current context.
+ * @throws {Error}
+ * An error describing the first invalid property found in the
+ * schema object.
+ */
+ static checkSchemaProperties(schema, path, extra = []) {
+ if (DEBUG) {
+ let allowedSet = new Set([...this.EXTRA_PROPERTIES, ...extra]);
+
+ for (let prop of Object.keys(schema)) {
+ if (!allowedSet.has(prop)) {
+ throw new Error(
+ `Internal error: Namespace ${path.join(".")} has ` +
+ `invalid type property "${prop}" ` +
+ `in type "${schema.id || JSON.stringify(schema)}"`
+ );
+ }
+ }
+ }
+ }
+
+ // Takes a value, checks that it has the correct type, and returns a
+ // "normalized" version of the value. The normalized version will
+ // include "nulls" in place of omitted optional properties. The
+ // result of this function is either {error: "Some type error"} or
+ // {value: <normalized-value>}.
+ normalize(value, context) {
+ return context.error("invalid type");
+ }
+
+ // Unlike normalize, this function does a shallow check to see if
+ // |baseType| (one of the possible getValueBaseType results) is
+ // valid for this type. It returns true or false. It's used to fill
+ // in optional arguments to functions before actually type checking
+
+ checkBaseType(baseType) {
+ return false;
+ }
+
+ // Helper method that simply relies on checkBaseType to implement
+ // normalize. Subclasses can choose to use it or not.
+ normalizeBase(type, value, context) {
+ if (this.checkBaseType(getValueBaseType(value))) {
+ this.checkDeprecated(context, value);
+ return { value: this.preprocess(value, context) };
+ }
+
+ let choice;
+ if ("aeiou".includes(type[0])) {
+ choice = `be an ${type} value`;
+ } else {
+ choice = `be a ${type} value`;
+ }
+
+ return context.error(
+ () => `Expected ${type} instead of ${JSON.stringify(value)}`,
+ choice
+ );
+ }
+}
+
+// Type that allows any value.
+class AnyType extends Type {
+ normalize(value, context) {
+ this.checkDeprecated(context, value);
+ return this.postprocess({ value }, context);
+ }
+
+ checkBaseType(baseType) {
+ return true;
+ }
+}
+
+// An untagged union type.
+class ChoiceType extends Type {
+ static get EXTRA_PROPERTIES() {
+ return ["choices", ...super.EXTRA_PROPERTIES];
+ }
+
+ /** @type {(root, schema, path, extraProperties?: Iterable) => ChoiceType} */
+ static parseSchema(root, schema, path, extraProperties = []) {
+ this.checkSchemaProperties(schema, path, extraProperties);
+
+ let choices = schema.choices.map(t => root.parseSchema(t, path));
+ return new this(schema, choices);
+ }
+
+ constructor(schema, choices) {
+ super(schema);
+ this.choices = choices;
+ }
+
+ extend(type) {
+ this.choices.push(...type.choices);
+
+ return this;
+ }
+
+ normalize(value, context) {
+ this.checkDeprecated(context, value);
+
+ let error;
+ let { choices, result } = context.withChoices(() => {
+ for (let choice of this.choices) {
+ // Ignore a possible choice if it is not supported by
+ // the manifest version we are normalizing.
+ if (!context.matchManifestVersion(choice)) {
+ continue;
+ }
+
+ let r = choice.normalize(value, context);
+ if (!r.error) {
+ return r;
+ }
+
+ error = r;
+ }
+ });
+
+ if (result) {
+ return result;
+ }
+ if (choices.size <= 1) {
+ return error;
+ }
+
+ choices = Array.from(choices, forceString);
+ let n = choices.length - 1;
+ choices[n] = `or ${choices[n]}`;
+
+ let message;
+ if (typeof value === "object") {
+ message = () => `Value must either: ${choices.join(", ")}`;
+ } else {
+ message = () =>
+ `Value ${JSON.stringify(value)} must either: ${choices.join(", ")}`;
+ }
+
+ return context.error(message, null);
+ }
+
+ checkBaseType(baseType) {
+ return this.choices.some(t => t.checkBaseType(baseType));
+ }
+
+ getDescriptor(path, context) {
+ // In StringType.getDescriptor, unlike any other Type, a descriptor is returned if
+ // it is an enumeration. Since we need versioned choices in some cases, here we
+ // build a list of valid enumerations that will work for a given manifest version.
+ if (
+ !this.choices.length ||
+ !this.choices.every(t => t.checkBaseType("string") && t.enumeration)
+ ) {
+ return;
+ }
+
+ let obj = Cu.createObjectIn(context.cloneScope);
+ let descriptor = { value: obj };
+ for (let choice of this.choices) {
+ // Ignore a possible choice if it is not supported by
+ // the manifest version we are normalizing.
+ if (!context.matchManifestVersion(choice)) {
+ continue;
+ }
+ let d = choice.getDescriptor(path, context);
+ if (d) {
+ Object.assign(obj, d.descriptor.value);
+ }
+ }
+
+ return { descriptor };
+ }
+}
+
+// This is a reference to another type--essentially a typedef.
+class RefType extends Type {
+ static get EXTRA_PROPERTIES() {
+ return ["$ref", ...super.EXTRA_PROPERTIES];
+ }
+
+ /** @type {(root, schema, path, extraProperties?: Iterable) => RefType} */
+ static parseSchema(root, schema, path, extraProperties = []) {
+ this.checkSchemaProperties(schema, path, extraProperties);
+
+ let ref = schema.$ref;
+ let ns = path.join(".");
+ if (ref.includes(".")) {
+ [, ns, ref] = /^(.*)\.(.*?)$/.exec(ref);
+ }
+ return new this(root, schema, ns, ref);
+ }
+
+ // For a reference to a type named T declared in namespace NS,
+ // namespaceName will be NS and reference will be T.
+ constructor(root, schema, namespaceName, reference) {
+ super(schema);
+ this.root = root;
+ this.namespaceName = namespaceName;
+ this.reference = reference;
+ }
+
+ get targetType() {
+ let ns = this.root.getNamespace(this.namespaceName);
+ let type = ns.get(this.reference);
+ if (!type) {
+ throw new Error(`Internal error: Type ${this.reference} not found`);
+ }
+ return type;
+ }
+
+ normalize(value, context) {
+ this.checkDeprecated(context, value);
+ return this.targetType.normalize(value, context);
+ }
+
+ checkBaseType(baseType) {
+ return this.targetType.checkBaseType(baseType);
+ }
+}
+
+class StringType extends Type {
+ static get EXTRA_PROPERTIES() {
+ return [
+ "enum",
+ "minLength",
+ "maxLength",
+ "pattern",
+ "format",
+ ...super.EXTRA_PROPERTIES,
+ ];
+ }
+
+ static parseSchema(root, schema, path, extraProperties = []) {
+ this.checkSchemaProperties(schema, path, extraProperties);
+
+ let enumeration = schema.enum || null;
+ if (enumeration) {
+ // The "enum" property is either a list of strings that are
+ // valid values or else a list of {name, description} objects,
+ // where the .name values are the valid values.
+ enumeration = enumeration.map(e => {
+ if (typeof e == "object") {
+ return e.name;
+ }
+ return e;
+ });
+ }
+
+ let pattern = null;
+ if (schema.pattern) {
+ try {
+ pattern = parsePattern(schema.pattern);
+ } catch (e) {
+ throw new Error(
+ `Internal error: Invalid pattern ${JSON.stringify(schema.pattern)}`
+ );
+ }
+ }
+
+ let format = null;
+ if (schema.format) {
+ if (!(schema.format in FORMATS)) {
+ throw new Error(
+ `Internal error: Invalid string format ${schema.format}`
+ );
+ }
+ format = FORMATS[schema.format];
+ }
+ return new this(
+ schema,
+ schema.id || undefined,
+ enumeration,
+ schema.minLength || 0,
+ schema.maxLength || Infinity,
+ pattern,
+ format
+ );
+ }
+
+ constructor(
+ schema,
+ name,
+ enumeration,
+ minLength,
+ maxLength,
+ pattern,
+ format
+ ) {
+ super(schema);
+ this.name = name;
+ this.enumeration = enumeration;
+ this.minLength = minLength;
+ this.maxLength = maxLength;
+ this.pattern = pattern;
+ this.format = format;
+ }
+
+ normalize(value, context) {
+ let r = this.normalizeBase("string", value, context);
+ if (r.error) {
+ return r;
+ }
+ value = r.value;
+
+ if (this.enumeration) {
+ if (this.enumeration.includes(value)) {
+ return this.postprocess({ value }, context);
+ }
+
+ let choices = this.enumeration.map(JSON.stringify).join(", ");
+
+ return context.error(
+ () => `Invalid enumeration value ${JSON.stringify(value)}`,
+ `be one of [${choices}]`
+ );
+ }
+
+ if (value.length < this.minLength) {
+ return context.error(
+ () =>
+ `String ${JSON.stringify(value)} is too short (must be ${
+ this.minLength
+ })`,
+ `be longer than ${this.minLength}`
+ );
+ }
+ if (value.length > this.maxLength) {
+ return context.error(
+ () =>
+ `String ${JSON.stringify(value)} is too long (must be ${
+ this.maxLength
+ })`,
+ `be shorter than ${this.maxLength}`
+ );
+ }
+
+ if (this.pattern && !this.pattern.test(value)) {
+ return context.error(
+ () => `String ${JSON.stringify(value)} must match ${this.pattern}`,
+ `match the pattern ${this.pattern.toSource()}`
+ );
+ }
+
+ if (this.format) {
+ try {
+ r.value = this.format(r.value, context);
+ } catch (e) {
+ return context.error(
+ String(e),
+ `match the format "${this.format.name}"`
+ );
+ }
+ }
+
+ return r;
+ }
+
+ checkBaseType(baseType) {
+ return baseType == "string";
+ }
+
+ getDescriptor(path, context) {
+ if (this.enumeration) {
+ let obj = Cu.createObjectIn(context.cloneScope);
+
+ for (let e of this.enumeration) {
+ obj[e.toUpperCase()] = e;
+ }
+
+ return {
+ descriptor: { value: obj },
+ };
+ }
+ }
+}
+
+class NullType extends Type {
+ normalize(value, context) {
+ return this.normalizeBase("null", value, context);
+ }
+
+ checkBaseType(baseType) {
+ return baseType == "null";
+ }
+}
+
+let FunctionEntry;
+let Event;
+let SubModuleType;
+
+class ObjectType extends Type {
+ static get EXTRA_PROPERTIES() {
+ return [
+ "properties",
+ "patternProperties",
+ "$import",
+ ...super.EXTRA_PROPERTIES,
+ ];
+ }
+
+ static parseSchema(root, schema, path, extraProperties = []) {
+ if ("functions" in schema) {
+ return SubModuleType.parseSchema(root, schema, path, extraProperties);
+ }
+
+ if (DEBUG && !("$extend" in schema)) {
+ // Only allow extending "properties" and "patternProperties".
+ extraProperties = [
+ "additionalProperties",
+ "isInstanceOf",
+ ...extraProperties,
+ ];
+ }
+ this.checkSchemaProperties(schema, path, extraProperties);
+
+ let imported = null;
+ if ("$import" in schema) {
+ let importPath = schema.$import;
+ let idx = importPath.indexOf(".");
+ if (idx === -1) {
+ imported = [path[0], importPath];
+ } else {
+ imported = [importPath.slice(0, idx), importPath.slice(idx + 1)];
+ }
+ }
+
+ let parseProperty = (schema, extraProps = []) => {
+ return {
+ type: root.parseSchema(
+ schema,
+ path,
+ DEBUG && [
+ "unsupported",
+ "onError",
+ "permissions",
+ "default",
+ ...extraProps,
+ ]
+ ),
+ optional: schema.optional || false,
+ unsupported: schema.unsupported || false,
+ onError: schema.onError || null,
+ default: schema.default === undefined ? null : schema.default,
+ };
+ };
+
+ // Parse explicit "properties" object.
+ let properties = Object.create(null);
+ for (let propName of Object.keys(schema.properties || {})) {
+ properties[propName] = parseProperty(schema.properties[propName], [
+ "optional",
+ ]);
+ }
+
+ // Parse regexp properties from "patternProperties" object.
+ let patternProperties = [];
+ for (let propName of Object.keys(schema.patternProperties || {})) {
+ let pattern;
+ try {
+ pattern = parsePattern(propName);
+ } catch (e) {
+ throw new Error(
+ `Internal error: Invalid property pattern ${JSON.stringify(propName)}`
+ );
+ }
+
+ patternProperties.push({
+ pattern,
+ type: parseProperty(schema.patternProperties[propName]),
+ });
+ }
+
+ // Parse "additionalProperties" schema.
+ let additionalProperties = null;
+ if (schema.additionalProperties) {
+ let type = schema.additionalProperties;
+ if (type === true) {
+ type = { type: "any" };
+ }
+
+ additionalProperties = root.parseSchema(type, path);
+ }
+
+ return new this(
+ schema,
+ properties,
+ additionalProperties,
+ patternProperties,
+ schema.isInstanceOf || null,
+ imported
+ );
+ }
+
+ constructor(
+ schema,
+ properties,
+ additionalProperties,
+ patternProperties,
+ isInstanceOf,
+ imported
+ ) {
+ super(schema);
+ this.properties = properties;
+ this.additionalProperties = additionalProperties;
+ this.patternProperties = patternProperties;
+ this.isInstanceOf = isInstanceOf;
+
+ if (imported) {
+ let [ns, path] = imported;
+ ns = Schemas.getNamespace(ns);
+ let importedType = ns.get(path);
+ if (!importedType) {
+ throw new Error(`Internal error: imported type ${path} not found`);
+ }
+
+ if (DEBUG && !(importedType instanceof ObjectType)) {
+ throw new Error(
+ `Internal error: cannot import non-object type ${path}`
+ );
+ }
+
+ this.properties = Object.assign(
+ {},
+ importedType.properties,
+ this.properties
+ );
+ this.patternProperties = [
+ ...importedType.patternProperties,
+ ...this.patternProperties,
+ ];
+ this.additionalProperties =
+ importedType.additionalProperties || this.additionalProperties;
+ }
+ }
+
+ extend(type) {
+ for (let key of Object.keys(type.properties)) {
+ if (key in this.properties) {
+ throw new Error(
+ `InternalError: Attempt to extend an object with conflicting property "${key}"`
+ );
+ }
+ this.properties[key] = type.properties[key];
+ }
+
+ this.patternProperties.push(...type.patternProperties);
+
+ return this;
+ }
+
+ checkBaseType(baseType) {
+ return baseType == "object";
+ }
+
+ /**
+ * Extracts the enumerable properties of the given object, including
+ * function properties which would normally be omitted by X-ray
+ * wrappers.
+ *
+ * @param {object} value
+ * @param {Context} context
+ * The current parse context.
+ * @returns {object}
+ * An object with an `error` or `value` property.
+ */
+ extractProperties(value, context) {
+ // |value| should be a JS Xray wrapping an object in the
+ // extension compartment. This works well except when we need to
+ // access callable properties on |value| since JS Xrays don't
+ // support those. To work around the problem, we verify that
+ // |value| is a plain JS object (i.e., not anything scary like a
+ // Proxy). Then we copy the properties out of it into a normal
+ // object using a waiver wrapper.
+
+ let klass = ChromeUtils.getClassName(value, true);
+ if (klass != "Object") {
+ throw context.error(
+ `Expected a plain JavaScript object, got a ${klass}`,
+ `be a plain JavaScript object`
+ );
+ }
+
+ return ChromeUtils.shallowClone(value);
+ }
+
+ checkProperty(context, prop, propType, result, properties, remainingProps) {
+ let { type, optional, unsupported, onError } = propType;
+ let error = null;
+
+ if (!context.matchManifestVersion(type)) {
+ if (prop in properties) {
+ error = context.error(
+ `Property "${prop}" is unsupported in Manifest Version ${context.manifestVersion}`,
+ `not contain an unsupported "${prop}" property`
+ );
+
+ context.logWarning(forceString(error.error));
+ if (this.additionalProperties) {
+ // When `additionalProperties` is set to UnrecognizedProperty, the
+ // caller (i.e. ObjectType's normalize method) assigns the original
+ // value to `result[prop]`. Erase the property now to prevent
+ // `result[prop]` from becoming anything other than `undefined.
+ //
+ // A warning was already logged above, so we do not need to also log
+ // "An unexpected property was found in the WebExtension manifest."
+ remainingProps.delete(prop);
+ }
+ // When `additionalProperties` is not set, ObjectType's normalize method
+ // will return an error because prop is still in remainingProps.
+ return;
+ }
+ } else if (unsupported) {
+ if (prop in properties) {
+ error = context.error(
+ `Property "${prop}" is unsupported by Firefox`,
+ `not contain an unsupported "${prop}" property`
+ );
+ }
+ } else if (prop in properties) {
+ if (
+ optional &&
+ (properties[prop] === null || properties[prop] === undefined)
+ ) {
+ result[prop] = propType.default;
+ } else {
+ let r = context.withPath(prop, () =>
+ type.normalize(properties[prop], context)
+ );
+ if (r.error) {
+ error = r;
+ } else {
+ result[prop] = r.value;
+ properties[prop] = r.value;
+ }
+ }
+ remainingProps.delete(prop);
+ } else if (!optional) {
+ error = context.error(
+ `Property "${prop}" is required`,
+ `contain the required "${prop}" property`
+ );
+ } else if (optional !== "omit-key-if-missing") {
+ result[prop] = propType.default;
+ }
+
+ if (error) {
+ if (onError == "warn") {
+ context.logWarning(forceString(error.error));
+ } else if (onError != "ignore") {
+ throw error;
+ }
+
+ result[prop] = propType.default;
+ }
+ }
+
+ normalize(value, context) {
+ try {
+ let v = this.normalizeBase("object", value, context);
+ if (v.error) {
+ return v;
+ }
+ value = v.value;
+
+ if (this.isInstanceOf) {
+ if (DEBUG) {
+ if (
+ Object.keys(this.properties).length ||
+ this.patternProperties.length ||
+ !(this.additionalProperties instanceof AnyType)
+ ) {
+ throw new Error(
+ "InternalError: isInstanceOf can only be used " +
+ "with objects that are otherwise unrestricted"
+ );
+ }
+ }
+
+ if (
+ ChromeUtils.getClassName(value) !== this.isInstanceOf &&
+ (this.isInstanceOf !== "Element" || value.nodeType !== 1)
+ ) {
+ return context.error(
+ `Object must be an instance of ${this.isInstanceOf}`,
+ `be an instance of ${this.isInstanceOf}`
+ );
+ }
+
+ // This is kind of a hack, but we can't normalize things that
+ // aren't JSON, so we just return them.
+ return this.postprocess({ value }, context);
+ }
+
+ let properties = this.extractProperties(value, context);
+ let remainingProps = new Set(Object.keys(properties));
+
+ let result = {};
+ for (let prop of Object.keys(this.properties)) {
+ this.checkProperty(
+ context,
+ prop,
+ this.properties[prop],
+ result,
+ properties,
+ remainingProps
+ );
+ }
+
+ for (let prop of Object.keys(properties)) {
+ for (let { pattern, type } of this.patternProperties) {
+ if (pattern.test(prop)) {
+ this.checkProperty(
+ context,
+ prop,
+ type,
+ result,
+ properties,
+ remainingProps
+ );
+ }
+ }
+ }
+
+ if (this.additionalProperties) {
+ for (let prop of remainingProps) {
+ let r = context.withPath(prop, () =>
+ this.additionalProperties.normalize(properties[prop], context)
+ );
+ if (r.error) {
+ return r;
+ }
+ result[prop] = r.value;
+ }
+ } else if (remainingProps.size == 1) {
+ return context.error(
+ `Unexpected property "${[...remainingProps]}"`,
+ `not contain an unexpected "${[...remainingProps]}" property`
+ );
+ } else if (remainingProps.size) {
+ let props = [...remainingProps].sort().join(", ");
+ return context.error(
+ `Unexpected properties: ${props}`,
+ `not contain the unexpected properties [${props}]`
+ );
+ }
+
+ return this.postprocess({ value: result }, context);
+ } catch (e) {
+ if (e.error) {
+ return e;
+ }
+ throw e;
+ }
+ }
+}
+
+// This type is just a placeholder to be referred to by
+// SubModuleProperty. No value is ever expected to have this type.
+SubModuleType = class SubModuleType extends Type {
+ static get EXTRA_PROPERTIES() {
+ return ["functions", "events", "properties", ...super.EXTRA_PROPERTIES];
+ }
+
+ static parseSchema(root, schema, path, extraProperties = []) {
+ this.checkSchemaProperties(schema, path, extraProperties);
+
+ // The path we pass in here is only used for error messages.
+ path = [...path, schema.id];
+ let functions = schema.functions
+ .filter(fun => !fun.unsupported)
+ .map(fun => FunctionEntry.parseSchema(root, fun, path));
+
+ let events = [];
+
+ if (schema.events) {
+ events = schema.events
+ .filter(event => !event.unsupported)
+ .map(event => Event.parseSchema(root, event, path));
+ }
+
+ return new this(schema, functions, events);
+ }
+
+ constructor(schema, functions, events) {
+ // schema contains properties such as min/max_manifest_version needed
+ // in the base class so that the Context class can version compare
+ // any entries against the manifest version.
+ super(schema);
+ this.functions = functions;
+ this.events = events;
+ }
+};
+
+class NumberType extends Type {
+ normalize(value, context) {
+ let r = this.normalizeBase("number", value, context);
+ if (r.error) {
+ return r;
+ }
+
+ if (isNaN(r.value) || !Number.isFinite(r.value)) {
+ return context.error(
+ "NaN and infinity are not valid",
+ "be a finite number"
+ );
+ }
+
+ return r;
+ }
+
+ checkBaseType(baseType) {
+ return baseType == "number" || baseType == "integer";
+ }
+}
+
+class IntegerType extends Type {
+ static get EXTRA_PROPERTIES() {
+ return ["minimum", "maximum", ...super.EXTRA_PROPERTIES];
+ }
+
+ static parseSchema(root, schema, path, extraProperties = []) {
+ this.checkSchemaProperties(schema, path, extraProperties);
+
+ let { minimum = -Infinity, maximum = Infinity } = schema;
+ return new this(schema, minimum, maximum);
+ }
+
+ constructor(schema, minimum, maximum) {
+ super(schema);
+ this.minimum = minimum;
+ this.maximum = maximum;
+ }
+
+ normalize(value, context) {
+ let r = this.normalizeBase("integer", value, context);
+ if (r.error) {
+ return r;
+ }
+ value = r.value;
+
+ // Ensure it's between -2**31 and 2**31-1
+ if (!Number.isSafeInteger(value)) {
+ return context.error(
+ "Integer is out of range",
+ "be a valid 32 bit signed integer"
+ );
+ }
+
+ if (value < this.minimum) {
+ return context.error(
+ `Integer ${value} is too small (must be at least ${this.minimum})`,
+ `be at least ${this.minimum}`
+ );
+ }
+ if (value > this.maximum) {
+ return context.error(
+ `Integer ${value} is too big (must be at most ${this.maximum})`,
+ `be no greater than ${this.maximum}`
+ );
+ }
+
+ return this.postprocess(r, context);
+ }
+
+ checkBaseType(baseType) {
+ return baseType == "integer";
+ }
+}
+
+class BooleanType extends Type {
+ static get EXTRA_PROPERTIES() {
+ return ["enum", ...super.EXTRA_PROPERTIES];
+ }
+
+ static parseSchema(root, schema, path, extraProperties = []) {
+ this.checkSchemaProperties(schema, path, extraProperties);
+ let enumeration = schema.enum || null;
+ return new this(schema, enumeration);
+ }
+
+ constructor(schema, enumeration) {
+ super(schema);
+ this.enumeration = enumeration;
+ }
+
+ normalize(value, context) {
+ if (!this.checkBaseType(getValueBaseType(value))) {
+ return context.error(
+ () => `Expected boolean instead of ${JSON.stringify(value)}`,
+ `be a boolean`
+ );
+ }
+ value = this.preprocess(value, context);
+ if (this.enumeration && !this.enumeration.includes(value)) {
+ return context.error(
+ () => `Invalid value ${JSON.stringify(value)}`,
+ `be ${this.enumeration}`
+ );
+ }
+ this.checkDeprecated(context, value);
+ return { value };
+ }
+
+ checkBaseType(baseType) {
+ return baseType == "boolean";
+ }
+}
+
+class ArrayType extends Type {
+ static get EXTRA_PROPERTIES() {
+ return ["items", "minItems", "maxItems", ...super.EXTRA_PROPERTIES];
+ }
+
+ static parseSchema(root, schema, path, extraProperties = []) {
+ this.checkSchemaProperties(schema, path, extraProperties);
+
+ let items = root.parseSchema(schema.items, path, ["onError"]);
+
+ return new this(
+ schema,
+ items,
+ schema.minItems || 0,
+ schema.maxItems || Infinity
+ );
+ }
+
+ constructor(schema, itemType, minItems, maxItems) {
+ super(schema);
+ this.itemType = itemType;
+ this.minItems = minItems;
+ this.maxItems = maxItems;
+ this.onError = schema.items.onError || null;
+ }
+
+ normalize(value, context) {
+ let v = this.normalizeBase("array", value, context);
+ if (v.error) {
+ return v;
+ }
+ value = v.value;
+
+ let result = [];
+ for (let [i, element] of value.entries()) {
+ element = context.withPath(String(i), () =>
+ this.itemType.normalize(element, context)
+ );
+ if (element.error) {
+ if (this.onError == "warn") {
+ context.logWarning(forceString(element.error));
+ } else if (this.onError != "ignore") {
+ return element;
+ }
+ continue;
+ }
+ result.push(element.value);
+ }
+
+ if (result.length < this.minItems) {
+ return context.error(
+ `Array requires at least ${this.minItems} items; you have ${result.length}`,
+ `have at least ${this.minItems} items`
+ );
+ }
+
+ if (result.length > this.maxItems) {
+ return context.error(
+ `Array requires at most ${this.maxItems} items; you have ${result.length}`,
+ `have at most ${this.maxItems} items`
+ );
+ }
+
+ return this.postprocess({ value: result }, context);
+ }
+
+ checkBaseType(baseType) {
+ return baseType == "array";
+ }
+}
+
+class FunctionType extends Type {
+ static get EXTRA_PROPERTIES() {
+ return [
+ "parameters",
+ "async",
+ "returns",
+ "requireUserInput",
+ ...super.EXTRA_PROPERTIES,
+ ];
+ }
+
+ static parseSchema(root, schema, path, extraProperties = []) {
+ this.checkSchemaProperties(schema, path, extraProperties);
+
+ let isAsync = !!schema.async;
+ let isExpectingCallback = typeof schema.async === "string";
+ let parameters = null;
+ if ("parameters" in schema) {
+ parameters = [];
+ for (let param of schema.parameters) {
+ // Callbacks default to optional for now, because of promise
+ // handling.
+ let isCallback = isAsync && param.name == schema.async;
+ if (isCallback) {
+ isExpectingCallback = false;
+ }
+
+ parameters.push({
+ type: root.parseSchema(param, path, ["name", "optional", "default"]),
+ name: param.name,
+ optional: param.optional == null ? isCallback : param.optional,
+ default: param.default == undefined ? null : param.default,
+ });
+ }
+ }
+ let hasAsyncCallback = false;
+ if (isAsync) {
+ hasAsyncCallback =
+ parameters &&
+ parameters.length &&
+ parameters[parameters.length - 1].name == schema.async;
+ }
+
+ if (DEBUG) {
+ if (isExpectingCallback) {
+ throw new Error(
+ `Internal error: Expected a callback parameter ` +
+ `with name ${schema.async}`
+ );
+ }
+
+ if (isAsync && schema.returns) {
+ throw new Error(
+ "Internal error: Async functions must not have return values."
+ );
+ }
+ if (
+ isAsync &&
+ schema.allowAmbiguousOptionalArguments &&
+ !hasAsyncCallback
+ ) {
+ throw new Error(
+ "Internal error: Async functions with ambiguous " +
+ "arguments must declare the callback as the last parameter"
+ );
+ }
+ }
+
+ return new this(
+ schema,
+ parameters,
+ isAsync,
+ hasAsyncCallback,
+ !!schema.requireUserInput
+ );
+ }
+
+ constructor(schema, parameters, isAsync, hasAsyncCallback, requireUserInput) {
+ super(schema);
+ this.parameters = parameters;
+ this.isAsync = isAsync;
+ this.hasAsyncCallback = hasAsyncCallback;
+ this.requireUserInput = requireUserInput;
+ }
+
+ normalize(value, context) {
+ return this.normalizeBase("function", value, context);
+ }
+
+ checkBaseType(baseType) {
+ return baseType == "function";
+ }
+}
+
+// Represents a "property" defined in a schema namespace with a
+// particular value. Essentially this is a constant.
+class ValueProperty extends Entry {
+ constructor(schema, name, value) {
+ super(schema);
+ this.name = name;
+ this.value = value;
+ }
+
+ getDescriptor(path, context) {
+ // Prevent injection if not a supported version.
+ if (!context.matchManifestVersion(this)) {
+ return;
+ }
+
+ return {
+ descriptor: { value: this.value },
+ };
+ }
+}
+
+// Represents a "property" defined in a schema namespace that is not a
+// constant.
+class TypeProperty extends Entry {
+ unsupported = false;
+
+ constructor(schema, path, name, type, writable, permissions) {
+ super(schema);
+ this.path = path;
+ this.name = name;
+ this.type = type;
+ this.writable = writable;
+ this.permissions = permissions;
+ }
+
+ throwError(context, msg) {
+ throw context.makeError(`${msg} for ${this.path.join(".")}.${this.name}.`);
+ }
+
+ getDescriptor(path, context) {
+ if (this.unsupported || !context.matchManifestVersion(this)) {
+ return;
+ }
+
+ let apiImpl = context.getImplementation(path.join("."), this.name);
+
+ let getStub = () => {
+ this.checkDeprecated(context);
+ return apiImpl.getProperty();
+ };
+
+ let descriptor = {
+ get: Cu.exportFunction(getStub, context.cloneScope),
+ };
+
+ if (this.writable) {
+ let setStub = value => {
+ let normalized = this.type.normalize(value, context);
+ if (normalized.error) {
+ this.throwError(context, forceString(normalized.error));
+ }
+
+ apiImpl.setProperty(normalized.value);
+ };
+
+ descriptor.set = Cu.exportFunction(setStub, context.cloneScope);
+ }
+
+ return {
+ descriptor,
+ revoke() {
+ apiImpl.revoke();
+ apiImpl = null;
+ },
+ };
+ }
+}
+
+class SubModuleProperty extends Entry {
+ // A SubModuleProperty represents a tree of objects and properties
+ // to expose to an extension. Currently we support only a limited
+ // form of sub-module properties, where "$ref" points to a
+ // SubModuleType containing a list of functions and "properties" is
+ // a list of additional simple properties.
+ //
+ // name: Name of the property stuff is being added to.
+ // namespaceName: Namespace in which the property lives.
+ // reference: Name of the type defining the functions to add to the property.
+ // properties: Additional properties to add to the module (unsupported).
+ constructor(root, schema, path, name, reference, properties, permissions) {
+ super(schema);
+ this.root = root;
+ this.name = name;
+ this.path = path;
+ this.namespaceName = path.join(".");
+ this.reference = reference;
+ this.properties = properties;
+ this.permissions = permissions;
+ }
+
+ get targetType() {
+ let ns = this.root.getNamespace(this.namespaceName);
+ let type = ns.get(this.reference);
+ if (!type && this.reference.includes(".")) {
+ let [namespaceName, ref] = this.reference.split(".");
+ ns = this.root.getNamespace(namespaceName);
+ type = ns.get(ref);
+ }
+ return type;
+ }
+
+ getDescriptor(path, context) {
+ let obj = Cu.createObjectIn(context.cloneScope);
+
+ let ns = this.root.getNamespace(this.namespaceName);
+ let type = this.targetType;
+
+ // Prevent injection if not a supported version.
+ if (!context.matchManifestVersion(type)) {
+ return;
+ }
+
+ if (DEBUG) {
+ if (!type || !(type instanceof SubModuleType)) {
+ throw new Error(
+ `Internal error: ${this.namespaceName}.${this.reference} ` +
+ `is not a sub-module`
+ );
+ }
+ }
+ let subpath = [...path, this.name];
+
+ let functions = type.functions;
+ for (let fun of functions) {
+ context.injectInto(fun, obj, fun.name, subpath, ns);
+ }
+
+ let events = type.events;
+ for (let event of events) {
+ context.injectInto(event, obj, event.name, subpath, ns);
+ }
+
+ // TODO: Inject this.properties.
+
+ return {
+ descriptor: { value: obj },
+ revoke() {
+ let unwrapped = ChromeUtils.waiveXrays(obj);
+ for (let fun of functions) {
+ try {
+ delete unwrapped[fun.name];
+ } catch (e) {
+ Cu.reportError(e);
+ }
+ }
+ },
+ };
+ }
+}
+
+// This class is a base class for FunctionEntrys and Events. It takes
+// care of validating parameter lists (i.e., handling of optional
+// parameters and parameter type checking).
+class CallEntry extends Entry {
+ hasAsyncCallback = false;
+
+ constructor(schema, path, name, parameters, allowAmbiguousOptionalArguments) {
+ super(schema);
+ this.path = path;
+ this.name = name;
+ this.parameters = parameters;
+ this.allowAmbiguousOptionalArguments = allowAmbiguousOptionalArguments;
+ }
+
+ throwError(context, msg) {
+ throw context.makeError(`${msg} for ${this.path.join(".")}.${this.name}.`);
+ }
+
+ checkParameters(args, context) {
+ let fixedArgs = [];
+
+ // First we create a new array, fixedArgs, that is the same as
+ // |args| but with default values in place of omitted optional parameters.
+ let check = (parameterIndex, argIndex) => {
+ if (parameterIndex == this.parameters.length) {
+ if (argIndex == args.length) {
+ return true;
+ }
+ return false;
+ }
+
+ let parameter = this.parameters[parameterIndex];
+ if (parameter.optional) {
+ // Try skipping it.
+ fixedArgs[parameterIndex] = parameter.default;
+ if (check(parameterIndex + 1, argIndex)) {
+ return true;
+ }
+ }
+
+ if (argIndex == args.length) {
+ return false;
+ }
+
+ let arg = args[argIndex];
+ if (!parameter.type.checkBaseType(getValueBaseType(arg))) {
+ // For Chrome compatibility, use the default value if null or undefined
+ // is explicitly passed but is not a valid argument in this position.
+ if (parameter.optional && (arg === null || arg === undefined)) {
+ fixedArgs[parameterIndex] = Cu.cloneInto(parameter.default, {});
+ } else {
+ return false;
+ }
+ } else {
+ fixedArgs[parameterIndex] = arg;
+ }
+
+ return check(parameterIndex + 1, argIndex + 1);
+ };
+
+ if (this.allowAmbiguousOptionalArguments) {
+ // When this option is set, it's up to the implementation to
+ // parse arguments.
+ // The last argument for asynchronous methods is either a function or null.
+ // This is specifically done for runtime.sendMessage.
+ if (this.hasAsyncCallback && typeof args[args.length - 1] != "function") {
+ args.push(null);
+ }
+ return args;
+ }
+ let success = check(0, 0);
+ if (!success) {
+ this.throwError(context, "Incorrect argument types");
+ }
+
+ // Now we normalize (and fully type check) all non-omitted arguments.
+ fixedArgs = fixedArgs.map((arg, parameterIndex) => {
+ if (arg === null) {
+ return null;
+ }
+ let parameter = this.parameters[parameterIndex];
+ let r = parameter.type.normalize(arg, context);
+ if (r.error) {
+ this.throwError(
+ context,
+ `Type error for parameter ${parameter.name} (${forceString(r.error)})`
+ );
+ }
+ return r.value;
+ });
+
+ return fixedArgs;
+ }
+}
+
+// Represents a "function" defined in a schema namespace.
+FunctionEntry = class FunctionEntry extends CallEntry {
+ static parseSchema(root, schema, path) {
+ // When not in DEBUG mode, we just need to know *if* this returns.
+ /** @type {boolean|object} */
+ let returns = !!schema.returns;
+ if (DEBUG && "returns" in schema) {
+ returns = {
+ type: root.parseSchema(schema.returns, path, ["optional", "name"]),
+ optional: schema.returns.optional || false,
+ name: "result",
+ };
+ }
+
+ return new this(
+ schema,
+ path,
+ schema.name,
+ root.parseSchema(schema, path, [
+ "name",
+ "unsupported",
+ "returns",
+ "permissions",
+ "allowAmbiguousOptionalArguments",
+ "allowCrossOriginArguments",
+ ]),
+ schema.unsupported || false,
+ schema.allowAmbiguousOptionalArguments || false,
+ schema.allowCrossOriginArguments || false,
+ returns,
+ schema.permissions || null
+ );
+ }
+
+ constructor(
+ schema,
+ path,
+ name,
+ type,
+ unsupported,
+ allowAmbiguousOptionalArguments,
+ allowCrossOriginArguments,
+ returns,
+ permissions
+ ) {
+ super(schema, path, name, type.parameters, allowAmbiguousOptionalArguments);
+ this.unsupported = unsupported;
+ this.returns = returns;
+ this.permissions = permissions;
+ this.allowCrossOriginArguments = allowCrossOriginArguments;
+
+ this.isAsync = type.isAsync;
+ this.hasAsyncCallback = type.hasAsyncCallback;
+ this.requireUserInput = type.requireUserInput;
+ }
+
+ checkValue({ type, optional, name }, value, context) {
+ if (optional && value == null) {
+ return;
+ }
+ if (
+ type.reference === "ExtensionPanel" ||
+ type.reference === "ExtensionSidebarPane" ||
+ type.reference === "Port"
+ ) {
+ // TODO: We currently treat objects with functions as SubModuleType,
+ // which is just wrong, and a bigger yak. Skipping for now.
+ return;
+ }
+ const { error } = type.normalize(value, context);
+ if (error) {
+ this.throwError(
+ context,
+ `Type error for ${name} value (${forceString(error)})`
+ );
+ }
+ }
+
+ checkCallback(args, context) {
+ const callback = this.parameters[this.parameters.length - 1];
+ for (const [i, param] of callback.type.parameters.entries()) {
+ this.checkValue(param, args[i], context);
+ }
+ }
+
+ getDescriptor(path, context) {
+ let apiImpl = context.getImplementation(path.join("."), this.name);
+
+ let stub;
+ if (this.isAsync) {
+ stub = (...args) => {
+ this.checkDeprecated(context);
+ let actuals = this.checkParameters(args, context);
+ let callback = null;
+ if (this.hasAsyncCallback) {
+ callback = actuals.pop();
+ }
+ if (callback === null && context.isChromeCompat) {
+ // We pass an empty stub function as a default callback for
+ // the `chrome` API, so promise objects are not returned,
+ // and lastError values are reported immediately.
+ callback = () => {};
+ }
+ if (DEBUG && this.hasAsyncCallback && callback) {
+ let original = callback;
+ callback = (...args) => {
+ this.checkCallback(args, context);
+ original(...args);
+ };
+ }
+ let result = apiImpl.callAsyncFunction(
+ actuals,
+ callback,
+ this.requireUserInput
+ );
+ if (DEBUG && this.hasAsyncCallback && !callback) {
+ return result.then(result => {
+ this.checkCallback([result], context);
+ return result;
+ });
+ }
+ return result;
+ };
+ } else if (!this.returns) {
+ stub = (...args) => {
+ this.checkDeprecated(context);
+ let actuals = this.checkParameters(args, context);
+ return apiImpl.callFunctionNoReturn(actuals);
+ };
+ } else {
+ stub = (...args) => {
+ this.checkDeprecated(context);
+ let actuals = this.checkParameters(args, context);
+ let result = apiImpl.callFunction(actuals);
+ if (DEBUG && this.returns) {
+ this.checkValue(this.returns, result, context);
+ }
+ return result;
+ };
+ }
+
+ return {
+ descriptor: {
+ value: Cu.exportFunction(stub, context.cloneScope, {
+ allowCrossOriginArguments: this.allowCrossOriginArguments,
+ }),
+ },
+ revoke() {
+ apiImpl.revoke();
+ apiImpl = null;
+ },
+ };
+ }
+};
+
+// Represents an "event" defined in a schema namespace.
+//
+// TODO Bug 1369722: we should be able to remove the eslint-disable-line that follows
+// once Bug 1369722 has been fixed.
+// eslint-disable-next-line no-global-assign
+Event = class Event extends CallEntry {
+ static parseSchema(root, event, path) {
+ let extraParameters = Array.from(event.extraParameters || [], param => ({
+ type: root.parseSchema(param, path, ["name", "optional", "default"]),
+ name: param.name,
+ optional: param.optional || false,
+ default: param.default == undefined ? null : param.default,
+ }));
+
+ let extraProperties = [
+ "name",
+ "unsupported",
+ "permissions",
+ "extraParameters",
+ // We ignore these properties for now.
+ "returns",
+ "filters",
+ ];
+
+ return new this(
+ event,
+ path,
+ event.name,
+ root.parseSchema(event, path, extraProperties),
+ extraParameters,
+ event.unsupported || false,
+ event.permissions || null
+ );
+ }
+
+ constructor(
+ schema,
+ path,
+ name,
+ type,
+ extraParameters,
+ unsupported,
+ permissions
+ ) {
+ super(schema, path, name, extraParameters);
+ this.type = type;
+ this.unsupported = unsupported;
+ this.permissions = permissions;
+ }
+
+ checkListener(listener, context) {
+ let r = this.type.normalize(listener, context);
+ if (r.error) {
+ this.throwError(context, "Invalid listener");
+ }
+ return r.value;
+ }
+
+ getDescriptor(path, context) {
+ let apiImpl = context.getImplementation(path.join("."), this.name);
+
+ let addStub = (listener, ...args) => {
+ listener = this.checkListener(listener, context);
+ let actuals = this.checkParameters(args, context);
+ apiImpl.addListener(listener, actuals);
+ };
+
+ let removeStub = listener => {
+ listener = this.checkListener(listener, context);
+ apiImpl.removeListener(listener);
+ };
+
+ let hasStub = listener => {
+ listener = this.checkListener(listener, context);
+ return apiImpl.hasListener(listener);
+ };
+
+ let obj = Cu.createObjectIn(context.cloneScope);
+
+ Cu.exportFunction(addStub, obj, { defineAs: "addListener" });
+ Cu.exportFunction(removeStub, obj, { defineAs: "removeListener" });
+ Cu.exportFunction(hasStub, obj, { defineAs: "hasListener" });
+
+ return {
+ descriptor: { value: obj },
+ revoke() {
+ apiImpl.revoke();
+ apiImpl = null;
+
+ let unwrapped = ChromeUtils.waiveXrays(obj);
+ delete unwrapped.addListener;
+ delete unwrapped.removeListener;
+ delete unwrapped.hasListener;
+ },
+ };
+ }
+};
+
+const TYPES = Object.freeze(
+ Object.assign(Object.create(null), {
+ any: AnyType,
+ array: ArrayType,
+ boolean: BooleanType,
+ function: FunctionType,
+ integer: IntegerType,
+ null: NullType,
+ number: NumberType,
+ object: ObjectType,
+ string: StringType,
+ })
+);
+
+const LOADERS = {
+ events: "loadEvent",
+ functions: "loadFunction",
+ properties: "loadProperty",
+ types: "loadType",
+};
+
+class Namespace extends Map {
+ constructor(root, name, path) {
+ super();
+
+ this.root = root;
+
+ this._lazySchemas = [];
+ this.initialized = false;
+
+ this.name = name;
+ this.path = name ? [...path, name] : [...path];
+
+ this.superNamespace = null;
+
+ this.min_manifest_version = MIN_MANIFEST_VERSION;
+ this.max_manifest_version = MAX_MANIFEST_VERSION;
+
+ this.permissions = null;
+ this.allowedContexts = [];
+ this.defaultContexts = [];
+ }
+
+ /**
+ * Adds a JSON Schema object to the set of schemas that represent this
+ * namespace.
+ *
+ * @param {object} schema
+ * A JSON schema object which partially describes this
+ * namespace.
+ */
+ addSchema(schema) {
+ this._lazySchemas.push(schema);
+
+ for (let prop of [
+ "permissions",
+ "allowedContexts",
+ "defaultContexts",
+ "min_manifest_version",
+ "max_manifest_version",
+ ]) {
+ if (schema[prop]) {
+ this[prop] = schema[prop];
+ }
+ }
+
+ if (schema.$import) {
+ this.superNamespace = this.root.getNamespace(schema.$import);
+ }
+ }
+
+ /**
+ * Initializes the keys of this namespace based on the schema objects
+ * added via previous `addSchema` calls.
+ */
+ init() {
+ if (this.initialized) {
+ return;
+ }
+
+ if (this.superNamespace) {
+ this._lazySchemas.unshift(...this.superNamespace._lazySchemas);
+ }
+
+ // Keep in sync with LOADERS above.
+ this.types = new DefaultMap(() => []);
+ this.properties = new DefaultMap(() => []);
+ this.functions = new DefaultMap(() => []);
+ this.events = new DefaultMap(() => []);
+
+ for (let schema of this._lazySchemas) {
+ for (let type of schema.types || []) {
+ if (!type.unsupported) {
+ this.types.get(type.$extend || type.id).push(type);
+ }
+ }
+
+ for (let [name, prop] of Object.entries(schema.properties || {})) {
+ if (!prop.unsupported) {
+ this.properties.get(name).push(prop);
+ }
+ }
+
+ for (let fun of schema.functions || []) {
+ if (!fun.unsupported) {
+ this.functions.get(fun.name).push(fun);
+ }
+ }
+
+ for (let event of schema.events || []) {
+ if (!event.unsupported) {
+ this.events.get(event.name).push(event);
+ }
+ }
+ }
+
+ // For each type of top-level property in the schema object, iterate
+ // over all properties of that type, and create a temporary key for
+ // each property pointing to its type. Those temporary properties
+ // are later used to instantiate an Entry object based on the actual
+ // schema object.
+ for (let type of Object.keys(LOADERS)) {
+ for (let key of this[type].keys()) {
+ this.set(key, type);
+ }
+ }
+
+ this.initialized = true;
+
+ if (DEBUG) {
+ for (let key of this.keys()) {
+ this.get(key);
+ }
+ }
+ }
+
+ /**
+ * Initializes the value of a given key, by parsing the schema object
+ * associated with it and replacing its temporary value with an `Entry`
+ * instance.
+ *
+ * @param {string} key
+ * The name of the property to initialize.
+ * @param {string} type
+ * The type of property the key represents. Must have a
+ * corresponding entry in the `LOADERS` object, pointing to the
+ * initialization method for that type.
+ *
+ * @returns {Entry}
+ */
+ initKey(key, type) {
+ let loader = LOADERS[type];
+
+ for (let schema of this[type].get(key)) {
+ this.set(key, this[loader](key, schema));
+ }
+
+ return this.get(key);
+ }
+
+ loadType(name, type) {
+ if ("$extend" in type) {
+ return this.extendType(type);
+ }
+ return this.root.parseSchema(type, this.path, ["id"]);
+ }
+
+ extendType(type) {
+ let targetType = this.get(type.$extend);
+
+ // Only allow extending object and choices types for now.
+ if (targetType instanceof ObjectType) {
+ type.type = "object";
+ } else if (DEBUG) {
+ if (!targetType) {
+ throw new Error(
+ `Internal error: Attempt to extend a nonexistent type ${type.$extend}`
+ );
+ } else if (!(targetType instanceof ChoiceType)) {
+ throw new Error(
+ `Internal error: Attempt to extend a non-extensible type ${type.$extend}`
+ );
+ }
+ }
+
+ let parsed = this.root.parseSchema(type, this.path, ["$extend"]);
+
+ if (DEBUG && parsed.constructor !== targetType.constructor) {
+ throw new Error(`Internal error: Bad attempt to extend ${type.$extend}`);
+ }
+
+ targetType.extend(parsed);
+
+ return targetType;
+ }
+
+ loadProperty(name, prop) {
+ if ("$ref" in prop) {
+ if (!prop.unsupported) {
+ return new SubModuleProperty(
+ this.root,
+ prop,
+ this.path,
+ name,
+ prop.$ref,
+ prop.properties || {},
+ prop.permissions || null
+ );
+ }
+ } else if ("value" in prop) {
+ return new ValueProperty(prop, name, prop.value);
+ } else {
+ // We ignore the "optional" attribute on properties since we
+ // don't inject anything here anyway.
+ let type = this.root.parseSchema(
+ prop,
+ [this.name],
+ ["optional", "permissions", "writable"]
+ );
+ return new TypeProperty(
+ prop,
+ this.path,
+ name,
+ type,
+ prop.writable || false,
+ prop.permissions || null
+ );
+ }
+ }
+
+ loadFunction(name, fun) {
+ return FunctionEntry.parseSchema(this.root, fun, this.path);
+ }
+
+ loadEvent(name, event) {
+ return Event.parseSchema(this.root, event, this.path);
+ }
+
+ /**
+ * Injects the properties of this namespace into the given object.
+ *
+ * @param {object} dest
+ * The object into which to inject the namespace properties.
+ * @param {InjectionContext} context
+ * The injection context with which to inject the properties.
+ */
+ injectInto(dest, context) {
+ for (let name of this.keys()) {
+ // If the entry does not match the manifest version do not
+ // inject the property. This prevents the item from being
+ // enumerable in the namespace object. We cannot accomplish
+ // this inside exportLazyProperty, it specifically injects
+ // an enumerable object.
+ let entry = this.get(name);
+ if (!context.matchManifestVersion(entry)) {
+ continue;
+ }
+ exportLazyProperty(dest, name, () => {
+ let entry = this.get(name);
+
+ return context.getDescriptor(entry, dest, name, this.path, this);
+ });
+ }
+ }
+
+ getDescriptor(path, context) {
+ let obj = Cu.createObjectIn(context.cloneScope);
+
+ let ns = context.schemaRoot.getNamespace(this.path.join("."));
+ ns.injectInto(obj, context);
+
+ // Only inject the namespace object if it isn't empty.
+ if (Object.keys(obj).length) {
+ return {
+ descriptor: { value: obj },
+ };
+ }
+ }
+
+ keys() {
+ this.init();
+ return super.keys();
+ }
+
+ /** @returns {Generator<[string, Entry]>} */
+ *entries() {
+ for (let key of this.keys()) {
+ yield [key, this.get(key)];
+ }
+ }
+
+ get(key) {
+ this.init();
+ let value = super.get(key);
+
+ // The initial values of lazily-initialized schema properties are
+ // strings, pointing to the type of property, corresponding to one
+ // of the entries in the `LOADERS` object.
+ if (typeof value === "string") {
+ value = this.initKey(key, value);
+ }
+
+ return value;
+ }
+
+ /**
+ * Returns a Namespace object for the given namespace name. If a
+ * namespace object with this name does not already exist, it is
+ * created. If the name contains any '.' characters, namespaces are
+ * recursively created, for each dot-separated component.
+ *
+ * @param {string} name
+ * The name of the sub-namespace to retrieve.
+ * @param {boolean} [create = true]
+ * If true, create any intermediate namespaces which don't
+ * exist.
+ *
+ * @returns {Namespace}
+ */
+ getNamespace(name, create = true) {
+ let subName;
+
+ let idx = name.indexOf(".");
+ if (idx > 0) {
+ subName = name.slice(idx + 1);
+ name = name.slice(0, idx);
+ }
+
+ let ns = super.get(name);
+ if (!ns) {
+ if (!create) {
+ return null;
+ }
+ ns = new Namespace(this.root, name, this.path);
+ this.set(name, ns);
+ }
+
+ if (subName) {
+ return ns.getNamespace(subName);
+ }
+ return ns;
+ }
+
+ getOwnNamespace(name) {
+ return this.getNamespace(name);
+ }
+
+ has(key) {
+ this.init();
+ return super.has(key);
+ }
+}
+
+/**
+ * A namespace which combines the children of an arbitrary number of
+ * sub-namespaces.
+ */
+class Namespaces extends Namespace {
+ constructor(root, name, path, namespaces) {
+ super(root, name, path);
+
+ this.namespaces = namespaces;
+ }
+
+ injectInto(obj, context) {
+ for (let ns of this.namespaces) {
+ ns.injectInto(obj, context);
+ }
+ }
+}
+
+/**
+ * A root schema which combines the contents of an arbitrary number of base
+ * schema roots.
+ */
+class SchemaRoots extends Namespaces {
+ constructor(root, bases) {
+ bases = bases.map(base => base.rootSchema || base);
+
+ super(null, "", [], bases);
+
+ this.root = root;
+ this.bases = bases;
+ this._namespaces = new Map();
+ }
+
+ _getNamespace(name, create) {
+ let results = [];
+ for (let root of this.bases) {
+ let ns = root.getNamespace(name, create);
+ if (ns) {
+ results.push(ns);
+ }
+ }
+
+ if (results.length == 1) {
+ return results[0];
+ }
+
+ if (results.length) {
+ return new Namespaces(this.root, name, name.split("."), results);
+ }
+ return null;
+ }
+
+ getNamespace(name, create) {
+ let ns = this._namespaces.get(name);
+ if (!ns) {
+ ns = this._getNamespace(name, create);
+ if (ns) {
+ this._namespaces.set(name, ns);
+ }
+ }
+ return ns;
+ }
+
+ *getNamespaces(name) {
+ for (let root of this.bases) {
+ yield* root.getNamespaces(name);
+ }
+ }
+}
+
+/**
+ * A root schema namespace containing schema data which is isolated from data in
+ * other schema roots. May extend a base namespace, in which case schemas in
+ * this root may refer to types in a base, but not vice versa.
+ *
+ * @param {SchemaRoot|Array<SchemaRoot>|null} base
+ * A base schema root (or roots) from which to derive, or null.
+ * @param {Map<string, Array|StructuredCloneHolder>} schemaJSON
+ * A map of schema URLs and corresponding JSON blobs from which to
+ * populate this root namespace.
+ */
+export class SchemaRoot extends Namespace {
+ constructor(base, schemaJSON) {
+ super(null, "", []);
+
+ if (Array.isArray(base)) {
+ base = new SchemaRoots(this, base);
+ }
+
+ this.root = this;
+ this.base = base;
+ this.schemaJSON = schemaJSON;
+ }
+
+ *getNamespaces(path) {
+ let name = path.join(".");
+
+ let ns = this.getNamespace(name, false);
+ if (ns) {
+ yield ns;
+ }
+
+ if (this.base) {
+ yield* this.base.getNamespaces(name);
+ }
+ }
+
+ /**
+ * Returns the sub-namespace with the given name. If the given namespace
+ * doesn't already exist, attempts to find it in the base SchemaRoot before
+ * creating a new empty namespace.
+ *
+ * @param {string} name
+ * The namespace to retrieve.
+ * @param {boolean} [create = true]
+ * If true, an empty namespace should be created if one does not
+ * already exist.
+ * @returns {Namespace|null}
+ */
+ getNamespace(name, create = true) {
+ let ns = super.getNamespace(name, false);
+ if (ns) {
+ return ns;
+ }
+
+ ns = this.base && this.base.getNamespace(name, false);
+ if (ns) {
+ return ns;
+ }
+ return create && super.getNamespace(name, create);
+ }
+
+ /**
+ * Like getNamespace, but does not take the base SchemaRoot into account.
+ *
+ * @param {string} name
+ * The namespace to retrieve.
+ * @returns {Namespace}
+ */
+ getOwnNamespace(name) {
+ return super.getNamespace(name);
+ }
+
+ parseSchema(schema, path, extraProperties = []) {
+ let allowedProperties = DEBUG && new Set(extraProperties);
+
+ if ("choices" in schema) {
+ return ChoiceType.parseSchema(this, schema, path, allowedProperties);
+ } else if ("$ref" in schema) {
+ return RefType.parseSchema(this, schema, path, allowedProperties);
+ }
+
+ let type = TYPES[schema.type];
+
+ if (DEBUG) {
+ allowedProperties.add("type");
+
+ if (!("type" in schema)) {
+ throw new Error(`Unexpected value for type: ${JSON.stringify(schema)}`);
+ }
+
+ if (!type) {
+ throw new Error(`Unexpected type ${schema.type}`);
+ }
+ }
+
+ return type.parseSchema(this, schema, path, allowedProperties);
+ }
+
+ parseSchemas() {
+ for (let [key, schema] of this.schemaJSON.entries()) {
+ try {
+ if (typeof schema.deserialize === "function") {
+ schema = schema.deserialize(globalThis, isParentProcess);
+
+ // If we're in the parent process, we need to keep the
+ // StructuredCloneHolder blob around in order to send to future child
+ // processes. If we're in a child, we have no further use for it, so
+ // just store the deserialized schema data in its place.
+ if (!isParentProcess) {
+ this.schemaJSON.set(key, schema);
+ }
+ }
+
+ this.loadSchema(schema);
+ } catch (e) {
+ Cu.reportError(e);
+ }
+ }
+ }
+
+ loadSchema(json) {
+ for (let namespace of json) {
+ this.getOwnNamespace(namespace.namespace).addSchema(namespace);
+ }
+ }
+
+ /**
+ * Checks whether a given object has the necessary permissions to
+ * expose the given namespace.
+ *
+ * @param {string} namespace
+ * The top-level namespace to check permissions for.
+ * @param {object} wrapperFuncs
+ * Wrapper functions for the given context.
+ * @param {Function} wrapperFuncs.hasPermission
+ * A function which, when given a string argument, returns true
+ * if the context has the given permission.
+ * @returns {boolean}
+ * True if the context has permission for the given namespace.
+ */
+ checkPermissions(namespace, wrapperFuncs) {
+ let ns = this.getNamespace(namespace);
+ if (ns && ns.permissions) {
+ return ns.permissions.some(perm => wrapperFuncs.hasPermission(perm));
+ }
+ return true;
+ }
+
+ /**
+ * Inject registered extension APIs into `dest`.
+ *
+ * @param {object} dest The root namespace for the APIs.
+ * This object is usually exposed to extensions as "chrome" or "browser".
+ * @param {object} wrapperFuncs An implementation of the InjectionContext
+ * interface, which runs the actual functionality of the generated API.
+ */
+ inject(dest, wrapperFuncs) {
+ let context = new InjectionContext(wrapperFuncs, this);
+
+ this.injectInto(dest, context);
+ }
+
+ injectInto(dest, context) {
+ // For schema graphs where multiple schema roots have the same base, don't
+ // inject it more than once.
+
+ if (!context.injectedRoots.has(this)) {
+ context.injectedRoots.add(this);
+ if (this.base) {
+ this.base.injectInto(dest, context);
+ }
+ super.injectInto(dest, context);
+ }
+ }
+
+ /**
+ * Normalize `obj` according to the loaded schema for `typeName`.
+ *
+ * @param {object} obj The object to normalize against the schema.
+ * @param {string} typeName The name in the format namespace.propertyname
+ * @param {object} context An implementation of Context. Any validation errors
+ * are reported to the given context.
+ * @returns {object} The normalized object.
+ */
+ normalize(obj, typeName, context) {
+ let [namespaceName, prop] = typeName.split(".");
+ let ns = this.getNamespace(namespaceName);
+ let type = ns.get(prop);
+
+ let result = type.normalize(obj, new Context(context));
+ if (result.error) {
+ return { error: forceString(result.error) };
+ }
+ return result;
+ }
+}
+
+export var Schemas = {
+ initialized: false,
+
+ REVOKE: Symbol("@@revoke"),
+
+ // Maps a schema URL to the JSON contained in that schema file. This
+ // is useful for sending the JSON across processes.
+ schemaJSON: new Map(),
+
+ // A map of schema JSON which should be available in all content processes.
+ contentSchemaJSON: new Map(),
+
+ // A map of schema JSON which should only be available to extension processes.
+ privilegedSchemaJSON: new Map(),
+
+ _rootSchema: null,
+
+ // A weakmap for the validation Context class instances given an extension
+ // context (keyed by the extensin context instance).
+ // This is used instead of the InjectionContext for webIDL API validation
+ // and normalization (see Schemas.checkParameters).
+ paramsValidationContexts: new DefaultWeakMap(
+ extContext => new Context(extContext)
+ ),
+
+ get rootSchema() {
+ if (!this.initialized) {
+ this.init();
+ }
+ if (!this._rootSchema) {
+ this._rootSchema = new SchemaRoot(null, this.schemaJSON);
+ this._rootSchema.parseSchemas();
+ }
+ return this._rootSchema;
+ },
+
+ getNamespace(name) {
+ return this.rootSchema.getNamespace(name);
+ },
+
+ init() {
+ if (this.initialized) {
+ return;
+ }
+ this.initialized = true;
+
+ if (Services.appinfo.processType == Services.appinfo.PROCESS_TYPE_CONTENT) {
+ let addSchemas = schemas => {
+ for (let [key, value] of schemas.entries()) {
+ this.schemaJSON.set(key, value);
+ }
+ };
+
+ if (WebExtensionPolicy.isExtensionProcess || DEBUG) {
+ addSchemas(Services.cpmm.sharedData.get(KEY_PRIVILEGED_SCHEMAS));
+ }
+
+ let schemas = Services.cpmm.sharedData.get(KEY_CONTENT_SCHEMAS);
+ if (schemas) {
+ addSchemas(schemas);
+ }
+ }
+ },
+
+ _loadCachedSchemasPromise: null,
+ loadCachedSchemas() {
+ if (!this._loadCachedSchemasPromise) {
+ this._loadCachedSchemasPromise = lazy.StartupCache.schemas
+ .getAll()
+ .then(results => {
+ return results;
+ });
+ }
+
+ return this._loadCachedSchemasPromise;
+ },
+
+ addSchema(url, schema, content = false) {
+ this.schemaJSON.set(url, schema);
+
+ if (content) {
+ this.contentSchemaJSON.set(url, schema);
+ } else {
+ this.privilegedSchemaJSON.set(url, schema);
+ }
+
+ if (this._rootSchema) {
+ throw new Error("Schema loaded after root schema populated");
+ }
+ },
+
+ updateSharedSchemas() {
+ let { sharedData } = Services.ppmm;
+
+ sharedData.set(KEY_CONTENT_SCHEMAS, this.contentSchemaJSON);
+ sharedData.set(KEY_PRIVILEGED_SCHEMAS, this.privilegedSchemaJSON);
+ },
+
+ fetch(url) {
+ return readJSONAndBlobbify(url);
+ },
+
+ processSchema(json) {
+ return blobbify(json);
+ },
+
+ async load(url, content = false) {
+ if (!isParentProcess) {
+ return;
+ }
+
+ const startTime = Cu.now();
+ let schemaCache = await this.loadCachedSchemas();
+ const fromCache = schemaCache.has(url);
+
+ let blob =
+ schemaCache.get(url) ||
+ (await lazy.StartupCache.schemas.get(url, readJSONAndBlobbify));
+
+ if (!this.schemaJSON.has(url)) {
+ this.addSchema(url, blob, content);
+ }
+
+ ChromeUtils.addProfilerMarker(
+ "ExtensionSchemas",
+ { startTime },
+ `load ${url}, from cache: ${fromCache}`
+ );
+ },
+
+ /**
+ * Checks whether a given object has the necessary permissions to
+ * expose the given namespace.
+ *
+ * @param {string} namespace
+ * The top-level namespace to check permissions for.
+ * @param {object} wrapperFuncs
+ * Wrapper functions for the given context.
+ * @param {Function} wrapperFuncs.hasPermission
+ * A function which, when given a string argument, returns true
+ * if the context has the given permission.
+ * @returns {boolean}
+ * True if the context has permission for the given namespace.
+ */
+ checkPermissions(namespace, wrapperFuncs) {
+ return this.rootSchema.checkPermissions(namespace, wrapperFuncs);
+ },
+
+ /**
+ * Returns a sorted array of permission names for the given permission types.
+ *
+ * @param {Array} types An array of permission types, defaults to all permissions.
+ * @returns {Array} sorted array of permission names
+ */
+ getPermissionNames(
+ types = [
+ "Permission",
+ "OptionalPermission",
+ "PermissionNoPrompt",
+ "OptionalPermissionNoPrompt",
+ "PermissionPrivileged",
+ ]
+ ) {
+ const ns = this.getNamespace("manifest");
+ let names = [];
+ for (let typeName of types) {
+ for (let choice of ns
+ .get(typeName)
+ .choices.filter(choice => choice.enumeration)) {
+ names = names.concat(choice.enumeration);
+ }
+ }
+ return names.sort();
+ },
+
+ exportLazyGetter,
+
+ /**
+ * Inject registered extension APIs into `dest`.
+ *
+ * @param {object} dest The root namespace for the APIs.
+ * This object is usually exposed to extensions as "chrome" or "browser".
+ * @param {object} wrapperFuncs An implementation of the InjectionContext
+ * interface, which runs the actual functionality of the generated API.
+ */
+ inject(dest, wrapperFuncs) {
+ this.rootSchema.inject(dest, wrapperFuncs);
+ },
+
+ /**
+ * Normalize `obj` according to the loaded schema for `typeName`.
+ *
+ * @param {object} obj The object to normalize against the schema.
+ * @param {string} typeName The name in the format namespace.propertyname
+ * @param {object} context An implementation of Context. Any validation errors
+ * are reported to the given context.
+ * @returns {object} The normalized object.
+ */
+ normalize(obj, typeName, context) {
+ return this.rootSchema.normalize(obj, typeName, context);
+ },
+
+ /**
+ * Validate and normalize the arguments for an API request originated
+ * from the webIDL API bindings.
+ *
+ * This provides for calls originating through WebIDL the parameters
+ * validation and normalization guarantees that the ext-APINAMESPACE.js
+ * scripts expects (what InjectionContext does for the regular bindings).
+ *
+ * @param {object} extContext
+ * @param {mozIExtensionAPIRequest } apiRequest
+ *
+ * @returns {Array<any>} Normalized arguments array.
+ */
+ checkWebIDLRequestParameters(extContext, apiRequest) {
+ const getSchemaForProperty = (schemaObj, propName, schemaPath) => {
+ if (schemaObj instanceof Namespace) {
+ return schemaObj?.get(propName);
+ } else if (schemaObj instanceof SubModuleProperty) {
+ for (const fun of schemaObj.targetType.functions) {
+ if (fun.name === propName) {
+ return fun;
+ }
+ }
+
+ for (const fun of schemaObj.targetType.events) {
+ if (fun.name === propName) {
+ return fun;
+ }
+ }
+ } else if (schemaObj instanceof Event) {
+ return schemaObj;
+ }
+
+ const schemaPathType = schemaObj?.constructor.name;
+ throw new Error(
+ `API Schema for "${propName}" not found in ${schemaPath} (${schemaPath} type is ${schemaPathType})`
+ );
+ };
+ const { requestType, apiNamespace, apiName } = apiRequest;
+
+ let [ns, ...rest] = (
+ ["addListener", "removeListener"].includes(requestType)
+ ? `${apiNamespace}.${apiName}.${requestType}`
+ : `${apiNamespace}.${apiName}`
+ ).split(".");
+ let apiSchema = this.getNamespace(ns);
+
+ // Keep track of the current schema path, populated while navigating the nested API schema
+ // data and then used to include the full path to the API schema that is hitting unexpected
+ // errors due to schema data not found or an unexpected schema type.
+ let schemaPath = [ns];
+
+ while (rest.length) {
+ // Nested property as namespace (e.g. used for proxy.settings requests).
+ if (!apiSchema) {
+ throw new Error(`API Schema not found for ${schemaPath.join(".")}`);
+ }
+
+ let [propName, ...newRest] = rest;
+ rest = newRest;
+
+ apiSchema = getSchemaForProperty(
+ apiSchema,
+ propName,
+ schemaPath.join(".")
+ );
+ schemaPath.push(propName);
+ }
+
+ if (!apiSchema) {
+ throw new Error(`API Schema not found for ${schemaPath.join(".")}`);
+ }
+
+ if (!apiSchema.checkParameters) {
+ throw new Error(
+ `Unexpected API Schema type for ${schemaPath.join(
+ "."
+ )} (${schemaPath.join(".")} type is ${apiSchema.constructor.name})`
+ );
+ }
+
+ return apiSchema.checkParameters(
+ apiRequest.args,
+ this.paramsValidationContexts.get(extContext)
+ );
+ },
+};