@llui/markdown-editor 0.2.12 → 0.2.14

package/src/security.ts

@@ -0,0 +1,89 @@
+// URL-scheme policy for the editor.
+//
+// The read-only renderer (`@llui/markdown`) already refuses dangerous link/image
+// schemes (`javascript:`, `vbscript:`, `data:text/html`, …) via `sanitizeUrl`.
+// The EDITOR has additional ingress points that must enforce the SAME policy or
+// an attacker-authored document becomes live/clickable inside it:
+//
+//   1. link commit           — `$toggleLink` on a raw, user-typed URL,
+//   2. image src             — an `![alt](src)` inserted or imported,
+//   3. markdown paste/import — `$convertFromMarkdownString` builds real
+//      `LinkNode`s (and image decorator nodes) from untrusted text,
+//   4. the typed `[x](url)`  markdown shortcut — builds a `LinkNode` live.
+//
+// Links are additionally guarded by a global `LinkNode` node transform
+// ({@link registerLinkSanitizer}) so #1/#3/#4 all funnel through one enforcement
+// point. Rather than hand-roll (and drift from) a second allowlist, this module
+// reuses `@llui/markdown`'s exact `sanitizeUrl` and only differs in the
+// allowed-scheme SET per surface — which is data, not a divergent implementation.
+
+import { sanitizeUrl, defaultAllowedProtocols } from '@llui/markdown/security'
+import { $isLinkNode, LinkNode } from '@lexical/link'
+import { $isElementNode, type LexicalEditor, type LexicalNode } from 'lexical'
+
+/** Schemes allowed for a hyperlink href. A click navigates, so this is the strict
+ * set — identical to the renderer's default (`http`/`https`/`mailto`/`tel`). */
+export const LINK_PROTOCOLS: readonly string[] = defaultAllowedProtocols
+
+/** Schemes allowed for an image `src`. Adds `data:` on top of the link set: a
+ * base64 image never executes when loaded through `<img>` (unlike a `data:`
+ * hyperlink, which can carry `text/html`), and inline data images are a
+ * first-class editor feature (paste / upload). */
+export const IMAGE_PROTOCOLS: readonly string[] = [...defaultAllowedProtocols, 'data']
+
+/** Sanitize a hyperlink href. Returns the safe URL, or `null` when the scheme is
+ * not on {@link LINK_PROTOCOLS} (the link must then be dropped/unwrapped). */
+export function sanitizeLinkUrl(url: string): string | null {
+  return sanitizeUrl(url, LINK_PROTOCOLS)
+}
+
+/** Sanitize an image `src`. Returns the safe URL, or `null` when the scheme is
+ * not on {@link IMAGE_PROTOCOLS} (the image must then be dropped). */
+export function sanitizeImageUrl(url: string): string | null {
+  return sanitizeUrl(url, IMAGE_PROTOCOLS)
+}
+
+/** Neutralize one `LinkNode` in place (must run inside `editor.update`): rewrite a
+ * merely-normalized href, or — when the scheme is disallowed — UNWRAP the link so
+ * its visible text survives but the clickable `javascript:`/`data:` payload is
+ * gone. Returns true if the node was unwrapped/removed. */
+function neutralizeLink(node: LinkNode): boolean {
+  const url = node.getURL()
+  const safe = sanitizeLinkUrl(url)
+  if (safe === null) {
+    for (const child of node.getChildren()) node.insertBefore(child)
+    node.remove()
+    return true
+  }
+  if (safe !== url) node.setURL(safe)
+  return false
+}
+
+/** Walk `node` (depth-first) neutralizing every unsafe `LinkNode` beneath it. Must
+ * run inside an `editor.update`. Use right after importing untrusted markdown
+ * (e.g. paste) into a detached scratch tree, before it reaches the live document. */
+export function $sanitizeLinkNodes(node: LexicalNode): void {
+  if ($isLinkNode(node)) {
+    // Snapshot children first: unwrapping lifts them out of the (removed) link,
+    // so recurse the snapshot to catch a defensively-nested inner link either way.
+    const children = node.getChildren()
+    neutralizeLink(node)
+    for (const child of children) $sanitizeLinkNodes(child)
+    return
+  }
+  if ($isElementNode(node)) {
+    for (const child of node.getChildren()) $sanitizeLinkNodes(child)
+  }
+}
+
+/** Register a global `LinkNode` transform that keeps every link's href on the
+ * allowlist — the single choke point covering the link dialog, pasted/imported
+ * markdown, AND the typed `[text](url)` shortcut. Returns a disposer. A no-op when
+ * `LinkNode` isn't registered on the editor (no links are possible then, e.g. the
+ * single-block preset), since `registerNodeTransform` requires a registered node. */
+export function registerLinkSanitizer(editor: LexicalEditor): () => void {
+  if (!editor.hasNodes([LinkNode])) return () => {}
+  return editor.registerNodeTransform(LinkNode, (node) => {
+    neutralizeLink(node)
+  })
+}

package/src/state.ts

@@ -0,0 +1,220 @@
+// The editor's TEA state, messages, effects, and pure reducer. Lexical owns the
+// live document; this state holds JSON-serializable mirrors/derivations only, so
+// `update` stays pure and DOM-free (fully unit-testable).
+
+import type { Alignment } from '@llui/lexical'
+
+/** The block kind at the selection — base rich-text kinds plus list/code,
+ * resolved by the markdown layer. */
+export type BlockType =
+  | 'paragraph'
+  | 'h1'
+  | 'h2'
+  | 'h3'
+  | 'h4'
+  | 'h5'
+  | 'h6'
+  | 'quote'
+  | 'code'
+  | 'bullet'
+  | 'number'
+  | 'check'
+  | 'other'
+
+/** The toolbar-facing format surface at the current selection (all primitives). */
+export interface FormatState {
+  bold: boolean
+  italic: boolean
+  strikethrough: boolean
+  code: boolean
+  link: boolean
+  blockType: BlockType
+  alignment: Alignment
+  canUndo: boolean
+  canRedo: boolean
+}
+
+export const EMPTY_FORMAT: FormatState = {
+  bold: false,
+  italic: false,
+  strikethrough: false,
+  code: false,
+  link: false,
+  blockType: 'paragraph',
+  alignment: null,
+  canUndo: false,
+  canRedo: false,
+}
+
+/** Which floating surface is currently open. */
+export type OverlayKind = 'none' | 'floating' | 'slash' | 'context' | 'link'
+
+/** Live collaborative-session status (mirror of the CRDT provider state).
+ * `enabled` is false unless the editor was created with a `collab` factory. */
+export interface CollabStatus {
+  enabled: boolean
+  connected: boolean
+  synced: boolean
+  /** Remote peers currently present (excludes this client). */
+  peers: number
+}
+
+export const COLLAB_OFF: CollabStatus = {
+  enabled: false,
+  connected: false,
+  synced: false,
+  peers: 0,
+}
+
+export interface EditorState {
+  /** Last serialized markdown (mirror of the live document). */
+  value: string
+  format: FormatState
+  wordCount: number
+  charCount: number
+  ui: {
+    activeOverlay: OverlayKind
+    slashQuery: string
+    menu: { x: number; y: number }
+  }
+  /** Per-plugin UI state slices, keyed by plugin name (see {@link PluginUI}). */
+  plugins: Record<string, unknown>
+  dirty: boolean
+  readonly: boolean
+  /** Collaborative-session status (always present; inert unless `collab` set). */
+  collab: CollabStatus
+}
+
+export type EditorMsg =
+  | { type: 'markdownChanged'; value: string }
+  | { type: 'formatChanged'; format: FormatState; wordCount: number; charCount: number }
+  | { type: 'runCommand'; id: string }
+  | { type: 'setValue'; value: string }
+  | { type: 'openOverlay'; overlay: OverlayKind; x?: number; y?: number }
+  | { type: 'closeOverlay' }
+  | { type: 'slashQuery'; query: string }
+  | { type: 'setReadOnly'; readonly: boolean }
+  | { type: 'collabStatus'; connected: boolean }
+  | { type: 'collabSync'; synced: boolean }
+  | { type: 'collabPeers'; peers: number }
+  /** Route a message to a plugin's UI reducer (see {@link PluginUI}). */
+  | { type: 'plugin'; name: string; msg: unknown }
+
+/** The subset of messages a plugin may emit through its `PluginContext` (e.g. a
+ * `register` listener routing an editor event into its own plugin UI). */
+export type EditorOutMsg = Extract<
+  EditorMsg,
+  { type: 'openOverlay' | 'closeOverlay' | 'slashQuery' | 'plugin' }
+>
+
+export type EditorEffect =
+  | { type: 'execCommand'; id: string }
+  | { type: 'applyValue'; value: string }
+  | { type: 'emitChange'; value: string }
+  | { type: 'emitFormat'; format: FormatState }
+  /** An effect produced by a plugin's UI reducer (see {@link PluginUI}). */
+  | { type: 'pluginEffect'; name: string; effect: unknown }
+
+export interface InitOptions {
+  value: string
+  readonly: boolean
+  /** Whether a collaborative session is wired (drives `collab.enabled`). */
+  collab?: boolean
+}
+
+export function init(opts: InitOptions): [EditorState, EditorEffect[]] {
+  const wordCount = countWords(opts.value)
+  return [
+    {
+      value: opts.value,
+      format: EMPTY_FORMAT,
+      wordCount,
+      charCount: opts.value.length,
+      ui: { activeOverlay: 'none', slashQuery: '', menu: { x: 0, y: 0 } },
+      plugins: {},
+      dirty: false,
+      readonly: opts.readonly,
+      collab: { ...COLLAB_OFF, enabled: opts.collab ?? false },
+    },
+    [],
+  ]
+}
+
+export function update(state: EditorState, msg: EditorMsg): [EditorState, EditorEffect[]] {
+  switch (msg.type) {
+    case 'markdownChanged': {
+      // Idempotent: re-emitting the current value is a no-op (echo safety).
+      if (msg.value === state.value) return [state, []]
+      return [
+        { ...state, value: msg.value, dirty: true },
+        [{ type: 'emitChange', value: msg.value }],
+      ]
+    }
+    case 'formatChanged': {
+      return [
+        { ...state, format: msg.format, wordCount: msg.wordCount, charCount: msg.charCount },
+        [{ type: 'emitFormat', format: msg.format }],
+      ]
+    }
+    case 'runCommand': {
+      return [state, [{ type: 'execCommand', id: msg.id }]]
+    }
+    case 'setValue': {
+      // External markdown push (via the component handle). Idempotent; does not
+      // re-emit onChange (the consumer already owns this value).
+      if (msg.value === state.value) return [state, []]
+      return [
+        { ...state, value: msg.value, dirty: true },
+        [{ type: 'applyValue', value: msg.value }],
+      ]
+    }
+    case 'openOverlay': {
+      return [
+        {
+          ...state,
+          ui: {
+            ...state.ui,
+            activeOverlay: msg.overlay,
+            slashQuery: msg.overlay === 'slash' ? '' : state.ui.slashQuery,
+            menu: { x: msg.x ?? state.ui.menu.x, y: msg.y ?? state.ui.menu.y },
+          },
+        },
+        [],
+      ]
+    }
+    case 'closeOverlay': {
+      if (state.ui.activeOverlay === 'none') return [state, []]
+      return [{ ...state, ui: { ...state.ui, activeOverlay: 'none', slashQuery: '' } }, []]
+    }
+    case 'slashQuery': {
+      return [{ ...state, ui: { ...state.ui, slashQuery: msg.query } }, []]
+    }
+    case 'setReadOnly': {
+      if (state.readonly === msg.readonly) return [state, []]
+      return [{ ...state, readonly: msg.readonly }, []]
+    }
+    case 'collabStatus': {
+      if (state.collab.connected === msg.connected) return [state, []]
+      return [{ ...state, collab: { ...state.collab, connected: msg.connected } }, []]
+    }
+    case 'collabSync': {
+      if (state.collab.synced === msg.synced) return [state, []]
+      return [{ ...state, collab: { ...state.collab, synced: msg.synced } }, []]
+    }
+    case 'collabPeers': {
+      if (state.collab.peers === msg.peers) return [state, []]
+      return [{ ...state, collab: { ...state.collab, peers: msg.peers } }, []]
+    }
+    case 'plugin': {
+      // Plugin messages are routed by the host's composed reducer (it holds the
+      // plugin registry); the pure core reducer treats them as a no-op.
+      return [state, []]
+    }
+  }
+}
+
+/** Count whitespace-delimited words (shared by init and the format handler). */
+export function countWords(text: string): number {
+  const trimmed = text.trim()
+  return trimmed === '' ? 0 : trimmed.split(/\s+/).length
+}