django-altcha 1.0.0

Django field and widget for Altcha CAPTCHA.

Django Altcha

Django Altcha is a Django library that provides easy integration of Altcha CAPTCHA into your Django forms, enhancing user verification with configurable options.

By default, CAPTCHA validation operates in a fully self-hosted mode, eliminating the need for external services while ensuring privacy and control over the verification process.

Django Altcha is secure by default, featuring built-in protection against replay attacks to ensure each challenge is validated only once. This helps safeguard your forms from repeated or spoofed submissions without requiring additional configuration.

Installation

1. Install the package:

   pip install django-altcha
   

2. Add to INSTALLED_APPS:

   Update your Django project's settings.py:

   INSTALLED_APPS = [
       # Other installed apps
       "django_altcha",
   ]
   

3. Set your secret HMAC key:

   This key is used to HMAC-sign ALTCHA challenges and must be kept secret. Treat it like a password: use a secure, 64-character hex string.

   Update your Django project's settings.py:

   ALTCHA_HMAC_KEY="your_secret_hmac_key"
   

[!NOTE] You can generate a new secured HMAC key using: python -c "import secrets; print(secrets.token_hex(64))"

Usage

Adding the CAPTCHA Field to Your Form

To add the Altcha CAPTCHA field to a Django form, import AltchaField and add it to your form definition:

from django import forms
from django_altcha import AltchaField

class MyForm(forms.Form):
    captcha = AltchaField()

Configuration Options

You can pass configuration options to AltchaField that are supported by Altcha. These options are documented at Altcha's website integration guide.

Example with additional options:

from django import forms
from django_altcha import AltchaField

class MyForm(forms.Form):
    captcha = AltchaField(
        floating=True,   # Enables floating behavior
        debug=True,      # Enables debug mode (for development)
        # Additional options supported by Altcha
    )

Register a URL to Provide the Challenge

By default, challenge data is generated by the AltchaField and embedded directly into the rendered HTML using the challengejson option.

Alternatively, you can provide a URL that the Altcha widget’s JavaScript will fetch to retrieve the challenge, using the challengeurl option.

This approach is especially useful for enabling features like refetchonexpire, which only work when using a challengeurl (not challengejson).

A ready-to-use AltchaChallengeView is available in django_altcha. To enable it, register the view in your urlpatterns, for example:

from django.urls import path
from django_altcha import AltchaChallengeView

urlpatterns += [
    path("altcha/challenge/", AltchaChallengeView.as_view(), name="altcha_challenge"),
]

Once the URL is registered, you can configure your AltchaField to use it via the challengeurl option:

from django.urls import reverse_lazy
from django import forms
from django_altcha import AltchaField

class MyForm(forms.Form):
    captcha = AltchaField(
        challengeurl=reverse_lazy("altcha_challenge"),
    )

[!NOTE] You can customize the challenge generation by passing options directly when registering the view. For example: AltchaChallengeView.as_view(max_number=2000000)

Replay Attack Protection

Django Altcha automatically protects against replay attacks by ensuring each challenge can only be used once. When a challenge is successfully validated, it is stored in a cache and any subsequent attempt to reuse the same challenge will be rejected.

This protection is enabled by default and requires no additional configuration for single-process deployments.

[!IMPORTANT] By default, replay protection uses Django's default cache backend, which is LocMemCache unless you configure it otherwise. This in-memory cache is not shared across workers. If you run multiple workers (e.g., with gunicorn or uwsgi), configure a shared cache backend such as Redis or Memcached.

Settings

ALTCHA_HMAC_KEY

Required. This key is used to HMAC-sign ALTCHA challenges and must be kept secret.

ALTCHA_CACHE_ALIAS

Django cache alias used for replay attack protection. Defaults to "default".

If your default cache is already a shared backend (Redis, Memcached, database), no extra configuration is needed.

If you want to use a dedicated cache for ALTCHA, define one and point to it:

Using Redis or Memcached:

CACHES = {
    'altcha': {
        'BACKEND': 'django.core.cache.backends.redis.RedisCache',
        'LOCATION': 'redis://127.0.0.1:6379',
    }
}
ALTCHA_CACHE_ALIAS = 'altcha'

Using Database Caching:

If you prefer not to set up Redis or Memcached, Django's built-in database cache is a simple alternative:

CACHES = {
    'altcha': {
        'BACKEND': 'django.core.cache.backends.db.DatabaseCache',
        'LOCATION': 'altcha_cache',
    }
}
ALTCHA_CACHE_ALIAS = 'altcha'

Then create the cache table:

python manage.py createcachetable

ALTCHA_CHALLENGE_EXPIRE

Challenge expiration duration in milliseconds. Defaults to 20 minutes as per Altcha security recommendations.

ALTCHA_JS_URL

URL of the Altcha JavaScript file. Defaults to the bundled django-altcha file.

ALTCHA_INCLUDE_TRANSLATIONS

Whether to include Altcha translations. Defaults to False.

ALTCHA_JS_TRANSLATIONS_URL

URL of the Altcha translations JavaScript file. Defaults to the bundled django-altcha file.

Only loaded when ALTCHA_INCLUDE_TRANSLATIONS is True.

ALTCHA_VERIFICATION_ENABLED

Set to False to skip Altcha validation altogether. Defaults to True.

Logging

Django Altcha uses the standard Python logging module under the logger name django_altcha. No logs are emitted under normal operation; logging fires only on validation failures and misconfiguration.

What gets logged

• WARNING on invalid or missing CAPTCHA tokens submitted to a form.
• WARNING on replay attempts (a challenge reused after it has already been validated).
• ERROR when ALTCHA_HMAC_KEY is not configured.
• Exception with traceback when verification or payload decoding raises unexpectedly.

Payloads, challenge values, and the HMAC key are never included in log messages.

Enabling logs

Add the django_altcha logger to your project's LOGGING setting:

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
        },
    },
    "loggers": {
        "django_altcha": {
            "handlers": ["console"],
            "level": "WARNING",
        },
    },
}

Set "level": "ERROR" to see only misconfiguration and unexpected failures, or "level": "DEBUG" to see additional diagnostic messages during development.

Contributing

We welcome contributions to improve this library. Feel free to submit issues or pull requests!

License

This project is licensed under the MIT License. See the LICENSE file for details.