CKAuth
A production-minded authentication API built with Express 5, TypeScript and PostgreSQL.
It handles the full account lifecycle: sign-up with email verification, cookie-based sessions with refresh tokens, password reset and change, and profile avatars stored on ImageKit.
Building a frontend against this API? Go straight to the API reference.
Deploying? See docs/DEPLOYMENT.md (Hostinger VPS, Docker Compose, GitHub Actions).
New to auth or web hosting? The glossary explains every term the docs use, and DEVLOG / LEARNINGS tell the story of how this was built and what went wrong.
Live demo: ckauth.chiragdev.com
Start here, by what you want to do
The repo also contains the CKAuth web app in frontend/ (React + Vite + Tailwind), which implements every flow in the API.
Features
- Sign-up and sign-in with Zod validation and bcrypt password hashing.
- Email verification with single-use links that expire after 15 minutes, sent through Resend.
- Session handling with short-lived access tokens and refresh tokens that are replaced on every use, both stored in
httpOnly cookies.
- Password management: forgot password, reset password and change password.
- Roles and an admin panel: every account is a
user or an admin. Admins can search, invite and delete users at /admin, after confirming their password. Invited people choose their own password from an emailed link. Admins themselves are made and removed only from the server (pnpm admin), never through the website.
- Activity log: sign-ins, wrong passwords, password and email changes, deletions and every admin action are recorded in an audit log, each in the same database transaction as the action, and shown to admins at
/admin. Old events are deleted automatically (90 days for sign-ins, a year for the rest).
- Structured logs: the API writes one JSON line per request with a request ID (also returned as
X-Request-Id), names requests by their route template so one-time tokens never reach the logs, and never logs headers, cookies, bodies or email addresses.
- Avatar uploads to ImageKit. The real file type is checked from the file's contents, and old images are cleaned up automatically.
- Built with security in mind:
- Every token is stored hashed.
- Responses never reveal whether an email is registered.
- Sign-in requires a verified email.
- Database updates are safe when requests arrive at the same time.
- Rate limits per IP, per email and per user on every endpoint that checks a password, sends an email or uses a single-use token. They're shared through Redis.
- Password hashing runs off the main thread, so a burst of sign-ins can't stall everyone else.
Tech stack
| Area | Tools |
|---|
| Runtime | Node.js, TypeScript, Express 5 |
| Database | PostgreSQL 17 (Docker), Drizzle ORM |
| Validation | Zod |
| Auth | JSON Web Tokens (jsonwebtoken), native bcrypt (hashes off the main thread) |
| Rate limiting | express-rate-limit with a Redis store (rate-limit-redis) |
| Email | Resend |
| File uploads | Multer (in-memory), ImageKit |
| Frontend | React 19, Vite, Tailwind CSS 4, React Router |
| Hosting | Docker Compose on a Hostinger VPS behind a shared Caddy edge proxy (HTTPS), GitHub Actions → GHCR |
Getting started
Prerequisites
- Node.js 20+ (developed on Node 24)
- pnpm: run
corepack enable to use the version pinned in package.json
- Docker, for the local PostgreSQL and Redis
- A Resend API key (for emails) and an ImageKit private key (for avatars)
1. Install dependencies
pnpm install
2. Configure environment variables
cp .env.sample .env
Then open .env and fill in the values:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
