shrouded 0.2.0

Secure memory management with mlock, guard pages, and automatic zeroization
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153

//! Optional serde support for shrouded types.
//!
//! This module provides `Deserialize` implementations for shrouded types.
//! Note that `Serialize` is intentionally NOT implemented to prevent
//! accidental serialization of secrets.
//!
//! # Features
//!
//! Enable the `serde` feature to use these implementations:
//!
//! ```toml
//! [dependencies]
//! shrouded = { version = "0.1", features = ["serde"] }
//! ```
//!
//! # Example
//!
//! ```ignore
//! use shrouded::ShroudedString;
//! use serde::Deserialize;
//!
//! #[derive(Deserialize)]
//! struct Config {
//!     #[serde(deserialize_with = "shrouded::serde::deserialize_string")]
//!     api_key: ShroudedString,
//! }
//! ```

use crate::types::{ShroudedBytes, ShroudedString};
use serde::de::{self, Deserialize, Deserializer, Visitor};

/// Deserializes a `ShroudedString` from a string value.
///
/// Use with `#[serde(deserialize_with = "shrouded::serde::deserialize_string")]`
pub fn deserialize_string<'de, D>(deserializer: D) -> Result<ShroudedString, D::Error>
where
    D: Deserializer<'de>,
{
    struct StringVisitor;

    impl<'de> Visitor<'de> for StringVisitor {
        type Value = ShroudedString;

        fn expecting(&self, formatter: &mut core::fmt::Formatter) -> core::fmt::Result {
            formatter.write_str("a string")
        }

        fn visit_str<E>(self, v: &str) -> Result<Self::Value, E>
        where
            E: de::Error,
        {
            ShroudedString::new(v.to_string())
                .map_err(|e| E::custom(format!("failed to create ShroudedString: {}", e)))
        }
    }

    deserializer.deserialize_str(StringVisitor)
}

/// Deserializes a `ShroudedBytes` from a string (for JSON compatibility).
///
/// Use with `#[serde(deserialize_with = "shrouded::serde::deserialize_bytes")]`
pub fn deserialize_bytes<'de, D>(deserializer: D) -> Result<ShroudedBytes, D::Error>
where
    D: Deserializer<'de>,
{
    struct BytesVisitor;

    impl<'de> Visitor<'de> for BytesVisitor {
        type Value = ShroudedBytes;

        fn expecting(&self, formatter: &mut core::fmt::Formatter) -> core::fmt::Result {
            formatter.write_str("a string or byte sequence")
        }

        fn visit_str<E>(self, v: &str) -> Result<Self::Value, E>
        where
            E: de::Error,
        {
            let mut data = v.as_bytes().to_vec();
            ShroudedBytes::from_slice(&mut data)
                .map_err(|e| E::custom(format!("failed to create ShroudedBytes: {}", e)))
        }

        fn visit_bytes<E>(self, v: &[u8]) -> Result<Self::Value, E>
        where
            E: de::Error,
        {
            let mut data = v.to_vec();
            ShroudedBytes::from_slice(&mut data)
                .map_err(|e| E::custom(format!("failed to create ShroudedBytes: {}", e)))
        }
    }

    // Use deserialize_str for JSON compatibility (JSON doesn't have native bytes)
    deserializer.deserialize_str(BytesVisitor)
}

impl<'de> Deserialize<'de> for ShroudedString {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        deserialize_string(deserializer)
    }
}

impl<'de> Deserialize<'de> for ShroudedBytes {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        deserialize_bytes(deserializer)
    }
}

// Note: Serialize is intentionally NOT implemented to prevent accidental
// serialization of secrets. If you need to serialize, explicitly call
// .expose() and serialize the result.

#[cfg(test)]
mod tests {
    use super::*;
    use crate::traits::Expose;

    #[test]
    fn test_deserialize_string() {
        let json = r#""secret_password""#;
        let secret: ShroudedString = serde_json::from_str(json).unwrap();
        assert_eq!(secret.expose(), "secret_password");
    }

    #[test]
    fn test_deserialize_bytes_from_string() {
        // In JSON, bytes are typically represented as strings
        let json = r#""binary_data""#;
        let secret: ShroudedBytes = serde_json::from_str(json).unwrap();
        assert_eq!(secret.expose(), b"binary_data");
    }

    #[derive(serde::Deserialize)]
    struct TestConfig {
        #[serde(deserialize_with = "deserialize_string")]
        api_key: ShroudedString,
    }

    #[test]
    fn test_deserialize_in_struct() {
        let json = r#"{"api_key": "sk_test_123"}"#;
        let config: TestConfig = serde_json::from_str(json).unwrap();
        assert_eq!(config.api_key.expose(), "sk_test_123");
    }
}