html-preview-sandbox 0.1.0

package/docs/PROJECT_STRUCTURE.md

@@ -0,0 +1,121 @@
+# Project Structure
+
+This repository is a single-package TypeScript project. The package publishes a Node/default build and a browser build from the same core pipeline.
+
+## Top-Level Layout
+
+```text
+html-preview-sandbox/
+  src/                 TypeScript source for the package
+  dist/                Generated build output, ignored by git
+  playground/          Local inspection workbench
+  examples/            Minimal host integration examples
+  fixtures/            Benign, malicious, and edge HTML inputs
+  test/                Node and browser regression tests
+  docs/                Architecture, security, and integration notes
+  .github/workflows/   CI checks
+```
+
+## Source Modules
+
+```text
+src/index.ts           Node/default package entry
+src/index.browser.ts   Browser package entry
+src/types.ts           Public API types
+src/decode.ts          Input normalization and charset handling
+src/sanitize.ts        Node DOMPurify + jsdom sanitizer entry
+src/sanitize.browser.ts Browser DOMPurify sanitizer entry
+src/sanitize-core.ts   Shared sanitizer policy and reporting hooks
+src/policy.ts          CSP, sandbox, and external URL policies
+src/bridge.ts          Injected iframe bridge script
+src/document.ts        Node document assembly pipeline
+src/document.browser.ts Browser document assembly pipeline
+src/renderer-core.ts   Shared renderer factory (iframe lifecycle, bridge, nav)
+src/renderer.ts        Default renderer export (injects Node document pipeline)
+src/renderer.browser.ts Browser renderer export (injects browser document pipeline)
+src/scrollbar.ts       Optional scrollbar style injection
+src/errors.ts          Error codes and PreviewError
+```
+
+The public package surface is exported through `src/index.ts` and `src/index.browser.ts`. Keep new public APIs in `src/types.ts` and export them from both entrypoints when they apply to both runtimes.
+
+## Runtime Flow
+
+```text
+PreviewInput
+  -> normalizeInput()
+  -> sanitizeHtml()
+  -> buildCsp()
+  -> injectCspMeta()
+  -> injectBridgeScript()
+  -> injectScrollbarStyle()
+  -> iframe.srcdoc
+```
+
+Browser hosts usually call `createPreview()`. Node usage should call `createHtmlDocument()` or lower-level helpers.
+
+## Build Outputs
+
+`npm run build` runs two steps: `tsup` bundles the ESM JavaScript, then `tsc`
+emits the type declarations (tsup's dts pass is disabled because it injects a
+deprecated `baseUrl` that TypeScript 6 rejects). It generates:
+
+```text
+dist/index.js            (tsup, Node/default)
+dist/index.browser.js    (tsup, browser)
+dist/*.d.ts              (tsc, per-module declarations; index.d.ts is the public entry)
+dist/*.map
+```
+
+Consumers reach the API through the `.` and `./browser` export conditions; the
+per-module `.d.ts` files support the type graph but are not deep-importable by
+package name.
+
+Tests and local examples intentionally run against `dist` after build. This keeps development checks close to the published package behavior.
+
+## Test Layers
+
+- `test/*.test.js`: Node tests for decoding, CSP, sanitizer behavior, package metadata, and document assembly.
+- `test/browser/*.spec.js`: Playwright tests for browser iframe behavior, bridge forwarding, host navigation handling, external URL policy, and the example/Playground UIs (file upload, Web Component, sanitized-HTML view, shareable URL, drag-and-drop).
+- `fixtures/`: stable inputs for benign, malicious, and edge cases.
+
+## Local Workbench
+
+The Playground is a repository tool, not a published runtime API. It runs against `dist/index.browser.js` and exposes:
+
+- sample payloads;
+- drag-and-drop of a local HTML file into the editor;
+- CSP preset switching;
+- external protocol controls;
+- host suffix URL filtering;
+- sanitizer removal reports;
+- CSP violation reports;
+- external request reports;
+- current policy summary;
+- a "sanitized HTML" view of the exact pipeline output;
+- a shareable URL that encodes the input + preset.
+
+Run it with:
+
+```bash
+npm run build
+npm run serve
+```
+
+Then open `http://localhost:4173/playground/`.
+
+## Publishing Shape
+
+The npm package is intentionally small:
+
+```text
+dist/
+docs/
+README.md
+LICENSE
+THREAT_MODEL.md
+SECURITY.md
+CHANGELOG.md
+```
+
+Examples, fixtures, tests, and Playground stay in the repository for development and review, but they are not included in the package tarball.

package/docs/ROADMAP.md

@@ -0,0 +1,184 @@
+# Roadmap
+
+This document tracks what remains before the project is ready for a stronger public v0.1 release.
+
+## Current State
+
+Implemented:
+
+- single-package TypeScript source;
+- generated ESM Node/default build;
+- generated ESM browser build;
+- generated TypeScript declarations;
+- DOMPurify-backed sanitizer in browser and Node;
+- CSP presets;
+- sandboxed iframe renderer;
+- injected bridge for link, `window.open`, and CSP violation events;
+- external protocol and custom URL policy;
+- high-risk sandbox token filtering;
+- local Playground inspection workbench;
+- Node tests, Playwright tests, CI, audit script, and pack dry-run;
+- Biome linting (gated in CI) and formatter config.
+
+## Housekeeping
+
+- **One-time Biome format pass.** The formatter is configured (`biome.json`) and
+  available via `npm run format`, but existing files have not been reformatted, to
+  keep substantive diffs clean. Apply `biome format --write` in a dedicated
+  `chore: apply Biome formatting` commit (no logic changes). Only after that pass,
+  (re)add a `format:check` script (`biome format .`) and gate it in CI — it is
+  intentionally omitted now so no shipped script fails against the un-formatted tree.
+
+## Priority 0
+
+All three P0 items are done. The package is TypeScript-strict, has broad security
+fixture coverage, and documents its browser baseline.
+
+1. **Tighten TypeScript strictness** — Done. `strict: true` in both `tsconfig.json`
+   and `tsconfig.check.json`; DOMPurify hook parameters are typed, caught errors are
+   normalized to `PreviewErrorShape`, and the suite passes under strict. The `jsdom`
+   module shim and the `any`-typed DOMPurify factory remain as small, deliberate
+   boundaries; replacing them with precise upstream types is a follow-up nicety, not
+   a blocker.
+
+2. **Expand security fixture coverage** — Done. Fixtures + regression tests now cover:
+   `base` tag injection, URL-targeting SVG animation, mXSS mutation vectors,
+   `formaction` override, nested `iframe`/`srcdoc`, obfuscated (entity/whitespace/case)
+   `javascript:` schemes, irregular `srcset` whitespace/descriptors, CSS `url()`
+   exfiltration (layered sanitize + CSP assertion), plus GBK/non-UTF-8 decoding, empty,
+   and malformed HTML edge cases.
+
+3. **Document browser compatibility** — Done. See [BROWSER_SUPPORT.md](BROWSER_SUPPORT.md):
+   baseline (Chrome/Edge 90+, Firefox 90+, Safari 14+, Electron 12+, Node 18+) with the
+   binding constraint (`Blob.arrayBuffer`) and the full list of platform features used.
+
+## Priority 1
+
+These improve adoption and maintainability.
+
+1. **Integration examples**
+
+   Keep the package single-package, with repository examples:
+
+   - Done: string input (`examples/web/`).
+   - Done: File/Blob input via `<input type=file>` + drag & drop, with encoding /
+     sanitize-report / `OVERSIZED` error display (`examples/file-upload/`, covered by
+     Playwright smoke tests). Covers the attachment / upload / netdisk shape.
+   - Done: vanilla Web Component wrapper (`examples/web-component/`, smoke-tested).
+   - Done: Electron host navigation interception (`examples/electron/`, reference
+     code — runs with a separately installed `electron`).
+   - Done: Node `createHtmlDocument` (full pipeline, no iframe) for self-managed
+     webviews / SSR / CLI (`examples/node-create-document/`).
+   - Deferred: React/Vue examples (need a build step; Web Component already covers
+     the framework-agnostic entry) and a multiple-previews-per-page snippet. Low
+     priority — these are capability showcases, not core adoption entry points.
+
+2. **Improve CI signal**
+
+   Done: Dependabot (`.github/dependabot.yml`) and CodeQL static analysis
+   (`.github/workflows/codeql.yml`). The main CI workflow already runs a
+   `pack:dry` job.
+
+   Still to add:
+
+   - browser matrix expansion (Firefox/WebKit) once the compatibility target is
+     confirmed and those engines are verified to pass.
+
+3. **Package release workflow**
+
+   Done: tag-triggered publish workflow with npm provenance and a tag/version
+   consistency check (`.github/workflows/release.yml`); `CHANGELOG.md` in
+   Keep a Changelog format.
+
+   Still to decide:
+
+   - whether to adopt changesets/release-please for automated version bumps, or
+     keep manual CHANGELOG + tag (manual is fine while single-maintainer).
+
+## Priority 2
+
+These are useful but not release blockers.
+
+1. **Playground polish**
+
+   Done:
+
+   - drag-and-drop an HTML file into the editor;
+   - "sanitized HTML" view — toggle to inspect the exact document the pipeline produced;
+   - shareable URL — the input + preset are encoded into the location hash and restored on load.
+
+   Still potential:
+
+   - copyable reports;
+   - saved sample presets;
+   - visual before/after diff for removed tags and attributes.
+
+2. **Policy presets**
+
+   Consider whether `strict`, `balanced`, and `offline` need aliases or additional presets for:
+
+   - AI-generated reports;
+   - fully offline attachments;
+   - internal trusted dashboards;
+   - teaching/demo mode.
+
+3. **Performance and size profiling**
+
+   Add benchmarks for:
+
+   - large HTML input normalization;
+   - sanitizer runtime;
+   - iframe render time;
+   - bundle size and dependency impact.
+
+4. **`jsdom` dependency footprint**
+
+   Verified: `jsdom` is **not** referenced in the browser build (`dist/index.browser.js`,
+   0 occurrences), so it never reaches the final app bundle — a bundler resolving the
+   `browser` export condition never imports it. The only remaining cost is disk
+   footprint in `node_modules` for browser-only consumers who install via npm.
+
+   This is an install-hygiene improvement, not a runtime one. The candidate fix
+   (move `jsdom` to an optional peer dependency + lazily initialize it in the Node
+   entrypoint via `createRequire`, keeping the sync `sanitizeHtml` API and throwing a
+   clear error when absent) changes install semantics and touches the security-critical
+   sanitizer, so it should go through the normal review loop rather than a rushed change.
+
+5. **`EMPTY_AFTER_SANITIZE` behavior needs a proper definition (do not rush)**
+
+   DOMPurify's `WHOLE_DOCUMENT` mode wraps any input into an `html/head/body` shell,
+   so `sanitized.html.trim()` in `document.ts` is never blank and the
+   `EMPTY_AFTER_SANITIZE` error never fires. Content that sanitizes to nothing renders
+   as a blank preview instead.
+
+   The naive fix — `if (sanitized.report.strippedAll) throw ...` — is **wrong**, because
+   `strippedAll` currently keys off text content and a small tag set, so it would
+   misfire on content that is visually/interactively meaningful but text-free
+   (e.g. only `<canvas>`, `<svg>`, `<img>`, or `<input>`). Before changing behavior,
+   the "empty" concept must be split and each case decided explicitly:
+
+   - empty input;
+   - sanitized to no *visible* content;
+   - sanitized to no *interactive* content;
+   - only form/canvas/svg/media remain (no text).
+
+   Then decide per case whether to throw `EMPTY_AFTER_SANITIZE` or simply signal the
+   host via `sanitizeReport.strippedAll`. This is a dedicated design PR, not an inline fix.
+
+## Open Questions
+
+- Should the package expose a lower-level policy builder for hosts that already own iframe rendering?
+- Should Node sanitization remain a first-class path, or only support tests and document generation?
+
+## Resolved
+
+- **Should `strict` allow remote images by default?** No. Presets are layered by
+  exfiltration capability: `strict` keeps `img-src`/`media-src` at `blob: data:`
+  (an image URL is an attacker-readable exfiltration channel). Remote `https:`
+  images/media live in `balanced` only. `offline` has no network at all.
+- **Should the Playground become a hosted demo?** Yes. `.github/workflows/pages.yml`
+  deploys it to GitHub Pages on every push to `main` (assembling a site that mirrors
+  the Playground's relative imports). Requires enabling Pages (Source = GitHub Actions).
+- **Renderer duplication.** The Node and browser renderers now share
+  `renderer-core.ts` via a factory; the entrypoints only inject their
+  `createHtmlDocument` implementation.

package/docs/SANITIZER_DECISION.md

@@ -0,0 +1,78 @@
+# Sanitizer Decision
+
+## Decision
+
+`html-preview-sandbox` uses **DOMPurify** as the sanitizer for v0.1.
+
+`sanitize-html` was considered, but is not used in the current implementation.
+
+## Context
+
+This project previews untrusted HTML inside a browser-like environment. The sanitizer must therefore match browser parsing behavior as closely as practical, support hostile HTML/SVG inputs, and work as one layer in a larger sandbox pipeline.
+
+The pipeline is:
+
+```text
+input -> decode -> sanitize -> CSP policy -> bridge -> sandboxed iframe
+```
+
+The project is not a general CMS content cleaner and not a server-only HTML transformation library.
+
+## Decision Criteria
+
+The sanitizer choice was judged against these criteria:
+
+- **Browser fidelity:** the preview is eventually rendered by a browser iframe, so browser DOM behavior matters.
+- **XSS focus:** the default threat model is untrusted HTML with script, SVG, URL, parser, and mutation-style attack surfaces.
+- **Client runtime:** the package must run naturally in browser applications without requiring a server.
+- **Node support:** tests and server-side document generation still need a Node path.
+- **Hooks and reports:** the project needs policy hooks and a removal report for the Playground and host callbacks.
+- **Maintenance signal:** security-sensitive dependencies should have clear active maintenance and security posture.
+
+## Why DOMPurify
+
+DOMPurify is browser-first and DOM-based. Its public documentation describes it as an XSS sanitizer for HTML, MathML, and SVG, and explains that it uses browser-provided technologies as the basis of the filter. That matches this project's main runtime: previewing HTML that will be parsed and executed by a browser engine.
+
+DOMPurify also supports Node when paired with jsdom. That lets the project use the same sanitizer family in both entrypoints:
+
+- Browser entrypoint: DOMPurify with the real browser `window`.
+- Node/default entrypoint: DOMPurify with jsdom.
+
+This keeps policy behavior easier to reason about than maintaining unrelated sanitizers for browser and Node.
+
+## Why Not sanitize-html for v0.1
+
+`sanitize-html` is useful when the primary job is server-side cleanup of user-submitted HTML using explicit tag and attribute allowlists. Its public repository describes that model and notes that it is built on `htmlparser2`.
+
+That is not the best fit for this project's first release because:
+
+- The main rendering target is a sandboxed browser iframe, not a server-rendered CMS field.
+- Browser DOM parsing behavior is central to the security model.
+- The project needs a browser-native path without making the browser build feel like an adaptation of a server sanitizer.
+- A server-oriented sanitizer route was considered, but this project prioritizes browser-fidelity preview behavior and a fresh, general-purpose design.
+
+As of July 5, 2026, the original `apostrophecms/sanitize-html` GitHub repository is archived and points to a monorepo. That does not make the package unusable by itself, but it weakens the maintenance signal for choosing it as the core of a new security-oriented package.
+
+## Consequences
+
+Choosing DOMPurify means:
+
+- Node usage depends on keeping jsdom current.
+- Sanitization must stay one layer only; CSP, sandboxing, bridge filtering, and host navigation interception remain required.
+- Project hooks must preserve this package's stricter preview policy on top of DOMPurify defaults.
+- Tests must cover browser behavior, not only string-level sanitization.
+
+## Revisit Conditions
+
+Revisit the sanitizer choice if:
+
+- the package becomes primarily server-side;
+- browser runtime support is no longer required;
+- DOMPurify cannot support required policy hooks;
+- jsdom becomes unsuitable for the Node entrypoint;
+- a standardized browser Sanitizer API becomes mature enough for this project's compatibility target.
+
+## References
+
+- [DOMPurify](https://github.com/cure53/DOMPurify)
+- [sanitize-html](https://github.com/apostrophecms/sanitize-html)

package/docs/SECURITY_MODEL.md

@@ -0,0 +1,100 @@
+# Security Model
+
+`html-preview-sandbox` uses defense in depth. No single layer is treated as sufficient.
+
+## Layers
+
+1. **Sanitization**
+   DOMPurify-backed sanitization removes blocked tags, attributes, protocols, meta refresh, and user-provided CSP.
+   The Node entrypoint runs DOMPurify with jsdom; the browser entrypoint runs DOMPurify against the real browser `window`.
+
+2. **CSP**
+   A generated meta CSP limits network access, object embedding, form submission, and resource loading.
+
+3. **Sandboxed iframe**
+   The preview iframe uses `sandbox` without `allow-same-origin`, creating an opaque origin.
+
+4. **Bridge**
+   A small injected script forwards link clicks, `window.open`, and CSP violation reports to the host.
+
+5. **Host adapter**
+   Hosts may add stronger capabilities such as Electron navigation interception.
+
+## Default Sandbox
+
+```text
+allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox allow-modals
+```
+
+`allow-same-origin` and `allow-downloads` are intentionally omitted.
+
+If callers provide custom sandbox tokens, the renderer filters high-risk tokens by default:
+
+```text
+allow-same-origin allow-top-navigation allow-top-navigation-by-user-activation allow-downloads
+```
+
+These tokens are preserved only when `allowUnsafeSandboxTokens` is explicitly enabled.
+
+## CSP Presets
+
+The presets are layered by **exfiltration capability (egress)**, not by which resources they load (ingress). The core threat is not whether untrusted HTML can load a resource, but whether it can send data to a location the attacker can read.
+
+- `offline`: no network at all. Inline scripts/styles and local `data:`/`blob:` resources only. Nothing enters or leaves.
+- `strict`: default. Blocks attacker-readable exfiltration channels — `connect-src 'none'`, `form-action 'none'`, and no wildcard `img-src`/`media-src` (`blob: data:` only). It permits inline script, `unsafe-eval`, and fixed static CDN/font hosts, because in the presence of already-permitted inline scripts these add no attacker capability and provide no attacker-readable exfiltration sink. This is not zero network: requests to whitelisted hosts still leave the machine, leaving narrow low-bandwidth side channels (see `THREAT_MODEL.md` → Residual Risk).
+- `balanced`: opens `https:` images/media and `connect-src https:`, which is a general-purpose exfiltration surface. For semi-trusted content only.
+
+## Default External Protocols
+
+```text
+http: https: mailto: tel:
+```
+
+Other protocols are blocked before reaching `onOpenExternal`.
+
+Hosts can narrow this list with `externalProtocols`. They can also provide `allowExternalUrl(url, context)` for domain-level or product-level decisions. The custom callback is evaluated only after the protocol allowlist passes, and it must return `true` to allow the URL.
+
+## Important Limits
+
+- Scripts are allowed by design, because the project exists to preserve useful HTML interactivity.
+- `unsafe-inline` is allowed in CSP presets because the injected bridge and many self-contained reports rely on inline scripts.
+- `unsafe-eval` is allowed in `strict` and `balanced` (not `offline`). Since inline script is already permitted, `unsafe-eval` adds no attacker capability; blocking it would only break chart libraries and similar generated reports without a security gain.
+- `connect-src` is `none` in `strict` and `offline`, blocking the primary data-exfiltration channel despite script execution. `strict` additionally keeps `img-src`/`media-src` at `blob: data:` (no wildcard host) and `form-action 'none'` so there is no attacker-readable exfiltration sink.
+- `allowExternalUrl` is fail-closed when provided: thrown errors and non-`true` results block the URL.
+- Pure Web hosts cannot fully stop `window.location` navigation; stronger host adapters are required for that layer.
+
+## Known Trade-offs and Hardening Notes
+
+These are deliberate design choices, not defects. They are low-risk given the
+surrounding layers, but are documented so the trade-off is explicit and revisitable.
+
+- **`frame-src blob:`** — allows script inside the sandbox to create `blob:` sub-iframes.
+  Low risk: `<iframe>` markup is stripped by the sanitizer, and any script-created
+  nested frame inherits the sandbox flags (no `allow-same-origin`), so it stays opaque
+  and cannot reach the host. Could be tightened to `frame-src 'none'` if no dependency
+  needs blob frames.
+- **`allow-popups-to-escape-sandbox`** — in the default sandbox. In practice `window.open`
+  is overridden by the bridge and routed to `onOpenExternal`, so a real escaping popup is
+  hard to trigger from content. Kept as defense-in-depth belt so an approved "open in new
+  tab" reaches the host decision rather than opening a sandboxed blank page.
+- **Bridge `postMessage` uses `targetOrigin: '*'`** — the payload is a URL or a CSP
+  violation report (not secret), and the host receiver verifies `event.source ===
+  iframe.contentWindow` before acting. Acceptable given the sandboxed opaque origin.
+
+## Why DOMPurify Is Not Enough
+
+DOMPurify is a sanitizer. This project uses it as one layer, then adds CSP, sandboxing, link handling, and host integration. Users should not extract the sanitizer configuration and treat it as the whole security story.
+
+## Playground Coverage
+
+The Playground is an inspection surface for this model. It renders through the built browser bundle and exposes sanitizer removals, CSP violations, external request forwarding, CSP presets, protocol filtering, and host suffix URL policy in one place. A "sanitized HTML" view also shows the exact document the pipeline produced, so the injected CSP meta, bridge, and stripped content can be inspected directly.
+
+## DOMPurify vs sanitize-html
+
+The current implementation uses **DOMPurify**.
+
+`sanitize-html` was considered, but the package currently favors DOMPurify because browser-side DOM parsing and mXSS hardening are important for this project. Node usage is supported by running DOMPurify with jsdom.
+
+This choice can be revisited if future requirements prioritize a Node-only policy engine, but the v0.1 implementation and tests are DOMPurify-based.
+
+See [Sanitizer Decision](SANITIZER_DECISION.md) for the detailed criteria and trade-offs.