Initial commit: antigravity-claudekit

skills/ck-better-auth/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: ck-better-auth
+description: >
+  Implements authentication and authorization using Better Auth library patterns.
+  Activate when user says 'add authentication', 'implement login', 'set up auth',
+  'user sessions', 'OAuth integration', or 'role-based access control'.
+  Accepts framework context (Next.js, Express, etc.) and provider requirements.
+---
+
+## Overview
+Scaffolds and implements authentication flows using Better Auth (better-auth.com), covering session management, OAuth providers, email/password auth, and RBAC patterns.
+
+## When to Use
+- Setting up authentication from scratch in a web application
+- Adding OAuth providers (GitHub, Google, Discord, etc.)
+- Implementing session-based or JWT authentication
+- Adding role-based or permission-based access control
+- Securing API routes and server-side pages
+
+## Don't Use When
+- Project already has a working auth system and only needs minor fixes
+- Building a purely public API with no user accounts
+- Using a managed auth service like Clerk or Auth0 (those have their own SDKs)
+- Mobile-only app requiring native auth flows
+
+## Steps / Instructions
+
+### 1. Install Better Auth
+
+```bash
+npm install better-auth
+```
+
+### 2. Configure Auth Instance
+
+```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, { provider: 'postgresql' }),
+  emailAndPassword: { enabled: true },
+  socialProviders: {
+    github: {
+      clientId: process.env.GITHUB_CLIENT_ID!,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+    },
+    google: {
+      clientId: process.env.GOOGLE_CLIENT_ID!,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+    },
+  },
+  session: {
+    expiresIn: 60 * 60 * 24 * 7, // 7 days
+    updateAge: 60 * 60 * 24,      // refresh if older than 1 day
+  },
+});
+```
+
+### 3. Set Up API Route (Next.js)
+
+```typescript
+// app/api/auth/[...all]/route.ts
+import { auth } from '@/lib/auth';
+import { toNextJsHandler } from 'better-auth/next-js';
+
+export const { GET, POST } = toNextJsHandler(auth);
+```
+
+### 4. Create Auth Client
+
+```typescript
+// lib/auth-client.ts
+import { createAuthClient } from 'better-auth/react';
+
+export const authClient = createAuthClient({
+  baseURL: process.env.NEXT_PUBLIC_APP_URL,
+});
+
+export const { signIn, signOut, signUp, useSession } = authClient;
+```
+
+### 5. Protect Routes (Next.js Middleware)
+
+```typescript
+// middleware.ts
+import { auth } from '@/lib/auth';
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function middleware(request: NextRequest) {
+  const session = await auth.api.getSession({
+    headers: request.headers,
+  });
+
+  if (!session && request.nextUrl.pathname.startsWith('/dashboard')) {
+    return NextResponse.redirect(new URL('/login', request.url));
+  }
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ['/dashboard/:path*', '/settings/:path*'],
+};
+```
+
+### 6. Add RBAC (Optional)
+
+```typescript
+import { betterAuth } from 'better-auth';
+import { rbac } from 'better-auth/plugins';
+
+export const auth = betterAuth({
+  // ...base config
+  plugins: [
+    rbac({
+      roles: {
+        admin: { permissions: ['read', 'write', 'delete'] },
+        user:  { permissions: ['read'] },
+      },
+    }),
+  ],
+});
+```
+
+### 7. Database Schema Migration
+
+Run Better Auth CLI to generate schema:
+```bash
+npx better-auth generate
+npx prisma migrate dev --name add-auth-tables
+```
+
+### 8. Environment Variables Required
+
+```bash
+# .env (never commit this file)
+BETTER_AUTH_SECRET=<generate with: openssl rand -base64 32>
+BETTER_AUTH_URL=http://localhost:3000
+GITHUB_CLIENT_ID=...
+GITHUB_CLIENT_SECRET=...
+GOOGLE_CLIENT_ID=...
+GOOGLE_CLIENT_SECRET=...
+```
+
+## Notes
+- Always generate `BETTER_AUTH_SECRET` with a cryptographically secure method
+- Never expose client secrets in frontend code or version control
+- Use HTTPS in production — sessions over HTTP are insecure
+- Test OAuth flows with provider sandbox/test apps before production