Skip to main content

dustnet_server/
input.rs

1//! Accepting form submissions.
2//!
3//! Without a handler the server refuses `INPUT` with 405, which is what it did
4//! before this module existed and what `dustnetd` still does. Installing a
5//! handler is what lets a site accept a submission.
6//!
7//! # Fields are ordered and duplicates are kept
8//!
9//! [`docs/spec/02-protocol.md`](../../../docs/spec/02-protocol.md) says of the
10//! INPUT body: "Repeated field names are permitted and retain document order."
11//! So [`FormFields`] is a `Vec`, not a map. Collapsing duplicates would quietly
12//! discard data and, worse, make *which* value survives depend on whether the
13//! implementation kept the first or the last — a difference an attacker picks
14//! and a reviewer does not see.
15//!
16//! # What a handler is told, and what it returns
17//!
18//! A handler gets the path, any query riding on the form's action, and the
19//! fields. It returns [`InputOutcome`] — which page to answer with, or a
20//! refusal — and **never markup**. Rendering goes through the include resolver
21//! either way, so there is exactly one place that generates a page and it
22//! behaves the same whether or not a submission preceded it.
23//!
24//! An accepted submission is answered with the target *page*, not a redirect.
25//! That is forced by the protocol rather than chosen: `validate_redirect_body`
26//! requires an absolute `atp://` target, because the client resolves it with
27//! `AtpUri::parse` rather than against the current URI — and a server does not
28//! know its own public hostname, only the address it happens to be bound to.
29//! Answering with the page is what
30//! [`docs/spec/02-protocol.md`](../../../docs/spec/02-protocol.md) permits
31//! ("The server responds with a PAGE, REDIRECT, or ERROR") and costs one round
32//! trip instead of two.
33
34/// Most fields one submission may carry.
35///
36/// The body is already bounded by `MAX_INPUT_MESSAGE_SIZE`, but a bounded body
37/// can still hold a great many `&`s. This bounds the parsed vector too, so the
38/// cost of a submission is bounded in both bytes and elements.
39const MAX_FIELDS: usize = 64;
40
41/// Longest refusal reason that reaches the client.
42///
43/// A reason is a sentence for a person to read, and the client has to lay it
44/// out. A handler that puts a transport diagnostic in one — a multi-line SMTP
45/// error with a support URL, say — produced a page the client refused to render
46/// at all, reporting "page exceeded client resource budget" and hiding the
47/// actual problem. Bounding it here means no handler can do that, rather than
48/// every handler having to remember not to.
49pub(crate) const MAX_REASON: usize = 200;
50
51/// The decoded fields of one submission, in the order they were sent.
52#[derive(Debug, Default, Clone)]
53pub struct FormFields {
54    fields: Vec<(String, String)>,
55}
56
57impl FormFields {
58    /// Decode `key=value&key2=value2`, as the reference client encodes it:
59    /// `+` for a space and `%XX` for anything else outside the unreserved set.
60    ///
61    /// Malformed input is decoded as far as it makes sense rather than
62    /// rejected: a stray `%` is kept literally, and a pair with no `=` becomes
63    /// a field with an empty value. A submission is not a place to be clever —
64    /// the handler decides what it requires, and every value is untrusted
65    /// either way.
66    pub fn parse(encoded: &str) -> Self {
67        let mut fields = Vec::new();
68        for pair in encoded.split('&') {
69            if pair.is_empty() || fields.len() >= MAX_FIELDS {
70                continue;
71            }
72            let (name, value) = match pair.split_once('=') {
73                Some((name, value)) => (name, value),
74                None => (pair, ""),
75            };
76            fields.push((decode(name), decode(value)));
77        }
78        Self { fields }
79    }
80
81    /// The first value sent under `name`.
82    ///
83    /// First rather than last, and stated here because the choice is only
84    /// invisible until two values disagree. A handler that cares which one it
85    /// got should use [`FormFields::all`] and decide deliberately.
86    pub fn get(&self, name: &str) -> Option<&str> {
87        self.fields
88            .iter()
89            .find(|(field, _)| field == name)
90            .map(|(_, value)| value.as_str())
91    }
92
93    /// Every value sent under `name`, in order.
94    pub fn all<'a>(&'a self, name: &'a str) -> impl Iterator<Item = &'a str> + 'a {
95        self.fields
96            .iter()
97            .filter(move |(field, _)| field == name)
98            .map(|(_, value)| value.as_str())
99    }
100
101    pub fn len(&self) -> usize {
102        self.fields.len()
103    }
104
105    pub fn is_empty(&self) -> bool {
106        self.fields.is_empty()
107    }
108}
109
110/// Percent-decode one form component, treating `+` as a space.
111///
112/// Builds bytes and then converts, so a multi-byte character split across
113/// several `%XX` escapes reassembles. Invalid UTF-8 becomes U+FFFD rather than
114/// an error: the field is untrusted text either way, and a replacement
115/// character is a better answer than refusing a whole submission.
116fn decode(value: &str) -> String {
117    let bytes = value.as_bytes();
118    let mut out: Vec<u8> = Vec::with_capacity(bytes.len());
119    let mut index = 0;
120    // Indexed with `get` throughout: the crate denies `clippy::indexing_slicing`
121    // because this is a parser over remote bytes, and "the bound is obvious
122    // from the loop condition" is exactly the reasoning that goes stale when
123    // someone edits the loop.
124    while let Some(&byte) = bytes.get(index) {
125        match byte {
126            b'+' => {
127                out.push(b' ');
128                index += 1;
129            }
130            b'%' => {
131                let pair = bytes
132                    .get(index + 1..index + 3)
133                    .and_then(|pair| std::str::from_utf8(pair).ok())
134                    .and_then(|pair| u8::from_str_radix(pair, 16).ok());
135                match pair {
136                    Some(decoded) => {
137                        out.push(decoded);
138                        index += 3;
139                    }
140                    // Truncated, or not hex: not an escape, so keep the `%`.
141                    None => {
142                        out.push(b'%');
143                        index += 1;
144                    }
145                }
146            }
147            other => {
148                out.push(other);
149                index += 1;
150            }
151        }
152    }
153    String::from_utf8_lossy(&out).into_owned()
154}
155
156/// What a handler is told about a submission.
157#[derive(Debug, Clone, Copy)]
158pub struct InputRequest<'a> {
159    /// The form's action path, with any query removed.
160    pub path: &'a str,
161    /// The query the action carried, if any — how a form says *which* thing it
162    /// acts on, as in `[form action="/index?reply=12"]`.
163    pub query: Option<&'a str>,
164    /// The submitted fields.
165    pub fields: &'a FormFields,
166    /// Who submitted, resolved from their session token, or `None` for
167    /// anonymous. Never the token itself — see [`crate::session`].
168    pub identity: Option<&'a str>,
169    /// Where the submission came from.
170    ///
171    /// Given here and not to the include resolver, because this is what abuse
172    /// control needs and rendering does not: a login endpoint that cannot count
173    /// attempts per source cannot be defended against guessing, and a global
174    /// counter would let one attacker lock out everybody.
175    pub peer: std::net::IpAddr,
176}
177
178/// A handler's answer to a submission.
179#[derive(Debug, Clone)]
180pub enum InputOutcome {
181    /// Accepted. The server answers with this page, rendered exactly as a GET
182    /// for it would be — same include resolution, same everything — so there is
183    /// one path that produces a page whether or not a submission preceded it.
184    Render {
185        path: String,
186        query: Option<String>,
187        /// Session changes to apply to the response — issuing a token on a
188        /// successful login, clearing one on logout. Part of the return value
189        /// rather than a side effect, so a handler that grants a session says
190        /// so in the value it hands back.
191        session: crate::session::SessionChange,
192    },
193    /// Refused, with a reason to show the person who submitted it.
194    ///
195    /// A short sentence for a person to read. Anything longer is truncated
196    /// before it reaches the wire — see [`MAX_REASON`].
197    Rejected(String),
198}
199
200impl InputOutcome {
201    /// Accept, and answer with `path` and no query.
202    pub fn render(path: impl Into<String>) -> Self {
203        Self::Render {
204            path: path.into(),
205            query: None,
206            session: crate::session::SessionChange::none(),
207        }
208    }
209
210    /// Accept, and answer with `path?query`.
211    pub fn render_query(path: impl Into<String>, query: impl Into<String>) -> Self {
212        Self::Render {
213            path: path.into(),
214            query: Some(query.into()),
215            session: crate::session::SessionChange::none(),
216        }
217    }
218
219    /// Attach session changes to an acceptance.
220    ///
221    /// A no-op on a refusal: a refused login must not issue a session, and
222    /// making that unrepresentable is better than trusting every caller to
223    /// remember it.
224    pub fn with_session(self, change: crate::session::SessionChange) -> Self {
225        match self {
226            Self::Render { path, query, .. } => Self::Render {
227                path,
228                query,
229                session: change,
230            },
231            rejected @ Self::Rejected(_) => rejected,
232        }
233    }
234}
235
236/// Handles form submissions for a site.
237pub trait InputHandler: Send + Sync {
238    fn handle(&self, request: &InputRequest<'_>) -> InputOutcome;
239}
240
241/// Trim a refusal reason to something a client can render.
242///
243/// Truncated on a character boundary, and marked so the reader can tell they are
244/// seeing part of a sentence rather than a badly-worded whole one.
245pub(crate) fn short_reason(reason: &str) -> String {
246    if reason.chars().count() <= MAX_REASON {
247        return reason.to_string();
248    }
249    let kept: String = reason.chars().take(MAX_REASON - 1).collect();
250    format!("{kept}…")
251}
252
253/// Split a form action into its path and query.
254pub(crate) fn split_query(action: &str) -> (&str, Option<&str>) {
255    match action.split_once('?') {
256        Some((path, query)) if !query.is_empty() => (path, Some(query)),
257        Some((path, _)) => (path, None),
258        None => (action, None),
259    }
260}
261
262#[cfg(test)]
263mod tests {
264    use super::*;
265
266    #[test]
267    fn parses_a_simple_submission() {
268        let fields = FormFields::parse("title=Hello&url=atp%3A%2F%2Fx.dust");
269        assert_eq!(fields.get("title"), Some("Hello"));
270        assert_eq!(fields.get("url"), Some("atp://x.dust"));
271        assert_eq!(fields.len(), 2);
272    }
273
274    #[test]
275    fn plus_is_a_space() {
276        let fields = FormFields::parse("q=hello+world");
277        assert_eq!(fields.get("q"), Some("hello world"));
278    }
279
280    /// A multi-byte character arrives as consecutive escapes and must be
281    /// reassembled, not decoded byte by byte into mojibake.
282    #[test]
283    fn multibyte_escapes_reassemble() {
284        let fields = FormFields::parse("t=caf%C3%A9+%E2%98%85");
285        assert_eq!(fields.get("t"), Some("café ★"));
286    }
287
288    /// Order is preserved and duplicates are kept, which the protocol
289    /// specifies. Collapsing them would make which value wins an accident.
290    #[test]
291    fn duplicate_names_are_all_retained_in_order() {
292        let fields = FormFields::parse("tag=a&tag=b&tag=c");
293        assert_eq!(fields.all("tag").collect::<Vec<_>>(), ["a", "b", "c"]);
294        assert_eq!(fields.get("tag"), Some("a"), "get returns the first");
295    }
296
297    #[test]
298    fn malformed_input_decodes_as_far_as_it_can() {
299        let fields = FormFields::parse("bare&a=%zz&b=%&c=x");
300        assert_eq!(fields.get("bare"), Some(""), "no = means empty value");
301        assert_eq!(fields.get("a"), Some("%zz"), "not hex, so not an escape");
302        assert_eq!(fields.get("b"), Some("%"), "truncated escape");
303        assert_eq!(fields.get("c"), Some("x"));
304    }
305
306    /// A bounded body can still carry a great many separators, so the parsed
307    /// vector is bounded too.
308    #[test]
309    fn field_count_is_bounded() {
310        let encoded = (0..MAX_FIELDS * 4)
311            .map(|index| format!("f{index}=v"))
312            .collect::<Vec<_>>()
313            .join("&");
314        assert_eq!(FormFields::parse(&encoded).len(), MAX_FIELDS);
315    }
316
317    #[test]
318    fn an_empty_body_is_no_fields() {
319        assert!(FormFields::parse("").is_empty());
320    }
321
322    /// A form action carries which thing it acts on as a query.
323    /// A handler that puts a transport diagnostic in a refusal must not be able
324    /// to hand the client something it cannot lay out.
325    #[test]
326    fn an_over_long_reason_is_truncated() {
327        let short = "a title is required";
328        assert_eq!(short_reason(short), short);
329
330        // The shape that caused it: a real SMTP 421 with a support URL.
331        let diagnostic = "could not send mail: transient error (421): 4.7.0 Try again \
332                          later, closing connection. (EHLO) For more information, go to \
333                          https://support.google.com/a/answer/3221692 \
334                          5b1f17b1804b1-499c2fb02ecsm5772355e9.4 - gsmtp";
335        let trimmed = short_reason(diagnostic);
336        assert!(trimmed.chars().count() <= MAX_REASON);
337        assert!(trimmed.ends_with('…'), "{trimmed}");
338    }
339
340    /// Truncation must not split a character.
341    #[test]
342    fn truncation_lands_on_a_character_boundary() {
343        let reason = "é".repeat(MAX_REASON * 2);
344        let trimmed = short_reason(&reason);
345        assert!(trimmed.chars().count() <= MAX_REASON);
346        assert!(trimmed.is_char_boundary(trimmed.len()));
347    }
348
349    #[test]
350    fn an_action_query_is_split_off() {
351        assert_eq!(split_query("/index?reply=12"), ("/index", Some("reply=12")));
352        assert_eq!(split_query("/index"), ("/index", None));
353        assert_eq!(split_query("/index?"), ("/index", None));
354    }
355
356    /// A refusal cannot be turned into a session. Attaching one to a rejection
357    /// is silently dropped rather than quietly granting a login that failed.
358    #[test]
359    fn a_refusal_cannot_carry_a_session() {
360        let outcome = InputOutcome::Rejected("nope".into())
361            .with_session(crate::session::SessionChange::set("t", "/", 1));
362        assert!(matches!(outcome, InputOutcome::Rejected(_)));
363    }
364
365    #[test]
366    fn a_session_attaches_to_an_acceptance() {
367        let outcome =
368            InputOutcome::render("/").with_session(crate::session::SessionChange::set("t", "/", 1));
369        match outcome {
370            InputOutcome::Render { session, .. } => assert!(!session.is_empty()),
371            other => panic!("expected Render, got {other:?}"),
372        }
373    }
374
375    #[test]
376    fn outcome_constructors_carry_the_query() {
377        match InputOutcome::render("/index") {
378            InputOutcome::Render { path, query, .. } => {
379                assert_eq!(path, "/index");
380                assert_eq!(query, None);
381            }
382            other => panic!("expected Render, got {other:?}"),
383        }
384        match InputOutcome::render_query("/index", "item=7") {
385            InputOutcome::Render { path, query, .. } => {
386                assert_eq!(path, "/index");
387                assert_eq!(query.as_deref(), Some("item=7"));
388            }
389            other => panic!("expected Render, got {other:?}"),
390        }
391    }
392
393    /// Values are never trusted, and nothing here tries to make them safe:
394    /// escaping is the serializer's job, at the point markup is written.
395    /// This pins that a hostile value survives decoding intact so the handler
396    /// sees exactly what was sent.
397    #[test]
398    fn hostile_values_are_delivered_verbatim() {
399        let hostile = r#"x" ][form action="/login"]"#;
400        let encoded = format!(
401            "title={}",
402            hostile
403                .bytes()
404                .map(|byte| format!("%{byte:02X}"))
405                .collect::<String>()
406        );
407        assert_eq!(FormFields::parse(&encoded).get("title"), Some(hostile));
408    }
409}