How We Structured Next.js 15 App Router + Supabase Auth with Zero Leaks

If you migrated to Next.js 15 recently, you probably ran into the subtle landmines scattered across server-side authentication.

With React 19 server components, asynchronous request APIs (await cookies(), await headers()), and deprecation of legacy auth helpers (@supabase/auth-helpers-nextjs), the old copy-paste boilerplate from 2023 no longer works safely.

Worse: if you implement server-side auth incorrectly in Next.js 15, your application won't necessarily crash. Instead, it will fail silently — leaking cached user sessions across edge regions, getting stuck in infinite redirect loops on token refreshes, or trusting spoofed JWT tokens in Server Actions because of the infamous getSession() vs getUser() trap.

Here is the exact 3-layer architecture we run in production across our micro-SaaS and client apps to ensure rock-solid session handling, zero token leaks, and strict Row Level Security (RLS) enforcement.

---

1. The 3 Pitfalls That Silently Compromise Next.js 15 Auth

Before jumping into the implementation, let's address the bugs that bite 90% of teams:

Pitfall #1: The getSession() vs getUser() Security Vulnerability

Many developers still write this in Server Components and Route Handlers:

// ❌ INSECURE: Do not use getSession() for access control on the server
const { data: { session } } = await supabase.auth.getSession();
if (!session) redirect('/login');

Why it fails: getSession() reads the local cookie payload without verifying the authenticity of the JWT with the Supabase Auth server. If an attacker tampers with the cookie or supplies an expired/revoked token, getSession() may still return a truthy session object.

The Fix: Always use supabase.auth.getUser(). It communicates with the Supabase Auth server (or cryptographically validates the JWT against the project's signing key), ensuring the user ID and claims cannot be forged.

Pitfall #2: The Asynchronous cookies() API in Next.js 15

In Next.js 14 and earlier, cookies() was synchronous. In Next.js 15, cookies() returns a Promise<ReadonlyRequestCookies>.

If your Supabase client helper synchronously accesses cookie stores, Next.js throws runtime warnings in development and sporadic Error: Dynamic server usage or cookie mutability errors in production server actions.

Pitfall #3: Middleware Token Refresh Throttling

Every single request processed by Next.js triggers your middleware. If your matcher doesn't strictly exclude static assets (_next/static, favicon, images, fonts), your Edge Middleware will invoke Supabase token refreshes on every stylesheet and SVG requested.

In a dashboard with 30 assets, one page load fires 30 auth round-trips — hitting Supabase API rate limits within minutes.

---

2. Production Architecture: The 3 Client Factories

We structure all Supabase interactions through three dedicated factory files:

1. utils/supabase/middleware.ts — Synchronizes session cookies at the edge.
2. utils/supabase/server.ts — Read-only cookie client for Server Components & Pages.
3. utils/supabase/client.ts — Browser client for interactive Client Components.

Let's build each one.

Layer 1: Edge Middleware (utils/supabase/middleware.ts)

The middleware's single responsibility is refreshing expired auth tokens before the request hits your page routes or server actions.

// utils/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)
          );
        },
      },
    }
  );

  // IMPORTANT: Avoid getSession() — use getUser() to validate cryptographic signatures
  const {
    data: { user },
  } = await supabase.auth.getUser();

  const isAuthRoute = request.nextUrl.pathname.startsWith('/login') ||
                      request.nextUrl.pathname.startsWith('/register');
  const isProtectedRoute = request.nextUrl.pathname.startsWith('/dashboard') ||
                           request.nextUrl.pathname.startsWith('/settings');

  // Redirect unauthenticated visitors attempting to access protected areas
  if (!user && isProtectedRoute) {
    const url = request.nextUrl.clone();
    url.pathname = '/login';
    url.searchParams.set('redirectTo', request.nextUrl.pathname);
    return NextResponse.redirect(url);
  }

  // Redirect authenticated users away from public login/register forms
  if (user && isAuthRoute) {
    const url = request.nextUrl.clone();
    url.pathname = '/dashboard';
    return NextResponse.redirect(url);
  }

  return supabaseResponse;
}

Now connect it to your root middleware.ts with a hardened matcher:

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

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

export const config = {
  matcher: [
    /*
     * Match all request paths EXCEPT:
     * - _next/static (static files)
     * - _next/image (image optimization files)
     * - favicon.ico (favicon file)
     * - Public assets (*.svg, *.png, *.jpg, *.jpeg, *.gif, *.webp)
     */
    '/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
  ],
};

---

Layer 2: Next.js 15 Async Server Client (utils/supabase/server.ts)

Server Components in Next.js 15 cannot modify cookies (they are read-only render streams). Mutating cookies during server rendering triggers Cookies can only be modified in a Server Action or Route Handler.

Here is the clean implementation taking advantage of await cookies():

// utils/supabase/server.ts
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 is safe to ignore because middleware already refreshed the session.
          }
        },
      },
    }
  );
}

---

Layer 3: Server Actions with Strict Schema Validation

Never trust client payloads sent to Server Actions. Combine Supabase auth with runtime schema guards (Zod) to prevent malformed data and privilege escalation:

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

import { revalidatePath } from 'next/cache';
import { redirect } from 'next/navigation';
import { createClient } from '@/utils/supabase/server';
import { z } from 'zod';

const LoginSchema = z.object({
  email: z.string().email('Invalid email address'),
  password: z.string().min(8, 'Password must be at least 8 characters'),
});

export async function login(formData: FormData) {
  const parsed = LoginSchema.safeParse({
    email: formData.get('email'),
    password: formData.get('password'),
  });

  if (!parsed.success) {
    return { error: parsed.error.issues[0].message };
  }

  const supabase = await createClient();

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

  if (error) {
    return { error: error.message };
  }

  revalidatePath('/', 'layout');
  redirect('/dashboard');
}

export async function logout() {
  const supabase = await createClient();
  await supabase.auth.signOut();
  revalidatePath('/', 'layout');
  redirect('/login');
}

---

3. The PKCE OAuth Callback Route

If you use Google, GitHub, or magic links, you must exchange the temporary auth code for a session token using the PKCE flow.

Here is the hardened Next.js 15 Route Handler:

// app/auth/callback/route.ts
import { NextResponse } from 'next/server';
import { createClient } from '@/utils/supabase/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';

  // Prevent Open Redirect attacks: only allow internal relative paths
  const safePath = next.startsWith('/') && !next.startsWith('//') ? next : '/dashboard';

  if (code) {
    const supabase = await createClient();
    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}${safePath}`);
      } else if (forwardedHost) {
        return NextResponse.redirect(`https://${forwardedHost}${safePath}`);
      } else {
        return NextResponse.redirect(`${origin}${safePath}`);
      }
    }
  }

  // Return to an error page with instructions if exchange fails
  return NextResponse.redirect(`${origin}/login?error=auth-code-exchange-failed`);
}

---

4. Production Security Checklist

Before deploying your Next.js 15 app to production, run through this 5-point audit:

1. Service Role Key Quarantine: Ensure SUPABASE_SERVICE_ROLE_KEY is NEVER prefixed with NEXT_PUBLIC_. If this variable is exposed to the client, anyone can bypass all Row Level Security policies.
2. RLS Enabled on All Tables: Run ALTER TABLE public.profiles ENABLE ROW LEVEL SECURITY; for every single table in your Postgres schema. An open table without RLS allows any authenticated user to query all records via the client SDK.
3. No Raw User Input in SQL: When writing Supabase RPC functions, always use parameterized queries to avoid SQL injection.
4. Strict Middleware Matcher: Verify your matcher regex does not run against image assets or fonts, saving thousands of unnecessary edge function invocations.
5. Sanitize Redirect URLs: In OAuth callback routes, validate that next parameters cannot be exploited for phishing redirects to third-party domains.

---

Builder Tools & Battle-Tested Automation

Building full-stack indie apps, AI agents, and developer tooling requires reliable foundations so you don't spend weeks reinventing boilerplate or debugging token leaks.

If you are shipping automated products, scrapers, or AI systems:

• Universal Agent Skills & Production Prompt Vault 2026: Battle-tested system prompts, Pydantic V2 schema shields, and agent workflows: ancuboy.gumroad.com/l/universal-agent-skills-vault
• Production Python Scraper & n8n Lead Hunter Toolkit: Zero-SaaS web extraction and lead qualification workflows: ancuboy.gumroad.com/l/python-scraper-toolkit
• AgentFlow OS (Multi-Model AI Failover): Cascading router across Claude 3.5, GPT-4o, and DeepSeek with zero downtime: ancuboy.gumroad.com/l/agentflow-os

Use coupon code BUILDER50 for 50% off across the store at ancuboy.gumroad.com.

What auth architecture do you use in your Next.js projects? Drop your questions or setups below!

Comments

[Vlad Zoff]

I like the split between middleware, route handlers, and RLS because they protect different failure modes. The part I'd be careful about is treating any one of them as the architecture itself. RLS is the hard enforcement boundary, while middleware and handlers mostly shape request-path behavior. Keeping that distinction explicit makes auth changes much easier to reason about once the app starts growing.