DEV Community: edmondgi

Why Did You Choose That Database For Your Application?

edmondgi — Thu, 11 Dec 2025 23:51:51 +0000

A confession regarding Resume-Driven Development, the "Google Scale" fallacy, and why we always just end up using Postgres anyway.

There is a sacred ritual that occurs at the beginning of every new software project.

You pour a fresh cup of coffee, you crack your knuckles, you type mkdir my-next-billion-dollar-idea, and then... you freeze.

You have hit The Wall of Persistence.

It is time to choose a database. And let’s be honest, the answer you give during the System Design interview is rarely the actual reason you picked the database for your side project.

If we were being 100% honest, most architectural decision documents would read: "We chose MongoDB because the lead developer is terrified of JOIN statements," or "We chose Cassandra because we wanted to feel like we work at Netflix."

But you need to make an actual choice. Let’s explore the chaotic decision tree of picking a database, the lies we tell ourselves, and how to actually pick the right one without crying.

The Three Horsemen of Bad Database Decisions

Before we talk about what you should do, let’s look at the traps we all fall into.

1. The "Google Scale" Delusion

You are building a To-Do list app for your cat. You expect, realistically, three users: You, your partner, and the test account you created.

Yet, you find yourself thinking: "But what about sharding? What if my cat becomes an influencer and I need write-availability across three availability zones in AWS us-east-1?"

The Reality Check: You do not have Big Data. You have Small Data. You have "fits in RAM" data. You probably have "fits in a text file" data. Do not optimize for problems you hope to have in five years. Optimize for shipping next Tuesday.

2. Resume-Driven Development (RDD)

You see a new vector database on Hacker News. It’s written in Rust. The logo is a cool geometric fox. You have no idea what a vector embedding is, but you know that if you put it on your CV, a recruiter might accidentally offer you $200k.

The Reality Check: Boring technology makes money. Exciting technology makes outages.

3. The "Schema-less" Trap

"I don't want to define a schema," you say. "I want to move fast and break things."

So you pick a Document store. Six months later, your database contains user_id as a string in half the documents, an integer in the other half, and null in the ones created on that Tuesday you were tired.

The Reality Check: You always have a schema. It’s either enforced by the database (Good) or it’s enforced by a mess of if (typeof x === 'undefined') statements in your application code (Bad).

The Actual Menu: A Guide for the Perplexed

Okay, jokes aside. You actually need to store data. Here is the breakdown of when to use what, stripped of the marketing jargon.

1. Relational Databases (SQL)

The contenders: PostgreSQL, MySQL, MariaDB

The Vibe: The responsible older sibling who does their taxes on time.

When to use it: 95% of the time. Seriously. If your data has relationships (Users have Orders, Orders have Items), use SQL. It guarantees ACID compliance (your money doesn't disappear during a transaction) and it enforces structure.

Why people avoid it: You have to learn SQL.
Why you should use it: SQL is the lingua franca of data. It will survive the heat death of the universe.

Pro Tip: Just use PostgreSQL. It supports JSON blobs now. It’s basically a relational database and a NoSQL database in a trench coat.

2. Document Stores (NoSQL)

The contenders: MongoDB, Firestore, DynamoDB

The Vibe: A chaotic artist’s loft. Throw everything in a pile; we’ll sort it out later.

When to use it:

You are prototyping and the data structure changes daily.
Your data is truly document-centric (e.g., storing a blog post with comments and tags as a single object).
Read-heavy workloads where you just want to grab an ID and get a giant JSON blob back instantly.

The Warning: Relational data in a non-relational database is a circle of hell reserved for people who enjoy writing nested loops in application code.

3. Key-Value Stores

The contenders: Redis, Memcached

The Vibe: An adrenaline junkie on a caffeine drip.

When to use it: Caching. Session management. Leaderboards.
Do not use it as: Your primary source of truth. If the server restarts and you lose your Redis instance, and that’s where your user accounts were... congratulations, you no longer have users.

4. Graph Databases

The contenders: Neo4j, Amazon Neptune

The Vibe: That conspiracy theory board with red string connecting thumbtacks.

When to use it: When the relationships between data are more important than the data itself. Social networks (friends of friends), fraud detection rings, or recommendation engines.
The Math: If your SQL query has 14 JOIN statements and takes 20 seconds to run, you probably need a graph DB.

The Final Verdict

How do you choose? Here is a simple algorithm to save you weeks of research:

Do you need to perform complex searches across vectors for an AI app? Use a Vector DB (Pinecone, Weaviate, or pgvector).
Is your data literally a social graph? Use a Graph DB.
Do you have 50 million writes per second from IoT sensors? Use a Time-Series DB.
For literally everything else? Use a Relational Database.

"But which relational database?" I hear you ask.

Pick the one you know how to host. If you don't know how to host any of them, pick Postgres, buy a managed instance for $15 a month, and go build your actual feature.

Your users don't care about your database.
They care that the login button works.

How to Build a Professional Next.js Blog with a Secure CMS

edmondgi — Thu, 11 Dec 2025 10:36:04 +0000

Building a blog is often the "Hello World" of web development, but building a production-grade publication platform is a different beast. You need a fast, SEO-friendly public site for readers and a secure, powerful dashboard for your editorial team.

In this tutorial, we will build "TechChronicles," a dual-interface application:

The Public Front: A high-performance Next.js app for readers.
The Admin Console: A restricted area for editors to draft, review, and publish content.

We will focus on the architecture, the data flow, and solving the critical challenge of managing two distinct user types (Subscribers vs. Editors) without building two separate backends.

Phase 1: The Architecture

We want to avoid the "Monolithic WordPress" trap.
We also want to avoid over-engineering microservices.

Our Stack:

Frontend: Next.js 14 (App Router)
Backend: Node.js + Express (API)
Database: PostgreSQL + Prisma ORM
Auth: Rugi Auth (Centralized Identity)

The "Dual-Face" Strategy

Instead of mixing logic, we treat the "Public User" and the "Admin User" as different contexts.

reader.techchronicles.com -> Optimized for reading, caching, and speed.
admin.techchronicles.com -> Optimized for editing, data management, and security.

Phase 2: Project Setup & Data Modeling

Let's start by defining our data. We need to store posts, but we also need to know who wrote them.

1. The Schema

In schema.prisma, we define a Post that links to an authorId.

// prisma/schema.prisma

model Post {
  id        String   @id @default(uuid())
  title     String
  slug      String   @unique
  content   String   // Markdown or HTML
  published Boolean  @default(false)
  authorId  String   // The Rugi Auth User ID
  createdAt DateTime @default(now())
}

2. The API Server

Set up a simple Express server to serve these posts.

// src/server.ts
import express from 'express';
import { prisma } from './db';

const app = express();

// Public Endpoint: Everyone can see published posts
app.get('/api/posts', async (req, res) => {
  const posts = await prisma.post.findMany({
    where: { published: true }
  });
  res.json(posts);
});

// Admin Endpoint: Create a post (Wait, we need to protect this!)
app.post('/api/posts', async (req, res) => {
  // TODO: Verify if the user is actually an editor
  // const post = await prisma.post.create(...)
});

Phase 3: The Authentication Layer

Here is where most tutorials get bogged down. You start implementing "Sign up", "Login", "Forgot Password", "Email Verification", "JWT signing"... and suddenly your blog project is an auth project.

We will skip all that boilerplate by using Rugi Auth.

1. Initialize Rugi Auth

Run the initializer in a separate folder or container alongside your API.

npx rugi-auth init auth-service

2. Configure the "Dual" Apps

This is the secret sauce. We don't just create one "App". We create two distinct logical apps in Rugi Auth that share the same user pool.

App 1: TechChronicles Public
- Goal: Allow readers to subscribe/comment.
- Type: Public
- Roles: SUBSCRIBER
App 2: TechChronicles Admin
- Goal: Allow staff to write news.
- Type: Confidential
- Roles: EDITOR, ADMIN

3. Integrating the Protection

Now, back to our API. We can secure that POST route.

// src/middleware/auth.ts
import { verifyToken } from './utils'; // Your standard JWT verification

export const requireEditor = async (req, res, next) => {
  const token = req.headers.authorization?.split(' ')[1];
  const user = await verifyToken(token);

  // Check if they have the 'EDITOR' role specifically for the Admin App
  const adminRole = user.roles.find(r => 
    r.appId === process.env.ADMIN_APP_ID && 
    r.name === 'EDITOR'
  );

  if (!adminRole) return res.status(403).send("Editors only.");

  req.userId = user.id;
  next();
};

Phase 4: Building the Frontends

The Public Reader Site (Next.js)

This is standard Next.js. We fetch the published posts.

// app/page.tsx
export default async function HomePage() {
  const posts = await fetch('http://api/posts').then(r => r.json());

  return (
    <main>
      <h1>Latest News</h1>
      {posts.map(post => (
        <article key={post.id}>
          <h2>{post.title}</h2>
          <p>{post.excerpt}</p>
        </article>
      ))}
    </main>
  );
}

The Admin Dashboard (React/Next.js)

This is where Rugi Auth shines. We need a login screen.

Instead of coding form state, error handling, and validation:

Create a "Login" button.
Redirect the user to your Rugi Auth hosted login page: http://localhost:7100/auth/login?client_id=ADMIN_APP_ID

When they successfully log in as an Editor, they are redirected back to your dashboard with a secure token.

// app/admin/dashboard/page.tsx
"use client";

// This page is only accessible if you have a valid token
export default function Dashboard() {
  const { createPost } = useApi();

  return (
    <div>
      <h1>Editor Dashboard</h1>
      <button onClick={() => createPost({ title: "New Article" })}>
        Publish Article
      </button>
    </div>
  );
}

Why This Approach Wins

Separation of Concerns: Your public blog code doesn't know about "admin rights". It just displays content. Your API handles the gatekeeping.
Unified Identity: If a Subscriber is promoted to an Editor, you just add a role in Rugi Auth. You don't need to migrate their account.
Speed: We built a secure, role-protected CMS backend in minutes by offloading the complex user management logic.

Next Steps

Add a "Comments" section to the public site, requiring the SUBSCRIBER role.
Add an "Admin-Only" route to manage users (which proxies requests to Rugi Auth's API).

Building a Scalable E-Commerce Platform: From Storefront to Warehouse

edmondgi — Thu, 11 Dec 2025 10:17:16 +0000

In the world of e-commerce, trust is currency.
Your customers need to feel safe entering their details, and your operations team needs secure access to order data without risking a data breach.

This guide walks you through architecting a full-stack e-commerce solution called "MarketMinds". We will build:

The Storefront: Where customers browse and buy.
The Ops Dashboard: Where support staff manage orders.
The Command Center: Where super admins configured global settings.

Step 1: The Core Data Model

E-commerce data is relational. We have Users, Products, and Orders.

// schema.prisma

model Product {
  id          String   @id @default(uuid())
  name        String
  price       Decimal
  stock       Int
  orders      OrderItem[]
}

model Order {
  id        String    @id @default(uuid())
  userId    String    // The customer's ID
  total     Decimal
  status    String    // PENDING, SHIPPED, DELIVERED
  items     OrderItem[]
}

model OrderItem {
  orderId   String
  productId String
  quantity  Int

  order   Order   @relation(fields: [orderId], references: [id])
  product Product @relation(fields: [productId], references: [id])
}

Notice userId in the Order model. We strictly decouple our "Business Data" (Orders) from "Identity Data" (Passwords/Emails). This is a security best practice.

Step 2: Designing the Storefront API

Customers need to browse products (Public) and place orders (Authenticated).

// routes/storefront.ts
import express from 'express';
const router = express.Router();

// PUBLIC: Anyone can view products
router.get('/products', async (req, res) => {
  const products = await prisma.product.findMany();
  res.json(products);
});

// PROTECTED: Only logged-in customers can buy
router.post('/checkout', requireAuth, async (req, res) => {
  const userId = req.user.id; // Extracted from token
  // Business logic: create order, decrement stock, charge payment...
});

The Authentication Puzzle

We need customers to sign up, verify email, and log in. Building this from scratch is high-risk.
If you mess up password hashing or session storage, your store is finished.

Enter Rugi Auth.
We treat it as our dedicated Identity Provider.

Create the 'MarketMinds Storefront' App in Rugi Auth.
Enable "Subscribers" or "Customers" role by default.
Set up Google OAuth in the Rugi Auth settings so customers can sign in with one click.

Now, requireAuth just verifies the JWT signature.

Step 3: The Support Dashboard (Internal Tool)

Now comes the complex part. You hire a Customer Support agent, Alice.

Alice needs to see all orders (unlike a customer).
Alice should not be able to change the database schema or delete products.

We create a second app in Rugi Auth: "MarketMinds Internal".

Implementing Role-Based Access Control (RBAC)

We define strictly scoped roles for this internal app:

SUPPORT_AGENT: Can view orders, process refunds.
INVENTORY_MGR: Can update product stock and prices.

The Backend Logic:

// routes/admin.ts

// Middleware to check specific permissions
const assertRole = (role) => (req, res, next) => {
  // Check if the user has this role for the INTERNAL app
  if (!req.user.roles.includes(role)) throw new Error("Unauthorized");
  next();
};

// Route: Refund an order
router.post('/orders/:id/refund', 
  requireAuth, 
  assertRole('SUPPORT_AGENT'), 
  async (req, res) => {
    // Logic to refund order
    console.log(`User ${req.user.id} refunded order ${req.params.id}`);
    res.send("Refunded");
  }
);

// Route: Update Inventory
router.post('/products/:id/stock',
  requireAuth,
  assertRole('INVENTORY_MGR'),
  async (req, res) => {
    // Logic to update stock
  }
);

Step 4: The Super Admin (Founders)

You don't want your Support Agents to have Global Admin power.
In Rugi Auth, you can create a specialized role, or even a separate Command Center app, that is only accessible to you.

This isolation is powerful. If a Support Agent's laptop is compromised and their token is stolen, the attacker cannot access the "Delete Database" endpoints because that token is scoped only to the SUPPORT_AGENT role, not SUPER_ADMIN.

Step 5: Frontend Integration

For your internal dashboard, you normally want a quick, data-heavy UI.

The "Magic Link" Effect:
Because you are using a centralized auth system, your employees can have a seamless experience.

Alice logs into the Inventory App to update stock.
She gets a customer complaint and clicks "View Order in Support Portal".
She is redirected to the Support App.
Rugi Auth recognizes her session and automatically logs her in (SSO), provided she has permissions for the Support App.

This frictionless flow improves employee productivity while maintaining strict security boundaries.

Summary

By separating your E-Commerce platform into distinct logical "Apps" (Storefront, Internal Tools), you achieve:

Better Security: Least-privilege access.
Cleaner Code: Your storefront API doesn't need "Inventory Management" logic.
Scalability: You can spin up new microservices (e.g., a "Driver App" for delivery) and just hook them into the existing Auth ecosystem.

Architecting a B2B SaaS: Multi-Tenancy Made Simple

edmondgi — Thu, 11 Dec 2025 10:11:49 +0000

Building business software (SaaS) is different from consumer apps.

You aren't just managing users; you are managing Teams (or Organizations/Tenants).

In this tutorial, we will build "TaskFlow," a Trello-like project management tool where:

Users can belong to multiple Organizations (e.g., "Work", "Side Project").
Each Organization has its own Projects and Billing.
Data must be strictly isolated (Tenant A cannot see Tenant B's data).

Phase 1: The Multi-Tenant Data Model

The database schema is the foundation of multi-tenancy.
Every resource must "belong" to an organization.

// schema.prisma

model Organization {
  id        String   @id @default(uuid())
  name      String
  slug      String   @unique // e.g., taskflow.com/acme-corp
  members   OrgMember[]
  projects  Project[]
}

model OrgMember {
  id        String   @id @default(uuid())
  orgId     String
  userId    String   // The Rugi Auth User ID
  role      String   // 'OWNER', 'MEMBER', 'GUEST'

  organization Organization @relation(fields: [orgId], references: [id])

  @@unique([orgId, userId]) // User can join an org only once
}

model Project {
  id        String   @id @default(uuid())
  orgId     String
  title     String
  tasks     Task[]

  // CRITICAL: Linking project to Org ensures isolation
  organization Organization @relation(fields: [orgId], references: [id])
}

Phase 2: Resolving Identity vs. Context

Here is the conceptual leap:
Identity is "Who are you?" (I am Alice).
Context is "Where are you?" (I am currently working in Acme Corp).

Many developers make the mistake of creating a new user account for every organization (alice@acme.com, alice@beta.com). This is a nightmare for users.

The Better Way (Powered by Rugi Auth):

Alice has One Identity in Rugi Auth.
Your application handles the Context.

Step 1: Authentication (Identity)

Alice logs in via Rugi Auth. We get her userId.

Step 2: Tenant Resolution (Context)

When Alice visits app.taskflow.com/acme-corp/dashboard:

Middleware Check: Is Alice authenticated? (Yes, valid Token).
Membership Check: Does OrgMember table have an entry for userId: Alice AND orgId: AcmeCorp?
- Yes: Proceed.
- No: 403 Forbidden.

// middleware/tenant.ts
import { prisma } from './db';

export const requireTenantMembership = async (req, res, next) => {
  const userId = req.user.id;
  const orgSlug = req.params.orgSlug; // from URL

  const member = await prisma.orgMember.findFirst({
    where: {
      userId,
      organization: { slug: orgSlug }
    }
  });

  if (!member) {
    return res.status(403).json({ error: "You are not a member of this organization" });
  }

  // Attach membership info to request for downstream use
  req.memberRole = member.role;
  req.orgId = member.orgId;
  next();
};

Phase 3: Invitation System (Growth Engine)

SaaS grows via invites. "Alice invites Bob to Acme Corp."

Frontend: Alice enters Bob's email in the dashboard.
Backend:
- Check if Bob already has a Rugi Auth account?
- If Yes: Add entry to OrgMember. Send email "You've been added!".
- If No: create a "Pending Invite".

Using Rugi Auth's Registration API:
You can pre-provision users or simply send them to your registration page.
When Bob finally registers with that email, your webhook (or post-registration hook) detects the pending invite and automatically adds him to the organization.

Phase 4: Billing & Admin (Global Scope)

You, as the SaaS builder, need a "God Mode" to see who is paying.

In Rugi Auth, define a role SAAS_SUPER_ADMIN in your app configuration.

// routes/billing.ts

// Only for YOU
router.get('/all-tenants', requireRole('SAAS_SUPER_ADMIN'), async (req, res) => {
  const allOrgs = await prisma.organization.findMany({
    include: { _count: { select: { members: true } } }
  });
  res.json(allOrgs);
});

This keeps your "Super Admin" logic completely separate from the "Organization Owner" logic, preventing the accidental "Customer A sees Customer B" bugs.

Summary

Building a SaaS is about rigorous data isolation.

Rugi Auth handles the global "Who is this person?" question.
Your App handles the huge "Which team are they on?" matrix.

This separation allows your SaaS to support users who belong to 50 different teams with a single login, a feature users love and expect from modern tools.

Modernizing Enterprise IT: The Unified Internal Portal

edmondgi — Thu, 11 Dec 2025 10:04:15 +0000

Every growing company eventually ends up with "The Tool Sprawl."

Utilization: "Log into the HR portal for leave."
Finance: "Log into the Payroll system (different password)."
Engineering: "Log into the Jenkins dashboard."

Employees are frustrated, and IT is overwhelmed with password resets.
The solution is Single Sign-On (SSO), usually via an expensive enterprise vendor. Today, we will build our own using Rugi Auth.

We will simulate a fragmented corporate environment and unify it.

The Components

The "Legacy" System: A PHP-based employee directory (simulated).
The "Modern" System: A Node.js Analytics Dashboard.
The Identity Provider (IdP): Rugi Auth hosted on auth.internal.corp.

Step 1: Setting up the Identity Provider

We deploy Rugi Auth internally. We create two Apps in the dashboard:

Legacy Directory (Client ID: legacy-app)
Analytics Dash (Client ID: analytics-app)

We also enable LDAP or just use the database to store employee credentials centrally.

Step 2: The "Portal" (The Launchpad)

We build a simple static HTML page or a lightweight React app that serves as the "Dock" for employees.

<!-- portal.html -->
<h1>Welcome, Employee</h1>
<div id="user-info">Loading...</div>

<div class="apps">
  <a href="http://hr.internal.corp/login?sso=true">Go to HR Directory</a>
  <a href="http://analytics.internal.corp/login?sso=true">Go to Analytics</a>
</div>

<script>
  // Check if we have a valid Rugi Auth session
  async function checkSession() {
    const user = await fetch('http://auth.internal.corp/me');
    if (user.ok) {
      document.getElementById('user-info').innerText = `Hello ${user.email}`;
    } else {
      window.location.href = 'http://auth.internal.corp/login';
    }
  }
  checkSession();
</script>

Step 3: Integrating the "Modern" Node.js App

This is easy. The Analytics app uses standard JWT validation.

Login Flow:
The user clicks "Login with SSO". We redirect them to Rugi Auth.
http://auth.internal.corp/login?client_id=analytics-app&redirect_uri=...
Callback:
Rugi Auth validates the user (who is already logged in from the Portal!) and immediately redirects back with a code/token.
Token Validation:
The Node app validates the token against Rugi Auth's public keys (JWKS).

// Standard JWT verification using jwks-rsa
const client = jwksClient({
  jwksUri: 'http://auth.internal.corp/.well-known/jwks.json'
});
// ... verify token signature ...

Step 4: Integrating the "Legacy" PHP App

This is often the scary part.

How do you teach a 10-year-old PHP script to understand modern Auth?

You don't need to rewrite the app, You just need a Bridge Script.

The PHP Logic (login.php):

<?php
// 1. Capture the ID Token sent from the redirect
$token = $_GET['access_token'];

// 2. Verify it (Simpler method: call the introspection endpoint)
// In a real high-traffic app, you'd verify the signature locally in PHP.
// For internal tools, asking Rugi Auth "Is this valid?" is fine.

$ch = curl_init('http://auth.internal.corp/me');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $token]);
$response = curl_exec($ch);
$user = json_decode($response);

if ($user->id) {
    // SUCCESS!
    // Set the LEGACY session variable that the old app expects
    $_SESSION['user_id'] = $user->id;
    $_SESSION['is_logged_in'] = true;

    header('Location: /dashboard.php');
} else {
    die("SSO Failed");
}
?>

By adding this one login.php file, you have effectively "modernized" the authentication of a legacy artifact without touching its spaghetti core code.

Step 5: The Employee Experience

Morning: Employee logs into the Portal. (Enters password once).
Mid-day: Opens Analytics. The app detects no session, redirects to Rugi Auth. Rugi Auth sees the cookie from the morning, and immediately redirects back with a token. Zero typing.
Afternoon: Opens Legacy HR. Same thing.

Summary

In an enterprise environment, "Full Stack" often means gluing together different generations of technology.
Rugi Auth serves as the Universal Adapter.

It speaks JWT/OIDC for your modern React/Node apps.
It provides simple REST endpoints that even a bash script or PHP 5 app can consume to verify identity.

This centralization creates a single point of control.
When an employee leaves, you disable them in Rugi Auth, and they are instantly locked out of the Portal, the Analytics, AND the Legacy HR system.

Building Secure Multi-App Authentication with rugi-auth: A Complete Guide

edmondgi — Mon, 08 Dec 2025 11:20:14 +0000

Centralized authentication that scales across your entire application ecosystem

Introduction

In today's microservices and multi-application architectures, managing authentication can become a nightmare.
Each service needs to verify users, handle tokens, manage roles, and maintain security-often duplicating logic across multiple codebases. What if you could centralize all of this into a single, secure, battle-tested authentication service?

Enter rugi-auth: a production-ready, centralized authentication service built with TypeScript, Express, and Prisma.
It provides enterprise-grade security features while remaining simple to integrate and deploy.

What is rugi-auth?

rugi-auth is a secure, centralized authentication service designed for modern application architectures.
It enables a single user identity to work seamlessly across multiple applications while maintaining granular, app-specific role management.
Think of it as your own Auth0 or Okta, but open-source and fully customizable.

Core Philosophy

Centralized Identity: One user account works across all your applications
Security First: Built with industry-standard security practices from day one
Developer Friendly: Simple integration, comprehensive documentation, and TypeScript support
Production Ready: Battle-tested features like rate limiting, audit logging, and token rotation

Key Features

1. Multi-App Architecture

Unlike traditional auth systems that tie users to a single application, rugi-auth supports multiple applications (clients) with a shared user base. Each user can have different roles in different applications:

User: john@example.com
├── E-commerce App    → roles: ['customer', 'reviewer']
├── Admin Dashboard   → roles: ['admin']
└── Content Platform  → roles: ['author', 'editor']

This architecture is perfect for:

SaaS platforms with multiple products
Microservices architectures
Organizations with separate internal and customer-facing apps
White-label solutions

2. Multiple Authentication Methods

rugi-auth supports various authentication methods, all configurable per application:

Email + Password: Traditional authentication with secure password hashing
Email + OTP: Passwordless authentication via one-time passwords
OAuth Providers: Google, GitHub, Microsoft, and Facebook (with more coming)
Custom Methods: Extensible architecture for adding new providers

Each application can enable or disable specific authentication methods based on their needs.

3. App-Specific Role Management

Roles are scoped to applications, meaning a user can be an "admin" in one app and a "user" in another.

This provides:

Granular Permissions: Fine-grained access control per application
Security Isolation: Roles in one app don't affect another
Flexible Management: Assign roles programmatically or via API

4. JWT with RS256 and JWKS

rugi-auth uses industry-standard JWT tokens signed with RSA-256:

RS256 Algorithm: Asymmetric encryption ensures tokens can be verified without exposing secrets
JWKS Endpoint: Public keys are exposed via /.well-known/jwks.json for easy token verification
Key Rotation: Support for key rotation without service downtime
Stateless Verification: Consumer applications verify tokens without database lookups

5. Refresh Token Rotation

For enhanced security, refresh tokens are rotated on every use:

// First refresh
POST /refresh
{ refresh_token: "old-token" }
→ { access_token: "...", refresh_token: "new-token-1" }

// Second refresh (old token is now invalid)
POST /refresh
{ refresh_token: "new-token-1" }
→ { access_token: "...", refresh_token: "new-token-2" }

This prevents token reuse attacks and ensures compromised tokens become useless quickly.

6. Comprehensive Audit Logging

Every authentication event is logged for security auditing:

User registrations
Login attempts (successful and failed)
Token refreshes
Role assignments
Password reset requests
OTP requests and usage

This provides complete visibility into authentication activities for compliance and security monitoring.

Use Cases

1. Microservices Architecture

In a microservices setup, each service needs to verify user identity. With rugi-auth, services can verify JWT tokens independently without sharing databases or secrets:

// In your microservice
import { createAuthMiddleware } from 'rugi-auth/client';

const auth = createAuthMiddleware({
  jwksUri: 'https://auth.example.com/.well-known/jwks.json',
  issuer: 'rugi-auth',
  audience: 'your-service-id',
});

app.get('/api/orders', auth, (req, res) => {
  // req.user is automatically populated
  const orders = getOrdersForUser(req.user.userId);
  res.json({ orders });
});

Benefits:

No shared database between services
Stateless token verification
Independent service scaling
Centralized user management

2. Multi-Product SaaS Platform

If you're building a SaaS platform with multiple products (e.g., a CRM, an analytics dashboard, and a marketing tool), rugi-auth enables:

Single sign-on across all products
Product-specific roles and permissions
Unified user management
Centralized billing and subscription tracking

3. White-Label Solutions

For white-label applications where you need to support multiple client organizations:

Each client gets their own application instance
Users can have different roles per client
Centralized authentication reduces operational overhead
Easy onboarding of new clients

4. Enterprise Applications

Large organizations often have multiple internal tools:

HR systems
Project management tools
Internal dashboards
Customer-facing applications

rugi-auth provides a single identity provider for all these systems while maintaining appropriate access controls.

5. API Gateway Authentication

Use rugi-auth as the authentication layer for your API gateway:

All API requests are authenticated via JWT
Gateway verifies tokens using JWKS
Backend services receive validated user context
Centralized token management

Benefits

1. Reduced Development Time

Instead of implementing authentication in every application, you set it up once:

No repeated code: Authentication logic lives in one place
Faster feature development: Focus on business logic, not auth
Consistent behavior: All apps use the same authentication flow
Easy updates: Security improvements benefit all applications

2. Enhanced Security

rugi-auth implements security best practices out of the box:

Argon2id Password Hashing: Memory-hard algorithm resistant to GPU attacks
Rate Limiting: Redis-backed distributed rate limiting prevents brute force attacks
Timing Attack Protection: Constant-time operations prevent user enumeration
Token Rotation: Refresh tokens rotate on use, limiting attack windows
Audit Logging: Complete visibility into authentication events

3. Scalability

Designed for scale:

Stateless Tokens: No database lookups for token verification
Redis Rate Limiting: Distributed rate limiting across multiple instances
Horizontal Scaling: Run multiple instances behind a load balancer
Database Optimization: Efficient queries with proper indexing

4. Developer Experience

Built with developers in mind:

TypeScript Support: Full type safety and IntelliSense
Lightweight Client: Consumer apps only need 2 dependencies (jsonwebtoken, jwks-rsa)
Comprehensive Documentation: Integration guides, API references, and examples
CLI Tools: Scaffold projects, generate keys, create superadmins
Swagger UI: Interactive API documentation at /docs

5. Flexibility

Highly configurable to fit your needs:

Per-App Settings: Enable/disable authentication methods per application
Custom Roles: Define roles specific to each application
Email Configuration: Customize email templates and SMTP settings per app
OAuth Providers: Enable Google, GitHub, Microsoft, or Facebook per app

6. Cost Efficiency

Open-source alternative to commercial solutions:

No Per-User Fees: Unlike Auth0 or Okta, no cost per user
Self-Hosted: Full control over infrastructure and data
No Vendor Lock-in: Your data, your rules
Customizable: Modify to fit your exact requirements

Security Measures

Security is at the core of rugi-auth. Here's a deep dive into the security measures implemented:

1. Password Security

Argon2id Hashing

rugi-auth uses Argon2id, the winner of the Password Hashing Competition, for password hashing:

// Configuration
const ARGON2_OPTIONS = {
  type: argon2.argon2id,      // Hybrid approach (resistant to both side-channel and GPU attacks)
  memoryCost: 65536,           // 64MB memory
  timeCost: 3,                // 3 iterations
  parallelism: 4,             // 4 threads
};

Why Argon2id?

Memory-Hard: Requires significant memory, making GPU attacks expensive
Side-Channel Resistant: Constant-time operations prevent timing attacks
Tunable: Adjust memory, time, and parallelism based on your security needs

Timing Attack Protection

The login flow is designed to prevent timing attacks that could reveal whether a user exists:

// Both paths take similar time
// Non-existent user: hash verification attempt (constant time)
// Wrong password: hash verification attempt (constant time)
// Result: Attacker can't distinguish between "user doesn't exist" and "wrong password"

This is tested to ensure execution times are within 50-100ms of each other, regardless of whether the user exists or the password is wrong.

2. Token Security

RS256 Algorithm

Tokens are signed using RS256 (RSA with SHA-256), an asymmetric algorithm:

Private Key: Used by auth service to sign tokens (never exposed)
Public Key: Used by consumer apps to verify tokens (exposed via JWKS)
Benefits: Consumer apps can verify tokens without knowing the secret

JWKS (JSON Web Key Set)

Public keys are exposed via a standard JWKS endpoint:

GET /.well-known/jwks.json
{
  "keys": [
    {
      "kty": "RSA",
      "kid": "abc123",
      "use": "sig",
      "n": "...",
      "e": "AQAB"
    }
  ]
}

This follows OAuth 2.0 and OpenID Connect standards, making integration with standard libraries straightforward.

Token Claims

Tokens include standard JWT claims plus custom claims:

{
  sub: "user-id",           // Subject (user ID)
  aud: "client-id",         // Audience (application client ID)
  tid: "app-id",            // Tenant ID (application ID)
  roles: ["admin", "user"], // User roles for this app
  iss: "rugi-auth",         // Issuer
  iat: 1234567890,          // Issued at
  exp: 1234567890           // Expires at
}

Refresh Token Rotation

Refresh tokens rotate on every use:

Client uses refresh token to get new access token
Server generates new refresh token
Old refresh token is immediately invalidated
Client must save the new refresh token

This ensures that if a refresh token is compromised, it can only be used once before becoming invalid.

3. Rate Limiting

rugi-auth implements Redis-backed distributed rate limiting:

Authentication Endpoints

// Standard rate limiter
windowMs: 15 minutes
maxRequests: 100 requests per window

Sensitive Operations

// Stricter rate limiter for password reset, OTP requests
windowMs: 15 minutes
maxRequests: 3 requests per window

Features:

Distributed: Works across multiple server instances
Redis-Backed: Persistent rate limiting across restarts
IP-Based: Uses req.ip (respects trust proxy setting)
Graceful Fallback: Falls back to memory store if Redis is unavailable

4. Input Validation

All inputs are validated using Joi schemas:

Email Validation: RFC-compliant email validation
Password Strength: Configurable password requirements
Client Credentials: Validates client_id and client_secret format
Token Validation: Validates token structure before processing

5. SQL Injection Protection

rugi-auth uses Prisma ORM, which:

Parameterized Queries: All queries use parameterized statements
Type Safety: TypeScript types prevent invalid queries
SQL Injection Prevention: Built-in protection against SQL injection

6. CORS and Security Headers

Configurable CORS and security headers:

CORS: Configurable allowed origins
Helmet.js: Security headers (X-Content-Type-Options, X-Frame-Options, etc.)
HTTPS Enforcement: Can enforce HTTPS in production

7. Audit Logging

Comprehensive audit logging for security monitoring:

// All events are logged
- LOGIN (successful and failed)
- REGISTER
- REFRESH
- REVOKE
- ROLE_ASSIGN
- PASSWORD_RESET_REQUEST
- PASSWORD_RESET_COMPLETE
- OTP_REQUEST
- OTP_LOGIN

Each log entry includes:

User ID (if applicable)
Action type
Timestamp
Metadata (IP address, user agent, etc.)

8. Client Secret Security

For confidential applications, client secrets are:

Hashed: Stored as Argon2id hashes (not plaintext)
Validated: Verified on every authentication request
Rotatable: Can be rotated without affecting existing tokens

9. Email Security

OTP and password reset emails:

Time-Limited: Codes expire after a set duration (default: 10 minutes)
Single-Use: OTP codes can only be used once
Rate Limited: Prevents email spam and brute force attacks

10. Database Security

Indexed Queries: Efficient queries prevent timing-based enumeration
Cascade Deletes: Proper cleanup when users or apps are deleted
Transaction Safety: Critical operations use database transactions

Getting Started

Quick Setup

rugi-auth can be set up in minutes:

# 1. Initialize a new project
npx rugi-auth init my-auth-service

# 2. Start infrastructure
cd my-auth-service
docker-compose up -d

# 3. Run migrations and setup
npm run prisma:migrate
npm run setup

# 4. Start the server
npm run dev

Your authentication service is now running at http://localhost:7100!

Integration Example

Integrating with your Express application is straightforward:

// Install the lightweight client
npm install rugi-auth

// In your Express app
import { createAuthMiddleware, requireRole } from 'rugi-auth/client';

const auth = createAuthMiddleware({
  jwksUri: 'https://auth.example.com/.well-known/jwks.json',
  issuer: 'rugi-auth',
  audience: 'your-client-id',
});

// Protect routes
app.get('/api/profile', auth, (req, res) => {
  res.json({
    userId: req.user.userId,
    roles: req.user.roles,
  });
});

// Role-based access control
app.get('/api/admin', auth, requireRole('admin'), (req, res) => {
  res.json({ message: 'Admin access granted' });
});

Authentication Flow

User Registration/Login: User authenticates with rugi-auth service
Token Issuance: Service issues JWT access token and refresh token
API Requests: Client includes access token in Authorization: Bearer <token> header
Token Verification: Your app verifies token using JWKS (no database lookup needed)
Token Refresh: When access token expires, use refresh token to get new tokens

Architecture Overview

Standalone Service (Recommended)

Deploy rugi-auth as a separate service:

┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│   Client    │      │  Your Apps   │      │  rugi-auth  │
│  (Browser)  │      │  (Express)   │      │   Service   │
└──────┬──────┘      └──────┬───────┘      └──────┬──────┘
       │                    │                      │
       │ 1. Login            │                      │
       │──────────────────────────────────────────>│
       │                    │                      │
       │ 2. JWT Tokens       │                      │
       │<──────────────────────────────────────────│
       │                    │                      │
       │ 3. API Request     │                      │
       │    (Bearer token)  │                      │
       │───────────────────>│                      │
       │                    │                      │
       │                    │ 4. Verify via JWKS  │
       │                    │─────────────────────>│
       │                    │                      │
       │                    │ 5. Public Key        │
       │                    │<─────────────────────│
       │                    │                      │
       │ 6. Response        │                      │
       │<───────────────────│                      │

Benefits:

Microservices can verify tokens independently
No shared database between services
Centralized user management
Easy to scale

Package Import (Monolith)

For monolithic applications, import rugi-auth directly:

import { authMiddleware, roleMiddleware } from 'rugi-auth';

app.get('/protected', authMiddleware, (req, res) => {
  // req.user is available
});

Real-World Example: E-Commerce Platform

Imagine you're building an e-commerce platform with:

Customer App: Public-facing store
Admin Dashboard: Internal management tool
Vendor Portal: For third-party sellers
Analytics Service: Separate microservice

With rugi-auth, you can:

Single Sign-On: Users log in once, access all apps
Role-Based Access:
- Customers have customer role in customer app
- Admins have admin role in admin dashboard
- Vendors have vendor role in vendor portal
Microservice Authentication: Analytics service verifies tokens via JWKS
Centralized Management: Manage all users from one place

Comparison with Alternatives

Feature	rugi-auth	Auth0	Okta	Firebase Auth
Cost	Free (self-hosted)	Per-user pricing	Per-user pricing	Free tier, then per-user
Self-Hosted	✅ Yes	❌ No	❌ No	❌ No
Multi-App Support	✅ Native	✅ Yes	✅ Yes	⚠️ Limited
App-Specific Roles	✅ Yes	⚠️ Complex	⚠️ Complex	❌ No
Customization	✅ Full	⚠️ Limited	⚠️ Limited	⚠️ Limited
Open Source	✅ Yes	❌ No	❌ No	❌ No
TypeScript	✅ Native	⚠️ SDK only	⚠️ SDK only	⚠️ SDK only

Best Practices

1. Token Storage

Client-Side:

Use httpOnly cookies when possible (prevents XSS)
If using localStorage, ensure HTTPS only
Never log tokens to console

Server-Side:

Store refresh tokens securely (encrypted database)
Implement token rotation
Monitor for token abuse

2. Rate Limiting

Configure appropriate rate limits:

Authentication: 100 requests per 15 minutes
Password Reset: 3 requests per 15 minutes
OTP Requests: 5 requests per 15 minutes

3. Monitoring

Monitor authentication events:

Failed login attempts
Token refresh patterns
Role assignment changes
Unusual access patterns

4. Key Rotation

Rotate RSA keys periodically:

Generate new key pair
Update JWKS endpoint
Old tokens remain valid until expiry
New tokens use new key

5. HTTPS

Always use HTTPS in production:

Protects tokens in transit
Prevents man-in-the-middle attacks
Required for secure cookies

Conclusion

rugi-auth provides a robust, secure, and developer-friendly solution for centralized authentication. Whether you're building microservices, a multi-product SaaS platform, or an enterprise application suite, rugi-auth gives you:

✅ Security: Industry-standard practices out of the box
✅ Scalability: Designed to handle growth
✅ Flexibility: Configurable for your specific needs
✅ Developer Experience: TypeScript, comprehensive docs, easy integration
✅ Cost Efficiency: Open-source, self-hosted, no per-user fees

Getting Started

GitHub: https://github.com/EDMONDGIHOZO/rugi-auth
Documentation: See /docs directory in the repository
Examples: Check /examples for integration examples

Join the Community

Report issues, suggest features, or contribute on GitHub
Share your integration stories and use cases

Ready to centralize your authentication? Give **rugi-auth* a try and experience the benefits of secure, scalable, multi-app authentication.*

About the Author

This article was written to help developers understand the power and capabilities of rugi-auth, a production-ready authentication service built for modern application architectures.

Keywords: Authentication, JWT, OAuth, Microservices, TypeScript, Express, Security, Multi-Tenant, RBAC, Centralized Auth

The Hidden Vulnerabilities in Your Authentication System: A Deep Dive into Timing Attacks, IP Spoofing, and Race Conditions

edmondgi — Sun, 07 Dec 2025 20:24:12 +0000

How we discovered and fixed critical security flaws that most authentication systems overlook

Introduction
Authentication is the foundation of application security.

Yet, many developers even experienced ones overlook subtle vulnerabilities that can expose user data, enable account enumeration, or allow attackers to bypass rate limiting.

Over the past few months, I've been working on hardening an authentication service, and what I discovered shocked me: three critical vulnerabilities that are surprisingly common in production systems.

In this article, I'll walk you through these vulnerabilities, explain why they're dangerous, and show you how to fix them. Whether you're building your own auth system or evaluating third-party solutions, understanding these issues is crucial.

Vulnerability #1: Timing Attacks on Password Verification
The Problem
Imagine an attacker trying to guess a user's password.
They send login requests with different passwords and measure the response time.

If the server takes longer to respond when the username exists (even with a wrong password), the attacker knows the account exists. This is called a timing attack.

Here's what was happening in our code:

The vulnerability: When a user doesn't exist, the function returns immediately. When a user exists but the password is wrong, it performs the expensive password verification first.
This timing difference leaks information.

Why It Matters

Account Enumeration: Attackers can determine which email addresses are registered
User Privacy: Violates privacy by revealing account existence
Targeted Attacks: Attackers can focus on known accounts
The Fix
We implemented constant-time verification by always performing password verification, even for non-existent users:

// SECURE CODE
const user = await findUserByEmail(email);
const DUMMY_HASH = '$argon2id$v=19$m=65536,t=3,p=4$...'; // Pre-computed hash

// Always perform both verifications in parallel
const [, realResult] = await Promise.all([
  verifyPassword(DUMMY_HASH, DUMMY_PASSWORD), // Dummy verification (always fails)
  user && user.passwordHash 
    ? verifyPassword(user.passwordHash, input.password)
    : verifyPassword(DUMMY_HASH, DUMMY_PASSWORD), // Dummy if no user
]);

if (!user || !user.passwordHash || !realResult) {
  throw new AuthError('Invalid credentials');
}

Key improvements:

Both paths take similar time (constant-time execution)
No information leakage about user existence
Parallel execution maintains performance
Vulnerability #2: IP Spoofing in Rate Limiting
The Problem
Rate limiting is essential for preventing brute-force attacks. However, many implementations trust the X-Forwarded-For header directly, which can be easily spoofed by attackers.

// VULNERABLE CODE
const ip = req.headers['x-forwarded-for']?.split(',')[0] || req.ip;
// Use IP for rate limiting

The vulnerability: Attackers can send fake X-Forwarded-For headers to bypass rate limits or frame innocent users.

Why It Matters
Bypass Rate Limits: Attackers can make unlimited requests
IP Spoofing: Frame legitimate users by using their IPs
DDoS Amplification: Distribute attacks across multiple fake IPs
The Fix
We fixed this by relying on Express's built-in req.ip, which respects the trust proxy setting:

// SECURE CODE
// In app.ts - configure trust proxy properly
if (env.nodeEnv === 'production') {
  app.set('trust proxy', true); // Trust reverse proxy
} else if (process.env.TRUST_PROXY) {
  app.set('trust proxy', process.env.TRUST_PROXY);
}

// In rate limiter
keyGenerator: (req) => {
  // req.ip respects 'trust proxy' setting
  // Express validates X-Forwarded-For when trust proxy is configured
  return req.ip || 'unknown';
}

Key improvements:

Express validates proxy headers when trust proxy is set
No manual header parsing (which can be spoofed)
Proper configuration for production deployments

Vulnerability #3: Race Condition in OTP Verification
The Problem
When verifying one-time passwords (OTPs), there's a critical window between checking if an OTP is valid and marking it as used.
An attacker can exploit this with concurrent requests.

// VULNERABLE CODE (TOCTOU - Time of Check, Time of Use)
const otp = await findOTP(userId, code);

if (!otp || otp.used || otp.expiresAt < new Date()) {
  throw new AuthError('Invalid OTP');
}

// ⚠️ RACE CONDITION WINDOW: Another request could verify the same OTP here

await markOTPAsUsed(otp.id);

The vulnerability: Two simultaneous requests can both verify the same OTP before either marks it as used.

Why It Matters
OTP Reuse: Attackers can use the same OTP multiple times
Security Bypass: Defeats the purpose of one-time passwords
Account Takeover: Multiple login sessions from a single OTP

The Fix
We used an atomic database operation to verify and mark as used in a single transaction:

// SECURE CODE
const result = await prisma.emailOTP.updateMany({
  where: {
    userId: user.id,
    code,
    used: false,
    expiresAt: { gt: new Date() }, // Check expiry DB-side
  },
  data: {
    used: true, // Atomic update
  },
});

if (result.count === 0) {
  throw new AuthError('Invalid or expired OTP code');
}

Key improvements:

Atomic operation (verify + mark as used in one query)
Database-level expiry check
No race condition window
Only one request can succeed per OTP
Bonus: Distributed Rate Limiting with Redis
While fixing these vulnerabilities, we also improved our rate limiting architecture by moving from in-memory to Redis-backed distributed rate limiting.

Why This Matters

Horizontal Scaling: Rate limits work across multiple server instances
Consistency: Same limits apply regardless of which server handles the request
Resilience: Graceful fallback to memory store if Redis is unavailable

// Redis-backed rate limiting with fallback
const redisClient = new Redis({
  host: env.redis.host,
  port: env.redis.port,
  password: env.redis.password,
  retryStrategy: (times) => Math.min(times * 50, 3000),
});

redisClient.on('error', (error) => {
  logger.warn('Redis connection error, falling back to memory store');
  // express-rate-limit automatically falls back to memory store
});

The Impact: Before vs. After
Before
❌ Timing attacks could enumerate user accounts
❌ Rate limiting could be bypassed via IP spoofing
❌ OTPs could be reused through race conditions
❌ Rate limiting only worked per-server instance
After
✅ Constant-time password verification (no information leakage)
✅ Proper IP handling with Express trust proxy
✅ Atomic OTP verification (no race conditions)
✅ Distributed rate limiting with Redis

Best Practices for Authentication Security

Based on our experience, here are the key principles every authentication system should follow:

Constant-Time Operations
Always ensure security-critical operations take the same time regardless of input. Use dummy operations when needed.
Never Trust Client Headers Directly
Always validate proxy headers through your framework's built-in mechanisms (like Express's trust proxy).
Use Atomic Database Operations
For operations that check and modify state (like OTP verification), use atomic database operations to prevent race conditions.
Distributed Rate Limiting
Use Redis or similar for rate limiting in distributed systems.
Always have a fallback mechanism.
Comprehensive Testing
Write security-focused tests that specifically check for timing attacks, race conditions, and edge cases.

Testing Your Authentication System
We implemented comprehensive security tests to ensure these vulnerabilities stay fixed:

describe('Timing Attack Protection', () => {
  it('should have constant-time execution for non-existent users', async () => {
    const time1 = await measureLoginTime('nonexistent1@example.com');
    const time2 = await measureLoginTime('nonexistent2@example.com');

    // Times should be similar (within 50ms tolerance)
    expect(Math.abs(time1 - time2)).toBeLessThan(50);
  });
});

Key test categories:

Timing attack protection
Rate limiting effectiveness
Race condition prevention
Input validation
Conclusion: Building Secure Authentication
Authentication security is a continuous process.
The vulnerabilities we discovered are subtle but critical, and they're more common than you might think. By understanding these issues and implementing proper fixes, you can significantly improve your application's security posture.

Key Takeaways
Timing attacks are real - Always use constant-time operations for security-critical code
Never trust client headers - Use framework mechanisms for proxy validation
Race conditions matter - Use atomic database operations for state changes
Test security explicitly - Don't just test happy paths; test attack scenarios
Distributed systems need distributed rate limiting - In-memory limits don't scale
About Rugi Auth
While working on these security improvements, I was building Rugi Auth—a centralized authentication service designed with security as a first-class concern. It includes:

✅ RS256 JWT signing with RSA keys
✅ Argon2id password hashing (memory-hard, timing-attack resistant)
✅ Redis-backed distributed rate limiting with automatic fallback
✅ Comprehensive security protections against timing attacks, IP spoofing, and race conditions
✅ Extensive test coverage including security-focused tests
✅ Multi-app role management for complex authorization needs
If you're building authentication for your applications, I'd love for you to check it out. You can get started with:

npx rugi-auth init my-auth-server
The project is open-source, and all the security improvements discussed in this article are implemented and tested. You can find it on GitHub and install it via npm.

Resources
OWASP Authentication Cheat Sheet
Timing Attack Prevention
Express Trust Proxy Documentation
Redis Rate Limiting Best Practices

Have you encountered these vulnerabilities in your projects? What security measures do you implement in your authentication systems? Share your thoughts in the comments below!