@freedomofpress/webcat 0.0.0-stage → 3.0.1

package/dist/lib/webcat/resources.js

@@ -0,0 +1,41 @@
+const ALL_TYPES = [
+  "main_frame",
+  "sub_frame",
+  "stylesheet",
+  "script",
+  "image",
+  "font",
+  "object",
+  "xmlhttprequest",
+  "ping",
+  "csp_report",
+  "media",
+  "websocket",
+  "other",
+  "xslt",
+  "beacon",
+  "imageset",
+  "speculative",
+  "web_manifest"
+];
+const FRAME_TYPES = [
+  "main_frame",
+  "sub_frame"
+];
+const NON_FRAME_TYPES = ALL_TYPES.filter((t) => !FRAME_TYPES.includes(t));
+const PASS_THROUGH_TYPES = /* @__PURE__ */ new Set([
+  "image",
+  "imageset",
+  "media",
+  "font",
+  "websocket",
+  "xmlhttprequest",
+  "ping",
+  "speculative",
+  "other"
+]);
+export {
+  FRAME_TYPES,
+  NON_FRAME_TYPES,
+  PASS_THROUGH_TYPES
+};

package/dist/lib/webcat/response.d.ts

@@ -0,0 +1,39 @@
+import { BeforeRequestDetails, HeadersReceivedDetails } from "../browser/requests";
+import { HookBuilder } from "./hookbuilder";
+import { Database } from "./interfaces/database";
+import { WebcatError } from "./interfaces/errors";
+import { Stateful } from "./interfaces/requeststate";
+import { WebcatUI } from "./ui";
+/**
+ * Validates responses from WEBCAT-enrolled origins.
+ */
+export declare class ResponseValidator {
+    #private;
+    constructor(db: Database, ui: WebcatUI, hooks: HookBuilder);
+    /**
+     * Validates response headers.
+     *
+     * @param details The request details object to validate.
+     * @returns A Promise that resolves to undefined on successful validation, or
+     *   to a {@link WebcatError} on validation failure.
+     */
+    validateHeaders(details: Stateful<HeadersReceivedDetails>): Promise<WebcatError | undefined>;
+    /** @internal */
+    extractAndValidateHeaders(details: Stateful<HeadersReceivedDetails>): Map<string, string> | WebcatError;
+    /**
+     * Validates response content.
+     *
+     * @param details The request details object to validate.
+     */
+    validateContent(details: Stateful<BeforeRequestDetails>): Promise<void>;
+    /**
+     * Marks the start of response content by injecting a secret token. Must be
+     * called *later* than {@link validateContent}, which will remove the marker.
+     * The counter-intuitive ordering is inherited from
+     * {@link browser.webRequest.StreamFilter | StreamFilter} behavior.
+     *
+     * @param details
+     * @returns
+     */
+    markContent(details: HeadersReceivedDetails): void;
+}

package/dist/lib/webcat/response.js

@@ -0,0 +1,394 @@
+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 _marker, _db, _ui, _hooks;
+import permissions from "../browser/permissions.js";
+import { CacheKey } from "./cache.js";
+import { stringToUint8Array, Uint8ArrayToBase64Url, Uint8ArrayToString, base64UrlToUint8Array } from "./encoding.js";
+import { WebcatError, WebcatErrorCode } from "./interfaces/errors.js";
+import { logger } from "./logger.js";
+import { PASS_THROUGH_TYPES } from "./resources.js";
+import { isNewerSemver, clearBrowserCaches, isSameOriginURL, arraysEqual, SHA256 } from "./utils.js";
+import "../browser/sync.js";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __knownSymbol = (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, __knownSymbol("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 _ResponseValidator_decorators, _init;
+const WORKER_FETCH_DESTINATIONS = [
+  "worker",
+  "serviceworker",
+  "sharedworker",
+  "audioworklet",
+  "paintworklet"
+];
+function assertVerifiedManifest(originState) {
+  if (!originState.isManifestVerified()) {
+    throw new Error("origin is not populated when it was expected");
+  }
+}
+function assertHeadersAvailable(details) {
+  if (!("responseHeaders" in details)) {
+    throw new Error("response headers not available when expected");
+  }
+}
+_ResponseValidator_decorators = [permissions.require("webRequest"), permissions.require("webRequestBlocking"), permissions.require("webRequestFilterResponse"), permissions.require("webRequestFilterResponse.serviceWorkerScript")];
+class ResponseValidator {
+  constructor(db, ui, hooks) {
+    // #marker is ephemeral, not persisted anywhere, but that's ok:
+    // ResponseValidator attaches a StreamFilter that prevents the
+    // background service worker from terminating while a response
+    // is being processed
+    __privateAdd(this, _marker, stringToUint8Array(
+      `__WEBCAT_END__{${Uint8ArrayToBase64Url(crypto.getRandomValues(new Uint8Array(32)))}}
+`
+    ));
+    __privateAdd(this, _db);
+    __privateAdd(this, _ui);
+    __privateAdd(this, _hooks);
+    __privateSet(this, _db, db);
+    __privateSet(this, _ui, ui);
+    __privateSet(this, _hooks, hooks);
+  }
+  /**
+   * Validates response headers.
+   *
+   * @param details The request details object to validate.
+   * @returns A Promise that resolves to undefined on successful validation, or
+   *   to a {@link WebcatError} on validation failure.
+   */
+  async validateHeaders(details) {
+    if (!details.state.pendingOrigin) {
+      throw new Error("missing pendingOrigin in request state");
+    }
+    logger.info(`Validating response headers, url: ${details.url}`, details);
+    const result = this.extractAndValidateHeaders(details);
+    if (result instanceof WebcatError) {
+      return result;
+    }
+    const normalizedHeaders = result;
+    const csp = normalizedHeaders.get("content-security-policy");
+    const version = normalizedHeaders.get("x-webcat-version");
+    const delegation = normalizedHeaders.get("x-webcat-delegation");
+    const enrollment_header = normalizedHeaders.get("x-webcat-enrollment");
+    if (details.state.pendingOrigin.isRequestSent()) {
+      let enrollment;
+      if (enrollment_header) {
+        try {
+          enrollment = JSON.parse(
+            Uint8ArrayToString(base64UrlToUint8Array(enrollment_header))
+          );
+        } catch {
+          return new WebcatError(WebcatErrorCode.Headers.ENROLLMENT_MALFORMED);
+        }
+        await details.state.pendingOrigin.verifyEnrollment(
+          enrollment,
+          delegation
+        );
+      } else {
+        await details.state.pendingOrigin.verifyEnrollment(
+          void 0,
+          delegation
+        );
+      }
+      if (details.state.pendingOrigin.isFailed()) {
+        return details.state.pendingOrigin.error;
+      }
+      logger.debug("Header parsing complete", details);
+      await details.state.pendingOrigin.verifyManifest();
+      if (details.state.pendingOrigin.isFailed()) {
+        return details.state.pendingOrigin.error;
+      }
+      if (!details.state.pendingOrigin.isManifestVerified()) {
+        throw new Error(
+          `Error with the origin state: expected origin to be in state verified_manifest`
+        );
+      }
+      logger.info(`Metadata for ${details.url} loaded`, details);
+    }
+    if (!details.state.pendingOrigin.isManifestVerified()) {
+      throw new Error(
+        "Validating headers, but no valid manifest for the origin has been found."
+      );
+    }
+    if (version && isNewerSemver(version, details.state.pendingOrigin.manifest.version)) {
+      logger.info(
+        `Detected new version ${version}, current_version ${details.state.pendingOrigin.manifest.version}`,
+        details
+      );
+      await __privateGet(this, _db).origins.delete(
+        CacheKey(details.state.fqdn, details.state.cachePartition)
+      );
+      details.state.pendingOrigin.stale = true;
+      await clearBrowserCaches([details.state.fqdn]);
+      browser.tabs.reload(details.tabId);
+    }
+    const pathname = new URL(details.url).pathname;
+    if (csp) {
+      if (!details.state.pendingOrigin.verifyCSP(csp, pathname)) {
+        return new WebcatError(WebcatErrorCode.CSP.MISMATCH, [
+          String(pathname)
+        ]);
+      }
+      logger.info(`CSP validated for path ${pathname}`, details);
+    } else if (details.fromCache === true || details.statusCode === 304) {
+      logger.debug(
+        `Skipping CSP check for cached/304 response on path ${pathname}`,
+        details
+      );
+    } else {
+      return new WebcatError(WebcatErrorCode.Headers.MISSING_CRITICAL, [
+        "content-security-policy"
+      ]);
+    }
+    if (details.type === "main_frame") {
+      __privateGet(this, _ui).showOKIcon(
+        details.tabId,
+        details.state.pendingOrigin.delegation
+      );
+    }
+  }
+  /** @internal */
+  extractAndValidateHeaders(details) {
+    if (!details.responseHeaders) {
+      return new WebcatError(WebcatErrorCode.Headers.MISSING);
+    }
+    const criticalHeaders = /* @__PURE__ */ new Set(["content-security-policy"]);
+    const forbiddenHeaders = /* @__PURE__ */ new Set([
+      // See https://github.com/freedomofpress/webcat/issues/23
+      // Furthermore, as reported by TBD there's the risk of TBD
+      //"location",
+      // See https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Refresh
+      // It's just another way to achieve redirects
+      "refresh",
+      // See https://github.com/freedomofpress/webcat/issues/24
+      "link"
+    ]);
+    const seenCriticalHeaders = /* @__PURE__ */ new Set();
+    const normalizedHeaders = /* @__PURE__ */ new Map();
+    for (const header of details.responseHeaders) {
+      if (header.name && header.value) {
+        const lowerName = header.name.toLowerCase();
+        const value = header.value;
+        if (lowerName === "location") {
+          if (!details.state.isFrame) {
+            return new WebcatError(
+              WebcatErrorCode.Headers.LOCATION_SUBRESOURCE,
+              [String(value)]
+            );
+          }
+          if (!isSameOriginURL(value, details.url)) {
+            return new WebcatError(WebcatErrorCode.Headers.LOCATION_EXTERNAL, [
+              String(value)
+            ]);
+          }
+        } else if (lowerName === "origin-agent-cluster" && value.trim() !== "?1") {
+          return new WebcatError(WebcatErrorCode.Headers.FORBIDDEN, [
+            `${lowerName}: ${value}`
+          ]);
+        } else if (forbiddenHeaders.has(lowerName)) {
+          return new WebcatError(WebcatErrorCode.Headers.FORBIDDEN, [
+            String(lowerName)
+          ]);
+        }
+        if (criticalHeaders.has(lowerName)) {
+          if (seenCriticalHeaders.has(lowerName)) {
+            return new WebcatError(WebcatErrorCode.Headers.DUPLICATE, [
+              String(lowerName)
+            ]);
+          }
+          seenCriticalHeaders.add(lowerName);
+        }
+        normalizedHeaders.set(lowerName, header.value);
+      }
+    }
+    if (details.fromCache !== true && details.statusCode !== 304) {
+      for (const criticalHeader of criticalHeaders) {
+        if (!normalizedHeaders.has(criticalHeader)) {
+          return new WebcatError(WebcatErrorCode.Headers.MISSING_CRITICAL, [
+            String(criticalHeader)
+          ]);
+        }
+      }
+    }
+    return normalizedHeaders;
+  }
+  /**
+   * Validates response content.
+   *
+   * @param details The request details object to validate.
+   */
+  async validateContent(details) {
+    function deny(filter2) {
+      filter2.write(new Uint8Array([68, 69, 78, 73, 69, 68]));
+    }
+    const pathname = new URL(details.url).pathname;
+    const originState = details.state.pendingOrigin;
+    if (!originState) {
+      throw new Error("missing pendingOrigin in request state");
+    }
+    let manifest;
+    const filter = browser.webRequest.filterResponseData(details.requestId);
+    const source = [];
+    filter.onstart = () => {
+      assertVerifiedManifest(originState);
+      assertHeadersAvailable(details);
+      manifest = originState.manifest;
+      if (!manifest.files[pathname] && !(pathname.endsWith("/") && manifest.files[pathname + manifest.default_index]) && PASS_THROUGH_TYPES.has(details.type)) {
+        filter.disconnect();
+      }
+      if (details.type === "script" && details.requestHeaders) {
+        for (const header of details.requestHeaders) {
+          if (header.name.toLowerCase() === "sec-fetch-dest" && header.value !== void 0) {
+            if (WORKER_FETCH_DESTINATIONS.includes(header.value)) {
+              const hooks = __privateGet(this, _hooks).getPageHooks(
+                manifest.wasm,
+                details.state.cachePartition.firstParty,
+                // Hooks are only injected to workers, and CSP restrictions only allow
+                // same-origin workers, so the request's web origin is the URL's origin;
+                // determine whether the URL is same-origin with the first party
+                details.state.cachePartition.firstParty === new URL(details.url).origin
+              );
+              source.push(hooks.then((h) => stringToUint8Array(h).buffer));
+            }
+            break;
+          }
+        }
+      }
+    };
+    let writeQueue = Promise.resolve();
+    let markerSeen = false;
+    filter.ondata = (event) => {
+      if (arraysEqual(__privateGet(this, _marker), new Uint8Array(event.data))) {
+        source.forEach((hook) => {
+          writeQueue = writeQueue.then(async () => filter.write(await hook));
+        });
+        source.length = 0;
+        markerSeen = true;
+      } else {
+        source.push(Promise.resolve(event.data));
+      }
+    };
+    filter.onstop = async () => {
+      if (!markerSeen && !PASS_THROUGH_TYPES.has(details.type)) {
+        filter.close();
+        return;
+      }
+      try {
+        if (details.tabId !== -1) {
+          await details.completed;
+        }
+      } catch {
+        logger.warn(`Request canceled, url: ${details.url}`, details);
+        filter.close();
+        return;
+      }
+      const blob = await new Blob(await Promise.all(source)).arrayBuffer();
+      let manifest_hash;
+      if (manifest.files[pathname]) {
+        manifest_hash = manifest.files[pathname];
+      } else if (pathname.endsWith("/")) {
+        manifest_hash = manifest.files[pathname + manifest.default_index];
+      }
+      if (!manifest_hash && details.type === "main_frame") {
+        manifest_hash = manifest.files[manifest.default_fallback];
+      }
+      if (!manifest_hash) {
+        deny(filter);
+        filter.close();
+        __privateGet(this, _ui).showErrorPage(
+          details,
+          new WebcatError(WebcatErrorCode.File.MISSING, [pathname]),
+          true
+        );
+        return;
+      }
+      const content_hash = await SHA256(blob);
+      if (!arraysEqual(
+        base64UrlToUint8Array(manifest_hash),
+        new Uint8Array(content_hash)
+      ) && blob.byteLength !== 0) {
+        deny(filter);
+        filter.close();
+        __privateGet(this, _ui).showErrorPage(
+          details,
+          new WebcatError(WebcatErrorCode.File.MISMATCH, [
+            pathname,
+            String(manifest_hash),
+            String(Uint8ArrayToBase64Url(new Uint8Array(content_hash)))
+          ]),
+          true
+        );
+        return;
+      }
+      logger.info(`${pathname} verified.`, details);
+      await writeQueue;
+      filter.write(blob);
+      filter.close();
+      if (details.type === "main_frame") {
+        __privateGet(this, _ui).showOKIcon(details.tabId, originState.delegation);
+      }
+    };
+  }
+  /**
+   * Marks the start of response content by injecting a secret token. Must be
+   * called *later* than {@link validateContent}, which will remove the marker.
+   * The counter-intuitive ordering is inherited from
+   * {@link browser.webRequest.StreamFilter | StreamFilter} behavior.
+   *
+   * @param details
+   * @returns
+   */
+  markContent(details) {
+    if (PASS_THROUGH_TYPES.has(details.type)) return;
+    const endMarkerInjector = browser.webRequest.filterResponseData(
+      details.requestId
+    );
+    endMarkerInjector.onstart = () => {
+      endMarkerInjector.write(__privateGet(this, _marker));
+    };
+    endMarkerInjector.ondata = (event) => endMarkerInjector.write(event.data);
+    endMarkerInjector.onstop = () => endMarkerInjector.close();
+  }
+}
+_marker = new WeakMap();
+_db = new WeakMap();
+_ui = new WeakMap();
+_hooks = new WeakMap();
+_init = __decoratorStart();
+ResponseValidator = __decorateElement(_init, 0, "ResponseValidator", _ResponseValidator_decorators, ResponseValidator);
+__runInitializers(_init, 1, ResponseValidator);
+export {
+  ResponseValidator
+};

package/dist/lib/webcat/ui.d.ts

@@ -0,0 +1,70 @@
+import { BrowserChromeController, BrowserChromeControllerConfig, IconOptions } from "../browser/chrome";
+import { NamespacedKVStore } from "../browser/kvstore";
+import { RequestDetails } from "../browser/requests";
+import { Database } from "./interfaces/database";
+import { WebcatError } from "./interfaces/errors";
+import { Stateful } from "./interfaces/requeststate";
+/**
+ * Manages the UI for WEBCAT.
+ */
+export declare class WebcatUI extends BrowserChromeController {
+    #private;
+    /**
+     * @param db The database to load enrollments from.
+     * @param store The store to use for persistence.
+     * @param config
+     */
+    constructor(db: Database, store: NamespacedKVStore, config: BrowserChromeControllerConfig);
+    /**
+     * Displays the default WEBCAT icon in the browser's URL bar. If the UI has
+     * warnings, shows the warning icon instead.
+     *
+     * @param tabId The ID of the tab to display the icon in.
+     * @param options Icon options.
+     */
+    showIcon(tabId: number, options?: IconOptions): Promise<void>;
+    /**
+     * Displays the warning icon in the browser's URL bar. Clicking on the icon
+     * opens the popup with full warning info.
+     *
+     * @param tabId The ID of the tab to display the icon in.
+     */
+    showWarningIcon(tabId: number): Promise<void>;
+    /**
+     * Displays the OK icon in the browser's URL bar. If the UI has warnings,
+     * shows the warning icon instead.
+     *
+     * @param tabId The ID of the tab to display the icon in.
+     * @param delegation Optional delegation information to include in the title
+     *   text.
+     */
+    showOKIcon(tabId: number, delegation?: string): Promise<void>;
+    /**
+     * Displays the error icon in the browser's URL bar.
+     *
+     * @param tabId The ID of the tab to display the icon in.
+     */
+    showErrorIcon(tabId: number): Promise<void>;
+    /**
+     * Loads the error page in the tab(s) indicated by details.
+     *
+     * @param details Details for the request that triggered the error.
+     * @param error The error information.
+     * @param replace true to replace the current history entry, false to add a
+     *   new one.
+     */
+    showErrorPage(details: Stateful<RequestDetails>, error: WebcatError, replace?: boolean): Promise<void>;
+    /**
+     * Sets the message for the specified warning.
+     *
+     * @param id The ID of the warning.
+     * @param args The arguments of the warning. Must be serializable as JSON.
+     */
+    setWarning(id: string, ...args: unknown[]): Promise<void>;
+    /**
+     * Clears a specific warning from the UI.
+     *
+     * @param id The ID of the warning to clear.
+     */
+    clearWarning(id: string): Promise<void>;
+}