Metadata-Version: 2.5
Name: altcha-django
Version: 1.0.0
Summary: Django integration for ALTCHA — Widget v3, Proof-of-Work v2, and Sentinel.
Project-URL: Homepage, https://github.com/altcha-org/altcha-django
Project-URL: Documentation, https://github.com/altcha-org/altcha-django#readme
Project-URL: Source, https://github.com/altcha-org/altcha-django
Project-URL: Issues, https://github.com/altcha-org/altcha-django/issues
Project-URL: Changelog, https://github.com/altcha-org/altcha-django/blob/main/CHANGELOG.md
Author: altcha-django contributors
License-Expression: MIT
License-File: LICENSE
Keywords: altcha,bot,captcha,django,proof-of-work,sentinel,spam
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Classifier: Framework :: Django :: 6.1
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: altcha<3.0.0,>=2.1.0
Requires-Dist: django>=4.2
Provides-Extra: argon2
Requires-Dist: argon2-cffi>=21.3; extra == 'argon2'
Provides-Extra: dev
Requires-Dist: argon2-cffi>=21.3; extra == 'dev'
Requires-Dist: django-stubs>=5; extra == 'dev'
Requires-Dist: django>=4.2; extra == 'dev'
Requires-Dist: djangorestframework>=3.14; extra == 'dev'
Requires-Dist: httpx>=0.24; extra == 'dev'
Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: nox>=2024.4.15; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest-django>=4.8; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Provides-Extra: drf
Requires-Dist: djangorestframework>=3.14; extra == 'drf'
Provides-Extra: sentinel
Requires-Dist: httpx>=0.24; extra == 'sentinel'
Description-Content-Type: text/markdown

# altcha-django

Django integration for [ALTCHA](https://altcha.org) — built around **Widget v3**,
**Proof-of-Work v2**, and **ALTCHA Sentinel**.

- A real Django form field (`Form`, `ModelForm`, formsets, `Widget.Media`, translated errors).
- Pluggable verification backend: **local** proof-of-work or **Sentinel** (local
  server-signature verification or the remote API).
- Atomic replay protection via Django's cache framework.
- Signals for every verification outcome; optional built-in stats.
- Test mode and `django check` system checks.
- Optional Django REST Framework field.

> Requires Python 3.10+ and Django 4.2+.

## Install

```console
pip install altcha-django
# extras: [sentinel] (httpx), [argon2] (argon2-cffi), [drf] (djangorestframework)
```

## Quick start — local verification

```python
# settings.py
INSTALLED_APPS = [..., "altcha_django"]
ALTCHA_HMAC_SECRET = "a-long-random-string"   # keep secret

# urls.py
urlpatterns = [..., path("altcha/", include("altcha_django.urls"))]

# forms.py
from django import forms
from altcha_django import AltchaField, AltchaMixin

class ContactForm(AltchaMixin, forms.Form):
    email = forms.EmailField()
    captcha = AltchaField()
```

```python
# views.py
form = ContactForm(request.POST or None, request=request)
```

```django
{{ form.media }}
<form method="post">{% csrf_token %}{{ form.as_p }}<button>Send</button></form>
```

## Quick start — Sentinel

```python
ALTCHA_VERIFIER = "sentinel"
# Full challenge URL of your self-hosted Sentinel, API key in the query string:
ALTCHA_SENTINEL_CHALLENGE_URL = "https://sentinel.example.com/v1/challenge?apiKey=key_..."
ALTCHA_SENTINEL_API_SECRET = "sec_..."   # private — never leaves the server
```

Nothing else changes: the widget fetches its challenge from your Sentinel and the
field verifies the signed result locally. Read `score` / `classification` with
`AltchaField(return_result=True)`.

See [`docs/`](docs/) for the full settings reference, signals, system checks,
Sentinel guide, testing notes, and migration from `django-altcha`.

## License

MIT
