Authentication & Access Control

This skill provides workflows for implementing authentication and access control in this Next.js 15 + Supabase application using server-side auth with httpOnly cookies, hybrid route protection, and multi-tenant family-based data isolation.

System Overview

• Auth Provider: Supabase Auth with httpOnly cookies
• Architecture: Next.js 15 App Router with Server Components and Server Actions
• Route Protection: Hybrid approach (page-level auth checks, not middleware-only)
• Multi-Tenancy: Family-based data isolation with RLS policies
• Roles: Admin (first user in family) and Member

Core Workflows

Protecting a New Route

To protect a route from unauthenticated users:

1. Import requireAuthRedirect from @/lib/auth/server-auth
2. Call await requireAuthRedirect() at the start of the component
3. User will be redirected to /login if not authenticated

import { requireAuthRedirect } from '@/lib/auth/server-auth';

export default async function ProtectedPage() {
  await requireAuthRedirect();

  // User guaranteed authenticated here
  return <YourContent />;
}

To protect an entire route group, add this to the layout component. All child routes will inherit the protection.

Protecting a Server Action

To require authentication in a Server Action:

1. Import requireAuth from @/lib/auth/server-auth
2. Call const user = await requireAuth() at the start of the action
3. Action will throw UnauthorizedError if user not authenticated

'use server';
import { requireAuth } from '@/lib/auth/server-auth';

export async function myAction() {
  const user = await requireAuth();

  // Proceed with authenticated action
}

Getting Current User Data

• getCurrentUser() - Auth user (email, id), returns null if not logged in
• getUserData() - Extended profile (role, familyId, firstName, lastName, active)
• getCurrentFamilyId() - Just the family ID

All use React cache() - multiple calls in same request return cached value.

Implementing Admin-Only Features

To restrict a page to admins:

import { requireAdminRedirect } from '@/lib/auth/server-auth';

export default async function AdminPage() {
  await requireAdminRedirect();

  // User guaranteed to be admin
  return <AdminPanel />;
}

To restrict a Server Action to admins:

'use server';
import { requireAdmin } from '@/lib/auth/server-auth';

export async function adminAction() {
  await requireAdmin(); // Throws if not admin
  // Proceed
}

To conditionally show admin UI:

import { isAdmin } from '@/lib/auth/server-auth';

export default async function Page() {
  const userIsAdmin = await isAdmin();

  return (
    <>
      <RegularContent />
      {userIsAdmin && <AdminControls />}
    </>
  );
}

Enforcing Multi-Tenant Data Access

To ensure users only access their own family's data:

'use server';
import { requireFamilyAccess } from '@/lib/auth/server-auth';

export async function updateFamilyData(familyId: string, data: any) {
  await requireFamilyAccess(familyId); // Throws if user not in this family

  // User guaranteed to belong to this family
  await updateDatabase(familyId, data);
}

When fetching current user's family data, use getCurrentFamilyId() instead - no need for requireFamilyAccess since it's their own family.

Adding a New Authentication Page

To create a new auth page (login, register, password reset):

1. Create page under src/app/(auth)/page-name/
2. The (auth) group layout automatically redirects authenticated users to /dashboard
3. Create corresponding Server Action in actions.ts file
4. Import and use Supabase client: const supabase = await createClient()

Pages in (auth) group are automatically protected from authenticated users - they'll be redirected to dashboard if already logged in.

Implementing Login/Logout

Use supabase.auth.signInWithPassword() for login and supabase.auth.signOut() for logout. See references/patterns.md for complete code examples.

Adding OAuth Providers

1. Enable provider in Supabase Dashboard
2. Use supabase.auth.signInWithOAuth({ provider: 'github', options: {...} })
3. Callback handled automatically by src/app/auth/callback/route.ts

See references/patterns.md for full implementation examples.

Security Requirements

Token Validation

• Always use supabase.auth.getUser() to validate tokens (revalidates with server)
• Never use supabase.auth.getSession() in server code (can be spoofed)

Server-Side Only

• All auth helpers in src/lib/auth/server-auth.ts are server-side only
• Never import these in Client Components
• Never add 'use server' directive to server-auth.ts (breaks class exports)

Middleware

• Middleware automatically refreshes tokens on every request
• Uses updateSession() from src/lib/supabase/middleware.ts
• Calls getUser() to revalidate tokens
• No additional token refresh logic needed

Reference Files

For detailed information, see:

• references/file-tree.md - Complete file structure and organization
• references/security.md - Security best practices and requirements
• references/patterns.md - Code examples and common patterns
• references/flows.md - Authentication flow diagrams

Quick Reference

Key Files: src/lib/auth/server-auth.ts (helpers), src/middleware.ts (token refresh), src/app/dashboard/layout.tsx (dashboard protection)

Environment: NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY, NEXT_PUBLIC_SITE_URL

Database: auth.users (Supabase auth), public.families (households), public.users (profiles)

Common Issues

'use server' export error: Remove 'use server' from server-auth.ts - these are utilities, not actions

Middleware redirect fails: Use requireAuth() in Server Actions - middleware redirects don't work with POST

Multi-tenant access denied: Use requireFamilyAccess(familyId) to validate family ownership