feat: [#243] introduce SecretString-based secret types with folder module structure

Author: josecelano

Cargo.toml

@@ -51,6 +51,7 @@ parking_lot = "0.12"
 reqwest = "0.12"
 rust-embed = "8.0"
 schemars = "1.1"
+secrecy = { version = "0.10", features = [ "serde" ] }
 serde = { version = "1.0", features = [ "derive" ] }
 serde_json = "1.0"
 tempfile = "3.0"

docs/issues/243-introduce-secret-type-for-sensitive-data.md

@@ -5,7 +5,13 @@
 
 ## Overview
 
-Replace all primitive `String` types used for sensitive data (API tokens, passwords, database credentials) with the industry-standard `secrecy` crate's `Secret<String>` type. This enhances security by preventing accidental exposure through logging/debug output and enabling automatic memory zeroing.
+Replace all primitive `String` types used for sensitive data (API tokens, passwords, database credentials) with wrapper types based on the industry-standard `secrecy` crate's `SecretString` type. This enhances security by preventing accidental exposure through logging/debug output and enabling automatic memory zeroing.
+
+**Implementation Approach**: We use `secrecy::SecretString` as the foundation (which is a type alias for `SecretBox<str>`) and wrap it in domain-specific types (`ApiToken`, `Password`) that add:
+
+- Serialization support (secrecy intentionally doesn't serialize secrets by default)
+- PartialEq/Eq for config comparison in tests
+- Domain-specific type safety
 
 ## Refactor Plan
 
@@ -20,9 +26,9 @@ The plan includes:
 
 ## Goals
 
-- [ ] Replace 16 string-based secret fields with `Secret<String>` type
-- [ ] Prevent accidental secret exposure in logs and debug output
-- [ ] Enable secure memory zeroing for sensitive data
+- [ ] Replace 16 string-based secret fields with `ApiToken`/`Password` wrapper types
+- [ ] Leverage `SecretString` for automatic debug redaction and memory zeroing
+- [ ] Add serialization support for config file generation (deployment tool needs this)
 - [ ] Update documentation with secret handling guidelines
 
 ## Acceptance Criteria
@@ -35,7 +41,8 @@ The plan includes:
 
 **Task-Specific Criteria**:
 
-- [ ] All 16 secret fields converted to `Secret<String>` (tracked in refactor plan)
+- [ ] All 16 secret fields converted to `ApiToken`/`Password` types (tracked in refactor plan)
+- [ ] Wrapper types use `SecretString` internally for debug redaction and memory zeroing
 - [ ] No secrets appear in debug/display output
 - [ ] All unit tests pass with updated secret types
 - [ ] All E2E tests pass with secret handling

docs/refactors/plans/secret-type-introduction.md

@@ -2,9 +2,11 @@
 
 ## 📋 Overview
 
-Introduce the `secrecy` crate's `Secret<T>` type to replace primitive `String` types for sensitive data throughout the codebase. This refactoring enhances security by clearly identifying secret values, preventing accidental exposure through logging or debugging, and ensuring secrets are securely wiped from memory when dropped.
+Introduce wrapper types based on the `secrecy` crate's `SecretString` to replace primitive `String` types for sensitive data throughout the codebase. This refactoring enhances security by clearly identifying secret values, preventing accidental exposure through logging or debugging, and ensuring secrets are securely wiped from memory when dropped.
 
-**Decision**: After evaluating custom implementation vs industry-standard solutions, we chose the `secrecy` crate (see [ADR](../../decisions/secrecy-crate-for-sensitive-data.md)).
+**Decision**: After evaluating custom implementation vs industry-standard solutions, we chose to use `secrecy::SecretString` as the foundation with thin wrapper types (see [ADR](../../decisions/secrecy-crate-for-sensitive-data.md)).
+
+**Implementation Note**: `SecretString` (which is `SecretBox<str>`) provides debug redaction and memory zeroing but cannot implement `Serialize` (requires `SerializableSecret` trait which `str` doesn't implement due to orphan rules). Our wrapper types (`ApiToken`, `Password`) add serialization support needed for config file generation in this deployment tool.
 
 **Target Files:**
 
@@ -20,12 +22,12 @@ Introduce the `secrecy` crate's `Secret<T>` type to replace primitive `String` t
 
 **Scope:**
 
-- Add `secrecy` crate dependency to project
-- Create `src/shared/secret.rs` module (re-exports and type aliases)
-- Implement `SerializableSecret` marker trait for `String`
-- Replace all `String` fields containing secrets with `Secret<String>` type
-- Update all tests to use `Secret::new()` and `expose_secret()`
-- Verify debug output redacts secrets
+- Add `secrecy` crate dependency to project (with `serde` feature)
+- Create `src/shared/secret.rs` module with `ApiToken` and `Password` wrappers around `SecretString`
+- Wrappers add: serialization support, PartialEq/Eq for testing, domain-specific types
+- Replace all `String` fields containing secrets with `ApiToken`/`Password` types
+- Update all tests to use `ApiToken::from()` / `Password::from()` and `.expose_secret()`
+- Verify debug output redacts secrets (provided by `SecretString`)
 - Document decision in ADR (already completed)
 - Update AI agent instructions
 

schema.json

@@ -66,7 +66,7 @@
               "type": "string"
             },
             "password": {
-              "description": "Database password",
+              "description": "Database password (plain text during DTO serialization/deserialization)\n\nUses `PlainPassword` type alias to explicitly mark this as a temporarily visible secret.\nConverted to secure `Password` type in `to_database_config()` at the DTO-to-domain boundary.",
               "type": "string"
             },
             "port": {
@@ -118,7 +118,7 @@
       "type": "object",
       "properties": {
         "api_token": {
-          "description": "Hetzner API token (raw string).",
+          "description": "Hetzner API token in plain text format (DTO layer).\n\nThis uses [`PlainApiToken`] to mark it as a transparent secret during\ndeserialization. Convert to domain `ApiToken` at the DTO-to-domain boundary.",
           "type": "string"
         },
         "image": {

src/application/command_handlers/create/config/provider/hetzner.rs

@@ -7,6 +7,8 @@
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 
+use crate::shared::PlainApiToken;
+
 /// Hetzner-specific configuration section
 ///
 /// Uses raw `String` fields for JSON deserialization. Convert to domain
@@ -26,8 +28,11 @@ use serde::{Deserialize, Serialize};
 /// ```
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
 pub struct HetznerProviderSection {
-    /// Hetzner API token (raw string).
-    pub api_token: String,
+    /// Hetzner API token in plain text format (DTO layer).
+    ///
+    /// This uses [`PlainApiToken`] to mark it as a transparent secret during
+    /// deserialization. Convert to domain `ApiToken` at the DTO-to-domain boundary.
+    pub api_token: PlainApiToken,
 
     /// Hetzner server type (e.g., "cx22", "cx32", "cpx11").
     pub server_type: String,

src/application/command_handlers/create/config/provider/mod.rs

@@ -46,6 +46,7 @@ use serde::{Deserialize, Serialize};
 use crate::application::command_handlers::create::config::CreateConfigError;
 use crate::domain::provider::{HetznerConfig, LxdConfig, Provider, ProviderConfig};
 use crate::domain::ProfileName;
+use crate::shared::ApiToken;
 
 /// Provider-specific configuration section
 ///
@@ -147,7 +148,7 @@ impl ProviderSection {
             Self::Hetzner(hetzner) => {
                 // Note: Future improvement could add validation for these fields
                 Ok(ProviderConfig::Hetzner(HetznerConfig {
-                    api_token: hetzner.api_token,
+                    api_token: ApiToken::from(hetzner.api_token),
                     server_type: hetzner.server_type,
                     location: hetzner.location,
                     image: hetzner.image,
@@ -266,7 +267,7 @@ mod tests {
         assert_eq!(config.provider_name(), "hetzner");
 
         let hetzner = config.as_hetzner().unwrap();
-        assert_eq!(hetzner.api_token, "test-token");
+        assert_eq!(hetzner.api_token.expose_secret(), "test-token");
         assert_eq!(hetzner.server_type, "cx22");
         assert_eq!(hetzner.location, "nbg1");
         assert_eq!(hetzner.image, "ubuntu-24.04");

src/application/command_handlers/create/config/tracker/tracker_core_section.rs

@@ -9,6 +9,7 @@ use serde::{Deserialize, Serialize};
 
 use crate::application::command_handlers::create::config::errors::CreateConfigError;
 use crate::domain::tracker::{DatabaseConfig, MysqlConfig, SqliteConfig, TrackerCoreConfig};
+use crate::shared::{Password, PlainPassword};
 
 /// Database configuration section (application DTO)
 ///
@@ -54,8 +55,11 @@ pub enum DatabaseSection {
         database_name: String,
         /// Database username
         username: String,
-        /// Database password
-        password: String,
+        /// Database password (plain text during DTO serialization/deserialization)
+        ///
+        /// Uses `PlainPassword` type alias to explicitly mark this as a temporarily visible secret.
+        /// Converted to secure `Password` type in `to_database_config()` at the DTO-to-domain boundary.
+        password: PlainPassword,
     },
 }
 
@@ -83,7 +87,7 @@ impl DatabaseSection {
                 port: *port,
                 database_name: database_name.clone(),
                 username: username.clone(),
-                password: password.clone(),
+                password: Password::from(password.as_str()),
             })),
         }
     }
@@ -222,7 +226,7 @@ mod tests {
                 port: 3306,
                 database_name: "tracker".to_string(),
                 username: "tracker_user".to_string(),
-                password: "secure_password".to_string(),
+                password: Password::from("secure_password"),
             })
         );
         assert!(!config.private);

src/application/steps/rendering/docker_compose_templates.rs

@@ -39,6 +39,7 @@ use crate::infrastructure::templating::docker_compose::template::wrappers::env::
 use crate::infrastructure::templating::docker_compose::{
     DockerComposeProjectGenerator, DockerComposeProjectGeneratorError,
 };
+use crate::shared::PlainPassword;
 
 /// Step that renders Docker Compose templates to the build directory
 ///
@@ -118,7 +119,7 @@ impl<S> RenderDockerComposeTemplatesStep<S> {
                 mysql_config.port,
                 mysql_config.database_name.clone(),
                 mysql_config.username.clone(),
-                mysql_config.password.clone(),
+                mysql_config.password.expose_secret().to_string(),
             ),
         };
 
@@ -172,7 +173,7 @@ impl<S> RenderDockerComposeTemplatesStep<S> {
         port: u16,
         database_name: String,
         username: String,
-        password: String,
+        password: PlainPassword,
     ) -> (EnvContext, DockerComposeContextBuilder) {
         // For MySQL, generate a secure root password (in production, this should be managed securely)
         let root_password = format!("{password}_root");

src/domain/environment/user_inputs.rs

@@ -257,7 +257,7 @@ mod tests {
     use super::*;
     use crate::domain::provider::LxdConfig;
     use crate::domain::ProfileName;
-    use crate::shared::Username;
+    use crate::shared::{ApiToken, Username};
     use std::path::PathBuf;
 
     fn create_test_ssh_credentials() -> SshCredentials {
@@ -310,7 +310,7 @@ mod tests {
 
         let env_name = EnvironmentName::new("test-env".to_string()).unwrap();
         let provider_config = ProviderConfig::Hetzner(HetznerConfig {
-            api_token: "test-token".to_string(),
+            api_token: ApiToken::from("test-token"),
             server_type: "cx22".to_string(),
             location: "nbg1".to_string(),
             image: "ubuntu-24.04".to_string(),
@@ -323,7 +323,7 @@ mod tests {
         assert!(user_inputs.provider_config().as_lxd().is_none());
 
         let hetzner_config = user_inputs.provider_config().as_hetzner().unwrap();
-        assert_eq!(hetzner_config.api_token, "test-token");
+        assert_eq!(hetzner_config.api_token.expose_secret(), "test-token");
         assert_eq!(hetzner_config.server_type, "cx22");
         assert_eq!(hetzner_config.location, "nbg1");
         assert_eq!(hetzner_config.image, "ubuntu-24.04");

src/domain/provider/config.rs

@@ -118,14 +118,15 @@ impl ProviderConfig {
     /// ```rust
     /// use torrust_tracker_deployer_lib::domain::provider::{ProviderConfig, LxdConfig, HetznerConfig};
     /// use torrust_tracker_deployer_lib::domain::ProfileName;
+    /// use torrust_tracker_deployer_lib::shared::secrets::ApiToken;
     ///
     /// let lxd_config = ProviderConfig::Lxd(LxdConfig {
     ///     profile_name: ProfileName::new("test").unwrap(),
     /// });
     /// assert!(lxd_config.as_lxd().is_some());
     ///
     /// let hetzner_config = ProviderConfig::Hetzner(HetznerConfig {
-    ///     api_token: "token".to_string(),
+    ///     api_token: ApiToken::from("token"),
     ///     server_type: "cx22".to_string(),
     ///     location: "nbg1".to_string(),
     ///     image: "ubuntu-24.04".to_string(),
@@ -167,8 +168,10 @@ mod tests {
     }
 
     fn create_hetzner_config() -> ProviderConfig {
+        use crate::shared::ApiToken;
+
         ProviderConfig::Hetzner(HetznerConfig {
-            api_token: "test-token".to_string(),
+            api_token: ApiToken::from("test-token"),
             server_type: "cx22".to_string(),
             location: "nbg1".to_string(),
             image: "ubuntu-24.04".to_string(),
@@ -242,7 +245,7 @@ mod tests {
 
         assert_eq!(config.provider(), Provider::Hetzner);
         let hetzner = config.as_hetzner().unwrap();
-        assert_eq!(hetzner.api_token, "token");
+        assert_eq!(hetzner.api_token.expose_secret(), "token");
         assert_eq!(hetzner.server_type, "cx22");
         assert_eq!(hetzner.location, "nbg1");
         assert_eq!(hetzner.image, "ubuntu-24.04");