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