minecraft-toolkit 0.1.3 → 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

@@ -1,4 +1,5 @@
 import type { H3 } from "h3";
+import type { Buffer } from "node:buffer";
 
 export interface SkinTexture {
   url: string;
@@ -182,7 +183,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,6 +204,31 @@ 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;

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.3",
-  "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": {

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