Overview
Most development teams either rebuild authentication from scratch on every new project or hand it off to a third-party service like Auth0. The first approach is slow and inconsistent. The second means paying per user and losing control over something that sits at the core of every application you build.
This project is a third option — an internally owned, security-driven authentication and authorization baseline that can be cloned, configured, and deployed as the foundation for any new project. The system covers everything from registration through to role-based access control, with security built into every layer from the design phase rather than added afterward.
The live API is deployed at api.christianoguine.be and the full interactive documentation is available at api.christianoguine.be/api/docs.
The Problem It Solves
Every application that handles users faces the same set of decisions. How are passwords stored? How are sessions managed? What happens when a token expires? How are roles enforced? How do you handle an account that has been locked after repeated failed attempts?
These decisions get made differently on every project, often under time pressure, and the results are inconsistent. A reusable system makes these decisions once, makes them well, documents them, and carries them forward.
What Was Built
Hybrid authentication — browser clients authenticate through secure session cookies. Mobile and API clients authenticate through JWT access tokens with refresh token rotation. Both paths are handled by a single unified middleware layer, so every protected route works for both client types without any duplication.
Three-role RBAC — admin, primary, and secondary roles enforced through centralized middleware that runs before any route handler. Authorization logic is never scattered across individual endpoints. Adding a new protected route means declaring a required role — nothing else.
Full account lifecycle — registration with email verification through Resend, password recovery with time-limited single-use tokens, account lockout after five consecutive failed attempts, progressive delay on failed login attempts, and profile management with Cloudinary for media uploads.
Structured audit logging — every security-relevant event is written as structured JSON using Winston with daily log rotation. Login success, login failure, account lockout, logout, password change, token refresh, and all administrative actions are all recorded with timestamp, user ID, source IP, and event metadata.
Admin module — administrators can view all users, lock and unlock accounts, access the full audit trail, and terminate active sessions for any user account.
Live deployment — the system runs on a live VPS behind Nginx with Let's Encrypt SSL. GitHub Actions deploys automatically on every push to main. PM2 keeps the process running continuously.
Security Documentation
The project follows Secure SDLC principles throughout. The docs/ folder contains the full security foundation of the system:
- requirements.md — 22 functional requirements and 15 security requirements defined before development began
- threat-model.md — 14 identified threats using the STRIDE methodology with controls and risk ratings
- security-controls.md — 11 documented controls with verification methods
- architecture.md — system design, technology choices, and trust boundaries
- EXTENDING.md — how to adapt the system for any application domain
- NETBIRD.md — Zero Trust infrastructure setup with before and after comparison
Technology Stack
| Layer | Technology |
|---|---|
| Runtime | Node.js with TypeScript (strict) |
| Framework | Express.js |
| Database | PostgreSQL 16 |
| ORM | Drizzle ORM |
| Validation | Zod |
| Sessions | connect-pg-simple |
| Password hashing | bcrypt (cost factor 12) |
| Resend | |
| Media | Cloudinary |
| Security headers | Helmet |
| Logging | Winston + daily rotate |
| API docs | Swagger UI (OpenAPI 3.0) |
| Deployment | Hetzner VPS, Nginx, PM2 |
| CI/CD | GitHub Actions |
Key Design Decisions
Why hybrid authentication? Browser clients and API clients have different needs. Sessions provide immediate server-side revocation and native browser cookie handling. JWT provides stateless portability for API and mobile clients. A hybrid model gives each client type what it actually needs rather than forcing a compromise.
Why PostgreSQL for sessions? Storing sessions in PostgreSQL using connect-pg-simple means everything — users, sessions, tokens, audit logs — lives in the database. Simpler to deploy, simpler to maintain.
Why bcrypt at cost factor 12? Each increment of the cost factor doubles the computation time. At cost factor 12, bcrypt performs 4096 rounds and takes approximately 200-300ms on a modern server. This is imperceptible to a user logging in once but prohibitively slow for an attacker running millions of candidates against a stolen password database.
How to Extend It
The system is designed to be adopted by other projects with minimal changes. The role names (admin, primary, secondary) are generic identifiers. A marketplace maps them to seller and buyer. A booking platform maps them to host and guest. The EXTENDING.md guide covers exactly how this works and what to change for a new domain.
