feat: add security-variant integration tests with defensive IMAP cleanup

Add TLS and STARTTLS integration tests across all tiers:
- 16 new security tests (Tier 1): Implicit TLS IMAP/SMTP, STARTTLS SMTP,
  security mismatch detection, verify_ssl rejection of self-signed certs
- 3 new TLS Docker roundtrip tests (Tier 2): SMTPS/IMAPS end-to-end
- Self-signed certificate generation fixture (cryptography library)
- TLS-aware SMTP/IMAP fixtures for both tiers

Add defensive IMAP resource cleanup in test_imap_connection():
- _force_close_imap() helper closes transport and cancels _client_task
- Prevents leaked connections when IMAP operations fail or time out
- Workaround for aioimaplib#128 (tasks ignore asyncio cancellation)

Blocked tests (commented out with issue references):
- IMAP mismatch: plaintext-on-TLS + verify_ssl rejection (aioimaplib#128)
- Docker STARTTLS roundtrip: GreenMail lacks STARTTLS support (greenmail#135)

Update dependency versions: cryptography>=44.0.0 added to integration group.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Colin

Makefile

@@ -40,8 +40,25 @@ build: clean-build ## Build wheel file
 
 .PHONY: clean-build
 clean-build: ## Clean build artifacts
-	@echo "🚀 Removing build artifacts"
-	@uv run python -c "import shutil; import os; shutil.rmtree('dist') if os.path.exists('dist') else None"
+	@rm -rf dist build *.egg-info
+
+.PHONY: clean
+clean: clean-build ## Remove build, test, and cache artifacts
+	@find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+	@find . -type f -name "*.py[co]" -delete 2>/dev/null || true
+	@rm -rf .pytest_cache .coverage coverage.xml htmlcov .mypy_cache .ruff_cache .hypothesis
+	@echo "✨ Clean complete"
+
+.PHONY: clean-docker
+clean-docker: ## Stop and remove Docker test containers and volumes
+	@echo "🐳 Cleaning Docker test environment"
+	@docker compose -f tests/docker/docker-compose.yml down -v --remove-orphans 2>/dev/null || true
+	@echo "✨ Docker clean complete"
+
+.PHONY: clean-all
+clean-all: clean clean-docker ## Remove all artifacts including tox, docs, and Docker
+	@rm -rf .tox .nox site
+	@echo "✨ Deep clean complete"
 
 .PHONY: publish
 publish: ## Publish a release to PyPI.

mcp_email_server/emails/classic.py

@@ -166,8 +166,30 @@ async def _create_imap_connection(
     return imap
 
 
+def _force_close_imap(imap: aioimaplib.IMAP4 | aioimaplib.IMAP4_SSL) -> None:
+    """Force-close an IMAP connection's transport and cancel internal tasks.
+
+    Defensive cleanup for aioimaplib connections that may not shut down cleanly
+    after logout(). aioimaplib's _client_task and transport do not support
+    asyncio cancellation properly.
+    See: https://github.com/iroco-co/aioimaplib/issues/128
+    """
+    with contextlib.suppress(Exception):
+        if (
+            hasattr(imap, "protocol")
+            and imap.protocol
+            and hasattr(imap.protocol, "transport")
+            and imap.protocol.transport
+        ):
+            imap.protocol.transport.close()
+    with contextlib.suppress(Exception):
+        if hasattr(imap, "_client_task") and not imap._client_task.done():
+            imap._client_task.cancel()
+
+
 async def test_imap_connection(server: EmailServer, timeout: int = 10) -> str:
     """Test IMAP connection and login. Returns a user-friendly status message."""
+    imap = None
     try:
         imap = await asyncio.wait_for(_create_imap_connection(server), timeout=timeout)
         try:
@@ -190,6 +212,9 @@ async def test_imap_connection(server: EmailServer, timeout: int = 10) -> str:
         return f"❌ IMAP error: {e}"
     except Exception as e:
         return f"❌ IMAP error: {e}"
+    finally:
+        if imap is not None:
+            _force_close_imap(imap)
 
 
 async def test_smtp_connection(server: EmailServer, timeout: int = 10) -> str:

pyproject.toml

@@ -52,11 +52,12 @@ dev = [
     "mkdocstrings[python]>=0.26.1",
 ]
 integration = [
-    "pytest-localserver>=0.9.0",
-    "aiosmtpd>=1.4.0",
+    "pytest-localserver>=0.10.0",
+    "aiosmtpd>=1.4.6",
+    "cryptography>=44.0.0",
 ]
 docker = [
-    "pytest-docker>=3.1.0",
+    "pytest-docker>=3.2.5",
 ]
 
 [build-system]

tests/docker/conftest.py

@@ -1,7 +1,12 @@
 """Fixtures for Docker-based integration tests (Tier 2).
 
-GreenMail provides a real SMTP+IMAP server for full send→read roundtrip tests.
+GreenMail provides a real SMTP+IMAP server for full send/read roundtrip tests.
 Tests auto-skip if Docker is not available.
+
+Security modes tested:
+- NONE:     SMTP port 3025, IMAP port 3143 (plaintext)
+- TLS:      SMTPS port 3465, IMAPS port 3993 (Implicit TLS, self-signed)
+- STARTTLS: skipped (greenmail#135 — GreenMail does not support STARTTLS)
 """
 
 from __future__ import annotations
@@ -20,6 +25,8 @@
 
 GREENMAIL_SMTP_PORT = 3025
 GREENMAIL_IMAP_PORT = 3143
+GREENMAIL_SMTPS_PORT = 3465
+GREENMAIL_IMAPS_PORT = 3993
 
 
 def pytest_collection_modifyitems(config, items):
@@ -59,6 +66,12 @@ def _greenmail_is_ready() -> bool:
         # Test IMAP socket
         with socket.create_connection(("127.0.0.1", GREENMAIL_IMAP_PORT), timeout=3):
             pass
+        # Test SMTPS socket (TLS port)
+        with socket.create_connection(("127.0.0.1", GREENMAIL_SMTPS_PORT), timeout=3):
+            pass
+        # Test IMAPS socket (TLS port)
+        with socket.create_connection(("127.0.0.1", GREENMAIL_IMAPS_PORT), timeout=3):
+            pass
         return True
     except Exception:
         return False
@@ -77,14 +90,21 @@ def greenmail(docker_services):
         "smtp_port": GREENMAIL_SMTP_PORT,
         "imap_host": "127.0.0.1",
         "imap_port": GREENMAIL_IMAP_PORT,
+        "smtps_port": GREENMAIL_SMTPS_PORT,
+        "imaps_port": GREENMAIL_IMAPS_PORT,
         "user": GREENMAIL_USER,
         "password": GREENMAIL_PASSWORD,
     }
 
 
+# ---------------------------------------------------------------------------
+# Plaintext (NONE) fixtures
+# ---------------------------------------------------------------------------
+
+
 @pytest.fixture()
 def greenmail_smtp_server(greenmail) -> EmailServer:
-    """EmailServer config for GreenMail SMTP."""
+    """EmailServer config for GreenMail SMTP (plaintext)."""
     return EmailServer(
         host=greenmail["smtp_host"],
         port=greenmail["smtp_port"],
@@ -97,7 +117,7 @@ def greenmail_smtp_server(greenmail) -> EmailServer:
 
 @pytest.fixture()
 def greenmail_imap_server(greenmail) -> EmailServer:
-    """EmailServer config for GreenMail IMAP."""
+    """EmailServer config for GreenMail IMAP (plaintext)."""
     return EmailServer(
         host=greenmail["imap_host"],
         port=greenmail["imap_port"],
@@ -110,11 +130,105 @@ def greenmail_imap_server(greenmail) -> EmailServer:
 
 @pytest.fixture()
 def greenmail_smtp_client(greenmail_smtp_server) -> EmailClient:
-    """EmailClient wired to GreenMail SMTP."""
+    """EmailClient wired to GreenMail SMTP (plaintext)."""
     return EmailClient(greenmail_smtp_server, sender=GREENMAIL_USER)
 
 
 @pytest.fixture()
 def greenmail_imap_client(greenmail_imap_server) -> EmailClient:
-    """EmailClient wired to GreenMail IMAP."""
+    """EmailClient wired to GreenMail IMAP (plaintext)."""
     return EmailClient(greenmail_imap_server, sender=GREENMAIL_USER)
+
+
+# ---------------------------------------------------------------------------
+# Implicit TLS fixtures (SMTPS / IMAPS)
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture()
+def greenmail_smtps_server(greenmail) -> EmailServer:
+    """EmailServer config for GreenMail SMTPS (Implicit TLS)."""
+    return EmailServer(
+        host=greenmail["smtp_host"],
+        port=greenmail["smtps_port"],
+        user_name=greenmail["user"],
+        password=greenmail["password"],
+        security=ConnectionSecurity.TLS,
+        verify_ssl=False,
+    )
+
+
+@pytest.fixture()
+def greenmail_imaps_server(greenmail) -> EmailServer:
+    """EmailServer config for GreenMail IMAPS (Implicit TLS)."""
+    return EmailServer(
+        host=greenmail["imap_host"],
+        port=greenmail["imaps_port"],
+        user_name=greenmail["user"],
+        password=greenmail["password"],
+        security=ConnectionSecurity.TLS,
+        verify_ssl=False,
+    )
+
+
+@pytest.fixture()
+def greenmail_smtps_client(greenmail_smtps_server) -> EmailClient:
+    """EmailClient wired to GreenMail SMTPS (Implicit TLS)."""
+    return EmailClient(greenmail_smtps_server, sender=GREENMAIL_USER)
+
+
+@pytest.fixture()
+def greenmail_imaps_client(greenmail_imaps_server) -> EmailClient:
+    """EmailClient wired to GreenMail IMAPS (Implicit TLS)."""
+    return EmailClient(greenmail_imaps_server, sender=GREENMAIL_USER)
+
+
+# Note: GreenMail does not support STARTTLS on plaintext ports.
+# See https://github.com/greenmail-mail-test/greenmail/issues/135
+# STARTTLS is tested at Tier 1 (SMTP via aiosmtpd) and unit tests (IMAP).
+
+
+# ---------------------------------------------------------------------------
+# STARTTLS fixtures (upgrade on plaintext ports)
+# TODO(greenmail#135): GreenMail does not advertise STARTTLS on plaintext ports.
+# These fixtures are kept for when GreenMail adds STARTTLS support.
+# See: https://github.com/greenmail-mail-test/greenmail/issues/135
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture()
+def greenmail_smtp_starttls_server(greenmail) -> EmailServer:
+    """EmailServer config for GreenMail SMTP with STARTTLS."""
+    return EmailServer(
+        host=greenmail["smtp_host"],
+        port=greenmail["smtp_port"],
+        user_name=greenmail["user"],
+        password=greenmail["password"],
+        security=ConnectionSecurity.STARTTLS,
+        verify_ssl=False,
+    )
+
+
+@pytest.fixture()
+def greenmail_imap_starttls_server(greenmail) -> EmailServer:
+    """EmailServer config for GreenMail IMAP with STARTTLS."""
+    return EmailServer(
+        host=greenmail["imap_host"],
+        port=greenmail["imap_port"],
+        user_name=greenmail["user"],
+        password=greenmail["password"],
+        security=ConnectionSecurity.STARTTLS,
+        verify_ssl=False,
+    )
+
+
+@pytest.fixture()
+def greenmail_smtp_starttls_client(greenmail_smtp_starttls_server) -> EmailClient:
+    """EmailClient wired to GreenMail SMTP with STARTTLS."""
+    return EmailClient(greenmail_smtp_starttls_server, sender=GREENMAIL_USER)
+
+
+@pytest.fixture()
+def greenmail_imap_starttls_client(greenmail_imap_starttls_server) -> EmailClient:
+    """EmailClient wired to GreenMail IMAP with STARTTLS."""
+    return EmailClient(greenmail_imap_starttls_server, sender=GREENMAIL_USER)