Skip to main content

esh_providers_aws/
lib.rs

1//! AWS Secrets Manager and Systems Manager Parameter Store providers.
2//!
3//! These providers use an injectable [`AwsSecretsClient`] so unit tests do not
4//! require live AWS credentials. Production integrations can wrap the AWS SDK
5//! or a signed HTTP client behind the same trait.
6
7use async_trait::async_trait;
8use esh_core::{
9    ConfigValue, Error, Provider, ProviderCapability, ProviderId, ProviderMeta, Result,
10};
11use serde_json::Value as JsonValue;
12use std::collections::HashMap;
13use std::sync::Arc;
14
15/// Minimal client surface for Secrets Manager + SSM.
16#[async_trait]
17pub trait AwsSecretsClient: Send + Sync {
18    /// `GetSecretValue` equivalent. Returns secret string.
19    async fn get_secret_value(&self, secret_id: &str) -> Result<String>;
20
21    /// `GetParameter` equivalent (with decryption).
22    async fn get_parameter(&self, name: &str) -> Result<String>;
23}
24
25/// In-memory fake for tests and local demos.
26#[derive(Default, Clone)]
27pub struct MapAwsClient {
28    secrets: HashMap<String, String>,
29    parameters: HashMap<String, String>,
30    /// When set, all calls fail with this mode.
31    fault: Option<AwsFault>,
32}
33
34/// Injected failure mode for [`MapAwsClient`].
35#[derive(Clone, Copy, Debug, PartialEq, Eq)]
36pub enum AwsFault {
37    /// Simulate auth / access denied.
38    Auth,
39    /// Simulate request timeout.
40    Timeout,
41}
42
43impl MapAwsClient {
44    /// Create empty client.
45    #[must_use]
46    pub fn new() -> Self {
47        Self::default()
48    }
49
50    /// Insert a Secrets Manager value.
51    #[must_use]
52    pub fn with_secret(mut self, id: impl Into<String>, value: impl Into<String>) -> Self {
53        self.secrets.insert(id.into(), value.into());
54        self
55    }
56
57    /// Insert an SSM parameter.
58    #[must_use]
59    pub fn with_parameter(mut self, name: impl Into<String>, value: impl Into<String>) -> Self {
60        self.parameters.insert(name.into(), value.into());
61        self
62    }
63
64    /// Force all subsequent calls to fail.
65    #[must_use]
66    pub fn with_fault(mut self, fault: AwsFault) -> Self {
67        self.fault = Some(fault);
68        self
69    }
70
71    fn check_fault(&self) -> Result<()> {
72        match self.fault {
73            Some(AwsFault::Auth) => Err(Error::provider("aws", "access denied")),
74            Some(AwsFault::Timeout) => Err(Error::provider("aws", "timeout")),
75            None => Ok(()),
76        }
77    }
78}
79
80#[async_trait]
81impl AwsSecretsClient for MapAwsClient {
82    async fn get_secret_value(&self, secret_id: &str) -> Result<String> {
83        self.check_fault()?;
84        self.secrets
85            .get(secret_id)
86            .cloned()
87            .ok_or_else(|| Error::not_found(secret_id))
88    }
89
90    async fn get_parameter(&self, name: &str) -> Result<String> {
91        self.check_fault()?;
92        self.parameters
93            .get(name)
94            .cloned()
95            .ok_or_else(|| Error::not_found(name))
96    }
97}
98
99/// AWS Secrets Manager provider.
100///
101/// Key lookup uses `prefix` + key as the secret id/name. If the secret string
102/// is JSON, nested keys are available via `key` matching a top-level field.
103pub struct AwsSecretsManagerProvider {
104    meta: ProviderMeta,
105    client: Arc<dyn AwsSecretsClient>,
106    /// Prefix prepended to logical keys (e.g. `prod/app/`).
107    prefix: String,
108    /// When true, treat secret body as JSON object and extract `key`.
109    json_field_mode: bool,
110}
111
112impl AwsSecretsManagerProvider {
113    /// Create with an injectable client.
114    #[must_use]
115    pub fn new(client: Arc<dyn AwsSecretsClient>) -> Self {
116        Self {
117            meta: ProviderMeta {
118                id: ProviderId::new("aws-secrets-manager"),
119                name: "AWS Secrets Manager".into(),
120                capabilities: ProviderCapability {
121                    bulk: false,
122                    versioned: true,
123                    local: false,
124                },
125            },
126            client,
127            prefix: String::new(),
128            json_field_mode: false,
129        }
130    }
131
132    /// Set name prefix.
133    #[must_use]
134    pub fn with_prefix(mut self, prefix: impl Into<String>) -> Self {
135        self.prefix = prefix.into();
136        self
137    }
138
139    /// Extract JSON object fields by logical key.
140    #[must_use]
141    pub fn json_fields(mut self) -> Self {
142        self.json_field_mode = true;
143        self
144    }
145
146    fn secret_id(&self, key: &str) -> String {
147        format!("{}{key}", self.prefix)
148    }
149}
150
151#[async_trait]
152impl Provider for AwsSecretsManagerProvider {
153    fn meta(&self) -> &ProviderMeta {
154        &self.meta
155    }
156
157    async fn get(&self, key: &str) -> Result<ConfigValue> {
158        if self.json_field_mode {
159            // In JSON field mode, `prefix` is the secret id; `key` is a field.
160            let secret_id = if self.prefix.is_empty() {
161                return Err(Error::InvalidConfig(
162                    "aws-secrets-manager json_fields mode requires a secret prefix/id".into(),
163                ));
164            } else {
165                self.prefix.trim_end_matches('/').to_string()
166            };
167            let body = self.client.get_secret_value(&secret_id).await?;
168            let json: JsonValue = serde_json::from_str(&body).map_err(|e| {
169                Error::provider(self.meta.id.as_str(), format!("secret is not JSON: {e}"))
170            })?;
171            let field = json
172                .get(key)
173                .and_then(|v| v.as_str().map(str::to_string).or_else(|| Some(v.to_string())))
174                .ok_or_else(|| Error::not_found(key))?;
175            return Ok(ConfigValue::secret(field));
176        }
177
178        let id = self.secret_id(key);
179        let body = self.client.get_secret_value(&id).await.map_err(|e| match e {
180            Error::NotFound { .. } => Error::not_found(key),
181            other => other,
182        })?;
183        Ok(ConfigValue::secret(body))
184    }
185}
186
187/// AWS SSM Parameter Store provider.
188pub struct AwsSsmProvider {
189    meta: ProviderMeta,
190    client: Arc<dyn AwsSecretsClient>,
191    prefix: String,
192}
193
194impl AwsSsmProvider {
195    /// Create with injectable client.
196    #[must_use]
197    pub fn new(client: Arc<dyn AwsSecretsClient>) -> Self {
198        Self {
199            meta: ProviderMeta {
200                id: ProviderId::new("aws-ssm"),
201                name: "AWS SSM Parameter Store".into(),
202                capabilities: ProviderCapability {
203                    bulk: false,
204                    versioned: true,
205                    local: false,
206                },
207            },
208            client,
209            prefix: String::new(),
210        }
211    }
212
213    /// Path prefix (e.g. `/prod/app/`).
214    #[must_use]
215    pub fn with_prefix(mut self, prefix: impl Into<String>) -> Self {
216        self.prefix = prefix.into();
217        self
218    }
219
220    fn param_name(&self, key: &str) -> String {
221        if self.prefix.is_empty() {
222            key.to_string()
223        } else if self.prefix.ends_with('/') {
224            format!("{}{key}", self.prefix)
225        } else {
226            format!("{}/{key}", self.prefix)
227        }
228    }
229}
230
231#[async_trait]
232impl Provider for AwsSsmProvider {
233    fn meta(&self) -> &ProviderMeta {
234        &self.meta
235    }
236
237    async fn get(&self, key: &str) -> Result<ConfigValue> {
238        let name = self.param_name(key);
239        let body = self.client.get_parameter(&name).await.map_err(|e| match e {
240            Error::NotFound { .. } => Error::not_found(key),
241            other => other,
242        })?;
243        Ok(ConfigValue::secret(body))
244    }
245}
246
247#[cfg(test)]
248mod tests {
249    use super::*;
250    use esh_core::ProviderCapability;
251    use esh_test_support::{
252        run_provider_conformance, ProviderConformanceCfg, SAMPLE_SECRET, SAMPLE_TOKEN,
253    };
254
255    #[tokio::test]
256    async fn secrets_manager_json_field() {
257        let client = Arc::new(
258            MapAwsClient::new()
259                .with_secret("app/prod", r#"{"database_url":"postgres://aws"}"#),
260        );
261        let p = AwsSecretsManagerProvider::new(client)
262            .with_prefix("app/prod")
263            .json_fields();
264        let v = p.get("database_url").await.unwrap();
265        assert_eq!(v.as_str(), Some("postgres://aws"));
266    }
267
268    #[tokio::test]
269    async fn ssm_with_prefix() {
270        let client = Arc::new(MapAwsClient::new().with_parameter("/prod/app/token", "t1"));
271        let p = AwsSsmProvider::new(client).with_prefix("/prod/app");
272        assert_eq!(p.get("token").await.unwrap().as_str(), Some("t1"));
273    }
274
275    #[tokio::test]
276    async fn secrets_manager_conformance() {
277        let client = Arc::new(MapAwsClient::new().with_secret("database_url", SAMPLE_SECRET));
278        let p = AwsSecretsManagerProvider::new(client);
279        run_provider_conformance(
280            &p,
281            &ProviderConformanceCfg {
282                expected_id: "aws-secrets-manager".into(),
283                expected_capabilities: ProviderCapability {
284                    bulk: false,
285                    versioned: true,
286                    local: false,
287                },
288                present_key: "database_url".into(),
289                present_value: SAMPLE_SECRET.into(),
290                missing_key: "missing_key_xyz".into(),
291                fault_key: None,
292                health_ok: true,
293                test_get_many: true,
294            },
295        )
296        .await;
297    }
298
299    #[tokio::test]
300    async fn secrets_manager_auth_fault() {
301        let client = Arc::new(
302            MapAwsClient::new()
303                .with_secret("database_url", SAMPLE_SECRET)
304                .with_fault(AwsFault::Auth),
305        );
306        let p = AwsSecretsManagerProvider::new(client);
307        let err = p.get("database_url").await.unwrap_err();
308        assert!(matches!(err, Error::Provider { .. }));
309        assert!(!err.to_string().contains(SAMPLE_SECRET));
310    }
311
312    #[tokio::test]
313    async fn ssm_conformance() {
314        let client = Arc::new(MapAwsClient::new().with_parameter("api_token", SAMPLE_TOKEN));
315        let p = AwsSsmProvider::new(client);
316        run_provider_conformance(
317            &p,
318            &ProviderConformanceCfg {
319                expected_id: "aws-ssm".into(),
320                expected_capabilities: ProviderCapability {
321                    bulk: false,
322                    versioned: true,
323                    local: false,
324                },
325                present_key: "api_token".into(),
326                present_value: SAMPLE_TOKEN.into(),
327                missing_key: "nope".into(),
328                fault_key: None,
329                health_ok: true,
330                test_get_many: true,
331            },
332        )
333        .await;
334    }
335}