Auth
這個應用程式在 /api/auth/* 執行自己的 Better Auth,並透過 genericOAuth 外掛與共享的 Grok 身份驗證代理 (auth.grok.me) 進行聯合。此模板預先接好了 Google 與 X。
支援的登入方式 — 僅限使用這三種;不支援其他方式:Google、X 與電子郵件/密碼。 沒有其他的社交/OAuth 提供者(GitHub、Apple、Discord…),沒有魔法連結、通行金鑰、一次性密碼、電話/SMS 或匿名登入。請勿在 GROK_PROVIDERS 中新增條目。登入方式的詳細資訊以及電子郵件/密碼開關(僅編輯 src/lib/auth/email-password.ts):references/sign-in-methods.md。
例外情況 — 閘道檢視者已經登入;絕對不要為他們顯示登入/重新驗證按鈕。連接器 / 應用資料應用程式:僅限閘道「使用 Grok 繼續」,不顯示 Google/X 按鈕:references/grok-identity.md。
登入功能預設為關閉 — 模板附帶了 .grok/app-env.json,內容為 {"VITE_AUTH_ENABLED": "false"},因此只有在需求要求時才新增帳號(AGENTS.md §0.5)。啟用登入功能的方法請參考下方的「開啟登入功能」。
一旦開啟,登入功能就是真實的 — 包括在沙箱即時預覽中。 請勿建立示範/模擬/硬編碼使用者。預覽:彈出視窗 + 內建預覽客戶端;部署後:每個應用程式的客戶端 + DATABASE_URL + 零點擊閘道登入(references/prewired-and-env.md)。
當關閉時(VITE_AUTH_ENABLED=false),會回傳一個開發者使用者,以便非身份驗證應用程式在沒有已登入訪客的情況下也能渲染 — 僅限開發與預覽環境。部署後,該旗標由平台設定(永遠為 "true"),因此 requireUserId 會拒絕所有訪客 — 關閉身份驗證的應用程式不會使用它或 authMiddleware。
所有內容都已預先安裝並預先配置在 src/lib/auth/ 中 — 請勿執行 npm install;better-auth 是唯一的身份驗證套件(絕對不是 @neondatabase/*、@stackframe/* 或 @clerk/*)。請勿編輯或重寫 src/lib/auth/ 下的任何檔案 — 尤其是 server.ts — 除了 email-password.ts 中的那個旗標。每個檔案的對應關係:references/prewired-and-env.md。
/auth/popup 已由模板的 Vite 外掛處理(vite.config.ts → popup.server.ts):它永遠不會繪製 React 應用程式。請勿建立 src/routes/auth/popup.tsx(或該路徑下的任何 React 頁面 / 客戶端 OAuth)— 這會導致彈出視窗中顯示完整應用程式,這是常見的失敗模式。
永遠不要在此沙箱中編寫 .env / .env.local / .env.example:即時預覽不需要任何環境設定,而部署後的應用程式會由平台注入其變數。可用的設定選項位於 references/prewired-and-env.md — 絕對不要將非 VITE_ 的變數暴露給客戶端。
migrations/auth/0001_auth.sql 是 Better Auth 的資料庫綱要 — 請勿編輯。它位於全域的 migrations/ 目錄之外(兩個應用程式都不會套用它),因此不會應用於沒有登入功能的應用程式;「開啟登入功能」會將它複製上去。
開啟登入功能
執行以下所有步驟 — 僅路由本身會渲染停用的分支:
- 旗標: 從
.grok/app-env.json中刪除VITE_AUTH_ENABLED鍵,然後重新啟動開發伺服器。Vite 在啟動時讀取環境變數,因此 HMR 不會偵測到變更。npm run dev、npm run build與npm run preview都會透過scripts/with-app-env.mjs讀取該檔案,因此預覽與建置輸出會同時切換 — 永遠不要直接啟動 Vite。 - 資料庫綱要: 執行
cp migrations/auth/0001_auth.sql migrations/0001_auth.sql,然後重新啟動以套用它。它會根據基底名稱在_migrations中追蹤,因此已經具有此綱要的資料庫不會重新執行。 - 路由: 新增
src/routes/api/auth/$.ts+src/routes/login.tsx— 從references/wiring.md複製兩者(catch-all API 路由是讓/api/auth/*與代理回呼正常運作的關鍵)。 - 登出: 沒有登出方式的登入是不完整的 — 從
@/lib/auth/gates渲染<UserButton />(它會呼叫signOut();對閘道工作階段隱藏登出按鈕)。 - 現有資料: 將應用程式的伺服器函數包裝在
authMiddleware中(關閉身份驗證的應用程式之前不得使用它 — 請參閱neon技能)。在登入功能存在之前的資料列是開發資料:除非使用者另有指示,否則請刪除並重建它們 — 不要將它們交給第一個登入的人。
啟用後的擴充功能
- 登入 / 登出: 從
@/lib/auth/client使用signIn(providerId)與signOut();GROK_PROVIDERS會渲染按鈕。彈出視窗、承載權杖傳遞與請求附加是內部實作 — 請勿修改。建議優先使用<UserButton />(它會處理等待與失敗狀態);signOut()在部署後如果伺服器未確認,則會拒絕 — 請捕捉此情況。永遠不要使用authClient.signOut():它會將預覽承載權杖附加到後續每個請求,導致訪客保持登入狀態。 - 讀取使用者:
useCurrentUser()僅供顯示使用(null表示載入中或已登出,因此永遠不要單獨用它進行重新導向);請改用useCurrentUserState()的isPending來進行防護。閘道(SignedIn、SignedOut、SignInGate、RedirectToSignIn、UserButton)位於@/lib/auth/gates。行動呼籲的嚴格規則、骨架畫面以及 Cookie SSR 零閃爍:references/session-ui.md。 - 每個使用者的資料(強制): 每個處理每個使用者資料的伺服器函數都必須使用預先配置的
authMiddleware,並將每個讀取與寫入的範圍限定在context.userId— PostgreSQL 驅動程式具有完整的資料庫存取權限,因此沒有其他方式可以限制查詢。請將user_id欄位保持為TEXT型別;永遠不要信任用戶端提供的使用者 ID;當使用者登出時,中介軟體會拋出UnauthorizedError(401)。程式碼與停用模式的語意:references/per-user-data.md。 - 安全模型: 無頭代理、
__Host-cookies +trustedOrigins,以及 Fetch-Metadata 兄弟隔離都已預先配置 — 永遠不要為了消除錯誤而弱化它們(references/sign-in-methods.md涵蓋了模型與「無效來源」的修復方式)。