@freedomofpress/webcat 0.0.0-stage → 3.0.0

package/dist/lib/browser/kvstore.js

@@ -0,0 +1,241 @@
+var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : Symbol.for("Symbol." + name);
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
+var __using = (stack, value, async) => {
+  if (value != null) {
+    if (typeof value !== "object" && typeof value !== "function") __typeError("Object expected");
+    var dispose, inner;
+    if (async) dispose = value[__knownSymbol("asyncDispose")];
+    if (dispose === void 0) {
+      dispose = value[__knownSymbol("dispose")];
+      if (async) inner = dispose;
+    }
+    if (typeof dispose !== "function") __typeError("Object not disposable");
+    if (inner) dispose = function() {
+      try {
+        inner.call(this);
+      } catch (e) {
+        return Promise.reject(e);
+      }
+    };
+    stack.push([async, dispose, value]);
+  } else if (async) {
+    stack.push([async]);
+  }
+  return value;
+};
+var __callDispose = (stack, error, hasError) => {
+  var E = typeof SuppressedError === "function" ? SuppressedError : function(e, s, m, _) {
+    return _ = Error(m), _.name = "SuppressedError", _.error = e, _.suppressed = s, _;
+  };
+  var fail = (e) => error = hasError ? new E(e, error, "An error was suppressed during disposal") : (hasError = true, e);
+  var next = (it) => {
+    while (it = stack.pop()) {
+      try {
+        var result = it[1] && it[1].call(it[2]);
+        if (it[0]) return Promise.resolve(result).then(next, (e) => (fail(e), next()));
+      } catch (e) {
+        fail(e);
+      }
+    }
+    if (hasError) throw error;
+  };
+  return next();
+};
+var _mutex, _namespace, _store;
+import permissions from "./permissions.js";
+import { Mutex } from "./sync.js";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __knownSymbol2 = (name, symbol) => (symbol = Symbol[name]) ? symbol : Symbol.for("Symbol." + name);
+var __typeError2 = (msg) => {
+  throw TypeError(msg);
+};
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __decoratorStart = (base) => [, , , __create(null)];
+var __decoratorStrings = ["class", "method", "getter", "setter", "accessor", "field", "value", "get", "set"];
+var __expectFn = (fn) => fn !== void 0 && typeof fn !== "function" ? __typeError2("Function expected") : fn;
+var __decoratorContext = (kind, name, done, metadata, fns) => ({ kind: __decoratorStrings[kind], name, metadata, addInitializer: (fn) => done._ ? __typeError2("Already initialized") : fns.push(__expectFn(fn || null)) });
+var __decoratorMetadata = (array, target) => __defNormalProp(target, __knownSymbol2("metadata"), array[3]);
+var __runInitializers = (array, flags, self, value) => {
+  for (var i = 0, fns = array[flags >> 1], n = fns && fns.length; i < n; i++) fns[i].call(self);
+  return value;
+};
+var __decorateElement = (array, flags, name, decorators, target, extra) => {
+  var it, done, ctx, k = flags & 7, p = false;
+  var j = 0;
+  var extraInitializers = array[j] || (array[j] = []);
+  var desc = k && (target = target.prototype, k < 5 && (k > 3 || !p) && __getOwnPropDesc(target, name));
+  __name(target, name);
+  for (var i = decorators.length - 1; i >= 0; i--) {
+    ctx = __decoratorContext(k, name, done = {}, array[3], extraInitializers);
+    it = (0, decorators[i])(target, ctx), done._ = 1;
+    __expectFn(it) && (target = it);
+  }
+  return __decoratorMetadata(array, target), desc && __defProp(target, name, desc), p ? k ^ 4 ? extra : desc : target;
+};
+var _KVStore_decorators, _init;
+_KVStore_decorators = [permissions.require("storage")];
+class KVStore {
+  /**
+   * Reads a persisted value.
+   *
+   * @param key The key to read.
+   * @param area The name of the {@link browser.storage.StorageArea | storage area} to read from.
+   * @returns A Promise that resolves to the value read.
+   */
+  async get(key, area = "local") {
+    const item = await browser.storage[area].get(key);
+    return item[key];
+  }
+  /**
+   * Stores values.
+   *
+   * @param items An object consisting of one or more key/value pairs to store.
+   * @param area The name of the {@link browser.storage.StorageArea | storage area} to use.
+   */
+  async set(items, area = "local") {
+    return browser.storage[area].set(items);
+  }
+  /**
+   * Clears all values whose key matches the specified prefix.
+   *
+   * @param prefix The prefix to match against.
+   * @param area The name of the {@link browser.storage.StorageArea | storage area} to use.
+   */
+  async clear(prefix = "", area = "local") {
+    const keys = await this.getKeys(prefix, area);
+    return browser.storage[area].remove(keys);
+  }
+  /**
+   * Retrieves a list of stored keys matching the specified prefix.
+   *
+   * @param prefix The prefix to match against.
+   * @param area The name of the {@link browser.storage.StorageArea | storage area} to read from.
+   * @returns A Promise that resolves to an array of matching keys.
+   */
+  async getKeys(prefix = "", area = "local") {
+    let keys;
+    if (browser.storage[area]["getKeys"]) {
+      keys = await browser.storage[area].getKeys();
+    } else {
+      keys = Object.keys(await browser.storage[area].get(null));
+    }
+    return keys.filter((key) => key.startsWith(`${prefix}`));
+  }
+  /**
+   * Clears a single persisted value.
+   *
+   * @param key The key to clear.
+   * @param area The name of the {@link browser.storage.StorageArea | storage area} to use.
+   */
+  async remove(key, area = "local") {
+    return browser.storage[area].remove(key);
+  }
+}
+_init = __decoratorStart();
+KVStore = __decorateElement(_init, 0, "KVStore", _KVStore_decorators, KVStore);
+__runInitializers(_init, 1, KVStore);
+const _NamespacedKVStore = class _NamespacedKVStore {
+  /**
+   * @param namespace The namespace prefix to use for this store.
+   * @param store A backing {@link KVStore} instance to use for persistence.
+   */
+  constructor(namespace, store = new KVStore()) {
+    __privateAdd(this, _mutex, new Mutex());
+    __privateAdd(this, _namespace);
+    __privateAdd(this, _store);
+    __privateSet(this, _namespace, namespace);
+    __privateSet(this, _store, store);
+  }
+  async get(key, area = "local") {
+    var _stack = [];
+    try {
+      const _lock = __using(_stack, await __privateGet(this, _mutex).acquire());
+      const namespacedKey = `${__privateGet(this, _namespace)}:${key}`;
+      return await __privateGet(this, _store).get(namespacedKey, area);
+    } catch (_) {
+      var _error = _, _hasError = true;
+    } finally {
+      __callDispose(_stack, _error, _hasError);
+    }
+  }
+  async set(items, area = "local") {
+    var _stack = [];
+    try {
+      const _lock = __using(_stack, await __privateGet(this, _mutex).acquire());
+      const namespacedItems = {};
+      for (const key in items) {
+        namespacedItems[`${__privateGet(this, _namespace)}:${key}`] = items[key];
+      }
+      return await __privateGet(this, _store).set(namespacedItems, area);
+    } catch (_) {
+      var _error = _, _hasError = true;
+    } finally {
+      __callDispose(_stack, _error, _hasError);
+    }
+  }
+  async clear(prefix = "", area = "local") {
+    var _stack = [];
+    try {
+      const _lock = __using(_stack, await __privateGet(this, _mutex).acquire());
+      return await __privateGet(this, _store).clear(`${__privateGet(this, _namespace)}:${prefix}`, area);
+    } catch (_) {
+      var _error = _, _hasError = true;
+    } finally {
+      __callDispose(_stack, _error, _hasError);
+    }
+  }
+  async getKeys(prefix = "", area = "local") {
+    var _stack = [];
+    try {
+      const _lock = __using(_stack, await __privateGet(this, _mutex).acquire());
+      const namespacedKeys = await __privateGet(this, _store).getKeys(
+        `${__privateGet(this, _namespace)}:${prefix}`,
+        area
+      );
+      return namespacedKeys.map(
+        (key) => key.substring(__privateGet(this, _namespace).length + 1)
+      );
+    } catch (_) {
+      var _error = _, _hasError = true;
+    } finally {
+      __callDispose(_stack, _error, _hasError);
+    }
+  }
+  async remove(key, area) {
+    var _stack = [];
+    try {
+      const _lock = __using(_stack, await __privateGet(this, _mutex).acquire());
+      const namespacedKey = `${__privateGet(this, _namespace)}:${key}`;
+      return await __privateGet(this, _store).remove(namespacedKey, area);
+    } catch (_) {
+      var _error = _, _hasError = true;
+    } finally {
+      __callDispose(_stack, _error, _hasError);
+    }
+  }
+  /**
+   * Creates a new subnamespace within this namespace.
+   *
+   * @param namespace A new namespace prefix to append to the existing prefix.
+   */
+  namespace(namespace) {
+    return new _NamespacedKVStore(namespace, this);
+  }
+};
+_mutex = new WeakMap();
+_namespace = new WeakMap();
+_store = new WeakMap();
+let NamespacedKVStore = _NamespacedKVStore;
+export {
+  KVStore,
+  NamespacedKVStore
+};

package/dist/lib/browser/permissions.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The subject of a permission check. Typically a class or a method, but may
+ * also be a function or any object with a name property.
+ */
+export interface Subject {
+    /** The name of the subject. */
+    name: string;
+}
+/**
+ * The `permissionerror` event. Notifies the consumer of a missing permission.
+ */
+export declare class PermissionErrorEvent extends Event {
+    /**
+     * The subject of the missing permission passed to the decorator returned by
+     * {@link PermissionChecker.require}.
+     */
+    readonly subject: Subject;
+    /**
+     * The missing permission, as declared via {@link PermissionChecker.require}.
+     */
+    readonly permission: string;
+    /** @internal */
+    constructor(subject: Subject, permission: string);
+}
+/**
+ * The `permissionrestored` event. Notifies the consumer of a required
+ * permission gained by a subject.
+ */
+export declare class PermissionRestoredEvent extends Event {
+    /** The subject that required the permission. */
+    readonly subject: Subject;
+    /**
+     * The required permission, as declared via
+     * {@link PermissionChecker.require}.
+     */
+    readonly permission: string;
+    /** @internal */
+    constructor(subject: Subject, permission: string);
+}
+export interface PermissionChecker {
+    /** @group Methods */
+    addEventListener: EventTarget["addEventListener"] & ((type: "permissionerror", callback: (event: PermissionErrorEvent) => void) => void) & ((type: "permissionrestored", callback: (event: PermissionRestoredEvent) => void) => void);
+}
+/**
+ * Checks extension permissions and triggers warnings for missing ones. For
+ * an example, {@link PermissionChecker.require}.
+ */
+export declare class PermissionChecker extends EventTarget {
+    #private;
+    constructor();
+    /**
+     * Creates a decorator that checks for an extension permission. For a class
+     * or method that requires multiple permissions, use multiple decorators.
+     *
+     * Permissions are checked at declaration time, not at instantiation or call
+     * time. Permission checks are asynchronous, best-effort, and do not block
+     * any code from running.
+     *
+     * Permission warnings in the console may be suppressed by calling
+     * {@link PermissionErrorEvent.preventDefault}.
+     *
+     * @param permission The extension permission to require. May be either a
+     *   {@link https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#api_permissions | named permission}
+     *   or a {@link https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns | match pattern}
+     *   for a {@link https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/host_permissions | host permission}.
+     * @returns
+     *
+     * @example
+     * import permissions from "@freedomofpress/webcat/browser/permissions";
+     *
+     * @permissions.require("webRequest")
+     * @permissions.require("webRequestBlocking")
+     * @permissions.require("https://example.com/*")
+     * class ExampleBlocker {
+     *   ...
+     * }
+     */
+    require(permission: string): (subject: Subject) => void;
+    /**
+     * Reads the required permissions for a subject. If subject is omitted,
+     * reads the required permissions across all subjects.
+     *
+     * @param subject The subject of the permissions.
+     * @returns The set of permissions declared for the subject via
+     *   {@link require}, or if no subject is given, permissions across all
+     *   subjects.
+     */
+    getRequired(subject?: Subject): Set<string>;
+    /**
+     * Reads the missing permissions for a subject. If subject is omitted, reads
+     * the missing permissions across all subjects.
+     *
+     * @param subject The subject of the permissions.
+     * @returns The set of missing permissions required by the subject via
+     *   {@link require}, or if no subject is given, missing permissions across
+     *   all subjects.
+     */
+    getMissing(subject?: Subject): Set<string>;
+    /**
+     * Checks the permissions of a given subject.
+     *
+     * @param subject The subject of the permissions.
+     * @returns A Promise that resolves to true if the subject has all the
+     *   permissions required.
+     */
+    check(subject: Subject): Promise<boolean>;
+}
+/**
+ * The default {@link PermissionChecker} instance. For an example, see
+ * {@link PermissionChecker.require}.
+ */
+declare const _default: PermissionChecker;
+export default _default;

package/dist/lib/browser/permissions.js

@@ -0,0 +1,182 @@
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
+var _requirements, _missing, _PermissionChecker_instances, checkOne_fn, handleAdded_fn, handleRemoved_fn;
+class PermissionErrorEvent extends Event {
+  /** @internal */
+  constructor(subject, permission) {
+    super("permissionerror", { cancelable: true });
+    this.subject = subject;
+    this.permission = permission;
+  }
+}
+class PermissionRestoredEvent extends Event {
+  /** @internal */
+  constructor(subject, permission) {
+    super("permissionrestored", { cancelable: true });
+    this.subject = subject;
+    this.permission = permission;
+  }
+}
+class PermissionChecker extends EventTarget {
+  constructor() {
+    super();
+    __privateAdd(this, _PermissionChecker_instances);
+    __privateAdd(this, _requirements, /* @__PURE__ */ new Map());
+    __privateAdd(this, _missing, /* @__PURE__ */ new Map());
+    browser.permissions.onAdded.addListener(__privateMethod(this, _PermissionChecker_instances, handleAdded_fn).bind(this));
+    browser.permissions.onRemoved.addListener(__privateMethod(this, _PermissionChecker_instances, handleRemoved_fn).bind(this));
+  }
+  /**
+   * Creates a decorator that checks for an extension permission. For a class
+   * or method that requires multiple permissions, use multiple decorators.
+   *
+   * Permissions are checked at declaration time, not at instantiation or call
+   * time. Permission checks are asynchronous, best-effort, and do not block
+   * any code from running.
+   *
+   * Permission warnings in the console may be suppressed by calling
+   * {@link PermissionErrorEvent.preventDefault}.
+   *
+   * @param permission The extension permission to require. May be either a
+   *   {@link https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#api_permissions | named permission}
+   *   or a {@link https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns | match pattern}
+   *   for a {@link https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/host_permissions | host permission}.
+   * @returns
+   *
+   * @example
+   * import permissions from "@freedomofpress/webcat/browser/permissions";
+   *
+   * @permissions.require("webRequest")
+   * @permissions.require("webRequestBlocking")
+   * @permissions.require("https://example.com/*")
+   * class ExampleBlocker {
+   *   ...
+   * }
+   */
+  require(permission) {
+    return (subject) => {
+      let requirements = __privateGet(this, _requirements).get(subject);
+      if (!requirements) {
+        requirements = /* @__PURE__ */ new Set();
+        __privateGet(this, _requirements).set(subject, requirements);
+      }
+      requirements.add(permission);
+      __privateMethod(this, _PermissionChecker_instances, checkOne_fn).call(this, subject, permission);
+    };
+  }
+  /**
+   * Reads the required permissions for a subject. If subject is omitted,
+   * reads the required permissions across all subjects.
+   *
+   * @param subject The subject of the permissions.
+   * @returns The set of permissions declared for the subject via
+   *   {@link require}, or if no subject is given, permissions across all
+   *   subjects.
+   */
+  getRequired(subject) {
+    if (subject) {
+      return new Set(__privateGet(this, _requirements).get(subject));
+    }
+    return __privateGet(this, _requirements).values().reduce((all, permissions2) => {
+      return all.union(permissions2);
+    }, /* @__PURE__ */ new Set());
+  }
+  /**
+   * Reads the missing permissions for a subject. If subject is omitted, reads
+   * the missing permissions across all subjects.
+   *
+   * @param subject The subject of the permissions.
+   * @returns The set of missing permissions required by the subject via
+   *   {@link require}, or if no subject is given, missing permissions across
+   *   all subjects.
+   */
+  getMissing(subject) {
+    if (subject) {
+      return new Set(__privateGet(this, _missing).get(subject));
+    }
+    return __privateGet(this, _missing).values().reduce((all, missing) => {
+      return all.union(missing);
+    }, /* @__PURE__ */ new Set());
+  }
+  /**
+   * Checks the permissions of a given subject.
+   *
+   * @param subject The subject of the permissions.
+   * @returns A Promise that resolves to true if the subject has all the
+   *   permissions required.
+   */
+  async check(subject) {
+    const requirements = __privateGet(this, _requirements).get(subject) ?? /* @__PURE__ */ new Set();
+    const checks = Array.from(requirements).map(
+      (r) => __privateMethod(this, _PermissionChecker_instances, checkOne_fn).call(this, subject, r)
+    );
+    const results = await Promise.all(checks);
+    return results.every((ok) => ok);
+  }
+}
+_requirements = new WeakMap();
+_missing = new WeakMap();
+_PermissionChecker_instances = new WeakSet();
+checkOne_fn = async function(subject, permission) {
+  const permissions2 = new Array();
+  const origins = new Array();
+  if (permission.includes("://") || permission === "<all_urls>") {
+    origins.push(permission);
+  } else {
+    permissions2.push(permission);
+  }
+  return browser.permissions.contains({ permissions: permissions2, origins }).then((ok) => {
+    if (ok) {
+      const missing = __privateGet(this, _missing).get(subject);
+      if (missing) {
+        if (missing.delete(permission)) {
+          const event = new PermissionRestoredEvent(subject, permission);
+          this.dispatchEvent(event);
+        }
+      }
+    } else {
+      let missing = __privateGet(this, _missing).get(subject);
+      if (!missing) {
+        missing = /* @__PURE__ */ new Set();
+        __privateGet(this, _missing).set(subject, missing);
+      }
+      if (!missing.has(permission)) {
+        missing.add(permission);
+        const event = new PermissionErrorEvent(subject, permission);
+        this.dispatchEvent(event);
+        if (!event.defaultPrevented) {
+          console.warn(
+            "Extension permission requirements not fulfilled for %s. The '%s' permission is required.",
+            subject.name,
+            permission
+          );
+        }
+      }
+    }
+    return ok;
+  });
+};
+handleAdded_fn = function() {
+  for (const [subject, set] of __privateGet(this, _missing)) {
+    if (set.size > 0) {
+      this.check(subject);
+    }
+  }
+};
+handleRemoved_fn = function() {
+  for (const [subject, _] of __privateGet(this, _requirements)) {
+    this.check(subject);
+  }
+};
+const permissions = new PermissionChecker();
+export {
+  PermissionChecker,
+  PermissionErrorEvent,
+  PermissionRestoredEvent,
+  permissions as default
+};

package/dist/lib/browser/requests.d.ts

@@ -0,0 +1,145 @@
+/** @internal */
+export declare class RequestDetailsBase {
+    #private;
+    /**
+     * Resolved when the request completes or rejected if a network error occurs.
+     */
+    readonly completed: Promise<void>;
+    constructor();
+    /** @internal */
+    complete(): void;
+    /** @internal */
+    fail(): void;
+}
+/** @interface */
+export type BeforeRequestDetails = RequestDetailsBase & browser.webRequest._OnBeforeRequestDetails;
+/** @interface */
+export type BeforeHeadersDetails = BeforeRequestDetails & browser.webRequest._OnBeforeSendHeadersDetails;
+/** @interface */
+export type HeadersReceivedDetails = BeforeHeadersDetails & browser.webRequest._OnHeadersReceivedDetails;
+/** @interface */
+export type ErrorOccurredDetails = BeforeRequestDetails & browser.webRequest._OnErrorOccurredDetails;
+/** @interface */
+export type CompletedDetails = HeadersReceivedDetails & browser.webRequest._OnCompletedDetails;
+export type RequestDetails = BeforeHeadersDetails | BeforeHeadersDetails | HeadersReceivedDetails | ErrorOccurredDetails | CompletedDetails;
+declare const dispose: typeof Symbol.dispose;
+/**
+ * The response of a single listener to a blocking {@link RequestEvent},
+ * created with {@link RequestEvent.createBlockingResponse}. Implements the
+ * {@link Disposable} interface. A new BlockingResponse cancels the request;
+ * a listener signals successful completion by setting {@link cancel} to
+ * false, either by assigning to it directly or with the {@link set} method.
+ * A listener must create it with a
+ * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/using using declaration}
+ * before its first await expression; the response is reported on disposal.
+ *
+ * @example
+ * handler.addEventListener("beforeheaders", async (event) => {
+ *  using blockingResponse = event.createBlockingResponse();
+ *  await doSomething(event.details);
+ *  blockingResponse.cancel = false;
+ * });
+ */
+export declare class BlockingResponse implements browser.webRequest.BlockingResponse, Disposable {
+    #private;
+    /**
+     * Whether to cancel the request. Defaults to true, so that a listener that
+     * throws, or never completes its checks, cancels the request. Set to false
+     * to signal successful completion.
+     */
+    cancel: boolean | undefined;
+    redirectUrl?: string | undefined;
+    upgradeToSecure?: boolean | undefined;
+    requestHeaders?: browser.webRequest.HttpHeaders | undefined;
+    responseHeaders?: browser.webRequest.HttpHeaders | undefined;
+    authCredentials?: browser.webRequest._BlockingResponseAuthCredentials | undefined;
+    constructor(details?: RequestDetails);
+    /**
+     * Implements the {@link Disposable} interface.
+     */
+    [dispose](): void;
+    /**
+     * @returns A Promise that resolves to this BlockingResponse after disposal.
+     */
+    ready(): Promise<BlockingResponse>;
+    /**
+     * @param value An object whose properties are copied to this BlockingResponse.
+     */
+    set(value: browser.webRequest.BlockingResponse): void;
+    /**
+     * Sets the response header `name` to `value`, replacing any existing
+     * occurrences. Starts from the response's original headers, so the rest
+     * pass through unchanged.
+     */
+    setHeader(name: string, value: string): void;
+}
+/**
+ * Event type for events dispatched by RequestHandlers.
+ */
+export declare class RequestEvent<T extends RequestDetails> extends Event {
+    #private;
+    /**
+     * Details of the request this event concerns.
+     */
+    readonly details: T;
+    /** @internal */
+    constructor(type: string, details: T);
+    /**
+     * Creates a {@link BlockingResponse} for this event. Each listener creates
+     * its own before its first await expression, so that listeners respond
+     * independently of each other; see {@link ready} for how the responses are
+     * combined.
+     *
+     * @returns A new BlockingResponse that cancels the request unless the
+     *   listener sets {@link BlockingResponse.cancel} to false.
+     */
+    createBlockingResponse(): BlockingResponse;
+    /**
+     * Awaits all BlockingResponses created for this event and merges them into
+     * a single response. If any of them cancels the request, so does the
+     * result; otherwise, their other properties are combined. With no
+     * BlockingResponses, the request proceeds unchanged.
+     *
+     * @returns A Promise that resolves to the merged response.
+     * @internal
+     */
+    ready(): Promise<browser.webRequest.BlockingResponse>;
+}
+export interface RequestHandler extends EventTarget {
+    /** @group Methods */
+    addEventListener: EventTarget["addEventListener"] & ((type: "beforerequest", callback: (event: RequestEvent<BeforeRequestDetails>) => void) => void) & ((type: "beforeheaders", callback: (event: RequestEvent<BeforeHeadersDetails>) => void) => void) & ((type: "headersreceived", callback: (event: RequestEvent<HeadersReceivedDetails>) => void) => void) & ((type: "erroroccurred", callback: (event: RequestEvent<ErrorOccurredDetails>) => void) => void) & ((type: "completed", callback: (event: RequestEvent<CompletedDetails>) => void) => void);
+}
+/**
+ * Handles web requests and responses for specific FQDNs. Manages the entire
+ * lifecycle of a request and aggregates details such as request headers and
+ * response headers to make them available in later stages.
+ */
+export declare class RequestHandler extends EventTarget {
+    #private;
+    /**
+     * Binds the handler to the given list of FQDNs. When called, the handler
+     * starts handling requests for the FQDNs in the list and stops handling
+     * requests for any previously bound FQDNs that are not in the new list.
+     *
+     * @param fqdns A list of fully-qualified domain names to bind to.
+     */
+    bind(fqdns: string[]): void;
+    /** @internal */
+    protected getListenerOptions(fqdns: string[], type: "beforerequest"): [browser.webRequest.RequestFilter, browser.webRequest.OnBeforeRequestOptions[]];
+    /** @internal */
+    protected getListenerOptions(fqdns: string[], type: "beforeheaders"): [browser.webRequest.RequestFilter, browser.webRequest.OnBeforeSendHeadersOptions[]];
+    /** @internal */
+    protected getListenerOptions(fqdns: string[], type: "headersreceived"): [browser.webRequest.RequestFilter, browser.webRequest.OnHeadersReceivedOptions[]];
+    /** @internal */
+    protected getListenerOptions(fqdns: string[], type: "erroroccurred" | "completed"): [browser.webRequest.RequestFilter];
+    /**
+     * Returns a tuple consisting of a request filter and an optional options
+     * array, used when registering webRequest listeners. Overriding this method
+     * allows changing the registration behavior.
+     *
+     * @param fqdns Fully-qualified domain names to handle requests for.
+     * @param type The type of event to handle.
+     */
+    protected getListenerOptions(fqdns: string[], type: string): [browser.webRequest.RequestFilter] | [browser.webRequest.RequestFilter, (browser.webRequest.OnBeforeRequestOptions[] | browser.webRequest.OnBeforeSendHeadersOptions[] | browser.webRequest.OnHeadersReceivedOptions[])];
+}
+export {};