> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 垃圾資訊防護

通過環境變數切換的 Turnstile 校驗，覆蓋公開表單與認證端點。

## 初學者演練

先決條件：閱讀下面的兩個初學者指南，完成 Web 本地設定，並在編輯器的根目錄中開啟此 monorepo。網頁設定屬於`apps/web/.env.local`； Next.js不讀取根`.env`。預設fake模式下的`/dashboard`是無資料庫演示； `/auth` 需要遷移資料庫。

簡而言之：工作區是一個團隊的單獨使用者、資料和設定。伺服器是可信後端；讓提供商金鑰遠離瀏覽器和電話程式碼。遷移是建立或更新表的版本化資料庫更改。人工智慧模型是回答的引擎；型號目錄是伺服器上可用型號 ID 和價格的列表。提供商是一種外部服務，例如人工智慧、電子郵件或計費服務。權利是允許工作區使用某項功能的授權。 Webhook 是一個服務傳送到另一個服務的 URL 的訊息。

1. 為確切的本地/部署主機名建立 Turnstile 測試小部件。在`apps/web/.env.local`中，設定`CAPTCHA_PROVIDER=turnstile`和`NEXT_PUBLIC_TURNSTILE_SITE_KEY`；僅將 `TURNSTILE_SECRET_KEY` 放入伺服器秘密儲存中。

2. 重新啟動並提交測試聯絡表。

3. 期待挑戰和成功的有效令牌響應。如果每個請求都失敗，則比較主機名和金鑰對；永遠不要洩露秘密金鑰。

對於自定義程式碼，請從提供的 `prompts/README.md` 開始，然後複製最接近的提示：對於應用程式螢幕為 `prompts/new-app-screen.md`，對於公共頁面為 `prompts/new-landing-page.md`。對於伺服器、資料庫或提供商工作，請為您的編碼代理提供本指南的任務，並要求其讀取 `AGENTS.md`、`.ai/PROJECT_CONTEXT.md` 和匹配的 `.ai/` 映象；檢查此處指定的確切原始檔；列出檔案並在編輯前進行檢查；保留工作區所有權和僅限伺服器的機密；並向您展示差異。告訴它您想要的行為、輸入和輸出欄位、允許的角色、預期的成功和錯誤以及測試帳戶、提供程式或裝置。使用樣本值；永遠不要貼上真正的秘密。

[開始之前](https://supastack.dev/zh-tw/docs/web/before-you-start.md)

[終端基礎知識](https://supastack.dev/zh-tw/docs/web/terminal-basics.md)

[網路本地設定](https://supastack.dev/zh-tw/docs/web/ship-in-5-minutes.md)

[座席提示和專案記憶體](https://supastack.dev/zh-tw/docs/web/agents.md)


## 啟用兩個鍵

`CAPTCHA_PROVIDER=off` 是預設值。選擇 `turnstile`，在 Turnstile 應用程式中配置匹配的主機名並提供兩個金鑰。 `NEXT_PUBLIC_TURNSTILE_SITE_KEY` 為公開； `TURNSTILE_SECRET_KEY`僅供伺服器驗證者使用。

```
CAPTCHA_PROVIDER=turnstile
NEXT_PUBLIC_TURNSTILE_SITE_KEY=your-site-key
# TURNSTILE_SECRET_KEY belongs in the server secret store.
```


## 保護受保護的表面

該門涵蓋聯絡/新聞通訊表格以及 Better Auth 登入、註冊、OTP 和密碼重置憑證端點。它補充了驗證/速率限制；它不能替代會話或工作區授權。


## 驗證拒絕和恢復

測試有效令牌、丟失/過期/無效令牌、驗證器失敗以及客戶端小部件重置後的重試。保留可操作的人工檢查副本和鍵盤訪問；在切換提供商之前檢查所選身份驗證引擎的覆蓋範圍。

[受保護的形式](https://supastack.dev/zh-tw/docs/web/project-structure.md)

[驗證引擎差異](https://supastack.dev/zh-tw/docs/web/project-structure.md)


## 安裝與配置

CAPTCHA_PROVIDER 選擇驗證器：off（預設，本地開發無需憑據）或 turnstile。啟用 turnstile 需要服務端配置 TURNSTILE_SECRET_KEY，客戶端元件使用 NEXT_PUBLIC_TURNSTILE_SITE_KEY——任一缺失時 config schema 會讓啟動直接失敗。

apps/web/src/captcha.ts 組合出一個程式級共享驗證器，將 token 以十秒超時傳送到 Cloudflare 的 siteverify 端點，並採用失敗即拒絕策略——無法驗證的 token 永遠不算人類證明。

```
CAPTCHA_PROVIDER=turnstile
TURNSTILE_SECRET_KEY=…           # server-only
NEXT_PUBLIC_TURNSTILE_SITE_KEY=…

Guarded: sign-in/up, OTP send, reset,
contact + newsletter forms
```


## 實現流程

CaptchaWidget（src/captcha-widget.tsx）渲染元件並把 cf-turnstile-response 欄位注入父表單，認證客戶端呼叫則通過 x-captcha-response 頭攜帶 token。聯絡與訂閱動作在寫入前完成校驗——校驗失敗會返回 status=captcha，而不會建立線索。

當 provider 開啟時，packages/auth 掛載 better-auth 的 captcha 外掛；CAPTCHA_ENDPOINTS 覆蓋憑據輸入與簽發 token 的路由——登入、註冊、OTP 傳送、密碼重置。check-verification-otp 這類消費型端點被有意排除在外：那裡 OTP 或 token 本身就是證明。


## 驗證與排障

對每個受保護表單分別提交缺失 token 與畸形 token——兩者都必須失敗即拒絕。驗證 siteverify 不可達時是拒絕而不是放行，provider=off 時本地開發保持開放，且 secret 永遠不會出現在客戶端打包產物或日誌中。


## 下一篇

[管理控制台](https://supastack.dev/zh-tw/docs/web/admin.md)