Skip to main content

Build an app with duck-auth

WIP

An eight-chapter course that builds the sign-in for one notes app, from a first password check to a production deployment

This course builds the authentication for DuckNotes, a small notes app, one chapter at a time. Every chapter adds to the same source tree, and every snippet runs as shown against @gentleduck/auth.

What you build

Loading diagram...

By the end, people sign up, verify their address, sign in with a password, a mailed link or GitHub, add a TOTP second factor, and must step up before a destructive action. It all runs on Postgres and Valkey behind a strict() production check.

The roadmap

Loading diagram...

Part 1 drives the engine from a script, so every answer is printed. Part 2 puts it behind HTTP and a browser, then hardens it.

Course map

ChapterTopicWhat you learn
1Your first sign-increateAuth, identities, passwords, signIn, resolveSession, AuthError
2Accountsdeliver, email verification, password reset, events
3SessionsThe row, deadlines, rotation, devices, hijack detection
4Behind HTTPAuth routes over auth.flows, sign-up, CSRF, errorToHttp
5In the browserfetch calls to your routes, the error envelope, the CSRF cookie
6More ways inMagic links, GitHub OAuth, account linking
7A second factorTOTP enrollment, backup codes, step-up to AAL 2
8ProductionPostgres, Valkey, strict(), tests

Prerequisites

  • TypeScript and async/await.
  • Node.js 22 or newer, or Bun.
  • No database until chapter 8, which uses Postgres and Valkey.

Setup

Create the project

mkdir ducknotes && cd ducknotes
npm init -y
npm pkg set type=module
mkdir src

Install duck-auth

npm i @gentleduck/auth @node-rs/argon2

@node-rs/argon2 is the password hasher's peer. Everything else is installed by the chapter that needs it.

Add a runner

npm i -D tsx
npx tsx src/main.ts

Start

Go to Chapter 1: your first sign-in.

How the chapters are written

Each chapter has learning goals, a diagram of what it introduces, the code, what just happened inside the engine, and a try it exercise. New concepts link to their reference page.

See also