Add Markdown text escaping

CHANGELOG.md

@@ -4,6 +4,10 @@
 
 ## [Unreleased]
 
+### Changed
+
+- Markdown export now escapes user-controlled text and link destinations following CommonMark rules, and sizes code span/block delimiters to their content. Markdown output containing metacharacters changes as a result. See [Markdown escaping](https://wagtail.github.io/draftjs_exporter/markdown/#escaping).
+
 ## [v6.0.0](https://github.com/wagtail/draftjs_exporter/releases/tag/v6.0.0)
 
 ### Added

docs/SECURITY.md

@@ -47,6 +47,7 @@ Out of scope. Depends entirely on the integrating application.
 - **Entity `data` is passed straight through into element attributes.** [`EntityState.render_entities`](https://github.com/wagtail/draftjs_exporter/blob/main/draftjs_exporter/entity_state.py) copies `entity_details["data"]` into the props of the element the entity decorator renders, e.g. a `LINK` entity's `url` typically becomes an `href`. Attribute values are HTML-escaped by every engine (`html.escape` in the `string` engine, BeautifulSoup/lxml elsewhere), which prevents attribute/quote breakout, but the library doesn't validate URL schemes. A malicious `"data": {"url": "javascript:alert(1)"}` will render as `href="javascript:alert(1)"` verbatim. Entity decorators that emit `href`, `src`, or similar URL-bearing attributes must validate the scheme (allow-list `http`/`https`/`mailto`) themselves.
 - **`style` props are interpolated without CSS validation.** A style dict is converted to an inline `style="..."` string by joining property/value pairs; values aren’t validated as safe CSS, only escaped for the surrounding attribute quotes. Entity/decorator code that forwards untrusted `data` into `style` props can inject arbitrary CSS declarations (e.g. `url()`-based exfiltration).
 - **`DOM.parse_html()` / `Elt.from_html()` intentionally bypass escaping.** This exists so integrators can render pre-sanitized, developer-controlled HTML fragments. If a decorator instead feeds it attacker-controlled text (e.g. raw entity data), that text is emitted into the page unescaped. That’s a stored-XSS vector. Never call `parse_html` with data sourced from ContentState.
+- **The Markdown engine escapes user-controlled text and link destinations.** Block text is backslash-escaped following CommonMark rules (including at line starts, so attacker text cannot inject headings, lists, blockquotes, or link syntax), and URLs emitted into `](…)` destinations have `\`, `(`, `)` escaped and control characters percent-encoded. URL scheme validation remains the integrator's responsibility, exactly as for HTML output: a `"data": {"url": "javascript:alert(1)"}` renders as `[text](javascript:alert(1))` verbatim.
 
 ### Repudiation
 

docs/markdown.md

@@ -148,6 +148,20 @@ config = {
 }
 ```
 
+## Escaping
+
+The Markdown exporter escapes user-controlled text so it renders literally rather than as Markdown syntax, following CommonMark backslash-escape rules. This is always on; there is no configuration option.
+
+- Anywhere in text: `\`, `` ` ``, `*`, `_`, `[`, `]`, `<`, `&`.
+- At the start of a line: `#`, `-`, `+`, `>`, `=`, `|`, `~`, and ordered list markers like `1.` (rendered as `1\.`). "Start of a line" means the start of a block, after any line ending (`\n`, `\r\n`, or a lone `\r`), or after a list/blockquote marker. The line-start rules also apply after any leading run of spaces, since CommonMark allows block constructs to be indented.
+- Link and image URLs inside `](…)` get destination-specific escaping: `\`, `(`, `)` are backslash-escaped and whitespace/control characters are percent-encoded. URL scheme validation (`javascript:` etc.) remains the integrating application's responsibility.
+- Code spans and code blocks are never escaped. Instead, the exporter sizes the delimiters to the content: a code span containing a backtick is wrapped in double backticks, and a code block containing a fence gets a fence one character longer.
+
+Limitations:
+
+- Text starting with four or more spaces or a tab may render as an indented code block downstream. Backslash escapes cannot protect leading whitespace.
+- GFM-only syntax other than tables (`|`) is not escaped — for example autolinkable bare URLs remain autolinkable.
+
 ## Unsupported
 
 The Markdown exporter has inherent limitations compared to the HTML exporter.
@@ -157,5 +171,4 @@ The Markdown exporter has inherent limitations compared to the HTML exporter.
 - **No table support**: Draft.js has no built-in table block type, and the exporter does not attempt to generate Markdown tables from custom block types.
 - **No Setext-style headings**: Headings always use ATX style (`# Heading`).
 - **Entity data fidelity**: The Markdown link syntax `[text](url)` only preserves the URL.
-- **No HTML escaping in text**: If your Draft.js content contains literal HTML characters like like `<` or `>`, the Markdown output will include them unescaped, which may be interpreted as HTML by Markdown renderers.
 - **Inline style nesting edge cases**: When bold and italic styles partially overlap, the exporter may produce markers that some strict Markdown parsers reject (e.g. `**Bold **_Italic_**`). Most renderers handle this correctly, but it is not guaranteed by the CommonMark spec.

docs/migration-guide.md

@@ -2,6 +2,14 @@
 
 This page collects the upgrade notes for each major (and selected minor) release of the exporter. Each section describes the breaking changes and the steps to follow when upgrading from the previous version. For the full list of changes in each release, see the [CHANGELOG](https://github.com/wagtail/draftjs_exporter/blob/main/CHANGELOG.md).
 
+## Upgrading to v6.1.0
+
+### Markdown export now escapes text
+
+The Markdown exporter now escapes user-controlled text and link destinations following CommonMark rules, so content like `#`, `[`, `<`, or `&` in block text renders literally instead of being interpreted as Markdown or HTML. Code spans and code blocks are not escaped; their delimiters are instead sized to the content, which also fixes output corruption when code content contains backticks or fences.
+
+Any Markdown output containing metacharacters in text changes. If your tests compare exact Markdown output, update them. Markdown support remains experimental.
+
 ## Upgrading to v6.0.0
 
 ### Python 3.7, 3.8, and 3.9 support removed

draftjs_exporter/engines/markdown.py

@@ -3,6 +3,11 @@
 from html import escape
 
 from draftjs_exporter.engines.base import Attr, DOMEngine
+from draftjs_exporter.markdown.escape import (
+    code_block_fence,
+    code_span_delimiters,
+    escape_text,
+)
 from draftjs_exporter.types import HTML, Tag
 
 # http://w3c.github.io/html/single-page.html#void-elements
@@ -28,7 +33,9 @@
 class Elt:
     """A DOM element that the Markdown engine manipulates.
 
-    Identical to the string engine's Elt, but rendering does not escape text.
+    Identical to the string engine's Elt, with extra Markdown-specific node
+    types: ``mark_safe`` (structural syntax rendered verbatim), ``code_span``
+    and ``code_block`` (content rendered unescaped with sized delimiters).
     """
 
     __slots__ = ("type", "attr", "children", "markup")
@@ -60,7 +67,12 @@ def from_html(markup: HTML) -> "Elt":
 
 
 class DOMMarkdown(DOMEngine):
-    """String concatenation implementation of the DOM API for Markdown output."""
+    """String concatenation implementation of the DOM API for Markdown output.
+
+    Invariant: a plain ``str`` child in the tree is always user-controlled
+    text. Structural Markdown syntax must be wrapped in ``mark_safe``
+    elements by components, or it will be escaped as text.
+    """
 
     @staticmethod
     def create_tag(type_: Tag, attr: Attr | None = None) -> Elt:
@@ -118,17 +130,66 @@ def render_attrs(attr: Attr) -> str:
 
     @staticmethod
     def render_children(children: list[HTML | Elt]) -> HTML:
-        """Render a list of children to a string without escaping text.
+        """Render a list of children, escaping plain strings as user text.
+
+        A plain ``str`` child is always user-controlled text and is escaped.
+        Structural syntax wrapped in ``mark_safe`` elements renders verbatim.
+        Line-start-sensitive characters are escaped when a string begins a
+        line: at the start of the children list, when the output so far ends
+        with a newline or carriage return, or right after a ``mark_safe``
+        element created with ``block_prefix``.
 
         Parameters:
             children: A list of strings and elements to render.
 
         Returns:
-            The concatenated child content.
+            The rendered children.
+        """
+        out: list[str] = []
+        at_line_start = True
+        for c in children:
+            if isinstance(c, Elt):
+                rendered = DOMMarkdown.render(c)
+                out.append(rendered)
+                if (
+                    c.type == "mark_safe"
+                    and c.attr
+                    and c.attr.get("block_prefix") == "true"
+                ):
+                    at_line_start = True
+                elif rendered:
+                    at_line_start = rendered.endswith(("\n", "\r"))
+            else:
+                out.append(escape_text(c, at_line_start))
+                if c:
+                    at_line_start = c.endswith(("\n", "\r"))
+        return "".join(out)
+
+    @staticmethod
+    def flatten_text(children: list["str | Elt"]) -> str:
+        """Flatten children to raw text, discarding element structure.
+
+        ``mark_safe`` and ``escaped_html`` markup is included verbatim;
+        other elements contribute only their text content.
+
+        Parameters:
+            children: A list of strings and elements.
+
+        Returns:
+            The concatenated raw text.
         """
-        return "".join(
-            [DOMMarkdown.render(c) if isinstance(c, Elt) else c for c in children]
-        )
+        parts = []
+        for c in children:
+            if isinstance(c, Elt):
+                if c.type == "mark_safe":
+                    parts.append(c.attr["markup"] if c.attr else "")
+                elif c.markup:
+                    parts.append(c.markup)
+                else:
+                    parts.append(DOMMarkdown.flatten_text(c.children))
+            else:
+                parts.append(c)
+        return "".join(parts)
 
     @staticmethod
     def render(elt: Elt) -> HTML:
@@ -150,8 +211,19 @@ def render(elt: Elt) -> HTML:
         match type_:
             case "fragment":
                 return children
+            case "mark_safe":
+                return elt.attr["markup"] if elt.attr else ""
             case "escaped_html":
                 return elt.markup
+            case "code_span":
+                content = DOMMarkdown.flatten_text(elt.children)
+                opening, closing = code_span_delimiters(content)
+                return f"{opening}{content}{closing}"
+            case "code_block":
+                content = DOMMarkdown.flatten_text(elt.children)
+                fence_char = (elt.attr or {}).get("fence", "`")
+                fence = code_block_fence(content, fence_char)
+                return f"{fence}\n{content}{fence}\n\n"
             case _ if type_ in VOID_ELEMENTS:
                 return f"<{type_}{attr}/>"
             case _:

draftjs_exporter/markdown/__init__.py

@@ -35,7 +35,7 @@
     entity_fallback,
     style_fallback,
 )
-from draftjs_exporter.markdown.styles import inline_style
+from draftjs_exporter.markdown.styles import code_span, inline_style
 from draftjs_exporter.types import Component, ConfigMap
 
 
@@ -72,7 +72,7 @@ class MarkdownOptions(TypedDict, total=False):
             "element": ol,
             "wrapper": list_wrapper,
         },
-        BLOCK_TYPES.BLOCKQUOTE: prefixed_block("> "),
+        BLOCK_TYPES.BLOCKQUOTE: prefixed_block("> ", block_prefix=True),
         BLOCK_TYPES.CODE: {
             "element": code_element,
             "wrapper": code_wrapper,
@@ -85,7 +85,7 @@ class MarkdownOptions(TypedDict, total=False):
     HTML_STYLE_MAP,
     **{
         INLINE_STYLES.BOLD: inline_style("**"),
-        INLINE_STYLES.CODE: inline_style("`"),
+        INLINE_STYLES.CODE: code_span,
         INLINE_STYLES.ITALIC: inline_style("_"),
         INLINE_STYLES.STRIKETHROUGH: inline_style("~"),
         INLINE_STYLES.FALLBACK: style_fallback,
@@ -147,9 +147,9 @@ def build_markdown_config(options: MarkdownOptions | None = None) -> ExporterCon
             "element": make_ol(ol_delimiter),
             "wrapper": list_wrapper,
         },
-        BLOCK_TYPES.BLOCKQUOTE: prefixed_block("> "),
+        BLOCK_TYPES.BLOCKQUOTE: prefixed_block("> ", block_prefix=True),
         BLOCK_TYPES.CODE: {
-            "element": make_code_element(fence),
+            "element": make_code_element(),
             "wrapper": make_code_wrapper(fence),
         },
         BLOCK_TYPES.ATOMIC: lambda props: props["children"],
@@ -158,7 +158,7 @@ def build_markdown_config(options: MarkdownOptions | None = None) -> ExporterCon
     style_map: ConfigMap = {
         **HTML_STYLE_MAP,
         INLINE_STYLES.BOLD: inline_style(bold),
-        INLINE_STYLES.CODE: inline_style("`"),
+        INLINE_STYLES.CODE: code_span,
         INLINE_STYLES.ITALIC: inline_style(italic),
         INLINE_STYLES.STRIKETHROUGH: inline_style(strikethrough),
     }

draftjs_exporter/markdown/blocks.py

@@ -1,20 +1,24 @@
 """Markdown block-level components: headings, lists, blockquotes, and plain paragraphs."""
 
-from draftjs_exporter.markdown.helpers import block, inline
+from draftjs_exporter.markdown.helpers import block, inline, mark_safe
 from draftjs_exporter.markdown.lists import list_item, make_numbered_li_prefix
 from draftjs_exporter.types import Component, Element, Props
 
 
-def prefixed_block(prefix: str) -> Component:
+def prefixed_block(prefix: str, block_prefix: bool = False) -> Component:
     """Create a block component that prefixes its children with the given string.
 
     Parameters:
         prefix: The literal prefix to insert before the block's children.
+        block_prefix: Whether children can start a nested block after the
+            prefix (true for blockquotes, false for headings).
 
     Returns:
         A component that renders the prefixed block.
     """
-    return lambda props: block([prefix, props["children"]])
+    return lambda props: block(
+        [mark_safe(prefix, block_prefix=block_prefix), props["children"]]
+    )
 
 
 def make_ul(marker: str) -> Component:

draftjs_exporter/markdown/code.py

@@ -1,26 +1,22 @@
 """Markdown code block components and fenced code builders."""
 
 from draftjs_exporter.dom import DOM
-from draftjs_exporter.markdown.lists import get_li_suffix
+from draftjs_exporter.markdown.helpers import mark_safe
 from draftjs_exporter.types import Component, Element, Props
 
 
-def make_code_element(fence: str) -> Component:
-    """Create a code-block element component using the given fence.
+def make_code_element() -> Component:
+    """Create a code-block line component.
 
-    Parameters:
-        fence: The delimiter to use at the closing of the code block.
+    Each Draft.js code block contributes one line to the shared code_block
+    node created by the wrapper.
 
     Returns:
-        A component that renders the contents and closing fence of a code block.
+        A component that renders one line of code block content.
     """
 
     def element(props: Props) -> Element:
-        suffix = get_li_suffix(props)
-        block_end = f"\n{fence}" if suffix == "\n\n" else ""
-        return DOM.create_element(
-            "fragment", {}, [props["children"], block_end, suffix]
-        )
+        return DOM.create_element("fragment", {}, [props["children"], mark_safe("\n")])
 
     return element
 
@@ -29,14 +25,15 @@ def make_code_wrapper(fence: str) -> Component:
     """Create a code-block wrapper component using the given fence.
 
     Parameters:
-        fence: The delimiter to place at the start of the code block.
+        fence: The fence delimiter; its first character sizes the rendered
+            fence (`` ``` `` or ``~~~``).
 
     Returns:
-        A component that renders only the opening fence.
+        A component that creates the code_block node holding all lines.
     """
-    prefix = f"{fence}\n"
-    return lambda props: DOM.create_element("fragment", {}, [prefix])
+    fence_char = fence[0]
+    return lambda props: DOM.create_element("code_block", {"fence": fence_char})
 
 
-code_element: Component = make_code_element("```")
+code_element: Component = make_code_element()
 code_wrapper: Component = make_code_wrapper("```")

draftjs_exporter/markdown/entities.py

@@ -1,6 +1,6 @@
 """Markdown entity decorators for images, links, and horizontal rules."""
 
-from draftjs_exporter.markdown.helpers import block, inline
+from draftjs_exporter.markdown.helpers import block, inline, link_destination, mark_safe
 from draftjs_exporter.types import Component, Element, Props
 
 
@@ -13,7 +13,15 @@ def image(props: Props) -> Element:
     Returns:
         A block-level image element.
     """
-    return block(["![", props.get("alt", ""), "](", props["src"], ")"])
+    return block(
+        [
+            mark_safe("!["),
+            props.get("alt", ""),
+            mark_safe("]("),
+            link_destination(props["src"]),
+            mark_safe(")"),
+        ]
+    )
 
 
 def link(props: Props) -> Element:
@@ -25,7 +33,15 @@ def link(props: Props) -> Element:
     Returns:
         An inline link element.
     """
-    return inline(["[", props["children"], "](", props["url"], ")"])
+    return inline(
+        [
+            mark_safe("["),
+            props["children"],
+            mark_safe("]("),
+            link_destination(props["url"]),
+            mark_safe(")"),
+        ]
+    )
 
 
 def make_horizontal_rule(marker: str) -> Component:
@@ -37,7 +53,7 @@ def make_horizontal_rule(marker: str) -> Component:
     Returns:
         A component that renders a horizontal rule.
     """
-    return lambda props: block([marker])
+    return lambda props: block([mark_safe(marker)])
 
 
 horizontal_rule: Component = make_horizontal_rule("---")