npm - @marianmeres/safe-html - Versions diffs - 0.2.0 - Mend

@marianmeres/safe-html 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (27) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,212 @@
+# @marianmeres/safe-html
+[![NPM](https://img.shields.io/npm/v/@marianmeres/safe-html)](https://www.npmjs.com/package/@marianmeres/safe-html)
+[![JSR](https://jsr.io/badges/@marianmeres/safe-html)](https://jsr.io/@marianmeres/safe-html)
+[![License](https://img.shields.io/npm/l/@marianmeres/safe-html)](LICENSE)
+HTML tagged templates with **contextual escaping**. Every interpolated value is escaped for the
+place it appears — element text, attribute value, URL attribute, `<script>`, `<style>` — as
+worked out once per call site from the template's static markup. Slot positions that can never
+be made safe (unquoted attributes, event handlers, tag names, comments) are rejected the first
+time the template renders, whatever the data.
+Zero dependencies. Runtime-agnostic ESM (Deno, Node, Bun, browsers). For servers that render
+HTML strings without a framework.
+## Installation
+```sh
+deno add jsr:@marianmeres/safe-html
+```
+```sh
+npm install @marianmeres/safe-html
+```
+## Usage
+<!-- deno-fmt-ignore-start -->
+```ts
+import { html, jsonScript } from "@marianmeres/safe-html";
+interface Link {
+	label: string;
+	href: string;
+}
+const LinkItem = (link: Link) => html`<li><a href="${link.href}">${link.label}</a></li>`;
+export const page = (title: string, links: Link[], ld: object) =>
+	html`<!doctype html>
+<html lang="en">
+<head>
+	<meta charset="utf-8">
+	<title>${title}</title>
+	<script type="application/ld+json">${jsonScript(ld)}</script>
+</head>
+<body>
+	<h1>${title}</h1>
+	${links.length > 0 ? html`<ul>${links.map(LinkItem)}</ul>` : html`<p>No links.</p>`}
+</body>
+</html>`;
+// String(page(…)) is the document.
+// label "<img src=x onerror=alert(1)>"  → rendered as text
+// href  "javascript:alert(1)"           → rendered as href="about:invalid#blocked"
+```
+<!-- deno-fmt-ignore-end -->
+Components are plain functions returning `html`. Conditionals, lists and nesting are plain
+expressions:
+<!-- deno-fmt-ignore-start -->
+```ts
+import { attrs, html, join, scriptText, srcset, styleText, url } from "@marianmeres/safe-html";
+html`<p>${user.name}</p>`;                                   // text: escaped
+html`<p title="${note}" class="card ${kind}">…</p>`;         // quoted attribute: escaped
+html`<a href="${link}">…</a>`;                               // URL: scheme allowlist, then escaped
+html`<img src="${cdn}/img/${file}.png">`;                    // URL slot followed by "/", "?" or "#"
+html`<a href="/items/${id}?tab=${tab}">…</a>`;               // static prefix settles the scheme
+html`<button ${attrs({ type: "submit", disabled: busy })}>`; // attribute list
+html`<img srcset="${srcset([{ url: a }, { url: b, descriptor: "2x" }])}">`;
+html`<script>const data = ${jsonScript(data)};</script>`;    // data island
+html`<script>${scriptText(source)}</script>`;                // inline code
+html`<style>${styleText(css)}</style>`;                      // inline CSS
+html`<p>${join(tags, ", ")}</p>`;                            // separated list
+html`<ul>${items.map((i) => html`<li>${i}</li>`)}</ul>`;     // arrays render item by item
+html`${loggedIn && html`<a href="/logout">Log out</a>`}`;    // false/null/undefined render nothing
+html`<img src="${url(dataUri, { schemes: ["data"] })}">`;    // allow a scheme for one value
+```
+<!-- deno-fmt-ignore-end -->
+## What is rejected
+<!-- deno-fmt-ignore-start -->
+```ts
+html`<a href=${u}>`;                       // HtmlTemplateError: unquoted attribute value
+html`<button onclick="${js}">`;            // HtmlTemplateError: slot in event-handler attribute
+html`<${tag}>`;                            // HtmlTemplateError: slot in tag name
+html`<a href="${base}${path}">`;           // HtmlTemplateError: URL slot must be alone (or continue with / ? #)
+html`<a href="http${s}://x">`;             // HtmlTemplateError: ambiguous scheme
+html`<a href="javascript:go('${id}')">`;   // HtmlTemplateError: static scheme not allowed
+html`<!-- ${note} -->`;                    // HtmlTemplateError: slot in comment
+html`<div class="x">${a}<b title="`;       // HtmlTemplateError: template ends inside a tag
+html`<svg><style>${styleText(css)}</style></svg>`; // HtmlTemplateError: not raw text inside SVG
+html`<script>let n = ${n};</script>`;      // HtmlValueError: script takes jsonScript()/scriptText()
+html`<p title="${html`<b>x</b>`}">`;       // HtmlValueError: html fragment in an attribute value
+html`<p>${new Date()}</p>`;                // HtmlValueError (and a type error)
+```
+<!-- deno-fmt-ignore-end -->
+Template errors depend only on the template, never on data, so rendering each template once in
+a test surfaces them all. Value errors depend on a value's _type_, never on string content:
+**a crafted string in your database can't turn a page into a 500**. Error messages never
+include values.
+## Safety
+**Guaranteed.** Given templates that pass analysis and no `unsafeRaw()`, no string value can:
+- create an element, attribute, comment or declaration;
+- close an element or attribute value that the template opened;
+- inject script through an event-handler attribute (those slots are rejected);
+- put a URL with a scheme outside the allowlist into a URL attribute (default: `http`,
+  `https`, `mailto`, `tel`), including through `srcset` or `attrs()`;
+- break out of `<script>`, `<style>`, `<title>` or `<textarea>` content;
+- change how SVG/MathML content parses.
+This is tested against [parse5](https://github.com/inikulin/parse5), a spec-compliant HTML
+parser: templates rendered with adversarial strings (XSS filter-evasion vectors plus seeded
+fuzzing) must parse to the same tree as with benign values.
+**Not guaranteed:**
+- CSS injection inside `style="…"` or `styleText()`. A value can't break out, but it can
+  restyle the page or load a `url(…)`. Build style values from validated tokens.
+- Semantic misuse: `<meta http-equiv="refresh" content="${x}">`, `<base href>` pointing at a
+  hostile `https:` host, open redirects, and `//host` protocol-relative URLs (relative, so
+  allowed).
+- Attributes that other code later treats as URLs or code: `data-src`, `data-href`, and
+  client-side frameworks that evaluate attributes or text (Alpine `x-*`, htmx `hx-on*`,
+  Vue/Angular template syntax in server-rendered markup). Don't interpolate data there.
+- DOM clobbering through data-controlled `id` or `name` values.
+- A slot inside a JavaScript string literal in a `<script>`. `jsonScript()` output must be
+  used as a whole JS expression.
+- URL component encoding: `href="/search?q=${q}"` is HTML-escaped, not
+  `encodeURIComponent`-ed. That is your job.
+- Anything passed through `unsafeRaw()` — it means _trusted_, never _cleaned_. This is **not an
+  HTML sanitizer**: to accept HTML from users, sanitize it elsewhere first.
+- Character encoding. Serve `content-type: text/html; charset=utf-8` and emit
+  `<meta charset="utf-8">`.
+The full rules are in [docs/design.md](docs/design.md).
+## URL policy
+The default exports use a default kit. Create your own for a different policy:
+```ts
+import { createHtml, DEFAULT_URL_SCHEMES } from "@marianmeres/safe-html";
+export const { html, attrs, url, srcset } = createHtml({
+	urlSchemes: [...DEFAULT_URL_SCHEMES, "sms"],
+	blockedUrl: "#blocked",
+	onBlockedUrl: ({ url, tag, attribute }) =>
+		log.warn("blocked URL", { tag, attribute }),
+});
+```
+## Porting from Svelte templates
+| Svelte                         | Here                                               |
+| ------------------------------ | -------------------------------------------------- |
+| `{expr}`                       | `${expr}`                                          |
+| `{#if c}A{:else}B{/if}`        | ``${c ? html`A` : html`B`}``                       |
+| `{#if c}A{/if}`                | ``${c && html`A`}`` (careful when `c` is a number) |
+| `{#each xs as x}…{/each}`      | ``${xs.map((x) => html`…`)}``                      |
+| `{#snippet row(x)}…{/snippet}` | `` const row = (x: T) => html`…` `` / `${row(x)}`  |
+| `<Card {...props} />`          | `${Card(props)}`                                   |
+| `<div {...rest}>`              | `<div ${attrs(rest)}>`                             |
+| `class:active={on}`            | `class="${on ? "active" : ""}"`                    |
+| `{@html jsonLd}` in `<script>` | `${jsonScript(data)}`                              |
+| `{@html css}` in `<style>`     | `${styleText(css)}`                                |
+| `{@html anythingElse}`         | `${unsafeRaw(s)}` (review every one)               |
+| `{#await}`                     | not supported; await the data before rendering     |
+## Notes
+- **Booleans render nothing, `true` included** (as in JSX). Numbers render, so
+  ``${count && html`…`}`` prints `0` for zero: write `count > 0 && …`.
+- An **untagged** template literal around a fragment (`` `<p>${frag}</p>` ``) makes a plain
+  string, which `html` escapes: visibly double-escaped, never an injection.
+- Every attribute value that contains a slot must be quoted.
+- `attrs()` output starts with a space. When an attribute appears both statically and in
+  `attrs()`, the first one in the tag wins (HTML parsing rules).
+- Whitespace is preserved exactly; nothing is minified.
+- **`deno fmt` formats the contents of `html`-tagged templates** (whitespace, `/>`, line
+  breaks), which changes your output. Add `// deno-fmt-ignore` above a statement (or
+  `// deno-fmt-ignore-file`) where exact output matters.
+- `unsafeRaw` is long and loud on purpose, so every use is greppable. A codebase can assert
+  in a test how many uses it has.
+## Performance
+Analysis runs once per call site and is cached. A render is one pass of concatenation plus
+escaping. Steady state on an Apple M2 (Deno 2.9, `deno task bench`):
+| Benchmark                 | hand-written concatenation + manual escaping | safe-html | ratio |
+| ------------------------- | -------------------------------------------- | --------- | ----- |
+| 1 000-row table           | 141 µs                                       | 264 µs    | ~1.9× |
+| small page (31 templates) | 2.7 µs                                       | 5.5 µs    | ~2.0× |
+The safe-html side does more work: every URL is scheme-checked and every fragment is a
+branded value.
+## API
+See [API.md](API.md) for the complete API.
+## License
+[MIT](LICENSE)

package/dist/errors.d.ts ADDED Viewed

@@ -0,0 +1,39 @@
+/**
+ * Errors. Messages never contain an interpolated value, so a thrown error can't leak data into
+ * logs. Template excerpts contain only static, developer-written text.
+ */
+import type { SlotContext } from "./types.js";
+/**
+ * A template the scanner refuses: a slot in a position that can never be made safe, markup the
+ * scanner does not model, or a call that is not a genuine tagged template. Depends on the
+ * template only, never on data, so rendering each template once in a test surfaces them all.
+ */
+export declare class HtmlTemplateError extends Error {
+    name: string;
+    /** Index of the offending slot, when the error is about a slot. */
+    readonly slot?: number;
+    /** The static template text, slots shown as `${…}`, the error position as `⟨here⟩`. */
+    readonly excerpt: string;
+    constructor(message: string, excerpt?: string, slot?: number);
+}
+/**
+ * A value that has no rendering in the context it was placed in (depends on the value's type or
+ * trusted kind), or an invalid attribute name / srcset descriptor (content that is expected to
+ * come from code).
+ */
+export declare class HtmlValueError extends TypeError {
+    name: string;
+    /** Index of the slot, when raised while rendering a template. */
+    readonly slot?: number;
+    /** Context of the slot, when raised while rendering a template or `join()`. */
+    readonly context?: SlotContext;
+    /** Type or trusted kind of the value, e.g. `"object"`, `"Promise"`, `"Trusted<html>"`. */
+    readonly received: string;
+    constructor(message: string, details: {
+        slot?: number;
+        context?: SlotContext;
+        received: string;
+    });
+}
+/** Describes a value by type or kind, never by content. */
+export declare function describe(v: unknown): string;

package/dist/errors.js ADDED Viewed

@@ -0,0 +1,63 @@
+/**
+ * A template the scanner refuses: a slot in a position that can never be made safe, markup the
+ * scanner does not model, or a call that is not a genuine tagged template. Depends on the
+ * template only, never on data, so rendering each template once in a test surfaces them all.
+ */
+export class HtmlTemplateError extends Error {
+    name = "HtmlTemplateError";
+    /** Index of the offending slot, when the error is about a slot. */
+    slot;
+    /** The static template text, slots shown as `${…}`, the error position as `⟨here⟩`. */
+    excerpt;
+    constructor(message, excerpt = "", slot) {
+        super(excerpt
+            ? `${message}\n    ${slot === undefined ? "in" : `slot ${slot} in`}: ${excerpt}`
+            : message);
+        this.excerpt = excerpt;
+        this.slot = slot;
+    }
+}
+/**
+ * A value that has no rendering in the context it was placed in (depends on the value's type or
+ * trusted kind), or an invalid attribute name / srcset descriptor (content that is expected to
+ * come from code).
+ */
+export class HtmlValueError extends TypeError {
+    name = "HtmlValueError";
+    /** Index of the slot, when raised while rendering a template. */
+    slot;
+    /** Context of the slot, when raised while rendering a template or `join()`. */
+    context;
+    /** Type or trusted kind of the value, e.g. `"object"`, `"Promise"`, `"Trusted<html>"`. */
+    received;
+    constructor(message, details) {
+        const where = [
+            details.slot !== undefined ? `slot ${details.slot}` : "",
+            details.context ? `context ${details.context}` : "",
+            `received ${details.received}`,
+        ].filter(Boolean).join(", ");
+        super(`${message} (${where})`);
+        this.slot = details.slot;
+        this.context = details.context;
+        this.received = details.received;
+    }
+}
+/** Describes a value by type or kind, never by content. */
+export function describe(v) {
+    if (v === null)
+        return "null";
+    const t = typeof v;
+    if (t !== "object")
+        return t;
+    // deno-lint-ignore no-explicit-any
+    const kind = v?.[Symbol.for("@marianmeres/safe-html/brand")] === true
+        // deno-lint-ignore no-explicit-any
+        ? v.kind
+        : undefined;
+    if (typeof kind === "string")
+        return `Trusted<${kind}>`;
+    if (Array.isArray(v))
+        return "array";
+    const tag = Object.prototype.toString.call(v).slice(8, -1);
+    return tag === "Object" ? "object" : tag;
+}

package/dist/escape.d.ts ADDED Viewed

@@ -0,0 +1,6 @@
+/**
+ * HTML escaping: correct in text, RCDATA, and double- or single-quoted attribute values.
+ * Not enough for unquoted values, which is why those are template errors.
+ */
+/** Escapes `& < > " '`. Returns the input unchanged when there is nothing to escape. */
+export declare function escapeHtml(value: string): string;

package/dist/escape.js ADDED Viewed

@@ -0,0 +1,40 @@
+/**
+ * HTML escaping: correct in text, RCDATA, and double- or single-quoted attribute values.
+ * Not enough for unquoted values, which is why those are template errors.
+ */
+const TEST = /[&<>"']/;
+/** Escapes `& < > " '`. Returns the input unchanged when there is nothing to escape. */
+export function escapeHtml(value) {
+    const s = typeof value === "string" ? value : String(value);
+    if (!TEST.test(s))
+        return s;
+    let out = "";
+    let last = 0;
+    for (let i = 0; i < s.length; i++) {
+        let rep;
+        switch (s.charCodeAt(i)) {
+            case 38: // &
+                rep = "&amp;";
+                break;
+            case 60: // <
+                rep = "&lt;";
+                break;
+            case 62: // >
+                rep = "&gt;";
+                break;
+            case 34: // "
+                rep = "&quot;";
+                break;
+            case 39: // '
+                rep = "&#39;";
+                break;
+            default:
+                continue;
+        }
+        if (last !== i)
+            out += s.slice(last, i);
+        out += rep;
+        last = i + 1;
+    }
+    return out + s.slice(last);
+}

package/dist/helpers.d.ts ADDED Viewed

@@ -0,0 +1,35 @@
+import type { Renderable, SafeHtml, Trusted } from "./types.js";
+/**
+ * `JSON.stringify(value, null, space)` made safe for `<script>` raw text: `<`, `>`, `&`,
+ * U+2028 and U+2029 become `\uXXXX` escapes. The result is valid JSON decoding to the same
+ * value, and a valid JavaScript expression. Accepted in `script` context only.
+ *
+ * Throws `HtmlValueError` when there is no JSON representation (a function, symbol or
+ * `undefined` at the root). `JSON.stringify`'s own errors (cycles, BigInt) propagate.
+ */
+export declare function jsonScript(value: unknown, space?: number): Trusted<"json">;
+/**
+ * Inline JavaScript that is code, not data. Every case-insensitive `</script` becomes
+ * `<\/script`, every `<!--` becomes `\x3C!--`, and a `<` that ends the source (alone or
+ * followed by the start of `/script` or `!--`) becomes `\x3C`, so the value can't complete
+ * those sequences with the static text after it. Accepted in `script` context only.
+ */
+export declare function scriptText(source: string): Trusted<"js">;
+/**
+ * Inline CSS. Every case-insensitive `</style` becomes `<\/style`, and a `<` that ends the
+ * source (alone or followed by the start of `/style`) becomes `\00003C`. Other `<` are kept
+ * (media-query ranges use them). Prevents breakout, not CSS injection. Accepted in `style`
+ * context only.
+ */
+export declare function styleText(source: string): Trusted<"css">;
+/**
+ * The escape hatch: inserted verbatim in any context, with no checks. Means *trusted*, never
+ * *cleaned*.
+ */
+export declare function unsafeRaw(value: string): Trusted<"unsafe">;
+/**
+ * Renders each value under the `text` rules, separated by `separator` (a string is escaped,
+ * `html` is inserted as is). `null`, `undefined` and booleans are skipped, so
+ * `join([a, cond && b], " · ")` leaves no stray separator.
+ */
+export declare function join(values: readonly Renderable[], separator?: string | SafeHtml): SafeHtml;

package/dist/helpers.js ADDED Viewed

@@ -0,0 +1,124 @@
+/**
+ * Policy-free helpers: jsonScript, scriptText, styleText, unsafeRaw, join.
+ */
+import { describe, HtmlValueError } from "./errors.js";
+import { escapeHtml } from "./escape.js";
+import { renderValue } from "./render.js";
+import { slotInfo } from "./scanner.js";
+import { isNeutral, isTrusted, makeTrusted, trustedString } from "./trusted.js";
+const JSON_ESCAPES = {
+    "<": "\\u003c",
+    ">": "\\u003e",
+    "&": "\\u0026",
+    "\u2028": "\\u2028",
+    "\u2029": "\\u2029",
+};
+/**
+ * `JSON.stringify(value, null, space)` made safe for `<script>` raw text: `<`, `>`, `&`,
+ * U+2028 and U+2029 become `\uXXXX` escapes. The result is valid JSON decoding to the same
+ * value, and a valid JavaScript expression. Accepted in `script` context only.
+ *
+ * Throws `HtmlValueError` when there is no JSON representation (a function, symbol or
+ * `undefined` at the root). `JSON.stringify`'s own errors (cycles, BigInt) propagate.
+ */
+export function jsonScript(value, space) {
+    if (space !== undefined && typeof space !== "number") {
+        throw new HtmlValueError("jsonScript(): space must be a number", {
+            received: describe(space),
+        });
+    }
+    const json = JSON.stringify(value, null, space);
+    if (json === undefined) {
+        throw new HtmlValueError("jsonScript(): the value has no JSON representation", {
+            received: describe(value),
+        });
+    }
+    return makeTrusted("json", json.replace(/[<>&\u2028\u2029]/g, (c) => JSON_ESCAPES[c]));
+}
+// "<" followed by a proper prefix of "/script" or "!--" at the very end
+const SCRIPT_TAIL = /<(?:\/(?:s(?:c(?:r(?:i(?:p)?)?)?)?)?|!-?)?$/i;
+// "<" followed by a proper prefix of "/style" at the very end
+const STYLE_TAIL = /<(?:\/(?:s(?:t(?:y(?:l)?)?)?)?)?$/i;
+/**
+ * Inline JavaScript that is code, not data. Every case-insensitive `</script` becomes
+ * `<\/script`, every `<!--` becomes `\x3C!--`, and a `<` that ends the source (alone or
+ * followed by the start of `/script` or `!--`) becomes `\x3C`, so the value can't complete
+ * those sequences with the static text after it. Accepted in `script` context only.
+ */
+export function scriptText(source) {
+    if (typeof source !== "string") {
+        throw new HtmlValueError("scriptText() takes a string", {
+            received: describe(source),
+        });
+    }
+    const s = source
+        .replace(/<\/(script)/gi, "<\\/$1")
+        .replace(/<!--/g, "\\x3C!--")
+        .replace(SCRIPT_TAIL, (m) => "\\x3C" + m.slice(1));
+    return makeTrusted("js", s);
+}
+/**
+ * Inline CSS. Every case-insensitive `</style` becomes `<\/style`, and a `<` that ends the
+ * source (alone or followed by the start of `/style`) becomes `\00003C`. Other `<` are kept
+ * (media-query ranges use them). Prevents breakout, not CSS injection. Accepted in `style`
+ * context only.
+ */
+export function styleText(source) {
+    if (typeof source !== "string") {
+        throw new HtmlValueError("styleText() takes a string", {
+            received: describe(source),
+        });
+    }
+    const s = source
+        .replace(/<\/(style)/gi, "<\\/$1")
+        .replace(STYLE_TAIL, (m) => "\\00003C" + m.slice(1));
+    return makeTrusted("css", s);
+}
+/**
+ * The escape hatch: inserted verbatim in any context, with no checks. Means *trusted*, never
+ * *cleaned*.
+ */
+export function unsafeRaw(value) {
+    if (typeof value !== "string") {
+        throw new HtmlValueError("unsafeRaw() takes a string", {
+            received: describe(value),
+        });
+    }
+    return makeTrusted("unsafe", value);
+}
+const TEXT_SLOT = slotInfo("text");
+/**
+ * Renders each value under the `text` rules, separated by `separator` (a string is escaped,
+ * `html` is inserted as is). `null`, `undefined` and booleans are skipped, so
+ * `join([a, cond && b], " · ")` leaves no stray separator.
+ */
+export function join(values, separator = "") {
+    if (!Array.isArray(values)) {
+        throw new HtmlValueError("join() takes an array", { received: describe(values) });
+    }
+    const st = { neutral: true };
+    let sep;
+    if (typeof separator === "string")
+        sep = escapeHtml(separator);
+    else if (isTrusted(separator, "html")) {
+        sep = trustedString(separator);
+        if (!isNeutral(separator))
+            st.neutral = false;
+    }
+    else {
+        throw new HtmlValueError("join(): the separator must be a string or html``", {
+            received: describe(separator),
+        });
+    }
+    let out = "";
+    let first = true;
+    for (let i = 0; i < values.length; i++) {
+        const v = values[i];
+        if (v === null || v === undefined || typeof v === "boolean")
+            continue;
+        const r = renderValue(v, TEXT_SLOT, undefined, undefined, st);
+        out += first ? r : sep + r;
+        first = false;
+    }
+    return makeTrusted("html", out, st.neutral);
+}

package/dist/kit.d.ts ADDED Viewed

@@ -0,0 +1,14 @@
+import type { HtmlKit, HtmlOptions } from "./types.js";
+/**
+ * Creates a kit whose `html`, `attrs`, `url` and `srcset` use the given URL policy.
+ * Throws `TypeError` on malformed options.
+ */
+export declare function createHtml(options?: HtmlOptions): HtmlKit;
+/** The template tag of the default kit. Every interpolated value is escaped for its context. */
+export declare const html: HtmlKit["html"];
+/** `attrs()` of the default kit. */
+export declare const attrs: HtmlKit["attrs"];
+/** `url()` of the default kit. */
+export declare const url: HtmlKit["url"];
+/** `srcset()` of the default kit. */
+export declare const srcset: HtmlKit["srcset"];