html-preview-sandbox 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). During the `0.x`
+phase the public API may change between minor versions.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-06
+
+Initial release.
+
+### Added
+
+- Defense-in-depth preview pipeline for untrusted HTML: `decode → sanitize → CSP
+  policy → bridge → sandboxed iframe`.
+- `createPreview(container, options)` renderer with an opaque-origin sandboxed
+  iframe (no `allow-same-origin`), plus lower-level `createHtmlDocument`,
+  `sanitizeHtml`, and `buildCsp` helpers.
+- Three CSP presets layered by exfiltration capability:
+  - `offline` — no network at all.
+  - `strict` (default) — blocks attacker-readable exfiltration channels
+    (`connect-src 'none'`, `form-action 'none'`, no wildcard `img-src`/`media-src`)
+    while allowing inline script, `unsafe-eval`, and fixed CDN/font hosts.
+  - `balanced` — opens `https:` images/media and `connect-src https:` for
+    semi-trusted content.
+- DOMPurify-backed sanitizer with project hooks for URL-scheme filtering, meta
+  refresh / user CSP removal, base-tag removal, URL-targeting SVG animation removal,
+  and connection/prefetch resource-hint `<link>` removal
+  (`preconnect`/`dns-prefetch`/`prefetch`/`prerender`), plus a removal report
+  surfaced through `onSanitize`.
+- Injected iframe bridge forwarding link clicks, `window.open`, and
+  `securitypolicyviolation` reports to the host.
+- Fail-closed external URL handling: protocol allowlist plus optional
+  `allowExternalUrl` callback; high-risk sandbox tokens filtered unless explicitly
+  opted in.
+- Optional host navigation hook (`notifyNavigationAttempt`) that re-mounts the last
+  trusted document and routes the URL through the external-link allowlist.
+- Separate Node (jsdom) and browser build entrypoints.
+- Node and Playwright test suites, security regression fixtures, threat model,
+  security policy, and contributor documentation.
+
+[Unreleased]: https://github.com/preview-sandbox/html-preview-sandbox/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/preview-sandbox/html-preview-sandbox/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 html-preview-sandbox contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# html-preview-sandbox
+
+Safely preview untrusted, interactive HTML in a sandboxed iframe.
+
+`html-preview-sandbox` helps applications render untrusted HTML files, user uploads, and AI-generated reports without giving them full browser power. It combines DOMPurify sanitization, CSP presets, opaque-origin sandboxed iframes, external-link mediation, and host callbacks.
+
+## Install
+
+```bash
+npm install html-preview-sandbox
+```
+
+## Quick Start
+
+```js
+import { createPreview } from 'html-preview-sandbox';
+
+const preview = createPreview(document.querySelector('#preview'), {
+  csp: 'strict',
+  onOpenExternal(url) {
+    window.open(url, '_blank', 'noopener,noreferrer');
+  },
+  onCspViolation(report) {
+    console.warn('CSP blocked:', report);
+  },
+  onSanitize(report) {
+    console.info('Sanitize report:', report);
+  },
+});
+
+await preview.render(fileOrHtmlString);
+```
+
+## Runtime Entrypoints
+
+The package is **ESM-only** and requires Node 18+ for the Node/default entrypoint.
+It exposes separate Node and browser builds through package export conditions:
+
+- Node/default import: uses DOMPurify with jsdom.
+- Browser import: uses DOMPurify with the real browser `window`.
+- Explicit browser import: `html-preview-sandbox/browser`.
+
+Most modern bundlers resolve the `browser` condition automatically. The example and Playground run against `dist/index.browser.js`, so build the package before opening them from the repository.
+
+Use the explicit browser subpath when your runtime or bundler does not honor the `browser` condition:
+
+```js
+import { createPreview } from 'html-preview-sandbox/browser';
+```
+
+## Sanitizer Choice
+
+This project currently uses **DOMPurify** for the sanitization layer.
+
+- Browser runtime: DOMPurify runs against the real browser `window`.
+- Node runtime: DOMPurify runs with jsdom.
+- `sanitize-html` is not used in the current implementation.
+
+DOMPurify is still only one layer. The preview also relies on CSP, a sandboxed iframe, bridge handling, external URL filtering, and optional host navigation interception.
+
+## What It Is
+
+- A client-side preview pipeline for untrusted HTML files and strings.
+- A way to preserve useful interactivity while reducing host-app risk.
+- A small core package with Web examples and a Playground.
+
+## What It Is Not
+
+- Not a browser: it does not browse URLs or support multi-page navigation.
+- Not an attachment system: download, decrypt, cache, and permission checks belong to the host app.
+- Not a DOMPurify replacement: sanitization is one layer in a defense-in-depth pipeline.
+- Not a guarantee that all HTML is safe: see `THREAT_MODEL.md`.
+
+## Pipeline
+
+```text
+input -> decode -> sanitize -> CSP policy -> bridge -> sandboxed iframe
+```
+
+The default sandbox intentionally omits `allow-same-origin`, giving the previewed document an opaque origin. External links and `window.open` calls are forwarded to the host through callbacks. In pure Web environments, JavaScript-driven `window.location` navigation cannot be fully intercepted; Electron or other hosts can add stronger navigation controls.
+
+Host integrations that can observe iframe navigations may call `preview.notifyNavigationAttempt(url)`. The core renderer will restore the last trusted `srcdoc` and forward the URL through the same external-link allowlist.
+
+The three CSP presets are layered by **exfiltration capability**, not by which resources they load:
+
+- `offline`: no network at all. Only inline scripts/styles and `data:`/`blob:` resources.
+- `strict` (default): blocks attacker-readable exfiltration channels — `connect-src 'none'`, `form-action 'none'`, and no wildcard `img-src`/`media-src`. Fixed static CDN/font hosts may be loaded, and inline script plus `unsafe-eval` are permitted, because they add no attacker capability beyond the already-permitted inline scripts and provide no attacker-readable exfiltration sink. This is not "zero network" — requests to whitelisted hosts still leave the machine (see the residual-risk note in `THREAT_MODEL.md`).
+- `balanced`: opens `https:` images/media and `connect-src https:`. This is a general-purpose exfiltration surface, so use it only for semi-trusted content.
+
+Custom sandbox tokens are filtered by default. High-risk tokens such as `allow-same-origin`, `allow-downloads`, and top-navigation permissions are ignored unless `allowUnsafeSandboxTokens` is set.
+
+External links are also fail-closed. The default protocol allowlist is `http:`, `https:`, `mailto:`, and `tel:`. Hosts can narrow it with `externalProtocols` and add domain or product rules with `allowExternalUrl`.
+
+## Documentation
+
+- [Integration Guide](docs/INTEGRATION.md)
+- [使用文档(中文)](docs/使用文档.zh-CN.md)
+- [Security Model](docs/SECURITY_MODEL.md)
+- [Sanitizer Decision](docs/SANITIZER_DECISION.md)
+- [Browser Support](docs/BROWSER_SUPPORT.md)
+- [Project Structure](docs/PROJECT_STRUCTURE.md)
+- [Branching & Releases](docs/BRANCHING.md)
+- [Roadmap](docs/ROADMAP.md)
+- [Threat Model](THREAT_MODEL.md)
+- [Security Policy](SECURITY.md)
+
+## Project Structure
+
+The package source lives in `src/` and builds to `dist/`. Tests and local examples run against the built output so local checks match the package that consumers receive.
+
+```text
+src/          TypeScript package source
+dist/         Generated ESM bundles and declarations
+playground/   Local security inspection workbench
+examples/     Minimal integration examples
+fixtures/     HTML regression inputs
+test/         Node and Playwright tests
+docs/         Integration, architecture, and security notes
+```
+
+## Tests
+
+```bash
+npm run check:types
+npm test
+npm run test:browser
+npm run build
+```
+
+The type check validates the TypeScript source and generated public API surface. The Node test suite covers decoding, CSP generation, injection order, protocol filtering, and sanitization reports. The Playwright suite verifies real browser iframe sandboxing and external-link bridging, plus the Web example, file-upload example, Web Component, and Playground behaviors.
+
+In CI, install the Playwright browser before `npm run test:browser`:
+
+```bash
+npx playwright install --with-deps chrome
+```
+
+Run the default local quality gate before publishing changes:
+
+```bash
+npm run check
+```
+
+## Playground
+
+Build the package, serve the repository root with any static file server, then open `/playground/`.
+
+```bash
+npm run build
+npm run serve
+```
+
+Then visit `http://localhost:4173/playground/`.
+
+The Playground is a three-panel workbench with HTML input, sandboxed preview, and an inspector for sanitizer removals, CSP violations, external requests, and current policy. It also includes sample payloads plus controls for CSP preset, external protocols, and host suffix filtering. You can drag an HTML file onto the editor, toggle a "sanitized HTML" view to inspect the exact document the pipeline produced, and use Share to encode the input + preset into a shareable URL.
+
+### Hosted Playground
+
+`.github/workflows/pages.yml` deploys the Playground to GitHub Pages on every push to `main`. The workflow builds the library and assembles a site that mirrors the Playground's relative imports, so no code changes are needed. One-time setup: in the repository, go to **Settings → Pages → Source** and select **GitHub Actions**. After the first successful run the Playground is available at `https://preview-sandbox.github.io/html-preview-sandbox/playground/`.
+
+## Status
+
+This is an initial v0.1 TypeScript implementation. The API is expected to evolve before 1.0.

package/SECURITY.md

@@ -0,0 +1,40 @@
+# Security Policy
+
+## Supported Versions
+
+During the v0.x phase, security reports are accepted for the latest published minor version.
+
+## Reporting a Vulnerability
+
+Please do not open public issues for security problems. Use GitHub Security Advisories when the repository is published, or contact the maintainer through the private channel listed in the repository profile.
+
+## Response Timeline
+
+- Confirmation: best effort within 72 hours.
+- Initial assessment: best effort within 7 days.
+- High-severity fixes: target within 14 days when practical.
+- Other fixes: target within 30 days when practical.
+
+This project may be maintained by a small team or individual maintainers, so timelines are best effort.
+
+## Security Scope
+
+Examples of in-scope issues:
+
+- Sanitizer bypasses that defeat the documented default policy.
+- CSP injection or bridge injection failures.
+- External-link protocol validation bypasses.
+- Sandbox configuration mistakes in the default renderer.
+- Bridge behavior that lets untrusted HTML attack the host page.
+
+## Out of Scope
+
+- CPU exhaustion, infinite loops, or mining inside the sandbox.
+- Phishing content rendered as normal HTML.
+- Browser, Electron, or operating-system sandbox vulnerabilities.
+- Issues that require intentionally unsafe custom policy overrides.
+- Self-XSS and attacks requiring users to paste trusted secrets into untrusted content.
+
+## Credit
+
+Reporters may be credited in advisories and release notes unless they request anonymity.

package/THREAT_MODEL.md

@@ -0,0 +1,51 @@
+# Threat Model
+
+`html-preview-sandbox` is designed for apps that need to preview untrusted HTML files or strings while preserving useful interactivity.
+
+## Trust Boundaries
+
+- Host app: trusted application code, storage, cookies, and user context.
+- Preview iframe: untrusted HTML running in a sandboxed `srcdoc` iframe.
+- External browser/system handler: destination for host-approved external links.
+
+## Defense Goals
+
+- Reduce access from previewed HTML to host app DOM, storage, cookies, and APIs.
+- Block common dangerous tags, attributes, protocols, and auto-triggering handlers.
+- Limit data exfiltration through CSP presets.
+- Prevent external links and popups from silently taking over the preview iframe.
+- Surface sanitizer changes and CSP violations to the host app.
+
+## Non Goals
+
+- It does not stop CPU-heavy scripts, infinite loops, or resource exhaustion inside the sandbox.
+- It does not detect phishing content or misleading text rendered inside HTML.
+- It does not protect against browser or runtime sandbox vulnerabilities.
+- It does not make dangerous custom policies safe.
+- It does not fully intercept `window.location` navigation in pure Web hosts.
+
+## Residual Risk: Low-Bandwidth Side Channels (strict preset)
+
+The `strict` preset blocks general-purpose, attacker-readable exfiltration channels, but it is not "zero network". Because it permits loading from fixed static CDN and font hosts, some low-bandwidth information leakage remains possible and is **out of scope**:
+
+- Request patterns to whitelisted hosts (for example, encoding data into a path served by a CDN whose access logs the attacker can observe indirectly).
+- DNS resolution of whitelisted hostnames.
+- Request timing and ordering.
+
+These channels are narrow, aggregated, and high-latency compared to `connect-src`/image-URL exfiltration, which `strict` does block. Integrations that must eliminate even these should use the `offline` preset (no network at all).
+
+## Web vs Host Adapters
+
+Pure Web integrations can intercept link clicks and `window.open` through the bridge script, but cannot reliably intercept all JavaScript-driven `window.location` navigation. Desktop hosts such as Electron can add navigation interception outside the iframe and re-render the original content.
+
+## Default Position
+
+The default `strict` preset fails closed for attacker-readable exfiltration: `connect-src 'none'`, `form-action 'none'`, no wildcard `img-src`/`media-src`, and no external link opening when `onOpenExternal` is not provided. It permits inline script, `unsafe-eval`, and fixed static CDN/font hosts, none of which add attacker capability beyond the already-permitted inline scripts (see the residual-risk note above for the narrow side channels that remain).
+
+Custom sandbox tokens are also fail-closed for high-risk permissions. `allow-same-origin`, download, and top-navigation permissions are filtered unless the host explicitly opts into unsafe sandbox tokens.
+
+External URL handling is fail-closed in two stages: the protocol must pass the configured allowlist, then `allowExternalUrl` must return `true` when that callback is provided.
+
+## Sanitizer Position
+
+The project uses DOMPurify for sanitization. DOMPurify reduces common HTML/script injection risk, but this project does not treat sanitization as sufficient by itself. CSP, iframe sandboxing, URL filtering, and host integration remain required parts of the design.

package/dist/bridge.d.ts

@@ -0,0 +1,3 @@
+export declare const BRIDGE_OPEN_EXTERNAL = "html-preview-sandbox:openExternal";
+export declare const BRIDGE_CSP_VIOLATION = "html-preview-sandbox:cspViolation";
+export declare function injectBridgeScript(html: string): string;

package/dist/decode.d.ts

@@ -0,0 +1,12 @@
+import type { PreviewInput } from './types.js';
+export declare const DEFAULT_MAX_BYTES: number;
+export interface DecodeResult {
+    html: string;
+    encoding: string;
+    usedBom: boolean;
+    size: number;
+}
+export declare function normalizeInput(input: PreviewInput, options?: {
+    maxBytes?: number;
+}): Promise<DecodeResult>;
+export declare function decodeHtmlBytes(input: ArrayBuffer | Uint8Array): DecodeResult;

package/dist/document.browser.d.ts

@@ -0,0 +1,2 @@
+import type { PreviewInput, PreviewOptions, RenderResult } from './types.js';
+export declare function createHtmlDocument(input: PreviewInput, options?: PreviewOptions): Promise<RenderResult>;

package/dist/document.d.ts

@@ -0,0 +1,2 @@
+import type { PreviewInput, PreviewOptions, RenderResult } from './types.js';
+export declare function createHtmlDocument(input: PreviewInput, options?: PreviewOptions): Promise<RenderResult>;

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+import type { PreviewErrorCode } from './types.js';
+export declare class PreviewError extends Error {
+    code: PreviewErrorCode;
+    cause?: unknown;
+    constructor(code: PreviewErrorCode, message: string, cause?: unknown);
+}
+export declare const ERROR_CODES: {
+    readonly OVERSIZED: "OVERSIZED";
+    readonly DECODE_FAILED: "DECODE_FAILED";
+    readonly EMPTY_AFTER_SANITIZE: "EMPTY_AFTER_SANITIZE";
+    readonly RENDER_FAILED: "RENDER_FAILED";
+};

package/dist/index.browser.d.ts

@@ -0,0 +1,9 @@
+export type { CspPolicy, CspPreset, CspViolationReport, OpenExternalSource, PreviewErrorCode, PreviewErrorShape, PreviewHandle, PreviewInput, PreviewOptions, RenderResult, SanitizeOptions, SanitizeReport, } from './types.js';
+export { createPreview } from './renderer.browser.js';
+export { createHtmlDocument } from './document.browser.js';
+export { decodeHtmlBytes, normalizeInput, DEFAULT_MAX_BYTES } from './decode.js';
+export { sanitizeHtml } from './sanitize.browser.js';
+export { DEFAULT_ALLOWED_EXTERNAL_PROTOCOLS, DEFAULT_SANDBOX_TOKENS, UNSAFE_SANDBOX_TOKENS, buildCsp, getSandboxAttribute, injectCspMeta, isAllowedExternalUrl, } from './policy.js';
+export { hasAuthorScrollbarStyle, injectScrollbarStyle, } from './scrollbar.js';
+export { BRIDGE_CSP_VIOLATION, BRIDGE_OPEN_EXTERNAL, injectBridgeScript, } from './bridge.js';
+export { PreviewError, ERROR_CODES } from './errors.js';