Skip to main content

minco_config/
secret.rs

1use serde::{Deserialize, Deserializer, Serialize, de::Error as _};
2use std::fmt;
3use thiserror::Error;
4
5/// Provider named by an opaque secret reference.
6#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
7#[serde(rename_all = "snake_case")]
8pub enum SecretProvider {
9    EnvironmentVariable,
10    SystemsManagerParameter,
11}
12
13/// A provider-neutral pointer to a secret value.
14///
15/// This type contains a reference name, never a resolved secret value. Its
16/// `Debug` implementation intentionally omits the name so ordinary diagnostic
17/// logging cannot reveal secret inventory.
18#[derive(Clone, PartialEq, Eq, Serialize)]
19#[serde(tag = "provider", rename_all = "snake_case")]
20pub enum SecretReference {
21    EnvironmentVariable { name: String },
22    SystemsManagerParameter { name: String },
23}
24
25#[derive(Deserialize)]
26#[serde(tag = "provider", rename_all = "snake_case")]
27enum SecretReferenceRepresentation {
28    EnvironmentVariable { name: String },
29    SystemsManagerParameter { name: String },
30}
31
32impl<'de> Deserialize<'de> for SecretReference {
33    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
34    where
35        D: Deserializer<'de>,
36    {
37        match SecretReferenceRepresentation::deserialize(deserializer)? {
38            SecretReferenceRepresentation::EnvironmentVariable { name } => {
39                Self::environment_variable(name).map_err(D::Error::custom)
40            }
41            SecretReferenceRepresentation::SystemsManagerParameter { name } => {
42                Self::systems_manager_parameter(name).map_err(D::Error::custom)
43            }
44        }
45    }
46}
47
48impl SecretReference {
49    /// Construct a reference to an explicitly named environment variable.
50    pub fn environment_variable(name: impl Into<String>) -> Result<Self, SecretReferenceError> {
51        let name = name.into();
52        validate_environment_name(&name)?;
53        Ok(Self::EnvironmentVariable { name })
54    }
55
56    /// Construct a reference to an explicitly named SSM parameter.
57    pub fn systems_manager_parameter(
58        name: impl Into<String>,
59    ) -> Result<Self, SecretReferenceError> {
60        let name = name.into();
61        validate_parameter_name(&name)?;
62        Ok(Self::SystemsManagerParameter { name })
63    }
64
65    /// Parse the only accepted configuration syntaxes: `env:NAME` and
66    /// `ssm:/absolute/parameter/name`.
67    pub fn parse(value: &str) -> Result<Self, SecretReferenceError> {
68        if let Some(name) = value.strip_prefix("env:") {
69            return Self::environment_variable(name);
70        }
71        if let Some(name) = value.strip_prefix("ssm:") {
72            return Self::systems_manager_parameter(name);
73        }
74        Err(SecretReferenceError::UnsupportedSyntax)
75    }
76
77    pub const fn provider(&self) -> SecretProvider {
78        match self {
79            Self::EnvironmentVariable { .. } => SecretProvider::EnvironmentVariable,
80            Self::SystemsManagerParameter { .. } => SecretProvider::SystemsManagerParameter,
81        }
82    }
83}
84
85impl fmt::Debug for SecretReference {
86    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
87        formatter
88            .debug_struct("SecretReference")
89            .field("provider", &self.provider())
90            .field("name", &"[REDACTED]")
91            .finish()
92    }
93}
94
95#[derive(Debug, Clone, PartialEq, Eq, Error)]
96pub enum SecretReferenceError {
97    #[error("secret references must use env:NAME or ssm:/absolute/name")]
98    UnsupportedSyntax,
99    #[error("environment secret reference names must match [A-Z_][A-Z0-9_]*")]
100    InvalidEnvironmentName,
101    #[error("SSM secret reference names must satisfy bounded Parameter Store path syntax")]
102    InvalidParameterName,
103}
104
105fn validate_environment_name(name: &str) -> Result<(), SecretReferenceError> {
106    let mut bytes = name.bytes();
107    let Some(first) = bytes.next() else {
108        return Err(SecretReferenceError::InvalidEnvironmentName);
109    };
110    if name.len() > 256
111        || !(first.is_ascii_uppercase() || first == b'_')
112        || bytes.any(|byte| !(byte.is_ascii_uppercase() || byte.is_ascii_digit() || byte == b'_'))
113    {
114        return Err(SecretReferenceError::InvalidEnvironmentName);
115    }
116    Ok(())
117}
118
119fn validate_parameter_name(name: &str) -> Result<(), SecretReferenceError> {
120    let Some(relative) = name.strip_prefix('/') else {
121        return Err(SecretReferenceError::InvalidParameterName);
122    };
123    if name.len() > 1_011
124        || relative.is_empty()
125        || !relative
126            .bytes()
127            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'.' | b'-' | b'/'))
128        || relative.split('/').any(str::is_empty)
129        || relative.split('/').count() > 15
130        || relative.get(..3).is_some_and(|prefix| {
131            prefix.eq_ignore_ascii_case("aws") || prefix.eq_ignore_ascii_case("ssm")
132        })
133    {
134        return Err(SecretReferenceError::InvalidParameterName);
135    }
136    Ok(())
137}
138
139#[cfg(test)]
140mod tests {
141    use super::*;
142
143    #[test]
144    fn secret_reference_syntax_is_bounded() {
145        assert!(SecretReference::parse("env:DATABASE_URL").is_ok());
146        assert!(SecretReference::parse("ssm:/orders/production/database-url").is_ok());
147        assert!(SecretReference::parse("ssm:/Orders_v2/Production/database.url").is_ok());
148        for invalid in [
149            "secret",
150            "env:lowercase",
151            "env:",
152            "ssm:relative",
153            "ssm:/bad//name",
154            "ssm:/bad name",
155            "ssm:/bad:name",
156            "ssm:/aws/managed",
157            "ssm:/SSM-secret",
158            "ssm:/1/2/3/4/5/6/7/8/9/10/11/12/13/14/15/16",
159        ] {
160            assert!(SecretReference::parse(invalid).is_err(), "{invalid}");
161        }
162        let oversized = format!("ssm:/{}", "a".repeat(1_011));
163        assert!(SecretReference::parse(&oversized).is_err());
164    }
165
166    #[test]
167    fn debug_redacts_reference_names() {
168        let reference = SecretReference::environment_variable("DATABASE_URL").unwrap();
169        let rendered = format!("{reference:?}");
170        assert!(rendered.contains("[REDACTED]"));
171        assert!(!rendered.contains("DATABASE_URL"));
172    }
173
174    #[test]
175    fn deserialization_cannot_bypass_reference_validation() {
176        let invalid = r#"{"provider":"environment_variable","name":"secret-value"}"#;
177        assert!(serde_json::from_str::<SecretReference>(invalid).is_err());
178    }
179}