webfinger-rs 0.0.31

WebFinger request and response types for Rust, with first-party Reqwest, Axum, and Actix Web integrations.
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

use std::str::FromStr;

use http::Uri;
use http::uri::{InvalidUri, PathAndQuery, Scheme};
use percent_encoding::{AsciiSet, utf8_percent_encode};

use crate::{WELL_KNOWN_PATH, WebFingerRequest, WebFingerResponse};

pub(crate) const CORS_ALLOW_ORIGIN: &str = "*";

/// The set of bytes to percent-encode in WebFinger query parameter values.
///
/// RFC 7033 section 4.1 percent-encodes the `resource` and `rel` parameter values before placing
/// them in the query component. Only RFC 3986 unreserved characters are left literal here, which
/// matches the RFC examples and keeps URI delimiters inside parameter values unambiguous. The set
/// includes `%` so already-percent-encoded resource or relation URIs survive WebFinger query
/// parsing as literal percent escapes in the target value.
///
/// See the following RFCs for more information:
/// - <https://www.rfc-editor.org/rfc/rfc7033#section-4.1>
/// - <https://www.rfc-editor.org/rfc/rfc3986#section-2.1>
/// - <https://www.rfc-editor.org/rfc/rfc3986#section-3.4>
/// - <https://www.rfc-editor.org/rfc/rfc3986#appendix-A>
///
/// Note: this may be implemented in the `percent-encoding` crate soon in
/// <https://github.com/servo/rust-url/pull/971>
const QUERY: AsciiSet = percent_encoding::CONTROLS
    .add(b' ')
    .add(b'!')
    .add(b'"')
    .add(b'#')
    .add(b'$')
    .add(b'%')
    .add(b'&')
    .add(b'\'')
    .add(b'(')
    .add(b')')
    .add(b'*')
    .add(b'+')
    .add(b',')
    .add(b'/')
    .add(b':')
    .add(b';')
    .add(b'<')
    .add(b'=')
    .add(b'>')
    .add(b'?')
    .add(b'@')
    .add(b'[')
    .add(b'\\')
    .add(b']')
    .add(b'^')
    .add(b'`')
    .add(b'{')
    .add(b'|')
    .add(b'}');

impl TryFrom<&WebFingerRequest> for PathAndQuery {
    type Error = InvalidUri;

    fn try_from(query: &WebFingerRequest) -> Result<PathAndQuery, InvalidUri> {
        let resource = query.resource.to_string();
        let resource = utf8_percent_encode(&resource, &QUERY).to_string();
        let mut path = WELL_KNOWN_PATH.to_owned();
        path.push_str("?resource=");
        path.push_str(&resource);
        for rel in &query.rels {
            let rel = utf8_percent_encode(rel.as_ref(), &QUERY).to_string();
            path.push_str("&rel=");
            path.push_str(&rel);
        }
        PathAndQuery::from_str(&path)
    }
}

impl TryFrom<&WebFingerRequest> for Uri {
    type Error = http::Error;

    fn try_from(query: &WebFingerRequest) -> Result<Uri, http::Error> {
        let path_and_query = PathAndQuery::try_from(query)?;

        // HTTPS is mandatory
        // <https://www.rfc-editor.org/rfc/rfc7033.html#section-4>
        // <https://www.rfc-editor.org/rfc/rfc7033.html#section-9.1>
        const SCHEME: Scheme = Scheme::HTTPS;

        Uri::builder()
            .scheme(SCHEME)
            .authority(query.host.clone())
            .path_and_query(path_and_query)
            .build()
    }
}

impl TryFrom<&WebFingerResponse> for http::Response<()> {
    type Error = http::Error;
    fn try_from(_: &WebFingerResponse) -> Result<http::Response<()>, http::Error> {
        http::Response::builder()
            .header("Content-Type", "application/jrd+json")
            .header("Access-Control-Allow-Origin", CORS_ALLOW_ORIGIN)
            .body(())
    }
}

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

    /// Percent-encodes literal percent signs in the outgoing `resource` value.
    ///
    /// RFC 7033 section 4.1 puts the resource URI inside a WebFinger query parameter. If the target
    /// URI already contains percent escapes, the `%` signs must become `%25` in the outer query or a
    /// server will decode them as part of the WebFinger parameter and change the target resource.
    ///
    /// See <https://www.rfc-editor.org/rfc/rfc7033.html#section-4.1> and
    /// <https://www.rfc-editor.org/rfc/rfc3986.html#section-2.1>.
    #[test]
    fn outgoing_resource_preserves_inner_percent_escapes() {
        let request = WebFingerRequest {
            resource: "https://example.org/profile/a%20b".parse().unwrap(),
            host: "example.org".to_string(),
            rels: Vec::new(),
        };

        let uri = Uri::try_from(&request).unwrap();

        assert_eq!(
            uri.to_string(),
            "https://example.org/.well-known/webfinger?resource=https%3A%2F%2Fexample.org%2Fprofile%2Fa%2520b",
        );
    }

    /// Percent-encodes literal percent signs in outgoing `rel` values.
    ///
    /// Relation filters are also WebFinger query parameter values. Encoding `%` prevents an already
    /// escaped relation URI from being decoded one level too far by the receiving WebFinger server.
    ///
    /// See <https://www.rfc-editor.org/rfc/rfc7033.html#section-4.1> and
    /// <https://www.rfc-editor.org/rfc/rfc3986.html#section-2.1>.
    #[test]
    fn outgoing_rel_preserves_inner_percent_escapes() {
        let request = WebFingerRequest {
            resource: "acct:carol@example.org".parse().unwrap(),
            host: "example.org".to_string(),
            rels: vec![Rel::new("https://example.org/rel/a%2Fb")],
        };

        let uri = Uri::try_from(&request).unwrap();

        assert_eq!(
            uri.to_string(),
            "https://example.org/.well-known/webfinger?resource=acct%3Acarol%40example.org&rel=https%3A%2F%2Fexample.org%2Frel%2Fa%252Fb",
        );
    }
}