apiVersion: capsule.dev/v0.1
kind: Capsule
name: f4c-turnstile-gate
version: 0.1.0
type: adapter
purpose:
summary: 'Provides a React component to integrate Cloudflare Turnstile for bot verification,
wrapping the application content. It handles the client-side rendering of the
Turnstile widget and stores the token in session storage.
'
owns:
- Client-side Turnstile widget rendering
- Storing Turnstile token in `sessionStorage`
- Wrapping application content with a verification gate
does_not_own:
- Server-side Turnstile token verification
- Core application logic or UI
interfaces:
provides:
- kind: library
name: TurnstileGate
description: React component that displays a Cloudflare Turnstile challenge.
- kind: env
name: sessionStorage.ts_token
description: Stores the successfully verified Turnstile token in browser session
storage.
requires:
- kind: http_api
name: Cloudflare Turnstile JS API
description: Loads the Turnstile JavaScript API from Cloudflare.
agent:
summary_for_ai: 'This capsule handles client-side Turnstile integration. Agents
should focus on ensuring the widget loads correctly, token storage is secure,
and the component integrates seamlessly with the application flow. The `TURNSTILE_SITEKEY`
is crucial.
'
avoid:
- Adding server-side verification logic.
- Introducing direct dependencies on application-specific components.
verification:
invariants:
- A valid Turnstile token must be stored in `sessionStorage` upon successful verification.
- The component must re-challenge if `sessionStorage.ts_token` is not present or
on route change.
x-reuse:
notes: 'app/src/components/TurnstileGate.tsx: `TURNSTILE_SITEKEY` has a hardcoded
fallback to Cloudflare''s always-pass test key, which should be replaced in production.
Relies on `sessionStorage` for token persistence, which might not be suitable
for all applications.
'
x-reconstruct:
install: install.json