Vendor dependencies

notes-service/vendor/stringprep/src/lib.rs

@@ -0,0 +1,437 @@
+//! An implementation of the "stringprep" algorithm defined in [RFC 3454][].
+//!
+//! [RFC 3454]: https://tools.ietf.org/html/rfc3454
+#![warn(missing_docs)]
+extern crate unicode_bidi;
+extern crate unicode_normalization;
+extern crate unicode_properties;
+
+use std::borrow::Cow;
+use std::fmt;
+use unicode_normalization::UnicodeNormalization;
+use unicode_properties::{GeneralCategoryGroup, UnicodeGeneralCategory};
+
+mod rfc3454;
+pub mod tables;
+
+/// Describes why a string failed stringprep normalization.
+#[derive(Debug)]
+enum ErrorCause {
+    /// Contains stringprep prohibited characters.
+    ProhibitedCharacter(char),
+    /// Violates stringprep rules for bidirectional text.
+    ProhibitedBidirectionalText,
+    /// Starts with a combining character
+    StartsWithCombiningCharacter,
+    /// Empty String
+    EmptyString,
+}
+
+/// An error performing the stringprep algorithm.
+#[derive(Debug)]
+pub struct Error(ErrorCause);
+
+impl fmt::Display for Error {
+    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
+        match self.0 {
+            ErrorCause::ProhibitedCharacter(c) => write!(fmt, "prohibited character `{}`", c),
+            ErrorCause::ProhibitedBidirectionalText => write!(fmt, "prohibited bidirectional text"),
+            ErrorCause::StartsWithCombiningCharacter => {
+                write!(fmt, "starts with combining character")
+            }
+            ErrorCause::EmptyString => write!(fmt, "empty string"),
+        }
+    }
+}
+
+impl std::error::Error for Error {}
+
+/// Prepares a string with the SASLprep profile of the stringprep algorithm.
+///
+/// SASLprep is defined in [RFC 4013][].
+///
+/// [RFC 4013]: https://tools.ietf.org/html/rfc4013
+pub fn saslprep(s: &str) -> Result<Cow<'_, str>, Error> {
+    // fast path for ascii text
+    if s.chars()
+        .all(|c| c.is_ascii() && !tables::ascii_control_character(c))
+    {
+        return Ok(Cow::Borrowed(s));
+    }
+
+    // 2.1 Mapping
+    let mapped = s
+        .chars()
+        .map(|c| {
+            if tables::non_ascii_space_character(c) {
+                ' '
+            } else {
+                c
+            }
+        })
+        .filter(|&c| !tables::commonly_mapped_to_nothing(c));
+
+    // 2.2 Normalization
+    let normalized = mapped.nfkc().collect::<String>();
+
+    // 2.3 Prohibited Output
+    let prohibited = normalized.chars().find(|&c| {
+        tables::non_ascii_space_character(c) /* C.1.2 */ ||
+            tables::ascii_control_character(c) /* C.2.1 */ ||
+            tables::non_ascii_control_character(c) /* C.2.2 */ ||
+            tables::private_use(c) /* C.3 */ ||
+            tables::non_character_code_point(c) /* C.4 */ ||
+            tables::surrogate_code(c) /* C.5 */ ||
+            tables::inappropriate_for_plain_text(c) /* C.6 */ ||
+            tables::inappropriate_for_canonical_representation(c) /* C.7 */ ||
+            tables::change_display_properties_or_deprecated(c) /* C.8 */ ||
+            tables::tagging_character(c) /* C.9 */
+    });
+    if let Some(c) = prohibited {
+        return Err(Error(ErrorCause::ProhibitedCharacter(c)));
+    }
+
+    // 2.4. Bidirectional Characters
+    if is_prohibited_bidirectional_text(&normalized) {
+        return Err(Error(ErrorCause::ProhibitedBidirectionalText));
+    }
+
+    // 2.5 Unassigned Code Points
+    let unassigned = normalized
+        .chars()
+        .find(|&c| tables::unassigned_code_point(c));
+    if let Some(c) = unassigned {
+        return Err(Error(ErrorCause::ProhibitedCharacter(c)));
+    }
+
+    Ok(Cow::Owned(normalized))
+}
+
+// RFC3454, 6. Bidirectional Characters
+fn is_prohibited_bidirectional_text(s: &str) -> bool {
+    if s.contains(tables::bidi_r_or_al) {
+        // 2) If a string contains any RandALCat character, the string
+        // MUST NOT contain any LCat character.
+        if s.contains(tables::bidi_l) {
+            return true;
+        }
+
+        // 3) If a string contains any RandALCat character, a RandALCat
+        // character MUST be the first character of the string, and a
+        // RandALCat character MUST be the last character of the string.
+        if !tables::bidi_r_or_al(s.chars().next().unwrap())
+            || !tables::bidi_r_or_al(s.chars().next_back().unwrap())
+        {
+            return true;
+        }
+    }
+
+    false
+}
+
+/// Prepares a string with the Nameprep profile of the stringprep algorithm.
+///
+/// Nameprep is defined in [RFC 3491][].
+///
+/// [RFC 3491]: https://tools.ietf.org/html/rfc3491
+pub fn nameprep(s: &str) -> Result<Cow<'_, str>, Error> {
+    // fast path for ascii text
+    if s.chars()
+        .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '.' || c == '-')
+    {
+        return Ok(Cow::Borrowed(s));
+    }
+
+    // 3. Mapping
+    let mapped = s
+        .chars()
+        .filter(|&c| !tables::commonly_mapped_to_nothing(c))
+        .flat_map(tables::case_fold_for_nfkc);
+
+    // 4. Normalization
+    let normalized = mapped.nfkc().collect::<String>();
+
+    // 5. Prohibited Output
+    let prohibited = normalized.chars().find(|&c| {
+        tables::non_ascii_space_character(c) /* C.1.2 */ ||
+            tables::non_ascii_control_character(c) /* C.2.2 */ ||
+            tables::private_use(c) /* C.3 */ ||
+            tables::non_character_code_point(c) /* C.4 */ ||
+            tables::surrogate_code(c) /* C.5 */ ||
+            tables::inappropriate_for_plain_text(c) /* C.6 */ ||
+            tables::inappropriate_for_canonical_representation(c) /* C.7 */ ||
+            tables::change_display_properties_or_deprecated(c) /* C.9 */ ||
+            tables::tagging_character(c) /* C.9 */
+    });
+    if let Some(c) = prohibited {
+        return Err(Error(ErrorCause::ProhibitedCharacter(c)));
+    }
+
+    // 6. Bidirectional Characters
+    if is_prohibited_bidirectional_text(&normalized) {
+        return Err(Error(ErrorCause::ProhibitedBidirectionalText));
+    }
+
+    // 7 Unassigned Code Points
+    let unassigned = normalized
+        .chars()
+        .find(|&c| tables::unassigned_code_point(c));
+    if let Some(c) = unassigned {
+        return Err(Error(ErrorCause::ProhibitedCharacter(c)));
+    }
+
+    Ok(Cow::Owned(normalized))
+}
+
+/// Prepares a string with the Nodeprep profile of the stringprep algorithm.
+///
+/// Nameprep is defined in [RFC 3920, Appendix A][].
+///
+/// [RFC 3920, Appendix A]: https://tools.ietf.org/html/rfc3920#appendix-A
+pub fn nodeprep(s: &str) -> Result<Cow<'_, str>, Error> {
+    // fast path for common ascii text
+    if s.chars()
+        .all(|c| matches!(c, '['..='~' | '0'..='9' | '('..='.' | '#'..='%'))
+    {
+        return Ok(Cow::Borrowed(s));
+    }
+
+    // A.3. Mapping
+    let mapped = s
+        .chars()
+        .filter(|&c| !tables::commonly_mapped_to_nothing(c))
+        .flat_map(tables::case_fold_for_nfkc);
+
+    // A.4. Normalization
+    let normalized = mapped.nfkc().collect::<String>();
+
+    // A.5. Prohibited Output
+    let prohibited = normalized.chars().find(|&c| {
+        tables::ascii_space_character(c) /* C.1.1 */ ||
+            tables::non_ascii_space_character(c) /* C.1.2 */ ||
+            tables::ascii_control_character(c) /* C.2.1 */ ||
+            tables::non_ascii_control_character(c) /* C.2.2 */ ||
+            tables::private_use(c) /* C.3 */ ||
+            tables::non_character_code_point(c) /* C.4 */ ||
+            tables::surrogate_code(c) /* C.5 */ ||
+            tables::inappropriate_for_plain_text(c) /* C.6 */ ||
+            tables::inappropriate_for_canonical_representation(c) /* C.7 */ ||
+            tables::change_display_properties_or_deprecated(c) /* C.9 */ ||
+            tables::tagging_character(c) /* C.9 */ ||
+            prohibited_node_character(c)
+    });
+    if let Some(c) = prohibited {
+        return Err(Error(ErrorCause::ProhibitedCharacter(c)));
+    }
+
+    // A.6. Bidirectional Characters
+    if is_prohibited_bidirectional_text(&normalized) {
+        return Err(Error(ErrorCause::ProhibitedBidirectionalText));
+    }
+
+    let unassigned = normalized
+        .chars()
+        .find(|&c| tables::unassigned_code_point(c));
+    if let Some(c) = unassigned {
+        return Err(Error(ErrorCause::ProhibitedCharacter(c)));
+    }
+
+    Ok(Cow::Owned(normalized))
+}
+
+// Additional characters not allowed in JID nodes, by RFC3920.
+fn prohibited_node_character(c: char) -> bool {
+    matches!(c, '"' | '&' | '\'' | '/' | ':' | '<' | '>' | '@')
+}
+
+/// Prepares a string with the Resourceprep profile of the stringprep algorithm.
+///
+/// Nameprep is defined in [RFC 3920, Appendix B][].
+///
+/// [RFC 3920, Appendix B]: https://tools.ietf.org/html/rfc3920#appendix-B
+pub fn resourceprep(s: &str) -> Result<Cow<'_, str>, Error> {
+    // fast path for ascii text
+    if s.chars().all(|c| matches!(c, ' '..='~')) {
+        return Ok(Cow::Borrowed(s));
+    }
+
+    // B.3. Mapping
+    let mapped = s
+        .chars()
+        .filter(|&c| !tables::commonly_mapped_to_nothing(c))
+        .collect::<String>();
+
+    // B.4. Normalization
+    let normalized = mapped.nfkc().collect::<String>();
+
+    // B.5. Prohibited Output
+    let prohibited = normalized.chars().find(|&c| {
+        tables::non_ascii_space_character(c) /* C.1.2 */ ||
+            tables::ascii_control_character(c) /* C.2.1 */ ||
+            tables::non_ascii_control_character(c) /* C.2.2 */ ||
+            tables::private_use(c) /* C.3 */ ||
+            tables::non_character_code_point(c) /* C.4 */ ||
+            tables::surrogate_code(c) /* C.5 */ ||
+            tables::inappropriate_for_plain_text(c) /* C.6 */ ||
+            tables::inappropriate_for_canonical_representation(c) /* C.7 */ ||
+            tables::change_display_properties_or_deprecated(c) /* C.9 */ ||
+            tables::tagging_character(c) /* C.9 */
+    });
+    if let Some(c) = prohibited {
+        return Err(Error(ErrorCause::ProhibitedCharacter(c)));
+    }
+
+    // B.6. Bidirectional Characters
+    if is_prohibited_bidirectional_text(&normalized) {
+        return Err(Error(ErrorCause::ProhibitedBidirectionalText));
+    }
+
+    let unassigned = normalized
+        .chars()
+        .find(|&c| tables::unassigned_code_point(c));
+    if let Some(c) = unassigned {
+        return Err(Error(ErrorCause::ProhibitedCharacter(c)));
+    }
+
+    Ok(Cow::Owned(normalized))
+}
+
+/// Prepares a string according to the procedures described in Section 7 of
+/// [ITU-T Recommendation X.520 (2019)](https://www.itu.int/rec/T-REC-X.520-201910-I/en).
+///
+/// Note that this function does _not_ remove leading, trailing, or inner
+/// spaces as described in Section 7.6, because the characters needing removal
+/// will vary across the matching rules and ASN.1 syntaxes used.
+pub fn x520prep(s: &str, case_fold: bool) -> Result<Cow<'_, str>, Error> {
+    if s.is_empty() {
+        return Err(Error(ErrorCause::EmptyString));
+    }
+    if s.chars()
+        .all(|c| matches!(c, ' '..='~') && (!case_fold || c.is_ascii_lowercase()))
+    {
+        return Ok(Cow::Borrowed(s));
+    }
+
+    // 1. Transcode
+    // Already done because &str is enforced to be Unicode.
+
+    // 2. Map
+    let mapped = s
+        .chars()
+        .filter(|&c| !tables::x520_mapped_to_nothing(c))
+        .map(|c| {
+            if tables::x520_mapped_to_space(c) {
+                ' '
+            } else {
+                c
+            }
+        });
+
+    // 3. Normalize
+    let normalized = if case_fold {
+        mapped
+            .flat_map(tables::case_fold_for_nfkc)
+            .collect::<String>()
+    } else {
+        mapped.nfkc().collect::<String>()
+    };
+
+    // 4. Prohibit
+    let prohibited = normalized.chars().find(
+        |&c| {
+            tables::unassigned_code_point(c)
+                || tables::private_use(c)
+                || tables::non_character_code_point(c)
+                || tables::surrogate_code(c)
+                || c == '\u{FFFD}'
+        }, // REPLACEMENT CHARACTER
+    );
+    if let Some(c) = prohibited {
+        return Err(Error(ErrorCause::ProhibitedCharacter(c)));
+    }
+    // From ITU-T Recommendation X.520, Section 7.4:
+    // "The first code point of a string is prohibited from being a combining character."
+    match s.chars().next() {
+        Some(c) => {
+            if c.general_category_group() == GeneralCategoryGroup::Mark {
+                return Err(Error(ErrorCause::StartsWithCombiningCharacter));
+            }
+        }
+        None => return Err(Error(ErrorCause::EmptyString)),
+    }
+
+    // 5. Check bidi
+    // From ITU-T Recommendation X.520, Section 7.4:
+    // "There are no bidirectional restrictions. The output string is the input string."
+    // So there is nothing to do for this step.
+
+    // 6. Insignificant Character Removal
+    // Done in calling functions.
+
+    Ok(normalized.into())
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
+
+    fn assert_prohibited_character<T>(result: Result<T, Error>) {
+        match result {
+            Err(Error(ErrorCause::ProhibitedCharacter(_))) => (),
+            _ => panic!(),
+        }
+    }
+
+    fn assert_starts_with_combining_char<T>(result: Result<T, Error>) {
+        match result {
+            Err(Error(ErrorCause::StartsWithCombiningCharacter)) => (),
+            _ => panic!(),
+        }
+    }
+
+    // RFC4013, 3. Examples
+    #[test]
+    fn saslprep_examples() {
+        assert_prohibited_character(saslprep("\u{0007}"));
+    }
+
+    #[test]
+    fn nodeprep_examples() {
+        assert_prohibited_character(nodeprep(" "));
+        assert_prohibited_character(nodeprep("\u{00a0}"));
+        assert_prohibited_character(nodeprep("foo@bar"));
+    }
+
+    #[test]
+    fn resourceprep_examples() {
+        assert_eq!("foo@bar", resourceprep("foo@bar").unwrap());
+    }
+
+    #[test]
+    fn x520prep_examples() {
+        assert_eq!(x520prep("foo@bar", true).unwrap(), "foo@bar");
+        assert_eq!(
+            x520prep("J.\u{FE00} \u{9}W. \u{B}wuz h\u{0115}re", false).unwrap(),
+            "J.  W.  wuz h\u{0115}re"
+        );
+        assert_eq!(
+            x520prep("J.\u{FE00} \u{9}W. \u{B}wuz h\u{0115}re", true).unwrap(),
+            "j.  w.  wuz h\u{0115}re"
+        );
+        assert_eq!(x520prep("UPPERCASED", true).unwrap(), "uppercased");
+        assert_starts_with_combining_char(x520prep("\u{0306}hello", true));
+    }
+
+    #[test]
+    fn ascii_optimisations() {
+        if let Cow::Owned(_) = nodeprep("nodepart").unwrap() {
+            panic!("“nodepart” should get optimised as ASCII");
+        }
+        if let Cow::Owned(_) = nameprep("domainpart.example").unwrap() {
+            panic!("“domainpart.example” should get optimised as ASCII");
+        }
+        if let Cow::Owned(_) = resourceprep("resourcepart").unwrap() {
+            panic!("“resourcepart” should get optimised as ASCII");
+        }
+    }
+}