@kood/claude-code 0.1.0

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

@@ -0,0 +1,136 @@
+# Better Auth - 2단계 인증 (2FA)
+
+> **상위 문서**: [Better Auth](./index.md)
+
+## 서버 설정
+
+```typescript
+import { betterAuth } from 'better-auth'
+import { twoFactor } from 'better-auth/plugins'
+
+export const auth = betterAuth({
+  plugins: [
+    twoFactor({
+      issuer: 'My Application',
+      otpOptions: {
+        async sendOTP({ user, otp }) {
+          await sendEmail({
+            to: user.email,
+            subject: 'Your verification code',
+            html: `Your code is: ${otp}`,
+          })
+        },
+        period: 300, // 5분
+        length: 6,
+      },
+      backupCodeLength: 10,
+      backupCodeCount: 10,
+    }),
+  ],
+})
+```
+
+## 클라이언트 설정
+
+```typescript
+import { twoFactorClient } from 'better-auth/client/plugins'
+
+const authClient = createAuthClient({
+  plugins: [
+    twoFactorClient({
+      twoFactorPage: '/two-factor',
+    }),
+  ],
+})
+```
+
+## 2FA 활성화
+
+```typescript
+// 2FA 활성화
+const { data } = await authClient.twoFactor.enable({
+  password: 'userPassword123',
+})
+console.log('TOTP URI:', data.totpURI)
+console.log('Backup codes:', data.backupCodes)
+```
+
+## TOTP 코드 검증
+
+```typescript
+// TOTP 코드 검증
+await authClient.twoFactor.verifyTotp({
+  code: '123456',
+})
+```
+
+## OTP 전송 및 검증
+
+```typescript
+// OTP 전송
+await authClient.twoFactor.sendOtp()
+
+// OTP 검증
+await authClient.twoFactor.verifyOtp({
+  code: '123456',
+})
+```
+
+## 백업 코드
+
+```typescript
+// 백업 코드 사용
+await authClient.twoFactor.useBackupCode({
+  code: 'ABCD-1234-EFGH',
+})
+
+// 백업 코드 재생성
+const { data: newCodes } = await authClient.twoFactor.regenerateBackupCodes({
+  password: 'userPassword123',
+})
+```
+
+## 2FA 비활성화
+
+```typescript
+await authClient.twoFactor.disable({
+  password: 'userPassword123',
+})
+```
+
+## 2FA 페이지 구현
+
+```tsx
+// pages/two-factor.tsx
+import { useState } from 'react'
+import { authClient } from '~/lib/auth-client'
+
+export default function TwoFactorPage() {
+  const [code, setCode] = useState('')
+  const [error, setError] = useState('')
+
+  const handleVerify = async () => {
+    try {
+      await authClient.twoFactor.verifyTotp({ code })
+      // 성공 시 대시보드로 이동
+      window.location.href = '/dashboard'
+    } catch (e) {
+      setError('Invalid code')
+    }
+  }
+
+  return (
+    <div>
+      <h1>2단계 인증</h1>
+      <input
+        type="text"
+        value={code}
+        onChange={(e) => setCode(e.target.value)}
+        placeholder="6자리 코드 입력"
+      />
+      <button onClick={handleVerify}>확인</button>
+      {error && <p style={{ color: 'red' }}>{error}</p>}
+    </div>
+  )
+}
+```

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

@@ -0,0 +1,138 @@
+# Better Auth - 고급 기능
+
+> **상위 문서**: [Better Auth](./index.md)
+
+## CAPTCHA 보호
+
+```typescript
+import { betterAuth } from 'better-auth'
+import { captcha } from 'better-auth/plugins'
+
+export const auth = betterAuth({
+  plugins: [
+    captcha({
+      provider: 'recaptcha', // 'recaptcha' | 'hcaptcha'
+      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'
+
+const authClient = createAuthClient({
+  plugins: [
+    captchaClient({
+      siteKey: process.env.NEXT_PUBLIC_RECAPTCHA_SITE_KEY!,
+    }),
+  ],
+})
+
+// CAPTCHA는 보호된 요청에 자동 포함됨
+await authClient.signUp.email({
+  email: 'user@example.com',
+  password: 'SecurePassword123!',
+})
+```
+
+## SSO (Single Sign-On)
+
+```typescript
+// Provider ID로 SSO 로그인
+const res = await authClient.signIn.sso({
+  providerId: 'example-provider-id',
+  callbackURL: '/dashboard',
+})
+```
+
+## SIWE (Sign-In with Ethereum)
+
+### 서버 설정
+
+```typescript
+import { betterAuth } from 'better-auth'
+import { siwe } from 'better-auth/plugins'
+
+export const auth = betterAuth({
+  plugins: [
+    siwe({
+      domain: 'example.com',
+      uri: 'https://example.com',
+      statement: 'Sign in with your Ethereum account',
+    }),
+  ],
+})
+```
+
+### 클라이언트 사용
+
+```typescript
+import { siweClient } from 'better-auth/client/plugins'
+import { ethers } from 'ethers'
+
+const authClient = createAuthClient({
+  plugins: [siweClient()],
+})
+
+// Nonce 가져오기
+const { data: nonce } = await authClient.siwe.getNonce()
+
+// 메시지 생성 및 서명
+const provider = new ethers.BrowserProvider(window.ethereum)
+const signer = await provider.getSigner()
+const address = await signer.getAddress()
+
+const message = await authClient.siwe.prepareMessage({
+  address,
+  nonce: nonce.nonce,
+})
+
+const signature = await signer.signMessage(message)
+
+// 검증 및 로그인
+await authClient.siwe.signIn({
+  message,
+  signature,
+})
+```
+
+## Stateless 모드
+
+데이터베이스 없이 사용:
+
+```typescript
+import { betterAuth } from 'better-auth'
+
+export const auth = betterAuth({
+  // 데이터베이스 설정 없음 - 자동으로 stateless 모드
+  socialProviders: {
+    google: {
+      clientId: process.env.GOOGLE_CLIENT_ID,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+    },
+  },
+})
+```
+
+### Redis와 함께 하이브리드 모드
+
+```typescript
+import { betterAuth } from 'better-auth'
+import { redis } from './redis'
+
+export const auth = betterAuth({
+  secondaryStorage: {
+    get: async (key) => await redis.get(key),
+    set: async (key, value, ttl) => await redis.set(key, value, 'EX', ttl),
+    delete: async (key) => await redis.del(key),
+  },
+  session: {
+    cookieCache: {
+      maxAge: 5 * 60, // 5분
+      refreshCache: false,
+    },
+  },
+})
+```

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

@@ -0,0 +1,83 @@
+# Better Auth
+
+> **Version**: Latest
+> **Framework**: TypeScript Authentication Library
+> **Source**: [Better Auth Documentation](https://www.better-auth.com)
+
+Better Auth는 TypeScript를 위한 프레임워크 독립적인 인증 및 권한 부여 라이브러리입니다.
+
+## 문서 구조
+
+- [설치 및 설정](./setup.md) - 서버/클라이언트 설정, 소셜 로그인
+- [세션 관리](./session.md) - 세션 설정, 쿠키 캐시
+- [플러그인](./plugins.md) - Multi-Session, Custom Session
+- [2단계 인증](./2fa.md) - TOTP, OTP, 백업 코드
+- [고급 기능](./advanced.md) - CAPTCHA, SSO, SIWE, Stateless 모드
+
+## 빠른 시작
+
+```bash
+yarn add better-auth
+```
+
+### 기본 서버 설정
+
+```typescript
+// lib/auth.ts
+import { betterAuth } from 'better-auth'
+import { prismaAdapter } from 'better-auth/adapters/prisma'
+import { prisma } from './prisma'
+
+export const auth = betterAuth({
+  database: prismaAdapter(prisma),
+  emailAndPassword: {
+    enabled: true,
+    requireEmailVerification: false,
+  },
+})
+```
+
+### 기본 클라이언트 설정
+
+```typescript
+// lib/auth-client.ts
+import { createAuthClient } from 'better-auth/react'
+
+export const authClient = createAuthClient({
+  // 옵션
+})
+```
+
+## 핵심 개념
+
+### 이메일/비밀번호 인증
+```typescript
+// 로그인
+await authClient.signIn.email({
+  email: 'user@example.com',
+  password: 'password123',
+})
+
+// 회원가입
+await authClient.signUp.email({
+  email: 'user@example.com',
+  password: 'password123',
+  name: 'John Doe',
+})
+```
+
+### 세션 조회
+```typescript
+// 클라이언트
+const session = await authClient.getSession()
+
+// 서버
+const session = await auth.api.getSession({
+  headers: request.headers,
+})
+```
+
+## 참고 자료
+
+- [Better Auth 공식 문서](https://www.better-auth.com)
+- [Better Auth GitHub](https://github.com/better-auth/better-auth)

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

@@ -0,0 +1,111 @@
+# Better Auth - 플러그인
+
+> **상위 문서**: [Better Auth](./index.md)
+
+## Multi-Session Plugin
+
+여러 계정으로 동시 로그인을 지원합니다.
+
+### 서버 설정
+
+```typescript
+import { betterAuth } from 'better-auth'
+import { multiSession } from 'better-auth/plugins'
+
+export const auth = betterAuth({
+  plugins: [
+    multiSession({
+      maximumSessions: 5, // 최대 동시 세션 수
+    }),
+  ],
+})
+```
+
+### 클라이언트 사용
+
+```typescript
+import { createAuthClient } from 'better-auth/client'
+import { multiSessionClient } from 'better-auth/client/plugins'
+
+export const authClient = createAuthClient({
+  plugins: [multiSessionClient()],
+})
+
+// 활성 세션 목록 조회
+const { data: sessions } = await authClient.multiSession.listSessions()
+
+sessions?.forEach((session) => {
+  console.log(`Device: ${session.userAgent}, Last active: ${session.updatedAt}`)
+})
+
+// 특정 세션 취소
+await authClient.multiSession.revokeSession({
+  sessionId: 'session_456',
+})
+
+// 다른 모든 세션 취소
+await authClient.multiSession.revokeOtherSessions()
+```
+
+## Polar Checkout Plugin
+
+결제 통합을 위한 플러그인입니다.
+
+```typescript
+import { polar, checkout } from '@polar-sh/better-auth'
+
+const auth = betterAuth({
+  plugins: [
+    polar({
+      use: [
+        checkout({
+          products: [{ productId: '123-456-789', slug: 'pro' }],
+          successUrl: '/success?checkout_id={CHECKOUT_ID}',
+          authenticatedUsersOnly: true,
+        }),
+      ],
+    }),
+  ],
+})
+
+// 클라이언트
+import { polarClient } from '@polar-sh/better-auth'
+
+export const authClient = createAuthClient({
+  plugins: [polarClient()],
+})
+```
+
+## 플러그인 조합
+
+```typescript
+import { betterAuth } from 'better-auth'
+import {
+  multiSession,
+  customSession,
+  twoFactor,
+  captcha
+} from 'better-auth/plugins'
+
+export const auth = betterAuth({
+  database: prismaAdapter(prisma),
+  plugins: [
+    multiSession({ maximumSessions: 5 }),
+    customSession({
+      schema: {
+        session: {
+          fields: {
+            ipAddress: { type: 'string', required: false },
+          },
+        },
+      },
+    }),
+    twoFactor({ issuer: 'My App' }),
+    captcha({
+      provider: 'recaptcha',
+      siteKey: process.env.RECAPTCHA_SITE_KEY!,
+      secretKey: process.env.RECAPTCHA_SECRET_KEY!,
+    }),
+  ],
+})
+```

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

@@ -0,0 +1,127 @@
+# Better Auth - 세션 관리
+
+> **상위 문서**: [Better Auth](./index.md)
+
+## 세션 설정
+
+```typescript
+import { betterAuth } from 'better-auth'
+
+export const auth = betterAuth({
+  session: {
+    modelName: 'sessions',
+    fields: {
+      userId: 'user_id',
+    },
+    expiresIn: 604800, // 7일 (초 단위)
+    updateAge: 86400, // 1일마다 갱신
+    additionalFields: {
+      customField: {
+        type: 'string',
+      },
+    },
+  },
+})
+```
+
+## 쿠키 캐시
+
+세션 조회 성능 최적화를 위한 쿠키 캐시:
+
+```typescript
+export const auth = betterAuth({
+  session: {
+    cookieCache: {
+      enabled: true,
+      maxAge: 5 * 60, // 5분
+      strategy: 'compact', // 'compact' | 'jwt' | 'jwe'
+      refreshCache: true,
+    },
+  },
+})
+```
+
+## 세션 가져오기
+
+### 클라이언트
+
+```typescript
+// 기본
+const session = await authClient.getSession()
+
+// 쿠키 캐시 우회 (DB에서 직접 가져오기)
+const session = await authClient.getSession({
+  query: {
+    disableCookieCache: true,
+  },
+})
+```
+
+### 서버
+
+```typescript
+await auth.api.getSession({
+  query: {
+    disableCookieCache: true,
+  },
+  headers: req.headers,
+})
+```
+
+## Custom Session Plugin
+
+세션 스키마 확장 및 커스텀 로직 구현:
+
+```typescript
+import { betterAuth } from 'better-auth'
+import { customSession } from 'better-auth/plugins'
+
+export const auth = betterAuth({
+  plugins: [
+    customSession({
+      // 세션 스키마 확장
+      schema: {
+        session: {
+          fields: {
+            ipAddress: {
+              type: 'string',
+              required: false,
+            },
+            userAgent: {
+              type: 'string',
+              required: false,
+            },
+            metadata: {
+              type: 'json',
+              required: false,
+            },
+          },
+        },
+      },
+
+      // 세션 생성 시 커스터마이즈
+      async onSessionCreate(session, context) {
+        return {
+          ...session,
+          ipAddress: context.request.headers.get('x-forwarded-for'),
+          userAgent: context.request.headers.get('user-agent'),
+          metadata: { loginMethod: 'email' },
+        }
+      },
+
+      // 세션 조회 시 커스터마이즈
+      async onSessionGet(session, context) {
+        return {
+          ...session,
+          activeDevices: await getActiveDevices(session.userId),
+        }
+      },
+    }),
+  ],
+})
+
+// 타입 안전한 커스텀 세션 데이터 접근
+const session = await auth.api.getSession({ headers })
+console.log('IP Address:', session?.ipAddress)
+console.log('Metadata:', session?.metadata)
+```

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

@@ -0,0 +1,123 @@
+# Better Auth - 설치 및 설정
+
+> **상위 문서**: [Better Auth](./index.md)
+
+## 설치
+
+```bash
+yarn add better-auth
+```
+
+## 서버 설정
+
+### 기본 설정
+
+```typescript
+// lib/auth.ts
+import { betterAuth } from 'better-auth'
+import { prismaAdapter } from 'better-auth/adapters/prisma'
+import { prisma } from './prisma'
+
+export const auth = betterAuth({
+  database: prismaAdapter(prisma),
+
+  // 이메일/비밀번호 인증 활성화
+  emailAndPassword: {
+    enabled: true,
+    requireEmailVerification: false,
+  },
+})
+```
+
+### 소셜 로그인 설정
+
+```typescript
+import { betterAuth } from 'better-auth'
+
+export const auth = betterAuth({
+  database: prismaAdapter(prisma),
+  socialProviders: {
+    google: {
+      clientId: process.env.GOOGLE_CLIENT_ID as string,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET as string,
+    },
+    github: {
+      clientId: process.env.GITHUB_CLIENT_ID as string,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET as string,
+    },
+    spotify: {
+      clientId: process.env.SPOTIFY_CLIENT_ID as string,
+      clientSecret: process.env.SPOTIFY_CLIENT_SECRET as string,
+    },
+  },
+})
+```
+
+## 클라이언트 설정
+
+### 기본 클라이언트
+
+```typescript
+// lib/auth-client.ts
+import { createAuthClient } from 'better-auth/client'
+
+export const authClient = createAuthClient({
+  // 옵션
+})
+```
+
+### React 클라이언트
+
+```typescript
+import { createAuthClient } from 'better-auth/react'
+
+export const authClient = createAuthClient({
+  // 옵션
+})
+```
+
+### 플러그인 포함 클라이언트
+
+```typescript
+import { createAuthClient } from 'better-auth/client'
+import { twoFactorClient } from 'better-auth/client/plugins'
+
+const authClient = createAuthClient({
+  plugins: [
+    twoFactorClient({
+      twoFactorPage: '/two-factor',
+      onTwoFactorRedirect() {
+        router.push('/two-factor')
+      },
+    }),
+  ],
+})
+```
+
+## TanStack Start 통합
+
+```typescript
+// lib/auth.ts
+import { betterAuth } from 'better-auth'
+import { prismaAdapter } from 'better-auth/adapters/prisma'
+import { prisma } from './prisma'
+
+export const auth = betterAuth({
+  database: prismaAdapter(prisma),
+  emailAndPassword: {
+    enabled: true,
+  },
+})
+
+// Server Function에서 사용
+import { createServerFn } from '@tanstack/react-start'
+import { auth } from '~/lib/auth'
+
+export const getSession = createServerFn({ method: 'GET' })
+  .handler(async ({ request }) => {
+    const session = await auth.api.getSession({
+      headers: request.headers,
+    })
+    return session
+  })
+```