SPLENT feature: image CAPTCHA provider
  • Python 86.2%
  • JavaScript 8.7%
  • HTML 5.1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-08 18:06:12 +01:00
src Leave a margin in the within-the-limit test; issued is truncated to the second 2026-11-08 18:05:32 +01:00
.gitignore chore: scaffold splent_feature_captcha_image 2026-10-20 23:26:38 +02:00
COPYING chore: scaffold splent_feature_captcha_image 2026-10-20 23:26:38 +02:00
COPYING.LESSER chore: scaffold splent_feature_captcha_image 2026-10-20 23:26:38 +02:00
MANIFEST.in chore: scaffold splent_feature_captcha_image 2026-10-20 23:26:38 +02:00
pyproject.toml chore: release splent_io/splent_feature_captcha_image to v0.3.1 2026-11-08 18:06:12 +01:00
README.md docs: upgrade captcha_image together with captcha, and read its log 2026-10-23 17:17:24 +02:00

splent_feature_captcha_image

The captcha_image feature of a SPLENT product line.

An image captcha the product draws itself. The visitor sees a few distorted characters and types them back, or, if they cannot see the image, listens to a few digits read out and types those. It needs no keys, no account with anybody and no request to a third party, so it works offline, behind a firewall and in development without any setup.

It is one of the three providers of splent_feature_captcha, next to splent_feature_recaptcha (Google reCAPTCHA) and splent_feature_cloudflare (Turnstile). A product installs captcha and one of them. ImageCaptchaService implements captcha's CaptchaService and registers through it, and captcha does the rest, the same for every provider: it decides which forms ask for an answer (CAPTCHA_PROTECTED_FORMS, the sign-up alone by default), draws this widget in them and asks verify() for the answer they post as captcha. See captcha's README for the forms it can protect.

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.

Upgrading from 0.1

0.1 chose the forms itself, with CAPTCHA_IMAGE_FORMS (all four it knew by default), connected its own checks to their signals and filled signup's slot. Now captcha does all of that for every provider, and its setting is CAPTCHA_PROTECTED_FORMS, which can also name the login and the request for a reset link. Its default is the sign-up alone.

[tool.splent.config]
# What CAPTCHA_IMAGE_FORMS = ["signup", "contact"] said before.
CAPTCHA_PROTECTED_FORMS = ["signup", "contact"]

The product installs splent_feature_captcha too, which captcha_image now requires, and lists it first, in the same change that upgrades captcha_image. captcha added next to captcha_image 0.1 leaves the forms to it, as before, and the log says to upgrade it. On the first request captcha's log also names any form in CAPTCHA_PROTECTED_FORMS the product does not have.

CAPTCHA_IMAGE_FORMS is obsolete. While a product still sets it, this version reads it as CAPTCHA_PROTECTED_FORMS and the log says so when the product starts. The next minor version stops reading it.

CAPTCHA_IMAGE_FORMS CAPTCHA_PROTECTED_FORMS The forms checked
Not set, or blank Anything CAPTCHA_PROTECTED_FORMS
Set Not set, or captcha's default (signup) CAPTCHA_IMAGE_FORMS, with a warning
Set Any other list CAPTCHA_PROTECTED_FORMS, and the log says the old one is ignored

captcha's default counts as no choice because product:env --merge writes it into every product's .env. A value the product's config.py chose wins over both, as the framework keeps it over a feature's.

/captcha/generate is gone. It answered the image as a data URI, which the script fetched and put in the picture, so without JavaScript there was no image and a Content-Security-Policy had to allow data: images. The script now loads the picture from /captcha/image, by URL like any other image, the same address the widget's <noscript> uses. A product that overrides captcha_image/widget.html sets data-captcha-url to url_for('captcha_image.image'), and a proxy that limited /captcha/generate limits /captcha/image and /captcha/audio instead.

How an answer is checked

  1. The widget comes without an image. When the visitor selects the box, assets/js/captcha_image.js loads one from /captcha/image. The session keeps an HMAC of its text, keyed with SECRET_KEY, and the time it was drawn. The text itself is never stored.
  2. The visitor types the characters in the box, in capitals or not. One who presses "Listen instead" gets a few digits read out from /captcha/audio, kept the same way, and types those.
  3. On submit, captcha's check asks verify(), which takes the stored answer out of the session and compares it with what was typed.
Case Result
The right characters, in any case and with spaces around them Accepted
The digits of the recording, after listening Accepted
The characters of an image drawn before the recording, or the digits of a recording heard before a new image Refused, the last one drawn is the one to answer
Wrong characters, an empty box, or no image drawn for this session Refused
The same answer a second time Refused, an image is answered once
A second guess after a wrong one Refused, the wrong guess spent the image
An image older than CAPTCHA_IMAGE_MAX_AGE Refused

A refused form comes back with the widget, and a new image arrives when the visitor selects the box again. The "New image" button asks /captcha/image for another one, and the image it replaces can no longer be answered.

Settings

Setting Default What it does
CAPTCHA_IMAGE_MAX_AGE 600 Seconds an image can be answered after it was drawn. A value that is not a positive whole number falls back to the default
CAPTCHA_IMAGE_MAX_IMAGES 300 Images one address can have drawn per window, counting the widget's first image, every "New image" and every recording. 0 turns the budget off
CAPTCHA_IMAGE_WINDOW_SECONDS 600 The window that budget is counted over
CAPTCHA_IMAGE_ALTERNATIVE "audio" What the widget offers to a visitor who cannot see the image. "audio" reads a few digits out, "none" offers nothing. A word it does not know falls back to "audio", and is logged. See The recording is the weaker check
[tool.splent.config]
CAPTCHA_IMAGE_MAX_AGE = 300
CAPTCHA_IMAGE_MAX_IMAGES = 100

What an image costs

Every image drawn costs some drawing, a write to the visitor's session and two statements on the product's database, in auth's throttle table. A SELECT reads what is left of the address's budget and an INSERT counts the image. A refused image costs the SELECT alone, and without auth's throttle (see below) there are no statements at all.

A recording costs the same, with more drawing: about a tenth of a second and some 130 KB for six digits.

A page view costs none of it. The widget comes without an image and draws the first one only when the visitor selects the box, so a crawler, or a visitor who reads the page and never fills in the form, spends no budget and writes nothing. The one exception is a browser that runs no JavaScript, which loads the image the widget holds for it in <noscript> with the page.

How many images an address can ask for

/captcha/image and /captcha/audio need no account, so each address has a budget, CAPTCHA_IMAGE_MAX_IMAGES images and recordings in CAPTCHA_IMAGE_WINDOW_SECONDS.

Past the budget What happens
GET /captcha/image or /captcha/audio 429 with Retry-After and a short message, and the session is left alone
A page with the widget The page renders as usual. When the visitor selects the box the widget says why no image comes, and the box or the button can fetch one once the budget allows it

The budget is counted per address, never per session, because a client that drops its cookie gets a new session with every request. The address is request.remote_addr, so a product behind a reverse proxy sets SPLENT_TRUSTED_PROXIES, as for auth's login throttle. The default sits far above what a classroom or an office behind one address asks for, because a spent budget refuses everyone behind it.

The count lives in auth's throttle table, so every worker of the product shares it. It needs splent_feature_auth 1.19.0 or later. With an older auth, or none, images are drawn without a budget and the log says so once.

Draw it on a form of your own

A template calls captcha's two helpers, which draw whichever provider is installed, as captcha's README shows. captcha_script() returns nothing with this provider, because the layout's layout.scripts slot already loads assets/js/captcha_image.js. The call is still worth keeping, since recaptcha and cloudflare need it.

The widget posts its answer as captcha. A route that checks it itself goes through the service locator, so it keeps working with the other providers.

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):
    ...

The endpoints

Route Answer
GET /captcha/image A new image, as a PNG. The script points the picture here, and a browser without JavaScript loads it from <noscript>
GET /captcha/audio A few new digits read out, as a WAV. 404 when CAPTCHA_IMAGE_ALTERNATIVE is "none"
HEAD on either 200, or 429 with Retry-After past the budget, with nothing drawn, counted or stored

Both are sent with Cache-Control: no-store, and answer 429 with Retry-After past the address's budget. Every image or recording a GET draws replaces the answer the session holds, so the script asks for a new address each time (/captcha/image?n=..., which the route ignores). It loads /captcha/image when the visitor first selects the box and for every "New image", and fetches /captcha/audio for every "Listen instead", never on page load. A HEAD draws nothing, so a link checker or a prefetch leaves the answer on the page alone, and the script asks with one why an image did not arrive, which the image itself cannot tell: a 429 shows the message about the budget, anything else the one about a failure.

Accessibility

The widget is a labelled group with a visible label on the box, alternative text on the image and a line of help tied to the box with aria-describedby. The image arrives when the box gets the focus, by keyboard or by pointer, and a polite live region says so. Each button is announced as controlling the image or the player. It has no inline script and no inline event handler, and its images come from the product itself, so it works under a strict Content-Security-Policy once media-src allows blob: (the recording, played from memory) and connect-src allows the product itself.

A visitor who cannot see the image presses "Listen instead", before the box in the order of the page. The script fetches a few digits read out, plays them in a player with its own controls, and the live region says to type the digits heard. The box keeps them: selecting it again does not fetch an image over them. "New image" goes back to an image. The recording is fetched whole and played from memory, so replaying or seeking it never asks the server for new digits. CAPTCHA_IMAGE_ALTERNATIVE = "none" takes the button away, and with it the only way in for whoever cannot see.

Without JavaScript the widget shows the image, /captcha/image, with a line that says to reload the page for another, and a link that downloads the recording. A download, and not the browser's own player on a page of its own, because that player asks the route again to replay or seek, and each request draws new digits. The visitor's player replays the file as often as needed. A browser that runs scripts skips both.

The recording reads digits alone, since the voices the image library ships say nothing else, and reads them in English, whatever the language of the page. The Spanish texts of the widget say so. A visitor who can neither see the image nor hear the recording still needs another way in, such as the other providers or an account opened by hand.

The recording is the weaker check

A bot can press "Listen instead" as well as a person can, and the recording is easier for it than the image:

  • six digits out of ten have a million answers, where six characters out of the image's 32 have about a billion;
  • the voices are the fixed ones the library ships, which speech recognition transcribes well, while the image is drawn anew each time.

So with the default, "audio", the captcha is about as strong as its recording. It is still the default because without it whoever cannot see the image is shut out (WCAG 1.1.1), and a captcha installed on a sign-up is first of all a form people must be able to fill in. What bounds a bot is the same for both: one attempt per challenge and the budget of images and recordings per address. A product whose forms draw more bots than it can take sets "none" only when the people it shuts out have another way in (uvlhub's sign-up with GitHub or ORCID, say), or installs another provider.

Change how it looks

The widget is templates/captcha_image/widget.html, with Bootstrap class names that the admin shell styles natively and the public theme styles itself. A product that wants other markup puts its own captcha_image/widget.html in src/<product>/templates/. It keeps the data-captcha-* attributes, which the script looks for (data-captcha-url is /captcha/image), keeps what <noscript> holds, and posts the answer as captcha.

Special cases

  • One widget per page. Each image or recording drawn replaces the answer of the one before it, so with two widgets on a page only the last one asked can be answered.
  • Single use depends on where the sessions live. With server-side sessions (session_redis, session_filesystem) a spent image is gone. With the default cookie session, a client can resend an old cookie together with an answer it already knows. CAPTCHA_IMAGE_MAX_AGE bounds how long that works.
  • A browser that restores a page from its back-forward cache would show an image or offer a recording already spent. The script asks for a new one when that happens, without playing it, and a widget that had nothing yet waits for its box to be selected.

Use it in a product

splent feature:add splent_feature_captcha
splent feature:add splent_feature_captcha_image

Develop

splent feature:test splent_feature_captcha_image
splent feature:test splent_feature_captcha_image --e2e
splent feature:contract splent_feature_captcha_image

The end-to-end tests drive the product's sign-up page in Chrome, with JavaScript and without. The browser counts its own requests, so they check that the recording is asked for once however often it is replayed, and need nothing from the server but the page. A product whose sign-up draws no image captcha skips them.

Release

splent feature:release splent_feature_captcha_image --dry-run --bump minor
splent feature:release splent_feature_captcha_image

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.