parley_markup/

lib.rs

//! Renders untrusted markdown into a typed tree that cannot carry markup.
//!
//! Message bodies are attacker-controlled. In the CLI they land in a
//! terminal; in a webview they land somewhere that can execute code, and
//! a sender who achieves script execution there is inside the trust
//! boundary and can read and exfiltrate every conversation. That is
//! strictly worse than compromising the relay, which only ever sees
//! ciphertext.
//!
//! So this crate never produces an HTML string. It produces [`Node`] and
//! [`Inline`] values that a renderer maps to elements, which means there
//! is no string for an injection to hide in and no `innerHTML` at the far
//! end. Three rules do the work:
//!
//! 1. **Raw HTML is text, not markup.** `pulldown-cmark` emits embedded
//!    HTML as its own event; those become [`Inline::Text`] verbatim. A
//!    body containing `<script>` renders those characters on screen.
//! 2. **Link targets are allowlisted** to `http`, `https`, and `mailto`.
//!    Anything else (`javascript:`, `data:`, `vbscript:`, `file:`) loses
//!    its link and keeps its text, so the content survives and the
//!    navigation does not.
//! 3. **Remote images are not fetched.** This is privacy, not just
//!    safety: an inlined remote image is a read receipt telling the
//!    sender when you opened a message and from which IP. They arrive as
//!    [`ImageSource::Blocked`] for the UI to offer as click-to-load.

use pulldown_cmark::{Event, HeadingLevel, Options, Parser, Tag, TagEnd};
use serde::{Deserialize, Serialize};

/// Schemes a link may navigate to. Everything else is stripped.
const ALLOWED_SCHEMES: [&str; 3] = ["http", "https", "mailto"];

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum Node {
    Paragraph {
        content: Vec<Inline>,
    },
    Heading {
        level: u8,
        content: Vec<Inline>,
    },
    List {
        ordered: bool,
        items: Vec<Vec<Node>>,
    },
    CodeBlock {
        language: Option<String>,
        code: String,
    },
    BlockQuote {
        content: Vec<Node>,
    },
    Rule,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum Inline {
    Text {
        text: String,
    },
    Code {
        code: String,
    },
    Emphasis {
        content: Vec<Inline>,
    },
    Strong {
        content: Vec<Inline>,
    },
    Strikethrough {
        content: Vec<Inline>,
    },
    /// A link whose target already passed the scheme allowlist.
    Link {
        href: String,
        content: Vec<Inline>,
    },
    Image {
        source: ImageSource,
        alt: String,
    },
    SoftBreak,
    HardBreak,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum ImageSource {
    /// Already on disk and end-to-end encrypted in transit: a received
    /// file. Safe to render inline; fetching it tells nobody anything.
    Local { path: String },
    /// Off-machine. Never fetched automatically, because loading it would
    /// report back to whoever controls that host. Retained so a UI can
    /// offer an explicit click-to-load.
    Blocked { url: String },
}

/// Parse `markdown` into a tree that carries no markup.
#[must_use]
pub fn render(markdown: &str) -> Vec<Node> {
    let mut options = Options::empty();
    options.insert(Options::ENABLE_STRIKETHROUGH);
    options.insert(Options::ENABLE_TABLES);
    options.insert(Options::ENABLE_FOOTNOTES);
    // Deliberately NOT enabling any option that widens what the parser
    // will treat as markup.

    let mut blocks = Vec::new();
    let mut parser = Parser::new_ext(markdown, options).peekable();
    while let Some(event) = parser.next() {
        if let Some(node) = block(&mut parser, event) {
            blocks.push(node);
        }
    }
    blocks
}

type EventStream<'a> = std::iter::Peekable<Parser<'a>>;

fn block(p: &mut EventStream<'_>, event: Event<'_>) -> Option<Node> {
    match event {
        Event::Start(Tag::Paragraph) => Some(Node::Paragraph {
            content: inlines(p, TagEnd::Paragraph),
        }),
        Event::Start(Tag::Heading { level, .. }) => Some(Node::Heading {
            level: heading_level(level),
            content: inlines(p, TagEnd::Heading(level)),
        }),
        Event::Start(Tag::CodeBlock(kind)) => {
            let language = match kind {
                pulldown_cmark::CodeBlockKind::Fenced(l) if !l.is_empty() => Some(l.to_string()),
                _ => None,
            };
            let mut code = String::new();
            for e in p.by_ref() {
                match e {
                    // Inside a fence everything is literal, including
                    // anything that looks like a tag.
                    Event::Text(t) | Event::Html(t) | Event::InlineHtml(t) => code.push_str(&t),
                    Event::End(TagEnd::CodeBlock) => break,
                    _ => {}
                }
            }
            Some(Node::CodeBlock { language, code })
        }
        Event::Start(Tag::BlockQuote(_)) => {
            let mut content = Vec::new();
            while let Some(e) = p.next() {
                if matches!(e, Event::End(TagEnd::BlockQuote(_))) {
                    break;
                }
                if let Some(n) = block(p, e) {
                    content.push(n);
                }
            }
            Some(Node::BlockQuote { content })
        }
        Event::Start(Tag::List(start)) => {
            let ordered = start.is_some();
            let mut items = Vec::new();
            while let Some(e) = p.next() {
                match e {
                    Event::Start(Tag::Item) => {
                        let mut item = Vec::new();
                        while let Some(ie) = p.next() {
                            if matches!(ie, Event::End(TagEnd::Item)) {
                                break;
                            }
                            // A bare item body arrives as loose inlines
                            // rather than a paragraph; wrap it so items
                            // always hold blocks.
                            if let Some(n) = block(p, ie.clone()) {
                                item.push(n);
                            } else if let Some(inline) = inline_of(&ie) {
                                match item.last_mut() {
                                    Some(Node::Paragraph { content }) => content.push(inline),
                                    _ => item.push(Node::Paragraph {
                                        content: vec![inline],
                                    }),
                                }
                            }
                        }
                        items.push(item);
                    }
                    Event::End(TagEnd::List(_)) => break,
                    _ => {}
                }
            }
            Some(Node::List { ordered, items })
        }
        Event::Rule => Some(Node::Rule),
        // A stray inline at block level (common for one-line bodies).
        other => inline_of(&other).map(|i| Node::Paragraph { content: vec![i] }),
    }
}

fn inlines(p: &mut EventStream<'_>, until: TagEnd) -> Vec<Inline> {
    let mut out = Vec::new();
    while let Some(e) = p.next() {
        if e == Event::End(until) {
            break;
        }
        match e {
            Event::Start(Tag::Emphasis) => out.push(Inline::Emphasis {
                content: inlines(p, TagEnd::Emphasis),
            }),
            Event::Start(Tag::Strong) => out.push(Inline::Strong {
                content: inlines(p, TagEnd::Strong),
            }),
            Event::Start(Tag::Strikethrough) => out.push(Inline::Strikethrough {
                content: inlines(p, TagEnd::Strikethrough),
            }),
            Event::Start(Tag::Link { dest_url, .. }) => {
                let content = inlines(p, TagEnd::Link);
                match sanitize_href(&dest_url) {
                    // Target rejected: keep what it said, drop where it went.
                    None => out.extend(content),
                    Some(href) => out.push(Inline::Link { href, content }),
                }
            }
            Event::Start(Tag::Image { dest_url, .. }) => {
                let alt = plain_text(&inlines(p, TagEnd::Image));
                out.push(Inline::Image {
                    source: image_source(&dest_url),
                    alt,
                });
            }
            other => {
                if let Some(i) = inline_of(&other) {
                    out.push(i);
                }
            }
        }
    }
    out
}

fn inline_of(e: &Event<'_>) -> Option<Inline> {
    match e {
        Event::Text(t) => Some(Inline::Text {
            text: t.to_string(),
        }),
        Event::Code(c) => Some(Inline::Code {
            code: c.to_string(),
        }),
        // The load-bearing case: embedded HTML becomes literal text, so
        // `<script>` is something you read, not something that runs.
        Event::Html(h) | Event::InlineHtml(h) => Some(Inline::Text {
            text: h.to_string(),
        }),
        Event::SoftBreak => Some(Inline::SoftBreak),
        Event::HardBreak => Some(Inline::HardBreak),
        _ => None,
    }
}

/// Accept a link target only if its scheme is allowlisted, or if it has
/// no scheme at all (a relative or fragment link, which cannot navigate
/// off-origin from a bundled page).
fn sanitize_href(raw: &str) -> Option<String> {
    let trimmed = raw.trim();
    if trimmed.is_empty() {
        return None;
    }
    // Control characters (including NUL and newlines) are how
    // `java\0script:` style bypasses are smuggled past naive checks.
    if trimmed.chars().any(char::is_control) {
        return None;
    }
    match scheme_of(trimmed) {
        None => Some(trimmed.to_owned()),
        Some(scheme) => ALLOWED_SCHEMES
            .contains(&scheme.as_str())
            .then(|| trimmed.to_owned()),
    }
}

/// The scheme of `s`, lowercased, if it has one. A colon appearing after
/// a `/`, `?`, or `#` belongs to a path, not a scheme.
fn scheme_of(s: &str) -> Option<String> {
    let end = s.find(':')?;
    let candidate = &s[..end];
    if candidate.is_empty() || s[..end].contains(['/', '?', '#']) {
        return None;
    }
    // Per RFC 3986 a scheme is ALPHA *( ALPHA / DIGIT / "+" / "-" / "." ).
    let mut chars = candidate.chars();
    let first = chars.next()?;
    if !first.is_ascii_alphabetic() {
        return None;
    }
    if !chars.all(|c| c.is_ascii_alphanumeric() || matches!(c, '+' | '-' | '.')) {
        return None;
    }
    Some(candidate.to_ascii_lowercase())
}

fn image_source(raw: &str) -> ImageSource {
    let trimmed = raw.trim();
    match scheme_of(trimmed) {
        // No scheme: a path to something already on disk.
        None => ImageSource::Local {
            path: trimmed.to_owned(),
        },
        Some(s) if s == "file" => ImageSource::Local {
            path: trimmed.to_owned(),
        },
        _ => ImageSource::Blocked {
            url: trimmed.to_owned(),
        },
    }
}

fn plain_text(inlines: &[Inline]) -> String {
    let mut s = String::new();
    for i in inlines {
        match i {
            Inline::Text { text } => s.push_str(text),
            Inline::Code { code } => s.push_str(code),
            Inline::Emphasis { content }
            | Inline::Strong { content }
            | Inline::Strikethrough { content }
            | Inline::Link { content, .. } => s.push_str(&plain_text(content)),
            Inline::SoftBreak | Inline::HardBreak => s.push(' '),
            Inline::Image { alt, .. } => s.push_str(alt),
        }
    }
    s
}

fn heading_level(l: HeadingLevel) -> u8 {
    match l {
        HeadingLevel::H1 => 1,
        HeadingLevel::H2 => 2,
        HeadingLevel::H3 => 3,
        HeadingLevel::H4 => 4,
        HeadingLevel::H5 => 5,
        HeadingLevel::H6 => 6,
    }
}

#[cfg(test)]
#[allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
mod tests {
    use super::*;

    /// Flatten to the text a reader would see, so assertions can check
    /// that content survived without depending on tree shape.
    fn visible(nodes: &[Node]) -> String {
        fn walk(nodes: &[Node], out: &mut String) {
            for n in nodes {
                match n {
                    Node::Paragraph { content } | Node::Heading { content, .. } => {
                        out.push_str(&plain_text(content));
                        out.push('\n');
                    }
                    Node::CodeBlock { code, .. } => out.push_str(code),
                    Node::BlockQuote { content } => walk(content, out),
                    Node::List { items, .. } => {
                        for i in items {
                            walk(i, out);
                        }
                    }
                    Node::Rule => out.push('\n'),
                }
            }
        }
        let mut s = String::new();
        walk(nodes, &mut s);
        s
    }

    fn links(nodes: &[Node]) -> Vec<String> {
        fn walk_inline(is: &[Inline], out: &mut Vec<String>) {
            for i in is {
                match i {
                    Inline::Link { href, content } => {
                        out.push(href.clone());
                        walk_inline(content, out);
                    }
                    Inline::Emphasis { content }
                    | Inline::Strong { content }
                    | Inline::Strikethrough { content } => walk_inline(content, out),
                    _ => {}
                }
            }
        }
        fn walk(nodes: &[Node], out: &mut Vec<String>) {
            for n in nodes {
                match n {
                    Node::Paragraph { content } | Node::Heading { content, .. } => {
                        walk_inline(content, out);
                    }
                    Node::BlockQuote { content } => walk(content, out),
                    Node::List { items, .. } => {
                        for i in items {
                            walk(i, out);
                        }
                    }
                    _ => {}
                }
            }
        }
        let mut v = Vec::new();
        walk(nodes, &mut v);
        v
    }

    fn images(nodes: &[Node]) -> Vec<ImageSource> {
        let mut out = Vec::new();
        fn walk_inline(is: &[Inline], out: &mut Vec<ImageSource>) {
            for i in is {
                match i {
                    Inline::Image { source, .. } => out.push(source.clone()),
                    Inline::Emphasis { content }
                    | Inline::Strong { content }
                    | Inline::Strikethrough { content }
                    | Inline::Link { content, .. } => walk_inline(content, out),
                    _ => {}
                }
            }
        }
        for n in nodes {
            if let Node::Paragraph { content } | Node::Heading { content, .. } = n {
                walk_inline(content, &mut out);
            }
        }
        out
    }

    #[test]
    fn ordinary_markdown_still_formats() {
        let nodes = render("# Title\n\nSome **bold** and `code`.\n\n- one\n- two\n");
        assert!(matches!(nodes[0], Node::Heading { level: 1, .. }));
        let seen = visible(&nodes);
        assert!(seen.contains("Title"), "{seen}");
        assert!(seen.contains("bold"), "{seen}");
        assert!(seen.contains("one"), "{seen}");
        assert!(
            nodes.iter().any(|n| matches!(n, Node::List { .. })),
            "expected a list: {nodes:#?}"
        );
    }

    #[test]
    fn fenced_code_survives_verbatim() {
        let nodes = render("```rust\nlet x = 1;\n```\n");
        let Some(Node::CodeBlock { language, code }) = nodes.first() else {
            panic!("expected a code block, got {nodes:#?}");
        };
        assert_eq!(language.as_deref(), Some("rust"));
        assert_eq!(code, "let x = 1;\n");
    }

    /// The whole point. Embedded HTML must be readable, never runnable.
    #[test]
    fn raw_html_becomes_literal_text() {
        for body in [
            "<script>alert(1)</script>",
            "<img src=x onerror=alert(1)>",
            "<iframe src=\"https://evil.example\"></iframe>",
            "hello <b>there</b>",
            "<svg/onload=alert(1)>",
        ] {
            let nodes = render(body);
            let seen = visible(&nodes);
            assert!(
                seen.contains('<'),
                "markup should survive as text for {body:?}, got {seen:?}"
            );
            // Nothing anywhere in the tree claims to be a link.
            assert!(
                links(&nodes).is_empty(),
                "raw html produced a link for {body:?}"
            );
        }
    }

    #[test]
    fn dangerous_link_schemes_lose_the_link_and_keep_the_text() {
        for body in [
            "[click](javascript:alert(1))",
            "[click](JaVaScRiPt:alert(1))",
            "[click](  javascript:alert(1)  )",
            "[click](data:text/html;base64,PHNjcmlwdD4=)",
            "[click](vbscript:msgbox)",
            "[click](file:///etc/passwd)",
        ] {
            let nodes = render(body);
            assert!(
                links(&nodes).is_empty(),
                "{body:?} should not produce a link, got {:?}",
                links(&nodes)
            );
            assert!(
                visible(&nodes).contains("click"),
                "{body:?} should keep its text"
            );
        }
    }

    #[test]
    fn control_characters_cannot_smuggle_a_scheme() {
        // A NUL or newline inside the scheme is the classic way past a
        // naive `starts_with("javascript:")` check.
        for body in [
            "[x](java\u{0}script:alert(1))",
            "[x](java\nscript:alert(1))",
            "[x](\u{0}javascript:alert(1))",
        ] {
            let nodes = render(body);
            assert!(
                links(&nodes).is_empty(),
                "{body:?} smuggled a link through: {:?}",
                links(&nodes)
            );
        }
    }

    #[test]
    fn ordinary_links_are_kept() {
        let nodes = render("[docs](https://example.com/a?b=1#c) and [mail](mailto:a@b.c)");
        let hrefs = links(&nodes);
        assert!(
            hrefs.contains(&"https://example.com/a?b=1#c".to_owned()),
            "{hrefs:?}"
        );
        assert!(hrefs.contains(&"mailto:a@b.c".to_owned()), "{hrefs:?}");
    }

    #[test]
    fn relative_and_fragment_links_are_kept() {
        // No scheme means it cannot navigate off a bundled page.
        let nodes = render("[a](#section) [b](./notes.md) [c](/abs/path)");
        assert_eq!(links(&nodes).len(), 3, "{:?}", links(&nodes));
    }

    /// A remote image is a read receipt: fetching it tells the sender
    /// when the message was opened, and from which IP.
    #[test]
    fn remote_images_are_blocked_local_ones_are_not() {
        let nodes = render("![tracker](https://evil.example/pixel.png)");
        assert_eq!(
            images(&nodes),
            vec![ImageSource::Blocked {
                url: "https://evil.example/pixel.png".to_owned()
            }]
        );

        let nodes = render("![diagram](./diagram.png)");
        assert_eq!(
            images(&nodes),
            vec![ImageSource::Local {
                path: "./diagram.png".to_owned()
            }]
        );
    }

    #[test]
    fn image_alt_text_is_plain() {
        let nodes = render("![<script>x</script>](https://e.example/a.png)");
        let Some(Node::Paragraph { content }) = nodes.first() else {
            panic!("expected paragraph, got {nodes:#?}");
        };
        let Some(Inline::Image { alt, .. }) = content.first() else {
            panic!("expected image, got {content:#?}");
        };
        assert!(alt.contains("script"), "alt should keep text: {alt:?}");
    }

    #[test]
    fn a_plain_message_is_still_a_paragraph() {
        // The overwhelmingly common case: one line of prose.
        let nodes = render("just a normal message");
        assert_eq!(visible(&nodes).trim(), "just a normal message");
    }

    #[test]
    fn empty_input_is_empty_output() {
        assert!(render("").is_empty());
        assert!(render("   \n  \n").is_empty());
    }

    #[test]
    fn nested_structures_do_not_lose_content() {
        let nodes = render("> quoted **bold**\n>\n> - item one\n> - item two\n");
        let seen = visible(&nodes);
        assert!(seen.contains("quoted"), "{seen}");
        assert!(seen.contains("bold"), "{seen}");
        assert!(seen.contains("item one"), "{seen}");
        assert!(seen.contains("item two"), "{seen}");
    }

    #[test]
    fn scheme_detection_does_not_trip_on_paths() {
        // A colon after a slash belongs to the path, not a scheme.
        assert_eq!(scheme_of("https://a.example/x:y"), Some("https".into()));
        assert_eq!(scheme_of("/path/to:thing"), None);
        assert_eq!(scheme_of("#frag:ment"), None);
        assert_eq!(scheme_of("no-colon-here"), None);
        assert_eq!(scheme_of("1nvalid:x"), None);
    }
}