@dogsbay/render-html 0.0.0-stage → 0.2.0-beta.116

package/dist/sanitize.d.ts

@@ -0,0 +1,13 @@
+import type { TreeNode } from "@dogsbay/types";
+/** What sanitizing removed, by kind; the caller reports it (@dogsbay/render's report codes). */
+export type SanitizeWarningCode = "html-sanitized" | "attribute-dropped" | "unsafe-url" | "image-remote";
+export type Warn = (code: SanitizeWarningCode, message: string) => void;
+/**
+ * Whether a URL is safe to put in an href or src: http(s), mailto, a fragment,
+ * a relative path, or (for images only) a raster data: URI.
+ */
+export declare function safeUrl(raw: string, kind: "link" | "image"): boolean;
+/** Raw HTML through the allowlist. Text is re-escaped; unknown elements keep their text. */
+export declare function sanitizeHtml(html: string, warn: Warn): string;
+/** A sanitized copy of the tree. */
+export declare function sanitizeTree(nodes: TreeNode[], warn: Warn): TreeNode[];

package/dist/sanitize.js

@@ -0,0 +1,230 @@
+/**
+ * Sanitizing for untrusted input, on the parsed tree rather than the output.
+ * render-html escapes everything it writes itself, so what can carry markup or
+ * script into the page is limited to:
+ *   - raw HTML (`html` and `html-inline` nodes), filtered here to an allowlist
+ *     of elements and attributes;
+ *   - URLs (http, https, mailto, tel, relative, #) in directive attributes and inline links/images (`:::card{href}`,
+ *     link buttons), which never pass markdown-it's link validation;
+ *   - `class` and `style` from attribute blocks: a class like `bg-[url(…)]`
+ *     becomes real CSS once the page's classes are compiled, and fetches.
+ * Shared by @dogsbay/render (single pages), dogsbay-ssg and the Astro pipeline
+ * (content.html: sanitize). In @dogsbay/render the page's CSP (document.ts) is the second line: it blocks scripts that are
+ * not ours and every external request, even if something gets past this.
+ */
+import { Parser } from "htmlparser2";
+const ELEMENTS = new Set([
+    "a", "abbr", "b", "bdi", "bdo", "blockquote", "br", "caption", "cite", "code", "col", "colgroup",
+    "dd", "del", "details", "dfn", "div", "dl", "dt", "em", "figcaption", "figure",
+    "h1", "h2", "h3", "h4", "h5", "h6", "hr", "i", "img", "ins", "kbd", "li", "mark", "ol", "p", "pre",
+    "q", "rp", "rt", "ruby", "s", "samp", "small", "span", "strong", "sub", "summary", "sup",
+    "table", "tbody", "td", "tfoot", "th", "thead", "time", "tr", "u", "ul", "var", "wbr",
+]);
+/** Elements dropped together with everything inside them. */
+const DROP_WITH_CONTENT = new Set(["script", "style", "iframe", "object", "embed", "template", "noscript", "svg", "math", "frame", "frameset", "noembed", "textarea", "select", "button", "form", "input"]);
+const VOID = new Set(["br", "col", "hr", "img", "wbr"]);
+const GLOBAL_ATTRS = new Set(["id", "title", "lang", "dir"]);
+const ATTRS = {
+    a: new Set(["href", "rel"]),
+    img: new Set(["src", "alt", "width", "height"]),
+    td: new Set(["colspan", "rowspan", "headers"]),
+    th: new Set(["colspan", "rowspan", "headers", "scope"]),
+    col: new Set(["span"]),
+    colgroup: new Set(["span"]),
+    ol: new Set(["start", "reversed", "type"]),
+    li: new Set(["value"]),
+    time: new Set(["datetime"]),
+    details: new Set(["open"]),
+    q: new Set(["cite"]),
+    blockquote: new Set(["cite"]),
+    del: new Set(["cite", "datetime"]),
+    ins: new Set(["cite", "datetime"]),
+};
+const URL_ATTRS = new Set(["href", "src", "cite"]);
+/** Node types whose `html` field is source text, not markup. */
+const TEXT_HTML_TYPES = new Set(["code", "math", "math-block", "diagram"]);
+/** Prop keys on directive nodes that hold a URL. */
+const URL_PROPS = new Set(["href", "src", "url", "link", "poster", "image", "logo"]);
+const escAttr = (s) => s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/'/g, "&#39;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+const escText = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+/** Ids the page's own components use (render-html RESERVED_ID): raw HTML may not take them. */
+const RESERVED_ID = /^(db-|tab-\d|tabpanel-\d|acc-\d|accpanel-\d|fn-|fnref-)/;
+/**
+ * Whether a URL is safe to put in an href or src: http(s), mailto, a fragment,
+ * a relative path, or (for images only) a raster data: URI.
+ */
+export function safeUrl(raw, kind) {
+    // Browsers ignore control characters and whitespace inside a scheme ("java\tscript:").
+    const v = raw.replace(/[\u0000- \u007f-\u009f]/g, "").toLowerCase();
+    const scheme = /^([a-z][a-z0-9+.-]*):/.exec(v)?.[1];
+    if (!scheme)
+        return !v.startsWith("//") || kind === "link"; // relative; protocol-relative only as a link
+    if (scheme === "http" || scheme === "https")
+        return true;
+    if ((scheme === "mailto" || scheme === "tel") && kind === "link")
+        return true;
+    if (scheme === "data" && kind === "image")
+        return /^data:image\/(png|jpeg|gif|webp);/.test(v);
+    return false;
+}
+/** Raw HTML through the allowlist. Text is re-escaped; unknown elements keep their text. */
+export function sanitizeHtml(html, warn) {
+    // Inline raw HTML arrives one tag per node, so a closing tag is often alone; the
+    // parser ignores an unmatched closer, which would leave the allowed element open.
+    const closer = /^\s*<\/([a-zA-Z][a-zA-Z0-9]*)\s*>\s*$/.exec(html);
+    if (closer) {
+        const name = closer[1].toLowerCase();
+        return ELEMENTS.has(name) && !VOID.has(name) ? `</${name}>` : "";
+    }
+    let out = "";
+    let dropDepth = 0;
+    const dropped = new Set();
+    const parser = new Parser({
+        onopentag(name, attribs) {
+            if (dropDepth > 0 || DROP_WITH_CONTENT.has(name)) {
+                if (!VOID.has(name))
+                    dropDepth++;
+                dropped.add(name);
+                return;
+            }
+            if (!ELEMENTS.has(name)) {
+                dropped.add(name);
+                return;
+            }
+            const allowed = ATTRS[name];
+            let attrs = "";
+            for (const [k, v] of Object.entries(attribs)) {
+                const key = k.toLowerCase();
+                if (!GLOBAL_ATTRS.has(key) && !allowed?.has(key)) {
+                    if (key.startsWith("on") || key === "style" || key === "class" || key === "srcset")
+                        dropped.add(`${name}[${key}]`);
+                    continue;
+                }
+                if (key === "id" && RESERVED_ID.test(v)) {
+                    dropped.add(`${name}[id=${v.slice(0, 40)}]`);
+                    continue;
+                }
+                if (URL_ATTRS.has(key) && !safeUrl(v, name === "img" && key === "src" ? "image" : "link")) {
+                    dropped.add(`${name}[${key}=${v.slice(0, 40)}]`);
+                    continue;
+                }
+                if (name === "img" && key === "src" && /^(https?:)?\/\//i.test(v))
+                    warn("image-remote", `"${v.slice(0, 80)}" (raw HTML): remote images are not loaded`);
+                attrs += ` ${key}="${escAttr(v)}"`;
+            }
+            out += `<${name}${attrs}>`;
+        },
+        ontext(text) {
+            if (dropDepth === 0)
+                out += escText(text);
+        },
+        onclosetag(name, isImplied) {
+            if (dropDepth > 0) {
+                if (!VOID.has(name))
+                    dropDepth--;
+                return;
+            }
+            if (ELEMENTS.has(name) && !VOID.has(name) && !isImplied)
+                out += `</${name}>`;
+        },
+    }, { decodeEntities: true, lowerCaseTags: true, lowerCaseAttributeNames: true, recognizeSelfClosing: true });
+    parser.write(html);
+    parser.end();
+    if (dropped.size)
+        warn("html-sanitized", `raw HTML: removed ${[...dropped].join(", ")}`);
+    return out;
+}
+function cleanProps(props, where, warn) {
+    if (!props)
+        return props;
+    const out = {};
+    for (const [k, v] of Object.entries(props)) {
+        // copyText would make the copy button copy something other than the code shown;
+        // data-* attributes can steer the page's element scripts; aria-* (aria-hidden) can
+        // hide content from assistive technology.
+        // svg: a diagram's prebuilt SVG is written as markup, unfiltered.
+        if (k === "class" || k === "className" || k === "style" || k === "svg" || k.startsWith("on") || k === "copyText" || k.startsWith("data-") || k.startsWith("aria-")) {
+            warn("attribute-dropped", `${where}: dropped the "${k}" attribute (not allowed in a sanitized page)`);
+            continue;
+        }
+        // Footnote ids (fn-1, fnref-1) are the parser's own, not authored.
+        if (k === "id" && typeof v === "string" && RESERVED_ID.test(v) && !where.startsWith("footnote")) {
+            warn("attribute-dropped", `${where}: dropped id="${v.slice(0, 40)}" (reserved for the page's own components)`);
+            continue;
+        }
+        if (URL_PROPS.has(k) && typeof v === "string" && !safeUrl(v, k === "src" || k === "poster" || k === "image" || k === "logo" ? "image" : "link")) {
+            warn("unsafe-url", `${where}: removed ${k}="${v.slice(0, 60)}" (only http, https, mailto and relative links are allowed)`);
+            continue;
+        }
+        out[k] = v;
+    }
+    return out;
+}
+/** An inline fragment that opens an element whose content is dropped: the name, unless it also closes it. */
+function opensDropped(html) {
+    const m = /^\s*<([a-zA-Z][a-zA-Z0-9]*)\b[^>]*>/.exec(html);
+    if (!m)
+        return undefined;
+    const name = m[1].toLowerCase();
+    if (!DROP_WITH_CONTENT.has(name) || /\/>\s*$/.test(m[0]))
+        return undefined;
+    return new RegExp(`</${name}\\s*>`, "i").test(html) ? undefined : name;
+}
+function inline(nodes, warn) {
+    if (!nodes)
+        return nodes;
+    // Inline raw HTML is split into one node per tag, so `<script>` … `</script>` are
+    // separate nodes: everything between an opened dropped element and its closer goes too.
+    let skipping;
+    const kept = nodes.filter((n) => {
+        const html = n.type === "html-inline" ? String(n.html ?? "") : "";
+        if (skipping) {
+            if (new RegExp(`^\\s*</${skipping}\\s*>`, "i").test(html))
+                skipping = undefined;
+            return false;
+        }
+        if (html) {
+            const name = opensDropped(html);
+            if (name) {
+                warn("html-sanitized", `raw HTML: removed ${name}`);
+                skipping = name;
+                return false;
+            }
+        }
+        return true;
+    });
+    return kept.map((n) => {
+        const node = { ...n };
+        if (node.type === "html-inline" && typeof node.html === "string")
+            node.html = sanitizeHtml(node.html, warn);
+        if (node.type === "link" && typeof node.href === "string" && !safeUrl(node.href, "link")) {
+            warn("unsafe-url", `link: removed href="${node.href.slice(0, 60)}"`);
+            node.href = "#";
+        }
+        if (node.type === "image" && typeof node.src === "string" && !safeUrl(node.src, "image")) {
+            warn("unsafe-url", `image: removed src="${node.src.slice(0, 60)}"`);
+            node.src = "";
+        }
+        if (node.attrs && typeof node.attrs === "object")
+            node.attrs = cleanProps(node.attrs, node.type, warn);
+        if (Array.isArray(node.children))
+            node.children = inline(node.children, warn);
+        return node;
+    });
+}
+/** A sanitized copy of the tree. */
+export function sanitizeTree(nodes, warn) {
+    return nodes.map((n) => {
+        const node = { ...n };
+        // Any node carrying raw HTML (html, html-block, html-container under a <details>…).
+        // Code and math keep their source text in `html`; it is escaped when written.
+        if (typeof node.html === "string" && !TEXT_HTML_TYPES.has(node.type))
+            node.html = sanitizeHtml(node.html, warn);
+        node.props = cleanProps(node.props, node.type, warn);
+        if (node.inline)
+            node.inline = inline(node.inline, warn);
+        if (node.children)
+            node.children = sanitizeTree(node.children, warn);
+        return node;
+    });
+}

package/dist/tone-classes.d.ts

@@ -0,0 +1 @@
+export declare const TONE_CLASSES: Record<string, string>;

package/dist/tone-classes.js

@@ -0,0 +1,15 @@
+// Generated by packages/render-html/scripts/sync-sources.mjs from @dogsbay/format-astro TONE_CLASSES. Do not edit.
+export const TONE_CLASSES = {
+    "primary": "bg-primary text-primary-foreground",
+    "primary-strong": "bg-primary/80 text-primary-foreground",
+    "primary-medium": "bg-primary/60 text-primary-foreground",
+    "primary-half": "bg-primary/50 text-primary-foreground",
+    "primary-light": "bg-primary/20 text-primary",
+    "primary-soft": "bg-primary/10 text-primary",
+    "muted": "bg-muted text-muted-foreground",
+    "blue": "bg-blue-500/15 text-blue-700 dark:text-blue-300",
+    "amber": "bg-amber-500/15 text-amber-700 dark:text-amber-300",
+    "green": "bg-green-500/15 text-green-700 dark:text-green-300",
+    "purple": "bg-purple-500/15 text-purple-700 dark:text-purple-300",
+    "red": "bg-red-500/15 text-red-700 dark:text-red-300"
+};

package/dist/url.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A URL that runs script or carries a document of its own: javascript:, vbscript:,
+ * a data: link, or a data: "image" that is not an image. render-html
+ * refuses these wherever it writes a link or an image: they are never legitimate
+ * in docs, and directive attributes (`:::card{href}`) never meet markdown-it's link
+ * check. Other schemes (ftp:, vscode:) are allowed; the strict allowlist is
+ * `safeUrl` in ./sanitize.js. Character references are decoded first, for URLs
+ * taken from raw HTML.
+ */
+export declare function scriptUrl(raw: string, kind: "link" | "image"): boolean;

package/dist/url.js

@@ -0,0 +1,29 @@
+/**
+ * The one URL check render-html applies whatever the caller's settings
+ * (dogsbay-ssg plans/html-safety.md): serialize-core's `isSafeHref`, the check the
+ * Astro serializer applies to the same links, so both pipelines refuse the same URLs.
+ */
+import { isSafeHref } from "@dogsbay/serialize-core";
+/** Character references a browser decodes in an attribute before reading a scheme ("java	script:"). */
+const SCHEME_REFS = /&(?:#(\d+)|#x([0-9a-f]+)|(tab|newline|colon));?/gi;
+/**
+ * A URL that runs script or carries a document of its own: javascript:, vbscript:,
+ * a data: link, or a data: "image" that is not an image. render-html
+ * refuses these wherever it writes a link or an image: they are never legitimate
+ * in docs, and directive attributes (`:::card{href}`) never meet markdown-it's link
+ * check. Other schemes (ftp:, vscode:) are allowed; the strict allowlist is
+ * `safeUrl` in ./sanitize.js. Character references are decoded first, for URLs
+ * taken from raw HTML.
+ */
+export function scriptUrl(raw, kind) {
+    const v = raw.replace(SCHEME_REFS, (_, dec, hex, named) => {
+        if (named)
+            return { tab: "\t", newline: "\n", colon: ":" }[named.toLowerCase()];
+        const cp = Number.parseInt(dec ?? hex, dec ? 10 : 16);
+        return cp > 0 && cp <= 0x10ffff ? String.fromCodePoint(cp) : "";
+    });
+    // An <img> never runs script, SVG included, so any data:image/ is kept (isSafeHref allows raster only).
+    if (kind === "image" && /^data:image\//i.test(v.replace(/[\u0000-\u0020\u007f]+/g, "")))
+        return false;
+    return !isSafeHref(v, kind);
+}

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@dogsbay/render-html",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0-beta.116",
+  "description": "Dogsbay MD TreeNode → HTML with the Astro components' markup and classes. No highlighter, math or CSS compiler unless you pass one; Worker- and browser-safe",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./math": {
+      "types": "./dist/math.d.ts",
+      "import": "./dist/math.js"
+    },
+    "./css/*": "./css/*",
+    "./assets/*": "./assets/*",
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js"
+    }
+  },
+  "files": [
+    "dist",
+    "css",
+    "assets",
+    "README.md"
+  ],
+  "dependencies": {
+    "htmlparser2": "^10.1.0",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.116",
+    "@dogsbay/serialize-core": "0.2.0-beta.116",
+    "@dogsbay/types": "0.2.0-beta.116"
+  },
+  "peerDependencies": {
+    "katex": "^0.16.0"
+  },
+  "peerDependenciesMeta": {
+    "katex": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "esbuild": "^0.25.0",
+    "katex": "^0.16.47",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dogsbay/dogsbay.git",
+    "directory": "packages/render-html"
+  },
+  "scripts": {
+    "build": "tsc",
+    "sync-sources": "node scripts/sync-sources.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
 }