SSR Caching, Refresh & Auth Debugging Diagnose session failures without weakening cookie or token security
Phase 17 - Supabase Authentication Volume 05 - Authentication & Security
v
v
v
Phase 17 implements cookie-based Supabase Auth in Next.js. NestJS token verification remains Phase 18.
SSR authentication fails in ways ordinary client-only auth does not Cookie synchronization, token refresh, route prefetching, caching, and response headers all affect SSR authentication. Random logout symptoms often come from session cookies not being propagated consistently.
User signs in then appears logged out on Server Proxy/session-cookie refresh path Component
getSession has user but protected page should reject Use getClaims/getUser for identity verification
Do not cache authenticated Set-Cookie responses publicly Supabase warns that session refresh writes Set-Cookie. If a CDN caches that response and serves it to another visitor, session leakage can occur. Current @supabase/ssr versions provide cache-related headers during refresh; the Proxy must apply those headers. Authenticated routes should not use ISR casually.
Authentication flows that depend on a browser first processing new cookies can interact poorly with prefetching. Keep the SSR guide current, test real navigation behavior, and use dynamic rendering for authenticated pages when request-time session state is required.
Debug with observable boundaries • Confirm NEXT_PUBLIC_SUPABASE_URL and publishable key are loaded in apps/web.
• Confirm the dashboard Site URL matches the browser origin.
• Inspect the /auth/confirm request and redirect chain.
• Inspect Set-Cookie responses without copying token values into logs/screenshots.
• Confirm proxy.ts matcher actually runs for protected routes.
• Confirm getClaims returns verified claims after sign-in/refresh.
• Do not fix auth by disabling cookie security or exposing a secret key.
Authentication answers who the request represents. Treating decoded or client-supplied identity as trusted is a security boundary failure.
Restate the goal of “SSR Caching Refresh and Auth Debugging” as one observable behavior. Write the success signal before touching code.
Trace the boundary map: credentials/session → token → verification → trusted identity → protected operation. Mark the one boundary this lesson changes.
Inspect the current repository state and record the exact files, route, table, or runtime involved. Avoid creating an abstraction before you can name the existing owner.
Implement the smallest vertical slice. Add one coherent change, run the narrowest verification command, and read the output before continuing.
Connect the slice to TaskFlow’s phase artifact: Working TaskFlow authentication UI/session integration whose server-side checks are explicit and ready to hand tokens to NestJS.. Verify behavior from the outside as a user or API client would.
Create one controlled failure that is safe to reproduce. Predict the symptom first, capture evidence, locate the earliest broken boundary, then fix only that cause.
Close the reference and rebuild or explain the core change from memory. Record what you would monitor or test before trusting the same change in production.
const token = readBearerToken(request);
const claims = await verifier.verify(token);
request.user = {
id: claims.sub,
email: claims.email,
};Do not copy this as a finished answer. Predict what each boundary does, type the smallest useful slice, run it, then compare the result with your prediction.
Inspect whether a token exists, whether it is expired, which issuer/audience signed it, and what the API verifier expects.
Trust only verified server claims; never repair identity by accepting a client-sent user id.
Without copying the final source, create a second small scenario that applies “SSR Caching Refresh and Auth Debugging” to a different TaskFlow resource or input. Write the acceptance criteria first, implement it, and provide the evidence that each criterion is satisfied.
Implement sign-up/sign-in and surface provider errors safely.
Use the smallest change that demonstrates this lesson. Stop after it works and capture evidence.Using service-role key in browser code
Predict the symptom before causing the failure. Then locate the earliest boundary where reality diverges from expectation.Why does this responsibility live here, what input does it trust, what output proves success, and what would go wrong if another layer owned it?
If your explanation is vague, repeat the boundary trace before moving on.Close the reference. Reproduce the core idea from memory or explain the exact request/data flow aloud. Then check your diff or notes for accidental shortcuts that bypass validation, authorization, error handling, or verification earned in earlier phases.