feat(mysql): make root_password configurable, generate at creation time

Bug 2 fix from issue #410.

- Add optional root_password field to environment config JSON schema
- MysqlConfig.root_password is Password (non-optional); domain always has a value
- MysqlConfigRaw.root_password is Option<Password> for backward compat with
  persisted environments that pre-date this field
- Add src/shared/secrets/random.rs: generate_random_password() -> Password
  using rand::rng(), mixed charset (lower+upper+digit+symbol), length 32,
  satisfies MySQL validate_password MEDIUM policy
- Generate root_password once in TryFrom<DatabaseSection> at environment
  creation time (not at render time) so it is stable across re-renders
- Remove format!("{password}_root") derivation from create_mysql_contexts
- Update spec docs/issues/410-bug-multiple-mysql-configuration-issues.md
  to reflect the actual implementation

Author: josecelano

Cargo.toml

@@ -50,6 +50,7 @@ clap = { version = "4.0", features = [ "derive" ] }
 derive_more = { version = "2.1", features = [ "display", "from" ] }
 figment = { version = "0.10", features = [ "json" ] }
 parking_lot = "0.12"
+rand = "0.9"
 reqwest = "0.12"
 rust-embed = "8.0"
 schemars = "1.1"

docs/issues/410-bug-multiple-mysql-configuration-issues.md

@@ -46,11 +46,12 @@ value.
 
 ### Bug 2 — Root password not configurable
 
-- [ ] Add an optional `root_password` field to the MySQL section of the environment
+- [x] Add an optional `root_password` field to the MySQL section of the environment
       configuration JSON schema
-- [ ] When a root password is provided by the user, use it; when omitted, generate a
-      strong random password at render time rather than deriving it from the app password
-- [ ] Remove the `format!("{password}_root")` derivation from `create_mysql_contexts`
+- [x] When a root password is provided by the user, use it; when omitted, generate a
+      strong random password at environment creation time (application layer) rather
+      than deriving it from the app password
+- [x] Remove the `format!("{password}_root")` derivation from `create_mysql_contexts`
 
 ### Bug 3 — Reserved username not rejected
 
@@ -174,21 +175,44 @@ no `root_password` field for MySQL. The deployer therefore always sets
 
 **Fix**: Add an optional `root_password` to the MySQL section of the environment
 configuration JSON. If the user provides it, use it. If they omit it, generate a
-cryptographically random password at render time instead of deriving it from the app
-password. Remove the `format!("{password}_root")` derivation.
+cryptographically random password at **environment creation time** (application layer)
+instead of deriving it from the app password. Remove the `format!("{password}_root")`
+derivation.
+
+**Key design decision — generate at creation time, not render time**: The root password
+is a domain invariant that must remain stable across multiple renders (e.g. re-deploying
+without reprovisioning). Generating it at render time would produce a different
+`MYSQL_ROOT_PASSWORD` on each render, breaking MySQL container restarts. Instead,
+generation happens once in the application layer (`TryFrom<DatabaseSection>`) when the
+environment is first created, and the value is persisted alongside the rest of the
+environment config.
 
 **Affected modules and types**:
 
+- `Cargo.toml`: add `rand = "0.9"` dependency.
 - `schemas/environment-config.json`: add optional `root_password` string to the MySQL
   database object.
-- `src/domain/tracker/config/core/database/mysql.rs` (`MysqlConfig`): add optional
-  `root_password` field; update constructor and accessors.
-- `src/presentation/cli/controllers/create/subcommands/environment/config_loader.rs`
-  (or equivalent deserialization path): propagate the optional field through to the
-  domain type.
+- `src/shared/secrets/random.rs` (new file): `generate_random_password() -> Password`
+  using `rand::rng()` (ThreadRng seeded from OsRng), guaranteeing one character from each
+  class (lower, upper, digit, symbol), filled to 32 characters, then shuffled. Satisfies
+  MySQL `validate_password MEDIUM` policy.
+- `src/shared/secrets/mod.rs` and `src/shared/mod.rs`: re-export
+  `generate_random_password`.
+- `src/domain/tracker/config/core/database/mysql.rs` (`MysqlConfig`): `root_password`
+  field is `Password` (non-optional) — the domain type always has a value. Constructor
+  `new()` takes `root_password: Password`. Accessor `root_password() -> &Password` added.
+  `MysqlConfigRaw` (the serde deserialization intermediate) keeps
+  `root_password: Option<Password>` with `#[serde(default)]` for backward compatibility
+  with persisted environments that pre-date this field; missing values are filled by
+  calling `generate_random_password()` during deserialization.
+- `src/application/command_handlers/create/config/tracker/tracker_core_section.rs`
+  (`TryFrom<DatabaseSection>`): generation happens here — the optional user-supplied
+  `root_password` is mapped to `Password` if present, or `generate_random_password()` is
+  called if absent. This is the single point of generation for new environments.
 - `src/application/services/rendering/docker_compose.rs` (`create_mysql_contexts`):
-  replace `format!("{password}_root")` with either the user-supplied root password or a
-  freshly generated random password.
+  `root_password` parameter is now `PlainPassword` (non-optional); call site passes
+  `mysql_config.root_password().expose_secret().to_string()`. No generation logic
+  remains here.
 
 ### Bug 3 — Reserved MySQL Username `"root"` Not Rejected
 
@@ -237,24 +261,27 @@ Tasks are ordered from simplest to most complex.
 
 ### Phase 1: Reject reserved MySQL username (Bug 3)
 
-- [ ] In `MysqlConfigError` (`mysql.rs`): add `ReservedUsername` variant
-- [ ] Add `help()` arm for `ReservedUsername` with actionable fix instructions
-- [ ] In `MysqlConfig::new()`: add `if username == "root"` guard returning
+- [x] In `MysqlConfigError` (`mysql.rs`): add `ReservedUsername` variant
+- [x] Add `help()` arm for `ReservedUsername` with actionable fix instructions
+- [x] In `MysqlConfig::new()`: add `if username == "root"` guard returning
       `Err(MysqlConfigError::ReservedUsername)`
-- [ ] Add unit test `it_should_reject_root_as_username`
+- [x] Add unit test `it_should_reject_root_as_username`
 
 ### Phase 2: Make root password configurable (Bug 2)
 
-- [ ] `schemas/environment-config.json`: add optional `root_password` string to the
+- [x] `schemas/environment-config.json`: add optional `root_password` string to the
       MySQL database object
-- [ ] `MysqlConfig` (`mysql.rs`): add optional `root_password` field; update constructor
-      and accessor
-- [ ] Deserialization/config-loading path: thread the optional field through to the
-      application layer
-- [ ] `create_mysql_contexts` (`docker_compose.rs`): replace
-      `format!("{password}_root")` with user-supplied value or a randomly generated
-      password (use `rand` / `getrandom` — already in `Cargo.toml` — to produce a
-      16+ character alphanumeric string)
+- [x] `MysqlConfig` (`mysql.rs`): `root_password` is `Password` (non-optional) in the
+      domain — always has a value. `MysqlConfigRaw` uses `Option<Password>` for backward
+      compat with persisted environments lacking the field.
+- [x] `src/shared/secrets/random.rs` (new): `generate_random_password() -> Password`
+      using mixed charset (lower + upper + digit + symbol), length 32, satisfies MySQL
+      MEDIUM password policy
+- [x] `TryFrom<DatabaseSection>` (`tracker_core_section.rs`): generates root password at
+      environment creation time — not at render time — so it is stable across re-renders
+- [x] `create_mysql_contexts` (`docker_compose.rs`): replaced `format!("{password}_root")`
+      with `mysql_config.root_password().expose_secret().to_string()`; no generation
+      logic remains here
 
 ### Phase 3: Move DSN to env var override and add URL-encoding (Bug 1)
 
@@ -308,13 +335,17 @@ Tasks are ordered from simplest to most complex.
 
 **Task-Specific Criteria — Bug 2 (root password)**:
 
-- [ ] The environment configuration JSON schema accepts an optional `root_password` field
+- [x] The environment configuration JSON schema accepts an optional `root_password` field
       in the MySQL database object
-- [ ] When `root_password` is provided in the env JSON it is used as `MYSQL_ROOT_PASSWORD`
+- [x] When `root_password` is provided in the env JSON it is used as `MYSQL_ROOT_PASSWORD`
       in the rendered `.env`
-- [ ] When `root_password` is omitted, a randomly generated password is used — it is
+- [x] When `root_password` is omitted, a randomly generated password is used — it is
       **not** derived from the app password
-- [ ] `create_mysql_contexts` no longer contains `format!("{password}_root")`
+- [x] `create_mysql_contexts` no longer contains `format!("{password}_root")`
+- [x] The random password is generated once at environment creation time (not at render
+      time), ensuring stability across multiple renders
+- [x] The domain type `MysqlConfig.root_password` is always populated (`Password`,
+      non-optional)
 
 **Task-Specific Criteria — Bug 1 (DSN in tracker.toml)**:
 

schemas/environment-config.json

@@ -145,6 +145,14 @@
             "username": {
               "description": "Database username",
               "type": "string"
+            },
+            "root_password": {
+              "description": "Optional `MySQL` root password\n\nWhen provided, used as `MYSQL_ROOT_PASSWORD` in the rendered `.env` file.\nWhen absent, a cryptographically random password is generated at render time.\nNever set this to the same value as `password` in production environments.",
+              "type": [
+                "string",
+                "null"
+              ],
+              "default": null
             }
           },
           "required": [
@@ -515,4 +523,4 @@
       ]
     }
   }
-}
+}

src/application/command_handlers/create/config/builder.rs

@@ -203,6 +203,7 @@ impl EnvironmentCreationConfigBuilder {
             database_name: database_name.into(),
             username: username.into(),
             password: password.into(),
+            root_password: None,
         });
         self
     }

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

@@ -16,7 +16,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};
+use crate::shared::{generate_random_password, Password, PlainPassword};
 
 /// Database configuration section (application DTO)
 ///
@@ -67,6 +67,12 @@ pub enum DatabaseSection {
         /// 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,
+        /// Optional `MySQL` root password
+        ///
+        /// When provided, used as `MYSQL_ROOT_PASSWORD` in the rendered `.env` file.
+        /// When absent, a cryptographically random password is generated at environment creation time.
+        #[serde(default)]
+        root_password: Option<PlainPassword>,
     },
 }
 
@@ -85,13 +91,18 @@ impl TryFrom<DatabaseSection> for DatabaseConfig {
                 database_name,
                 username,
                 password,
+                root_password,
             } => {
+                let root_password = root_password
+                    .map(|p| Password::from(p.as_str()))
+                    .unwrap_or_else(generate_random_password);
                 let config = MysqlConfig::new(
                     host,
                     port,
                     database_name,
                     username,
                     Password::from(password.as_str()),
+                    root_password,
                 )?;
                 Ok(Self::Mysql(config))
             }
@@ -212,25 +223,23 @@ mod tests {
                 database_name: "tracker".to_string(),
                 username: "tracker_user".to_string(),
                 password: "secure_password".to_string(),
+                root_password: None,
             },
             private: false,
         };
 
         let config: TrackerCoreConfig = section.try_into().unwrap();
 
-        assert_eq!(
-            *config.database(),
-            DatabaseConfig::Mysql(
-                MysqlConfig::new(
-                    "localhost",
-                    3306,
-                    "tracker",
-                    "tracker_user",
-                    Password::from("secure_password"),
-                )
-                .unwrap()
-            )
-        );
+        let DatabaseConfig::Mysql(mysql) = config.database() else {
+            panic!("expected MySQL config");
+        };
+        assert_eq!(mysql.host(), "localhost");
+        assert_eq!(mysql.port(), 3306);
+        assert_eq!(mysql.database_name(), "tracker");
+        assert_eq!(mysql.username(), "tracker_user");
+        assert_eq!(mysql.password().expose_secret(), "secure_password");
+        // root_password is generated randomly — just verify it is non-empty
+        assert!(!mysql.root_password().expose_secret().is_empty());
         assert!(!config.private());
     }
 
@@ -243,6 +252,7 @@ mod tests {
                 database_name: "tracker".to_string(),
                 username: "tracker_user".to_string(),
                 password: "pass123".to_string(),
+                root_password: None,
             },
             private: false,
         };
@@ -280,6 +290,7 @@ mod tests {
                 database_name: "tracker".to_string(),
                 username: "tracker_user".to_string(),
                 password: "secure_password".to_string(),
+                root_password: None,
             }
         );
         assert!(!section.private);

src/application/services/rendering/docker_compose.rs

@@ -111,6 +111,7 @@ impl DockerComposeTemplateRenderingService {
                 mysql_config.database_name().to_string(),
                 mysql_config.username().to_string(),
                 mysql_config.password().expose_secret().to_string(),
+                mysql_config.root_password().expose_secret().to_string(),
             ),
         };
 
@@ -217,10 +218,8 @@ impl DockerComposeTemplateRenderingService {
         database_name: String,
         username: String,
         password: PlainPassword,
+        root_password: PlainPassword,
     ) -> (EnvContext, DockerComposeContextBuilder) {
-        // For MySQL, generate a secure root password (in production, this should be managed securely)
-        let root_password = format!("{password}_root");
-
         let metadata = TemplateMetadata::new(self.clock.now());
         let env_context = EnvContext::new_with_mysql(
             metadata.clone(),

src/domain/tracker/config/core/database/mod.rs

@@ -139,6 +139,7 @@ mod tests {
                 "tracker",
                 "tracker_user",
                 Password::from("secure_password"),
+                Password::from("root_pass"),
             )
             .unwrap(),
         );
@@ -156,6 +157,7 @@ mod tests {
                 "tracker",
                 "tracker_user",
                 Password::from("pass123"),
+                Password::from("root123"),
             )
             .unwrap(),
         );