Hands-On Lab & Phase Exit Prove signup, confirmation, session refresh, route protection, and sign-out before protecting the API
Phase 17 - Supabase Authentication Volume 05 - Authentication & Security
v
v
v
v
v
Phase 17 implements cookie-based Supabase Auth in Next.js. NestJS token verification remains Phase 18.
Hands-on lab: make authentication observable Complete the lab in order. Do not proceed because the login page looks correct; proceed because each session transition is verified.
Lab A - Install and configure • From taskflow\apps\web install @supabase/supabase-js@2.116.0 and @supabase/ssr@0.12.7.
• Create .env.local from .env.local.example using your project URL and Publishable key.
• Configure Site URL and the signup confirmation template in the Supabase dashboard.
• Create browser.ts/server.ts equivalents and proxy.ts exactly once - do not create duplicate auth clients per feature.
Lab B - Verify flows Test Expected result
Create account with confirmation enabled Message asks you to check email; no false authenticated UI
Open confirmation email /auth/confirm verifies token hash and redirects to /account
Refresh /account repeatedly Session remains valid; no random logout
Sign out Current session ends; protected page redirects again
Lab C - Explain the trust chain Draw this without looking at the book: Credentials -> Supabase Auth -> cookie-backed session -> Proxy/getClaims -> verified claims -> protected Next.js page -> raw access token when calling NestJS -> NestJS verification in Phase 18.
Exercise levels Level Challenge
1 - Follow Reproduce the reference auth flow and verify every transition.
2 - Modify Add a public /about route while keeping /account and /tasks protected. Explain where the rule belongs.
3 - Implement Add a "Sign out all devices" action that intentionally uses global scope and clearly labels the effect.
4 - Engineer Design an HRIS login/session policy: email confirmation, MFA trigger, local vs global logout, fresh-user checks for payroll approval, and session-revocation expectations.
Phase exit checklist • You can explain why @supabase/ssr exists in addition to supabase-js.
• You know which Supabase values may be NEXT_PUBLIC and which must never be public.
• You can implement the browser client, server client, and Next.js 16 Proxy session path.
• You use getClaims for protected SSR identity checks rather than trusting getSession().user.
• You can explain email confirmation token-hash exchange.
• You can explain local vs global sign out.
• You understand why authenticated responses must not be cached across users.
• You can retrieve an access token for transport to NestJS without treating it as verified by NestJS.
• You understand that Phase 17 authenticates the web session but does not yet secure the NestJS API.
v
v
v
v
v
v
Phase 17 is complete when the web session works reliably and the learner can explain every trust boundary.
Authentication answers who the request represents. Treating decoded or client-supplied identity as trusted is a security boundary failure.
Restate the goal of “Hands On Lab and Phase Exit” 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 “Hands On Lab and Phase Exit” 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-out and prove protected routes recover to unauthenticated state.
Use the smallest change that demonstrates this lesson. Stop after it works and capture evidence.Broken redirect URLs across environments
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.