Add Secret class

Author: RobertoPrevato

CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.7] - 2025-10-01 :fallen_leaf:
+
+- Add a `Secret` class to handle secrets in code instead of using plain `str`. This
+  approach offers several advantages:
+
+1. It encourages loading secrets from environment variables, and discourages programmers
+   from hardcoding secrets in source code.
+1. Avoids accidental exposure of secrets in logs or error messages, by overriding
+   __str__ and __repr__.
+1. It causes exception if someone tries to JSON encode it using the built-in JSON
+   module, unlike `str`.
+1. For convenience, it can be compared directly to strings. It uses constant-time
+   comparison to prevent timing attacks, with the built-in `secrets.compare_digest`.
+1. Environment variables can be changed at runtime, using this class applications can
+   pick up secret changes without needing to be restarted.
+
+- Add an `EnvironmentVariableNotFound` exception that can be used when an expected env
+  variable is not set.
+- Handle `timedelta` objects in the `FriendlyEncoder` class, by @arthurbrenno.
+- Improve the order of `if` statements in the `FriendlyEncoder` class to prioritize the
+  most frequently encountered types first, which should provide better performance in
+  typical use cases.
+
 ## [1.1.6] - 2025-03-29 :snake:
 
 - Drop Python 3.6 and Python 3.7 support.

essentials/__init__.py

@@ -1 +1 @@
-__version__ = "1.1.6"
+__version__ = "1.1.7"

essentials/decorators/logs.py

@@ -67,7 +67,6 @@ def after(name, stop_watch, function_call_id, value):
             )
 
     def log_decorator(fn):
-        nonlocal logger
         name = fn.__module__ + "." + fn.__name__
 
         if iscoroutinefunction(fn):

essentials/exceptions.py

@@ -60,3 +60,8 @@ class OperationFailedException(Exception):
 
 class SystemException(Exception):
     pass
+
+
+class EnvironmentVariableNotFound(ValueError):
+    def __init__(self, name: str) -> None:
+        super().__init__(f"Environment variable {name} not found.")

essentials/json.py

@@ -20,28 +20,38 @@ def default(self, obj: Any) -> Any:
         try:
             return json.JSONEncoder.default(self, obj)
         except TypeError:
-            if hasattr(obj, "model_dump"):
-                return obj.model_dump()
-            if hasattr(obj, "dict"):
-                return obj.dict()
-            if isinstance(obj, time):
-                return obj.strftime("%H:%M:%S")
+            # The ordering prioritizes the most frequently encountered types first,
+            # which should provide better performance in typical use cases.
+
+            # Most common datetime objects first
             if isinstance(obj, datetime):
                 return obj.isoformat()
-            if isinstance(obj, timedelta):
-                return obj.total_seconds()
             if isinstance(obj, date):
                 return obj.strftime("%Y-%m-%d")
-            if isinstance(obj, bytes):
-                return base64.urlsafe_b64encode(obj).decode("utf8")
+            if isinstance(obj, time):
+                return obj.strftime("%H:%M:%S")
+
+            # Very common built-in types
             if isinstance(obj, UUID):
                 return str(obj)
-            if isinstance(obj, Decimal):
-                return str(obj)
             if isinstance(obj, Enum):
                 return obj.value
+            if isinstance(obj, Decimal):
+                return str(obj)
+
+            # Common serializable objects
             if dataclasses.is_dataclass(obj):
-                return dataclasses.asdict(obj)  # type:ignore[arg-type]
+                return dataclasses.asdict(obj)
+            if hasattr(obj, "model_dump"):  # Pydantic v2
+                return obj.model_dump()
+            if hasattr(obj, "dict"):  # Pydantic v1 or similar
+                return obj.dict()
+
+            # Less common types
+            if isinstance(obj, timedelta):
+                return obj.total_seconds()
+            if isinstance(obj, bytes):
+                return base64.urlsafe_b64encode(obj).decode("utf8")
             raise
 
 

essentials/secrets.py

@@ -0,0 +1,113 @@
+import os
+import secrets
+
+from essentials.exceptions import EnvironmentVariableNotFound
+
+
+class Secret:
+    """
+    A type that encourages loading secrets from environment variables, and discourages
+    programmers from hardcoding secrets in source code. This also avoids accidental
+    exposure of secrets in logs or error messages, by overriding __str__ and __repr__,
+    and causes exception if someone tries to JSON encode it using the built-in
+    JSON module. For convenience, it can be compared directly to strings.
+    It uses constant-time comparison to prevent timing attacks, with
+    `secrets.compare_digest`.
+    Another benefit is that environment variables can be changed at runtime, so
+    applications can pick up secret changes without needing to be restarted.
+
+    my_secret = Secret.from_env("MY_SECRET_ENV_VAR")
+
+    >>> str(my_secret)
+    '******'
+    >>> repr(my_secret)
+    "Secret('******')"
+
+    Hardcoding secrets in source code is a security risk. See:
+
+    https://www.gitguardian.com/state-of-secrets-sprawl-report-2023
+    """
+
+    def __init__(self, value: str, *, direct_value: bool = False) -> None:
+        """
+        Create an instance of Secret.
+
+        Args:
+            value: The name of an environment variable reference (prefixed with $), or
+                   a secret if direct_value=True.
+            direct_value: Must be set to True to allow passing secrets directly
+
+        Raises:
+            ValueError: If hardcoded secret is provided without explicit permission
+        """
+        if not value.startswith("$") and not direct_value:
+            raise ValueError(
+                "Hardcoded secrets are not allowed. Either:\n"
+                "1. Use Secret.from_env('ENV_VAR_NAME') for environment variables\n"
+                "2. Use Secret('$ENV_VAR_NAME') for env var references\n"
+                "3. Set direct_value=True if you really need a hardcoded secret"
+            )
+        self._value = value
+        # Validate that we can retrieve a value
+        value = self.get_value()
+        if not isinstance(value, str) or not value:
+            raise ValueError("Secret value must be a non-empty string")
+
+    @classmethod
+    def from_env(cls, env_var: str) -> "Secret":
+        """Obtain a secret from an environment variable."""
+        return cls(f"${env_var}")
+
+    @classmethod
+    def from_plain_text(cls, value: str) -> "Secret":
+        """
+        Create a Secret from a plain text value.
+
+        This is intended for secrets that are:
+        - Generated at runtime
+        - Loaded from secure storage (databases, key vaults, etc.)
+        - Received from secure APIs
+
+        WARNING: Don't hardcode secrets in source code! This method should only
+        be used with variables containing secrets obtained from secure sources.
+
+        Args:
+            value: The secret value as plain text
+
+        Returns:
+            Secret: A new Secret instance
+        """
+        return cls(value, direct_value=True)
+
+    def get_value(self) -> str:
+        """Get the secret value."""
+        if self._value.startswith("$"):
+            env_var = self._value[1:]  # Remove $ prefix
+            value = os.getenv(env_var)
+            if value is None:
+                raise EnvironmentVariableNotFound(env_var)
+            return value
+        return self._value
+
+    def __str__(self) -> str:
+        return "******"  # Never expose the actual value
+
+    def __repr__(self) -> str:
+        # Never expose the actual value
+        # Show the source (env var name) but never the value
+        if self._value.startswith("$"):
+            env_var = self._value[1:]
+            return f"Secret.from_env('{env_var}')"
+        return "Secret('******')"  # For hardcoded secrets
+
+    def __eq__(self, other: object) -> bool:
+        # Allow comparison with strings for convenience
+        if isinstance(other, str):
+            # Using constant-time comparison to prevent timing attacks, with
+            # secrets.compare_digest.
+            return secrets.compare_digest(self.get_value(), other)
+
+        if not isinstance(other, Secret):
+            return NotImplemented
+
+        return secrets.compare_digest(self.get_value(), other.get_value())

tests/test_meta.py

@@ -46,5 +46,6 @@ def test_deprecated_async_method():
 
 
 def test_deprecated_async_method_exc():
-    with pytest.raises(DeprecatedException):
-        asyncio.run(async_dep_method2())
+    with pytest.warns(DeprecationWarning, match="`async_dep_method2` is deprecated."):
+        with pytest.raises(DeprecatedException):
+            asyncio.run(async_dep_method2())

tests/test_secrets.py

@@ -0,0 +1,139 @@
+import pytest
+from essentials.secrets import Secret
+from essentials.exceptions import EnvironmentVariableNotFound
+
+
+def test_from_env_success(monkeypatch):
+    """Test creating Secret from environment variable."""
+    monkeypatch.setenv("TEST_SECRET", "secret_value")
+    secret = Secret.from_env("TEST_SECRET")
+    assert secret.get_value() == "secret_value"
+
+
+def test_from_env_missing_raises_exception():
+    """Test that missing environment variable raises EnvironmentVariableNotFound."""
+    with pytest.raises(EnvironmentVariableNotFound):
+        Secret.from_env("NON_EXISTENT_VAR").get_value()
+
+
+def test_from_plain_text_success():
+    """Test creating Secret from plain text."""
+    secret = Secret.from_plain_text("my_secret")
+    assert secret.get_value() == "my_secret"
+
+
+def test_direct_constructor_with_env_var(monkeypatch):
+    """Test direct constructor with environment variable reference."""
+    monkeypatch.setenv("TEST_SECRET", "secret_value")
+    secret = Secret("$TEST_SECRET")
+    assert secret.get_value() == "secret_value"
+
+
+def test_direct_constructor_with_direct_value():
+    """Test direct constructor with direct_value=True."""
+    secret = Secret("hardcoded_secret", direct_value=True)
+    assert secret.get_value() == "hardcoded_secret"
+
+
+def test_hardcoded_secret_without_permission_raises_error():
+    """Test that hardcoded secrets without permission raise ValueError."""
+    with pytest.raises(ValueError, match="Hardcoded secrets are not allowed"):
+        Secret("hardcoded_secret")
+
+
+def test_empty_secret_raises_error(monkeypatch):
+    """Test that empty secret values raise ValueError."""
+    monkeypatch.setenv("EMPTY_SECRET", "")
+    with pytest.raises(ValueError, match="Secret value must be a non-empty string"):
+        Secret.from_env("EMPTY_SECRET")
+
+
+def test_str_representation_hides_value(monkeypatch):
+    """Test that __str__ never exposes the actual value."""
+    monkeypatch.setenv("TEST_SECRET", "secret_value")
+    secret = Secret.from_env("TEST_SECRET")
+    assert str(secret) == "******"
+
+
+def test_repr_shows_env_var_name(monkeypatch):
+    """Test that __repr__ shows environment variable name but not value."""
+    monkeypatch.setenv("TEST_SECRET", "secret_value")
+    secret = Secret.from_env("TEST_SECRET")
+    assert repr(secret) == "Secret.from_env('TEST_SECRET')"
+
+
+def test_repr_hides_hardcoded_value():
+    """Test that __repr__ hides hardcoded secret values."""
+    secret = Secret.from_plain_text("secret")
+    assert repr(secret) == "Secret('******')"
+
+
+def test_equality_with_string(monkeypatch):
+    """Test that Secret can be compared with strings."""
+    monkeypatch.setenv("TEST_SECRET", "secret_value")
+    secret = Secret.from_env("TEST_SECRET")
+    assert secret == "secret_value"
+    assert secret != "wrong_value"
+
+
+def test_equality_with_another_secret(monkeypatch):
+    """Test that Secrets can be compared with each other."""
+    monkeypatch.setenv("SECRET1", "same_value")
+    monkeypatch.setenv("SECRET2", "same_value")
+    monkeypatch.setenv("SECRET3", "different_value")
+
+    secret1 = Secret.from_env("SECRET1")
+    secret2 = Secret.from_env("SECRET2")
+    secret3 = Secret.from_env("SECRET3")
+
+    assert secret1 == secret2
+    assert secret1 != secret3
+
+
+def test_equality_with_incompatible_type(monkeypatch):
+    """Test that comparison with incompatible types returns NotImplemented."""
+    monkeypatch.setenv("TEST_SECRET", "secret_value")
+    secret = Secret.from_env("TEST_SECRET")
+    assert secret.__eq__(123) == NotImplemented
+    assert secret != 123
+
+
+def test_mixed_secret_sources_comparison(monkeypatch):
+    """Test comparing secrets from different sources."""
+    monkeypatch.setenv("ENV_SECRET", "same_value")
+    env_secret = Secret.from_env("ENV_SECRET")
+    plain_secret = Secret.from_plain_text("same_value")
+
+    assert env_secret == plain_secret
+
+
+def test_get_value_called_multiple_times(monkeypatch):
+    """Test that get_value works consistently across multiple calls."""
+    monkeypatch.setenv("TEST_SECRET", "secret_value")
+    secret = Secret.from_env("TEST_SECRET")
+
+    assert secret.get_value() == "secret_value"
+    assert secret.get_value() == "secret_value"
+
+
+def test_env_var_change_at_runtime(monkeypatch):
+    """Test that Secret picks up environment variable changes."""
+    monkeypatch.setenv("DYNAMIC_SECRET", "initial_value")
+    secret = Secret.from_env("DYNAMIC_SECRET")
+    assert secret.get_value() == "initial_value"
+
+    monkeypatch.setenv("DYNAMIC_SECRET", "changed_value")
+    assert secret.get_value() == "changed_value"
+
+
+def test_constructor_validation_with_empty_env_var(monkeypatch):
+    """Test constructor validation when env var exists but is empty."""
+    monkeypatch.setenv("EMPTY_VAR", "")
+    with pytest.raises(ValueError, match="Secret value must be a non-empty string"):
+        Secret("$EMPTY_VAR")
+
+
+def test_from_plain_text_with_empty_string():
+    """Test that from_plain_text with empty string raises ValueError."""
+    with pytest.raises(ValueError, match="Secret value must be a non-empty string"):
+        Secret.from_plain_text("")