Metadata-Version: 2.4
Name: django-server-captcha
Version: 1.0.0
Summary: Fully server-side captcha for Django — math, image, and word challenges with zero external API calls.
Author-email: BHDASH <beh.ash125@gmail.com>
Project-URL: Homepage, https://github.com/yourname/django-server-captcha
Project-URL: Repository, https://github.com/yourname/django-server-captcha
Project-URL: Issues, https://github.com/yourname/django-server-captcha/issues
Keywords: django,captcha,security,server-side
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 6.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: django>=4.2
Dynamic: license-file

# django-server-captcha

Fully server-side captcha for Django — math, image, and word challenges with **zero external API calls**.

No third-party services, no API keys, no external requests. Everything runs on your own server.

## Features

- **Math Captcha** — arithmetic expression the user must solve
- **Image Captcha** — 3x3 SVG shape grid; select images matching a color+shape criteria
- **Word Captcha** — reversed word the user must type correctly
- **Refresh buttons** — each captcha can be regenerated independently via AJAX
- **Session-based** — answers stored in Django's session framework (no database required)
- **Fully server-side** — no Google/reCAPTCHA keys, no external HTTP calls

## Requirements

- Python 3.9+
- Django 4.2+

## Installation

```bash
pip install django-server-captcha
```

## Setup

1. Add `'captcha'` to your `INSTALLED_APPS`:

```python
# settings.py
INSTALLED_APPS = [
    ...
    'captcha',
]
```

2. Make sure `django.contrib.sessions` is in `INSTALLED_APPS` and `SessionMiddleware` is in `MIDDLEWARE` (both are enabled by default).

3. Run a migrate (for the sessions table if you haven't already):

```bash
python manage.py migrate
```

## Usage

### In a view

```python
from captcha.views import CaptchaFormView

urlpatterns = [
    path('verify/', CaptchaFormView.as_view(), name='captcha_form'),
]
```

### In your own view

```python
from captcha.forms import MathCaptchaForm, ImageCaptchaForm, WordCaptchaForm

def my_view(request):
    math_form = MathCaptchaForm(request.POST or None, session=request.session)
    image_form = ImageCaptchaForm(request.POST or None, session=request.session)
    word_form = WordCaptchaForm(request.POST or None, session=request.session)

    if request.method == 'POST':
        if math_form.is_valid() and image_form.is_valid() and word_form.is_valid():
            # All captchas passed
            ...
```

### In a template

```html
<form method="post">
    {% csrf_token %}

    {{ math_form.answer }}
    {{ math_form.answer.errors }}

    {{ image_form.selected }}
    {{ image_form.selected.errors }}

    {{ word_form.word }}
    {{ word_form.word.errors }}

    <button type="submit">Verify</button>
</form>
```

### Refresh endpoint

The package includes a JSON endpoint for refreshing captchas via AJAX:

```python
# urls.py
path('captcha/refresh/', 'captcha.views.captcha_refresh', name='captcha_refresh'),
```

```javascript
fetch("/captcha/refresh/", {
    method: "POST",
    headers: {"X-CSRFToken": csrfToken},
    body: new URLSearchParams({type: "math"})
})
.then(r => r.json())
.then(data => {
    document.getElementById("math-display").textContent = data.display;
});
```

Valid `type` values: `"math"`, `"image"`, `"word"`.

## License

MIT
