Lesson 17.0

Orientation: the chapter where your API learns who you are

Artifact: A clear map of the two flows you'll ship and the four traps you'll dodge

1. The promise

You'll know what this chapter ships, what code lands in your repo by the end, and the four security traps the chapter spends time on by name. You'll also know what you need running on your machine before you start.

2. The mental model

The previous chapters built rooms. Ch 14 and Ch 15 built the API. Ch 16 built the database. This chapter installs the locks, the keys, and the badge readers. By the end, the API knows who's at the door before it lets them in.

(DIAGRAM: the door system metaphor — annotated SVG — building with two doors labelled "email/password" and "Google OAuth", plus four labelled "alarm" boxes for hashing, tokens, CSRF, XSS)

A short vocabulary note. An auth flow is the end-to-end sequence a user goes through to prove identity and receive permission. A trap is a known way auth gets broken that this chapter calls out by name and shows how to prevent.

3. You do it, with me

There's nothing to install in this unit. Read along and check your machine.

Open your NestJS API from Ch 15 and start it.

(SCREENSHOT: VSCode with the Ch 15 NestJS project open — terminal panel showing "Nest application successfully started" on port 3000 — full window)

bashterminal — start the Nest API
cd ~/projects/click-to-career/api
npm run start:dev

In a second terminal, start your Next.js front-end from Ch 12.

bashterminal — start the front-end
cd ~/projects/click-to-career/web
npm run dev -- -p 3001

(SCREENSHOT: the Click to Career chapter index for Ch 17 — full window — orientation unit highlighted)

Confirm Postgres from Ch 16 is up. Run a one-liner.

bashterminal — confirm Postgres is reachable
psql "$DATABASE_URL" -c "SELECT 1;"

If that prints 1, you're set.

(SCREENSHOT: a labelled mock of the finished login screen the student will build — Next.js page with email/password fields and a "Sign in with Google" button — full window)

4. What you should be seeing

Three pictures in your head:

  • The two artifacts you'll ship. An email/password login and a Google OAuth login. Both run against the Nest API on localhost:3000 and the Next.js front-end on localhost:3001.
  • The four named traps. Weak hashing, leaked tokens, CSRF (the forged cheque attack), XSS (the poisoned script attack). Each gets its own unit later.
  • The two big debates this chapter resolves. Sessions vs JWTs, and "roll your own" vs use a library. You'll pick on purpose, not by accident.

An honest note. Real auth is hard. The chapter teaches you the model so you can read whichever library you end up using on the job. It doesn't cover billing, email verification past the magic-link flow, or compliance certifications. Those land in Ch 24 and Ch 25.

5. Common stumbles

  • You skip the orientation and get lost when the chapter calls a session a session and you were thinking of a JWT. Re-read this unit if the words start blurring at unit 17.7.
  • You try to read the chapter without the Nest API and Postgres running. The hands-on units assume both are up and reachable. Confirm before you begin.
  • You assume "auth" means a single thing. It splits into two: who you are (authentication) and what you may do (authorisation). Unit 17.2 makes that split sharp.

6. You should know

1/18
Next