npm package: @kaushverse/middleware
Description: A shared TypeScript middleware layer providing standardized authentication, authorization, logging, request context, and error handling for company backend services.
Author: Kaushik
Latest version: 1.0.4

# 🚀 @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

```bash
npm install @kaushverse/middleware
```

or

```bash
yarn add @kaushverse/middleware
```

> ℹ️ This package expects **Express** to be installed in the consuming app.


```bash
npm install cookie-parser
```

---

## 🧱 Basic Setup

```ts
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.

```ts
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**.

```ts
app.get("/me", authMiddleware(), (req, res) => {
  res.json({ user: req.user });
});
```

### With role-based access control

```ts
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

```ts
res.cookie("access_token", token, {
  httpOnly: true,
  secure: true,
  sameSite: "strict",
  maxAge: 15 * 60 * 1000,
});
```

### Frontend fetch

```js
fetch("/api/me", {
  credentials: "include",
});
```

---

## 📜 Logger Middleware

Automatically logs every request with timing and requestId.

```ts
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.

```ts
app.use(errorMiddleware); // MUST be last
```

### Example response

```json
{
  "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`:

```ts
req.requestId?: string;
req.user?: {
  id: string;
  role?: string;
};
```

No extra imports required — works automatically.

---

## 🏗️ Recommended Middleware Order

```ts
app.use(requestIdMiddleware);
app.use(loggerMiddleware);
app.use(errorMiddleware); // always last
```

---

## 🧪 Example Full App

```ts
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 🚀