1use serde::{Deserialize, Deserializer, Serialize, de::Error as _};
2use std::fmt;
3use thiserror::Error;
4
5#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
7#[serde(rename_all = "snake_case")]
8pub enum SecretProvider {
9 EnvironmentVariable,
10 SystemsManagerParameter,
11}
12
13#[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 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 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 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}