mas_jose/
base64.rs

1// Copyright 2025 New Vector Ltd.
2//
3// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
4// Please see LICENSE files in the repository root for full details.
5
6//! Transparent base64 encoding / decoding as part of (de)serialization.
7
8use std::{borrow::Cow, fmt, marker::PhantomData, str};
9
10use base64ct::Encoding;
11use serde::{
12    Deserialize, Deserializer, Serialize, Serializer,
13    de::{self, Unexpected, Visitor},
14};
15
16/// A wrapper around `Vec<u8>` that (de)serializes from / to a base64 string.
17///
18/// The generic parameter `C` represents the base64 flavor.
19#[derive(Clone, PartialEq, Eq, PartialOrd, Ord)]
20pub struct Base64<C = base64ct::Base64> {
21    bytes: Vec<u8>,
22    // Invariant PhantomData, Send + Sync
23    _phantom_conf: PhantomData<fn(C) -> C>,
24}
25
26pub type Base64UrlNoPad = Base64<base64ct::Base64UrlUnpadded>;
27
28impl<C: Encoding> Base64<C> {
29    /// Create a `Base64` instance from raw bytes, to be base64-encoded in
30    /// serialization.
31    #[must_use]
32    pub fn new(bytes: Vec<u8>) -> Self {
33        Self {
34            bytes,
35            _phantom_conf: PhantomData,
36        }
37    }
38
39    /// Get a reference to the raw bytes held by this `Base64` instance.
40    #[must_use]
41    pub fn as_bytes(&self) -> &[u8] {
42        self.bytes.as_ref()
43    }
44
45    /// Encode the bytes contained in this `Base64` instance to unpadded base64.
46    #[must_use]
47    pub fn encode(&self) -> String {
48        C::encode_string(self.as_bytes())
49    }
50
51    /// Get the raw bytes held by this `Base64` instance.
52    #[must_use]
53    pub fn into_inner(self) -> Vec<u8> {
54        self.bytes
55    }
56
57    /// Create a `Base64` instance containing an empty `Vec<u8>`.
58    #[must_use]
59    pub fn empty() -> Self {
60        Self::new(Vec::new())
61    }
62
63    /// Parse some base64-encoded data to create a `Base64` instance.
64    ///
65    /// # Errors
66    ///
67    /// Returns an error if the input is not valid base64.
68    pub fn parse(encoded: &str) -> Result<Self, base64ct::Error> {
69        C::decode_vec(encoded).map(Self::new)
70    }
71}
72
73impl<C: Encoding> fmt::Debug for Base64<C> {
74    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
75        self.encode().fmt(f)
76    }
77}
78
79impl<C: Encoding> fmt::Display for Base64<C> {
80    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
81        self.encode().fmt(f)
82    }
83}
84
85impl<'de, C: Encoding> Deserialize<'de> for Base64<C> {
86    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
87    where
88        D: Deserializer<'de>,
89    {
90        let encoded = deserialize_cow_str(deserializer)?;
91        Self::parse(&encoded).map_err(de::Error::custom)
92    }
93}
94
95impl<C: Encoding> Serialize for Base64<C> {
96    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
97    where
98        S: Serializer,
99    {
100        serializer.serialize_str(&self.encode())
101    }
102}
103
104/// Deserialize a `Cow<'de, str>`.
105///
106/// Different from serde's implementation of `Deserialize` for `Cow` since it
107/// borrows from the input when possible.
108pub fn deserialize_cow_str<'de, D>(deserializer: D) -> Result<Cow<'de, str>, D::Error>
109where
110    D: Deserializer<'de>,
111{
112    deserializer.deserialize_string(CowStrVisitor)
113}
114
115struct CowStrVisitor;
116
117impl<'de> Visitor<'de> for CowStrVisitor {
118    type Value = Cow<'de, str>;
119
120    fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
121        formatter.write_str("a string")
122    }
123
124    fn visit_borrowed_str<E>(self, v: &'de str) -> Result<Self::Value, E>
125    where
126        E: de::Error,
127    {
128        Ok(Cow::Borrowed(v))
129    }
130
131    fn visit_borrowed_bytes<E>(self, v: &'de [u8]) -> Result<Self::Value, E>
132    where
133        E: de::Error,
134    {
135        match str::from_utf8(v) {
136            Ok(s) => Ok(Cow::Borrowed(s)),
137            Err(_) => Err(de::Error::invalid_value(Unexpected::Bytes(v), &self)),
138        }
139    }
140
141    fn visit_str<E>(self, v: &str) -> Result<Self::Value, E>
142    where
143        E: de::Error,
144    {
145        Ok(Cow::Owned(v.to_owned()))
146    }
147
148    fn visit_string<E>(self, v: String) -> Result<Self::Value, E>
149    where
150        E: de::Error,
151    {
152        Ok(Cow::Owned(v))
153    }
154
155    fn visit_bytes<E>(self, v: &[u8]) -> Result<Self::Value, E>
156    where
157        E: de::Error,
158    {
159        match str::from_utf8(v) {
160            Ok(s) => Ok(Cow::Owned(s.to_owned())),
161            Err(_) => Err(de::Error::invalid_value(Unexpected::Bytes(v), &self)),
162        }
163    }
164
165    fn visit_byte_buf<E>(self, v: Vec<u8>) -> Result<Self::Value, E>
166    where
167        E: de::Error,
168    {
169        match String::from_utf8(v) {
170            Ok(s) => Ok(Cow::Owned(s)),
171            Err(e) => Err(de::Error::invalid_value(
172                Unexpected::Bytes(&e.into_bytes()),
173                &self,
174            )),
175        }
176    }
177}
mas_jose/base64.rs

mas_jose/
base64.rs
