@wazobiatech/auth-middleware 1.0.0

package/README.md

@@ -0,0 +1,986 @@
+# @platform/jwt-auth
+
+A comprehensive TypeScript authentication library for the Wazobia platform, supporting both user JWT tokens and project service tokens. This library provides authentication middleware for Express.js, NestJS guards, and GraphQL resolvers with Redis caching and JWKS (JSON Web Key Set) validation.
+
+## 🚀 Features
+
+- 🔐 **Dual Authentication**: Supports both user JWT authentication and project service authentication
+- 🏗️ **Multiple Framework Support**: Works seamlessly with Express.js, NestJS, and GraphQL
+- 🔑 **JWKS Integration**: Dynamically fetches and caches public keys from JWKS endpoints
+- ⚡ **Redis Caching**: High-performance caching for validated tokens and JWKS
+- 🚫 **Token Revocation**: Built-in support for checking revoked tokens
+- 🏢 **Project-based Security**: Service-to-service authentication with project-specific access control
+- 📝 **TypeScript**: Full TypeScript support with comprehensive type definitions
+- 🛡️ **Security First**: RS512 algorithm, signature verification, and comprehensive validation
+- 📊 **Performance Optimized**: Intelligent caching strategies and minimal memory footprint
+
+## 🏗️ Architecture Overview
+
+### User Authentication (JWT)
+- Validates JWT tokens signed with RS512 algorithm using Mercury service
+- Fetches public keys from project-specific JWKS endpoints (`/api/jwks/{project_uuid}`)
+- Supports intelligent token caching and revocation checking via Redis
+- Extracts comprehensive user context (uuid, email, name, project_uuid)
+- Validates token claims: issuer, audience, expiration, not-before
+
+### Project Authentication
+- Validates project service tokens for secure service-to-service communication
+- Checks service access permissions based on `enabled_services` configuration
+- Supports secret versioning for seamless token rotation without downtime
+- Validates project-specific access controls and service authorization
+- Integrates with Athens service for project management
+
+### Caching Strategy
+- **JWKS Cache**: 5 hours (18000 seconds) for public keys
+- **Token Cache**: Configurable via `CACHE_EXPIRY_TIME` (default: 1 hour)
+- **Revoked Tokens**: Real-time tracking via Redis
+- **Project Metadata**: Cached for performance optimization
+
+## 📦 Installation
+
+```bash
+npm install @platform/jwt-auth
+```
+
+## 📋 Requirements
+
+- Node.js >= 16.0.0
+- TypeScript >= 4.5.0
+- Redis >= 6.0.0 (for caching and token management)
+- Mercury service (JWT issuer and JWKS provider)
+- Athens service (project authentication, optional)
+
+## Quick Start
+
+### Express.js Middleware
+
+```typescript
+import { jwtAuthMiddleware, projectAuthMiddleware } from '@platform/jwt-auth';
+
+const app = express();
+
+// User authentication
+app.use('/api/user', jwtAuthMiddleware());
+
+// Project authentication
+app.use('/api/project', projectAuthMiddleware());
+
+// Combined authentication
+app.use('/api/secure', jwtAuthMiddleware(), projectAuthMiddleware());
+```
+
+### NestJS Guards
+
+```typescript
+import { ProjectAndUserAuth } from '@platform/jwt-auth';
+
+@UseGuard(ProjectAndUserAuth) // Combines both JWT and project authentication
+@Controller('secure')
+export class SecureController {
+  @Get()
+  getSecureData(@CurrentUser() user: AuthUser) {
+    return { user, message: 'Authenticated!' };
+  }
+}
+```
+
+### GraphQL Resolvers
+
+```typescript
+import { GraphQLAuthHelper } from '@platform/jwt-auth';
+
+export class UserResolver {
+  private authHelper = new GraphQLAuthHelper();
+
+  @Query()
+  async getUser(
+    @Args() args: any,
+    @Context() context: GqlContext
+  ) {
+    return this.authHelper.withJwtAuth(async (parent, args, ctx, info) => {
+      // Your resolver logic here
+      return ctx.req.user;
+    })(null, args, context, null);
+  }
+}
+```
+
+## ⚙️ Environment Variables
+
+### Required Variables
+
+| Variable | Description | Example | Notes |
+|----------|-------------|---------|-------|
+| `MERCURY_BASE_URL` | Mercury service base URL (JWT issuer) | `http://localhost:4000` | Must match JWT `iss` claim |
+| `REDIS_URL` | Redis connection URL for caching | `redis://localhost:6379` | Used for token/JWKS cache |
+| `SERVICE_ID` | Unique identifier for current service | `helios`, `dolos`, `coeus` | Must match Athens service config |
+| `SIGNATURE_SHARED_SECRET` | HMAC shared secret for JWKS security | `your-256-bit-secret` | Keep secure, rotate regularly |
+
+### Optional Variables
+
+| Variable | Description | Default | Example |
+|----------|-------------|---------|---------|
+| `NEXUS_ID` | Frontend admin dashboard service ID, Default project UUID for JWKS fallback | `null` | `550e8400-e29b-41d4-a716-446655440000` |
+| `CACHE_EXPIRY_TIME` | Token cache TTL in seconds | `3600` | `7200` |
+| `JWKS_CACHE_TTL` | JWKS public key cache TTL in seconds | `18000` | `21600` |
+
+### Environment File Example
+
+Create a `.env` file in your project root:
+
+```bash
+# Mercury Service Configuration (JWT Authentication)
+MERCURY_BASE_URL=http://localhost:4000
+
+# Redis Configuration (Caching & Token Management)
+REDIS_URL=redis://localhost:6379/0
+
+# Security Configuration
+SIGNATURE_SHARED_SECRET=your-very-secure-256-bit-shared-secret-key
+
+# Service Configuration
+SERVICE_ID=helios                                        # Current service identifier
+NEXUS_ID=550e8400-e29b-41d4-a716-446655440000           # Frontend admin dashboard ID (optional)
+
+# Cache Configuration (Optional - Performance Tuning)
+CACHE_EXPIRY_TIME=3600                                   # JWT token cache TTL (1 hour)
+JWKS_CACHE_TTL=18000                                     # JWKS cache TTL (5 hours)
+
+# Additional Configuration (Application Specific)
+NODE_ENV=development
+PORT=3000
+```
+
+### Detailed Environment Variable Reference
+
+#### MERCURY_BASE_URL
+- **Purpose**: Base URL of the Mercury authentication service
+- **Usage**: JWT issuer validation and JWKS endpoint construction (`/api/jwks/{project_uuid}`)
+- **Format**: Complete URL with protocol (e.g., `http://localhost:4000`)
+- **Validation**: Must match the `iss` (issuer) claim in JWT tokens exactly
+- **Examples**:
+  - Development: `http://localhost:4000`
+  - Production: `https://auth.wazobia.com`
+
+#### REDIS_URL
+- **Purpose**: Redis connection string for caching and token management
+- **Usage**: Stores validated tokens, JWKS cache, revoked token lists, and project metadata
+- **Format**: Standard Redis connection URL
+- **Examples**:
+  - Local: `redis://localhost:6379`
+  - With auth: `redis://username:password@redis-host:6379`
+  - With database: `redis://localhost:6379/1`
+  - TLS: `rediss://redis-host:6380`
+- **Database Usage**:
+  - `/0`: Token cache and JWKS
+  - `/1`: Revoked tokens
+  - `/2`: Project metadata
+
+#### SERVICE_ID
+- **Purpose**: Unique identifier for the current service instance
+- **Usage**: Validates project token `enabled_services` array contains this service
+- **Format**: String identifier (kebab-case recommended)
+- **Examples**: `helios`, `dolos`, `coeus`, `udjat`
+- **Important**: Must exactly match service IDs configured in Athens project management
+
+#### SIGNATURE_SHARED_SECRET
+- **Purpose**: HMAC-SHA256 shared secret for JWKS request authentication
+- **Usage**: Signs requests to Mercury JWKS endpoints for additional security
+- **Format**: Base64 or hexadecimal encoded secret (minimum 256 bits recommended)
+- **Security**: 
+  - Keep secret secure and never commit to version control
+  - Rotate regularly (quarterly recommended)
+  - Use strong random generation (crypto.randomBytes(32))
+
+#### NEXUS_ID (Optional)
+- **Purpose**: Service identifier for the Nexus frontend admin dashboard
+- **Usage**: Special handling for admin dashboard authentication flows
+- **Format**: UUID v4 format
+- **Required**: Only if your service interacts with the Nexus admin interface
+- **Example**: `550e8400-e29b-41d4-a716-446655440000`
+
+#### ATHENS_SERVICE_ID (Optional)
+- **Purpose**: Fallback project UUID when JWT tokens don't specify `project_uuid`
+- **Usage**: JWKS endpoint construction for legacy or system tokens
+- **Format**: UUID v4 format
+- **Required**: Only if you have tokens without project context
+- **Example**: `550e8400-e29b-41d4-a716-446655440000`
+
+#### CACHE_EXPIRY_TIME (Optional)
+- **Purpose**: TTL for validated JWT token cache entries
+- **Usage**: Redis expiration time for token validation results
+- **Format**: Integer seconds
+- **Default**: `3600` (1 hour)
+- **Considerations**:
+  - Lower values: Better security, higher load on Mercury service
+  - Higher values: Better performance, potential stale token issues
+  - Recommended: 1-2 hours for most applications
+
+#### JWKS_CACHE_TTL (Optional)
+- **Purpose**: TTL for JWKS public key cache entries
+- **Usage**: Redis expiration time for fetched public keys
+- **Format**: Integer seconds
+- **Default**: `18000` (5 hours)
+- **Considerations**:
+  - JWKS keys rotate infrequently
+  - Higher cache times reduce Mercury service load
+  - Keys are validated before use even when cached
+
+## Usage Examples
+
+### Express Middleware
+
+```typescript
+import express from 'express';
+import { jwtAuthMiddleware, projectAuthMiddleware } from '@platform/jwt-auth';
+import { AuthenticatedRequest } from '@platform/jwt-auth/types';
+
+const app = express();
+
+// JWT Authentication only
+app.get('/user/profile', jwtAuthMiddleware(), (req: AuthenticatedRequest, res) => {
+  res.json({ 
+    user: req.user // { uuid, email, name }
+  });
+});
+
+// Project Authentication only  
+app.get('/service/health', projectAuthMiddleware(), (req: AuthenticatedRequest, res) => {
+  res.json({ 
+    project: req.project // { project_uuid, enabled_services, ... }
+  });
+});
+
+// Combined Authentication
+app.get('/secure/data', 
+  jwtAuthMiddleware(), 
+  projectAuthMiddleware(), 
+  (req: AuthenticatedRequest, res) => {
+    res.json({ 
+      user: req.user,
+      project: req.project
+    });
+  }
+);
+```
+
+### NestJS Integration
+
+```typescript
+// Module setup
+import { JwtAuthModule } from '@platform/jwt-auth';
+
+@Module({
+  imports: [JwtAuthModule],
+  controllers: [UserController],
+})
+export class AppModule {}
+
+// Controller usage
+import { Controller, Get, UseGuards } from '@nestjs/common';
+import { JwtAuthGuard, ProjectAuthGuard, CurrentUser } from '@platform/jwt-auth';
+
+@Controller('api')
+export class UserController {
+  @Get('profile')
+  @UseGuards(JwtAuthGuard)
+  getProfile(@CurrentUser() user: AuthUser) {
+    return user;
+  }
+
+  @Get('project-data')
+  @UseGuards(ProjectAuthGuard)
+  getProjectData(@Request() req) {
+    return req.project;
+  }
+
+  @Get('secure')
+  @UseGuards(JwtAuthGuard, ProjectAuthGuard)
+  getSecureData(@CurrentUser() user: AuthUser, @Request() req) {
+    return { user, project: req.project };
+  }
+}
+```
+
+### GraphQL Integration
+
+```typescript
+import { GraphQLAuthHelper } from '@platform/jwt-auth';
+import { Resolver, Query, Context, Args } from '@nestjs/graphql';
+
+@Resolver()
+export class UserResolver {
+  private authHelper = new GraphQLAuthHelper();
+
+  @Query()
+  async getCurrentUser(@Context() context: GqlContext) {
+    return this.authHelper.withJwtAuth(async (parent, args, ctx) => {
+      return ctx.req.user;
+    })(null, {}, context, null);
+  }
+
+  @Query()
+  async getProjectInfo(@Context() context: GqlContext) {
+    return this.authHelper.withProjectAuth(async (parent, args, ctx) => {
+      return ctx.req.project;
+    })(null, {}, context, null);
+  }
+
+  @Query()
+  async getSecureData(@Context() context: GqlContext) {
+    return this.authHelper.withCombinedAuth(async (parent, args, ctx) => {
+      return {
+        user: ctx.req.user,
+        project: ctx.req.project
+      };
+    })(null, {}, context, null);
+  }
+}
+```
+
+## Token Format
+
+### JWT User Token
+```json
+{
+  "sub": {
+    "uuid": "user-uuid",
+    "email": "user@example.com", 
+    "name": "User Name"
+  },
+  "project_uuid": "project-uuid",
+  "type": "user",
+  "iss": "https://auth.yourdomain.com",
+  "aud": "https://api.yourdomain.com", 
+  "exp": 1640995200,
+  "nbf": 1640908800,
+  "iat": 1640908800,
+  "jti": "token-id"
+}
+```
+
+### Project Service Token
+```json
+{
+  "project_uuid": "project-uuid",
+  "secret_version": 1,
+  "enabled_services": ["user-service", "order-service"],
+  "token_id": "project-token-id",
+  "type": "project",
+  "iat": 1640908800,
+  "exp": 1640995200
+}
+```
+
+## Headers
+
+### JWT Authentication
+```
+Authorization: Bearer <jwt-token>
+```
+
+### Project Authentication  
+```
+x-project-token: Bearer <project-token>
+```
+or
+```
+x-project-token: <project-token>
+```
+
+## Error Handling
+
+The library throws descriptive errors for different scenarios:
+
+### JWT Authentication Errors
+- `No authorization header provided`
+- `Invalid JWT token: <reason>`
+- `Token expired`
+- `Token has been revoked`
+- `Invalid issuer`
+
+### Project Authentication Errors
+- `No project token provided`
+- `Service access denied`
+- `Token has been revoked`
+- `Token secret version outdated`
+
+### JWKS Errors
+- `JWKS endpoint not reachable`
+- `Key not found in JWKS`
+- `Mercury service unavailable`
+
+## Performance Considerations
+
+### Caching Strategy
+- **JWKS Cache**: 10 minutes (600 seconds)
+- **Token Cache**: Configurable via `CACHE_EXPIRY_TIME` (default: 1 hour)
+- **Project JWKS Cache**: 5 hours (18000 seconds)
+
+### Redis Usage
+- Validated tokens are cached to avoid re-validation
+- JWKS responses are cached to reduce HTTP requests
+- Revoked tokens are stored for quick lookup
+- Project secret versions are cached
+
+### Memory Usage
+- In-memory JWKS cache with expiration
+- Minimal memory footprint for token caching
+- Automatic cleanup of expired cache entries
+
+## Security Features
+
+### Token Validation
+- RSA signature verification using JWKS
+- Timestamp validation (exp, nbf, iat)
+- Issuer validation
+- Token revocation checking
+
+### Project Security
+- Service-specific access control
+- Secret version validation for token rotation
+- HMAC signature verification for JWKS requests
+
+### Best Practices
+- Tokens are never logged in full
+- Sensitive data is not cached
+- Automatic cleanup of expired cache entries
+- Comprehensive error messages without exposing internals
+
+## 🔗 Service Integration
+
+### Mercury Service Integration
+The JWT authentication library integrates with the Mercury service for:
+- **JWT Token Validation**: Verifies token signatures using Mercury's public keys
+- **JWKS Endpoint**: Fetches public keys from `/api/jwks/{project_uuid}`
+- **Token Revocation**: Checks revoked token lists maintained by Mercury
+- **User Context**: Extracts user information from validated JWT tokens
+
+### Athens Service Integration (Optional)
+When using project authentication, the library can integrate with Athens for:
+- **Project Management**: Validates project existence and configuration
+- **Service Authorization**: Checks if services are enabled for specific projects
+- **Project Metadata**: Caches project information for performance
+
+### Redis Integration
+Redis is used extensively for performance optimization:
+- **Token Cache**: Stores validation results to avoid repeated Mercury calls
+- **JWKS Cache**: Caches public keys with configurable TTL
+- **Revoked Tokens**: Maintains real-time revoked token blacklist
+- **Project Data**: Caches project metadata and service configurations
+
+### Supported Service Types
+
+| Service | Environment Example | Usage Pattern |
+|---------|-------------------|---------------|
+| **Helios** | `SERVICE_ID=helios` | API Gateway, routing, load balancing |
+| **Dolos** | `SERVICE_ID=dolos` | Background processing, async tasks |
+| **Coeus** | `SERVICE_ID=coeus` | Analytics, reporting, data processing |
+| **Udjat** | `SERVICE_ID=udjat` | Monitoring, logging, observability |
+| **Nexus** | Special handling via `NEXUS_ID` | Frontend admin dashboard |
+
+## 🛠️ Development
+
+### Local Development Setup
+
+1. **Install Dependencies**
+   ```bash
+   npm install
+   ```
+
+2. **Setup Environment**
+   ```bash
+   cp .env.example .env
+   # Edit .env with your configuration
+   ```
+
+3. **Start Required Services**
+   ```bash
+   # Start Redis
+   docker run -d -p 6379:6379 redis:alpine
+   
+   # Start Mercury service (if running locally)
+   cd ../../../apps/node-services/mercury
+   npm run start:dev
+   ```
+
+4. **Run Tests**
+   ```bash
+   # Unit tests
+   npm test
+   
+   # Integration tests (requires Redis + Mercury)
+   npm run test:integration
+   
+   # Coverage report
+   npm run test:coverage
+   ```
+
+### Testing Configuration
+
+Create a test environment file `.env.test`:
+
+```bash
+# Test Environment Configuration
+NODE_ENV=test
+MERCURY_BASE_URL=http://localhost:4000
+REDIS_URL=redis://localhost:6380  # Use different Redis DB for tests
+SERVICE_ID=test-service
+SIGNATURE_SHARED_SECRET=test-secret-key-for-testing-only
+CACHE_EXPIRY_TIME=60  # Shorter cache for faster tests
+JWKS_CACHE_TTL=300
+```
+
+### Docker Development
+
+```dockerfile
+# Dockerfile example for service using jwt-auth
+FROM node:18-alpine
+
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+
+COPY . .
+EXPOSE 3000
+
+# Environment variables will be provided by docker-compose
+CMD ["npm", "start"]
+```
+
+```yaml
+# docker-compose.yml example
+version: '3.8'
+services:
+  your-service:
+    build: .
+    environment:
+      - MERCURY_BASE_URL=http://mercury:4000
+      - REDIS_URL=redis://redis:6379
+      - SERVICE_ID=your-service
+      - SIGNATURE_SHARED_SECRET=${SIGNATURE_SHARED_SECRET}
+    depends_on:
+      - redis
+      - mercury
+
+  redis:
+    image: redis:alpine
+    ports:
+      - "6379:6379"
+```
+
+## 🔧 Troubleshooting
+
+### Common Authentication Issues
+
+#### JWT Authentication Problems
+
+**1. "JWKS endpoint not reachable"**
+- **Cause**: Cannot connect to Mercury service JWKS endpoint
+- **Solutions**:
+  ```bash
+  # Check Mercury service status
+  curl http://localhost:4000/health
+  
+  # Verify JWKS endpoint
+  curl http://localhost:4000/api/jwks/{project_uuid}
+  
+  # Check network connectivity
+  ping mercury-service-host
+  ```
+- **Environment Check**: Ensure `MERCURY_BASE_URL` is correct and accessible
+
+**2. "Key not found in JWKS"**
+- **Cause**: JWT token's `kid` header doesn't match any key in JWKS response
+- **Solutions**:
+  - Verify token is signed with current Mercury keys
+  - Check if Mercury key rotation occurred recently
+  - Clear JWKS cache: `redis-cli DEL jwks:*`
+- **Debug**: Examine JWT header: `echo 'token' | cut -d. -f1 | base64 -d`
+
+**3. "Invalid JWT token: Token expired"**
+- **Cause**: JWT token `exp` claim is in the past
+- **Solutions**:
+  - Check system clock synchronization (NTP)
+  - Obtain fresh token from Mercury `/auth/login`
+  - Verify Mercury token expiry configuration
+
+**4. "Invalid issuer"**
+- **Cause**: JWT `iss` claim doesn't match `MERCURY_BASE_URL`
+- **Solutions**:
+  - Ensure `MERCURY_BASE_URL` exactly matches JWT issuer
+  - Check for trailing slashes or protocol mismatches
+  - Verify Mercury service configuration
+
+#### Project Authentication Problems
+
+**5. "Service access denied"**
+- **Cause**: `SERVICE_ID` not in project token's `enabled_services` array
+- **Solutions**:
+  ```bash
+  # Check project configuration in Athens
+  curl http://athens:3000/api/projects/{project_uuid}
+  
+  # Verify service is enabled
+  # enabled_services should contain your SERVICE_ID
+  ```
+- **Debug**: Decode project token payload to check `enabled_services`
+
+**6. "No project token provided"**
+- **Cause**: Missing `x-project-token` header
+- **Solutions**:
+  - Add header: `x-project-token: Bearer <project-token>`
+  - Or: `x-project-token: <project-token>`
+  - Verify client is sending correct headers
+
+#### Redis Connection Issues
+
+**7. Redis connection errors**
+- **Cause**: Cannot connect to Redis server
+- **Solutions**:
+  ```bash
+  # Test Redis connectivity
+  redis-cli -u $REDIS_URL ping
+  
+  # Check Redis server status
+  docker ps | grep redis
+  
+  # Verify Redis URL format
+  echo $REDIS_URL
+  ```
+- **Common Formats**:
+  - `redis://localhost:6379`
+  - `redis://user:pass@host:port/db`
+  - `rediss://host:port` (TLS)
+
+#### Performance Issues
+
+**8. Slow authentication responses**
+- **Cause**: JWKS or token validation taking too long
+- **Solutions**:
+  ```bash
+  # Check Redis performance
+  redis-cli --latency -h redis-host -p 6379
+  
+  # Monitor cache hit rates
+  redis-cli info stats | grep keyspace
+  
+  # Optimize cache TTL values
+  CACHE_EXPIRY_TIME=7200  # 2 hours
+  JWKS_CACHE_TTL=21600    # 6 hours
+  ```
+
+**9. Memory usage growing over time**
+- **Cause**: Cache not expiring properly
+- **Solutions**:
+  - Monitor Redis memory: `redis-cli info memory`
+  - Set appropriate TTL values
+  - Clear cache if needed: `redis-cli FLUSHDB`
+
+### Debug Mode & Logging
+
+Enable detailed logging for troubleshooting:
+
+```bash
+# Enable all jwt-auth debug logs
+DEBUG=jwt-auth:* npm start
+
+# Enable specific component logs
+DEBUG=jwt-auth:jwt,jwt-auth:jwks npm start
+
+# Enable with log levels
+NODE_ENV=development DEBUG=jwt-auth:* npm start
+```
+
+### Health Check Endpoints
+
+Add health checks to your service:
+
+```typescript
+import { createClient } from 'redis';
+
+app.get('/health', async (req, res) => {
+  const health = {
+    status: 'ok',
+    timestamp: new Date().toISOString(),
+    services: {}
+  };
+
+  try {
+    // Check Redis connectivity
+    const redis = createClient({ url: process.env.REDIS_URL });
+    await redis.connect();
+    await redis.ping();
+    await redis.quit();
+    health.services.redis = 'connected';
+  } catch (error) {
+    health.services.redis = 'disconnected';
+    health.status = 'error';
+  }
+
+  try {
+    // Check Mercury connectivity
+    const response = await fetch(`${process.env.MERCURY_BASE_URL}/health`);
+    health.services.mercury = response.ok ? 'connected' : 'error';
+  } catch (error) {
+    health.services.mercury = 'disconnected';
+    health.status = 'error';
+  }
+
+  res.status(health.status === 'ok' ? 200 : 503).json(health);
+});
+```
+
+### Monitoring & Alerting
+
+Set up monitoring for authentication issues:
+
+```typescript
+// Custom middleware for auth metrics
+const authMetricsMiddleware = (req, res, next) => {
+  const startTime = Date.now();
+  
+  res.on('finish', () => {
+    const duration = Date.now() - startTime;
+    const status = res.statusCode;
+    
+    // Log authentication metrics
+    console.log({
+      type: 'auth_metric',
+      path: req.path,
+      method: req.method,
+      status,
+      duration,
+      user_id: req.user?.uuid,
+      project_id: req.project?.project_uuid
+    });
+  });
+  
+  next();
+};
+```
+
+### Migration & Deployment
+
+When deploying authentication changes:
+
+1. **Zero-downtime deployment**:
+   ```bash
+   # Clear caches gradually
+   redis-cli --scan --pattern "jwt:*" | xargs redis-cli del
+   
+   # Monitor error rates during deployment
+   kubectl logs -f deployment/your-service | grep "auth"
+   ```
+
+2. **Rollback procedures**:
+   ```bash
+   # Restore previous environment variables
+   kubectl set env deployment/your-service MERCURY_BASE_URL=old-url
+   
+   # Clear Redis cache to force fresh validation
+   redis-cli flushall
+   ```
+
+## 📚 API Reference
+
+### Core Middleware
+
+#### `projectAuthMiddleware(options?)`
+Express middleware for project service authentication.
+
+### NestJS Guards
+
+#### `JwtAuthGuard`
+NestJS guard for JWT authentication.
+
+```typescript
+@Controller('api')
+export class UserController {
+  @UseGuards(JwtAuthGuard)
+  @Get('profile')
+  getProfile(@CurrentUser() user: AuthUser) {
+    return user;
+  }
+}
+```
+
+#### `ProjectAuthGuard`
+NestJS guard for project authentication.
+
+```typescript
+@UseGuards(ProjectAuthGuard)
+@Get('project-data')
+getProjectData(@Request() req) {
+  return req.project;
+}
+```
+
+#### `ProjectAndUserAuth`
+Combined guard for both JWT and project authentication.
+
+```typescript
+@UseGuards(ProjectAndUserAuth)
+@Get('secure-data')
+getSecureData(@CurrentUser() user: AuthUser, @Request() req) {
+  return { user, project: req.project };
+}
+```
+
+### GraphQL Integration
+
+#### `GraphQLAuthHelper`
+Helper class for GraphQL resolver authentication.
+
+```typescript
+class GraphQLAuthHelper {
+  withJwtAuth<T>(resolver: GraphQLResolver<T>): GraphQLResolver<T>
+  withProjectAuth<T>(resolver: GraphQLResolver<T>): GraphQLResolver<T>
+  withCombinedAuth<T>(resolver: GraphQLResolver<T>): GraphQLResolver<T>
+}
+```
+
+### Type Definitions
+
+#### `AuthUser`
+User information extracted from JWT token.
+
+```typescript
+interface AuthUser {
+  uuid: string;
+  email: string;
+  name: string;
+  project_uuid?: string;
+}
+```
+
+#### `AuthProject`
+Project information from project token.
+
+```typescript
+interface AuthProject {
+  project_uuid: string;
+  enabled_services: string[];
+  secret_version: number;
+  token_id: string;
+}
+```
+
+#### `AuthenticatedRequest`
+Extended Express request with authentication context.
+
+```typescript
+interface AuthenticatedRequest extends Request {
+  user?: AuthUser;
+  project?: AuthProject;
+}
+```
+
+### Utility Functions
+
+#### `verifyJwtToken(token, projectUuid?)`
+Manually verify JWT token.
+
+```typescript
+const user = await verifyJwtToken(bearerToken, projectUuid);
+if (user) {
+  console.log('Valid user:', user);
+}
+```
+
+#### `verifyProjectToken(token, serviceId)`
+Manually verify project token.
+
+```typescript
+const project = await verifyProjectToken(projectToken, 'helios');
+if (project) {
+  console.log('Valid project:', project);
+}
+```
+
+## 🤝 Contributing
+
+We welcome contributions to improve the JWT authentication library! Please follow these steps:
+
+### Development Setup
+
+1. **Fork and Clone**
+   ```bash
+   git clone https://github.com/your-username/wazobia-platform.git
+   cd nx-msp/libs/node/jwt-auth
+   ```
+
+2. **Install Dependencies**
+   ```bash
+   npm install
+   ```
+
+3. **Setup Test Environment**
+   ```bash
+   cp .env.example .env.test
+   # Configure test Redis and Mercury URLs
+   ```
+
+4. **Run Tests**
+   ```bash
+   npm test
+   npm run test:integration
+   ```
+
+### Contribution Guidelines
+
+- **Code Style**: Follow existing TypeScript/ESLint configuration
+- **Testing**: Add comprehensive tests for new functionality
+- **Documentation**: Update README and JSDoc comments
+- **Security**: Follow security best practices, no hardcoded secrets
+- **Performance**: Consider caching and Redis optimization
+
+### Pull Request Process
+
+1. Create feature branch: `git checkout -b feature/your-feature`
+2. Make changes with tests
+3. Run test suite: `npm run test:all`
+4. Update documentation
+5. Submit pull request with clear description
+
+### Security Issues
+
+For security vulnerabilities, please email security@wazobia.com instead of creating public issues.
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## 📋 Changelog
+
+### Version 2.1.0 (Latest)
+- ✅ Added comprehensive environment variable documentation
+- ✅ Improved Redis connection management
+- ✅ Enhanced error messages and debugging
+- ✅ Added health check utilities
+- ✅ Performance optimizations for JWKS caching
+
+### Version 2.0.0
+- ✅ Major TypeScript rewrite
+- ✅ Added NestJS guard support
+- ✅ Implemented project authentication
+- ✅ Added GraphQL resolver helpers
+- ✅ Breaking: New environment variable names
+
+### Version 1.x.x
+- ✅ Initial Express middleware implementation
+- ✅ Basic JWT validation with JWKS
+- ✅ Redis caching support
+
+See [CHANGELOG.md](CHANGELOG.md) for complete version history.
+
+---
+
+## 🆘 Support
+
+- **Documentation**: [Wazobia Platform Docs](https://docs.wazobia.com)
+- **Issues**: [GitHub Issues](https://github.com/wazobia/platform/issues)
+- **Slack**: `#authentication` channel
+- **Email**: developers@wazobia.com
+
+Built with ❤️ by the Wazobia Platform Team