Merge pull request #134 from cachix/feat/awssm-tags-kms

feat(awssm): support KMS key and tags on secret creation

Author: domenkozar

CHANGELOG.md

@@ -8,6 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- The `awssm` provider accepts `kms_key_id` and `tag.NAME=VALUE` query
+  parameters (e.g. `awssm://prod@us-east-1?kms_key_id=alias/my-key&tag.team=platform`).
+  Both are applied only when secretspec creates a secret, so accounts that enforce
+  a customer-managed KMS key or "tag-on-create" guardrails (an SCP requiring
+  `aws:RequestTag/*` on `CreateSecret`) can now store secrets. A pre-existing
+  secret keeps the key and tags it was created with.
 - PHP SDK (`cachix/secretspec`): resolve secrets from PHP, Laravel, and Symfony
   over the same shared resolver as the other language SDKs. It ships as a native
   PHP extension that embeds the resolver (works under PHP-FPM with no

docs/src/content/docs/providers/awssm.md

@@ -16,12 +16,21 @@ The AWS Secrets Manager provider integrates with AWS for centralized secret mana
 ### URI Format
 
 ```
-awssm://[AWS_PROFILE@]REGION[?prefix=PREFIX]
+awssm://[AWS_PROFILE@]REGION[?prefix=PREFIX][&kms_key_id=KEY][&tag.NAME=VALUE...]
 ```
 
 - `REGION`: AWS region (e.g., `us-east-1`). If omitted, the SDK default region chain is used.
 - `AWS_PROFILE`: Optional AWS profile from `~/.aws/credentials`. If omitted, the SDK default credential chain is used.
 - `PREFIX`: Optional root prefix prepended to all secret names. Useful when IAM policies scope access by prefix (e.g., only allow `myteam/*`).
+- `kms_key_id`: Optional KMS key (id, ARN, or `alias/...`) used to encrypt secrets that secretspec creates.
+- `tag.NAME=VALUE`: Optional tags applied to secrets that secretspec creates. Repeat for multiple tags.
+
+`kms_key_id` and `tag.NAME=VALUE` are applied **only when secretspec creates a
+secret** (`CreateSecret`); updating a value (`PutSecretValue`) accepts neither,
+and a pre-existing secret keeps the key and tags it was created with. This
+supports AWS "tag-on-create" guardrails, where an SCP or IAM condition denies
+`CreateSecret` unless required `aws:RequestTag/*` tags (and often a
+customer-managed key) are present in the same call.
 
 ### Examples
 
@@ -35,6 +44,9 @@ $ secretspec check --provider awssm://production@us-east-1
 # Use a prefix to scope secrets under "myteam/"
 $ secretspec set DATABASE_URL --provider "awssm://us-east-1?prefix=myteam"
 
+# Create secrets with a customer-managed KMS key and required tags
+$ secretspec set DATABASE_URL --provider "awssm://prod@us-east-1?kms_key_id=alias/my-key&tag.team=platform&tag.env=prod"
+
 # Get a secret
 $ secretspec get DATABASE_URL --provider awssm://us-east-1
 
@@ -45,6 +57,15 @@ $ secretspec run --provider awssm://us-east-1 -- npm start
 $ secretspec set DATABASE_URL --provider awssm
 ```
 
+Because guardrail tags and keys usually vary per environment, they are a natural
+fit for a checked-in [provider alias](/reference/configuration/) in
+`secretspec.toml`:
+
+```toml
+[providers]
+prod = "awssm://prod@us-east-1?kms_key_id=alias/my-key&tag.team=platform&tag.env=prod"
+```
+
 ## Secret References
 
 By default each secret is stored under `secretspec/{project}/{profile}/{key}`. A
@@ -122,6 +143,11 @@ arn:aws:secretsmanager:*:*:secret:myteam/secretspec/*
 The `BatchGetSecretValue` permission is required for batch fetching, which is used automatically during `check` and `run` commands to reduce API calls. If your IAM policy was created before this feature, you may need to add this permission.
 :::
 
+:::note
+Using `tag.NAME=VALUE` additionally requires `secretsmanager:TagResource`, and a
+`kms_key_id` requires `kms:GenerateDataKey` and `kms:Decrypt` on that key.
+:::
+
 ### CI/CD
 
 ```bash

secretspec/src/provider/awssm.rs

@@ -12,11 +12,13 @@
 //!
 //! # URI Format
 //!
-//! `awssm://[aws-profile@]region[?prefix=PREFIX]`
+//! `awssm://[aws-profile@]region[?prefix=PREFIX][&kms_key_id=KEY][&tag.NAME=VALUE…]`
 //!
 //! - `awssm://us-east-1` — use SDK default credentials in us-east-1
 //! - `awssm://production@us-east-1` — use the "production" AWS profile in us-east-1
 //! - `awssm://us-east-1?prefix=myteam` — prefix all secret names with `myteam/`
+//! - `awssm://prod@us-east-1?kms_key_id=alias/my-key&tag.team=platform&tag.env=prod`
+//!   — encrypt with a customer-managed key and tag secrets on create
 //! - `awssm://` — use SDK defaults for both profile and region
 //!
 //! # Secret Naming
@@ -26,6 +28,15 @@
 //! When a `prefix` query parameter is set, it is prepended to the secret name,
 //! allowing IAM policies to scope access (e.g. `arn:aws:secretsmanager:*:*:secret:myteam/*`).
 //!
+//! # KMS Key and Tags
+//!
+//! The `kms_key_id` and `tag.NAME=VALUE` query parameters are applied **only when
+//! secretspec creates a secret** (`CreateSecret`); updates (`PutSecretValue`) accept
+//! neither, and a pre-existing secret keeps whatever key and tags it was created with.
+//! This supports AWS "tag-on-create" guardrails, where an SCP or IAM condition denies
+//! `CreateSecret` unless required `aws:RequestTag/*` tags (and often a customer-managed
+//! key) are present in the same call.
+//!
 //! # Example
 //!
 //! ```bash
@@ -39,9 +50,10 @@
 use super::{Address, Provider, ProviderUrl};
 use crate::{Result, SecretSpecError};
 use aws_sdk_secretsmanager::Client;
+use aws_sdk_secretsmanager::types::Tag;
 use secrecy::{ExposeSecret, SecretString};
 use serde::{Deserialize, Serialize};
-use std::collections::HashMap;
+use std::collections::{BTreeMap, HashMap};
 
 /// Maximum number of secrets per BatchGetSecretValue API call.
 const AWS_BATCH_GET_MAX_SECRETS: usize = 20;
@@ -57,6 +69,13 @@ pub struct AwssmConfig {
     /// `myteam/secretspec/{project}/{profile}/{key}`).
     /// Useful for scoping IAM policies by prefix.
     pub prefix: Option<String>,
+    /// KMS key (id, ARN, or `alias/…`) used to encrypt secrets this provider
+    /// creates. Applied only on create; `None` uses the account's default key.
+    pub kms_key_id: Option<String>,
+    /// Tags applied only when this provider creates a secret. A `BTreeMap` so
+    /// iteration (and thus `uri()`) is deterministic for the audit log.
+    #[serde(default)]
+    pub tags: BTreeMap<String, String>,
 }
 
 impl TryFrom<&ProviderUrl> for AwssmConfig {
@@ -84,6 +103,20 @@ impl TryFrom<&ProviderUrl> for AwssmConfig {
 
         let prefix = url.query_value("prefix");
 
+        let kms_key_id = url.query_value("kms_key_id");
+
+        // Tags are collected from every `tag.NAME=VALUE` query pair. Iterating
+        // `query_pairs` directly (rather than `query_value`) both collects the
+        // whole namespaced set and preserves empty values, which AWS accepts.
+        let tags: BTreeMap<String, String> = url
+            .query_pairs()
+            .filter_map(|(k, v)| {
+                k.strip_prefix("tag.")
+                    .filter(|name| !name.is_empty())
+                    .map(|name| (name.to_string(), v.into_owned()))
+            })
+            .collect();
+
         // The path reference form from earlier iterations is rejected with a
         // pointer at the `ref` table, instead of being silently ignored and
         // reading the conventional layout.
@@ -101,6 +134,8 @@ impl TryFrom<&ProviderUrl> for AwssmConfig {
             region,
             aws_profile,
             prefix,
+            kms_key_id,
+            tags,
         })
     }
 }
@@ -119,7 +154,7 @@ crate::register_provider! {
     name: "awssm",
     description: "AWS Secrets Manager",
     schemes: ["awssm"],
-    examples: ["awssm://us-east-1", "awssm://production@us-east-1", "awssm://us-east-1?prefix=myteam"],
+    examples: ["awssm://us-east-1", "awssm://production@us-east-1", "awssm://us-east-1?prefix=myteam", "awssm://prod@us-east-1?kms_key_id=alias/my-key&tag.team=platform"],
 }
 
 impl AwssmProvider {
@@ -310,23 +345,34 @@ impl AwssmProvider {
     }
 
     /// Creates or updates a secret at its full name in AWS Secrets Manager.
+    ///
+    /// The configured `kms_key_id` and `tags` are applied only on create;
+    /// `PutSecretValue` accepts neither, so an existing secret keeps the key
+    /// and tags it was created with.
     async fn set_secret_async(&self, secret_name: &str, value: &SecretString) -> Result<()> {
         let client = self.create_client().await?;
 
-        // Try to create the secret first
-        let create_result = client
+        // Try to create the secret first, applying the KMS key and tags. These
+        // must ride the CreateSecret call itself to satisfy "tag-on-create"
+        // guardrails (`aws:RequestTag`); a later TagResource would not.
+        let mut create = client
             .create_secret()
             .name(secret_name)
-            .secret_string(value.expose_secret())
-            .send()
-            .await;
+            .secret_string(value.expose_secret());
+        if let Some(kms_key_id) = &self.config.kms_key_id {
+            create = create.kms_key_id(kms_key_id);
+        }
+        for (key, val) in &self.config.tags {
+            create = create.tags(Tag::builder().key(key).value(val).build());
+        }
 
-        match create_result {
+        match create.send().await {
             Ok(_) => Ok(()),
             Err(err) => {
                 let service_err = err.into_service_error();
                 if service_err.is_resource_exists_exception() {
-                    // Secret already exists, update it
+                    // Secret already exists, update its value (KMS key and tags
+                    // are create-only and left untouched here).
                     client
                         .put_secret_value()
                         .secret_id(secret_name)
@@ -376,17 +422,37 @@ impl Provider for AwssmProvider {
             (None, Some(region)) => format!("awssm://{}", region),
             (_, None) => "awssm".to_string(),
         };
-        match &self.config.prefix {
-            Some(prefix) => {
-                let sep = if base.contains("://") { "?" } else { "://?" };
-                format!(
-                    "{}{}prefix={}",
-                    base,
-                    sep,
-                    ProviderUrl::encode_query(prefix)
-                )
-            }
-            None => base,
+
+        // Reconstruct every query parameter. `tags` is a BTreeMap, so it
+        // iterates in sorted key order and `uri()` is deterministic.
+        let mut params: Vec<String> = Vec::new();
+        if let Some(prefix) = &self.config.prefix {
+            params.push(format!("prefix={}", ProviderUrl::encode_query(prefix)));
+        }
+        if let Some(kms_key_id) = &self.config.kms_key_id {
+            params.push(format!(
+                "kms_key_id={}",
+                ProviderUrl::encode_query(kms_key_id)
+            ));
+        }
+        for (key, value) in &self.config.tags {
+            params.push(format!(
+                "tag.{}={}",
+                ProviderUrl::encode_query(key),
+                ProviderUrl::encode_query(value)
+            ));
+        }
+
+        if params.is_empty() {
+            base
+        } else {
+            // Only the region-less `awssm` arm omits the `://` authority.
+            let sep = if self.config.region.is_some() {
+                "?"
+            } else {
+                "://?"
+            };
+            format!("{}{}{}", base, sep, params.join("&"))
         }
     }
 
@@ -486,6 +552,62 @@ mod tests {
         assert_eq!(coords.item, "myteam/secretspec/proj/default/A");
     }
 
+    #[test]
+    fn parses_kms_key_id_and_tags() {
+        let c =
+            config("awssm://prod@us-east-1?kms_key_id=alias/my-key&tag.env=prod&tag.team=platform");
+        assert_eq!(c.kms_key_id.as_deref(), Some("alias/my-key"));
+        assert_eq!(c.tags.get("env").map(String::as_str), Some("prod"));
+        assert_eq!(c.tags.get("team").map(String::as_str), Some("platform"));
+    }
+
+    #[test]
+    fn absent_kms_and_tags_default_to_empty() {
+        let c = config("awssm://us-east-1");
+        assert_eq!(c.kms_key_id, None);
+        assert!(c.tags.is_empty());
+    }
+
+    /// AWS accepts empty tag values, and `tag.NAME=` carries a real (empty)
+    /// value — kept rather than dropped like an empty `prefix`/`kms_key_id`.
+    #[test]
+    fn empty_tag_value_is_kept() {
+        let c = config("awssm://us-east-1?tag.env=");
+        assert_eq!(c.tags.get("env").map(String::as_str), Some(""));
+    }
+
+    /// `uri()` reconstructs every parameter and orders tags deterministically
+    /// (BTreeMap), regardless of the order they appeared in the source URI, so
+    /// the audit log stays stable.
+    #[test]
+    fn uri_round_trips_kms_and_sorted_tags() {
+        let c = config("awssm://prod@us-east-1?tag.team=platform&kms_key_id=alias/k&tag.env=prod");
+        let p = AwssmProvider::new(c);
+        assert_eq!(
+            p.uri(),
+            "awssm://prod@us-east-1?kms_key_id=alias/k&tag.env=prod&tag.team=platform"
+        );
+        // Re-parsing the reconstructed URI yields the same config.
+        let reparsed = config(&p.uri());
+        assert_eq!(reparsed.kms_key_id.as_deref(), Some("alias/k"));
+        assert_eq!(reparsed.tags.get("env").map(String::as_str), Some("prod"));
+        assert_eq!(
+            reparsed.tags.get("team").map(String::as_str),
+            Some("platform")
+        );
+    }
+
+    #[test]
+    fn uri_round_trips_prefix_with_kms_and_tags() {
+        let p = AwssmProvider::new(config(
+            "awssm://us-east-1?prefix=myteam&kms_key_id=alias/k&tag.env=prod",
+        ));
+        assert_eq!(
+            p.uri(),
+            "awssm://us-east-1?prefix=myteam&kms_key_id=alias/k&tag.env=prod"
+        );
+    }
+
     #[test]
     fn test_batch_chunking() {
         let names: Vec<String> = (0..45).map(|i| format!("SECRET_{}", i)).collect();