dotenvmodel 0.3.0__tar.gz → 0.3.1__tar.gz

{dotenvmodel-0.3.0 → dotenvmodel-0.3.1}/.github/workflows/ci.yml

@@ -133,7 +133,7 @@ jobs:
           cd /tmp && $GITHUB_WORKSPACE/test-src-env/bin/python -c "import dotenvmodel; print(dotenvmodel.__version__)"
 
       - name: Upload build artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/

dotenvmodel-0.3.1/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.3.1"
+}

{dotenvmodel-0.3.0 → dotenvmodel-0.3.1}/CHANGELOG.md

@@ -5,6 +5,13 @@ 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).
 
+## [0.3.1](https://github.com/AZX-PBC-OSS/dotenvmodel/compare/v0.3.0...v0.3.1) (2026-07-13)
+
+
+### Bug Fixes
+
+* redact credentials in DSN repr, errors, docs, and secret exception chains ([#29](https://github.com/AZX-PBC-OSS/dotenvmodel/issues/29)) ([cfdd218](https://github.com/AZX-PBC-OSS/dotenvmodel/commit/cfdd218ff157d41f7af06c1beaf4c539080fa2dd))
+
 ## [0.3.0](https://github.com/AZX-PBC-OSS/dotenvmodel/compare/v0.2.0...v0.3.0) (2026-07-09)
 
 

{dotenvmodel-0.3.0 → dotenvmodel-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotenvmodel
-Version: 0.3.0
+Version: 0.3.1
 Summary: Type-safe environment configuration with automatic .env file loading
 Project-URL: Homepage, https://github.com/AZX-PBC-OSS/dotenvmodel
 Project-URL: Repository, https://github.com/AZX-PBC-OSS/dotenvmodel

{dotenvmodel-0.3.0 → dotenvmodel-0.3.1}/dotenvmodel/__init__.py

@@ -31,7 +31,7 @@ Public API:
       Exception hierarchy
 """
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"
 __author__ = "AZX, PBC."
 __email__ = "oss@azx.io"
 __license__ = "MIT"

dotenvmodel-0.3.1/dotenvmodel/_redaction.py

@@ -0,0 +1,260 @@
+"""Credential-redaction helpers shared across display paths.
+
+Kept dependency-free (stdlib only) so both ``exceptions`` and ``types`` can
+import it without creating an import cycle.
+
+Masking philosophy — deliberately asymmetric. These helpers run only on
+error/describe/``repr`` display paths, where over-masking a benign value
+(``sort_key=name`` shown as ``sort_key=***``) costs a little debug context,
+while under-masking leaks a credential. So the classifier keeps NO benign
+carve-out lists: any key with a secret-word token is masked, and the word
+list is the single place to maintain.
+
+Known, documented non-goals (use ``SecretStr`` for these):
+- secrets embedded in a URL *path* segment (Slack webhooks, ``/bot<token>/``);
+- plain non-URL secret values and secrets inside containers/JSON bodies;
+- ``user:pw@host`` shapes buried mid-string (only a leading one is masked).
+"""
+
+import re
+from urllib.parse import unquote_plus, urlparse
+
+__all__ = ["redact_url_password"]
+
+_MASK = "***"
+
+# A key is sensitive when ANY of its separator/camelCase tokens is one of
+# these words, or the separator-stripped whole key matches (``session_id`` ->
+# ``sessionid``, ``connection_string`` -> ``connectionstring``). Exact token
+# equality keeps lookalikes benign: ``keyword``/``monkey``/``authors``/
+# ``oauth``/``bypass``/``passwordless`` never match.
+_SECRET_WORDS = frozenset(
+    {
+        "password",
+        "passwd",
+        "pwd",
+        "pass",
+        "passphrase",
+        "passcode",
+        "secret",
+        "credential",
+        "credentials",
+        "apikey",
+        "key",
+        "token",
+        "auth",
+        "authorization",
+        "assertion",
+        "signature",
+        "sig",
+        "hmac",
+        "jwt",
+        "bearer",
+        "sessionid",
+        "jsessionid",
+        "phpsessid",
+        "sid",
+        "session",
+        "otp",
+        "totp",
+        "sas",
+        "saml",
+        "verifier",
+        "challenge",
+        "pin",
+        "cvv",
+        "cvc",
+        "pat",
+        "license",
+        "dsn",
+        "connectionstring",
+        "connstr",
+    }
+)
+
+# Credential only as the ENTIRE key: OAuth's bare ``?code=`` masks, while
+# ``status_code``/``error_code`` (debug-critical) stay visible.
+_SECRET_WHOLE_ONLY = frozenset({"code"})
+
+# Glued (separator-less) suffixes, e.g. ``sslpassword`` / ``xapikey``.
+_SECRET_SUFFIXES = (
+    "password",
+    "passphrase",
+    "passcode",
+    "signature",
+    "apikey",
+    "connectionstring",
+    "connstr",
+)
+
+# Prefixes that make a glued (separator-less) ``*key``/``*token``/``*secret``
+# compound a credential: ``secretkey``, ``accesstoken``, ``clientsecret``.
+_CREDENTIAL_PREFIXES = frozenset(
+    {
+        "secret",
+        "access",
+        "private",
+        "api",
+        "client",
+        "signing",
+        "encryption",
+        "refresh",
+        "session",
+        "shared",
+        "master",
+        "auth",
+        "bearer",
+        "consumer",
+        "sas",
+        "ssl",
+        "account",
+        "storage",
+    }
+)
+
+# Split camelCase and ACRONYMBoundaries (HMACKey -> HMAC, Key).
+_CAMEL = re.compile(r"(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])")
+_SEPARATORS = re.compile(r"[-_.]+")
+# Fallback for unparseable URLs: mask the userinfo password (scheme://user:PW@).
+# The password class allows '@'/':' and backtracks to the last '@' before the
+# path, so an unescaped '@' in the password is still fully masked.
+_USERINFO_PW = re.compile(r"(://[^:/?#@\s]*:)[^/?#\s]+(@)")
+# Scheme-less userinfo (the forgot-the-scheme typo: ``dbuser:pw@host/db``).
+# urlparse reads ``dbuser`` as the scheme there, so the netloc path never
+# fires; anchored at the start so prose with colons is left alone.
+_SCHEMELESS_PW = re.compile(r"^([^:/?#@\s]+:)[^/?#\s]+(@)(?=[^/?#\s@]*[/:])")
+
+
+def _is_sensitive_key(key: str) -> bool:
+    """True if a query/fragment/params key names a credential.
+
+    Any secret-word token masks (``access_token``, ``db_pass``,
+    ``api_key_v2beta`` — the qualifier tokens don't hide the match), plus a
+    stripped-whole-key check for separator-spanning words and a suffix/prefix
+    check for glued forms like ``sslpassword``/``secretkey``. No benign
+    carve-outs: ``sort_key``/``page_token`` mask too, by design (see module
+    docstring).
+    """
+    raw = unquote_plus(key).strip()
+    if not raw:
+        return False
+
+    k = _CAMEL.sub("_", raw).lower()
+    tokens = [t for t in _SEPARATORS.split(k) if t]
+    if not tokens:
+        return False
+    stripped = "".join(tokens)
+
+    if stripped in _SECRET_WHOLE_ONLY:
+        return True
+    # A secret-word token (or its plural: passwords/tokens/keys).
+    if any(t in _SECRET_WORDS or (t.endswith("s") and t[:-1] in _SECRET_WORDS) for t in tokens):
+        return True
+    # A secret word spanning separators (session_id -> sessionid).
+    if stripped in _SECRET_WORDS:
+        return True
+    if _is_glued_credential(stripped):
+        return True
+    return any(stripped.endswith(sfx) for sfx in _SECRET_SUFFIXES)
+
+
+def _is_glued_credential(stripped: str) -> bool:
+    """True for separator-less compounds like ``secretkey`` / ``accesstoken``."""
+    for suffix in ("key", "token", "secret", "password"):
+        if stripped.endswith(suffix) and len(stripped) > len(suffix):
+            prefix = stripped[: -len(suffix)]
+            # ``secretaccesskey`` -> prefix ``secretaccess`` starts with ``secret``.
+            if any(prefix.startswith(p) for p in _CREDENTIAL_PREFIXES):
+                return True
+    return False
+
+
+def _redact_pairs(component: str) -> tuple[str, bool]:
+    """Mask sensitive values in an ``&``-separated key=value string.
+
+    Per the WHATWG URL standard, ``&`` is the only separator; a ``;`` is data
+    and stays inside its value. A sensitive key masks its whole value
+    (including any ``;`` tail). Defensively, a legacy ``;``-glued sub-pair
+    inside a *benign* key's value (``db=0;password=x``) is also masked, pair
+    by pair. Non-sensitive pairs are preserved byte-for-byte. Returns the
+    (possibly rewritten) component and whether anything changed.
+    """
+    changed = False
+    parts = component.split("&")
+    for i, part in enumerate(parts):
+        key, sep, value = part.partition("=")
+        if sep and value and _is_sensitive_key(key):
+            parts[i] = f"{key}={_MASK}"
+            changed = True
+            continue
+        if ";" in part:
+            subs = part.split(";")
+            sub_changed = False
+            for j, sub in enumerate(subs):
+                skey, ssep, svalue = sub.partition("=")
+                if ssep and svalue and _is_sensitive_key(skey):
+                    subs[j] = f"{skey}={_MASK}"
+                    sub_changed = True
+            if sub_changed:
+                parts[i] = ";".join(subs)
+                changed = True
+    return ("&".join(parts), changed) if changed else (component, False)
+
+
+def redact_url_password(value: str) -> str:
+    """Return ``value`` with any URL credential replaced by ``***``.
+
+    Masks the userinfo password (``user:pass@host`` -> ``user:***@host``,
+    including the scheme-less typo form ``user:pass@host`` with no ``//``)
+    and the value of any sensitive key in the query string, fragment, or
+    ``;``-params component (e.g. ``?password=`` / ``#access_token=`` /
+    ``/path;password=``). Host, port, and non-sensitive parameters are
+    preserved verbatim. A string without any credential-shaped part is
+    returned unchanged, so this is safe to call on arbitrary values.
+    """
+    # Scheme-less userinfo: urlparse would read the username as the scheme, so
+    # mask a leading `user:pw@host/…` up front (anchored + a path/port lookahead
+    # so `https://…` and email-shaped `cc:john@example.com` are left alone). Done
+    # unconditionally so a later `://` (e.g. in a redirect param) can't skip it.
+    prefix_masked = _SCHEMELESS_PW.sub(rf"\1{_MASK}\2", value)
+
+    try:
+        parsed = urlparse(prefix_masked)
+    except ValueError:
+        # Malformed URL (e.g. bad IPv6). urlparse can't help, but neither the
+        # userinfo password nor a query/fragment secret may leak, so mask the
+        # userinfo by regex and redact the (splittable) query and fragment.
+        masked = _USERINFO_PW.sub(rf"\1{_MASK}\2", prefix_masked)
+        head, hsep, frag = masked.partition("#")
+        head, qsep, query = head.partition("?")
+        head, psep, params = head.partition(";")
+        if psep:
+            params = _redact_pairs(params)[0]
+        if qsep:
+            query = _redact_pairs(query)[0]
+        if hsep:
+            frag = _redact_pairs(frag)[0]
+        return head + psep + params + qsep + query + hsep + frag
+
+    netloc = parsed.netloc
+    changed = prefix_masked != value
+
+    if parsed.password:
+        userinfo, _, hostpart = netloc.rpartition("@")
+        username = userinfo.partition(":")[0]
+        netloc = f"{username}:{_MASK}@{hostpart}"
+        changed = True
+
+    params, params_changed = (
+        _redact_pairs(parsed.params) if parsed.params else (parsed.params, False)
+    )
+    query, query_changed = _redact_pairs(parsed.query) if parsed.query else (parsed.query, False)
+    fragment, frag_changed = (
+        _redact_pairs(parsed.fragment) if parsed.fragment else (parsed.fragment, False)
+    )
+    changed = changed or params_changed or query_changed or frag_changed
+
+    if not changed:
+        return value
+
+    return parsed._replace(netloc=netloc, params=params, query=query, fragment=fragment).geturl()

{dotenvmodel-0.3.0 → dotenvmodel-0.3.1}/dotenvmodel/describe/formatters.py

@@ -13,8 +13,9 @@ from typing import Any, Union, get_args, get_origin
 
 from typing_extensions import TypeForm
 
+from dotenvmodel._redaction import redact_url_password
 from dotenvmodel.fields import _MISSING, FieldInfo
-from dotenvmodel.types import SecretStr
+from dotenvmodel.types import BaseDsn, SecretStr
 
 # Maximum column widths to prevent unbounded table growth
 MAX_WIDTHS = {
@@ -317,6 +318,23 @@ def format_constraints(
     return ", ".join(constraints) if constraints else "-"
 
 
+def _union_members(field_type: TypeForm[Any]) -> list[Any]:
+    """Return the non-None members of an Optional/Union, else ``[field_type]``.
+
+    Handles multi-member unions (``PostgresDsn | RedisDsn | None``) so a DSN or
+    SecretStr anywhere in the union is still recognised for redaction.
+    """
+    origin = get_origin(field_type)
+    if origin is types.UnionType or origin is Union:
+        return [a for a in get_args(field_type) if a is not type(None)]
+    return [field_type]
+
+
+def _is_type_in_union(field_type: TypeForm[Any], target: type) -> bool:
+    """True if any member of ``field_type`` is a subclass of ``target``."""
+    return any(isinstance(m, type) and issubclass(m, target) for m in _union_members(field_type))
+
+
 def format_default(field_info: FieldInfo, field_type: TypeForm[Any], truncate: bool = True) -> str:
     """Format default value for display."""
     if field_info.default is _MISSING and field_info.default_factory is None:
@@ -340,9 +358,15 @@ def format_default(field_info: FieldInfo, field_type: TypeForm[Any], truncate: b
     if isinstance(default, Enum):
         return str(default.value)
 
-    if isinstance(field_type, type) and issubclass(field_type, SecretStr):
+    # Recognise DSN/SecretStr even inside an Optional/multi-member Union
+    # (e.g. `PostgresDsn | RedisDsn | None`) so nested defaults are redacted.
+    if _is_type_in_union(field_type, SecretStr):
         return "<secret>"
 
+    # DSN defaults may embed credentials; redact the password before display.
+    if _is_type_in_union(field_type, BaseDsn) and isinstance(default, str):
+        return f'"{redact_url_password(str.__str__(default))}"'
+
     if isinstance(default, str):
         if truncate and len(default) > TRUNCATE_THRESHOLD_SHORT:
             return f'"{default[: TRUNCATE_THRESHOLD_SHORT - 3]}..."'

{dotenvmodel-0.3.0 → dotenvmodel-0.3.1}/dotenvmodel/exceptions.py

@@ -4,6 +4,15 @@ from typing import Any
 
 from typing_extensions import TypeForm
 
+from dotenvmodel._redaction import redact_url_password
+
+
+def _value_repr(value: Any) -> str:
+    """Repr a field value for error messages, redacting URL passwords."""
+    if isinstance(value, str):
+        return repr(redact_url_password(str.__str__(value)))
+    return repr(value)
+
 
 class DotEnvModelError(Exception):
     """Base exception for all dotenvmodel errors.
@@ -83,7 +92,7 @@ class ValidationError(DotEnvModelError):
     def _format_message(self) -> str:
         """Format a detailed error message."""
         msg = f"Field '{self.field_name}' validation failed:\n"
-        msg += f"  Value: {self.value!r}\n"
+        msg += f"  Value: {_value_repr(self.value)}\n"
         if self.field_type:
             type_name = getattr(self.field_type, "__name__", str(self.field_type))
             msg += f"  Expected type: {type_name}\n"
@@ -182,7 +191,7 @@ class TypeCoercionError(ValidationError):
         if self.field_type:
             type_name = getattr(self.field_type, "__name__", str(self.field_type))
         msg = f"TypeCoercionError: Failed to coerce field '{self.field_name}' to type {type_name}.\n\n"
-        msg += f"Value: {self.value!r}\n"
+        msg += f"Value: {_value_repr(self.value)}\n"
         msg += f"Environment variable: {self.env_var_name}\n"
         msg += f"Error: {self.error_msg}\n"
         msg += f"Hint: Ensure {self.env_var_name} contains a valid {type_name}"
@@ -239,7 +248,7 @@ class ConstraintViolationError(ValidationError):
     def _format_message(self) -> str:
         """Format a detailed error message for constraint violations."""
         msg = f"ConstraintViolationError: Field '{self.field_name}' violates constraint.\n\n"
-        msg += f"Value: {self.value!r}\n"
+        msg += f"Value: {_value_repr(self.value)}\n"
         msg += f"Constraint: {self.constraint}\n"
         msg += f"Error: {self.error_msg}\n"
         msg += f"Hint: Set {self.env_var_name} to a value that satisfies the constraint"
@@ -284,7 +293,7 @@ class MultipleValidationErrors(DotEnvModelError):
             msg += f"{i}. {error.__class__.__name__}: {error.error_msg}\n"
             msg += f"   Field: {error.field_name}\n"
             if error.value is not None:
-                msg += f"   Value: {error.value!r}\n"
+                msg += f"   Value: {_value_repr(error.value)}\n"
             msg += f"   Environment variable: {error.env_var_name}\n"
             if hasattr(error, "constraint") and error.constraint is not None:  # type: ignore[attr-defined]
                 msg += f"   Constraint: {error.constraint}\n"  # type: ignore[attr-defined]

{dotenvmodel-0.3.0 → dotenvmodel-0.3.1}/dotenvmodel/types.py

@@ -8,6 +8,7 @@ from typing import TYPE_CHECKING, TypeVar
 from urllib.parse import ParseResult, unquote, urlparse
 from uuid import UUID
 
+from dotenvmodel._redaction import redact_url_password
 from dotenvmodel.exceptions import TypeCoercionError
 
 _T = TypeVar("_T")
@@ -146,6 +147,19 @@ class BaseDsn(str):
 
         return str.__new__(cls, value)
 
+    def __repr__(self) -> str:
+        """Return a redacted ``repr`` with any password masked.
+
+        Only ``repr`` is overridden. ``str(dsn)`` and the raw buffer remain the
+        real connection string so the DSN stays usable with database drivers
+        (``create_engine(str(url))``, ``redis.from_url(str(url))``, etc.). This
+        masks the accidental-display path (``repr(config)``, debuggers, ``%r``
+        logging) without breaking functionality. Values that must never appear
+        in serialized output (``json.dumps``, ``.encode()``) should use
+        ``SecretStr`` instead.
+        """
+        return repr(redact_url_password(str.__str__(self)))
+
     @property
     def parsed(self) -> ParseResult:
         """Get the parsed URL components."""

{dotenvmodel-0.3.0 → dotenvmodel-0.3.1}/dotenvmodel/validation.py

@@ -49,16 +49,16 @@ def validate_field(field_name: str, value: Any, field_info: FieldInfo, env_var_n
     if isinstance(value, str):
         _validate_string(field_name, value, field_info, env_var_name)
     elif isinstance(value, SecretStr):
-        try:
-            _validate_string(field_name, value.get_secret_value(), field_info, env_var_name)
-        except ConstraintViolationError as e:
-            raise ConstraintViolationError(
-                field_name=e.field_name,
-                value=value,
-                constraint=e.constraint,
-                error_msg=e.error_msg,
-                env_var_name=e.env_var_name,
-            ) from e
+        # Check the plaintext for length/regex, but report the masked SecretStr.
+        # No plaintext-bearing exception is ever constructed, so nothing can
+        # leak via the exception chain (__cause__/__context__).
+        _validate_string(
+            field_name,
+            value.get_secret_value(),
+            field_info,
+            env_var_name,
+            report_value=value,
+        )
 
     # Choice validation (works for any type)
     if field_info.choices is not None:
@@ -114,12 +114,25 @@ def _validate_numeric(
         )
 
 
-def _validate_string(field_name: str, value: str, field_info: FieldInfo, env_var_name: str) -> None:
-    """Validate string constraints (min_length, max_length, regex)."""
+def _validate_string(
+    field_name: str,
+    value: str,
+    field_info: FieldInfo,
+    env_var_name: str,
+    report_value: object | None = None,
+) -> None:
+    """Validate string constraints (min_length, max_length, regex).
+
+    ``value`` is the plaintext used for the checks; ``report_value`` (when given,
+    e.g. the masking ``SecretStr`` wrapper) is what appears in any raised error,
+    so the plaintext never enters an exception.
+    """
+    reported = value if report_value is None else report_value
+
     if field_info.min_length is not None and len(value) < field_info.min_length:
         raise ConstraintViolationError(
             field_name=field_name,
-            value=value,
+            value=reported,
             constraint=f"min_length={field_info.min_length}",
             error_msg=f"String must be at least {field_info.min_length} characters long",
             env_var_name=env_var_name,
@@ -128,7 +141,7 @@ def _validate_string(field_name: str, value: str, field_info: FieldInfo, env_var
     if field_info.max_length is not None and len(value) > field_info.max_length:
         raise ConstraintViolationError(
             field_name=field_name,
-            value=value,
+            value=reported,
             constraint=f"max_length={field_info.max_length}",
             error_msg=f"String must be at most {field_info.max_length} characters long",
             env_var_name=env_var_name,
@@ -141,7 +154,7 @@ def _validate_string(field_name: str, value: str, field_info: FieldInfo, env_var
     ):
         raise ConstraintViolationError(
             field_name=field_name,
-            value=value,
+            value=reported,
             constraint=f"regex={field_info.regex!r}",
             error_msg=f"String must match pattern: {field_info.regex}",
             env_var_name=env_var_name,

{dotenvmodel-0.3.0 → dotenvmodel-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dotenvmodel"
-version = "0.3.0"
+version = "0.3.1"
 description = "Type-safe environment configuration with automatic .env file loading"
 readme = "README.md"
 requires-python = ">=3.12"