@kood/claude-code 0.3.6 → 0.3.7

package/templates/nextjs/docs/library/better-auth/index.md

@@ -0,0 +1,541 @@
+# Better Auth
+
+> TypeScript Authentication Library
+
+---
+
+<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, { provider: "postgresql" }),
+  emailAndPassword: { enabled: true },
+})
+
+// src/lib/auth-client.ts - 클라이언트
+import { createAuthClient } from "better-auth/react"
+
+export const authClient = createAuthClient({
+  baseURL: process.env.NEXT_PUBLIC_APP_URL || "http://localhost:3000",
+})
+```
+
+## Next.js Route Handler
+
+```typescript
+// app/api/auth/[...all]/route.ts
+import { auth } from "@/lib/auth"
+
+export const GET = (request: Request) => auth.handler(request)
+export const POST = (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 } })
+
+// ✅ 서버 (Server Component)
+import { auth } from "@/lib/auth"
+import { headers } from "next/headers"
+
+export default async function Page() {
+  const session = await auth.api.getSession({ headers: headers() })
+  if (!session?.user) redirect("/login")
+
+  return <div>Welcome {session.user.name}</div>
+}
+
+// ✅ 서버 (Server Action)
+"use server"
+
+import { auth } from "@/lib/auth"
+import { headers } from "next/headers"
+
+export async function getSession() {
+  const session = await auth.api.getSession({ headers: headers() })
+  return session
+}
+
+// ✅ 세션 업데이트
+await authClient.updateUser({ name: "New Name" })
+
+// ✅ 로그아웃
+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>
+
+## Next.js Integration
+
+| 패턴 | 용도 |
+|------|------|
+| Route Handler | `app/api/auth/[...all]/route.ts` |
+| Server Component | `auth.api.getSession({ headers })` |
+| Server Action | `auth.api.getSession({ headers })` |
+| Middleware | `auth.api.getSession({ headers })` + redirect |
+
+### Server Component Pattern
+
+```typescript
+// app/dashboard/page.tsx
+import { auth } from "@/lib/auth"
+import { headers } from "next/headers"
+import { redirect } from "next/navigation"
+
+export default async function DashboardPage() {
+  const session = await auth.api.getSession({ headers: headers() })
+
+  if (!session?.user) {
+    redirect("/login")
+  }
+
+  return <div>Welcome {session.user.name}</div>
+}
+```
+
+### Server Action Pattern
+
+```typescript
+// actions/auth.ts
+"use server"
+
+import { auth } from "@/lib/auth"
+import { headers } from "next/headers"
+import { redirect } from "next/navigation"
+
+export async function requireAuth() {
+  const session = await auth.api.getSession({ headers: headers() })
+
+  if (!session?.user) {
+    redirect("/login")
+  }
+
+  return session.user
+}
+
+export async function getProtectedData() {
+  const user = await requireAuth()
+  return prisma.data.findMany({ where: { userId: user.id } })
+}
+```
+
+### Middleware Pattern
+
+```typescript
+// middleware.ts
+import { auth } from "@/lib/auth"
+import { NextResponse } from "next/server"
+import type { NextRequest } from "next/server"
+
+export async function middleware(request: NextRequest) {
+  const session = await auth.api.getSession({ headers: request.headers })
+
+  if (!session?.user) {
+    return NextResponse.redirect(new URL("/login", request.url))
+  }
+
+  return NextResponse.next()
+}
+
+export const config = {
+  matcher: ["/dashboard/:path*", "/profile/:path*"],
+}
+```
+
+## Common Patterns
+
+| 작업 | 패턴 |
+|------|------|
+| 로그인 | `authClient.signIn.email({ email, password })` |
+| 회원가입 | `authClient.signUp.email({ email, password, name })` |
+| 로그아웃 | `authClient.signOut()` |
+| 세션 조회 | `authClient.getSession()` (클라이언트) |
+| 세션 조회 | `auth.api.getSession({ headers })` (서버) |
+| 사용자 업데이트 | `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>