flux-md 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -4,6 +4,44 @@ Notable changes to flux-md. Format based on
 [Keep a Changelog](https://keepachangelog.com/); this project aims to follow
 [Semantic Versioning](https://semver.org/).
 
+## 0.15.0 — 2026-06-17
+
+### Added
+
+- **Safe raw-HTML sanitizer (`htmlAllowlist` / `dropHtmlTags`)** — render a safe
+  subset of *inline* raw HTML (`<br>`, `<sub>`, `<sup>`, `<mark>`, …) **without**
+  `unsafeHtml`. Setting either list (even to `[]`) engages it: `htmlAllowlist`
+  non-empty renders only those tags (others escaped); **empty allows all tags
+  except a built-in, non-overridable dangerous set** (`script`, `style`,
+  `iframe`, `object`, `embed`, `form`, `svg`, `xmp`, `plaintext`, …);
+  `dropHtmlTags` removes tags entirely. Every rendered tag's attributes are
+  sanitized — `on*` handlers and `style` (a CSS beacon / clickjacking vector)
+  dropped, dangerous URL schemes (incl. multi-encoded) → `#`. Inline-scoped;
+  block-level raw HTML stays escaped. Matching is case-insensitive.
+
+### Fixed
+
+- **HTML comments are dropped instead of escaped to visible text.** `<!--mk:id-->`
+  (a common LLM marker) previously rendered as a literal `&lt;!--…--&gt;` run or a
+  `<pre><code>` block; it now has no visible representation, in every mode except
+  bare `unsafeHtml` pass-through (which keeps it verbatim for CommonMark fidelity —
+  the browser ignores it either way). A comment-led block with trailing content
+  keeps that content (only comment-*only* blocks are dropped).
+
+### Security
+
+- The dangerous-tag set is **non-overridable** (allowlisting `script`/`iframe`/`svg`
+  still drops them), `style` is stripped from every sanitized/component tag, and
+  raw-text elements (`xmp`/`plaintext`/`noembed`/`noframes`/`listing`) are blocked
+  in allow-all mode — closing CSS-exfiltration / clickjacking / DOM-corruption
+  vectors found in adversarial review. The React `htmlToReact` path mirrors the
+  `style` value-filter as defense-in-depth (safe declarations like `text-align`
+  still pass).
+
+Feature-off output is byte-identical except HTML comments now drop (the
+CommonMark/GFM suites run with `unsafeHtml` on, so the 652/GFM floors are
+unaffected).
+
 ## 0.14.0 — 2026-06-17
 
 ### Added

package/README.md

@@ -558,6 +558,8 @@ const client = new FluxClient({
     unsafeHtml: false,    // pass raw HTML through (default false — keep it false for untrusted input)
     componentTags: ["Thinking", "Callout"], // BLOCK custom tags w/ markdown inside (default none)
     inlineComponentTags: ["tik", "cite"],   // INLINE custom tags (chips/citations) w/ markdown inside (default none)
+    htmlAllowlist: ["br", "sub", "sup"],    // safe raw-HTML sanitizer: [] = allow all but dangerous; list = only those (default off)
+    dropHtmlTags: [],                        // tags removed entirely (comments always dropped when sanitizing; default off)
     blockData: true,      // opt-in structured kind.data per block (default false — see "Structured block data")
   },
 });
@@ -592,6 +594,9 @@ When to enable each flag:
 - `inlineComponentTags: ["tik", …]` — same idea for **inline** custom elements
   that sit inside a paragraph, heading, list item, or **table cell** (ticker
   chips, citations, `@mentions`). See [Inline component tags](#inline-component-tags).
+- `htmlAllowlist` / `dropHtmlTags` — render a **safe subset of raw HTML** (e.g.
+  `<br>`, `<sub>`, `<sup>`) natively without `unsafeHtml`, drop specific tags, and
+  drop HTML comments. See [Safe raw HTML](#safe-raw-html).
 
 **Footnotes** (`gfmFootnotes`) work in streaming with one honest caveat: a
 `[^1]` reference renders speculatively the moment it's seen (committed blocks
@@ -826,6 +831,37 @@ surrounding content.
 > renders inline-in-cells too — `inlineComponentTags` simply replaces that
 > workaround with first-class inline elements.
 
+### Safe raw HTML
+
+LLMs emit a little raw HTML — `<br>`, `<sub>`/`<sup>`, `<mark>`, and HTML comments
+as markers (`<!--mk:id-->`). `unsafeHtml` is all-or-nothing; instead opt into a
+**sanitizer** that renders a safe subset natively. Setting `htmlAllowlist` and/or
+`dropHtmlTags` (even to `[]`) engages it:
+
+```ts
+// Render only these inline tags; escape everything else:
+new FluxClient({ config: { htmlAllowlist: ["br", "sub", "sup", "mark"] } });
+
+// Or allow everything except a built-in dangerous set:
+new FluxClient({ config: { htmlAllowlist: [] } });
+```
+
+- **HTML comments are dropped** — no more `<!--mk:id-->` surfacing as escaped text
+  — in every mode except bare `unsafeHtml` pass-through.
+- **`htmlAllowlist: ["br", …]`** renders only those inline tags; everything else is
+  escaped. **`htmlAllowlist: []`** (empty) allows *all* tags **except a built-in
+  dangerous set** (`script`, `style`, `iframe`, `object`, `embed`, `form`, `svg`,
+  `xmp`, `plaintext`, … — **non-overridable**: allowlisting one still drops it).
+- **`dropHtmlTags: ["mk", …]`** removes those tags entirely (markup gone; inner
+  text stays as inert text).
+- Every rendered tag's **attributes are sanitized**: `on*` handlers and `style`
+  (a CSS beacon / clickjacking vector) are dropped, and dangerous URL schemes
+  (`javascript:`, …, including multi-encoded) become `#`.
+- **Scope:** *inline* raw HTML. Block-level raw HTML stays escaped for now (use
+  `unsafeHtml` **without** the sanitizer to render block HTML — when the sanitizer
+  is engaged, block HTML stays escaped even if `unsafeHtml` is also on). Tag
+  matching is case-insensitive.
+
 ### Types
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flux-md",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Zero-dep streaming markdown for the browser. Rust→WASM core, Web Worker per stream, incremental parse with speculative closure.",
   "type": "module",
   "sideEffects": ["./src/worker.ts", "./src/styles.css"],

package/src/html-to-react.ts

@@ -110,6 +110,27 @@ export function parseStyle(css: string): Record<string, string> {
   return out;
 }
 
+// CSS values that beacon/exfiltrate (`url(`), execute (legacy `expression(`,
+// `-moz-binding`, `behavior:`), or pull external resources (`@import`,
+// `image-set(`). Defense-in-depth: the core sanitizer already drops `style`, but
+// `htmlToReact` is exported and may be handed untrusted HTML directly.
+const DANGEROUS_CSS_VALUE = /url\(|expression\(|image-set\(|-moz-binding|@import|behavior\s*:/i;
+
+/** Strip CSS declarations that can beacon/exfiltrate, execute, or overlay the
+ *  viewport (`position: fixed/sticky` → clickjacking). Safe declarations
+ *  (`text-align`, `color`, …) — including flux's own table-alignment style —
+ *  pass through untouched. */
+function safeStyle(style: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const k in style) {
+    const v = style[k];
+    if (DANGEROUS_CSS_VALUE.test(v)) continue;
+    if (k.toLowerCase() === "position" && /\b(?:fixed|sticky)\b/i.test(v)) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
 /** Parse one opening tag starting at `start` (the `<`). */
 function parseOpenTag(html: string, start: number) {
   let i = start + 1;
@@ -245,7 +266,7 @@ function attrsToProps(tag: string, attrs: Record<string, string | true>, key: st
     // future React behavior.
     if (lower.startsWith("on")) continue;
     if (lower === "style" && typeof value === "string") {
-      props.style = parseStyle(value);
+      props.style = safeStyle(parseStyle(value));
       continue;
     }
     // Neutralize dangerous-scheme URLs (javascript:, vbscript:, data:text/html).

package/src/server.tsx

@@ -87,6 +87,12 @@ function makeParser(config?: ParserConfig): FluxParser {
   p.setUnsafeHtml(config?.unsafeHtml ?? false);
   p.setComponentTags(config?.componentTags ?? []);
   p.setInlineComponentTags(config?.inlineComponentTags ?? []);
+  // Engage the safe raw-HTML sanitizer when either list is provided (even []).
+  p.setHtmlSanitize(
+    config?.htmlAllowlist !== undefined || config?.dropHtmlTags !== undefined,
+    config?.htmlAllowlist ?? [],
+    config?.dropHtmlTags ?? [],
+  );
   p.setBlockData(config?.blockData ?? false);
   return p;
 }

package/src/types-core.ts

@@ -261,6 +261,26 @@ export interface ParserConfig {
    * `componentTags`. Empty/omitted = off.
    */
   inlineComponentTags?: string[];
+  /**
+   * Opt-in **safe raw-HTML allowlist**. Setting this (even to `[]`) engages a
+   * sanitizer that renders a safe subset of *inline* raw HTML **without**
+   * `unsafeHtml`: an **empty** array means "allow all tags except a built-in
+   * dangerous set" (`script`, `style`, `iframe`, `object`, `embed`, `form`,
+   * `input`, `svg`, …); a **non-empty** array renders only those tags (e.g.
+   * `["br","sub","sup"]`) and escapes the rest. Every rendered tag's attributes
+   * are sanitized (event handlers dropped, dangerous URL schemes → `#`), and HTML
+   * comments are dropped. Block-level raw HTML stays escaped (sanitize is
+   * inline-scoped for now). Unset/omitted = off (raw HTML handling unchanged).
+   * Matching is case-insensitive. See also {@link dropHtmlTags}.
+   */
+  htmlAllowlist?: string[];
+  /**
+   * Tags removed entirely (markup dropped; any text between an open/close pair
+   * stays as inert text) — e.g. app marker tags, or belt-and-suspenders
+   * `["script","style"]`. Setting this (even to `[]`) also engages the safe
+   * raw-HTML sanitizer (see {@link htmlAllowlist}). Case-insensitive.
+   */
+  dropHtmlTags?: string[];
   /**
    * Opt-in structured table data. When on, a `Table` block's `kind.data` is
    * populated with `{ headers, rows, aligns }` (each cell `{ text, html }`) so a

package/src/wasm/flux_md_core.d.ts

@@ -71,6 +71,15 @@ export class FluxParser {
      * `<div class="math math-display">` for a KaTeX pass on the JS side.
      */
     setGfmMath(on: boolean): void;
+    /**
+     * Engage the safe raw-HTML sanitizer. When `on`, inline raw HTML renders
+     * sanitized without full unsafe HTML: `allow` empty = allow all tags except
+     * a built-in dangerous set (`script`, `style`, `iframe`, …); `allow`
+     * non-empty = only those render (others escaped); `drop` tags are removed
+     * entirely; HTML comments are dropped; every rendered tag's attributes are
+     * sanitized. Off by default (raw-HTML handling unchanged).
+     */
+    setHtmlSanitize(on: boolean, allow: string[], drop: string[]): void;
     /**
      * Set the opt-in INLINE component-tag allowlist (e.g. `["tik", "cite"]`).
      * An allowlisted inline `<tik>…</tik>` (or self-closing `<tik/>`) renders as
@@ -105,6 +114,7 @@ export interface InitOutput {
     readonly fluxparser_setGfmAutolinks: (a: number, b: number) => void;
     readonly fluxparser_setGfmFootnotes: (a: number, b: number) => void;
     readonly fluxparser_setGfmMath: (a: number, b: number) => void;
+    readonly fluxparser_setHtmlSanitize: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
     readonly fluxparser_setInlineComponentTags: (a: number, b: number, c: number) => void;
     readonly fluxparser_setUnsafeHtml: (a: number, b: number) => void;
     readonly __wbindgen_export: (a: number, b: number) => number;

package/src/wasm/flux_md_core.js

@@ -171,6 +171,24 @@ export class FluxParser {
     setGfmMath(on) {
         wasm.fluxparser_setGfmMath(this.__wbg_ptr, on);
     }
+    /**
+     * Engage the safe raw-HTML sanitizer. When `on`, inline raw HTML renders
+     * sanitized without full unsafe HTML: `allow` empty = allow all tags except
+     * a built-in dangerous set (`script`, `style`, `iframe`, …); `allow`
+     * non-empty = only those render (others escaped); `drop` tags are removed
+     * entirely; HTML comments are dropped; every rendered tag's attributes are
+     * sanitized. Off by default (raw-HTML handling unchanged).
+     * @param {boolean} on
+     * @param {string[]} allow
+     * @param {string[]} drop
+     */
+    setHtmlSanitize(on, allow, drop) {
+        const ptr0 = passArrayJsValueToWasm0(allow, wasm.__wbindgen_export);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passArrayJsValueToWasm0(drop, wasm.__wbindgen_export);
+        const len1 = WASM_VECTOR_LEN;
+        wasm.fluxparser_setHtmlSanitize(this.__wbg_ptr, on, ptr0, len0, ptr1, len1);
+    }
     /**
      * Set the opt-in INLINE component-tag allowlist (e.g. `["tik", "cite"]`).
      * An allowlisted inline `<tik>…</tik>` (or self-closing `<tik/>`) renders as

package/src/wasm/flux_md_core_bg.wasm.d.ts

@@ -16,6 +16,7 @@ export const fluxparser_setGfmAlerts: (a: number, b: number) => void;
 export const fluxparser_setGfmAutolinks: (a: number, b: number) => void;
 export const fluxparser_setGfmFootnotes: (a: number, b: number) => void;
 export const fluxparser_setGfmMath: (a: number, b: number) => void;
+export const fluxparser_setHtmlSanitize: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
 export const fluxparser_setInlineComponentTags: (a: number, b: number, c: number) => void;
 export const fluxparser_setUnsafeHtml: (a: number, b: number) => void;
 export const __wbindgen_export: (a: number, b: number) => number;

package/src/wasm/package.json

@@ -2,7 +2,7 @@
   "name": "flux-md-core",
   "type": "module",
   "description": "Incremental, streaming-aware markdown parser with speculative closure",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "license": "MIT",
   "files": [
     "flux_md_core_bg.wasm",

package/src/worker.ts

@@ -31,6 +31,12 @@ const core = new WorkerCore({
     p.setUnsafeHtml(c?.unsafeHtml ?? false);
     p.setComponentTags(c?.componentTags ?? []);
     p.setInlineComponentTags(c?.inlineComponentTags ?? []);
+    // Engage the safe raw-HTML sanitizer when either list is provided (even []).
+    p.setHtmlSanitize(
+      c?.htmlAllowlist !== undefined || c?.dropHtmlTags !== undefined,
+      c?.htmlAllowlist ?? [],
+      c?.dropHtmlTags ?? [],
+    );
     p.setBlockData(c?.blockData ?? false);
     return p;
   },