minisiwyg-editor 0.1.0

package/src/defaults.ts

@@ -0,0 +1,32 @@
+import type { SanitizePolicy } from './types';
+
+const policy: SanitizePolicy = {
+  tags: {
+    p: [],
+    br: [],
+    strong: [],
+    em: [],
+    a: ['href', 'title', 'target'],
+    h1: [],
+    h2: [],
+    h3: [],
+    ul: [],
+    ol: [],
+    li: [],
+    blockquote: [],
+    pre: [],
+    code: [],
+  },
+  strip: true,
+  maxDepth: 10,
+  maxLength: 100_000,
+  protocols: ['https', 'http', 'mailto'],
+};
+
+// Deep freeze to prevent mutation of security-critical defaults
+Object.freeze(policy);
+Object.freeze(policy.protocols);
+for (const attrs of Object.values(policy.tags)) Object.freeze(attrs);
+Object.freeze(policy.tags);
+
+export const DEFAULT_POLICY: Readonly<SanitizePolicy> = policy;

package/src/editor.ts

@@ -0,0 +1,376 @@
+import type { SanitizePolicy, EditorOptions, Editor } from './types';
+import { DEFAULT_POLICY } from './defaults';
+import { sanitizeToFragment } from './sanitize';
+import { createPolicyEnforcer, type PolicyEnforcer } from './policy';
+import { isProtocolAllowed } from './shared';
+
+export type { Editor, EditorOptions } from './types';
+export { DEFAULT_POLICY } from './defaults';
+
+type EditorEvent = 'change' | 'paste' | 'overflow' | 'error';
+type EventHandler = (...args: unknown[]) => void;
+
+const SUPPORTED_COMMANDS = new Set([
+  'bold',
+  'italic',
+  'heading',
+  'blockquote',
+  'unorderedList',
+  'orderedList',
+  'link',
+  'unlink',
+  'codeBlock',
+]);
+
+/**
+ * Create a contentEditable-based editor with built-in sanitization.
+ *
+ * The paste handler is the primary security boundary — it sanitizes HTML
+ * before insertion via Selection/Range API. The MutationObserver-based
+ * policy enforcer provides defense-in-depth.
+ */
+export function createEditor(
+  element: HTMLElement,
+  options?: EditorOptions,
+): Editor {
+  if (!element) {
+    throw new TypeError('createEditor requires an HTMLElement');
+  }
+  if (!element.ownerDocument || !element.parentNode) {
+    throw new TypeError('createEditor requires an element attached to the DOM');
+  }
+
+  const src = options?.policy ?? DEFAULT_POLICY;
+  const policy: SanitizePolicy = {
+    tags: Object.fromEntries(
+      Object.entries(src.tags).map(([k, v]) => [k, [...v]]),
+    ),
+    strip: src.strip,
+    maxDepth: src.maxDepth,
+    maxLength: src.maxLength,
+    protocols: [...src.protocols],
+  };
+
+  const handlers: Record<string, EventHandler[]> = {};
+  const doc = element.ownerDocument;
+
+  function emit(event: EditorEvent, ...args: unknown[]): void {
+    for (const handler of handlers[event] ?? []) {
+      handler(...args);
+    }
+  }
+
+  // Set up contentEditable
+  element.contentEditable = 'true';
+
+  // Attach policy enforcer (MutationObserver defense-in-depth)
+  const enforcer: PolicyEnforcer = createPolicyEnforcer(element, policy);
+  enforcer.on('error', (err) => emit('error', err));
+
+  // Paste handler — the primary security boundary
+  function onPaste(e: ClipboardEvent): void {
+    e.preventDefault();
+
+    const clipboard = e.clipboardData;
+    if (!clipboard) return;
+
+    // Inside code block: paste as plain text only
+    const sel = doc.getSelection();
+    if (sel && sel.rangeCount > 0 && sel.anchorNode) {
+      const pre = findAncestor(sel.anchorNode, 'PRE');
+      if (pre) {
+        const text = clipboard.getData('text/plain');
+        if (!text) return;
+        if (policy.maxLength > 0) {
+          const currentLen = element.textContent?.length ?? 0;
+          if (currentLen + text.length > policy.maxLength) {
+            emit('overflow', policy.maxLength);
+          }
+        }
+        const range = sel.getRangeAt(0);
+        range.deleteContents();
+        const textNode = doc.createTextNode(text);
+        range.insertNode(textNode);
+        range.setStartAfter(textNode);
+        range.collapse(true);
+        sel.removeAllRanges();
+        sel.addRange(range);
+        emit('paste', element.innerHTML);
+        emit('change', element.innerHTML);
+        return;
+      }
+    }
+
+    // Prefer HTML, fall back to plain text
+    let html = clipboard.getData('text/html');
+    if (!html) {
+      const text = clipboard.getData('text/plain');
+      if (!text) return;
+      // Escape plain text and convert newlines to <br>
+      html = text
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;')
+        .replace(/\n/g, '<br>');
+    }
+
+    // Sanitize through policy — returns DocumentFragment directly
+    // to avoid the serialize→reparse mXSS vector
+    const fragment = sanitizeToFragment(html, policy);
+
+    // Insert via Selection/Range API (NOT execCommand('insertHTML'))
+    const selection = doc.getSelection();
+    if (!selection || selection.rangeCount === 0) return;
+
+    const range = selection.getRangeAt(0);
+    range.deleteContents();
+
+    // Check overflow using text content length
+    if (policy.maxLength > 0) {
+      const pasteTextLen = fragment.textContent?.length ?? 0;
+      const currentLen = element.textContent?.length ?? 0;
+      if (currentLen + pasteTextLen > policy.maxLength) {
+        emit('overflow', policy.maxLength);
+      }
+    }
+
+    // Remember last inserted node for cursor positioning
+    let lastNode: Node | null = fragment.lastChild;
+    range.insertNode(fragment);
+
+    // Move cursor after inserted content
+    if (lastNode) {
+      const newRange = doc.createRange();
+      newRange.setStartAfter(lastNode);
+      newRange.collapse(true);
+      selection.removeAllRanges();
+      selection.addRange(newRange);
+    }
+
+    emit('paste', element.innerHTML);
+    emit('change', element.innerHTML);
+  }
+
+  // Input handler for change events
+  function onInput(): void {
+    emit('change', element.innerHTML);
+    options?.onChange?.(element.innerHTML);
+  }
+
+  // Keydown handler for code block behavior
+  function onKeydown(e: KeyboardEvent): void {
+    const sel = doc.getSelection();
+    if (!sel || sel.rangeCount === 0) return;
+    const anchor = sel.anchorNode;
+    if (!anchor) return;
+
+    const pre = findAncestor(anchor, 'PRE');
+
+    if (e.key === 'Enter' && pre) {
+      // Insert newline instead of new paragraph
+      e.preventDefault();
+      const range = sel.getRangeAt(0);
+      range.deleteContents();
+      const textNode = doc.createTextNode('\n');
+      range.insertNode(textNode);
+      range.setStartAfter(textNode);
+      range.collapse(true);
+      sel.removeAllRanges();
+      sel.addRange(range);
+      emit('change', element.innerHTML);
+    }
+
+    if (e.key === 'Backspace' && pre) {
+      // At start of empty pre, convert to <p>
+      const text = pre.textContent || '';
+      const isAtStart = sel.anchorOffset === 0;
+      const isEmpty = text === '' || text === '\n';
+      if (isAtStart && isEmpty) {
+        e.preventDefault();
+        const p = doc.createElement('p');
+        p.appendChild(doc.createElement('br'));
+        pre.parentNode?.replaceChild(p, pre);
+        const range = doc.createRange();
+        range.selectNodeContents(p);
+        range.collapse(true);
+        sel.removeAllRanges();
+        sel.addRange(range);
+        emit('change', element.innerHTML);
+      }
+    }
+  }
+
+  element.addEventListener('keydown', onKeydown);
+  element.addEventListener('paste', onPaste);
+  element.addEventListener('input', onInput);
+
+  function findAncestor(node: Node, tagName: string): Element | null {
+    let current: Node | null = node;
+    while (current && current !== element) {
+      if (current.nodeType === 1 && (current as Element).tagName === tagName) return current as Element;
+      current = current.parentNode;
+    }
+    return null;
+  }
+
+  function hasAncestor(node: Node, tagName: string): boolean {
+    let current: Node | null = node;
+    while (current && current !== element) {
+      if (current.nodeType === 1 && (current as Element).tagName === tagName) return true;
+      current = current.parentNode;
+    }
+    return false;
+  }
+
+  const editor: Editor = {
+    exec(command: string, value?: string): void {
+      if (!SUPPORTED_COMMANDS.has(command)) {
+        throw new Error(`Unknown editor command: "${command}"`);
+      }
+
+      element.focus();
+
+      switch (command) {
+        case 'bold':
+          doc.execCommand('bold', false);
+          break;
+        case 'italic':
+          doc.execCommand('italic', false);
+          break;
+        case 'heading': {
+          const level = value ?? '1';
+          if (!['1', '2', '3'].includes(level)) {
+            throw new Error(`Invalid heading level: "${level}". Use 1, 2, or 3`);
+          }
+          doc.execCommand('formatBlock', false, `<h${level}>`);
+          break;
+        }
+        case 'blockquote':
+          doc.execCommand('formatBlock', false, '<blockquote>');
+          break;
+        case 'unorderedList':
+          doc.execCommand('insertUnorderedList', false);
+          break;
+        case 'orderedList':
+          doc.execCommand('insertOrderedList', false);
+          break;
+        case 'link': {
+          if (!value) {
+            throw new Error('Link command requires a URL value');
+          }
+          const trimmed = value.trim();
+          if (!isProtocolAllowed(trimmed, policy.protocols)) {
+            emit('error', new Error(`Protocol not allowed: ${trimmed}`));
+            return;
+          }
+          doc.execCommand('createLink', false, trimmed);
+          break;
+        }
+        case 'unlink':
+          doc.execCommand('unlink', false);
+          break;
+        case 'codeBlock': {
+          const sel = doc.getSelection();
+          if (!sel || sel.rangeCount === 0) break;
+          const anchor = sel.anchorNode;
+          const pre = anchor ? findAncestor(anchor, 'PRE') : null;
+          if (pre) {
+            // Toggle off: unwrap <pre><code> to <p>
+            const p = doc.createElement('p');
+            p.textContent = pre.textContent || '';
+            pre.parentNode?.replaceChild(p, pre);
+            const r = doc.createRange();
+            r.selectNodeContents(p);
+            r.collapse(false);
+            sel.removeAllRanges();
+            sel.addRange(r);
+          } else {
+            // Wrap current block in <pre><code>
+            const range = sel.getRangeAt(0);
+            let block = range.startContainer;
+            while (block.parentNode && block.parentNode !== element) {
+              block = block.parentNode;
+            }
+            const pre2 = doc.createElement('pre');
+            const code = doc.createElement('code');
+            const blockText = block.textContent || '';
+            code.textContent = blockText.endsWith('\n') ? blockText : blockText + '\n';
+            pre2.appendChild(code);
+            if (block.parentNode === element) {
+              element.replaceChild(pre2, block);
+            } else {
+              element.appendChild(pre2);
+            }
+            const r = doc.createRange();
+            r.selectNodeContents(code);
+            r.collapse(false);
+            sel.removeAllRanges();
+            sel.addRange(r);
+          }
+          emit('change', element.innerHTML);
+          break;
+        }
+      }
+    },
+
+    queryState(command: string): boolean {
+      if (!SUPPORTED_COMMANDS.has(command)) {
+        throw new Error(`Unknown editor command: "${command}"`);
+      }
+
+      const sel = doc.getSelection();
+      if (!sel || sel.rangeCount === 0) return false;
+
+      const node = sel.anchorNode;
+      if (!node || !element.contains(node)) return false;
+
+      switch (command) {
+        case 'bold':
+          return hasAncestor(node, 'STRONG') || hasAncestor(node, 'B');
+        case 'italic':
+          return hasAncestor(node, 'EM') || hasAncestor(node, 'I');
+        case 'heading':
+          return hasAncestor(node, 'H1') || hasAncestor(node, 'H2') || hasAncestor(node, 'H3');
+        case 'blockquote':
+          return hasAncestor(node, 'BLOCKQUOTE');
+        case 'unorderedList':
+          return hasAncestor(node, 'UL');
+        case 'orderedList':
+          return hasAncestor(node, 'OL');
+        case 'link':
+          return hasAncestor(node, 'A');
+        case 'unlink':
+          return false;
+        case 'codeBlock':
+          return hasAncestor(node, 'PRE');
+        default:
+          return false;
+      }
+    },
+
+    getHTML(): string {
+      return element.innerHTML;
+    },
+
+    getText(): string {
+      return element.textContent ?? '';
+    },
+
+    destroy(): void {
+      element.removeEventListener('keydown', onKeydown);
+      element.removeEventListener('paste', onPaste);
+      element.removeEventListener('input', onInput);
+      enforcer.destroy();
+      element.contentEditable = 'false';
+    },
+
+    on(event: string, handler: EventHandler): void {
+      if (!handlers[event]) handlers[event] = [];
+      handlers[event].push(handler);
+    },
+  };
+
+  return editor;
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export type {
+  SanitizePolicy,
+  EditorOptions,
+  Editor,
+  ToolbarOptions,
+  Toolbar,
+} from './types';
+export { DEFAULT_POLICY } from './defaults';
+export { sanitize, sanitizeToFragment } from './sanitize';
+export { createPolicyEnforcer } from './policy';
+export type { PolicyEnforcer } from './policy';
+export { createEditor } from './editor';
+export { createToolbar } from './toolbar';

package/src/policy.ts

@@ -0,0 +1,226 @@
+import type { SanitizePolicy } from './types';
+import { TAG_NORMALIZE, URL_ATTRS, isProtocolAllowed } from './shared';
+
+export { DEFAULT_POLICY } from './defaults';
+export type { SanitizePolicy } from './types';
+
+export interface PolicyEnforcer {
+  destroy(): void;
+  on(event: 'error', handler: (error: Error) => void): void;
+}
+
+/**
+ * Get the nesting depth of a node within a root element.
+ */
+function getDepth(node: Node, root: Node): number {
+  let depth = 0;
+  let current = node.parentNode;
+  while (current && current !== root) {
+    if (current.nodeType === 1) depth++;
+    current = current.parentNode;
+  }
+  return depth;
+}
+
+/**
+ * Check if an element is allowed by the policy and fix it if not.
+ * Returns true if the node was removed/replaced.
+ */
+function enforceElement(
+  el: Element,
+  policy: SanitizePolicy,
+  root: HTMLElement,
+): boolean {
+  let tagName = el.tagName.toLowerCase();
+  const normalized = TAG_NORMALIZE[tagName];
+  if (normalized) tagName = normalized;
+
+  // Check depth
+  const depth = getDepth(el, root);
+  if (depth >= policy.maxDepth) {
+    el.parentNode?.removeChild(el);
+    return true;
+  }
+
+  // Check tag whitelist
+  const allowedAttrs = policy.tags[tagName];
+  if (allowedAttrs === undefined) {
+    if (policy.strip) {
+      el.parentNode?.removeChild(el);
+    } else {
+      // Unwrap: move children up, then remove the element
+      const parent = el.parentNode;
+      if (parent) {
+        while (el.firstChild) {
+          parent.insertBefore(el.firstChild, el);
+        }
+        parent.removeChild(el);
+      }
+    }
+    return true;
+  }
+
+  // Normalize tag if needed (e.g. <b> → <strong>)
+  let current: Element = el;
+  if (normalized && el.tagName.toLowerCase() !== normalized) {
+    const replacement = el.ownerDocument.createElement(normalized);
+    while (el.firstChild) {
+      replacement.appendChild(el.firstChild);
+    }
+    // Copy allowed attributes
+    for (const attr of Array.from(el.attributes)) {
+      replacement.setAttribute(attr.name, attr.value);
+    }
+    el.parentNode?.replaceChild(replacement, el);
+    current = replacement;
+  }
+
+  // Strip disallowed attributes
+  for (const attr of Array.from(current.attributes)) {
+    const attrName = attr.name.toLowerCase();
+
+    if (attrName.startsWith('on')) {
+      current.removeAttribute(attr.name);
+      continue;
+    }
+
+    if (!allowedAttrs.includes(attrName)) {
+      current.removeAttribute(attr.name);
+      continue;
+    }
+
+    if (URL_ATTRS.has(attrName)) {
+      if (!isProtocolAllowed(attr.value, policy.protocols)) {
+        current.removeAttribute(attr.name);
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Recursively enforce policy on all descendants of a node.
+ */
+function enforceSubtree(node: Node, policy: SanitizePolicy, root: HTMLElement): void {
+  const children = Array.from(node.childNodes);
+  for (const child of children) {
+    if (child.nodeType !== 1) {
+      // Remove non-text, non-element nodes (comments, etc.)
+      if (child.nodeType !== 3) {
+        node.removeChild(child);
+      }
+      continue;
+    }
+    const removed = enforceElement(child as Element, policy, root);
+    if (!removed) {
+      enforceSubtree(child, policy, root);
+    }
+  }
+}
+
+/**
+ * Create a policy enforcer that uses MutationObserver to enforce
+ * the sanitization policy on a live DOM element.
+ *
+ * This is defense-in-depth — the paste handler is the primary security boundary.
+ * The observer catches mutations from execCommand, programmatic DOM manipulation,
+ * and other sources.
+ */
+export function createPolicyEnforcer(
+  element: HTMLElement,
+  policy: SanitizePolicy,
+): PolicyEnforcer {
+  if (!policy || !policy.tags) {
+    throw new TypeError('Policy must have a "tags" property');
+  }
+
+  let isApplyingFix = false;
+  const errorHandlers: Array<(error: Error) => void> = [];
+
+  function emitError(error: Error): void {
+    for (const handler of errorHandlers) {
+      handler(error);
+    }
+  }
+
+  const observer = new MutationObserver((mutations) => {
+    if (isApplyingFix) return;
+    isApplyingFix = true;
+
+    try {
+      for (const mutation of mutations) {
+        if (mutation.type === 'childList') {
+          for (const node of Array.from(mutation.addedNodes)) {
+            // Skip text nodes
+            if (node.nodeType === 3) continue;
+
+            // Remove non-element nodes
+            if (node.nodeType !== 1) {
+              node.parentNode?.removeChild(node);
+              continue;
+            }
+
+            const removed = enforceElement(node as Element, policy, element);
+            if (!removed) {
+              // Also enforce on all descendants of the added node
+              enforceSubtree(node, policy, element);
+            }
+          }
+        } else if (mutation.type === 'attributes') {
+          const target = mutation.target as Element;
+          if (target.nodeType !== 1) continue;
+
+          const attrName = mutation.attributeName;
+          if (!attrName) continue;
+
+          const tagName = target.tagName.toLowerCase();
+          const normalizedTag = TAG_NORMALIZE[tagName] || tagName;
+          const allowedAttrs = policy.tags[normalizedTag];
+
+          if (!allowedAttrs) continue;
+
+          const lowerAttr = attrName.toLowerCase();
+
+          if (lowerAttr.startsWith('on')) {
+            target.removeAttribute(attrName);
+            continue;
+          }
+
+          if (!allowedAttrs.includes(lowerAttr)) {
+            target.removeAttribute(attrName);
+            continue;
+          }
+
+          if (URL_ATTRS.has(lowerAttr)) {
+            const value = target.getAttribute(attrName);
+            if (value && !isProtocolAllowed(value, policy.protocols)) {
+              target.removeAttribute(attrName);
+            }
+          }
+        }
+      }
+    } catch (err) {
+      emitError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      isApplyingFix = false;
+    }
+  });
+
+  observer.observe(element, {
+    childList: true,
+    attributes: true,
+    subtree: true,
+  });
+
+  return {
+    destroy() {
+      observer.disconnect();
+    },
+    on(event: 'error', handler: (error: Error) => void) {
+      if (event === 'error') {
+        errorHandlers.push(handler);
+      }
+    },
+  };
+}