alpm_types/
openpgp.rs

1use std::{
2    fmt::{Display, Formatter},
3    str::FromStr,
4    string::ToString,
5};
6
7use email_address::EmailAddress;
8use lazy_regex::{Lazy, lazy_regex};
9use regex::Regex;
10use serde::{Deserialize, Serialize};
11
12use crate::Error;
13
14/// An OpenPGP key identifier.
15///
16/// The `OpenPGPIdentifier` enum represents a valid OpenPGP identifier, which can be either an
17/// OpenPGP Key ID or an OpenPGP v4 fingerprint.
18///
19/// This type wraps an [`OpenPGPKeyId`] and an [`OpenPGPv4Fingerprint`] and provides a unified
20/// interface for both.
21///
22/// ## Examples
23///
24/// ```
25/// use std::str::FromStr;
26///
27/// use alpm_types::{Error, OpenPGPIdentifier, OpenPGPKeyId, OpenPGPv4Fingerprint};
28/// # fn main() -> Result<(), alpm_types::Error> {
29/// // Create a OpenPGPIdentifier from a valid OpenPGP v4 fingerprint
30/// let key = OpenPGPIdentifier::from_str("4A0C4DFFC02E1A7ED969ED231C2358A25A10D94E")?;
31/// assert_eq!(
32///     key,
33///     OpenPGPIdentifier::OpenPGPv4Fingerprint(OpenPGPv4Fingerprint::from_str(
34///         "4A0C4DFFC02E1A7ED969ED231C2358A25A10D94E"
35///     )?)
36/// );
37/// assert_eq!(key.to_string(), "4A0C4DFFC02E1A7ED969ED231C2358A25A10D94E");
38/// assert_eq!(
39///     key,
40///     OpenPGPv4Fingerprint::from_str("4A0C4DFFC02E1A7ED969ED231C2358A25A10D94E")?.into()
41/// );
42///
43/// // Create a OpenPGPIdentifier from a valid OpenPGP Key ID
44/// let key = OpenPGPIdentifier::from_str("2F2670AC164DB36F")?;
45/// assert_eq!(
46///     key,
47///     OpenPGPIdentifier::OpenPGPKeyId(OpenPGPKeyId::from_str("2F2670AC164DB36F")?)
48/// );
49/// assert_eq!(key.to_string(), "2F2670AC164DB36F");
50/// assert_eq!(key, OpenPGPKeyId::from_str("2F2670AC164DB36F")?.into());
51/// # Ok(())
52/// # }
53/// ```
54#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
55pub enum OpenPGPIdentifier {
56    /// An OpenPGP Key ID.
57    #[serde(rename = "openpgp_key_id")]
58    OpenPGPKeyId(OpenPGPKeyId),
59    /// An OpenPGP v4 fingerprint.
60    #[serde(rename = "openpgp_v4_fingerprint")]
61    OpenPGPv4Fingerprint(OpenPGPv4Fingerprint),
62}
63
64impl FromStr for OpenPGPIdentifier {
65    type Err = Error;
66
67    fn from_str(s: &str) -> Result<Self, Self::Err> {
68        match s.parse::<OpenPGPv4Fingerprint>() {
69            Ok(fingerprint) => Ok(OpenPGPIdentifier::OpenPGPv4Fingerprint(fingerprint)),
70            Err(_) => match s.parse::<OpenPGPKeyId>() {
71                Ok(key_id) => Ok(OpenPGPIdentifier::OpenPGPKeyId(key_id)),
72                Err(e) => Err(e),
73            },
74        }
75    }
76}
77
78impl From<OpenPGPKeyId> for OpenPGPIdentifier {
79    fn from(key_id: OpenPGPKeyId) -> Self {
80        OpenPGPIdentifier::OpenPGPKeyId(key_id)
81    }
82}
83
84impl From<OpenPGPv4Fingerprint> for OpenPGPIdentifier {
85    fn from(fingerprint: OpenPGPv4Fingerprint) -> Self {
86        OpenPGPIdentifier::OpenPGPv4Fingerprint(fingerprint)
87    }
88}
89
90impl Display for OpenPGPIdentifier {
91    fn fmt(&self, f: &mut Formatter) -> std::fmt::Result {
92        match self {
93            OpenPGPIdentifier::OpenPGPKeyId(key_id) => write!(f, "{key_id}"),
94            OpenPGPIdentifier::OpenPGPv4Fingerprint(fingerprint) => write!(f, "{fingerprint}"),
95        }
96    }
97}
98
99/// An OpenPGP Key ID.
100///
101/// The `OpenPGPKeyId` type wraps a `String` representing an [OpenPGP Key ID],
102/// ensuring that it consists of exactly 16 uppercase hexadecimal characters.
103///
104/// [OpenPGP Key ID]: https://openpgp.dev/book/glossary.html#term-Key-ID
105///
106/// ## Note
107///
108/// - This type supports constructing from both uppercase and lowercase hexadecimal characters but
109///   guarantees to return the key ID in uppercase.
110///
111/// - The usage of this type is highly discouraged as the keys may not be unique. This will lead to
112///   a linting error in the future.
113///
114/// ## Examples
115///
116/// ```
117/// use std::str::FromStr;
118///
119/// use alpm_types::{Error, OpenPGPKeyId};
120///
121/// # fn main() -> Result<(), alpm_types::Error> {
122/// // Create OpenPGPKeyId from a valid key ID
123/// let key = OpenPGPKeyId::from_str("2F2670AC164DB36F")?;
124/// assert_eq!(key.as_str(), "2F2670AC164DB36F");
125///
126/// // Attempting to create an OpenPGPKeyId from an invalid key ID will fail
127/// assert!(OpenPGPKeyId::from_str("INVALIDKEYID").is_err());
128///
129/// // Format as String
130/// assert_eq!(format!("{key}"), "2F2670AC164DB36F");
131/// # Ok(())
132/// # }
133/// ```
134#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
135pub struct OpenPGPKeyId(String);
136
137impl OpenPGPKeyId {
138    /// Creates a new `OpenPGPKeyId` instance.
139    ///
140    /// See [`OpenPGPKeyId::from_str`] for more information on how the OpenPGP Key ID is validated.
141    pub fn new(key_id: String) -> Result<Self, Error> {
142        if key_id.len() == 16 && key_id.chars().all(|c| c.is_ascii_hexdigit()) {
143            Ok(Self(key_id.to_ascii_uppercase()))
144        } else {
145            Err(Error::InvalidOpenPGPKeyId(key_id))
146        }
147    }
148
149    /// Returns a reference to the inner OpenPGP Key ID as a `&str`.
150    pub fn as_str(&self) -> &str {
151        &self.0
152    }
153
154    /// Consumes the `OpenPGPKeyId` and returns the inner `String`.
155    pub fn into_inner(self) -> String {
156        self.0
157    }
158}
159
160impl FromStr for OpenPGPKeyId {
161    type Err = Error;
162
163    /// Creates a new `OpenPGPKeyId` instance after validating that it follows the correct format.
164    ///
165    /// A valid OpenPGP Key ID should be exactly 16 characters long and consist only
166    /// of digits (`0-9`) and hexadecimal letters (`A-F`).
167    ///
168    /// # Errors
169    ///
170    /// Returns an error if the OpenPGP Key ID is not valid.
171    fn from_str(s: &str) -> Result<Self, Self::Err> {
172        Self::new(s.to_string())
173    }
174}
175
176impl Display for OpenPGPKeyId {
177    /// Converts the `OpenPGPKeyId` to an uppercase `String`.
178    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
179        write!(f, "{}", self.0)
180    }
181}
182
183/// An OpenPGP v4 fingerprint.
184///
185/// The `OpenPGPv4Fingerprint` type wraps a `String` representing an [OpenPGP v4 fingerprint],
186/// ensuring that it consists of exactly 40 uppercase hexadecimal characters.
187///
188/// [OpenPGP v4 fingerprint]: https://openpgp.dev/book/certificates.html#fingerprint
189///
190/// ## Note
191///
192/// This type supports constructing from both uppercase and lowercase hexadecimal characters but
193/// guarantees to return the fingerprint in uppercase.
194///
195/// ## Examples
196///
197/// ```
198/// use std::str::FromStr;
199///
200/// use alpm_types::{Error, OpenPGPv4Fingerprint};
201///
202/// # fn main() -> Result<(), alpm_types::Error> {
203/// // Create OpenPGPv4Fingerprint from a valid OpenPGP v4 fingerprint
204/// let key = OpenPGPv4Fingerprint::from_str("4A0C4DFFC02E1A7ED969ED231C2358A25A10D94E")?;
205/// assert_eq!(key.as_str(), "4A0C4DFFC02E1A7ED969ED231C2358A25A10D94E");
206///
207/// // Attempting to create a OpenPGPv4Fingerprint from an invalid fingerprint will fail
208/// assert!(OpenPGPv4Fingerprint::from_str("INVALIDKEY").is_err());
209///
210/// // Format as String
211/// assert_eq!(
212///     format!("{}", key),
213///     "4A0C4DFFC02E1A7ED969ED231C2358A25A10D94E"
214/// );
215/// # Ok(())
216/// # }
217/// ```
218#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
219pub struct OpenPGPv4Fingerprint(String);
220
221impl OpenPGPv4Fingerprint {
222    /// Creates a new `OpenPGPv4Fingerprint` instance
223    ///
224    /// See [`OpenPGPv4Fingerprint::from_str`] for more information on how the OpenPGP v4
225    /// fingerprint is validated.
226    pub fn new(fingerprint: String) -> Result<Self, Error> {
227        Self::from_str(&fingerprint)
228    }
229
230    /// Returns a reference to the inner OpenPGP v4 fingerprint as a `&str`.
231    pub fn as_str(&self) -> &str {
232        &self.0
233    }
234
235    /// Consumes the `OpenPGPv4Fingerprint` and returns the inner `String`.
236    pub fn into_inner(self) -> String {
237        self.0
238    }
239}
240
241impl FromStr for OpenPGPv4Fingerprint {
242    type Err = Error;
243
244    /// Creates a new `OpenPGPv4Fingerprint` instance after validating that it follows the correct
245    /// format.
246    ///
247    /// A valid OpenPGP v4 fingerprint should be exactly 40 characters long and consist only
248    /// of digits (`0-9`) and hexadecimal letters (`A-F`).
249    ///
250    /// # Errors
251    ///
252    /// Returns an error if the OpenPGP v4 fingerprint is not valid.
253    fn from_str(s: &str) -> Result<Self, Self::Err> {
254        if s.len() == 40 && s.chars().all(|c| c.is_ascii_hexdigit()) {
255            Ok(Self(s.to_ascii_uppercase()))
256        } else {
257            Err(Error::InvalidOpenPGPv4Fingerprint)
258        }
259    }
260}
261
262impl Display for OpenPGPv4Fingerprint {
263    /// Converts the `OpenPGPv4Fingerprint` to a uppercase `String`.
264    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
265        write!(f, "{}", self.as_str().to_ascii_uppercase())
266    }
267}
268
269pub(crate) static PACKAGER_REGEX: Lazy<Regex> =
270    lazy_regex!(r"^(?P<name>[\w\s\-().]+) <(?P<email>.*)>$");
271
272/// A packager of a package
273///
274/// A `Packager` is represented by a User ID (e.g. `"Foobar McFooFace <foobar@mcfooface.org>"`).
275/// Internally this struct wraps a `String` for the name and an `EmailAddress` for a valid email
276/// address.
277///
278/// ## Examples
279/// ```
280/// use std::str::FromStr;
281///
282/// use alpm_types::{Error, Packager};
283///
284/// # fn main() -> Result<(), alpm_types::Error> {
285/// // create Packager from &str
286/// let packager = Packager::from_str("Foobar McFooface <foobar@mcfooface.org>")?;
287///
288/// // get name
289/// assert_eq!("Foobar McFooface", packager.name());
290///
291/// // get email
292/// assert_eq!("foobar@mcfooface.org", packager.email().to_string());
293///
294/// // get email domain
295/// assert_eq!("mcfooface.org", packager.email().domain());
296///
297/// // format as String
298/// assert_eq!(
299///     "Foobar McFooface <foobar@mcfooface.org>",
300///     format!("{}", packager)
301/// );
302/// # Ok(())
303/// # }
304/// ```
305#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
306pub struct Packager {
307    name: String,
308    email: EmailAddress,
309}
310
311impl Packager {
312    /// Create a new Packager
313    pub fn new(name: String, email: EmailAddress) -> Packager {
314        Packager { name, email }
315    }
316
317    /// Return the name of the Packager
318    pub fn name(&self) -> &str {
319        &self.name
320    }
321
322    /// Return the email of the Packager
323    pub fn email(&self) -> &EmailAddress {
324        &self.email
325    }
326}
327
328impl FromStr for Packager {
329    type Err = Error;
330    /// Create a Packager from a string
331    fn from_str(s: &str) -> Result<Packager, Self::Err> {
332        if let Some(captures) = PACKAGER_REGEX.captures(s) {
333            if captures.name("name").is_some() && captures.name("email").is_some() {
334                let email = EmailAddress::from_str(captures.name("email").unwrap().as_str())?;
335                Ok(Packager {
336                    name: captures.name("name").unwrap().as_str().to_string(),
337                    email,
338                })
339            } else {
340                Err(Error::MissingComponent {
341                    component: if captures.name("name").is_none() {
342                        "name"
343                    } else {
344                        "email"
345                    },
346                })
347            }
348        } else {
349            Err(Error::RegexDoesNotMatch {
350                value: s.to_string(),
351                regex_type: "packager".to_string(),
352                regex: PACKAGER_REGEX.to_string(),
353            })
354        }
355    }
356}
357
358impl Display for Packager {
359    fn fmt(&self, fmt: &mut Formatter) -> std::fmt::Result {
360        write!(fmt, "{} <{}>", self.name, self.email)
361    }
362}
363
364#[cfg(test)]
365mod tests {
366    use rstest::rstest;
367    use testresult::TestResult;
368
369    use super::*;
370
371    #[rstest]
372    #[case("4A0C4DFFC02E1A7ED969ED231C2358A25A10D94E")]
373    #[case("1234567890abcdef1234567890abcdef12345678")]
374    fn test_parse_openpgp_fingerprint(#[case] input: &str) -> Result<(), Error> {
375        input.parse::<OpenPGPv4Fingerprint>()?;
376        Ok(())
377    }
378
379    #[rstest]
380    // Contains non-hex characters 'G' and 'H'
381    #[case(
382        "A1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6E7F8G9H0",
383        Err(Error::InvalidOpenPGPv4Fingerprint)
384    )]
385    // Less than 40 characters
386    #[case(
387        "1234567890ABCDEF1234567890ABCDEF1234567",
388        Err(Error::InvalidOpenPGPv4Fingerprint)
389    )]
390    // More than 40 characters
391    #[case(
392        "1234567890ABCDEF1234567890ABCDEF1234567890",
393        Err(Error::InvalidOpenPGPv4Fingerprint)
394    )]
395    // Just invalid
396    #[case("invalid", Err(Error::InvalidOpenPGPv4Fingerprint))]
397    fn test_parse_invalid_openpgp_fingerprint(
398        #[case] input: &str,
399        #[case] expected: Result<OpenPGPv4Fingerprint, Error>,
400    ) {
401        let result = input.parse::<OpenPGPv4Fingerprint>();
402        assert_eq!(result, expected);
403    }
404
405    #[rstest]
406    #[case("2F2670AC164DB36F")]
407    #[case("584A3EBFE705CDCD")]
408    fn test_parse_openpgp_key_id(#[case] input: &str) -> Result<(), Error> {
409        input.parse::<OpenPGPKeyId>()?;
410        Ok(())
411    }
412
413    #[test]
414    fn test_serialize_openpgp_key_id() -> TestResult {
415        let id = "584A3EBFE705CDCD".parse::<OpenPGPKeyId>()?;
416        let json = serde_json::to_string(&OpenPGPIdentifier::OpenPGPKeyId(id))?;
417        assert_eq!(r#"{"openpgp_key_id":"584A3EBFE705CDCD"}"#, json);
418
419        Ok(())
420    }
421
422    #[test]
423    fn test_serialize_openpgp_v4_fingerprint() -> TestResult {
424        let print = "1234567890abcdef1234567890abcdef12345678".parse::<OpenPGPv4Fingerprint>()?;
425        let json = serde_json::to_string(&OpenPGPIdentifier::OpenPGPv4Fingerprint(print))?;
426        assert_eq!(
427            r#"{"openpgp_v4_fingerprint":"1234567890ABCDEF1234567890ABCDEF12345678"}"#,
428            json
429        );
430
431        Ok(())
432    }
433
434    #[rstest]
435    // Contains non-hex characters 'G' and 'H'
436    #[case("1234567890ABCGH", Err(Error::InvalidOpenPGPKeyId("1234567890ABCGH".to_string())))]
437    // Less than 16 characters
438    #[case("1234567890ABCDE", Err(Error::InvalidOpenPGPKeyId("1234567890ABCDE".to_string())))]
439    // More than 16 characters
440    #[case("1234567890ABCDEF0", Err(Error::InvalidOpenPGPKeyId("1234567890ABCDEF0".to_string())))]
441    // Just invalid
442    #[case("invalid", Err(Error::InvalidOpenPGPKeyId("invalid".to_string())))]
443    fn test_parse_invalid_openpgp_key_id(
444        #[case] input: &str,
445        #[case] expected: Result<OpenPGPKeyId, Error>,
446    ) {
447        let result = input.parse::<OpenPGPKeyId>();
448        assert_eq!(result, expected);
449    }
450
451    #[rstest]
452    #[case(
453        "Foobar McFooface (The Third) <foobar@mcfooface.org>",
454        Packager{
455            name: "Foobar McFooface (The Third)".to_string(),
456            email: EmailAddress::from_str("foobar@mcfooface.org").unwrap()
457        }
458    )]
459    #[case(
460        "Foobar McFooface <foobar@mcfooface.org>",
461        Packager{
462            name: "Foobar McFooface".to_string(),
463            email: EmailAddress::from_str("foobar@mcfooface.org").unwrap()
464        }
465    )]
466    fn valid_packager(#[case] from_str: &str, #[case] packager: Packager) {
467        assert_eq!(Packager::from_str(from_str), Ok(packager));
468    }
469
470    /// Test that invalid packager email expressions throw the expected email errors.
471    #[rstest]
472    #[case(
473        "Foobar McFooface <@mcfooface.org>",
474        email_address::Error::LocalPartEmpty
475    )]
476    #[case(
477        "Foobar McFooface <foobar@mcfooface.org> <foobar@mcfoofacemcfooface.org>",
478        email_address::Error::MissingEndBracket
479    )]
480    fn invalid_packager_email(#[case] packager: &str, #[case] error: email_address::Error) {
481        assert_eq!(Packager::from_str(packager), Err(error.into()));
482    }
483
484    /// Test that invalid packager expressionare detected as such throw the expected Regex error.
485    #[rstest]
486    #[case("<foobar@mcfooface.org>")]
487    #[case("[foo] <foobar@mcfooface.org>")]
488    #[case("foobar@mcfooface.org")]
489    #[case("Foobar McFooface")]
490    fn invalid_packager_regex(#[case] packager: &str) {
491        assert_eq!(
492            Packager::from_str(packager),
493            Err(Error::RegexDoesNotMatch {
494                value: packager.to_string(),
495                regex_type: "packager".to_string(),
496                regex: PACKAGER_REGEX.to_string(),
497            })
498        );
499    }
500
501    #[rstest]
502    #[case(
503        Packager::from_str("Foobar McFooface <foobar@mcfooface.org>").unwrap(),
504        "Foobar McFooface <foobar@mcfooface.org>"
505    )]
506    fn packager_format_string(#[case] packager: Packager, #[case] packager_str: &str) {
507        assert_eq!(packager_str, format!("{}", packager));
508    }
509
510    #[rstest]
511    #[case(Packager::from_str("Foobar McFooface <foobar@mcfooface.org>").unwrap(), "Foobar McFooface")]
512    fn packager_name(#[case] packager: Packager, #[case] name: &str) {
513        assert_eq!(name, packager.name());
514    }
515
516    #[rstest]
517    #[case(
518        Packager::from_str("Foobar McFooface <foobar@mcfooface.org>").unwrap(),
519        &EmailAddress::from_str("foobar@mcfooface.org").unwrap(),
520    )]
521    fn packager_email(#[case] packager: Packager, #[case] email: &EmailAddress) {
522        assert_eq!(email, packager.email());
523    }
524}
alpm_types/openpgp.rs

alpm_types/
openpgp.rs
