minecraft-toolkit 0.1.0 → 0.1.2

package/src/player/profile/index.js

@@ -0,0 +1,144 @@
+import { MOJANG_PROFILE_BASE, SESSION_PROFILE_BASE, NAME_HISTORY_BASE } from "../../constants.js";
+import { MinecraftToolkitError } from "../../errors.js";
+import { fetchJson } from "../../utils/http/index.js";
+import { normalizeUsername } from "../../utils/validation.js";
+import { decodeTexturePayload, getSkinURL, getCapeURL, extractTextureHash } from "../textures.js";
+
+export async function fetchPlayerProfile(username) {
+  const normalizedUsername = normalizeUsername(username);
+  const identity = await fetchJson(
+    `${MOJANG_PROFILE_BASE}/${encodeURIComponent(normalizedUsername)}`,
+    {
+      notFoundMessage: "Player not found",
+    },
+  );
+
+  const sessionProfile = await fetchJson(`${SESSION_PROFILE_BASE}/${identity.id}`);
+  const texturePayload = decodeTexturePayload(sessionProfile.properties);
+
+  return {
+    id: identity.id,
+    name: identity.name,
+    profile: sessionProfile,
+    textures: texturePayload?.textures ?? {},
+    skin: texturePayload?.textures?.SKIN ?? null,
+    cape: texturePayload?.textures?.CAPE ?? null,
+  };
+}
+
+export async function playerExists(username) {
+  const normalizedUsername = normalizeUsername(username);
+  try {
+    await fetchJson(`${MOJANG_PROFILE_BASE}/${encodeURIComponent(normalizedUsername)}`);
+    return true;
+  } catch (error) {
+    if (error instanceof MinecraftToolkitError && error.statusCode === 404) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+export async function fetchPlayerSummary(username) {
+  const profile = await fetchPlayerProfile(username);
+  return {
+    id: profile.id,
+    name: profile.name,
+    skinUrl: getSkinURL(profile),
+    capeUrl: getCapeURL(profile),
+  };
+}
+
+export function hasSkinChanged(profileA, profileB) {
+  const hashA = extractTextureHash(getSkinURL(profileA));
+  const hashB = extractTextureHash(getSkinURL(profileB));
+  return hashA !== hashB;
+}
+
+export async function fetchPlayerSkin(username) {
+  const profile = await fetchPlayerProfile(username);
+  return {
+    id: profile.id,
+    name: profile.name,
+    skin: profile.skin,
+    cape: profile.cape,
+  };
+}
+
+export async function fetchPlayerUUID(username) {
+  const profile = await fetchPlayerProfile(username);
+  return {
+    id: profile.id,
+    name: profile.name,
+  };
+}
+
+export async function fetchUsernameByUUID(uuid) {
+  const response = await fetchJson(`${SESSION_PROFILE_BASE}/${uuid}`, {
+    notFoundMessage: "UUID not found",
+  });
+  return {
+    id: response.id,
+    name: response.name,
+  };
+}
+
+export async function fetchNameHistory(uuid) {
+  const entries = await fetchJson(`${NAME_HISTORY_BASE}/${uuid}/names`, {
+    notFoundMessage: "UUID not found",
+  });
+  return Array.isArray(entries)
+    ? entries.map((entry) => ({
+        name: entry.name,
+        changedAt: entry.changedToAt ? new Date(entry.changedToAt) : null,
+      }))
+    : [];
+}
+
+export async function fetchPlayers(usernames, options = {}) {
+  const { delayMs = 100, signal } = options;
+  if (!Array.isArray(usernames) || usernames.length === 0) {
+    return [];
+  }
+
+  const deduped = Array.from(new Set(usernames.map((name) => normalizeUsername(name))));
+  const results = [];
+
+  for (let index = 0; index < deduped.length; index += 1) {
+    const username = deduped[index];
+    if (signal?.aborted) {
+      throw new MinecraftToolkitError("Batch fetch aborted", { statusCode: 499 });
+    }
+
+    try {
+      const profile = await fetchPlayerProfile(username);
+      results.push({ username, profile });
+    } catch (error) {
+      results.push({ username, error });
+    }
+
+    if (index < deduped.length - 1 && delayMs > 0) {
+      await wait(delayMs, signal);
+    }
+  }
+
+  return results;
+}
+
+function wait(ms, signal) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener?.("abort", onAbort);
+      resolve();
+    }, ms);
+
+    function onAbort() {
+      clearTimeout(timer);
+      reject(new MinecraftToolkitError("Batch fetch aborted", { statusCode: 499 }));
+    }
+
+    if (signal) {
+      signal.addEventListener?.("abort", onAbort, { once: true });
+    }
+  });
+}

package/src/player/resolve.js

@@ -0,0 +1,31 @@
+import { isUUID, normalizeUUID, uuidWithDashes } from "./identity/index.js";
+import { fetchPlayerProfile, fetchPlayerUUID, fetchUsernameByUUID } from "./profile/index.js";
+
+export async function resolvePlayer(input) {
+  if (typeof input !== "string" || input.trim().length === 0) {
+    throw new TypeError("resolvePlayer input must be a non-empty string");
+  }
+
+  const raw = input.trim();
+
+  if (isUUID(raw)) {
+    const normalized = normalizeUUID(raw);
+    const identity = await fetchUsernameByUUID(normalized);
+    const profile = await fetchPlayerProfile(identity.name);
+    return {
+      id: uuidWithDashes(normalized),
+      name: identity.name,
+      skin: profile.skin ?? null,
+      cape: profile.cape ?? null,
+    };
+  }
+
+  const profile = await fetchPlayerProfile(raw);
+  const { id } = await fetchPlayerUUID(raw);
+  return {
+    id: uuidWithDashes(id),
+    name: profile.name,
+    skin: profile.skin ?? null,
+    cape: profile.cape ?? null,
+  };
+}

package/src/player/skin.js

@@ -0,0 +1,93 @@
+import { PNG } from "pngjs";
+import { MinecraftToolkitError } from "../errors.js";
+import { fetchPlayerProfile } from "./profile/index.js";
+
+const HEAD_REGION = { x: 8, y: 8, width: 8, height: 8 };
+
+export async function fetchSkinMetadata(username, options = {}) {
+  const profile = await fetchPlayerProfile(username);
+  const skinUrl = profile.skin?.url ?? null;
+  let dominantColor = null;
+
+  if (skinUrl && options.dominantColor !== false) {
+    dominantColor = await computeSkinDominantColor(skinUrl, options.sampleRegion);
+  }
+
+  return {
+    id: profile.id,
+    name: profile.name,
+    skin: profile.skin,
+    cape: profile.cape,
+    hasCape: Boolean(profile.cape),
+    dominantColor,
+  };
+}
+
+export async function computeSkinDominantColor(url, region = HEAD_REGION) {
+  const png = await fetchPng(url);
+  const { width, height, data } = png;
+  const { x, y, width: regionWidth, height: regionHeight } = clampRegion(region, width, height);
+
+  let r = 0;
+  let g = 0;
+  let b = 0;
+  let samples = 0;
+
+  for (let row = y; row < y + regionHeight; row += 1) {
+    for (let col = x; col < x + regionWidth; col += 1) {
+      const idx = (row * width + col) * 4;
+      const alpha = data[idx + 3] / 255;
+      if (alpha === 0) {
+        continue;
+      }
+      r += data[idx] * alpha;
+      g += data[idx + 1] * alpha;
+      b += data[idx + 2] * alpha;
+      samples += 1;
+    }
+  }
+
+  if (samples === 0) {
+    return null;
+  }
+
+  const avgR = Math.round(r / samples);
+  const avgG = Math.round(g / samples);
+  const avgB = Math.round(b / samples);
+  return rgbToHex(avgR, avgG, avgB);
+}
+
+async function fetchPng(url) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new MinecraftToolkitError(`Unable to load skin texture: ${url}`, {
+      statusCode: response.status,
+    });
+  }
+
+  const buffer = Buffer.from(await response.arrayBuffer());
+  try {
+    return PNG.sync.read(buffer);
+  } catch (error) {
+    throw new MinecraftToolkitError("Unable to decode PNG skin texture", {
+      statusCode: 500,
+      cause: error,
+    });
+  }
+}
+
+function clampRegion(region, width, height) {
+  const x = Math.max(0, Math.min(width - 1, region.x ?? HEAD_REGION.x));
+  const y = Math.max(0, Math.min(height - 1, region.y ?? HEAD_REGION.y));
+  const regionWidth = Math.min(region.width ?? HEAD_REGION.width, width - x);
+  const regionHeight = Math.min(region.height ?? HEAD_REGION.height, height - y);
+  return { x, y, width: regionWidth, height: regionHeight };
+}
+
+function rgbToHex(r, g, b) {
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+}
+
+function toHex(value) {
+  return value.toString(16).padStart(2, "0");
+}

package/src/player/textures.js

@@ -0,0 +1,39 @@
+import { MinecraftToolkitError } from "../errors.js";
+
+export function decodeTexturePayload(properties = []) {
+  const texturesProperty = properties.find((prop) => prop.name === "textures");
+  if (!texturesProperty?.value) {
+    return null;
+  }
+
+  try {
+    const decoded = Buffer.from(texturesProperty.value, "base64").toString("utf8");
+    return JSON.parse(decoded);
+  } catch (error) {
+    throw new MinecraftToolkitError("Unable to decode Mojang texture payload", {
+      statusCode: 500,
+      cause: error,
+    });
+  }
+}
+
+export function getSkinURL(profile) {
+  return profile?.skin?.url ?? null;
+}
+
+export function getCapeURL(profile) {
+  return profile?.cape?.url ?? null;
+}
+
+export function getSkinModel(profile) {
+  const model = profile?.skin?.metadata?.model;
+  return model === "slim" ? "slim" : "default";
+}
+
+export function extractTextureHash(url) {
+  if (!url) {
+    return null;
+  }
+  const match = url.match(/\/texture\/([A-Za-z0-9]+)/);
+  return match ? match[1] : null;
+}

package/src/server/bedrock/status.js

@@ -0,0 +1,147 @@
+import { createSocket } from "node:dgram";
+import { randomBytes } from "node:crypto";
+import { DEFAULT_BEDROCK_PORT, RAKNET_MAGIC } from "../../constants.js";
+import { MinecraftToolkitError } from "../../errors.js";
+import { normalizeAddress } from "../../utils/validation.js";
+import { resolveAddress } from "../../utils/network.js";
+import { resolveTimeout, makeError } from "../shared.js";
+
+export async function fetchBedrockServerStatus(address, options = {}) {
+  const normalized = normalizeAddress(address);
+  const { host, port } = resolveAddress(normalized, options.port, DEFAULT_BEDROCK_PORT);
+  const timeoutMs = resolveTimeout(options.timeoutMs);
+
+  return new Promise((resolve, reject) => {
+    const socket = createSocket("udp4");
+    let settled = false;
+
+    const timestamp = BigInt(Date.now());
+    const clientGuid = randomBytes(8);
+    const pingPacket = buildBedrockPingPacket(timestamp, clientGuid);
+
+    const timeout = setTimeout(() => {
+      rejectOnce(
+        new MinecraftToolkitError(`Timed out while querying Bedrock server ${host}:${port}`, {
+          statusCode: 504,
+        }),
+      );
+    }, timeoutMs);
+
+    function cleanup() {
+      clearTimeout(timeout);
+      socket.removeAllListeners();
+      socket.close();
+    }
+
+    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 query Bedrock server ${host}:${port}`, error),
+      );
+    }
+
+    socket.once("error", (error) => {
+      rejectOnce(makeError(`Unable to reach Bedrock server ${host}:${port}`, error));
+    });
+
+    socket.on("message", (message) => {
+      try {
+        const status = parseBedrockStatus(message, host, port);
+        resolveOnce(status);
+      } catch (error) {
+        rejectOnce(
+          error instanceof MinecraftToolkitError
+            ? error
+            : makeError("Invalid Bedrock response", error),
+        );
+      }
+    });
+
+    socket.send(pingPacket, port, host, (error) => {
+      if (error) {
+        rejectOnce(makeError(`Failed to send Bedrock ping to ${host}:${port}`, error));
+      }
+    });
+  });
+}
+
+function buildBedrockPingPacket(timestamp, clientGuid) {
+  const buffer = Buffer.alloc(1 + 8 + 16 + 8);
+  let offset = 0;
+  buffer.writeUInt8(0x01, offset);
+  offset += 1;
+  buffer.writeBigInt64BE(timestamp, offset);
+  offset += 8;
+  RAKNET_MAGIC.copy(buffer, offset);
+  offset += RAKNET_MAGIC.length;
+  clientGuid.copy(buffer, offset);
+  return buffer;
+}
+
+function parseBedrockStatus(message, host, port) {
+  if (message.length < 35) {
+    throw new MinecraftToolkitError("Bedrock response too short");
+  }
+  const packetId = message.readUInt8(0);
+  if (packetId !== 0x1c) {
+    throw new MinecraftToolkitError(`Unexpected Bedrock packet id ${packetId}`);
+  }
+  const magic = message.subarray(17, 33);
+  if (!magic.equals(RAKNET_MAGIC)) {
+    throw new MinecraftToolkitError("Invalid RakNet magic");
+  }
+  const stringLength = message.readUInt16BE(33);
+  const totalLength = 35 + stringLength;
+  if (message.length < totalLength) {
+    throw new MinecraftToolkitError("Bedrock payload truncated");
+  }
+  const data = message.subarray(35, totalLength).toString("utf8");
+  const parts = data.split(";");
+  if (parts[0] !== "MCPE") {
+    throw new MinecraftToolkitError("Unexpected Bedrock edition identifier");
+  }
+
+  const protocol = Number.parseInt(parts[2] ?? "0", 10) || 0;
+  const versionName = parts[3] ?? "";
+  const onlinePlayers = Number.parseInt(parts[4] ?? "0", 10) || 0;
+  const maxPlayers = Number.parseInt(parts[5] ?? "0", 10) || 0;
+  const ipv4Port = Number.parseInt(parts[9] ?? `${port}`, 10) || port;
+  const ipv6Port = parts[10] ? Number.parseInt(parts[10], 10) || null : null;
+
+  return {
+    edition: "bedrock",
+    online: true,
+    host,
+    port,
+    motd: parts[1] ?? "",
+    version: {
+      protocol,
+      name: versionName,
+    },
+    players: {
+      online: onlinePlayers,
+      max: maxPlayers,
+    },
+    serverId: parts[6] ?? "",
+    map: parts[7] ?? "",
+    gamemode: parts[8] ?? "",
+    ipv4Port,
+    ipv6Port,
+    raw: data,
+  };
+}

package/src/server/java/status.js

@@ -0,0 +1,259 @@
+import { Socket } from "node:net";
+import { DEFAULT_JAVA_PORT, DEFAULT_PROTOCOL_VERSION } from "../../constants.js";
+import { MinecraftToolkitError } from "../../errors.js";
+import { normalizeAddress } from "../../utils/validation.js";
+import { resolveAddress } from "../../utils/network.js";
+import { resolveTimeout, makeError } from "../shared.js";
+
+export async function fetchJavaServerStatus(address, options = {}) {
+  const normalized = normalizeAddress(address);
+  const { host, port } = resolveAddress(normalized, options.port, DEFAULT_JAVA_PORT);
+  const timeoutMs = resolveTimeout(options.timeoutMs);
+  const protocolVersion = Number.isInteger(options.protocolVersion)
+    ? options.protocolVersion
+    : DEFAULT_PROTOCOL_VERSION;
+
+  return new Promise((resolve, reject) => {
+    const socket = new Socket();
+    socket.setNoDelay(true);
+
+    let buffer = Buffer.alloc(0);
+    let statusPayload = null;
+    let settled = false;
+    let pingStartedAt = 0;
+    let pingFallbackTimer;
+
+    const handshakePacket = buildHandshakePacket(host, port, protocolVersion);
+    const statusRequestPacket = buildStatusRequestPacket();
+
+    function cleanup() {
+      clearTimeout(pingFallbackTimer);
+      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 query ${host}:${port}`, error),
+      );
+    }
+
+    function finish(latencyMs = null) {
+      resolveOnce(buildJavaStatus(statusPayload, host, port, latencyMs));
+    }
+
+    socket.setTimeout(timeoutMs, () => {
+      rejectOnce(
+        new MinecraftToolkitError(`Timed out while querying ${host}:${port}`, { statusCode: 504 }),
+      );
+    });
+
+    socket.on("error", (error) => {
+      rejectOnce(makeError(`Unable to reach ${host}:${port}`, error));
+    });
+
+    socket.on("close", () => {
+      if (!settled) {
+        if (statusPayload) {
+          finish(null);
+        } else {
+          rejectOnce(
+            new MinecraftToolkitError(
+              `Connection closed before status was received for ${host}:${port}`,
+            ),
+          );
+        }
+      }
+    });
+
+    socket.on("data", (chunk) => {
+      buffer = Buffer.concat([buffer, chunk]);
+      processPackets();
+    });
+
+    socket.connect(port, host, () => {
+      try {
+        socket.write(handshakePacket);
+        socket.write(statusRequestPacket);
+      } catch (error) {
+        rejectOnce(makeError(`Failed to send status request to ${host}:${port}`, error));
+      }
+    });
+
+    function processPackets() {
+      while (true) {
+        const packet = extractPacket();
+        if (!packet) {
+          break;
+        }
+        const { id, payload } = packet;
+        if (id === 0 && !statusPayload) {
+          try {
+            statusPayload = parseStatusPayload(payload);
+          } catch (error) {
+            rejectOnce(makeError("Invalid status payload", error));
+            return;
+          }
+
+          try {
+            pingStartedAt = Date.now();
+            socket.write(buildPingPacket(pingStartedAt));
+            pingFallbackTimer = setTimeout(() => {
+              if (!settled) {
+                finish(null);
+              }
+            }, 200);
+          } catch {
+            finish(null);
+          }
+        } else if (id === 1 && statusPayload) {
+          const latency = Math.max(0, Date.now() - pingStartedAt);
+          finish(latency);
+        }
+      }
+    }
+
+    function extractPacket() {
+      try {
+        const { value: length, size: lengthSize } = decodeVarInt(buffer, 0);
+        if (buffer.length < lengthSize + length) {
+          return null;
+        }
+        const packetData = buffer.subarray(lengthSize, lengthSize + length);
+        buffer = buffer.subarray(lengthSize + length);
+        const { value: packetId, size: idSize } = decodeVarInt(packetData, 0);
+        const payload = packetData.subarray(idSize);
+        return { id: packetId, payload };
+      } catch {
+        return null;
+      }
+    }
+  });
+}
+
+function buildHandshakePacket(host, port, protocolVersion) {
+  const hostBytes = Buffer.from(host, "utf8");
+  const payload = Buffer.concat([
+    encodeVarInt(protocolVersion),
+    encodeVarInt(hostBytes.length),
+    hostBytes,
+    writePort(port),
+    encodeVarInt(1),
+  ]);
+  return createPacket(0, payload);
+}
+
+function buildStatusRequestPacket() {
+  return createPacket(0, Buffer.alloc(0));
+}
+
+function buildPingPacket(timestampMs) {
+  const payload = Buffer.alloc(8);
+  payload.writeBigInt64BE(BigInt(timestampMs));
+  return createPacket(1, payload);
+}
+
+function createPacket(packetId, payload) {
+  const payloadBuffer = Buffer.concat([encodeVarInt(packetId), payload]);
+  const lengthBuffer = encodeVarInt(payloadBuffer.length);
+  return Buffer.concat([lengthBuffer, payloadBuffer]);
+}
+
+function encodeVarInt(value) {
+  const bytes = [];
+  let current = value >>> 0;
+  do {
+    let byte = current & 0x7f;
+    current >>>= 7;
+    if (current !== 0) {
+      byte |= 0x80;
+    }
+    bytes.push(byte);
+  } while (current !== 0);
+  return Buffer.from(bytes);
+}
+
+function decodeVarInt(buffer, offset = 0) {
+  let numRead = 0;
+  let result = 0;
+  let byte = 0;
+  do {
+    if (offset + numRead >= buffer.length) {
+      throw new RangeError("VarInt extends beyond buffer");
+    }
+    byte = buffer[offset + numRead];
+    result |= (byte & 0x7f) << (7 * numRead);
+    numRead += 1;
+    if (numRead > 5) {
+      throw new RangeError("VarInt is too big");
+    }
+  } while ((byte & 0x80) === 0x80);
+  return { value: result, size: numRead };
+}
+
+function parseStatusPayload(payload) {
+  const { value: stringLength, size } = decodeVarInt(payload, 0);
+  const end = size + stringLength;
+  if (payload.length < end) {
+    throw new RangeError("Status string exceeds payload length");
+  }
+  const json = payload.subarray(size, end).toString("utf8");
+  return JSON.parse(json);
+}
+
+function buildJavaStatus(payload, host, port, latencyMs) {
+  return {
+    edition: "java",
+    online: true,
+    host,
+    port,
+    version: payload.version ?? null,
+    players: payload.players ?? null,
+    motd: stringifyDescription(payload.description) ?? null,
+    favicon: payload.favicon ?? null,
+    latencyMs,
+    raw: payload,
+  };
+}
+
+function stringifyDescription(description) {
+  if (!description) {
+    return null;
+  }
+  if (typeof description === "string") {
+    return description;
+  }
+  if (Array.isArray(description)) {
+    return description.map((entry) => stringifyDescription(entry) ?? "").join("");
+  }
+  if (typeof description === "object") {
+    const text = description.text ?? "";
+    const extra = Array.isArray(description.extra)
+      ? description.extra.map((entry) => stringifyDescription(entry) ?? "").join("")
+      : "";
+    return `${text}${extra}` || null;
+  }
+  return null;
+}
+
+function writePort(port) {
+  const buffer = Buffer.alloc(2);
+  buffer.writeUInt16BE(port, 0);
+  return buffer;
+}