@reblu/site-blocks 0.2.3 → 0.3.1

package/README.md

@@ -13,7 +13,8 @@ a different-looking site for every tenant, with zero forks.
 | Export | Entry | Purpose |
 | ------ | ----- | ------- |
 | `readingTime`, `formatPrice`, `buildShareUrls`, `markdownToSafeHtml` | `.` | Pure, framework-agnostic helpers (RSC-safe). |
-| `MarkdownRenderer` | `.` | Canonical Blog renderer: `marked` → **DOMPurify** (XSS) → component map, with a YouTube-domain allowlist. RSC-safe. |
+| `sanitizeHtml` | `.` | Sanitises an HTML string before `dangerouslySetInnerHTML` — the **HTML boundary**. See "Security boundaries" below. |
+| `MarkdownRenderer` | `.` | Canonical Blog renderer: `marked` → **hast-util-sanitize** (XSS) → component map, with a YouTube-domain allowlist. RSC-safe. |
 | `Treatment`, `Specialty`, `ProfileCard`, `ProductCard` | `.` | Presentational organisms over the SITE API contracts. RSC-safe. |
 | `useCollection` | `./client` | Headless filterable/sortable/paginated collection hook (facets, category, tag, search). Serves both page and blog indexes. |
 | `Collection` | `./client` | Token-driven presentational grid over `useCollection`. |
@@ -25,5 +26,25 @@ a different-looking site for every tenant, with zero forks.
 - **`@reblu/site-blocks`** = organisms + headless data hooks. Higher churn — its
   own package so a breaking change in an organism does not bump the stable atoms.
 
+## Security boundaries
+
+Two sinks, two different helpers, in two different packages — do not reach for
+one where the other belongs:
+
+| Sink | Helper | Package |
+| ---- | ------ | ------- |
+| HTML rendered via `dangerouslySetInnerHTML` | `sanitizeHtml` (strip/allowlist sanitiser) | `@reblu/site-blocks` (here) |
+| `<script type="application/ld+json">` body | `jsonLdScriptContent` / `<JsonLd>` (escaper) | [`@reblu/site-next/json-ld`](../site-next#structured-data-json-ld) |
+
+A `<script>` body is HTML's **raw-text** context: the parser ends it on the
+first `</script` byte sequence regardless of whether that sequence sits inside
+a JSON string, so `JSON.stringify`-ing tenant data straight into a JSON-LD
+`<script>` is a stored-XSS sink `sanitizeHtml` does not cover (it sanitises
+markup, not JSON). `jsonLdScriptContent` lives in `@reblu/site-next` rather
+than here: it has zero dependencies of its own, and this package's main entry
+bundles `parse5` + the `hast-util-*` chain + `marked` for `sanitizeHtml`
+(`treeshake: false`, ~463 KB unminified) — importing the escaper from here
+would drag that parser chain behind a 40-line function.
+
 Types come from [`@reblu/site-contracts`](../site-contracts) (the SDK view of the
 `/api/site/*` responses). No Zod and no Prisma reach the consumer runtime.