Django implementation of Cap.js Server for Proof of Work captcha
Project description
Django Cap
This is a implementation of Cap.js Server for Django, which provides challenge generation and verification for PoW (Proof of Work) captcha. See
Usage
Installation
To install the package, simply run:
pip install django_cap
If you want to use the Django Ninja integration, you can install it with:
pip install django_cap[ninja]
Or if you want to use the Django Rest Framework integration, you can install it with:
pip install django_cap[drf]
Note that currently, only ninja integration and vanilla Django Json views are implemented, DRF integration will be added shortly.
Configuration
To use this package, you need to add django_cap to your INSTALLED_APPS in your Django settings file:
INSTALLED_APPS = [
...
'django_cap',
'django_cap.ninja', # Add this if you want enable ninja integration
]
You need to configure the url patterns in your Django project's urls.py file:
urlpatterns = [
...
path("cap/", include("django_cap.urls")),
...
]
You can access the api at /cap/v1/[challenge|redeem|validate] endpoints. This is compatible with Cap.js/widgets. If your frontend is not hosted by Django, you need to refer Cap.js documentation for the installation, and simply configure the api endpoint as following:
<cap-widget id="cap" data-cap-api-endpoint="https://your-api-site/cap/v1/"></cap-widget>
By default, ninja doc will be avaliable at /cap/v1/docs/ and /cap/v1/openapi.json. If you want to disable the ninja doc, you can disable it in your Django settings file:
#django_settings.py
...
CAP_NINJA_API_ENABLE_DOCS = False
...
Use with Django Templates
This package also provides a custom template tag to render the captcha widget in your Django templates. You can use it as follows:
{% load django_cap %}
<head>
...
<!-- Load the CAP widget script using template tag -->
{% cap_widget_script %}
...
</head>
<body>
...
<!-- Render the CAP widget -->
{% cap_widget %}
...
</body>
TODO: token validation procedure for Django templates is not implemented yet, currently we only provide the widget rendering. Help welcome if you are familiar with Django templates.
Configuration Options
CAP_NINJA_API_ENABLE_DOCS: Enable or disable the ninja API docs. Default isTrue.CAP_CHALLENGE_COUNT: The number of answer required for one challenge. Default is 50.CAP_CHALLENGE_SIZE: The size of the challenge string. Default is 32.CAP_CHALLENGE_DIFFICULTY: The difficulty of the challenge, Default is 4CAP_CHALLENGE_EXPIRES_S: The expiration time of the challenge in seconds. Default is 30 seconds.CAP_TOKEN_EXPIRES_S: The expiration time of the token in seconds. Default is 10 minutes.CAP_CLEANUP_INTERVAL_S: The interval for cleaning up expired challenges and tokens in seconds. Default is 60 seconds.
Dev environment setup
-
Clone this repository.
-
Make sure you have python 3.13 installed.
python --version -
Make sure you have uv installed.
# for MacOS, recommend using homebrew brew install uv
# for Linux, recommend using their installer # curl curl -LsSf https://astral.sh/uv/install.sh | sh # wget wget -qO- https://astral.sh/uv/install.sh | sh
# for Windows, recommend using WinGet winget install --id=astral-sh.uv -e # you can also use scoop scoop install main/uv
-
Install the dependencies:
uv sync -
Activate the virtual environment:
# for linux/macOS source .venv/bin/activate
# for windows .\.venv\Scripts\Activate.ps1
-
Run tests:
uv run pytest
-
Run linting and formatting:
# Check code quality uv run ruff check # Format code uv run ruff format
-
Build the package:
uv run pdm build
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Links
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file django_cap-0.1.0.tar.gz.
File metadata
- Download URL: django_cap-0.1.0.tar.gz
- Upload date:
- Size: 20.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.12.9
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
fc2a4a9473ca6e0b7be5850c5f47e34476de014b79193b24d7714847561f980c
|
|
| MD5 |
9315ec50060b7f4dc516bfa8740120a9
|
|
| BLAKE2b-256 |
48855d4bdc5c6a84d20fe7692b9f4124f34b328aa72b6c8546c1d42833fb8fee
|
Provenance
The following attestation bundles were made for django_cap-0.1.0.tar.gz:
Publisher:
release.yml on Somiona/django_cap
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
django_cap-0.1.0.tar.gz -
Subject digest:
fc2a4a9473ca6e0b7be5850c5f47e34476de014b79193b24d7714847561f980c - Sigstore transparency entry: 272484822
- Sigstore integration time:
-
Permalink:
Somiona/django_cap@9a5fe1deee7163d5635731efccc414c90c3e39b6 -
Branch / Tag:
refs/tags/0.1.0 - Owner: https://github.com/Somiona
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@9a5fe1deee7163d5635731efccc414c90c3e39b6 -
Trigger Event:
push
-
Statement type:
File details
Details for the file django_cap-0.1.0-py3-none-any.whl.
File metadata
- Download URL: django_cap-0.1.0-py3-none-any.whl
- Upload date:
- Size: 23.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.12.9
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
2a2d842f8074f1512cd5ce655479d6eb97630b055b153b6c1adfa8cb1f01ad5a
|
|
| MD5 |
580436fff3e468bf40c1472afc380bf6
|
|
| BLAKE2b-256 |
1984025a5484adb85c993b483c27576e761536f5c1bd4d497428ff5dcc59cbd8
|
Provenance
The following attestation bundles were made for django_cap-0.1.0-py3-none-any.whl:
Publisher:
release.yml on Somiona/django_cap
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
django_cap-0.1.0-py3-none-any.whl -
Subject digest:
2a2d842f8074f1512cd5ce655479d6eb97630b055b153b6c1adfa8cb1f01ad5a - Sigstore transparency entry: 272484823
- Sigstore integration time:
-
Permalink:
Somiona/django_cap@9a5fe1deee7163d5635731efccc414c90c3e39b6 -
Branch / Tag:
refs/tags/0.1.0 - Owner: https://github.com/Somiona
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@9a5fe1deee7163d5635731efccc414c90c3e39b6 -
Trigger Event:
push
-
Statement type:
