Metadata-Version: 2.4
Name: redeyed-sentinel-django
Version: 1.0.0
Summary: Redeyed Sentinel CAPTCHA integration for Django forms — free, privacy-respecting human verification.
Author-email: Redeyed Corporation <dev@redeyed.com>
License: MIT
Project-URL: Homepage, https://redeyed.com
Project-URL: Documentation, https://redeyed.com/developers
Project-URL: Source, https://github.com/bruted/sentinel-django
Keywords: django,captcha,sentinel,redeyed,spam,bot,verification
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
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: 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

# Redeyed Sentinel CAPTCHA for Django

Add friendly, privacy-respecting human verification to your Django forms with
[Redeyed Sentinel](https://redeyed.com). A drop-in form field renders the
Sentinel widget and verifies the result server-side.

**Free to install.** The integration stays inert until you add your keys —
no keys means the widget renders nothing and the field fails open, so your
forms keep working while you get set up.

## Install

```bash
pip install redeyed-sentinel-django
```

Add the app to `INSTALLED_APPS`:

```python
# settings.py
INSTALLED_APPS = [
    # ...
    "redeyed_captcha",
]
```

## Configure

Grab a **Site Key** and **API Key** from the Redeyed Lab:
**Developer → Sentinel → Sites + API Keys**. Then add them to your settings:

```python
# settings.py
REDEYED_SENTINEL = {
    "SITE_KEY": "pk_your_public_site_key",   # public, renders the widget
    "API_KEY":  "sk_your_secret_api_key",    # secret, server-side only
    "BASE_URL": "https://redeyed.com",       # optional, this is the default
}
```

Keep `API_KEY` secret — load it from an environment variable in production:

```python
import os

REDEYED_SENTINEL = {
    "SITE_KEY": os.environ["REDEYED_SENTINEL_SITE_KEY"],
    "API_KEY":  os.environ["REDEYED_SENTINEL_API_KEY"],
}
```

> Until both `SITE_KEY` and `API_KEY` are set the field is **inert**: nothing
> renders and verification passes automatically (fail open). Forms are never
> blocked by missing configuration.

## Use it in a form

```python
from django import forms
from redeyed_captcha import SentinelField


class ContactForm(forms.Form):
    name = forms.CharField()
    email = forms.EmailField()
    message = forms.CharField(widget=forms.Textarea)
    captcha = SentinelField()
```

Render the form normally in your template:

```html
<form method="post">
  {% csrf_token %}
  {{ form.as_p }}
  <button type="submit">Send</button>
</form>
```

The field renders the Sentinel loader script and a
`<div class="sentinel-captcha" data-sitekey="...">` mount point. The widget
script injects a hidden `sentinel-token` input, and on submit the field POSTs
that token to `{BASE_URL}/api/v1/verify` with your secret key in the
`X-Api-Key` header. If verification fails the form raises:

> Human verification failed — please try again.

## How verification works

| Step   | Detail |
|--------|--------|
| Render | Loads `{BASE_URL}/sentinel.js` once and a `sentinel-captcha` div using your `SITE_KEY`. |
| Submit | Reads the hidden `sentinel-token` injected by the widget. |
| Verify | `POST {BASE_URL}/api/v1/verify` with header `X-Api-Key: {API_KEY}` and body `{"site_key": "...", "token": "..."}`. |
| Pass   | Only when the JSON response has `data.success === true` or top-level `success === true`. |

## Requirements

- Python 3.9+
- Django 4.2+

No third-party HTTP dependency — verification uses the Python standard library
(`urllib`).

## License

MIT © 2026 Redeyed Corporation
