identity_kit/jose/
compact.rs

1//! Compact JWS serialization (RFC 7515 §7.1): decoding without verification, and encoding with
2//! a [`Signer`].
3
4use core::fmt;
5
6use indexmap::IndexMap;
7use serde::de::DeserializeOwned;
8use serde::{Deserialize, Serialize};
9use serde_json::Value;
10
11use super::{Jwk, JwsAlgorithm, JwsError, JwsVerifier, SignError, VerificationError, base64url};
12
13/// The JOSE header of a JWS (RFC 7515 §4).
14///
15/// The registered parameters this crate acts on are fields; everything else, `x5c` and `b64`
16/// included, lives in `additional` in insertion order. `jwk` is the public key the signer claims
17/// to have used; trusting it is the verifier's decision, never the crate's.
18///
19/// # Examples
20///
21/// ```
22/// use identity_kit::jose::{JwsAlgorithm, JwsHeader};
23///
24/// let mut header = JwsHeader::new(JwsAlgorithm::ES256).with_kid("did:example:123#key-1");
25/// header.typ = Some("JWT".to_owned());
26/// assert_eq!(
27///     serde_json::to_string(&header)?,
28///     r#"{"alg":"ES256","typ":"JWT","kid":"did:example:123#key-1"}"#
29/// );
30/// # Ok::<(), serde_json::Error>(())
31/// ```
32#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
33#[non_exhaustive]
34pub struct JwsHeader {
35    /// The signature algorithm (`alg`).
36    pub alg: JwsAlgorithm,
37    /// The media type of the whole JWS (`typ`), such as `JWT` or `vc+jwt`.
38    #[serde(default, skip_serializing_if = "Option::is_none")]
39    pub typ: Option<String>,
40    /// The media type of the payload (`cty`).
41    #[serde(default, skip_serializing_if = "Option::is_none")]
42    pub cty: Option<String>,
43    /// The key id (`kid`); for a DID controller, usually a DID URL with a fragment.
44    #[serde(default, skip_serializing_if = "Option::is_none")]
45    pub kid: Option<String>,
46    /// The public key the signature was made with (`jwk`).
47    #[serde(default, skip_serializing_if = "Option::is_none")]
48    pub jwk: Option<Jwk>,
49    /// Extensions a recipient must understand (`crit`).
50    #[serde(default, skip_serializing_if = "Option::is_none")]
51    pub crit: Option<Vec<String>>,
52    /// Every other header parameter, in insertion order.
53    #[serde(flatten)]
54    pub additional: IndexMap<String, Value>,
55}
56
57impl JwsHeader {
58    /// A header with only `alg` set.
59    pub fn new(alg: JwsAlgorithm) -> Self {
60        Self {
61            alg,
62            typ: None,
63            cty: None,
64            kid: None,
65            jwk: None,
66            crit: None,
67            additional: IndexMap::new(),
68        }
69    }
70
71    /// This header with its `kid` set.
72    #[must_use]
73    pub fn with_kid(mut self, kid: impl Into<String>) -> Self {
74        self.kid = Some(kid.into());
75        self
76    }
77
78    /// This header with its `typ` set.
79    #[must_use]
80    pub fn with_typ(mut self, typ: impl Into<String>) -> Self {
81        self.typ = Some(typ.into());
82        self
83    }
84}
85
86/// A decoded compact JWS: `BASE64URL(header) || '.' || BASE64URL(payload) || '.' ||
87/// BASE64URL(signature)`.
88///
89/// Decoding parses the header and the parts and nothing more: [`CompactJws::verify`] (or any
90/// [`JwsVerifier`]) checks the signature once the caller has resolved the key, which usually
91/// means dereferencing [`kid`](Self::kid) through a DID resolver.
92///
93/// # Examples
94///
95/// ```
96/// use identity_kit::jose::{CompactJws, JwsAlgorithm};
97///
98/// // RFC 8037 Appendix A.4.
99/// let token = "eyJhbGciOiJFZERTQSJ9.RXhhbXBsZSBvZiBFZDI1NTE5IHNpZ25pbmc.\
100///              hgyY0il_MGCjP0JzlnLWG1PPOt7-09PGcvMg3AIbQR6dWbhijcNR4ki4iylGjg5BhVsPt9g7sVvpAr_MuM0KAg";
101/// let jws = CompactJws::decode(token)?;
102/// assert_eq!(jws.alg(), JwsAlgorithm::EdDSA);
103/// assert_eq!(jws.kid(), None);
104/// assert_eq!(jws.payload(), b"Example of Ed25519 signing");
105/// assert_eq!(
106///     jws.signing_input(),
107///     b"eyJhbGciOiJFZERTQSJ9.RXhhbXBsZSBvZiBFZDI1NTE5IHNpZ25pbmc"
108/// );
109/// assert_eq!(jws.signature().len(), 64);
110/// # Ok::<(), identity_kit::jose::JwsError>(())
111/// ```
112#[derive(Debug, Clone)]
113pub struct CompactJws {
114    token: String,
115    /// Byte offset of the `.` between payload and signature; the signing input ends there.
116    signing_input_end: usize,
117    header: JwsHeader,
118    payload: Vec<u8>,
119    signature: Vec<u8>,
120}
121
122impl CompactJws {
123    /// Parses a compact JWS without verifying it.
124    ///
125    /// # Errors
126    ///
127    /// A [`JwsError`] when the input is not three base64url parts, the header is not a JSON
128    /// object with a supported `alg`, or the header has `crit` or `b64: false`.
129    pub fn decode(token: &str) -> Result<Self, JwsError> {
130        let mut parts = token.split('.');
131        let (Some(header_b64), Some(payload_b64), Some(signature_b64), None) =
132            (parts.next(), parts.next(), parts.next(), parts.next())
133        else {
134            return Err(JwsError::InvalidFormat {
135                parts: token.split('.').count(),
136            });
137        };
138        let header_json = base64url::decode(header_b64)
139            .map_err(|_| JwsError::InvalidBase64Url { part: "header" })?;
140        let header = parse_header(&header_json)?;
141        let payload = base64url::decode(payload_b64)
142            .map_err(|_| JwsError::InvalidBase64Url { part: "payload" })?;
143        let signature = base64url::decode(signature_b64)
144            .map_err(|_| JwsError::InvalidBase64Url { part: "signature" })?;
145        Ok(Self {
146            token: token.to_owned(),
147            signing_input_end: header_b64.len() + 1 + payload_b64.len(),
148            header,
149            payload,
150            signature,
151        })
152    }
153
154    /// The protected header.
155    pub fn header(&self) -> &JwsHeader {
156        &self.header
157    }
158
159    /// The header `alg`.
160    pub fn alg(&self) -> JwsAlgorithm {
161        self.header.alg
162    }
163
164    /// The header `kid`, if any.
165    pub fn kid(&self) -> Option<&str> {
166        self.header.kid.as_deref()
167    }
168
169    /// The JWS signing input: `BASE64URL(header) || '.' || BASE64URL(payload)` as ASCII.
170    pub fn signing_input(&self) -> &[u8] {
171        &self.token.as_bytes()[..self.signing_input_end]
172    }
173
174    /// The decoded payload.
175    pub fn payload(&self) -> &[u8] {
176        &self.payload
177    }
178
179    /// The decoded signature.
180    pub fn signature(&self) -> &[u8] {
181        &self.signature
182    }
183
184    /// The payload read as JSON into `T`, a [`JwtClaims`](super::JwtClaims) set say, unverified:
185    /// nothing about the signature or the claims is checked.
186    ///
187    /// # Errors
188    ///
189    /// [`JwsError::InvalidPayload`] when the payload is not JSON of the shape `T` expects.
190    ///
191    /// # Examples
192    ///
193    /// ```
194    /// use identity_kit::jose::{CompactJws, JwtClaims};
195    ///
196    /// // RFC 7515 Appendix A.3: the RFC 7519 §3.1 claims set, signed with ES256.
197    /// let jws = CompactJws::decode(
198    ///     "eyJhbGciOiJFUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGF\
199    ///      tcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDx\
200    ///      w5djxLa8ISlSApmWQxfKTUJqPP3-Kg6NU1Q",
201    /// )?;
202    /// let claims: JwtClaims = jws.claims()?;
203    /// assert_eq!(claims.iss.as_deref(), Some("joe"));
204    /// assert_eq!(claims.exp, Some(1300819380));
205    /// assert_eq!(claims.additional["http://example.com/is_root"], true);
206    /// # Ok::<(), identity_kit::jose::JwsError>(())
207    /// ```
208    pub fn claims<T: DeserializeOwned>(&self) -> Result<T, JwsError> {
209        serde_json::from_slice(&self.payload).map_err(|e| JwsError::InvalidPayload(e.to_string()))
210    }
211
212    /// The compact serialization as it was decoded.
213    pub fn as_str(&self) -> &str {
214        &self.token
215    }
216
217    /// Verifies the signature with `verifier` under `key` and the header `alg`.
218    ///
219    /// # Errors
220    ///
221    /// Whatever the verifier reports; see [`JwsVerifier::verify`].
222    pub fn verify<V: JwsVerifier + ?Sized>(
223        &self,
224        verifier: &V,
225        key: &Jwk,
226    ) -> Result<(), VerificationError> {
227        verifier.verify(self.alg(), self.signing_input(), &self.signature, key)
228    }
229}
230
231impl fmt::Display for CompactJws {
232    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
233        f.write_str(&self.token)
234    }
235}
236
237impl AsRef<str> for CompactJws {
238    fn as_ref(&self) -> &str {
239        &self.token
240    }
241}
242
243/// Parses the header JSON, naming an unsupported `alg` and rejecting `crit` and `b64: false`.
244fn parse_header(json: &[u8]) -> Result<JwsHeader, JwsError> {
245    let value: Value =
246        serde_json::from_slice(json).map_err(|e| JwsError::InvalidHeader(e.to_string()))?;
247    let Some(object) = value.as_object() else {
248        return Err(JwsError::InvalidHeader("not a JSON object".to_owned()));
249    };
250    match object.get("alg") {
251        Some(Value::String(alg)) if alg.parse::<JwsAlgorithm>().is_ok() => {}
252        Some(Value::String(alg)) => return Err(JwsError::UnsupportedAlgorithm(alg.clone())),
253        Some(other) => return Err(JwsError::UnsupportedAlgorithm(other.to_string())),
254        None => return Err(JwsError::InvalidHeader("missing `alg`".to_owned())),
255    }
256    if object
257        .get("b64")
258        .is_some_and(|b64| b64 != &Value::Bool(true))
259    {
260        return Err(JwsError::UnencodedPayload);
261    }
262    let header: JwsHeader =
263        serde_json::from_value(value).map_err(|e| JwsError::InvalidHeader(e.to_string()))?;
264    if let Some(crit) = &header.crit {
265        return Err(JwsError::UnsupportedCritical(crit.clone()));
266    }
267    Ok(header)
268}
269
270/// Produces JWS signatures.
271///
272/// A signer binds one key and one algorithm. Private keys live behind it, in a key store, an HSM
273/// or a cloud service, which is why signing is `async`. The signature is returned in the JWS form
274/// of the algorithm: raw `r || s` for ECDSA, never DER.
275#[async_trait::async_trait]
276pub trait Signer: Send + Sync {
277    /// The algorithm every signature of this signer uses.
278    fn alg(&self) -> JwsAlgorithm;
279
280    /// The key id to put in a header, if the signer has one.
281    fn kid(&self) -> Option<&str>;
282
283    /// Signs `signing_input`.
284    ///
285    /// # Errors
286    ///
287    /// A [`SignError`] wrapping whatever the backend reports.
288    async fn sign(&self, signing_input: &[u8]) -> Result<Vec<u8>, SignError>;
289}
290
291/// Encodes `payload` under `header` as a compact JWS signed by `signer`.
292///
293/// The header is serialized as given: `alg` must equal the signer's algorithm, and `kid` is
294/// whatever the caller set (a DID URL, usually), not necessarily [`Signer::kid`].
295///
296/// # Errors
297///
298/// [`JwsError::AlgorithmMismatch`] when `header.alg` differs from the signer's algorithm, and
299/// [`JwsError::Signer`] when signing fails.
300///
301/// # Examples
302///
303/// ```
304/// use identity_kit::jose::{CompactJws, JwsAlgorithm, JwsHeader, SignError, Signer, encode_compact};
305///
306/// struct Rejecting;
307///
308/// #[async_trait::async_trait]
309/// impl Signer for Rejecting {
310///     fn alg(&self) -> JwsAlgorithm { JwsAlgorithm::ES256 }
311///     fn kid(&self) -> Option<&str> { None }
312///     async fn sign(&self, _: &[u8]) -> Result<Vec<u8>, SignError> {
313///         Err(SignError::msg("key store is offline"))
314///     }
315/// }
316///
317/// # tokio::runtime::Builder::new_current_thread().build()?.block_on(async {
318/// let header = JwsHeader::new(JwsAlgorithm::ES256);
319/// let err = encode_compact(&header, b"{}", &Rejecting).await.unwrap_err();
320/// assert_eq!(err.to_string(), "signing failed: key store is offline");
321/// # Ok::<(), Box<dyn std::error::Error>>(())
322/// # })?;
323/// # Ok::<(), Box<dyn std::error::Error>>(())
324/// ```
325pub async fn encode_compact(
326    header: &JwsHeader,
327    payload: &[u8],
328    signer: &dyn Signer,
329) -> Result<String, JwsError> {
330    if header.alg != signer.alg() {
331        return Err(JwsError::AlgorithmMismatch {
332            header: header.alg,
333            signer: signer.alg(),
334        });
335    }
336    // Serializing a header cannot fail: every field is a string, a list, a `Jwk` or a `Value`.
337    let header_json =
338        serde_json::to_vec(header).map_err(|e| JwsError::InvalidHeader(e.to_string()))?;
339    let mut token = base64url::encode(&header_json);
340    token.push('.');
341    token.push_str(&base64url::encode(payload));
342    let signature = signer
343        .sign(token.as_bytes())
344        .await
345        .map_err(JwsError::Signer)?;
346    token.push('.');
347    token.push_str(&base64url::encode(&signature));
348    Ok(token)
349}
identity_kit/jose/compact.rs

identity_kit/jose/
compact.rs
