🔐 Authosphere Node.js Module

Plug-and-play authentication module for Node.js applications with database integration support.

✨ Features

• 🔑 JWT Authentication - Secure token-based authentication
• 🌐 OAuth Integration - Google, GitHub, and more OAuth providers
• ⚡ Plug-and-Play - Minimal configuration required
• 🛡️ Security First - Rate limiting, CORS, Helmet protection
• 🗄️ Database Integration - MongoDB, PostgreSQL, Redis support
• 🔄 Hybrid Storage - Primary storage + Redis caching
• 📊 Health Monitoring - Built-in health checks and monitoring
• 🎯 TypeScript Ready - Full TypeScript support
• 📚 Comprehensive Examples - Complete working examples

🚀 Quick Start

Installation

npm install @authosphere/nodejs-auth-module

Basic Usage

const { createAuthosphere } = require('@authosphere/nodejs-auth-module');
const express = require('express');

const app = express();

// Configure Authosphere
const authosphere = createAuthosphere({
  jwtSecret: 'your-super-secret-jwt-key',
  storage: {
    type: 'mongodb', // or 'postgresql', 'redis', 'memory'
    options: {
      uri: 'mongodb://localhost:27017/authosphere'
    }
  },
  oauth: {
    google: {
      clientId: 'your-google-client-id',
      clientSecret: 'your-google-client-secret'
    }
  }
});

// Use Authosphere middleware
app.use('/auth', authosphere);

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

🗄️ Storage Types

In-Memory Storage (Default)

const app = createAuthosphere({
  storage: {
    type: 'memory'
  }
});

MongoDB Storage

const app = createAuthosphere({
  storage: {
    type: 'mongodb',
    options: {
      uri: 'mongodb://localhost:27017/authosphere'
    }
  }
});

PostgreSQL Storage

const app = createAuthosphere({
  storage: {
    type: 'postgresql',
    options: {
      databaseUrl: 'postgresql://user:pass@localhost:5432/authosphere'
    }
  }
});

Redis Storage

const app = createAuthosphere({
  storage: {
    type: 'redis',
    options: {
      url: 'redis://localhost:6379'
    }
  }
});

Hybrid Storage (PostgreSQL + Redis)

const app = createAuthosphere({
  storage: {
    primary: {
      type: 'postgresql',
      options: {
        databaseUrl: 'postgresql://user:pass@localhost:5432/authosphere'
      }
    },
    cache: {
      type: 'redis',
      options: {
        url: 'redis://localhost:6379'
      }
    }
  }
});

🔧 Configuration

Environment Variables

# JWT Configuration
JWT_SECRET=your-super-secret-jwt-key-change-in-production

# Database Configuration
MONGODB_URI=mongodb://localhost:27017/authosphere
DATABASE_URL=postgresql://user:pass@localhost:5432/authosphere
REDIS_URL=redis://localhost:6379
STORAGE_TYPE=mongodb

# OAuth Providers
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# Frontend URL
FRONTEND_URL=http://localhost:3000

Configuration Options

const app = createAuthosphere({
  // Server Configuration
  port: 3000,
  host: 'localhost',
  
  // JWT Configuration
  jwtSecret: 'your-super-secret-jwt-key',
  
  // Storage Configuration
  storage: {
    type: 'mongodb',
    options: {
      uri: 'mongodb://localhost:27017/authosphere'
    }
  },
  
  // OAuth Configuration
  oauth: {
    google: {
      clientId: 'your-google-client-id',
      clientSecret: 'your-google-client-secret'
    }
  },
  
  // Security Configuration
  rateLimitMax: 100,
  bcryptRounds: 12,
  
  // Frontend Configuration
  frontendUrl: 'http://localhost:3000'
});

📋 API Endpoints

Authentication

• POST /register - Register new user
• POST /login - User login
• POST /logout - User logout
• POST /refresh - Refresh JWT token
• GET /profile - Get user profile

OAuth

• GET /oauth/:provider/authorize - Start OAuth flow
• GET /oauth/:provider/callback - OAuth callback
• GET /oauth/providers - Get available providers

User Management

• GET /users - Get all users (admin)
• DELETE /users/me - Delete current user

System

• GET /health - Health check

🛡️ Security Features

• JWT Tokens - Secure token-based authentication
• Password Hashing - bcrypt with configurable rounds
• Rate Limiting - Configurable request limits
• CORS Protection - Configurable CORS policies
• Helmet Security - Security headers
• Input Validation - Joi schema validation
• SQL Injection Protection - Parameterized queries
• XSS Protection - Input sanitization

📊 Health Monitoring

Health Check Endpoint

curl http://localhost:3000/auth/health

Response

{
  "status": "healthy",
  "timestamp": "2023-01-01T00:00:00.000Z",
  "storage": {
    "status": "healthy",
    "type": "mongodb",
    "initialized": true,
    "connection": "connected",
    "stats": {
      "users": 150,
      "sessions": 25,
      "oauthStates": 3,
      "refreshTokens": 45
    }
  }
}

🧪 Testing

Unit Tests

npm test

Integration Tests

npm run test:integration

Load Testing

npm run test:load

📚 Examples

Basic Example

const { createAuthosphere } = require('@authosphere/nodejs-auth-module');

const app = createAuthosphere({
  jwtSecret: 'secret',
  storage: { type: 'memory' }
});

app.listen(3000);

MongoDB Example

const { createAuthosphere } = require('@authosphere/nodejs-auth-module');

const app = createAuthosphere({
  jwtSecret: 'secret',
  storage: {
    type: 'mongodb',
    options: {
      uri: 'mongodb://localhost:27017/authosphere'
    }
  }
});

app.listen(3000);

Hybrid Storage Example

const { createAuthosphere } = require('@authosphere/nodejs-auth-module');

const app = createAuthosphere({
  jwtSecret: 'secret',
  storage: {
    primary: {
      type: 'postgresql',
      options: {
        databaseUrl: 'postgresql://user:pass@localhost:5432/authosphere'
      }
    },
    cache: {
      type: 'redis',
      options: {
        url: 'redis://localhost:6379'
      }
    }
  }
});

app.listen(3000);

🔄 Migration from v1

See Migration Guide for detailed migration instructions.

Quick Migration

// Before (v1)
const app = createAuthosphere({
  jwtSecret: 'secret'
});

// After (v2)
const app = createAuthosphere({
  jwtSecret: 'secret',
  storage: {
    type: 'mongodb',
    options: {
      uri: 'mongodb://localhost:27017/authosphere'
    }
  }
});

📖 Documentation

• API Reference - Complete API documentation
• Database Integration - Database setup guide
• Migration Guide - v1 to v2 migration
• Examples - Working examples

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Support

• 📧 Email: [email protected]
• 🌐 Website: www.terekhindt.com
• 🐛 Issues: GitHub Issues

🙏 Acknowledgments

• Express.js - Web framework
• Mongoose - MongoDB ODM
• Prisma - PostgreSQL ORM
• Redis - In-memory data store
• JWT - JSON Web Tokens
• OAuth 2.0 - Authorization framework

Made with ❤️ by Terekhin Digital Crew