Metadata-Version: 2.4
Name: splent_feature_recaptcha
Version: 0.4.0
License-Expression: LGPL-3.0-or-later
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: COPYING
License-File: COPYING.LESSER
Requires-Dist: splent_framework>=1.19.0
Dynamic: license-file

# splent_feature_recaptcha

The `recaptcha` feature of a [SPLENT](https://splent.io) 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

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

`RecaptchaService` implements captcha's `CaptchaService` and registers
through it. captcha does the rest, the same for every provider: it draws
the widget and Google'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 `g-recaptcha-response`. See
captcha's README for the forms it can protect.

The keys come from the settings stored by the panel first and from
`RECAPTCHA_SITE_KEY` and `RECAPTCHA_SECRET_KEY` second. Their defaults are
Google's test keys, which always pass, 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`, for the accounts whose role
is `admin`.

## Upgrading from 0.3

0.3 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:

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

The product installs `splent_feature_captcha` too, which recaptcha now
requires, in the same change that upgrades recaptcha 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 recaptcha 0.3 or older leaves the forms to it,
as before, and the log says to upgrade it.

## Use it in a product

```bash
splent feature:add splent_feature_captcha
splent feature:add splent_feature_recaptcha
```

## Develop

```bash
splent feature:test splent_feature_recaptcha
splent feature:contract splent_feature_recaptcha
```

## Release

```bash
splent feature:release splent_feature_recaptcha --dry-run --bump minor
splent feature:release splent_feature_recaptcha
```

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.
