From d5d618e3ab69ad2b94736a35c49464e83010bf74 Mon Sep 17 00:00:00 2001 From: Niels Andriesse Date: Fri, 23 Apr 2021 14:03:26 +1000 Subject: [PATCH] Include docs directly (wikis don't carry across forks) --- CLI.md | 15 ++ DOCUMENTATION.md | 448 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 463 insertions(+) create mode 100644 CLI.md create mode 100644 DOCUMENTATION.md diff --git a/CLI.md b/CLI.md new file mode 100644 index 0000000..e599598 --- /dev/null +++ b/CLI.md @@ -0,0 +1,15 @@ +With the server running in the background (e.g. using systemd), you can run the following commands to perform various operations: + +| Command | Effect | +| --------------------------------------- |:---------------------------------:| +| `--add-room room_id room_name` | to add a room | +| `--delete-room room_id` | to delete a room | +| `--add-moderator public_key room_id` | to add a moderator to a room | +| `--delete-moderator public_key room_id` | to delete a moderator from a room | +| `--print-url` | to print your server's URL | + +The open group server binary is normally located in `/usr/bin`, so to e.g. execute the `--print-url` command you'd run: + +``` +/usr/bin/session-open-group-server --print-url +``` diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md new file mode 100644 index 0000000..8f0ed6b --- /dev/null +++ b/DOCUMENTATION.md @@ -0,0 +1,448 @@ +All endpoints return the status code in the response body because that's the only way to propagate the status code back to the client when using onion requests. + +## Endpoints + +### GET /rooms/:room_id + +| Header | Required | Notes | +| ------------- | -------- | ----- | +| Authorization | No | | +| Room | No | | + +Returns information about the room with the given ID. + +**Response:** + +``` +{ + status_code: u16, + room: { + id: String, + name: String + } +} +``` + +### GET /rooms + +| Header | Required | Notes | +| ------------- | -------- | ----- | +| Authorization | No | | +| Room | No | | + +Returns a list of all rooms on the server. + +**Response:** + +``` +{ + status_code: u16, + rooms: [ + { + id: String, + name: String + }, + ... + ] +} +``` + +### POST /files + +| Header | Required | Notes | +| ------------- | -------- | ----- | +| Authorization | Yes | Basic | +| Room | Yes | | + +Store a file on the server. + +**Expected body:** + +``` +{ + file: String // base64 encoded data +} +``` + +**Response:** + +``` +{ + status_code: u16 +} +``` + +### POST /rooms/:room_id/image + +| Header | Required | Notes | +| ------------- | -------- | --------- | +| Authorization | Yes | Moderator | +| Room | No | | + +Set the image for a room. + +**Expected body:** + +``` +{ + file: String // base64 encoded data +} +``` + +**Response:** + +``` +{ + status_code: u16, + room_id: String +} +``` + +### GET /files/:file_id + +| Header | Required | Notes | +| ------------- | -------- | ----- | +| Authorization | Yes | Basic | +| Room | Yes | | + +Get a file from the server. + +**Response:** + +``` +{ + status_code: u16, + result: String // base64 encoded data +} +``` + +### GET /rooms/:room_id/image + +| Header | Required | Notes | +| ------------- | -------- | ----- | +| Authorization | No | | +| Room | No | | + +Returns the preview image for the given group. + +**Response:** + +``` +{ + status_code: u16, + result: String // base64 encoded data +} +``` + +### GET /auth_token_challenge?public_key=string + +| Header | Required | Notes | +| ------------- | -------- | ----- | +| Authorization | No | | +| Room | Yes | | + +Get an auth token challenge. The requesting user generates a symmetric key from the ephemeral public key returned by the server and their private key, which can be used to decrypt the ciphertext and get the auth token. + +**Response:** + +``` +{ + status_code: u16, + challenge: { + ciphertext: String, // base64 encoded data + ephemeral_public_key: String // base64 encoded data + } +} +``` + +### POST /claim_auth_token + +| Header | Required | Notes | +| ------------- | -------- | ----- | +| Authorization | Yes | Basic | +| Room | Yes | | + +Claim the auth token in the `Authorization` header. + +**Expected body:** + +``` +{ + public_key: String +} +``` + +**Response:** + +``` +{ + status_code: u16 +} +``` + +### DELETE /auth_token + +| Header | Required | Notes | +| ------------- | -------- | ----- | +| Authorization | Yes | Basic | +| Room | Yes | | + +Delete the auth token in the `Authorization` header. + +**Response:** + +``` +{ + status_code: u16 +} +``` + +### POST /compact_poll +| Header | Required | Notes | +| ------------- | -------- | -------------------------------------------------------------------- | +| Authorization | No | Authorization is handled on a room-by-room basis in the request body | +| Room | No | | + +Poll for new messages, new deletions and the current moderator list for multiple rooms all in one request. + +**Expected body:** + +``` +{ + requests: [ + { + room_id: String, + auth_token: String, + from_deletion_server_id: Option, + from_message_server_id: Option + }, + { + ... + } + ] +} +``` + +**Response:** + +``` +{ + status_code: u16 + results: [ + { + room_id: String, + status_code: u16, + deletions: [ 0, 1, 2, ... ] + messages: [ + { + server_id: i64, + public_key: String, + timestamp: i64, + data: String, + signature: String + }, + { + ... + } + ] + moderators: [ "public_key_0", "public_key_1", "public_key_2", ... ] + }, + { + ... + } + ] +} +``` + +### POST /messages + +| Header | Required | Notes | +| ------------- | -------- | ----- | +| Authorization | Yes | Basic | +| Room | Yes | | + +Store the given message on the server. + +**Expected body:** + +``` +{ + public_key: Option, // the public key of the sender + timestamp: i64, // the sent timestamp of the message + data: String, // the serialized protobuf + signature: String // the base64 encoded message signature +} +``` + +**Response:** + +``` +{ + status_code: u16 + message: { + server_id: String, + public_key: Option + timestamp: i64 + data: String + signature: String + } +} +``` + +### GET /messages?from_server_id=i64&limit=u16 + +| Header | Required | Notes | +| ------------- | -------- | ----- | +| Authorization | Yes | Basic | +| Room | Yes | | + +Get messages from the server. If `from_server_id` is set only messages stored after that server ID are returned (limited to a maximum of 256 messages). Otherwise, if `limit` is set, the last `limit` messages stored on the server are returned (limited to a maximum of 256 messages). + +**Response:** + +``` +{ + status_code: u16, + messages: [ + { + server_id: String, + public_key: Option, // the public key of the sender + timestamp: i64, // the sent timestamp of the message + data: String, // the serialized protobuf + signature: String // the base64 encoded message signature + }, + ... + ] +} +``` + +### DELETE /messages/:message_id + +| Header | Required | Notes | +| ------------- | -------- | ------------------ | +| Authorization | Yes | Basic OR Moderator | +| Room | Yes | | + +Delete the message with the given ID from the server. The requesting user must either be the sender of the message or have moderation permission. + +**Response:** + +``` +{ + status_code: u16 +} +``` + +### GET /deleted_messages?from_server_id=i64&limit=u16 + +| Header | Required | Notes | +| ------------- | -------- | ----- | +| Authorization | Yes | Basic | +| Room | Yes | | + +Get deleted messages from the server. If `from_server_id` is set only deletions that happened after that server ID are returned (limited to a maximum of 256 deletions). Otherwise, if `limit` is set, the last `limit` deletions stored on the server are returned (limited to a maximum of 256 deletions). + +**Response:** + +``` +{ + status_code: u16, + ids: [ 0, 1, 2, ... ] // the server IDs of the deleted messages +} +``` + +### GET /moderators + +| Header | Required | Notes | +| ------------- | -------- | ----- | +| Authorization | Yes | Basic | +| Room | Yes | | + +Get the full list of moderators. + +**Response:** + +``` +{ + status_code: u16, + moderators: [ "public_key_0", "public_key_1", "public_key_2", ... ] +} +``` + +### POST /block_list + +| Header | Required | Notes | +| ------------- | -------- | --------- | +| Authorization | Yes | Moderator | +| Room | Yes | | + +Ban the given public key from the server. + +**Expected body:** + +``` +{ + public_key: String +} +``` + +**Response:** + +``` +{ + status_code: u16 +} +``` + +### DELETE /block_list/:public_key + +| Header | Required | Notes | +| ------------- | -------- | --------- | +| Authorization | Yes | Moderator | +| Room | Yes | | + +Unban the given public key from the server. + +**Response:** + +``` +{ + status_code: u16 +} +``` + +### GET /block_list + +| Header | Required | Notes | +| ------------- | -------- | ----- | +| Authorization | Yes | Basic | +| Room | Yes | | + +Get the full list of banned public_keys. + +**Response:** + +``` +{ + status_code: u16, + moderators: [ "public_key_0", "public_key_1", "public_key_2", ... ] +} +``` + +### GET /member_count + +| Header | Required | Notes | +| ------------- | -------- | ----- | +| Authorization | Yes | Basic | +| Room | Yes | | + +Get the member count for the given room. + +**Response:** + +``` +{ + status_code: u16, + member_count: usize +} +```