CollabVM 1.2 Protocol Reference: Difference between revisions

Jump to navigation Jump to search
no edit summary
No edit summary
No edit summary
(13 intermediate revisions by the same user not shown)
 
All messages on the CollabVM protocol are UTF-8 string arrays encoded in Guacamole Format, detailed in the Design section of the [https://guacamole.apache.org/doc/0.9.5/gug/guacamole-protocol.html Guacamole 0.9.5 Manual, Chapter 9]. Servers '''SHOULD''' drop the connection if the client sends a message not conforming to this.
 
Every message consists of an "opcode" at position zero, followed by zero to unlimited parameters.
 
== nop ==
<tr><td>Parameter 3</td><td>A Base64-encoded thumbnail for the VM. Will be either PNG or JPEG depending on the server implementation. This can be determined through magic numbers.</td></tr>
</table>
 
=== Request a username ===
 
Before connecting, the client must now obtain a username.
 
==== Request ====
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>rename</code></td></tr>
<tr><td>Parameter 1</td><td><b>(OPTIONAL)</b> The username requested by the client. May be omitted if the client has no preference. The server is under no obligation to respect this and may provide a guest username for a multitude of reasons</td></tr>
</table>
 
==== Response ====
 
The server will respond with a [[#Client Renamed|Client Renamed]] event, however with one key difference: The status will always be <code>0</code> (success), even if the requested username was not available for whatever reason. In this case, a guest username is assigned.
 
=== Connect to a VM ===
Possible statuses:
 
<table class="wikitable">
'''1''': The connection was successful and the client is now connected to the VM.
<tr><th>Value</th><th>Status</th></tr>
 
'''<tr><td>0''': </td><td>The connection failed. This is usually due to an invalid VM ID but depending on the server implementation and protocol extensions could mean something else.
</td></tr>
<tr><td>1</td><td>The connection was successful and the client is now connected to the VM.</td></tr>
</table>
 
After successfully connecting to a VM, the client will begin to recieve messages as normal, and may send messages.
== Client-to-Server Opcodes ==
 
These opcodes may be sent by the client at any time after the handshake to perform various actions
TODO
 
=== RankAccount Login ===
 
Used to log in with a CollabVM account. This should only be sent if the server announced authentication using the <code>auth</code> opcode during the handshake phase. Sending this opcode otherwise is undefined behavior.
 
==== Request ====
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>login</code></td></tr>
<tr><td>Parameter 1</td><td>A session token OR bot token obtained from the authentication server announced during handshake.</td></tr>
</table>
 
==== Response ====
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>login</code></td></tr>
<tr><td>Parameter 1</td><td>Login status. <code>0</code> for error, <code>1</code> for success.</td></tr>
<tr><td>Parameter 2</td><td>Human-readable error. Only sent if status was <code>0</code></td></tr>
</table>
 
After a successful login, the client should expect to be renamed and have their rank updated by the server.
 
=== Rename ===
 
Used to change the client's username. This opcode is not available on servers that use account authentication, and the server will respond with an error.
 
==== Request ====
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>rename</code></td></tr>
<tr><td>Parameter 1</td><td>The username requested by the client. If omitted, the server will reassign a guest username.</td></tr>
</table>
 
==== Response ====
 
The server will respond with a [[#Client Renamed|Client Renamed]] event.
 
=== Send Chat ===
 
Send a public chat message to the server.
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>chat</code></td></tr>
<tr><td>Parameter 1</td><td>Chat message to send</td></tr>
</table>
 
=== Take turn ===
 
Request a turn on the VM.
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>turn</code></td></tr>
<tr><td>Parameter 1</td><td><code>1</code> to take a turn, <code>0</code> to cancel your turn. If not specified, the server will infer <code>1</code>.</td></tr>
</table>
 
=== Mouse Instruction ===
 
Send a mouse update to the VM. Only effective if the client has the turn or is an Admin. This opcode has no response.
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>mouse</code></td></tr>
<tr><td>Parameter 1</td><td>X position of the mouse pointer on the VM screen</td></tr>
<tr><td>Parameter 2</td><td>Y position of the mouse pointer on the VM screen</td></tr>
<tr><td>Parameter 3</td><td>Bitmask of mouse buttons being held. See [https://github.com/rfbproto/rfbproto/blob/master/rfbproto.rst#pointerevent Remote Framebuffer Protocol§PointerEvent]</td></tr>
</table>
 
=== Keyboard Instruction ===
 
Send a keyboard update to the VM. Only effective if the client has the turn or is an Admin. This opcode has no response.
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>key</code></td></tr>
<tr><td>Parameter 1</td><td>Key symbol for the key being pressed as a base-10 integer. See [https://cgit.freedesktop.org/xorg/proto/x11proto/tree/keysymdef.h keysymdef.h] for a list (values are in hex and must be converted to base 10)</td></tr>
<tr><td>Parameter 2</td><td><code>1</code> to press the key, <code>0</code> to release.</td></tr>
</table>
 
=== Vote-for-reset ===
 
Vote for or against resetting the VM to snapshot.
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>vote</code></td></tr>
<tr><td>Parameter 1</td><td><code>1</code> to vote in favor of a reset, <code>0</code> to vote against a reset. If there is no active vote, <code>1</code> is used to start one, while <code>0</code> has no effect.</td></tr>
</table>
 
== Admin Opcodes ==
 
These opcodes may be sent to perform administration actions on the VM.
 
=== Staff Login ===
 
Used to log in as an Admin or Moderator on the VM using a staff password. This opcode is disabled if the VM uses Account Authentication, in which case the [[#Account Login|Account Login]] opcode should be used instead.
 
==== Request ====
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>2</code></td></tr>
<tr><td>Parameter 2</td><td>The staff password</td></tr>
</table>
 
==== Response ====
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>0</code></td></tr>
<tr><td>Parameter 2</td><td>Status of the login. See below for possible values.</td></tr>
<tr><td>Parameter 3</td><td>[[#Permissions|Permissions]] integer defining available moderation actions. Only sent if status is <code>3</code></td></tr>
</table>
 
Status can be one of the following:
 
<table class="wikitable">
<tr><th>Value</th><th>Status</th></tr>
<tr><td>0</td><td>Invalid credentials, or access denied for another reason.</td></tr>
<tr><td>1</td><td>Logged in successfully as Admin</td></tr>
<tr><td>3</td><td>Logged in successfully as Moderator</td></tr>
</table>
 
After successfully logging in, the server will also send a new [[#New User(s)|New User]] event to announce your rank change.
 
=== QEMU Monitor ===
 
Used to send a [https://qemu-project.gitlab.io/qemu/system/monitor.html QEMU Monitor] command to the VM. Only Admins may use this opcode.
 
==== Request ====
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>5</code></td></tr>
<tr><td>Parameter 2</td><td>Command to send to QEMU</td></tr>
</table>
 
==== Response ====
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>2</code></td></tr>
<tr><td>Parameter 2</td><td>Response from QEMU</td></tr>
</table>
 
=== Restore VM ===
 
Restore the VM to snapshot without a vote.
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>8</code></td></tr>
</table>
 
=== Reboot VM ===
 
Reboot the VM.
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>10</code></td></tr>
</table>
 
=== Ban User ===
 
Ban a user. The actual backend behavior here is dependent on server implementation. Usually this runs a command set in configuration.
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>12</code></td></tr>
<tr><td>Parameter 2</td><td>Username to ban</td></tr>
</table>
 
=== Force vote ===
 
Forcibly end a vote-for-reset with the specified outcome
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>13</code></td></tr>
<tr><td>Parameter 2</td><td><code>1</code> to pass the vote and reset the VM, <code>0</code> to fail the vote</td></tr>
</table>.
 
=== Mute ===
 
Mute a user
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>14</code></td></tr>
<tr><td>Parameter 2</td><td>Username to mute</td></tr>
<tr><td>Parameter 3</td><td><code>0</code> for temporary mute, <code>1</code> for permanent. Temporary mute duration is left up to the server and is usually configurable.</td></tr>
</table>
 
=== Kick ===
 
Disconnect a user from the VM.
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>15</code></td></tr>
<tr><td>Parameter 2</td><td>Username to kick</td></tr>
</table>
 
=== End turn ===
 
End a user's turn, or forfeit their spot in the queue.
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>16</code></td></tr>
<tr><td>Parameter 2</td><td>Username to end turn</td></tr>
</table>
 
=== Clear turn queue ===
 
Clear the turn queue
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>17</code></td></tr>
<tr><td>Parameter 2</td><td>VM Node ID to clear the turn queue of</td></tr>
</table>
 
=== Rename user ===
 
Change another user's name.
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>18</code></td></tr>
<tr><td>Parameter 2</td><td>User to rename</td></tr>
<tr><td>Parameter 3</td><td>New username</td></tr>
</table>
 
=== Grab IP ===
 
Grab a user's IP Address
 
==== Request ====
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>19</code></td></tr>
<tr><td>Parameter 2</td><td>User to IP grab</td></tr>
</table>
 
==== Response ====
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>19</code></td></tr>
<tr><td>Parameter 2</td><td>User whose IP was grabbed</td></tr>
<tr><td>Parameter 3</td><td>The requested IP address</td></tr>
</table>
 
=== Bypass turn queue ===
 
Jump directly in front of the queue and take the turn.
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>20</code></td></tr>
</table>
 
=== Send raw message ===
 
Send a raw (XSS) message to the chat, bypassing HTML sanitization and character limits. When a moderator sends a raw message, admins will still receive a sanitized version for security reasons.
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>21</code></td></tr>
<tr><td>Parameter 2</td><td>Raw message to send</td></tr>
</table>
 
=== Toggle turns ===
 
Prevent or allow non-staff to take turns on the VM
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>22</code></td></tr>
<tr><td>Parameter 2</td><td><code>1</code> to enable turns, <code>0</code> to disable them.</td></tr>
</table>
 
=== Indefinite turn ===
 
Jump directly to the front of the turn queue and take a turn that does not end until you disconnect or end it manually.
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>23</code></td></tr>
</table>
 
=== Hide screen ===
 
Hide or show the VM screen from non-staff.
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>24</code></td></tr>
<tr><td>Parameter 2</td><td><code>1</code> to show the screen, <code>0</code> to hide it.</td></tr>
</table>
 
=== Send system message ===
 
Send a raw (XSS) message as a system message from the server.
 
<table class="wikitable">
<tr><td>Opcode</td><td><code>admin</code></td></tr>
<tr><td>Parameter 1</td><td><code>25</code></td></tr>
<tr><td>Parameter 2</td><td>System message to send</td></tr>
</table>
 
= Rank =
 
CollabVM has four ranks:
<tr><td>2</td><td>Admin</td><td>Has all permissions on the VM.</td></tr>
<tr><td>3</td><td>Moderator</td><td>Permissions vary depending on server configuration. Even with all permissions granted moderators can still not use the QEMU monitor.</td></tr>
</table>
 
= Permissions =
 
When logging in as a Moderator, permissions are defined by a bitmask that can contain the following values:
 
<table class="wikitable">
<tr><th>Value</th><th>Description</th></tr>
<tr><td>1</td><td>Reset the VM back to it's initial state.</td></tr>
<tr><td>2</td><td>Reboot the VM</td></tr>
<tr><td>4</td><td>Ban a user from your VM</td></tr>
<tr><td>8</td><td>Forcibly pass or cancel a vote to reset</td></tr>
<tr><td>16</td><td>Mute a user, preventing them from chatting or taking turns</td></tr>
<tr><td>32</td><td>Kick a user from the VM</td></tr>
<tr><td>64</td><td>Jump to the front of the turn queue, as well as clear the turn queue and end individual turns</td></tr>
<tr><td>128</td><td>Rename another user</td></tr>
<tr><td>256</td><td>Get the IP address of another user</td></tr>
<tr><td>512</td><td>Send a raw (not HTML-sanitized) chat message, allowing the execution of arbitrary scripts on another user's browser. Admins will not be affected by XSS messages sent by mods.</td></tr>
</table>

Navigation menu