# Worker CAPTCHA

The Gmail API with Repo connection and reconnect forms use Prosopo Procaptcha.
The existing legacy login and legacy Gmail authorization CAPTCHA configuration
is separate.

## Administrator setup

1. Open `/worker-help` on each domain being used.
2. Enter the Prosopo site key and secret key, select Enabled, and save.
3. In the Prosopo portal, allow that domain and choose Puzzle or Image if a
   visible challenge is required on each attempt. Frictionless mode may pass
   visitors without a visual challenge.

Each domain has its own saved configuration. Prosopo must also allow the domain
where the worker opens the task; an `Unauthorized origin URL` response requires
correcting the allowed-domain list in the Prosopo portal.

The worker loads both browser bundles in explicit-rendering mode and starts the
widget using `/inbox-tasks/captcha.js`. This avoids the implicit loader attaching
its startup listener to an unused `nomodule` script, leaving an empty box in a
modern browser. The initializer handles either script load order and displays a
simple failure message if the provider cannot load.

Secrets are encrypted in `inbox_captcha_settings`. A blank secret field preserves
an existing Prosopo secret. Existing hCaptcha keys are marked as hCaptcha by
migration `2026_10_19_000002`; they cannot authenticate Prosopo requests. An
enabled old configuration blocks worker sign-in until new keys are saved or
CAPTCHA is explicitly disabled. Disabling CAPTCHA is an administrator action.

## Verification

The widget posts `procaptcha-response`. Before redirecting to Google, the backend
POSTs JSON to the fixed HTTPS endpoint `https://api.prosopo.io/siteverify`, with
the decrypted secret, token and server-issued `clientSessionId`. The public
challenge identifier is independent of session cookies and CSRF tokens and is
scoped to the assignment. It is consumed on success; a reconnect requires a new
challenge. Accepted token hashes are cached for 20 minutes to reject replay.

Only a successful HTTP response containing `status: "ok"` and `verified: true`
passes. Local timeout, HTTP failure, malformed response, or decryption failure
blocks Google sign-in. No redirects are followed. Tokens and secrets are not
flashed to the session or written to application logs by this integration.

Prosopo documents an upstream fail-open case for verification-provider timeouts:
its API can itself return `verified: true`. On the free tier this cannot be
distinguished from a normal successful verification. Our server cannot infer a
different result from that response. A visible puzzle is also not proof that
all automation has been stopped.

References:

- https://docs.prosopo.io/en/basics/client-side-rendering/
- https://docs.prosopo.io/en/basics/server-side-verification/
- https://docs.prosopo.io/en/basics/captcha-types/

Automated verification uses mocked HTTP and synthetic keys; it does not authorize
a real Gmail mailbox or send a campaign.
