mastercontroller 1.3.0 → 1.3.1

package/.claude/settings.local.json

@@ -4,7 +4,8 @@
       "Bash(rm:*)",
       "Bash(mv:*)",
       "Bash(node -e:*)",
-      "Bash(find:*)"
+      "Bash(find:*)",
+      "Bash(node -c:*)"
     ],
     "deny": [],
     "ask": []

package/MasterControl.js

@@ -270,6 +270,7 @@ class MasterControl {
                     'MasterError',
                     'MasterCors',
                     'MasterSession',
+                    'SessionSecurity',
                     'MasterSocket',
                     'MasterHtml',
                     'MasterTemplate',
@@ -619,6 +620,7 @@ class MasterControl {
                 'MasterRequest': './MasterRequest',
                 'MasterCors': './MasterCors',
                 'MasterSession': './MasterSession',
+                'SessionSecurity': './security/SessionSecurity',
                 'MasterSocket': './MasterSocket',
                 'MasterHtml': './MasterHtml',
                 'MasterTemplate': './MasterTemplate',

package/MasterPipeline.js

@@ -44,7 +44,7 @@ class MasterPipeline {
     /**
      * Run: Add terminal middleware that ends the pipeline
      *
-     * Terminal middleware signature: async (ctx) => { /* send response */ }
+     * Terminal middleware signature: async (ctx) => { ... send response ... }
      * - Does NOT call next()
      * - Must send response
      *

package/MasterTools.js

@@ -51,21 +51,48 @@ class MasterTools{
     };
    
     encrypt(payload, secret){
-        let iv = crypto.randomBytes(16).toString('hex').slice(0, 16);
-        let key = crypto.createHash('sha256').update(String(secret)).digest('base64').substr(0, 32);
-        crypto.createCipheriv('aes-256-cbc', key, iv);
-        var cipher = crypto.createCipher(algorithm,  key);
-        var crypted = cipher.update(payload,'utf8','hex');
-        crypted += cipher.final('hex');
-        return crypted;
+        // Generate random IV (16 bytes for AES)
+        const iv = crypto.randomBytes(16);
+
+        // Create 256-bit key from secret
+        const key = crypto.createHash('sha256').update(String(secret)).digest();
+
+        // Create cipher with AES-256-CBC
+        const cipher = crypto.createCipheriv('aes-256-cbc', key, iv);
+
+        // Encrypt payload
+        let encrypted = cipher.update(String(payload), 'utf8', 'hex');
+        encrypted += cipher.final('hex');
+
+        // Prepend IV to encrypted data (IV is not secret, needed for decryption)
+        return iv.toString('hex') + ':' + encrypted;
     }
-    
+
     decrypt(encryption, secret){
-          var key = crypto.createHash('sha256').update(String(secret)).digest('base64').substr(0, 32);
-          var decipher = crypto.createDecipheriv('aes-256-cbc', key, iv);
-          var dec = decipher.update(encryption,'hex','utf8');
-          dec += decipher.final('utf8');
-          return dec;
+        try {
+            // Split IV and encrypted data
+            const parts = encryption.split(':');
+            if (parts.length !== 2) {
+                throw new Error('Invalid encrypted data format');
+            }
+
+            const iv = Buffer.from(parts[0], 'hex');
+            const encryptedData = parts[1];
+
+            // Create 256-bit key from secret
+            const key = crypto.createHash('sha256').update(String(secret)).digest();
+
+            // Create decipher
+            const decipher = crypto.createDecipheriv('aes-256-cbc', key, iv);
+
+            // Decrypt
+            let decrypted = decipher.update(encryptedData, 'hex', 'utf8');
+            decrypted += decipher.final('utf8');
+
+            return decrypted;
+        } catch (error) {
+            throw new Error('Decryption failed: ' + error.message);
+        }
     }
     
     generateRandomKey(hash){

package/README.md

@@ -790,94 +790,230 @@ master.cors.init({
 
 ## Sessions
 
-### `master.sessions.init(options)`
+MasterController provides **two session systems**:
+- **`master.session`** (NEW) - Secure, Rails/Django-style sessions with automatic regeneration and protection (RECOMMENDED)
+- **`master.sessions`** (LEGACY) - Original cookie-based session API (backward compatibility only)
 
-Initialize sessions (auto-registers with middleware pipeline).
+### Secure Sessions (NEW - Recommended)
+
+#### `master.session.init(options)`
+
+Initialize secure sessions with Rails/Django-style `req.session` object (auto-registers with middleware pipeline).
 
 ```javascript
-master.sessions.init({
-    secret: 'your-secret-key',
-    maxAge: 900000,        // 15 minutes
-    httpOnly: true,
-    secure: true,          // HTTPS only
-    sameSite: true,
-    path: '/'
+// Environment-specific configuration
+const isProduction = master.environmentType === 'production';
+
+master.session.init({
+    cookieName: 'mc_session',
+    maxAge: isProduction ? 3600000 : 86400000,  // Production: 1 hour, Dev: 24 hours
+    httpOnly: true,                              // Prevent JavaScript access (XSS protection)
+    secure: isProduction,                        // HTTPS only in production
+    sameSite: isProduction ? 'strict' : 'lax',  // CSRF protection
+    rolling: true,                               // Extend session on each request
+    regenerateInterval: 900000,                  // Regenerate session ID every 15 minutes
+    useFingerprint: false                        // Session hijacking detection (opt-in)
 });
 ```
 
-### Session API
+**Security Features:**
+- ✅ 32-byte (256-bit) session IDs (cryptographically secure)
+- ✅ Automatic session regeneration (prevents fixation attacks)
+- ✅ HttpOnly cookies (prevents XSS cookie theft)
+- ✅ Secure flag for HTTPS (prevents MITM attacks)
+- ✅ SameSite CSRF protection
+- ✅ Rolling sessions (extends expiry on activity)
+- ✅ Automatic cleanup of expired sessions
+- ✅ Optional fingerprinting (detects hijacking)
+
+#### Using Sessions in Controllers
 
-#### `master.sessions.set(name, data, response, secret, options)`
-Create a session.
+Sessions are accessed via `obj.request.session` object:
 
 ```javascript
 class AuthController {
     login(obj) {
         const user = authenticateUser(obj.params.formData);
 
-        master.sessions.set('user', user, obj.response);
+        // Set session data (Rails/Express style)
+        obj.request.session.userId = user.id;
+        obj.request.session.username = user.name;
+        obj.request.session.loggedInAt = Date.now();
 
         this.redirect('/dashboard');
     }
+
+    logout(obj) {
+        // Destroy entire session
+        master.session.destroy(obj.request, obj.response);
+        this.redirect('/');
+    }
 }
 ```
 
-#### `master.sessions.get(name, request, secret)`
-Retrieve session data.
-
 ```javascript
 class DashboardController {
     index(obj) {
-        const user = master.sessions.get('user', obj.request);
+        // Read session data
+        const userId = obj.request.session.userId;
 
-        if (!user) {
+        if (!userId) {
             this.redirect('/login');
             return;
         }
 
-        this.render('dashboard', { user });
+        this.render('dashboard', { userId });
     }
 }
 ```
 
-#### `master.sessions.delete(name, response)`
-Delete a session.
+#### Session Management API
+
+**`master.session.destroy(req, res)`** - Destroy session completely
 
 ```javascript
-class AuthController {
-    logout(obj) {
-        master.sessions.delete('user', obj.response);
-        this.redirect('/');
-    }
-}
+master.session.destroy(obj.request, obj.response);
 ```
 
-#### `master.sessions.reset()`
-Clear all sessions (useful for testing).
+**`master.session.touch(sessionId)`** - Extend session expiry
 
 ```javascript
-master.sessions.reset();
+master.session.touch(obj.request.sessionId);
+```
+
+**`master.session.getSessionCount()`** - Get active session count (monitoring)
+
+```javascript
+const count = master.session.getSessionCount();
+console.log(`Active sessions: ${count}`);
+```
+
+**`master.session.clearAllSessions()`** - Clear all sessions (testing only)
+
+```javascript
+master.session.clearAllSessions();
+```
+
+#### Environment-Specific Best Practices
+
+```javascript
+// Get recommended settings
+const settings = master.session.getBestPractices('production');
+master.session.init(settings);
+```
+
+**Production Settings:**
+- Secure: true (HTTPS only)
+- SameSite: 'strict' (maximum CSRF protection)
+- MaxAge: 1 hour (short-lived sessions)
+- RegenerateInterval: 15 minutes
+
+**Development Settings:**
+- Secure: false (allow HTTP)
+- SameSite: 'lax' (easier testing)
+- MaxAge: 24 hours (convenient for development)
+- RegenerateInterval: 1 hour
+
+---
+
+### Legacy Sessions (Backward Compatibility)
+
+**⚠️ DEPRECATED: Use `master.session` (singular) for new projects.**
+
+The original `master.sessions` (plural) API is maintained for backward compatibility but lacks modern security features.
+
+#### `master.sessions.init(options)`
+
+Initialize legacy sessions (auto-registers with middleware pipeline).
+
+```javascript
+master.sessions.init({
+    secret: 'your-secret-key',
+    maxAge: 900000,        // 15 minutes
+    httpOnly: true,
+    secure: true,          // HTTPS only
+    sameSite: 'strict',    // Must be string: 'strict', 'lax', or 'none'
+    path: '/'
+});
+```
+
+#### Legacy Session API
+
+**`master.sessions.set(name, data, response, secret, options)`** - Create a session
+
+```javascript
+master.sessions.set('user', userData, obj.response);
 ```
 
-### Cookie Methods
+**`master.sessions.get(name, request, secret)`** - Retrieve session data
 
-Direct cookie access:
+```javascript
+const user = master.sessions.get('user', obj.request);
+```
+
+**`master.sessions.delete(name, response)`** - Delete a session
 
-#### `master.sessions.setCookie(name, value, response, options)`
+```javascript
+master.sessions.delete('user', obj.response);
+```
+
+**`master.sessions.reset()`** - Clear all sessions
+
+```javascript
+master.sessions.reset();
+```
+
+#### Legacy Cookie Methods
+
+**`master.sessions.setCookie(name, value, response, options)`**
 ```javascript
 master.sessions.setCookie('theme', 'dark', obj.response);
 ```
 
-#### `master.sessions.getCookie(name, request, secret)`
+**`master.sessions.getCookie(name, request, secret)`**
 ```javascript
 const theme = master.sessions.getCookie('theme', obj.request);
 ```
 
-#### `master.sessions.deleteCookie(name, response, options)`
+**`master.sessions.deleteCookie(name, response, options)`**
 ```javascript
 master.sessions.deleteCookie('theme', obj.response);
 ```
 
+#### Migration Guide: Legacy → Secure Sessions
+
+**Old (master.sessions):**
+```javascript
+// Set
+master.sessions.set('user', userData, obj.response);
+
+// Get
+const user = master.sessions.get('user', obj.request);
+
+// Delete
+master.sessions.delete('user', obj.response);
+```
+
+**New (master.session):**
+```javascript
+// Set (Rails/Express style)
+obj.request.session.user = userData;
+
+// Get
+const user = obj.request.session.user;
+
+// Delete
+master.session.destroy(obj.request, obj.response);
+```
+
+**Benefits of migration:**
+- ✅ Automatic session regeneration (prevents fixation)
+- ✅ 32-byte session IDs (stronger than 20-byte)
+- ✅ Rolling sessions (better UX)
+- ✅ Automatic cleanup (no memory leaks)
+- ✅ Rails/Express-style API (more familiar)
+- ✅ No broken encryption (legacy has crypto bugs)
+
 ---
 
 ## Security

package/package.json

@@ -18,5 +18,5 @@
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
-  "version": "1.3.0"
+  "version": "1.3.1"
 }

package/security/SessionSecurity.js

@@ -25,8 +25,8 @@ class SessionSecurity {
     this.domain = options.domain || null;
     this.path = options.path || '/';
 
-    // Session fingerprinting
-    this.useFingerprint = options.useFingerprint !== false;
+    // Session fingerprinting (disabled by default like ASP.NET Core)
+    this.useFingerprint = options.useFingerprint === true;
 
     // Start cleanup interval
     this._startCleanup();
@@ -407,6 +407,103 @@ const SESSION_BEST_PRACTICES = {
   }
 };
 
+// MasterController Integration
+const master = require('../MasterControl');
+
+// Create MasterController-compatible wrapper
+class MasterSessionSecurity {
+  constructor() {
+    this._instance = null;
+    this._options = {};
+  }
+
+  /**
+   * Initialize session security (Rails/Django style)
+   * Auto-registers with middleware pipeline
+   */
+  init(options = {}) {
+    this._options = options;
+    this._instance = new SessionSecurity(options);
+
+    // Auto-register with pipeline if available
+    if (master.pipeline) {
+      master.pipeline.use(this._instance.middleware());
+    }
+
+    return this;
+  }
+
+  /**
+   * Get middleware function
+   */
+  middleware() {
+    if (!this._instance) {
+      this.init();
+    }
+    return this._instance.middleware();
+  }
+
+  /**
+   * Destroy session
+   */
+  destroy(req, res) {
+    if (!this._instance) {
+      throw new Error('SessionSecurity not initialized. Call master.session.init() first.');
+    }
+    return this._instance.destroySession(req, res);
+  }
+
+  /**
+   * Get session by ID
+   */
+  getSession(sessionId) {
+    if (!this._instance) {
+      throw new Error('SessionSecurity not initialized. Call master.session.init() first.');
+    }
+    return this._instance.getSession(sessionId);
+  }
+
+  /**
+   * Touch session (extend expiry)
+   */
+  touch(sessionId) {
+    if (!this._instance) {
+      throw new Error('SessionSecurity not initialized. Call master.session.init() first.');
+    }
+    return this._instance.touch(sessionId);
+  }
+
+  /**
+   * Get session count (monitoring)
+   */
+  getSessionCount() {
+    if (!this._instance) {
+      throw new Error('SessionSecurity not initialized. Call master.session.init() first.');
+    }
+    return this._instance.getSessionCount();
+  }
+
+  /**
+   * Clear all sessions (testing only)
+   */
+  clearAllSessions() {
+    if (!this._instance) {
+      throw new Error('SessionSecurity not initialized. Call master.session.init() first.');
+    }
+    return this._instance.clearAllSessions();
+  }
+
+  /**
+   * Get recommended settings for environment
+   */
+  getBestPractices(env) {
+    return SESSION_BEST_PRACTICES[env] || SESSION_BEST_PRACTICES.development;
+  }
+}
+
+// Auto-register with MasterController
+master.extend("session", MasterSessionSecurity);
+
 module.exports = {
   SessionSecurity,
   session,