Auth
이 앱은 genericOAuth 플러그인을 통해 공유 Grok 인증 브로커(auth.grok.me)에 연합하는 자체 Better Auth를 /api/auth/*에서 실행합니다. 이 템플릿은 Google 및 X를 연결합니다.
지원되는 로그인 방식 — 다음 세 가지 방식만 사용하십시오. 다른 방식은 지원되지 않습니다: Google, X, 이메일/비밀번호. 다른 소셜/OAuth 제공자(GitHub, Apple, Discord 등), 매직 링크, 패스키, OTP, 전화/SMS, 익명 로그인은 사용할 수 없습니다. GROK_PROVIDERS에 항목을 추가하지 마십시오. 방식 세부 정보 및 이메일/비밀번호 전환 (src/lib/auth/email-password.ts만 편집): references/sign-in-methods.md
예외 — 게이트 뷰어는 이미 로그인되어 있습니다. 이들을 위해 로그인/재인증 버튼을 절대 렌더링하지 마십시오. 커넥터/앱-데이터 앱: Google/X 버튼 없이 'Continue with Grok' 게이트만 사용: 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) 개발 사용자가 반환되어 인증이 없는 앱이 로그인된 방문자 없이 렌더링됩니다. dev 및 미리보기 전용입니다. 배포되면 이 플래그는 플랫폼의 값(항상 "true")이므로 requireUserId는 모든 방문자를 거부합니다. 인증이 꺼진 앱은 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을 절대 작성하지 마십시오: 라이브 미리보기에는 환경 변수 구성이 전혀 필요하지 않으며, 배포된 앱은 플랫폼에서 변수를 주입합니다. 존재하는 노브(knob)는 references/prewired-and-env.md에 있습니다. — 클라이언트에 VITE_가 아닌 변수를 노출하지 마십시오.
migrations/auth/0001_auth.sql은 Better Auth 스키마입니다. — 편집하지 마십시오. 이 파일은 glob 패턴의 migrations/ 디렉토리 밖에 있으므로(어느 applier도 하강하지 않음) 로그인이 없는 앱에는 적용되지 않습니다. "로그인 켜기"에서 이 파일을 복사합니다.
로그인 켜기
다음 모든 단계를 수행하십시오. 라우트만으로 비활성화 분기가 렌더링됩니다.
- 플래그:
.grok/app-env.json에서VITE_AUTH_ENABLED키를 삭제하고 dev 서버를 재시작하십시오. Vite는 시작 시 env를 읽으므로 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에서 복사하십시오(포괄적인 API 라우트는/api/auth/*와 브로커 콜백을 작동하게 합니다). - 로그아웃: 로그인이 가능하면서 로그아웃이 없는 것은 완료된 것이 아닙니다. —
@/lib/auth/gates에서<UserButton />을 렌더링하십시오(signOut()을 연결하며, 게이트 세션에 대해 로그아웃을 숨깁니다). - 기존 데이터: 앱의 서버 함수를
authMiddleware로 감싸십시오(인증이 꺼진 앱은 이 미들웨어를 사용하지 않았어야 합니다. —neon기술 참조). 로그인 이전에 존재했던 행은 개발 데이터입니다. 사용자가 달리 명시하지 않는 한 이를 삭제하고 다시 생성하십시오. 누가 먼저 로그인하는지에 관계없이 전달하지 마십시오.
켜진 후 구축하기
- 로그인/로그아웃:
@/lib/auth/client의signIn(providerId)및signOut();GROK_PROVIDERS가 버튼을 렌더링합니다. 팝업, 베어러 토큰 핸드오프 및 요청 첨부는 내부적으로 처리되므로 그대로 두십시오.<UserButton />을 선호하십시오(대기 및 실패 상태를 처리합니다). 배포 시 서버가 확인하지 않으면signOut()이 거부됩니다. 이를 catch하십시오.authClient.signOut()을 사용하지 마십시오. 미리보기 베어러 토큰이 이후의 모든 요청에 첨부되어 방문자가 로그인 상태로 유지됩니다. - 사용자 읽기:
useCurrentUser()는 표시 전용입니다(null은 로딩 중 OR 로그아웃을 의미하므로 이 값만으로 리디렉션하지 마십시오). 대신useCurrentUserState()의isPending을 기준으로 가드하십시오. 게이트(SignedIn,SignedOut,SignInGate,RedirectToSignIn,UserButton)는@/lib/auth/gates에 있습니다. CTA 하드 규칙, 스켈레톤 및 쿠키-SSR 제로 플래시:references/session-ui.md - 사용자별 데이터 (필수): 사용자별 데이터에 접근하는 모든 서버 함수는 사전 연결된
authMiddleware를 사용하고 모든 읽기 및 쓰기를context.userId로 범위를 지정해야 합니다. Postgres 드라이버는 전체 DB 액세스 권한을 가지므로 다른 것은 쿼리를 제한하지 않습니다.user_id열은TEXT로 유지하십시오. 클라이언트가 제공한 사용자 ID를 절대 신뢰하지 마십시오. 로그아웃된 상태에서 미들웨어는UnauthorizedError(401)를 throw합니다. 코드 및 비활성화 모드 의미론:references/per-user-data.md - 보안 모델: 헤드리스 브로커,
__Host-쿠키 +trustedOrigins, 그리고 Fetch-Metadata 형제 격리는 이미 연결되어 있습니다. 오류를 없애기 위해 이를 약화시키지 마십시오(references/sign-in-methods.md에서 모델과 "Invalid origin" 수정 방법을 다룹니다).