diff --git a/mailjet_rest/__init__.py b/mailjet_rest/__init__.py index 8b0b512..66617a8 100644 --- a/mailjet_rest/__init__.py +++ b/mailjet_rest/__init__.py @@ -1,23 +1,47 @@ """Mailjet REST API Python Wrapper.""" -from mailjet_rest.client import Client, Config -from mailjet_rest.errors import ( - ActionDeniedError, - ApiError, - ApiRateLimitError, - AuthorizationError, - CriticalApiError, - DoesNotExistError, - MailjetApiError, - MailjetAuthError, - MailjetNetworkError, - TimeoutError, # ruff: ignore[builtin-import-shadowing] - ValidationError, -) -from mailjet_rest.utils.version import get_version - - -__version__: str = get_version() +from __future__ import annotations + +import importlib +from typing import TYPE_CHECKING, Any + + +if TYPE_CHECKING: + from mailjet_rest.client import Client, Config + from mailjet_rest.errors import ( + ActionDeniedError, + ApiError, + ApiRateLimitError, + AuthorizationError, + CriticalApiError, + DoesNotExistError, + MailjetApiError, + MailjetAuthError, + MailjetNetworkError, + TimeoutError, # ruff: ignore[builtin-import-shadowing] + ValidationError, + ) + from mailjet_rest.utils.version import get_version + + __version__: str + + +_LAZY_EXPORTS: dict[str, tuple[str, str]] = { + "ActionDeniedError": ("mailjet_rest.errors", "ActionDeniedError"), + "ApiError": ("mailjet_rest.errors", "ApiError"), + "ApiRateLimitError": ("mailjet_rest.errors", "ApiRateLimitError"), + "AuthorizationError": ("mailjet_rest.errors", "AuthorizationError"), + "Client": ("mailjet_rest.client", "Client"), + "Config": ("mailjet_rest.client", "Config"), + "CriticalApiError": ("mailjet_rest.errors", "CriticalApiError"), + "DoesNotExistError": ("mailjet_rest.errors", "DoesNotExistError"), + "MailjetApiError": ("mailjet_rest.errors", "MailjetApiError"), + "MailjetAuthError": ("mailjet_rest.errors", "MailjetAuthError"), + "MailjetNetworkError": ("mailjet_rest.errors", "MailjetNetworkError"), + "TimeoutError": ("mailjet_rest.errors", "TimeoutError"), + "ValidationError": ("mailjet_rest.errors", "ValidationError"), + "get_version": ("mailjet_rest.utils.version", "get_version"), +} __all__ = [ "ActionDeniedError", @@ -35,3 +59,35 @@ "ValidationError", "get_version", ] + + +def __getattr__(name: str) -> Any: + """Resolve top-level SDK exports lazily via PEP 562. + + Returns: + Any: The resolved class, function, or version string. + """ + if name == "__version__": + version_mod = importlib.import_module("mailjet_rest.utils.version") + value = version_mod.get_version() + globals()[name] = value + return value + + target = _LAZY_EXPORTS.get(name) + if target is None: + msg = f"module 'mailjet_rest' has no attribute {name!r}" + raise AttributeError(msg) + + module_name, attr_name = target + value = getattr(importlib.import_module(module_name), attr_name) + globals()[name] = value + return value + + +def __dir__() -> list[str]: + """Return top-level exports including lazy attributes for introspection tools. + + Returns: + list[str]: Sorted list of exposed attributes. + """ + return sorted({*globals(), *__all__, "__version__"}) diff --git a/mailjet_rest/builders.py b/mailjet_rest/builders.py index c1001ac..03b6567 100644 --- a/mailjet_rest/builders.py +++ b/mailjet_rest/builders.py @@ -5,7 +5,6 @@ import base64 import errno import json -import mimetypes import os import stat import sys @@ -30,6 +29,8 @@ class ChunkedStreamer: """Generator for encoding large file attachments.""" + __slots__ = () + @staticmethod def encode_file( path: str | Path, @@ -254,7 +255,12 @@ def attach_file( target = SecurityGuard.validate_attachment_path(file_path, base_dir) SecurityGuard.check_file_size(target) - ctype = content_type or mimetypes.guess_type(target)[0] or "application/octet-stream" + if content_type is not None: + ctype = content_type + else: + import mimetypes # ruff: ignore[import-outside-top-level] + + ctype = mimetypes.guess_type(target)[0] or "application/octet-stream" if "Attachments" not in self._payload: self._payload["Attachments"] = [] @@ -279,7 +285,12 @@ def attach_inline( target = SecurityGuard.validate_attachment_path(file_path, base_dir) SecurityGuard.check_file_size(target) - ctype = content_type or mimetypes.guess_type(target)[0] or "application/octet-stream" + if content_type is not None: + ctype = content_type + else: + import mimetypes # ruff: ignore[import-outside-top-level] + + ctype = mimetypes.guess_type(target)[0] or "application/octet-stream" if "InlinedAttachments" not in self._payload: self._payload["InlinedAttachments"] = [] diff --git a/mailjet_rest/client.py b/mailjet_rest/client.py index 6cc31d4..967f240 100644 --- a/mailjet_rest/client.py +++ b/mailjet_rest/client.py @@ -7,7 +7,6 @@ from __future__ import annotations -import difflib import logging import secrets import sys @@ -98,6 +97,8 @@ class Client: endpoint attributes based on the static routing registry. """ + __slots__ = ("_closed", "_endpoint_cache", "_lock", "_session", "auth", "config") + _MUTATING_METHODS: ClassVar[frozenset[str]] = frozenset({"POST", "PUT", "PATCH", "DELETE"}) _RETRY_STRATEGY: ClassVar[JitterRetry] = JitterRetry( @@ -138,37 +139,61 @@ def __init__( self._lock = threading.RLock() self._closed = False + self._session: requests.Session | None = None + self._endpoint_cache: dict[str, Endpoint] = {} self.config = Config(**kwargs) if config is None else config - self.session = requests.Session() - resolved_verify = SecurityGuard.resolve_tls_verify(self.config.verify) - self.session.verify = resolved_verify + SecurityGuard.resolve_tls_verify(self.config.verify) # Delegate auth validation and coercion to SecurityGuard self.auth = SecurityGuard.validate_and_coerce_auth(auth) + if getattr(self.config, "enable_security_audit", False): + SecurityGuard.enable_audit_logging() + + def _build_session(self) -> requests.Session: + resolved_verify = SecurityGuard.resolve_tls_verify(self.config.verify) + session = requests.Session() + session.verify = resolved_verify + + session.auth = self.auth if isinstance(self.auth, SecretAuth) else None if isinstance(self.auth, str): - self.session.auth = None - self.session.headers.update({"Authorization": f"Bearer {self.auth}"}) - elif isinstance(self.auth, SecretAuth): - self.session.auth = self.auth - else: - self.session.auth = None # type: ignore[unreachable] + session.headers.update({"Authorization": f"Bearer {self.auth}"}) - self.session.headers.update({"User-Agent": self.config.user_agent}) + session.headers.update({"User-Agent": self.config.user_agent}) ca_bundle = resolved_verify if isinstance(resolved_verify, str) else None adapter = SecureHTTPAdapter( ca_bundle=ca_bundle, - pool_connections=100, - pool_maxsize=100, + pool_connections=self.config.pool_connections, + pool_maxsize=self.config.pool_maxsize, max_retries=self._RETRY_STRATEGY, ) - self.session.mount("https://", adapter) + session.mount("https://", adapter) + return session - self._endpoint_cache: dict[str, Endpoint] = {} + @property + def session(self) -> requests.Session: + """Lazily create and return the underlying thread-safe HTTP session. - if getattr(self.config, "enable_security_audit", False): - SecurityGuard.enable_audit_logging() + Returns: + requests.Session: The configured session instance. + """ + with self._lock: + if self._session is None: + if self._closed: + closed_session = requests.Session() + closed_session.auth = None + closed_session.headers.clear() + closed_session.close() + self._session = closed_session + else: + self._session = self._build_session() + return self._session + + @session.setter + def session(self, value: requests.Session | None) -> None: + with self._lock: + self._session = value def __enter__(self) -> Self: """Enter the context manager and return the client instance. @@ -213,12 +238,28 @@ def close(self) -> None: """Secure resource teardown closing internal sockets.""" with self._lock: self._closed = True - session = getattr(self, "session", None) + session = self._session if session is not None: session.auth = None session.headers.clear() session.close() + def __del__(self) -> None: + """Optionally emit ResourceWarning on GC teardown when Config.warn_unclosed is enabled.""" + try: + cfg = object.__getattribute__(self, "config") + session = object.__getattribute__(self, "_session") + closed = object.__getattribute__(self, "_closed") + except (OSError, RuntimeError, AttributeError): + return + + if getattr(cfg, "warn_unclosed", False) and session is not None and not closed: + warnings.warn( + "Unclosed Mailjet Client session; call client.close() or use a context manager.", + ResourceWarning, + stacklevel=2, + ) + def __getattr__(self, name: str) -> Endpoint: """O(1) Route mapping. @@ -238,9 +279,12 @@ def __getattr__(self, name: str) -> Endpoint: # Fail fast for typos: Only check simple un-composited names. # A cutoff of 0.8 catches obvious mistakes like 'snd'->'send' or 'session'->'session', # but allows legitimate dynamic endpoints to pass through to the fallback. - if "_" not in name and name not in ROUTE_MAP and difflib.get_close_matches(name, dir(self), n=1, cutoff=0.8): - msg = f"'{self.__class__.__name__}' has no endpoint or attribute '{name}'." - raise AttributeError(msg) + if "_" not in name and name not in ROUTE_MAP: + import difflib # ruff: ignore[import-outside-top-level] + + if difflib.get_close_matches(name, dir(self), n=1, cutoff=0.8): + msg = f"'{self.__class__.__name__}' has no endpoint or attribute '{name}'." + raise AttributeError(msg) # If it doesn't exist, we fall back to assuming it's a dynamic path # which will be safely encoded by sanitize_segment during _build_url @@ -416,8 +460,6 @@ def api_call( # ruff: ignore[complex-structure] # Strip None filters clean_filters = {k: v for k, v in filters.items() if v is not None} if filters else None - trace_suffix, _ = self._extract_telemetry(data, req_headers) - try: response = self._execute_request( method=method, @@ -443,7 +485,8 @@ def api_call( # ruff: ignore[complex-structure] self._handle_api_error(e) else: - if response.status_code in {200, 201, 204}: + if response.status_code in {200, 201, 204} and logger.isEnabledFor(logging.DEBUG): + trace_suffix, _ = self._extract_telemetry(data, req_headers) self._log_request(method, url, response, trace_suffix) return response diff --git a/mailjet_rest/config.py b/mailjet_rest/config.py index 05c1391..704352b 100644 --- a/mailjet_rest/config.py +++ b/mailjet_rest/config.py @@ -26,6 +26,9 @@ class Config: enable_security_audit (bool): Enable runtime PEP 578 security audit event emission. verify (bool | str | Path): TLS verification setting or path to a custom CA bundle. auto_idempotency_mode (AutoIdempotencyMode): Strategy for auto-populating Idempotency-Key. + pool_connections (int): Number of urllib3 connection pools to cache per Client. + pool_maxsize (int): Maximum number of persistent connections saved per pool. + warn_unclosed (bool): Emit ResourceWarning on garbage collection if session was not closed. """ ALLOWED_ROOT_DOMAIN: ClassVar[str] = "mailjet.com" @@ -38,6 +41,15 @@ class Config: enable_security_audit: bool = False verify: bool | str | Path = True auto_idempotency_mode: AutoIdempotencyMode = "fingerprint" + pool_connections: int = 100 + pool_maxsize: int = 100 + warn_unclosed: bool = False + + @staticmethod + def _validate_pool_size(name: str, value: int) -> None: + if isinstance(value, bool) or not isinstance(value, int) or value < 1: + msg = f"{name} must be an integer >= 1, got {value!r}." + raise ValueError(msg) def __post_init__(self) -> None: """Validate configuration for secure transport and resource limits (OWASP Input Validation).""" @@ -58,3 +70,11 @@ def __post_init__(self) -> None: if self.auto_idempotency_mode not in _VALID_IDEMPOTENCY_MODES: msg = f"Invalid auto_idempotency_mode {self.auto_idempotency_mode!r}; expected one of {sorted(_VALID_IDEMPOTENCY_MODES)}." raise ValueError(msg) + + # 5. Validate connection pool bounds and warning flags + self._validate_pool_size("pool_connections", self.pool_connections) + self._validate_pool_size("pool_maxsize", self.pool_maxsize) + raw_warn: object = self.warn_unclosed + if not isinstance(raw_warn, bool): + msg = f"warn_unclosed must be a bool, got {type(raw_warn).__name__}." + raise TypeError(msg) diff --git a/mailjet_rest/endpoint.py b/mailjet_rest/endpoint.py index 49e6b8a..80713d9 100644 --- a/mailjet_rest/endpoint.py +++ b/mailjet_rest/endpoint.py @@ -231,9 +231,7 @@ def _build_headers(self, custom_headers: Mapping[str, str | None] | None = None) if custom_headers: clean_custom = SecurityGuard.sanitize_headers(dict(custom_headers)) - merged: dict[str, str | None] = dict(base_headers) - merged.update(clean_custom) - return merged + return {**base_headers, **clean_custom} return dict(base_headers) @staticmethod diff --git a/mailjet_rest/types.py b/mailjet_rest/types.py index cbc75f9..19c1828 100644 --- a/mailjet_rest/types.py +++ b/mailjet_rest/types.py @@ -40,7 +40,7 @@ _DEFAULT_TIMEOUT: Final[int] = 60 _JSON_HEADERS: Final = MappingProxyType({"Content-Type": "application/json"}) _TEXT_HEADERS: Final = MappingProxyType({"Content-Type": "text/plain"}) -_ALLOWED_TRACE_FIELDS: Final[set[str]] = {"CustomID", "TemplateID"} +_ALLOWED_TRACE_FIELDS: Final[frozenset[str]] = frozenset({"CustomID", "TemplateID"}) class EmailAddress(TypedDict): diff --git a/mailjet_rest/utils/guardrails.py b/mailjet_rest/utils/guardrails.py index 87b7fc3..c979eda 100644 --- a/mailjet_rest/utils/guardrails.py +++ b/mailjet_rest/utils/guardrails.py @@ -7,48 +7,55 @@ from __future__ import annotations -import base64 import contextlib import hashlib -import hmac import json import logging import math import os import re -import ssl import sys -import tempfile import traceback import unicodedata import warnings from functools import lru_cache -from html.parser import HTMLParser from pathlib import Path -from typing import TYPE_CHECKING, Any, ClassVar, Final, NoReturn +from typing import TYPE_CHECKING, Any, ClassVar, Final from urllib.parse import quote, unquote, urlparse +from mailjet_rest.errors import ValidationError +from mailjet_rest.utils.transport_security import ( + SecretAuth, + SecureHTTPAdapter, + _build_tls_context, + get_secure_ssl_context, + resolve_tls_verify, +) + if TYPE_CHECKING: from collections.abc import Mapping - - import requests + from html.parser import HTMLParser from mailjet_rest.types import TimeoutType -from requests.adapters import HTTPAdapter -from requests.auth import AuthBase -from requests.utils import DEFAULT_CA_BUNDLE_PATH - -from mailjet_rest.errors import ValidationError - if sys.version_info >= (3, 12): - from typing import TYPE_CHECKING, override + from typing import override else: from typing_extensions import override +__all__ = [ + "RedactingFilter", + "SecretAuth", + "SecureHTTPAdapter", + "SecurityGuard", + "_build_tls_context", + "get_secure_ssl_context", +] + + _CRLF_RE: Final = re.compile(r"[\r\n]") # RFC 9110 strict control characters (blocks all non-printable ASCII except \x09 tab) _CONTROL_CHAR_RE: Final = re.compile(r"[\x00-\x08\x0a-\x1f\x7f]") @@ -73,146 +80,19 @@ def _get_secret_pattern() -> re.Pattern[str]: ) -def _build_tls_context(ca_bundle: str | None = None) -> ssl.SSLContext: - """Create a hardened SSL context enforcing TLS 1.2+, cert checks, and isolated CA trust stores. - - Returns: - ssl.SSLContext: Configured SSL context. - """ - if ca_bundle is not None: - context = ssl.create_default_context(cafile=ca_bundle) - else: - context = ssl.create_default_context() - if DEFAULT_CA_BUNDLE_PATH and Path(DEFAULT_CA_BUNDLE_PATH).is_file(): - context.load_verify_locations(cafile=DEFAULT_CA_BUNDLE_PATH) - context.minimum_version = ssl.TLSVersion.TLSv1_2 - context.check_hostname = True - context.verify_mode = ssl.CERT_REQUIRED - context.options |= getattr(ssl, "OP_NO_COMPRESSION", 0) - return context - - -class SecureHTTPAdapter(HTTPAdapter): - """Custom HTTP Adapter enforcing modern TLS versions and isolated CA trust stores (CWE-319, CWE-295).""" - - def __init__(self, ca_bundle: str | None = None, **kwargs: Any) -> None: - """Initialize the TLS adapter with an optional custom CA bundle path.""" - self._ca_bundle = ca_bundle - self._ssl_context = _build_tls_context(ca_bundle) - super().__init__(**kwargs) - - @staticmethod - def _get_secure_ssl_context(ca_bundle: str | None = None) -> ssl.SSLContext: - """Create and return a hardened SSL context enforcing TLS 1.2+. - - Returns: - ssl.SSLContext: The configured SSL context. - """ - return _build_tls_context(ca_bundle) - - @override - def init_poolmanager(self, *args: Any, **kwargs: Any) -> None: - kwargs["ssl_context"] = self._ssl_context - super().init_poolmanager(*args, **kwargs) # type: ignore[no-untyped-call] - - @override - def proxy_manager_for(self, proxy: str, **proxy_kwargs: Any) -> Any: - """Ensure proxy connections also strictly enforce TLS 1.2+. - - Returns: - Any: The proxy manager instance. - """ - proxy_kwargs["ssl_context"] = self._ssl_context - return super().proxy_manager_for(proxy, **proxy_kwargs) # type: ignore[no-untyped-call] - - @override - def cert_verify(self, conn: Any, url: str, verify: Any, cert: Any) -> None: - """Enforce strict TLS verification and isolate per-call CA/client-cert SSL contexts.""" - resolved = SecurityGuard.resolve_tls_verify(verify) - super().cert_verify(conn, url, resolved, cert) # type: ignore[no-untyped-call] - if url.lower().startswith("https"): - needs_isolated_ctx = ( - cert is not None - or (isinstance(resolved, str) and resolved != self._ca_bundle) - or (resolved is True and self._ca_bundle is not None) - ) - if needs_isolated_ctx: - target_ca = resolved if isinstance(resolved, str) else None - conn.ssl_context = _build_tls_context(target_ca) - else: - conn.ssl_context = self._ssl_context - # Clear ca_certs/ca_cert_dir because conn.ssl_context already holds the exact trust store; - # otherwise urllib3 mutates the shared SSLContext on handshake. - conn.ca_certs = None - conn.ca_cert_dir = None - - -class SecretAuth(AuthBase): - """OWASP: Obfuscate credentials in memory dumps and tracebacks (CWE-316). - - Inherits from AuthBase instead of tuple to prevent index/iteration exposure. - """ - - def __init__(self, auth_tuple: tuple[str, str]) -> None: - """Initialize with API credentials.""" - __tracebackhide__ = True - self._api_key = auth_tuple[0] - self._api_secret = auth_tuple[1] - - def __call__(self, r: requests.PreparedRequest) -> requests.PreparedRequest: - """Apply Basic Auth headers to the request. - - Returns: - requests.PreparedRequest: The modified request. - """ - __tracebackhide__ = True - auth_str = f"{self._api_key}:{self._api_secret}".encode("latin1") - r.headers["Authorization"] = "Basic " + base64.b64encode(auth_str).decode("ascii") - return r +_SECRET_SENTINELS: Final[tuple[str, ...]] = ( + "authorization", + "api_key", + "api-key", + "api_secret", + "api-secret", + "token", +) - def __hash__(self) -> int: - """Hash the credentials for dictionary lookups. - Returns: - int: The computed hash value. - """ - return hash((self._api_key, self._api_secret)) - - def __eq__(self, other: object) -> bool: - """Compare credentials in constant time using hmac.compare_digest. - - Returns: - bool: True if equal, False otherwise. - """ - if isinstance(other, SecretAuth): - other_key = other._api_key - other_secret = other._api_secret - elif isinstance(other, tuple) and len(other) == 2 and all(isinstance(item, str) for item in other): - other_key, other_secret = other - else: - return False - - key_match = hmac.compare_digest(self._api_key.encode("utf-8"), other_key.encode("utf-8")) - secret_match = hmac.compare_digest(self._api_secret.encode("utf-8"), other_secret.encode("utf-8")) - return bool(key_match & secret_match) - - def __getitem__(self, index: int) -> NoReturn: - """Prevent Credential extraction via tuple unpacking / indexing.""" - msg = "Credential extraction via indexing is blocked for security (CWE-316)." - raise TypeError(msg) - - def __iter__(self) -> Any: - """Prevent Credential extraction via iteration.""" - msg = "Credential extraction via iteration is blocked for security (CWE-316)." - raise TypeError(msg) - - def __repr__(self) -> str: - """Return a safe representation of the credential.""" - return "SecretAuth(***REDACTED***)" - - def __str__(self) -> str: - """Return a safe string representation of the credential.""" - return "SecretAuth(***REDACTED***)" +def _may_contain_secret(text: str) -> bool: + lower = text.lower() + return any(token in lower for token in _SECRET_SENTINELS) class RedactingFilter(logging.Filter): @@ -286,6 +166,12 @@ def _redact_str(data: str) -> str: except Exception: # ruff: ignore[blind-except] return "[REDACTION_FAILED_UNSAFE_STRING]" + @classmethod + def _redact_str_fast(cls, data: str) -> str: + if not _may_contain_secret(data): + return data + return cls._redact_str(data) + def _redact_tuple(self, data: tuple[Any, ...], depth: int) -> tuple[Any, ...]: """Recursively sanitize tuple items preserving namedtuple structure. @@ -316,7 +202,7 @@ def _redact_object(self, data: Any, depth: int) -> Any: except Exception: # ruff: ignore[blind-except] return "" - return self._redact_str(str_val) + return self._redact_str_fast(str_val) def _deep_redact(self, data: Any, depth: int = 0) -> Any: """Recursively search and scrub secrets from complex nested data structures. @@ -330,7 +216,7 @@ def _deep_redact(self, data: Any, depth: int = 0) -> Any: if isinstance(data, (int, float, bool, type(None))): return data if isinstance(data, str): - return self._redact_str(data) + return self._redact_str_fast(data) if isinstance(data, dict): return { k: ("********" if self._is_sensitive_key(k, v) else self._deep_redact(v, depth + 1)) @@ -349,11 +235,11 @@ def _deep_redact(self, data: Any, depth: int = 0) -> Any: def _redact_exc_info(self, record: logging.LogRecord) -> None: if isinstance(record.exc_text, str): - record.exc_text = self._redact_str(record.exc_text) + record.exc_text = self._redact_str_fast(record.exc_text) if isinstance(record.exc_info, tuple) and len(record.exc_info) == 3: formatted = "".join(traceback.format_exception(*record.exc_info)).rstrip("\n") - record.exc_text = self._redact_str(formatted) + record.exc_text = self._redact_str_fast(formatted) record.exc_info = None def _redact_extra_attrs(self, record: logging.LogRecord) -> None: @@ -372,34 +258,50 @@ def filter(self, record: logging.LogRecord) -> bool: bool: Always True (permits the log to write but strictly scrubs the content beforehand). """ try: # ruff: ignore[too-many-statements-in-try-clause] - if isinstance(record.msg, str): + has_args = bool(isinstance(record.args, (dict, tuple)) and record.args) + has_exc = record.exc_text is not None or record.exc_info is not None + has_extras = any(attr not in self._STANDARD_ATTRS for attr in record.__dict__) + + if isinstance(record.msg, str) and _may_contain_secret(record.msg): record.msg = self._redact_str(record.msg) + elif not has_args and not has_exc and not has_extras: + return True - if isinstance(record.args, (dict, tuple)): + if has_args: record.args = self._deep_redact(record.args) - self._redact_extra_attrs(record) - self._redact_exc_info(record) + if has_extras: + self._redact_extra_attrs(record) + if has_exc: + self._redact_exc_info(record) except Exception as e: # ruff: ignore[blind-except] # Failsafe: Never let logging filters crash application execution logging.getLogger(__name__).debug("Redaction filter failed: %s", e) return True -class SecurityGuard: - """Centralized OWASP API security and payload guardrails.""" +def _inspect_starttag(parser: Any, tag: str, attrs: list[tuple[str, str | None]]) -> None: + parser._count_tag() # ruff: ignore[private-member-access] + if tag.lower() in {"script", "iframe", "object", "embed", "applet"}: + parser.has_script = True + parser.is_safe = False + parser.issues.append(f"Blocked executable tag: <{tag}>") - MAX_HTML_SIZE: int = 5 * 1024 * 1024 # 5MB safe limit (CWE-400) - MAX_TAG_COUNT: int = 10000 # DoS protection against tag bombs (CWE-400) + for attr, _ in attrs: + if attr.lower().startswith("on"): + parser.has_script = True + parser.is_safe = False + parser.issues.append(f"Blocked event handler: {attr}") - VOLATILE_IDEMPOTENCY_KEYS: ClassVar[frozenset[str]] = frozenset({"CustomID", "EventPayload", "SandboxMode"}) - ALLOWED_KWARGS: ClassVar[frozenset[str]] = frozenset( - {"proxies", "cert", "stream", "verify", "allow_redirects", "files"} - ) + +def _build_spam_guard_parser() -> type[Any]: + from html.parser import HTMLParser # ruff: ignore[import-outside-top-level] class _SpamGuardParser(HTMLParser): """Internal lightweight HTML analyzer to preemptively catch XSS and tag bombs.""" + __slots__ = ("has_script", "is_safe", "issues", "max_tags", "tag_count") + def __init__(self, max_tags: int = 10000) -> None: super().__init__() self.has_script: bool = False @@ -416,19 +318,7 @@ def _count_tag(self) -> None: @override def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None: - self._count_tag() - # Catch known executable injection points - if tag.lower() in {"script", "iframe", "object", "embed", "applet"}: - self.has_script = True - self.is_safe = False - self.issues.append(f"Blocked executable tag: <{tag}>") - - # Catch any injected event handlers (e.g., onerror, onclick) - for attr, _ in attrs: - if attr.lower().startswith("on"): - self.has_script = True - self.is_safe = False - self.issues.append(f"Blocked event handler: {attr}") + _inspect_starttag(self, tag, attrs) @override def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None: @@ -442,6 +332,73 @@ def handle_endtag(self, tag: str) -> None: def handle_comment(self, data: str) -> None: self._count_tag() + return _SpamGuardParser + + +class _LazyGuardMeta(type): + """Defer importing html.parser until HTML safety checks run.""" + + def __getattr__(cls, name: str) -> Any: + if name == "_SpamGuardParser": + parser_cls = _build_spam_guard_parser() + type.__setattr__(cls, "_SpamGuardParser", parser_cls) + return parser_cls + msg = f"type object {cls.__name__!r} has no attribute {name!r}" + raise AttributeError(msg) + + +@lru_cache(maxsize=32) +def _validate_config_url_cached(url: str, allowed_root_domain: str) -> None: + parsed = urlparse(url) + + if parsed.scheme not in {"http", "https"}: + msg = f"Security Alert (CWE-918): Invalid scheme '{parsed.scheme}'. Only http/https allowed." + raise ValueError(msg) + + hostname = parsed.hostname or "" + allowed_exact_hosts = frozenset( + { + allowed_root_domain, + f"api.{allowed_root_domain}", + "localhost", + "127.0.0.1", + "::1", + } + ) + + is_safe = hostname in allowed_exact_hosts or hostname.endswith(f".{allowed_root_domain}") + if not is_safe: + msg = ( + f"Security Alert (CWE-918): Hostname '{hostname}' is not permitted. " + f"Must be a '{allowed_root_domain}' domain or a local loopback for testing." + ) + raise ValueError(msg) + + +class SecurityGuard(metaclass=_LazyGuardMeta): + """Centralized OWASP API security and payload guardrails.""" + + __slots__ = () + + MAX_HTML_SIZE: int = 5 * 1024 * 1024 # 5MB safe limit (CWE-400) + MAX_TAG_COUNT: int = 10000 # DoS protection against tag bombs (CWE-400) + + VOLATILE_IDEMPOTENCY_KEYS: ClassVar[frozenset[str]] = frozenset({"CustomID", "EventPayload", "SandboxMode"}) + ALLOWED_KWARGS: ClassVar[frozenset[str]] = frozenset( + {"proxies", "cert", "stream", "verify", "allow_redirects", "files"} + ) + + if TYPE_CHECKING: + + class _SpamGuardParser(HTMLParser): + has_script: bool + is_safe: bool + issues: list[str] + tag_count: int + max_tags: int + + def __init__(self, max_tags: int = 10000) -> None: ... + @staticmethod def resolve_tls_verify(verify: Any) -> bool | str: """Validate TLS verification flag or custom CA bundle path (CWE-295). @@ -449,30 +406,7 @@ def resolve_tls_verify(verify: Any) -> bool | str: Returns: bool | str: True for system/certifi CA verification, or validated CA bundle path string. """ - if verify is False or verify is None: - sys.audit("mailjet.security.tls_disabled", str(verify)) - msg = "Security Violation: Mailjet API TLS verification cannot be disabled (verify=False is forbidden)." - raise ValueError(msg) - - if verify is True: - return True - - if isinstance(verify, (str, os.PathLike)): - raw_verify = os.fspath(verify) - if not isinstance(raw_verify, str): - msg = f"Invalid CA bundle path type: expected str or os.PathLike[str], got {type(raw_verify).__name__}." - raise TypeError(msg) - if not raw_verify.strip() or _CONTROL_CHAR_RE.search(raw_verify): - msg = "Invalid CA bundle path: must be a non-empty path without control characters." - raise ValueError(msg) - ca_path = Path(raw_verify).expanduser() - if not ca_path.exists() or not ca_path.is_file(): - msg = f"Custom CA bundle path does not exist or is not a file: {ca_path}" - raise ValueError(msg) - return str(ca_path) - - msg = f"Invalid 'verify' type: expected bool, str, or PathLike, got {type(verify).__name__}." - raise TypeError(msg) + return resolve_tls_verify(verify) @staticmethod def enable_audit_logging() -> None: @@ -498,39 +432,8 @@ def validate_config_url(url: str, allowed_root_domain: str = "mailjet.com") -> N Args: url (str): The configured API URL to validate. allowed_root_domain (str): The trusted root domain for production traffic. - - Raises: - ValueError: If the scheme or hostname violates zero-trust policies. """ - parsed = urlparse(url) - - # 1. Enforce Safe Schemes (Block file://, dict://, gopher://, etc.) - if parsed.scheme not in {"http", "https"}: - msg = f"Security Alert (CWE-918): Invalid scheme '{parsed.scheme}'. Only http/https allowed." - raise ValueError(msg) - - hostname = parsed.hostname or "" - - # 2. Allowlist (Production + Local CI/CD loopbacks) - allowed_exact_hosts = frozenset( - { - allowed_root_domain, - f"api.{allowed_root_domain}", - "localhost", - "127.0.0.1", - "::1", # Include IPv6 loopback for modern CI environments - } - ) - - # Safe if it's an exact match OR a valid subdomain of the trusted root - is_safe = hostname in allowed_exact_hosts or hostname.endswith(f".{allowed_root_domain}") - - if not is_safe: - msg = ( - f"Security Alert (CWE-918): Hostname '{hostname}' is not permitted. " - f"Must be a '{allowed_root_domain}' domain or a local loopback for testing." - ) - raise ValueError(msg) + _validate_config_url_cached(url, allowed_root_domain) @staticmethod def check_request_security(kwargs: dict[str, Any]) -> None: @@ -548,7 +451,13 @@ def sanitize_headers(headers: Mapping[str, str | None]) -> dict[str, str | None] """ clean_headers: dict[str, str | None] = {} for k, v in headers.items(): - if _CRLF_RE.search(k) or (v is not None and _CRLF_RE.search(str(v))): + key_ok = k.isascii() and k.isprintable() + val_ok = v is None or (isinstance(v, str) and v.isascii() and v.isprintable()) + if not key_ok and _CRLF_RE.search(k): + sys.audit("mailjet.security.header_injection", k) + msg = f"Security Violation: CRLF injection detected in header '{k}'" + raise ValueError(msg) + if not val_ok and _CRLF_RE.search(str(v)): sys.audit("mailjet.security.header_injection", k) msg = f"Security Violation: CRLF injection detected in header '{k}'" raise ValueError(msg) @@ -681,6 +590,8 @@ def _validate_zero_trust_path(original_path: str, target: Path) -> None: is_in_temp = False with contextlib.suppress(Exception): + import tempfile # ruff: ignore[import-outside-top-level] + temp_dir = Path(tempfile.gettempdir()).resolve() is_in_temp = target.is_relative_to(temp_dir) diff --git a/mailjet_rest/utils/transport_security.py b/mailjet_rest/utils/transport_security.py new file mode 100644 index 0000000..7ed970e --- /dev/null +++ b/mailjet_rest/utils/transport_security.py @@ -0,0 +1,240 @@ +"""Transport-layer TLS context caching, keep-alive adapter, and credential auth.""" + +from __future__ import annotations + +import base64 +import hmac +import os +import re +import socket +import ssl +import sys +from functools import lru_cache +from pathlib import Path +from typing import TYPE_CHECKING, Any, Final, NoReturn + +from requests.adapters import HTTPAdapter +from requests.auth import AuthBase +from requests.utils import DEFAULT_CA_BUNDLE_PATH +from urllib3.connection import HTTPConnection + + +if TYPE_CHECKING: + import requests + +if sys.version_info >= (3, 12): + from typing import override +else: + from typing_extensions import override + + +_CONTROL_CHAR_RE: Final = re.compile(r"[\x00-\x08\x0a-\x1f\x7f]") + +_KEEPALIVE_OPTION: Final[tuple[int, int, int]] = (socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1) +_DEFAULT_SOCKET_OPTIONS: Final[tuple[Any, ...]] = tuple(HTTPConnection.default_socket_options or ()) +_KEEPALIVE_SOCKET_OPTIONS: Final[tuple[Any, ...]] = ( + _DEFAULT_SOCKET_OPTIONS + if _KEEPALIVE_OPTION in _DEFAULT_SOCKET_OPTIONS + else (*_DEFAULT_SOCKET_OPTIONS, _KEEPALIVE_OPTION) +) + + +def resolve_tls_verify(verify: Any) -> bool | str: + """Validate TLS verification flag or custom CA bundle path (CWE-295). + + Returns: + bool | str: True for default CA verification, or validated CA bundle path string. + """ + if verify is False or verify is None: + sys.audit("mailjet.security.tls_disabled", str(verify)) + msg = "Security Violation: Mailjet API TLS verification cannot be disabled (verify=False is forbidden)." + raise ValueError(msg) + + if verify is True: + return True + + if isinstance(verify, (str, os.PathLike)): + raw_verify = os.fspath(verify) + if not isinstance(raw_verify, str): + msg = f"Invalid CA bundle path type: expected str or os.PathLike[str], got {type(raw_verify).__name__}." + raise TypeError(msg) + if not raw_verify.strip() or _CONTROL_CHAR_RE.search(raw_verify): + msg = "Invalid CA bundle path: must be a non-empty path without control characters." + raise ValueError(msg) + ca_path = Path(raw_verify).expanduser() + if not ca_path.exists() or not ca_path.is_file(): + msg = f"Custom CA bundle path does not exist or is not a file: {ca_path}" + raise ValueError(msg) + return str(ca_path) + + msg = f"Invalid 'verify' type: expected bool, str, or PathLike, got {type(verify).__name__}." + raise TypeError(msg) + + +@lru_cache(maxsize=8) +def _cached_ssl_context(ca_bundle: str | None, mtime_ns: int, size: int) -> ssl.SSLContext: + """Build and cache an isolated TLS 1.2+ SSLContext keyed on CA bundle identity and mtime/size. + + Returns: + ssl.SSLContext: Configured SSL context with isolated CA trust store. + """ + _ = (mtime_ns, size) + if ca_bundle is not None: + context = ssl.create_default_context(cafile=ca_bundle) + else: + context = ssl.create_default_context() + if DEFAULT_CA_BUNDLE_PATH and Path(DEFAULT_CA_BUNDLE_PATH).is_file(): + context.load_verify_locations(cafile=DEFAULT_CA_BUNDLE_PATH) + context.minimum_version = ssl.TLSVersion.TLSv1_2 + context.check_hostname = True + context.verify_mode = ssl.CERT_REQUIRED + context.options |= getattr(ssl, "OP_NO_COMPRESSION", 0) + return context + + +def get_secure_ssl_context(ca_bundle: str | None = None) -> ssl.SSLContext: + """Return a hardened TLS 1.2+ SSLContext, invalidating cache when a custom CA file changes. + + Returns: + ssl.SSLContext: Configured SSL context. + """ + if ca_bundle is not None: + st = Path(ca_bundle).stat() + return _cached_ssl_context(ca_bundle, st.st_mtime_ns, st.st_size) + return _cached_ssl_context(None, 0, 0) + + +def _build_tls_context(ca_bundle: str | None = None) -> ssl.SSLContext: + """Create or retrieve a hardened SSLContext enforcing TLS 1.2+ and isolated CA trust stores. + + Returns: + ssl.SSLContext: Configured SSL context. + """ + return get_secure_ssl_context(ca_bundle) + + +class SecureHTTPAdapter(HTTPAdapter): + """Custom HTTP Adapter enforcing TLS 1.2+, isolated CA trust stores, and TCP keep-alive.""" + + def __init__(self, ca_bundle: str | None = None, **kwargs: Any) -> None: + """Initialize the TLS adapter with an optional custom CA bundle path.""" + self._ca_bundle = ca_bundle + self._ssl_context = _build_tls_context(ca_bundle) + super().__init__(**kwargs) + + @staticmethod + def _get_secure_ssl_context(ca_bundle: str | None = None) -> ssl.SSLContext: + """Create and return a hardened SSL context enforcing TLS 1.2+. + + Returns: + ssl.SSLContext: The configured SSL context. + """ + return _build_tls_context(ca_bundle) + + @override + def init_poolmanager(self, *args: Any, **kwargs: Any) -> None: + kwargs["ssl_context"] = self._ssl_context + kwargs.setdefault("socket_options", _KEEPALIVE_SOCKET_OPTIONS) + super().init_poolmanager(*args, **kwargs) # type: ignore[no-untyped-call] + + @override + def proxy_manager_for(self, proxy: str, **proxy_kwargs: Any) -> Any: + """Ensure proxy connections also strictly enforce TLS 1.2+ and TCP keep-alive. + + Returns: + Any: The proxy manager instance. + """ + proxy_kwargs["ssl_context"] = self._ssl_context + proxy_kwargs.setdefault("socket_options", _KEEPALIVE_SOCKET_OPTIONS) + return super().proxy_manager_for(proxy, **proxy_kwargs) # type: ignore[no-untyped-call] + + @override + def cert_verify(self, conn: Any, url: str, verify: Any, cert: Any) -> None: + """Enforce strict TLS verification and isolate per-call CA/client-cert SSL contexts.""" + resolved = resolve_tls_verify(verify) + super().cert_verify(conn, url, resolved, cert) # type: ignore[no-untyped-call] + if url.lower().startswith("https"): + needs_isolated_ctx = ( + cert is not None + or (isinstance(resolved, str) and resolved != self._ca_bundle) + or (resolved is True and self._ca_bundle is not None) + ) + if needs_isolated_ctx: + target_ca = resolved if isinstance(resolved, str) else None + conn.ssl_context = _build_tls_context(target_ca) + else: + conn.ssl_context = self._ssl_context + # Clear ca_certs/ca_cert_dir because conn.ssl_context already holds the exact trust store; + # otherwise urllib3 mutates the shared SSLContext on handshake. + conn.ca_certs = None + conn.ca_cert_dir = None + + +class SecretAuth(AuthBase): + """OWASP: Obfuscate credentials in memory dumps and tracebacks (CWE-316). + + Kept unslotted in 1.x because requests.auth.AuthBase defines no __slots__. + Pre-encodes the Basic Authorization header in __init__. + """ + + def __init__(self, auth_tuple: tuple[str, str]) -> None: + """Initialize with API credentials and pre-compute Basic Auth header.""" + __tracebackhide__ = True + self._api_key = auth_tuple[0] + self._api_secret = auth_tuple[1] + auth_bytes = f"{self._api_key}:{self._api_secret}".encode("latin1") + self._auth_header = "Basic " + base64.b64encode(auth_bytes).decode("ascii") + + def __call__(self, r: requests.PreparedRequest) -> requests.PreparedRequest: + """Apply pre-computed Basic Auth headers to the request. + + Returns: + requests.PreparedRequest: The modified request. + """ + __tracebackhide__ = True + r.headers["Authorization"] = self._auth_header + return r + + def __hash__(self) -> int: + """Hash the credentials for dictionary lookups. + + Returns: + int: The computed hash value. + """ + return hash((self._api_key, self._api_secret)) + + def __eq__(self, other: object) -> bool: + """Compare credentials in constant time using hmac.compare_digest. + + Returns: + bool: True if equal, False otherwise. + """ + if isinstance(other, SecretAuth): + other_key = other._api_key + other_secret = other._api_secret + elif isinstance(other, tuple) and len(other) == 2 and all(isinstance(item, str) for item in other): + other_key, other_secret = other + else: + return False + + key_match = hmac.compare_digest(self._api_key.encode("utf-8"), other_key.encode("utf-8")) + secret_match = hmac.compare_digest(self._api_secret.encode("utf-8"), other_secret.encode("utf-8")) + return bool(key_match & secret_match) + + def __getitem__(self, index: int) -> NoReturn: + """Prevent Credential extraction via tuple unpacking / indexing.""" + msg = "Credential extraction via indexing is blocked for security (CWE-316)." + raise TypeError(msg) + + def __iter__(self) -> Any: + """Prevent Credential extraction via iteration.""" + msg = "Credential extraction via iteration is blocked for security (CWE-316)." + raise TypeError(msg) + + def __repr__(self) -> str: + """Return a safe representation of the credential.""" + return "SecretAuth(***REDACTED***)" + + def __str__(self) -> str: + """Return a safe string representation of the credential.""" + return "SecretAuth(***REDACTED***)" diff --git a/mailjet_rest/utils/version.py b/mailjet_rest/utils/version.py index 9c5a4fd..62d26de 100644 --- a/mailjet_rest/utils/version.py +++ b/mailjet_rest/utils/version.py @@ -62,4 +62,4 @@ def get_version(version: tuple[int, ...] | None = None) -> str: if len(version) != 3: msg = "The tuple 'version' must contain 3 items" raise ValueError(msg) - return "{}.{}.{}".format(*(x for x in version)) + return f"{version[0]}.{version[1]}.{version[2]}" diff --git a/pyproject.toml b/pyproject.toml index de57c8b..d07b65a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -204,7 +204,10 @@ dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$" # Ignore E402 (import violations) in all '__init__.py' files, and in `path/to/file.py`. [tool.ruff.lint.per-file-ignores] -"__init__.py" = ["module-import-not-at-top-of-file"] # E402 +"__init__.py" = [ + "module-import-not-at-top-of-file", # E402 + "non-empty-init-module", # RUF067 (PEP 562 lazy exports) +] #"path/to/file.py" = ["E402"] [tool.ruff.lint.extend-per-file-ignores] diff --git a/tests/property/test_client_properties.py b/tests/property/test_client_properties.py index f0b1199..a349d9b 100644 --- a/tests/property/test_client_properties.py +++ b/tests/property/test_client_properties.py @@ -3,7 +3,7 @@ """ from typing import Any -from unittest.mock import MagicMock +from unittest.mock import MagicMock, patch import warnings from hypothesis import given, settings, strategies as st, example @@ -88,15 +88,14 @@ def test_property_api_call_resilience(method: Any, payload: Any, timeout: Any) - mock_resp = MagicMock() mock_resp.status_code = 200 - client._execute_request = MagicMock(return_value=mock_resp) # type: ignore[method-assign] + with patch.object(Client, "_execute_request", return_value=mock_resp) as mock_exec: + # API call must not crash on random standard payload variants + res = client.api_call( + method=method, url="https://api.mailjet.com/v3/test", headers={}, data=payload, timeout=timeout + ) + assert res.status_code == 200 - # API call must not crash on random standard payload variants - res = client.api_call( - method=method, url="https://api.mailjet.com/v3/test", headers={}, data=payload, timeout=timeout - ) - assert res.status_code == 200 - - # Ensure idempotency was calculated for valid dictionaries/lists during mutations - if method in {"POST", "PUT", "DELETE"} and isinstance(payload, (dict, list)): - call_args = client._execute_request.call_args[1] - assert "Idempotency-Key" in call_args["headers"] + # Ensure idempotency was calculated for valid dictionaries/lists during mutations + if method in {"POST", "PUT", "DELETE"} and isinstance(payload, (dict, list)): + call_args = mock_exec.call_args[1] + assert "Idempotency-Key" in call_args["headers"] diff --git a/tests/unit/test_boot_and_slots.py b/tests/unit/test_boot_and_slots.py new file mode 100644 index 0000000..ec275ca --- /dev/null +++ b/tests/unit/test_boot_and_slots.py @@ -0,0 +1,178 @@ +"""Unit tests for Wave 3: PEP 562 lazy boot, __slots__, SSL context cache, keep-alive, and warn_unclosed.""" + +from __future__ import annotations + +import gc +import json +import logging +import os +import socket +import ssl +import subprocess +import sys +import warnings +from pathlib import Path +from unittest.mock import MagicMock, patch + +import pytest +import requests + +from mailjet_rest.builders import ChunkedStreamer +from mailjet_rest.client import Client, Config +from mailjet_rest.utils.guardrails import RedactingFilter, SecretAuth, SecureHTTPAdapter, SecurityGuard +from mailjet_rest.utils.transport_security import _cached_ssl_context, get_secure_ssl_context + + +def test_pep562_lazy_top_level_import_isolation() -> None: + """Importing mailjet_rest does not eagerly load heavy transport or parser modules.""" + code = ( + "import json, sys, mailjet_rest; " + "heavy = ('requests', 'urllib3', 'ssl', 'html.parser', 'difflib', 'mimetypes'); " + "loaded = [m for m in heavy if m in sys.modules]; " + "print(json.dumps({'loaded': loaded, 'has_client': 'Client' in dir(mailjet_rest)}))" + ) + proc = subprocess.run( + [sys.executable, "-c", code], + capture_output=True, + text=True, + check=True, + timeout=15, + ) + payload = json.loads(proc.stdout) + assert payload["loaded"] == [] + assert payload["has_client"] is True + + +def test_package_lazy_exports_and_missing_attr() -> None: + """Top-level PEP 562 exposes Client, Config, __version__ and rejects unknown attributes.""" + import mailjet_rest # ruff: ignore[import-outside-top-level] + + assert mailjet_rest.Client is Client + assert mailjet_rest.Config is Config + assert isinstance(mailjet_rest.__version__, str) + assert "Client" in dir(mailjet_rest) + assert "__version__" in dir(mailjet_rest) + + with pytest.raises(AttributeError, match="no attribute"): + _ = mailjet_rest.non_existent_symbol_xyz # type: ignore[attr-defined] + + +def test_slots_enforced_and_secret_auth_unslotted() -> None: + """Client, ChunkedStreamer, and SecurityGuard use __slots__; SecretAuth stays unslotted.""" + client = Client(auth=("api_key_value", "api_secret_value")) + try: + assert not hasattr(client, "__dict__") + assert not hasattr(ChunkedStreamer(), "__dict__") + assert not hasattr(SecurityGuard(), "__dict__") + # SecretAuth inherits from requests.auth.AuthBase (unslotted in 1.x) + assert isinstance(client.auth, SecretAuth) + assert hasattr(client.auth, "__dict__") + finally: + client.close() + + +def test_lazy_session_and_pool_configuration() -> None: + """Client defers session creation until first use and applies Config pool sizes.""" + cfg = Config(pool_connections=12, pool_maxsize=24) + with Client(auth=("api_key_value", "api_secret_value"), config=cfg) as client: + assert client._session is None + _ = client.contact + assert client._session is None + + session = client.session + assert client._session is session + adapter = session.adapters["https://"] + assert isinstance(adapter, SecureHTTPAdapter) + pool_kw = adapter.poolmanager.connection_pool_kw + sock_opts = pool_kw.get("socket_options", ()) + assert (socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1) in sock_opts + + proxy_mgr = adapter.proxy_manager_for("http://127.0.0.1:8080") + assert (socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1) in proxy_mgr.connection_pool_kw.get("socket_options", ()) + + +def test_config_pool_and_warn_unclosed_validation() -> None: + """Config validates pool_connections, pool_maxsize, and warn_unclosed strictly.""" + with pytest.raises(ValueError, match="pool_connections"): + Config(pool_connections=0) + with pytest.raises(ValueError, match="pool_maxsize"): + Config(pool_maxsize=True) # type: ignore[arg-type] + with pytest.raises(TypeError, match="warn_unclosed"): + Config(warn_unclosed="yes") # type: ignore[arg-type] + + +def test_ssl_context_cache_and_rotation_invalidation(tmp_path: Path) -> None: + """get_secure_ssl_context caches identical inputs and reloads when CA file changes.""" + ca_file = tmp_path / "ca.pem" + ca_file.write_text("dummy-ca-v1", encoding="utf-8") + + fake_ctx_1 = MagicMock(spec=ssl.SSLContext) + fake_ctx_2 = MagicMock(spec=ssl.SSLContext) + _cached_ssl_context.cache_clear() + + with patch("ssl.create_default_context", side_effect=[fake_ctx_1, fake_ctx_2]) as mock_ctx: + ctx_a = get_secure_ssl_context(str(ca_file)) + ctx_b = get_secure_ssl_context(str(ca_file)) + assert ctx_a is fake_ctx_1 + assert ctx_b is fake_ctx_1 + assert mock_ctx.call_count == 1 + + # Simulate rotated CA bundle with different size and mtime + ca_file.write_text("dummy-ca-rotated-v2-longer", encoding="utf-8") + st = ca_file.stat() + os.utime(ca_file, ns=(st.st_atime_ns, st.st_mtime_ns + 1_000_000)) + + ctx_c = get_secure_ssl_context(str(ca_file)) + assert ctx_c is fake_ctx_2 + assert mock_ctx.call_count == 2 + + _cached_ssl_context.cache_clear() + + +def test_secret_auth_precomputes_authorization_header() -> None: + """SecretAuth pre-computes Basic Authorization header in __init__.""" + auth = SecretAuth(("my_key", "my_secret")) + assert auth._auth_header.startswith("Basic ") + req = requests.Request("GET", "https://api.mailjet.com/v3/REST/contact").prepare() + auth(req) + assert req.headers["Authorization"] == auth._auth_header + + +def test_redacting_filter_fast_path_and_secret_scrubbing() -> None: + """RedactingFilter skips regex compilation on clean messages and scrubs secrets when present.""" + flt = RedactingFilter() + clean_record = logging.LogRecord("mailjet_rest", logging.INFO, "", 0, "Sent campaign batch 42", (), None) + + with patch("mailjet_rest.utils.guardrails._get_secret_pattern", side_effect=AssertionError("should skip regex")): + assert flt.filter(clean_record) is True + assert clean_record.msg == "Sent campaign batch 42" + + secret_record = logging.LogRecord( + "mailjet_rest", + logging.INFO, + "", + 0, + "Using Authorization: Bearer supersecret99", + (), + None, + ) + assert flt.filter(secret_record) is True + assert "supersecret99" not in str(secret_record.msg) + assert "********" in str(secret_record.msg) + + +def test_warn_unclosed_opt_in_lifecycle() -> None: + """ResourceWarning is emitted on GC only when Config.warn_unclosed=True and session was opened.""" + with warnings.catch_warnings(record=True) as quiet_warnings: + warnings.simplefilter("always", ResourceWarning) + c_default = Client(auth=("api_key_value", "api_secret_value")) + _ = c_default.session + del c_default + gc.collect() + assert not [w for w in quiet_warnings if issubclass(w.category, ResourceWarning)] + + with pytest.warns(ResourceWarning, match="Unclosed Mailjet Client session"): + c_warn = Client(auth=("api_key_value", "api_secret_value"), warn_unclosed=True) + _ = c_warn.session + del c_warn + gc.collect() diff --git a/tests/unit/test_endpoint.py b/tests/unit/test_endpoint.py index fa0706d..375b413 100644 --- a/tests/unit/test_endpoint.py +++ b/tests/unit/test_endpoint.py @@ -227,12 +227,12 @@ def test_endpoint_call_deprecated_encoding_scalar_payload(monkeypatch: pytest.Mo client = Client(auth=("key", "secret")) endpoint = client.contact - def mock_api_call(*args: object, **kwargs: object) -> requests.Response: + def mock_api_call(self: object, *args: object, **kwargs: object) -> requests.Response: resp = requests.Response() resp.status_code = 200 return resp - monkeypatch.setattr(client, "api_call", mock_api_call) + monkeypatch.setattr(Client, "api_call", mock_api_call) with pytest.warns(DeprecationWarning, match="'ensure_ascii' and 'data_encoding' are deprecated"): # Passing string data instead of dict/list tests the branch fallback diff --git a/tests/unit/test_wave2_security.py b/tests/unit/test_wave2_security.py index f1f029a..bec6278 100644 --- a/tests/unit/test_wave2_security.py +++ b/tests/unit/test_wave2_security.py @@ -73,7 +73,7 @@ def test_custom_ca_bundle_isolated_context(tmp_path: Path) -> None: mock_ctx_default = MagicMock(spec=ssl.SSLContext) with patch( - "mailjet_rest.utils.guardrails._build_tls_context", + "mailjet_rest.utils.transport_security._build_tls_context", side_effect=[mock_ctx_one, mock_ctx_two, mock_ctx_default], ) as build_ctx: cfg = Config(verify=ca_one) @@ -129,24 +129,25 @@ def test_auto_idempotency_modes(monkeypatch: pytest.MonkeyPatch) -> None: """Verify fingerprint, uuid4, off, and case-insensitive header preservation.""" captured_headers: list[dict[str, Any]] = [] - def mock_exec(method: str, url: str, headers: dict[str, Any], *args: Any, **kwargs: Any) -> requests.Response: + def mock_exec( + self: Any, method: str, url: str, headers: dict[str, Any], *args: Any, **kwargs: Any + ) -> requests.Response: captured_headers.append(dict(headers)) r = requests.Response() r.status_code = 200 return r + monkeypatch.setattr(Client, "_execute_request", mock_exec) + client_uuid = Client(auth=("pub", "priv"), auto_idempotency_mode="uuid4") - monkeypatch.setattr(client_uuid, "_execute_request", mock_exec) client_uuid.api_call("POST", "https://api.mailjet.com/v3/REST/contact", data={"a": 1}) assert len(captured_headers[-1]["Idempotency-Key"]) == 36 client_off = Client(auth=("pub", "priv"), auto_idempotency_mode="off") - monkeypatch.setattr(client_off, "_execute_request", mock_exec) client_off.api_call("PATCH", "https://api.mailjet.com/v3/REST/contact", data={"a": 1}) assert "Idempotency-Key" not in captured_headers[-1] client_fp = Client(auth=("pub", "priv"), auto_idempotency_mode="fingerprint") - monkeypatch.setattr(client_fp, "_execute_request", mock_exec) client_fp.api_call( "POST", "https://api.mailjet.com/v3/REST/contact",