read-no-evil-mcp 0.2.0__py3-none-any.whl

read_no_evil_mcp/mailbox.py

@@ -0,0 +1,329 @@
+"""Secure mailbox with prompt injection protection and permission enforcement."""
+
+from datetime import date, timedelta
+from types import TracebackType
+
+from read_no_evil_mcp.accounts.permissions import AccountPermissions
+from read_no_evil_mcp.email.connectors.base import BaseConnector
+from read_no_evil_mcp.exceptions import PermissionDeniedError
+from read_no_evil_mcp.models import Email, EmailSummary, Folder, ScanResult
+from read_no_evil_mcp.protection.service import ProtectionService
+
+
+class PromptInjectionError(Exception):
+    """Raised when prompt injection is detected in email content."""
+
+    def __init__(self, scan_result: ScanResult, email_uid: int, folder: str) -> None:
+        self.scan_result = scan_result
+        self.email_uid = email_uid
+        self.folder = folder
+        patterns = ", ".join(scan_result.detected_patterns)
+        super().__init__(
+            f"Prompt injection detected in email {folder}/{email_uid}. "
+            f"Detected patterns: {patterns}"
+        )
+
+
+class SecureMailbox:
+    """Secure email access with prompt injection protection and permission enforcement.
+
+    Wraps a BaseConnector and scans email content before returning it.
+    Blocks emails that contain detected prompt injection attacks.
+    Enforces account permissions on all operations.
+    """
+
+    def __init__(
+        self,
+        connector: BaseConnector,
+        permissions: AccountPermissions,
+        protection: ProtectionService | None = None,
+        from_address: str | None = None,
+        from_name: str | None = None,
+    ) -> None:
+        """Initialize secure mailbox.
+
+        Args:
+            connector: Email connector for fetching and optionally sending emails.
+            permissions: Account permissions to enforce.
+            protection: Protection service for scanning. Defaults to standard service.
+            from_address: Sender email address for outgoing emails (e.g., "user@example.com").
+            from_name: Optional display name for sender (e.g., "Atlas").
+        """
+        self._connector = connector
+        self._permissions = permissions
+        self._protection = protection or ProtectionService()
+        self._from_address = from_address
+        self._from_name = from_name
+
+    def _require_read(self) -> None:
+        """Check if read access is allowed.
+
+        Raises:
+            PermissionDeniedError: If read access is denied.
+        """
+        if not self._permissions.read:
+            raise PermissionDeniedError("Read access denied for this account")
+
+    def _require_folder(self, folder: str) -> None:
+        """Check if access to a specific folder is allowed.
+
+        Args:
+            folder: The folder name to check access for.
+
+        Raises:
+            PermissionDeniedError: If access to the folder is denied.
+        """
+        if self._permissions.folders is not None and folder not in self._permissions.folders:
+            raise PermissionDeniedError(f"Access to folder '{folder}' denied")
+
+    def _require_move(self) -> None:
+        """Check if move access is allowed.
+
+        Raises:
+            PermissionDeniedError: If move access is denied.
+        """
+        if not self._permissions.move:
+            raise PermissionDeniedError("Move access denied for this account")
+
+    def _filter_allowed_folders(self, folders: list[Folder]) -> list[Folder]:
+        """Filter folders to only include those allowed by permissions.
+
+        Args:
+            folders: List of folders to filter.
+
+        Returns:
+            List of folders that are allowed by permissions.
+        """
+        if self._permissions.folders is None:
+            return folders
+        return [f for f in folders if f.name in self._permissions.folders]
+
+    def _require_send(self) -> None:
+        """Check if send access is allowed.
+
+        Raises:
+            PermissionDeniedError: If send access is denied.
+        """
+        if not self._permissions.send:
+            raise PermissionDeniedError("Send access denied for this account")
+
+    def connect(self) -> None:
+        """Connect to the email server."""
+        self._connector.connect()
+
+    def disconnect(self) -> None:
+        """Disconnect from the email server."""
+        self._connector.disconnect()
+
+    def __enter__(self) -> "SecureMailbox":
+        """Enter context manager, connecting to the server."""
+        self.connect()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        """Exit context manager, disconnecting from the server."""
+        self.disconnect()
+
+    def list_folders(self) -> list[Folder]:
+        """List all available folders.
+
+        Returns:
+            List of Folder objects.
+
+        Raises:
+            PermissionDeniedError: If read access is denied.
+        """
+        self._require_read()
+        folders = self._connector.list_folders()
+        return self._filter_allowed_folders(folders)
+
+    def _scan_summary(self, summary: EmailSummary) -> ScanResult:
+        """Scan email summary fields for prompt injection.
+
+        Args:
+            summary: Email summary to scan.
+
+        Returns:
+            ScanResult from scanning subject and sender.
+        """
+        parts: list[str] = [summary.subject]
+
+        if summary.sender.name:
+            parts.append(summary.sender.name)
+        parts.append(summary.sender.address)
+
+        combined = "\n".join(parts)
+        return self._protection.scan(combined)
+
+    def fetch_emails(
+        self,
+        folder: str = "INBOX",
+        *,
+        lookback: timedelta,
+        from_date: date | None = None,
+        limit: int | None = None,
+    ) -> list[EmailSummary]:
+        """Fetch email summaries from a folder with protection scanning.
+
+        Scans subject and sender fields for prompt injection.
+        Emails with detected attacks are filtered out.
+
+        Args:
+            folder: Folder to fetch from (default: INBOX)
+            lookback: How far back to look
+            from_date: Starting point for lookback (default: today)
+            limit: Maximum number of emails to return
+
+        Returns:
+            List of safe EmailSummary objects, newest first.
+
+        Raises:
+            PermissionDeniedError: If read access is denied or folder is not allowed.
+        """
+        self._require_read()
+        self._require_folder(folder)
+
+        summaries = self._connector.fetch_emails(
+            folder,
+            lookback=lookback,
+            from_date=from_date,
+            limit=limit,
+        )
+
+        safe_summaries: list[EmailSummary] = []
+        for summary in summaries:
+            scan_result = self._scan_summary(summary)
+            if not scan_result.is_blocked:
+                safe_summaries.append(summary)
+
+        return safe_summaries
+
+    def get_email(self, folder: str, uid: int) -> Email | None:
+        """Get full email content by UID with protection scanning.
+
+        Scans email content for prompt injection attacks before returning.
+
+        Args:
+            folder: Folder containing the email
+            uid: Unique identifier of the email
+
+        Returns:
+            Full Email object or None if not found.
+
+        Raises:
+            PermissionDeniedError: If read access is denied or folder is not allowed.
+            PromptInjectionError: If prompt injection is detected.
+        """
+        self._require_read()
+        self._require_folder(folder)
+
+        email = self._connector.get_email(folder, uid)
+
+        if email is None:
+            return None
+
+        # Build content to scan: subject, sender, body
+        parts: list[str] = [email.subject]
+
+        if email.sender.name:
+            parts.append(email.sender.name)
+        parts.append(email.sender.address)
+
+        if email.body_plain:
+            parts.append(email.body_plain)
+        if email.body_html:
+            parts.append(email.body_html)
+
+        combined = "\n".join(parts)
+        scan_result = self._protection.scan(combined)
+
+        if scan_result.is_blocked:
+            raise PromptInjectionError(scan_result, uid, folder)
+
+        return email
+
+    def send_email(
+        self,
+        to: list[str],
+        subject: str,
+        body: str,
+        cc: list[str] | None = None,
+        reply_to: str | None = None,
+    ) -> bool:
+        """Send an email.
+
+        Args:
+            to: List of recipient email addresses.
+            subject: Email subject line.
+            body: Email body text (plain text).
+            cc: Optional list of CC recipients.
+            reply_to: Optional Reply-To email address.
+
+        Returns:
+            True if email was sent successfully.
+
+        Raises:
+            PermissionDeniedError: If send access is denied.
+            RuntimeError: If sending is not supported by the connector.
+        """
+        self._require_send()
+
+        if not self._connector.can_send():
+            raise RuntimeError("Sending not configured for this account")
+
+        if not self._from_address:
+            raise RuntimeError("From address not configured for this account")
+
+        return self._connector.send(
+            from_address=self._from_address,
+            to=to,
+            subject=subject,
+            body=body,
+            from_name=self._from_name,
+            cc=cc,
+            reply_to=reply_to,
+        )
+
+    def move_email(self, folder: str, uid: int, target_folder: str) -> bool:
+        """Move an email to a target folder.
+
+        Args:
+            folder: Folder containing the email
+            uid: Unique identifier of the email
+            target_folder: Destination folder to move the email to
+
+        Returns:
+            True if successful, False if email not found.
+
+        Raises:
+            PermissionDeniedError: If move access is denied or folder is not allowed.
+        """
+        self._require_move()
+        self._require_folder(folder)
+        self._require_folder(target_folder)
+
+        return self._connector.move_email(folder, uid, target_folder)
+
+    def delete_email(self, folder: str, uid: int) -> bool:
+        """Delete an email by UID.
+
+        Args:
+            folder: Folder containing the email
+            uid: Unique identifier of the email
+
+        Returns:
+            True if email was deleted successfully, False otherwise.
+
+        Raises:
+            PermissionDeniedError: If delete access is denied or folder is not allowed.
+        """
+        if not self._permissions.delete:
+            raise PermissionDeniedError("Delete access denied for this account")
+        self._require_folder(folder)
+
+        return self._connector.delete_email(folder, uid)

read_no_evil_mcp/models.py

@@ -0,0 +1,88 @@
+"""Data models for read-no-evil-mcp."""
+
+from datetime import datetime
+
+from pydantic import BaseModel, SecretStr
+
+
+class IMAPConfig(BaseModel):
+    """IMAP server configuration."""
+
+    host: str
+    port: int = 993
+    username: str
+    password: SecretStr
+    ssl: bool = True
+
+
+class SMTPConfig(BaseModel):
+    """SMTP server configuration."""
+
+    host: str
+    port: int = 587
+    username: str
+    password: SecretStr
+    ssl: bool = False  # False = use STARTTLS, True = use SSL
+
+
+class EmailAddress(BaseModel):
+    """Parsed email address with optional display name."""
+
+    name: str | None = None
+    address: str
+
+    def __str__(self) -> str:
+        if self.name:
+            return f"{self.name} <{self.address}>"
+        return self.address
+
+
+class Folder(BaseModel):
+    """IMAP folder/mailbox."""
+
+    name: str
+    delimiter: str = "/"
+    flags: list[str] = []
+
+
+class Attachment(BaseModel):
+    """Email attachment metadata (content not included)."""
+
+    filename: str
+    content_type: str
+    size: int | None = None
+
+
+class EmailSummary(BaseModel):
+    """Lightweight email representation for list views."""
+
+    uid: int
+    folder: str
+    subject: str
+    sender: EmailAddress
+    date: datetime
+    has_attachments: bool = False
+
+
+class Email(EmailSummary):
+    """Full email content."""
+
+    to: list[EmailAddress] = []
+    cc: list[EmailAddress] = []
+    body_plain: str | None = None
+    body_html: str | None = None
+    attachments: list[Attachment] = []
+    message_id: str | None = None
+
+
+class ScanResult(BaseModel):
+    """Result of scanning content for prompt injection attacks."""
+
+    is_safe: bool
+    score: float  # 0.0 = safe, 1.0 = definitely malicious
+    detected_patterns: list[str] = []
+
+    @property
+    def is_blocked(self) -> bool:
+        """Return True if content should be blocked."""
+        return not self.is_safe

read_no_evil_mcp/protection/__init__.py

@@ -0,0 +1,6 @@
+"""Protection service for prompt injection detection."""
+
+from read_no_evil_mcp.protection.heuristic import HeuristicScanner
+from read_no_evil_mcp.protection.service import ProtectionService
+
+__all__ = ["HeuristicScanner", "ProtectionService"]

read_no_evil_mcp/protection/heuristic.py

@@ -0,0 +1,82 @@
+"""Heuristic scanner for prompt injection detection.
+
+Uses the ProtectAI DeBERTa model with PyTorch for ML-based
+prompt injection detection.
+"""
+
+from typing import Any
+
+import structlog
+from transformers import Pipeline, pipeline
+
+from read_no_evil_mcp.models import ScanResult
+
+logger = structlog.get_logger()
+
+# Model for prompt injection detection
+MODEL_ID = "protectai/deberta-v3-base-prompt-injection-v2"
+
+
+class HeuristicScanner:
+    """Scanner for prompt injection detection using ProtectAI's DeBERTa model."""
+
+    def __init__(self, threshold: float = 0.5) -> None:
+        """Initialize scanner with the prompt injection detection model.
+
+        Args:
+            threshold: Detection threshold (0.0-1.0). Scores above this are
+                considered prompt injection. Defaults to 0.5.
+        """
+        self._threshold = threshold
+        self._classifier: Pipeline | None = None  # Lazy load
+
+    def _get_classifier(self) -> Any:
+        """Lazy load the classifier to avoid slow startup."""
+        if self._classifier is None:
+            logger.debug("Loading prompt injection model", model=MODEL_ID)
+            self._classifier = pipeline(
+                "text-classification",
+                model=MODEL_ID,
+                truncation=True,
+                max_length=512,
+            )
+            logger.debug("Model loaded successfully")
+        return self._classifier
+
+    def scan(self, content: str) -> ScanResult:
+        """Scan content for prompt injection patterns.
+
+        Args:
+            content: Text content to scan.
+
+        Returns:
+            ScanResult with detection details.
+        """
+        if not content:
+            return ScanResult(
+                is_safe=True,
+                score=0.0,
+                detected_patterns=[],
+            )
+
+        classifier = self._get_classifier()
+        result = classifier(content)[0]
+
+        # Model returns label "INJECTION" or "SAFE" with a score
+        is_injection = result["label"] == "INJECTION"
+        score: float = result["score"] if is_injection else 1.0 - result["score"]
+
+        is_safe = score < self._threshold
+        detected_patterns: list[str] = []
+
+        if not is_safe:
+            detected_patterns.append("prompt_injection")
+            logger.warning("Detected prompt injection", injection_score=score)
+        else:
+            logger.debug("No prompt injection detected", highest_score=score)
+
+        return ScanResult(
+            is_safe=is_safe,
+            score=score,
+            detected_patterns=detected_patterns,
+        )

read_no_evil_mcp/protection/service.py

@@ -0,0 +1,110 @@
+"""Protection service for orchestrating security scanning."""
+
+import re
+from html.parser import HTMLParser
+
+from read_no_evil_mcp.models import ScanResult
+from read_no_evil_mcp.protection.heuristic import HeuristicScanner
+
+
+class _HTMLTextExtractor(HTMLParser):
+    """Extract plain text from HTML content."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._text_parts: list[str] = []
+
+    def handle_data(self, data: str) -> None:
+        self._text_parts.append(data)
+
+    def get_text(self) -> str:
+        return " ".join(self._text_parts)
+
+
+def strip_html_tags(html: str) -> str:
+    """Strip HTML tags and return plain text content.
+
+    Args:
+        html: HTML content to strip.
+
+    Returns:
+        Plain text extracted from HTML.
+    """
+    parser = _HTMLTextExtractor()
+    parser.feed(html)
+    text = parser.get_text()
+    # Normalize whitespace
+    return re.sub(r"\s+", " ", text).strip()
+
+
+class ProtectionService:
+    """Orchestrates content scanning for prompt injection attacks.
+
+    Delegates to HeuristicScanner which uses ProtectAI's DeBERTa model
+    for ML-based prompt injection detection.
+    """
+
+    def __init__(self, scanner: HeuristicScanner | None = None) -> None:
+        """Initialize the protection service.
+
+        Args:
+            scanner: Heuristic scanner to use. Defaults to standard scanner.
+        """
+        self._scanner = scanner or HeuristicScanner()
+
+    def scan(self, content: str) -> ScanResult:
+        """Scan content for prompt injection attacks.
+
+        Automatically strips HTML tags if content contains HTML markup.
+
+        Args:
+            content: Text content to scan (email body, subject, etc.)
+
+        Returns:
+            ScanResult indicating if content is safe.
+        """
+        if not content:
+            return ScanResult(is_safe=True, score=0.0, detected_patterns=[])
+
+        # Strip HTML tags if content looks like HTML
+        if "<" in content and ">" in content:
+            content = strip_html_tags(content)
+            if not content:
+                return ScanResult(is_safe=True, score=0.0, detected_patterns=[])
+
+        return self._scanner.scan(content)
+
+    def scan_email_content(
+        self,
+        subject: str | None = None,
+        body_plain: str | None = None,
+        body_html: str | None = None,
+    ) -> ScanResult:
+        """Scan all email content fields.
+
+        Combines subject and body content for scanning. HTML content is
+        automatically stripped by scan().
+
+        Args:
+            subject: Email subject line.
+            body_plain: Plain text body.
+            body_html: HTML body (will be stripped automatically).
+
+        Returns:
+            ScanResult with combined detection results.
+        """
+        # Combine all content for scanning
+        parts: list[str] = []
+
+        if subject:
+            parts.append(subject)
+        if body_plain:
+            parts.append(body_plain)
+        if body_html:
+            parts.append(body_html)
+
+        if not parts:
+            return ScanResult(is_safe=True, score=0.0, detected_patterns=[])
+
+        combined = "\n".join(parts)
+        return self.scan(combined)

read_no_evil_mcp/server.py

@@ -0,0 +1,12 @@
+"""MCP server implementation for read-no-evil-mcp using FastMCP."""
+
+from read_no_evil_mcp.tools import mcp
+
+
+def main() -> None:
+    """Entry point for the MCP server."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

read_no_evil_mcp/tools/__init__.py

@@ -0,0 +1,16 @@
+"""MCP tools package.
+
+This module re-exports the shared FastMCP instance and imports all tools
+to trigger their registration.
+"""
+
+from read_no_evil_mcp.tools import delete_email as _delete_email  # noqa: F401
+from read_no_evil_mcp.tools import get_email as _get_email  # noqa: F401
+from read_no_evil_mcp.tools import list_accounts as _list_accounts  # noqa: F401
+from read_no_evil_mcp.tools import list_emails as _list_emails  # noqa: F401
+from read_no_evil_mcp.tools import list_folders as _list_folders  # noqa: F401
+from read_no_evil_mcp.tools import move_email as _move_email  # noqa: F401
+from read_no_evil_mcp.tools import send_email as _send_email  # noqa: F401
+from read_no_evil_mcp.tools._app import mcp
+
+__all__ = ["mcp"]

read_no_evil_mcp/tools/_app.py

@@ -0,0 +1,6 @@
+"""Shared FastMCP application instance."""
+
+from fastmcp import FastMCP
+
+# Create the shared FastMCP server instance
+mcp = FastMCP(name="read-no-evil-mcp")