coalition.endorsements.spam_prevention
======================================

.. py:module:: coalition.endorsements.spam_prevention

.. autoapi-nested-parse::

   Spam prevention utilities for endorsement forms



Attributes
----------

.. autoapisummary::

   coalition.endorsements.spam_prevention.akismet
   coalition.endorsements.spam_prevention.validate_email
   coalition.endorsements.spam_prevention.logger


Classes
-------

.. autoapisummary::

   coalition.endorsements.spam_prevention.SpamPreventionService


Functions
---------

.. autoapisummary::

   coalition.endorsements.spam_prevention.secure_ip_key
   coalition.endorsements.spam_prevention.get_client_ip


Module Contents
---------------

.. py:data:: akismet
   :value: None


.. py:data:: validate_email
   :value: None


.. py:data:: logger

.. py:function:: secure_ip_key(group: str, request: django.http.HttpRequest) -> str

   Custom rate limit key function that uses our secure IP extraction.

   This prevents IP spoofing attacks by using get_client_ip() which validates
   IP addresses and handles proxy headers safely.


.. py:function:: get_client_ip(request: django.http.HttpRequest) -> str

   Securely extract client IP address with validation and spoofing protection.

   Validates IP addresses and handles proxy headers safely to prevent
   rate limit bypass and log pollution attacks.


.. py:class:: SpamPreventionService

   Service for preventing spam in endorsement submissions


   .. py:attribute:: RATE_LIMIT_WINDOW


   .. py:attribute:: RATE_LIMIT_MAX_ATTEMPTS


   .. py:attribute:: SUSPICIOUS_DOMAINS
      :value: ['mailinator.com', '10minutemail.com', 'guerrillamail.com', 'temp-mail.org', 'throwaway.email']



   .. py:method:: check_rate_limit(request: django.http.HttpRequest) -> dict[str, Any]
      :classmethod:


      Check if request has exceeded rate limit using django-ratelimit
      Returns dict with 'allowed' boolean and 'remaining' count



   .. py:method:: record_submission_attempt(request: django.http.HttpRequest) -> None
      :classmethod:


      Record a submission attempt using django-ratelimit



   .. py:method:: validate_honeypot(form_data: dict[str, Any]) -> bool
      :classmethod:


      Validate honeypot fields
      Returns True if validation passes (human), False if spam detected



   .. py:method:: validate_timing(form_data: dict[str, Any]) -> bool
      :classmethod:


      Validate form submission timing
      Too fast = bot, too slow = potentially abandoned



   .. py:method:: check_email_reputation(email: str) -> dict[str, Any]
      :classmethod:


      Check email address reputation using email-validator
      Falls back to basic checks if email-validator is unavailable
      Returns dict with 'suspicious' boolean and 'reasons' list



   .. py:method:: check_content_quality(stakeholder_data: dict[str, Any], statement: str, ip_address: str = None, user_agent: str = None) -> dict[str, Any]
      :classmethod:


      Check content quality for spam indicators using Akismet
      Falls back to custom checks if Akismet is unavailable
      Returns dict with 'suspicious' boolean and 'reasons' list



   .. py:method:: comprehensive_spam_check(request: django.http.HttpRequest, stakeholder_data: dict[str, Any], statement: str, form_data: dict[str, Any], user_agent: str = None, skip_rate_limiting: bool = False) -> dict[str, Any]
      :classmethod:


      Run comprehensive spam check
      Returns dict with overall assessment and details