omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/utils/util_datetime.py

@@ -0,0 +1,372 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Datetime validation and normalization utilities.
+
+This module provides utilities for ensuring datetime values are timezone-aware
+before persisting to databases. Naive datetimes (without timezone info) can cause
+subtle bugs when stored in PostgreSQL's TIMESTAMPTZ columns or when compared
+across different timezones.
+
+ONEX Datetime Guidelines:
+    - All datetimes should be timezone-aware (preferably UTC)
+    - Naive datetimes trigger warnings and are auto-converted to UTC
+    - Use datetime.now(UTC) instead of datetime.utcnow() (deprecated in Python 3.12+)
+
+See Also:
+    - PostgreSQL TIMESTAMPTZ documentation
+    - Python datetime best practices (PEP 495)
+    - ONEX infrastructure datetime conventions
+
+Example:
+    >>> from datetime import datetime, UTC
+    >>> from omnibase_infra.utils import ensure_timezone_aware
+    >>>
+    >>> # Aware datetime passes through unchanged
+    >>> aware_dt = datetime.now(UTC)
+    >>> result = ensure_timezone_aware(aware_dt)
+    >>> result == aware_dt
+    True
+    >>>
+    >>> # Naive datetime is converted to UTC with warning
+    >>> naive_dt = datetime(2025, 1, 15, 12, 0, 0)
+    >>> result = ensure_timezone_aware(naive_dt)  # Logs warning
+    >>> result.tzinfo is not None
+    True
+
+.. versionadded:: 0.8.0
+    Created as part of PR #146 datetime validation improvements.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+from uuid import UUID, uuid4
+
+if TYPE_CHECKING:
+    from omnibase_infra.errors import ModelInfraErrorContext
+
+logger = logging.getLogger(__name__)
+
+
+def ensure_timezone_aware(
+    dt: datetime,
+    *,
+    assume_utc: bool = True,
+    warn_on_naive: bool = True,
+    context: str | None = None,
+) -> datetime:
+    """Ensure a datetime is timezone-aware, converting naive datetimes to UTC.
+
+    This function validates that datetime values have timezone information before
+    they are persisted to the database. Naive datetimes (those without tzinfo)
+    are ambiguous and can cause subtle bugs when stored in TIMESTAMPTZ columns
+    or compared across timezones.
+
+    Behavior:
+        - Timezone-aware datetimes: Passed through unchanged
+        - Naive datetimes with assume_utc=True: Converted to UTC with warning
+        - Naive datetimes with assume_utc=False: Raises ProtocolConfigurationError
+
+    Args:
+        dt: The datetime to validate/normalize.
+        assume_utc: If True (default), naive datetimes are assumed to be UTC
+            and converted. If False, naive datetimes raise ValueError.
+        warn_on_naive: If True (default), logs a warning when a naive datetime
+            is converted. Set to False to suppress warnings (e.g., in migration
+            scripts where naive datetimes are expected).
+        context: Optional context string for the warning message (e.g., column
+            name, operation type). Helps identify the source of naive datetimes.
+
+    Returns:
+        A timezone-aware datetime. If the input was already aware, returns
+        the same datetime. If naive and assume_utc=True, returns a new
+        datetime with UTC timezone.
+
+    Raises:
+        ProtocolConfigurationError: If dt is naive and assume_utc=False.
+
+    Example:
+        >>> from datetime import datetime, UTC, timezone
+        >>> from omnibase_infra.utils.util_datetime import ensure_timezone_aware
+        >>>
+        >>> # Already aware - passes through unchanged
+        >>> aware = datetime(2025, 1, 15, 12, 0, 0, tzinfo=UTC)
+        >>> ensure_timezone_aware(aware) == aware
+        True
+        >>>
+        >>> # Naive datetime - converted to UTC with warning
+        >>> naive = datetime(2025, 1, 15, 12, 0, 0)
+        >>> result = ensure_timezone_aware(naive, context="updated_at")
+        >>> result.tzinfo == UTC
+        True
+        >>>
+        >>> # Strict mode - raises ProtocolConfigurationError for naive datetimes
+        >>> ensure_timezone_aware(naive, assume_utc=False)  # doctest: +ELLIPSIS
+        Traceback (most recent call last):
+        ...
+        omnibase_infra.errors...ProtocolConfigurationError: Naive datetime not allowed...
+
+    Warning:
+        Using assume_utc=True can silently mask timezone bugs in your code.
+        It's better to fix the source of naive datetimes than to rely on
+        automatic conversion. The warning log helps identify these issues.
+
+    Related:
+        - OMN-1170: Converting ProjectorRegistration to declarative contracts
+        - PR #146: Datetime validation improvements
+    """
+    # Check if datetime is already timezone-aware
+    if is_timezone_aware(dt):
+        return dt
+
+    # Handle naive datetime
+    if not assume_utc:
+        # Lazy imports to avoid circular dependency (utils -> errors -> models -> utils)
+        from omnibase_infra.enums import EnumInfraTransportType
+        from omnibase_infra.errors import (
+            ModelInfraErrorContext,
+            ProtocolConfigurationError,
+        )
+
+        error_context = ModelInfraErrorContext(
+            transport_type=EnumInfraTransportType.RUNTIME,
+            operation="ensure_timezone_aware",
+            target_name=context,
+            correlation_id=uuid4(),
+        )
+        raise ProtocolConfigurationError(
+            "Naive datetime not allowed. "
+            "Use timezone-aware datetime (e.g., datetime.now(UTC)).",
+            context=error_context,
+            parameter="dt",
+            value=dt.isoformat(),
+        )
+
+    # Log warning if enabled
+    if warn_on_naive:
+        context_msg = f" for '{context}'" if context else ""
+        logger.warning(
+            "Converting naive datetime to UTC%s. "
+            "Consider using datetime.now(UTC) instead of datetime.utcnow() or naive datetime().",
+            context_msg,
+            extra={
+                "naive_datetime": dt.isoformat(),
+                "context": context,
+                "action": "converted_to_utc",
+            },
+        )
+
+    # Convert naive datetime to UTC by replacing tzinfo
+    # Using replace() instead of astimezone() because astimezone() interprets
+    # naive datetimes as local time, which we don't want
+    return dt.replace(tzinfo=UTC)
+
+
+def is_timezone_aware(dt: datetime) -> bool:
+    """Check if a datetime is timezone-aware.
+
+    A datetime is timezone-aware if it has a tzinfo attribute that is not None
+    AND returns a valid utcoffset(). Some tzinfo objects may be set but not
+    properly configured, so we check both conditions.
+
+    Args:
+        dt: The datetime to check.
+
+    Returns:
+        True if datetime is timezone-aware, False if naive.
+
+    Example:
+        >>> from datetime import datetime, UTC
+        >>> from omnibase_infra.utils.util_datetime import is_timezone_aware
+        >>>
+        >>> is_timezone_aware(datetime.now(UTC))
+        True
+        >>> is_timezone_aware(datetime.now())  # Naive
+        False
+    """
+    return dt.tzinfo is not None and dt.utcoffset() is not None
+
+
+def validate_timezone_aware_with_context(
+    dt: datetime,
+    context: ModelInfraErrorContext,
+    *,
+    field_name: str = "envelope_timestamp",
+) -> datetime:
+    """Validate that a datetime is timezone-aware, raising ProtocolConfigurationError if not.
+
+    This is the SINGLE SOURCE OF TRUTH for handler-level timezone validation.
+    Use this function when you need to validate datetime values in handlers
+    and raise structured errors with context information.
+
+    For Pydantic field validators, use :func:`validate_timezone_aware_datetime`
+    from ``util_pydantic_validators.py`` instead.
+
+    Args:
+        dt: The datetime to validate.
+        context: A ModelInfraErrorContext instance for error reporting.
+            The context provides transport_type, operation, target_name,
+            and correlation_id for the error.
+        field_name: Name of the field being validated, used in error message.
+            Defaults to "envelope_timestamp".
+
+    Returns:
+        The validated datetime (unchanged if valid).
+
+    Raises:
+        ProtocolConfigurationError: If datetime is naive (no timezone info).
+
+    Example:
+        >>> from datetime import datetime, UTC
+        >>> from uuid import uuid4
+        >>> from omnibase_infra.enums import EnumInfraTransportType
+        >>> from omnibase_infra.errors import ModelInfraErrorContext
+        >>> from omnibase_infra.utils import validate_timezone_aware_with_context
+        >>>
+        >>> ctx = ModelInfraErrorContext(
+        ...     transport_type=EnumInfraTransportType.RUNTIME,
+        ...     operation="handle_event",
+        ...     target_name="my_handler",
+        ...     correlation_id=uuid4(),
+        ... )
+        >>>
+        >>> # Valid: timezone-aware datetime passes through
+        >>> aware = datetime.now(UTC)
+        >>> validate_timezone_aware_with_context(aware, ctx) == aware
+        True
+        >>>
+        >>> # Invalid: naive datetime raises ProtocolConfigurationError
+        >>> naive = datetime.now()
+        >>> validate_timezone_aware_with_context(naive, ctx)  # doctest: +ELLIPSIS
+        Traceback (most recent call last):
+        ...
+        omnibase_infra.errors...ProtocolConfigurationError: envelope_timestamp must be timezone-aware...
+
+    Related:
+        - OMN-1181: Replace RuntimeError with structured errors
+        - PR #158: Consolidate duplicate validation functions
+
+    .. versionadded:: 0.9.1
+        Created to consolidate duplicate timezone validation in handlers.
+    """
+    if is_timezone_aware(dt):
+        return dt
+
+    # Lazy imports to avoid circular dependency (utils -> errors -> models -> utils)
+    from omnibase_infra.errors import ProtocolConfigurationError
+
+    raise ProtocolConfigurationError(
+        f"{field_name} must be timezone-aware. Use datetime.now(UTC) or "
+        "datetime(..., tzinfo=timezone.utc) instead of naive datetime.",
+        context=context,
+        parameter=field_name,
+        value=dt.isoformat(),
+    )
+
+
+def warn_if_naive_datetime(
+    dt: datetime,
+    *,
+    field_name: str | None = None,
+    context: str | None = None,
+    correlation_id: UUID | None = None,
+    logger: logging.Logger | None = None,
+) -> None:
+    """Log a warning if the datetime is naive (lacks timezone info).
+
+    This is a WARNING-ONLY function that does not modify or convert the datetime.
+    Use this when you want to detect and log naive datetimes without changing
+    them, such as for auditing or gradual migration scenarios.
+
+    For automatic conversion of naive datetimes to UTC, use :func:`ensure_timezone_aware`
+    instead.
+
+    Args:
+        dt: The datetime to check for timezone awareness.
+        field_name: Optional name of the field/column containing the datetime.
+            Used in the warning message to identify the source.
+        context: Optional context string for the warning message (e.g., operation
+            name, handler name). Provides additional context for debugging.
+        correlation_id: Optional correlation ID for distributed tracing. Included
+            in the log extra dict when provided.
+        logger: Optional logger instance to use. If not provided, uses the
+            module-level logger (omnibase_infra.utils.util_datetime).
+
+    Returns:
+        None. This function only logs a warning and does not return a value.
+
+    Example:
+        >>> from datetime import datetime, UTC
+        >>> from uuid import uuid4
+        >>> from omnibase_infra.utils import warn_if_naive_datetime
+        >>>
+        >>> # Naive datetime triggers warning
+        >>> naive_dt = datetime(2025, 1, 15, 12, 0, 0)
+        >>> warn_if_naive_datetime(
+        ...     naive_dt,
+        ...     field_name="created_at",
+        ...     context="manifest_persistence",
+        ...     correlation_id=uuid4(),
+        ... )  # Logs warning
+        >>>
+        >>> # Aware datetime - no warning logged
+        >>> aware_dt = datetime.now(UTC)
+        >>> warn_if_naive_datetime(aware_dt, field_name="updated_at")  # Silent
+
+    Warning:
+        This function is intentionally warning-only. If you need to convert naive
+        datetimes to UTC, use :func:`ensure_timezone_aware` with ``assume_utc=True``.
+        The separation allows callers to choose between:
+
+        - **warn_if_naive_datetime**: Audit/detect without modification
+        - **ensure_timezone_aware**: Convert with optional warning
+
+    Related:
+        - OMN-1340: Extract datetime warning utility
+        - OMN-1163: Handler manifest persistence datetime handling
+
+    .. versionadded:: 0.9.0
+        Extracted from handler_manifest_persistence.py for reuse across codebase.
+    """
+    # Use module logger if none provided
+    log = logger if logger is not None else globals()["logger"]
+
+    # Check if datetime is timezone-aware - if so, nothing to warn about
+    if is_timezone_aware(dt):
+        return
+
+    # Build context-aware message parts
+    location_parts: list[str] = []
+    if field_name:
+        location_parts.append(f"field '{field_name}'")
+    if context:
+        location_parts.append(f"context '{context}'")
+
+    location_str = " in ".join(location_parts) if location_parts else "datetime value"
+
+    # Build extra dict for structured logging
+    extra: dict[str, str | None] = {
+        "field_name": field_name,
+        "context": context,
+        "datetime_value": dt.isoformat(),
+    }
+    if correlation_id is not None:
+        extra["correlation_id"] = str(correlation_id)
+
+    log.warning(
+        "Naive datetime detected for %s. For accurate comparisons, use "
+        "timezone-aware datetimes (e.g., datetime.now(UTC)). "
+        "See util_datetime module docstring for timezone handling details.",
+        location_str,
+        extra=extra,
+    )
+
+
+__all__: list[str] = [
+    "ensure_timezone_aware",
+    "is_timezone_aware",
+    "validate_timezone_aware_with_context",
+    "warn_if_naive_datetime",
+]

omnibase_infra/utils/util_dsn_validation.py

@@ -0,0 +1,333 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""PostgreSQL DSN validation utility.
+
+This module provides robust DSN validation using urllib.parse instead of regex.
+It handles edge cases like IPv6 addresses, URL-encoded passwords, query parameters,
+and validates DSN structure comprehensively.
+
+Security:
+    - Never logs credentials in error messages
+    - Returns [REDACTED] in error messages for sensitive values
+    - Validates structure without exposing DSN contents
+
+Edge Cases Handled:
+    - IPv6 addresses: postgresql://user:pass@[::1]:5432/db
+    - URL-encoded passwords: user:p%40ssword@host (p@ssword)
+    - Missing components: postgresql://localhost/db (no user/pass/port)
+    - Query parameters: postgresql://host/db?sslmode=require
+    - Unix sockets: postgresql:///db?host=/var/run/postgresql
+    - Empty password: user:@host (different from no password)
+
+Limitations:
+    - Multiple hosts (host1:5432,host2:5433) are not validated
+      (urllib.parse treats them as a single hostname)
+    - If multi-host support is needed, use a PostgreSQL-specific parser
+"""
+
+from __future__ import annotations
+
+from typing import Literal, cast
+from urllib.parse import parse_qs, unquote, urlparse
+from uuid import uuid4
+
+from omnibase_infra.types import ModelParsedDSN
+
+
+def _assert_postgres_scheme(scheme: str) -> Literal["postgresql", "postgres"]:
+    """Type-safe scheme assertion for PostgreSQL DSN schemes.
+
+    This helper enables proper type narrowing for the Literal type
+    using typing.cast for explicit type assertion.
+
+    Args:
+        scheme: The scheme string to validate
+
+    Returns:
+        The scheme cast to the appropriate Literal type
+
+    Raises:
+        ProtocolConfigurationError: If scheme is not 'postgresql' or 'postgres'.
+
+    Note:
+        This function should only be called AFTER validating
+        that scheme is one of the valid values.
+    """
+    if scheme not in ("postgresql", "postgres"):
+        # Lazy imports to avoid circular dependency (utils -> errors -> models -> utils)
+        from omnibase_infra.enums import EnumInfraTransportType
+        from omnibase_infra.errors import (
+            ModelInfraErrorContext,
+            ProtocolConfigurationError,
+        )
+
+        context = ModelInfraErrorContext(
+            transport_type=EnumInfraTransportType.DATABASE,
+            operation="validate_dsn_scheme",
+            target_name="dsn_validator",
+            correlation_id=uuid4(),
+        )
+        raise ProtocolConfigurationError(
+            f"Invalid scheme: expected 'postgresql' or 'postgres', got '{scheme}'",
+            context=context,
+            parameter="scheme",
+            value=scheme,
+        )
+    return cast(Literal["postgresql", "postgres"], scheme)
+
+
+def parse_and_validate_dsn(dsn: object) -> ModelParsedDSN:
+    """Parse and validate PostgreSQL DSN format using urllib.parse.
+
+    This function provides comprehensive DSN validation that handles edge cases
+    like IPv6 addresses, URL-encoded passwords, and query parameters. It uses
+    urllib.parse for robust parsing instead of fragile regex patterns.
+
+    Args:
+        dsn: PostgreSQL connection string (any type - validated)
+
+    Returns:
+        ModelParsedDSN with parsed components:
+            - scheme: "postgresql" or "postgres" (Literal type)
+            - username: Username or None
+            - password: Password (URL-decoded) or None
+            - hostname: Hostname or IP address or None
+            - port: Port number or None
+            - database: Database name
+            - query: Dict of query parameters (str keys, str | list[str] values)
+
+    Raises:
+        ProtocolConfigurationError: If DSN format is invalid
+
+    Example:
+        >>> result = parse_and_validate_dsn("postgresql://user:pass@localhost:5432/mydb")
+        >>> assert result.hostname == "localhost"
+        >>> assert result.database == "mydb"
+
+    Security Note:
+        Error messages never contain the actual DSN value. Sensitive information
+        is replaced with [REDACTED] to prevent credential leakage in logs.
+    """
+    # Lazy imports to avoid circular dependency (utils → errors → models → utils)
+    from omnibase_infra.enums import EnumInfraTransportType
+    from omnibase_infra.errors import ModelInfraErrorContext, ProtocolConfigurationError
+
+    context = ModelInfraErrorContext(
+        transport_type=EnumInfraTransportType.DATABASE,
+        operation="validate_dsn",
+        target_name="dsn_validator",
+        correlation_id=uuid4(),
+    )
+
+    # Type validation
+    if dsn is None:
+        raise ProtocolConfigurationError(
+            "Invalid dsn: expected a string, got None",
+            context=context,
+            parameter="dsn",
+            value=None,
+        )
+
+    if not isinstance(dsn, str):
+        raise ProtocolConfigurationError(
+            f"Invalid dsn type: expected str, got {type(dsn).__name__}",
+            context=context,
+            parameter="dsn",
+            value=type(dsn).__name__,
+        )
+
+    # Empty string validation
+    if not dsn.strip():
+        raise ProtocolConfigurationError(
+            "Invalid dsn: expected a non-empty string, got empty string",
+            context=context,
+            parameter="dsn",
+            value="",
+        )
+
+    dsn_str = dsn.strip()
+
+    # Scheme validation (before parsing to provide clear error)
+    valid_prefixes = ("postgresql://", "postgres://")
+    if not dsn_str.startswith(valid_prefixes):
+        raise ProtocolConfigurationError(
+            f"dsn must start with one of {valid_prefixes}",
+            context=context,
+            parameter="dsn",
+            value="[REDACTED]",  # Never log DSN contents
+        )
+
+    # Check for multi-host DSN format (not supported)
+    # Multi-host format: postgresql://host1:port1,host2:port2/db
+    # We check for comma after :// and before / (in the host portion)
+    scheme_end = dsn_str.index("://") + 3
+    path_start = dsn_str.find("/", scheme_end)
+    host_portion = (
+        dsn_str[scheme_end:path_start] if path_start != -1 else dsn_str[scheme_end:]
+    )
+    if "," in host_portion:
+        raise ProtocolConfigurationError(
+            "Multi-host DSNs are not supported. Use a single host or consider "
+            "psycopg2.conninfo_to_dict for multi-host parsing.",
+            context=context,
+            parameter="dsn",
+            value="[REDACTED]",
+        )
+
+    # Parse DSN using urllib.parse
+    try:
+        parsed = urlparse(dsn_str)
+    except ValueError as e:
+        # urlparse can raise ValueError for invalid ports, etc.
+        raise ProtocolConfigurationError(
+            f"Invalid DSN format: {e}",
+            context=context,
+            parameter="dsn",
+            value="[REDACTED]",
+        ) from e
+
+    # Validate scheme (redundant but explicit)
+    if parsed.scheme not in ("postgresql", "postgres"):
+        raise ProtocolConfigurationError(
+            f"Invalid scheme: expected 'postgresql' or 'postgres', got '{parsed.scheme}'",
+            context=context,
+            parameter="dsn",
+            value="[REDACTED]",
+        )
+
+    # Validate port if present
+    # Note: Accessing parsed.port can raise ValueError if port is invalid
+    try:
+        port = parsed.port
+        if port is not None:
+            if port < 1 or port > 65535:
+                raise ProtocolConfigurationError(
+                    f"Port must be between 1 and 65535, got {port}",
+                    context=context,
+                    parameter="dsn.port",
+                    value=port,
+                )
+    except ValueError as e:
+        # urlparse raises ValueError for invalid ports (non-numeric, out of range)
+        raise ProtocolConfigurationError(
+            f"Invalid port in DSN: {e}",
+            context=context,
+            parameter="dsn.port",
+            value="[REDACTED]",
+        ) from e
+
+    # Validate database name
+    # Path is "/dbname" or "///dbname" for Unix socket
+    # Strip leading slashes to get database name
+    database = parsed.path.lstrip("/") if parsed.path else ""
+
+    # Database name is required (unless using Unix socket with query param)
+    # For Unix sockets: postgresql:///dbname?host=/var/run/postgresql
+    # For network: postgresql://host/dbname
+    if not database:
+        # Check if Unix socket is specified in query params
+        query_params = parse_qs(parsed.query)
+        if "host" not in query_params:
+            raise ProtocolConfigurationError(
+                "Database name is required in DSN path (e.g., postgresql://host:5432/dbname)",
+                context=context,
+                parameter="dsn.path",
+                value="[REDACTED]",
+            )
+        # Unix socket case - database might be in query params or path
+        # Allow empty database for now (will be validated at connection time)
+
+    # Parse query parameters
+    query_dict = {}
+    if parsed.query:
+        # parse_qs returns lists, flatten to single values
+        parsed_qs = parse_qs(parsed.query)
+        query_dict = {k: v[0] if len(v) == 1 else v for k, v in parsed_qs.items()}
+
+    # Return parsed components
+    # Note: urlparse does NOT decode URL-encoded passwords, so we use unquote()
+    # Important: Check 'is not None' instead of truthiness to preserve empty strings
+    return ModelParsedDSN(
+        scheme=_assert_postgres_scheme(parsed.scheme),
+        username=unquote(parsed.username) if parsed.username is not None else None,
+        password=unquote(parsed.password) if parsed.password is not None else None,
+        hostname=parsed.hostname,
+        port=port,
+        database=database,
+        query=query_dict,
+    )
+
+
+def sanitize_dsn(dsn: str) -> str:
+    """Sanitize DSN by removing password for safe logging.
+
+    SECURITY: This function should ONLY be used for development/debugging.
+    Production code should NEVER log DSN values, even sanitized ones.
+
+    Replaces the password portion of the DSN with asterisks using URL parsing
+    instead of regex for robustness.
+
+    Args:
+        dsn: Raw PostgreSQL connection string containing credentials
+
+    Returns:
+        Sanitized DSN with password replaced by '***'
+
+    Example:
+        >>> sanitize_dsn("postgresql://user:secret@host:5432/db")
+        'postgresql://user:***@host:5432/db'
+
+        >>> sanitize_dsn("postgresql://user:p%40ss@host/db")
+        'postgresql://user:***@host/db'
+
+    Note:
+        This function is intentionally NOT used in production error paths.
+        It exists as a utility for development/debugging only.
+    """
+    try:
+        parsed = urlparse(dsn)
+
+        # Rebuild DSN with password masked
+        # Format: scheme://[user[:password]@]host[:port]/path[?query][#fragment]
+        netloc = parsed.hostname or ""
+
+        # Add port if present (handle ValueError from invalid ports)
+        try:
+            port = parsed.port
+            if port:
+                netloc = f"{netloc}:{port}"
+        except ValueError:
+            # Invalid port - include raw port string from netloc
+            # Extract port from raw netloc if present
+            if ":" in (parsed.netloc or ""):
+                # Keep original port notation even if invalid
+                parts = parsed.netloc.split("@")[-1]  # Get host:port part
+                if ":" in parts:
+                    netloc = parts
+
+        # Add username with masked password
+        if parsed.username:
+            if parsed.password:
+                netloc = f"{parsed.username}:***@{netloc}"
+            else:
+                netloc = f"{parsed.username}@{netloc}"
+
+        # Reconstruct URL
+        sanitized = f"{parsed.scheme}://{netloc}{parsed.path}"
+
+        # Add query string if present
+        if parsed.query:
+            sanitized = f"{sanitized}?{parsed.query}"
+
+        # Add fragment if present
+        if parsed.fragment:
+            sanitized = f"{sanitized}#{parsed.fragment}"
+
+        return sanitized
+
+    except Exception:
+        # If parsing fails, return a safe placeholder
+        return "[INVALID_DSN]"
+
+
+__all__: list[str] = ["ModelParsedDSN", "parse_and_validate_dsn", "sanitize_dsn"]