@smicolon/ai-kit 0.3.1 → 0.4.0

package/packs/better-auth/commands/auth-setup.md

@@ -1,298 +0,0 @@
----
-name: auth-setup
-description: Initialize Better Auth with configuration and optional auth pages
-args:
-  - name: with-pages
-    description: Include login, register, and forgot-password pages
-    required: false
-  - name: providers
-    description: Comma-separated list of social providers (google,github,discord)
-    required: false
-  - name: 2fa
-    description: Enable two-factor authentication
-    required: false
-  - name: passkeys
-    description: Enable passkey/WebAuthn support
-    required: false
----
-
-# Setup Better Auth
-
-Initialize Better Auth with full configuration for your React application.
-
-## Instructions
-
-1. **Install Dependencies**:
-   ```bash
-   bun add better-auth
-   bun add -D @types/better-auth
-   ```
-
-2. **Create Server Configuration** at `src/lib/auth.ts`:
-   ```typescript
-   import { betterAuth } from 'better-auth'
-   import { prismaAdapter } from 'better-auth/adapters/prisma'
-   import { prisma } from './prisma'
-
-   export const auth = betterAuth({
-     database: prismaAdapter(prisma, {
-       provider: 'postgresql', // or 'mysql', 'sqlite'
-     }),
-
-     emailAndPassword: {
-       enabled: true,
-       requireEmailVerification: true,
-       password: {
-         minLength: 12,
-         requireUppercase: true,
-         requireNumber: true,
-       },
-       sendVerificationEmail: async (user, token, url) => {
-         // TODO: Implement email sending
-         console.log('Verification URL:', url)
-       },
-       sendResetPasswordToken: async (user, token, url) => {
-         // TODO: Implement email sending
-         console.log('Reset URL:', url)
-       },
-     },
-
-     session: {
-       expiresIn: 60 * 60 * 24 * 7, // 7 days
-       updateAge: 60 * 60 * 24,     // Extend daily
-       cookie: {
-         httpOnly: true,
-         secure: process.env.NODE_ENV === 'production',
-         sameSite: 'lax',
-       },
-     },
-
-     // Add social providers if requested
-     socialProviders: {
-       // Configured based on --providers flag
-     },
-
-     // Add plugins if requested
-     plugins: [
-       // Added based on --2fa and --passkeys flags
-     ],
-   })
-
-   export type Auth = typeof auth
-   ```
-
-3. **Create Auth Client** at `src/auth/client.ts`:
-   ```typescript
-   import { createAuthClient } from 'better-auth/react'
-   import type { Auth } from '@/lib/auth'
-
-   export const authClient = createAuthClient<Auth>({
-     baseURL: import.meta.env.VITE_API_URL || 'http://localhost:3000',
-   })
-
-   export const {
-     signIn,
-     signUp,
-     signOut,
-     useSession,
-     getSession,
-     resetPassword,
-     verifyEmail,
-   } = authClient
-   ```
-
-4. **Create Auth Hooks** at `src/auth/hooks.ts`:
-   ```typescript
-   import { useSession, signOut } from './client'
-   import { useNavigate } from '@tanstack/react-router'
-   import { useEffect } from 'react'
-
-   export function useAuth() {
-     const { data: session, isPending, error } = useSession()
-
-     return {
-       user: session?.user ?? null,
-       session: session?.session ?? null,
-       isAuthenticated: !!session?.user,
-       isLoading: isPending,
-       error,
-     }
-   }
-
-   export function useRequireAuth() {
-     const auth = useAuth()
-     const navigate = useNavigate()
-
-     useEffect(() => {
-       if (!auth.isLoading && !auth.isAuthenticated) {
-         navigate({ to: '/login' })
-       }
-     }, [auth.isLoading, auth.isAuthenticated, navigate])
-
-     return auth
-   }
-
-   export function useLogout() {
-     const navigate = useNavigate()
-
-     return async () => {
-       await signOut()
-       navigate({ to: '/login' })
-     }
-   }
-   ```
-
-5. **Update Root Route** at `src/routes/__root.tsx`:
-   ```typescript
-   import { createRootRouteWithContext, Outlet } from '@tanstack/react-router'
-   import { getSession } from '@/auth/client'
-   import type { QueryClient } from '@tanstack/react-query'
-
-   interface RouterContext {
-     queryClient: QueryClient
-     session: Awaited<ReturnType<typeof getSession>>['data'] | null
-   }
-
-   export const Route = createRootRouteWithContext<RouterContext>()({
-     beforeLoad: async () => {
-       const result = await getSession()
-       return { session: result?.data ?? null }
-     },
-     component: RootComponent,
-   })
-
-   function RootComponent() {
-     return (
-       <>
-         <Outlet />
-       </>
-     )
-   }
-   ```
-
-6. **Create Protected Route Layout** at `src/routes/_auth.tsx`:
-   ```typescript
-   import { createFileRoute, Outlet, redirect } from '@tanstack/react-router'
-
-   export const Route = createFileRoute('/_auth')({
-     beforeLoad: async ({ context, location }) => {
-       if (!context.session) {
-         throw redirect({
-           to: '/login',
-           search: { redirect: location.pathname },
-         })
-       }
-     },
-     component: () => <Outlet />,
-   })
-   ```
-
-7. **Create Guest Route Layout** at `src/routes/_guest.tsx`:
-   ```typescript
-   import { createFileRoute, Outlet, redirect } from '@tanstack/react-router'
-
-   export const Route = createFileRoute('/_guest')({
-     beforeLoad: async ({ context }) => {
-       if (context.session) {
-         throw redirect({ to: '/dashboard' })
-       }
-     },
-     component: () => <Outlet />,
-   })
-   ```
-
-8. **If --with-pages, Create Auth Pages**:
-
-   `src/routes/_guest.login.tsx`:
-   ```typescript
-   import { createFileRoute } from '@tanstack/react-router'
-   import { LoginForm } from '@/features/auth/components/LoginForm'
-   import { SocialLoginButtons } from '@/features/auth/components/SocialLoginButtons'
-
-   export const Route = createFileRoute('/_guest/login')({
-     component: LoginPage,
-   })
-
-   function LoginPage() {
-     return (
-       <div className="min-h-screen flex items-center justify-center">
-         <div className="w-full max-w-md space-y-8">
-           <h1 className="text-2xl font-bold text-center">Sign In</h1>
-           <LoginForm />
-           <div className="relative">
-             <div className="absolute inset-0 flex items-center">
-               <div className="w-full border-t" />
-             </div>
-             <div className="relative flex justify-center text-sm">
-               <span className="bg-white px-2 text-gray-500">Or continue with</span>
-             </div>
-           </div>
-           <SocialLoginButtons />
-         </div>
-       </div>
-     )
-   }
-   ```
-
-   `src/routes/_guest.register.tsx`:
-   ```typescript
-   import { createFileRoute } from '@tanstack/react-router'
-   import { RegisterForm } from '@/features/auth/components/RegisterForm'
-
-   export const Route = createFileRoute('/_guest/register')({
-     component: RegisterPage,
-   })
-
-   function RegisterPage() {
-     return (
-       <div className="min-h-screen flex items-center justify-center">
-         <div className="w-full max-w-md space-y-8">
-           <h1 className="text-2xl font-bold text-center">Create Account</h1>
-           <RegisterForm />
-         </div>
-       </div>
-     )
-   }
-   ```
-
-9. **Create Auth Components** in `src/features/auth/components/`:
-
-   - `LoginForm.tsx` - Email/password login form
-   - `RegisterForm.tsx` - Registration form
-   - `ForgotPasswordForm.tsx` - Password reset request
-   - `ResetPasswordForm.tsx` - New password form
-   - `SocialLoginButtons.tsx` - OAuth provider buttons
-
-10. **Add Environment Variables** to `.env`:
-    ```bash
-    # Better Auth
-    BETTER_AUTH_SECRET=your-secret-key-min-32-chars
-
-    # Database
-    DATABASE_URL=postgresql://...
-
-    # Social Providers (if enabled)
-    GOOGLE_CLIENT_ID=
-    GOOGLE_CLIENT_SECRET=
-    GITHUB_CLIENT_ID=
-    GITHUB_CLIENT_SECRET=
-    ```
-
-11. **Run Database Migrations**:
-    ```bash
-    bunx prisma db push
-    # or
-    bunx prisma migrate dev
-    ```
-
-## Quality Checklist
-
-- [ ] Server auth config at `lib/auth.ts`
-- [ ] Client at `auth/client.ts` with typed exports
-- [ ] Session loaded in `__root.tsx` beforeLoad
-- [ ] Protected routes use `_auth.tsx` layout
-- [ ] Guest routes use `_guest.tsx` layout
-- [ ] Environment variables documented
-- [ ] Database adapter configured
-- [ ] Email verification enabled
-- [ ] Secure session cookies configured

package/packs/better-auth/skills/auth-security/SKILL.md

@@ -1,425 +0,0 @@
----
-name: Auth Security Patterns
-description: >-
-  Auto-enforce authentication security best practices. Activates when
-  implementing password policies, rate limiting, session security, CSRF
-  protection, or security headers in auth flows.
-version: 1.0.0
----
-
-# Auth Security Patterns
-
-This skill enforces authentication security best practices for Better Auth implementations.
-
-## Password Security
-
-### Strong Password Policy
-```typescript
-import { betterAuth } from 'better-auth'
-
-export const auth = betterAuth({
-  emailAndPassword: {
-    enabled: true,
-    password: {
-      minLength: 12,
-      maxLength: 128,
-      requireLowercase: true,
-      requireUppercase: true,
-      requireNumber: true,
-      requireSpecialChar: true,
-      // Custom validation
-      validate: (password) => {
-        // Check against common passwords
-        if (commonPasswords.includes(password.toLowerCase())) {
-          return 'Password is too common'
-        }
-        // Check for repeated characters
-        if (/(.)\1{2,}/.test(password)) {
-          return 'Password cannot have 3+ repeated characters'
-        }
-        return true
-      },
-    },
-  },
-})
-```
-
-### Password Hashing
-```typescript
-// Better Auth uses bcrypt by default with cost factor 10
-// For higher security requirements:
-export const auth = betterAuth({
-  advanced: {
-    password: {
-      hash: async (password) => {
-        const salt = await bcrypt.genSalt(12) // Higher cost
-        return bcrypt.hash(password, salt)
-      },
-      verify: async (password, hash) => {
-        return bcrypt.compare(password, hash)
-      },
-    },
-  },
-})
-```
-
-## Rate Limiting
-
-### Global Rate Limiting
-```typescript
-import { rateLimit } from 'better-auth/plugins/rate-limit'
-
-export const auth = betterAuth({
-  plugins: [
-    rateLimit({
-      window: 60,  // 1 minute window
-      max: 100,    // 100 requests per window
-      keyGenerator: (req) => {
-        // Rate limit by IP
-        return req.headers.get('x-forwarded-for') || req.ip
-      },
-    }),
-  ],
-})
-```
-
-### Endpoint-Specific Limits
-```typescript
-rateLimit({
-  endpoints: {
-    // Strict limits for auth endpoints
-    'sign-in': {
-      window: 300,  // 5 minutes
-      max: 5,       // 5 attempts
-    },
-    'sign-up': {
-      window: 3600, // 1 hour
-      max: 3,       // 3 registrations
-    },
-    'reset-password': {
-      window: 3600, // 1 hour
-      max: 3,       // 3 reset requests
-    },
-    'verify-email': {
-      window: 60,   // 1 minute
-      max: 5,       // 5 verification attempts
-    },
-  },
-})
-```
-
-### Progressive Delays
-```typescript
-rateLimit({
-  endpoints: {
-    'sign-in': {
-      window: 300,
-      max: 5,
-      // Add delay after failed attempts
-      onRateLimitExceeded: async (req, res) => {
-        const attempts = await getFailedAttempts(req.ip)
-        const delay = Math.min(attempts * 1000, 30000) // Max 30s
-        await new Promise(resolve => setTimeout(resolve, delay))
-      },
-    },
-  },
-})
-```
-
-## Session Security
-
-### Secure Session Configuration
-```typescript
-export const auth = betterAuth({
-  session: {
-    expiresIn: 60 * 60 * 24 * 7,  // 7 days max
-    updateAge: 60 * 60 * 24,      // Extend daily on activity
-
-    // Cookie settings
-    cookie: {
-      name: '__session',
-      httpOnly: true,
-      secure: process.env.NODE_ENV === 'production',
-      sameSite: 'lax',
-      path: '/',
-      domain: process.env.COOKIE_DOMAIN,
-    },
-
-    // Session cache (reduce DB lookups)
-    cookieCache: {
-      enabled: true,
-      maxAge: 60 * 5, // 5 minute cache
-    },
-
-    // Require fresh session for sensitive ops
-    freshAge: 60 * 10, // 10 minutes
-  },
-})
-```
-
-### Session Invalidation
-```typescript
-import { signOut, useSession } from '@/auth/client'
-
-// Sign out from current device
-await signOut()
-
-// Sign out from all devices
-await signOut({ revokeAllSessions: true })
-
-// Server-side: Invalidate specific session
-await auth.api.invalidateSession({ sessionId })
-
-// Server-side: Invalidate all user sessions
-await auth.api.invalidateUserSessions({ userId })
-```
-
-### Session Binding
-```typescript
-// Bind session to device fingerprint
-export const auth = betterAuth({
-  session: {
-    // Store device info
-    onSessionCreated: async (session, user, request) => {
-      await prisma.session.update({
-        where: { id: session.id },
-        data: {
-          userAgent: request.headers.get('user-agent'),
-          ipAddress: request.ip,
-        },
-      })
-    },
-    // Validate on each request
-    onSessionValidate: async (session, request) => {
-      const storedIp = session.ipAddress
-      const currentIp = request.ip
-
-      // Warn on IP change (but don't block for mobile users)
-      if (storedIp !== currentIp) {
-        await logSecurityEvent('session_ip_change', {
-          sessionId: session.id,
-          oldIp: storedIp,
-          newIp: currentIp,
-        })
-      }
-
-      return true
-    },
-  },
-})
-```
-
-## CSRF Protection
-
-### Token-Based CSRF
-```typescript
-export const auth = betterAuth({
-  csrf: {
-    enabled: true,
-    // Double submit cookie pattern
-    cookieName: '__csrf',
-    headerName: 'x-csrf-token',
-    // Token rotation
-    rotateOnAuthentication: true,
-  },
-})
-
-// Client: Include CSRF token
-const csrfToken = getCookie('__csrf')
-await fetch('/api/auth/sign-out', {
-  method: 'POST',
-  headers: {
-    'x-csrf-token': csrfToken,
-  },
-})
-```
-
-### SameSite Cookie Protection
-```typescript
-session: {
-  cookie: {
-    sameSite: 'strict', // Strictest CSRF protection
-    // Or 'lax' for balance between security and usability
-  },
-}
-```
-
-## Security Headers
-
-### Recommended Headers
-```typescript
-// Middleware or server config
-const securityHeaders = {
-  'Strict-Transport-Security': 'max-age=31536000; includeSubDomains',
-  'X-Content-Type-Options': 'nosniff',
-  'X-Frame-Options': 'DENY',
-  'X-XSS-Protection': '1; mode=block',
-  'Referrer-Policy': 'strict-origin-when-cross-origin',
-  'Content-Security-Policy': [
-    "default-src 'self'",
-    "script-src 'self'",
-    "style-src 'self' 'unsafe-inline'",
-    "img-src 'self' data: https:",
-    "font-src 'self'",
-    "connect-src 'self'",
-    "frame-ancestors 'none'",
-  ].join('; '),
-}
-```
-
-## Account Security
-
-### Account Lockout
-```typescript
-export const auth = betterAuth({
-  emailAndPassword: {
-    lockout: {
-      enabled: true,
-      maxAttempts: 5,
-      lockoutDuration: 15 * 60, // 15 minutes
-      // Notify user
-      onLockout: async (user) => {
-        await sendEmail({
-          to: user.email,
-          subject: 'Account Locked',
-          html: 'Your account has been locked due to multiple failed login attempts.',
-        })
-      },
-    },
-  },
-})
-```
-
-### Email Verification
-```typescript
-export const auth = betterAuth({
-  emailAndPassword: {
-    requireEmailVerification: true,
-    verificationTokenExpiry: 60 * 60 * 24, // 24 hours
-    sendVerificationEmail: async (user, token, url) => {
-      await sendEmail({
-        to: user.email,
-        subject: 'Verify your email',
-        html: `<a href="${url}">Verify email</a>`,
-      })
-    },
-  },
-})
-```
-
-### Password Reset Security
-```typescript
-export const auth = betterAuth({
-  emailAndPassword: {
-    resetPasswordTokenExpiry: 60 * 60, // 1 hour
-    sendResetPasswordToken: async (user, token, url) => {
-      await sendEmail({
-        to: user.email,
-        subject: 'Reset your password',
-        html: `<a href="${url}">Reset password</a>`,
-      })
-
-      // Log for security audit
-      await logSecurityEvent('password_reset_requested', {
-        userId: user.id,
-        email: user.email,
-      })
-    },
-    onPasswordReset: async (user) => {
-      // Invalidate all existing sessions
-      await auth.api.invalidateUserSessions({ userId: user.id })
-
-      // Notify user
-      await sendEmail({
-        to: user.email,
-        subject: 'Password changed',
-        html: 'Your password was recently changed.',
-      })
-    },
-  },
-})
-```
-
-## Security Logging
-
-### Audit Trail
-```typescript
-export const auth = betterAuth({
-  advanced: {
-    hooks: {
-      onSignIn: async (user, session) => {
-        await logSecurityEvent('sign_in', {
-          userId: user.id,
-          sessionId: session.id,
-          method: session.method, // 'email', 'google', etc.
-        })
-      },
-      onSignOut: async (user, session) => {
-        await logSecurityEvent('sign_out', {
-          userId: user.id,
-          sessionId: session.id,
-        })
-      },
-      onSignUp: async (user) => {
-        await logSecurityEvent('sign_up', {
-          userId: user.id,
-          email: user.email,
-        })
-      },
-    },
-  },
-})
-
-async function logSecurityEvent(event: string, data: Record<string, any>) {
-  await prisma.securityLog.create({
-    data: {
-      event,
-      data,
-      timestamp: new Date(),
-      ip: data.ip,
-      userAgent: data.userAgent,
-    },
-  })
-}
-```
-
-## Security Checklist
-
-- [ ] Password minimum 12 characters with complexity
-- [ ] Rate limiting on all auth endpoints
-- [ ] Session cookies are httpOnly and secure
-- [ ] CSRF protection enabled
-- [ ] Email verification required
-- [ ] Account lockout after failed attempts
-- [ ] Security headers configured
-- [ ] Password changes invalidate sessions
-- [ ] Security events logged
-- [ ] 2FA available for users
-
-## Anti-Patterns
-
-```typescript
-// ❌ WRONG: Weak password policy
-password: { minLength: 6 }
-
-// ✅ CORRECT: Strong policy
-password: { minLength: 12, requireUppercase: true, ... }
-
-// ❌ WRONG: No rate limiting
-emailAndPassword: { enabled: true }
-
-// ✅ CORRECT: With rate limiting
-plugins: [rateLimit({ ... })]
-
-// ❌ WRONG: Long-lived sessions
-session: { expiresIn: 60 * 60 * 24 * 365 } // 1 year
-
-// ✅ CORRECT: Reasonable expiry
-session: { expiresIn: 60 * 60 * 24 * 7 } // 7 days
-
-// ❌ WRONG: Cookies without flags
-cookie: { name: 'session' }
-
-// ✅ CORRECT: Secure cookie flags
-cookie: { httpOnly: true, secure: true, sameSite: 'lax' }
-```