Skip to main content

reallyme_openid4vp_types/
transaction_data.rs

1// SPDX-FileCopyrightText: 2026 ReallyMe Technologies Limited
2//
3// SPDX-License-Identifier: MIT OR Apache-2.0
4
5use std::fmt;
6
7use reallyme_codec::base64url::{base64url_to_bytes, bytes_to_base64url};
8use reallyme_codec::jcs::{canonicalize_json_text, canonicalize_trusted_json_value, JcsError};
9use serde::{Deserialize, Deserializer, Serialize, Serializer};
10use serde_json::{Map as JsonMap, Value as JsonValue};
11use sha2::{Digest, Sha256};
12use zeroize::{Zeroize, ZeroizeOnDrop, Zeroizing};
13
14use crate::zeroize_json::zeroize_json_value;
15use crate::{OpenId4vpTypeError, OpenId4vpTypeErrorReason};
16
17/// Maximum JSON nesting canonicalized by this crate's transaction-data helper.
18pub const MAX_TRANSACTION_DATA_JSON_DEPTH: usize = 128;
19
20/// Maximum decoded JSON accepted for one transaction-data value.
21pub const MAX_TRANSACTION_DATA_JSON_BYTES: usize = 256 * 1024;
22
23/// Transaction data object from OpenID4VP 1.0 final.
24#[derive(Clone, PartialEq)]
25pub struct TransactionData {
26    /// Application or profile-defined transaction type.
27    transaction_type: String,
28    /// Credential ids this transaction data applies to.
29    credential_ids: Vec<String>,
30    /// Profile-specific transaction data payload.
31    payload: JsonValue,
32    /// Exact base64url value received or deterministically built locally.
33    encoded_value: String,
34}
35
36impl TransactionData {
37    /// Construct transaction data and retain its deterministic wire encoding.
38    pub fn new(
39        transaction_type: String,
40        credential_ids: Vec<String>,
41        payload: JsonValue,
42    ) -> Result<Self, OpenId4vpTypeError> {
43        let mut value = Self {
44            transaction_type,
45            credential_ids,
46            payload,
47            encoded_value: String::new(),
48        };
49        validate_transaction_data(&value)?;
50        let canonical = canonical_transaction_data_bytes(&value)?;
51        value.encoded_value = bytes_to_base64url(&canonical);
52        Ok(value)
53    }
54
55    /// Application or profile-defined transaction type.
56    #[must_use]
57    pub fn transaction_type(&self) -> &str {
58        &self.transaction_type
59    }
60
61    /// Credential ids this transaction data applies to.
62    #[must_use]
63    pub fn credential_ids(&self) -> &[String] {
64        &self.credential_ids
65    }
66
67    /// Profile-specific transaction data payload.
68    #[must_use]
69    pub const fn payload(&self) -> &JsonValue {
70        &self.payload
71    }
72
73    /// Exact base64url string whose bytes are covered by transaction-data hashes.
74    #[must_use]
75    pub fn encoded_value(&self) -> &str {
76        &self.encoded_value
77    }
78}
79
80impl fmt::Debug for TransactionData {
81    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
82        formatter
83            .debug_struct("TransactionData")
84            .field("transaction_type", &self.transaction_type)
85            .field("credential_id_count", &self.credential_ids.len())
86            .field("payload", &"<redacted>")
87            .finish()
88    }
89}
90
91impl Zeroize for TransactionData {
92    fn zeroize(&mut self) {
93        self.transaction_type.zeroize();
94        self.credential_ids.zeroize();
95        zeroize_json_value(&mut self.payload);
96        self.encoded_value.zeroize();
97    }
98}
99
100impl Drop for TransactionData {
101    fn drop(&mut self) {
102        self.zeroize();
103    }
104}
105
106impl ZeroizeOnDrop for TransactionData {}
107
108impl Serialize for TransactionData {
109    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
110    where
111        S: Serializer,
112    {
113        let encoded = encoded_transaction_data_string(self)
114            .map_err(|_| serde::ser::Error::custom("invalid transaction data"))?;
115        serializer.serialize_str(&encoded)
116    }
117}
118
119impl<'de> Deserialize<'de> for TransactionData {
120    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
121    where
122        D: Deserializer<'de>,
123    {
124        let encoded = Zeroizing::new(String::deserialize(deserializer)?);
125        decode_transaction_data_string(&encoded)
126            .map_err(|_| serde::de::Error::custom("invalid transaction data"))
127    }
128}
129
130/// Transaction data hash algorithm.
131#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
132pub enum TransactionDataHashAlgorithm {
133    /// SHA-256.
134    #[serde(rename = "sha-256")]
135    Sha256,
136}
137
138/// Fixed-size transaction data digest.
139#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
140pub struct TransactionDataHash {
141    /// Hash algorithm.
142    pub algorithm: TransactionDataHashAlgorithm,
143    /// Digest bytes.
144    pub digest: [u8; 32],
145}
146
147impl TransactionDataHash {
148    /// Compute SHA-256 over caller-provided canonical transaction data bytes.
149    pub fn sha256(canonical_transaction_data: &[u8]) -> Result<Self, OpenId4vpTypeError> {
150        if canonical_transaction_data.is_empty() {
151            return Err(OpenId4vpTypeError::new(
152                OpenId4vpTypeErrorReason::EmptyValue,
153            ));
154        }
155        let mut hasher = Sha256::new();
156        hasher.update(canonical_transaction_data);
157        let digest = hasher.finalize().into();
158        Ok(Self {
159            algorithm: TransactionDataHashAlgorithm::Sha256,
160            digest,
161        })
162    }
163
164    /// Compute SHA-256 over the exact received final-spec transaction data string.
165    ///
166    /// OpenID4VP hashes the base64url-encoded `transaction_data` member, not
167    /// the decoded JSON object. This method validates the encoded value before
168    /// hashing so callers can keep wire-level interop without accepting
169    /// malformed transaction data.
170    pub fn sha256_received_transaction_data_string(
171        encoded: &str,
172    ) -> Result<Self, OpenId4vpTypeError> {
173        decode_transaction_data_string(encoded)?;
174        Self::sha256(encoded.as_bytes())
175    }
176
177    /// Compute SHA-256 over the exact encoding retained by `TransactionData`.
178    ///
179    /// Decoded values retain their received base64url string; locally
180    /// constructed values retain the deterministic encoding created by
181    /// [`TransactionData::new`].
182    pub fn sha256_transaction_data(
183        transaction_data: &TransactionData,
184    ) -> Result<Self, OpenId4vpTypeError> {
185        let encoded = encoded_transaction_data_string(transaction_data)?;
186        Self::sha256(encoded.as_bytes())
187    }
188}
189
190/// Encode a transaction data object as the final-spec base64url string.
191pub fn encoded_transaction_data_string(
192    transaction_data: &TransactionData,
193) -> Result<String, OpenId4vpTypeError> {
194    validate_transaction_data(transaction_data)?;
195    if transaction_data.encoded_value.is_empty() {
196        return Err(OpenId4vpTypeError::new(
197            OpenId4vpTypeErrorReason::InvalidEncoding,
198        ));
199    }
200    Ok(transaction_data.encoded_value.clone())
201}
202
203/// Decode one final-spec base64url transaction data string.
204pub fn decode_transaction_data_string(
205    encoded: &str,
206) -> Result<TransactionData, OpenId4vpTypeError> {
207    if encoded.is_empty() {
208        return Err(OpenId4vpTypeError::new(
209            OpenId4vpTypeErrorReason::EmptyValue,
210        ));
211    }
212
213    if encoded.len() > max_transaction_data_encoded_bytes()? {
214        return Err(OpenId4vpTypeError::new(
215            OpenId4vpTypeErrorReason::JsonSizeExceeded,
216        ));
217    }
218
219    let bytes = Zeroizing::new(
220        base64url_to_bytes(encoded)
221            .map_err(|_| OpenId4vpTypeError::new(OpenId4vpTypeErrorReason::InvalidEncoding))?,
222    );
223    if bytes.len() > MAX_TRANSACTION_DATA_JSON_BYTES {
224        return Err(OpenId4vpTypeError::new(
225            OpenId4vpTypeErrorReason::JsonSizeExceeded,
226        ));
227    }
228
229    let json_text = core::str::from_utf8(&bytes)
230        .map_err(|_| OpenId4vpTypeError::new(OpenId4vpTypeErrorReason::InvalidEncoding))?;
231    let canonical =
232        Zeroizing::new(canonicalize_json_text(json_text).map_err(map_untrusted_jcs_error)?);
233    if canonical.len() > MAX_TRANSACTION_DATA_JSON_BYTES {
234        return Err(OpenId4vpTypeError::new(
235            OpenId4vpTypeErrorReason::JsonSizeExceeded,
236        ));
237    }
238
239    let object: JsonMap<String, JsonValue> = serde_json::from_str(&canonical)
240        .map_err(|_| OpenId4vpTypeError::new(OpenId4vpTypeErrorReason::InvalidEncoding))?;
241    transaction_data_from_object(
242        SensitiveTransactionDataObject::new(object),
243        Zeroizing::new(encoded.to_owned()),
244    )
245}
246
247/// Build deterministic JSON bytes for OpenID4VP transaction data hashing.
248pub fn canonical_transaction_data_bytes(
249    transaction_data: &TransactionData,
250) -> Result<Zeroizing<Vec<u8>>, OpenId4vpTypeError> {
251    validate_transaction_data(transaction_data)?;
252    let mut json = transaction_data_object_value(transaction_data)?;
253    let canonical_result = canonicalize_trusted_json_value(&json);
254    zeroize_json_value(&mut json);
255
256    let canonical = Zeroizing::new(canonical_result.map_err(map_trusted_jcs_error)?);
257    if canonical.len() > MAX_TRANSACTION_DATA_JSON_BYTES {
258        return Err(OpenId4vpTypeError::new(
259            OpenId4vpTypeErrorReason::JsonSizeExceeded,
260        ));
261    }
262
263    Ok(Zeroizing::new(canonical.as_bytes().to_vec()))
264}
265
266fn max_transaction_data_encoded_bytes() -> Result<usize, OpenId4vpTypeError> {
267    MAX_TRANSACTION_DATA_JSON_BYTES
268        .checked_add(2)
269        .and_then(|value| value.checked_div(3))
270        .and_then(|value| value.checked_mul(4))
271        .ok_or_else(|| OpenId4vpTypeError::new(OpenId4vpTypeErrorReason::JsonSizeExceeded))
272}
273
274fn map_untrusted_jcs_error(error: JcsError) -> OpenId4vpTypeError {
275    let reason = match error {
276        JcsError::DuplicateProperty => OpenId4vpTypeErrorReason::DuplicateJsonKey,
277        JcsError::DepthExceeded => OpenId4vpTypeErrorReason::JsonDepthExceeded,
278        _ => OpenId4vpTypeErrorReason::InvalidEncoding,
279    };
280    OpenId4vpTypeError::new(reason)
281}
282
283fn map_trusted_jcs_error(error: JcsError) -> OpenId4vpTypeError {
284    let reason = match error {
285        JcsError::DepthExceeded => OpenId4vpTypeErrorReason::JsonDepthExceeded,
286        _ => OpenId4vpTypeErrorReason::SerializationFailed,
287    };
288    OpenId4vpTypeError::new(reason)
289}
290
291fn transaction_data_object_value(
292    transaction_data: &TransactionData,
293) -> Result<JsonValue, OpenId4vpTypeError> {
294    let mut map = JsonMap::new();
295    map.insert(
296        "type".to_owned(),
297        JsonValue::String(transaction_data.transaction_type.clone()),
298    );
299    map.insert(
300        "credential_ids".to_owned(),
301        JsonValue::Array(
302            transaction_data
303                .credential_ids
304                .iter()
305                .cloned()
306                .map(JsonValue::String)
307                .collect(),
308        ),
309    );
310    let JsonValue::Object(payload) = &transaction_data.payload else {
311        return Err(OpenId4vpTypeError::new(
312            OpenId4vpTypeErrorReason::InvalidEncoding,
313        ));
314    };
315    for (key, value) in payload {
316        if key != "type" && key != "credential_ids" {
317            map.insert(key.clone(), value.clone());
318        }
319    }
320    Ok(JsonValue::Object(map))
321}
322
323fn transaction_data_from_object(
324    mut object: SensitiveTransactionDataObject,
325    mut encoded_value: Zeroizing<String>,
326) -> Result<TransactionData, OpenId4vpTypeError> {
327    let mut transaction_type = match object.0.remove("type") {
328        Some(JsonValue::String(value)) => Zeroizing::new(value),
329        Some(mut invalid) => {
330            zeroize_json_value(&mut invalid);
331            return Err(OpenId4vpTypeError::new(
332                OpenId4vpTypeErrorReason::InvalidEncoding,
333            ));
334        }
335        None => {
336            return Err(OpenId4vpTypeError::new(
337                OpenId4vpTypeErrorReason::InvalidEncoding,
338            ));
339        }
340    };
341    let mut credential_values = match object.0.remove("credential_ids") {
342        Some(JsonValue::Array(values)) => SensitiveJsonValues(values),
343        Some(mut invalid) => {
344            zeroize_json_value(&mut invalid);
345            return Err(OpenId4vpTypeError::new(
346                OpenId4vpTypeErrorReason::InvalidEncoding,
347            ));
348        }
349        None => {
350            return Err(OpenId4vpTypeError::new(
351                OpenId4vpTypeErrorReason::InvalidEncoding,
352            ));
353        }
354    };
355    let mut credential_ids = Zeroizing::new(Vec::with_capacity(credential_values.0.len()));
356    while let Some(mut value) = credential_values.0.pop() {
357        match value {
358            JsonValue::String(mut value) => {
359                credential_ids.push(core::mem::take(&mut value));
360                value.zeroize();
361            }
362            _ => {
363                zeroize_json_value(&mut value);
364                return Err(OpenId4vpTypeError::new(
365                    OpenId4vpTypeErrorReason::InvalidEncoding,
366                ));
367            }
368        }
369    }
370    credential_ids.reverse();
371    let payload = JsonValue::Object(core::mem::take(&mut object.0));
372    let mut transaction_data = TransactionData {
373        transaction_type: core::mem::take(&mut transaction_type),
374        credential_ids: core::mem::take(&mut credential_ids),
375        payload,
376        encoded_value: core::mem::take(&mut encoded_value),
377    };
378    if let Err(error) = validate_transaction_data(&transaction_data) {
379        transaction_data.zeroize();
380        return Err(error);
381    }
382    Ok(transaction_data)
383}
384
385struct SensitiveTransactionDataObject(JsonMap<String, JsonValue>);
386
387impl SensitiveTransactionDataObject {
388    const fn new(value: JsonMap<String, JsonValue>) -> Self {
389        Self(value)
390    }
391}
392
393impl Drop for SensitiveTransactionDataObject {
394    fn drop(&mut self) {
395        let mut value = JsonValue::Object(core::mem::take(&mut self.0));
396        zeroize_json_value(&mut value);
397    }
398}
399
400struct SensitiveJsonValues(Vec<JsonValue>);
401
402impl Drop for SensitiveJsonValues {
403    fn drop(&mut self) {
404        for value in &mut self.0 {
405            zeroize_json_value(value);
406        }
407    }
408}
409
410fn validate_transaction_data(transaction_data: &TransactionData) -> Result<(), OpenId4vpTypeError> {
411    if transaction_data.transaction_type.is_empty()
412        || transaction_data.credential_ids.is_empty()
413        || transaction_data.credential_ids.iter().any(String::is_empty)
414    {
415        return Err(OpenId4vpTypeError::new(
416            OpenId4vpTypeErrorReason::EmptyValue,
417        ));
418    }
419    if !transaction_data.payload.is_object() {
420        return Err(OpenId4vpTypeError::new(
421            OpenId4vpTypeErrorReason::InvalidEncoding,
422        ));
423    }
424    Ok(())
425}
426
427#[cfg(test)]
428#[path = "transaction_data_tests.rs"]
429mod tests;