platzky 1.2.2__py3-none-any.whl → 1.3.0__py3-none-any.whl

platzky/attachment/__init__.py

@@ -0,0 +1,39 @@
+"""Attachment package for file attachments in notifications.
+
+This package provides the Attachment class factory and related utilities for
+handling file attachments in the notification system.
+
+Usage via Engine (recommended):
+    >>> # Engine exposes a configured Attachment class
+    >>> attachment = engine.Attachment("report.pdf", pdf_bytes, "application/pdf")
+
+Direct usage with factory:
+    >>> from platzky.attachment import create_attachment_class
+    >>> from platzky.config import AttachmentConfig
+    >>> config = AttachmentConfig(max_size=5 * 1024 * 1024)  # 5MB limit
+    >>> Attachment = create_attachment_class(config)
+    >>> attachment = Attachment("report.pdf", pdf_bytes, "application/pdf")
+"""
+
+from platzky.attachment.constants import (
+    BLOCKED_EXTENSIONS,
+    DEFAULT_MAX_ATTACHMENT_SIZE,
+    AttachmentSizeError,
+    BlockedExtensionError,
+    ExtensionNotAllowedError,
+    InvalidMimeTypeError,
+)
+from platzky.attachment.core import AttachmentProtocol, create_attachment_class
+from platzky.attachment.mime_validation import ContentMismatchError
+
+__all__ = [
+    "BLOCKED_EXTENSIONS",
+    "DEFAULT_MAX_ATTACHMENT_SIZE",
+    "AttachmentProtocol",
+    "AttachmentSizeError",
+    "BlockedExtensionError",
+    "ContentMismatchError",
+    "ExtensionNotAllowedError",
+    "InvalidMimeTypeError",
+    "create_attachment_class",
+]

platzky/attachment/constants.py

@@ -0,0 +1,139 @@
+"""Attachment size limits and related constants."""
+
+# Default maximum attachment size: 10MB
+DEFAULT_MAX_ATTACHMENT_SIZE = 10 * 1024 * 1024
+
+# Blocked file extensions - dangerous executable and script formats.
+# SECURITY: These extensions are PERMANENTLY blocked and cannot be overridden
+# via allowed_extensions. This includes .js which can execute via Windows
+# Script Host, Node.js, or browsers.
+BLOCKED_EXTENSIONS: frozenset[str] = frozenset(
+    {
+        # Windows executables
+        "exe",
+        "dll",
+        "scr",
+        "msi",
+        "com",
+        "pif",
+        # Windows scripts
+        "bat",
+        "cmd",
+        "vbs",
+        "vbe",
+        "js",
+        "jse",
+        "ws",
+        "wsf",
+        "wsc",
+        "wsh",
+        "ps1",
+        "psm1",
+        "psd1",
+        # Shortcuts and links
+        "lnk",
+        "url",
+        "hta",
+        # macOS executables
+        "app",
+        "dmg",
+        "pkg",
+        # Linux packages
+        "deb",
+        "rpm",
+        "appimage",
+        # Shell scripts
+        "sh",
+        "bash",
+        "zsh",
+        "ksh",
+        "csh",
+        # Scripting languages
+        "py",
+        "pyc",
+        "pyo",
+        "pyw",
+        "rb",
+        "pl",
+        "php",
+        "php3",
+        "php4",
+        "php5",
+        "phtml",
+        # Java
+        "jar",
+        "class",
+        "war",
+        # Other dangerous formats
+        "reg",  # Windows registry
+        "inf",  # Windows setup information
+        "scf",  # Windows Explorer command
+        "cpl",  # Control panel extension
+        "msc",  # Microsoft Management Console
+        "gadget",  # Windows gadget
+    }
+)
+
+
+class BlockedExtensionError(ValueError):
+    """Raised when attachment has a blocked file extension."""
+
+    def __init__(self, filename: str, extension: str) -> None:
+        self.filename = filename
+        self.extension = extension
+        message = (
+            f"Attachment '{filename}' has blocked extension '.{extension}'. "
+            f"Executable and script file types are not allowed for security reasons."
+        )
+        super().__init__(message)
+
+
+class ExtensionNotAllowedError(ValueError):
+    """Raised when attachment extension is not in the allow-list."""
+
+    def __init__(self, filename: str, extension: str | None) -> None:
+        self.filename = filename
+        self.extension = extension
+        if extension is None:
+            message = (
+                f"Attachment '{filename}' has no file extension. "
+                f"Files without extensions are not allowed."
+            )
+        else:
+            message = (
+                f"Attachment '{filename}' has extension '.{extension}' which is not "
+                f"in the allowed extensions list."
+            )
+        super().__init__(message)
+
+
+class AttachmentSizeError(ValueError):
+    """Raised when attachment content exceeds the maximum allowed size."""
+
+    def __init__(self, filename: str, actual_size: int, max_size: int | None = None) -> None:
+        self.filename = filename
+        self.actual_size = actual_size
+        self.max_size = max_size if max_size is not None else DEFAULT_MAX_ATTACHMENT_SIZE
+        message = (
+            f"Attachment '{filename}' exceeds maximum size of "
+            f"{self.max_size / (1024 * 1024):.2f}MB "
+            f"(size: {actual_size / (1024 * 1024):.2f}MB)"
+        )
+        super().__init__(message)
+
+
+class InvalidMimeTypeError(ValueError):
+    """Raised when MIME type format is invalid or not in the allowlist."""
+
+    def __init__(self, filename: str, mime_type: str, *, invalid_format: bool = False) -> None:
+        self.filename = filename
+        self.mime_type = mime_type
+        self.invalid_format = invalid_format
+        if invalid_format:
+            message = (
+                f"Invalid MIME type format '{mime_type}' for attachment '{filename}'. "
+                f"MIME type must be in 'type/subtype' format (e.g., 'text/plain', 'image/png')."
+            )
+        else:
+            message = f"MIME type '{mime_type}' is not allowed for attachment '{filename}'."
+        super().__init__(message)

platzky/attachment/core.py

@@ -0,0 +1,268 @@
+"""Core Attachment class factory for file attachments in notifications."""
+
+from __future__ import annotations
+
+import logging
+import mimetypes
+import ntpath
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from platzky.attachment.constants import (
+    AttachmentSizeError,
+    BlockedExtensionError,
+    ExtensionNotAllowedError,
+    InvalidMimeTypeError,
+)
+from platzky.attachment.mime_validation import validate_content_mime_type
+
+if TYPE_CHECKING:
+    from platzky.config import AttachmentConfig
+
+logger = logging.getLogger(__name__)
+
+
+@runtime_checkable
+class AttachmentProtocol(Protocol):
+    """Protocol defining the interface for Attachment classes.
+
+    This protocol allows type-safe usage of dynamically created Attachment classes.
+    """
+
+    filename: str
+    content: bytes
+    mime_type: str
+
+    def __init__(
+        self,
+        filename: str,
+        content: bytes,
+        mime_type: str,
+        _max_size: int | None = None,
+    ) -> None: ...
+
+    @classmethod
+    def from_bytes(
+        cls,
+        content: bytes,
+        filename: str,
+        mime_type: str,
+        max_size_override: int | None = None,
+    ) -> AttachmentProtocol: ...
+
+    @classmethod
+    def from_file(
+        cls,
+        file_path: str | Path,
+        filename: str | None = None,
+        mime_type: str | None = None,
+        max_size_override: int | None = None,
+    ) -> AttachmentProtocol: ...
+
+
+def _sanitize_filename(filename: str) -> str:
+    """Remove path components from filename, returning just the basename.
+
+    Strips trailing separators first to handle path-only inputs like "/" or "dir/",
+    then extracts basename. Returns empty string for invalid inputs rather than
+    preserving path separators, allowing validation to reject them.
+    """
+    # Strip trailing separators to handle inputs like "/" or "dir/"
+    stripped = filename.rstrip("/\\")
+    return os.path.basename(ntpath.basename(stripped))
+
+
+def _get_extension(filename: str) -> str | None:
+    """Extract the file extension from a filename, lowercased.
+
+    Returns None if no extension is found or if extension is empty (e.g., "file.").
+    """
+    if "." not in filename:
+        return None
+    ext = filename.rsplit(".", 1)[-1]
+    return ext.lower() or None
+
+
+def _guess_mime_type(filename: str) -> str:
+    """Guess MIME type from filename, defaulting to application/octet-stream."""
+    guessed_type, _ = mimetypes.guess_type(filename)
+    return guessed_type or "application/octet-stream"
+
+
+def _validate_extension(
+    filename: str,
+    ext: str | None,
+    blocked_extensions: frozenset[str],
+    allowed_extensions: frozenset[str] | None,
+) -> None:
+    """Validate filename extension against block-list and allow-list.
+
+    Validation order:
+    1. If extension is in blocked_extensions → REJECT (BlockedExtensionError)
+    2. If allowed_extensions is None → REJECT (ExtensionNotAllowedError)
+    3. If no extension → REJECT (ExtensionNotAllowedError)
+    4. If extension not in allowed_extensions → REJECT (ExtensionNotAllowedError)
+    5. Otherwise → ALLOW
+    """
+    if ext is not None and ext in blocked_extensions:
+        raise BlockedExtensionError(filename, ext)
+
+    if allowed_extensions is None or ext is None or ext not in allowed_extensions:
+        raise ExtensionNotAllowedError(filename, ext)
+
+
+def _validate_mime_type(mime_type: str, filename: str, allowed_mime_types: frozenset[str]) -> None:
+    """Validate MIME type format and against allowlist."""
+    if not mime_type or "/" not in mime_type:
+        raise InvalidMimeTypeError(filename, mime_type, invalid_format=True)
+
+    if mime_type not in allowed_mime_types:
+        raise InvalidMimeTypeError(filename, mime_type)
+
+
+def _do_sanitize_filename(filename: str) -> str:
+    """Sanitize filename and return result. Raises if empty or invalid after sanitization."""
+    sanitized = _sanitize_filename(filename)
+    if not sanitized or sanitized in (".", ".."):
+        raise ValueError("Attachment filename cannot be empty")
+    if sanitized != filename:
+        logger.warning(
+            "Attachment filename contained path components, sanitized from '%s' to '%s'",
+            filename,
+            sanitized,
+        )
+    return sanitized
+
+
+def create_attachment_class(config: AttachmentConfig) -> type:
+    """Create an Attachment class with configuration captured via closure.
+
+    Args:
+        config: Attachment configuration containing allowed_mime_types,
+            validate_content, allow_unrecognized_content, max_size,
+            and blocked_extensions.
+
+    Returns:
+        A configured Attachment class that validates attachments according
+        to the provided configuration.
+
+    Example:
+        >>> from platzky.config import AttachmentConfig
+        >>> config = AttachmentConfig()
+        >>> Attachment = create_attachment_class(config)
+        >>> attachment = Attachment("report.pdf", pdf_bytes, "application/pdf")
+    """
+    # Capture config values in closure
+    allowed_mime_types = config.allowed_mime_types
+    validate_content = config.validate_content
+    allow_unrecognized_content = config.allow_unrecognized_content
+    max_size = config.max_size
+    blocked_extensions = config.blocked_extensions
+    allowed_extensions = config.allowed_extensions
+
+    @dataclass(frozen=True)
+    class Attachment:
+        """Represents a file attachment for notifications.
+
+        Attributes:
+            filename: Name of the file (without path components).
+            content: Binary content of the file.
+            mime_type: MIME type of the file (e.g., 'image/png', 'application/pdf').
+
+        Raises:
+            ValueError: If filename is empty or MIME type is invalid/not allowed.
+            AttachmentSizeError: If content exceeds configured max_size.
+            ContentMismatchError: If content does not match declared MIME type.
+
+        Example:
+            >>> attachment = Attachment("report.pdf", pdf_bytes, "application/pdf")
+        """
+
+        filename: str
+        content: bytes
+        mime_type: str
+        _max_size: int | None = field(default=None, repr=False, compare=False)
+
+        def __post_init__(self) -> None:
+            """Validate attachment data using config from closure."""
+            sanitized = _do_sanitize_filename(self.filename)
+            if sanitized != self.filename:
+                object.__setattr__(self, "filename", sanitized)
+
+            _validate_extension(
+                self.filename, _get_extension(self.filename), blocked_extensions, allowed_extensions
+            )
+
+            effective_max_size = self._max_size if self._max_size is not None else max_size
+            if len(self.content) > effective_max_size:
+                raise AttachmentSizeError(self.filename, len(self.content), effective_max_size)
+
+            _validate_mime_type(self.mime_type, self.filename, allowed_mime_types)
+
+            if validate_content:
+                validate_content_mime_type(
+                    self.content,
+                    self.mime_type,
+                    self.filename,
+                    allow_unrecognized=allow_unrecognized_content,
+                )
+
+        @classmethod
+        def from_bytes(
+            cls,
+            content: bytes,
+            filename: str,
+            mime_type: str,
+            max_size_override: int | None = None,
+        ) -> Attachment:
+            """Create an Attachment from bytes with size validation before object creation.
+
+            Note: The bytes must already be in memory. This method validates size before
+            creating the Attachment object. For memory-safe loading from disk, use from_file().
+            """
+            limit = max_size if max_size_override is None else max_size_override
+            if len(content) > limit:
+                raise AttachmentSizeError(_sanitize_filename(filename), len(content), limit)
+            return cls(filename=filename, content=content, mime_type=mime_type, _max_size=limit)
+
+        @classmethod
+        def from_file(
+            cls,
+            file_path: str | Path,
+            filename: str | None = None,
+            mime_type: str | None = None,
+            max_size_override: int | None = None,
+        ) -> Attachment:
+            """Create an Attachment from a file path with bounded read for size safety.
+
+            Uses a bounded read to prevent loading oversized files into memory,
+            avoiding TOCTOU issues where a file could grow between size check and read.
+            """
+            path = Path(file_path)
+            limit = max_size if max_size_override is None else max_size_override
+
+            # Early check to reject obviously oversized files without opening them
+            file_size = path.stat().st_size
+            if file_size > limit:
+                raise AttachmentSizeError(path.name, file_size, limit)
+
+            # Bounded read to prevent TOCTOU: even if file grows after stat(),
+            # we never load more than limit + 1 bytes
+            with path.open("rb") as f:
+                content = f.read(limit + 1)
+
+            if len(content) > limit:
+                # Report actual bytes read (not stat size) for TOCTOU consistency
+                raise AttachmentSizeError(path.name, len(content), limit)
+
+            effective_filename = filename or path.name
+            return cls(
+                filename=effective_filename,
+                content=content,
+                mime_type=mime_type or _guess_mime_type(effective_filename),
+                _max_size=limit,
+            )
+
+    return Attachment

platzky/attachment/mime_validation.py

@@ -0,0 +1,82 @@
+"""MIME type validation utilities using puremagic for content detection."""
+
+from __future__ import annotations
+
+import puremagic
+
+
+class ContentMismatchError(ValueError):
+    """Raised when attachment content does not match the declared MIME type."""
+
+
+# MIME type equivalences - puremagic may return alternative names for the same format
+# Maps canonical types to their aliases
+_MIME_EQUIVALENCES: dict[str, set[str]] = {
+    "image/bmp": {"image/x-ms-bmp"},
+    "application/gzip": {"application/x-gzip"},
+    "application/zip": {"application/x-zip-compressed"},
+}
+
+# Reverse mapping: alias -> canonical type
+_ALIAS_TO_CANONICAL: dict[str, str] = {
+    alias: canonical for canonical, aliases in _MIME_EQUIVALENCES.items() for alias in aliases
+}
+
+# Text-based formats that don't have reliable magic bytes.
+# Note: These types are NOT in the default allowed MIME types for security reasons.
+# If users explicitly allow these types, content validation will be skipped.
+_SKIP_VALIDATION_TYPES = {"application/json", "application/xml", "application/rtf", "image/svg+xml"}
+
+
+def validate_content_mime_type(
+    content: bytes,
+    mime_type: str,
+    filename: str,
+    *,
+    allow_unrecognized: bool = False,
+) -> None:
+    """Validate that content matches the declared MIME type using magic bytes.
+
+    Args:
+        content: The binary content to validate.
+        mime_type: The declared MIME type.
+        filename: The filename (used for error messages).
+        allow_unrecognized: If True, allow content that cannot be identified.
+
+    Raises:
+        ContentMismatchError: If content does not match the declared MIME type.
+    """
+    # Skip validation for empty content, text types, and text-based formats
+    if not content or mime_type.startswith("text/") or mime_type in _SKIP_VALIDATION_TYPES:
+        return
+
+    try:
+        detected = puremagic.magic_string(content)
+    except puremagic.PureError as err:
+        if allow_unrecognized:
+            return
+        raise ContentMismatchError(
+            f"Content of '{filename}' does not match declared MIME type '{mime_type}'. "
+            "Could not identify file type from content."
+        ) from err
+
+    detected_mimes = {m.mime_type for m in detected if m.mime_type}
+
+    # Direct match
+    if mime_type in detected_mimes:
+        return
+
+    # Check if declared type is canonical and detected includes an alias
+    equivalent_aliases = _MIME_EQUIVALENCES.get(mime_type, set())
+    if detected_mimes & equivalent_aliases:
+        return
+
+    # Check if declared type is an alias and detected includes the canonical
+    canonical = _ALIAS_TO_CANONICAL.get(mime_type)
+    if canonical and canonical in detected_mimes:
+        return
+
+    raise ContentMismatchError(
+        f"Content of '{filename}' does not match declared MIME type '{mime_type}'. "
+        f"Detected types: {detected_mimes}"
+    )

platzky/config.py

@@ -9,6 +9,7 @@ import typing as t
 import yaml
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
+from .attachment.constants import BLOCKED_EXTENSIONS, DEFAULT_MAX_ATTACHMENT_SIZE
 from .db.db import DBConfig
 from .db.db_loader import get_db_module
 
@@ -126,6 +127,99 @@ class TelemetryConfig(StrictBaseModel):
         return v
 
 
+_DEFAULT_ALLOWED_MIME_TYPES: frozenset[str] = frozenset(
+    {
+        # Image types (binary formats with verifiable magic bytes)
+        "image/png",
+        "image/jpeg",
+        "image/gif",
+        "image/webp",
+        "image/bmp",
+        "image/tiff",
+        # Application types (binary formats)
+        "application/pdf",
+        # Archive types - validated but NEVER auto-extracted (zip bomb protection)
+        "application/zip",
+        "application/gzip",
+        "application/x-tar",
+        "application/msword",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        "application/vnd.ms-excel",
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        "application/vnd.ms-powerpoint",
+        "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+        # Audio types
+        "audio/mpeg",
+        "audio/wav",
+        "audio/ogg",
+        # Video types
+        "video/mp4",
+        "video/webm",
+        "video/ogg",
+        # Note: Text types (text/*, application/json, application/xml, application/rtf,
+        # image/svg+xml) are NOT included by default for security reasons. They can
+        # bypass content validation and may contain executable code. To allow text
+        # types, explicitly add them:
+        #   AttachmentConfig(allowed_mime_types=_DEFAULT_ALLOWED_MIME_TYPES | {"text/plain"})
+    }
+)
+
+
+class AttachmentConfig(StrictBaseModel):
+    """Configuration for attachment handling.
+
+    Attributes:
+        allowed_mime_types: MIME types allowed for attachments.
+        validate_content: Whether to validate content matches declared MIME type.
+        allow_unrecognized_content: If True, allow content that cannot be identified.
+        max_size: Maximum attachment size in bytes (default: 10MB).
+        blocked_extensions: File extensions that are PERMANENTLY blocked (executable
+            and script formats). These cannot be overridden via allowed_extensions.
+        allowed_extensions: File extensions to allow. Defaults to common safe formats
+            (images, documents, archives, audio/video). Set to None to block all.
+            Note: blocked_extensions takes precedence over allowed_extensions.
+            Files without extensions are always blocked when allowed_extensions is set.
+    """
+
+    allowed_mime_types: frozenset[str] = Field(default=_DEFAULT_ALLOWED_MIME_TYPES)
+    validate_content: bool = Field(default=True)
+    allow_unrecognized_content: bool = Field(default=False)
+    max_size: int = Field(default=DEFAULT_MAX_ATTACHMENT_SIZE, gt=0)
+    blocked_extensions: frozenset[str] = Field(default=BLOCKED_EXTENSIONS)
+    allowed_extensions: frozenset[str] | None = Field(
+        default=frozenset(
+            {
+                # Images
+                "png",
+                "jpg",
+                "jpeg",
+                "gif",
+                "webp",
+                "bmp",
+                "tiff",
+                # Documents
+                "pdf",
+                "doc",
+                "docx",
+                "xls",
+                "xlsx",
+                "ppt",
+                "pptx",
+                # Archives
+                "zip",
+                "gz",
+                "tar",
+                # Audio/Video
+                "mp3",
+                "wav",
+                "ogg",
+                "mp4",
+                "webm",
+            }
+        )
+    )
+
+
 class Config(StrictBaseModel):
     """Main application configuration.
 
@@ -143,6 +237,7 @@ class Config(StrictBaseModel):
         testing: Enable testing mode
         feature_flags: Feature flag configuration
         telemetry: OpenTelemetry configuration
+        attachment: Attachment handling configuration
     """
 
     app_name: str = Field(alias="APP_NAME")
@@ -161,6 +256,7 @@ class Config(StrictBaseModel):
     testing: bool = Field(default=False, alias="TESTING")
     feature_flags: t.Optional[dict[str, bool]] = Field(default=None, alias="FEATURE_FLAGS")
     telemetry: TelemetryConfig = Field(default_factory=TelemetryConfig, alias="TELEMETRY")
+    attachment: AttachmentConfig = Field(default_factory=AttachmentConfig, alias="ATTACHMENT")
 
     @classmethod
     def model_validate(

platzky/engine.py

@@ -1,22 +1,44 @@
+"""Flask application engine with notification support."""
+
+import logging
 import os
+import threading
 from collections.abc import Callable
-from concurrent.futures import ThreadPoolExecutor, TimeoutError
+from concurrent.futures import Future, TimeoutError
 from typing import Any
 
-from flask import Blueprint, Flask, jsonify, make_response, request, session
+from flask import Blueprint, Flask, Response, jsonify, make_response, request, session
 from flask_babel import Babel
 
+from platzky.attachment import AttachmentProtocol, create_attachment_class
 from platzky.config import Config
 from platzky.db.db import DB
 from platzky.models import CmsModule
+from platzky.notifier import Notifier, NotifierWithAttachments
+
+logger = logging.getLogger(__name__)
 
 
 class Engine(Flask):
-    def __init__(self, config: Config, db: DB, import_name: str) -> None:
+    def __init__(
+        self,
+        config: Config,
+        db: DB,
+        import_name: str,
+    ) -> None:
+        """Initialize the Engine.
+
+        Args:
+            config: Application configuration.
+            db: Database instance.
+            import_name: Name of the application module.
+        """
         super().__init__(import_name)
         self.config.from_mapping(config.model_dump(by_alias=True))
         self.db = db
-        self.notifiers = []
+        self.Attachment: type[AttachmentProtocol] = create_attachment_class(config.attachment)
+        self.notifiers: list[Notifier] = []
+        self.notifiers_with_attachments: list[NotifierWithAttachments] = []
         self.login_methods = []
         self.dynamic_body = ""
         self.dynamic_head = ""
@@ -37,13 +59,34 @@ class Engine(Flask):
         # TODO add plugins as CMS Module - all plugins should be visible from
         # admin page at least as configuration
 
-    def notify(self, message: str):
+    def notify(self, message: str, attachments: list[AttachmentProtocol] | None = None) -> None:
+        """Send a notification to all registered notifiers.
+
+        Args:
+            message: The notification message text.
+            attachments: Optional list of Attachment objects created via engine.Attachment().
+        """
         for notifier in self.notifiers:
             notifier(message)
+        for notifier in self.notifiers_with_attachments:
+            notifier(message, attachments=attachments)
 
-    def add_notifier(self, notifier: Callable[[str], None]) -> None:
+    def add_notifier(self, notifier: Notifier) -> None:
+        """Register a simple notifier (message only).
+
+        Args:
+            notifier: A callable that accepts a message string.
+        """
         self.notifiers.append(notifier)
 
+    def add_notifier_with_attachments(self, notifier: NotifierWithAttachments) -> None:
+        """Register a notifier that supports attachments.
+
+        Args:
+            notifier: A callable that accepts message and optional attachments.
+        """
+        self.notifiers_with_attachments.append(notifier)
+
     def add_cms_module(self, module: CmsModule):
         """Add a CMS module to the modules list."""
         self.cms_modules.append(module)
@@ -82,62 +125,68 @@ class Engine(Flask):
             raise TypeError(f"check_function must be callable, got {type(check_function)}")
         self.health_checks.append((name, check_function))
 
-    def _register_default_health_endpoints(self):
-        """Register default health endpoints"""
-
+    def _register_default_health_endpoints(self) -> None:
+        """Register default health endpoints."""
         health_bp = Blueprint("health", __name__)
-        HEALTH_CHECK_TIMEOUT = 10  # seconds
+        health_check_timeout = 10  # seconds
+
+        def run_health_check(
+            check_func: Callable[[], None],
+            timeout: int,
+        ) -> str:
+            """Run a health check with timeout using a daemon thread.
+
+            Uses daemon threads so stuck checks don't prevent app shutdown.
+            Note: Health checks should implement their own internal timeouts
+            for proper resource cleanup - the external timeout only prevents
+            blocking the response, but the check continues running.
+            """
+            future: Future[None] = Future()
+
+            def run() -> None:
+                try:
+                    check_func()
+                    future.set_result(None)
+                except Exception as e:
+                    future.set_exception(e)
+
+            thread = threading.Thread(target=run, daemon=True)
+            thread.start()
+
+            try:
+                future.result(timeout=timeout)
+            except TimeoutError:
+                return "failed: timeout"
+            except Exception as e:
+                logger.exception("Health check failed")
+                return f"failed: {e!s}"
+            else:
+                return "ok"
 
         @health_bp.route("/health/liveness")
-        def liveness():
+        def liveness() -> tuple[Response, int]:
             """Simple liveness check - is the app running?"""
             return jsonify({"status": "alive"}), 200
 
         @health_bp.route("/health/readiness")
-        def readiness():
+        def readiness() -> Response:
             """Readiness check - can the app serve traffic?"""
             health_status: dict[str, Any] = {"status": "ready", "checks": {}}
-            status_code = 200
 
-            executor = ThreadPoolExecutor(max_workers=1)
-            try:
-                # Database health check with timeout
-                future = executor.submit(self.db.health_check)
-                try:
-                    future.result(timeout=HEALTH_CHECK_TIMEOUT)
-                    health_status["checks"]["database"] = "ok"
-                except TimeoutError:
-                    health_status["checks"]["database"] = "failed: timeout"
-                    health_status["status"] = "not_ready"
-                    status_code = 503
-                except Exception as e:
-                    health_status["checks"]["database"] = f"failed: {e!s}"
+            all_checks = [("database", self.db.health_check), *self.health_checks]
+
+            for check_name, check_func in all_checks:
+                status = run_health_check(check_func, health_check_timeout)
+                health_status["checks"][check_name] = status
+                if status != "ok":
                     health_status["status"] = "not_ready"
-                    status_code = 503
-
-                # Run application-registered health checks
-                for check_name, check_func in self.health_checks:
-                    future = executor.submit(check_func)
-                    try:
-                        future.result(timeout=HEALTH_CHECK_TIMEOUT)
-                        health_status["checks"][check_name] = "ok"
-                    except TimeoutError:
-                        health_status["checks"][check_name] = "failed: timeout"
-                        health_status["status"] = "not_ready"
-                        status_code = 503
-                    except Exception as e:
-                        health_status["checks"][check_name] = f"failed: {e!s}"
-                        health_status["status"] = "not_ready"
-                        status_code = 503
-            finally:
-                # Shutdown without waiting if any futures are still running
-                executor.shutdown(wait=False)
 
+            status_code = 200 if health_status["status"] == "ready" else 503
             return make_response(jsonify(health_status), status_code)
 
-        # Simple /health alias for liveness
         @health_bp.route("/health")
-        def health():
+        def health() -> tuple[Response, int]:
+            """Simple /health alias for liveness."""
             return liveness()
 
         self.register_blueprint(health_bp)

platzky/notifier.py

@@ -0,0 +1,43 @@
+"""Notification system types and protocols.
+
+This module provides notifier protocols for the platzky notification system.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from platzky.attachment import AttachmentProtocol
+
+
+class Notifier(Protocol):
+    """Protocol for simple notification handlers (message only).
+
+    Example:
+        def slack_notifier(message: str) -> None:
+            slack.post(message)
+
+        engine.add_notifier(slack_notifier)
+    """
+
+    def __call__(self, message: str) -> None: ...
+
+
+class NotifierWithAttachments(Protocol):
+    """Protocol for notification handlers that support attachments.
+
+    SECURITY: Archive attachments (zip, gzip, tar) are validated but never
+    extracted by platzky. Notifier implementations MUST NOT auto-extract
+    archives to avoid zip bomb attacks.
+
+    Example:
+        def email_notifier(message: str, attachments: list | None = None) -> None:
+            send_email(message, attachments=attachments)
+
+        engine.add_notifier_with_attachments(email_notifier)
+    """
+
+    def __call__(
+        self, message: str, attachments: list[AttachmentProtocol] | None = None
+    ) -> None: ...

{platzky-1.2.2.dist-info → platzky-1.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: platzky
-Version: 1.2.2
+Version: 1.3.0
 Summary: Not only blog engine
 License: MIT
 License-File: LICENSE
@@ -30,6 +30,7 @@ Requires-Dist: opentelemetry-exporter-otlp-proto-grpc (>=1.27.0,<2.0.0) ; extra
 Requires-Dist: opentelemetry-instrumentation-flask (>=0.48b0,<0.49) ; extra == "telemetry"
 Requires-Dist: opentelemetry-instrumentation-logging (>=0.48b0,<0.49) ; extra == "telemetry"
 Requires-Dist: opentelemetry-sdk (>=1.27.0,<2.0.0) ; extra == "telemetry"
+Requires-Dist: puremagic (>=1.30,<2.0)
 Requires-Dist: pydantic (>=2.7.1,<3.0.0)
 Requires-Dist: pygithub (>=2.6.1,<3.0.0)
 Requires-Dist: pymongo (>=4.7.0,<5.0.0)

{platzky-1.2.2.dist-info → platzky-1.3.0.dist-info}/RECORD

@@ -4,10 +4,14 @@ platzky/admin/fake_login.py,sha256=Z_4M4PLQ73qL-sKh05CmDx_nFy8S30PdsNfPPDeFSmE,3
 platzky/admin/templates/admin.html,sha256=zgjROhSezayZqnNFezvVa0MEfgmXLvOM8HRRaZemkQw,688
 platzky/admin/templates/login.html,sha256=oBNuv130iMTwXrtRnDUDcGIGvu0O2VsIbjQxw-Tjd7Y,380
 platzky/admin/templates/module.html,sha256=WuQZxKQDD4INl-QF2uiKHf9Fmf2h7cEW9RLe1nWKC8k,175
+platzky/attachment/__init__.py,sha256=v60Fk8yrTc4KeQdHzEfJWbsXD7uQp3ZAHQDksrBEuws,1349
+platzky/attachment/constants.py,sha256=9WB8w_sKxsq2DM5hfz2ShRI-nUT2E5v9tfBWIOgrq-U,4135
+platzky/attachment/core.py,sha256=-jrelChnHEeowg5d4-41fY6slFfqnv3fEqiI_sMPFd8,9656
+platzky/attachment/mime_validation.py,sha256=VO272nF7K_Mx_Zefuw-10M-Tapj0ZxX197syh8yy0oQ,2874
 platzky/blog/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 platzky/blog/blog.py,sha256=n3bsZ1GpVCmvxCFMiF7QUDb_PHbmBiTu0GDu3r_Su24,5490
 platzky/blog/comment_form.py,sha256=yOuXvX9PZLc6qQLIWZWLFcbwFQD4a849X82PlXKUzdk,805
-platzky/config.py,sha256=_TQNZ8w8-xQImtm6Gw2SawBqf-UFxF9okIlZi_DGrGA,7540
+platzky/config.py,sha256=4HPfJ1bY2A1auSR9dbGwDIo65SRolQ6H3imMDyuvH30,11194
 platzky/db/README.md,sha256=IO-LoDsd4dLBZenaz423EZjvEOQu_8m2OC0G7du170w,1753
 platzky/db/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 platzky/db/db.py,sha256=gi5uxvY8Ww8O4y2rxaH1Zj_12Yno8SbILvIaWnQPbYQ,4778
@@ -18,10 +22,11 @@ platzky/db/graph_ql_db.py,sha256=a8LGPJKoNpmTkJ6Bb89eg6m6Q9GFetp5z8A0xuemuSk,145
 platzky/db/json_db.py,sha256=pANXJZzVPAO890TRy3IvzHjpCaeDgNNgNOR5Uhkk2h4,8078
 platzky/db/json_file_db.py,sha256=Tl6b67p4hNViXSAjujXZ9vtVHN61QhrzJUgOuvngyMI,2232
 platzky/db/mongodb_db.py,sha256=nq07j0NldK014qRL1mF-cvBXQF1LKKTTeWxaZdyzjAs,8595
-platzky/engine.py,sha256=9Y74nrO4gwr9_CqRTzPs9LtcY2t0fs0XtPyjPiqRlVQ,5573
+platzky/engine.py,sha256=wNVNjLA5UpN5sNF2S5ltCJM0e9rKAbrp6SqInqwbgz8,7079
 platzky/locale/en/LC_MESSAGES/messages.po,sha256=WaZGlFAegKRq7CSz69dWKic-mKvQFhVvssvExxNmGaU,1400
 platzky/locale/pl/LC_MESSAGES/messages.po,sha256=sUPxMKDeEOoZ5UIg94rGxZD06YVWiAMWIby2XE51Hrc,1624
 platzky/models.py,sha256=Ws5ZSWf5EhcpFxl3Yeze2pQiesjnjAA_haBJ90bN6lk,7435
+platzky/notifier.py,sha256=fh6_sdeD9TRFPkBjnuSz9jH6UKoSDkaqqGfZD1dmVZc,1214
 platzky/platzky.py,sha256=1LKYq8pLm1QBlOcEPhugxWi8W0vuWqjjINIFK8b2Kow,9319
 platzky/plugin/plugin.py,sha256=KZb6VEph__lx9xrv5Ay4h4XkFFYbodV5OimaG6B9IDc,2812
 platzky/plugin/plugin_loader.py,sha256=eKG6zodUCkiRLxJ2ZX9zdN4-ZrZ9EwssoY1SDtThaFo,6707
@@ -41,7 +46,7 @@ platzky/templates/post.html,sha256=GSgjIZsOQKtNx3cEbquSjZ5L4whPnG6MzRyoq9k4B8Q,1
 platzky/templates/robots.txt,sha256=2_j2tiYtYJnzZUrANiX9pvBxyw5Dp27fR_co18BPEJ0,116
 platzky/templates/sitemap.xml,sha256=iIJZ91_B5ZuNLCHsRtsGKZlBAXojOTP8kffqKLacgvs,578
 platzky/www_handler.py,sha256=pF6Rmvem1sdVqHD7z3RLrDuG-CwAqfGCti50_NPsB2w,725
-platzky-1.2.2.dist-info/METADATA,sha256=X-0JrkrtD11LPZthFnzRinn3fjUXiWYRXnnkEzjgMcg,2556
-platzky-1.2.2.dist-info/WHEEL,sha256=3ny-bZhpXrU6vSQ1UPG34FoxZBp3lVcvK0LkgUz6VLk,88
-platzky-1.2.2.dist-info/licenses/LICENSE,sha256=wCdfk-qEosi6BDwiBulMfKMi0hxp1UXV0DdjLrRm788,1077
-platzky-1.2.2.dist-info/RECORD,,
+platzky-1.3.0.dist-info/METADATA,sha256=tOipcd7zixJPKW2a0fRgnPQzqVyrET55p0MeVxYRNc0,2595
+platzky-1.3.0.dist-info/WHEEL,sha256=3ny-bZhpXrU6vSQ1UPG34FoxZBp3lVcvK0LkgUz6VLk,88
+platzky-1.3.0.dist-info/licenses/LICENSE,sha256=wCdfk-qEosi6BDwiBulMfKMi0hxp1UXV0DdjLrRm788,1077
+platzky-1.3.0.dist-info/RECORD,,