feat: [#243] add debug tracing for secret access

Author: josecelano

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

@@ -36,17 +36,17 @@ Introduce wrapper types based on the `secrecy` crate's `SecretString` to replace
 **Total Active Proposals**: 10
 **Total Postponed**: 0
 **Total Discarded**: 0
-**Completed**: 9
+**Completed**: 10
 **In Progress**: 0
-**Not Started**: 1
+**Not Started**: 0
 
 ### Phase Summary
 
 - **Phase 0 - Core Setup (High Impact, Low Effort)**: ✅ 2/2 completed (100%)
 - **Phase 1 - Provider Secrets (High Impact, Medium Effort)**: ✅ 2/2 completed (100%)
 - **Phase 2 - Database Secrets (High Impact, Medium Effort)**: ✅ 2/2 completed (100%)
 - **Phase 3 - Documentation and Guidance (High Impact, Low Effort)**: ✅ 2/2 completed (100%) - ADR and AGENTS.md completed
-- **Phase 4 - Future Enhancements (Low Impact, Medium Effort)**: ✅ 2/3 completed (67%) - Proposals #9 and #10 verified
+- **Phase 4 - Future Enhancements (Low Impact, Medium Effort)**: ✅ 3/3 completed (100%) - All proposals completed
 
 ### Discarded Proposals
 
@@ -846,7 +846,7 @@ Optional improvements that can be done later if needed.
 
 ### Proposal #8: Add Debug Tracing for Secret Access
 
-**Status**: ⏳ Not Started  
+**Status**: ✅ Completed  
 **Impact**: 🟢 Low  
 **Effort**: 🔵🔵 Medium  
 **Priority**: P4  

src/shared/secrets/api_token.rs

@@ -44,8 +44,20 @@ impl ApiToken {
     /// Exposes the secret API token value.
     ///
     /// This method should be used carefully as it provides access to the sensitive data.
+    ///
+    /// # Debug Tracing
+    ///
+    /// In debug builds, this method logs the caller location to help audit secret access patterns.
+    /// No performance impact in release builds.
     #[must_use]
+    #[track_caller]
     pub fn expose_secret(&self) -> &str {
+        #[cfg(debug_assertions)]
+        tracing::trace!(
+            location = ?std::panic::Location::caller(),
+            "Secret API token exposed"
+        );
+
         self.0.expose_secret()
     }
 }
@@ -160,4 +172,14 @@ mod tests {
         let _from_str_slice = ApiToken::new("token");
         let _from_owned_string = ApiToken::new("token".to_string());
     }
+
+    #[test]
+    #[cfg(debug_assertions)]
+    fn it_should_trace_secret_exposure_in_debug_builds() {
+        // This test verifies that tracing is compiled and callable in debug builds.
+        // The actual trace output would require a tracing subscriber to capture.
+        let token = ApiToken::new("debug-token");
+        let _exposed = token.expose_secret();
+        // If this compiles and runs without panic, tracing is working
+    }
 }

src/shared/secrets/password.rs

@@ -44,8 +44,20 @@ impl Password {
     /// Exposes the secret password value.
     ///
     /// This method should be used carefully as it provides access to the sensitive data.
+    ///
+    /// # Debug Tracing
+    ///
+    /// In debug builds, this method logs the caller location to help audit secret access patterns.
+    /// No performance impact in release builds.
     #[must_use]
+    #[track_caller]
     pub fn expose_secret(&self) -> &str {
+        #[cfg(debug_assertions)]
+        tracing::trace!(
+            location = ?std::panic::Location::caller(),
+            "Secret password exposed"
+        );
+
         self.0.expose_secret()
     }
 }
@@ -160,4 +172,14 @@ mod tests {
         let _from_str_slice = Password::new("password");
         let _from_owned_string = Password::new("password".to_string());
     }
+
+    #[test]
+    #[cfg(debug_assertions)]
+    fn it_should_trace_secret_exposure_in_debug_builds() {
+        // This test verifies that tracing is compiled and callable in debug builds.
+        // The actual trace output would require a tracing subscriber to capture.
+        let password = Password::new("debug-password");
+        let _exposed = password.expose_secret();
+        // If this compiles and runs without panic, tracing is working
+    }
 }