OAuth & Authentication Microservice

A production-ready, high-performance, and secure Authentication Microservice built with ElysiaJS, Bun, Drizzle ORM, PostgreSQL, and Redis.

This service implements a modern stateless session architecture with robust security mechanisms like multi-device token rotation, social OAuth integrations, and WhatsApp passwordless OTP flows.

---

🚀 Key Features

• 🔒 Secure Local Auth: Sign-up and Sign-in with secure Argon2id password hashing and Nodemailer-based email verification.
• 🌐 Google OAuth Integration: Full redirection flow and authorization code exchange to link social accounts seamlessly.
• 💬 WhatsApp OTP Login: Passwordless verification utilizing Meta’s Cloud WhatsApp API, complete with sandbox fallback support for easy local development.
• 🔄 Refresh Token Rotation: Implements a secure Refresh Token Rotation (RTR) mechanism storing Argon2id hashes in a database array. Protects against token reuse attacks by instantly revoking all active sessions if reuse is detected.
• 👥 Role-Based Access Control (RBAC): Secure routes using granular access levels ('user', 'admin'). Features an Elysia-derived global context middleware (authMiddleware) and declarative route macros (roles(['admin'])).
• ⚡ Type-Safe Validation: Built-in request validation using Typebox schemas to guarantee request body, param, and query parameter integrity.
• 📦 Integration Testing Suite: Complete in-house validation suite simulating logout, token rotation, and WhatsApp OTP flows.

---

🛠️ Technology Stack

• Runtime: Bun (Fast all-in-one JS/TS runtime)
• Web Framework: ElysiaJS (End-to-end type-safe framework)
• Database ORM: Drizzle ORM
• Database: PostgreSQL
• Security & Encryption: Argon2id (for password & token hashing), JSON Web Tokens (JWT)

---

📂 Project Architecture

The codebase follows a clean, modular layer separation to make codebase scaling simple:

src/
├── config/              # App configuration, environments, CORS, and security guards
├── db/                  # DB connection initialization and schema exports
│   └── migrations/      # Autogenerated PostgreSQL migrations
├── errors/              # Custom domain exceptions and centralized error-handling middleware
├── middleware/          # Authentication context and request logging middleware
├── modules/             # Domain Feature Modules
│   └── auth/            # Encapsulated Auth module (Routes, Controllers, Repositories, Schemas)
├── utils/               # Shared helpers (JWT utilities, cookies, password crypts)
└── index.ts             # Application bootstrapper and server listener

---

⚙️ Environment Variables

Copy the .env.example file to .env and fill in the parameters:

# Application Config
PORT=3000
NODE_ENV=development

# Database Setup
DATABASE_URL=postgresql://user:password@localhost:5432/oauth_authentication

# JWT Keys
JWT_ACCESS_SECRET=your_jwt_access_secret_here
JWT_REFRESH_SECRET=your_jwt_refresh_secret_here

# Mail Config (Nodemailer/Mailtrap)
SMTP_HOST=sandbox.smtp.mailtrap.io
SMTP_PORT=2525
SMTP_USER=your_mailtrap_user
SMTP_PASS=your_mailtrap_password
SMTP_FROM=noreply@oauthauth.com

# Google OAuth Credentials
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_CALLBACK_URL=http://localhost:3000/auth/callback

# WhatsApp Cloud API Configuration
WHATSAPP_ACCESS_TOKEN=your_meta_whatsapp_access_token
WHATSAPP_PHONE_NUMBER_ID=your_whatsapp_phone_number_id
WHATSAPP_BUSINESS_ACCOUNT_ID=your_whatsapp_business_account_id
WHATSAPP_API_VERSION=v25.0

---

🛣️ API Endpoint Directory

🚪 Authentication Routes

• POST /auth/signup - Registers a new local credentials account (sends validation email).
• POST /auth/signin - Validates credentials, saves a rotated HttpOnly refresh_token cookie, and returns a short-lived accessToken.
• GET /auth/verify-email - Confirms registration via a query string token.

💬 WhatsApp OTP Routes

• POST /auth/whatsapp/send-otp - Initiates a passwordless OTP verification code sent directly via the Meta API.
• POST /auth/whatsapp/verify-otp - Validates the 6-digit OTP code, updates user verification, and signs a new session.

🌐 Google OAuth Routes

• GET /auth/google - Redirects users to the Google Account consent page.
• GET /auth/callback - Callback route that exchanges authorization codes for credentials.

🔄 Session Management

• POST /auth/refresh - Evaluates the current refresh_token cookie, runs rotation, updates the database hash array, and issues a new access token.
• POST /auth/logout - Revokes the current session's refresh token and clears client cookies.

👤 Profile & Administration

• GET /auth/me - (Protected) Retrieves the authenticated user's profile detail.
• PUT /auth/me - (Protected) Modifies user details.
• GET /auth/admin/users - (Admin Only) Lists all users registered in the database.
• DELETE /auth/admin/users/:id - (Admin Only) Deletes a user profile.

---

🚀 Getting Started

1. Install Dependencies

bun install

To run:

bun run index.ts

This project was created using bun init in bun v1.3.14. Bun is a fast all-in-one JavaScript runtime.