@nextsparkjs/ai-workflow 0.1.0-beta.100

package/claude/commands/how-to/setup-authentication.md

@@ -0,0 +1,388 @@
+# /how-to:setup-authentication
+
+Interactive guide to configure authentication with Better Auth.
+
+---
+
+## Required Skills
+
+Before executing, these skills provide deeper context:
+- `.claude/skills/better-auth/SKILL.md` - Authentication patterns
+
+---
+
+## Syntax
+
+```
+/how-to:setup-authentication
+```
+
+---
+
+## Behavior
+
+Guides the user through configuring authentication providers, OAuth, and security settings.
+
+---
+
+## Tutorial Overview
+
+```
+STEPS OVERVIEW (4 steps)
+
+Step 1: Configure Better Auth
+        └── Core auth settings
+
+Step 2: Set Up Email/Password Auth
+        └── Basic authentication
+
+Step 3: Add OAuth Providers
+        └── Google, GitHub, etc.
+
+Step 4: Test Authentication
+        └── Verify login flows
+```
+
+---
+
+## Step 1: Configure Better Auth
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📚 HOW TO: SETUP AUTHENTICATION
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+STEP 1 OF 4: Configure Better Auth
+
+Set up the core authentication environment:
+
+```env
+# .env.local
+
+# REQUIRED: Auth secret (min 32 characters)
+BETTER_AUTH_SECRET="your-super-secret-key-at-least-32-chars"
+
+# REQUIRED: App URL
+BETTER_AUTH_URL="http://localhost:3000"
+
+# Optional: Trust host in production
+BETTER_AUTH_TRUST_HOST="true"
+```
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Generate a Secure Secret:
+
+```bash
+# Using OpenSSL
+openssl rand -base64 32
+
+# Using Node.js
+node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
+```
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Auth Configuration:
+
+```typescript
+// contents/themes/your-theme/config/auth.config.ts
+import type { AuthConfig } from '@/core/types/auth'
+
+export const authConfig: AuthConfig = {
+  // Session settings
+  session: {
+    strategy: 'database',  // or 'jwt'
+    maxAge: 7 * 24 * 60 * 60,  // 7 days
+  },
+
+  // Email settings
+  email: {
+    verification: {
+      required: true,
+      sendOnSignup: true,
+    },
+  },
+
+  // Password settings
+  password: {
+    minLength: 8,
+    requireUppercase: true,
+    requireNumber: true,
+    requireSpecial: false,
+  },
+
+  // Sign-up settings
+  registration: {
+    enabled: true,
+    requireInvite: false,
+  },
+}
+```
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+What would you like to do?
+
+[1] Continue to Step 2 (Email/Password)
+[2] Show me all auth config options
+[3] I'm getting auth errors
+```
+
+---
+
+## Step 2: Email/Password Authentication
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+STEP 2 OF 4: Email/Password Authentication
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Email/password auth is enabled by default. Configure email sending:
+
+```env
+# .env.local
+
+# Email provider (Resend recommended)
+RESEND_API_KEY="re_xxxx"
+EMAIL_FROM="noreply@yourdomain.com"
+```
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Sign Up a New User:
+
+```bash
+# Via API
+curl -X POST http://localhost:3000/api/auth/sign-up \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "user@example.com",
+    "password": "SecurePass123",
+    "name": "Test User"
+  }'
+```
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Password Reset Flow:
+
+```typescript
+// Request password reset
+await auth.api.forgotPassword({
+  body: { email: 'user@example.com' }
+})
+
+// Reset with token (from email)
+await auth.api.resetPassword({
+  body: {
+    token: 'reset-token-from-email',
+    newPassword: 'NewSecurePass123'
+  }
+})
+```
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Development Test Users:
+
+Configure test users for development:
+
+```typescript
+// contents/themes/your-theme/config/app.config.ts
+export const appConfig = {
+  devKeyring: [
+    {
+      email: 'admin@test.com',
+      password: 'Test1234',
+      name: 'Admin User',
+      role: 'superadmin',
+    },
+    {
+      email: 'user@test.com',
+      password: 'Test1234',
+      name: 'Regular User',
+      role: 'member',
+    },
+  ],
+}
+```
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+What would you like to do?
+
+[1] Continue to Step 3 (OAuth)
+[2] How do I disable email verification?
+[3] Set up email templates
+```
+
+---
+
+## Step 3: Add OAuth Providers
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+STEP 3 OF 4: Add OAuth Providers
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Google OAuth:
+
+1. Go to console.cloud.google.com
+2. Create OAuth 2.0 credentials
+3. Set redirect URI: http://localhost:3000/api/auth/callback/google
+
+```env
+# .env.local
+GOOGLE_CLIENT_ID="xxx.apps.googleusercontent.com"
+GOOGLE_CLIENT_SECRET="GOCSPX-xxx"
+```
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 GitHub OAuth:
+
+1. Go to github.com/settings/developers
+2. Create new OAuth App
+3. Set callback URL: http://localhost:3000/api/auth/callback/github
+
+```env
+# .env.local
+GITHUB_CLIENT_ID="Ov23xxxx"
+GITHUB_CLIENT_SECRET="xxx"
+```
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Enable Providers in Config:
+
+```typescript
+// contents/themes/your-theme/config/auth.config.ts
+export const authConfig: AuthConfig = {
+  providers: {
+    google: {
+      enabled: true,
+      clientId: process.env.GOOGLE_CLIENT_ID,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+    },
+    github: {
+      enabled: true,
+      clientId: process.env.GITHUB_CLIENT_ID,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET,
+    },
+  },
+}
+```
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Use OAuth in Login:
+
+```typescript
+'use client'
+
+import { signIn } from '@/core/lib/auth/client'
+
+function LoginPage() {
+  return (
+    <div>
+      <button onClick={() => signIn.social({ provider: 'google' })}>
+        Sign in with Google
+      </button>
+      <button onClick={() => signIn.social({ provider: 'github' })}>
+        Sign in with GitHub
+      </button>
+    </div>
+  )
+}
+```
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+What would you like to do?
+
+[1] Continue to Step 4 (Test)
+[2] Add more OAuth providers
+[3] How do I handle OAuth errors?
+```
+
+---
+
+## Step 4: Test Authentication
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+STEP 4 OF 4: Test Authentication
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Test all authentication flows:
+
+```bash
+# 1. Start the dev server
+pnpm dev
+
+# 2. Go to http://localhost:3000/login
+```
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Test Checklist:
+
+[ ] Sign up with email/password
+[ ] Verify email (check console in dev)
+[ ] Sign in with email/password
+[ ] Sign out
+[ ] Password reset flow
+[ ] Sign in with Google (if configured)
+[ ] Sign in with GitHub (if configured)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Check Session:
+
+```typescript
+// Server-side
+import { auth } from '@/core/lib/auth'
+
+const session = await auth.api.getSession({
+  headers: request.headers,
+})
+
+// Client-side
+import { useSession } from '@/core/lib/auth/client'
+
+function MyComponent() {
+  const { data: session, isPending } = useSession()
+
+  if (isPending) return <div>Loading...</div>
+  if (!session) return <div>Not logged in</div>
+
+  return <div>Hello, {session.user.name}</div>
+}
+```
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✅ TUTORIAL STORY!
+
+Your authentication is set up with:
+• Email/password authentication
+• OAuth providers (if configured)
+• Session management
+• Password reset flow
+
+📚 Related tutorials:
+   • /how-to:set-user-roles-and-permissions - RBAC setup
+   • /how-to:customize-app - App settings
+
+🔙 Back to menu: /how-to:start
+```
+
+---
+
+## Related Commands
+
+| Command | Action |
+|---------|--------|
+| `/how-to:set-user-roles-and-permissions` | Configure roles |
+| `/how-to:customize-app` | App settings |