zhongwei/gh-hopeoverture-worldbuilding-app-skills-plugins-supabase-auth-ssr-setup
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:46:51 +08:00
commit 26a675f3a7
15 changed files with 1450 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.claude-plugin/plugin.json Normal file
View File

@@ -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"
]
}

3
README.md Normal file
View File

@@ -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.

89
plugin.lock.json Normal file
View File

@@ -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": []
}
}

296
skills/supabase-auth-ssr-setup/SKILL.md Normal file
View File

@@ -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';
<button onClick={() => logout()}>
Sign Out
</button>
```
### 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 <div>Hello {user.email}</div>;
}
```
### 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 (
<div>
{user ? `Welcome ${user.email}` : 'Please log in'}
</div>
);
}
```
## 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

98
skills/supabase-auth-ssr-setup/assets/auth-actions.ts Normal file
View File

@@ -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' };
}

29
skills/supabase-auth-ssr-setup/assets/auth-callback-route.ts Normal file
View File

@@ -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`);
}

67
skills/supabase-auth-ssr-setup/assets/auth-utils.ts Normal file
View File

@@ -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<boolean> {
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;
}

67
skills/supabase-auth-ssr-setup/assets/dashboard-page.tsx Normal file
View File

@@ -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 (
<div className="min-h-screen p-8">
<div className="mx-auto max-w-4xl">
<div className="mb-8 flex items-center justify-between">
<h1 className="text-3xl font-bold">Dashboard</h1>
<form action={logout}>
<button
type="submit"
className="rounded-md border border-gray-300 px-4 py-2 hover:bg-gray-50"
>
Sign out
</button>
</form>
</div>
<div className="rounded-lg border p-6">
<h2 className="mb-4 text-xl font-semibold">User Information</h2>
<dl className="space-y-2">
<div>
<dt className="text-sm font-medium text-gray-500">Email</dt>
<dd className="text-base">{user.email}</dd>
</div>
<div>
<dt className="text-sm font-medium text-gray-500">User ID</dt>
<dd className="font-mono text-sm">{user.id}</dd>
</div>
<div>
<dt className="text-sm font-medium text-gray-500">
Email Verified
</dt>
<dd className="text-base">
{user.email_confirmed_at ? 'Yes' : 'No'}
</dd>
</div>
<div>
<dt className="text-sm font-medium text-gray-500">
Last Sign In
</dt>
<dd className="text-base">
{user.last_sign_in_at
? new Date(user.last_sign_in_at).toLocaleString()
: 'N/A'}
</dd>
</div>
</dl>
</div>
<div className="mt-6 rounded-lg bg-blue-50 p-4">
<p className="text-sm text-blue-900">
This is a protected page. You can only access it when authenticated.
</p>
</div>
</div>
</div>
);
}

134
skills/supabase-auth-ssr-setup/assets/login-page.tsx Normal file
View File

@@ -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 (
<div className="flex min-h-screen items-center justify-center">
<div className="w-full max-w-md space-y-8 rounded-lg border p-8">
<div>
<h2 className="text-center text-3xl font-bold">Sign in</h2>
<p className="mt-2 text-center text-sm text-gray-600">
Access your account
</p>
</div>
{searchParams.error && (
<div className="rounded-md bg-red-50 p-4">
<p className="text-sm text-red-800">{searchParams.error}</p>
</div>
)}
{/* Email/Password Form */}
<form action={signInWithPassword} className="space-y-6">
<div>
<label htmlFor="email" className="block text-sm font-medium">
Email address
</label>
<input
id="email"
name="email"
type="email"
autoComplete="email"
required
className="mt-1 block w-full rounded-md border border-gray-300 px-3 py-2"
/>
</div>
<div>
<label htmlFor="password" className="block text-sm font-medium">
Password
</label>
<input
id="password"
name="password"
type="password"
autoComplete="current-password"
required
className="mt-1 block w-full rounded-md border border-gray-300 px-3 py-2"
/>
</div>
<button
type="submit"
className="w-full rounded-md bg-blue-600 px-4 py-2 text-white hover:bg-blue-700"
>
Sign in with email
</button>
</form>
<div className="relative">
<div className="absolute inset-0 flex items-center">
<div className="w-full border-t border-gray-300" />
</div>
<div className="relative flex justify-center text-sm">
<span className="bg-white px-2 text-gray-500">Or</span>
</div>
</div>
{/* Magic Link Form */}
<form action={signInWithMagicLink} className="space-y-4">
<div>
<label htmlFor="magic-email" className="block text-sm font-medium">
Email for magic link
</label>
<input
id="magic-email"
name="email"
type="email"
autoComplete="email"
required
className="mt-1 block w-full rounded-md border border-gray-300 px-3 py-2"
/>
</div>
<button
type="submit"
className="w-full rounded-md border border-gray-300 bg-white px-4 py-2 hover:bg-gray-50"
>
Send magic link
</button>
</form>
{/* OAuth Providers - Uncomment to enable */}
{/*
<div className="space-y-2">
<button
onClick={() => signInWithOAuth('google')}
className="w-full rounded-md border border-gray-300 bg-white px-4 py-2 hover:bg-gray-50"
>
Continue with Google
</button>
<button
onClick={() => signInWithOAuth('github')}
className="w-full rounded-md border border-gray-300 bg-white px-4 py-2 hover:bg-gray-50"
>
Continue with GitHub
</button>
</div>
*/}
<div className="text-center text-sm">
<a href="/signup" className="text-blue-600 hover:underline">
Don't have an account? Sign up
</a>
</div>
</div>
</div>
);
}

28
skills/supabase-auth-ssr-setup/assets/middleware.ts Normal file
View File

@@ -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)$).*)',
],
};

8
skills/supabase-auth-ssr-setup/assets/supabase-client.ts Normal file
View File

@@ -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!
);
}

38
skills/supabase-auth-ssr-setup/assets/supabase-middleware.ts Normal file
View File

@@ -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 };
}

29
skills/supabase-auth-ssr-setup/assets/supabase-server.ts Normal file
View File

@@ -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.
}
},
},
}
);
}

252
skills/supabase-auth-ssr-setup/references/authentication-patterns.md Normal file
View File

@@ -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 (
<div>
{user ? (
<div>
<h1>Welcome back, {user.email}!</h1>
<a href="/dashboard">Go to Dashboard</a>
</div>
) : (
<div>
<h1>Welcome to our app</h1>
<a href="/login">Sign in</a>
</div>
)}
</div>
);
}
```
### 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 <div>Admin Dashboard</div>;
}
```
### 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 (
<div>
<h1>{profile?.name}</h1>
<h2>Posts</h2>
{posts?.map((post) => (
<div key={post.id}>{post.title}</div>
))}
</div>
);
}
```
### 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

300
skills/supabase-auth-ssr-setup/references/security-considerations.md Normal file
View File

@@ -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 <div>{/* Use privateData */}</div>;
}
```
```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 <div>Unauthorized</div>;
}
return <div>Admin content</div>; // 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 <div>Admin content</div>;
}
```
### 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