minenepal-votifier 0.0.1

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Biraj Rai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# MineNepal Votifier
+
+# MineNepal Votifier
+
+Lightweight Votifier v2 client helper used by MineNepal to send signed vote messages to a Votifier v2 server.
+
+## Installation
+
+Install from npm:
+
+```bash
+npm install --save minenepal-votifier
+```
+
+## Usage
+
+The module exports a function `vote(options, cb)` and also supports a Promise-based call when the callback is omitted.
+
+Example (callback):
+
+```js
+const vote = require('minenepal-votifier');
+
+const options = {
+    host: '127.0.0.1',
+    port: 8192,
+    token: 'MYTOKEN',
+    vote: {
+        username: 'Herobrine',
+        address: '127.0.0.1',
+        timestamp: Date.now(),
+        serviceName: 'MineNepal',
+    },
+};
+
+vote(options, err => {
+    if (err) return console.error('Vote failed:', err);
+    console.log('Vote delivered');
+});
+```
+
+Example (Promise):
+
+```js
+const vote = require('minenepal-votifier');
+
+(async () => {
+    try {
+        await vote(options);
+        console.log('Vote delivered');
+    } catch (err) {
+        console.error('Vote failed:', err);
+    }
+})();
+```
+
+## Options
+
+- `host` (string) - Votifier server host
+- `port` (number) - Votifier server port
+- `token` (string) - Shared secret/token for HMAC signing
+- `vote` (object) - Vote payload containing `username`, `address`, `timestamp`, `serviceName`
+- `timeout` (number, optional) - Socket timeout in milliseconds (default 2000)
+
+## Behavior & Errors
+
+- Throws or rejects on invalid arguments.
+- Calls back with an Error or resolves the Promise on failure.
+- Returns successfully (callback with null / resolved Promise) when the server accepts the vote.
+
+## Example file
+
+See `example.js` for a concrete runnable example.
+
+## License
+
+MIT
+
+## Server frameworks
+
+These short examples show how to use the package from server-side code. Never call this from browser/client code — the `token` is a secret and must stay on the server.
+
+### Express (route example)
+
+```js
+const express = require('express');
+const vote = require('minenepal-votifier');
+
+const app = express();
+app.use(express.json());
+
+app.post('/api/vote', async (req, res) => {
+    const { username, address } = req.body;
+    const options = {
+        host: process.env.VOTIFIER_HOST,
+        port: Number(process.env.VOTIFIER_PORT),
+        token: process.env.VOTIFIER_TOKEN,
+        vote: {
+            username,
+            address,
+            timestamp: Date.now(),
+            serviceName: process.env.SERVICE_NAME || 'MineNepal',
+        },
+    };
+
+    try {
+        await vote(options);
+        res.status(200).json({ ok: true });
+    } catch (err) {
+        res.status(502).json({ error: err.message });
+    }
+});
+
+app.listen(3000);
+```
+
+### Next.js (API Route)
+
+For Next.js pages/api route (Next 12/13):
+
+```js
+// pages/api/vote.js
+import vote from 'minenepal-votifier';
+
+export default async function handler(req, res) {
+    if (req.method !== 'POST') return res.status(405).end();
+    const { username, address } = req.body;
+
+    const options = {
+        host: process.env.VOTIFIER_HOST,
+        port: Number(process.env.VOTIFIER_PORT),
+        token: process.env.VOTIFIER_TOKEN,
+        vote: { username, address, timestamp: Date.now(), serviceName: process.env.SERVICE_NAME },
+    };
+
+    try {
+        await vote(options);
+        res.status(200).json({ ok: true });
+    } catch (err) {
+        res.status(502).json({ error: err.message });
+    }
+}
+```
+
+If you're using the App Router or server components, the same server-side logic applies — ensure the code runs only on the server and environment variables are configured.
+
+### Security & Deployment notes
+
+- Keep `VOTIFIER_TOKEN` in server-side environment variables or a secrets manager.
+- Do not log the token or full signed payload in production.
+- Consider running your Votifier connection from a backend worker or queue if you expect high volume, to avoid delaying HTTP responses.

package/index.js

@@ -0,0 +1,107 @@
+'use strict';
+
+const crypto = require('crypto');
+const net = require('net');
+
+function createMessage(header, vote, options) {
+    const data = header.trim().split(/\s+/);
+
+    if (data.length < 3) {
+        throw new Error('Not a Votifier v2 protocol server');
+    }
+
+    // data[2] is the challenge token (may include newline)
+    vote.challenge = data[2].replace(/\r?\n$/, '');
+    const voteAsJson = JSON.stringify(vote);
+    const digest = crypto.createHmac('sha256', options.token);
+    digest.update(voteAsJson);
+    const sig = digest.digest('base64');
+
+    const message = JSON.stringify({ payload: voteAsJson, signature: sig });
+    const messageLength = Buffer.byteLength(message, 'utf8');
+    const messageBuffer = Buffer.alloc(4 + messageLength);
+    messageBuffer.writeUInt16BE(0x733a, 0);
+    messageBuffer.writeUInt16BE(messageLength, 2);
+    messageBuffer.write(message, 4, 'utf8');
+    return messageBuffer;
+}
+
+function _vote(options, cb) {
+    if (!options || typeof options !== 'object') return cb(new Error('options must be an object'));
+    if (!options.host || !options.port || !options.token || !options.vote) {
+        return cb(new Error("missing host, port, token, or vote in 'options'"));
+    }
+
+    const vote = options.vote;
+    if (!vote.username || !vote.address || !vote.timestamp || !vote.serviceName) {
+        return cb(new Error("missing username, address, timestamp, or serviceName in 'vote'"));
+    }
+
+    const timeoutMs = typeof options.timeout === 'number' ? options.timeout : 2000;
+
+    const socket = net.createConnection({ port: options.port, host: options.host });
+    let finished = false;
+
+    function done(err) {
+        if (finished) return;
+        finished = true;
+        try {
+            socket.setTimeout(0);
+        } catch (e) {}
+        try {
+            socket.removeAllListeners();
+        } catch (e) {}
+        try {
+            socket.end();
+        } catch (e) {}
+        cb(err || null);
+    }
+
+    socket.setTimeout(timeoutMs, function () {
+        done(new Error('Socket timeout'));
+    });
+
+    socket.on('error', function (err) {
+        done(new Error('Socket error: ' + (err && err.message ? err.message : err)));
+    });
+
+    socket.once('data', function (buf) {
+        try {
+            const message = createMessage(buf.toString('utf8'), vote, options);
+            socket.write(message);
+        } catch (e) {
+            return done(e);
+        }
+
+        socket.once('data', function (respBuf) {
+            try {
+                const respText = respBuf.toString('utf8');
+                const resp = JSON.parse(respText);
+                if (resp && resp.status === 'error') {
+                    const cause = resp.cause || 'error';
+                    const msg = resp.errorMessage || resp.message || 'unknown';
+                    return done(new Error(cause + ': ' + msg));
+                }
+                return done(null);
+            } catch (e) {
+                return done(e);
+            }
+        });
+    });
+
+    socket.on('end', function () {
+        if (!finished) done(new Error('Socket ended unexpectedly'));
+    });
+}
+
+module.exports = function vote(options, cb) {
+    if (typeof cb !== 'function') {
+        return new Promise(function (resolve, reject) {
+            _vote(options, function (err) {
+                if (err) return reject(err);
+                resolve();
+            });
+        });
+    }
+    return _vote(options, cb);
+};

package/package.json

@@ -0,0 +1,26 @@
+{
+    "name": "minenepal-votifier",
+    "version": "0.0.1",
+    "description": "A Votifier protocol v2 client for MineNepal",
+    "main": "index.js",
+    "scripts": {
+        "test": "node test/vote.test.js",
+        "pretest": "node -e \"console.log('Running tests...')\""
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/birajrai/minenepal-votifier.git"
+    },
+    "keywords": [
+        "votifier",
+        "minecraft",
+        "votifier-v2"
+    ],
+    "author": "birajrai",
+    "license": "MIT",
+    "bugs": {
+        "url": "https://github.com/birajrai/minenepal-votifier/issues"
+    },
+    "homepage": "https://github.com/birajrai/minenepal-votifier",
+    "dependencies": {}
+}

package/test/vote.test.js

@@ -0,0 +1,142 @@
+const assert = require('assert');
+const net = require('net');
+const crypto = require('crypto');
+const vote = require('../index');
+
+function timeout(ms) {
+    return new Promise(r => setTimeout(r, ms));
+}
+
+async function testSendSignedVote() {
+    const server = net.createServer();
+    await new Promise(res => server.listen(0, '127.0.0.1', res));
+    const port = server.address().port;
+    const token = 'MYTOKEN';
+
+    server.on('connection', socket => {
+        socket.write('VOTIFIER 2 challenge\n');
+        let buf = Buffer.alloc(0);
+        socket.on('data', data => {
+            buf = Buffer.concat([buf, data]);
+            if (buf.length >= 4) {
+                const magic = buf.readUInt16BE(0);
+                assert.strictEqual(magic, 0x733a);
+                const len = buf.readUInt16BE(2);
+                if (buf.length >= 4 + len) {
+                    const msg = buf.slice(4, 4 + len).toString('utf8');
+                    const obj = JSON.parse(msg);
+                    assert.ok(obj.payload);
+                    assert.ok(obj.signature);
+                    const payload = JSON.parse(obj.payload);
+                    const expected = crypto
+                        .createHmac('sha256', token)
+                        .update(JSON.stringify(payload))
+                        .digest('base64');
+                    assert.strictEqual(obj.signature, expected);
+                    socket.write(JSON.stringify({ status: 'ok' }));
+                    socket.end();
+                    server.close();
+                }
+            }
+        });
+    });
+
+    const options = {
+        host: '127.0.0.1',
+        port,
+        token,
+        vote: {
+            username: 'tester',
+            address: '127.0.0.1',
+            timestamp: Date.now(),
+            serviceName: 'MineNepal',
+        },
+        timeout: 2000,
+    };
+
+    await vote(options);
+}
+
+async function testInvalidOptions() {
+    try {
+        await vote(null);
+        throw new Error('expected rejection');
+    } catch (err) {
+        assert.ok(err instanceof Error);
+    }
+}
+
+function testCallbackAPI() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.listen(0, '127.0.0.1', () => {
+            const port = server.address().port;
+            const token = 'MYTOKEN';
+
+            server.on('connection', socket => {
+                socket.write('VOTIFIER 2 c\n');
+                let buf = Buffer.alloc(0);
+                socket.on('data', data => {
+                    buf = Buffer.concat([buf, data]);
+                    if (buf.length >= 4) {
+                        const len = buf.readUInt16BE(2);
+                        if (buf.length >= 4 + len) {
+                            socket.write(JSON.stringify({ status: 'ok' }));
+                            socket.end();
+                            server.close();
+                        }
+                    }
+                });
+            });
+
+            const options = {
+                host: '127.0.0.1',
+                port,
+                token,
+                vote: {
+                    username: 'cbuser',
+                    address: '127.0.0.1',
+                    timestamp: Date.now(),
+                    serviceName: 'MineNepal',
+                },
+            };
+
+            vote(options, function (err) {
+                if (err) return reject(err);
+                resolve();
+            });
+        });
+    });
+}
+
+async function run() {
+    const tests = [
+        { name: 'sends a signed vote (Promise API)', fn: testSendSignedVote },
+        { name: 'rejects when options are invalid', fn: testInvalidOptions },
+        { name: 'works with callback API', fn: testCallbackAPI },
+    ];
+
+    for (const t of tests) {
+        try {
+            await t.fn();
+            console.log('✔', t.name);
+        } catch (err) {
+            console.error('✖', t.name);
+            console.error(err && err.stack ? err.stack : err);
+            process.exitCode = 1;
+            return;
+        }
+        // small pause to let sockets close cleanly
+        await timeout(20);
+    }
+    console.log('\nAll tests passed');
+}
+
+if (require.main === module) {
+    run().catch(e => {
+        console.error(e);
+        process.exit(1);
+    });
+}
+
+module.exports = { testSendSignedVote, testInvalidOptions, testCallbackAPI };