dustnet-server 0.2.1

ATP static-server library; install dustnetd to run a server
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
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
//! Accepting form submissions.
//!
//! Without a handler the server refuses `INPUT` with 405, which is what it did
//! before this module existed and what `dustnetd` still does. Installing a
//! handler is what lets a site accept a submission.
//!
//! # Fields are ordered and duplicates are kept
//!
//! [`docs/spec/02-protocol.md`](../../../docs/spec/02-protocol.md) says of the
//! INPUT body: "Repeated field names are permitted and retain document order."
//! So [`FormFields`] is a `Vec`, not a map. Collapsing duplicates would quietly
//! discard data and, worse, make *which* value survives depend on whether the
//! implementation kept the first or the last — a difference an attacker picks
//! and a reviewer does not see.
//!
//! # What a handler is told, and what it returns
//!
//! A handler gets the path, any query riding on the form's action, and the
//! fields. It returns [`InputOutcome`] — which page to answer with, or a
//! refusal — and **never markup**. Rendering goes through the include resolver
//! either way, so there is exactly one place that generates a page and it
//! behaves the same whether or not a submission preceded it.
//!
//! An accepted submission is answered with the target *page*, not a redirect.
//! That is forced by the protocol rather than chosen: `validate_redirect_body`
//! requires an absolute `atp://` target, because the client resolves it with
//! `AtpUri::parse` rather than against the current URI — and a server does not
//! know its own public hostname, only the address it happens to be bound to.
//! Answering with the page is what
//! [`docs/spec/02-protocol.md`](../../../docs/spec/02-protocol.md) permits
//! ("The server responds with a PAGE, REDIRECT, or ERROR") and costs one round
//! trip instead of two.

/// Most fields one submission may carry.
///
/// The body is already bounded by `MAX_INPUT_MESSAGE_SIZE`, but a bounded body
/// can still hold a great many `&`s. This bounds the parsed vector too, so the
/// cost of a submission is bounded in both bytes and elements.
const MAX_FIELDS: usize = 64;

/// Longest refusal reason that reaches the client.
///
/// A reason is a sentence for a person to read, and the client has to lay it
/// out. A handler that puts a transport diagnostic in one — a multi-line SMTP
/// error with a support URL, say — produced a page the client refused to render
/// at all, reporting "page exceeded client resource budget" and hiding the
/// actual problem. Bounding it here means no handler can do that, rather than
/// every handler having to remember not to.
pub(crate) const MAX_REASON: usize = 200;

/// The decoded fields of one submission, in the order they were sent.
#[derive(Debug, Default, Clone)]
pub struct FormFields {
    fields: Vec<(String, String)>,
}

impl FormFields {
    /// Decode `key=value&key2=value2`, as the reference client encodes it:
    /// `+` for a space and `%XX` for anything else outside the unreserved set.
    ///
    /// Malformed input is decoded as far as it makes sense rather than
    /// rejected: a stray `%` is kept literally, and a pair with no `=` becomes
    /// a field with an empty value. A submission is not a place to be clever —
    /// the handler decides what it requires, and every value is untrusted
    /// either way.
    pub fn parse(encoded: &str) -> Self {
        let mut fields = Vec::new();
        for pair in encoded.split('&') {
            if pair.is_empty() || fields.len() >= MAX_FIELDS {
                continue;
            }
            let (name, value) = match pair.split_once('=') {
                Some((name, value)) => (name, value),
                None => (pair, ""),
            };
            fields.push((decode(name), decode(value)));
        }
        Self { fields }
    }

    /// The first value sent under `name`.
    ///
    /// First rather than last, and stated here because the choice is only
    /// invisible until two values disagree. A handler that cares which one it
    /// got should use [`FormFields::all`] and decide deliberately.
    pub fn get(&self, name: &str) -> Option<&str> {
        self.fields
            .iter()
            .find(|(field, _)| field == name)
            .map(|(_, value)| value.as_str())
    }

    /// Every value sent under `name`, in order.
    pub fn all<'a>(&'a self, name: &'a str) -> impl Iterator<Item = &'a str> + 'a {
        self.fields
            .iter()
            .filter(move |(field, _)| field == name)
            .map(|(_, value)| value.as_str())
    }

    pub fn len(&self) -> usize {
        self.fields.len()
    }

    pub fn is_empty(&self) -> bool {
        self.fields.is_empty()
    }
}

/// Percent-decode one form component, treating `+` as a space.
///
/// Builds bytes and then converts, so a multi-byte character split across
/// several `%XX` escapes reassembles. Invalid UTF-8 becomes U+FFFD rather than
/// an error: the field is untrusted text either way, and a replacement
/// character is a better answer than refusing a whole submission.
fn decode(value: &str) -> String {
    let bytes = value.as_bytes();
    let mut out: Vec<u8> = Vec::with_capacity(bytes.len());
    let mut index = 0;
    // Indexed with `get` throughout: the crate denies `clippy::indexing_slicing`
    // because this is a parser over remote bytes, and "the bound is obvious
    // from the loop condition" is exactly the reasoning that goes stale when
    // someone edits the loop.
    while let Some(&byte) = bytes.get(index) {
        match byte {
            b'+' => {
                out.push(b' ');
                index += 1;
            }
            b'%' => {
                let pair = bytes
                    .get(index + 1..index + 3)
                    .and_then(|pair| std::str::from_utf8(pair).ok())
                    .and_then(|pair| u8::from_str_radix(pair, 16).ok());
                match pair {
                    Some(decoded) => {
                        out.push(decoded);
                        index += 3;
                    }
                    // Truncated, or not hex: not an escape, so keep the `%`.
                    None => {
                        out.push(b'%');
                        index += 1;
                    }
                }
            }
            other => {
                out.push(other);
                index += 1;
            }
        }
    }
    String::from_utf8_lossy(&out).into_owned()
}

/// What a handler is told about a submission.
#[derive(Debug, Clone, Copy)]
pub struct InputRequest<'a> {
    /// The form's action path, with any query removed.
    pub path: &'a str,
    /// The query the action carried, if any — how a form says *which* thing it
    /// acts on, as in `[form action="/index?reply=12"]`.
    pub query: Option<&'a str>,
    /// The submitted fields.
    pub fields: &'a FormFields,
    /// Who submitted, resolved from their session token, or `None` for
    /// anonymous. Never the token itself — see [`crate::session`].
    pub identity: Option<&'a str>,
    /// Where the submission came from.
    ///
    /// Given here and not to the include resolver, because this is what abuse
    /// control needs and rendering does not: a login endpoint that cannot count
    /// attempts per source cannot be defended against guessing, and a global
    /// counter would let one attacker lock out everybody.
    pub peer: std::net::IpAddr,
}

/// A handler's answer to a submission.
#[derive(Debug, Clone)]
pub enum InputOutcome {
    /// Accepted. The server answers with this page, rendered exactly as a GET
    /// for it would be — same include resolution, same everything — so there is
    /// one path that produces a page whether or not a submission preceded it.
    Render {
        path: String,
        query: Option<String>,
        /// Session changes to apply to the response — issuing a token on a
        /// successful login, clearing one on logout. Part of the return value
        /// rather than a side effect, so a handler that grants a session says
        /// so in the value it hands back.
        session: crate::session::SessionChange,
    },
    /// Refused, with a reason to show the person who submitted it.
    ///
    /// A short sentence for a person to read. Anything longer is truncated
    /// before it reaches the wire — see [`MAX_REASON`].
    Rejected(String),
}

impl InputOutcome {
    /// Accept, and answer with `path` and no query.
    pub fn render(path: impl Into<String>) -> Self {
        Self::Render {
            path: path.into(),
            query: None,
            session: crate::session::SessionChange::none(),
        }
    }

    /// Accept, and answer with `path?query`.
    pub fn render_query(path: impl Into<String>, query: impl Into<String>) -> Self {
        Self::Render {
            path: path.into(),
            query: Some(query.into()),
            session: crate::session::SessionChange::none(),
        }
    }

    /// Attach session changes to an acceptance.
    ///
    /// A no-op on a refusal: a refused login must not issue a session, and
    /// making that unrepresentable is better than trusting every caller to
    /// remember it.
    pub fn with_session(self, change: crate::session::SessionChange) -> Self {
        match self {
            Self::Render { path, query, .. } => Self::Render {
                path,
                query,
                session: change,
            },
            rejected @ Self::Rejected(_) => rejected,
        }
    }
}

/// Handles form submissions for a site.
pub trait InputHandler: Send + Sync {
    fn handle(&self, request: &InputRequest<'_>) -> InputOutcome;
}

/// Trim a refusal reason to something a client can render.
///
/// Truncated on a character boundary, and marked so the reader can tell they are
/// seeing part of a sentence rather than a badly-worded whole one.
pub(crate) fn short_reason(reason: &str) -> String {
    if reason.chars().count() <= MAX_REASON {
        return reason.to_string();
    }
    let kept: String = reason.chars().take(MAX_REASON - 1).collect();
    format!("{kept}…")
}

/// Split a form action into its path and query.
pub(crate) fn split_query(action: &str) -> (&str, Option<&str>) {
    match action.split_once('?') {
        Some((path, query)) if !query.is_empty() => (path, Some(query)),
        Some((path, _)) => (path, None),
        None => (action, None),
    }
}

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

    #[test]
    fn parses_a_simple_submission() {
        let fields = FormFields::parse("title=Hello&url=atp%3A%2F%2Fx.dust");
        assert_eq!(fields.get("title"), Some("Hello"));
        assert_eq!(fields.get("url"), Some("atp://x.dust"));
        assert_eq!(fields.len(), 2);
    }

    #[test]
    fn plus_is_a_space() {
        let fields = FormFields::parse("q=hello+world");
        assert_eq!(fields.get("q"), Some("hello world"));
    }

    /// A multi-byte character arrives as consecutive escapes and must be
    /// reassembled, not decoded byte by byte into mojibake.
    #[test]
    fn multibyte_escapes_reassemble() {
        let fields = FormFields::parse("t=caf%C3%A9+%E2%98%85");
        assert_eq!(fields.get("t"), Some("café ★"));
    }

    /// Order is preserved and duplicates are kept, which the protocol
    /// specifies. Collapsing them would make which value wins an accident.
    #[test]
    fn duplicate_names_are_all_retained_in_order() {
        let fields = FormFields::parse("tag=a&tag=b&tag=c");
        assert_eq!(fields.all("tag").collect::<Vec<_>>(), ["a", "b", "c"]);
        assert_eq!(fields.get("tag"), Some("a"), "get returns the first");
    }

    #[test]
    fn malformed_input_decodes_as_far_as_it_can() {
        let fields = FormFields::parse("bare&a=%zz&b=%&c=x");
        assert_eq!(fields.get("bare"), Some(""), "no = means empty value");
        assert_eq!(fields.get("a"), Some("%zz"), "not hex, so not an escape");
        assert_eq!(fields.get("b"), Some("%"), "truncated escape");
        assert_eq!(fields.get("c"), Some("x"));
    }

    /// A bounded body can still carry a great many separators, so the parsed
    /// vector is bounded too.
    #[test]
    fn field_count_is_bounded() {
        let encoded = (0..MAX_FIELDS * 4)
            .map(|index| format!("f{index}=v"))
            .collect::<Vec<_>>()
            .join("&");
        assert_eq!(FormFields::parse(&encoded).len(), MAX_FIELDS);
    }

    #[test]
    fn an_empty_body_is_no_fields() {
        assert!(FormFields::parse("").is_empty());
    }

    /// A form action carries which thing it acts on as a query.
    /// A handler that puts a transport diagnostic in a refusal must not be able
    /// to hand the client something it cannot lay out.
    #[test]
    fn an_over_long_reason_is_truncated() {
        let short = "a title is required";
        assert_eq!(short_reason(short), short);

        // The shape that caused it: a real SMTP 421 with a support URL.
        let diagnostic = "could not send mail: transient error (421): 4.7.0 Try again \
                          later, closing connection. (EHLO) For more information, go to \
                          https://support.google.com/a/answer/3221692 \
                          5b1f17b1804b1-499c2fb02ecsm5772355e9.4 - gsmtp";
        let trimmed = short_reason(diagnostic);
        assert!(trimmed.chars().count() <= MAX_REASON);
        assert!(trimmed.ends_with('…'), "{trimmed}");
    }

    /// Truncation must not split a character.
    #[test]
    fn truncation_lands_on_a_character_boundary() {
        let reason = "é".repeat(MAX_REASON * 2);
        let trimmed = short_reason(&reason);
        assert!(trimmed.chars().count() <= MAX_REASON);
        assert!(trimmed.is_char_boundary(trimmed.len()));
    }

    #[test]
    fn an_action_query_is_split_off() {
        assert_eq!(split_query("/index?reply=12"), ("/index", Some("reply=12")));
        assert_eq!(split_query("/index"), ("/index", None));
        assert_eq!(split_query("/index?"), ("/index", None));
    }

    /// A refusal cannot be turned into a session. Attaching one to a rejection
    /// is silently dropped rather than quietly granting a login that failed.
    #[test]
    fn a_refusal_cannot_carry_a_session() {
        let outcome = InputOutcome::Rejected("nope".into())
            .with_session(crate::session::SessionChange::set("t", "/", 1));
        assert!(matches!(outcome, InputOutcome::Rejected(_)));
    }

    #[test]
    fn a_session_attaches_to_an_acceptance() {
        let outcome =
            InputOutcome::render("/").with_session(crate::session::SessionChange::set("t", "/", 1));
        match outcome {
            InputOutcome::Render { session, .. } => assert!(!session.is_empty()),
            other => panic!("expected Render, got {other:?}"),
        }
    }

    #[test]
    fn outcome_constructors_carry_the_query() {
        match InputOutcome::render("/index") {
            InputOutcome::Render { path, query, .. } => {
                assert_eq!(path, "/index");
                assert_eq!(query, None);
            }
            other => panic!("expected Render, got {other:?}"),
        }
        match InputOutcome::render_query("/index", "item=7") {
            InputOutcome::Render { path, query, .. } => {
                assert_eq!(path, "/index");
                assert_eq!(query.as_deref(), Some("item=7"));
            }
            other => panic!("expected Render, got {other:?}"),
        }
    }

    /// Values are never trusted, and nothing here tries to make them safe:
    /// escaping is the serializer's job, at the point markup is written.
    /// This pins that a hostile value survives decoding intact so the handler
    /// sees exactly what was sent.
    #[test]
    fn hostile_values_are_delivered_verbatim() {
        let hostile = r#"x" ][form action="/login"]"#;
        let encoded = format!(
            "title={}",
            hostile
                .bytes()
                .map(|byte| format!("%{byte:02X}"))
                .collect::<String>()
        );
        assert_eq!(FormFields::parse(&encoded).get("title"), Some(hostile));
    }
}