@marianmeres/safe-html 0.2.0

package/dist/kit.js

@@ -0,0 +1,170 @@
+/**
+ * The URL-policy-bound API: `createHtml()` and the default kit.
+ */
+import { describe, HtmlValueError } from "./errors.js";
+import { escapeHtml } from "./escape.js";
+import { renderValue } from "./render.js";
+import { analyze, templateError, URL_ATTRIBUTES } from "./scanner.js";
+import { isTrusted, makeTrusted, trustedString } from "./trusted.js";
+import { createPolicy, normalizeSchemes, vetUrl } from "./url.js";
+const ATTR_NAME = /^[A-Za-z_][A-Za-z0-9_.:-]*$/;
+const DESCRIPTOR = /^(?:\d+(?:\.\d+)?x|\d+w)$/;
+const BLANK = /^[\t\n\f\r ]*$/;
+/** Percent-encodes what would break `srcset` parsing: ASCII whitespace, edge commas. */
+function encodeSrcsetUrl(u) {
+    return u
+        .replace(/[\t\n\f\r ]/g, (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0"))
+        .replace(/^,+|,+$/g, (m) => "%2C".repeat(m.length));
+}
+/**
+ * Creates a kit whose `html`, `attrs`, `url` and `srcset` use the given URL policy.
+ * Throws `TypeError` on malformed options.
+ */
+export function createHtml(options = {}) {
+    const policy = createPolicy(options);
+    const schemeLists = new WeakMap();
+    function html(strings, ...values) {
+        const a = analyze(strings);
+        const slots = a.slots;
+        if (values.length !== slots.length) {
+            throw templateError(strings, "html must be called as a tagged template: html`…`");
+        }
+        const st = { neutral: a.neutral };
+        let out = strings[0];
+        for (let i = 0; i < slots.length; i++) {
+            const slot = slots[i];
+            if (slot.scheme !== "" && !policy.schemes.has(slot.scheme)) {
+                throw templateError(strings, `the static URL text before the slot uses the scheme "${slot.scheme}:", which this kit does not allow; build the whole URL in code and pass it through url(value, { schemes })`, i);
+            }
+            out += renderValue(values[i], slot, i, policy, st) + strings[i + 1];
+        }
+        return makeTrusted("html", out, st.neutral);
+    }
+    function attrValue(lower, value, n) {
+        if (lower === "srcset" || lower === "imagesrcset") {
+            if (isTrusted(value, "srcset"))
+                return escapeHtml(trustedString(value));
+            if (isTrusted(value, "unsafe"))
+                return trustedString(value);
+            throw new HtmlValueError(`attrs(): "${lower}" takes srcset([…])`, {
+                received: describe(value),
+            });
+        }
+        switch (typeof value) {
+            case "string":
+            case "number":
+            case "bigint": {
+                const s = String(value);
+                if (!URL_ATTRIBUTES.has(lower) && lower !== "data")
+                    return escapeHtml(s);
+                return escapeHtml(vetUrl(s, policy, undefined, lower) ?? policy.blockedUrl);
+            }
+            case "object":
+                if (isTrusted(value, "url") || isTrusted(value, "srcset")) {
+                    return escapeHtml(trustedString(value));
+                }
+                if (isTrusted(value, "unsafe"))
+                    return trustedString(value);
+        }
+        throw new HtmlValueError(`attrs(): the value of attribute #${n} has no attribute rendering`, {
+            received: describe(value),
+        });
+    }
+    function attrs(record) {
+        if (record === null || typeof record !== "object" || Array.isArray(record) ||
+            isTrusted(record)) {
+            throw new HtmlValueError("attrs() takes a plain object", {
+                received: describe(record),
+            });
+        }
+        let out = "";
+        const names = Object.keys(record);
+        for (let n = 0; n < names.length; n++) {
+            const name = names[n];
+            if (!ATTR_NAME.test(name)) {
+                throw new HtmlValueError(`attrs(): attribute #${n} has an invalid name (must match ${ATTR_NAME})`, { received: "attribute name" });
+            }
+            const lower = name.toLowerCase();
+            if (lower.startsWith("on")) {
+                throw new HtmlValueError(`attrs(): attribute #${n} is an event handler (on*)`, {
+                    received: "attribute name",
+                });
+            }
+            if (lower === "srcdoc" || lower === "ping") {
+                throw new HtmlValueError(`attrs(): "${lower}" is not supported`, {
+                    received: "attribute name",
+                });
+            }
+            const value = record[name];
+            if (value === null || value === undefined || value === false)
+                continue;
+            out += value === true
+                ? " " + name
+                : " " + name + '="' + attrValue(lower, value, n) + '"';
+        }
+        return makeTrusted("attrs", out);
+    }
+    function url(value, options) {
+        if (typeof value !== "string") {
+            throw new HtmlValueError("url() takes a string", {
+                received: describe(value),
+            });
+        }
+        let schemes = policy.schemes;
+        const list = options?.schemes;
+        if (list !== undefined) {
+            // cache only frozen lists: a mutable array could change between calls
+            schemes = schemeLists.get(list) ?? normalizeSchemes(list);
+            if (Object.isFrozen(list))
+                schemeLists.set(list, schemes);
+        }
+        return makeTrusted("url", vetUrl(value, policy, undefined, undefined, schemes) ?? policy.blockedUrl);
+    }
+    function srcset(candidates) {
+        if (!Array.isArray(candidates)) {
+            throw new HtmlValueError("srcset() takes an array", {
+                received: describe(candidates),
+            });
+        }
+        const parts = [];
+        for (let n = 0; n < candidates.length; n++) {
+            const c = candidates[n];
+            if (c === null || typeof c !== "object") {
+                throw new HtmlValueError(`srcset(): candidate #${n} must be an object`, {
+                    received: describe(c),
+                });
+            }
+            const { url: u, descriptor } = c;
+            if (descriptor !== undefined &&
+                (typeof descriptor !== "string" || !DESCRIPTOR.test(descriptor))) {
+                throw new HtmlValueError(`srcset(): candidate #${n} has an invalid descriptor (expected e.g. "2x", "1.5x", "800w")`, { received: describe(descriptor) });
+            }
+            let vetted;
+            if (typeof u === "string") {
+                vetted = vetUrl(u, policy, undefined, "srcset");
+            }
+            else if (isTrusted(u, "url"))
+                vetted = trustedString(u);
+            else {
+                throw new HtmlValueError(`srcset(): candidate #${n} url must be a string or url()`, {
+                    received: describe(u),
+                });
+            }
+            if (vetted === null || BLANK.test(vetted))
+                continue;
+            const enc = encodeSrcsetUrl(vetted);
+            parts.push(descriptor ? `${enc} ${descriptor}` : enc);
+        }
+        return makeTrusted("srcset", parts.join(", "));
+    }
+    return Object.freeze({ html, attrs, url, srcset });
+}
+const defaultKit = createHtml();
+/** The template tag of the default kit. Every interpolated value is escaped for its context. */
+export const html = defaultKit.html;
+/** `attrs()` of the default kit. */
+export const attrs = defaultKit.attrs;
+/** `url()` of the default kit. */
+export const url = defaultKit.url;
+/** `srcset()` of the default kit. */
+export const srcset = defaultKit.srcset;

package/dist/mod.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @module
+ * HTML tagged templates with contextual escaping. Every interpolated value is escaped for the
+ * place it appears (text, attribute, URL, `<script>`, `<style>`), worked out once per call site
+ * from the template's static markup. Slot positions that can never be made safe are rejected.
+ *
+ * @example
+ * ```ts
+ * import { html } from "@marianmeres/safe-html";
+ *
+ * const link = (href: string, label: string) => html`<a href="${href}">${label}</a>`;
+ * String(link("javascript:alert(1)", "<b>hi</b>"));
+ * // <a href="about:invalid#blocked">&lt;b&gt;hi&lt;/b&gt;</a>
+ * ```
+ */
+export type { AttrValue, BlockedUrlInfo, HtmlKit, HtmlOptions, Renderable, SafeAttrs, SafeHtml, SafeSrcset, SafeUrl, SlotContext, SrcsetCandidate, Trusted, TrustedKind, } from "./types.js";
+export { attrs, createHtml, html, srcset, url } from "./kit.js";
+export { join, jsonScript, scriptText, styleText, unsafeRaw } from "./helpers.js";
+export { escapeHtml } from "./escape.js";
+export { isTrusted } from "./trusted.js";
+export { HtmlTemplateError, HtmlValueError } from "./errors.js";
+export { DEFAULT_URL_SCHEMES } from "./url.js";

package/dist/mod.js

@@ -0,0 +1,6 @@
+export { attrs, createHtml, html, srcset, url } from "./kit.js";
+export { join, jsonScript, scriptText, styleText, unsafeRaw } from "./helpers.js";
+export { escapeHtml } from "./escape.js";
+export { isTrusted } from "./trusted.js";
+export { HtmlTemplateError, HtmlValueError } from "./errors.js";
+export { DEFAULT_URL_SCHEMES } from "./url.js";

package/dist/render.d.ts

@@ -0,0 +1,9 @@
+import type { SlotInfo } from "./scanner.js";
+import { type UrlPolicy } from "./url.js";
+/** Mutable state of one render. */
+export interface RenderState {
+    /** Stays true while every HTML fragment placed in a text slot is neutral. */
+    neutral: boolean;
+}
+/** Renders one interpolated value for a slot. */
+export declare function renderValue(v: unknown, slot: SlotInfo, index: number | undefined, policy: UrlPolicy | undefined, st: RenderState, depth?: number): string;

package/dist/render.js

@@ -0,0 +1,131 @@
+/**
+ * Rendering: value × context rules. Whether a render throws depends on a value's type or
+ * trusted kind, never on the content of a string.
+ */
+import { describe, HtmlValueError } from "./errors.js";
+import { escapeHtml } from "./escape.js";
+import { isNeutral, isTrusted, trustedString } from "./trusted.js";
+import { vetUrl } from "./url.js";
+/** Guards against cyclic arrays. */
+const MAX_DEPTH = 100;
+const HINTS = {
+    text: "",
+    rcdata: "<title> and <textarea> hold text only: pass a string",
+    "attr-list": "use attrs({ … })",
+    "attr-value": "attribute values take strings, numbers or url()",
+    url: "URL attributes take a string or url()",
+    srcset: "use srcset([…])",
+    script: "use jsonScript(data) for data, or scriptText(source) for code",
+    style: "use styleText(source)",
+};
+/** Renders one interpolated value for a slot. */
+export function renderValue(v, slot, index, policy, st, depth = 0) {
+    const ctx = slot.context;
+    if (typeof v === "string") {
+        if (ctx === "text" || ctx === "attr-value" || ctx === "rcdata") {
+            return escapeHtml(v);
+        }
+        if (ctx === "url")
+            return escapeHtml(vet(v, slot, policy));
+        return refuse(v, slot, index);
+    }
+    if (v === null || v === undefined || typeof v === "boolean")
+        return "";
+    if (typeof v === "object") {
+        if (isTrusted(v)) {
+            const out = renderTrusted(v, slot, st);
+            if (out !== undefined)
+                return out;
+        }
+        else if (Array.isArray(v) &&
+            (ctx === "text" || ctx === "rcdata" || ctx === "attr-list")) {
+            if (depth >= MAX_DEPTH) {
+                throw new HtmlValueError("arrays nested too deeply (a cycle?)", {
+                    slot: index,
+                    context: ctx,
+                    received: "array",
+                });
+            }
+            let out = "";
+            for (let i = 0; i < v.length; i++) {
+                out += renderValue(v[i], slot, index, policy, st, depth + 1);
+            }
+            return out;
+        }
+    }
+    else if (typeof v === "number" || typeof v === "bigint") {
+        if (ctx === "text" || ctx === "attr-value" || ctx === "rcdata")
+            return String(v);
+        if (ctx === "url")
+            return escapeHtml(vet(String(v), slot, policy));
+    }
+    return refuse(v, slot, index);
+}
+function renderTrusted(v, slot, st) {
+    const ctx = slot.context;
+    const s = trustedString(v);
+    switch (v.kind) {
+        case "unsafe":
+            return s;
+        case "html":
+            if (ctx !== "text")
+                return undefined;
+            if (!isNeutral(v)) {
+                if (slot.foreign)
+                    return undefined;
+                st.neutral = false;
+            }
+            return s;
+        case "attrs":
+            return ctx === "attr-list" ? s : undefined;
+        case "url":
+            return ctx === "text" || ctx === "rcdata" || ctx === "attr-value" ||
+                ctx === "url"
+                ? escapeHtml(s)
+                : undefined;
+        case "srcset":
+            return ctx === "srcset" || ctx === "attr-value" ? escapeHtml(s) : undefined;
+        case "json":
+        case "js":
+            return ctx === "script" ? s : undefined;
+        case "css":
+            return ctx === "style" ? s : undefined;
+    }
+    return undefined;
+}
+function vet(value, slot, policy) {
+    return vetUrl(value, policy, slot.tag, slot.attr) ??
+        policy.blockedUrl;
+}
+function refuse(v, slot, index) {
+    const ctx = slot.context;
+    const received = describe(v);
+    let msg;
+    // deno-lint-ignore no-explicit-any
+    if (typeof v?.then === "function") {
+        msg = "async values are not supported: await before rendering";
+    }
+    else if (isTrusted(v)) {
+        if (v.kind === "html" && ctx === "text") {
+            msg =
+                "this HTML fragment can't go inside <svg>/<math>: it contains markup that parses differently there (e.g. <style>, <p>)";
+        }
+        else if (v.kind === "html" && (ctx === "attr-value" || ctx === "url")) {
+            msg = "an html fragment can't be an attribute value";
+        }
+        else {
+            msg = `cannot render ${received} in ${ctx} context: ${HINTS[ctx] || "not allowed"}`;
+        }
+    }
+    else if (typeof v === "function" || typeof v === "symbol" ||
+        (typeof v === "object" && !Array.isArray(v))) {
+        msg = "this value has no HTML rendering: convert it to a string first";
+    }
+    else if (Array.isArray(v)) {
+        msg =
+            `arrays render only in text and attribute-list slots, not in ${ctx} context`;
+    }
+    else
+        msg = `cannot render ${received} in ${ctx} context: ${HINTS[ctx]}`;
+    throw new HtmlValueError(msg, { slot: index, context: ctx, received });
+}

package/dist/scanner.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Context analysis (the scanner).
+ *
+ * Purpose: classify every slot of a template from its static strings alone, once per call
+ * site, and cache the result (including a failure) by template object.
+ *
+ * Invariants:
+ * - Models only the part of the HTML tokenizer, and of the tree construction that switches the
+ *   tokenizer (raw text, RCDATA, SVG/MathML foreign content), needed to classify slots.
+ *   Anything it does not model is an error, never a guess.
+ * - A slot never changes the scanner state: every value renders so that it can't.
+ * - A template ends where it started: in text, outside any tag, comment, raw text or foreign
+ *   content. That makes a fragment safe to drop into another template's text slot.
+ * - Foreign content: a fragment is "neutral" when a second scan that starts inside SVG/MathML
+ *   agrees with the HTML scan; only neutral fragments may go into SVG/MathML text slots.
+ */
+import { HtmlTemplateError } from "./errors.js";
+import type { SlotContext } from "./types.js";
+/** What the scanner knows about one slot. All fields are always present (one object shape). */
+export interface SlotInfo {
+    readonly context: SlotContext;
+    /** Lowercased tag name (attribute and raw-text slots), else `""`. */
+    readonly tag: string;
+    /** Lowercased attribute name (attribute value slots), else `""`. */
+    readonly attr: string;
+    /** Scheme written statically before a URL slot, else `""`; checked against the kit. */
+    readonly scheme: string;
+    /** A `text` slot inside SVG/MathML: HTML fragments must be neutral. */
+    readonly foreign: boolean;
+}
+/** Creates a slot description (always the same shape, which keeps rendering monomorphic). */
+export declare function slotInfo(context: SlotContext, tag?: string, attr?: string, scheme?: string, foreign?: boolean): SlotInfo;
+/** The cached result for one call site. */
+export interface Analysis {
+    readonly slots: readonly SlotInfo[];
+    /** Parses the same inside SVG/MathML as in HTML (see module doc). */
+    readonly neutral: boolean;
+}
+/** Attributes whose value is a URL (plus `data` on `<object>`). */
+export declare const URL_ATTRIBUTES: ReadonlySet<string>;
+/** Number of analyses run so far. For tests only (not exported from mod.ts). */
+export declare function analysisCount(): number;
+/**
+ * The analysis of a template, from the cache or computed once. Throws `HtmlTemplateError` if
+ * `strings` is not a genuine template object, or if the template is refused.
+ */
+export declare function analyze(strings: TemplateStringsArray): Analysis;
+/**
+ * An `HtmlTemplateError` whose excerpt shows the static text with slots as `${…}` and the
+ * error position (a slot, or a chunk offset) marked `⟨here⟩`.
+ */
+export declare function templateError(strings: TemplateStringsArray, reason: string, slot?: number, chunk?: number, offset?: number, useRaw?: boolean): HtmlTemplateError;