Fix code scanning alert: Clear-text logging of sensitive information (#27)

Address security issue identified in:
https://github.com/jpstroop/fitbit-client-python/security/code-scanning/8

- Add docs/SECURITY.md with comprehensive guidance on debug mode security
- Add explicit security warnings to debug output in _base.py
- Update docstrings in debug-related methods to highlight security risks

Debug mode intentionally includes OAuth tokens for troubleshooting, but
now includes proper documentation and warnings about secure usage.

Author: jpstroop

docs/DEVELOPMENT.md

@@ -195,9 +195,14 @@ All resource mocks are in the root [conftest.py](tests/conftest.py).
 
 ### Response Mocking
 
+<<<<<<< Updated upstream
 The test suite uses the `mock_response_factory` fixture from `tests/conftest.py`
 to create consistent, configurable mock responses. This is the required pattern
 for all tests that need to mock HTTP responses.
+=======
+The test suite uses the `mock_response_factory` fixture from `tests/conftest.py` to create consistent,
+configurable mock responses. This is the required pattern for all tests that need to mock HTTP responses.
+>>>>>>> Stashed changes
 
 #### Standard Mock Response Pattern
 
@@ -253,9 +258,14 @@ mock_response.text = "<xml>content</xml>"
 
 #### Parameter Validation Pattern
 
+<<<<<<< Updated upstream
 For tests that only need to verify parameter validation or endpoint construction
 (not response handling), it's acceptable to use the following alternative
 pattern:
+=======
+For tests that only need to verify parameter validation or endpoint construction (not response handling),
+it's acceptable to use the following alternative pattern:
+>>>>>>> Stashed changes
 
 ```python
 def test_validation(resource):
@@ -268,8 +278,12 @@ def test_validation(resource):
 ```
 
 This approach provides a clean, standardized way to create mock responses with
+<<<<<<< Updated upstream
 the desired status code, data, and headers. All test files must use one of these
 patterns.
+=======
+the desired status code, data, and headers. All test files must use one of these patterns.
+>>>>>>> Stashed changes
 
 ## OAuth Callback Implementation
 

docs/SECURITY.md

@@ -0,0 +1,45 @@
+# Security Considerations
+
+## Debug Mode Security Considerations and Warning
+
+This library includes a debug mode feature that generates complete cURL commands
+for troubleshooting API requests. This feature is designed to help during
+development and debugging only.
+
+When you enable debug mode by setting `debug=True` in any API method call:
+
+```python
+# This will print a complete curl command to stdout
+client.get_profile(debug=True)
+```
+
+The generated cURL command includes:
+
+- The full API endpoint URL
+- All request parameters and data
+- The OAuth bearer token used for authentication
+
+**WARNING: This exposes sensitive authentication credentials that could allow
+API access as the authenticated user.**
+
+1. **NEVER use debug mode in production environments**
+2. **NEVER log debug mode output to persistent storage**
+3. **NEVER share debug mode output without removing the authorization token**
+4. **NEVER commit debug mode output to version control**
+
+## General Security Considerations
+
+### OAuth Token Management
+
+- Store OAuth tokens securely, preferably in an encrypted format
+- Implement token rotation and refresh mechanisms properly
+- Never hard-code tokens in application code
+- Use environment variables or secure configuration management for client IDs
+  and secrets
+
+### Production Deployment
+
+- Ensure token refresh callbacks use HTTPS
+- Validate that your callback URL is properly secured
+- Follow OAuth 2.0 best practices for authentication flows
+- Set appropriate token expiration times

fitbit_client/resources/_base.py

@@ -1,11 +1,13 @@
 # fitbit_client/resources/_base.py
 
+
 # Standard library imports
 from datetime import datetime
 from inspect import currentframe
 from json import JSONDecodeError
 from json import dumps
 from logging import getLogger
+import re
 from time import sleep
 from typing import Dict
 from typing import Optional
@@ -480,7 +482,8 @@ def _make_request(
             requires_user_id: Whether the endpoint requires user_id in the path
             http_method: HTTP method to use (GET, POST, DELETE)
             api_version: API version to use (default: "1")
-            debug: If True, prints a curl command to stdout to help with debugging
+            debug: If True, prints a curl command to stdout to help with debugging.
+                 WARNING: This exposes authentication tokens! See docs/SECURITY.md for guidance.
 
         Returns:
             JSONType: The API response in one of these formats:
@@ -516,7 +519,9 @@ def _make_request(
 
         if debug:
             curl_command = self._build_curl_command(url, http_method, data, json, params)
-            print(f"\n# Debug curl command for {calling_method}:")
+            print(f"\n# DEBUG MODE: Security Warning - contains authentication tokens!")
+            print(f"# See docs/SECURITY.md for guidance on sharing this output safely.")
+            print(f"# Debug curl command for {calling_method}:")
             print(curl_command)
             print()
             return None
@@ -628,7 +633,8 @@ def _make_direct_request(self, path: str, debug: bool = False) -> JSONType:
 
         Args:
             path: Full relative API path including query string (e.g., '/1/user/-/sleep/list.json?offset=10&limit=10')
-            debug: If True, prints a curl command to stdout to help with debugging
+            debug: If True, prints a curl command to stdout to help with debugging.
+                 WARNING: This exposes authentication tokens! See docs/SECURITY.md for guidance.
 
         Returns:
             JSONDict: The API response as a dictionary
@@ -641,7 +647,9 @@ def _make_direct_request(self, path: str, debug: bool = False) -> JSONType:
 
         if debug:
             curl_command = self._build_curl_command(url, "GET")
-            print(f"\n# Debug curl command for {calling_method} (pagination):")
+            print(f"\n# DEBUG MODE: Security Warning - contains authentication tokens!")
+            print(f"# See docs/SECURITY.md for guidance on sharing this output safely.")
+            print(f"# Debug curl command for {calling_method} (pagination):")
             print(curl_command)
             print()
             return {}

fitbit_client/utils/curl_debug_mixin.py

@@ -37,6 +37,10 @@ def _build_curl_command(
         """
         Build a curl command string for debugging API requests.
         
+        WARNING: Security Risk - The generated command includes the actual OAuth bearer token,
+        which should never be logged, shared, or committed to version control.
+        See docs/SECURITY.md for guidance on securely using this feature.
+        
         Args:
             url: Full API URL
             http_method: HTTP method (GET, POST, DELETE)
@@ -49,7 +53,7 @@ def _build_curl_command(
 
         The generated command includes:
         - The HTTP method (for non-GET requests)
-        - Authorization header with OAuth token
+        - Authorization header with OAuth token (SENSITIVE INFORMATION)
         - Request body (if data or json is provided)
         - Query parameters (if provided)
         

tests/fitbit_client/resources/test_base.py

@@ -299,9 +299,13 @@ def test_handle_json_response_with_invalid_json(base_resource, mock_logger):
 def test_make_request_json_success(base_resource, mock_oauth_session, mock_response_factory):
     """Test successful JSON request"""
     expected_data = {"success": True}
+<<<<<<< Updated upstream
     mock_response = mock_response_factory(
         200, expected_data, headers={"content-type": "application/json"}
     )
+=======
+    mock_response = mock_response_factory(200, expected_data, headers={"content-type": "application/json"})
+>>>>>>> Stashed changes
     mock_oauth_session.request.return_value = mock_response
 
     result = base_resource._make_request("test/endpoint")
@@ -320,9 +324,15 @@ def test_make_request_no_content(base_resource, mock_oauth_session, mock_respons
 def test_make_request_xml_response(base_resource, mock_oauth_session, mock_response_factory):
     """Test XML response handling"""
     mock_response = mock_response_factory(
+<<<<<<< Updated upstream
         200,
         headers={"content-type": "application/vnd.garmin.tcx+xml"},
         content_type="application/vnd.garmin.tcx+xml",
+=======
+        200, 
+        headers={"content-type": "application/vnd.garmin.tcx+xml"},
+        content_type="application/vnd.garmin.tcx+xml"
+>>>>>>> Stashed changes
     )
     mock_response.text = "<test>data</test>"
     mock_oauth_session.request.return_value = mock_response
@@ -331,12 +341,21 @@ def test_make_request_xml_response(base_resource, mock_oauth_session, mock_respo
     assert result == "<test>data</test>"
 
 
+<<<<<<< Updated upstream
 def test_make_request_unexpected_content_type(
     base_resource, mock_oauth_session, mock_response_factory
 ):
     """Test handling of unexpected content type"""
     mock_response = mock_response_factory(
         200, headers={"content-type": "text/plain"}, content_type="text/plain"
+=======
+def test_make_request_unexpected_content_type(base_resource, mock_oauth_session, mock_response_factory):
+    """Test handling of unexpected content type"""
+    mock_response = mock_response_factory(
+        200, 
+        headers={"content-type": "text/plain"},
+        content_type="text/plain"
+>>>>>>> Stashed changes
     )
     mock_response.text = "some data"
     mock_oauth_session.request.return_value = mock_response
@@ -619,8 +638,14 @@ def test_make_direct_request_with_debug(mock_build_curl, mock_print, base_resour
         # Verify the curl command was built correctly
         mock_build_curl.assert_called_once_with("https://api.fitbit.com/test", "GET")
 
-        # Verify print was called with the right message pattern
-        mock_print.assert_any_call("\n# Debug curl command for test_pagination (pagination):")
+        # Verify security warning messages were printed
+        mock_print.assert_any_call(
+            "\n# DEBUG MODE: Security Warning - contains authentication tokens!"
+        )
+        mock_print.assert_any_call(
+            "# See docs/SECURITY.md for guidance on sharing this output safely."
+        )
+        mock_print.assert_any_call("# Debug curl command for test_pagination (pagination):")
 
 
 @patch("fitbit_client.resources._base.BaseResource._handle_json_response")