- Python 86.2%
- JavaScript 8.7%
- HTML 5.1%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| src | ||
| .gitignore | ||
| COPYING | ||
| COPYING.LESSER | ||
| MANIFEST.in | ||
| pyproject.toml | ||
| README.md | ||
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
- The widget comes without an image. When the visitor selects the box,
assets/js/captcha_image.jsloads one from/captcha/image. The session keeps an HMAC of its text, keyed withSECRET_KEY, and the time it was drawn. The text itself is never stored. - 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. - 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_AGEbounds 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.