agent-sanitizer 2.64.0 → 2.64.1

package/src/url-attributes.mjs

@@ -0,0 +1,76 @@
+/**
+ * The attributes a browser resolves as URLs: the one table every Layer-3 URL
+ * read (and Layer 2's data: resource count) goes through; its test partitions
+ * the HTML Standard's URL attributes between it and an exempt list. `property`
+ * is the hast spelling; `elements` null means any element; a "form" or
+ * "refresh" `context` is also flagged for leaving the origin; `fetched` is a
+ * load nobody decides on, except on `notFetchedOn`. Rows state only where they
+ * differ from {@link DEFAULTS}.
+ */
+
+/**
+ * @typedef {{
+ *   attribute: string,
+ *   property: string,
+ *   grammar: "url" | "urls" | "srcset" | "refresh" | "css",
+ *   elements: readonly string[] | null,
+ *   context: "resource" | "form" | "refresh",
+ *   fetched: boolean,
+ *   notFetchedOn: readonly string[],
+ * }} UrlAttribute
+ */
+
+const DEFAULTS = Object.freeze({
+  grammar: "url",
+  elements: null,
+  context: "resource",
+  fetched: true,
+  notFetchedOn: [],
+});
+
+/** @type {readonly UrlAttribute[]} */
+export const URL_ATTRIBUTES = Object.freeze(
+  /** @type {Array<Partial<UrlAttribute> & { attribute: string, property: string }>} */ ([
+    { attribute: "src", property: "src" },
+    // A link waits for a click; `<base>` only re-bases relative URLs.
+    {
+      attribute: "href",
+      property: "href",
+      notFetchedOn: ["a", "area", "base"],
+    },
+    { attribute: "xlink:href", property: "xLinkHref", notFetchedOn: ["a"] },
+    { attribute: "background", property: "background" },
+    { attribute: "srcset", property: "srcSet", grammar: "srcset" },
+    {
+      attribute: "imagesrcset",
+      property: "imageSrcSet",
+      grammar: "srcset",
+      elements: ["link"],
+    },
+    { attribute: "ping", property: "ping", grammar: "urls" },
+    { attribute: "action", property: "action", context: "form" },
+    { attribute: "formaction", property: "formAction", context: "form" },
+    { attribute: "data", property: "data", elements: ["object"] },
+    { attribute: "poster", property: "poster", elements: ["video"] },
+    {
+      attribute: "cite",
+      property: "cite",
+      elements: ["blockquote", "del", "ins", "q"],
+      fetched: false,
+    },
+    {
+      attribute: "longdesc",
+      property: "longDesc",
+      elements: ["img", "iframe", "frame"],
+      fetched: false,
+    },
+    {
+      attribute: "content",
+      property: "content",
+      grammar: "refresh",
+      elements: ["meta"],
+      context: "refresh",
+    },
+    { attribute: "style", property: "style", grammar: "css" },
+  ]).map((row) => Object.freeze({ ...DEFAULTS, ...row })),
+);

package/types/css-syntax-data.d.mts

@@ -0,0 +1,6 @@
+/** GENERATED by scripts/gen-css-syntax.mjs — DO NOT EDIT (mdn-data, CC0). */
+/** @type {{ types: Record<string, string>, properties: Record<string, string> }} */
+export const CSS_SYNTAX: {
+    types: Record<string, string>;
+    properties: Record<string, string>;
+};

package/types/html-tree-adapter.d.mts

@@ -21,3 +21,46 @@ export function createTreeAdapter(): {
  * @returns {any}
  */
 export function parseHtmlFragment(html: string): any;
+/**
+ * `fromParse5(tree, { file })`, recursing at most `chunkDepth` levels at a time.
+ *
+ * Every node a multiple of `chunkDepth` levels down is converted on its own,
+ * deepest first, and then stands in its parent's `childNodes` as a placeholder
+ * text node carrying the converted subtree's position — the one thing about a
+ * child its parent's conversion reads (an unclosed element ends where its last
+ * child does). One walk then swaps each placeholder for its subtree. The result
+ * is the tree a single `fromParse5` call returns, which
+ * `html-tree-adapter.test` holds it to.
+ *
+ * Mutates `tree`: {@link parseHtmlFragment} owns the parse and drops it after.
+ * @param {any} tree
+ * @param {VFile} file
+ * @param {number} [chunkDepth]
+ * @returns {any}
+ */
+export function fromParse5Bounded(tree: any, file: VFile, chunkDepth?: number): any;
+/**
+ * How many levels of the tree one `fromParse5` call converts.
+ *
+ * WHY IT EXISTS — `hast-util-from-parse5` converts by recursion, three frames
+ * (`one` → `all` → `element`) per level, so how deep a tree it survives is
+ * whatever stack is left, and that depends on the JIT tier: a cold call's
+ * interpreted frames are bigger than an optimized one's. ~2500 nested elements
+ * overflowed on the first call in a process and converted fine on a later one,
+ * so the same document came back withheld or sanitized depending on what had
+ * run before it. 128 levels still convert cold on a 100 KB stack, a tenth of
+ * Node's default.
+ */
+export const CONVERT_DEPTH: 128;
+/**
+ * The deepest a node may sit below the fragment root; a deeper parse throws, so
+ * the caller fails closed on it.
+ *
+ * Conversion no longer limits depth (see {@link CONVERT_DEPTH}), so this is the
+ * one place that does, and it answers the same way at every JIT tier. No real
+ * document comes near it — Blink's parser flattens anything nested past 512 —
+ * and what lies past it is built to cost: parse5's scope checks walk the
+ * open-element stack per tag, so parsing is quadratic in depth.
+ */
+export const MAX_HTML_DEPTH: 4096;
+import { VFile } from "vfile";

package/types/html.d.mts

@@ -1,15 +1,18 @@
 /**
+ * True when an inline style hides its element's text, read as a block box
+ * with nothing inherited.
  * @param {string} styleStr
  * @returns {boolean}
  */
 export function isHiddenStyle(styleStr: string): boolean;
 /**
- * True for an element a rendered page would not show: `hidden` attribute or a
- * hiding inline style. Works on both hast nodes and parseHtmlTag results.
+ * True for an element a rendered page would not show (`hidden` or a hiding
+ * inline style, in element context). Takes hast nodes and parseHtmlTag results.
  * @param {any} node
+ * @param {any} [parent] the element's parent, when known
  * @returns {boolean}
  */
-export function isHiddenElement(node: any): boolean;
+export function isHiddenElement(node: any, parent?: any): boolean;
 /**
  * @param {string} htmlValue
  * @returns {string | null}
@@ -119,10 +122,9 @@ export function checkExfilUrl(url: string, options?: {
  */
 export function urlHost(url: string): string;
 /**
- * Layer 3: report data-exfil-shaped URLs in markdown links/images/definitions
- * and HTML attributes (src/href/background/srcset/ping, form action/formaction,
- * meta-refresh). Detection only — the text is never modified; the caller
- * surfaces the threats as a warning.
+ * Layer 3: report data-exfil-shaped URLs among the ones {@link collectUrls}
+ * reads. Detection only — the text is never modified; the caller surfaces the
+ * threats as a warning.
  *
  * `autoFetched` marks a threat that needs no deliberate act to fire — a
  * rendered image, a stylesheet, a form target, a meta refresh — as opposed to a
@@ -161,6 +163,40 @@ export const REPORTED_TAGS: Set<string>;
 export const HIDDEN_PLACEHOLDER: "[hidden HTML removed";
 export const COMMENT_PLACEHOLDER: "[HTML comment removed";
 export const DATA_URI_LENGTH_THRESHOLD: 4096;
+export type StyleDeclaration = {
+    property: string;
+    value: any;
+    important: boolean;
+    index: number;
+};
+/**
+ * `winnerOf`: the declaration applied (its own, a shorthand's or `all`'s);
+ * `nodeOf`/`textOf`: its value when it is the property's OWN (else null/"");
+ * `exhausted`: a lookup ran out of {@link VALIDATION_BUDGET}.
+ */
+export type Cascade = {
+    winnerOf: (property: string) => StyleDeclaration | null;
+    nodeOf: (property: string) => any;
+    textOf: (property: string) => string;
+    exhausted: boolean;
+};
+export type InheritedHide = "font-size" | "visibility" | "color" | "text-indent";
+/**
+ * `color` and a concrete `-webkit-text-fill-color` (`textFill`) inherit
+ * SEPARATELY, so a child's `color` does not undo an inherited transparent fill.
+ */
+export type ColorState = {
+    color: string;
+    textFill: string;
+    backdrop: string;
+    imageLayer: boolean;
+    paintedVisible: boolean;
+};
+export type RegionState = {
+    kinds: Set<InheritedHide>;
+    color: ColorState;
+};
+export type RegionVerdict = "hidden" | "neutral" | "visible" | "mixed";
 export type CollectedUrl = {
     url: string;
     isImage: boolean;

package/types/url-attributes.d.mts

@@ -0,0 +1,11 @@
+/** @type {readonly UrlAttribute[]} */
+export const URL_ATTRIBUTES: readonly UrlAttribute[];
+export type UrlAttribute = {
+    attribute: string;
+    property: string;
+    grammar: "url" | "urls" | "srcset" | "refresh" | "css";
+    elements: readonly string[] | null;
+    context: "resource" | "form" | "refresh";
+    fetched: boolean;
+    notFetchedOn: readonly string[];
+};