@reblu/site-blocks 0.2.2 → 0.3.0

package/dist/index.d.cts

@@ -34,24 +34,138 @@ declare function buildShareUrls(url: string, title: string): ShareUrls;
  * Blog `content` arrives as raw Markdown (tiptap-markdown). This module owns the
  * single, hardened conversion every SITE reuses instead of reinventing it:
  *
- *   Markdown ──(marked, GFM)──▶ HTML ──(DOMPurify)──▶ safe HTML
+ *   Markdown ──(marked, GFM)──▶ HTML ──(hast-util-sanitize)──▶ safe HTML
  *
- * DOMPurify is MANDATORY (XSS): the output is later parsed into React nodes by
- * `MarkdownRenderer` (no `dangerouslySetInnerHTML`), but sanitising here means the
- * string is safe regardless of how a consumer chooses to render it.
+ * Sanitisation is MANDATORY (XSS): the output is later parsed into React nodes by
+ * `MarkdownRenderer` (no `dangerouslySetInnerHTML`), but `sanitizeHtml` is also used
+ * directly against `dangerouslySetInnerHTML` for tenant-authored HTML — the nexus
+ * "HTML personalizado" editor (`apps/base-api/src/components/nexus/pages/page-editor/
+ * page-editor-form.tsx`) writes `page.customHtml`/`section.contentHtml`, rendered in
+ * `apps/demo-site/src/app/[slug]/page.tsx` and `apps/demo-site/src/app/services/
+ * [slug]/page.tsx` — so the string must be safe on its own regardless of how a
+ * consumer chooses to render it.
  *
- * `<iframe>` is the one non-default tag we allow, and ONLY when its `src` host is
- * on the YouTube allowlist — every other embed (arbitrary iframes) is dropped.
+ * SCOPE OF THE PARITY GUARANTEES BELOW. Everything this module says about preserving a
+ * tenant's `class`, `style`, `id`, `hidden`, `data-*` and `aria-*` is a guarantee about
+ * the STRING `sanitizeHtml` returns, and it reaches the page unchanged only on the
+ * `dangerouslySetInnerHTML` consumers listed above. `MarkdownRenderer` re-parses that
+ * string through `html-react-parser` into a token-styled component map
+ * (`markdown-renderer.tsx` `buildOptions`), and that map rebuilds most elements from
+ * scratch — so on the blog-body path author attributes are dropped downstream of this
+ * module regardless of what the schema allows. Widening the renderer's attribute
+ * forwarding is a separate change; do not read these comments as a claim about it.
+ *
+ * REB-606: this used to run on `isomorphic-dompurify`, which pulls `jsdom` into the
+ * import graph. `jsdom`'s transitive `html-encoding-sniffer` → `@exodus/bytes` chain
+ * is ESM-only and fails to load under Vercel's Node runtime (`ERR_REQUIRE_ESM`),
+ * producing a 500 on every route that renders tenant HTML.
+ *
+ * The replacement is deliberately assembled from the three `hast` utilities DIRECTLY
+ * (`parse5` → `hast-util-from-parse5` → `hast-util-sanitize` → `hast-util-to-html`)
+ * rather than through the `unified`/`rehype-*` plugin wrappers. `unified().processSync`
+ * builds a `VFile`, and `VFile`'s constructor calls `process.cwd()` through `vfile`'s
+ * `minproc`/`minpath`/`minurl` modules — which a bundler resolves under the **node**
+ * condition, so the bundle acquires bare `path`/`process`/`url` imports. That would
+ * reproduce REB-606's exact shape (a build-invisible, runtime-only module failure) in
+ * a different runtime: a SITE importing this framework-agnostic entry into a client
+ * component gets `Module not found: Can't resolve 'path'`, and an Edge route gets a
+ * `TypeError` the first time `sanitizeHtml` reaches `process.cwd`. The direct
+ * utilities never construct a `VFile`, so the emitted bundle has NO runtime import
+ * outside this package's declared dependencies. `packages/site-blocks/test/
+ * use-client-smoke.test.ts` pins that specifier set for both emitted entries — that
+ * assertion, not this comment, is what keeps it true.
+ *
+ * `hast-util-sanitize`'s own `defaultSchema` is GitHub's markdown-comment policy, which
+ * is meaningfully STRICTER than DOMPurify's unconfigured default (no `class`, no
+ * `style`, no `target`, structural tags like `figure`/`article`/`nav` missing, no
+ * `tel:` links, and it rewrites `id`/`name` to fight DOM clobbering). Swapping the
+ * library is not "behaviour preserving" if it also silently swaps the policy — a
+ * tenant's `customHtml` authored under the old, permissive DOMPurify default would
+ * lose styling, anchors, phone CTAs and structure on this deploy. `SANITIZE_SCHEMA`
+ * below restores DOMPurify's default HTML profile (see `dompurify/dist/purify.cjs.js`
+ * `html$1`/`html`/`IS_ALLOWED_URI`) for everything that carries **no new injection
+ * surface**, and it turns GitHub's `id`/`name` clobber-rewrite off (DOMPurify never did
+ * this, so leaving it on would break tenant anchor links that worked for the last
+ * month).
+ *
+ * It deliberately does NOT restore the parts of DOMPurify's default that ARE
+ * meaningfully riskier and have no evidenced use in this codebase: the `<style>`
+ * element, form controls (`form`/`input`/`button`/`select`/`textarea`/`label`/
+ * `fieldset`/`legend`/`option`/`optgroup`/`datalist`/`output`/`progress`/`meter`
+ * beyond the existing GFM task-list checkbox — phishing/UI-redress surface),
+ * `<script>`/`<template>`/`<object>`/`<embed>`/`<canvas>`, image maps (`map`/`area`),
+ * document/shadow-DOM plumbing (`html`/`head`/`body`/`slot`/`content`/`shadow`/
+ * `element`/`decorator`), the obsolete set (`dir`/`marquee`/`nobr`/`spacer`/`blink`/
+ * `menuitem`), `dialog`/`menu`/`search`, and the SVG/MathML namespaces (recurring
+ * source of real-world DOMPurify/sanitiser bypasses via `foreignObject`/namespace
+ * confusion). The changeset for this release enumerates every one of them.
+ *
+ * `<style>` specifically: it is not restored because a tenant-authored stylesheet
+ * applies to the WHOLE document, not just the injected fragment — attribute-selector
+ * rules like `input[value^="a"]{background:url(...)}` read and exfiltrate values from
+ * markup this sanitiser never saw. The `style` ATTRIBUTE is a different, narrower
+ * primitive (it can only style the element that carries it), it is part of DOMPurify's
+ * default that tenant `customHtml` has relied on for a month, and it is kept — see the
+ * changeset, which discloses that an inline `style` can still issue an outbound
+ * `url()` request. Closing that is a separate, deliberate decision (a CSS property
+ * allowlist) this bug-fix does not make.
+ *
+ * ARIA (`role` + the standard `aria-*` set, enumerated in `RESTORED_ARIA_ATTRIBUTES`
+ * below using `property-information`'s exact camelCase spellings — e.g.
+ * `ariaValueMax`, not `ariaValuemax`; hast-util-sanitize matches property names
+ * case-sensitively, so a naive hyphen-to-camelCase guess silently drops the
+ * attribute instead of erroring) is restored too — DOMPurify allows it by default
+ * (`ALLOW_ARIA_ATTR`) and losing it would be an accessibility regression on tenant
+ * content, not a security fix (see REB-286's axe gate). Custom `data-*` attributes
+ * (DOMPurify's `ALLOW_DATA_ATTR`) are restored via hast-util-sanitize's `'data*'`
+ * wildcard property name (`lib/index.js:758` in `hast-util-sanitize`) — they carry
+ * no URL/script/CSS interpretation, so allowing arbitrary values is safe.
+ *
+ * `srcset` is the one attribute this schema takes AWAY from DOMPurify's default, on
+ * purpose. `protocols` validates only the attribute's leading scheme
+ * (`hast-util-sanitize`'s `safeProtocol` looks at the text before the first
+ * `:`/`/`/`?`/`#`), but `srcset` is a comma-separated candidate list — so a value like
+ * `"https://ok.png 1x, //evil.tld/track.png 2x"` cannot be gated by this schema model
+ * at all. `defaultSchema` ships `source: ['srcSet']` and keeps `source`/`picture` in
+ * `tagNames`, which would leave `srcSet` on `<source>` as the ONLY completely ungated
+ * URL sink in the policy: not script execution (browsers do not run `javascript:` from
+ * an image source), but an arbitrary tenant-authored third-party request carrying a
+ * visitor's IP, UA and Referer. `RESTORED_MEDIA_ATTRIBUTES.source` replaces that list
+ * with protocol-gated `src` only.
+ *
+ * `<iframe>` is the one non-default TAG we allow, and ONLY when its `src` host is on
+ * the YouTube allowlist — every other embed (arbitrary iframes) is dropped.
+ *
+ * FOREIGN CONTENT (SVG/MathML) IS REMOVED BEFORE THE TREE IS EVEN BUILT, and that
+ * pre-pass is load-bearing for three separate reasons — see `dropForeignContent`.
+ * The policy above already said the SVG and MathML namespaces are not allowed; until
+ * this pass existed that was implemented by UNWRAPPING them, which is a different
+ * thing and got two of the three wrong.
  */
 /** Hosts permitted for `<iframe>` embeds. Exact host match — no suffix tricks. */
 declare const ALLOWED_YOUTUBE_HOSTS: readonly string[];
 /** True when `src` is an absolute URL whose host is exactly a YouTube host. */
 declare function isAllowedYouTubeHost(src: string | null | undefined): boolean;
 /**
- * Sanitise an already-HTML string with the same policy (default-safe tags plus a
- * host-gated `<iframe>`). Use for content that arrives as HTML — e.g. page
- * `section.contentHtml` from base-api, which is `marked` output that has NOT been
- * sanitised server-side.
+ * Sanitise an already-HTML string with the same policy (DOMPurify-default-equivalent
+ * tags/attributes plus a host-gated `<iframe>`). Use for content that arrives as
+ * HTML — e.g. page `section.contentHtml` from base-api, which is `marked` output
+ * that has NOT been sanitised server-side.
+ *
+ * WHAT A PARSE FAILURE DOES, AND WHY. Everything up to `fromParse5` runs BEFORE the
+ * sanitiser, so a throw there cannot be caught by anything downstream — and none of
+ * this module's callers catch anything at all. There are only two behaviours that keep
+ * the function's contract ("the returned string is safe to inject as HTML"):
+ * propagate, or return `''`. Propagating turns one malformed block inside one tenant's
+ * page into a 500 for the WHOLE route, which is the exact incident this module exists
+ * to end. So it fails closed: the block is dropped, the rest of the page renders, and
+ * the failure is reported through `console.error` so it is not silent — a dropped
+ * block with a log line is recoverable, a 500 is not. Returning the input, escaped or
+ * otherwise, is not an option: unparsed input is unsanitised input.
+ *
+ * This is a backstop, not the fix. The known crash class (foreign-content `<template>`)
+ * is removed structurally by `dropForeignContent`; this catch exists because
+ * `fromParse5` has already surprised us once.
  */
 declare function sanitizeHtml(html: string | null | undefined): string;
 /** Convert raw Markdown to sanitised, XSS-safe HTML. */
@@ -60,7 +174,7 @@ declare function markdownToSafeHtml(markdown: string | null | undefined): string
 /**
  * `MarkdownRenderer` — the canonical Blog body renderer.
  *
- * Pipeline: raw Markdown → `markdownToSafeHtml` (marked → DOMPurify, XSS-safe) →
+ * Pipeline: raw Markdown → `markdownToSafeHtml` (marked → hast-util-sanitize, XSS-safe) →
  * `html-react-parser` into a token-styled React tree. We parse the sanitised HTML
  * into real React nodes (a component map) rather than using
  * `dangerouslySetInnerHTML`, so images lazy-load, external links are hardened, and

package/dist/index.d.ts

@@ -34,24 +34,138 @@ declare function buildShareUrls(url: string, title: string): ShareUrls;
  * Blog `content` arrives as raw Markdown (tiptap-markdown). This module owns the
  * single, hardened conversion every SITE reuses instead of reinventing it:
  *
- *   Markdown ──(marked, GFM)──▶ HTML ──(DOMPurify)──▶ safe HTML
+ *   Markdown ──(marked, GFM)──▶ HTML ──(hast-util-sanitize)──▶ safe HTML
  *
- * DOMPurify is MANDATORY (XSS): the output is later parsed into React nodes by
- * `MarkdownRenderer` (no `dangerouslySetInnerHTML`), but sanitising here means the
- * string is safe regardless of how a consumer chooses to render it.
+ * Sanitisation is MANDATORY (XSS): the output is later parsed into React nodes by
+ * `MarkdownRenderer` (no `dangerouslySetInnerHTML`), but `sanitizeHtml` is also used
+ * directly against `dangerouslySetInnerHTML` for tenant-authored HTML — the nexus
+ * "HTML personalizado" editor (`apps/base-api/src/components/nexus/pages/page-editor/
+ * page-editor-form.tsx`) writes `page.customHtml`/`section.contentHtml`, rendered in
+ * `apps/demo-site/src/app/[slug]/page.tsx` and `apps/demo-site/src/app/services/
+ * [slug]/page.tsx` — so the string must be safe on its own regardless of how a
+ * consumer chooses to render it.
  *
- * `<iframe>` is the one non-default tag we allow, and ONLY when its `src` host is
- * on the YouTube allowlist — every other embed (arbitrary iframes) is dropped.
+ * SCOPE OF THE PARITY GUARANTEES BELOW. Everything this module says about preserving a
+ * tenant's `class`, `style`, `id`, `hidden`, `data-*` and `aria-*` is a guarantee about
+ * the STRING `sanitizeHtml` returns, and it reaches the page unchanged only on the
+ * `dangerouslySetInnerHTML` consumers listed above. `MarkdownRenderer` re-parses that
+ * string through `html-react-parser` into a token-styled component map
+ * (`markdown-renderer.tsx` `buildOptions`), and that map rebuilds most elements from
+ * scratch — so on the blog-body path author attributes are dropped downstream of this
+ * module regardless of what the schema allows. Widening the renderer's attribute
+ * forwarding is a separate change; do not read these comments as a claim about it.
+ *
+ * REB-606: this used to run on `isomorphic-dompurify`, which pulls `jsdom` into the
+ * import graph. `jsdom`'s transitive `html-encoding-sniffer` → `@exodus/bytes` chain
+ * is ESM-only and fails to load under Vercel's Node runtime (`ERR_REQUIRE_ESM`),
+ * producing a 500 on every route that renders tenant HTML.
+ *
+ * The replacement is deliberately assembled from the three `hast` utilities DIRECTLY
+ * (`parse5` → `hast-util-from-parse5` → `hast-util-sanitize` → `hast-util-to-html`)
+ * rather than through the `unified`/`rehype-*` plugin wrappers. `unified().processSync`
+ * builds a `VFile`, and `VFile`'s constructor calls `process.cwd()` through `vfile`'s
+ * `minproc`/`minpath`/`minurl` modules — which a bundler resolves under the **node**
+ * condition, so the bundle acquires bare `path`/`process`/`url` imports. That would
+ * reproduce REB-606's exact shape (a build-invisible, runtime-only module failure) in
+ * a different runtime: a SITE importing this framework-agnostic entry into a client
+ * component gets `Module not found: Can't resolve 'path'`, and an Edge route gets a
+ * `TypeError` the first time `sanitizeHtml` reaches `process.cwd`. The direct
+ * utilities never construct a `VFile`, so the emitted bundle has NO runtime import
+ * outside this package's declared dependencies. `packages/site-blocks/test/
+ * use-client-smoke.test.ts` pins that specifier set for both emitted entries — that
+ * assertion, not this comment, is what keeps it true.
+ *
+ * `hast-util-sanitize`'s own `defaultSchema` is GitHub's markdown-comment policy, which
+ * is meaningfully STRICTER than DOMPurify's unconfigured default (no `class`, no
+ * `style`, no `target`, structural tags like `figure`/`article`/`nav` missing, no
+ * `tel:` links, and it rewrites `id`/`name` to fight DOM clobbering). Swapping the
+ * library is not "behaviour preserving" if it also silently swaps the policy — a
+ * tenant's `customHtml` authored under the old, permissive DOMPurify default would
+ * lose styling, anchors, phone CTAs and structure on this deploy. `SANITIZE_SCHEMA`
+ * below restores DOMPurify's default HTML profile (see `dompurify/dist/purify.cjs.js`
+ * `html$1`/`html`/`IS_ALLOWED_URI`) for everything that carries **no new injection
+ * surface**, and it turns GitHub's `id`/`name` clobber-rewrite off (DOMPurify never did
+ * this, so leaving it on would break tenant anchor links that worked for the last
+ * month).
+ *
+ * It deliberately does NOT restore the parts of DOMPurify's default that ARE
+ * meaningfully riskier and have no evidenced use in this codebase: the `<style>`
+ * element, form controls (`form`/`input`/`button`/`select`/`textarea`/`label`/
+ * `fieldset`/`legend`/`option`/`optgroup`/`datalist`/`output`/`progress`/`meter`
+ * beyond the existing GFM task-list checkbox — phishing/UI-redress surface),
+ * `<script>`/`<template>`/`<object>`/`<embed>`/`<canvas>`, image maps (`map`/`area`),
+ * document/shadow-DOM plumbing (`html`/`head`/`body`/`slot`/`content`/`shadow`/
+ * `element`/`decorator`), the obsolete set (`dir`/`marquee`/`nobr`/`spacer`/`blink`/
+ * `menuitem`), `dialog`/`menu`/`search`, and the SVG/MathML namespaces (recurring
+ * source of real-world DOMPurify/sanitiser bypasses via `foreignObject`/namespace
+ * confusion). The changeset for this release enumerates every one of them.
+ *
+ * `<style>` specifically: it is not restored because a tenant-authored stylesheet
+ * applies to the WHOLE document, not just the injected fragment — attribute-selector
+ * rules like `input[value^="a"]{background:url(...)}` read and exfiltrate values from
+ * markup this sanitiser never saw. The `style` ATTRIBUTE is a different, narrower
+ * primitive (it can only style the element that carries it), it is part of DOMPurify's
+ * default that tenant `customHtml` has relied on for a month, and it is kept — see the
+ * changeset, which discloses that an inline `style` can still issue an outbound
+ * `url()` request. Closing that is a separate, deliberate decision (a CSS property
+ * allowlist) this bug-fix does not make.
+ *
+ * ARIA (`role` + the standard `aria-*` set, enumerated in `RESTORED_ARIA_ATTRIBUTES`
+ * below using `property-information`'s exact camelCase spellings — e.g.
+ * `ariaValueMax`, not `ariaValuemax`; hast-util-sanitize matches property names
+ * case-sensitively, so a naive hyphen-to-camelCase guess silently drops the
+ * attribute instead of erroring) is restored too — DOMPurify allows it by default
+ * (`ALLOW_ARIA_ATTR`) and losing it would be an accessibility regression on tenant
+ * content, not a security fix (see REB-286's axe gate). Custom `data-*` attributes
+ * (DOMPurify's `ALLOW_DATA_ATTR`) are restored via hast-util-sanitize's `'data*'`
+ * wildcard property name (`lib/index.js:758` in `hast-util-sanitize`) — they carry
+ * no URL/script/CSS interpretation, so allowing arbitrary values is safe.
+ *
+ * `srcset` is the one attribute this schema takes AWAY from DOMPurify's default, on
+ * purpose. `protocols` validates only the attribute's leading scheme
+ * (`hast-util-sanitize`'s `safeProtocol` looks at the text before the first
+ * `:`/`/`/`?`/`#`), but `srcset` is a comma-separated candidate list — so a value like
+ * `"https://ok.png 1x, //evil.tld/track.png 2x"` cannot be gated by this schema model
+ * at all. `defaultSchema` ships `source: ['srcSet']` and keeps `source`/`picture` in
+ * `tagNames`, which would leave `srcSet` on `<source>` as the ONLY completely ungated
+ * URL sink in the policy: not script execution (browsers do not run `javascript:` from
+ * an image source), but an arbitrary tenant-authored third-party request carrying a
+ * visitor's IP, UA and Referer. `RESTORED_MEDIA_ATTRIBUTES.source` replaces that list
+ * with protocol-gated `src` only.
+ *
+ * `<iframe>` is the one non-default TAG we allow, and ONLY when its `src` host is on
+ * the YouTube allowlist — every other embed (arbitrary iframes) is dropped.
+ *
+ * FOREIGN CONTENT (SVG/MathML) IS REMOVED BEFORE THE TREE IS EVEN BUILT, and that
+ * pre-pass is load-bearing for three separate reasons — see `dropForeignContent`.
+ * The policy above already said the SVG and MathML namespaces are not allowed; until
+ * this pass existed that was implemented by UNWRAPPING them, which is a different
+ * thing and got two of the three wrong.
  */
 /** Hosts permitted for `<iframe>` embeds. Exact host match — no suffix tricks. */
 declare const ALLOWED_YOUTUBE_HOSTS: readonly string[];
 /** True when `src` is an absolute URL whose host is exactly a YouTube host. */
 declare function isAllowedYouTubeHost(src: string | null | undefined): boolean;
 /**
- * Sanitise an already-HTML string with the same policy (default-safe tags plus a
- * host-gated `<iframe>`). Use for content that arrives as HTML — e.g. page
- * `section.contentHtml` from base-api, which is `marked` output that has NOT been
- * sanitised server-side.
+ * Sanitise an already-HTML string with the same policy (DOMPurify-default-equivalent
+ * tags/attributes plus a host-gated `<iframe>`). Use for content that arrives as
+ * HTML — e.g. page `section.contentHtml` from base-api, which is `marked` output
+ * that has NOT been sanitised server-side.
+ *
+ * WHAT A PARSE FAILURE DOES, AND WHY. Everything up to `fromParse5` runs BEFORE the
+ * sanitiser, so a throw there cannot be caught by anything downstream — and none of
+ * this module's callers catch anything at all. There are only two behaviours that keep
+ * the function's contract ("the returned string is safe to inject as HTML"):
+ * propagate, or return `''`. Propagating turns one malformed block inside one tenant's
+ * page into a 500 for the WHOLE route, which is the exact incident this module exists
+ * to end. So it fails closed: the block is dropped, the rest of the page renders, and
+ * the failure is reported through `console.error` so it is not silent — a dropped
+ * block with a log line is recoverable, a 500 is not. Returning the input, escaped or
+ * otherwise, is not an option: unparsed input is unsanitised input.
+ *
+ * This is a backstop, not the fix. The known crash class (foreign-content `<template>`)
+ * is removed structurally by `dropForeignContent`; this catch exists because
+ * `fromParse5` has already surprised us once.
  */
 declare function sanitizeHtml(html: string | null | undefined): string;
 /** Convert raw Markdown to sanitised, XSS-safe HTML. */
@@ -60,7 +174,7 @@ declare function markdownToSafeHtml(markdown: string | null | undefined): string
 /**
  * `MarkdownRenderer` — the canonical Blog body renderer.
  *
- * Pipeline: raw Markdown → `markdownToSafeHtml` (marked → DOMPurify, XSS-safe) →
+ * Pipeline: raw Markdown → `markdownToSafeHtml` (marked → hast-util-sanitize, XSS-safe) →
  * `html-react-parser` into a token-styled React tree. We parse the sanitised HTML
  * into real React nodes (a component map) rather than using
  * `dangerouslySetInnerHTML`, so images lazy-load, external links are hardened, and