Auth and Multi-Tenancy

An agent builds you a settings page. It reads the current user in a client component, checks if (user.role !== "admin") return null, and hides the member-management UI from everyone else. You click through it as an admin, as a member, as a client; the right things show and hide. It looks completely done. It is also completely unprotected, because the check runs in the browser, which is to say on the attacker's computer, and the data behind it is one fetch to your API away from anyone with the developer console open. This is the single most common way agent-built SaaS ships a hole, and this lesson is about building auth so that the hole cannot exist, then proving it with a test that opens the console for you.

Where a session can be trusted

Supabase's SSR guidance for the App Router is precise about one thing, and the whole security model hangs on it: the server gets the session from cookies, and cookies can be spoofed, so server code must verify the token rather than believe it. The mechanism is supabase.auth.getClaims(), which validates the JWT's signature against the project's published keys every time. Its two siblings are traps if misused: getSession() reads the token from storage without re-validating it, so its user object must never drive an authorization decision in server code; getUser() makes a network call for a fresh record when you need one. The rule to memorize: protect pages and route handlers with getClaims(); never authorize off getSession().

The plumbing is three small client factories plus a proxy that refreshes tokens, straight from the current Supabase Next.js guide. The install is @supabase/supabase-js and @supabase/ssr, and the env vars are the project URL and the publishable key:

import { createServerClient } from '@supabase/ssr'
import { cookies } from 'next/headers'

// Server Component / Route Handler client. Reads cookies for the
// session; the proxy is what refreshes them.
export async function createClient() {
const cookieStore = await cookies()
return createServerClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
  {
    cookies: {
      getAll() {
        return cookieStore.getAll()
      },
      setAll(cookiesToSet) {
        try {
          cookiesToSet.forEach(({ name, value, options }) =>
            cookieStore.set(name, value, options))
        } catch {
          // Called from a Server Component: the proxy handles the
          // refresh, so this can be safely ignored.
        }
      },
    },
  },
)
}

The proxy (Next.js middleware) calls getClaims() on every matched request to keep tokens fresh and hand them to server components; the Supabase guide's matcher excludes static assets. That is refresh plumbing, not your authorization layer. The authorization layer is next, and it is the part you design.

Membership as one layer

The failure that scatters auth across a codebase is treating every page as its own security question. Twenty pages, twenty slightly different role checks, and the nineteenth is where the bug lives. The fix is one function that answers "who is this user, in this org, with what role, and is this org's subscription live", called everywhere, defined once. Because RLS (4.5) already enforces data isolation at the database, this app-layer function is not the security boundary; it is the layer that decides what to render and which actions to offer, backed by the boundary underneath. Defense in depth: the app layer is the polite front door, RLS is the wall.

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

export type OrgContext = {
userId: string
orgId: string
role: 'owner' | 'admin' | 'member' | 'client'
billingActive: boolean
}

// The single authorization entry point. Verifies identity with
// getClaims (never getSession), loads membership under RLS, and
// redirects unauthenticated or non-member users. Every protected
// page and route handler calls this.
export async function requireOrg(orgId: string): Promise<OrgContext> {
const supabase = await createClient()

const { data: claims } = await supabase.auth.getClaims()
const userId = claims?.claims.sub
if (!userId) redirect('/login')

// This read is itself RLS-protected: a non-member gets no row.
const { data: membership } = await supabase
  .from('org_members')
  .select('role')
  .eq('org_id', orgId)
  .single()
if (!membership) redirect('/dashboard')

const { data: sub } = await supabase
  .from('subscriptions')
  .select('status, current_period_end')
  .eq('org_id', orgId)
  .single()
const billingActive =
  sub?.status === 'active' || sub?.status === 'trialing'

return {
  userId,
  orgId,
  role: membership.role,
  billingActive,
}
}

// Guard for staff-only actions. Throwing (not hiding) is the point.
export function assertStaff(ctx: OrgContext) {
if (ctx.role === 'client') {
  throw new Response('Forbidden', { status: 403 })
}
}

Two properties make this the layer instead of a helper. It verifies with getClaims, so the identity it returns is server-confirmed, not cookie-asserted. And the membership read runs under RLS, so even this function cannot be tricked into returning a membership for an org the user does not belong to: the database returns no row, and the function redirects. The app check and the database wall agree because they are the same fact enforced twice.

A protected page becomes three honest lines:

import { requireOrg, assertStaff } from '@/lib/auth'

export default async function MembersPage(
{ params }: { params: Promise<{ orgId: string }> },
) {
const { orgId } = await params
const ctx = await requireOrg(orgId)   // redirects if not a member
assertStaff(ctx)                       // 403 if a client
// ... render member management, safe because the checks are
// server-side and the data reads are RLS-bounded anyway.
}

The attack, walked

Here is the client-side-only version an agent writes when you under-specify, and exactly how it falls. Suppose the member list is fetched from GET /api/orgs/[orgId]/members, and the route handler looks like this:

// BAD: no server-side identity check. "Protection" is the client
// component that decides whether to call this route.
export async function GET(
_req: Request,
{ params }: { params: Promise<{ orgId: string }> },
) {
const { orgId } = await params
const supabase = await createClient()
const { data } = await supabase
  .from('org_members')
  .select('user_id, role')
  .eq('org_id', orgId)
return Response.json(data)
}

The developer believes this is safe because the members page hides its link from clients. The attack needs no tools beyond the address bar and a session: a client user, logged in, requests /api/orgs/<their-own-org>/members directly. Now, does this leak? It depends entirely on whether RLS is doing its job, which is the whole reason 4.5 came first. With the members_select policy from 4.5 (a user reads member rows only of orgs they belong to), the client sees the member list of their own org, which the product may or may not intend, but crucially sees nothing of any other org. Without RLS, or with a route using the service-role key, this returns every membership row it is asked for, across all tenants. The lesson inside the lesson: client-side-only checks are not a leak by themselves; they are a leak amplifier that turns any missing database boundary into a full breach. The defense is both layers: server-verified identity in the handler, RLS underneath.

The correct handler asserts identity and role server-side, so the address-bar request from a client is refused before RLS is even consulted:

import { requireOrg, assertStaff } from '@/lib/auth'

export async function GET(
_req: Request,
{ params }: { params: Promise<{ orgId: string }> },
) {
const { orgId } = await params
const ctx = await requireOrg(orgId)  // 401/redirect if not a member
assertStaff(ctx)                      // 403 if a client
const supabase = await createClient()
const { data } = await supabase
  .from('org_members')
  .select('user_id, role')
  .eq('org_id', orgId)
return Response.json(data)
}

The test that catches it

The gate for this dispatch is an unauthorized-access suite: for every protected route, a request with the wrong (or no) identity must be refused, asserted as a test, not clicked through as a human. This is 3.8's threat model as a merge blocker. The shape, using the framework you wired in 4.9 (here expressed as intent so it reads cleanly):

import { test, expect } from '@playwright/test'

// Each protected surface gets a negative test. These are the tests
// that would have caught the client-side-only handler: they never
// open the UI, they hit the route the way an attacker does.

test('anonymous request to a protected page redirects to login', async ({
request,
}) => {
const res = await request.get('/settings/members', {
  maxRedirects: 0,
})
expect(res.status()).toBe(307) // Next redirect to /login
})

test('client role is forbidden from the members API', async ({
browser,
}) => {
const ctx = await browser.newContext({
  storageState: 'tests/.auth/client.json', // a logged-in client
})
const res = await ctx.request.get('/api/orgs/ORG_A/members')
expect(res.status()).toBe(403) // assertStaff throws, not hides
await ctx.close()
})

test('member of org A cannot read org B members', async ({
browser,
}) => {
const ctx = await browser.newContext({
  storageState: 'tests/.auth/a-admin.json',
})
const res = await ctx.request.get('/api/orgs/ORG_B/members')
// requireOrg redirects (no membership row under RLS); the API
// returns no org-B data regardless.
expect([307, 403]).toContain(res.status())
await ctx.close()
})

The three tests map to the three ways this breaks: no identity, wrong role, wrong tenant. Each drives the route directly, the way the attacker does, never through the UI that hides the button. A suite that only clicks the UI as different roles tests your CSS, not your security.

The dispatch

Where it breaks

The defining failure is the one in the cold open: authorization that lives only in the client. The tell is a role check inside a .tsx component that renders UI, with no matching check in the route handler or server component that serves the data. The countermeasure is structural and already built: requireOrg/assertStaff in the handler, and the negative test that hits the handler directly. If a protected route has no negative test, treat it as unprotected until proven otherwise.

The second is authorizing off getSession(). It is an easy mistake because getSession() returns a user object that looks authoritative, and in a client component it is fine for display. In server code making an access decision, it is a spoofable input. Grep for getSession in any file that decides access, and replace with getClaims.

The third is the layer that quietly becomes many layers again: a new page copies a role check inline "just this once" instead of calling requireOrg, and now the authorization logic has two homes that will drift. The rule is that no page or handler makes an authorization decision except through the one layer. Enforce it in review: an inline role === outside lib/auth.ts is a finding.

Knowledge check

Sources

• Supabase Creating a client for SSR / Next.js (createServerClient, proxy refresh with getClaims, getClaims vs getSession vs getUser, publishable key env vars, cookies-can-be-spoofed guidance): https://supabase.com/docs/guides/auth/server-side/nextjs (fetched July 2026)
• Supabase Row Level Security (the wall the app layer sits on; membership reads are RLS-bounded): https://supabase.com/docs/guides/database/postgres/row-level-security (fetched July 2026)
• Best practices for Claude Code (spec-then-verify discipline the auth dispatch and its negative-test gate follow): https://code.claude.com/docs/en/best-practices (fetched July 2026)
• The Briefcase auth layer and attack tests are this course's reference artifacts, authored against the fetched Supabase App Router patterns.