minecraft-toolkit 0.1.3 → 1.0.0

package/README.md

@@ -8,7 +8,7 @@
 
 <!-- /automd -->
 
-Lightweight Mojang player utilities (profile, skin, UUID) for Node, Vite, and edge projects.
+Lightweight Minecraft API + infrastructure toolkit: player profiles & textures, Java/Bedrock server status probes, and Votifier (v1/v2) clients that run in Node, Vite, and edge runtimes.
 
 > This toolkit wraps Mojang APIs. Rate limits and availability still apply. Write endpoints (name change, skin upload) are not yet included.
 
@@ -81,9 +81,10 @@ import {
 
 isValidUsername("26bz"); // true
 uuidWithDashes("069a79f444e94726a5befca90e38aaf5");
-const skinUrl = getSkinURL(await fetchPlayerProfile("26bz"));
+const profile = await fetchPlayerProfile("26bz");
+const skinUrl = getSkinURL(profile);
 const hash = extractTextureHash(skinUrl);
-const model = getSkinModel(skinUrl); // "slim" | "classic"
+const model = getSkinModel(profile); // "slim" | "default"
 ```
 
 ## Skin Metadata & Color Sampling
@@ -139,18 +140,60 @@ import {
   fetchBedrockServerStatus,
 } from "minecraft-toolkit";
 
-const javaStatus = await fetchJavaServerStatus({ host: "mc.hypixel.net", port: 25565 });
-const bedrockStatus = await fetchBedrockServerStatus({ host: "play.example.net", port: 19132 });
+const javaStatus = await fetchJavaServerStatus("mc.hypixel.net", { port: 25565 });
+const bedrockStatus = await fetchBedrockServerStatus("play.example.net", { port: 19132 });
 
 // fetchServerStatus picks the right probe based on the `edition` field
-const autoStatus = await fetchServerStatus({ host: "my.realm.net", edition: "bedrock" });
+const autoStatus = await fetchServerStatus("my.realm.net", { edition: "bedrock" });
 
-console.log(javaStatus.players.online, bedrockStatus.motd.text);
+console.log(javaStatus.players.online, bedrockStatus.motd);
 ```
 
 Both helpers normalize MOTD text, favicon/Base64 icons, latency, and version info. Errors surface as
 `MinecraftToolkitError` with contextual status codes.
 
+### Server Icon Helper
+
+```ts
+import { fetchServerIcon } from "minecraft-toolkit";
+
+const icon = await fetchServerIcon("play.example.net");
+console.log(icon.base64); // "iVBOR..."
+console.log(icon.byteLength); // raw PNG size in bytes
+```
+
+The helper reuses the Java status ping to extract the favicon, returning:
+
+- `dataUri`: ready-to-render `data:image/png;base64,...`
+- `base64`: raw Base64 payload
+- `buffer` + `byteLength` for further processing (e.g., resizing, hashing)
+
+If the server doesn’t expose an icon, it throws `MinecraftToolkitError` (404).
+
+## Votifier Client (Java)
+
+Send vote notifications to classic Votifier v1 (RSA public key) and NuVotifier v2 (token/HMAC) servers without re-implementing either protocol.
+
+```ts
+import { sendVotifierVote } from "minecraft-toolkit";
+
+const result = await sendVotifierVote({
+  host: "votifier.myserver.net",
+  port: 8192, // defaults to 8192 if omitted
+  publicKey: process.env.VOTIFIER_PUBLIC_KEY, // v1 servers
+  serviceName: "MyTopList",
+  username: "26bz",
+  address: "198.51.100.42",
+  token: listingSiteConfig.token, // v2 servers (optional)
+  protocol: "auto", // let the handshake decide between v1/v2
+});
+
+console.log(result.acknowledged, result.version, result.protocol);
+```
+
+- Provide either a legacy RSA public key (for protocol v1) **or** a NuVotifier token (protocol v2). Server listing sites typically store each server's token and pass it here; `protocol: "auto"` will select the right flow based on the handshake.
+- `timestamp` accepts a `Date` or millisecond value (default: `Date.now()`). All failures bubble as `MinecraftToolkitError`.
+
 ## Minecraft Formatting Renderer
 
 Convert legacy `§` or `&` codes into safe HTML fragments or CSS class spans.

package/index.d.ts

@@ -1,4 +1,5 @@
 import type { H3 } from "h3";
+import type { Buffer } from "node:buffer";
 
 export interface SkinTexture {
   url: string;
@@ -70,7 +71,7 @@ export function fetchSkinMetadata(
     sampleRegion?: { x?: number; y?: number; width?: number; height?: number };
   },
 ): Promise<SkinMetadataResult>;
-export function fetchSkinDominantColor(
+export function computeSkinDominantColor(
   url: string,
   region?: { x?: number; y?: number; width?: number; height?: number },
 ): Promise<string | null>;
@@ -135,6 +136,7 @@ export interface BedrockServerStatusOptions {
 
 export interface ServerStatusOptions extends JavaServerStatusOptions {
   edition?: ServerEdition;
+  /** @deprecated Use `edition` instead. */
   type?: ServerEdition;
 }
 
@@ -182,7 +184,19 @@ export interface BedrockServerStatus {
 
 export type ServerStatus = JavaServerStatus | BedrockServerStatus;
 
-export function fetchServerStatus(address: string, options?: ServerStatusOptions): Promise<ServerStatus>;
+export interface ServerIconResult {
+  host: string;
+  port: number;
+  dataUri: string;
+  base64: string;
+  buffer: Buffer;
+  byteLength: number;
+}
+
+export function fetchServerStatus(
+  address: string,
+  options?: ServerStatusOptions,
+): Promise<ServerStatus>;
 export function fetchJavaServerStatus(
   address: string,
   options?: JavaServerStatusOptions,
@@ -191,13 +205,47 @@ export function fetchBedrockServerStatus(
   address: string,
   options?: BedrockServerStatusOptions,
 ): Promise<BedrockServerStatus>;
+export function fetchServerIcon(
+  address: string,
+  options?: JavaServerStatusOptions,
+): Promise<ServerIconResult>;
+
+export interface VotifierVoteOptions {
+  host: string;
+  port?: number;
+  publicKey: string;
+  serviceName: string;
+  username: string;
+  address: string;
+  timestamp?: number | Date;
+  timeoutMs?: number;
+  token?: string;
+  protocol?: "auto" | "v1" | "v2";
+}
+
+export interface VotifierVoteResult {
+  acknowledged: boolean;
+  version: string | null;
+  protocol: "v1" | "v2";
+}
+
+export function sendVotifierVote(options: VotifierVoteOptions): Promise<VotifierVoteResult>;
 
 export interface PlayerHandlers {
-  profileHandler: any;
-  skinHandler: any;
-  summaryHandler: any;
-  uuidHandler: any;
-  resolverHandler: any;
+  profileHandler: import("h3").EventHandler;
+  skinHandler: import("h3").EventHandler;
+  summaryHandler: import("h3").EventHandler;
+  uuidHandler: import("h3").EventHandler;
+  resolverHandler: import("h3").EventHandler;
+  nameHistoryHandler: import("h3").EventHandler;
+  existsHandler: import("h3").EventHandler;
+  batchHandler: import("h3").EventHandler;
+  nameChangeInfoHandler: import("h3").EventHandler;
+  nameAvailabilityHandler: import("h3").EventHandler;
+  giftCodeValidationHandler: import("h3").EventHandler;
+  blockedServersHandler: import("h3").EventHandler;
+  serverStatusHandler: import("h3").EventHandler;
+  serverIconHandler: import("h3").EventHandler;
 }
 
 export function createPlayerHandlers(): PlayerHandlers;

package/index.js

@@ -10,7 +10,13 @@ export {
   hasSkinChanged,
 } from "./src/player/profile/index.js";
 export { fetchSkinMetadata, computeSkinDominantColor } from "./src/player/skin.js";
-export { isValidUsername } from "./src/player/identity/index.js";
+export {
+  isValidUsername,
+  isUUID,
+  normalizeUUID,
+  uuidWithDashes,
+  uuidWithoutDashes,
+} from "./src/player/identity/index.js";
 export { getSkinURL, getCapeURL, getSkinModel, extractTextureHash } from "./src/player/textures.js";
 export { resolvePlayer } from "./src/player/resolve.js";
 export {
@@ -33,3 +39,5 @@ export {
   convertPrefix,
   getMaps,
 } from "./src/utils/formatting.js";
+export { sendVotifierVote } from "./src/server/votifier/index.js";
+export { fetchServerIcon } from "./src/server/icon.js";

package/package.json

@@ -1,17 +1,21 @@
 {
   "name": "minecraft-toolkit",
-  "version": "0.1.3",
-  "description": "Developer toolkit for working with Mojang Minecraft player data, skins, and utilities.",
+  "version": "1.0.0",
+  "description": "Minecraft toolkit for Mojang player data, server status probes, and Votifier v1/v2 clients.",
   "keywords": [
     "minecraft",
     "minecraft-api",
     "minecraft-player",
+    "minecraft-server",
     "minecraft-skins",
+    "minecraft-status",
     "minecraft-tools",
     "minecraft-utils",
     "minecraft-uuid",
+    "minecraft-votifier",
     "mojang",
-    "mojang-api"
+    "mojang-api",
+    "votifier"
   ],
   "homepage": "https://github.com/26bz/minecraft-toolkit",
   "bugs": {
@@ -43,17 +47,6 @@
       "default": "./index.js"
     }
   },
-  "scripts": {
-    "test": "vitest",
-    "test:watch": "vitest watch",
-    "test:coverage": "vitest run --coverage",
-    "lint": "oxlint",
-    "lint:fix": "oxlint --fix",
-    "fmt": "oxfmt",
-    "fmt:check": "oxfmt --check",
-    "prepare": "husky install",
-    "docs:sync": "automd"
-  },
   "dependencies": {
     "h3": "2.0.1-rc.14",
     "pngjs": "^7.0.0"
@@ -72,5 +65,14 @@
   "engines": {
     "node": ">=18"
   },
-  "packageManager": "pnpm@10.30.2"
-}
+  "scripts": {
+    "test": "vitest",
+    "test:watch": "vitest watch",
+    "test:coverage": "vitest run --coverage",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "docs:sync": "automd"
+  }
+}

package/src/constants.js

@@ -11,6 +11,7 @@ export const PACKAGE_METADATA = {
 
 export const DEFAULT_JAVA_PORT = 25565;
 export const DEFAULT_BEDROCK_PORT = 19132;
+export const DEFAULT_VOTIFIER_PORT = 8192;
 export const DEFAULT_CACHE_TTL_SECONDS = 30;
 export const DEFAULT_TIMEOUT_MS = 5000;
 export const DEFAULT_PROTOCOL_VERSION = 760; // Minecraft 1.20.4

package/src/errors.js

@@ -1,8 +1,7 @@
 export class MinecraftToolkitError extends Error {
   constructor(message, { statusCode = 500, cause } = {}) {
-    super(message);
+    super(message, { cause });
     this.name = "MinecraftToolkitError";
     this.statusCode = statusCode;
-    this.cause = cause;
   }
 }

package/src/h3/routes.js

@@ -1,4 +1,12 @@
-import { H3, defineHandler, definePlugin, readBody, getQuery } from "h3";
+import {
+  H3,
+  defineHandler,
+  definePlugin,
+  readBody,
+  getQuery,
+  getRouterParam,
+  getRequestHeader,
+} from "h3";
 import { MinecraftToolkitError } from "../errors.js";
 import {
   fetchPlayerProfile,
@@ -17,10 +25,11 @@ import {
   fetchBlockedServers,
 } from "../player/account/index.js";
 import { fetchServerStatus } from "../server/status.js";
+import { fetchServerIcon } from "../server/icon.js";
 import { normalizeAddress, validatePort } from "../utils/validation.js";
 
-function requireParam(event, key, message) {
-  const value = event.context.params?.[key];
+function requireRouterParam(event, key, message) {
+  const value = getRouterParam(event, key);
   if (!value) {
     throw new MinecraftToolkitError(message, { statusCode: 400 });
   }
@@ -29,37 +38,37 @@ function requireParam(event, key, message) {
 
 export function createPlayerHandlers() {
   const profileHandler = defineHandler(async (event) => {
-    const username = requireParam(event, "username", "Username parameter is required");
+    const username = requireRouterParam(event, "username", "Username parameter is required");
     return fetchPlayerProfile(username);
   });
 
   const skinHandler = defineHandler(async (event) => {
-    const username = requireParam(event, "username", "Username parameter is required");
+    const username = requireRouterParam(event, "username", "Username parameter is required");
     return fetchPlayerSkin(username);
   });
 
   const summaryHandler = defineHandler(async (event) => {
-    const username = requireParam(event, "username", "Username parameter is required");
+    const username = requireRouterParam(event, "username", "Username parameter is required");
     return fetchPlayerSummary(username);
   });
 
   const uuidHandler = defineHandler(async (event) => {
-    const username = requireParam(event, "username", "Username parameter is required");
+    const username = requireRouterParam(event, "username", "Username parameter is required");
     return fetchPlayerUUID(username);
   });
 
   const resolverHandler = defineHandler(async (event) => {
-    const input = requireParam(event, "input", "Username or UUID parameter is required");
+    const input = requireRouterParam(event, "input", "Username or UUID parameter is required");
     return resolvePlayer(input);
   });
 
   const nameHistoryHandler = defineHandler(async (event) => {
-    const uuid = requireParam(event, "uuid", "UUID parameter is required");
+    const uuid = requireRouterParam(event, "uuid", "UUID parameter is required");
     return fetchNameHistory(uuid);
   });
 
   const existsHandler = defineHandler(async (event) => {
-    const username = requireParam(event, "username", "Username parameter is required");
+    const username = requireRouterParam(event, "username", "Username parameter is required");
     const exists = await playerExists(username);
     return { username, exists };
   });
@@ -82,7 +91,7 @@ export function createPlayerHandlers() {
   });
 
   const nameAvailabilityHandler = defineHandler(async (event) => {
-    const name = requireParam(event, "name", "Name parameter is required");
+    const name = requireRouterParam(event, "name", "Name parameter is required");
     const token = requireAccessToken(event);
     return checkNameAvailability(name, token);
   });
@@ -100,9 +109,31 @@ export function createPlayerHandlers() {
 
   const blockedServersHandler = defineHandler(async () => fetchBlockedServers());
 
+  const serverIconHandler = defineHandler(async (event) => {
+    const address = normalizeAddress(
+      requireRouterParam(event, "address", "Server address parameter is required"),
+    );
+    const query = getQuery(event);
+    const port = typeof query.port === "string" ? validatePort(query.port) : undefined;
+    const timeoutMs =
+      typeof query.timeoutMs === "string" ? Number.parseInt(query.timeoutMs, 10) : undefined;
+    const protocolVersion =
+      typeof query.protocolVersion === "string"
+        ? Number.parseInt(query.protocolVersion, 10)
+        : undefined;
+
+    const icon = await fetchServerIcon(address, {
+      port,
+      timeoutMs,
+      protocolVersion,
+    });
+
+    return icon.buffer;
+  });
+
   const serverStatusHandler = defineHandler(async (event) => {
     const address = normalizeAddress(
-      requireParam(event, "address", "Server address parameter is required"),
+      requireRouterParam(event, "address", "Server address parameter is required"),
     );
     const query = getQuery(event);
     const edition = typeof query.edition === "string" ? query.edition : undefined;
@@ -136,6 +167,7 @@ export function createPlayerHandlers() {
     giftCodeValidationHandler,
     blockedServersHandler,
     serverStatusHandler,
+    serverIconHandler,
   };
 }
 
@@ -195,6 +227,10 @@ export function createPlayerApp(options = {}) {
     meta: { category: "server", resource: "status" },
   });
 
+  app.get("/server/:address/icon", handlers.serverIconHandler, {
+    meta: { category: "server", resource: "icon" },
+  });
+
   return { app, handlers };
 }
 
@@ -204,7 +240,7 @@ export const playerPlugin = definePlugin((app) => {
 });
 
 function requireAccessToken(event) {
-  const header = event.req?.headers?.get?.("authorization") ?? "";
+  const header = getRequestHeader(event, "authorization") ?? "";
   if (!header.toLowerCase().startsWith("bearer ")) {
     throw new MinecraftToolkitError("Authorization header with Bearer token is required", {
       statusCode: 401,

package/src/player/resolve.js

@@ -1,5 +1,5 @@
 import { isUUID, normalizeUUID, uuidWithDashes } from "./identity/index.js";
-import { fetchPlayerProfile, fetchPlayerUUID, fetchUsernameByUUID } from "./profile/index.js";
+import { fetchPlayerProfile, fetchUsernameByUUID } from "./profile/index.js";
 
 export async function resolvePlayer(input) {
   if (typeof input !== "string" || input.trim().length === 0) {
@@ -21,9 +21,8 @@ export async function resolvePlayer(input) {
   }
 
   const profile = await fetchPlayerProfile(raw);
-  const { id } = await fetchPlayerUUID(raw);
   return {
-    id: uuidWithDashes(id),
+    id: uuidWithDashes(profile.id),
     name: profile.name,
     skin: profile.skin ?? null,
     cape: profile.cape ?? null,

package/src/server/icon.js

@@ -0,0 +1,28 @@
+import { Buffer } from "node:buffer";
+import { fetchJavaServerStatus } from "./status.js";
+import { MinecraftToolkitError } from "../errors.js";
+
+export async function fetchServerIcon(address, options = {}) {
+  const status = await fetchJavaServerStatus(address, options);
+  const favicon = status?.favicon ?? status?.raw?.favicon;
+  if (!favicon || typeof favicon !== "string") {
+    throw new MinecraftToolkitError("Server did not expose a favicon", { statusCode: 404 });
+  }
+
+  const base64 = extractBase64(favicon);
+  const buffer = Buffer.from(base64, "base64");
+
+  return {
+    host: status.host,
+    port: status.port,
+    dataUri: `data:image/png;base64,${base64}`,
+    base64,
+    buffer,
+    byteLength: buffer.byteLength,
+  };
+}
+
+function extractBase64(favicon) {
+  const prefix = "data:image/png;base64,";
+  return favicon.startsWith(prefix) ? favicon.slice(prefix.length) : favicon;
+}

package/src/server/java/status.js

@@ -218,17 +218,18 @@ function parseStatusPayload(payload) {
 }
 
 function buildJavaStatus(payload, host, port, latencyMs) {
+  const { version, players, description, favicon, ...rest } = payload;
   return {
     edition: "java",
     online: true,
     host,
     port,
-    version: payload.version ?? null,
-    players: payload.players ?? null,
-    motd: stringifyDescription(payload.description) ?? null,
-    favicon: payload.favicon ?? null,
+    version: version ?? null,
+    players: players ?? null,
+    motd: stringifyDescription(description) ?? null,
+    favicon: favicon ?? null,
     latencyMs,
-    raw: payload,
+    raw: rest,
   };
 }
 

package/src/server/votifier/index.js

@@ -0,0 +1,328 @@
+import { Socket } from "node:net";
+import {
+  createPublicKey,
+  publicEncrypt,
+  constants as cryptoConstants,
+  createHmac,
+  randomBytes,
+} from "node:crypto";
+import { DEFAULT_TIMEOUT_MS, DEFAULT_VOTIFIER_PORT } from "../../constants.js";
+import { MinecraftToolkitError } from "../../errors.js";
+import { normalizeAddress, normalizeUsername } from "../../utils/validation.js";
+import { resolveTimeout, makeError } from "../shared.js";
+
+const HANDSHAKE_PREFIX = "VOTIFIER";
+
+const PROTOCOL_V1 = "v1";
+const PROTOCOL_V2 = "v2";
+
+export async function sendVotifierVote(options = {}) {
+  const {
+    host,
+    port = DEFAULT_VOTIFIER_PORT,
+    publicKey,
+    serviceName,
+    username,
+    address,
+    timestamp = Date.now(),
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    token,
+    protocol = "auto",
+  } = options;
+
+  if (!host) {
+    throw new MinecraftToolkitError("Votifier host is required", { statusCode: 400 });
+  }
+
+  if (!serviceName || typeof serviceName !== "string") {
+    throw new MinecraftToolkitError("Service name is required", { statusCode: 400 });
+  }
+  if (!username || typeof username !== "string") {
+    throw new MinecraftToolkitError("Username is required", { statusCode: 400 });
+  }
+  if (!address || typeof address !== "string") {
+    throw new MinecraftToolkitError("Voter IP address is required", { statusCode: 400 });
+  }
+
+  const normalizedHost = normalizeAddress(host);
+  const normalizedUsername = normalizeUsername(username);
+  const sanitizedService = serviceName.trim();
+  const sanitizedAddress = address.trim();
+  if (!sanitizedService) {
+    throw new MinecraftToolkitError("Service name cannot be empty", { statusCode: 400 });
+  }
+  if (!sanitizedAddress) {
+    throw new MinecraftToolkitError("Voter IP address cannot be empty", { statusCode: 400 });
+  }
+
+  const resolvedPort = Number.isInteger(port) ? port : DEFAULT_VOTIFIER_PORT;
+  const resolvedTimeout = resolveTimeout(timeoutMs);
+  const normalizedProtocol = normalizeProtocol(protocol);
+  const hasPublicKey = typeof publicKey === "string" && publicKey.trim().length > 0;
+  const hasToken = typeof token === "string" && token.trim().length > 0;
+
+  if (normalizedProtocol === PROTOCOL_V1 && !hasPublicKey) {
+    throw new MinecraftToolkitError("Votifier public key is required for protocol v1", {
+      statusCode: 400,
+    });
+  }
+  if (normalizedProtocol === PROTOCOL_V2 && !hasToken) {
+    throw new MinecraftToolkitError("Votifier token is required for protocol v2", {
+      statusCode: 400,
+    });
+  }
+  if (normalizedProtocol === "auto" && !hasPublicKey && !hasToken) {
+    throw new MinecraftToolkitError("Either a public key or token must be provided", {
+      statusCode: 400,
+    });
+  }
+
+  const unixSeconds =
+    typeof timestamp === "number"
+      ? Math.floor(timestamp / 1000)
+      : Math.floor(timestamp.getTime() / 1000);
+  const voteString = buildVotePayload({
+    serviceName: sanitizedService,
+    username: normalizedUsername,
+    address: sanitizedAddress,
+    timestamp: unixSeconds,
+  });
+  const voteBufferV1 = hasPublicKey
+    ? encryptVotePayload(Buffer.from(voteString, "utf8"), publicKey)
+    : null;
+
+  return new Promise((resolve, reject) => {
+    const socket = new Socket();
+    socket.setNoDelay?.(true);
+
+    let settled = false;
+    let handshakeBuffer = Buffer.alloc(0);
+    let handshakeReceived = false;
+    let reportedVersion = null;
+    let voteDispatched = false;
+    let selectedProtocol = normalizedProtocol === "auto" ? null : normalizedProtocol;
+
+    function cleanup() {
+      socket.removeAllListeners();
+      socket.destroy();
+    }
+
+    function resolveOnce(value) {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      resolve(value);
+    }
+
+    function rejectOnce(error) {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      reject(
+        error instanceof MinecraftToolkitError
+          ? error
+          : makeError(`Unable to send Votifier vote to ${normalizedHost}:${resolvedPort}`, error),
+      );
+    }
+
+    socket.setTimeout(resolvedTimeout, () => {
+      rejectOnce(
+        new MinecraftToolkitError(
+          `Timed out while sending vote to ${normalizedHost}:${resolvedPort}`,
+          {
+            statusCode: 504,
+          },
+        ),
+      );
+    });
+
+    socket.once("error", (error) => {
+      rejectOnce(makeError(`Unable to connect to ${normalizedHost}:${resolvedPort}`, error));
+    });
+
+    socket.on("data", (chunk) => {
+      handshakeBuffer = Buffer.concat([handshakeBuffer, chunk]);
+      const handshakeText = handshakeBuffer.toString("utf8").trim();
+      if (!handshakeText.startsWith(HANDSHAKE_PREFIX)) {
+        return;
+      }
+      handshakeReceived = true;
+
+      const { version, challenge } = parseHandshake(handshakeText);
+      reportedVersion = version;
+
+      if (!selectedProtocol || selectedProtocol === "auto") {
+        if (version?.startsWith("2") && hasToken) {
+          selectedProtocol = PROTOCOL_V2;
+        } else if (hasPublicKey) {
+          selectedProtocol = PROTOCOL_V1;
+        } else if (hasToken) {
+          selectedProtocol = PROTOCOL_V2;
+        }
+      }
+
+      if (selectedProtocol === PROTOCOL_V1 && !hasPublicKey) {
+        rejectOnce(
+          new MinecraftToolkitError("Server expects Votifier v1 but no public key was provided", {
+            statusCode: 400,
+          }),
+        );
+        return;
+      }
+      if (selectedProtocol === PROTOCOL_V2 && !hasToken) {
+        rejectOnce(
+          new MinecraftToolkitError("Server expects Votifier v2 but no token was provided", {
+            statusCode: 400,
+          }),
+        );
+        return;
+      }
+
+      sendVote(challenge);
+    });
+
+    socket.on("close", () => {
+      if (settled) {
+        return;
+      }
+      if (!handshakeReceived || !voteDispatched) {
+        rejectOnce(
+          new MinecraftToolkitError("Connection closed before Votifier vote was sent", {
+            statusCode: 502,
+          }),
+        );
+        return;
+      }
+      resolveOnce({
+        acknowledged: true,
+        version: reportedVersion,
+        protocol: selectedProtocol ?? PROTOCOL_V1,
+      });
+    });
+
+    socket.connect(resolvedPort, normalizedHost);
+
+    function sendVote(challengeSegment) {
+      socket.removeAllListeners("data");
+      try {
+        voteDispatched = true;
+        if (selectedProtocol === PROTOCOL_V2) {
+          const payload = buildV2Payload({
+            serviceName: sanitizedService,
+            username: normalizedUsername,
+            address: sanitizedAddress,
+            timestamp: unixSeconds,
+            token,
+            challengeSegment,
+          });
+          socket.write(payload, (writeError) => {
+            if (writeError) {
+              rejectOnce(makeError("Failed to deliver Votifier v2 payload", writeError));
+              return;
+            }
+            socket.once("data", (response) => {
+              try {
+                const parsed = JSON.parse(response.toString("utf8"));
+                if (parsed?.status === "error") {
+                  rejectOnce(
+                    new MinecraftToolkitError(parsed.errorMessage || "Votifier v2 error", {
+                      cause: parsed,
+                      statusCode: 502,
+                    }),
+                  );
+                } else {
+                  socket.end();
+                }
+              } catch (parseError) {
+                rejectOnce(makeError("Invalid Votifier v2 response", parseError));
+              }
+            });
+          });
+          return;
+        }
+
+        socket.write(voteBufferV1, (writeError) => {
+          if (writeError) {
+            rejectOnce(makeError("Failed to deliver Votifier payload", writeError));
+            return;
+          }
+          socket.end();
+        });
+      } catch (sendError) {
+        rejectOnce(makeError("Failed to send Votifier payload", sendError));
+      }
+    }
+  });
+}
+
+function buildVotePayload({ serviceName, username, address, timestamp }) {
+  return `VOTE\n${serviceName}\n${username}\n${address}\n${timestamp}\n`;
+}
+
+function buildV2Payload({ serviceName, username, address, timestamp, token, challengeSegment }) {
+  const normalizedChallenge = challengeSegment?.trim() || randomBytes(16).toString("hex");
+  const vote = {
+    serviceName,
+    username,
+    address,
+    timestamp,
+    challenge: normalizedChallenge,
+  };
+  const payload = JSON.stringify(vote);
+  const signature = createHmac("sha256", token).update(payload).digest("base64");
+  const message = JSON.stringify({ payload, signature });
+  const buffer = Buffer.alloc(4 + Buffer.byteLength(message));
+  buffer.writeUInt16BE(0x733a, 0);
+  buffer.writeUInt16BE(Buffer.byteLength(message), 2);
+  buffer.write(message, 4, "utf8");
+  return buffer;
+}
+
+function encryptVotePayload(payload, publicKey) {
+  let key;
+  try {
+    key = createPublicKey(
+      publicKey.includes("BEGIN")
+        ? publicKey
+        : `-----BEGIN PUBLIC KEY-----\n${publicKey}\n-----END PUBLIC KEY-----`,
+    );
+  } catch (error) {
+    throw new MinecraftToolkitError("Invalid Votifier public key", {
+      statusCode: 400,
+      cause: error,
+    });
+  }
+
+  try {
+    return publicEncrypt(
+      {
+        key,
+        padding: cryptoConstants.RSA_PKCS1_PADDING,
+      },
+      payload,
+    );
+  } catch (error) {
+    throw new MinecraftToolkitError("Failed to encrypt Votifier payload", {
+      statusCode: 400,
+      cause: error,
+    });
+  }
+}
+
+function parseHandshake(text) {
+  const parts = text.split(" ");
+  return {
+    version: parts[1] ?? null,
+    challenge: parts[2] ?? null,
+  };
+}
+
+function normalizeProtocol(protocol) {
+  return protocol === PROTOCOL_V1 || protocol === PROTOCOL_V2 || protocol === "auto"
+    ? protocol
+    : "auto";
+}

package/src/utils/network.js

@@ -5,10 +5,14 @@ export function resolveAddress(address, overridePort, fallbackPort) {
     return { host: address, port: validatePort(overridePort) };
   }
 
-  const parts = address.split(":");
-  if (parts.length > 1 && parts[parts.length - 1] !== "") {
-    const extractedPort = parts.pop();
-    return { host: parts.join(":"), port: validatePort(extractedPort) };
+  // Only treat as "host:port" when there is exactly one colon.
+  const colonCount = (address.match(/:/g) ?? []).length;
+  if (colonCount === 1) {
+    const lastColon = address.lastIndexOf(":");
+    const potentialPort = address.slice(lastColon + 1);
+    if (potentialPort !== "") {
+      return { host: address.slice(0, lastColon), port: validatePort(potentialPort) };
+    }
   }
 
   return { host: address, port: fallbackPort };