cfsa-antigravity 3.0.2 → 3.1.0

package/template/.codex/skill-library/stack/auth/lucia/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: lucia
+description: "Lucia auth patterns covering session management, database adapters, OAuth integration, password hashing, and middleware. Use when implementing authentication with Lucia."
+version: 1.0.0
+source: self
+date_added: "2026-03-14"
+---
+
+# Lucia
+
+Lightweight, session-based auth library. No magic — you own the user table, session table, and auth logic. Lucia handles session tokens and cookie management.
+
+## When to Use
+
+- Want full control over auth without a third-party service
+- Building with Astro, SvelteKit, Next.js, or Express
+- Need session-based auth (not JWT-based)
+- Want to store users/sessions in your own database
+
+## When NOT to Use
+
+- Want a managed auth service with pre-built UI (use Clerk or Auth.js)
+- Need JWT-based authentication (Lucia uses opaque session tokens)
+- Want OAuth without writing the callback handler yourself
+
+## Setup
+
+### Installation
+
+```bash
+npm install lucia
+npm install @lucia-auth/adapter-drizzle  # or adapter-prisma, adapter-mongoose, etc.
+```
+
+### Database Schema (Drizzle Example)
+
+```typescript
+// db/schema.ts
+import { pgTable, text, timestamp } from 'drizzle-orm/pg-core';
+
+export const userTable = pgTable('user', {
+  id: text('id').primaryKey(), // Generate with generateIdFromEntropySize(10)
+  email: text('email').notNull().unique(),
+  hashedPassword: text('hashed_password'),
+  name: text('name'),
+});
+
+export const sessionTable = pgTable('session', {
+  id: text('id').primaryKey(),
+  userId: text('user_id').notNull().references(() => userTable.id),
+  expiresAt: timestamp('expires_at', { withTimezone: true, mode: 'date' }).notNull(),
+});
+```
+
+### Lucia Instance
+
+```typescript
+// lib/auth.ts
+import { Lucia } from 'lucia';
+import { DrizzlePostgreSQLAdapter } from '@lucia-auth/adapter-drizzle';
+import { db } from './db';
+import { sessionTable, userTable } from './db/schema';
+
+const adapter = new DrizzlePostgreSQLAdapter(db, sessionTable, userTable);
+
+export const lucia = new Lucia(adapter, {
+  sessionCookie: {
+    attributes: {
+      secure: process.env.NODE_ENV === 'production',
+    },
+  },
+  getUserAttributes: (attributes) => ({
+    email: attributes.email,
+    name: attributes.name,
+  }),
+});
+
+// Type augmentation
+declare module 'lucia' {
+  interface Register {
+    Lucia: typeof lucia;
+    DatabaseUserAttributes: { email: string; name: string };
+  }
+}
+```
+
+## Sign-Up Flow
+
+```typescript
+import { generateIdFromEntropySize } from 'lucia';
+import { hash } from '@node-rs/argon2';
+
+async function signUp(email: string, password: string, name: string) {
+  const userId = generateIdFromEntropySize(10); // 16-char random ID
+  const hashedPassword = await hash(password, {
+    memoryCost: 19456,
+    timeCost: 2,
+    outputLen: 32,
+    parallelism: 1,
+  });
+
+  await db.insert(userTable).values({ id: userId, email, hashedPassword, name });
+
+  const session = await lucia.createSession(userId, {});
+  const sessionCookie = lucia.createSessionCookie(session.id);
+  return sessionCookie; // Set this as a response cookie
+}
+```
+
+## Sign-In Flow
+
+```typescript
+import { verify } from '@node-rs/argon2';
+
+async function signIn(email: string, password: string) {
+  const user = await db.query.userTable.findFirst({ where: eq(userTable.email, email) });
+  if (!user || !user.hashedPassword) {
+    throw new Error('Invalid email or password');
+  }
+
+  const validPassword = await verify(user.hashedPassword, password);
+  if (!validPassword) {
+    throw new Error('Invalid email or password');
+  }
+
+  const session = await lucia.createSession(user.id, {});
+  return lucia.createSessionCookie(session.id);
+}
+```
+
+## Session Validation Middleware
+
+### Next.js
+
+```typescript
+// middleware.ts or lib/auth-middleware.ts
+import { cookies } from 'next/headers';
+
+export async function validateRequest() {
+  const sessionId = (await cookies()).get(lucia.sessionCookieName)?.value ?? null;
+  if (!sessionId) return { user: null, session: null };
+
+  const result = await lucia.validateSession(sessionId);
+
+  if (result.session?.fresh) {
+    const cookie = lucia.createSessionCookie(result.session.id);
+    (await cookies()).set(cookie.name, cookie.value, cookie.attributes);
+  }
+  if (!result.session) {
+    const cookie = lucia.createBlankSessionCookie();
+    (await cookies()).set(cookie.name, cookie.value, cookie.attributes);
+  }
+
+  return result;
+}
+```
+
+### Usage in Server Components
+
+```typescript
+// app/dashboard/page.tsx
+import { validateRequest } from '@/lib/auth-middleware';
+import { redirect } from 'next/navigation';
+
+export default async function DashboardPage() {
+  const { user, session } = await validateRequest();
+  if (!user) redirect('/login');
+
+  return <h1>Welcome, {user.name}</h1>;
+}
+```
+
+## Sign Out
+
+```typescript
+async function signOut() {
+  const { session } = await validateRequest();
+  if (session) {
+    await lucia.invalidateSession(session.id);
+  }
+  const cookie = lucia.createBlankSessionCookie();
+  (await cookies()).set(cookie.name, cookie.value, cookie.attributes);
+}
+```
+
+## OAuth Integration
+
+```typescript
+// Using Arctic for OAuth providers
+import { GitHub } from 'arctic';
+
+const github = new GitHub(
+  process.env.GITHUB_CLIENT_ID!,
+  process.env.GITHUB_CLIENT_SECRET!,
+  null
+);
+
+// 1. Redirect to provider
+async function initiateOAuth() {
+  const state = generateState();
+  const url = github.createAuthorizationURL(state, ['user:email']);
+  // Set state in cookie, redirect to url
+}
+
+// 2. Handle callback
+async function handleOAuthCallback(code: string) {
+  const tokens = await github.validateAuthorizationCode(code);
+  const response = await fetch('https://api.github.com/user', {
+    headers: { Authorization: `Bearer ${tokens.accessToken()}` },
+  });
+  const githubUser = await response.json();
+
+  // Find or create user, then create session
+  const session = await lucia.createSession(user.id, {});
+  return lucia.createSessionCookie(session.id);
+}
+```
+
+## Anti-Patterns
+
+| Don't | Do |
+|-------|-----|
+| Use `bcrypt` for password hashing | Use `@node-rs/argon2` — Argon2id is the current best |
+| Skip the `session.fresh` check | Always refresh session cookies when `fresh === true` |
+| Store session tokens in localStorage | Use httpOnly cookies via `lucia.createSessionCookie()` |
+| Call `validateSession` on every render | Cache the result per-request (e.g., in React `cache()`) |
+| Create sessions without invalidating old ones | Implement session limits or invalidate on password change |
+| Skip type augmentation for `Register` | Always declare `DatabaseUserAttributes` for type safety |
+| Use UUIDs for user IDs | Use `generateIdFromEntropySize()` — shorter, more entropy |
+| Hash passwords with default/weak params | Set explicit Argon2 params (memoryCost ≥ 19456) |

package/template/.codex/skill-library/stack/auth/supabase-auth/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: supabase-auth
+description: "Supabase Auth patterns covering email/password, OAuth, magic link, session management, RLS integration, server-side auth, and middleware. Use when implementing authentication with Supabase."
+version: 1.0.0
+source: self
+date_added: "2026-03-14"
+---
+
+# Supabase Auth
+
+Authentication and authorization using Supabase's built-in auth service. Covers sign-up flows, session management, Row Level Security integration, and server-side auth patterns.
+
+## When to Use
+
+- Project uses Supabase as backend/database
+- Need email/password, OAuth, or magic link authentication
+- Need RLS policies tied to authenticated users
+- Need server-side auth verification in API routes or middleware
+
+## When NOT to Use
+
+- Using a separate auth provider (Clerk, Auth.js, Firebase Auth) with Supabase as DB only
+- Building auth from scratch without Supabase
+
+## Setup
+
+### Client-Side (Browser)
+
+```typescript
+import { createBrowserClient } from '@supabase/ssr';
+
+export function createClient() {
+  return createBrowserClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+  );
+}
+```
+
+### Server-Side (Next.js App Router)
+
+```typescript
+import { createServerClient } from '@supabase/ssr';
+import { cookies } from 'next/headers';
+
+export async function createServerSupabase() {
+  const cookieStore = await cookies();
+  return createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      cookies: {
+        getAll: () => cookieStore.getAll(),
+        setAll: (cookiesToSet) => {
+          cookiesToSet.forEach(({ name, value, options }) =>
+            cookieStore.set(name, value, options)
+          );
+        },
+      },
+    }
+  );
+}
+```
+
+### Environment Variables
+
+```env
+NEXT_PUBLIC_SUPABASE_URL=https://<project-ref>.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
+SUPABASE_SERVICE_ROLE_KEY=eyJ...  # Server-only, never expose to client
+```
+
+## Authentication Flows
+
+### Email/Password Sign-Up
+
+```typescript
+const { data, error } = await supabase.auth.signUp({
+  email: 'user@example.com',
+  password: 'secure-password-123',
+  options: {
+    data: { full_name: 'Jane Doe', role: 'member' },
+    emailRedirectTo: `${origin}/auth/callback`,
+  },
+});
+// data.user exists but email unconfirmed until link clicked
+```
+
+### Email/Password Sign-In
+
+```typescript
+const { data, error } = await supabase.auth.signInWithPassword({
+  email: 'user@example.com',
+  password: 'secure-password-123',
+});
+// data.session contains access_token and refresh_token
+```
+
+### OAuth (Google, GitHub, etc.)
+
+```typescript
+const { data, error } = await supabase.auth.signInWithOAuth({
+  provider: 'google',
+  options: {
+    redirectTo: `${origin}/auth/callback`,
+    queryParams: { access_type: 'offline', prompt: 'consent' },
+  },
+});
+// Redirects to provider, then back to /auth/callback
+```
+
+### Magic Link
+
+```typescript
+const { error } = await supabase.auth.signInWithOtp({
+  email: 'user@example.com',
+  options: { emailRedirectTo: `${origin}/auth/callback` },
+});
+```
+
+### Sign Out
+
+```typescript
+const { error } = await supabase.auth.signOut();
+```
+
+## Auth Callback Route
+
+Handle the OAuth/magic link redirect:
+
+```typescript
+// app/auth/callback/route.ts
+import { createServerSupabase } from '@/lib/supabase/server';
+import { NextResponse } from 'next/server';
+
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url);
+  const code = searchParams.get('code');
+  const next = searchParams.get('next') ?? '/dashboard';
+
+  if (code) {
+    const supabase = await createServerSupabase();
+    const { error } = await supabase.auth.exchangeCodeForSession(code);
+    if (!error) {
+      return NextResponse.redirect(new URL(next, request.url));
+    }
+  }
+  return NextResponse.redirect(new URL('/auth/error', request.url));
+}
+```
+
+## Middleware (Route Protection)
+
+```typescript
+// middleware.ts
+import { createServerClient } from '@supabase/ssr';
+import { NextResponse, type NextRequest } from 'next/server';
+
+export async function middleware(request: NextRequest) {
+  let response = NextResponse.next({ request });
+  const supabase = createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      cookies: {
+        getAll: () => request.cookies.getAll(),
+        setAll: (cookiesToSet) => {
+          cookiesToSet.forEach(({ name, value, options }) => {
+            request.cookies.set(name, value);
+            response.cookies.set(name, value, options);
+          });
+        },
+      },
+    }
+  );
+
+  const { data: { user } } = await supabase.auth.getUser();
+
+  // Redirect unauthenticated users to login
+  if (!user && request.nextUrl.pathname.startsWith('/dashboard')) {
+    return NextResponse.redirect(new URL('/login', request.url));
+  }
+
+  return response;
+}
+
+export const config = {
+  matcher: ['/dashboard/:path*', '/api/protected/:path*'],
+};
+```
+
+## Row Level Security (RLS)
+
+### Enable RLS and Create Policies
+
+```sql
+-- Enable RLS on a table
+ALTER TABLE profiles ENABLE ROW LEVEL SECURITY;
+
+-- Users can read their own profile
+CREATE POLICY "Users read own profile"
+  ON profiles FOR SELECT
+  USING (auth.uid() = id);
+
+-- Users can update their own profile
+CREATE POLICY "Users update own profile"
+  ON profiles FOR UPDATE
+  USING (auth.uid() = id)
+  WITH CHECK (auth.uid() = id);
+
+-- Admins can read all profiles
+CREATE POLICY "Admins read all profiles"
+  ON profiles FOR SELECT
+  USING (
+    EXISTS (
+      SELECT 1 FROM user_roles
+      WHERE user_roles.user_id = auth.uid()
+      AND user_roles.role = 'admin'
+    )
+  );
+```
+
+### Auto-Create Profile on Sign-Up
+
+```sql
+CREATE OR REPLACE FUNCTION public.handle_new_user()
+RETURNS TRIGGER AS $$
+BEGIN
+  INSERT INTO public.profiles (id, email, full_name, avatar_url)
+  VALUES (
+    NEW.id,
+    NEW.email,
+    NEW.raw_user_meta_data->>'full_name',
+    NEW.raw_user_meta_data->>'avatar_url'
+  );
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER;
+
+CREATE TRIGGER on_auth_user_created
+  AFTER INSERT ON auth.users
+  FOR EACH ROW EXECUTE FUNCTION public.handle_new_user();
+```
+
+## Session Management
+
+```typescript
+// Listen for auth state changes
+supabase.auth.onAuthStateChange((event, session) => {
+  if (event === 'SIGNED_IN') { /* redirect to dashboard */ }
+  if (event === 'SIGNED_OUT') { /* redirect to login */ }
+  if (event === 'TOKEN_REFRESHED') { /* session renewed */ }
+  if (event === 'PASSWORD_RECOVERY') { /* show reset form */ }
+});
+
+// Get current session
+const { data: { session } } = await supabase.auth.getSession();
+
+// Get current user (verifies JWT — preferred over getSession)
+const { data: { user } } = await supabase.auth.getUser();
+```
+
+## Service Role (Admin Operations)
+
+```typescript
+// Server-only — bypasses RLS
+import { createClient } from '@supabase/supabase-js';
+
+const supabaseAdmin = createClient(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.SUPABASE_SERVICE_ROLE_KEY!, // Never expose to client
+  { auth: { autoRefreshToken: false, persistSession: false } }
+);
+
+// Admin: delete user
+await supabaseAdmin.auth.admin.deleteUser(userId);
+
+// Admin: list users
+const { data } = await supabaseAdmin.auth.admin.listUsers();
+```
+
+## Anti-Patterns
+
+| Don't | Do |
+|-------|-----|
+| Use `getSession()` for auth verification | Use `getUser()` — it validates the JWT against the server |
+| Expose `SUPABASE_SERVICE_ROLE_KEY` to client | Keep it server-side only, use `anon` key on client |
+| Skip RLS on tables with user data | Always enable RLS and create explicit policies |
+| Store roles in JWT custom claims only | Store roles in a DB table and check via RLS policies |
+| Skip the auth callback route | Always handle `exchangeCodeForSession` for OAuth/magic link |
+| Use `supabase.auth.getUser()` in middleware without cookie sync | Pass cookies to the server client via `@supabase/ssr` |
+| Hardcode redirect URLs | Use `emailRedirectTo` with dynamic origin for portability |
+| Trust client-side auth state alone | Always verify server-side with middleware or API route checks |