openzeppelin_relayer/utils/serde/

repository_encryption.rs

//! Helper functions to serialize and deserialize secrets as encrypted base64 for storage.
//!
//! This module provides serde serializers/deserializers that automatically encrypt
//! sensitive data when storing to Redis and decrypt when retrieving.
//!
//! ## AAD (Additional Authenticated Data)
//!
//! **Serialization**: Always uses AAD (via `EncryptionContext`) to bind the ciphertext
//! to its storage location. The `EncryptionContext`
//! must be set before serialization.
//!
//! **Deserialization**: Supports both legacy (v1, no AAD) and new (v2, with AAD)
//! encrypted data for backwards compatibility. If `EncryptionContext` is set, it will
//! be used for v2 decryption; v1 data can be decrypted without context.

use secrets::SecretVec;
use serde::{Deserialize, Deserializer, Serializer};

use crate::{
    models::SecretString,
    utils::{
        base64_decode, base64_encode, decrypt_sensitive_field_auto,
        encrypt_sensitive_field_with_aad,
    },
};

/// Helper function to serialize secrets as encrypted base64 for storage.
///
/// Uses AAD from `EncryptionContext` to bind the ciphertext to its storage location.
/// The `EncryptionContext` must be set before calling this function.
pub fn serialize_secret_vec<S>(secret: &SecretVec<u8>, serializer: S) -> Result<S::Ok, S::Error>
where
    S: Serializer,
{
    // First encode the raw secret as base64
    let base64 = base64_encode(secret.borrow().as_ref());

    // Then encrypt the base64 string for secure storage with AAD
    let encrypted = encrypt_sensitive_field_with_aad(&base64)
        .map_err(|e| serde::ser::Error::custom(format!("Encryption failed: {e}")))?;

    serializer.serialize_str(&encrypted)
}

/// Helper function to deserialize secrets from encrypted base64 storage.
///
/// Supports both legacy (v1, no AAD) and new (v2, with AAD) encrypted data
/// for backwards compatibility. Uses `EncryptionContext` for v2 decryption if set.
pub fn deserialize_secret_vec<'de, D>(deserializer: D) -> Result<SecretVec<u8>, D::Error>
where
    D: Deserializer<'de>,
{
    let encrypted_str = String::deserialize(deserializer)?;

    // Decrypt using auto-detection to handle both v1 (legacy) and v2 (with AAD)
    let base64_str = decrypt_sensitive_field_auto(&encrypted_str)
        .map_err(|e| serde::de::Error::custom(format!("Decryption failed: {e}")))?;

    // Then decode the base64 to get the raw secret bytes
    let decoded = base64_decode(&base64_str)
        .map_err(|e| serde::de::Error::custom(format!("Invalid base64: {e}")))?;

    Ok(SecretVec::new(decoded.len(), |v| {
        v.copy_from_slice(&decoded)
    }))
}

/// Helper function to serialize secrets as encrypted base64 for storage.
///
/// Uses AAD from `EncryptionContext` to bind the ciphertext to its storage location.
/// The `EncryptionContext` must be set before calling this function.
pub fn serialize_secret_string<S>(secret: &SecretString, serializer: S) -> Result<S::Ok, S::Error>
where
    S: Serializer,
{
    let secret_content = secret.to_str();

    // Encrypt with AAD (already returns base64-encoded string)
    let encrypted = encrypt_sensitive_field_with_aad(&secret_content)
        .map_err(|e| serde::ser::Error::custom(format!("Encryption failed: {e}")))?;

    serializer.serialize_str(&encrypted)
}

/// Helper function to deserialize secrets from encrypted base64 storage.
///
/// Supports three formats for backwards compatibility:
/// 1. Encrypted format (v2): base64(encrypted data with AAD)
/// 2. Legacy encrypted format (v1): base64(encrypted data without AAD)
/// 3. Plain text format: unencrypted plain string (for data stored before encryption was added)
///
/// Uses `EncryptionContext` for v2 decryption if set.
pub fn deserialize_secret_string<'de, D>(deserializer: D) -> Result<SecretString, D::Error>
where
    D: Deserializer<'de>,
{
    let value_str = String::deserialize(deserializer)?;

    // First try the direct decrypt path (single-layer base64 payloads).
    if let Ok(decrypted) = decrypt_sensitive_field_auto(&value_str) {
        return Ok(SecretString::new(&decrypted));
    }

    // Fall back to treating the original string as plain text.
    Ok(SecretString::new(&value_str))
}

/// Helper function to serialize optional secrets as encrypted base64 for storage.
///
/// Uses AAD from `EncryptionContext` to bind the ciphertext to its storage location.
/// The `EncryptionContext` must be set before calling this function.
pub fn serialize_option_secret_string<S>(
    secret: &Option<SecretString>,
    serializer: S,
) -> Result<S::Ok, S::Error>
where
    S: Serializer,
{
    match secret {
        Some(secret_string) => {
            let secret_content = secret_string.to_str();

            // Encrypt with AAD (already returns base64-encoded string)
            let encrypted = encrypt_sensitive_field_with_aad(&secret_content)
                .map_err(|e| serde::ser::Error::custom(format!("Encryption failed: {e}")))?;

            serializer.serialize_some(&encrypted)
        }
        None => serializer.serialize_none(),
    }
}

/// Helper function to deserialize optional secrets from encrypted base64 storage.
///
/// Supports three formats for backwards compatibility:
/// 1. Encrypted format (v2): base64(encrypted data with AAD)
/// 2. Legacy encrypted format (v1): base64(encrypted data without AAD)
/// 3. Plain text format: unencrypted plain string (for data stored before encryption was added)
///
/// Uses `EncryptionContext` for v2 decryption if set.
pub fn deserialize_option_secret_string<'de, D>(
    deserializer: D,
) -> Result<Option<SecretString>, D::Error>
where
    D: Deserializer<'de>,
{
    let opt_value_str: Option<String> = Option::deserialize(deserializer)?;

    match opt_value_str {
        Some(value_str) => {
            // First try the direct decrypt path (single-layer base64 payloads).
            if let Ok(decrypted) = decrypt_sensitive_field_auto(&value_str) {
                return Ok(Some(SecretString::new(&decrypted)));
            }

            // Fall back to treating the original string as plain text.
            Ok(Some(SecretString::new(&value_str)))
        }
        None => Ok(None),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::utils::EncryptionContext;
    use secrets::SecretVec;
    use serde_json;

    fn test_aad() -> String {
        "test-context".to_string()
    }

    #[test]
    fn test_serialize_deserialize_secret_string() {
        let secret = SecretString::new("test-secret-content");

        // Create a test struct that uses the secret string serialization
        #[derive(serde::Serialize, serde::Deserialize)]
        struct TestStruct {
            #[serde(
                serialize_with = "serialize_secret_string",
                deserialize_with = "deserialize_secret_string"
            )]
            secret: SecretString,
        }

        let test_struct = TestStruct {
            secret: secret.clone(),
        };

        // Test serialization with AAD context
        let serialized = EncryptionContext::with_aad_sync(test_aad(), || {
            serde_json::to_string(&test_struct).unwrap()
        });

        // Test deserialization with AAD context
        let deserialized: TestStruct = EncryptionContext::with_aad_sync(test_aad(), || {
            serde_json::from_str(&serialized).unwrap()
        });

        // Verify content matches
        assert_eq!(secret.to_str(), deserialized.secret.to_str());
    }

    #[test]
    fn test_serialize_deserialize_secret_vec() {
        let original_data = vec![1, 2, 3, 4, 5];
        let secret = SecretVec::new(original_data.len(), |v| v.copy_from_slice(&original_data));

        // Create a test struct that uses the secret vec serialization
        #[derive(serde::Serialize, serde::Deserialize)]
        struct TestStruct {
            #[serde(
                serialize_with = "serialize_secret_vec",
                deserialize_with = "deserialize_secret_vec"
            )]
            secret_data: SecretVec<u8>,
        }

        let test_struct = TestStruct {
            secret_data: secret,
        };

        // Test serialization with AAD context
        let serialized = EncryptionContext::with_aad_sync(test_aad(), || {
            serde_json::to_string(&test_struct).unwrap()
        });

        // Test deserialization with AAD context
        let deserialized: TestStruct = EncryptionContext::with_aad_sync(test_aad(), || {
            serde_json::from_str(&serialized).unwrap()
        });

        // Verify content matches
        let original_borrowed = original_data;
        let deserialized_borrowed = deserialized.secret_data.borrow();
        assert_eq!(original_borrowed, *deserialized_borrowed);
    }

    #[test]
    fn test_serialize_deserialize_option_secret_string_some() {
        let secret = SecretString::new("test-optional-secret");

        // Create a test struct that uses the option secret string serialization
        #[derive(serde::Serialize, serde::Deserialize)]
        struct TestStruct {
            #[serde(
                serialize_with = "serialize_option_secret_string",
                deserialize_with = "deserialize_option_secret_string"
            )]
            optional_secret: Option<SecretString>,
        }

        let test_struct = TestStruct {
            optional_secret: Some(secret.clone()),
        };

        // Test serialization with AAD context
        let serialized = EncryptionContext::with_aad_sync(test_aad(), || {
            serde_json::to_string(&test_struct).unwrap()
        });

        // Test deserialization with AAD context
        let deserialized: TestStruct = EncryptionContext::with_aad_sync(test_aad(), || {
            serde_json::from_str(&serialized).unwrap()
        });

        // Verify content matches
        assert!(deserialized.optional_secret.is_some());
        assert_eq!(
            secret.to_str(),
            deserialized.optional_secret.unwrap().to_str()
        );
    }

    #[test]
    fn test_serialize_deserialize_option_secret_string_none() {
        let secret: Option<SecretString> = None;

        // Create a test struct that uses the option secret string serialization
        #[derive(serde::Serialize, serde::Deserialize)]
        struct TestStruct {
            #[serde(
                serialize_with = "serialize_option_secret_string",
                deserialize_with = "deserialize_option_secret_string"
            )]
            optional_secret: Option<SecretString>,
        }

        let test_struct = TestStruct {
            optional_secret: secret,
        };

        // Test serialization with AAD context
        let serialized = EncryptionContext::with_aad_sync(test_aad(), || {
            serde_json::to_string(&test_struct).unwrap()
        });

        // Test deserialization with AAD context
        let deserialized: TestStruct = EncryptionContext::with_aad_sync(test_aad(), || {
            serde_json::from_str(&serialized).unwrap()
        });

        // Verify it's None
        assert!(deserialized.optional_secret.is_none());
    }

    #[test]
    fn test_round_trip_secret_string() {
        let original = SecretString::new("complex-secret-with-special-chars-!@#$%^&*()");

        #[derive(serde::Serialize, serde::Deserialize)]
        struct TestStruct {
            #[serde(
                serialize_with = "serialize_secret_string",
                deserialize_with = "deserialize_secret_string"
            )]
            secret: SecretString,
        }

        let test_struct = TestStruct {
            secret: original.clone(),
        };

        // Serialize to JSON with AAD context
        let json = EncryptionContext::with_aad_sync(test_aad(), || {
            serde_json::to_string(&test_struct).unwrap()
        });

        // Deserialize back with AAD context
        let deserialized: TestStruct =
            EncryptionContext::with_aad_sync(test_aad(), || serde_json::from_str(&json).unwrap());

        // Verify the content is identical
        assert_eq!(original.to_str(), deserialized.secret.to_str());
    }

    #[test]
    fn test_round_trip_option_secret_string_with_multiple_values() {
        let test_cases = vec![
            Some(SecretString::new("test1")),
            None,
            Some(SecretString::new("")),
            Some(SecretString::new("test-with-unicode-🔐")),
            Some(SecretString::new(&"very-long-secret-".repeat(100))),
        ];

        #[derive(serde::Serialize, serde::Deserialize)]
        struct TestStruct {
            #[serde(
                serialize_with = "serialize_option_secret_string",
                deserialize_with = "deserialize_option_secret_string"
            )]
            optional_secret: Option<SecretString>,
        }

        for test_case in test_cases {
            let test_struct = TestStruct {
                optional_secret: test_case.clone(),
            };

            // Serialize to JSON with AAD context
            let json = EncryptionContext::with_aad_sync(test_aad(), || {
                serde_json::to_string(&test_struct).unwrap()
            });

            // Deserialize back with AAD context
            let deserialized: TestStruct = EncryptionContext::with_aad_sync(test_aad(), || {
                serde_json::from_str(&json).unwrap()
            });

            // Verify the content matches
            match (test_case, deserialized.optional_secret) {
                (Some(original), Some(deserialized_secret)) => {
                    assert_eq!(original.to_str(), deserialized_secret.to_str());
                }
                (None, None) => {
                    // Both are None, this is correct
                }
                _ => panic!("Mismatch between original and deserialized optional secret"),
            }
        }
    }

    #[test]
    fn test_serialized_content_is_encrypted() {
        let secret = SecretString::new("plaintext-secret");

        #[derive(serde::Serialize)]
        struct TestStruct {
            #[serde(serialize_with = "serialize_secret_string")]
            secret: SecretString,
        }

        let test_struct = TestStruct { secret };

        // Serialize with AAD context
        let json = EncryptionContext::with_aad_sync(test_aad(), || {
            serde_json::to_string(&test_struct).unwrap()
        });

        // The serialized JSON should not contain the plaintext secret
        assert!(!json.contains("plaintext-secret"));

        // It should be base64 encoded (contains only valid base64 characters)
        let json_value: serde_json::Value = serde_json::from_str(&json).unwrap();
        let serialized_secret = json_value["secret"].as_str().unwrap();

        // Verify it's valid base64 by attempting to decode it
        assert!(base64_decode(serialized_secret).is_ok());
    }

    #[test]
    fn test_serialized_option_content_when_some() {
        let secret = Some(SecretString::new("plaintext-secret"));

        #[derive(serde::Serialize)]
        struct TestStruct {
            #[serde(serialize_with = "serialize_option_secret_string")]
            optional_secret: Option<SecretString>,
        }

        let test_struct = TestStruct {
            optional_secret: secret,
        };

        // Serialize with AAD context
        let json = EncryptionContext::with_aad_sync(test_aad(), || {
            serde_json::to_string(&test_struct).unwrap()
        });

        // The serialized JSON should not contain the plaintext secret
        assert!(!json.contains("plaintext-secret"));

        // Parse the JSON to verify structure
        let json_value: serde_json::Value = serde_json::from_str(&json).unwrap();
        assert!(json_value["optional_secret"].is_string());

        let serialized_secret = json_value["optional_secret"].as_str().unwrap();
        // Verify it's valid base64
        assert!(base64_decode(serialized_secret).is_ok());
    }

    #[test]
    fn test_serialized_option_content_when_none() {
        let secret: Option<SecretString> = None;

        #[derive(serde::Serialize)]
        struct TestStruct {
            #[serde(serialize_with = "serialize_option_secret_string")]
            optional_secret: Option<SecretString>,
        }

        let test_struct = TestStruct {
            optional_secret: secret,
        };

        // Serialize with AAD context
        let json = EncryptionContext::with_aad_sync(test_aad(), || {
            serde_json::to_string(&test_struct).unwrap()
        });

        // Parse the JSON to verify structure
        let json_value: serde_json::Value = serde_json::from_str(&json).unwrap();
        assert!(json_value["optional_secret"].is_null());
    }

    #[test]
    fn test_serialize_fails_without_context() {
        let secret = SecretString::new("test-secret");

        #[derive(serde::Serialize)]
        struct TestStruct {
            #[serde(serialize_with = "serialize_secret_string")]
            secret: SecretString,
        }

        let test_struct = TestStruct { secret };

        // Should fail without AAD context
        let result = serde_json::to_string(&test_struct);
        assert!(result.is_err());
        assert!(result
            .unwrap_err()
            .to_string()
            .contains("EncryptionContext not set"));
    }

    #[test]
    fn test_deserialize_plain_text_backward_compatibility() {
        // Test deserializing plain text that was stored before encryption was added
        #[derive(serde::Deserialize)]
        struct TestStruct {
            #[serde(deserialize_with = "deserialize_secret_string")]
            project_id: SecretString,
            #[serde(deserialize_with = "deserialize_secret_string")]
            location: SecretString,
        }

        // Simulate old JSON format with plain strings (including hyphens)
        let old_json = r#"{"project_id":"my-project-123","location":"us-central1"}"#;

        // Should successfully deserialize plain text as SecretString
        let deserialized: TestStruct = serde_json::from_str(old_json).unwrap();

        assert_eq!(*deserialized.project_id.to_str(), "my-project-123");
        assert_eq!(*deserialized.location.to_str(), "us-central1");
    }

    #[test]
    fn test_deserialize_option_plain_text_backward_compatibility() {
        // Test deserializing optional plain text
        #[derive(serde::Deserialize)]
        struct TestStruct {
            #[serde(deserialize_with = "deserialize_option_secret_string")]
            field: Option<SecretString>,
        }

        // Plain text
        let json = r#"{"field":"plain-value-with-hyphen"}"#;
        let deserialized: TestStruct = serde_json::from_str(json).unwrap();
        assert_eq!(
            *deserialized.field.unwrap().to_str(),
            "plain-value-with-hyphen"
        );

        // None
        let json = r#"{"field":null}"#;
        let deserialized: TestStruct = serde_json::from_str(json).unwrap();
        assert!(deserialized.field.is_none());
    }

    #[test]
    fn test_mixed_format_deserialization() {
        // Test deserializing a mix of encrypted and plain text fields
        #[derive(serde::Deserialize)]
        struct TestStruct {
            #[serde(deserialize_with = "deserialize_secret_string")]
            plain_field: SecretString,
            #[serde(deserialize_with = "deserialize_secret_string")]
            encrypted_field: SecretString,
        }

        // First, create an encrypted value
        let encrypted_value = EncryptionContext::with_aad_sync(test_aad(), || {
            #[derive(serde::Serialize)]
            struct TempStruct {
                #[serde(serialize_with = "serialize_secret_string")]
                field: SecretString,
            }
            let temp = TempStruct {
                field: SecretString::new("encrypted-content"),
            };
            serde_json::to_string(&temp).unwrap()
        });

        let encrypted_value_parsed: serde_json::Value =
            serde_json::from_str(&encrypted_value).unwrap();
        let encrypted_field_value = encrypted_value_parsed["field"].as_str().unwrap();

        // Create JSON with both plain and encrypted fields
        let mixed_json = format!(
            r#"{{"plain_field":"plain-text-value","encrypted_field":"{encrypted_field_value}"}}"#
        );

        // Should successfully deserialize both
        let deserialized: TestStruct = EncryptionContext::with_aad_sync(test_aad(), || {
            serde_json::from_str(&mixed_json).unwrap()
        });

        assert_eq!(*deserialized.plain_field.to_str(), "plain-text-value");
        assert_eq!(*deserialized.encrypted_field.to_str(), "encrypted-content");
    }
}