🚀 @kaushverse/middleware

Production‑ready TypeScript middleware package for authentication, logging, request tracing, and global error handling — designed for kaushverse backend services.

✨ Features

• 🔐 Authentication Middleware (JWT + Cookies)
• 🧵 Request ID / Tracing (per-request unique ID)
• 📜 Centralized Logging (structured logs)
• 💥 Global Error Handling (safe & consistent responses)
• 🧠 TypeScript First (strict types, Express augmentation)
• 🧩 Framework-friendly (Express-first, extendable)

📦 Installation

npm install @kaushverse/middleware

or

yarn add @kaushverse/middleware

ℹ️ This package expects Express to be installed in the consuming app.

⚙️ Prerequisites

• Node.js >= 18
• Express ^4.18
• TypeScript (recommended)

Optional (for cookie auth):

npm install cookie-parser

🧱 Basic Setup

import express from "express";
import cookieParser from "cookie-parser";

import {
  requestIdMiddleware,
  loggerMiddleware,
  authMiddleware,
  errorMiddleware,
} from "@kaushverse/middleware";

const app = express();

app.use(express.json());
app.use(cookieParser());

app.use(requestIdMiddleware);
app.use(loggerMiddleware);

🧵 Request ID Middleware

Adds a unique requestId to every request for tracing and debugging.

app.use(requestIdMiddleware);

What it does

• Reads X-Request-Id header if present
• Otherwise generates a new UUID
• Attaches it to:
  • req.requestId
  • response header X-Request-Id

Use cases

• Distributed tracing
• Debugging production issues
• Log correlation

🔐 Authentication Middleware

Supports JWT tokens from headers or cookies.

app.get("/me", authMiddleware(), (req, res) => {
  res.json({ user: req.user });
});

With role-based access control

app.post("/admin", authMiddleware({ roles: ["admin"] }), handler);

Token sources (priority order)

1. Authorization: Bearer <token> header
2. access_token HTTP-only cookie

🍪 Cookie-based Auth (Web Apps)

Login example

res.cookie("access_token", token, {
  httpOnly: true,
  secure: true,
  sameSite: "strict",
  maxAge: 15 * 60 * 1000,
});

Frontend fetch

fetch("/api/me", {
  credentials: "include",
});

📜 Logger Middleware

Automatically logs every request with timing and requestId.

app.use(loggerMiddleware);

Logged fields

• HTTP method
• URL
• Status code
• Duration
• requestId

Why this matters

• Clean production logs
• Easy monitoring
• Faster incident response

💥 Global Error Middleware

Catches all unhandled errors and returns a safe response.

app.use(errorMiddleware); // MUST be last

Example response

{
  "message": "Internal Server Error",
  "requestId": "abc-123"
}

Benefits

• No stack traces leaked to clients
• Centralized error logging
• Request-based debugging

🧠 TypeScript Support

This package extends Express types.

Available on req:

req.requestId?: string;
req.user?: {
  id: string;
  role?: string;
};

No extra imports required — works automatically.

🏗️ Recommended Middleware Order

app.use(requestIdMiddleware);
app.use(loggerMiddleware);
app.use(errorMiddleware); // always last

🧪 Example Full App

app.get("/health", (req, res) => {
  res.json({ status: "ok" });
});

app.get("/me", authMiddleware(), (req, res) => {
  res.json({ user: req.user });
});

app.use(errorMiddleware);

🔒 Security Best Practices

• Always use httpOnly cookies
• Enable HTTPS (secure: true)
• Set sameSite for CSRF protection
• Never hardcode secrets

📈 Use Cases

• 🏢 Company backend services
• 🧩 Microservices architecture
• 🌐 Web apps (cookie auth)
• 📱 Mobile APIs (Bearer tokens)
• ☁️ Cloud / Kubernetes deployments

🛣️ Roadmap

• Fastify adapter
• NestJS Guard version
• OpenTelemetry integration
• Rate limiting middleware
• RBAC / ABAC helpers

📄 License

UNLICENSED — Internal kaushverse use only.

❤️ Maintained By

Kaushik

If it breaks, we fix it. If it scales, we own it 🚀