feat: 🎉 begin project

Author: RichardDorian

.github/workflows/build.yml

@@ -1,25 +1,25 @@
-# name: Build
+name: Build
 
-# on:
-#   push:
-#     branches: [main]
-#   pull_request:
-#     branches: [main]
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
 
-# jobs:
-#   build:
-#     runs-on: ubuntu-latest
-#     strategy:
-#       matrix:
-#         node-version: [16.x]
-#     steps:
-#       - uses: actions/checkout@v2
-#       - name: Node.js
-#         uses: actions/setup-node@v2
-#         with:
-#           node-version: ${{ matrix.node-version }}
-#       - run: npm install
-#       - name: Build code
-#         run: npm run build
-#       - name: Test code
-#         run: npm run test
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18.x]
+    steps:
+      - uses: actions/checkout@v2
+      - name: Node.js
+        uses: actions/setup-node@v2
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm install
+      - name: Build code
+        run: npm run build
+      # - name: Test code
+      #   run: npm run test

README.md

@@ -1,3 +1,29 @@
-# MinecraftJS Template
+# Yggdrasil
 
-Fill with your own content
+![GitHub Workflow Status](https://img.shields.io/github/workflow/status/MinecraftJS/Yggdrasil/Build?style=for-the-badge)
+![GitHub](https://img.shields.io/github/license/MinecraftJS/Yggdrasil?style=for-the-badge)
+![npm (scoped)](https://img.shields.io/npm/v/@minecraft-js/yggdrasil?style=for-the-badge)
+
+Yggdrasil wrapper written in TypeScript
+
+# Documentation
+
+## Installation
+
+Install the package:
+
+```bash
+$ npm install @minecraft-js/yggdrasil
+```
+
+And then import it in your JavaScript/TypeScript file
+
+```ts
+const { yggdrasil } = require('@minecraft-js/yggdrasil'); // CommonJS
+
+import { yggdrasil } from '@minecraft-js/yggdrasil'; // ES6
+```
+
+## Usage
+
+This library is meant for client and server authentication. See [this](https://wiki.vg/Protocol_Encryption) for more information.

package-lock.json

@@ -1,27 +1,30 @@
 {
-  "name": "template",
+  "name": "@minecraft-js/yggdrasil",
   "version": "1.0.0",
-  "description": "todo: change",
+  "description": "Yggdrasil wrapper written in TypeScript",
   "main": "dist/index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
     "build": "tsc"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/MinecraftJS/template.git"
+    "url": "git+https://github.com/MinecraftJS/Yggdrasil.git"
   },
   "keywords": [
     "minecraftjs"
   ],
-  "author": "todo: change",
+  "author": "RichardDorian",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/MinecraftJS/template/issues"
+    "url": "https://github.com/MinecraftJS/Yggdrasil/issues"
+  },
+  "homepage": "https://github.com/MinecraftJS/Yggdrasil#readme",
+  "dependencies": {
+    "@minecraft-js/uuid": "^1.0.3"
   },
-  "homepage": "https://github.com/MinecraftJS/template#readme",
-  "dependencies": {},
   "devDependencies": {
+    "@types/node": "^18.7.18",
     "prettier": "^2.7.1",
     "typescript": "^4.8.2"
   },

package.json

@@ -0,0 +1,144 @@
+import { parseUUID, UUID } from '@minecraft-js/uuid';
+import { URLSearchParams } from 'node:url';
+import {
+  EmptyResponseError,
+  InsufficientPrivilegesError,
+  UserBannedError,
+} from './utils/errors';
+import { generateHexDigest } from './utils/hash';
+import { request } from './utils/request';
+
+export class YggdrasilClient {
+  /** Default instance using the default host */
+  public static readonly instance = new YggdrasilClient();
+  /** Headers to apply to every single requests */
+  public static readonly HEADERS = {
+    'User-Agent':
+      'MinecraftJS/1.0.0 (https://github.com/MinecraftJS/Yggdrasil)',
+    'Content-Type': 'application/json',
+  };
+
+  /** Host this instance is bound to */
+  public readonly host: string;
+
+  public constructor(host?: string) {
+    this.host = host ?? 'https://sessionserver.mojang.com';
+  }
+
+  public async join(
+    accessToken: string,
+    selectedProfile: UUID,
+    serverId: string,
+    sharedSecret: Buffer,
+    serverPublicKey: Buffer
+  ): Promise<void> {
+    const hash = generateHexDigest(serverId, sharedSecret, serverPublicKey);
+
+    const { body, response } = await request(
+      this.host + '/session/minecraft/join',
+      JSON.stringify({
+        accessToken,
+        selectedProfile,
+        serverId: hash,
+      }),
+      {
+        headers: YggdrasilClient.HEADERS,
+        method: 'POST',
+      }
+    );
+
+    switch (response.statusCode) {
+      case 204:
+        return;
+
+      case 403:
+        const error = JSON.parse(body.toString()).error;
+
+        switch (error) {
+          case 'InsufficientPrivilegesException':
+            throw new InsufficientPrivilegesError(
+              'Xbox profile has multiplayer disabled'
+            );
+
+          case 'UserBannedException':
+            throw new UserBannedError('User is banned from multiplayer');
+
+          default:
+            throw new Error(error);
+        }
+
+      default:
+        throw new Error('Unexpected status code ' + response.statusCode);
+    }
+  }
+
+  /**
+   * Ask the authentication server if an online player connected to the server
+   *
+   * Note: The `id` and `name` fields are then sent back to the client using a Login Success packet. The profile id in the
+   * json response has format `11111111222233334444555555555555` which needs to be changed into format
+   * `11111111-2222-3333-4444-555555555555` before sending it back to the client.
+   *
+   * @param username The username is case insensitive and must match the client's username (which was received in the LoginStartPacket).
+   * Note that this is the in-game nickname of the selected profile, not the Mojang account name (which is never sent to the server).
+   * Servers should use the name sent in the "name" field.
+   * @param serverId ASCII encoding of the server id string from EncryptionRequestPacket
+   * @param sharedSecret Shared secret between the client and the server
+   * @param serverPublicKey Server's public key from EncryptionRequestPacket
+   * @param ip The ip field is optional and when present should be the IP address of the connecting player; it is the one that
+   * originally initiated the session request. The notchian server includes this only when `prevent-proxy-connections`
+   * is set to true in `server.properties`.
+   * @returns Object containing the UUID and the player's skin
+   */
+  public async hasJoined(
+    username: string,
+    serverId: string,
+    sharedSecret: Buffer,
+    serverPublicKey: Buffer,
+    ip?: string
+  ): Promise<HasJoinedResponse> {
+    const hash = generateHexDigest(serverId, sharedSecret, serverPublicKey);
+
+    const params = new URLSearchParams();
+    params.set('username', username);
+    params.set('serverId', hash);
+    if (ip) params.set('ip', ip);
+
+    const { body, response } = await request(
+      this.host + '/session/minecraft/hasJoined?' + params.toString(),
+      null,
+      {
+        headers: {
+          'User-Agent': YggdrasilClient.HEADERS['User-Agent'],
+        },
+      }
+    );
+
+    switch (response.statusCode) {
+      case 200:
+        const parsed = JSON.parse(body.toString());
+        parsed.id = parseUUID(parsed.id);
+        return parsed;
+
+      case 204:
+        throw new EmptyResponseError(
+          'Received an empty response from the server'
+        );
+
+      default:
+        throw new Error('Unexpected status code ' + response.statusCode);
+    }
+  }
+}
+
+export const yggdrasil = YggdrasilClient.instance;
+
+export interface HasJoinedResponse {
+  id: UUID;
+  name: string;
+  properties: {
+    name: string;
+    value: string;
+    signature: string;
+  }[];
+}

src/Client.ts

@@ -0,0 +1,3 @@
+export * from './Client';
+export * from './utils/errors';
+export * from './utils/hash';

src/index.ts

@@ -0,0 +1,3 @@
+export class EmptyResponseError extends Error {}
+export class InsufficientPrivilegesError extends Error {}
+export class UserBannedError extends Error {}

src/utils/errors.ts

@@ -0,0 +1,56 @@
+/**
+ * Most of the code here
+ * is just adapted to fit
+ * my needs
+ * @see https://gist.github.com/andrewrk/4425843?permalink_comment_id=3265398#gistcomment-3265398
+ * for the original code
+ */
+
+import { createHash } from 'node:crypto';
+
+/**
+ * Generate a server hash from its serverId, shared secret and public key
+ * @param serverId ASCII encoding of the server id string from EncryptionRequestPacket
+ * @param sharedSecret Shared secret between the client and the server
+ * @param serverPublicKey Server's public key from EncryptionRequestPacket
+ * @returns The hash
+ */
+export function generateHexDigest(
+  serverId: string,
+  sharedSecret: Buffer,
+  serverPublicKey: Buffer
+): string {
+  // The hex digest is the hash made below.
+  // However, when this hash is negative (meaning its MSB is 1, as it is in two's complement), instead of leaving it
+  // like that, we make it positive and simply put a '-' in front of it. This is a simple process: as you always do
+  // with 2's complement you simply flip all bits and add 1
+
+  let hash = createHash('sha1')
+    .update(serverId)
+    .update(sharedSecret)
+    .update(serverPublicKey)
+    .digest();
+
+  // Negative check: check if the most significant bit of the hash is a 1.
+  const isNegative = (hash.readUInt8(0) & (1 << 7)) !== 0; // when 0, it is positive
+
+  if (isNegative) {
+    // Flip all bits and add one. Start at the right to make sure the carry works
+    const inverted = Buffer.allocUnsafe(hash.length);
+    let carry = 0;
+    for (let i = hash.length - 1; i >= 0; i--) {
+      let num = hash.readUInt8(i) ^ 0b11111111; // a byte XOR a byte of 1's = the inverse of the byte
+      if (i === hash.length - 1) num++;
+      num += carry;
+      carry = Math.max(0, num - 0b11111111);
+      num = Math.min(0b11111111, num);
+      inverted.writeUInt8(num, i);
+    }
+    hash = inverted;
+  }
+  let result = hash.toString('hex').replace(/^0+/, '');
+  // If the result was negative, add a '-' sign
+  if (isNegative) result = `-${result}`;
+
+  return result;
+}