@trebor/buildhtml 1.0.2 → 1.0.4

package/README.md

@@ -1,7 +1,6 @@
-# BuildHTML
+# @trebor/buildhtml
 
-**High-performance, server-side rendering (SSR) library for Node.js.**  
-*"Build HTML at lightning speed with reactive state management."*
+**High-performance, server-side rendering (SSR) library for Node.js.** *"Build HTML at lightning speed with reactive state management."*
 
 ---
 
@@ -9,20 +8,20 @@
 
 BuildHTML is a lightweight SSR library for Node.js featuring object pooling, reactive state management, and CSS-in-JS capabilities. Build HTML on the server with minimal memory usage and blazing-fast performance.
 
-- **Zero dependencies** – Only Node.js required
-- **High Performance** – Object pooling and LRU caching (1-5ms render time)
-- **Reactive State** – Built-in state management with automatic UI updates
-- **CSS-in-JS** – Scoped and global styling with automatic CSS generation
-- **Security** – XSS protection, CSS sanitization, and CSP nonce support
-- **Production Ready** – HTML minification, compression, and metrics
-- **JSON Export** – Save/restore pages with optional obfuscation
+- **Zero dependencies** – Only Node.js required.
+- **High Performance** – Object pooling and LRU caching (1-5ms render time).
+- **Reactive State** – Built-in state management with automatic UI updates.
+- **CSS-in-JS** – Scoped and global styling with automatic CSS generation.
+- **Security** – XSS protection, CSS sanitization, and CSP nonce support.
+- **Production Ready** – HTML minification, compression, and metrics.
+- **JSON Export** – Save/restore pages with optional obfuscation.
 
 ---
 
 ## Installation
 
 ```bash
-npm install buildhtml
+npm install @trebor/buildhtml
 ```
 
 ---
@@ -30,7 +29,7 @@ npm install buildhtml
 ## Quick Start
 
 ```javascript
-const { Document } = require('buildhtml');
+const { Document } = require('@trebor/buildhtml');
 
 // Create a document
 const doc = new Document();
@@ -257,7 +256,7 @@ const {
   resetPools,        // Reset object pools
   healthCheck,       // Health check data
   metrics            // Performance metrics
-} = require('buildhtml');
+} = require('@trebor/buildhtml');
 ```
 
 ---
@@ -268,7 +267,7 @@ const {
 
 ```javascript
 const express = require('express');
-const { Document } = require('buildhtml');
+const { Document } = require('@trebor/buildhtml');
 
 const app = express();
 
@@ -400,7 +399,7 @@ app.get('/spa', (req, res) => {
 ## Configuration
 
 ```javascript
-const { CONFIG } = require('buildhtml');
+const { CONFIG } = require('@trebor/buildhtml');
 
 CONFIG.mode = 'prod';           // 'prod' or 'dev'
 CONFIG.poolSize = 150;          // Max pooled elements
@@ -436,14 +435,14 @@ clearCache('user-');    // Clear all keys containing 'user-'
 ### enableCompression()
 
 ```javascript
-const { enableCompression } = require('buildhtml');
+const { enableCompression } = require('@trebor/buildhtml');
 app.use(enableCompression());
 ```
 
 ### warmupCache(routes)
 
 ```javascript
-const { warmupCache } = require('buildhtml');
+const { warmupCache } = require('@trebor/buildhtml');
 
 await warmupCache([
   { key: 'home', builder: () => buildHomePage() },
@@ -479,7 +478,7 @@ const html = doc.render();
 
 ```javascript
 // Render with JSON embedded in HTML
-const html = doc.renderJSON({ encrypt: true });
+const html = doc.renderJSON({ obfuscate: true });
 
 // In browser:
 console.log(window.__SCULPTOR_DATA__);
@@ -490,31 +489,92 @@ console.log(window.__SCULPTOR_DATA__);
 
 ## Security
 
-### XSS Protection
-
-All text is automatically escaped:
+### Built-in Security Features
 
+**Automatic XSS Protection**
 ```javascript
 doc.create('div').text('<script>alert("XSS")</script>');
 // Output: &lt;script&gt;alert("XSS")&lt;/script&gt;
 ```
 
-### CSS Injection Protection
-
-Dangerous CSS characters are sanitized:
-
+**CSS Injection Prevention**
 ```javascript
 el.css({ background: 'red; } body { display: none; }' });
 // Sanitized automatically
 ```
 
-### CSP Nonce Support
-
+**CSP Nonce Support**
 ```javascript
 const doc = new Document({ nonce: 'abc123' });
 // All inline scripts/styles get nonce attribute
 ```
 
+### Enhanced Security Features (NEW!)
+
+**Security Headers Middleware**
+```javascript
+const { securityHeaders } = require('@trebor/buildhtml');
+
+app.use(securityHeaders({
+  enableCSP: true,
+  enableHSTS: true,
+  enableXFrameOptions: true,
+  cspNonce: (req) => req.nonce
+}));
+```
+
+**Input Sanitization**
+```javascript
+const { sanitize } = require('@trebor/buildhtml');
+
+// Text sanitization
+const safe = sanitize.text('<script>bad</script>');
+
+// URL sanitization (blocks javascript:, data:, vbscript:)
+const url = sanitize.url('javascript:alert(1)'); // Returns ''
+
+// Email validation
+const email = sanitize.email('user@example.com');
+
+// Filename sanitization (prevents path traversal)
+const filename = sanitize.filename('../../../etc/passwd');
+```
+
+**CSRF Protection**
+```javascript
+const { csrf } = require('@trebor/buildhtml');
+
+app.use(csrf.middleware());
+
+app.post('/submit', (req, res) => {
+  // CSRF token automatically validated
+  // Request blocked if invalid
+});
+```
+
+**Rate Limiting**
+```javascript
+const { createRateLimiter } = require('@trebor/buildhtml');
+
+app.use('/api', createRateLimiter({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  maxRequests: 100
+}));
+```
+
+**CSP Header Generation**
+```javascript
+const { generateCSP } = require('@trebor/buildhtml');
+
+const csp = generateCSP({
+  scriptSrc: ["'self'", "'nonce-abc123'"],
+  styleSrc: ["'self'"],
+  imgSrc: ["'self'", 'data:', 'https:']
+});
+```
+
+📖 **See [SECURITY.md](./SECURITY.md) for complete security documentation**
+
 ---
 
 ## Advanced Features
@@ -546,7 +606,7 @@ doc.oncreate(() => {
 ```javascript
 process.env.ENABLE_METRICS = 'true';
 
-const { metrics } = require('buildhtml');
+const { metrics } = require('@trebor/buildhtml');
 
 // After some requests...
 console.log(metrics.getStats());
@@ -663,7 +723,7 @@ const html = doc.render();
 
 ```javascript
 const express = require('express');
-const { Document, createCachedRenderer } = require('buildhtml');
+const { Document, createCachedRenderer } = require('@trebor/buildhtml');
 
 const app = express();
 

package/index.js

@@ -688,25 +688,20 @@ class LRUCache {
 const responseCache = new LRUCache(CONFIG.cacheLimit);
 const inFlightCache = new Map();
 
-/* ---------------- ENCRYPTION ---------------- */
+/* ---------------- OBFUSCATION (NOT ENCRYPTION) ---------------- */
 // Simple Base64 obfuscation for JSON data
-// NOTE: This is obfuscation, NOT cryptographic security!
-function generateEncryptionKey() {
-  // Not needed for Base64, but kept for API compatibility
-  return 1;
-}
-
-function encryptString(str, key) {
+// WARNING: This is obfuscation ONLY, NOT cryptographic security!
+// It only reduces payload size and makes data less human-readable.
+function obfuscateString(str) {
   // Simple Base64 is fast and sufficient for obfuscation.
-  // Reversing large strings is too expensive for the client.
   if (typeof Buffer !== 'undefined') {
     return Buffer.from(str, 'utf-8').toString('base64');
   }
   return btoa(unescape(encodeURIComponent(str)));
 }
 
-function getDecryptScript() {
-  // Optimized decoder: Just decode Base64 (O(1) complexity relative to string ops)
+function getDeobfuscateScript() {
+  // Optimized decoder: Just decode Base64
   return `var _d=function(e){return decodeURIComponent(escape(atob(e)));};`;
 }
 
@@ -962,23 +957,13 @@ class Document {
     doc.head.globalStyles = json.globalStyles || [];
     doc.head.classStyles = json.classStyles || {};
 
-    // Restore global state
+    // Restore global state (data only)
     doc._globalState = json.globalState || {};
 
-    // Restore oncreate callbacks
-    if (json.oncreateCallbacks && Array.isArray(json.oncreateCallbacks)) {
-      for (const fnStr of json.oncreateCallbacks) {
-        try {
-          // eslint-disable-next-line no-eval
-          const fn = eval(`(${fnStr})`);
-          doc._oncreateCallbacks.push(fn);
-        } catch (err) {
-          if (CONFIG.mode === 'dev') {
-            console.error('Failed to restore oncreate callback:', err);
-          }
-        }
-      }
-    }
+    // WARNING: Functions cannot be restored from JSON for security reasons.
+    // oncreate callbacks, computed functions, and event handlers are NOT restored.
+    // This method is intended for server-side data restoration only.
+    // For client-side hydration with functions, use renderJSON() instead.
 
     // Restore body
     const deserializeElement = (node) => {
@@ -1009,35 +994,9 @@ class Document {
         el._stateBindings = node.stateBindings;
       }
 
-      if (node.computed) {
-        try {
-          // eslint-disable-next-line no-eval
-          el._computed = eval(`(${node.computed})`);
-        } catch (err) {
-          if (CONFIG.mode === 'dev') {
-            console.error('Failed to restore computed function:', err);
-          }
-        }
-      }
-
-      if (node.events && Array.isArray(node.events)) {
-        for (const evt of node.events) {
-          try {
-            // eslint-disable-next-line no-eval
-            const fn = eval(`(${evt.fn})`);
-            el.events.push({
-              event: evt.event,
-              id: evt.id,
-              targetId: evt.targetId,
-              fn: fn
-            });
-          } catch (err) {
-            if (CONFIG.mode === 'dev') {
-              console.error('Failed to restore event handler:', err);
-            }
-          }
-        }
-      }
+      // NOTE: Functions (computed, events, oncreate) are NOT restored from JSON
+      // for security reasons. This method is for data restoration only.
+      // For full client-side hydration with functions, use renderJSON() instead.
 
       el.hydrate = node.hydrate || false;
 
@@ -1206,8 +1165,8 @@ class Document {
     
     // Inject JSON Data (Fast Decode)
     if (obfuscate) {
-      const obfuscated = encryptString(jsonStr, true);
-      parts.push(getDecryptScript(), `window.${jsonVarName}=JSON.parse(_d("${obfuscated}"));`);
+      const obfuscated = obfuscateString(jsonStr);
+      parts.push(getDeobfuscateScript(), `window.${jsonVarName}=JSON.parse(_d("${obfuscated}"));`);
     } else {
       parts.push(`window.${jsonVarName}=${jsonStr};`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trebor/buildhtml",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Zero-dependency, ultra-fast HTML builder for server-side rendering (SSR).",
   "main": "index.js",
   "files": [
@@ -35,4 +35,4 @@
     "url": "https://github.com/0trebor0/buildhtml/issues"
   },
   "homepage": "https://github.com/0trebor0/buildhtml#readme"
-}
+}