Skip to content

"Vibe-Trading: Your Personal Trading Agent"

8.4 KB
Raw Blame
"""Standalone email credential probe, split from ``email.py`` for size.

The probe validates a (possibly unsaved) IMAP + SMTP credential set without
touching the channel's polling loop or send path. Everything here is
stateless: functions take the ``EmailConfig`` explicitly so the module never
imports the adapter at runtime (only under ``TYPE_CHECKING``). Unlike the
token-endpoint probes (:mod:`src.channels.token_probe`), email is stdlib-only
(``imaplib`` / ``smtplib``), so ``sdk_available`` is always True and the
blocking transports are driven through :func:`asyncio.to_thread`.

Classification mirrors the adapter's own transport semantics
(:meth:`EmailChannel._open_imap_client` and :meth:`EmailChannel._smtp_send`):

- IMAP: ``imap_use_ssl`` → ``IMAP4_SSL`` else ``IMAP4`` + ``starttls`` when
  ``imap_use_tls``; a connect or upgrade failure is
  ``network``, a rejected login is ``invalid_credentials``, and a mailbox
  that cannot be selected is ``invalid_credentials`` naming the mailbox.
- SMTP: ``smtp_use_ssl`` → ``SMTP_SSL`` else ``SMTP`` + ``starttls`` when
  ``smtp_use_tls``; an authentication rejection is ``invalid_credentials``,
  every other transport failure is ``network``.

Details are prefixed with the failing side (``imap:`` / ``smtp:``), bounded to
200 characters and scrubbed of both the password and the username, so a
server that echoes the credential in its rejection never leaks it into a
result envelope or a log line.
"""

from __future__ import annotations

import asyncio
import contextlib
import imaplib
import smtplib
from collections.abc import Iterable
from typing import TYPE_CHECKING, Any

from src.channels.token_probe import scrub_secrets
from src.channels.utils import email_tls_context, send_imap_id

if TYPE_CHECKING:
    from src.channels.email import EmailConfig

_CONNECT_TIMEOUT_S = 10
_DETAIL_LIMIT = 200

# Bound at import: ``imaplib.IMAP4.error`` is a stable exception class
# (``.abort`` is a subclass), and resolving it through the ``IMAP4`` attribute
# at call time would break whenever the class itself is replaced (tests).
_IMAP4_ERROR = imaplib.IMAP4.error

_CREDENTIAL_FIELDS = (
    "imap_host",
    "imap_username",
    "imap_password",
    "smtp_host",
    "smtp_username",
    "smtp_password",
)


def _bounded(side: str, exc: BaseException, secrets: Iterable[str]) -> str:
    """Return a scrubbed, bounded ``<side>: <error>`` detail string."""
    text = str(exc) or type(exc).__name__
    return scrub_secrets(f"{side}: {text}", secrets)[:_DETAIL_LIMIT]


def _select_reason(status: str, data: Any) -> str:
    """Extract a human-readable reason from an IMAP ``select`` response."""
    if isinstance(data, (list, tuple)):
        for item in data:
            if isinstance(item, (bytes, bytearray)) and item.strip():
                return bytes(item).decode("utf-8", errors="replace").strip()
            if isinstance(item, str) and item.strip():
                return item.strip()
    return status


def _probe_imap(config: EmailConfig) -> tuple[str, str] | None:
    """Login + mailbox-select over IMAP; return ``(code, detail)`` or None."""
    secrets = (config.imap_password, config.imap_username)
    mailbox = config.imap_mailbox or "INBOX"
    client: imaplib.IMAP4 | None = None
    try:
        try:
            if config.imap_use_ssl:
                client = imaplib.IMAP4_SSL(
                    config.imap_host,
                    config.imap_port,
                    timeout=_CONNECT_TIMEOUT_S,
                    ssl_context=email_tls_context(config.verify_tls),
                )
            else:
                client = imaplib.IMAP4(
                    config.imap_host, config.imap_port, timeout=_CONNECT_TIMEOUT_S
                )
                if config.imap_use_tls:
                    client.starttls(ssl_context=email_tls_context(config.verify_tls))
        except (OSError, _IMAP4_ERROR) as exc:
            # A transport that cannot be established or upgraded (no STARTTLS
            # offered, a failed handshake) is network-class, as for SMTP.
            return "network", _bounded("imap", exc, secrets)

        try:
            client.login(config.imap_username, config.imap_password)
        except _IMAP4_ERROR as exc:  # IMAP4.abort is a subclass
            return "invalid_credentials", _bounded("imap", exc, secrets)
        except OSError as exc:
            return "network", _bounded("imap", exc, secrets)

        # NetEase requires an IMAP ID before SELECT; harmless elsewhere.
        send_imap_id(client)

        try:
            status, data = client.select(mailbox)
        except Exception as exc:  # noqa: BLE001 - any select failure names the mailbox
            reason = str(exc) or type(exc).__name__
            detail = f"imap mailbox select failed: {mailbox} ({reason})"
            return "invalid_credentials", scrub_secrets(detail, secrets)[:_DETAIL_LIMIT]
        if status != "OK":
            detail = f"imap mailbox select failed: {mailbox} ({_select_reason(status, data)})"
            return "invalid_credentials", scrub_secrets(detail, secrets)[:_DETAIL_LIMIT]
    finally:
        if client is not None:
            with contextlib.suppress(Exception):
                client.logout()
    return None


def _probe_smtp(config: EmailConfig) -> tuple[str, str] | None:
    """Connect (+ optional STARTTLS) and login over SMTP; ``(code, detail)`` or None."""
    secrets = (config.smtp_password, config.smtp_username)
    client: smtplib.SMTP | None = None
    try:
        try:
            if config.smtp_use_ssl:
                client = smtplib.SMTP_SSL(
                    config.smtp_host,
                    config.smtp_port,
                    timeout=_CONNECT_TIMEOUT_S,
                    ssl_context=email_tls_context(config.verify_tls),
                )
            else:
                client = smtplib.SMTP(
                    config.smtp_host, config.smtp_port, timeout=_CONNECT_TIMEOUT_S
                )
                if config.smtp_use_tls:
                    client.starttls(context=email_tls_context(config.verify_tls))
        except (smtplib.SMTPException, OSError) as exc:
            # Covers SMTPConnectError / SMTPServerDisconnected / socket.timeout;
            # a transport that cannot be established or upgraded is network-class.
            return "network", _bounded("smtp", exc, secrets)

        try:
            client.login(config.smtp_username, config.smtp_password)
        except smtplib.SMTPAuthenticationError as exc:
            return "invalid_credentials", _bounded("smtp", exc, secrets)
        except (smtplib.SMTPException, OSError) as exc:
            return "network", _bounded("smtp", exc, secrets)
    finally:
        if client is not None:
            with contextlib.suppress(Exception):
                client.quit()
    return None


async def test_connection(config: EmailConfig) -> dict[str, Any]:
    """Validate the email credentials with standalone IMAP + SMTP probes.

    Uses fresh ``imaplib`` / ``smtplib`` connections rather than the channel's
    polling loop (which only exists after :meth:`EmailChannel.start`), so an
    unsaved credential set can be checked before the channel is started. The
    SMTP half runs only after the IMAP half passes, and no message is ever
    sent: the probe logs in and selects a mailbox, nothing more.

    Args:
        config: The email credential set to validate.

    Returns:
        A JSON-serializable envelope with ``ok`` and a ``code`` of ``ok`` /
        ``invalid_credentials`` / ``network``, plus ``sdk_available`` (always
        True — the probe is stdlib-only). Any ``detail`` is bounded to 200
        characters and scrubbed of credential values.
    """
    missing = [field for field in _CREDENTIAL_FIELDS if not getattr(config, field)]
    if missing:
        # Field NAMES are not secrets; naming them tells the operator exactly
        # which half (IMAP/SMTP) of the six-field credential set is incomplete.
        return {
            "ok": False,
            "code": "invalid_credentials",
            "detail": "missing credentials: " + ", ".join(missing),
            "sdk_available": True,
        }

    failure = await asyncio.to_thread(_probe_imap, config)
    if failure is None:
        failure = await asyncio.to_thread(_probe_smtp, config)
    if failure is not None:
        code, detail = failure
        return {"ok": False, "code": code, "detail": detail, "sdk_available": True}
    return {"ok": True, "code": "ok", "sdk_available": True}