feat: add brute force protection for SMS verification codes

Add comprehensive brute force protection to prevent automated attacks on SMS verification codes:

- Add failed_attempts field to SMSVerification model with database migration
- Implement MAX_FAILED_ATTEMPTS setting (default: 5) for session lockout
- Implement MIN_TOKEN_LENGTH setting (default: 6) to enforce minimum security code length
- Track failed attempts for invalid, expired, and already-verified codes
- Reset failed_attempts to 0 on successful verification
- Update validation logic to check brute force limit before other validations
- Add SECURITY_CODE_TOO_MANY_ATTEMPTS status code and error handling
- Update sandbox backends to support brute force protection while maintaining test-friendly behavior
- Add comprehensive test coverage for brute force protection scenarios
- Update documentation with new security settings

Closes #100

Co-authored-by: Harsh <[email protected]>

Author: CuriousLearner

CHANGELOG.rst

@@ -6,6 +6,7 @@ Release Notes
 
 Added
 """""
+- **Brute Force Protection**: Added comprehensive brute force protection for SMS verification codes to prevent automated attacks. New settings: ``MAX_FAILED_ATTEMPTS`` (default: 5) for session lockout threshold and ``MIN_TOKEN_LENGTH`` (default: 6) to enforce minimum security code length. Added ``failed_attempts`` field to ``SMSVerification`` model with migration for backward compatibility. Contributed by `Harsh <https://github.com/Kaos599>`_. Closes `#100 <https://github.com/CuriousLearner/django-phone-verify/issues/100>`_.
 - **Internationalization (i18n)**: Added support for localizing verification messages based on the ``Accept-Language`` HTTP header. The library now automatically detects the user's preferred language and sends verification messages in that language using Django's translation system. Contributed by `Hari Mahadevan <https://github.com/harikvpy>`_.
 - **Documentation**: Completely overhauled documentation to professional, enterprise-grade quality:
 

docs/getting_started.rst

@@ -108,6 +108,8 @@ Add the ``PHONE_VERIFICATION`` configuration to your ``settings.py``.
             'FROM': os.environ.get('TWILIO_PHONE_NUMBER'),    # Your Twilio phone number (e.g., '+1234567890')
         },
         'TOKEN_LENGTH': 6,                                     # Length of security code
+        'MIN_TOKEN_LENGTH': 6,                                 # Minimum allowed token length for security
+        'MAX_FAILED_ATTEMPTS': 5,                             # Maximum failed verification attempts before locking session
         'MESSAGE': 'Welcome to {app}! Please use security code {security_code} to proceed.',
         'APP_NAME': 'MyApp',                                   # Your app name (used in MESSAGE)
         'SECURITY_CODE_EXPIRATION_TIME': 600,                 # 10 minutes (in seconds)
@@ -129,6 +131,8 @@ Add the ``PHONE_VERIFICATION`` configuration to your ``settings.py``.
             'FROM': 'MyApp',                                   # Sender ID (alphanumeric or phone number)
         },
         'TOKEN_LENGTH': 6,
+        'MIN_TOKEN_LENGTH': 6,                                 # Minimum allowed token length for security
+        'MAX_FAILED_ATTEMPTS': 5,                             # Maximum failed verification attempts before locking session
         'MESSAGE': 'Welcome to {app}! Please use security code {security_code} to proceed.',
         'APP_NAME': 'MyApp',
         'SECURITY_CODE_EXPIRATION_TIME': 600,
@@ -171,6 +175,8 @@ Here's what each setting does:
   - Nexmo: ``KEY``, ``SECRET``, ``FROM``
 
 - **TOKEN_LENGTH**: Number of digits in the security code (recommended: 6)
+- **MIN_TOKEN_LENGTH**: Minimum allowed token length for security (default: 6). Prevents setting TOKEN_LENGTH to insecure low values
+- **MAX_FAILED_ATTEMPTS**: Maximum failed verification attempts before session lockout (default: 5). Protects against brute force attacks
 - **MESSAGE**: SMS message template. Variables: ``{app}`` and ``{security_code}``
 - **APP_NAME**: Your application name (used in MESSAGE template)
 - **SECURITY_CODE_EXPIRATION_TIME**: How long codes are valid (in seconds). Recommended: 300-600 (5-10 minutes)

phone_verify/admin.py

@@ -9,14 +9,15 @@
 
 @admin.register(SMSVerification)
 class SMSVerificationAdmin(admin.ModelAdmin):
-    list_display = ("id", "security_code", "phone_number", "is_verified", "created_at")
+    list_display = ("id", "security_code", "phone_number", "is_verified", "failed_attempts", "created_at")
     search_fields = ("phone_number",)
     ordering = ("phone_number",)
     readonly_fields = (
         "security_code",
         "phone_number",
         "session_token",
         "is_verified",
+        "failed_attempts",
         "created_at",
         "modified_at",
     )

phone_verify/backends/base.py

@@ -6,12 +6,15 @@
 # Third Party Stuff
 import jwt
 from django.conf import settings as django_settings
+from django.db import models
 from django.utils import timezone
 from django.utils.crypto import get_random_string
 
 from ..models import SMSVerification
 
 DEFAULT_TOKEN_LENGTH = 6
+DEFAULT_MIN_TOKEN_LENGTH = 6
+DEFAULT_MAX_FAILED_ATTEMPTS = 5
 
 
 class BaseBackend(metaclass=ABCMeta):
@@ -20,6 +23,7 @@ class BaseBackend(metaclass=ABCMeta):
     SECURITY_CODE_EXPIRED = 2
     SECURITY_CODE_VERIFIED = 3
     SESSION_TOKEN_INVALID = 4
+    SECURITY_CODE_TOO_MANY_ATTEMPTS = 5
 
     def __init__(self, **settings):
         self.exception_class = None
@@ -102,6 +106,34 @@ def create_security_code_and_session_token(self, number):
         )
         return security_code, session_token
 
+    def _should_bypass_code_check(self, security_code):
+        """
+        Hook for sandbox backends to bypass security code validation.
+        Returns True if the code check should be bypassed.
+
+        :param security_code: The security code to check
+        :return: Boolean indicating whether to bypass code validation
+        """
+        return False
+
+    def _increment_failed_attempts(self, verification):
+        """Atomically increment failed attempts counter."""
+        verification.failed_attempts = models.F('failed_attempts') + 1
+        verification.save(update_fields=['failed_attempts'])
+        verification.refresh_from_db()
+
+    def _reset_failed_attempts(self, verification):
+        """Reset failed attempts counter to 0."""
+        verification.failed_attempts = 0
+        verification.save(update_fields=['failed_attempts'])
+
+    def _check_brute_force_limit(self, verification):
+        """Check if verification has exceeded failed attempts limit."""
+        max_failed_attempts = django_settings.PHONE_VERIFICATION.get(
+            "MAX_FAILED_ATTEMPTS", DEFAULT_MAX_FAILED_ATTEMPTS
+        )
+        return verification.failed_attempts >= max_failed_attempts
+
     def validate_security_code(self, security_code, phone_number, session_token):
         """
         A utility method to verify if the `security_code` entered is valid for
@@ -120,32 +152,53 @@ def validate_security_code(self, security_code, phone_number, session_token):
             - `BaseBackend.SECURITY_CODE_EXPIRED`
             - `BaseBackend.SECURITY_CODE_VERIFIED`
             - `BaseBackend.SESSION_TOKEN_INVALID`
+            - `BaseBackend.SECURITY_CODE_TOO_MANY_ATTEMPTS`
         """
         stored_verification = SMSVerification.objects.filter(
-            security_code=security_code, phone_number=phone_number
+            phone_number=phone_number, session_token=session_token
         ).first()
 
-        # check security_code exists
-        if stored_verification is None:
-            return stored_verification, self.SECURITY_CODE_INVALID
+        # Allow sandbox backends to bypass validation (but check brute force first if verification exists)
+        if self._should_bypass_code_check(security_code):
+            if stored_verification is None:
+                return SMSVerification.objects.none(), self.SECURITY_CODE_VALID
+
+            # Even for sandbox, check brute force limit first
+            if self._check_brute_force_limit(stored_verification):
+                return stored_verification, self.SECURITY_CODE_TOO_MANY_ATTEMPTS
 
-        # check session code exists
-        if not stored_verification.session_token == session_token:
+            self._reset_failed_attempts(stored_verification)
+            return SMSVerification.objects.none(), self.SECURITY_CODE_VALID
+
+        # check verification exists
+        if stored_verification is None:
             return stored_verification, self.SESSION_TOKEN_INVALID
 
+        # check if too many failed attempts
+        if self._check_brute_force_limit(stored_verification):
+            return stored_verification, self.SECURITY_CODE_TOO_MANY_ATTEMPTS
+
+        # check security_code matches
+        if stored_verification.security_code != security_code:
+            self._increment_failed_attempts(stored_verification)
+            return stored_verification, self.SECURITY_CODE_INVALID
+
         # check security_code is not expired
         if self.check_security_code_expiry(stored_verification):
+            self._increment_failed_attempts(stored_verification)
             return stored_verification, self.SECURITY_CODE_EXPIRED
 
         # check security_code is not verified
         if stored_verification.is_verified and django_settings.PHONE_VERIFICATION.get(
             "VERIFY_SECURITY_CODE_ONLY_ONCE"
         ):
+            self._increment_failed_attempts(stored_verification)
             return stored_verification, self.SECURITY_CODE_VERIFIED
 
         # mark security_code as verified
         stored_verification.is_verified = True
-        stored_verification.save()
+        stored_verification.failed_attempts = 0
+        stored_verification.save(update_fields=['is_verified', 'failed_attempts'])
 
         return stored_verification, self.SECURITY_CODE_VALID
 

phone_verify/backends/nexmo.py

@@ -5,8 +5,6 @@
 import nexmo
 from nexmo.errors import ClientError
 
-from phone_verify.models import SMSVerification
-
 # Local
 from .base import BaseBackend
 
@@ -58,5 +56,9 @@ def generate_security_code(self):
         """
         return self._token
 
-    def validate_security_code(self, security_code, phone_number, session_token):
-        return SMSVerification.objects.none(), self.SECURITY_CODE_VALID
+    def _should_bypass_code_check(self, security_code):
+        """
+        Sandbox mode: bypass code validation if the security code matches the sandbox token.
+        This allows testing without real SMS while still enforcing brute force protection.
+        """
+        return security_code == self._token

phone_verify/backends/twilio.py

@@ -5,8 +5,6 @@
 from twilio.base.exceptions import TwilioRestException
 from twilio.rest import Client as TwilioRestClient
 
-from phone_verify.models import SMSVerification
-
 # Local
 from .base import BaseBackend
 
@@ -57,5 +55,9 @@ def generate_security_code(self):
         """
         return self._token
 
-    def validate_security_code(self, security_code, phone_number, session_token):
-        return SMSVerification.objects.none(), self.SECURITY_CODE_VALID
+    def _should_bypass_code_check(self, security_code):
+        """
+        Sandbox mode: bypass code validation if the security code matches the sandbox token.
+        This allows testing without real SMS while still enforcing brute force protection.
+        """
+        return security_code == self._token

phone_verify/migrations/0003_smsverification_failed_attempts.py

@@ -0,0 +1,18 @@
+# Generated by Django 5.0.1 on 2025-10-12 20:19
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('phone_verify', '0002_auto_20190817_1753'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='smsverification',
+            name='failed_attempts',
+            field=models.PositiveIntegerField(default=0, verbose_name='Failed Attempts'),
+        ),
+    ]

phone_verify/models.py

@@ -39,6 +39,7 @@ class SMSVerification(TimeStampedUUIDModel):
     phone_number = PhoneNumberField(_("Phone Number"))
     session_token = models.CharField(_("Device Session Token"), max_length=500)
     is_verified = models.BooleanField(_("Security Code Verified"), default=False)
+    failed_attempts = models.PositiveIntegerField(_("Failed Attempts"), default=0)
 
     class Meta:
         db_table = "sms_verification"

phone_verify/serializers.py

@@ -44,9 +44,13 @@ def validate(self, attrs):
             raise serializers.ValidationError(_("Security code is not valid"))
         elif token_validatation == backend.SESSION_TOKEN_INVALID:
             raise serializers.ValidationError(_("Session Token mis-match"))
+        elif token_validatation == backend.SECURITY_CODE_INVALID:
+            raise serializers.ValidationError(_("Security code is not valid"))
         elif token_validatation == backend.SECURITY_CODE_EXPIRED:
             raise serializers.ValidationError(_("Security code has expired"))
         elif token_validatation == backend.SECURITY_CODE_VERIFIED:
             raise serializers.ValidationError(_("Security code is already verified"))
+        elif token_validatation == backend.SECURITY_CODE_TOO_MANY_ATTEMPTS:
+            raise serializers.ValidationError(_("Too many failed verification attempts. Please request a new code."))
 
         return attrs

phone_verify/services.py

@@ -10,6 +10,7 @@
 
 # phone_verify stuff
 from .backends import get_sms_backend
+from .backends.base import DEFAULT_MIN_TOKEN_LENGTH, DEFAULT_TOKEN_LENGTH
 
 logger = logging.getLogger(__name__)
 
@@ -88,6 +89,14 @@ def _check_required_settings(self):
                 )
             )
 
+        # Validate minimum token length
+        token_length = settings.PHONE_VERIFICATION.get("TOKEN_LENGTH", DEFAULT_TOKEN_LENGTH)
+        min_token_length = settings.PHONE_VERIFICATION.get("MIN_TOKEN_LENGTH", DEFAULT_MIN_TOKEN_LENGTH)
+        if token_length < min_token_length:
+            raise ImproperlyConfigured(
+                f"TOKEN_LENGTH ({token_length}) cannot be less than MIN_TOKEN_LENGTH ({min_token_length})"
+            )
+
 
 def send_security_code_and_generate_session_token(phone_number, language=None):
     sms_backend = get_sms_backend(phone_number)