ㅈ# @ahhaohho/auth-middleware

Shared authentication middleware with Passport.js for ahhaohho microservices.

Features

• ✅ Passport.js JWT authentication strategy
• ✅ Multi-key JWT verification with fallback support
• ✅ Redis-based token blacklist
• ✅ AWS Secrets Manager integration
• ✅ Express middleware ready

Installation

Using npm (recommended)

npm install @ahhaohho/auth-middleware

Or add to package.json:

{
  "dependencies": {
    "@ahhaohho/auth-middleware": "^1.0.2"
  }
}

Using Git

npm install git+ssh://[email protected]:Future-Lab-META/auth-middleware.git#v1.0.2

Or add to package.json:

{
  "dependencies": {
    "@ahhaohho/auth-middleware": "git+ssh://[email protected]:Future-Lab-META/auth-middleware.git#v1.0.2"
  }
}

Usage

Basic Setup

const express = require('express');
const { authenticateJWT, authenticateRefresh } = require('@ahhaohho/auth-middleware');

const app = express();

// Environment variables required
// AWS_REGION=ap-northeast-2
// REDIS_HOST=your-redis-host
// REDIS_PORT=6379
// JWT_SECRET_NAME=your-secret-name

// Protected routes
app.get('/api/verify', authenticateJWT, (req, res) => {
  res.json({
    userId: req.user.userId,
    userRole: req.user.userRole
  });
});

app.get('/api/refresh', authenticateRefresh, (req, res) => {
  // Generate new access token
  res.json({ newAccessToken: '...' });
});

app.listen(3000);

Environment Variables

# Required
AWS_REGION=ap-northeast-2
REDIS_HOST=your-redis-host
REDIS_PORT=6379
JWT_SECRET_NAME=your-secret-name

# Optional
ELASTICACHE_ENDPOINT=your-elasticache-endpoint  # If using ElastiCache (auto-enables TLS)
REDIS_TLS=true                                  # Force enable TLS for Redis connection

Redis Configuration Notes

• REDIS_HOST: If set, takes priority over ELASTICACHE_ENDPOINT
• ELASTICACHE_ENDPOINT: Used only when REDIS_HOST is not set
• TLS Auto-detection:
  • TLS is automatically disabled for localhost and 127.0.0.1
  • TLS is automatically enabled when using ELASTICACHE_ENDPOINT (without REDIS_HOST)
  • Use REDIS_TLS=true to force enable TLS for any host

Architecture

JWT Verification Flow

Request with JWT
    ↓
authenticateJWT middleware
    ↓
Extract token from Authorization header
    ↓
Verify with current JWT key
    ↓ (if fails)
Fallback to previous JWT key
    ↓
Check Redis blacklist
    ↓
Inject user data to req.user
    ↓
Next middleware

Multi-Key Support

Supports seamless JWT key rotation:

• Verifies with current key first
• Falls back to previous key if current fails
• Allows zero-downtime key rotation

Token Blacklist

Uses Redis to maintain revoked tokens:

• Stores blacklisted tokens per user
• Automatically expires with token TTL
• Checked on every authentication

API Reference

authenticateJWT(req, res, next)

Passport.js middleware for JWT authentication.

Headers:

• Authorization: Bearer <access_token>

Sets:

• req.user: { userId, userRole, phoneNumber }

Errors:

• 401: Unauthorized (invalid or expired token)
• 500: Authentication error

authenticateRefresh(req, res, next)

Passport.js middleware for refresh token authentication.

Headers:

• Refresh-Token: Bearer <refresh_token>

Sets:

• req.user: { userId, userRole, phoneNumber }

Errors:

• 401: Invalid refresh token
• 500: Token refresh error

Development

Project Structure

auth-middleware/
├── src/
│   ├── index.js                 # Main export
│   ├── strategies/
│   │   ├── jwt.strategy.js      # Passport JWT strategy
│   │   └── refresh.strategy.js  # Refresh token strategy
│   ├── middleware/
│   │   └── auth.js              # Express middleware
│   ├── utils/
│   │   ├── jwtValidator.js      # Multi-key verification
│   │   ├── blacklist.js         # Redis blacklist
│   │   └── secretManager.js     # AWS Secrets Manager
│   └── config/
│       └── redis.js             # Redis client singleton
├── package.json
└── README.md

Testing Locally

# Clone the repository
git clone [email protected]:Future-Lab-META/auth-middleware.git
cd auth-middleware

# Install dependencies
npm install

# Link locally for testing
npm link

# In your service directory
npm link @ahhaohho/auth-middleware

Versioning

This package follows Semantic Versioning.

Creating a New Version

# Update version in package.json
npm version patch  # 1.0.0 -> 1.0.1
npm version minor  # 1.0.0 -> 1.1.0
npm version major  # 1.0.0 -> 2.0.0

# Push with tags
git push origin main --tags

Using Specific Versions

# npm
npm install @ahhaohho/[email protected]

# Git
npm install git+ssh://[email protected]:Future-Lab-META/auth-middleware.git#v1.0.2

Or in package.json:

{
  "dependencies": {
    "@ahhaohho/auth-middleware": "1.0.2"
  }
}

Migration Guide

See MIGRATION.md for detailed migration guide from HTTP-based authentication to Passport.js.

License

MIT