init commit

README.md

@@ -1,3 +1,11 @@
-# essential-re
+# Essential RE Findings
 
-Reverse-engineered information about the Essential Minecraft mod
+This is a repository containing information about the [Essential](https://essential.gg/) Minecraft mod, found through reverse engineering the mod and its server.
+
+You're most likely looking for the [converted cosmetic downloads](https://git.oat.zone/oat/essential-re/releases). If you want a nicer, less formal write-up of what's going on, you're looking for the [blog post](https://blog.oat.zone/p/53f3872a-03f5-4610-9160-42ec692f36f3/).
+
+Otherwise, here's what I've found, categorized nicely:
+
+## Findings
+
+- [packets.md](./packets.md), describing how packets are structured

packets.md

@@ -0,0 +1,87 @@
+# Essential Packets
+
+In Essential, packets are sent over WebSockets to `wss://connect.essential.gg/v1`. Both the server and client share the same simple structure:
+
+1. A single byte, representing the packet type sent as an integer.
+
+The type ID is a number that is unique to the client and server and established by the sending party.
+
+For example, if a client wants to send a `ClientConnectionLoginPacket`, they will have to send to the server a packet of ID `0`, establishing that `ClientConnectionLoginPacket` is ID `1` (which looks something like `{"a":"connection.ClientConnectionLoginPacket","b":1}`), and then send a packet with the newly established ID `1`. This packet will then be understood by the server as a `ClientConnectionLoginPacket` consequentially, and will not need to be redefined.
+
+Both parties establish that a packet of ID `0` is a `RegisterPacketTypeId` packet upon connection.
+
+2. A single byte, representing the length of the packet UUID this packet is in reply to. Set to NUL and ignore next spot if this packet is not in reply to anything.
+3. The UUIDv4 of the packet this packet is in reply to. Usually either 0 or 36 bytes long, seperated by dashes.
+
+It's unknown to me how the UUID of a packet is obtained. This UUID is not sent by the sending party, but it wasn't relevant to what I was doing so I discarded it.
+
+4. The length of the payload.
+5. The JSON-encoded payload.
+
+The payload will be encoded using a custom GSON config which encodes simple JSON keys into single characters. For instance, a payload of `{"className":"connection.ClientConnectionLoginPacket","packetId":1}` will be converted into `{"a":"connection.ClientConnectionLoginPacket","b":1}`. This seems to be a networking optimization and obfuscation tactic. The keys will always stay consistent and seem to be based on definition order; if a constructor of a packet lists the properties `id` and `type`, then you can always know that `a` will mean `id` and `b` will mean `type`. It seems that both parties always maintain packet definitions for both sides to decode recieved packets.
+
+## Packets
+
+Here are some note-worthy packets I've discovered:
+
+### connection.RegisterPacketTypeId
+
+This is a packet that's always registered internally as `0` for both sides, which lets a party define the ID of a packet.
+
+### connection.ClientConnectionLoginPacket
+
+This packet is sent by the client and is used for authentication. A `username` and `sharedSecret` are sent which are then processed by the server to authenticate the user. Afterwards, the server will consider the user authenticated, and proceed to send them various packets. All packets sent upon authentication from now on will be marked with "Sent on authentication".
+
+### response.ResponseActionPacket
+
+This packet contains a single boolean and is used in responses to other packets to indicate whether something succeeded or failed.
+
+### cosmetic.ServerCosmeticsPopulatePacket
+
+_Sent on authentication_
+
+_Server-exclusive_
+
+This packet sends every cosmetic registered on the server, along with the necessary assets and metadata. This is the only packet where information about a cosmetic is sent.
+
+### profile.trustedhosts.ServerProfileTrustedHostsPopulatePacket
+
+_Sent on authentication_
+
+_Server-exclusive_
+
+This packet seems to provide the client with "trusted hosts". As of writing, this is what this packet looks like:
+
+```json
+{
+  "a": [
+    {
+      "a": "60cb24a50dc956941869312d",
+      "b": "Discord",
+      "c": [ "cdn.discordapp.com", "media.discordapp.net" ]
+    },
+    {
+      "a": "60cb24a50dc956941869312e",
+      "b": "BadLion",
+      "c": [ "i.badlion.net" ]
+    },
+    {
+      "a": "60cb24a50dc956941869312f",
+      "b": "Imgur",
+      "c": [ "i.imgur.com", "imgur.com" ]
+    },
+    {
+      "a": "60cb24a50dc9569418693130",
+      "b": "Reddit",
+      "c": [ "i.redd.it" ]
+    },
+    {
+      a: "60cb24a50dc9569418693131",
+      b: "Twitter",
+      c: [ "pbs.twimg.com" ]
+    }
+  ]
+}
+```
+
+It is unknown what purpose these links serve. It may be a list of links that you are allowed to embed in private messages.