Skip to main content

nitr_std/validate/media/
mod.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//! The media types a `file` rule can name, and how each is established
7//! from an upload's first bytes: a signature (authoritative over the
8//! declared header), the text sniffer (then the declared subtype is
9//! trusted), or the header alone. Executables are a family that never
10//! matches.
11//!
12//! [`types`] is the table, [`sniff`] the detection, [`dimensions`] the
13//! header-only image readers.
14
15use mlua::{Lua, Table};
16
17mod dimensions;
18mod sniff;
19#[cfg(test)]
20mod tests;
21mod types;
22
23pub use dimensions::dimensions;
24pub use sniff::{detect, is_text, text_subtype_matches};
25pub use types::MEDIA_TYPES;
26
27use super::TypePattern;
28
29/// The type reported when nothing is known: the declared header when it
30/// names nothing detectable, else this.
31pub(crate) const UNKNOWN_TYPE: &str = "application/octet-stream";
32
33/// The type reported for the executable family.
34pub(crate) const EXECUTABLE_TYPE: &str = "application/x-executable";
35
36/// How many bytes detection reads.
37pub const SNIFF_BYTES: usize = 64 * 1024;
38
39/// A family of media types.
40#[derive(Debug, Clone, Copy, PartialEq, Eq)]
41pub enum Family {
42    /// Raster images.
43    Image,
44    /// SVG: text that is also active content.
45    Vector,
46    /// PDF and office documents.
47    Document,
48    /// Plain and structured text.
49    Text,
50    /// Compressed containers.
51    Archive,
52    /// Audio.
53    Audio,
54    /// Video.
55    Video,
56    /// Fonts.
57    Font,
58    /// Machine data formats.
59    Data,
60    /// `application/octet-stream`.
61    Generic,
62}
63
64impl Family {
65    fn name(self) -> &'static str {
66        match self {
67            Self::Image => "image",
68            Self::Vector => "vector",
69            Self::Document => "document",
70            Self::Text => "text",
71            Self::Archive => "archive",
72            Self::Audio => "audio",
73            Self::Video => "video",
74            Self::Font => "font",
75            Self::Data => "data",
76            Self::Generic => "generic",
77        }
78    }
79}
80
81/// How a type is established for a part.
82#[derive(Debug, Clone, Copy, PartialEq, Eq)]
83pub enum Tier {
84    /// A signature in the prefix; the declared header is ignored.
85    Detected,
86    /// The prefix passes the text sniffer; the declared subtype is trusted.
87    Text,
88    /// Header only.
89    Header,
90}
91
92impl Tier {
93    fn name(self) -> &'static str {
94        match self {
95            Self::Detected => "detected",
96            Self::Text => "text",
97            Self::Header => "header",
98        }
99    }
100}
101
102/// One entry of the media-type table.
103#[derive(Debug)]
104pub struct MediaType {
105    /// The media type name (`image/png`).
106    pub name: &'static str,
107    /// Extensions this type is known by, lowercase, without the dot.
108    pub extensions: &'static [&'static str],
109    /// The family, for `type/*` patterns and the presets.
110    pub family: Family,
111    /// How it is established.
112    pub tier: Tier,
113    /// The short name in messages (`a PDF`, `an image`).
114    pub short: &'static str,
115    /// Whether a dimension reader exists for it.
116    dims: bool,
117}
118
119impl MediaType {
120    /// Whether the header carries readable image dimensions.
121    pub fn has_dimensions(&self) -> bool {
122        self.dims
123    }
124}
125
126/// Entries are compared by name: the table holds each once.
127impl PartialEq for MediaType {
128    fn eq(&self, other: &Self) -> bool {
129        self.name == other.name
130    }
131}
132
133impl Eq for MediaType {}
134
135/// What the prefix of an upload says about it.
136#[derive(Debug, Clone, Copy, PartialEq, Eq)]
137pub enum Detection {
138    /// A known signature.
139    Detected(&'static MediaType),
140    /// Looks like UTF-8 text.
141    Text,
142    /// An executable format: refused by every `types` list by default.
143    Executable,
144    /// Nothing recognizable.
145    Unknown,
146}
147
148/// Types a browser runs script from when it opens them. A family
149/// wildcard (`image/*`, `text/*`) never matches one; a rule has to name
150/// it, and naming it logs a warning at load.
151pub fn is_active_content(name: &str) -> bool {
152    matches!(
153        name,
154        "image/svg+xml" | "text/html" | "application/xhtml+xml"
155    )
156}
157
158/// Looks a media type up by name.
159pub fn lookup(name: &str) -> Option<&'static MediaType> {
160    MEDIA_TYPES.iter().find(|m| m.name == name)
161}
162
163/// The family a type name belongs to (`image` for `image/png`).
164fn family_name(name: &str) -> &str {
165    name.split('/').next().unwrap_or(name)
166}
167
168/// Whether an extension is one this type is known by.
169pub(crate) fn extension_matches(media: &MediaType, ext: &str) -> bool {
170    media.extensions.contains(&ext)
171}
172
173/// Whether a filename extension marks an executable regardless of bytes.
174pub fn executable_extension(ext: &str) -> bool {
175    types::SCRIPT_EXTENSIONS.contains(&ext)
176}
177
178/// The phrase for a `types` list in a message: the family's short name
179/// when the list is one family, the short names otherwise.
180pub(crate) fn describe_types(patterns: &[TypePattern]) -> String {
181    // Several exact types of one family read as that family with their
182    // extensions: "an image (png, jpg, gif, webp)".
183    let families: Vec<&str> = patterns
184        .iter()
185        .filter_map(|p| match p {
186            TypePattern::Exact(name) => Some(family_name(name)),
187            _ => None,
188        })
189        .collect();
190    if families.len() > 1
191        && families.len() == patterns.len()
192        && families.iter().all(|f| *f == families[0])
193    {
194        let exts: Vec<&str> = patterns
195            .iter()
196            .filter_map(|p| match p {
197                TypePattern::Exact(name) => {
198                    lookup(name).and_then(|m| m.extensions.first().copied())
199                }
200                _ => None,
201            })
202            .collect();
203        let family = families[0];
204        let article = if family.starts_with(['a', 'e', 'i', 'o', 'u']) {
205            "an"
206        } else {
207            "a"
208        };
209        return format!("{article} {family} ({})", exts.join(", "));
210    }
211    let mut parts = Vec::new();
212    for pattern in patterns {
213        parts.push(match pattern {
214            TypePattern::Any => "any file".to_string(),
215            TypePattern::Family(f) => {
216                let exts: Vec<&str> = MEDIA_TYPES
217                    .iter()
218                    .filter(|m| family_name(m.name) == f && !m.extensions.is_empty())
219                    .map(|m| m.extensions[0])
220                    .collect();
221                let article = if f.starts_with(['a', 'e', 'i', 'o', 'u']) {
222                    "an"
223                } else {
224                    "a"
225                };
226                if exts.is_empty() {
227                    format!("{article} {f} file")
228                } else {
229                    format!("{article} {f} ({})", exts.join(", "))
230                }
231            }
232            TypePattern::Exact(name) => lookup(name)
233                .map(|m| m.short.to_string())
234                .unwrap_or_else(|| name.clone()),
235        });
236    }
237    match parts.len() {
238        0 => "a file".into(),
239        1 => parts.remove(0),
240        _ => {
241            let last = parts.pop().unwrap_or_default();
242            format!("{} or {last}", parts.join(", "))
243        }
244    }
245}
246
247/// `nitr.validate.media_types()`: the table as data.
248pub(crate) fn media_types_table(lua: &Lua) -> mlua::Result<Table> {
249    let out = lua.create_table()?;
250    for media in MEDIA_TYPES {
251        let entry = lua.create_table()?;
252        entry.set(
253            "extensions",
254            lua.create_sequence_from(media.extensions.iter().copied())?,
255        )?;
256        entry.set("family", media.family.name())?;
257        entry.set("tier", media.tier.name())?;
258        entry.set("dimensions", media.dims)?;
259        out.set(media.name, entry)?;
260    }
261    Ok(out)
262}