@render-policy/core 0.1.0

package/dist/policy.js

@@ -0,0 +1,110 @@
+/**
+ * A RenderPolicy is the single place where an application decides what
+ * agent-generated content may do once it reaches the DOM.
+ *
+ * Sanitization (no scripts, no event handlers, no unknown elements) is not
+ * negotiable and is not part of the policy. The policy covers what a
+ * sanitizer alone cannot decide for you, grouped into three concerns:
+ *
+ * - `content`: which elements, attributes and classes agent output may carry.
+ * - `urls`: which URLs any attribute may point at (schemes, sink hosts, encoded
+ *   payloads, and an application hook that decides or rewrites each one).
+ * - `images`: what happens to the image requests those URLs would make, which
+ *   fire without a click (host allowlist, query strings, proxy rewrite, placeholder).
+ */
+export const DEFAULT_URL_HEURISTICS = Object.freeze({
+    maxLength: 2048,
+    maxTokenLength: 64,
+    minEntropy: 4,
+});
+/** Content rules are identical in every mode; modes differ only in their URL and image posture. */
+const CONTENT = Object.freeze({
+    allowImages: true,
+    allowForms: false,
+    allowSvg: false,
+    allowMedia: false,
+    allowInlineStyles: false,
+    allowDataAttributes: false,
+    allowTargetBlank: true,
+    allowedClassPatterns: Object.freeze([/^language-[\w+#.-]+$/, /^rp-[\w-]+$/]),
+    forbidTags: Object.freeze([]),
+    forbidAttributes: Object.freeze([]),
+});
+const URLS_COMMON = { allowedSchemes: Object.freeze(['http', 'https', 'mailto', 'tel']), allowRelativeUrls: true, decide: null };
+const IMAGES_COMMON = { allowWildcardHosts: false, rewriteUrl: null, blocked: 'placeholder' };
+/**
+ * Mode presets.
+ *
+ * - strict: no remote images at all; sink hosts blocked; heuristics on.
+ * - balanced: remote images only from the allowlist, query strings stripped; sink hosts blocked; heuristics on.
+ * - permissive: every host allowed, nothing rewritten; sink hosts and nothing else are only logged.
+ *
+ * Sanitization is identical in all three modes. Permissive is still XSS-safe; it just stops
+ * making decisions about where data may flow.
+ */
+export const MODE_PRESETS = Object.freeze({
+    strict: Object.freeze({
+        mode: 'strict',
+        content: CONTENT,
+        urls: Object.freeze({ ...URLS_COMMON, heuristics: DEFAULT_URL_HEURISTICS, sinkDenylist: 'block' }),
+        images: Object.freeze({ ...IMAGES_COMMON, hosts: 'none', query: 'strip' }),
+    }),
+    balanced: Object.freeze({
+        mode: 'balanced',
+        content: CONTENT,
+        urls: Object.freeze({ ...URLS_COMMON, heuristics: DEFAULT_URL_HEURISTICS, sinkDenylist: 'block' }),
+        images: Object.freeze({ ...IMAGES_COMMON, hosts: Object.freeze([]), query: 'strip' }),
+    }),
+    permissive: Object.freeze({
+        mode: 'permissive',
+        content: CONTENT,
+        urls: Object.freeze({ ...URLS_COMMON, heuristics: false, sinkDenylist: 'log' }),
+        images: Object.freeze({ ...IMAGES_COMMON, hosts: 'any', query: 'keep' }),
+    }),
+});
+export const DEFAULT_MODE = 'balanced';
+/**
+ * Build a policy from a mode preset plus explicit overrides. Each group is merged on top of the
+ * preset, so an override names only the fields it changes. Throws on configurations that silently
+ * widen exposure (wildcard hosts without opting in).
+ */
+export function resolvePolicy(mode = DEFAULT_MODE, overrides = {}) {
+    const preset = MODE_PRESETS[mode];
+    if (!preset) {
+        throw new Error(`@render-policy/core: unknown mode "${String(mode)}"`);
+    }
+    const policy = {
+        mode,
+        content: { ...preset.content, ...stripUndefined(overrides.content ?? {}) },
+        urls: { ...preset.urls, ...stripUndefined(overrides.urls ?? {}) },
+        images: { ...preset.images, ...stripUndefined(overrides.images ?? {}) },
+    };
+    if (Array.isArray(policy.images.hosts) && !policy.images.allowWildcardHosts) {
+        const wildcard = policy.images.hosts.find((h) => h.includes('*'));
+        if (wildcard) {
+            throw new Error(`@render-policy/core: images.hosts contains the wildcard pattern "${wildcard}" but images.allowWildcardHosts is false. ` +
+                'List exact hosts, or set images.allowWildcardHosts: true deliberately.');
+        }
+    }
+    for (const scheme of policy.urls.allowedSchemes) {
+        if (scheme !== scheme.toLowerCase() || scheme.endsWith(':')) {
+            throw new Error(`@render-policy/core: urls.allowedSchemes entries must be lower-case and without the colon (got "${scheme}")`);
+        }
+    }
+    for (const pattern of policy.content.allowedClassPatterns) {
+        if (pattern.global || pattern.sticky) {
+            throw new Error(`@render-policy/core: content.allowedClassPatterns must not use the g or y flags (got ${String(pattern)})`);
+        }
+    }
+    return policy;
+}
+function stripUndefined(value) {
+    const out = {};
+    for (const key of Object.keys(value)) {
+        if (value[key] !== undefined) {
+            out[key] = value[key];
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=policy.js.map

package/dist/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"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"}

package/dist/render.d.ts

@@ -0,0 +1,79 @@
+import type { TrustedHTML } from 'trusted-types/lib/index.js';
+import type { RenderDecision } from './decisions.js';
+import { type MarkdownRenderer } from './markdown.js';
+import { type RenderMode, type RenderPolicy, type RenderPolicyOverrides } from './policy.js';
+import type { SinkDenylist } from './sinks.js';
+import { type RenderStream, type StreamOptions } from './stream.js';
+import { type RenderWindow } from './window.js';
+/** Where rendered content goes: an element, a shadow root or a fragment. Never a whole document. */
+export type RenderTarget = Element | DocumentFragment;
+export interface RenderResult {
+    readonly decisions: readonly RenderDecision[];
+}
+/** What a render knows about itself. Transforms receive it, with the document added. */
+export interface RenderContext {
+    /** True while a stream renders, intermediate or final. Default false. */
+    readonly streaming: boolean;
+    /** True for a one-shot render or the final render of a stream. Default true. */
+    readonly final: boolean;
+    /** True when the source ended inside a code fence that the stream closed for display. Default false. */
+    readonly openFenceAtEnd: boolean;
+}
+export interface RenderOptions extends Partial<RenderContext> {
+    /**
+     * Keep the leading child nodes of the target that are unchanged and replace only
+     * from the first difference. Used by streams; a one-shot render replaces everything.
+     */
+    readonly patch?: boolean;
+}
+export interface TransformContext extends RenderContext {
+    /** The document to create nodes in. The fragment itself may belong to the parser's document. */
+    readonly document: Document;
+}
+/**
+ * Post-processes a sanitized fragment before insertion: diagrams, syntax highlighting,
+ * link decorations. A transform runs on already-sanitized content and is trusted code;
+ * whatever it adds is inserted as is. A transform that throws is skipped and journaled;
+ * the fragment is inserted without its work.
+ */
+export type FragmentTransform = (fragment: DocumentFragment, context: TransformContext) => void;
+export interface FragmentResult extends RenderResult {
+    readonly fragment: DocumentFragment;
+}
+export interface RendererOptions {
+    /** The window to render with. Defaults to the global window; pass a JSDOM window in tests. */
+    readonly window?: RenderWindow;
+    /** Policy preset. Default 'balanced'. */
+    readonly mode?: RenderMode;
+    /** Overrides applied on top of the preset. Each group (`content`, `urls`, `images`) is merged. */
+    readonly policy?: RenderPolicyOverrides;
+    /** Replace the bundled sink denylist. */
+    readonly sinkDenylist?: SinkDenylist;
+    /** Replace the Markdown renderer. Its output is sanitized regardless. */
+    readonly markdown?: MarkdownRenderer;
+    /** Receive every policy decision as it is made. */
+    readonly onDecision?: (decision: RenderDecision) => void;
+    /** Post-processors applied to every sanitized fragment before insertion, in order. */
+    readonly transforms?: readonly FragmentTransform[];
+}
+export interface Renderer {
+    readonly policy: RenderPolicy;
+    /** Sanitize HTML into an inert fragment without touching any live DOM. */
+    sanitizeHtml(html: string, options?: RenderOptions): FragmentResult;
+    /** Convert Markdown and sanitize into an inert fragment. */
+    markdownToFragment(markdown: string, options?: RenderOptions): FragmentResult;
+    /** Sanitize and insert with replaceChildren(). innerHTML is never used. */
+    renderHtmlInto(target: RenderTarget, html: string, options?: RenderOptions): RenderResult;
+    /** Convert Markdown, sanitize and insert with replaceChildren(). Falls back to plain text if the Markdown step throws. */
+    renderMarkdownInto(target: RenderTarget, markdown: string, options?: RenderOptions): RenderResult;
+    /** Insert plain text. Never interpreted as markup. */
+    renderTextInto(target: RenderTarget, text: string): void;
+    /** Escape hatch for string sinks you cannot remove: sanitized HTML as a TrustedHTML where the API exists, else a string. */
+    trustedHTML(html: string): TrustedHTML | string;
+    /** Same as trustedHTML, from Markdown. */
+    markdownToTrustedHTML(markdown: string): TrustedHTML | string;
+    /** Incremental rendering for streamed model output. */
+    createStream(target: RenderTarget, options?: StreamOptions): RenderStream;
+}
+export declare function createRenderer(options?: RendererOptions): Renderer;
+//# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"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"}

package/dist/render.js

@@ -0,0 +1,130 @@
+import { SINK_DENYLIST } from './data/sink-domains.js';
+import { patchChildren } from './dom.js';
+import { messageOf } from './errors.js';
+import { createMarkdownRenderer } from './markdown.js';
+import { resolvePolicy } from './policy.js';
+import { createSanitizer } from './sanitize.js';
+import { createRenderStream } from './stream.js';
+import { resolveWindow } from './window.js';
+const MARKDOWN_FAILED = Object.freeze({
+    kind: 'blocked',
+    subject: 'markdown',
+    code: 'markdown-failed',
+    reason: 'the Markdown renderer threw; the input was rendered as plain text',
+});
+export function createRenderer(options = {}) {
+    const win = resolveWindow(options.window);
+    const policy = resolvePolicy(options.mode, options.policy);
+    const sanitizer = createSanitizer(win, policy, options.sinkDenylist ?? SINK_DENYLIST);
+    const markdown = options.markdown ?? createMarkdownRenderer();
+    const onDecision = options.onDecision;
+    const transforms = options.transforms ?? [];
+    /** Run the transforms; a transform that throws is skipped and reported, the others still run. */
+    const applyTransforms = (fragment, options) => {
+        if (transforms.length === 0)
+            return [];
+        const context = {
+            streaming: options?.streaming ?? false,
+            final: options?.final ?? true,
+            openFenceAtEnd: options?.openFenceAtEnd ?? false,
+            // The fragment belongs to the sanitizer's parser document; transforms create nodes in the live one.
+            document: win.document,
+        };
+        const failures = [];
+        for (const transform of transforms) {
+            try {
+                transform(fragment, context);
+            }
+            catch (error) {
+                failures.push({ kind: 'flagged', subject: 'transform', code: 'transform-failed', reason: `a transform threw and was skipped: ${messageOf(error)}` });
+            }
+        }
+        return failures;
+    };
+    const emit = (decisions) => {
+        if (!onDecision)
+            return;
+        for (const decision of decisions)
+            onDecision(decision);
+    };
+    const toHtml = (source) => {
+        try {
+            return { html: markdown(source) };
+        }
+        catch {
+            return { failed: true };
+        }
+    };
+    const documentOf = (target) => target.ownerDocument ?? win.document;
+    const renderTextInto = (target, text) => {
+        target.replaceChildren(documentOf(target).createTextNode(text));
+    };
+    const sanitizeHtml = (html, options) => {
+        const { output, decisions: sanitized } = sanitizer.toFragment(html);
+        const failures = applyTransforms(output, options);
+        const decisions = failures.length === 0 ? sanitized : [...sanitized, ...failures];
+        emit(decisions);
+        return { fragment: output, decisions };
+    };
+    const markdownToFragment = (source, options) => {
+        const converted = toHtml(source);
+        if ('failed' in converted) {
+            const fragment = win.document.createDocumentFragment();
+            fragment.append(source);
+            emit([MARKDOWN_FAILED]);
+            return { fragment, decisions: [MARKDOWN_FAILED] };
+        }
+        return sanitizeHtml(converted.html, options);
+    };
+    const insert = (target, fragment, options) => {
+        if (options?.patch) {
+            patchChildren(target, fragment);
+        }
+        else {
+            target.replaceChildren(fragment);
+        }
+    };
+    const renderHtmlInto = (target, html, options) => {
+        const { fragment, decisions } = sanitizeHtml(html, options);
+        insert(target, fragment, options);
+        return { decisions };
+    };
+    const renderMarkdownInto = (target, source, options) => {
+        const converted = toHtml(source);
+        if ('failed' in converted) {
+            renderTextInto(target, source);
+            emit([MARKDOWN_FAILED]);
+            return { decisions: [MARKDOWN_FAILED] };
+        }
+        return renderHtmlInto(target, converted.html, options);
+    };
+    const trustedHTML = (html) => {
+        const { output, decisions } = sanitizer.toTrustedHTML(html);
+        emit(decisions);
+        return output;
+    };
+    return {
+        policy,
+        sanitizeHtml,
+        markdownToFragment,
+        renderHtmlInto,
+        renderMarkdownInto,
+        renderTextInto,
+        trustedHTML,
+        markdownToTrustedHTML(source) {
+            const converted = toHtml(source);
+            if ('failed' in converted) {
+                emit([MARKDOWN_FAILED]);
+                return trustedHTML(escapeText(source));
+            }
+            return trustedHTML(converted.html);
+        },
+        createStream(target, streamOptions = {}) {
+            return createRenderStream(target, streamOptions, { markdown: renderMarkdownInto, html: renderHtmlInto });
+        },
+    };
+}
+function escapeText(text) {
+    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+//# sourceMappingURL=render.js.map

package/dist/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"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"}

package/dist/sanitize.d.ts

@@ -0,0 +1,17 @@
+import type { TrustedHTML } from 'trusted-types/lib/index.js';
+import type { RenderDecision } from './decisions.js';
+import type { RenderPolicy } from './policy.js';
+import { type SinkDenylist } from './sinks.js';
+import type { RenderWindow } from './window.js';
+export interface SanitizeOutcome<T> {
+    readonly output: T;
+    readonly decisions: readonly RenderDecision[];
+}
+export interface Sanitizer {
+    /** Sanitize into an inert DocumentFragment. This is the only path the renderer uses. */
+    toFragment(html: string): SanitizeOutcome<DocumentFragment>;
+    /** Sanitize to a TrustedHTML when the Trusted Types API is present, else a string. */
+    toTrustedHTML(html: string): SanitizeOutcome<TrustedHTML | string>;
+}
+export declare function createSanitizer(win: RenderWindow, policy: RenderPolicy, denylist: SinkDenylist): Sanitizer;
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/sanitize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../src/sanitize.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,KAAK,EAAqC,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAExF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAa,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,QAAQ,CAAC,SAAS,EAAE,SAAS,cAAc,EAAE,CAAC;CAC/C;AAED,MAAM,WAAW,SAAS;IACxB,wFAAwF;IACxF,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAAC,gBAAgB,CAAC,CAAC;IAC5D,sFAAsF;IACtF,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAAC,WAAW,GAAG,MAAM,CAAC,CAAC;CACpE;AAgFD,wBAAgB,eAAe,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,GAAG,SAAS,CA4P1G"}