No description
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-01 12:23:29 +01:00
src signals: one listener per form captcha knows, from KNOWN_FORMS 2026-10-31 15:29:45 +01:00
.gitignore chore: scaffold splent_feature_captcha 2026-10-23 13:22:27 +02:00
COPYING chore: scaffold splent_feature_captcha 2026-10-23 13:22:27 +02:00
COPYING.LESSER chore: scaffold splent_feature_captcha 2026-10-23 13:22:27 +02:00
MANIFEST.in chore: scaffold splent_feature_captcha 2026-10-23 13:22:27 +02:00
pyproject.toml chore: release splent_io/splent_feature_captcha to v0.3.0 2026-11-01 12:23:29 +01:00
README.md docs: the providers' settings and test keys, and the protected forms as a parameter of the line 2026-10-25 16:25:52 +01:00

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-submitting and opens auth.login.form_fields, which no released auth does yet. Until then naming login protects 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.