minecraft-toolkit 0.1.2 → 0.1.4

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.
 
@@ -151,6 +151,48 @@ console.log(javaStatus.players.online, bedrockStatus.motd.text);
 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

@@ -0,0 +1,251 @@
+import type { H3 } from "h3";
+import type { Buffer } from "node:buffer";
+
+export interface SkinTexture {
+  url: string;
+  metadata?: {
+    model?: "default" | "slim";
+  };
+}
+
+export interface CapeTexture {
+  url: string;
+}
+
+export interface PlayerProfile {
+  id: string;
+  name: string;
+  profile: Record<string, unknown>;
+  textures: Record<string, unknown>;
+  skin: SkinTexture | null;
+  cape: CapeTexture | null;
+}
+
+export interface PlayerSkin {
+  id: string;
+  name: string;
+  skin: SkinTexture | null;
+  cape: CapeTexture | null;
+}
+
+export interface PlayerSummary {
+  id: string;
+  name: string;
+  skinUrl: string | null;
+  capeUrl: string | null;
+}
+
+export interface BatchResult {
+  username: string;
+  profile?: PlayerProfile;
+  error?: unknown;
+}
+
+export interface BatchOptions {
+  delayMs?: number;
+  signal?: AbortSignal;
+}
+
+export interface SkinMetadataResult {
+  id: string;
+  name: string;
+  skin: SkinTexture | null;
+  cape: CapeTexture | null;
+  hasCape: boolean;
+  dominantColor: string | null;
+}
+
+export function fetchPlayerProfile(username: string): Promise<PlayerProfile>;
+export function fetchPlayerSkin(username: string): Promise<PlayerSkin>;
+export function fetchPlayerUUID(username: string): Promise<{ id: string; name: string }>;
+export function fetchUsernameByUUID(uuid: string): Promise<{ id: string; name: string }>;
+export function fetchNameHistory(uuid: string): Promise<{ name: string; changedAt: Date | null }[]>;
+export function fetchPlayers(usernames: string[], options?: BatchOptions): Promise<BatchResult[]>;
+export function fetchPlayerSummary(username: string): Promise<PlayerSummary>;
+export function playerExists(username: string): Promise<boolean>;
+export function hasSkinChanged(profileA: PlayerProfile, profileB: PlayerProfile): boolean;
+export function fetchSkinMetadata(
+  username: string,
+  options?: {
+    dominantColor?: boolean;
+    sampleRegion?: { x?: number; y?: number; width?: number; height?: number };
+  },
+): Promise<SkinMetadataResult>;
+export function fetchSkinDominantColor(
+  url: string,
+  region?: { x?: number; y?: number; width?: number; height?: number },
+): Promise<string | null>;
+export function resolvePlayer(input: string): Promise<PlayerSkin>;
+
+export function isValidUsername(username: string): boolean;
+export function isUUID(value: string): boolean;
+export function normalizeUUID(uuid: string): string;
+export function uuidWithDashes(uuid: string): string;
+export function uuidWithoutDashes(uuid: string): string;
+
+export type FormattingMode = "inline" | "class";
+
+export interface FormattingOptions {
+  mode?: FormattingMode;
+  classPrefix?: string;
+  animationName?: string;
+  obfuscatedSpeedMs?: number;
+  escapeHtml?: boolean;
+}
+
+export interface FormattingColorMeta {
+  name: string;
+  classSuffix: string;
+  hex: string;
+}
+
+export interface FormattingFormatMeta {
+  name: string;
+  classSuffix: string;
+}
+
+export interface FormattingMaps {
+  colors: Record<string, FormattingColorMeta>;
+  formats: Record<string, FormattingFormatMeta>;
+}
+
+export function toHTML(input: string, options?: FormattingOptions): string;
+export function stripCodes(input: string): string;
+export function generateCSS(options?: FormattingOptions): string;
+export function hasCodes(input: string): boolean;
+export function convertPrefix(input: string, direction?: "toSection" | "toAmpersand"): string;
+export function getMaps(): FormattingMaps;
+
+export function getSkinURL(profile: PlayerProfile | PlayerSkin): string | null;
+export function getCapeURL(profile: PlayerProfile | PlayerSkin): string | null;
+export function getSkinModel(profile: PlayerProfile | PlayerSkin): "default" | "slim";
+export function extractTextureHash(url: string | null): string | null;
+
+export type ServerEdition = "java" | "bedrock" | "auto";
+
+export interface JavaServerStatusOptions {
+  port?: number;
+  timeoutMs?: number;
+  protocolVersion?: number;
+}
+
+export interface BedrockServerStatusOptions {
+  port?: number;
+  timeoutMs?: number;
+}
+
+export interface ServerStatusOptions extends JavaServerStatusOptions {
+  edition?: ServerEdition;
+  type?: ServerEdition;
+}
+
+export interface JavaServerStatus {
+  edition: "java";
+  online: boolean;
+  host: string;
+  port: number;
+  version: {
+    name?: string | null;
+    protocol?: number | null;
+  } | null;
+  players: {
+    max?: number | null;
+    online?: number | null;
+    sample?: Array<{ name: string; id: string }>;
+  } | null;
+  motd: string | null;
+  favicon: string | null;
+  latencyMs: number | null;
+  raw: Record<string, unknown>;
+}
+
+export interface BedrockServerStatus {
+  edition: "bedrock";
+  online: boolean;
+  host: string;
+  port: number;
+  motd: string;
+  version: {
+    protocol: number;
+    name: string;
+  };
+  players: {
+    online: number;
+    max: number;
+  };
+  serverId: string;
+  map: string;
+  gamemode: string;
+  ipv4Port: number;
+  ipv6Port: number | null;
+  raw: string;
+}
+
+export type ServerStatus = JavaServerStatus | BedrockServerStatus;
+
+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,
+): Promise<JavaServerStatus>;
+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;
+}
+
+export function createPlayerHandlers(): PlayerHandlers;
+export function createPlayerApp(options?: { app?: ConstructorParameters<typeof H3>[0] }): {
+  app: H3;
+  handlers: PlayerHandlers;
+};
+export const playerPlugin: (app: H3) => PlayerHandlers;
+
+export function fetchNameChangeInfo(accessToken: string): Promise<any>;
+export function checkNameAvailability(name: string, accessToken: string): Promise<any>;
+export function validateGiftCode(code: string, accessToken: string): Promise<boolean>;
+export function fetchBlockedServers(): Promise<string[]>;

package/index.js

@@ -33,3 +33,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.2",
-  "description": "Developer toolkit for working with Mojang Minecraft player data, skins, and utilities.",
+  "version": "0.1.4",
+  "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": {
@@ -30,6 +34,7 @@
   "files": [
     "src",
     "index.js",
+    "index.d.ts",
     "README.md",
     "LICENSE"
   ],
@@ -37,11 +42,10 @@
   "sideEffects": false,
   "types": "./index.d.ts",
   "exports": {
-    ".": "./index.js",
-    "./player": "./src/player/profile/index.js",
-    "./skin": "./src/player/skin.js",
-    "./identity": "./src/player/identity/index.js",
-    "./textures": "./src/player/textures.js"
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
   },
   "scripts": {
     "test": "vitest",

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/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/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/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";
+}