# 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:**

   ```bash
   pip install django-altcha
   ```

2. **Add to `INSTALLED_APPS`:**

   Update your Django project's `settings.py`:

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

## 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:

```python
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](https://altcha.org/docs/website-integration/).

### Example with additional options:

```python
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:

```python
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:

```python
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)``

## 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](./LICENSE) file for details.
