refactor: update turnstile flow, show all verification states and improve ux

Author: HMarzban

packages/webapp/.env.example

@@ -18,7 +18,7 @@ NEXT_PUBLIC_SPACES_SECRET=
 
 # Turnstile
 NEXT_PUBLIC_TURNSTILE_SITE_KEY=
-TURNSTILE_SECRET_KEY=
+NEXT_PRIVATE_TURNSTILE_SECRET_KEY=
 
 # Google One Tap
 NEXT_PUBLIC_GOOGLE_CLIENT_ID=

packages/webapp/components/TurnstilePage.tsx

@@ -1,109 +1,195 @@
 import { useStore } from '@stores'
 import { SiCloudflare } from 'react-icons/si'
 import { Turnstile } from '@marsidev/react-turnstile'
-import axios from 'axios'
-import { useState, useRef, useEffect } from 'react'
+import { useState, useRef, useCallback } from 'react'
 import Config from '@config'
+import { SlugPageLoader } from './SlugPageLoader'
+
 type Props = {
   showTurnstile: boolean
 }
-import { SlugPageLoader } from './SlugPageLoader'
+
+type TurnstileState =
+  | 'loading' // Widget is loading
+  | 'ready' // Widget ready for interaction
+  | 'solving' // User is solving the challenge
+  | 'verifying' // Verifying with our API
+  | 'success' // Verification complete
+  | 'error' // Error occurred
+  | 'expired' // Token expired
+  | 'unsupported' // Browser doesn't support Turnstile
 
 const TurnstileModal = ({ showTurnstile }: Props) => {
+  const [state, setState] = useState<TurnstileState>('loading')
   const [error, setError] = useState<string | null>(null)
+  const [retryCount, setRetryCount] = useState(0)
   const ref = useRef<any>(null)
   const setWorkspaceSetting = useStore((state) => state.setWorkspaceSetting)
 
-  useEffect(() => {
-    setWorkspaceSetting('isTurnstileVerified', !showTurnstile)
-  }, [showTurnstile, setWorkspaceSetting])
+  const handleLoad = useCallback(() => {
+    setState('ready')
+    setError(null)
+  }, [])
 
-  const handleVerification = async (token: string | null) => {
-    if (!token) return
+  const handleBeforeInteractive = useCallback(() => {
+    setState('solving')
+  }, [])
 
-    try {
-      const response = await axios.post(
-        Config.app.turnstile.verifyUrl,
-        { token },
-        {
-          headers: {
-            'Content-Type': 'application/json'
-          }
+  const handleVerification = useCallback(
+    async (token: string | null) => {
+      if (!token || state === 'verifying') return
+
+      setState('verifying')
+      setError(null)
+
+      try {
+        const response = await fetch(Config.app.turnstile.verifyUrl, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ token }),
+          signal: AbortSignal.timeout(15000)
+        })
+
+        const data = await response.json()
+
+        if (data.success) {
+          setState('success')
+          setWorkspaceSetting('isTurnstileVerified', true)
+          // No page reload needed!
+        } else {
+          throw new Error(data.message || 'Verification failed')
         }
-      )
+      } catch (err) {
+        let errorMessage = 'Verification failed. Please try again.'
 
-      const data = response.data
+        if (err instanceof Error) {
+          if (err.name === 'TimeoutError') {
+            errorMessage = 'Verification timed out. Please try again.'
+          } else if (err.message.includes('fetch')) {
+            errorMessage = 'Network error. Please check your connection.'
+          } else {
+            errorMessage = err.message
+          }
+        }
 
-      if (data.success) {
-        setWorkspaceSetting('isTurnstileVerified', true)
-        window.location.reload()
-      } else {
-        setError('Verification failed. Please try again.')
-      }
-    } catch (err) {
-      if (axios.isAxiosError(err)) {
-        console.error('Verification error:', err.response?.data || err.message)
-      } else {
-        console.error('Verification error:', err)
+        setState('error')
+        setError(errorMessage)
+        console.error('Turnstile verification error:', err)
       }
-      setError('An error occurred during verification. Please try again.')
-    }
-  }
+    },
+    [state, setWorkspaceSetting]
+  )
 
-  const handleError = (error: string) => {
-    setError(error)
-  }
+  const handleError = useCallback((errorCode: string) => {
+    console.error('Turnstile widget error:', errorCode)
+    setState('error')
+    setError('Captcha failed to load. Please refresh the page.')
+  }, [])
 
-  if (!Config.app.turnstile.siteKey) {
-    return <p>Error: Turnstile site key is not set.</p>
-  }
+  const handleExpire = useCallback(() => {
+    setState('expired')
+    setError('Verification expired. Please try again.')
+  }, [])
 
-  const retryHandler = () => {
-    window.location.reload()
+  const handleUnsupported = useCallback(() => {
+    setState('unsupported')
+    setError('Your browser does not support this security feature.')
+  }, [])
+
+  const handleRetry = useCallback(() => {
+    setState('loading')
     setError(null)
+    setRetryCount((prev) => prev + 1)
+    ref.current?.reset()
+  }, [])
+
+  // Get display text and loading state based on current state
+  const getStateInfo = () => {
+    switch (state) {
+      case 'loading':
+        return { text: 'Loading security check', showSpinner: true }
+      case 'ready':
+        return { text: 'Complete security check', showSpinner: false }
+      case 'solving':
+        return { text: 'Solving challenge', showSpinner: true }
+      case 'verifying':
+        return { text: 'Verifying', showSpinner: true }
+      case 'success':
+        return { text: 'Verified', showSpinner: false }
+      case 'error':
+      case 'expired':
+      case 'unsupported':
+        return { text: 'Security check failed', showSpinner: false }
+      default:
+        return { text: 'Security check', showSpinner: false }
+    }
   }
 
-  return (
-    <div className="fixed inset-0 z-20 flex size-full h-dvh flex-col items-center justify-center">
-      {error && (
-        <div className="rounded-md p-6 py-2 drop-shadow-md backdrop-blur-md">
-          <div>
-            <h2 className="mt-6 text-center text-3xl font-extrabold text-gray-900">
-              Cloudflare Verification Failed
-            </h2>
-            <div className="mt-4 rounded-md border border-red-200 bg-red-50 p-4">
-              <div className="text-sm text-red-700">
-                <p className="mt-1">Details: {error}</p>
-              </div>
-            </div>
-            <div className="mt-4 text-center">
-              <button
-                onClick={retryHandler}
-                className="text-sm font-medium text-indigo-600 hover:text-indigo-500">
-                Retry
-              </button>
-            </div>
-          </div>
+  const { text, showSpinner } = getStateInfo()
+
+  if (!Config.app.turnstile.siteKey) {
+    return (
+      <div className="fixed inset-0 bottom-0 z-30 flex items-center justify-center bg-red-50/40 backdrop-blur-sm">
+        <div className="text-center">
+          <h2 className="text-xl font-semibold text-red-700">Configuration Error</h2>
+          <p className="mt-2 text-red-600">Turnstile site key is not configured.</p>
         </div>
-      )}
+      </div>
+    )
+  }
 
+  return (
+    <div className="fixed bottom-4 left-0 z-10 flex w-auto items-center rounded-lg bg-gray-100 px-4 py-1 text-sm text-gray-700 md:left-4">
       <Turnstile
+        key={retryCount}
         ref={ref}
         siteKey={Config.app.turnstile.siteKey}
+        onLoad={handleLoad}
+        onBeforeInteractive={handleBeforeInteractive}
         onSuccess={handleVerification}
         onError={handleError}
-        onExpire={handleError}
+        onExpire={handleExpire}
+        onUnsupported={handleUnsupported}
       />
-      <div className="fixed bottom-4 left-4 flex w-fit items-center rounded-full bg-gray-100 px-3 py-1 text-sm text-gray-700 md:right-4">
-        <SiCloudflare size={20} className="mr-2 text-[#f38020]" />
-        Security by Cloudflare
-        <span className="loading loading-dots loading-xs mt-2 ml-2"></span>
+
+      <div className="flex w-full items-center justify-center gap-1">
+        <span className={`flex ${error && 'hidden md:flex'} justify-center gap-1`}>
+          <SiCloudflare size={20} className="mr-2 text-[#f38020]" />
+          Security by Cloudflare
+        </span>
+
+        {/* Show current state */}
+        {!error && (
+          <>
+            <div className="divider divider-horizontal m-0 w-0 py-1"></div>
+            <span className="text-xs font-normal text-gray-400">{text}</span>
+            {showSpinner && <span className="loading loading-dots loading-xs"></span>}
+          </>
+        )}
+
+        {/* Error state */}
+        {error && (
+          <>
+            <div className="divider divider-horizontal m-0 hidden w-0 py-1 md:flex"></div>
+            <p className="text-sm text-red-700">{error}</p>
+            <button
+              onClick={handleRetry}
+              disabled={state === 'verifying'}
+              className={`btn btn-sm btn-ghost btn-error btn-dash h-5 md:h-auto`}>
+              Try Again
+            </button>
+          </>
+        )}
       </div>
     </div>
   )
 }
 
 export const SlugPageLoaderWithTurnstile = ({ showTurnstile }: Props) => {
+  if (!showTurnstile) {
+    return <SlugPageLoader />
+  }
+
   return (
     <div className="h-full">
       <TurnstileModal showTurnstile={showTurnstile} />

packages/webapp/components/skeleton/SlugPageLoaderWithTurnstile.tsx

@@ -6,7 +6,7 @@ const AVATARS_BUCKET_URL = `${PUBLIC_BUCKET_URL}/user_avatars`
 const config: Config = {
   app: {
     turnstile: {
-      isEnabled: process.env.TURNSTILE_SECRET_KEY ? true : false,
+      isEnabled: process.env.NEXT_PRIVATE_TURNSTILE_SECRET_KEY ? true : false,
       siteKey: process.env.NEXT_PUBLIC_TURNSTILE_SITE_KEY || '',
       verifyUrl: '/api/verify-turnstile',
       expireTime: 60 * 60 * 24 * 2 // 2 days