From f27c431df7d7902d399e8fd9c3cb18756a5b5f49 Mon Sep 17 00:00:00 2001
From: StringKE <stringke.me@gmail.com>
Date: Fri, 14 Aug 2026 11:33:52 +0400
Subject: [PATCH] fix(auth): gate protected actions on Turnstile

Signed-off-by: StringKE <stringke.me@gmail.com>
---
 .../src/routes/forgot-password/index.test.tsx | 33 +++++++-
 .../src/routes/forgot-password/index.tsx      |  7 +-
 .../routes/sign-in/SignInGuestButton.test.tsx | 11 +++
 .../src/routes/sign-in/SignInGuestButton.tsx  |  8 +-
 .../routes/sign-in/SignInOtpPanel.test.tsx    | 22 ++++-
 .../src/routes/sign-in/SignInOtpPanel.tsx     |  6 +-
 .../src/routes/sign-in/SignInPage.test.tsx    |  1 +
 apps/server/src/routes/sign-in/SignInPage.tsx | 24 ++++--
 .../sign-in/SignInSocialButtons.test.tsx      | 43 ++++++++++
 .../routes/sign-in/SignInSocialButtons.tsx    |  4 +-
 .../src/routes/sign-in/useSignIn.test.tsx     | 82 ++++++++++++++++++-
 apps/server/src/routes/sign-in/useSignIn.ts   | 32 ++++++--
 docs/design/01-authentication.md              |  2 +
 docs/zh-Hans/design/01-authentication.md      |  4 +-
 14 files changed, 253 insertions(+), 26 deletions(-)
 create mode 100644 apps/server/src/routes/sign-in/SignInSocialButtons.test.tsx

diff --git a/apps/server/src/routes/forgot-password/index.test.tsx b/apps/server/src/routes/forgot-password/index.test.tsx
index 41913f04..149ece7c 100644
--- a/apps/server/src/routes/forgot-password/index.test.tsx
+++ b/apps/server/src/routes/forgot-password/index.test.tsx
@@ -3,7 +3,7 @@
 import { act } from 'react'
 import { createRoot } from 'react-dom/client'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
-import type { InputHTMLAttributes, ReactNode } from 'react'
+import type { ButtonHTMLAttributes, InputHTMLAttributes, ReactNode } from 'react'
 
 const routerState = vi.hoisted(() => ({
   navigate: vi.fn(),
@@ -17,6 +17,11 @@ const mutationState = vi.hoisted(() => ({
   }[],
 }))
 
+const authConfigState = vi.hoisted(() => ({
+  data: undefined as { turnstileSiteKey: string | null } | undefined,
+  isPending: false,
+}))
+
 vi.mock('@lingui/react/macro', () => ({
   Trans: ({ children }: { children: ReactNode }) => <>{children}</>,
   useLingui: () => ({ t: (strings: TemplateStringsArray) => strings[0] }),
@@ -36,7 +41,11 @@ vi.mock('../../lib/router', () => ({
 }))
 
 vi.mock('@tanstack/react-query', () => ({
-  useQuery: () => ({ data: undefined, isPending: false, error: null }),
+  useQuery: () => ({
+    data: authConfigState.data,
+    isPending: authConfigState.isPending,
+    error: null,
+  }),
   useMutation: (options: (typeof mutationState.captured)[number]) => {
     mutationState.captured.push(options)
     return { mutate: vi.fn(), mutateAsync: vi.fn(), isPending: false, isSuccess: false }
@@ -54,7 +63,11 @@ vi.mock('../../components/layout', () => ({
 
 vi.mock('../../components/ui', () => ({
   Alert: ({ children }: { children: ReactNode }) => <div>{children}</div>,
-  Button: ({ children }: { children: ReactNode }) => <button type="button">{children}</button>,
+  Button: ({ children, ...props }: ButtonHTMLAttributes<HTMLButtonElement>) => (
+    <button type="button" {...props}>
+      {children}
+    </button>
+  ),
   Field: ({ children }: { children: ReactNode }) => <div>{children}</div>,
   Input: (props: InputHTMLAttributes<HTMLInputElement>) => <input {...props} />,
   PageHeader: ({ title }: { title: ReactNode }) => <h1>{title}</h1>,
@@ -126,6 +139,8 @@ describe('ForgotPasswordPage navigation links', () => {
     mutationState.captured.length = 0
     routerState.search = {}
     routerState.pathname = '/forgot-password'
+    authConfigState.data = undefined
+    authConfigState.isPending = false
     globalThis.sessionStorage.clear()
     globalThis.history.replaceState({}, '', '/forgot-password')
   })
@@ -139,6 +154,18 @@ describe('ForgotPasswordPage navigation links', () => {
     await unmount(container, root)
   })
 
+  it('disables reset-link delivery until Turnstile is ready', async () => {
+    authConfigState.data = { turnstileSiteKey: 'site-key' }
+
+    const { container, root } = await renderPage()
+
+    const submit = Array.from(container.querySelectorAll('button')).find((button) =>
+      button.textContent?.includes('Send reset link'),
+    )
+    expect(submit?.disabled).toBe(true)
+    await unmount(container, root)
+  })
+
   it('keeps organization and locale context when returning to sign in', async () => {
     routerState.search = { organization_id: 'org-1', locale: 'en' }
     globalThis.history.replaceState({}, '', '/forgot-password?organization_id=org-1&locale=en')
diff --git a/apps/server/src/routes/forgot-password/index.tsx b/apps/server/src/routes/forgot-password/index.tsx
index 05c3a572..16c636ac 100644
--- a/apps/server/src/routes/forgot-password/index.tsx
+++ b/apps/server/src/routes/forgot-password/index.tsx
@@ -114,6 +114,8 @@ function RequestStep({ organizationId, onDone }: RequestStepProps): ReactNode {
     turnstileToken,
     setTurnstileToken,
   )
+  const turnstileReady =
+    !authConfigQuery.isPending && (authConfig.turnstileSiteKey === null || Boolean(turnstileToken))
 
   const requestMutation = useMutation({
     mutationFn: (emailValue: string) =>
@@ -145,6 +147,7 @@ function RequestStep({ organizationId, onDone }: RequestStepProps): ReactNode {
       setEmailError(t`Enter a valid email address`)
       return
     }
+    if (!turnstileReady) return
     await requestMutation.mutateAsync(email)
   }
 
@@ -171,10 +174,10 @@ function RequestStep({ organizationId, onDone }: RequestStepProps): ReactNode {
           />
         </Field>
 
-        <Button type="submit" fullWidth isLoading={isSubmitting}>
+        <div ref={containerRef} {...stylex.props(styles.turnstile)} />
+        <Button type="submit" fullWidth isLoading={isSubmitting} disabled={!turnstileReady}>
           <Trans>Send reset link</Trans>
         </Button>
-        <div ref={containerRef} {...stylex.props(styles.turnstile)} />
       </div>
     </form>
   )
diff --git a/apps/server/src/routes/sign-in/SignInGuestButton.test.tsx b/apps/server/src/routes/sign-in/SignInGuestButton.test.tsx
index 9ccf1eed..08370c20 100644
--- a/apps/server/src/routes/sign-in/SignInGuestButton.test.tsx
+++ b/apps/server/src/routes/sign-in/SignInGuestButton.test.tsx
@@ -51,6 +51,17 @@ describe('SignInGuestButton', () => {
     })
     expect(onContinue).toHaveBeenCalledTimes(1)
 
+    await act(async () => {
+      root.render(<SignInGuestButton onContinue={onContinue} isLoading={false} disabled={true} />)
+    })
+    const turnstileBlockedButton = container.querySelector('button')
+    expect(turnstileBlockedButton?.disabled).toBe(true)
+
+    await act(async () => {
+      turnstileBlockedButton?.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+    })
+    expect(onContinue).toHaveBeenCalledTimes(1)
+
     await act(async () => {
       root.unmount()
     })
diff --git a/apps/server/src/routes/sign-in/SignInGuestButton.tsx b/apps/server/src/routes/sign-in/SignInGuestButton.tsx
index 9889714f..2e38ccfa 100644
--- a/apps/server/src/routes/sign-in/SignInGuestButton.tsx
+++ b/apps/server/src/routes/sign-in/SignInGuestButton.tsx
@@ -25,9 +25,14 @@ const guestStyles = stylex.create({
 export type SignInGuestButtonProps = {
   onContinue: () => void
   isLoading: boolean
+  disabled?: boolean
 }
 
-export function SignInGuestButton({ onContinue, isLoading }: SignInGuestButtonProps): ReactNode {
+export function SignInGuestButton({
+  onContinue,
+  isLoading,
+  disabled = false,
+}: SignInGuestButtonProps): ReactNode {
   const { t } = useLingui()
   return (
     <div {...stylex.props(guestStyles.stack)}>
@@ -40,6 +45,7 @@ export function SignInGuestButton({ onContinue, isLoading }: SignInGuestButtonPr
         variant="secondary"
         fullWidth
         isLoading={isLoading}
+        disabled={disabled}
         aria-label={t`Continue as guest`}
         onClick={onContinue}
       >
diff --git a/apps/server/src/routes/sign-in/SignInOtpPanel.test.tsx b/apps/server/src/routes/sign-in/SignInOtpPanel.test.tsx
index b0765843..26ee8038 100644
--- a/apps/server/src/routes/sign-in/SignInOtpPanel.test.tsx
+++ b/apps/server/src/routes/sign-in/SignInOtpPanel.test.tsx
@@ -20,18 +20,22 @@ function profileValues(): ProfileValues {
   }
 }
 
-function renderPanel(enabledMethods: readonly OtpSignInMethod[]): string {
+function renderPanel(
+  enabledMethods: readonly OtpSignInMethod[],
+  options: { identifier?: string; isTurnstileReady?: boolean } = {},
+): string {
   return renderToStaticMarkup(
     <SignInOtpPanel
       method={enabledMethods[0] ?? 'otp-email'}
       enabledMethods={enabledMethods}
       step="input"
-      identifier=""
+      identifier={options.identifier ?? ''}
       otpCode=""
       profileValues={profileValues()}
       profileFields={[]}
       requiredProfileFields={[]}
       isLoading={false}
+      isTurnstileReady={options.isTurnstileReady ?? true}
       onChangeIdentifier={vi.fn()}
       onChangeProfileValue={vi.fn()}
       onChangeCode={vi.fn()}
@@ -60,4 +64,18 @@ describe('SignInOtpPanel', () => {
     expect(html.indexOf('WhatsApp OTP')).toBeLessThan(html.indexOf('SMS OTP'))
     expect(html).not.toContain('Email OTP')
   })
+
+  it('disables OTP delivery until Turnstile is ready', () => {
+    const blocked = renderPanel(['otp-email'], {
+      identifier: 'owner@example.com',
+      isTurnstileReady: false,
+    })
+    const ready = renderPanel(['otp-email'], {
+      identifier: 'owner@example.com',
+      isTurnstileReady: true,
+    })
+
+    expect(blocked).toMatch(/<button[^>]*disabled=""[^>]*>Send code via email<\/button>/)
+    expect(ready).not.toMatch(/<button[^>]*disabled=""[^>]*>Send code via email<\/button>/)
+  })
 })
diff --git a/apps/server/src/routes/sign-in/SignInOtpPanel.tsx b/apps/server/src/routes/sign-in/SignInOtpPanel.tsx
index d05cff6d..faadff96 100644
--- a/apps/server/src/routes/sign-in/SignInOtpPanel.tsx
+++ b/apps/server/src/routes/sign-in/SignInOtpPanel.tsx
@@ -27,6 +27,7 @@ export type SignInOtpPanelProps = {
   profileFields: readonly ProfileFieldKey[]
   requiredProfileFields: readonly ProfileFieldKey[]
   isLoading: boolean
+  isTurnstileReady: boolean
   onChangeIdentifier: (value: string) => void
   onChangeProfileValue: (field: ProfileFieldKey, value: string) => void
   onChangeCode: (value: string) => void
@@ -45,6 +46,7 @@ export function SignInOtpPanel({
   profileFields,
   requiredProfileFields,
   isLoading,
+  isTurnstileReady,
   onChangeIdentifier,
   onChangeProfileValue,
   onChangeCode,
@@ -63,7 +65,7 @@ export function SignInOtpPanel({
   }, [step])
 
   function handleIdentifierKey(event: KeyboardEvent<HTMLInputElement>): void {
-    if (event.key === 'Enter' && identifier.trim()) onRequestOtp()
+    if (event.key === 'Enter' && identifier.trim() && isTurnstileReady) onRequestOtp()
   }
 
   function handleCodeKey(event: KeyboardEvent<HTMLInputElement>): void {
@@ -138,7 +140,7 @@ export function SignInOtpPanel({
           <Button
             fullWidth
             isLoading={isLoading}
-            disabled={!identifier.trim() || !profileComplete}
+            disabled={!identifier.trim() || !profileComplete || !isTurnstileReady}
             onClick={onRequestOtp}
           >
             {isEmail ? (
diff --git a/apps/server/src/routes/sign-in/SignInPage.test.tsx b/apps/server/src/routes/sign-in/SignInPage.test.tsx
index 47149ac3..3e8f621f 100644
--- a/apps/server/src/routes/sign-in/SignInPage.test.tsx
+++ b/apps/server/src/routes/sign-in/SignInPage.test.tsx
@@ -127,6 +127,7 @@ vi.mock('./useSignIn', () => ({
       error: null,
       otpStep: 'input',
       turnstileToken: null,
+      turnstileReady: true,
       tenantSelection: signInState.tenantSelection,
     },
     {
diff --git a/apps/server/src/routes/sign-in/SignInPage.tsx b/apps/server/src/routes/sign-in/SignInPage.tsx
index 86dfa517..7c9ea01d 100644
--- a/apps/server/src/routes/sign-in/SignInPage.tsx
+++ b/apps/server/src/routes/sign-in/SignInPage.tsx
@@ -354,10 +354,13 @@ function SignInPage(): ReactNode {
           </Alert>
         ) : null}
 
+        <div ref={containerRef} {...stylex.props(styles.turnstile)} />
+
         <SignInSocialButtons
           providers={state.authConfig.socialProviders}
           onSelect={actions.handleSocial}
           isLoading={state.isLoading}
+          disabled={!state.turnstileReady}
         />
 
         {showSeparator ? (
@@ -426,7 +429,7 @@ function SignInPage(): ReactNode {
                     type="submit"
                     fullWidth
                     isLoading={state.isLoading}
-                    disabled={!state.identifier.trim()}
+                    disabled={!state.identifier.trim() || !state.turnstileReady}
                   >
                     <Trans>Continue with SSO</Trans>
                   </Button>
@@ -461,6 +464,7 @@ function SignInPage(): ReactNode {
                 <Button
                   fullWidth
                   isLoading={state.isLoading}
+                  disabled={!state.turnstileReady}
                   onClick={actions.triggerPasskeyButton}
                   aria-label={t`Sign in with passkey`}
                 >
@@ -534,7 +538,10 @@ function SignInPage(): ReactNode {
                     fullWidth
                     isLoading={state.isLoading}
                     disabled={
-                      !state.identifier.trim() || !state.password.trim() || !requiredProfileComplete
+                      !state.identifier.trim() ||
+                      !state.password.trim() ||
+                      !requiredProfileComplete ||
+                      !state.turnstileReady
                     }
                   >
                     {isSignUpFlow ? <Trans>Sign up</Trans> : <Trans>Sign in</Trans>}
@@ -572,7 +579,9 @@ function SignInPage(): ReactNode {
                     type="submit"
                     fullWidth
                     isLoading={state.isLoading}
-                    disabled={!state.identifier.trim() || !requiredProfileComplete}
+                    disabled={
+                      !state.identifier.trim() || !requiredProfileComplete || !state.turnstileReady
+                    }
                   >
                     <Trans>Send magic link</Trans>
                   </Button>
@@ -592,6 +601,7 @@ function SignInPage(): ReactNode {
                   profileFields={profileFields}
                   requiredProfileFields={requiredFields}
                   isLoading={state.isLoading}
+                  isTurnstileReady={state.turnstileReady}
                   onChangeIdentifier={actions.setIdentifier}
                   onChangeProfileValue={actions.setProfileValue}
                   onChangeCode={actions.setOtpCode}
@@ -605,12 +615,14 @@ function SignInPage(): ReactNode {
         ) : null}
 
         {ambiguousResolution ? null : state.authConfig.guest ? (
-          <SignInGuestButton onContinue={actions.submitGuest} isLoading={state.isLoading} />
+          <SignInGuestButton
+            onContinue={actions.submitGuest}
+            isLoading={state.isLoading}
+            disabled={!state.turnstileReady}
+          />
         ) : state.guestEntryPending ? (
           <div aria-hidden="true" {...stylex.props(styles.guestEntryPlaceholder)} />
         ) : null}
-
-        <div ref={containerRef} {...stylex.props(styles.turnstile)} />
       </div>
     </AuthLayout>
   )
diff --git a/apps/server/src/routes/sign-in/SignInSocialButtons.test.tsx b/apps/server/src/routes/sign-in/SignInSocialButtons.test.tsx
new file mode 100644
index 00000000..73b8aec6
--- /dev/null
+++ b/apps/server/src/routes/sign-in/SignInSocialButtons.test.tsx
@@ -0,0 +1,43 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import { describe, expect, it, vi } from 'vitest'
+import type { ReactNode } from 'react'
+import { SignInSocialButtons } from './SignInSocialButtons'
+
+vi.mock('@lingui/react/macro', () => ({
+  Trans: ({ children }: { children: ReactNode }) => <>{children}</>,
+}))
+
+const providers = [
+  {
+    provider: 'github',
+    allowLogin: true,
+    allowUserCreation: true,
+    requireVerifiedEmail: true,
+    allowedEmailDomains: [],
+    blockedEmailDomains: [],
+  },
+]
+
+describe('SignInSocialButtons', () => {
+  it('disables provider authorization until Turnstile is ready', () => {
+    const blocked = renderToStaticMarkup(
+      <SignInSocialButtons
+        providers={providers}
+        onSelect={vi.fn()}
+        isLoading={false}
+        disabled={true}
+      />,
+    )
+    const ready = renderToStaticMarkup(
+      <SignInSocialButtons
+        providers={providers}
+        onSelect={vi.fn()}
+        isLoading={false}
+        disabled={false}
+      />,
+    )
+
+    expect(blocked).toMatch(/<button[^>]*disabled=""[^>]*>.*Continue with GitHub.*<\/button>/)
+    expect(ready).not.toMatch(/<button[^>]*disabled=""[^>]*>.*Continue with GitHub.*<\/button>/)
+  })
+})
diff --git a/apps/server/src/routes/sign-in/SignInSocialButtons.tsx b/apps/server/src/routes/sign-in/SignInSocialButtons.tsx
index afeddce3..bbd63826 100644
--- a/apps/server/src/routes/sign-in/SignInSocialButtons.tsx
+++ b/apps/server/src/routes/sign-in/SignInSocialButtons.tsx
@@ -11,6 +11,7 @@ export type SignInSocialButtonsProps = {
   providers: readonly PublicSocialProvider[]
   onSelect: (provider: string) => void
   isLoading: boolean
+  disabled?: boolean
 }
 
 function GoogleIcon(): ReactNode {
@@ -111,6 +112,7 @@ export function SignInSocialButtons({
   providers,
   onSelect,
   isLoading,
+  disabled = false,
 }: SignInSocialButtonsProps): ReactNode {
   const visibleProviders = useProviders(providers)
 
@@ -123,7 +125,7 @@ export function SignInSocialButtons({
           key={p.id}
           variant="secondary"
           fullWidth
-          disabled={isLoading}
+          disabled={isLoading || disabled}
           onClick={() => onSelect(p.id)}
           {...stylex.props(styles.socialButton)}
         >
diff --git a/apps/server/src/routes/sign-in/useSignIn.test.tsx b/apps/server/src/routes/sign-in/useSignIn.test.tsx
index d5832ed1..71dbeee2 100644
--- a/apps/server/src/routes/sign-in/useSignIn.test.tsx
+++ b/apps/server/src/routes/sign-in/useSignIn.test.tsx
@@ -7,6 +7,7 @@ import { describe, expect, it, vi } from 'vitest'
 import type { ReactNode } from 'react'
 import type { Result } from '@xid-kit/types'
 import type { ApiClient } from '../../lib/api'
+import type { PublicHostedAuthConfig } from './auth-config'
 
 const passkeyCalls = vi.hoisted(
   (): Array<{
@@ -16,6 +17,9 @@ const passkeyCalls = vi.hoisted(
   }> => [],
 )
 const postCalls = vi.hoisted((): Array<{ path: string; body: unknown }> => [])
+const authConfigState = vi.hoisted(() => ({
+  config: null as PublicHostedAuthConfig | null,
+}))
 const routerState = vi.hoisted(() => ({
   search: {} as Record<string, string | undefined>,
   navigate: vi.fn(),
@@ -39,7 +43,10 @@ vi.mock('../../lib/router', () => ({
 vi.mock('../../lib/auth-context', () => ({
   useAuth: () => ({
     api: {
-      get: async <T,>() => failure<T>(),
+      get: async <T,>() =>
+        authConfigState.config
+          ? ({ ok: true, value: authConfigState.config as T } satisfies Result<T>)
+          : failure<T>(),
       post: async <T,>(path: string, body?: unknown) => {
         postCalls.push({ path, body })
         return failure<T>()
@@ -231,6 +238,7 @@ describe('useSignIn passkey policy gate', () => {
 
 describe('useSignIn rememberMe', () => {
   it('密码提交 body 带 rememberMe:默认 false,勾选后 true', async () => {
+    authConfigState.config = null
     postCalls.length = 0
     routerState.search = {}
     ;(globalThis as Record<string, unknown>)['IS_REACT_ACT_ENVIRONMENT'] = true
@@ -250,6 +258,9 @@ describe('useSignIn rememberMe', () => {
         </QueryClientProvider>,
       )
     })
+    await act(async () => {
+      await vi.waitFor(() => expect(captured?.[0].turnstileReady).toBe(true))
+    })
 
     expect(captured?.[0].rememberMe).toBe(false)
 
@@ -277,3 +288,72 @@ describe('useSignIn rememberMe', () => {
     })
   })
 })
+
+describe('useSignIn Turnstile action gate', () => {
+  it('blocks protected actions until the configured widget produces a token', async () => {
+    authConfigState.config = {
+      ...DEFAULT_PUBLIC_AUTH_CONFIG,
+      turnstileSiteKey: 'site-key',
+      methods: {
+        ...DEFAULT_PUBLIC_AUTH_CONFIG.methods,
+        passkey: { enabled: true, allowLogin: true, allowUserCreation: false },
+      },
+    }
+    postCalls.length = 0
+    passkeyCalls.length = 0
+    routerState.search = {}
+    ;(globalThis as Record<string, unknown>)['IS_REACT_ACT_ENVIRONMENT'] = true
+    const queryClient = new QueryClient()
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+    let captured: ReturnType<typeof useSignIn> | null = null
+    function Host(): ReactNode {
+      captured = useSignIn()
+      return null
+    }
+    const root = createRoot(container)
+
+    try {
+      await act(async () => {
+        root.render(
+          <QueryClientProvider client={queryClient}>
+            <Host />
+          </QueryClientProvider>,
+        )
+      })
+      await act(async () => {
+        await vi.waitFor(() => expect(captured?.[0].authConfig.turnstileSiteKey).toBe('site-key'))
+      })
+
+      expect(captured?.[0].turnstileReady).toBe(false)
+      expect(passkeyCalls.at(-1)?.enabled).toBe(false)
+
+      await act(async () => {
+        captured?.[1].submitMagicLink()
+        captured?.[1].submitPassword()
+        captured?.[1].submitOtpRequest()
+        captured?.[1].submitEnterpriseSso()
+        captured?.[1].triggerPasskeyButton()
+      })
+      expect(postCalls).toEqual([])
+
+      await act(async () => {
+        captured?.[1].setTurnstileToken('turnstile-token-1')
+      })
+      expect(captured?.[0].turnstileReady).toBe(true)
+      expect(passkeyCalls.at(-1)?.enabled).toBe(true)
+
+      await act(async () => {
+        captured?.[1].submitMagicLink()
+      })
+      expect(postCalls.at(-1)).toMatchObject({
+        path: '/auth/magic-link/send',
+        body: { turnstileToken: 'turnstile-token-1' },
+      })
+    } finally {
+      await act(async () => root.unmount())
+      container.remove()
+      authConfigState.config = null
+    }
+  })
+})
diff --git a/apps/server/src/routes/sign-in/useSignIn.ts b/apps/server/src/routes/sign-in/useSignIn.ts
index 1ca01a94..a1ea0067 100644
--- a/apps/server/src/routes/sign-in/useSignIn.ts
+++ b/apps/server/src/routes/sign-in/useSignIn.ts
@@ -106,6 +106,7 @@ export type SignInState = {
   error: SignInErrorKey | null
   otpStep: 'input' | 'sent'
   turnstileToken: string | null
+  turnstileReady: boolean
   // config 未返回且 URL 不排除 guest 时为 true,页面固定高度占位防 CLS。
   guestEntryPending: boolean
   tenantSelection: {
@@ -177,6 +178,8 @@ export function useSignIn(): [SignInState, SignInActions] {
 
   const authConfigQuery = useQuery(authConfigQueryOptions(search, api))
   const authConfig = authConfigQuery.data ?? DEFAULT_PUBLIC_AUTH_CONFIG
+  const turnstileReady =
+    !authConfigQuery.isPending && (authConfig.turnstileSiteKey === null || Boolean(turnstileToken))
   const enabledMethods = useMemo<readonly SignInMethod[]>(() => {
     return enabledSignInMethodsForIntent(
       authConfig,
@@ -244,7 +247,7 @@ export function useSignIn(): [SignInState, SignInActions] {
 
   const passkey = usePasskeySignIn({
     api,
-    enabled: enabledMethods.includes('passkey'),
+    enabled: enabledMethods.includes('passkey') && turnstileReady,
     identifier,
     organizationId: selectedOrganizationId,
     applicationClientId: search.client_id,
@@ -430,6 +433,7 @@ export function useSignIn(): [SignInState, SignInActions] {
 
   const handleSocial = useCallback(
     (provider: string): void => {
+      if (!turnstileReady) return
       trackEvent('social_login_start', { provider })
       setPendingAuthCompletion({ method: 'social', intent: analyticsAuthIntent })
       const url = buildSocialAuthorizeUrl({
@@ -458,6 +462,7 @@ export function useSignIn(): [SignInState, SignInActions] {
       search.client_id,
       search.invitation_token,
       turnstileToken,
+      turnstileReady,
     ],
   )
 
@@ -525,6 +530,7 @@ export function useSignIn(): [SignInState, SignInActions] {
     error: passkey.error ?? error,
     otpStep,
     turnstileToken,
+    turnstileReady,
     // org/client/invitation/authz 任一存在则无 guest 入口;租户维度须等 config。
     guestEntryPending:
       authConfigQuery.isPending &&
@@ -549,15 +555,27 @@ export function useSignIn(): [SignInState, SignInActions] {
     setRememberMe,
     setOtpCode: (value) => setOtpCode(value.replace(/\D/g, '')),
     setTurnstileToken,
-    submitPassword: () => passwordMutation.mutate(),
-    submitMagicLink: () => magicLinkMutation.mutate(),
-    submitOtpRequest: () => otpRequestMutation.mutate(),
+    submitPassword: () => {
+      if (turnstileReady) passwordMutation.mutate()
+    },
+    submitMagicLink: () => {
+      if (turnstileReady) magicLinkMutation.mutate()
+    },
+    submitOtpRequest: () => {
+      if (turnstileReady) otpRequestMutation.mutate()
+    },
     submitOtpVerify: () => otpVerifyMutation.mutate(),
-    submitEnterpriseSso: () => enterpriseSsoMutation.mutate(),
+    submitEnterpriseSso: () => {
+      if (turnstileReady) enterpriseSsoMutation.mutate()
+    },
     submitGuest: () => {
-      if (authConfig.guest) guestMutation.mutate(authConfig.guest.capabilityToken)
+      if (authConfig.guest && turnstileReady) {
+        guestMutation.mutate(authConfig.guest.capabilityToken)
+      }
+    },
+    triggerPasskeyButton: () => {
+      if (turnstileReady) passkey.triggerButton()
     },
-    triggerPasskeyButton: passkey.triggerButton,
     handleSocial,
     selectOrganizationContext,
   }
diff --git a/docs/design/01-authentication.md b/docs/design/01-authentication.md
index 82d86c30..6f95c0e0 100644
--- a/docs/design/01-authentication.md
+++ b/docs/design/01-authentication.md
@@ -611,6 +611,8 @@ and validity window.
 ### Bot protection intervention points
 
 - Sign-in page load: Turnstile explicit widget with `interaction-only` appearance
+- Protected sign-in controls remain disabled until auth configuration resolves and, when Turnstile
+  is configured, the widget yields a single-use token; the widget is mounted before those controls
 - Sign-up: Turnstile plus optional email verification
 - Password reset requests: Turnstile to prevent flooding
 - OTP send endpoint: its own rate limit
diff --git a/docs/zh-Hans/design/01-authentication.md b/docs/zh-Hans/design/01-authentication.md
index b1d20276..c10e7111 100644
--- a/docs/zh-Hans/design/01-authentication.md
+++ b/docs/zh-Hans/design/01-authentication.md
@@ -1,4 +1,4 @@
-<!-- xid-translation source=docs/design/01-authentication.md source-commit=working-tree source-blob=82d86c30cd528fd3306de13caaae8a7debcefb92 -->
+<!-- xid-translation source=docs/design/01-authentication.md source-commit=working-tree source-blob=6f95c0e0ce4dc2b39fc84c505698edab2111b744 -->
 
 > Translation of `docs/design/01-authentication.md` at commit `5d55b0c`. The English version is authoritative.
 > 本文是 [`docs/design/01-authentication.md`](../../design/01-authentication.md) 的中文翻译,英文版为准。两版不一致时以英文版为准。
@@ -415,6 +415,8 @@ UTF-8 解码后 `JSON.parse`,按以下顺序校验,任一失败即拒绝并返
 ### Bot 防护介入点
 
 - 登录页加载:Turnstile 显式 widget,使用 `interaction-only` appearance
+- 认证配置返回前,受保护的登录操作保持禁用;配置 Turnstile 时,widget 签发单次 token 后才可操作,
+  且 widget 挂载在这些操作之前
 - 注册:Turnstile + 可选 email 验证
 - 密码重置请求:Turnstile 防刷
 - OTP 发送接口:独立速率限制