Supabase SSR: getClaims, not getSession, on the server

The Next.js + Supabase pack pins Next.js 16.4.1 and @supabase/ssr 0.12.7. In server code such as proxy.ts, getSession() reads the session from the cookie without revalidating it. A forged cookie must never decide who can read a page or write data. Never authorize with session.user.

Use getClaims() to protect pages and data. It verifies the JWT signature on every call. With asymmetric signing keys, the default for new projects, verification happens locally against cached JWKS. With symmetric keys, it calls the Auth server. getClaims() also refreshes the session when the access token is close to expiring.

Use getUser() only when you need an up-to-date user record from the Auth server; it makes a network call. Use getSession() only when you need the raw access or refresh token. Reading a token is different from verifying the identity allowed to use server data. Keep the authorization check on the server with getClaims().

Every Server Action re-checks auth with getClaims(). An action is a public HTTP endpoint even if no button calls it. Validate mutation input, check claims, then write. Pages also check claims themselves. proxy.ts refreshes the session, copies cookies onto both the request and the response, and returns the response that setAll last built. Proxy is not the only lock.

For the Next.js 16 interceptor filename and cookie handling, see /fixes/nextjs-16-middleware-to-proxy. Browser code uses createBrowserClient; Server Components, Server Actions, and Route Handlers use createServerClient with cookies.getAll and cookies.setAll.

Last verified 2026-10-15. doc-verified; TypeScript snippets pass tsc --strict (TypeScript 5, @types/react 19) with zod and the Supabase client stubbed.