getClaims, getUser, getSession & API Token Handoff Use each Supabase Auth method for its intended trust job and prepare the NestJS boundary
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.
Three Auth methods, three jobs Current Supabase SSR guidance distinguishes getClaims, getUser, and getSession. Using each for the correct reason prevents subtle trust bugs.
getClaims() Protect pages/data; verify JWT identity Verifies token signature/claims; preferred for SSR protection
getUser() Need fresh user record from Auth server Network request; catches account/session state changes
getSession() Need raw access/refresh token or expiry Do not trust embedded user by itself in server cookie context
Phase 18 handoff: forwarding the access token TaskFlow has a separate NestJS API. To call it, Next.js will eventually need the raw access token. getSession is appropriate for retrieving the token as transport material, but Next.js must not treat the session.user object as the final authorization proof.
const {
data: { session },
} = await supabase.auth.getSession()const accessToken = session?.access_token// Phase 18: // Authorization: Bearer <accessToken> // NestJS verifies it before trusting sub/claims.
Next.js retrieving an access token does not make NestJS trust it. Phase 18 creates the verification boundary in the API.
Revocation gap A correctly signed, unexpired access token can remain valid until exp even after the underlying refresh session is revoked. The Supabase advanced guide recommends getUser where detecting server-side session termination immediately matters. This is a product/security policy choice, not a reason to call getUser on every render automatically.
Authentication answers who the request represents. Treating decoded or client-supplied identity as trusted is a security boundary failure.
Restate the goal of “getClaims getUser getSession and Access Token Handoff” 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 “getClaims getUser getSession and Access Token Handoff” to a different TaskFlow resource or input. Write the acceptance criteria first, implement it, and provide the evidence that each criterion is satisfied.
Create browser and server Supabase clients with the correct key exposure model.
Use the smallest change that demonstrates this lesson. Stop after it works and capture evidence.Stale UI after session changes
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.