cipher-shield 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Omindu Dissanayaka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,666 @@
+# cipher-shield 🛡️
+
+**Industrial-grade security middleware for Node.js/Express applications**
+
+[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/OminduDissanayaka/cipher-shield)
+[![NPM](https://img.shields.io/npm/v/cipher-shield.svg)](https://www.npmjs.com/package/cipher-shield)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D14.0.0-green.svg)](https://nodejs.org/)
+
+cipher-shield provides **layered active defense** against unauthorized access, automated threats, and data breaches. Built for production environments requiring robust security.
+
+---
+
+## 📋 Table of Contents
+
+- [⚡ 5-Minute Setup](#-5-minute-setup)
+- [✨ Features Overview](#-features-overview)
+- [🔐 AES Vault](#-aes-vault)
+- [👻 Ghost Routes](#-ghost-routes)
+- [🌑 Shadow Ban](#-shadow-ban)
+- [🤖 AI Gate](#-ai-gate)
+- [🚨 DEFCON System](#-defcon-system)
+- [📋 Smart Blacklist](#-smart-blacklist)
+- [🛡️ Helmet Security](#️-helmet-security)
+- [🚦 Rate Limiting](#-rate-limiting)
+- [🔒 SSL Manager](#-ssl-manager)
+- [🏷️ Security Signature](#️-security-signature)
+- [📝 Smart Logger](#-smart-logger)
+- [🔑 Magic Auth](#-magic-auth)
+- [📚 API Reference](#-api-reference)
+- [⚠️ Security Best Practices](#️-security-best-practices)
+- [🔍 Troubleshooting](#-troubleshooting)
+- [📞 Support](#-support)
+
+---
+
+## ⚡ 5-Minute Setup
+
+Get protected immediately with minimal configuration:
+
+```bash
+npm install cipher-shield
+```
+
+```javascript
+const express = require('express');
+const cipherShield = require('cipher-shield');
+
+const app = express();
+app.use(express.json());
+
+// 🔒 Add security middleware
+app.use(cipherShield({
+  ghostRoutes: ['/admin', '.env'],           // Block unauthorized routes
+  shadowBan: { enabled: true, delayTime: 5000 }, // Delay malicious IPs
+  encryption: {                               // Encrypt sensitive data
+    enabled: true,
+    algorithm: 'aes-256-gcm',
+    secretKey: 'your-32-character-secret-key!!!'
+  }
+}));
+
+app.get('/', (req, res) => {
+  res.json({ message: 'Your app is now protected! 🛡️' });
+});
+
+app.listen(3000, () => {
+  console.log('🔒 Secure server running on port 3000');
+});
+```
+
+**Test it:** Visit `http://localhost:3000/admin` (blocked) or `http://localhost:3000` (allowed).
+
+---
+
+## ✨ Features Overview
+
+| Feature | Description | Status |
+|---------|-------------|--------|
+| 🔐 **AES Vault** | Multi-algorithm encryption (GCM/CBC/CTR) with automatic key validation | ✅ Production-ready |
+| 👻 **Ghost Routes** | Honeypot detection for unauthorized scanners | ✅ Production-ready |
+| 🌑 **Shadow Ban** | Time-wasting delays for suspicious IPs | ✅ Production-ready |
+| 🤖 **AI Gate** | AI-powered payload analysis (Gemini/OpenAI) | ✅ Production-ready |
+| 🚨 **DEFCON System** | Adaptive threat escalation with automatic response | ✅ Production-ready |
+| 📋 **Smart Blacklist** | IP management with automatic expiry and analytics | ✅ Production-ready |
+| 🛡️ **Helmet Security** | Comprehensive HTTP security headers (CSP, HSTS, XSS) | ✅ Production-ready |
+| 🚦 **Rate Limiting** | DDoS protection with configurable limits | ✅ Production-ready |
+| 🔒 **SSL Manager** | Automated Let's Encrypt certificate management | ✅ Production-ready |
+| 🏷️ **Security Signature** | Customizable security headers with branding | ✅ Production-ready |
+| 📝 **Smart Logger** | Intelligent logging with automatic data masking | ✅ Production-ready |
+| 🔑 **Magic Auth** | Complete JWT authentication system | ✅ Production-ready |
+
+---
+
+## 🔐 AES Vault
+
+**Advanced encryption with multiple algorithms and automatic key validation.**
+
+Provides secure data encryption/decryption with support for AES-GCM (recommended), AES-CBC, and AES-CTR modes. Includes automatic key length validation and secure key generation.
+
+### Usage
+
+```javascript
+const cipherShield = require('cipher-shield');
+
+// Enable encryption middleware
+app.use(cipherShield({
+  encryption: {
+    enabled: true,
+    algorithm: 'aes-256-gcm',  // Recommended for new projects
+    secretKey: process.env.ENCRYPTION_KEY
+  }
+}));
+
+// Client-side encryption
+const { encrypt } = require('cipher-shield');
+const encrypted = encrypt(JSON.stringify({ sensitive: 'data' }), key, 'aes-256-gcm');
+
+// Server automatically decrypts req.body
+app.post('/api/secure', (req, res) => {
+  console.log(req.body); // Automatically decrypted
+  res.json({ received: req.body });
+});
+```
+
+### Supported Algorithms
+
+| Algorithm | Key Length | Mode | Use Case |
+|-----------|------------|------|----------|
+| `aes-128-gcm` | 16 chars | GCM (AEAD) | **Balanced security/performance** |
+| `aes-256-gcm` | 32 chars | GCM (AEAD) | **Maximum security** |
+| `aes-128-cbc` | 16 chars | CBC | Legacy compatibility |
+| `aes-256-cbc` | 32 chars | CBC | Legacy compatibility |
+| `aes-128-ctr` | 16 chars | CTR | High performance |
+| `aes-256-ctr` | 32 chars | CTR | High performance |
+
+### Key Generation
+
+```javascript
+const { generateKey } = require('cipher-shield');
+
+// Generate a secure key for your algorithm
+const key = generateKey('aes-256-gcm'); // Returns 32-character key
+console.log('Your secure key:', key);
+```
+
+---
+
+## 👻 Ghost Routes
+
+**Honeypot detection that identifies and blocks unauthorized route scanners.**
+
+Automatically detects access to common attack vectors like admin panels, configuration files, and development endpoints. Uses pattern matching and wildcard support.
+
+### Usage
+
+```javascript
+app.use(cipherShield({
+  ghostRoutes: [
+    '/admin',           // Direct match
+    '/wp-admin',        // WordPress admin
+    '/phpmyadmin',      // Database admin
+    '.env',            // Environment file
+    '/config.json',    // Config file
+    '/.git',           // Git repository
+    '/backup.zip'      // Backup file
+  ]
+}));
+```
+
+### Pattern Matching
+
+- **Exact Match**: `/admin` matches exactly
+- **Prefix Match**: `/api` matches `/api/users`, `/api/posts`
+- **File Extension**: `.env` matches any `.env` file
+- **Wildcard**: `/admin/*` matches `/admin/users`, `/admin/settings`
+
+---
+
+## 🌑 Shadow Ban
+
+**Time-wasting delays that frustrate malicious automated scanners.**
+
+Applies configurable delays to blacklisted IPs, making automated attacks inefficient while maintaining normal user experience.
+
+### Usage
+
+```javascript
+app.use(cipherShield({
+  shadowBan: {
+    enabled: true,
+    delayTime: 10000  // 10-second delay for blacklisted IPs
+  }
+}));
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `true` | Enable shadow ban protection |
+| `delayTime` | number | `5000` | Delay in milliseconds |
+| `maxDelay` | number | `30000` | Maximum delay time |
+| `whitelist` | string[] | `[]` | IPs to exclude from delays |
+
+---
+
+## 🤖 AI Gate
+
+**AI-powered threat detection using Gemini or OpenAI for payload analysis.**
+
+Scans request payloads for malicious patterns, SQL injection, XSS attempts, and other threats using advanced AI models.
+
+### Usage
+
+```javascript
+app.use(cipherShield({
+  aiGate: {
+    enabled: true,
+    provider: 'gemini',  // or 'openai'
+    gemini: {
+      apiKey: process.env.GEMINI_API_KEY,
+      model: 'gemini-pro'
+    },
+    scanRoutes: ['/api/*'],  // Scan all API routes
+    failSafe: true           // Continue if AI fails
+  }
+}));
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `false` | Enable AI threat detection |
+| `provider` | string | `'gemini'` | AI provider (`gemini` or `openai`) |
+| `scanRoutes` | string[] | `['/api/*']` | Routes to scan |
+| `failSafe` | boolean | `true` | Continue on AI failure |
+| `cacheResults` | boolean | `true` | Cache scan results |
+
+---
+
+## 🚨 DEFCON System
+
+**Adaptive threat escalation that automatically adjusts security levels.**
+
+Monitors threat patterns and escalates security measures from GREEN (normal) to RED (maximum security) based on detected threats.
+
+### Usage
+
+```javascript
+app.use(cipherShield({
+  adaptiveDefcon: true  // Enable automatic escalation
+}));
+```
+
+### DEFCON Levels
+
+- **GREEN**: Normal operation, standard security
+- **YELLOW**: Elevated threat, increased monitoring
+- **ORANGE**: High threat, reduced AI scanning
+- **RED**: Maximum threat, minimal processing
+
+### Manual Control
+
+```javascript
+const { defconSystem } = require('cipher-shield');
+
+// Check current status
+const status = defconSystem.getStatus();
+
+// Manual escalation
+defconSystem.escalate('DDoS_ATTACK_DETECTED');
+```
+
+---
+
+## 📋 Smart Blacklist
+
+**Intelligent IP management with automatic expiry and analytics.**
+
+Maintains blacklists with automatic cleanup, reason tracking, and performance monitoring.
+
+### Usage
+
+```javascript
+const { blacklistMem } = require('cipher-shield');
+
+// Add IP to blacklist
+blacklistMem.add('192.168.1.100', 'suspicious_activity', 3600000); // 1 hour
+
+// Check if IP is blacklisted
+if (blacklistMem.isBlacklisted('192.168.1.100')) {
+  // Apply shadow ban or block
+}
+```
+
+### Features
+
+- **Automatic Expiry**: IPs removed after specified time
+- **Reason Tracking**: Log why IPs were blacklisted
+- **Analytics**: Track blacklist hit rates
+- **Memory Efficient**: Optimized for high-performance
+
+---
+
+## 🛡️ Helmet Security
+
+**Comprehensive HTTP security headers for passive defense.**
+
+Applies industry-standard security headers including CSP, HSTS, XSS protection, and more.
+
+### Usage
+
+```javascript
+app.use(cipherShield({
+  headers: {
+    enabled: true,
+    security: 'standard'  // 'standard' or 'strict'
+  }
+}));
+```
+
+### Headers Applied
+
+**Standard Mode:**
+- `X-Content-Type-Options: nosniff`
+- `X-Frame-Options: SAMEORIGIN`
+- `X-XSS-Protection: 1; mode=block`
+- `Referrer-Policy: strict-origin-when-cross-origin`
+
+**Strict Mode (adds):**
+- `Content-Security-Policy: default-src 'self'`
+- `Strict-Transport-Security: max-age=31536000`
+
+---
+
+## 🚦 Rate Limiting
+
+**DDoS protection with configurable request limits.**
+
+Prevents brute force attacks and flood attempts using express-rate-limit.
+
+### Usage
+
+```javascript
+app.use(cipherShield({
+  rateLimit: {
+    enabled: true,
+    windowMs: 900000,  // 15 minutes
+    max: 100          // 100 requests per window
+  }
+}));
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `windowMs` | number | `900000` | Time window (15 min) |
+| `max` | number | `100` | Max requests per window |
+| `message` | string | `'Too many requests'` | Error message |
+| `skipSuccessfulRequests` | boolean | `false` | Count successful requests |
+| `skipFailedRequests` | boolean | `false` | Count failed requests |
+
+---
+
+## 🔒 SSL Manager
+
+**Automated SSL certificate management with Let's Encrypt ACME.**
+
+> ⚠️ **Requires VPS Server**: SSL Manager needs full file system access and HTTP challenge capabilities. **Not compatible with shared hosting.**
+
+### Usage
+
+```javascript
+const { CipherShield } = require('cipher-shield');
+
+const shield = new CipherShield({
+  // Basic configuration
+});
+
+await shield.enableSSL({
+  email: 'admin@yourdomain.com',
+  domains: ['yourdomain.com', 'www.yourdomain.com'],
+  staging: true  // Use false for production
+});
+```
+
+### Requirements
+
+- ✅ **VPS Server** with full file system access
+- ✅ **Port 80** accessible for HTTP challenges
+- ✅ **Domain ownership** verification
+- ❌ **Shared hosting** (cPanel, Plesk, etc.)
+
+### Features
+
+- **Automatic Renewal**: Certificates renew before expiry
+- **Staging Environment**: Safe testing environment
+- **Multiple Domains**: SAN certificates supported
+- **RSA/ECDSA Keys**: Flexible key types
+
+---
+
+## 🏷️ Security Signature
+
+**Customizable security headers with flexible branding.**
+
+Adds identifiable headers to responses for security attribution and monitoring.
+
+### Usage
+
+```javascript
+app.use(cipherShield({
+  signature: {
+    enabled: true,
+    headerValue: 'My Security System',
+    customHeaderName: 'X-Secured-By'
+  }
+}));
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `true` | Enable signature headers |
+| `headerValue` | string | `'CipherShield'` | Header value |
+| `customHeaderName` | string | `'X-Protected-By'` | Header name |
+| `randomize` | boolean | `false` | Randomize header values |
+| `customServer` | string | `null` | Custom server header |
+
+---
+
+## 📝 Smart Logger
+
+**Intelligent logging with automatic sensitive data masking.**
+
+Prevents accidental exposure of passwords, tokens, and secrets in logs through recursive scanning.
+
+### Usage
+
+```javascript
+const { SmartLogger } = require('cipher-shield');
+
+const logger = new SmartLogger({
+  maskKeys: ['password', 'token', 'secret']
+});
+
+// Automatically masks sensitive data
+logger.info('User login', {
+  username: 'john_doe',
+  password: 'secret123',    // → ********
+  token: 'jwt-token'        // → ********
+});
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `maskKeys` | string[] | `['password', 'token', 'secret']` | Keys to mask |
+| `maskValues` | string[] | `['Bearer ', 'Token ']` | Values to mask |
+| `maskPatterns` | RegExp[] | `[credit card patterns]` | Regex patterns |
+| `colors` | boolean | `true` | Enable colored output |
+| `timestamps` | boolean | `true` | Include timestamps |
+
+---
+
+## 🔑 Magic Auth
+
+**Complete JWT authentication system with secure defaults.**
+
+Provides token generation, verification, middleware, and refresh token support.
+
+### Usage
+
+```javascript
+const { MagicAuth } = require('cipher-shield');
+
+const auth = new MagicAuth({
+  secret: process.env.JWT_SECRET,
+  expiresIn: '1h'
+});
+
+// Generate token
+const token = auth.sign({ userId: 123, role: 'admin' });
+
+// Protect routes
+app.get('/api/profile', auth.middleware(), (req, res) => {
+  res.json({ user: req.user });
+});
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `secret` | string | **required** | JWT signing secret |
+| `expiresIn` | string | `'1h'` | Token expiration |
+| `algorithm` | string | `'HS256'` | Signing algorithm |
+| `issuer` | string | `undefined` | Token issuer |
+| `audience` | string | `undefined` | Token audience |
+
+### Methods
+
+- `sign(payload)` - Generate JWT token
+- `verify(token)` - Verify and decode token
+- `middleware(roles?)` - Express authentication middleware
+- `generateTokens(payload)` - Create access + refresh tokens
+- `refreshAccessToken(refreshToken)` - Refresh access token
+
+---
+
+## 📚 API Reference
+
+### Core Functions
+
+```javascript
+const cipherShield = require('cipher-shield');
+
+// Main middleware
+const middleware = cipherShield(config);
+
+// Encryption utilities
+const { encrypt, decrypt, generateKey } = require('cipher-shield');
+
+// Classes
+const { SmartLogger, MagicAuth, CipherShield } = require('cipher-shield');
+```
+
+### Configuration Schema
+
+```javascript
+const config = {
+  // Core Security
+  ghostRoutes: ['/admin', '.env'],
+  shadowBan: { enabled: true, delayTime: 5000 },
+  encryption: {
+    enabled: true,
+    algorithm: 'aes-256-gcm',
+    secretKey: process.env.ENCRYPTION_KEY
+  },
+
+  // Advanced Features
+  aiGate: { enabled: false },
+  adaptiveDefcon: true,
+
+  // Passive Defense
+  headers: { enabled: true, security: 'standard' },
+  rateLimit: { enabled: true, windowMs: 900000, max: 100 },
+  signature: { enabled: true, headerValue: 'CipherShield' }
+};
+```
+
+---
+
+## ⚠️ Security Best Practices
+
+### 🔐 Key Management
+- Use environment variables for all secrets
+- Generate keys with `generateKey()` function
+- Rotate keys regularly in production
+- Use different keys for different environments
+
+### 🛡️ Production Setup
+```javascript
+// .env file
+ENCRYPTION_KEY=your-32-character-secret-key!!!
+JWT_SECRET=your-jwt-signing-secret-here
+GEMINI_API_KEY=your-ai-api-key
+NODE_ENV=production
+
+// server.js
+require('dotenv').config();
+
+const shield = cipherShield({
+  encryption: { secretKey: process.env.ENCRYPTION_KEY },
+  aiGate: { gemini: { apiKey: process.env.GEMINI_API_KEY } }
+});
+```
+
+### 📊 Monitoring
+- Enable debug logging in development
+- Monitor DEFCON status in production
+- Log security events for analysis
+- Set up alerts for threat escalation
+
+---
+
+## 🔍 Troubleshooting
+
+### Common Issues
+
+**"Key length mismatch"**
+```javascript
+// Use correct key length for algorithm
+const key = generateKey('aes-256-gcm'); // 32 characters
+```
+
+**"AI Gate not working"**
+```javascript
+// Check API key and network
+console.log('API Key:', !!process.env.GEMINI_API_KEY);
+```
+
+**"SSL Manager fails on shared hosting"**
+```javascript
+// SSL Manager requires VPS server
+// Shared hosting doesn't support ACME challenges
+```
+
+**"MagicAuth tokens invalid"**
+```javascript
+// Ensure consistent secrets across restarts
+const auth = new MagicAuth({
+  secret: process.env.JWT_SECRET  // Same secret always
+});
+```
+
+### Debug Mode
+
+```javascript
+const shield = cipherShield({
+  debug: true  // Enable verbose logging
+});
+```
+
+---
+
+## 📞 Support
+
+### 🆘 Getting Help
+
+- 📧 **Email**: hellow@omindu.dev
+- 🐛 **Issues**: [GitHub Issues](https://github.com/OminduDissanayaka/cipher-shield/issues)
+- 📖 **Documentation**: [Website](https://github.com/OminduDissanayaka/cipher-shield)
+
+### 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit changes (`git commit -m 'Add amazing feature'`)
+4. Push to branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### 📄 License
+
+**MIT License** - See [LICENSE](LICENSE) file for details.
+
+---
+
+## 🎯 Quick Checklist
+
+- [ ] Node.js >= 14.0.0 installed
+- [ ] `npm install cipher-shield` executed
+- [ ] Environment variables configured
+- [ ] Security configuration added
+- [ ] Application tested with protection enabled
+
+---
+
+**Built with ❤️ by [Omindu Dissanayaka](https://omindu.dev)**
+
+