@kood/claude-code 0.2.5 → 0.3.0

package/templates/tanstack-start/docs/library/better-auth/index.md

@@ -2,33 +2,486 @@
 
 > TypeScript Authentication Library
 
-@setup.md
-@session.md
-@plugins.md
-@2fa.md
-@advanced.md
+---
 
-## Quick Reference
+<quick_start>
+
+## Installation
+
+```bash
+npm install better-auth
+```
+
+## Minimal Setup
 
 ```typescript
-// 서버
+// src/lib/auth.ts - 서버
 import { betterAuth } from 'better-auth'
 import { prismaAdapter } from 'better-auth/adapters/prisma'
+import { prisma } from '@/database/prisma'
 
 export const auth = betterAuth({
-  database: prismaAdapter(prisma),
+  database: prismaAdapter(prisma, { provider: 'postgresql' }),
   emailAndPassword: { enabled: true },
 })
 
-// 클라이언트
+// src/lib/auth-client.ts - 클라이언트
 import { createAuthClient } from 'better-auth/react'
-export const authClient = createAuthClient({})
 
-// 로그인/가입
-await authClient.signIn.email({ email, password })
-await authClient.signUp.email({ email, password, name })
+export const authClient = createAuthClient({
+  baseURL: 'http://localhost:3000',
+})
+```
+
+## TanStack Start Handler
+
+```typescript
+// src/routes/api/auth/$.ts
+import { auth } from '@/lib/auth'
+
+export const GET = async ({ request }: { request: Request }) => auth.handler(request)
+export const POST = async ({ request }: { request: Request }) => auth.handler(request)
+```
+
+</quick_start>
+
+---
+
+<setup>
+
+## Database Adapters
+
+| Adapter | Import | Provider |
+|---------|--------|----------|
+| Prisma | `better-auth/adapters/prisma` | `postgresql`, `mysql`, `sqlite` |
+| Drizzle | `better-auth/adapters/drizzle` | `pg`, `mysql2`, `better-sqlite3` |
+| Kysely | `better-auth/adapters/kysely` | dialect 기반 |
+
+## Auth Config
+
+| 옵션 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `database` | `Adapter` | 필수 | DB 어댑터 |
+| `baseURL` | `string` | `http://localhost:3000` | 앱 URL |
+| `basePath` | `string` | `/api/auth` | Auth 경로 |
+| `secret` | `string` | 환경변수 | JWT 시크릿 |
+| `trustedOrigins` | `string[]` | `[]` | CORS 허용 오리진 |
+
+## Social Providers
+
+```typescript
+export const auth = betterAuth({
+  database: prismaAdapter(prisma),
+  socialProviders: {
+    google: {
+      clientId: process.env.GOOGLE_CLIENT_ID!,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+    },
+    github: {
+      clientId: process.env.GITHUB_CLIENT_ID!,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+    },
+  },
+})
+```
+
+## Email & Password
+
+```typescript
+export const auth = betterAuth({
+  emailAndPassword: {
+    enabled: true,
+    requireEmailVerification: false,
+    sendResetPassword: async ({ user, url }) => {
+      await sendEmail({ to: user.email, subject: 'Reset Password', html: `<a href="${url}">Reset</a>` })
+    },
+  },
+})
+```
+
+</setup>
+
+---
+
+<session>
+
+## Session Config
+
+| 옵션 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `expiresIn` | `number` | `604800` (7일) | 세션 만료 시간 (초) |
+| `updateAge` | `number` | `86400` (1일) | 세션 갱신 주기 (초) |
+| `cookieCache.enabled` | `boolean` | `true` | 쿠키 캐시 활성화 |
+| `cookieCache.maxAge` | `number` | `300` (5분) | 캐시 유효 시간 (초) |
+| `cookieCache.strategy` | `'compact' \| 'jwt' \| 'jwe'` | `'compact'` | 캐시 전략 |
+
+```typescript
+export const auth = betterAuth({
+  session: {
+    expiresIn: 604800, // 7일
+    updateAge: 86400,  // 1일마다 갱신
+    cookieCache: {
+      enabled: true,
+      maxAge: 300,     // 5분
+      strategy: 'compact',
+    },
+  },
+})
+```
+
+## Session Methods
+
+```typescript
+// ✅ 클라이언트
+const session = await authClient.getSession()
+const session = await authClient.getSession({ query: { disableCookieCache: true } })
+
+// ✅ 서버 (TanStack Start)
+export const getSession = createServerFn({ method: 'GET' })
+  .handler(async ({ request }) => {
+    const session = await auth.api.getSession({ headers: request.headers })
+    return session
+  })
+
+// ✅ 세션 업데이트
+await authClient.updateUser({ name: 'New Name' })
 
-// 세션
-const session = await authClient.getSession()  // 클라이언트
-const session = await auth.api.getSession({ headers })  // 서버
+// ✅ 로그아웃
+await authClient.signOut()
 ```
+
+## Custom Session Fields
+
+```typescript
+import { customSession } from 'better-auth/plugins'
+
+export const auth = betterAuth({
+  plugins: [
+    customSession({
+      schema: {
+        session: {
+          fields: {
+            ipAddress: { type: 'string' },
+            userAgent: { type: 'string' },
+            metadata: { type: 'json' },
+          },
+        },
+      },
+      async onSessionCreate(session, context) {
+        return {
+          ...session,
+          ipAddress: context.request.headers.get('x-forwarded-for') || 'unknown',
+          userAgent: context.request.headers.get('user-agent') || 'unknown',
+        }
+      },
+    }),
+  ],
+})
+```
+
+</session>
+
+---
+
+<auth_methods>
+
+## Email/Password
+
+```typescript
+// ✅ 회원가입
+await authClient.signUp.email({
+  email: 'user@example.com',
+  password: 'password123',
+  name: 'User Name',
+})
+
+// ✅ 로그인
+await authClient.signIn.email({
+  email: 'user@example.com',
+  password: 'password123',
+})
+
+// ✅ 비밀번호 재설정 요청
+await authClient.forgetPassword({ email: 'user@example.com' })
+
+// ✅ 비밀번호 재설정
+await authClient.resetPassword({ token, password: 'newpassword' })
+```
+
+## Social Login
+
+```typescript
+// ✅ 소셜 로그인
+await authClient.signIn.social({ provider: 'google', callbackURL: '/dashboard' })
+await authClient.signIn.social({ provider: 'github', callbackURL: '/dashboard' })
+
+// ✅ SSO
+await authClient.signIn.sso({ providerId: 'provider-id', callbackURL: '/dashboard' })
+```
+
+## Two-Factor Authentication
+
+### Server Setup
+
+```typescript
+import { twoFactor } from 'better-auth/plugins'
+
+export const auth = betterAuth({
+  plugins: [
+    twoFactor({
+      issuer: 'My App',
+      otpOptions: {
+        async sendOTP({ user, otp }) {
+          await sendEmail({
+            to: user.email,
+            subject: 'Your OTP Code',
+            html: `Your code: ${otp}`,
+          })
+        },
+        period: 300,  // 5분
+        length: 6,    // 6자리
+      },
+      backupCodeLength: 10,
+      backupCodeCount: 10,
+    }),
+  ],
+})
+```
+
+### Client Setup
+
+```typescript
+import { twoFactorClient } from 'better-auth/client/plugins'
+
+export const authClient = createAuthClient({
+  plugins: [
+    twoFactorClient({
+      twoFactorPage: '/two-factor',
+    }),
+  ],
+})
+```
+
+### 2FA Usage
+
+```typescript
+// ✅ TOTP 활성화
+const { data } = await authClient.twoFactor.enable({ password: 'current-password' })
+// data: { totpURI: 'otpauth://...', backupCodes: ['ABCD-1234', ...] }
+
+// ✅ TOTP 검증
+await authClient.twoFactor.verifyTotp({ code: '123456' })
+
+// ✅ OTP 전송
+await authClient.twoFactor.sendOtp()
+
+// ✅ OTP 검증
+await authClient.twoFactor.verifyOtp({ code: '123456' })
+
+// ✅ 백업 코드 사용
+await authClient.twoFactor.useBackupCode({ code: 'ABCD-1234' })
+
+// ✅ 백업 코드 재생성
+const { data } = await authClient.twoFactor.regenerateBackupCodes({ password: 'current-password' })
+
+// ✅ 2FA 비활성화
+await authClient.twoFactor.disable({ password: 'current-password' })
+```
+
+</auth_methods>
+
+---
+
+<plugins>
+
+## Plugin System
+
+| Plugin | Import | 기능 |
+|--------|--------|------|
+| `multiSession` | `better-auth/plugins` | 다중 세션 관리 |
+| `customSession` | `better-auth/plugins` | 세션 필드 확장 |
+| `twoFactor` | `better-auth/plugins` | 2단계 인증 |
+| `captcha` | `better-auth/plugins` | CAPTCHA 검증 |
+
+## Multi-Session
+
+```typescript
+// ✅ 서버
+import { multiSession } from 'better-auth/plugins'
+
+export const auth = betterAuth({
+  plugins: [
+    multiSession({
+      maximumSessions: 5, // 최대 세션 수
+    }),
+  ],
+})
+
+// ✅ 클라이언트
+import { multiSessionClient } from 'better-auth/client/plugins'
+
+export const authClient = createAuthClient({
+  plugins: [multiSessionClient()],
+})
+
+// 사용
+const sessions = await authClient.multiSession.listSessions()
+await authClient.multiSession.revokeSession({ sessionId: 'session-id' })
+await authClient.multiSession.revokeOtherSessions()
+```
+
+## CAPTCHA
+
+```typescript
+// ✅ 서버
+import { captcha } from 'better-auth/plugins'
+
+export const auth = betterAuth({
+  plugins: [
+    captcha({
+      provider: 'recaptcha',
+      siteKey: process.env.RECAPTCHA_SITE_KEY!,
+      secretKey: process.env.RECAPTCHA_SECRET_KEY!,
+      protectEndpoints: ['/sign-up/email', '/sign-in/email'],
+    }),
+  ],
+})
+
+// ✅ 클라이언트
+import { captchaClient } from 'better-auth/client/plugins'
+
+export const authClient = createAuthClient({
+  plugins: [
+    captchaClient({
+      siteKey: process.env.NEXT_PUBLIC_RECAPTCHA_SITE_KEY!,
+    }),
+  ],
+})
+```
+
+</plugins>
+
+---
+
+<advanced>
+
+## SIWE (Ethereum)
+
+```typescript
+// 서버: siwe({ domain, uri })
+// 클라이언트:
+const { data } = await authClient.siwe.getNonce()
+const message = await authClient.siwe.prepareMessage({ address: '0x...', nonce: data.nonce })
+const signature = await signer.signMessage(message)
+await authClient.siwe.signIn({ message, signature })
+```
+
+## Stateless Mode
+
+```typescript
+// ✅ DB 없이 소셜 로그인만
+export const auth = betterAuth({
+  socialProviders: {
+    google: {
+      clientId: process.env.GOOGLE_CLIENT_ID!,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+    },
+  },
+})
+```
+
+## Redis Secondary Storage
+
+```typescript
+import { Redis } from 'ioredis'
+
+const redis = new Redis()
+
+export const auth = betterAuth({
+  database: prismaAdapter(prisma),
+  secondaryStorage: {
+    get: async (key: string) => {
+      const value = await redis.get(key)
+      return value ? JSON.parse(value) : null
+    },
+    set: async (key: string, value: any, ttl: number) => {
+      await redis.set(key, JSON.stringify(value), 'EX', ttl)
+    },
+    delete: async (key: string) => {
+      await redis.del(key)
+    },
+  },
+})
+```
+
+</advanced>
+
+---
+
+<patterns>
+
+## TanStack Start Integration
+
+| 패턴 | 용도 |
+|------|------|
+| API Handler | `src/routes/api/auth/$.ts` |
+| Server Function | `createServerFn` + `auth.api.getSession` |
+| Middleware | `auth.api.getSession` + redirect |
+
+### Server Function Pattern
+
+```typescript
+// ✅ 인증 체크 Server Function
+export const requireAuth = createServerFn({ method: 'GET' })
+  .handler(async ({ request }) => {
+    const session = await auth.api.getSession({ headers: request.headers })
+    if (!session?.user) {
+      throw redirect({ to: '/login' })
+    }
+    return session.user
+  })
+
+// ✅ 보호된 데이터 조회
+export const getProtectedData = createServerFn({ method: 'GET' })
+  .handler(async ({ request }) => {
+    const user = await requireAuth()
+    return prisma.data.findMany({ where: { userId: user.id } })
+  })
+```
+
+### Route Protection
+
+```typescript
+// ✅ Route Loader
+export const Route = createFileRoute('/dashboard')({
+  component: Dashboard,
+  async loader() {
+    const user = await requireAuth()
+    const data = await getProtectedData()
+    return { user, data }
+  },
+})
+```
+
+## Common Patterns
+
+| 작업 | 패턴 |
+|------|------|
+| 로그인 | `authClient.signIn.email({ email, password })` |
+| 회원가입 | `authClient.signUp.email({ email, password, name })` |
+| 로그아웃 | `authClient.signOut()` |
+| 세션 조회 | `authClient.getSession()` |
+| 사용자 업데이트 | `authClient.updateUser({ name })` |
+| 비밀번호 재설정 | `authClient.forgetPassword({ email })` → `authClient.resetPassword({ token, password })` |
+
+## Do's & Don'ts
+
+| ✅ Do | ❌ Don't |
+|-------|----------|
+| `auth.api.getSession()` 서버에서 사용 | 클라이언트에서 직접 세션 조작 |
+| `authClient` 클라이언트에서 사용 | 하드코딩된 시크릿 |
+| 환경변수로 시크릿 관리 | 세션 토큰 로컬스토리지 저장 |
+| HTTPS 프로덕션 필수 | HTTP 프로덕션 배포 |
+| `baseURL` 환경별 설정 | 절대 경로 하드코딩 |
+
+</patterns>