📊 Node.js Votifier

A comprehensive Node.js implementation of the Minecraft Votifier protocol with full support for both v1 (RSA) and v2 (HMAC-SHA256) protocols. Features robust RSA key format support and full compatibility with Java-based Votifier servers like VotifierPlus.

✨ Features

• 🚀 Complete Protocol Support: Both Votifier v1 and v2 implementations
• 🔐 Robust RSA Key Parsing: Supports SPKI, PKCS#1, base64, XML, and hex formats
• 🤝 Java Server Compatible: Tested with VotifierPlus and other Java implementations
• 🌐 Web Testing Interface: Beautiful dark-themed web UI for testing votes
• 📦 Zero Dependencies: Pure Node.js implementation (web tester uses Express)
• 🧪 Comprehensive Tests: Full test suite with real-world scenarios
• 📚 Rich Documentation: Complete examples and API documentation

🚀 Quick Start

Installation

git clone https://github.com/yourusername/nodejs-votifier.git
cd nodejs-votifier

Basic Usage

const { newV1Client, newV2Client, newVote } = require('./nodejs-votifier');

// Create a vote
const vote = newVote('MyService', 'PlayerName', '127.0.0.1');

// V1 Client (RSA)
const v1Client = newV1Client('localhost:8192', publicKey);
await v1Client.sendVote(vote);

// V2 Client (HMAC-SHA256)  
const v2Client = newV2Client('localhost:8192', 'secret-token');
await v2Client.sendVote(vote);

📁 Project Structure

nodejs-votifier/
├── lib/                 # Core library
│   ├── index.js        # Main exports
│   ├── vote.js         # Vote class
│   ├── protocol-v1.js  # V1 protocol implementation
│   ├── protocol-v2.js  # V2 protocol implementation
│   ├── v1-client.js    # V1 client
│   ├── v2-client.js    # V2 client
│   ├── server.js       # Votifier server
│   └── utils.js        # Utility functions
├── examples/           # Usage examples
├── test/              # Test suite
└── README.md

votifier-web-tester/   # Web testing interface
├── server.js          # Express.js backend
├── public/           # Frontend assets
└── package.json

🎯 Examples

Running Examples

# Start example server
npm run example-server

# Test V1 client
npm run example-client-v1

# Test V2 client  
npm run example-client-v2

V1 Protocol Example

const { newV1Client, newVote } = require('./lib');

const publicKey = `-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
-----END PUBLIC KEY-----`;

const client = newV1Client('localhost:8192', publicKey);
const vote = newVote('WebTester', 'TestUser', '127.0.0.1');

try {
    await client.sendVote(vote);
    console.log('✅ Vote sent successfully!');
} catch (error) {
    console.error('❌ Vote failed:', error.message);
}

V2 Protocol Example

const { newV2Client, newVote } = require('./lib');

const client = newV2Client('localhost:8192', 'your-secret-token');
const vote = newVote('WebTester', 'TestUser', '127.0.0.1');

try {
    await client.sendVote(vote);
    console.log('✅ Vote sent successfully!');
} catch (error) {
    console.error('❌ Vote failed:', error.message);
}

🌐 Web Testing Interface

Launch the beautiful web testing interface:

cd votifier-web-tester
npm install
npm start

Visit http://localhost:3000 to access the testing interface with:

• 🎨 Modern Dark Theme: Beautiful, responsive design
• 🔄 Protocol Switching: Easy V1/V2 protocol selection
• 📝 Smart Forms: Auto-validation and error handling
• ⚡ Real-time Testing: Instant feedback and results
• 🔧 RSA Key Generation: Built-in key pair generator

🧪 Testing

Run the comprehensive test suite:

npm test

🔧 RSA Key Format Support

This library automatically detects and supports multiple RSA key formats:

• SPKI: Standard -----BEGIN PUBLIC KEY----- format
• PKCS#1: -----BEGIN RSA PUBLIC KEY----- format
• Base64: Raw base64 encoded keys
• XML: <RSAKeyValue> XML format
• Hex: Hexadecimal encoded keys

🤝 Java Server Compatibility

Fully tested and compatible with:

• ✅ VotifierPlus (Bukkit/Spigot/Paper)
• ✅ Votifier (Original Bukkit plugin)
• ✅ NuVotifier (BungeeCord)
• ✅ Custom Java implementations

📚 API Reference

Vote Class

const vote = newVote(serviceName, username, address, timestamp);
// Creates a new vote instance

V1Client

const client = newV1Client(address, publicKey);
await client.sendVote(vote);

V2Client

const client = newV2Client(address, token);
await client.sendVote(vote);

Server

const server = newVotifierServer(port, privateKey, tokens);
server.listen();

🚨 Troubleshooting

Common Issues

RSA Key Format Error

Error: Failed to parse RSA public key

• Solution: Use the robust key parsing - supports multiple formats automatically

V2 Connection Closed

Error: Connection closed before receiving response

• Solution: This may be normal - some servers close connection after successful vote

V2 Signature Invalid

Error: signature invalid  

• Solution: Verify your token matches the server configuration exactly

🤔 Why This Library?

• 🏗️ Production Ready: Thoroughly tested with real Minecraft servers
• 🔄 Protocol Complete: Full v1 and v2 support with all features
• 🛠️ Developer Friendly: Rich examples, documentation, and error handling
• 🎯 Java Compatible: Works seamlessly with existing Java servers
• 🚀 Modern Node.js: Clean async/await API with Promise support

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Credits

Ported from the excellent go-votifier library. Special thanks to the original authors and the Minecraft community for their contributions to the Votifier protocol.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

Made with ❤️ for the Minecraft community