keypointjs 1.0.0

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "keypointjs",
+  "version": "1.0.0",
+  "description": "KeypointJS Identity-First API Framework with Mandatory Authentication",
+  "main": "src/keypointJS.js",
+  "type": "module",
+  "exports": {
+    ".": "./src/keypointJS.js",
+    "./keypoint": "./src/keypoint/Keypoint.js",
+    "./keypoint/context": "./src/keypoint/KeypointContext.js",
+    "./keypoint/storage": "./src/keypoint/KeypointStorage.js",
+    "./keypoint/validator": "./src/keypoint/KeypointValidator.js",
+    "./keypoint/scopes": "./src/keypoint/ScopeManager.js",
+    "./plugins": "./src/plugins/PluginManager.js",
+    "./plugins/audit": "./src/plugins/AuditLogger.js",
+    "./plugins/ratelimit": "./src/plugins/RateLimiter.js",
+    "./plugins/websocket": "./src/plugins/WebSocketGuard.js",
+    "./policy": "./src/policy/PolicyEngine.js",
+    "./policy/rules": "./src/policy/PolicyRule.js",
+    "./policy/decision": "./src/policy/AccessDecision.js",
+    "./router": "./src/router/MinimalRouter.js",
+    "./core": "./src/core/Context.js",
+    "./core/protocol": "./src/core/ProtocolEngine.js"
+  },
+  "scripts": {
+    "test": "node --test test/basic.test.js",
+    "test:all": "node --test test/*.test.js",
+    "test:integration": "node --test test/integration.test.js",
+    "test:performance": "node test/performance.test.js",
+    "test:coverage": "NODE_V8_COVERAGE=coverage node --test test/basic.test.js",
+    "start": "node examples/server.js",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "authentication",
+    "authorization",
+    "api",
+    "security",
+    "middleware",
+    "keypoint",
+    "nodejs",
+    "websocket",
+    "rate-limiting",
+    "audit-logging"
+  ],
+  "author": "AnasBex",
+  "website": "https://anasbex.vercel.app",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anasbex-dev/keypointjs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/anasbex-dev/keypointjs/issues"
+  },
+  "homepage": "https://github.com/anasbex-dev/keypointjs#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "ws": "^8.14.2"
+  },
+  "optionalDependencies": {
+    "bufferutil": "^4.0.8",
+    "utf-8-validate": "^6.0.3"
+  }
+}

package/src/core/Context.js

@@ -0,0 +1,104 @@
+export class Context {
+  constructor(request) {
+    this.request = request;
+    this.response = {
+      status: 200,
+      headers: {},
+      body: null
+    };
+    this.state = {};
+    this.keypoint = null;
+    this.policyDecision = null;
+    this.pluginData = new Map();
+  }
+  
+  // Response helpers
+  json(data, status = 200) {
+    this.response.status = status;
+    this.response.body = data;
+    this.response.headers['content-type'] = 'application/json';
+    return this;
+  }
+  
+  text(data, status = 200) {
+    this.response.status = status;
+    this.response.body = data;
+    this.response.headers['content-type'] = 'text/plain';
+    return this;
+  }
+  
+  html(data, status = 200) {
+    this.response.status = status;
+    this.response.body = data;
+    this.response.headers['content-type'] = 'text/html';
+    return this;
+  }
+  
+  setHeader(key, value) {
+    this.response.headers[key.toLowerCase()] = value;
+    return this;
+  }
+  
+  getHeader(key) {
+    return this.request.headers[key.toLowerCase()];
+  }
+  
+  status(code) {
+    this.response.status = code;
+    return this;
+  }
+  
+  // Query and param helpers
+  getQuery(key) {
+    return this.request.url.searchParams.get(key);
+  }
+  
+  getAllQuery() {
+    const result = {};
+    for (const [key, value] of this.request.url.searchParams) {
+      result[key] = value;
+    }
+    return result;
+  }
+  
+  // Body accessor
+  get body() {
+    return this.request.body;
+  }
+  
+  // Protocol info
+  get protocol() {
+    return this.request.protocol;
+  }
+  
+  get ip() {
+    return this.request.ip;
+  }
+  
+  get method() {
+    return this.request.method;
+  }
+  
+  get path() {
+    return this.request.url.pathname;
+  }
+  
+  // State management
+  setState(key, value) {
+    this.state[key] = value;
+    return this;
+  }
+  
+  getState(key) {
+    return this.state[key];
+  }
+  
+  // Plugin data
+  setPluginData(pluginName, data) {
+    this.pluginData.set(pluginName, data);
+  }
+  
+  getPluginData(pluginName) {
+    return this.pluginData.get(pluginName);
+  }
+}

package/src/core/ProtocolEngine.js

@@ -0,0 +1,144 @@
+import crypto from 'crypto';
+
+export class ProtocolEngine {
+  constructor(options = {}) {
+    this.options = {
+      maxBodySize: '1mb',
+      parseJSON: true,
+      parseForm: true,
+      ...options
+    };
+    
+    this.supportedProtocols = new Set(['https', 'wss', 'http']);
+  }
+  
+  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}`);
+    }
+    
+    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';
+  }
+  
+  normalizeHeaders(headers) {
+    const normalized = {};
+    for (const [key, value] of Object.entries(headers)) {
+      normalized[key.toLowerCase()] = value;
+    }
+    return normalized;
+  }
+  
+  extractIP(request) {
+    return request.headers['x-forwarded-for']?.split(',')[0].trim() ||
+           request.headers['x-real-ip'] ||
+           request.connection?.remoteAddress ||
+           request.socket?.remoteAddress ||
+           request.connection?.socket?.remoteAddress ||
+           '0.0.0.0';
+  }
+  
+  shouldParseBody(request) {
+    const method = request.method.toUpperCase();
+    if (!['POST', 'PUT', 'PATCH'].includes(method)) return false;
+    
+    const contentType = request.headers['content-type'] || '';
+    return contentType.includes('application/json') || 
+           contentType.includes('application/x-www-form-urlencoded');
+  }
+  
+  async parseRequestBody(request) {
+    return new Promise((resolve, reject) => {
+      let body = '';
+      request.on('data', chunk => {
+        body += chunk.toString();
+        
+        // Check size limit
+        if (body.length > this.parseSizeLimit()) {
+          request.destroy();
+          reject(new ProtocolError('Request body too large'));
+        }
+      });
+      
+      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) {
+              result[key] = value;
+            }
+            resolve(result);
+          } else {
+            resolve(body);
+          }
+        } catch (error) {
+          reject(new ProtocolError(`Failed to parse body: ${error.message}`));
+        }
+      });
+      
+      request.on('error', reject);
+    });
+  }
+  
+  parseSizeLimit() {
+    const size = this.options.maxBodySize;
+    if (typeof size === 'number') return size;
+    
+    const match = size.match(/^(\d+)(mb|kb|b)$/i);
+    if (!match) return 1024 * 1024; // 1MB default
+    
+    const [, num, unit] = match;
+    const multiplier = {
+      'b': 1,
+      'kb': 1024,
+      'mb': 1024 * 1024
+    }[unit.toLowerCase()];
+    
+    return parseInt(num) * multiplier;
+  }
+}
+
+export class ProtocolError extends Error {
+  constructor(message, code = 400) {
+    super(message);
+    this.name = 'ProtocolError';
+    this.code = code;
+    this.timestamp = new Date();
+  }
+}

package/src/keypoint/Keypoint.js

@@ -0,0 +1,36 @@
+export class Keypoint {
+  constructor(data) {
+    this.keyId = data.keyId;
+    this.secret = data.secret;
+    this.name = data.name || '';
+    this.scopes = data.scopes || [];
+    this.protocols = data.protocols || ['https'];
+    this.allowedOrigins = data.allowedOrigins || [];
+    this.allowedIps = data.allowedIps || [];
+    this.rateLimit = data.rateLimit || {
+      requests: 100,
+      window: 60 // seconds
+    };
+    this.expiresAt = data.expiresAt || null;
+    this.createdAt = data.createdAt || new Date();
+    this.metadata = data.metadata || {};
+  }
+  
+  hasScope(requiredScope) {
+    return this.scopes.includes('*') || this.scopes.includes(requiredScope);
+  }
+  
+  isExpired() {
+    return this.expiresAt && new Date() > this.expiresAt;
+  }
+  
+  validateOrigin(origin) {
+    if (this.allowedOrigins.length === 0) return true;
+    return this.allowedOrigins.includes('*') || 
+           this.allowedOrigins.includes(origin);
+  }
+  
+  validateProtocol(protocol) {
+    return this.protocols.includes(protocol);
+  }
+}

package/src/keypoint/KeypointContext.js

@@ -0,0 +1,88 @@
+import { Context } from '../core/Context.js';
+
+export class KeypointContext extends Context {
+  constructor(request) {
+    super(request);
+    this.keypoint = null;
+    this.scopes = [];
+    this.rateLimit = null;
+    this.accessLog = [];
+  }
+  
+  // Keypoint-specific methods
+  hasScope(scope) {
+    if (!this.keypoint) return false;
+    return this.keypoint.hasScope(scope);
+  }
+  
+  hasAnyScope(scopes) {
+    if (!this.keypoint) return false;
+    return scopes.some(scope => this.keypoint.hasScope(scope));
+  }
+  
+  hasAllScopes(scopes) {
+    if (!this.keypoint) return false;
+    return scopes.every(scope => this.keypoint.hasScope(scope));
+  }
+  
+  getKeypointId() {
+    return this.keypoint?.keyId;
+  }
+  
+  getKeypointMetadata() {
+    return this.keypoint?.metadata || {};
+  }
+  
+  // Rate limit info
+  getRateLimitInfo() {
+    if (!this.keypoint) return null;
+    
+    return {
+      limit: this.keypoint.rateLimit.requests,
+      window: this.keypoint.rateLimit.window,
+      remaining: this.rateLimit?.remaining || this.keypoint.rateLimit.requests
+    };
+  }
+  
+  // Audit logging
+  logAccess(action, details = {}) {
+    this.accessLog.push({
+      timestamp: new Date(),
+      action,
+      keypointId: this.getKeypointId(),
+      ip: this.ip,
+      method: this.method,
+      path: this.path,
+      ...details
+    });
+  }
+  
+  // Security validation
+  validateOrigin() {
+    if (!this.keypoint) return false;
+    
+    const origin = this.getHeader('origin') || this.getHeader('referer');
+    if (!origin) return true; // No origin to validate
+    
+    return this.keypoint.validateOrigin(origin);
+  }
+  
+  validateProtocol() {
+    if (!this.keypoint) return false;
+    return this.keypoint.validateProtocol(this.protocol);
+  }
+  
+  // Convenience getters
+  get isAuthenticated() {
+    return !!this.keypoint;
+  }
+  
+  get isExpired() {
+    return this.keypoint?.isExpired() || false;
+  }
+  
+  get allowedMethods() {
+    const policy = this.keypoint?.metadata?.allowedMethods;
+    return policy || ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];
+  }
+}

package/src/keypoint/KeypointStorage.js

@@ -0,0 +1,236 @@
+export class KeypointStorage {
+  constructor(driver = 'memory') {
+    this.driver = driver;
+    this.store = new Map();
+    this.indexes = {
+      bySecret: new Map(),
+      byName: new Map(),
+      byScope: new Map()
+    };
+  }
+  
+  async set(keypoint) {
+    if (!keypoint.keyId) {
+      throw new Error('Keypoint must have keyId');
+    }
+    
+    this.store.set(keypoint.keyId, keypoint);
+    
+    // Update indexes
+    if (keypoint.secret) {
+      this.indexes.bySecret.set(keypoint.secret, keypoint.keyId);
+    }
+    
+    if (keypoint.name) {
+      if (!this.indexes.byName.has(keypoint.name)) {
+        this.indexes.byName.set(keypoint.name, new Set());
+      }
+      this.indexes.byName.get(keypoint.name).add(keypoint.keyId);
+    }
+    
+    // Index by scopes
+    for (const scope of keypoint.scopes) {
+      if (!this.indexes.byScope.has(scope)) {
+        this.indexes.byScope.set(scope, new Set());
+      }
+      this.indexes.byScope.get(scope).add(keypoint.keyId);
+    }
+    
+    return true;
+  }
+  
+  async get(keyId) {
+    return this.store.get(keyId) || null;
+  }
+  
+  async getBySecret(secret) {
+    const keyId = this.indexes.bySecret.get(secret);
+    return keyId ? await this.get(keyId) : null;
+  }
+  
+  async getByName(name) {
+    const keyIds = this.indexes.byName.get(name);
+    if (!keyIds) return [];
+    
+    const results = [];
+    for (const keyId of keyIds) {
+      const keypoint = await this.get(keyId);
+      if (keypoint) results.push(keypoint);
+    }
+    return results;
+  }
+  
+  async getByScope(scope) {
+    const keyIds = this.indexes.byScope.get(scope);
+    if (!keyIds) return [];
+    
+    const results = [];
+    for (const keyId of keyIds) {
+      const keypoint = await this.get(keyId);
+      if (keypoint) results.push(keypoint);
+    }
+    return results;
+  }
+  
+  async update(keyId, updates) {
+    const existing = await this.get(keyId);
+    if (!existing) return false;
+    
+    // Remove old indexes
+    await this.removeIndexes(existing);
+    
+    // Apply updates
+    const updated = {
+      ...existing,
+      ...updates,
+      updatedAt: new Date()
+    };
+    
+    // Save updated keypoint
+    await this.set(updated);
+    return true;
+  }
+  
+  async delete(keyId) {
+    const keypoint = await this.get(keyId);
+    if (!keypoint) return false;
+    
+    // Remove indexes
+    await this.removeIndexes(keypoint);
+    
+    // Remove from store
+    return this.store.delete(keyId);
+  }
+  
+  async removeIndexes(keypoint) {
+    // Remove from secret index
+    if (keypoint.secret) {
+      this.indexes.bySecret.delete(keypoint.secret);
+    }
+    
+    // Remove from name index
+    if (keypoint.name) {
+      const nameSet = this.indexes.byName.get(keypoint.name);
+      if (nameSet) {
+        nameSet.delete(keypoint.keyId);
+        if (nameSet.size === 0) {
+          this.indexes.byName.delete(keypoint.name);
+        }
+      }
+    }
+    
+    // Remove from scope indexes
+    for (const scope of keypoint.scopes) {
+      const scopeSet = this.indexes.byScope.get(scope);
+      if (scopeSet) {
+        scopeSet.delete(keypoint.keyId);
+        if (scopeSet.size === 0) {
+          this.indexes.byScope.delete(scope);
+        }
+      }
+    }
+  }
+  
+  async list(filter = {}) {
+    const results = [];
+    
+    for (const keypoint of this.store.values()) {
+      let match = true;
+      
+      // Apply filters
+      if (filter.scope && !keypoint.hasScope(filter.scope)) {
+        match = false;
+      }
+      
+      if (filter.protocol && !keypoint.protocols.includes(filter.protocol)) {
+        match = false;
+      }
+      
+      if (filter.expired !== undefined) {
+        const isExpired = keypoint.isExpired();
+        if (filter.expired !== isExpired) {
+          match = false;
+        }
+      }
+      
+      if (filter.name && keypoint.name !== filter.name) {
+        match = false;
+      }
+      
+      if (match) {
+        results.push(keypoint);
+      }
+    }
+    
+    return results;
+  }
+  
+  async count() {
+    return this.store.size;
+  }
+  
+  async cleanupExpired() {
+    const expired = [];
+    
+    for (const [keyId, keypoint] of this.store) {
+      if (keypoint.isExpired()) {
+        expired.push(keyId);
+      }
+    }
+    
+    for (const keyId of expired) {
+      await this.delete(keyId);
+    }
+    
+    return expired.length;
+  }
+}
+
+// Memory storage implementation (default)
+export class MemoryKeypointStorage extends KeypointStorage {
+  constructor() {
+    super('memory');
+  }
+}
+
+// File storage implementation
+export class FileKeypointStorage extends KeypointStorage {
+  constructor(filePath) {
+    super('file');
+    this.filePath = filePath;
+    this.loadFromFile();
+  }
+  
+  async loadFromFile() {
+    try {
+      const fs = await import('fs/promises');
+      const data = await fs.readFile(this.filePath, 'utf-8');
+      const parsed = JSON.parse(data);
+      
+      for (const item of parsed) {
+        await this.set(item);
+      }
+    } catch (error) {
+      // File doesn't exist or is empty
+      await this.saveToFile();
+    }
+  }
+  
+  async saveToFile() {
+    const fs = await import('fs/promises');
+    const data = Array.from(this.store.values());
+    await fs.writeFile(this.filePath, JSON.stringify(data, null, 2));
+  }
+  
+  async set(keypoint) {
+    await super.set(keypoint);
+    await this.saveToFile();
+    return true;
+  }
+  
+  async delete(keyId) {
+    const result = await super.delete(keyId);
+    if (result) await this.saveToFile();
+    return result;
+  }
+}