damascene-html 0.4.2

Damascene — HTML to El tree transformer
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153

//! Hardcoded sanitization policy for the v1 transformer.
//!
//! These rules apply before any tag-to-widget mapping: blocked tags
//! cause the entire subtree to be skipped, blocked attributes are
//! filtered when reading element attrs, and blocked URLs cause the
//! containing `href` / `src` to be treated as absent.
//!
//! Embedders handling untrusted HTML should still layer a dedicated
//! sanitizer (e.g. `ammonia`) in front; this is the irreducible safety
//! floor, not a security boundary on its own.

/// Tags whose entire subtree the walker skips. Mix of script / plugin
/// hosts (security) and document-shell tags that don't render content
/// (`<head>`, `<meta>`, `<link>`, `<title>`).
pub(crate) fn is_blocked_tag(name: &str) -> bool {
    matches!(
        name,
        "script"
            | "iframe"
            | "object"
            | "embed"
            | "noscript"
            | "head"
            | "meta"
            | "link"
            | "title"
            | "base"
            | "template"
            | "frame"
            | "frameset"
            // `<style>` element bodies are collected at entry by
            // `collect_stylesheets` and applied through the cascade;
            // the element itself must not render its CSS text as a
            // paragraph during the regular walk.
            | "style"
    )
}

/// Attributes the walker silently drops. Event handlers and a couple of
/// historical scripting hooks. Style attributes pass through; the v1
/// transformer ignores their values but the v2 CSS pass will read
/// them.
pub(crate) fn is_blocked_attr(name: &str) -> bool {
    // Every `on*` attribute (onclick, onload, onerror, …).
    if name.starts_with("on") {
        return true;
    }
    matches!(name, "srcdoc" | "formaction")
}

/// Returns `true` if `url` is in the allowed scheme set: `http(s)`,
/// `mailto`, `tel`, `data:image/*`, or scheme-relative / path-relative.
/// Used to validate `href` and `src` values before they reach the El
/// tree.
pub(crate) fn is_safe_url(url: &str) -> bool {
    let trimmed = url.trim();
    if trimmed.is_empty() {
        return false;
    }
    // Path-relative, root-relative, and fragment / query references
    // never carry a scheme — accept directly.
    if !contains_scheme(trimmed) {
        return true;
    }
    let lower = trimmed.to_ascii_lowercase();
    if lower.starts_with("http://")
        || lower.starts_with("https://")
        || lower.starts_with("mailto:")
        || lower.starts_with("tel:")
    {
        return true;
    }
    if let Some(rest) = lower.strip_prefix("data:") {
        // Only image data URLs — drops `data:text/html` and friends,
        // which can carry script payloads.
        return rest.starts_with("image/");
    }
    false
}

fn contains_scheme(url: &str) -> bool {
    // A URL has a scheme if some prefix matches `[a-zA-Z][a-zA-Z0-9+.-]*:`.
    // Cheap manual scan — avoids pulling a URL crate for this single
    // check.
    let bytes = url.as_bytes();
    if bytes.is_empty() || !bytes[0].is_ascii_alphabetic() {
        return false;
    }
    for (i, &b) in bytes.iter().enumerate().skip(1) {
        match b {
            b'a'..=b'z' | b'A'..=b'Z' | b'0'..=b'9' | b'+' | b'.' | b'-' => continue,
            b':' => return i > 0,
            _ => return false,
        }
    }
    false
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn allowed_urls_pass() {
        for url in [
            "https://damascene.dev",
            "http://example.com/path",
            "mailto:user@example.com",
            "tel:+15551234",
            "/relative/path",
            "./file.html",
            "../sibling",
            "#anchor",
            "?query=1",
            "data:image/png;base64,AAA",
        ] {
            assert!(is_safe_url(url), "expected safe: {url}");
        }
    }

    #[test]
    fn dangerous_urls_blocked() {
        for url in [
            "javascript:alert(1)",
            "JAVASCRIPT:alert(1)",
            "vbscript:msgbox",
            "data:text/html,<script>",
            "data:application/javascript,alert(1)",
            "",
            "   ",
        ] {
            assert!(!is_safe_url(url), "expected blocked: {url}");
        }
    }

    #[test]
    fn on_attrs_blocked() {
        assert!(is_blocked_attr("onclick"));
        assert!(is_blocked_attr("onerror"));
        assert!(is_blocked_attr("onmouseover"));
        assert!(!is_blocked_attr("href"));
        assert!(!is_blocked_attr("class"));
    }

    #[test]
    fn script_and_iframe_blocked() {
        assert!(is_blocked_tag("script"));
        assert!(is_blocked_tag("iframe"));
        assert!(is_blocked_tag("object"));
        assert!(!is_blocked_tag("div"));
        assert!(!is_blocked_tag("p"));
    }
}