keypointjs 1.0.0 → 1.1.1

package/README.md

@@ -6,12 +6,11 @@
 
 </div>
 
-Based on your complete codebase, here is the comprehensive documentation:
-
 <div align="center">
 <p align="center">
   <img alt="GitHub" src="https://img.shields.io/github/license/anasbex-dev/keypointjs?color=blue">
   <img alt="npm" src="https://img.shields.io/npm/v/keypointjs">
+  <img alt="npmcharts" src="https://img.shields.io/npm/dm/keypointjs?style=for-the-badge">
   <img alt="Node.js" src="https://img.shields.io/badge/Node.js-%3E%3D18.0.0-green">
   <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-Ready-blue">
   <img alt="Tests" src="https://img.shields.io/badge/tests-100%25%20passing-brightgreen">
@@ -23,7 +22,6 @@ Based on your complete codebase, here is the comprehensive documentation:
 </div>
 
 
-
 # Project Overview
 
 KeypointJS is a sophisticated, layered authentication and authorization framework for Node.js with built-in security features, plugin architecture, and real-time capabilities.
@@ -51,7 +49,6 @@ Layered Middleware System
 │ Layer 7: Response Processing    │
 └─────────────────────────────────┘
 ```
-
 # File Structure & Responsibilities
 
 ## Core Components (core/)
@@ -192,6 +189,16 @@ responses
 
 Installation & Setup
 
+``` bash
+
+npm install keypointjs
+# or
+yarn add keypointjs
+# or
+pnpm add keypointjs
+
+```
+
 ```javascript
 import { KeypointJS } from './src/keypointJS.js';
 
@@ -800,9 +807,12 @@ Apache-2.0 license - see the LICENSE file for details.
 - Contributions: PRs welcome for bug fixes and features
 - Questions: Open a discussion for usage questions
 
----
+## KeypointJS is Independent
+
+KeypointJS does not depend on Express, Fastify, or any third-party HTTP framework.
+It ships with its own HTTP server, routing system, middleware pipeline, and security layer.
 
 ## Created Base ♥️ KeypointJS
 ### AnasBex - (⁠づ⁠￣⁠ ⁠³⁠￣⁠)⁠づ 
 
-KeypointJS provides a comprehensive, layered approach to API security with extensibility through plugins, real-time capabilities via WebSocket, and detailed monitoring through audit logging. The framework is production-ready with built-in security features and can be extended to meet specific requirements.
+KeypointJS provides a comprehensive, layered approach to API security with extensibility through plugins, real-time capabilities via WebSocket, and detailed monitoring through audit logging. The framework is production-ready with built-in security features and can be extended to meet specific requirements.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keypointjs",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "KeypointJS Identity-First API Framework with Mandatory Authentication",
   "main": "src/keypointJS.js",
   "type": "module",
@@ -12,6 +12,7 @@
     "./keypoint/validator": "./src/keypoint/KeypointValidator.js",
     "./keypoint/scopes": "./src/keypoint/ScopeManager.js",
     "./plugins": "./src/plugins/PluginManager.js",
+    "./plugins/transformer": "./src/plugins/transformer/TransformerPlugin.js",
     "./plugins/audit": "./src/plugins/AuditLogger.js",
     "./plugins/ratelimit": "./src/plugins/RateLimiter.js",
     "./plugins/websocket": "./src/plugins/WebSocketGuard.js",

package/src/core/ProtocolEngine.js

@@ -6,52 +6,106 @@ export class ProtocolEngine {
       maxBodySize: '1mb',
       parseJSON: true,
       parseForm: true,
+      validateProtocol: true, // protocol validation
+      trustedProxies: [], // trusted proxy list
+      maxHeaderSize: 8192, // header limits
       ...options
     };
     
-    this.supportedProtocols = new Set(['https', 'wss', 'http']);
+    this.supportedProtocols = new Set(['https', 'wss', 'http', 'grpc']); // grpc
   }
   
   async process(request) {
-    const context = {
-      id: crypto.randomUUID(),
-      timestamp: new Date(),
-      protocol: this.detectProtocol(request),
-      request: {
-        method: request.method,
-        url: new URL(request.url, `http://${request.headers.host}`),
-        headers: this.normalizeHeaders(request.headers),
-        ip: this.extractIP(request),
-        userAgent: request.headers['user-agent'] || '',
-        body: null
-      },
-      metadata: {}
-    };
-    
-    // Parse body based on content-type
-    if (this.shouldParseBody(request)) {
-      context.request.body = await this.parseRequestBody(request);
-    }
-    
-    // Validate protocol
-    if (!this.supportedProtocols.has(context.protocol)) {
-      throw new ProtocolError(`Unsupported protocol: ${context.protocol}`);
+  // Validate request basics
+  if (!request.method || !request.url) {
+    throw new ProtocolError('Invalid request structure', 400);
+  }
+  
+  // Validate headers size
+  const headerSize = JSON.stringify(request.headers).length;
+  if (headerSize > this.options.maxHeaderSize) {
+    throw new ProtocolError('Request headers too large', 431);
+  }
+  
+  const context = {
+    id: crypto.randomUUID(),
+    timestamp: new Date(),
+    protocol: this.detectProtocol(request),
+    request: {
+      method: request.method,
+      url: this.parseURL(request),
+      headers: this.normalizeHeaders(request.headers),
+      ip: this.extractIP(request),
+      userAgent: request.headers['user-agent'] || '',
+      body: null,
+      cookies: this.parseCookies(request.headers.cookie), // cookies
+      trailers: request.trailers || {} // trailers
+    },
+    metadata: {
+      bodyParsed: false,
+      secure: false,
+      clientInfo: {}
     }
-    
-    return context;
+  };
+  
+  // Set secure flag
+  context.metadata.secure = context.protocol === 'https' || context.protocol === 'wss';
+  
+  // Add client information
+  context.metadata.clientInfo = this.extractClientInfo(request);
+  
+  // Parse body if needed
+  if (this.shouldParseBody(request)) {
+    context.request.body = await this.parseRequestBody(request);
+    context.metadata.bodyParsed = true;
+  }
+  
+  // Validate protocol
+  if (this.options.validateProtocol && !this.supportedProtocols.has(context.protocol)) {
+    throw new ProtocolError(
+      `Unsupported protocol: ${context.protocol}. Supported: ${Array.from(this.supportedProtocols).join(', ')}`,
+      426 // Upgrade Required
+    );
   }
   
+  return context;
+}
+  
   detectProtocol(request) {
-    const forwardedProto = request.headers['x-forwarded-proto'];
-    if (forwardedProto) return forwardedProto;
-    
-    const isSecure = request.connection?.encrypted || 
-                    request.socket?.encrypted ||
-                    (request.headers['x-arr-ssl'] !== undefined);
-    
-    return isSecure ? 'https' : 'http';
+  // Prioritize headers
+  const forwardedProto = request.headers['x-forwarded-proto'];
+  if (forwardedProto) {
+    // Security: Validate against trusted proxies
+    const clientIP = this.extractIP(request);
+    if (this.isTrustedProxy(clientIP)) {
+      return forwardedProto.split(',')[0].trim();
+    }
+  }
+  
+  // Check for ALPN protocol (HTTP/2, HTTP/3)
+  const alpnProtocol = request.socket?.alpnProtocol;
+  if (alpnProtocol) {
+    if (alpnProtocol === 'h2') return 'https';
+    if (alpnProtocol === 'h3') return 'https';
   }
   
+  // Standard detection
+  const isSecure = request.connection?.encrypted ||
+    request.socket?.encrypted ||
+    request.secure ||
+    (request.headers['x-arr-ssl'] !== undefined) ||
+    (request.headers['x-forwarded-ssl'] === 'on');
+  
+  return isSecure ? 'https' : 'http';
+}
+
+isTrustedProxy(ip) {
+  if (this.options.trustedProxies.length === 0) return true;
+  return this.options.trustedProxies.some(proxy =>
+    proxy === ip || this.isIPInCIDR(ip, proxy)
+  );
+}
+  
   normalizeHeaders(headers) {
     const normalized = {};
     for (const [key, value] of Object.entries(headers)) {
@@ -79,42 +133,128 @@ export class ProtocolEngine {
   }
   
   async parseRequestBody(request) {
-    return new Promise((resolve, reject) => {
-      let body = '';
-      request.on('data', chunk => {
-        body += chunk.toString();
+  return new Promise((resolve, reject) => {
+    let body = Buffer.from('');
+    let totalSize = 0;
+    
+    request.on('data', chunk => {
+      totalSize += chunk.length;
+      
+      // Check size limit early
+      if (totalSize > this.parseSizeLimit()) {
+        request.destroy();
+        reject(new ProtocolError(`Request body too large (max: ${this.options.maxBodySize})`, 413));
+        return;
+      }
+      
+      body = Buffer.concat([body, chunk]);
+    });
+    
+    request.on('end', async () => {
+      try {
+        const contentType = request.headers['content-type'] || '';
+        const mimeType = contentType.split(';')[0].trim();
         
-        // Check size limit
-        if (body.length > this.parseSizeLimit()) {
-          request.destroy();
-          reject(new ProtocolError('Request body too large'));
+        // Stream parsing for large files
+        if (totalSize > 1024 * 1024) { // > 1MB
+          resolve(await this.parseLargeBody(body, mimeType));
+          return;
         }
-      });
-      
-      request.on('end', () => {
-        try {
-          const contentType = request.headers['content-type'] || '';
-          
-          if (contentType.includes('application/json')) {
-            resolve(JSON.parse(body));
-          } else if (contentType.includes('application/x-www-form-urlencoded')) {
-            const params = new URLSearchParams(body);
-            const result = {};
-            for (const [key, value] of params) {
+        
+        const bodyString = body.toString('utf-8');
+        
+        // Content-Type specific parsing
+        if (mimeType === 'application/json' && this.options.parseJSON) {
+          if (bodyString.trim() === '') resolve({});
+          else resolve(JSON.parse(bodyString));
+        } 
+        else if (mimeType === 'application/x-www-form-urlencoded' && this.options.parseForm) {
+          const params = new URLSearchParams(bodyString);
+          const result = {};
+          for (const [key, value] of params) {
+            // Handle duplicate keys (array values)
+            if (key in result) {
+              if (Array.isArray(result[key])) {
+                result[key].push(value);
+              } else {
+                result[key] = [result[key], value];
+              }
+            } else {
               result[key] = value;
             }
-            resolve(result);
-          } else {
-            resolve(body);
           }
-        } catch (error) {
-          reject(new ProtocolError(`Failed to parse body: ${error.message}`));
+          resolve(result);
         }
-      });
-      
-      request.on('error', reject);
+        else if (mimeType === 'multipart/form-data') {
+          resolve(await this.parseMultipartFormData(body, contentType));
+        }
+        else if (mimeType === 'text/plain' || mimeType === 'text/html') {
+          resolve(bodyString);
+        }
+        else {
+          // Raw buffer untuk binary data
+          resolve(body);
+        }
+      } catch (error) {
+        reject(new ProtocolError(
+          `Failed to parse body: ${error.message}`,
+          400,
+          { contentType: request.headers['content-type'] }
+        ));
+      }
     });
+    
+    request.on('error', reject);
+  });
+}
+
+parseURL(request) {
+  try {
+    const url = new URL(request.url, `http://${request.headers.host || 'localhost'}`);
+    
+    // Security: Sanitize URL
+    return {
+      href: url.href,
+      origin: url.origin,
+      protocol: url.protocol,
+      hostname: url.hostname,
+      port: url.port,
+      pathname: url.pathname,
+      search: url.search,
+      searchParams: url.searchParams,
+      hash: url.hash,
+      toString: () => url.toString()
+    };
+  } catch (error) {
+    throw new ProtocolError(`Invalid URL: ${request.url}`, 400);
   }
+}
+
+extractClientInfo(request) {
+  return {
+    ip: this.extractIP(request),
+    port: request.socket?.remotePort,
+    family: request.socket?.remoteFamily,
+    tlsVersion: request.socket?.getProtocol?.(),
+    cipher: request.socket?.getCipher?.(),
+    servername: request.socket?.servername, // SNI
+    authenticated: request.socket?.authorized || false,
+    certificate: request.socket?.getPeerCertificate?.() || null
+  };
+}
+
+parseCookies(cookieHeader) {
+  if (!cookieHeader) return {};
+  
+  const cookies = {};
+  cookieHeader.split(';').forEach(cookie => {
+    const [name, ...valueParts] = cookie.trim().split('=');
+    if (name) {
+      cookies[name] = decodeURIComponent(valueParts.join('=') || '');
+    }
+  });
+  return cookies;
+}
   
   parseSizeLimit() {
     const size = this.options.maxBodySize;
@@ -135,10 +275,23 @@ export class ProtocolEngine {
 }
 
 export class ProtocolError extends Error {
-  constructor(message, code = 400) {
+  constructor(message, code = 400, details = {}) {
     super(message);
     this.name = 'ProtocolError';
     this.code = code;
+    this.details = details;
     this.timestamp = new Date();
+    this.stackTrace = process.env.NODE_ENV === 'development' ? this.stack : undefined;
+  }
+  
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      timestamp: this.timestamp.toISOString(),
+      details: this.details,
+      ...(process.env.NODE_ENV === 'development' && { stack: this.stackTrace })
+    };
   }
 }

package/src/keypointJS.js

@@ -1,10 +1,8 @@
-// Import http module once at top level
-let http;
-try {
-  http = await import('http');
-} catch (error) {
-  console.error('Failed to import http module:', error);
-}
+/*
+ KeypointJS Main Module © 2026
+ __________________________________________
+  
+*/
 
 import { Context } from './core/Context.js';
 import { ProtocolEngine, ProtocolError } from './core/ProtocolEngine.js';
@@ -20,6 +18,7 @@ import { PluginManager, BuiltInHooks } from './plugins/PluginManager.js';
 import { RateLimiter } from './plugins/RateLimiter.js';
 import { AuditLogger } from './plugins/AuditLogger.js';
 import { WebSocketGuard } from './plugins/WebSocketGuard.js';
+import { AccessDecision } from './policy/AccessDecision.js';
 
 export class KeypointJS {
   constructor(options = {}) {
@@ -36,6 +35,7 @@ export class KeypointJS {
         'X-Content-Type-Options': 'nosniff'
       },
       errorHandler: this.defaultErrorHandler.bind(this),
+      trustedProxies: [], // TAMBAH: untuk ProtocolEngine
       ...options
     };
     
@@ -48,6 +48,9 @@ export class KeypointJS {
     // Setup built-in policies
     this.setupBuiltInPolicies();
     
+    // Setup built-in plugins
+    this.setupBuiltInPlugins(); // TAMBAH METHOD BARU
+    
     // Event emitter
     this.events = new Map();
     
@@ -62,6 +65,38 @@ export class KeypointJS {
     };
   }
   
+ getProtocolEngine() {
+  return this.protocolEngine;
+ }
+
+ configureProtocolEngine(options) {
+  this.protocolEngine = new ProtocolEngine({
+    ...this.protocolEngine.options,
+    ...options
+  });
+  return this;
+ }
+  
+  setupBuiltInPlugins() {
+    // Register built-in plugins jika di-enable via options
+    if (this.options.enableAuditLog !== false) {
+      const auditLogger = new AuditLogger({
+        logToConsole: this.options.auditToConsole !== false,
+        logToFile: this.options.auditToFile || false,
+        filePath: this.options.auditFilePath || './audit.log'
+      });
+      this.registerPlugin(auditLogger);
+    }
+    
+    if (this.options.enableRateLimiter !== false) {
+      const rateLimiter = new RateLimiter({
+        window: this.options.rateLimitWindow || 60000,
+        max: this.options.rateLimitMax || 100
+      });
+      this.registerPlugin(rateLimiter);
+    }
+  }
+  
   initializeCore() {
     // Core protocol engine
     this.protocolEngine = new ProtocolEngine({
@@ -101,25 +136,45 @@ export class KeypointJS {
 // Layer 1: Protocol Engine
 this.use(async (ctx, next) => {
   try {
+    // Make sure ctx.request is a native Node.js Request object.
+    if (!ctx.request || typeof ctx.request !== 'object') {
+      throw new ProtocolError('Invalid request object', 400);
+    }
+    
     const processed = await this.protocolEngine.process(ctx.request);
     
-    ctx.id = processed.id;
-    ctx.timestamp = processed.timestamp;
-    ctx.metadata = processed.metadata;
+    // Update context dengan data processed
+    Object.assign(ctx, {
+      id: processed.id,
+      timestamp: processed.timestamp,
+      metadata: {
+        ...ctx.metadata,
+        ...processed.metadata
+      }
+    });
     
-    // Update request object
-    if (processed.request) {
-      ctx.request = {
-        ...ctx.request,
-        ...processed.request
-      };
-    }
+    // Update request object - pertahankan original request
+    ctx.request = {
+      ...ctx.request,
+      ...processed.request,
+      originalRequest: ctx.request // Save reference to original
+    };
     
+    // Set protocol and IP
     ctx.setState('_protocol', processed.protocol);
-    ctx.setState('_ip', processed.request?.ip);
+    ctx.setState('_ip', processed.request?.ip || '0.0.0.0');
+    
+    // Set protocol and ip properties in context
+    if (!ctx._protocol) {
+      ctx._protocol = processed.protocol;
+    }
     
   } catch (error) {
-    throw new KeypointError(`Protocol error: ${error.message}`, 400);
+    // Use ProtocolError if available, otherwise KeypointError
+    if (error.name === 'ProtocolError') {
+      throw error;
+    }
+    throw new ProtocolError(`Protocol processing error: ${error.message}`, 400);
   }
   return next(ctx);
 });
@@ -410,32 +465,42 @@ this.use(async (ctx, next) => {
   // Request handling
   
   async handleRequest(request, response) {
-    const ctx = new KeypointContext(request);
-    this.stats.requests++;
+  const ctx = new KeypointContext(request);
+  this.stats.requests++;
+  
+  try {
+    // Run the middleware chain
+    await this.runMiddlewareChain(ctx);
+    this.stats.successful++;
     
-    try {
-      await this.runMiddlewareChain(ctx);
-      this.stats.successful++;
-      
-      this.emit('request:success', {
-        ctx,
-        timestamp: new Date(),
-        duration: ctx.response?.duration || 0
-      });
-      
-      return ctx.response;
-    } catch (error) {
-      this.stats.failed++;
-      
-      this.emit('request:error', {
-        ctx,
-        error,
-        timestamp: new Date()
-      });
-      
-      return this.options.errorHandler(error, ctx, response);
-    }
+    // Emit success event
+    this.emit('request:success', {
+      ctx,
+      timestamp: new Date(),
+      duration: ctx.response?.duration || 0
+    });
+    
+    // Return response
+    return ctx.response || {
+      status: 404,
+      headers: { 'Content-Type': 'application/json' },
+      body: { error: 'Not Found', code: 404 }
+    };
+    
+  } catch (error) {
+    this.stats.failed++;
+    
+    // Emit error event
+    this.emit('request:error', {
+      ctx,
+      error,
+      timestamp: new Date()
+    });
+    
+    // Handle error via error handler
+    return this.options.errorHandler(error, ctx, response);
   }
+}
   
   async runMiddlewareChain(ctx, index = 0) {
     if (index >= this.middlewareChain.length) return;
@@ -446,147 +511,168 @@ this.use(async (ctx, next) => {
     return await middleware(ctx, next);
   }
   
-// HTTP Server integration
+// HTTP Server integration - SINGLE VERSION
 createServer() {
-  if (!http) {
-    throw new Error('HTTP module not available');
-  }
-  
-  const server = http.createServer(async (req, res) => {
-    const response = await this.handleRequest(req, res);
-    
-    res.statusCode = response.status || 200;
-    Object.entries(response.headers || {}).forEach(([key, value]) => {
-      res.setHeader(key, value);
-    });
-    
-    if (response.body !== undefined) {
-      const body = typeof response.body === 'string' ?
-        response.body :
-        JSON.stringify(response.body);
-      res.end(body);
-    } else {
-      res.end();
+  return new Promise(async (resolve, reject) => {
+    try {
+      // Dynamic import http module
+      const http = await import('http');
+      
+      const server = http.createServer(async (req, res) => {
+        try {
+          const response = await this.handleRequest(req, res);
+          
+          // Set response
+          res.statusCode = response.status || 200;
+          
+          // Set headers
+          if (response.headers) {
+            Object.entries(response.headers).forEach(([key, value]) => {
+              if (value !== undefined && value !== null) {
+                res.setHeader(key, value);
+              }
+            });
+          }
+          
+          // Send body
+          if (response.body !== undefined && response.body !== null) {
+            const body = typeof response.body === 'string' ?
+              response.body :
+              JSON.stringify(response.body);
+            res.end(body);
+          } else {
+            res.end();
+          }
+          
+        } catch (error) {
+          console.error('Server error:', error);
+          res.statusCode = 500;
+          res.setHeader('Content-Type', 'application/json');
+          res.end(JSON.stringify({
+            error: 'Internal Server Error',
+            timestamp: new Date().toISOString()
+          }));
+        }
+      });
+      
+      // Setup WebSocket jika ada
+      if (this.wsGuard) {
+        this.wsGuard.attachToServer(server, this);
+      }
+      
+      resolve(server);
+      
+    } catch (error) {
+      reject(new Error(`Failed to create server: ${error.message}`));
     }
   });
-  
-  if (this.wsGuard) {
-    this.wsGuard.attachToServer(server, this);
-  }
-  
-  return server;
 }
 
+// SINGLE listen method
 listen(port, hostname = '0.0.0.0', callback) {
-  const server = this.createServer();
-  
-  server.listen(port, hostname, () => {
-    const address = server.address();
-    console.log(`
- KeypointJS Server Started
-════════════════════════════════════════
- Address: ${hostname}:${port}
- Mode: ${this.options.requireKeypoint ? 'Strict (Keypoint Required)' : 'Permissive'}
- Protocols: HTTP/HTTPS${this.wsGuard ? ' + WebSocket' : ''}
- Plugins: ${this.pluginManager.getPluginNames().length} loaded
- Keypoints: ${this.keypointStorage.store.size} registered
-════════════════════════════════════════
-    `);
-    
-    if (callback) callback(server);
+  return new Promise(async (resolve, reject) => {
+    try {
+      const server = await this.createServer();
+      
+      server.listen(port, hostname, () => {
+        const address = server.address();
+        const actualHost = address.address;
+        const actualPort = address.port;
+        
+        console.log(`
+╔═══════════════════════════════════════════════╗
+║            KeypointJS Server Started          ║
+╠═══════════════════════════════════════════════╣
+║ Address:   ${actualHost}:${actualPort}${' '.repeat(20 - (actualHost.length + actualPort.toString().length))}║
+║ Mode:      ${this.options.requireKeypoint ? 'Strict' : 'Permissive'}${' '.repeat(25 - (this.options.requireKeypoint ? 6 : 9))}║
+║ Protocols: HTTP/HTTPS${this.wsGuard ? ' + WebSocket' : ''}${' '.repeat(25 - (this.wsGuard ? 21 : 10))}║
+║ Plugins:   ${this.pluginManager.getPluginNames().length} loaded${' '.repeat(20 - this.pluginManager.getPluginNames().length.toString().length)}║
+║ Keypoints: ${this.keypointStorage.store.size} registered${' '.repeat(20 - this.keypointStorage.store.size.toString().length)}║
+╚═══════════════════════════════════════════════╝
+        `);
+        
+        // Emit event
+        this.emit('server:started', {
+          host: actualHost,
+          port: actualPort,
+          timestamp: new Date()
+        });
+        
+        if (callback) callback(server);
+        resolve(server);
+      });
+      
+      server.on('error', (error) => {
+        this.emit('server:error', { error, timestamp: new Date() });
+        reject(error);
+      });
+      
+      // Handle graceful shutdown
+      process.on('SIGTERM', () => this.shutdown());
+      process.on('SIGINT', () => this.shutdown());
+      
+    } catch (error) {
+      reject(error);
+    }
   });
-  
-  return server;
 }
 
-async listen(port, hostname = '0.0.0.0', callback) {
-  const server = await this.createServer();
-  
-  server.listen(port, hostname, () => {
-    const address = server.address();
-    console.log(`
- KeypointJS Server Started
-════════════════════════════════════════
- Address: ${hostname}:${port}
- Mode: ${this.options.requireKeypoint ? 'Strict (Keypoint Required)' : 'Permissive'}
- Protocols: HTTP/HTTPS${this.wsGuard ? ' + WebSocket' : ''}
- Plugins: ${this.pluginManager.getPluginNames().length} loaded
- Keypoints: ${this.keypointStorage.store.size} registered
-════════════════════════════════════════
-    `);
-    
-    if (callback) callback(server);
-  });
-  
-  return server;
-}
-  
-  listen(port, hostname = '0.0.0.0', callback) {
-    const server = this.createServer();
-    
-    server.listen(port, hostname, () => {
-      const address = server.address();
-      console.log(`
- KeypointJS Server Started
-════════════════════════════════════════
- Address: ${hostname}:${port}
- Mode: ${this.options.requireKeypoint ? 'Strict (Keypoint Required)' : 'Permissive'}
- Protocols: HTTP/HTTPS${this.wsGuard ? ' + WebSocket' : ''}
- Plugins: ${this.pluginManager.getPluginNames().length} loaded
- Keypoints: ${this.keypointStorage.store.size} registered
-════════════════════════════════════════
-      `);
-      
-      if (callback) callback(server);
-    });
-    
-    return server;
-  }
   
   // Error handling
-  
   defaultErrorHandler(error, ctx, response) {
-    const status = error.code || 500;
-    const message = error.message || 'Internal Server Error';
-    
-    if (this.options.strictMode) {
-      // Hide internal error details in production
-      const safeMessage = status >= 500 && process.env.NODE_ENV === 'production'
-        ? 'Internal Server Error'
-        : message;
-      
-      return {
-        status,
-        headers: {
-          'Content-Type': 'application/json',
-          ...this.options.defaultResponseHeaders
-        },
-        body: {
-          error: safeMessage,
-          code: status,
-          timestamp: new Date().toISOString(),
-          requestId: ctx?.id
-        }
-      };
+  // Determine status code
+  let status = error.code || 500;
+  let message = error.message || 'Internal Server Error';
+  let exposeDetails = false;
+  
+  // Classify errors
+  if (error.name === 'ProtocolError' || error.name === 'KeypointError' ||
+    error.name === 'PolicyError' || error.name === 'ValidationError') {
+    exposeDetails = this.options.strictMode ? false : true;
+  } else if (status < 500) {
+    exposeDetails = true; // 4xx errors
+  }
+  
+  // Prepare response
+  const errorResponse = {
+    status,
+    headers: {
+      'Content-Type': 'application/json',
+      ...this.options.defaultResponseHeaders
+    },
+    body: {
+      error: exposeDetails ? message : (status >= 500 ? 'Internal Server Error' : message),
+      code: status,
+      timestamp: new Date().toISOString(),
+      requestId: ctx?.id
     }
+  };
+  
+  // Add details if allowed
+  if (exposeDetails) {
+    if (error.details) errorResponse.body.details = error.details;
+    if (error.decision) errorResponse.body.decision = error.decision;
+    if (error.errors) errorResponse.body.errors = error.errors;
     
-    return {
-      status,
-      headers: {
-        'Content-Type': 'application/json',
-        ...this.options.defaultResponseHeaders
-      },
-      body: {
-        error: message,
-        code: status,
-        timestamp: new Date().toISOString(),
-        requestId: ctx?.id,
-        details: error.details || {},
-        stack: process.env.NODE_ENV === 'development' ? error.stack : undefined
-      }
-    };
+    // Stack trace in development
+    if (process.env.NODE_ENV === 'development' && error.stack) {
+      errorResponse.body.stack = error.stack.split('\n').slice(0, 5).join('\n');
+    }
+  }
+  
+  // Log error
+  if (status >= 500) {
+    console.error(`Server Error [${status}]:`, {
+      message: error.message,
+      stack: error.stack,
+      requestId: ctx?.id,
+      path: ctx?.path
+    });
   }
   
+  return errorResponse;
+}
+  
   // Event system
   
   on(event, handler) {

package/src/plugins/transformer/TransformerPlugin.js

@@ -0,0 +1,82 @@
+// Copyright AnasBex - 2026 TransformersPlugin.js
+/*
+
+API response standardization
+
+Inject metadata (requestId, timestamp, duration)
+
+Optional envelope (success, data, error)
+
+*/
+
+export class TransformerPlugin {
+  constructor(options = {}) {
+    this.options = {
+      envelope: true,
+      addRequestId: true,
+      addTimestamp: true,
+      addDuration: true,
+      ...options
+    };
+  }
+
+  async process(ctx, next) {
+    const start = Date.now();
+
+    const response = await next(ctx);
+
+    // If handler returns null / undefined
+    if (!response) return response;
+
+    // If the response is not a KeypointJS API object
+    if (typeof response !== 'object' || !response.body) {
+      return response;
+    }
+
+    const duration = Date.now() - start;
+
+    // Error response
+    if (response.status >= 400) {
+      return {
+        ...response,
+        body: this.options.envelope
+          ? {
+              success: false,
+              error: response.body,
+              meta: this._meta(ctx, duration)
+            }
+          : response.body
+      };
+    }
+
+    // Success response
+    return {
+      ...response,
+      body: this.options.envelope
+        ? {
+            success: true,
+            data: response.body,
+            meta: this._meta(ctx, duration)
+          }
+        : response.body
+    };
+  }
+
+  _meta(ctx, duration) {
+    const meta = {};
+
+    if (this.options.addRequestId) {
+      meta.requestId = ctx.id;
+    }
+
+    if (this.options.addTimestamp) {
+      meta.timestamp = new Date().toISOString();
+    }
+
+    if (this.options.addDuration) {
+      meta.durationMs = duration;
+    }
+
+    return meta;
+  }
+}