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

read_no_evil_mcp/__init__.py

@@ -0,0 +1,36 @@
+"""A secure email gateway MCP server that protects AI agents from prompt injection attacks in emails."""
+
+from read_no_evil_mcp.config import Settings
+from read_no_evil_mcp.email.connectors.base import BaseConnector
+from read_no_evil_mcp.email.connectors.imap import IMAPConnector
+from read_no_evil_mcp.mailbox import PromptInjectionError, SecureMailbox
+from read_no_evil_mcp.models import (
+    Attachment,
+    Email,
+    EmailAddress,
+    EmailSummary,
+    Folder,
+    IMAPConfig,
+    ScanResult,
+)
+from read_no_evil_mcp.protection.heuristic import HeuristicScanner
+from read_no_evil_mcp.protection.service import ProtectionService
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Attachment",
+    "BaseConnector",
+    "Email",
+    "EmailAddress",
+    "EmailSummary",
+    "Folder",
+    "HeuristicScanner",
+    "IMAPConfig",
+    "IMAPConnector",
+    "PromptInjectionError",
+    "ProtectionService",
+    "ScanResult",
+    "SecureMailbox",
+    "Settings",
+]

read_no_evil_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m read_no_evil_mcp."""
+
+from read_no_evil_mcp.server import main
+
+if __name__ == "__main__":
+    main()

read_no_evil_mcp/accounts/__init__.py

@@ -0,0 +1,21 @@
+"""Account management module for multi-account support."""
+
+from read_no_evil_mcp.accounts.config import (
+    AccountConfig,
+    BaseAccountConfig,
+    IMAPAccountConfig,
+)
+from read_no_evil_mcp.accounts.credentials import CredentialBackend, EnvCredentialBackend
+from read_no_evil_mcp.accounts.permissions import AccountPermissions, PermissionChecker
+from read_no_evil_mcp.accounts.service import AccountService
+
+__all__ = [
+    "AccountConfig",
+    "AccountPermissions",
+    "AccountService",
+    "BaseAccountConfig",
+    "CredentialBackend",
+    "EnvCredentialBackend",
+    "IMAPAccountConfig",
+    "PermissionChecker",
+]

read_no_evil_mcp/accounts/config.py

@@ -0,0 +1,93 @@
+"""Account configuration models with discriminated union for multi-connector support."""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from read_no_evil_mcp.accounts.permissions import AccountPermissions
+
+
+class BaseAccountConfig(BaseModel):
+    """Base configuration shared by all account types.
+
+    Attributes:
+        id: Unique identifier for the account (e.g., "work", "personal").
+    """
+
+    id: str = Field(
+        ...,
+        min_length=1,
+        pattern=r"^[a-zA-Z][a-zA-Z0-9_-]*$",
+        description="Unique account identifier (alphanumeric, hyphens, underscores)",
+    )
+
+
+class IMAPAccountConfig(BaseAccountConfig):
+    """IMAP-specific account configuration.
+
+    Attributes:
+        type: Connector type, always "imap" for this class.
+        host: Email server hostname.
+        port: Email server port (default: 993 for IMAP SSL).
+        username: Account username/email address.
+        ssl: Whether to use SSL/TLS (default: True).
+        permissions: Account permissions (default: read-only).
+        smtp_host: SMTP server hostname (default: same as IMAP host).
+        smtp_port: SMTP server port (default: 587 for STARTTLS).
+        smtp_ssl: Use SSL instead of STARTTLS for SMTP (default: False).
+    """
+
+    type: Literal["imap"] = Field(
+        default="imap",
+        description="Connector type (imap)",
+    )
+    host: str = Field(..., min_length=1, description="Email server hostname")
+    port: int = Field(default=993, ge=1, le=65535, description="Email server port")
+    username: str = Field(..., min_length=1, description="Account username/email")
+    ssl: bool = Field(default=True, description="Use SSL/TLS connection")
+    permissions: AccountPermissions = Field(
+        default_factory=AccountPermissions,
+        description="Account permissions (default: read-only)",
+    )
+    smtp_host: str | None = Field(
+        default=None,
+        description="SMTP server hostname (defaults to IMAP host)",
+    )
+    smtp_port: int = Field(
+        default=587,
+        ge=1,
+        le=65535,
+        description="SMTP server port (default: 587 for STARTTLS)",
+    )
+    smtp_ssl: bool = Field(
+        default=False,
+        description="Use SSL instead of STARTTLS for SMTP (default: False)",
+    )
+    from_address: str | None = Field(
+        default=None,
+        min_length=1,
+        description="Sender email address for outgoing emails (required for send)",
+    )
+    from_name: str | None = Field(
+        default=None,
+        description="Display name for outgoing emails (e.g., 'Atlas')",
+    )
+
+
+# Future connectors will follow the same pattern as IMAPAccountConfig:
+# - Inherit from BaseAccountConfig
+# - Add a `type` field with Literal["connector_name"]
+# - Add connector-specific fields
+# Examples: GmailAccountConfig (type="gmail"), MSGraphAccountConfig (type="msgraph")
+
+# Discriminated union - Pydantic picks the right type based on "type" field.
+# When adding new connectors, convert AccountConfig to a discriminated union:
+#
+#     from typing import Annotated, Union
+#     AccountConfig = Annotated[
+#         Union[IMAPAccountConfig, GmailAccountConfig, MSGraphAccountConfig],
+#         Field(discriminator="type"),
+#     ]
+#
+# For now with single type, use simple alias (discriminator activates with Union).
+AccountConfig = IMAPAccountConfig

read_no_evil_mcp/accounts/credentials/__init__.py

@@ -0,0 +1,6 @@
+"""Credential backends for account authentication."""
+
+from read_no_evil_mcp.accounts.credentials.base import CredentialBackend
+from read_no_evil_mcp.accounts.credentials.env import EnvCredentialBackend
+
+__all__ = ["CredentialBackend", "EnvCredentialBackend"]

read_no_evil_mcp/accounts/credentials/base.py

@@ -0,0 +1,29 @@
+"""Abstract base class for credential backends."""
+
+from abc import ABC, abstractmethod
+
+from pydantic import SecretStr
+
+
+class CredentialBackend(ABC):
+    """Abstract interface for credential storage.
+
+    Credential backends are responsible for retrieving passwords for email accounts.
+    Different implementations can retrieve credentials from environment variables,
+    keyrings, encrypted files, etc.
+    """
+
+    @abstractmethod
+    def get_password(self, account_id: str) -> SecretStr:
+        """Retrieve password for the given account.
+
+        Args:
+            account_id: The unique identifier of the account.
+
+        Returns:
+            The password as a SecretStr.
+
+        Raises:
+            CredentialNotFoundError: If the credential is not found.
+        """
+        ...

read_no_evil_mcp/accounts/credentials/env.py

@@ -0,0 +1,44 @@
+"""Environment variable credential backend."""
+
+import os
+
+from pydantic import SecretStr
+
+from read_no_evil_mcp.accounts.credentials.base import CredentialBackend
+from read_no_evil_mcp.exceptions import CredentialNotFoundError
+
+
+class EnvCredentialBackend(CredentialBackend):
+    """Credential backend using environment variables.
+
+    Looks for passwords in environment variables named:
+    RNOE_ACCOUNT_{ID}_PASSWORD
+
+    Where {ID} is the account ID in uppercase with hyphens replaced by underscores.
+    For example:
+    - Account "work" -> RNOE_ACCOUNT_WORK_PASSWORD
+    - Account "personal" -> RNOE_ACCOUNT_PERSONAL_PASSWORD
+    - Account "my-gmail" -> RNOE_ACCOUNT_MY_GMAIL_PASSWORD
+    """
+
+    def get_password(self, account_id: str) -> SecretStr:
+        """Retrieve password from environment variable.
+
+        Args:
+            account_id: The unique identifier of the account.
+
+        Returns:
+            The password as a SecretStr.
+
+        Raises:
+            CredentialNotFoundError: If the environment variable is not set.
+        """
+        # Normalize account ID: uppercase and replace hyphens with underscores
+        normalized_id = account_id.upper().replace("-", "_")
+        env_key = f"RNOE_ACCOUNT_{normalized_id}_PASSWORD"
+
+        value = os.environ.get(env_key)
+        if not value:
+            raise CredentialNotFoundError(account_id, env_key)
+
+        return SecretStr(value)

read_no_evil_mcp/accounts/permissions.py

@@ -0,0 +1,87 @@
+"""Account permissions model and checker for rights management."""
+
+from pydantic import BaseModel
+
+from read_no_evil_mcp.exceptions import PermissionDeniedError
+
+
+class AccountPermissions(BaseModel):
+    """Permissions configuration for an email account.
+
+    Attributes:
+        read: Whether reading emails is allowed (default: True).
+        delete: Whether deleting emails is allowed (default: False).
+        send: Whether sending emails is allowed (default: False).
+        move: Whether moving emails between folders is allowed (default: False).
+        folders: List of allowed folders, or None for all folders (default: None).
+    """
+
+    read: bool = True
+    delete: bool = False
+    send: bool = False
+    move: bool = False
+    folders: list[str] | None = None
+
+
+class PermissionChecker:
+    """Checker for account permissions.
+
+    Validates operations against account permissions and raises
+    PermissionDeniedError if the operation is not allowed.
+    """
+
+    def __init__(self, permissions: AccountPermissions) -> None:
+        """Initialize the permission checker.
+
+        Args:
+            permissions: The account permissions to check against.
+        """
+        self.permissions = permissions
+
+    def check_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 check_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 check_delete(self) -> None:
+        """Check if delete access is allowed.
+
+        Raises:
+            PermissionDeniedError: If delete access is denied.
+        """
+        if not self.permissions.delete:
+            raise PermissionDeniedError("Delete access denied for this account")
+
+    def check_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 check_move(self) -> None:
+        """Check if moving emails is allowed.
+
+        Raises:
+            PermissionDeniedError: If move access is denied.
+        """
+        if not self.permissions.move:
+            raise PermissionDeniedError("Move access denied for this account")

read_no_evil_mcp/accounts/service.py

@@ -0,0 +1,109 @@
+"""Account service for managing multiple email accounts."""
+
+from pydantic import SecretStr
+
+from read_no_evil_mcp.accounts.config import AccountConfig
+from read_no_evil_mcp.accounts.credentials.base import CredentialBackend
+from read_no_evil_mcp.email.connectors.base import BaseConnector
+from read_no_evil_mcp.email.connectors.imap import IMAPConnector
+from read_no_evil_mcp.exceptions import AccountNotFoundError, UnsupportedConnectorError
+from read_no_evil_mcp.mailbox import SecureMailbox
+from read_no_evil_mcp.models import IMAPConfig, SMTPConfig
+
+
+class AccountService:
+    """Service for managing multiple email accounts.
+
+    Provides a unified interface for accessing email accounts by their IDs.
+    Handles credential retrieval and connector instantiation.
+    """
+
+    def __init__(
+        self,
+        accounts: list[AccountConfig],
+        credentials: CredentialBackend,
+    ) -> None:
+        """Initialize the account service.
+
+        Args:
+            accounts: List of account configurations.
+            credentials: Backend for retrieving account credentials.
+        """
+        self._accounts = {a.id: a for a in accounts}
+        self._credentials = credentials
+
+    def list_accounts(self) -> list[str]:
+        """Return list of configured account IDs.
+
+        Returns:
+            List of account identifiers in the order they were configured.
+        """
+        return list(self._accounts.keys())
+
+    def _create_connector(self, config: AccountConfig, password: SecretStr) -> BaseConnector:
+        """Create a connector based on account configuration.
+
+        Args:
+            config: The account configuration.
+            password: The account password.
+
+        Returns:
+            A configured connector instance.
+
+        Raises:
+            UnsupportedConnectorError: If the connector type is not supported.
+        """
+        if config.type == "imap":
+            imap_config = IMAPConfig(
+                host=config.host,
+                port=config.port,
+                username=config.username,
+                password=password,
+                ssl=config.ssl,
+            )
+
+            # Create SMTP config if send permission is enabled
+            smtp_config = None
+            if config.permissions.send:
+                smtp_config = SMTPConfig(
+                    host=config.smtp_host or config.host,
+                    port=config.smtp_port,
+                    username=config.username,
+                    password=password,
+                    ssl=config.smtp_ssl,
+                )
+
+            return IMAPConnector(imap_config, smtp_config=smtp_config)
+
+        raise UnsupportedConnectorError(config.type)
+
+    def get_mailbox(self, account_id: str) -> SecureMailbox:
+        """Create SecureMailbox for the specified account.
+
+        Args:
+            account_id: The unique identifier of the account.
+
+        Returns:
+            A SecureMailbox instance configured for the account.
+
+        Raises:
+            AccountNotFoundError: If the account ID is not found.
+            CredentialNotFoundError: If credentials cannot be retrieved.
+            UnsupportedConnectorError: If the connector type is not supported.
+        """
+        config = self._accounts.get(account_id)
+        if not config:
+            raise AccountNotFoundError(account_id)
+
+        password = self._credentials.get_password(account_id)
+        connector = self._create_connector(config, password)
+
+        # Use config.from_address, fall back to config.username if not set
+        from_address = config.from_address or config.username
+
+        return SecureMailbox(
+            connector,
+            config.permissions,
+            from_address=from_address,
+            from_name=config.from_name,
+        )

read_no_evil_mcp/config.py

@@ -0,0 +1,98 @@
+"""Configuration settings for read-no-evil-mcp using pydantic-settings."""
+
+import os
+from pathlib import Path
+from typing import Any
+
+from pydantic_settings import (
+    BaseSettings,
+    PydanticBaseSettingsSource,
+    SettingsConfigDict,
+)
+
+from read_no_evil_mcp.accounts.config import AccountConfig
+
+
+class YamlConfigSettingsSource(PydanticBaseSettingsSource):
+    """Settings source that loads configuration from a YAML file.
+
+    Looks for config file in the following order:
+    1. RNOE_CONFIG_FILE environment variable
+    2. ./rnoe.yaml (current directory)
+    3. ~/.config/read-no-evil-mcp/config.yaml
+    """
+
+    def get_field_value(self, field: Any, field_name: str) -> tuple[Any, str, bool]:
+        """Get field value from YAML config."""
+        yaml_data = self._load_yaml_config()
+        field_value = yaml_data.get(field_name)
+        return field_value, field_name, False
+
+    def __call__(self) -> dict[str, Any]:
+        """Return all settings from YAML config."""
+        return self._load_yaml_config()
+
+    def _load_yaml_config(self) -> dict[str, Any]:
+        """Load and cache YAML config file."""
+        if not hasattr(self, "_yaml_data"):
+            self._yaml_data = self._read_yaml_file()
+        return self._yaml_data
+
+    def _read_yaml_file(self) -> dict[str, Any]:
+        """Read YAML config from file."""
+        import yaml
+
+        config_paths = [
+            os.environ.get("RNOE_CONFIG_FILE"),
+            Path.cwd() / "rnoe.yaml",
+            Path.home() / ".config" / "read-no-evil-mcp" / "config.yaml",
+        ]
+
+        for path in config_paths:
+            if path and Path(path).exists():
+                with open(path) as f:
+                    data = yaml.safe_load(f)
+                    return data if data else {}
+
+        return {}
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables with RNOE_ prefix.
+
+    Multi-account configuration via YAML file:
+        accounts:
+          - id: "work"
+            type: "imap"
+            host: "mail.company.com"
+            username: "user@company.com"
+
+    Account passwords are retrieved via credential backends
+    (e.g., RNOE_ACCOUNT_WORK_PASSWORD environment variable).
+    """
+
+    model_config = SettingsConfigDict(env_prefix="RNOE_")
+
+    # Multi-account configuration
+    accounts: list[AccountConfig] = []
+
+    # Application defaults
+    default_lookback_days: int = 7
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        """Customize settings sources to include YAML config."""
+        return (
+            init_settings,
+            env_settings,
+            YamlConfigSettingsSource(settings_cls),
+            dotenv_settings,
+            file_secret_settings,
+        )

read_no_evil_mcp/email/__init__.py

@@ -0,0 +1,6 @@
+"""Email connectors for read-no-evil-mcp."""
+
+from read_no_evil_mcp.email.connectors.base import BaseConnector
+from read_no_evil_mcp.email.connectors.imap import IMAPConnector
+
+__all__ = ["BaseConnector", "IMAPConnector"]

read_no_evil_mcp/email/connectors/__init__.py

@@ -0,0 +1,6 @@
+"""Email connectors for read-no-evil-mcp."""
+
+from read_no_evil_mcp.email.connectors.base import BaseConnector
+from read_no_evil_mcp.email.connectors.imap import IMAPConnector
+
+__all__ = ["BaseConnector", "IMAPConnector"]