QuickShield — Fastify Auth Template

QuickShield is a minimal, secure starter for user authentication built on Fastify, Prisma, and TypeScript (runs great on Bun). It ships with cookie-based sessions, CSRF protection, rate-limiting, and automatic Swagger docs generated from TypeBox route schemas.

Features

• User registration, login, logout, and profile (/me)
• Password reset via secure, one-time tokens
• Encrypted cookie sessions (@fastify/secure-session), no Redis required
• CSRF protection for state-changing routes
• Rate limiting and security headers (helmet)
• CORS allowlist via env
• OpenAPI/Swagger UI at /docs (from TypeBox schemas)

CSRF usage

• Call GET /csrf to retrieve a CSRF token. The token is tied to your session.

• Send it in header x-csrf-token for any state-changing request (POST/PUT/PATCH/DELETE).

• Example:

  curl -c cookie.txt http://localhost:3000/csrf
  # => {"token":"..."}
  curl -b cookie.txt -H "x-csrf-token: <token>" -H "content-type: application/json" \
       -X POST -d '{"email":"dev@example.com","password":"secret123"}' http://localhost:3000/login

Stack

• Fastify, @sinclair/typebox, @fastify/swagger, @fastify/swagger-ui
• @fastify/secure-session, @fastify/csrf-protection, @fastify/helmet, @fastify/cors, @fastify/rate-limit
• Prisma ORM (+ @prisma/client)
• Argon2 password hashing (argon2id)
• Nodemailer email transport

Getting Started

Prerequisites

• Bun or Node.js 18+
• A relational DB (PostgreSQL recommended)

Installation

1. Clone the repository:

   git clone https://github.com/ShinniUwU/QuickShield.git
   cd QuickShield

2. Install dependencies:

   bun install

3. Configure environment:

   Copy .env.example to .env and fill values. Generate a session secret:

   cp .env.example .env
   openssl rand -base64 32  # paste into SESSION_SECRET

4. Run Prisma migrations:

   bunx prisma migrate dev --name init

5. Start the server:

   bun run start

   • API: http://localhost:3000
   • Docs: http://localhost:3000/docs

Endpoints

Documented at /docs. Core routes:

• POST /register — register user
• POST /login — start session (cookie)
• POST /logout — end session
• GET /me — current user
• POST /forgot-password — request reset link
• POST /reset-password — submit new password

Dev SMTP (optional)

Run a local SMTP sink on port 2525 and point .env to it for testing emails:

bun run smtp:dev

License

QuickShield is released under a permissive "Creditware" license.

You may use and modify it freely — including commercially — as long as you give credit to the original QuickShield repository and don’t resell it uncredited. See LICENSE for full terms.

Contributing

Fork the repo and open a PR. Please keep changes focused and documented.