commit 26a675f3a7a0bc321e9cf3ec19146390be1025a5 Author: Zhongwei Li Date: Sat Nov 29 18:46:51 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..3e47df0 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "supabase-auth-ssr-setup", + "description": "This skill should be used when configuring Supabase Auth for server-side rendering with Next.js App Router, including secure cookie handling, middleware protection, route guards, authentication utilities, and logout flow. Apply when setting up SSR auth, adding protected routes, implementing middleware authentication, configuring secure sessions, or building login/logout flows with Supabase.", + "version": "1.0.0", + "author": { + "name": "Hope Overture", + "email": "support@worldbuilding-app-skills.dev" + }, + "skills": [ + "./skills" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..5faba3e --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# supabase-auth-ssr-setup + +This skill should be used when configuring Supabase Auth for server-side rendering with Next.js App Router, including secure cookie handling, middleware protection, route guards, authentication utilities, and logout flow. Apply when setting up SSR auth, adding protected routes, implementing middleware authentication, configuring secure sessions, or building login/logout flows with Supabase. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..6c0baa6 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,89 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:hopeoverture/worldbuilding-app-skills:plugins/supabase-auth-ssr-setup", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "4623c6da9a0793672ad5440ca1d99fdb9f84555b", + "treeHash": "aa3ed0b58c8fb5cac6444aabd59e159dc94ca5c80a2470e59c42e48090d1828c", + "generatedAt": "2025-11-28T10:17:32.066753Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "supabase-auth-ssr-setup", + "description": "This skill should be used when configuring Supabase Auth for server-side rendering with Next.js App Router, including secure cookie handling, middleware protection, route guards, authentication utilities, and logout flow. Apply when setting up SSR auth, adding protected routes, implementing middleware authentication, configuring secure sessions, or building login/logout flows with Supabase.", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "dca8566f81b014cb2d53cf4b956a17ba9c58eb2e89b6a19e79a6f27a07300bc3" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "6664558b6e7c5bc9f8c58c3479921c7965fa395dd08d9194ffd1804f313d346b" + }, + { + "path": "skills/supabase-auth-ssr-setup/SKILL.md", + "sha256": "68c11fb9926369205d2c9525a97bc3a83724a390f573ec9ed10df196aa44f6e9" + }, + { + "path": "skills/supabase-auth-ssr-setup/references/authentication-patterns.md", + "sha256": "40ef8e7be31c664de5e535b4cd0e708c54c1ba34847a0ea04c1edb1e5865ad3a" + }, + { + "path": "skills/supabase-auth-ssr-setup/references/security-considerations.md", + "sha256": "64a706f71750d5127403f01d215f8135e2d27a87983dddd5badfaf9d2e8b0306" + }, + { + "path": "skills/supabase-auth-ssr-setup/assets/auth-utils.ts", + "sha256": "4de1e198de2adae26098ab88d41b7eecb0da26a7b63dd006818551020f9ad4b1" + }, + { + "path": "skills/supabase-auth-ssr-setup/assets/middleware.ts", + "sha256": "cdee24888432ea20d24a6f08e8902279392df4e6453e05d4c6ddbf59cb41db1f" + }, + { + "path": "skills/supabase-auth-ssr-setup/assets/dashboard-page.tsx", + "sha256": "ea60ce1a4e275260dedb425a16e7a7337684f5de420d5917fb0d4b6cfd1da4de" + }, + { + "path": "skills/supabase-auth-ssr-setup/assets/supabase-middleware.ts", + "sha256": "596ba74fcbb2dc8df20046ccb867a5feae576f767d4398d69b62f05dadc92648" + }, + { + "path": "skills/supabase-auth-ssr-setup/assets/supabase-server.ts", + "sha256": "87309d49763b66c6709ddfd0efbc490cb0888dc5c868b77577e0b76a14b0a090" + }, + { + "path": "skills/supabase-auth-ssr-setup/assets/auth-callback-route.ts", + "sha256": "2c41fcdf0338c0f9ee71378f095e3eed6f424e738b33424cced6288bc95f775a" + }, + { + "path": "skills/supabase-auth-ssr-setup/assets/supabase-client.ts", + "sha256": "94927a2acad856525a606fb67bf24cd2aff04d2625213c39033f773d014b98e3" + }, + { + "path": "skills/supabase-auth-ssr-setup/assets/auth-actions.ts", + "sha256": "6a2001056ac64f43f6fb6b711878e7860c4edaadfc1781d1057e34e4dfd3b133" + }, + { + "path": "skills/supabase-auth-ssr-setup/assets/login-page.tsx", + "sha256": "63a6d14abbcb88b6779d7595c18a475084f66fdcb128b6702967ad8f1a4d25ec" + } + ], + "dirSha256": "aa3ed0b58c8fb5cac6444aabd59e159dc94ca5c80a2470e59c42e48090d1828c" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/supabase-auth-ssr-setup/SKILL.md b/skills/supabase-auth-ssr-setup/SKILL.md new file mode 100644 index 0000000..7e06630 --- /dev/null +++ b/skills/supabase-auth-ssr-setup/SKILL.md @@ -0,0 +1,296 @@ +--- +name: supabase-auth-ssr-setup +description: This skill should be used when configuring Supabase Auth for server-side rendering with Next.js App Router, including secure cookie handling, middleware protection, route guards, authentication utilities, and logout flow. Apply when setting up SSR auth, adding protected routes, implementing middleware authentication, configuring secure sessions, or building login/logout flows with Supabase. +--- + +# Supabase Auth SSR Setup + +## Overview + +Configure Supabase Authentication for Next.js App Router with server-side rendering (SSR), secure cookie-based sessions, middleware protection, and complete authentication flows. + +## Installation and Configuration Steps + +### 1. Install Dependencies + +Install Supabase SSR package for Next.js: + +```bash +npm install @supabase/supabase-js @supabase/ssr +``` + +### 2. Create Supabase Client Utilities + +Create three client configurations for different contexts (browser, server, middleware): + +**File: `lib/supabase/client.ts`** (Browser client) + +Use the template from `assets/supabase-client.ts`. This client: +- Runs only in browser context +- Uses secure cookies for session storage +- Automatically refreshes tokens + +**File: `lib/supabase/server.ts`** (Server component client) + +Use the template from `assets/supabase-server.ts`. This client: +- Creates server-side Supabase client with cookie access +- Used in Server Components and Server Actions +- Provides read-only cookie access for security + +**File: `lib/supabase/middleware.ts`** (Middleware client) + +Use the template from `assets/supabase-middleware.ts`. This client: +- Used in Next.js middleware for route protection +- Can update cookies in responses +- Refreshes sessions on route navigation + +### 3. Configure Environment Variables + +Add Supabase credentials to `.env.local`: + +```env +NEXT_PUBLIC_SUPABASE_URL=your-project-url +NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key +``` + +Get these values from your Supabase project settings under API. + +**Security note**: The anon key is safe to expose publicly. Real security comes from Row Level Security (RLS) policies in your database. + +### 4. Create Middleware for Route Protection + +Create `middleware.ts` in project root using the template from `assets/middleware.ts`. This middleware: + +- Refreshes Supabase session on every request +- Protects routes matching specified patterns +- Redirects unauthenticated users to login +- Allows public routes to bypass authentication + +Configure protected routes by adjusting the matcher pattern: + +```typescript +export const config = { + matcher: [ + '/dashboard/:path*', + '/settings/:path*', + '/api/protected/:path*', + ], +}; +``` + +### 5. Create Authentication Utilities + +Create helper functions for common auth operations using templates from `assets/auth-utils.ts`: + +**Get current user server-side**: +```typescript +import { getCurrentUser } from '@/lib/auth/utils'; + +const user = await getCurrentUser(); +``` + +**Require authentication**: +```typescript +import { requireAuth } from '@/lib/auth/utils'; + +const user = await requireAuth(); // Throws error if not authenticated +``` + +**Get session**: +```typescript +import { getSession } from '@/lib/auth/utils'; + +const session = await getSession(); +``` + +These utilities simplify authentication checks in Server Components and Server Actions. + +### 6. Create Logout Server Action + +Create `app/actions/auth.ts` using the template from `assets/auth-actions.ts`. This provides: + +**Logout action**: +- Clears Supabase session +- Removes auth cookies +- Redirects to home page + +Use in client components: + +```typescript +import { logout } from '@/app/actions/auth'; + + +``` + +### 7. Create Login Page + +Create `app/login/page.tsx` using the template from `assets/login-page.tsx`. This page: + +- Provides email/password login form +- Handles magic link authentication +- Supports OAuth providers (Google, GitHub, etc.) +- Redirects authenticated users +- Shows error messages + +Customize the login page: +- Add your branding and styling +- Enable/disable OAuth providers +- Add password reset link +- Include sign-up link + +### 8. Create Protected Route Example + +Create a protected dashboard page at `app/dashboard/page.tsx` using the template from `assets/dashboard-page.tsx`. This demonstrates: + +- Using `requireAuth()` to protect routes +- Displaying user information +- Including logout functionality +- Server-side authentication check + +### 9. Set Up Callback Route for OAuth + +If using OAuth providers, create `app/auth/callback/route.ts` using the template from `assets/auth-callback-route.ts`. This handler: + +- Exchanges OAuth code for session +- Sets secure session cookies +- Redirects to intended destination +- Handles OAuth errors + +Configure OAuth in Supabase dashboard: +1. Go to Authentication > Providers +2. Enable desired providers (Google, GitHub, etc.) +3. Add redirect URL: `https://your-domain.com/auth/callback` + +## Authentication Flow + +### Login Flow + +1. User visits `/login` +2. User enters credentials or clicks OAuth +3. Supabase authenticates and sets session cookie +4. User redirected to dashboard or intended page +5. Middleware validates session on protected routes + +### Session Refresh Flow + +1. User navigates to any route +2. Middleware runs and refreshes session if needed +3. Updated session cookie sent to client +4. Server Components have access to fresh session + +### Logout Flow + +1. User clicks logout button +2. Server Action calls Supabase `signOut()` +3. Session and cookies cleared +4. User redirected to home page + +## Route Protection Patterns + +### Protecting Individual Pages + +Use `requireAuth()` at the top of Server Components: + +```typescript +import { requireAuth } from '@/lib/auth/utils'; + +export default async function ProtectedPage() { + const user = await requireAuth(); + + return
Hello {user.email}
; +} +``` + +### Protecting Route Groups + +Use Next.js route groups with layout: + +```typescript +// app/(protected)/layout.tsx +import { requireAuth } from '@/lib/auth/utils'; + +export default async function ProtectedLayout({ children }) { + await requireAuth(); + return <>{children}; +} +``` + +All routes in `(protected)` group are automatically protected. + +### Optional Authentication + +Check if user is logged in without requiring it: + +```typescript +import { getCurrentUser } from '@/lib/auth/utils'; + +export default async function OptionalAuthPage() { + const user = await getCurrentUser(); + + return ( +
+ {user ? `Welcome ${user.email}` : 'Please log in'} +
+ ); +} +``` + +## Server Actions with Authentication + +Protect Server Actions using `requireAuth()`: + +```typescript +'use server'; + +import { requireAuth } from '@/lib/auth/utils'; +import { createServerClient } from '@/lib/supabase/server'; + +export async function updateProfile(formData: FormData) { + const user = await requireAuth(); + const supabase = createServerClient(); + + const { error } = await supabase + .from('profiles') + .update({ name: formData.get('name') }) + .eq('id', user.id); + + if (error) throw error; +} +``` + +## Troubleshooting + +**Session not persisting**: Verify cookies are being set. Check browser dev tools > Application > Cookies. Ensure domain matches. + +**Middleware redirect loop**: Check matcher pattern doesn't include login page. Verify `/login` is accessible without auth. + +**OAuth redirect fails**: Confirm callback URL matches exactly in Supabase dashboard. Check for trailing slashes. + +**TypeScript errors**: Install types: `npm install -D @types/node`. Ensure `supabase` is typed correctly. + +**401 errors on protected routes**: Session may be expired. Check Supabase dashboard > Authentication > Settings for session timeout. + +## Resources + +### scripts/ + +No executable scripts needed for this skill. + +### references/ + +- `authentication-patterns.md` - Common auth patterns and best practices for Next.js + Supabase +- `security-considerations.md` - Security best practices for session handling and cookie configuration + +### assets/ + +- `supabase-client.ts` - Browser-side Supabase client configuration +- `supabase-server.ts` - Server-side Supabase client for Server Components +- `supabase-middleware.ts` - Middleware Supabase client for session refresh +- `middleware.ts` - Next.js middleware for route protection +- `auth-utils.ts` - Helper functions for authentication checks +- `auth-actions.ts` - Server Actions for logout and other auth operations +- `login-page.tsx` - Complete login page with email/password and OAuth +- `dashboard-page.tsx` - Example protected page using requireAuth +- `auth-callback-route.ts` - OAuth callback handler for provider authentication diff --git a/skills/supabase-auth-ssr-setup/assets/auth-actions.ts b/skills/supabase-auth-ssr-setup/assets/auth-actions.ts new file mode 100644 index 0000000..abc1d16 --- /dev/null +++ b/skills/supabase-auth-ssr-setup/assets/auth-actions.ts @@ -0,0 +1,98 @@ +'use server'; + +import { createServerClient } from '@/lib/supabase/server'; +import { revalidatePath } from 'next/cache'; +import { redirect } from 'next/navigation'; + +/** + * Sign out the current user + */ +export async function logout() { + const supabase = await createServerClient(); + await supabase.auth.signOut(); + revalidatePath('/', 'layout'); + redirect('/'); +} + +/** + * Sign in with email and password + */ +export async function signInWithPassword(formData: FormData) { + const email = formData.get('email') as string; + const password = formData.get('password') as string; + + const supabase = await createServerClient(); + const { error } = await supabase.auth.signInWithPassword({ + email, + password, + }); + + if (error) { + return { error: error.message }; + } + + revalidatePath('/', 'layout'); + redirect('/dashboard'); +} + +/** + * Sign up with email and password + */ +export async function signUpWithPassword(formData: FormData) { + const email = formData.get('email') as string; + const password = formData.get('password') as string; + + const supabase = await createServerClient(); + const { error } = await supabase.auth.signUp({ + email, + password, + options: { + emailRedirectTo: `${process.env.NEXT_PUBLIC_SITE_URL}/auth/callback`, + }, + }); + + if (error) { + return { error: error.message }; + } + + return { success: 'Check your email to confirm your account' }; +} + +/** + * Send magic link for passwordless login + */ +export async function signInWithMagicLink(formData: FormData) { + const email = formData.get('email') as string; + + const supabase = await createServerClient(); + const { error } = await supabase.auth.signInWithOtp({ + email, + options: { + emailRedirectTo: `${process.env.NEXT_PUBLIC_SITE_URL}/auth/callback`, + }, + }); + + if (error) { + return { error: error.message }; + } + + return { success: 'Check your email for the magic link' }; +} + +/** + * Request password reset + */ +export async function resetPassword(formData: FormData) { + const email = formData.get('email') as string; + + const supabase = await createServerClient(); + const { error } = await supabase.auth.resetPasswordForEmail(email, { + redirectTo: `${process.env.NEXT_PUBLIC_SITE_URL}/auth/reset-password`, + }); + + if (error) { + return { error: error.message }; + } + + return { success: 'Check your email for the password reset link' }; +} diff --git a/skills/supabase-auth-ssr-setup/assets/auth-callback-route.ts b/skills/supabase-auth-ssr-setup/assets/auth-callback-route.ts new file mode 100644 index 0000000..0bda504 --- /dev/null +++ b/skills/supabase-auth-ssr-setup/assets/auth-callback-route.ts @@ -0,0 +1,29 @@ +import { createServerClient } from '@/lib/supabase/server'; +import { NextResponse } from 'next/server'; + +export async function GET(request: Request) { + const { searchParams, origin } = new URL(request.url); + const code = searchParams.get('code'); + const next = searchParams.get('next') ?? '/dashboard'; + + if (code) { + const supabase = await createServerClient(); + const { error } = await supabase.auth.exchangeCodeForSession(code); + + if (!error) { + const forwardedHost = request.headers.get('x-forwarded-host'); + const isLocalEnv = process.env.NODE_ENV === 'development'; + + if (isLocalEnv) { + return NextResponse.redirect(`${origin}${next}`); + } else if (forwardedHost) { + return NextResponse.redirect(`https://${forwardedHost}${next}`); + } else { + return NextResponse.redirect(`${origin}${next}`); + } + } + } + + // Return the user to an error page with instructions + return NextResponse.redirect(`${origin}/auth/auth-code-error`); +} diff --git a/skills/supabase-auth-ssr-setup/assets/auth-utils.ts b/skills/supabase-auth-ssr-setup/assets/auth-utils.ts new file mode 100644 index 0000000..328a478 --- /dev/null +++ b/skills/supabase-auth-ssr-setup/assets/auth-utils.ts @@ -0,0 +1,67 @@ +import { createServerClient } from '@/lib/supabase/server'; +import { redirect } from 'next/navigation'; + +/** + * Get the current authenticated user + * Returns null if not authenticated + */ +export async function getCurrentUser() { + const supabase = await createServerClient(); + const { + data: { user }, + } = await supabase.auth.getUser(); + return user; +} + +/** + * Get the current session + * Returns null if not authenticated + */ +export async function getSession() { + const supabase = await createServerClient(); + const { + data: { session }, + } = await supabase.auth.getSession(); + return session; +} + +/** + * Require authentication - redirects to login if not authenticated + * Use in Server Components and Server Actions that require auth + */ +export async function requireAuth() { + const user = await getCurrentUser(); + + if (!user) { + redirect('/login'); + } + + return user; +} + +/** + * Check if user has specific role + * Assumes roles are stored in user metadata or a profiles table + */ +export async function hasRole(role: string): Promise { + const user = await getCurrentUser(); + + if (!user) return false; + + // Check user metadata for role + const userRole = user.user_metadata?.role; + return userRole === role; +} + +/** + * Require specific role - redirects to unauthorized page if role not met + */ +export async function requireRole(role: string) { + const user = await requireAuth(); + + if (!hasRole(role)) { + redirect('/unauthorized'); + } + + return user; +} diff --git a/skills/supabase-auth-ssr-setup/assets/dashboard-page.tsx b/skills/supabase-auth-ssr-setup/assets/dashboard-page.tsx new file mode 100644 index 0000000..3078108 --- /dev/null +++ b/skills/supabase-auth-ssr-setup/assets/dashboard-page.tsx @@ -0,0 +1,67 @@ +import { requireAuth } from '@/lib/auth/utils'; +import { logout } from '@/app/actions/auth'; + +export default async function DashboardPage() { + const user = await requireAuth(); + + return ( +
+
+
+

Dashboard

+ +
+ +
+
+ +
+

User Information

+ +
+
+
Email
+
{user.email}
+
+ +
+
User ID
+
{user.id}
+
+ +
+
+ Email Verified +
+
+ {user.email_confirmed_at ? 'Yes' : 'No'} +
+
+ +
+
+ Last Sign In +
+
+ {user.last_sign_in_at + ? new Date(user.last_sign_in_at).toLocaleString() + : 'N/A'} +
+
+
+
+ +
+

+ This is a protected page. You can only access it when authenticated. +

+
+
+
+ ); +} diff --git a/skills/supabase-auth-ssr-setup/assets/login-page.tsx b/skills/supabase-auth-ssr-setup/assets/login-page.tsx new file mode 100644 index 0000000..c5c3fa1 --- /dev/null +++ b/skills/supabase-auth-ssr-setup/assets/login-page.tsx @@ -0,0 +1,134 @@ +import { signInWithPassword, signInWithMagicLink } from '@/app/actions/auth'; +import { createServerClient } from '@/lib/supabase/server'; +import { redirect } from 'next/navigation'; + +export default async function LoginPage({ + searchParams, +}: { + searchParams: { redirect?: string; error?: string }; +}) { + // Check if user is already logged in + const supabase = await createServerClient(); + const { + data: { user }, + } = await supabase.auth.getUser(); + + if (user) { + redirect(searchParams.redirect || '/dashboard'); + } + + return ( +
+
+
+

Sign in

+

+ Access your account +

+
+ + {searchParams.error && ( +
+

{searchParams.error}

+
+ )} + + {/* Email/Password Form */} +
+
+ + +
+ +
+ + +
+ + +
+ +
+
+
+
+
+ Or +
+
+ + {/* Magic Link Form */} +
+
+ + +
+ + +
+ + {/* OAuth Providers - Uncomment to enable */} + {/* +
+ + + +
+ */} + + +
+
+ ); +} diff --git a/skills/supabase-auth-ssr-setup/assets/middleware.ts b/skills/supabase-auth-ssr-setup/assets/middleware.ts new file mode 100644 index 0000000..c9c06c6 --- /dev/null +++ b/skills/supabase-auth-ssr-setup/assets/middleware.ts @@ -0,0 +1,28 @@ +import { type NextRequest } from 'next/server'; +import { updateSession } from '@/lib/supabase/middleware'; + +export async function middleware(request: NextRequest) { + const { supabaseResponse, user } = await updateSession(request); + + // If accessing protected route without authentication, redirect to login + if (!user && request.nextUrl.pathname.startsWith('/dashboard')) { + const redirectUrl = new URL('/login', request.url); + redirectUrl.searchParams.set('redirect', request.nextUrl.pathname); + return Response.redirect(redirectUrl); + } + + return supabaseResponse; +} + +export const config = { + matcher: [ + /* + * Match all request paths except for the ones starting with: + * - _next/static (static files) + * - _next/image (image optimization files) + * - favicon.ico (favicon file) + * - public folder + */ + '/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)', + ], +}; diff --git a/skills/supabase-auth-ssr-setup/assets/supabase-client.ts b/skills/supabase-auth-ssr-setup/assets/supabase-client.ts new file mode 100644 index 0000000..e6db2a1 --- /dev/null +++ b/skills/supabase-auth-ssr-setup/assets/supabase-client.ts @@ -0,0 +1,8 @@ +import { createBrowserClient } from '@supabase/ssr'; + +export function createClient() { + return createBrowserClient( + process.env.NEXT_PUBLIC_SUPABASE_URL!, + process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY! + ); +} diff --git a/skills/supabase-auth-ssr-setup/assets/supabase-middleware.ts b/skills/supabase-auth-ssr-setup/assets/supabase-middleware.ts new file mode 100644 index 0000000..408bc37 --- /dev/null +++ b/skills/supabase-auth-ssr-setup/assets/supabase-middleware.ts @@ -0,0 +1,38 @@ +import { createServerClient } from '@supabase/ssr'; +import { NextResponse, type NextRequest } from 'next/server'; + +export async function updateSession(request: NextRequest) { + let supabaseResponse = NextResponse.next({ + request, + }); + + const supabase = createServerClient( + process.env.NEXT_PUBLIC_SUPABASE_URL!, + process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!, + { + cookies: { + getAll() { + return request.cookies.getAll(); + }, + setAll(cookiesToSet) { + cookiesToSet.forEach(({ name, value, options }) => { + request.cookies.set(name, value); + }); + supabaseResponse = NextResponse.next({ + request, + }); + cookiesToSet.forEach(({ name, value, options }) => { + supabaseResponse.cookies.set(name, value, options); + }); + }, + }, + } + ); + + // Refresh session if expired - required for Server Components + const { + data: { user }, + } = await supabase.auth.getUser(); + + return { supabaseResponse, user }; +} diff --git a/skills/supabase-auth-ssr-setup/assets/supabase-server.ts b/skills/supabase-auth-ssr-setup/assets/supabase-server.ts new file mode 100644 index 0000000..01ccae5 --- /dev/null +++ b/skills/supabase-auth-ssr-setup/assets/supabase-server.ts @@ -0,0 +1,29 @@ +import { createServerClient as createSSRServerClient } from '@supabase/ssr'; +import { cookies } from 'next/headers'; + +export async function createServerClient() { + const cookieStore = await cookies(); + + return createSSRServerClient( + process.env.NEXT_PUBLIC_SUPABASE_URL!, + process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!, + { + cookies: { + getAll() { + return cookieStore.getAll(); + }, + setAll(cookiesToSet) { + try { + cookiesToSet.forEach(({ name, value, options }) => { + cookieStore.set(name, value, options); + }); + } catch { + // The `setAll` method was called from a Server Component. + // This can be ignored if you have middleware refreshing + // user sessions. + } + }, + }, + } + ); +} diff --git a/skills/supabase-auth-ssr-setup/references/authentication-patterns.md b/skills/supabase-auth-ssr-setup/references/authentication-patterns.md new file mode 100644 index 0000000..98c0df7 --- /dev/null +++ b/skills/supabase-auth-ssr-setup/references/authentication-patterns.md @@ -0,0 +1,252 @@ +# Authentication Patterns for Next.js + Supabase + +## Common Authentication Patterns + +### Pattern 1: Protected Route Groups + +Use Next.js route groups to protect multiple routes with a single layout: + +``` +app/ +├── (public)/ +│ ├── layout.tsx # Public layout +│ ├── page.tsx # Home page +│ └── about/ +│ └── page.tsx # About page +└── (protected)/ + ├── layout.tsx # Protected layout with requireAuth() + ├── dashboard/ + │ └── page.tsx + └── settings/ + └── page.tsx +``` + +**Protected layout example:** +```typescript +// app/(protected)/layout.tsx +import { requireAuth } from '@/lib/auth/utils'; + +export default async function ProtectedLayout({ + children, +}: { + children: React.ReactNode; +}) { + await requireAuth(); + return <>{children}; +} +``` + +All routes inside `(protected)` automatically require authentication. + +### Pattern 2: Conditional UI Based on Auth State + +Show different content based on whether user is authenticated: + +```typescript +import { getCurrentUser } from '@/lib/auth/utils'; + +export default async function HomePage() { + const user = await getCurrentUser(); + + return ( +
+ {user ? ( +
+

Welcome back, {user.email}!

+ Go to Dashboard +
+ ) : ( +
+

Welcome to our app

+ Sign in +
+ )} +
+ ); +} +``` + +### Pattern 3: Role-Based Access Control + +Protect routes based on user roles: + +```typescript +// lib/auth/utils.ts - Add role checking +export async function requireRole(allowedRoles: string[]) { + const user = await requireAuth(); + const supabase = await createServerClient(); + + const { data: profile } = await supabase + .from('profiles') + .select('role') + .eq('id', user.id) + .single(); + + if (!profile || !allowedRoles.includes(profile.role)) { + redirect('/unauthorized'); + } + + return { user, profile }; +} +``` + +**Usage in admin page:** +```typescript +export default async function AdminPage() { + await requireRole(['admin', 'moderator']); + + return
Admin Dashboard
; +} +``` + +### Pattern 4: Server Action Authentication + +Protect Server Actions that modify data: + +```typescript +'use server'; + +import { requireAuth } from '@/lib/auth/utils'; +import { createServerClient } from '@/lib/supabase/server'; +import { revalidatePath } from 'next/cache'; + +export async function createPost(formData: FormData) { + const user = await requireAuth(); + const supabase = await createServerClient(); + + const title = formData.get('title') as string; + const content = formData.get('content') as string; + + const { error } = await supabase.from('posts').insert({ + title, + content, + author_id: user.id, + }); + + if (error) throw error; + + revalidatePath('/posts'); +} +``` + +### Pattern 5: API Route Authentication + +Protect API routes for external access: + +```typescript +// app/api/protected/route.ts +import { createServerClient } from '@/lib/supabase/server'; +import { NextResponse } from 'next/server'; + +export async function GET() { + const supabase = await createServerClient(); + const { + data: { user }, + } = await supabase.auth.getUser(); + + if (!user) { + return NextResponse.json({ error: 'Unauthorized' }, { status: 401 }); + } + + // Return protected data + return NextResponse.json({ data: 'Protected data' }); +} +``` + +### Pattern 6: Parallel Data Fetching with Auth + +Fetch user and their data in parallel: + +```typescript +export default async function ProfilePage() { + const user = await requireAuth(); + + const supabase = await createServerClient(); + + // Fetch user profile and posts in parallel + const [{ data: profile }, { data: posts }] = await Promise.all([ + supabase.from('profiles').select('*').eq('id', user.id).single(), + supabase.from('posts').select('*').eq('author_id', user.id), + ]); + + return ( +
+

{profile?.name}

+

Posts

+ {posts?.map((post) => ( +
{post.title}
+ ))} +
+ ); +} +``` + +### Pattern 7: Redirect After Login + +Preserve intended destination after login: + +**Middleware:** +```typescript +export async function middleware(request: NextRequest) { + const { supabaseResponse, user } = await updateSession(request); + + if (!user && request.nextUrl.pathname.startsWith('/dashboard')) { + const redirectUrl = new URL('/login', request.url); + // Save the intended destination + redirectUrl.searchParams.set('redirect', request.nextUrl.pathname); + return Response.redirect(redirectUrl); + } + + return supabaseResponse; +} +``` + +**Login page:** +```typescript +export default async function LoginPage({ + searchParams, +}: { + searchParams: { redirect?: string }; +}) { + // After successful login, redirect to intended page + const redirectTo = searchParams.redirect || '/dashboard'; + + // Use redirectTo in form action or success handler +} +``` + +### Pattern 8: Email Verification Check + +Require email verification before accessing certain features: + +```typescript +export async function requireVerifiedEmail() { + const user = await requireAuth(); + + if (!user.email_confirmed_at) { + redirect('/verify-email'); + } + + return user; +} +``` + +## Best Practices + +1. **Use Server Components for Auth Checks**: Leverage Server Components for initial auth checks to avoid client-side flashing +2. **Middleware for Session Refresh**: Always refresh sessions in middleware to keep auth state fresh +3. **Revalidate After Auth Changes**: Use `revalidatePath()` after login/logout to clear cached content +4. **Secure Cookie Configuration**: Ensure cookies use secure, httpOnly, and sameSite settings +5. **Handle Auth Errors Gracefully**: Provide clear error messages and recovery paths +6. **Use TypeScript**: Type your user objects and auth functions for better DX +7. **Test Protected Routes**: Verify both authenticated and unauthenticated access +8. **Implement Proper Redirects**: Always redirect after authentication changes to prevent stale UI + +## Anti-Patterns to Avoid + +1. **Client-Side Only Auth**: Don't rely solely on client-side auth checks +2. **Checking Auth on Every Component**: Use layouts and route groups instead +3. **Exposing Sensitive Data**: Never send sensitive data to client without auth check +4. **Hardcoded Redirects**: Use dynamic redirects based on user intent +5. **Ignoring Middleware**: Always use middleware for session refresh +6. **Not Handling Loading States**: Show appropriate loading states during auth checks diff --git a/skills/supabase-auth-ssr-setup/references/security-considerations.md b/skills/supabase-auth-ssr-setup/references/security-considerations.md new file mode 100644 index 0000000..6eb4226 --- /dev/null +++ b/skills/supabase-auth-ssr-setup/references/security-considerations.md @@ -0,0 +1,300 @@ +# Security Considerations for Supabase Auth + +## Cookie Security + +### Secure Cookie Configuration + +The `@supabase/ssr` package automatically configures secure cookies with these settings: + +- **httpOnly**: Prevents client-side JavaScript from accessing cookies +- **secure**: Cookies only sent over HTTPS (except localhost) +- **sameSite**: Prevents CSRF attacks by restricting cross-site cookie sending +- **path**: Limits cookie scope to specific paths + +**Do not modify** cookie settings unless you understand the security implications. + +### Session Duration + +Configure session timeout in Supabase dashboard: + +1. Go to Authentication > Settings +2. Adjust "JWT expiry limit" (default: 1 hour) +3. Set "Refresh token expiry" (default: 30 days) + +**Recommendations:** +- Short JWT expiry (1 hour) for better security +- Longer refresh token expiry (30 days) for better UX +- Use middleware to automatically refresh sessions + +## Row Level Security (RLS) + +### Enable RLS on All Tables + +Always enable Row Level Security on tables containing user data: + +```sql +ALTER TABLE profiles ENABLE ROW LEVEL SECURITY; +``` + +### Create Restrictive Policies + +**Read own data:** +```sql +CREATE POLICY "Users can view own profile" +ON profiles FOR SELECT +USING (auth.uid() = id); +``` + +**Update own data:** +```sql +CREATE POLICY "Users can update own profile" +ON profiles FOR UPDATE +USING (auth.uid() = id); +``` + +**Insert on signup:** +```sql +CREATE POLICY "Users can insert own profile" +ON profiles FOR INSERT +WITH CHECK (auth.uid() = id); +``` + +### Test RLS Policies + +Always test policies with different user contexts: + +```sql +-- Test as specific user +SET LOCAL ROLE authenticated; +SET LOCAL request.jwt.claims.sub = 'user-uuid-here'; + +-- Run queries to verify access +SELECT * FROM profiles; +``` + +## Authentication Best Practices + +### 1. Never Trust Client Input + +Always validate on server-side: + +```typescript +export async function updateProfile(formData: FormData) { + const user = await requireAuth(); + + // Validate input + const name = formData.get('name') as string; + if (!name || name.length < 2) { + throw new Error('Invalid name'); + } + + // Only update own profile + const supabase = await createServerClient(); + await supabase + .from('profiles') + .update({ name }) + .eq('id', user.id); // Ensure user can only update their own data +} +``` + +### 2. Use Server Components for Sensitive Data + +Fetch sensitive data in Server Components, not Client Components: + +```typescript +// [OK] Good - Server Component +export default async function ProfilePage() { + const user = await requireAuth(); + const supabase = await createServerClient(); + + const { data: privateData } = await supabase + .from('private_table') + .select('*') + .eq('user_id', user.id); + + return
{/* Use privateData */}
; +} +``` + +```typescript +// [ERROR] Bad - Client Component exposes API +'use client'; + +export default function ProfilePage() { + const [data, setData] = useState(null); + + useEffect(() => { + // Fetching sensitive data on client + fetch('/api/private-data').then(/* ... */); + }, []); +} +``` + +### 3. Implement Rate Limiting + +Protect authentication endpoints from brute force: + +```typescript +// Example using Upstash Rate Limit +import { Ratelimit } from '@upstash/ratelimit'; +import { Redis } from '@upstash/redis'; + +const ratelimit = new Ratelimit({ + redis: Redis.fromEnv(), + limiter: Ratelimit.slidingWindow(5, '15 m'), // 5 attempts per 15 minutes +}); + +export async function signInWithPassword(formData: FormData) { + const email = formData.get('email') as string; + + const { success } = await ratelimit.limit(email); + if (!success) { + return { error: 'Too many attempts. Please try again later.' }; + } + + // Proceed with sign in +} +``` + +### 4. Validate Email Addresses + +Require email verification before granting full access: + +```typescript +export async function requireVerifiedEmail() { + const user = await requireAuth(); + + if (!user.email_confirmed_at) { + redirect('/verify-email'); + } + + return user; +} +``` + +Configure in Supabase: +- Authentication > Settings > Enable "Confirm email" +- Customize email templates in Authentication > Email Templates + +### 5. Use Environment Variables Correctly + +**Public variables** (safe to expose): +- `NEXT_PUBLIC_SUPABASE_URL` +- `NEXT_PUBLIC_SUPABASE_ANON_KEY` + +**Private variables** (server-side only): +- `SUPABASE_SERVICE_ROLE_KEY` (never expose to client!) + +```typescript +// [OK] Good - Service role only on server +'use server'; + +import { createClient } from '@supabase/supabase-js'; + +export async function adminFunction() { + const supabase = createClient( + process.env.NEXT_PUBLIC_SUPABASE_URL!, + process.env.SUPABASE_SERVICE_ROLE_KEY! // Only accessible server-side + ); + + // Bypasses RLS - use carefully +} +``` + +## Common Security Mistakes + +### 1. Exposing Service Role Key + +[ERROR] **Never** use service role key in client-side code: + +```typescript +// [ERROR] DANGEROUS - Exposes admin access +const supabase = createClient( + process.env.NEXT_PUBLIC_SUPABASE_URL, + process.env.SUPABASE_SERVICE_ROLE_KEY // Exposed to client! +); +``` + +### 2. Skipping RLS + +[ERROR] **Never** disable RLS or use service role to bypass it unnecessarily: + +```sql +-- [ERROR] DANGEROUS - Allows anyone to read all data +ALTER TABLE profiles DISABLE ROW LEVEL SECURITY; +``` + +### 3. Client-Side Authorization + +[ERROR] **Never** rely only on client-side checks: + +```typescript +// [ERROR] BAD - Can be bypassed +'use client'; + +export default function AdminPanel() { + const [user, setUser] = useState(null); + + if (user?.role !== 'admin') { + return
Unauthorized
; + } + + return
Admin content
; // Still rendered in HTML! +} +``` + +[OK] **Always** enforce on server: + +```typescript +// [OK] GOOD - Server-side enforcement +export default async function AdminPanel() { + await requireRole('admin'); // Redirects if not admin + + return
Admin content
; +} +``` + +### 4. Not Revalidating After Auth Changes + +[ERROR] **Never** forget to revalidate after login/logout: + +```typescript +// [ERROR] BAD - Stale cached content may show +export async function logout() { + const supabase = await createServerClient(); + await supabase.auth.signOut(); + redirect('/'); // Missing revalidation! +} +``` + +[OK] **Always** revalidate: + +```typescript +// [OK] GOOD +export async function logout() { + const supabase = await createServerClient(); + await supabase.auth.signOut(); + revalidatePath('/', 'layout'); // Clears all cached pages + redirect('/'); +} +``` + +## Audit Checklist + +Use this checklist when implementing authentication: + +- [ ] RLS enabled on all tables with user data +- [ ] RLS policies tested with different user contexts +- [ ] Service role key never exposed to client +- [ ] Email verification required for sensitive actions +- [ ] Rate limiting on authentication endpoints +- [ ] Input validation on all Server Actions +- [ ] Secure cookies configured (httpOnly, secure, sameSite) +- [ ] Middleware refreshes sessions on all requests +- [ ] Sensitive data only fetched in Server Components +- [ ] Authorization checks on server-side, not client-side +- [ ] Proper revalidation after auth state changes +- [ ] Error messages don't leak sensitive information +- [ ] OAuth redirect URLs configured correctly +- [ ] Session timeout appropriate for use case +- [ ] Logout clears all auth state and cookies