Repository navigation
Assessment endpoint: Turnstile, validation and delivery #28
Description
Parent
Spec: #20
What to build
The endpoint behind the Assessment Form: a single server route in the same Worker that serves the site, which verifies the visitor is human, revalidates everything, and delivers the submission to the Inbox with the visitor's address as reply-to.
Turnstile runs invisible, on submit — never gating the button. Tokens are single-use with a 300-second window, so a retry after failure needs a fresh token; reusing the original fails as a duplicate and looks like a different bug.
The server revalidates independently. Client validation is a convenience, never a guard.
The response contract is a discriminated union the UI maps directly onto its states:
type Result =
| { ok: true }
| { ok: false; error: 'validation'; fields: Record<string, string> }
| { ok: false; error: 'challenge' | 'rate' | 'delivery' };Email sends from an Email Routing subdomain so the apex MX stays with Google.
Rate limiting is deliberately not in code — it is WAF configuration, so the Worker stays stateless.
The Worker logs field names and outcomes only, never values.
Acceptance criteria
- A server route accepts
POSTwithFormDataand has no component, so it is excluded from prerendering - Honeypot non-empty is rejected as a validation failure
- The Turnstile token is verified server-side; a missing or invalid token returns the challenge error
- Verification checks the response hostname against the expected host
- Every field is revalidated and length-capped server-side; unknown fields are rejected
- Success sends via the email binding with reply-to set to the visitor's address
- The subject identifies the practice or the sender; the body lists submitted fields, omitting empties, with honeypot and token stripped
- All five result shapes return their documented status codes with
Cache-Control: no-store - The UI maps each result onto the matching state from ticket 8
- A retry after a failure requests a fresh Turnstile token
- No message body, email address or field value is ever logged
- All paths are exercisable locally with test keys and a simulated binding, with no Cloudflare account
- An empty client sitekey does not disable server-side verification
Blocked by
- Assessment section and form UI #27 — Assessment section and form UI
Activity
[-]Assessment section and form UI[/-][+]Assessment endpoint: Turnstile, validation and delivery[/+]Abuubkar commentedon Sep 5, 2026
Done on branch
ticket/28-endpoint.Verified against the real Worker
Every path exercised under
wrangler/Miniflare with Turnstile test keys — no Cloudflare account:400 {"error":"validation"}403 {"error":"challenge"}400 {"fields":{"name":"required"}}400 {"fields":{"email":"invalid"}}400 {"fields":{"name":"too_long"}}502 {"error":"delivery"}That last one is correct: no
EMAILbinding exists locally, so delivery genuinely fails and the UI offers the mailto fallback rather than faking success. Every response carriescache-control: no-store.Three findings
1.
globalThis.envis not populated in Start server code. Reading it yields an empty secret, which short-circuits every submission tochallenge— indistinguishable from a real Turnstile failure.cloudflare:workersis the accessor, exactly as the #4 research documented; I had reached for the obvious-looking global first.2.
wrangler typesbreaks client typing. It emits a global Worker environment that overrides DOM lib types project-wide —document.head.append()stopped typechecking in client code. Replaced with a local declaration of just the four bindings the route needs, so the two environments cannot collide. Worth knowing before someone runswrangler typesagain.3. Validation reported the wrong reason. An over-long name came back as
requiredrather thantoo_long, because the required check overwrote the length flag — sending the visitor to look for an empty field. Fixed.Also worth noting: a Miniflare
ERR_RUNTIME_FAILUREmid-testing turned out to be leftover runtime state from repeatedly killing preview servers, not a code fault. A cleanrm -rf .wranglerrestart resolved it.Client
Turnstile loads on first form interaction, not page load (issue #18), and the widget is reset after every attempt — tokens are single-use with a 300-second window, so a retry needs a fresh one.
Abuubkar commentedon Sep 5, 2026
Done. All six paths verified against the real Worker; three bugs found doing so.
Assessment endpoint: Turnstile, validation and delivery