Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 39 ยท Projects and Practice

Project: A Secure Notes API

Build a complete notes API in Node.js: password hashing, short-lived JWTs, rotating refresh tokens, ownership checks, login throttling, pagination and ETags.

In this project you combine what you learned about tokens, security, pagination and caching into one working API. The server registers users, logs them in, issues short-lived access tokens and rotating refresh tokens, and lets each user create, list, read, update and delete only their own notes. It throttles password guessing, paginates with cursors, and protects updates with ETags.

Everything runs in plain Node.js with no packages, so you can read every line. A real project would add a framework, a database and a validation library, but the logic is the same.

What you will build

Accounts Register and log in.
Tokens Access JWT and refresh token.
Notes CRUD with ownership.
Protection Throttle, validate, ETag.

Each feature maps to an earlier lesson.

1 / 2

Design decisions

Concern Decision Lesson
Passwords scrypt with a random salt per user, compared in constant time API Keys explains why slow hashes are for passwords
Access token HS256 JWT, 5 minutes, iss and aud checked, algorithm pinned JWT Pitfalls
Refresh token Random, stored as a hash, single use, family revoked on reuse Refresh Tokens
Authorization The user ID comes from the token; every note query includes the owner BOLA
Login abuse 3 failed attempts per email, then 429 with Retry-After Rate Limiting
Lists Cursor pagination, limit capped at 5 Pagination
Concurrency ETag on a note, If-Match required for updates HTTP Caching
Errors JSON, correct status codes, no internals Input Validation

Step 1: the password helpers

Passwords are never stored. You store a random salt and the output of a deliberately slow key-derivation function. Check the helpers first, in isolation.

Node.js Hash and verify passwords with scrypt

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Step 2: the whole API

The program below starts the server on a loopback port and then plays a client through a complete story: register, wrong passwords until throttled, login, create notes, paginate, read with ETag, update with If-Match, try to read someone else's note, let the access token expire, refresh, reuse a refresh token, and delete. Time is a variable (now), so expiry and throttling are instant and deterministic.

Read the server part first. The client script at the bottom prints one line per step.

Node.js The complete secure notes API

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The final lines show the refresh token family being revoked: the reuse of an old token is answered with 401, and then even the legitimate newest token fails, so the owner must log in again.

Review the design

Go through the program with a security reviewer's eyes:

  • Where does the user ID come from? Only from the verified token (userFromToken). No handler reads an ID from the body.
  • What would happen if you forgot the owner check? Note 1 would be readable by Ben. Try removing the note.ownerId !== userId test and rerun it.
  • Why does login hash the password even for unknown emails? So response time does not reveal which emails are registered. The error message is also the same for both cases.
  • What is protected from mass assignment? The PUT handler copies only title and body. The ownerId and version fields in the test request were ignored.
  • What is missing for production? HTTPS, a real database, persistent refresh-token storage, an IP-level limiter in addition to the per-email one, structured logging, password breach checks, email verification, and tests (Testing REST APIs).

Extend the project

  1. Add DELETE /auth/logout that revokes the refresh token's family.
  2. Add scope claims (notes:read, notes:write) and check them in each route.
  3. Switch to RS256 with a kid and publish the public key at /.well-known/jwks.json.
  4. Add a GET /notes?q= search with a validated, length-limited query.
  5. Write the OpenAPI file for the API and lint it (Documenting APIs with OpenAPI).
  6. Write a contract test for the GET /notes response shape (Contract Testing).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does the login route run scrypt even when the email is unknown?

    Equal work and an identical error message prevent user enumeration through timing or wording.
  2. 2. Which line makes sure users cannot read each other's notes?

    Object-level authorization compares the record's owner with the authenticated user on every access.
  3. 3. What does the API return when a PUT arrives without If-Match?

    Requiring the header forces clients to prove which version they edit, preventing lost updates.
  4. 4. Why does PUT copy only title and body from the request?

    An allowlist ensures clients cannot change fields they should not control.
  5. 5. What happens to the legitimate client's newest refresh token after an old one is reused?

    Reuse signals theft, so the server revokes every token of the family and forces a new login.

Summary

  • You combined hashed passwords, short JWTs, rotating refresh tokens, owner-scoped data, throttling, cursor pagination and ETag concurrency in one API.
  • The user identity always comes from the verified token, and every object access checks ownership.
  • Updates use allowlists and If-Match; errors use consistent JSON and correct statuses.
  • A simulated clock makes expiry and throttling easy to test.
  • Production needs HTTPS, a real database, more limits, logging and a test suite.

Next: Project: A Mini OAuth 2.0 Provider