nawa-auth

A lightweight JWT-based authentication library with a CutOff mechanism for bulk token invalidation. Backed by MongoDB with optional Redis caching.

Features

• 🔐 JWT Signing & Verification – HS256-based token management via jose
• 🗄️ MongoDB Integration – Persistent CutOff date storage
• ⚡ Redis Cache (optional) – Speeds up CutOff lookups (TTL: 1 hour)
• 🍪 Cookie-based Auth – Automatic token management via nawa_auth_token cookie
• 🚫 Bulk Token Revocation – Instantly invalidate all tokens issued before a given date

Installation

npm install @nawadotdev/nawa-auth

Environment Variables

| Variable | Required | Description | | -------------- | -------- | ---------------------------------- | | MONGODB_URI | ✅ | MongoDB connection URI | | JWT_SECRET | ✅ | Secret key for JWT signing | | REDIS_URL | ❌ | Redis connection URL (optional) |

MONGODB_URI=mongodb://localhost:27017/nawa-auth
JWT_SECRET=super-secret-key
REDIS_URL=redis://localhost:6379

Quick Links

• 📖 Full Examples – Express.js, Next.js, Hono examples and best practices
• 🤝 Contributing Guide – How to add your project to our projects list
• 🐛 Issue Templates – Report bugs or request features

Usage

1. Create a JWT Token

import { signJWT } from "@nawadotdev/nawa-auth";

const token = await signJWT("user_abc123");

2. Verify a Request

import { AuthService } from "@nawadotdev/nawa-auth";

const authService = new AuthService();

// Verifies the nawa_auth_token cookie from the request
const authId = await authService.verifyRequest(request);

3. Revoke Tokens (CutOff)

Invalidate all existing tokens for a user (e.g. password change, security breach):

import { NawaAuth } from "@nawadotdev/nawa-auth";

// All tokens issued before this date become invalid
await NawaAuth.setCutOff("user_abc123", new Date());

4. Query CutOff Date

import { NawaAuth } from "@nawadotdev/nawa-auth";

const cutOff = await NawaAuth.getCutOff("user_abc123");
console.log("CutOff date:", cutOff);

5. Cookie Management (RequestHelper)

import { RequestHelper, signJWT } from "@nawadotdev/nawa-auth";

// Login: Set the token as a cookie
const token = await signJWT("user_abc123");
RequestHelper.setAuthToken(response, token);

// Logout: Clear the auth cookie
RequestHelper.clearAuthToken(response);

// Read the token from a request
const authToken = RequestHelper.getAuthToken(request);

How the CutOff Mechanism Works

1. signJWT(authId) → JWT is created (iat = current time)
2. AuthService.verifyRequest(req)
   ├─ Token is extracted from cookie
   ├─ JWT is verified → { authId, iat }
   ├─ NawaAuth.getCutOff(authId) → CutOff date is fetched
   │   ├─ If Redis is available: check Redis first
   │   └─ If Redis is unavailable or cache miss: fall back to MongoDB
   └─ iat < cutOff → ❌ Token rejected (Token is too old)
      iat >= cutOff → ✅ Token accepted

API Reference

signJWT(authId: string, options?: { expiresIn?: string | number | Date }): Promise<string>

Creates a JWT token for the given authId.
Default expiration is 1h.

verifyJWT(token: string): Promise<CutOffJWT>

Verifies a JWT token and returns the payload.

AuthService

| Method | Description | |--------|-------------| | verifyRequest(request: Request): Promise<string> | Verifies the request and returns the authId |

NawaAuth

| Method | Description | |--------|-------------| | getCutOff(authId: string): Promise<Date> | Returns the CutOff date (Redis → MongoDB fallback) | | setCutOff(authId: string, date: Date): Promise<void> | Updates the CutOff date |

RequestHelper

| Method | Description | |--------|-------------| | getAuthToken(req: Request): string \| null | Reads nawa_auth_token from the cookie header | | setAuthToken(res: Response, token: string): void | Sets the auth cookie on the response | | clearAuthToken(res: Response): void | Clears the auth cookie |

Types

interface CutOff {
  authId: string;
  date: Date;
}

interface CutOffJWT {
  authId: string;
  iat: number;
  exp?: number;
}

Publishing to npm

# 1. Install dependencies
npm install

# 2. Build TypeScript
npm run build

# 3. Login to npm
npm login

# 4. Publish
npm publish

Projects Using This Package

Showing projects that use nawa-auth helps build a community and demonstrates real-world usage.

Want to add your project? Follow this step-by-step guide or submit a PR:

1. Fork this repository
2. Add your project to the list below:

   - [Project Name](https://github.com/your-username/your-project) - Brief description

3. Create a Pull Request with the title: Add [Your Project Name] to projects list
4. Link to where you use nawa-auth in your project (README, code example, or docs)

Current Projects

No projects listed yet. Be the first to add yours!

Contributing Your Project

To add your project:

1. Ensure you're actually using nawa-auth in production or development
2. Your project should be public or have public documentation showing usage
3. Submit a PR with your project details

See CONTRIBUTING.md for detailed guidelines.

License

ISC