splent_feature_cloudflare

The cloudflare feature of a SPLENT product line.

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.

What it does

Cloudflare Turnstile as the product's captcha. It is one of the providers of splent_feature_captcha, next to splent_feature_recaptcha (Google reCAPTCHA) and splent_feature_captcha_image (an image the product draws itself). A product installs captcha and one of them.

CloudflareService implements captcha's CaptchaService and registers through it. captcha does the rest, the same for every provider: it draws the widget and Cloudflare's script on the forms named in CAPTCHA_PROTECTED_FORMS (the sign-up alone by default) and asks verify() for the token they post as cf-turnstile-response. See captcha's README for the forms it can protect.

The keys come from the settings stored by the panel first and from TURNSTILE_SITE_KEY and TURNSTILE_SECRET_KEY second. Their defaults are Cloudflare's test keys, so development works out of the box, and a live site sets its own pair. Without a site key no widget is drawn, and without a secret every submission goes through.

The panel edits the keys at /admin/captcha.

Upgrading from 0.2

0.2 checked the comment, contact and careers forms on its own, whatever the product wanted, and never the sign-up. Now captcha decides, and by default it checks the sign-up alone. A product that relied on the old forms names them:

[tool.splent.config]
CAPTCHA_PROTECTED_FORMS = ["contact", "comment", "careers"]

The product installs splent_feature_captcha too, which cloudflare now requires, in the same change that upgrades cloudflare and sets the forms. On the first request captcha's log names any form in CAPTCHA_PROTECTED_FORMS the product does not have, and says so as an error when that leaves no form protected, which is what a product without a sign-up that kept the default sees. captcha added next to cloudflare 0.2 or older leaves the forms to it, as before, and the log says to upgrade it.

Access

/admin/captcha opens only for the accounts whose role is admin. The keys are site secrets and switch the captcha of every form, so staff are refused too. Any other signed-in account gets 403 and does not see the Captcha link in the sidebar, and an anonymous visitor is sent to log in. The feature has no public screen of its own. Its check runs, through captcha, inside the forms other features open to everyone, signed in or not.

There is no setting for this role, and a refinement cannot replace the view that checks it, because it may add routes to this feature but never replace one of its own. Another feature can decide for this screen with an access policy registered for the prefix cloudflare.admin (register_access_policy, splent_framework 1.20.0). The framework asks the policy before the role. It answers True to let an account in, False to refuse it, or None to leave the decision to the role, and the sidebar link follows the same answer. That is the way to let a group of accounts manage only this section, for example the people who run the site's integrations, without giving them the admin role. See Access control.

Without such a feature, give the person's account the admin role. The staff role does not open this screen. Staff opens every panel screen that asks for PANEL_ROLES, and this one asks for ADMIN_ROLES.

splent feature:auth set-role someone@example.com admin

The stored secret key is never sent back to the browser. The settings screen says whether one is stored and leaves its field empty. Saving with the field empty keeps the stored secret, typing a new one replaces it, and the remove box clears it, so the product's TURNSTILE_SECRET_KEY is used again.

Two secrets leave the forms open, even when a real site key is stored. One is an empty secret, with which the check lets every submission through, and the other is Cloudflare's always-pass test key, the default of TURNSTILE_SECRET_KEY. CloudflareService.leaves_forms_open(secret) is true for both. While the secret in effect is one of them, the settings screen warns that the captcha does not protect the forms, with a message for each case. When a real secret is stored and the product's is empty or the test key, the remove box says that removing it leaves the forms unprotected, again naming the case. A live site stores its real secret here or sets it in its configuration.

Use it in a product

splent feature:add splent_feature_captcha
splent feature:add splent_feature_cloudflare

Develop

splent feature:test splent_feature_cloudflare
splent feature:contract splent_feature_cloudflare

Release

splent feature:release splent_feature_cloudflare --dry-run --bump patch
splent feature:release splent_feature_cloudflare

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.