Add documentation about "Replay Attack Protection"

README.md

@@ -46,7 +46,6 @@ requiring additional configuration.
 > 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
@@ -124,12 +123,77 @@ class MyForm(forms.Form):
 > 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]
+> The default in-memory cache is **not shared across workers**. If you run multiple
+> workers (e.g., with gunicorn or uwsgi), you must configure a shared cache backend
+> using the `ALTCHA_CACHE_ALIAS` setting. 
+
 ## Settings
 
 ### ALTCHA_HMAC_KEY
 
 **Required.** This key is used to HMAC-sign ALTCHA challenges and **must be kept secret**.
 
+### ALTCHA_CACHE_ALIAS
+
+Cache alias used for replay attack protection.
+
+By default, challenges are stored in a local in-memory cache to prevent reuse.
+This works well for single-process deployments, but **does not protect against
+replay attacks in multi-worker setups** (e.g., gunicorn or uwsgi with multiple workers).
+
+For production deployments with multiple workers, configure a shared cache backend:
+
+**Using Redis or Memcached:**
+
+```python
+CACHES = {
+    'default': {
+        'BACKEND': 'django.core.cache.backends.redis.RedisCache',
+        'LOCATION': 'redis://127.0.0.1:6379',
+    }
+}
+ALTCHA_CACHE_ALIAS = 'default'
+```
+
+**Using Database Caching:**
+
+If you prefer not to set up Redis or Memcached, 
+[Django's built-in database cache](https://docs.djangoproject.com/en/dev/topics/cache/#database-caching)
+is a simple alternative:
+
+```python
+CACHES = {
+    'altcha': {
+        'BACKEND': 'django.core.cache.backends.db.DatabaseCache',
+        'LOCATION': 'altcha_cache',
+    }
+}
+ALTCHA_CACHE_ALIAS = 'altcha'
+```
+
+Then create the cache table:
+
+```bash
+python manage.py createcachetable
+```
+
+### ALTCHA_CHALLENGE_EXPIRE
+
+Challenge expiration duration in milliseconds.
+Defaults to 20 minutes as per 
+[Altcha security recommendations](https://altcha.org/docs/v2/security-recommendations/).
+
 ### ALTCHA_JS_URL
 
 URL of the Altcha JavaScript file.
@@ -150,12 +214,7 @@ Only loaded when `ALTCHA_INCLUDE_TRANSLATIONS` is `True`.
 ### ALTCHA_VERIFICATION_ENABLED
 
 Set to `False` to skip Altcha validation altogether.
-
-### ALTCHA_CHALLENGE_EXPIRE
-
-Challenge expiration duration in milliseconds.
-Default to 20 minutes as per Altcha security recommendations.
-See https://altcha.org/docs/v2/security-recommendations/
+Defaults to `True`.
 
 ## Contributing
 
@@ -165,4 +224,5 @@ Feel free to submit issues or pull requests!
 ## License
 
 This project is licensed under the **MIT License**.
-See the [LICENSE](./LICENSE) file for details.
+See the [LICENSE](https://github.com/aboutcode-org/django-altcha/blob/main/LICENSE) 
+file for details.

docs/source/conf.py

@@ -34,6 +34,7 @@
     "sphinx_rtd_dark_mode",
     "sphinx.ext.extlinks",
     "sphinx_copybutton",
+    "myst_parser",
 ]
 
 
@@ -75,7 +76,7 @@
 
 html_context = {
     "display_github": True,
-    "github_user": "nexB",
+    "github_user": "aboutcode-org",
     "github_repo": "django-altcha",
     "github_version": "develop",  # branch
     "conf_py_path": "/docs/source/",  # path in the checkout to the docs root

docs/source/index.rst → docs/source/index.md

@@ -1,5 +1,4 @@
-Welcome to django-altcha's documentation!
-=========================================
+# Welcome to django-altcha's documentation!
 
 Django Altcha is a Django library that provides easy integration of Altcha CAPTCHA
 into your Django forms, enhancing user verification with configurable options.
@@ -8,15 +7,11 @@ 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.
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+```{include} ../../README.md
+```
 
-   installation
+## Indices and tables
 
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+- {ref}`genindex`
+- {ref}`modindex`
+- {ref}`search`

pyproject.toml

@@ -48,6 +48,7 @@ docs = [
     "sphinx-autobuild",
     "sphinx-rtd-dark-mode>=1.3.0",
     "sphinx-copybutton",
+    "myst-parser",
 ]
 
 [project.urls]