commentail 0.1.0__py3-none-any.whl

commentail/admission.py

@@ -0,0 +1,201 @@
+"""Request authorization boundary for the future server-rendered form adapter.
+
+Do not bypass this boundary with direct calls to trusted domain services.
+Views must still enforce POST and CSRF through Django middleware/decorators.
+"""
+
+import secrets
+from datetime import timedelta
+
+from django.conf import settings
+from django.core.mail import get_connection
+from django.core.mail.backends.smtp import EmailBackend
+from django.db import transaction
+from django.db.models import F
+from django.http import HttpRequest
+from django.utils import timezone
+from wagtail.models import Site
+
+from .config import technical_settings
+from .limits import client_ip, consume
+from .models import Access, Comment, Discussion, FormTicket, Mode, SubmissionRecord
+from .policies import editorial_settings, email_enabled
+from .security import digest, remembered_guest, verify_captcha
+from .services import DomainError, _text, confirm_email, submit_once
+
+
+def session_digest(request: HttpRequest) -> str:
+    if not request.session.session_key:
+        request.session.create()
+    return digest(request.session.session_key)
+
+
+def can_view(request: HttpRequest, discussion: Discussion) -> bool:
+    if not discussion.page_id:
+        from .objects import ObjectAccessError, checked_site, target_for
+
+        try:
+            return (
+                checked_site(target_for(discussion), request).pk == discussion.site_id
+            )
+        except ObjectAccessError:
+            return False
+    page = discussion.page
+    return page.live and all(
+        restriction.accept_request(request)
+        for restriction in page.get_view_restrictions()
+    )
+
+
+def smtp_configured() -> bool:
+    return (
+        isinstance(get_connection(), EmailBackend)
+        and settings.is_overridden("EMAIL_HOST")
+        and bool(settings.EMAIL_HOST)
+    )
+
+
+def issue_form(request: HttpRequest, discussion: Discussion) -> str:
+    if not can_view(request, discussion):
+        raise DomainError("Page access is required")
+    secret = secrets.token_urlsafe(32)
+    FormTicket.objects.create(
+        digest=digest(secret),
+        discussion=discussion,
+        session_digest=session_digest(request),
+        expires_at=timezone.now()
+        + timedelta(seconds=technical_settings(discussion.site)["FORM_TICKET_SECONDS"]),
+    )
+    return secret
+
+
+def accept_request(
+    request: HttpRequest,
+    discussion_id: int,
+    key: str,
+    *,
+    text: str,
+    guest_name: str = "",
+    guest_email: str = "",
+    reply_to: int | None = None,
+    challenge_id: str = "",
+    answer: str = "",
+    subscribe: bool = False,
+) -> Comment:
+    """Validate access on every attempt, including already-accepted form replays.
+
+    Incorrect CAPTCHA attempts commit before DomainError is raised, so the
+    attempts counter cannot be reset by rolling back a rejected submission.
+    A successful CAPTCHA and accepted comment share a transaction.
+    """
+    site = Site.find_for_request(request)
+    if site is None:
+        raise DomainError("Site cannot be determined")
+    failure = None
+    result = None
+    with transaction.atomic():
+        # Lock site-wide quotas before any reads in this admission transaction.
+        if not Site.objects.filter(pk=site.pk).update(port=F("port")):
+            raise DomainError("Site does not exist")
+        discussion = (
+            Discussion.objects.select_related("site", "page")
+            .filter(pk=discussion_id, site=site)
+            .first()
+        )
+        if discussion is None or not can_view(request, discussion):
+            raise DomainError("Page access is required")
+        options = editorial_settings(discussion)
+        if options.mode != Mode.OPEN:
+            raise DomainError("Discussion is closed")
+        ticket = FormTicket.objects.filter(
+            digest=digest(key),
+            discussion=discussion,
+            session_digest=session_digest(request),
+            expires_at__gt=timezone.now(),
+        ).first()
+        if ticket is None:
+            raise DomainError("Invalid or expired form")
+        user = request.user if request.user.is_authenticated else None
+        if user is not None and not user.is_active:
+            raise DomainError("Account cannot comment")
+        if (
+            options.access == Access.NONE
+            or (user is None and options.access == Access.REGISTERED)
+            or (user is not None and options.access == Access.GUESTS)
+        ):
+            raise DomainError("Author cannot comment")
+        mail_available = email_enabled(site.pk) and smtp_configured()
+        subscribe = mail_available and bool(
+            guest_email.strip() if user is None else getattr(user, "email", "")
+        )
+        if user is None and not mail_available:
+            raise DomainError("Guest comments require configured SMTP")
+        actor = (
+            "user:" + str(user.pk)
+            if user is not None
+            else "guest:" + guest_email.strip().casefold()
+        )
+        if SubmissionRecord.objects.filter(
+            discussion=discussion, actor_digest=digest(actor), key_digest=digest(key)
+        ).exists():
+            return submit_once(
+                discussion.pk,
+                key,
+                text=text,
+                user=user,
+                guest_name=guest_name,
+                guest_email=guest_email,
+                reply_to=reply_to,
+                subscribe=subscribe,
+                language=getattr(request, "LANGUAGE_CODE", settings.LANGUAGE_CODE),
+            )
+        _text(text, options)
+        grant = (
+            remembered_guest(
+                request.COOKIES.get(f"commentail_guest_{site.pk}", ""), site
+            )
+            if user is None
+            else None
+        )
+        remembered = (
+            grant is not None
+            and grant.email.strip().casefold() == guest_email.strip().casefold()
+        )
+        if (
+            user is None
+            and not remembered
+            and not verify_captcha(request, site, challenge_id, answer)
+        ):
+            failure = "Incorrect or expired CAPTCHA"
+        else:
+            consume(site, "comment", actor, client_ip(request, site))
+            checks = technical_settings(site)["GUEST_REQUEST_CHECKS"]
+            suspicious = user is None and (
+                (
+                    "missing_user_agent" in checks
+                    and not request.META.get("HTTP_USER_AGENT", "").strip()
+                )
+                or (
+                    "cross_site" in checks
+                    and request.META.get("HTTP_SEC_FETCH_SITE") == "cross-site"
+                )
+            )
+            result = submit_once(
+                discussion.pk,
+                key,
+                text=text,
+                user=user,
+                guest_name=guest_name,
+                guest_email=guest_email,
+                reply_to=reply_to,
+                subscribe=subscribe,
+                suspicious=suspicious,
+                language=getattr(request, "LANGUAGE_CODE", settings.LANGUAGE_CODE),
+            )
+            if user is None and remembered:
+                result = confirm_email(result.pk)
+    if failure:
+        raise DomainError(failure)
+    if result is None:
+        raise DomainError("Submission was not accepted")
+    return result

commentail/apps.py

@@ -0,0 +1,19 @@
+from importlib import import_module
+
+from django.apps import AppConfig
+
+
+class CommentailConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "commentail"
+
+    def ready(self) -> None:
+        import_module("commentail.checks")
+        import_module("commentail.signals")
+        import logging
+
+        from .logging import CapabilityFilter
+
+        logger = logging.getLogger("django.server")
+        if not any(isinstance(item, CapabilityFilter) for item in logger.filters):
+            logger.addFilter(CapabilityFilter())

commentail/assets.py

@@ -0,0 +1,21 @@
+"""Content-versioned package resources shared by public tags and admin forms."""
+
+from functools import lru_cache
+from hashlib import sha256
+from importlib.resources import files
+from typing import Literal
+
+from django.templatetags.static import static
+
+Asset = Literal["admin.css", "admin.js", "commentail.css", "commentail.js"]
+
+
+@lru_cache(maxsize=4)
+def asset_url(name: Asset) -> str:
+    if name not in ("admin.css", "admin.js", "commentail.css", "commentail.js"):
+        raise ValueError("Unknown Commentail asset")
+    version = sha256(
+        files("commentail").joinpath("static", "commentail", name).read_bytes()
+    ).hexdigest()[:12]
+    url = static("commentail/" + name)
+    return url + ("&" if "?" in url else "?") + "v=" + version

commentail/avatars.py

@@ -0,0 +1,80 @@
+"""Deterministic initials/gradient and a safe read-only avatar callback."""
+
+import logging
+from dataclasses import dataclass
+
+from django.contrib.auth.models import AbstractBaseUser
+from django.db.models import Model
+from django.http import HttpRequest
+from django.utils.module_loading import import_string
+from wagtail.models import Site
+
+from .config import technical_settings
+from .models import Comment
+from .objects import target_for
+
+logger = logging.getLogger("commentail")
+
+
+@dataclass(frozen=True)
+class CommentContext:
+    id: int
+    display_name: str
+    user: AbstractBaseUser | None
+    site: Site
+    target: Model
+
+
+def default_avatar(name: str) -> tuple[str, str]:
+    words = name.strip().split()
+    initials = (
+        (words[0][:2] if len(words) == 1 else words[0][0] + words[-1][0]).upper()
+        if words
+        else ""
+    )
+    if not initials:
+        return "?", "linear-gradient(135deg, hsl(220 85% 56%), hsl(265 85% 60%))"
+    hashed = 2166136261
+    for letter in initials:
+        hashed = ((hashed ^ ord(letter)) * 16777619) & 0xFFFFFFFF
+    hue = hashed % 360
+    second = (hue + 45 + ((hashed >> 8) % 90)) % 360
+    gradient = f"linear-gradient(135deg, hsl({hue} {78 + hashed % 12}% {48 + ((hashed >> 12) % 8)}%), hsl({second} {80 + ((hashed >> 4) % 12)}% {50 + ((hashed >> 20) % 8)}%))"
+    return initials, gradient
+
+
+def author_name(comment: Comment, request: HttpRequest) -> str:
+    path = technical_settings(comment.discussion.site)["GET_AUTHOR_NAME"]
+    if path and comment.user_id:
+        try:
+            value = import_string(path)(comment.user, request)
+            if isinstance(value, str) and value.strip():
+                return value.strip()
+        except Exception as exc:
+            logger.exception(
+                "Author name handler failed (%s)", type(exc).__name__, exc_info=False
+            )
+    return comment.display_name
+
+
+def avatar_url(comment: Comment, request: HttpRequest, name: str) -> str | None:
+    path = technical_settings(comment.discussion.site)["GET_AVATAR"]
+    if not path:
+        return None
+    try:
+        value = import_string(path)(
+            CommentContext(
+                comment.pk,
+                name,
+                comment.user,
+                comment.discussion.site,
+                target_for(comment.discussion),
+            ),
+            request,
+        )
+        return value if isinstance(value, str) and value else None
+    except Exception as exc:
+        logger.exception(
+            "Avatar handler failed (%s)", type(exc).__name__, exc_info=False
+        )
+        return None

commentail/checks.py

@@ -0,0 +1,8 @@
+from django.core.checks import Error, register
+
+from .config import configuration_errors
+
+
+@register()
+def check_settings(app_configs: object, **kwargs: object) -> list[Error]:
+    return [Error(message, id="commentail.E001") for message in configuration_errors()]

commentail/config.py

@@ -0,0 +1,193 @@
+"""Technical settings inherit library defaults, default, then Site.hostname."""
+
+import ipaddress
+from typing import Literal, TypedDict
+
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+from wagtail.models import Site
+
+StructuredDataMode = Literal["both", "json_ld", "microdata", "off"]
+
+
+class TechnicalSettings(TypedDict):
+    STRUCTURED_DATA: StructuredDataMode
+    OBJECT_ADAPTERS: dict[str, str]
+    RULES_CSV_MAX_BYTES: int
+    RULES_CSV_MAX_ROWS: int
+    FORM_TICKET_SECONDS: int
+    EDIT_WINDOW_SECONDS: int
+    EMAIL_CONFIRM_SECONDS: int
+    GUEST_GRANT_SECONDS: int
+    CAPTCHA_SECONDS: int
+    CAPTCHA_ATTEMPTS: int
+    AUTHOR_MIN_INTERVAL: int
+    AUTHOR_LIMIT_PER_HOUR: int
+    IP_LIMIT_PER_HOUR: int
+    RESEND_MIN_INTERVAL: int
+    RESEND_LIMIT_PER_HOUR: int
+    RESEND_IP_LIMIT_PER_HOUR: int
+    CAPTCHA_IP_LIMIT_PER_MINUTE: int
+    CAPTCHA_IP_LIMIT_PER_HOUR: int
+    TRUSTED_PROXIES: list[str]
+    GUEST_REQUEST_CHECKS: list[str]
+    MAIL_RETENTION_SECONDS: int
+    MAIL_LEASE_SECONDS: int
+    MAIL_RETRY_SECONDS: list[int]
+    ACTION_LINK_SECONDS: int
+    CAPTCHA_BACKEND: str | None
+    GET_AVATAR: str | None
+    GET_AUTHOR_NAME: str | None
+    GET_COMMENT_TEMPLATES: str | None
+    CAN_SEND_GUEST_EMAIL: str | None
+
+
+DEFAULTS: TechnicalSettings = {
+    "STRUCTURED_DATA": "both",
+    "OBJECT_ADAPTERS": {},
+    "RULES_CSV_MAX_BYTES": 5242880,
+    "RULES_CSV_MAX_ROWS": 20000,
+    "FORM_TICKET_SECONDS": 3600,
+    "EDIT_WINDOW_SECONDS": 900,
+    "EMAIL_CONFIRM_SECONDS": 86400,
+    "GUEST_GRANT_SECONDS": 2592000,
+    "CAPTCHA_SECONDS": 300,
+    "CAPTCHA_ATTEMPTS": 5,
+    "AUTHOR_MIN_INTERVAL": 30,
+    "AUTHOR_LIMIT_PER_HOUR": 20,
+    "IP_LIMIT_PER_HOUR": 100,
+    "RESEND_MIN_INTERVAL": 60,
+    "RESEND_LIMIT_PER_HOUR": 5,
+    "RESEND_IP_LIMIT_PER_HOUR": 20,
+    "CAPTCHA_IP_LIMIT_PER_MINUTE": 10,
+    "CAPTCHA_IP_LIMIT_PER_HOUR": 100,
+    "TRUSTED_PROXIES": [],
+    "GUEST_REQUEST_CHECKS": ["missing_user_agent", "cross_site"],
+    "MAIL_RETENTION_SECONDS": 604800,
+    "MAIL_LEASE_SECONDS": 300,
+    "MAIL_RETRY_SECONDS": [60, 300, 900],
+    "ACTION_LINK_SECONDS": 2592000,
+    "CAN_SEND_GUEST_EMAIL": None,
+    "GET_COMMENT_TEMPLATES": None,
+    "GET_AVATAR": None,
+    "CAPTCHA_BACKEND": None,
+    "GET_AUTHOR_NAME": None,
+}
+
+
+def configuration_errors() -> list[str]:
+    config = getattr(settings, "COMMENTAIL", {})
+    if not isinstance(config, dict):
+        return ["COMMENTAIL must be a dictionary"]
+    errors: list[str] = []
+    for hostname, values in config.items():
+        if (
+            not isinstance(hostname, str)
+            or not hostname
+            or not isinstance(values, dict)
+        ):
+            errors.append(
+                "COMMENTAIL sections must have string names and dictionary values"
+            )
+            continue
+        for key, value in values.items():
+            if key not in DEFAULTS:
+                errors.append(f"Unknown COMMENTAIL key: {key}")
+            elif key == "STRUCTURED_DATA":
+                if not isinstance(value, str) or value not in (
+                    "both", "json_ld", "microdata", "off"
+                ):
+                    errors.append("STRUCTURED_DATA must be both, json_ld, microdata or off")
+            elif key == "OBJECT_ADAPTERS":
+                from .objects import registry_errors
+
+                if hostname != "default":
+                    errors.append(
+                        "OBJECT_ADAPTERS is project-wide; configure it in default"
+                    )
+                errors.extend(registry_errors(value))
+            elif key.startswith("RULES_CSV_") and hostname != "default":
+                errors.append(f"{key} is project-wide; configure it in default")
+            elif key == "CAPTCHA_BACKEND":
+                if value is not None:
+                    from django.utils.module_loading import import_string
+
+                    try:
+                        backend = (
+                            import_string(value) if isinstance(value, str) else None
+                        )
+                        if (
+                            not isinstance(backend, type)
+                            or len(value) > 255
+                            or not all(
+                                callable(getattr(backend, method, None))
+                                for method in ("create", "verify")
+                            )
+                        ):
+                            errors.append(
+                                "CAPTCHA_BACKEND must be an import path to a class with create and verify methods"
+                            )
+                    except (ImportError, AttributeError):
+                        errors.append("CAPTCHA_BACKEND cannot be imported")
+            elif key in {
+                "CAN_SEND_GUEST_EMAIL",
+                "GET_COMMENT_TEMPLATES",
+                "GET_AVATAR",
+                "GET_AUTHOR_NAME",
+            }:
+                if value is not None:
+                    from django.utils.module_loading import import_string
+
+                    try:
+                        if not isinstance(value, str) or not callable(
+                            import_string(value)
+                        ):
+                            errors.append(f"{key} must be an import path to a callable")
+                    except (ImportError, AttributeError):
+                        errors.append(f"{key} cannot be imported")
+            elif key == "GUEST_REQUEST_CHECKS":
+                if (
+                    not isinstance(value, list)
+                    or not all(
+                        isinstance(item, str)
+                        and item in {"missing_user_agent", "cross_site"}
+                        for item in value
+                    )
+                    or len(value) != len(set(value))
+                ):
+                    errors.append(
+                        "GUEST_REQUEST_CHECKS must contain unique known signal names: missing_user_agent, cross_site"
+                    )
+            elif key == "MAIL_RETRY_SECONDS":
+                if not isinstance(value, list) or not all(
+                    type(item) is int and item > 0 for item in value
+                ):
+                    errors.append(
+                        "MAIL_RETRY_SECONDS must contain positive integer delays"
+                    )
+            elif key == "TRUSTED_PROXIES":
+                if not isinstance(value, list) or not all(
+                    isinstance(item, str) for item in value
+                ):
+                    errors.append("TRUSTED_PROXIES must be a list of network strings")
+                else:
+                    for item in value:
+                        try:
+                            ipaddress.ip_network(item)
+                        except ValueError:
+                            errors.append("Invalid TRUSTED_PROXIES network")
+            elif type(value) is not int or value <= 0:
+                errors.append(f"{key} must be a positive integer")
+    return errors
+
+
+def technical_settings(site: Site | None) -> TechnicalSettings:
+    errors = configuration_errors()
+    if errors:
+        raise ImproperlyConfigured("; ".join(errors))
+    config = getattr(settings, "COMMENTAIL", {})
+    return {
+        **DEFAULTS,
+        **config.get("default", {}),
+        **(config.get(site.hostname, {}) if site else {}),
+    }

commentail/detection.py

@@ -0,0 +1,89 @@
+from django.core.exceptions import ImproperlyConfigured
+from django.http import HttpRequest
+from django.template import Context, NodeList, TemplateDoesNotExist, TemplateSyntaxError
+from django.template.loader import get_template
+from django.template.loader_tags import ExtendsNode, IncludeNode
+from django.utils.module_loading import import_string
+from wagtail.models import Page, Site
+
+from .config import configuration_errors, technical_settings
+from .templatetags.commentail_tags import CommentailNode
+
+
+class DetectionError(ValueError):
+    """The library cannot establish the effective template chain."""
+
+
+def effective_settings(site: Site | None) -> dict[str, object]:
+    if errors := configuration_errors():
+        raise ImproperlyConfigured("; ".join(errors))
+    if site:
+        return dict(technical_settings(site))
+    from django.conf import settings
+
+    return dict(getattr(settings, "COMMENTAIL", {}).get("default", {}))
+
+
+def has_comments(page: Page, request: HttpRequest) -> bool:
+    """Inspect compiled nodes without rendering user templates or evaluating conditions.
+
+    A configured resolver must enumerate unresolved dynamic dependencies. Template
+    nodes are version-sensitive internals covered by integration tests.
+    """
+    config = effective_settings(Site.find_for_request(request))
+    resolver_path = config.get("GET_COMMENT_TEMPLATES")
+    resolver = import_string(str(resolver_path)) if resolver_path else None
+    try:
+        names = resolver(page, request) if resolver else [page.get_template(request)]
+    except Exception as exc:
+        # Do not expose handler exception payloads in editorial messages.
+        raise DetectionError("Comment template handler failed") from exc
+    if not isinstance(names, (list, tuple)) or not all(
+        isinstance(n, str) for n in names
+    ):
+        raise DetectionError("GET_COMMENT_TEMPLATES must return template names")
+    seen: set[str] = set()
+
+    def load(name: str) -> bool:
+        if name in seen:
+            return False
+        seen.add(name)
+        compiled = get_template(name).template
+        return scan(compiled.nodelist)
+
+    def dependency(expression: object) -> bool:
+        if getattr(expression, "is_var", True):
+            if resolver:
+                return False  # Resolver enumerates this dependency in names.
+            raise DetectionError(
+                "Dynamic template dependency requires GET_COMMENT_TEMPLATES"
+            )
+        value = expression.resolve(Context())
+        candidates = [value] if isinstance(value, str) else list(value)
+        for name in candidates:
+            try:
+                return load(name)
+            except TemplateDoesNotExist:
+                continue
+        raise DetectionError("Included template not found")
+
+    def scan(nodes: NodeList) -> bool:
+        for node in nodes:
+            if isinstance(node, CommentailNode):
+                return True
+            if isinstance(node, ExtendsNode) and dependency(node.parent_name):
+                return True
+            if isinstance(node, IncludeNode) and dependency(node.template):
+                return True
+            # Presence controls configuration, even in overridden blocks or
+            # false conditions. Rendering is deliberately not simulated.
+            for attr in getattr(node, "child_nodelists", ()):
+                children = getattr(node, attr, None)
+                if isinstance(children, NodeList) and scan(children):
+                    return True
+        return False
+
+    try:
+        return any(load(name) for name in names)
+    except (TemplateDoesNotExist, TemplateSyntaxError) as exc:
+        raise DetectionError(str(exc)) from exc