Skip to main content

nitr_std/validate/media/
sniff.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2// This file is part of Nitr.
3// See https://nitrweb.com/ for more information
4// Copyright (C) 2024-present Jose Quintana <joseluisq.net>
5
6//! Signature detection over an upload's first bytes, the text sniffer,
7//! and the ZIP-container reader that tells an office document from a
8//! plain archive. Every function reads a bounded prefix once and is
9//! linear in it; none of them decodes anything.
10
11use super::{Detection, MediaType, lookup};
12
13fn starts(prefix: &[u8], magic: &[u8]) -> bool {
14    prefix.len() >= magic.len() && &prefix[..magic.len()] == magic
15}
16
17fn at(prefix: &[u8], offset: usize, magic: &[u8]) -> bool {
18    prefix.len() >= offset + magic.len() && &prefix[offset..offset + magic.len()] == magic
19}
20
21/// The `ftyp` brand of an ISO base media file, when the prefix is one.
22fn ftyp_brand(prefix: &[u8]) -> Option<&[u8]> {
23    if at(prefix, 4, b"ftyp") && prefix.len() >= 12 {
24        Some(&prefix[8..12])
25    } else {
26        None
27    }
28}
29
30/// A ZIP's first local-file names, from the local headers in the prefix:
31/// enough to tell an office document from a plain archive.
32fn zip_entry_names(prefix: &[u8]) -> Vec<&[u8]> {
33    let mut names = Vec::new();
34    let mut pos = 0usize;
35    // Each local header: signature(4) ver(2) flag(2) method(2) time(2)
36    // date(2) crc(4) csize(4) usize(4) nlen(2) xlen(2) name[nlen] extra
37    // then the data (csize bytes, unless flag bit 3 defers it).
38    while names.len() < 8 && prefix.len() >= pos + 30 && at(prefix, pos, b"PK\x03\x04") {
39        let u16_at = |i: usize| u16::from_le_bytes([prefix[pos + i], prefix[pos + i + 1]]) as usize;
40        let u32_at = |i: usize| {
41            u32::from_le_bytes([
42                prefix[pos + i],
43                prefix[pos + i + 1],
44                prefix[pos + i + 2],
45                prefix[pos + i + 3],
46            ]) as usize
47        };
48        let flags = u16_at(6);
49        let csize = u32_at(18);
50        let nlen = u16_at(26);
51        let xlen = u16_at(28);
52        let name_start = pos + 30;
53        let Some(name_end) = name_start.checked_add(nlen) else {
54            break;
55        };
56        if name_end > prefix.len() {
57            break;
58        }
59        names.push(&prefix[name_start..name_end]);
60        if flags & 0x08 != 0 {
61            // Sizes deferred to a data descriptor: cannot skip reliably.
62            break;
63        }
64        let Some(next) = name_end
65            .checked_add(xlen)
66            .and_then(|n| n.checked_add(csize))
67        else {
68            break;
69        };
70        pos = next;
71    }
72    names
73}
74
75/// Which ZIP-based type a `PK` prefix is.
76fn zip_kind(prefix: &[u8]) -> &'static MediaType {
77    let names = zip_entry_names(prefix);
78    let first = names.first().copied().unwrap_or(b"");
79    // OpenDocument and EPUB: an uncompressed `mimetype` entry whose bytes
80    // are the media type, right after the header.
81    if first == b"mimetype" {
82        let start = 30 + first.len();
83        let body = &prefix[start.min(prefix.len())..];
84        for candidate in [
85            "application/vnd.oasis.opendocument.text",
86            "application/vnd.oasis.opendocument.spreadsheet",
87            "application/vnd.oasis.opendocument.presentation",
88            "application/epub+zip",
89        ] {
90            if starts(body, candidate.as_bytes())
91                && let Some(media) = lookup(candidate)
92            {
93                return media;
94            }
95        }
96    }
97    let has = |needle: &[u8]| names.iter().any(|n| n.starts_with(needle));
98    if names.iter().any(|n| *n == b"[Content_Types].xml") || has(b"_rels/") {
99        let office = if has(b"word/") {
100            "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
101        } else if has(b"xl/") {
102            "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
103        } else if has(b"ppt/") {
104            "application/vnd.openxmlformats-officedocument.presentationml.presentation"
105        } else {
106            "application/zip"
107        };
108        if let Some(media) = lookup(office) {
109            return media;
110        }
111    }
112    // Invariant: the table carries `application/zip`.
113    #[allow(clippy::expect_used)]
114    lookup("application/zip").expect("zip is in the media table")
115}
116
117/// Whether the prefix is UTF-8 text without NUL or stray control bytes.
118pub fn is_text(prefix: &[u8]) -> bool {
119    if prefix.is_empty() {
120        return true;
121    }
122    let body = prefix.strip_prefix(b"\xEF\xBB\xBF").unwrap_or(prefix);
123    let text = match std::str::from_utf8(body) {
124        Ok(text) => text,
125        // A prefix may cut a multi-byte sequence: accept the valid part
126        // when the cut is within the last three bytes.
127        Err(err) if err.error_len().is_none() && err.valid_up_to() > 0 => {
128            match std::str::from_utf8(&body[..err.valid_up_to()]) {
129                Ok(text) => text,
130                Err(_) => return false,
131            }
132        }
133        Err(_) => return false,
134    };
135    !text
136        .chars()
137        .any(|c| c.is_control() && c != '\t' && c != '\n' && c != '\r')
138}
139
140/// Whether the first bytes are an executable's.
141fn is_executable(prefix: &[u8]) -> bool {
142    if starts(prefix, b"MZ")
143        || starts(prefix, b"\x7fELF")
144        || starts(prefix, b"#!")
145        || starts(prefix, b"\xCA\xFE\xBA\xBE")
146    {
147        return true;
148    }
149    prefix.len() >= 4 && {
150        let magic = u32::from_be_bytes([prefix[0], prefix[1], prefix[2], prefix[3]]);
151        matches!(magic, 0xFEED_FACE | 0xFEED_FACF | 0xCEFA_EDFE | 0xCFFA_EDFE)
152    }
153}
154
155/// Sniffs the prefix.
156pub fn detect(prefix: &[u8]) -> Detection {
157    let hit = |name: &str| {
158        lookup(name)
159            .map(Detection::Detected)
160            .unwrap_or(Detection::Unknown)
161    };
162    // Executables first: a polyglot that is also an executable is an
163    // executable.
164    if is_executable(prefix) {
165        return Detection::Executable;
166    }
167    let signatures: &[(&[u8], &str)] = &[
168        (b"\x89PNG\r\n\x1a\n", "image/png"),
169        (b"\xFF\xD8\xFF", "image/jpeg"),
170        (b"GIF87a", "image/gif"),
171        (b"GIF89a", "image/gif"),
172        (b"II*\0", "image/tiff"),
173        (b"MM\0*", "image/tiff"),
174        (b"\0\0\x01\0", "image/x-icon"),
175        (b"%PDF-", "application/pdf"),
176        (b"\xD0\xCF\x11\xE0\xA1\xB1\x1A\xE1", "application/msword"),
177        (b"{\\rtf", "application/rtf"),
178        (b"\x1F\x8B", "application/gzip"),
179        (b"BZh", "application/x-bzip2"),
180        (b"\xFD7zXZ\0", "application/x-xz"),
181        (b"\x28\xB5\x2F\xFD", "application/zstd"),
182        (b"7z\xBC\xAF\x27\x1C", "application/x-7z-compressed"),
183        (b"Rar!\x1A\x07", "application/vnd.rar"),
184        (b"ID3", "audio/mpeg"),
185        (b"OggS", "audio/ogg"),
186        (b"fLaC", "audio/flac"),
187        (b"wOFF", "font/woff"),
188        (b"wOF2", "font/woff2"),
189        (b"\0\x01\0\0", "font/ttf"),
190        (b"true", "font/ttf"),
191        (b"OTTO", "font/otf"),
192        (b"\0asm", "application/wasm"),
193        (b"SQLite format 3\0", "application/vnd.sqlite3"),
194        (b"PAR1", "application/x-parquet"),
195    ];
196    for (magic, name) in signatures {
197        if starts(prefix, magic) {
198            return hit(name);
199        }
200    }
201    if starts(prefix, b"RIFF") {
202        if at(prefix, 8, b"WEBP") {
203            return hit("image/webp");
204        }
205        if at(prefix, 8, b"WAVE") {
206            return hit("audio/wav");
207        }
208        if at(prefix, 8, b"AVI ") {
209            return hit("video/x-msvideo");
210        }
211    }
212    // An ISO media file shorter than its brand says nothing yet — never
213    // let the frame-sync heuristics below claim it. Tested before the
214    // two-byte `BM` so `BM…ftyp` reads the same at every length.
215    if at(prefix, 4, b"ftyp") && prefix.len() < 12 {
216        return Detection::Unknown;
217    }
218    if let Some(brand) = ftyp_brand(prefix) {
219        return match brand {
220            b"avif" | b"avis" => hit("image/avif"),
221            b"heic" | b"heix" | b"hevc" | b"mif1" | b"msf1" => hit("image/heic"),
222            b"M4A " => hit("audio/mp4"),
223            b"qt  " => hit("video/quicktime"),
224            _ => hit("video/mp4"),
225        };
226    }
227    // `BM` is two bytes of English; the DIB header size at offset 14
228    // (one of the known header versions) is what makes it a bitmap.
229    if starts(prefix, b"BM")
230        && let Some(header) = prefix
231            .get(14..18)
232            .map(|b| u32::from_le_bytes([b[0], b[1], b[2], b[3]]))
233        && matches!(header, 12 | 40 | 52 | 56 | 108 | 124)
234    {
235        return hit("image/bmp");
236    }
237    if starts(prefix, b"PK\x03\x04") {
238        return Detection::Detected(zip_kind(prefix));
239    }
240    if at(prefix, 257, b"ustar") {
241        return hit("application/x-tar");
242    }
243    if prefix.len() >= 2 && prefix[0] == 0xFF {
244        // MPEG audio frame sync (`FFE`/`FFF`) and ADTS AAC (`FFF1`/`FFF9`).
245        if prefix[1] & 0xF6 == 0xF0 {
246            return hit("audio/aac");
247        }
248        // `FF FE`/`FF FF` are byte-order marks and padding, not frames.
249        if prefix[1] & 0xE0 == 0xE0 && prefix[1] < 0xFE {
250            return hit("audio/mpeg");
251        }
252    }
253    if starts(prefix, b"\x1A\x45\xDF\xA3") {
254        let is_webm = prefix.windows(4).take(64).any(|w| w == b"webm");
255        return hit(if is_webm {
256            "video/webm"
257        } else {
258            "video/x-matroska"
259        });
260    }
261    if is_text(prefix) {
262        return Detection::Text;
263    }
264    Detection::Unknown
265}
266
267/// For a text-tier declared type, whether the prefix has the structure
268/// the subtype implies (`{`/`[` for JSON, `<` for XML and HTML, `<svg`
269/// for SVG); plain text subtypes accept anything the sniffer accepted.
270pub fn text_subtype_matches(declared: &str, prefix: &[u8]) -> bool {
271    let body = prefix.strip_prefix(b"\xEF\xBB\xBF").unwrap_or(prefix);
272    let first = body.iter().copied().find(|b| !b.is_ascii_whitespace());
273    match declared {
274        "application/json" => matches!(first, Some(b'{') | Some(b'[')),
275        "application/xml" | "text/xml" | "text/html" => matches!(first, Some(b'<')),
276        "image/svg+xml" => {
277            let text = String::from_utf8_lossy(&body[..body.len().min(4096)]).to_ascii_lowercase();
278            let trimmed = text.trim_start();
279            trimmed.starts_with("<svg") || (trimmed.starts_with("<?xml") && text.contains("<svg"))
280        }
281        _ => true,
282    }
283}