castmail2list 0.1.0__tar.gz

castmail2list-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: castmail2list
+Version: 0.1.0
+Summary: Simple mailing list software with IMAP mailbox backend, web interface, and multiple list modes.
+License: GPL-3.0-only
+Author: Max Mehl
+Author-email: mail@mehl.mx
+Requires-Python: >=3.10,<4.0
+Classifier: Framework :: Flask
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Communications :: Email :: Mailing List Servers
+Classifier: Topic :: Communications :: Email :: Post-Office :: IMAP
+Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Dist: email-validator (>=2.3.0,<3.0.0)
+Requires-Dist: flask (>=3.1.2,<4.0.0)
+Requires-Dist: flask-babel (>=4.0.0,<5.0.0)
+Requires-Dist: flask-limiter (>=4.0.0,<5.0.0)
+Requires-Dist: flask-login (>=0.6.3,<0.7.0)
+Requires-Dist: flask-migrate (>=4.1.0,<5.0.0)
+Requires-Dist: flask-sqlalchemy (>=3.1.1,<4.0.0)
+Requires-Dist: flask-wtf (>=1.2.2,<2.0.0)
+Requires-Dist: flufl-bounce (>=4.0,<5.0)
+Requires-Dist: gunicorn (>=23.0.0,<24.0.0)
+Requires-Dist: imap-tools (>=1.11.0,<2.0.0)
+Requires-Dist: jsonschema (>=4.25.1,<5.0.0)
+Requires-Dist: platformdirs (>=4.5.0,<5.0.0)
+Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
+Requires-Dist: wtforms[email] (>=3.2.1,<4.0.0)
+Project-URL: Repository, https://github.com/mxmehl/castmail2list
+Description-Content-Type: text/markdown
+
+# CastMail2List
+
+## Usage
+
+For production use (using gunicorn as WSGI):
+
+```sh
+castmail2list --help
+```
+
+For local development and administrative commands (using Flask directly):
+
+```sh
+castmail2list-cli --help
+```
+
+
+## Configuration
+
+CastMail2List supports loading configuration from YAML files. There are some defaults and some required configuration keys.
+
+### Using YAML Configuration
+
+1. Copy the example configuration file:
+   ```bash
+   cp config.example.yaml config.yaml
+   ```
+
+2. Edit `config.yaml` with your settings
+
+3. Run the application with the `--config` flag:
+   ```bash
+   castmail2list --config config.yaml
+   ```
+
+### Example Configuration File
+
+See `config.example.yaml` for a complete example with all available configuration options.
+

castmail2list-0.1.0/README.md

@@ -0,0 +1,38 @@
+# CastMail2List
+
+## Usage
+
+For production use (using gunicorn as WSGI):
+
+```sh
+castmail2list --help
+```
+
+For local development and administrative commands (using Flask directly):
+
+```sh
+castmail2list-cli --help
+```
+
+
+## Configuration
+
+CastMail2List supports loading configuration from YAML files. There are some defaults and some required configuration keys.
+
+### Using YAML Configuration
+
+1. Copy the example configuration file:
+   ```bash
+   cp config.example.yaml config.yaml
+   ```
+
+2. Edit `config.yaml` with your settings
+
+3. Run the application with the `--config` flag:
+   ```bash
+   castmail2list --config config.yaml
+   ```
+
+### Example Configuration File
+
+See `config.example.yaml` for a complete example with all available configuration options.

castmail2list-0.1.0/castmail2list/__init__.py

@@ -0,0 +1,5 @@
+"""Castmail2List"""
+
+from importlib.metadata import version
+
+__version__ = version("castmail2list")

castmail2list-0.1.0/castmail2list/app.py

@@ -0,0 +1,289 @@
+"""Flask app and CLI for CastMail2List"""
+
+import argparse
+import logging
+from logging.config import dictConfig
+from pathlib import Path
+
+from flask import Flask
+from flask_babel import Babel
+from flask_limiter import Limiter
+from flask_limiter.util import get_remote_address
+from flask_login import LoginManager
+from flask_migrate import Migrate, check, downgrade, upgrade
+from flask_wtf import CSRFProtect
+from sqlalchemy.exc import OperationalError
+from werkzeug.middleware.proxy_fix import ProxyFix
+from werkzeug.security import generate_password_hash
+
+from .config import AppConfig
+from .imap_worker import initialize_imap_polling
+from .models import AlembicVersion, User, db
+from .seeder import seed_database
+from .utils import (
+    compile_scss_on_startup,
+    get_app_bin_dir,
+    get_user_config_path,
+    get_version_info,
+)
+from .views.auth import auth
+from .views.general import general
+from .views.lists import lists
+from .views.messages import messages
+
+SCSS_FILES = [("static/scss/main.scss", "static/css/main.scss.css")]
+
+
+def configure_logging(debug: bool) -> None:
+    """Configure logging"""
+    dictConfig(
+        {
+            "version": 1,
+            "formatters": {
+                "default": {
+                    "format": "[%(asctime)s] %(levelname)s in %(module)s: %(message)s",
+                }
+            },
+            "handlers": {
+                "wsgi": {
+                    "class": "logging.StreamHandler",
+                    "stream": "ext://flask.logging.wsgi_errors_stream",
+                    "formatter": "default",
+                }
+            },
+            "root": {"level": "DEBUG" if debug else "INFO", "handlers": ["wsgi"]},
+        }
+    )
+
+
+def create_app(
+    config_overrides: dict | None = None,
+    yaml_config_path: str | None = None,
+    one_off_call: bool = False,
+) -> Flask:
+    """Create Flask app
+
+    Args:
+        config_overrides (dict): optional dict to update app.config before DB init (e.g. for tests)
+        yaml_config_path (str): optional path to YAML configuration file
+        one_off_call (bool): if True, indicates this is a one-off call (e.g. for CLI commands)
+
+    Returns:
+        Flask: the Flask application
+    """
+    app = Flask(__name__)
+    logging.debug("Executable bin path: %s", get_app_bin_dir())
+
+    # Load config from YAML, if provided
+    if yaml_config_path:
+        appconfig = AppConfig.from_yaml_and_env(yaml_config_path)
+    else:
+        appconfig = AppConfig()  # default config
+
+    app.config.from_object(appconfig)
+
+    # apply overrides early so DB and other setup use them
+    if config_overrides:
+        app.config.update(config_overrides)
+
+    # Translations
+    Babel(app, default_locale=app.config.get("LANGUAGE", "en"))
+    logging.info("Language set to: %s", app.config.get("LANGUAGE", "en"))
+    app.jinja_env.globals["current_language"] = app.config.get("LANGUAGE", "en")
+
+    # Database
+    # default to SQLite in config dir if no DATABASE_URI set
+    if not app.config.get("DATABASE_URI"):
+        app.config["DATABASE_URI"] = "sqlite:///" + get_user_config_path(file="castmail2list.db")
+    app.config["SQLALCHEMY_DATABASE_URI"] = app.config["DATABASE_URI"]
+    logging.info("Using database at %s", app.config["SQLALCHEMY_DATABASE_URI"])
+    # Initialize the database
+    migrations_dir = str(Path(__file__).parent.resolve() / "migrations")
+    db.init_app(app)
+    Migrate(app=app, db=db, directory=migrations_dir)
+
+    # Trust headers from reverse proxy (1 layer by default)
+    app.wsgi_app = ProxyFix(  # type: ignore[method-assign]
+        app.wsgi_app, x_for=1, x_proto=1, x_host=1, x_prefix=1
+    )
+
+    # Secure session cookie config
+    app.config.update(
+        SESSION_COOKIE_HTTPONLY=True, SESSION_COOKIE_SECURE=True, SESSION_COOKIE_SAMESITE="Lax"
+    )
+
+    # Enable CSRF protection
+    CSRFProtect(app)
+
+    # Configure Flask-Login
+    login_manager = LoginManager()
+    login_manager.login_view = "auth.login"
+    login_manager.init_app(app)
+
+    # User loader function for Flask-Login
+    @login_manager.user_loader
+    def load_user(user_id):
+        return User.query.get(int(user_id))
+
+    # Register views and routes
+    app.register_blueprint(auth)
+    app.register_blueprint(general)
+    app.register_blueprint(messages)
+    app.register_blueprint(lists)
+
+    # Inject variables into templates
+    @app.context_processor
+    def inject_vars():
+        return {
+            "version_info": get_version_info(debug=app.debug),
+        }
+
+    # ---------------
+    # From here on, only for permanently running app, not one-off calls
+    if one_off_call:
+        return app
+
+    # Set up rate limiting
+    app.config.setdefault("RATE_LIMIT_DEFAULT", "20 per 1 minute")
+    app.config.setdefault("RATE_LIMIT_LOGIN", "2 per 10 seconds")
+    app.config.setdefault("RATELIMIT_STORAGE_URI", "memory://")
+    limiter = Limiter(
+        get_remote_address,
+        default_limits=[app.config.get("RATE_LIMIT_DEFAULT", "")],
+        storage_uri=app.config.get("RATE_LIMIT_STORAGE_URI"),
+    )
+    limiter.init_app(app)
+
+    if app.config.get("RATE_LIMIT_STORAGE_URI") == "memory://" and not app.debug:
+        logging.warning(
+            "Rate limiting is using in-memory storage. Limits may not work with multiple processes."
+        )
+
+    # Start background IMAP thread unless in testing
+    initialize_imap_polling(app)
+
+    # Compile SCSS files on startup
+    app.config["SCSS_FILES"] = compile_scss_on_startup(scss_files=SCSS_FILES)
+
+    # Debug logging of config
+    logging.debug("App configuration:\n%s", app.config)
+
+    return app
+
+
+def create_app_wrapper(app_config_path: str, debug: bool, one_off: bool) -> Flask:
+    """Wrapper to create app from arguments. Both for direct Flask app and WSGI (gunicorn)"""
+    # Configure logging
+    configure_logging(debug)
+
+    # Create Flask app
+    app = create_app(yaml_config_path=app_config_path, one_off_call=one_off)
+
+    return app
+
+
+def main():
+    """Run the app"""
+    parser = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.ArgumentDefaultsHelpFormatter
+    )
+    parser.add_argument("-H", "--host", type=str, help="Host of Flask app", default="127.0.0.1")
+    parser.add_argument("-p", "--port", type=int, help="Port of Flask app", default=2278)
+    parser.add_argument(
+        "-c",
+        "--app-config",
+        type=str,
+        help="Path to YAML configuration file",
+        default=get_user_config_path(file="config.yaml"),
+    )
+    parser.add_argument(
+        "--create-admin",
+        nargs=2,
+        metavar=("USERNAME", "PASSWORD"),
+        help="Create an admin user and exit (usage: --create-admin admin secret)",
+    )
+    # DB Commands
+    parser.add_argument(
+        "--db",
+        choices=["check", "upgrade", "downgrade", "init"],
+        help="Database commands, e.g. for migrations",
+    )
+    parser.add_argument(
+        "--db-seed",
+        type=str,
+        metavar="SEED_FILE",
+        help="Seed the database with a seed file and exit",
+    )
+    parser.add_argument(
+        "--debug", action="store_true", help="Run in debug mode (may leak sensitive information)"
+    )
+    args = parser.parse_args()
+
+    # Create the Flask application
+    one_off = False
+    if args.db or args.create_admin or args.db_seed:
+        # one-off call for most CLI commands
+        one_off = True
+    app = create_app_wrapper(app_config_path=args.app_config, debug=args.debug, one_off=one_off)
+
+    # Create admin user if requested
+    if args.create_admin:
+        username, password = args.create_admin
+        # run inside app context to access DB
+        with app.app_context():
+            existing = User.query.filter_by(username=username).first()
+            if existing:
+                logging.error("Error: user '%s' already exists", username)
+                return
+            new_user = User(
+                username=username, password=generate_password_hash(password), role="admin"
+            )
+            db.session.add(new_user)
+            db.session.commit()
+            logging.info("Admin user '%s' created", username)
+        return
+
+    # Handle DB commands if provided
+    if args.db is not None:
+        with app.app_context():
+            if args.db == "check":
+                check()
+            elif args.db in ("init", "upgrade"):
+                upgrade()
+            elif args.db == "downgrade":
+                downgrade()
+            return
+
+    # Seed database if requested
+    if args.db_seed:
+        seed_database(app, seed_file=args.db_seed)
+        return
+
+    # Identify and abort if database seems to be empty
+    with app.app_context():
+        try:
+            # get alembic version, first entry, version column
+            alembic_version = db.session.query(AlembicVersion).first()
+            logging.debug(
+                "Database revision: %s", alembic_version.version_num if alembic_version else None
+            )
+        except OperationalError as e:
+            logging.info("Database error: %s", e)
+            logging.critical(
+                "Database does not seem to be initialized. Run with --db init to initialize."
+            )
+            return
+
+    # Run the Flask app
+    app.run(
+        host=args.host,
+        port=args.port,
+        debug=args.debug,
+        extra_files=[
+            bundle[0] for bundle in app.config["SCSS_FILES"]
+        ],  # watch SCSS files for changes
+    )
+
+
+if __name__ == "__main__":
+    main()

castmail2list-0.1.0/castmail2list/babel.cfg

@@ -0,0 +1,2 @@
+[python: **.py]
+[jinja2: **/templates/**.html]

castmail2list-0.1.0/castmail2list/config.py

@@ -0,0 +1,130 @@
+"""Configuration for CastMail2List"""
+
+import logging
+from pathlib import Path
+from typing import Any
+
+import yaml
+from jsonschema import FormatChecker, validate
+from jsonschema.exceptions import ValidationError
+
+CONFIG_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "DATABASE_URI": {"type": "string"},
+        "SECRET_KEY": {"type": "string"},
+        "LANGUAGE": {"type": "string"},
+        "DOMAIN": {"type": "string"},
+        "HOST_TYPE": {"type": "string"},
+        "CREATE_LISTS_AUTOMATICALLY": {"type": "boolean"},
+        "POLL_INTERVAL_SECONDS": {"type": "integer"},
+        "IMAP_DEFAULT_HOST": {"type": "string"},
+        "IMAP_DEFAULT_PORT": {"type": "integer"},
+        "IMAP_DEFAULT_USER_DOMAIN": {"type": "string"},
+        "IMAP_DEFAULT_PASS": {"type": "string"},
+        "IMAP_FOLDER_INBOX": {"type": "string"},
+        "IMAP_FOLDER_PROCESSED": {"type": "string"},
+        "IMAP_FOLDER_SENT": {"type": "string"},
+        "IMAP_FOLDER_BOUNCES": {"type": "string"},
+        "IMAP_FOLDER_DENIED": {"type": "string"},
+        "IMAP_FOLDER_DUPLICATE": {"type": "string"},
+        "SMTP_HOST": {"type": "string"},
+        "SMTP_PORT": {"type": "integer"},
+        "SMTP_USER": {"type": "string"},
+        "SMTP_PASS": {"type": "string"},
+        "SMTP_STARTTLS": {"type": "boolean"},
+    },
+    "required": ["SECRET_KEY", "DOMAIN", "HOST_TYPE", "SMTP_HOST"],
+    "additionalProperties": False,
+}
+
+
+class AppConfig:  # pylint: disable=too-few-public-methods
+    """Flask configuration from YAML file with some defaults"""
+
+    # App settings
+    DATABASE_URI: str = ""
+    SECRET_KEY: str = ""
+
+    # General settings
+    LANGUAGE: str = "en"  # Supported languages: "en", "de"
+    DOMAIN: str = ""
+    HOST_TYPE = ""  # used for auto list creation. Can be: empty, uberspace7, uberspace8
+    CREATE_LISTS_AUTOMATICALLY: bool = False
+    POLL_INTERVAL_SECONDS: int = 60
+
+    # IMAP settings and defaults (used as defaults for new lists)
+    IMAP_DEFAULT_HOST: str = ""
+    IMAP_DEFAULT_PORT: int = 993
+    IMAP_DEFAULT_USER_DOMAIN: str = ""
+    IMAP_DEFAULT_PASS: str = ""
+
+    # IMAP folder names
+    IMAP_FOLDER_INBOX: str = "INBOX"
+    IMAP_FOLDER_PROCESSED: str = "Processed"
+    IMAP_FOLDER_SENT: str = "Sent"
+    IMAP_FOLDER_BOUNCES: str = "Bounces"
+    IMAP_FOLDER_DENIED: str = "Denied"
+    IMAP_FOLDER_DUPLICATE: str = "Duplicate"
+
+    # SMTP settings
+    SMTP_HOST: str = ""
+    SMTP_PORT: int = 587
+    SMTP_USER: str = ""
+    SMTP_PASS: str = ""
+    SMTP_STARTTLS = True
+
+    @classmethod
+    def validate_config_schema(cls, cfg: dict, schema: dict) -> None:
+        """Validate the config against a JSON schema"""
+        try:
+            validate(instance=cfg, schema=schema, format_checker=FormatChecker())
+        except ValidationError as e:
+            logging.critical("Config validation failed: %s", e.message)
+            raise ValueError(e) from None
+        logging.debug("Config validated successfully against schema.")
+
+    @classmethod
+    def load_from_yaml(cls, yaml_path: str | Path) -> dict[str, Any]:
+        """Load configuration from YAML file.
+
+        Args:
+            yaml_path: Path to YAML configuration file
+
+        Returns:
+            Dictionary with configuration values
+        """
+        logging.debug("Loading configuration from YAML file: %s", yaml_path)
+        try:
+            with open(yaml_path, encoding="utf-8") as f:
+                data = yaml.safe_load(f) or {}
+                cls.validate_config_schema(data, CONFIG_SCHEMA)
+                return data
+        except FileNotFoundError as e:
+            logging.critical("Configuration file not found: %s", yaml_path)
+            raise e
+        except yaml.YAMLError as e:
+            logging.critical("Error parsing YAML configuration file: %s", e)
+            raise e
+
+    @classmethod
+    def from_yaml_and_env(cls, yaml_path: str | Path) -> "AppConfig":
+        """Create Config instance from YAML file, overriding class defaults
+
+        Args:
+            yaml_path (str | Path): Path to YAML configuration file
+
+        Returns:
+            Config instance with merged configuration
+        """
+        config = cls()
+
+        # Load from YAML if provided
+        if yaml_path:
+            yaml_config = cls.load_from_yaml(yaml_path)
+            for key, value in yaml_config.items():
+                if hasattr(config, key.upper()):
+                    setattr(config, key.upper(), value)
+
+        # Environment variables override YAML (re-apply from env)
+        return config

castmail2list-0.1.0/castmail2list/forms.py

@@ -0,0 +1,118 @@
+"""Flask-WTF forms for castmail2list application"""
+
+from email.utils import parseaddr
+
+from flask_babel import lazy_gettext as _  # Using lazy_gettext for form field labels
+from flask_wtf import FlaskForm
+from wtforms import (
+    BooleanField,
+    EmailField,
+    IntegerField,
+    PasswordField,
+    RadioField,
+    StringField,
+    SubmitField,
+    ValidationError,
+)
+from wtforms.validators import DataRequired, Email, Length, NumberRange, Optional
+
+
+class LoginForm(FlaskForm):
+    """
+    LoginForm is a form class used for user authentication.
+
+    Attributes:
+        username (StringField): A field for entering the username. It is required.
+        password (PasswordField): A field for entering the password. It is required.
+    """
+
+    username = StringField(label="Username", validators=[DataRequired()])
+    password = PasswordField(label="Password", validators=[DataRequired()])
+    submit = SubmitField(_("Login"))
+
+
+def email_with_opt_display_name(form, field):
+    """Custom validator for multiple ways of providing email addresses:
+
+    foo@bar.com
+    John Doe <foo@bar.com>
+    "John P. Doe" <foo@bar.com>
+    """
+    _, addr = parseaddr(field.data or "")
+    if not addr:
+        raise ValidationError("Invalid email format")
+
+    # Temporarily replace field.data with the bare address
+    original = field.data
+    field.data = addr
+
+    try:
+        Email()(form, field)
+    finally:
+        field.data = original
+
+
+class MailingListForm(FlaskForm):
+    """Form for creating and editing mailing lists"""
+
+    # Basics
+    name = StringField(_("List Name"), validators=[DataRequired(), Length(min=1, max=100)])
+    address = EmailField(_("List Email Address"), validators=[DataRequired(), Email()])
+    avoid_duplicates = BooleanField(
+        _("Avoid duplicate copies of messages for subscribers"),
+        default=True,
+    )
+    # Modes
+    mode = RadioField(
+        _("Mode of the Mailing List"),
+        choices=[
+            ("broadcast", _("Broadcast List: One-to-many communication, distribution list")),
+            ("group", _("Group List: Many-to-many communication, discussion group")),
+        ],
+        default="broadcast",
+    )
+    from_addr = StringField(
+        _("From Address"),
+        validators=[Optional(), email_with_opt_display_name],
+        description=_(
+            "Optional 'From' address for emails sent by the list. If left empty, the list address "
+            "will be used. Only relevant in Broadcast mode."
+        ),
+    )
+    allowed_senders = StringField(
+        _("Allowed Senders"),
+        validators=[Optional()],
+        description=_(
+            "Enter email addresses that are allowed to send emails to the list. "
+            "Separated by commas. Only relevant in Broadcast mode."
+        ),
+    )
+    only_subscribers_send = BooleanField(
+        _("Only allow subscribers to send messages to the list. Only relevant in Group mode."),
+        default=False,
+    )
+    sender_auth = StringField(
+        _("Sender Authentication Passwords"),
+        validators=[Optional()],
+        description=_(
+            "Comma-separated list of passwords that senders must provide to send emails "
+            "to this list. This can be passed via 'listaddress+password1@example.com'. "
+            "Leave empty to disable sender authentication."
+        ),
+    )
+
+    # IMAP Settings
+    imap_host = StringField(_("IMAP Server"), validators=[Optional(), Length(max=200)])
+    imap_port = IntegerField(_("IMAP Port"), validators=[Optional(), NumberRange(min=1, max=65535)])
+    imap_user = StringField(_("IMAP Username"), validators=[Optional(), Length(max=200)])
+    imap_pass = PasswordField(_("IMAP Password"), validators=[Optional()])
+    submit = SubmitField(_("Save List"))
+
+
+class SubscriberAddForm(FlaskForm):
+    """Form for adding new subscribers"""
+
+    name = StringField(_("Name"), validators=[Optional(), Length(max=100)])
+    email = EmailField(_("Email Address"), validators=[DataRequired(), Email()])
+    comment = StringField(_("Comment"), validators=[Optional(), Length(max=100)])
+    submit = SubmitField(_("Save Subscriber"))

castmail2list-0.1.0/castmail2list/gunicorn.conf.py

@@ -0,0 +1,19 @@
+"""Gunicorn configuration file"""
+
+# pylint: disable=invalid-name
+
+# Server socket
+bind = "0.0.0.0:2278"
+
+# Worker processes
+workers = 1
+worker_class = "sync"
+timeout = 30
+
+# Logging
+accesslog = "-"  # Log to stdout
+errorlog = "-"   # Log to stderr
+loglevel = "info"
+
+# Process naming
+proc_name = "castmail2list"