- Python 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| src | ||
| .gitignore | ||
| COPYING | ||
| COPYING.LESSER | ||
| MANIFEST.in | ||
| pyproject.toml | ||
| README.md | ||
splent_feature_captcha
The captcha feature of a SPLENT product line.
The captcha every form of the product shares. It decides which forms ask for an answer, draws the widget in them and checks the answer on submit, once, for whichever provider the product installs:
| Provider | What the visitor sees | Its settings |
|---|---|---|
splent_feature_captcha_image |
An image of a few characters, drawn by the product itself, with no keys and no third party, or a few digits read out for whoever cannot see it. It works offline | No keys. CAPTCHA_IMAGE_MAX_AGE, CAPTCHA_IMAGE_MAX_IMAGES, CAPTCHA_IMAGE_WINDOW_SECONDS and CAPTCHA_IMAGE_ALTERNATIVE tune it |
splent_feature_recaptcha |
Google reCAPTCHA v2 | RECAPTCHA_SITE_KEY, RECAPTCHA_SECRET_KEY, or the panel's /admin/captcha |
splent_feature_cloudflare |
Cloudflare Turnstile | TURNSTILE_SITE_KEY, TURNSTILE_SECRET_KEY, or the panel's /admin/captcha |
The keys recaptcha and cloudflare default to are the providers' test keys, which always pass, so development works with no setup and a live site sets its own pair.
A product installs captcha and one provider. The provider implements the
CaptchaService interface and registers it, and does nothing else: it
connects no signal, fills no slot and gives templates no helper. Before
this feature each provider did all of that on its own, three times over,
and the copies had already drifted apart (recaptcha and cloudflare never
checked the sign-up, and only captcha_image let a product choose the forms).
A SPLENT feature is a Python package that a product composes with others.
Its models, routes, services, templates and hooks are registered when the
product starts. What this feature provides and requires is listed in the
[tool.splent.contract] section of pyproject.toml, which
splent feature:contract --write keeps in sync with the source.
The forms it protects
CAPTCHA_PROTECTED_FORMS names the forms that ask for an answer, by the
name of their submitting signal. None of the features behind them is
required: a form whose feature is not installed never sends its signal,
and its check never runs.
| Form | Its name | Where the widget is drawn | The check |
|---|---|---|---|
Sign-up (signup) |
signup |
This feature fills the signup.form_fields slot |
signup-submitting |
Login (auth) |
login |
This feature fills the auth.login.form_fields slot |
login-submitting |
Reset link (reset) |
reset |
This feature fills the reset.form_fields slot |
reset-submitting |
Contact (contact) |
contact |
The form calls captcha_widget() |
contact-submitting |
Comments (comments) |
comment |
The form calls captcha_widget() |
comment-submitting |
Careers (careers) |
careers |
The form calls captcha_widget() |
careers-submitting |
The default is the sign-up alone, the form bots fill in most. A product without a sign-up names its forms. A cms whose provider checked the contact, comment and careers forms on its own, before this feature existed, keeps them protected with:
[tool.splent.config]
CAPTCHA_PROTECTED_FORMS = ["contact", "comment", "careers"]
[tool.splent.config]
# The sign-up and the request for a reset link ask for an answer.
CAPTCHA_PROTECTED_FORMS = ["signup", "reset"]
A check returns False unless the provider verifies the posted answer, and
the form then refuses the submission. A form left out returns None, which
lets the submission through without asking the provider anything, so an
answer the visitor drew for another form stays answerable. Its widget is
not drawn either.
Each form needs a version of its feature that sends the signal and opens the slot:
- signup 0.3.0 or later;
- reset, from the release after 1.5.0;
- the login, from an auth that sends
login-submittingand opensauth.login.form_fields, which no released auth does yet. Until then namingloginprotects nothing.
An older form draws no widget and goes through unchecked, since it never asks this feature anything. The log says so on the first request, once every feature has loaded:
| What the setting names | The log |
|---|---|
A form whose *-submitting nothing in the product sends, next to others it does |
A warning naming the form and its signal |
| Only such forms, the default in a product without a sign-up included | An error, "captcha protects no form", naming the forms the product has |
| A name the feature does not know | A warning when the product starts. The name is kept |
Blank means the default, since a captcha installed to protect nothing is more likely a typo than a wish.
CAPTCHA_PROTECTED_FORMS is a typed parameter ([tool.splent.config_schema]):
a list whose items are among signup, login, reset, contact,
comment and careers, decided when the product is derived (derivation
bind), and marked uvl = true, so a line can model its values. openhubs_spl
gives captcha an or-group of nodes for the forms the line has,
captcha_on_signup, captcha_on_login and captcha_on_reset, which
product:validate selects from the product's value, with
captcha_on_signup => signup and captcha_on_reset => reset: a product that
protects a form it does not have does not validate. The line has no
feature for contact, comments or careers, so it has no node for them.
Draw it on a form of your own
A template calls the two helpers, and a check listens to the form's submitting signal.
<form method="post">
...
{% if captcha_widget is defined %}
{{ captcha_script() }}
{{ captcha_widget() }}
{% endif %}
<button type="submit">Send</button>
</form>
Both helpers draw nothing for a form the product left out of
CAPTCHA_PROTECTED_FORMS, so a third party's script is not loaded for a
widget nobody answers. The comment thread sits on other features' pages (a
post, a project), so the helpers tell it apart by the template that calls
them, comments/thread.html. A form of the product's own draws the widget
whatever the setting says.
A route that checks the answer itself goes through the service locator, so it keeps working with every provider:
from flask import request
from splent_framework.services.service_locator import service_proxy
captcha = service_proxy("CaptchaService")
if not captcha.verify(captcha.token_from(request.form), request.remote_addr):
...
Write a provider
A provider subclasses CaptchaService, names the field its widget posts the
answer in and registers the class from its init_feature:
from markupsafe import Markup
from splent_io.splent_feature_captcha import CaptchaService, register_captcha_provider
class MyCaptchaService(CaptchaService):
field_name = "my-captcha"
def widget(self):
return Markup('<input name="my-captcha" required>')
def verify(self, token, remoteip=None):
return token == "..."
def init_feature(app):
register_captcha_provider(app, MyCaptchaService)
| Member | Required | What captcha does with it |
|---|---|---|
field_name |
Yes | Reads the answer from the posted form under this name (token_from) |
widget() |
Yes | Draws it in the slot of a protected form and in captcha_widget() |
verify(token, remoteip=None) |
Yes | Asks it on submit. False refuses the submission |
script_tag() |
No, nothing by default | Draws it before the widget, and in captcha_script() |
enabled() |
No, true by default | Nothing. It tells a route whether the provider has its keys |
register_captcha_provider raises TypeError for a class that does not
subclass CaptchaService, misses widget or verify, or names no
field_name, and RuntimeError when another provider is registered
already. The provider is registered under the generic CaptchaService name
in the service locator, which this feature owns, so a refinement can still
replace it with refine_service.
In the product line's model the providers are an alternative group under
captcha, so a product picks exactly one. Each provider declares
captcha among its requirements.
Providers from before this feature
Before this feature each provider registered CaptchaService itself, with
a class of its own that does not subclass the interface, and checked the
forms it chose: captcha_image 0.1, cloudflare 0.2 and recaptcha 0.3, and
anything older. A product upgrades its provider in the same change that
adds captcha.
A product that adds captcha and keeps such a provider goes on as before:
captcha asks it nothing, leaves the slots to it and has its template
helpers draw its widget, as its own helpers did, so no form is checked
twice, drawn with two widgets or answered with a 500. CAPTCHA_PROTECTED_FORMS
changes nothing then, and the log says, once, which provider to upgrade.
Without a provider
A product that installs captcha without a provider protects nothing: no
widget is drawn and every submission goes through. The log says so, once,
the first time a form asks.
Use it in a product
splent feature:add splent_feature_captcha
splent feature:add splent_feature_captcha_image
A provider imports captcha as it loads, so list captcha before it, or
give the model a constraint such as captcha_image => captcha, which puts
captcha first in the load order. Add both in the same change, with a
provider recent enough to register through captcha (see above), and set
CAPTCHA_PROTECTED_FORMS in that change too when the product has no
sign-up.
Develop
splent feature:test splent_feature_captcha
splent feature:contract splent_feature_captcha
The tests put a provider of their own in place of the product's, so they run in a product with any provider.
Release
splent feature:release splent_feature_captcha --dry-run --bump patch
splent feature:release splent_feature_captcha
The first command rehearses the release and changes nothing. The second publishes it to the git forge and to PyPI, and a PyPI version is permanent.