leopost/.planning/phases/01-foundation-auth/01-RESEARCH.md

Phase 1: Foundation & Auth - Research

Researched: 2026-01-31 Domain: Authentication, Multi-Tenancy, Subscription Management Confidence: HIGH

Summary

Phase 1 establishes the authentication foundation using Supabase Auth integrated with Next.js 14 App Router. The research confirms that Supabase provides a production-ready authentication system with built-in email/password and OAuth support, session management, and Row Level Security (RLS) for multi-tenant data isolation.

The standard approach uses cookie-based authentication via the @supabase/ssr package (replacing the deprecated @supabase/auth-helpers-nextjs), with separate client patterns for Server Components vs Client Components. RLS policies enforce tenant isolation at the database level, with tenant_id stored in JWT app_metadata for optimal performance.

Subscription plans are modeled using a simple database schema: plans table for tier definitions (Free/Creator/Pro), user_profiles table linking users to their plan, and feature limits stored as JSONB for flexibility. The architecture follows a "defense in depth" strategy: RLS for baseline security, application logic for business rules, and middleware for route protection.

Primary recommendation: Use Supabase's official @supabase/ssr package with cookie-based auth, implement RLS policies from day one (never skip this), store tenant_id in JWT app_metadata for performance, and model plans as database tables with JSONB for feature limits.

Standard Stack

The established libraries/tools for Supabase Auth with Next.js 14:

Core

Library	Version	Purpose	Why Standard
@supabase/supabase-js	Latest	Supabase client SDK	Official JavaScript client for all Supabase features
@supabase/ssr	Latest	Server-side rendering support	Official package for Next.js App Router (replaces deprecated auth-helpers)
Next.js	14+	Frontend framework	App Router required for modern auth patterns
PostgreSQL	15+	Database	Supabase's underlying database with RLS support

Supporting

Library	Version	Purpose	When to Use
zod	3.x	Schema validation	Validate registration/login forms, password requirements
react-hook-form	7.x	Form management	Handle auth forms with validation
@supabase/auth-ui-react	Latest	Pre-built auth UI	Optional: rapid prototyping (customization limited)

Alternatives Considered

Instead of	Could Use	Tradeoff
Supabase Auth	NextAuth.js (Auth.js)	More provider flexibility, but requires managing database schema, no RLS integration
Supabase Auth	Clerk	Better UX, but expensive ($25/mo for 10k users vs Supabase free 50k MAU), vendor lock-in
Cookie-based sessions	JWT in localStorage	Faster client-side checks, but vulnerable to XSS attacks, no SSR support

Installation:

npm install @supabase/supabase-js @supabase/ssr zod react-hook-form

Architecture Patterns

Recommended Project Structure

app/
├── (auth)/              # Auth route group (unauthenticated layout)
│   ├── login/
│   ├── register/
│   ├── verify-email/
│   └── reset-password/
├── (dashboard)/         # Protected route group (authenticated layout)
│   ├── settings/
│   └── subscription/
├── api/
│   └── auth/
│       └── callback/    # OAuth callback handler
└── actions/             # Server Actions for auth operations
    └── auth.ts

lib/
├── supabase/
│   ├── client.ts        # Client Component client
│   ├── server.ts        # Server Component client
│   └── middleware.ts    # Middleware helper
└── schemas/
    └── auth.ts          # Zod validation schemas

middleware.ts            # Route protection + session refresh

Pattern 1: Dual Client Creation

What: Create separate Supabase client instances for Client Components vs Server Components When to use: Always - Next.js App Router runs code in two environments (browser and server)

Example:

// lib/supabase/client.ts (Client Components)
import { createBrowserClient } from '@supabase/ssr'

export function createClient() {
  return createBrowserClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
  )
}

// lib/supabase/server.ts (Server Components, Route Handlers, Server Actions)
import { createServerClient } from '@supabase/ssr'
import { cookies } from 'next/headers'

export async function createClient() {
  const cookieStore = await cookies()

  return createServerClient(
    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.
          }
        },
      },
    }
  )
}

Source: Supabase Server-Side Auth for Next.js

Pattern 2: Middleware Session Refresh

What: Use middleware to refresh user sessions on every request and protect routes When to use: MANDATORY - without this, sessions expire and authentication breaks

Example:

// middleware.ts
import { type NextRequest } from 'next/server'
import { updateSession } from '@/lib/supabase/middleware'

export async function middleware(request: NextRequest) {
  return await updateSession(request)
}

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
  ],
}

// lib/supabase/middleware.ts
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
  const { data: { user } } = await supabase.auth.getUser()

  // Protect routes
  if (!user && request.nextUrl.pathname.startsWith('/dashboard')) {
    const url = request.nextUrl.clone()
    url.pathname = '/login'
    return NextResponse.redirect(url)
  }

  return supabaseResponse
}

Source: Supabase Auth with Next.js App Router

Pattern 3: RLS Policies for Multi-Tenancy

What: Use Row Level Security policies to enforce tenant isolation at database level When to use: ALWAYS - this is the security foundation, never skip RLS

Example:

-- Enable RLS on all tables in public schema
ALTER TABLE profiles ENABLE ROW LEVEL SECURITY;
ALTER TABLE posts ENABLE ROW LEVEL SECURITY;

-- Helper function to get tenant_id from JWT
CREATE OR REPLACE FUNCTION auth.tenant_id()
RETURNS TEXT
LANGUAGE SQL STABLE
AS $$
  SELECT NULLIF(
    ((current_setting('request.jwt.claims')::jsonb ->> 'app_metadata')::jsonb ->> 'tenant_id'),
    ''
  )::TEXT
$$;

-- RLS Policy: Users can only access their tenant's data
CREATE POLICY "Tenant isolation"
ON profiles
FOR ALL
USING (tenant_id = (SELECT auth.tenant_id()));

-- RLS Policy: Users can only INSERT with their tenant_id
CREATE POLICY "Insert with tenant"
ON profiles
FOR INSERT
WITH CHECK (tenant_id = (SELECT auth.tenant_id()));

-- Important: Wrap auth functions in SELECT for 99% performance improvement
-- Good: (SELECT auth.uid()) = user_id
-- Bad: auth.uid() = user_id

Source: Supabase Row Level Security

Pattern 4: Subscription Plans Schema

What: Database schema for plans, user subscriptions, and feature limits When to use: For any SaaS with tiered pricing

Example:

-- Plans table (Free, Creator, Pro)
CREATE TABLE plans (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name TEXT NOT NULL UNIQUE, -- 'free', 'creator', 'pro'
  display_name TEXT NOT NULL, -- 'Free Plan', 'Creator Plan', 'Pro Plan'
  price_monthly INTEGER NOT NULL, -- in cents (0, 1900, 4900)
  features JSONB NOT NULL, -- Flexible feature limits
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Example plan features JSONB:
-- {
--   "posts_per_month": 10,
--   "ai_models": ["gpt-4o-mini"],
--   "social_accounts": 1,
--   "analytics": false
-- }

-- User profiles with plan assignment
CREATE TABLE profiles (
  id UUID PRIMARY KEY REFERENCES auth.users(id) ON DELETE CASCADE,
  tenant_id UUID NOT NULL, -- For multi-tenancy
  plan_id UUID REFERENCES plans(id) NOT NULL,
  email TEXT NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Index for tenant isolation (critical for performance)
CREATE INDEX idx_profiles_tenant_id ON profiles(tenant_id);

-- RLS policies
ALTER TABLE profiles ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Users can read own profile"
ON profiles FOR SELECT
USING ((SELECT auth.uid()) = id);

CREATE POLICY "Users can update own profile"
ON profiles FOR UPDATE
USING ((SELECT auth.uid()) = id)
WITH CHECK ((SELECT auth.uid()) = id);

Source: Multi-tenant SaaS model with PostgreSQL

Pattern 5: Email Verification Flow (PKCE)

What: Secure email verification using PKCE flow for SSR apps When to use: When email verification is mandatory (as per phase requirements)

Example:

// app/actions/auth.ts
'use server'

import { createClient } from '@/lib/supabase/server'
import { z } from 'zod'

const registerSchema = z.object({
  email: z.string().email('Email non valida'),
  password: z.string()
    .min(8, 'Minimo 8 caratteri')
    .regex(/[0-9]/, 'Deve contenere almeno un numero')
    .regex(/[A-Z]/, 'Deve contenere almeno una maiuscola'),
})

export async function register(formData: FormData) {
  const supabase = await createClient()

  const parsed = registerSchema.safeParse({
    email: formData.get('email'),
    password: formData.get('password'),
  })

  if (!parsed.success) {
    return { error: parsed.error.flatten().fieldErrors }
  }

  const { data, error } = await supabase.auth.signUp({
    email: parsed.data.email,
    password: parsed.data.password,
    options: {
      emailRedirectTo: `${process.env.NEXT_PUBLIC_APP_URL}/auth/callback`,
      data: {
        // Additional user metadata if needed
      }
    }
  })

  if (error) {
    // Return SPECIFIC error messages (per user requirement)
    if (error.message.includes('already registered')) {
      return { error: 'Email già registrata' }
    }
    return { error: error.message }
  }

  return { success: true, message: 'Controlla la tua email per confermare' }
}

// app/auth/callback/route.ts - OAuth callback handler
import { createClient } 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 createClient()
    const { error } = await supabase.auth.exchangeCodeForSession(code)
    if (!error) {
      return NextResponse.redirect(`${origin}${next}`)
    }
  }

  // Return the user to an error page with instructions
  return NextResponse.redirect(`${origin}/auth/auth-code-error`)
}

Source: Supabase Password-based Auth

Pattern 6: Google OAuth Setup

What: Configure Google OAuth provider with proper redirect URLs When to use: For social login (required in this phase)

Setup Steps:

1. Google Cloud Console:

   • Create OAuth 2.0 Client ID (Web application)
   • Add authorized JavaScript origins: https://your-domain.com
   • Add authorized redirect URI: https://<project-ref>.supabase.co/auth/v1/callback
   • For local dev: http://localhost:3000/auth/v1/callback

2. Supabase Dashboard:

   • Navigate to Authentication > Providers > Google
   • Enable Google provider
   • Paste Client ID and Client Secret from Google
   • Copy the Callback URL shown in dashboard

3. Implementation:

// Login with Google (client component)
'use client'

import { createClient } from '@/lib/supabase/client'

export function GoogleSignInButton() {
  const supabase = createClient()

  async function handleGoogleSignIn() {
    await supabase.auth.signInWithOAuth({
      provider: 'google',
      options: {
        redirectTo: `${window.location.origin}/auth/callback`,
      }
    })
  }

  return (
    <button onClick={handleGoogleSignIn}>
      Accedi con Google
    </button>
  )
}

Source: Supabase Login with Google

Anti-Patterns to Avoid

• Using service_role key in client code: Service role bypasses RLS - use only server-side, treat as secret
• Storing JWT in localStorage: Vulnerable to XSS - always use httpOnly cookies via @supabase/ssr
• Skipping RLS policies: 170+ apps were recently exposed by missing RLS (CVE-2025-48757)
• Complex RLS policies without indexes: Always index columns used in RLS WHERE clauses
• Using user_metadata for tenant_id: User can modify this client-side - use app_metadata only
• Missing SELECT policies on INSERT: PostgreSQL SELECTs newly inserted rows to return them - need both policies
• Relying only on middleware for auth: Verify auth at data access points (defense in depth)

Don't Hand-Roll

Problems that look simple but have existing solutions:

Problem	Don't Build	Use Instead	Why
Session management	Custom JWT signing/verification	@supabase/ssr cookie handling	Handles refresh tokens, PKCE flow, SSR edge cases automatically
Password hashing	bcrypt implementation	Supabase Auth	Uses Argon2 (more secure), handles salting, rate limiting built-in
Email verification	Custom token generation	Supabase email templates	Handles token expiry, one-time use, rate limiting, email delivery
OAuth flow	Implementing OAuth 2.0	Supabase OAuth providers	Handles state params, PKCE, token exchange, security edge cases
Multi-tenant isolation	Application-level filtering	RLS policies	Database-level enforcement, prevents bugs from leaking data
Password reset	Token generation + email	Supabase password reset	Secure one-time tokens, prevents brute force, handles edge cases

Key insight: Authentication has too many security edge cases to build from scratch. Supabase handles PKCE flow, token rotation, refresh logic, rate limiting, and OWASP compliance. Building custom auth means maintaining security patches forever.

Common Pitfalls

Pitfall 1: Missing RLS Policies (CRITICAL)

What goes wrong: Data leaks across tenants, complete database exposure via anon key Why it happens: Supabase auto-generates REST APIs from schema, but RLS is opt-in not default How to avoid:

• Enable RLS on EVERY table in public schema: ALTER TABLE tablename ENABLE ROW LEVEL SECURITY;
• Run Security Advisor in Supabase dashboard before production
• Never trust "it works" - test with multiple tenant accounts to verify isolation Warning signs:
• Can see other users' data when testing with different accounts
• Security Advisor shows missing RLS warnings
• Empty results when querying from client (RLS blocks everything by default)

Source: Supabase Security Flaw: 170+ Apps Exposed

Pitfall 2: INSERT Fails with "new row violates policy"

What goes wrong: INSERT operations fail even though you have an INSERT policy Why it happens: PostgreSQL SELECTs newly inserted rows to return them - needs SELECT policy too How to avoid: Create both INSERT and SELECT policies for tables where users insert data Warning signs: Error message "new row violates row-level security policy" on insert

Example fix:

-- Not enough - INSERT will fail
CREATE POLICY "Users can insert own posts" ON posts
FOR INSERT WITH CHECK (user_id = (SELECT auth.uid()));

-- Correct - need SELECT policy too
CREATE POLICY "Users can read own posts" ON posts
FOR SELECT USING (user_id = (SELECT auth.uid()));

CREATE POLICY "Users can insert own posts" ON posts
FOR INSERT WITH CHECK (user_id = (SELECT auth.uid()));

Source: Supabase RLS Best Practices

Pitfall 3: Session Expires Without Middleware

What goes wrong: Users randomly logged out, authentication state inconsistent Why it happens: Forgot to implement middleware session refresh - sessions expire How to avoid: ALWAYS implement middleware.ts with updateSession helper from @supabase/ssr Warning signs:

• Works initially, then users get logged out
• "session expired" errors in console
• Inconsistent auth state between pages

Source: Next.js Supabase Cookie-Based Auth

Pitfall 4: Slow RLS Policies (Performance)

What goes wrong: Queries take seconds instead of milliseconds, database overload Why it happens: RLS policies with complex joins or missing indexes How to avoid:

• Wrap auth.uid() in SELECT: (SELECT auth.uid()) - 99% performance improvement
• Index all columns used in RLS policies: CREATE INDEX idx_table_tenant_id ON table(tenant_id);
• Use IN subqueries instead of joins in policies
• Always include explicit filters in queries even though RLS adds them implicitly Warning signs:
• Queries taking >500ms in development
• High CPU usage on database
• EXPLAIN ANALYZE shows sequential scans on RLS columns

Source: Supabase Row Level Security

Pitfall 5: Using user_metadata for Tenant ID

What goes wrong: Users can modify their tenant_id, accessing other tenants' data Why it happens: user_metadata is editable client-side, confused with app_metadata How to avoid: ALWAYS use app_metadata for security-critical data like tenant_id Warning signs:

• Storing tenant_id in metadata accessible from user.user_metadata
• Using service role to update user_metadata instead of app_metadata

Correct approach:

// Setting tenant_id (server-side with service role)
const { data, error } = await supabaseAdmin.auth.admin.updateUserById(
  userId,
  {
    app_metadata: { tenant_id: 'tenant-uuid' }  // NOT user_metadata
  }
)

// SQL function to access it
CREATE FUNCTION auth.tenant_id() RETURNS TEXT AS $$
  SELECT ((current_setting('request.jwt.claims')::jsonb ->> 'app_metadata')::jsonb ->> 'tenant_id')::TEXT
$$ LANGUAGE SQL STABLE;

Source: Supabase Multi Tenancy Guide

Pitfall 6: Password Reset with Wrong Template

What goes wrong: Password reset emails use wrong template, verification fails Why it happens: PKCE flow (SSR) requires different email template than implicit flow How to avoid: Use "token_hash" template for reset-password emails, verify with verifyOtp not direct link Warning signs:

• Reset link in email doesn't work
• "Invalid token" errors on password reset
• Reset flow works in development but fails in production

Correct flow:

1. Call supabase.auth.resetPasswordForEmail()
2. Email sent with token_hash template
3. User clicks link → redirects to your page with token_hash query param
4. Call supabase.auth.verifyOtp({ token_hash, type: 'recovery' })
5. If verified, call supabase.auth.updateUser({ password: newPassword })

Source: Password Reset Flow in Next.js

Pitfall 7: Infinite Redirect Loops in Middleware

What goes wrong: App redirects endlessly between login and dashboard Why it happens: Middleware redirects authenticated users away from login, but doesn't check if they're already on protected route How to avoid: Check current path before redirecting in middleware Warning signs:

• Browser shows "too many redirects" error
• Network tab shows repeated redirects
• App never loads

Fix:

// middleware.ts - check path before redirecting
const { data: { user } } = await supabase.auth.getUser()

// Don't redirect if already on login page
if (!user && !request.nextUrl.pathname.startsWith('/login')) {
  return NextResponse.redirect(new URL('/login', request.url))
}

// Don't redirect if already on dashboard
if (user && request.nextUrl.pathname === '/login') {
  return NextResponse.redirect(new URL('/dashboard', request.url))
}

Source: Next.js Middleware Authentication Pitfalls

Code Examples

Verified patterns from official sources:

Email/Password Registration with Validation

// app/actions/auth.ts
'use server'

import { createClient } from '@/lib/supabase/server'
import { redirect } from 'next/navigation'
import { z } from 'zod'

const registerSchema = z.object({
  email: z.string().email('Email non valida'),
  password: z.string()
    .min(8, 'La password deve contenere almeno 8 caratteri')
    .regex(/[0-9]/, 'La password deve contenere almeno un numero')
    .regex(/[A-Z]/, 'La password deve contenere almeno una maiuscola'),
})

export async function registerUser(prevState: any, formData: FormData) {
  const supabase = await createClient()

  // Validate input
  const parsed = registerSchema.safeParse({
    email: formData.get('email'),
    password: formData.get('password'),
  })

  if (!parsed.success) {
    return {
      error: parsed.error.flatten().fieldErrors,
      success: false
    }
  }

  // Register user
  const { data, error } = await supabase.auth.signUp({
    email: parsed.data.email,
    password: parsed.data.password,
    options: {
      emailRedirectTo: `${process.env.NEXT_PUBLIC_APP_URL}/auth/callback`,
    }
  })

  if (error) {
    // Specific error messages (user requirement)
    if (error.message.includes('already registered')) {
      return { error: 'Email già registrata', success: false }
    }
    return { error: error.message, success: false }
  }

  return {
    success: true,
    message: 'Registrazione completata! Controlla la tua email per confermare l\'account.'
  }
}

Source: Supabase Password-based Auth

Server Component Data Fetching with RLS

// app/dashboard/page.tsx (Server Component)
import { createClient } from '@/lib/supabase/server'
import { redirect } from 'next/navigation'

export default async function DashboardPage() {
  const supabase = await createClient()

  // Get authenticated user
  const { data: { user }, error: authError } = await supabase.auth.getUser()

  if (authError || !user) {
    redirect('/login')
  }

  // Fetch user's data - RLS automatically filters by tenant_id
  const { data: profile } = await supabase
    .from('profiles')
    .select('*, plans(*)')
    .eq('id', user.id)
    .single()

  return (
    <div>
      <h1>Benvenuto {profile.email}</h1>
      <p>Piano: {profile.plans.display_name}</p>
    </div>
  )
}

Source: Supabase Auth with Next.js

Login Form with Error Handling

// app/(auth)/login/page.tsx
'use client'

import { createClient } from '@/lib/supabase/client'
import { useState } from 'react'
import { useRouter } from 'next/navigation'

export default function LoginPage() {
  const [email, setEmail] = useState('')
  const [password, setPassword] = useState('')
  const [error, setError] = useState('')
  const [loading, setLoading] = useState(false)
  const router = useRouter()
  const supabase = createClient()

  async function handleEmailLogin(e: React.FormEvent) {
    e.preventDefault()
    setLoading(true)
    setError('')

    const { data, error: signInError } = await supabase.auth.signInWithPassword({
      email,
      password,
    })

    if (signInError) {
      // Specific error messages (user requirement)
      if (signInError.message.includes('Invalid login credentials')) {
        setError('Email o password errata')
      } else if (signInError.message.includes('Email not confirmed')) {
        setError('Conferma la tua email prima di accedere')
      } else {
        setError(signInError.message)
      }
      setLoading(false)
      return
    }

    router.push('/dashboard')
    router.refresh()
  }

  async function handleGoogleLogin() {
    await supabase.auth.signInWithOAuth({
      provider: 'google',
      options: {
        redirectTo: `${window.location.origin}/auth/callback`,
      }
    })
  }

  return (
    <div>
      <h1>Accedi</h1>

      {error && <div className="error">{error}</div>}

      <form onSubmit={handleEmailLogin}>
        <input
          type="email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          placeholder="Email"
          required
        />
        <input
          type="password"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
          placeholder="Password"
          required
        />
        <button type="submit" disabled={loading}>
          {loading ? 'Accesso...' : 'Accedi con Email'}
        </button>
      </form>

      <button onClick={handleGoogleLogin}>
        Accedi con Google
      </button>
    </div>
  )
}

Source: Supabase Auth Quickstart

Database Migration for Auth Tables

-- migrations/001_initial_auth_setup.sql

-- Plans table
CREATE TABLE plans (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name TEXT NOT NULL UNIQUE CHECK (name IN ('free', 'creator', 'pro')),
  display_name TEXT NOT NULL,
  price_monthly INTEGER NOT NULL CHECK (price_monthly >= 0),
  features JSONB NOT NULL DEFAULT '{}',
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Insert default plans
INSERT INTO plans (name, display_name, price_monthly, features) VALUES
('free', 'Free', 0, '{
  "posts_per_month": 10,
  "ai_models": ["gpt-4o-mini"],
  "social_accounts": 1,
  "analytics": false,
  "automation": false
}'),
('creator', 'Creator', 1900, '{
  "posts_per_month": 50,
  "ai_models": ["gpt-4o-mini", "gpt-4o", "claude-3-5-sonnet"],
  "social_accounts": 3,
  "analytics": true,
  "automation": "manual"
}'),
('pro', 'Pro', 4900, '{
  "posts_per_month": 200,
  "ai_models": ["gpt-4o-mini", "gpt-4o", "claude-3-5-sonnet", "claude-opus-4"],
  "social_accounts": 10,
  "analytics": true,
  "automation": "full"
}');

-- User profiles with tenant isolation
CREATE TABLE profiles (
  id UUID PRIMARY KEY REFERENCES auth.users(id) ON DELETE CASCADE,
  tenant_id UUID NOT NULL DEFAULT gen_random_uuid(),
  plan_id UUID REFERENCES plans(id) NOT NULL DEFAULT (SELECT id FROM plans WHERE name = 'free'),
  email TEXT NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Indexes for performance
CREATE INDEX idx_profiles_tenant_id ON profiles(tenant_id);
CREATE INDEX idx_profiles_plan_id ON profiles(plan_id);

-- Enable RLS
ALTER TABLE profiles ENABLE ROW LEVEL SECURITY;
ALTER TABLE plans ENABLE ROW LEVEL SECURITY;

-- RLS Policies
CREATE POLICY "Users can read own profile"
ON profiles FOR SELECT
USING ((SELECT auth.uid()) = id);

CREATE POLICY "Users can update own profile"
ON profiles FOR UPDATE
USING ((SELECT auth.uid()) = id)
WITH CHECK ((SELECT auth.uid()) = id);

CREATE POLICY "Everyone can read plans"
ON plans FOR SELECT
TO authenticated, anon
USING (true);

-- Function to create profile on signup (trigger)
CREATE OR REPLACE FUNCTION public.handle_new_user()
RETURNS TRIGGER AS $$
BEGIN
  INSERT INTO public.profiles (id, email, tenant_id)
  VALUES (
    NEW.id,
    NEW.email,
    gen_random_uuid() -- Each user gets unique tenant_id
  );
  RETURN NEW;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

-- Trigger on auth.users insert
CREATE TRIGGER on_auth_user_created
  AFTER INSERT ON auth.users
  FOR EACH ROW
  EXECUTE FUNCTION public.handle_new_user();

-- Helper function to get current user's plan features
CREATE OR REPLACE FUNCTION public.get_user_plan_features()
RETURNS JSONB
LANGUAGE SQL STABLE
AS $$
  SELECT features
  FROM plans
  WHERE id = (
    SELECT plan_id
    FROM profiles
    WHERE id = (SELECT auth.uid())
  );
$$;

Source: Multi-tenant SaaS Database Schema

Checking Plan Limits in API Routes

// app/api/posts/route.ts
import { createClient } from '@/lib/supabase/server'
import { NextResponse } from 'next/server'

export async function POST(request: Request) {
  const supabase = await createClient()

  // Get authenticated user
  const { data: { user }, error: authError } = await supabase.auth.getUser()
  if (authError || !user) {
    return NextResponse.json({ error: 'Non autenticato' }, { status: 401 })
  }

  // Get user's plan features
  const { data: planFeatures, error: planError } = await supabase
    .rpc('get_user_plan_features')

  if (planError) {
    return NextResponse.json({ error: 'Errore recupero piano' }, { status: 500 })
  }

  // Count posts this month
  const { count, error: countError } = await supabase
    .from('posts')
    .select('*', { count: 'exact', head: true })
    .eq('user_id', user.id)
    .gte('created_at', new Date(new Date().getFullYear(), new Date().getMonth(), 1).toISOString())

  if (countError) {
    return NextResponse.json({ error: 'Errore conteggio post' }, { status: 500 })
  }

  // Check limit
  if (count >= planFeatures.posts_per_month) {
    return NextResponse.json({
      error: `Limite mensile raggiunto (${planFeatures.posts_per_month} post)`,
      upgrade_required: true
    }, { status: 403 })
  }

  // Proceed with creating post...
  const body = await request.json()
  const { data, error } = await supabase
    .from('posts')
    .insert({ ...body, user_id: user.id })
    .select()
    .single()

  if (error) {
    return NextResponse.json({ error: error.message }, { status: 500 })
  }

  return NextResponse.json(data)
}

State of the Art

Old Approach	Current Approach	When Changed	Impact
@supabase/auth-helpers-nextjs	@supabase/ssr	Nov 2023	New package required for App Router, cookie handling improved
JWT in localStorage	HttpOnly cookies via SSR	2023	XSS protection, SSR support, better security
Client-side auth checks only	Middleware + RLS + app logic	2024	Defense in depth, prevents CVE-2025-48757 class vulnerabilities
Manual session refresh	Automatic via middleware	2023	Prevents session expiry bugs, better UX
Generic error messages	Specific error messages	2025 UX trend	"Password errata" vs "Invalid credentials" - user requirement
Bare auth.uid() in RLS	(SELECT auth.uid()) wrapped	2024	99% performance improvement in benchmarks
user_metadata for tenant_id	app_metadata only	Security best practice	Prevents user tampering with tenant isolation
Stripe-style trial periods	Free tier as trial	SaaS trend 2025	Lower friction, Supabase/Vercel model

Deprecated/outdated:

• @supabase/auth-helpers-nextjs: Replaced by @supabase/ssr, doesn't work with App Router
• Pages Router auth patterns: App Router requires different client creation patterns
• supabase.auth.session(): Deprecated, use supabase.auth.getSession() or getUser()
• Manual PKCE implementation: @supabase/ssr handles this automatically

Open Questions

Things that couldn't be fully resolved:

1. New Device Email Notifications

   • What we know: User wants email when logging in from unrecognized device (security feature)
   • What's unclear: Supabase doesn't have this built-in, needs custom implementation
   • Recommendation: Implement in Phase 1 using database triggers or Edge Functions to track login IPs/user agents and send emails via Supabase Edge Functions + Resend/SendGrid

2. Session Duration

   • What we know: Default is 3600 seconds (1 hour) access token, 604800 seconds (7 days) refresh token
   • What's unclear: User preference for 30 days mentioned, but Supabase default is 7 days refresh
   • Recommendation: Configure in Supabase dashboard: Authentication > Settings > JWT Expiry. Set refresh token to 2592000 seconds (30 days). Document this in plan.

3. Multi-device Concurrent Sessions

   • What we know: User wants unlimited devices (likely)
   • What's unclear: Supabase allows unlimited concurrent sessions by default, no limit needed
   • Recommendation: No action required - works out of box. If "logout all devices" is needed, implement server action to revoke all sessions via supabase.auth.admin.signOut(user.id, 'global')

4. Plan Upgrade Flow

   • What we know: Need to support Free → Creator → Pro upgrades
   • What's unclear: Immediate activation vs billing cycle, proration, downgrade handling
   • Recommendation: Defer payment integration to later phase, focus on plan switching in database (update profiles.plan_id). Document that payment/Stripe integration is Phase 2+.

Sources

Primary (HIGH confidence)

• Supabase Server-Side Auth for Next.js - Official setup guide
• Supabase Row Level Security - Official RLS documentation
• Supabase Login with Google - OAuth setup
• Supabase Auth Helpers Next.js - Migration guide and examples

Secondary (MEDIUM confidence)

• Next.js Supabase Cookie-Based Auth Workflow 2025 - Verified against official docs
• Supabase Multi Tenancy Guide - app_metadata pattern
• Multi-tenant SaaS model with PostgreSQL - Schema design patterns
• Next.js Middleware Authentication 2025 - Middleware patterns

Tertiary (LOW confidence - flagged for validation)

• Supabase Best Practices - WebSearch only
• Supabase Security Flaw CVE-2025-48757 - CVE details, verify with official Supabase security advisories
• Password Reset Flow Next.js - Community implementation, verify against official docs

Metadata

Confidence breakdown:

• Standard stack: HIGH - Official Supabase documentation confirms @supabase/ssr is the current approach
• Architecture: HIGH - Verified with official docs, multiple sources agree on dual-client pattern
• RLS patterns: HIGH - Official PostgreSQL + Supabase docs, performance benchmarks verified
• Pitfalls: MEDIUM - Based on community experiences + official security advisories, some need validation
• Subscription schema: MEDIUM - Community patterns not official Supabase guidance, needs testing

Research date: 2026-01-31 Valid until: 2026-03-02 (30 days - stable ecosystem, Supabase updates quarterly)