Bureaucrats, Check users, Interface administrators, Push subscription managers, Suppressors, Administrators
415
edits
CollabVM 1.2 Protocol Reference: Difference between revisions
no edit summary
No edit summary |
No edit summary |
||
| (20 intermediate revisions by the same user not shown) | |||
|
The CollabVM protocol is the mutilated corpse of what used to be Guacamole 0.9.5. It maintains the same instruction format and opcodes for getting the VM display and controlling it, but that's about it.
=
The connection starts with the client making a WebSocket connection to the CollabVM endpoint. This can be anything, for example <code>wss://computernewb.com/collab-vm/vm0</code> for VM0b0t.
Assigned usernames are, by convention, <code>guest</code> followed by five random digits. However, the server may use whatever format it pleases.
==
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.
==
This is a keepalive signal sent through the duration of the session used to verify that the client is still connected.
Clients '''MAY''' drop the connection if the server does not send '''any''' messages over a period of time. However this should not be limited strictly to NOPs as these may not be consistently sent if there is other activity on the connection.
==
Upon making a WebSocket connection, the server will immediately begin sending NOPs, which will continue for the duration of the connection. The client is immediately in the handshaking phase of the connection.
The handshake is as follows:
=== Authentication announcement ===
A server that uses CollabVM Account Authentication will send a message with the <code>auth</code> opcode to announce this. This indicates a few changes in behavior:
* Clients may login using the <code>login</code> opcode.
* Clients may not change username except by logging in or having a guest username assigned.
* Depending on server configuration, clients may not be able to chat, take turns, or vote without logging in
* Staff-password authentication is disabled
==== Parameters ====
<table class="wikitable">
<tr><td>Opcode</td><td><code>auth</code></td></tr>
<tr><td>Parameter 1</td><td>The base URL of the authentication server used by this instance. Ex: <code>https://auth.collabvm.org</code></td></tr>
</table>
=== Obtain a list of VMs ===
The first thing the client may want to do is obtain a list of VMs available on this server. If the client already knows exactly what node ID it wants to connect to (common for bots) this may be skipped.
==== Request ====
<table class="wikitable">
<tr><td>Opcode</td><td><code>list</code></td></tr>
</table>
====
Parameters 1 through 3 are repeated for every available VM.
<table class="wikitable">
<tr><td>Opcode</td><td><code>list</code></td></tr>
<tr><td>Parameter 1</td><td>The ID of the node, that should be passed to the <code>connect</code> opcode.</td></tr>
<tr><td>Parameter 2</td><td>A display name for the VM. May contain HTML.</td></tr>
<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.
===
The client may now connect to a VM as follows:
==== Request ====
<table class="wikitable">
<tr><td>Opcode</td><td><code>connect</code></td></tr>
<tr><td>Parameter 1</td><td>The ID of the VM to connect to. Can be retrieved with the list opcode.</td></tr>
</table>
==== Response ====
<table class="wikitable">
<tr><td>Opcode</td><td><code>connect</code></td></tr>
<tr><td>Parameter 1</td><td>The status of the connection. See below</td></tr>
</table>
Possible statuses:
<table class="wikitable">
<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.
== Server-to-Client Opcodes ==
These messages may be sent by the server at any time after completing the handshake and must be handled by the client.
=== New User(s) ===
Sent to indicate that one or more users have joined the VM. This may also be sent during the handshake.
This may be resent for an already-joined user to announce that they have changed ranks after logging in. Make sure to check for duplicates.
Parameters 1 and 2 are repeated for each user added.
<table class="wikitable">
<tr><td>Opcode</td><td><code>adduser</code></td></tr>
<tr><td>Parameter 1</td><td>The username of the added user.</td></tr>
<tr><td>Parameter 2</td><td>The [[#Rank|Rank]] of the added user as an integer.</td></tr>
</table>
=== Removed User(s) ===
Sent when one or more users disconnect from the VM.
Parameter 2 is repeated for each user removed.
<table class="wikitable">
<tr><td>Opcode</td><td><code>remuser</code></td></tr>
<tr><td>Parameter 1</td><td>The number of users that have left</td></tr>
<tr><td>Parameter 2</td><td>The username that has left the VM.</td></tr>
</table>
=== Client Renamed ===
Sent when the current client (you) is renamed, either by you or the server.
<table class="wikitable">
<tr><td>Opcode</td><td><code>rename</code></td></tr>
<tr><td>Parameter 1</td><td><code>0</code></td></tr>
<tr><td>Parameter 2</td><td>The status of the rename. See below for available values.</td></tr>
<tr><td>Parameter 3</td><td>The client's new username. This may not necessarily be the username requested by the client, as the server can refuse this request for a variety of reasons and may instead assign a guest name.</td></tr>
</table>
Possible rename statuses:
<table class="wikitable">
</table>
=== User Renamed ===
<table class="wikitable">
<tr><td>Opcode</td><td><code>rename</code></td></tr>
<tr><td>Parameter 1</td><td><code>1</code></td></tr>
<tr><td>Parameter 2</td><td>The user's old username</td></tr>
<tr><td>Parameter 3</td><td>The user's new username</td></tr>
</table>
=== Chat message ===
Sent when one or more chat messages are received.
Parameters 1 and 2 may be repeated for multiple chat messages, and this should be checked for. In current server implementations, this will only happen immediately after connection to send the chat history.
<table class="wikitable">
<tr><td>Opcode</td><td><code>chat</code></td></tr>
<tr><td>Parameter 1</td><td>The user who sent the chat message. This may be an empty string to indicate a system message sent by the server, such as the Message of the Day, or a vote notification.</td></tr>
<tr><td>Parameter 2</td><td>The chat message</td></tr>
</table>
Sent to announce the screen size of the VM. This will be sent after connecting and after any resolution change on the VM.
<table class="wikitable">
<tr><td>Opcode</td><td><code>size</code></td></tr>
<tr><td>Parameter 1</td><td><code>0</code></td></tr>
<tr><td>Parameter 2</td><td>Screen width</td></tr>
<tr><td>Parameter 3</td><td>Screen height</td></tr>
</table>
=== Framebuffer Update ===
Sent to update the VM screen. The server will send one initial message containing the entire screen on connection, and after that will send a dirty rect for each update
<table class="wikitable">
<tr><td>Opcode</td><td><code>png</code></td></tr>
<tr><td>Parameter 1</td><td><code>0</code></td></tr>
<tr><td>Parameter 2</td><td><code>0</code></td></tr>
<tr><td>Parameter 3</td><td>X-axis position of the rectangle</td></tr>
<tr><td>Parameter 4</td><td>Y-axis position of the rectangle</td></tr>
<tr><td>Parameter 5</td><td>The base64-encoded rectangle. Despite the name of the opcode, this may be either PNG or JPEG and can be determined through magic numbers or headers.</td></tr>
</table>
=== Vote-for-reset notification ===
Sent when a Vote-for-reset on the VM updates
<table class="wikitable">
<tr><td>Opcode</td><td><code>vote</code></td></tr>
<tr><td>Parameter 1</td><td>The status of the vote. See below for values</td></tr>
<tr><td>Parameter 2</td><td>Amount of time left on the vote in milliseconds. If the above status was 3 (cooldown), this is the amount of time before the client can start a vote.</td></tr>
<tr><td>Parameter 3</td><td>The number of users who have voted in favor of resetting the VM</td></tr>
<tr><td>Parameter 4</td><td>The number of users who have voted against resetting the VM</td></tr>
</table>
Possible vote statuses:
<table class="wikitable">
<tr><th>Value</th><th>Status</th></tr>
<tr><td>0</td><td>The vote has started. The yes and no parameters may not be specified, and in such case should be assumed to be zero.</td></tr>
<tr><td>1</td><td>The vote count has updated.</td></tr>
<tr><td>2</td><td>The vote has ended. No other parameters will be given.</td></tr>
<tr><td>3</td><td>Sent if the client tried to start a vote, however there is an active cooldown. Only the time parameter is given.</td></tr>
</table>
=== Turn queue update ===
Indicates an update of the VM's turn queue
<table class="wikitable">
<tr><td>Opcode</td><td><code>turn</code></td></tr>
<tr><td>Parameter 1</td><td>How much time is left on the current user's turn in milliseconds.</td></tr>
<tr><td>Parameter 2</td><td>The amount of users in the queue.</td></tr>
<tr><td>Parameter 3-?</td><td>Each username in the queue given as separate parameters</td></tr>
<tr><td>End parameter</td><td>How much longer until the client will get a turn in milliseconds. Only sent if the client is waiting.</td></tr>
</table>
== Client-to-Server Opcodes ==
These opcodes may be sent by the client at any time after the handshake to perform various actions
=== Account 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>
<tr><td>1</td><td>
<tr><td>
</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.
====
<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>
====
<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 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 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:
<table class="wikitable">
<tr><th>ID</th><th>Name</th><th>Description</th></tr>
<tr><td>0</td><td>Unregistered</td><td>The default rank with no permissions that all users have prior to logging in.</td></tr>
<tr><td>1</td><td>Registered</td><td>A logged in user. This is only used by servers that use CollabVM Account Authentication.</td></tr>
<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>
| |||