feat(anatomy): V1-2.2 classify and clean drawings before upload

The sanitiser walk names removals that carried active or external
content; clean_svg answers clean, cleanable or rejected, the cleaned
text reading back with no removal. Committed cairo and ImageMagick
exports; the owner's editor exports go under exports/owner.
This commit is contained in:
bchanot committed 2026-10-29 13:14:22 +01:00
1 parent 64a43840ce
commit cf37aa265a
11 files changed
+840 -5

No files matched your search

+136
View File
@@ -0,0 +1,136 @@
//! Cleaning a drawing before upload (contract §9.2, O19): the page hands the file's bytes to
//! the core reader before anything is stored, and gets one of three answers.
//!
//! - rejected: a hard rejection of the reader (with its reason), a text that is not UTF-8
//! (`malformed`), or any removal of active or external content (`svg_active_content`, the
//! names in `active`); no cleaning is offered;
//! - cleanable: only other removals (editor metadata and namespaces, `data-*`, `<style>`,
//! `class` or `style` on the root, ids outside the grammar, unsupported elements, long
//! titles or descriptions): the cleaned text is the sanitised tree serialised, and it is
//! that text, read back with no removal, that is hashed and uploaded;
//! - clean: no removal; the original bytes are uploaded as they are.
//!
//! In every case but a rejection, `preview` is the drawing as the core reads it: the page
//! shows that, never the original file. Stored drawings are never repaired afterwards
//! (LRN-055): the verdict reads each one again and refuses any removal.
use serde::Serialize;
#[cfg(feature = "ts")]
use ts_rs::TS;
use super::prescan::SVG_CAPS;
use super::serialize::serialize;
use super::{read_svg, read_svg_for_cleaning};
use crate::domain::sheet::verdict::sha256_hex;
/// The reason of a refusal for active or external content.
pub const ACTIVE_CONTENT: &str = "svg_active_content";
/// A preview larger than the canvas accepts (`ops::MAX_COMPOSED_BYTES`).
const MAX_PREVIEW_BYTES: usize = 4 * 1024 * 1024;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[cfg_attr(feature = "ts", derive(TS), ts(export))]
#[serde(rename_all = "snake_case")]
pub enum CleaningOutcome {
Clean,
Cleanable,
Rejected,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[cfg_attr(feature = "ts", derive(TS), ts(export))]
pub struct SvgCleaning {
pub outcome: CleaningOutcome,
/// Rejected: the reader's reason, `malformed`, `too_large` or `svg_active_content`.
pub reason: Option<String>,
/// Every removal, `tag` or `tag@attribute`, in document order.
pub removed: Vec<String>,
/// The removals that carried active or external content.
pub active: Vec<String>,
/// A `<style>` element was removed: the classes it styled render unstyled.
pub style_removed: bool,
/// The drawing as the core reads it (sanitised, serialised).
pub preview: Option<String>,
/// Cleanable only: the text to upload.
pub cleaned: Option<String>,
/// SHA-256 and size of the bytes to upload: the original (clean) or the cleaned text.
pub sha256: Option<String>,
#[cfg_attr(feature = "ts", ts(type = "number | null"))]
pub byte_size: Option<u64>,
}
fn rejected(reason: &str, removed: Vec<String>, active: Vec<String>) -> SvgCleaning {
SvgCleaning {
outcome: CleaningOutcome::Rejected,
reason: Some(reason.to_owned()),
style_removed: removed.iter().any(|name| name == "style"),
removed,
active,
preview: None,
cleaned: None,
sha256: None,
byte_size: None,
}
}
/// The answer for the bytes of one file.
pub fn clean_svg(bytes: &[u8]) -> SvgCleaning {
if bytes.len() > SVG_CAPS.max_bytes {
return rejected("too_large", Vec::new(), Vec::new());
}
let Ok(text) = std::str::from_utf8(bytes) else {
return rejected("malformed", Vec::new(), Vec::new());
};
let read = match read_svg_for_cleaning(text) {
Ok(read) => read,
Err(rejection) => return rejected(rejection.reason(), Vec::new(), Vec::new()),
};
if !read.active.is_empty() {
return rejected(ACTIVE_CONTENT, read.removed, read.active);
}
let preview = serialize(&read.root);
if preview.len() > MAX_PREVIEW_BYTES {
return rejected("too_large", read.removed, read.active);
}
if read.removed.is_empty() {
return accepted(CleaningOutcome::Clean, bytes, preview, Vec::new());
}
if preview.len() > SVG_CAPS.max_bytes {
return rejected("too_large", read.removed, read.active);
}
if !reads_back_clean(&preview) {
return rejected("cleaning_unstable", read.removed, read.active);
}
accepted(
CleaningOutcome::Cleanable,
preview.as_bytes(),
preview.clone(),
read.removed,
)
}
fn accepted(
outcome: CleaningOutcome,
upload: &[u8],
preview: String,
removed: Vec<String>,
) -> SvgCleaning {
let cleaned = (outcome == CleaningOutcome::Cleanable).then(|| preview.clone());
SvgCleaning {
outcome,
reason: None,
style_removed: removed.iter().any(|name| name == "style"),
removed,
active: Vec::new(),
preview: Some(preview),
cleaned,
sha256: Some(sha256_hex(upload)),
byte_size: Some(upload.len() as u64),
}
}
/// The cleaned text reads back with nothing to remove (the fixpoint the property test of
/// `tests/svg_clean.rs` proves; checked here too, so no upload rests on it alone).
fn reads_back_clean(text: &str) -> bool {
read_svg(text).is_ok_and(|read| read.removed.is_empty())
}
+10
View File
@@ -1,6 +1,7 @@
//! SVG text → bounded, sanitised tree → text (plan R3 C2–C4). One reader for every SVG the
//! product draws: the sheet drawings now, the branding and Step 13 uploads later.
pub mod clean;
pub mod number;
pub mod prescan;
pub mod refs;
@@ -18,3 +19,12 @@ pub fn read_svg(text: &str) -> Result<Sanitized, SvgRejection> {
refs::check_references(&sanitized.root)?;
Ok(sanitized)
}
/// `read_svg` as the cleaning reads a file picked for upload: an oversized `title` or `desc`
/// is a removal, not a refusal (`sanitize::sanitize_for_cleaning`).
pub fn read_svg_for_cleaning(text: &str) -> Result<Sanitized, SvgRejection> {
let root = tree::parse_svg(text)?;
let sanitized = sanitize::sanitize_for_cleaning(root)?;
refs::check_references(&sanitized.root)?;
Ok(sanitized)
}
+118 -5
View File
@@ -4,6 +4,11 @@
//! no `class`/`style` on the root (inline SVG lives under the page's CSS), `id` values in the
//! reference grammar, no text outside `title`/`desc`. A refused element goes with its
//! subtree, a refused attribute alone; both are named in `removed` (names, never values).
//! The removals that carried active or external content (script, embedded documents and
//! images, animation, links, event handlers, a reference outside the document, `@import`,
//! `javascript:` and the other forbidden style tokens, a backslash escape) are also named in
//! `active` (contract §9.2, V1-2.2): a file with any is refused, never cleaned. The walk and
//! what it keeps are unchanged by that classification.
use super::number::{js_number_of, js_split_list, js_to_string};
use super::tree::{Element, Node, SvgRejection, XLINK_NS};
@@ -162,41 +167,91 @@ const STYLE_FORBIDDEN: [&str; 5] = [
"behavior:",
];
/// Elements whose removal means the file carried active or embedded content, by local name
/// (lowercase, compared without case: an unknown spelling is refused rather than cleaned).
const ACTIVE_ELEMENTS: [&str; 19] = [
"script",
"foreignobject",
"image",
"feimage",
"a",
"animate",
"animatemotion",
"animatetransform",
"animatecolor",
"set",
"discard",
"mpath",
"iframe",
"embed",
"object",
"video",
"audio",
"canvas",
"handler",
];
/// A sanitised tree and what was taken out of it.
#[derive(Debug, Clone, PartialEq)]
pub struct Sanitized {
pub root: Element,
/// `tag` and `tag@attribute` in document order (empty on the product's SVGs).
pub removed: Vec<String>,
/// The entries of `removed` that carried active or external content, same order.
pub active: Vec<String>,
}
/// Sanitises a parsed root (the caller parsed it with `tree::parse_svg`).
pub fn sanitize(mut root: Element) -> Result<Sanitized, SvgRejection> {
pub fn sanitize(root: Element) -> Result<Sanitized, SvgRejection> {
sanitize_with(root, false)
}
/// The cleaning's reading (contract §9.2): the same walk, except that a `title` or `desc`
/// over the text cap is removed and named instead of refusing the file. Stored drawings are
/// always read by `sanitize`, which refuses it.
pub fn sanitize_for_cleaning(root: Element) -> Result<Sanitized, SvgRejection> {
sanitize_with(root, true)
}
fn sanitize_with(mut root: Element, drop_long_text: bool) -> Result<Sanitized, SvgRejection> {
let mut walk = Walk {
removed: Vec::new(),
active: Vec::new(),
uses: 0,
drop_long_text,
};
// The inline root lives under the page: no page classes or styles, nothing that paints
// outside its box (security audit R3, LOW).
for name in ["class", "style", "transform", "filter", "mask", "clip-path"] {
if root.attr(name).is_some() {
if let Some(value) = root.attr(name) {
let active = attribute_is_active(name, value);
root.remove_attr(name);
walk.removed.push(format!("svg@{name}"));
walk.note(format!("svg@{name}"), active);
}
}
walk.visit(&mut root)?;
Ok(Sanitized {
root,
removed: walk.removed,
active: walk.active,
})
}
struct Walk {
removed: Vec<String>,
active: Vec<String>,
uses: usize,
drop_long_text: bool,
}
impl Walk {
fn note(&mut self, name: String, active: bool) {
if active {
self.active.push(name.clone());
}
self.removed.push(name);
}
fn visit(&mut self, element: &mut Element) -> Result<(), SvgRejection> {
if element.qname == "use" {
self.uses += 1;
@@ -209,11 +264,17 @@ impl Walk {
let children = std::mem::take(&mut element.children);
for child in children {
match child {
Node::Element(child) if self.drop_long_text && has_long_text(&child) => {
self.note(child.qname, false);
}
Node::Element(mut child) if element_allowed(&child) => {
self.visit(&mut child)?;
element.children.push(Node::Element(child));
}
Node::Element(child) => self.removed.push(child.qname),
Node::Element(child) => {
let active = subtree_is_active(&child);
self.note(child.qname, active);
}
Node::Text(text) if is_xml_space(&text) => element.children.push(Node::Text(text)),
Node::Text(text) if keeps_text => {
if text.len() > MAX_TEXT_BYTES {
@@ -234,7 +295,8 @@ impl Walk {
&& namespace_fits(&a.qname, a.namespace.as_deref())
&& value_acceptable(&a.qname, &a.value);
if !keep {
self.removed.push(format!("{tag}@{}", a.qname));
let active = attribute_is_active(&a.qname, &a.value);
self.note(format!("{tag}@{}", a.qname), active);
}
keep
});
@@ -242,6 +304,57 @@ impl Walk {
}
}
/// A `title` or `desc` whose text is over the cap the walk refuses.
fn has_long_text(element: &Element) -> bool {
matches!(element.qname.as_str(), "title" | "desc")
&& element
.children
.iter()
.any(|c| matches!(c, Node::Text(t) if !is_xml_space(t) && t.len() > MAX_TEXT_BYTES))
}
/// A removed subtree carried active content: an active element anywhere in it, an active
/// attribute, or a style sheet with an active value.
fn subtree_is_active(element: &Element) -> bool {
let name = element.local_name().to_ascii_lowercase();
if ACTIVE_ELEMENTS.contains(&name.as_str()) {
return true;
}
if element
.attrs
.iter()
.any(|a| attribute_is_active(&a.qname, &a.value))
{
return true;
}
element.children.iter().any(|child| match child {
Node::Element(child) => subtree_is_active(child),
Node::Text(text) => name == "style" && value_is_active(text),
})
}
/// An event handler, a link outside the document, or an active value.
fn attribute_is_active(qname: &str, value: &str) -> bool {
let local = qname
.rsplit(':')
.next()
.unwrap_or(qname)
.to_ascii_lowercase();
if local.starts_with("on") {
return true;
}
if local == "href" && !is_local_reference(local_reference_text(value)) {
return true;
}
value_is_active(value)
}
/// A reference outside the document, a forbidden style token, or a backslash (a CSS escape
/// can spell any of them).
fn value_is_active(value: &str) -> bool {
value.contains('\\') || !urls_are_local(value) || style_forbidden(value)
}
fn element_allowed(element: &Element) -> bool {
ALLOWED_ELEMENTS.contains(&element.qname.as_str()) && element.is_svg_namespace()
}