oxen-io
/
session-open-group-server
mirror of https://github.com/oxen-io/session-open-group-server.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Include docs directly (wikis don't carry across forks)

This commit is contained in:
Niels Andriesse 2021-04-23 14:03:26 +10:00
parent 421d5f0c94
commit d5d618e3ab
2 changed files with 463 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
CLI.md Normal file
View File

@ -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
```

448
DOCUMENTATION.md Normal file
View File

@ -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<i64>,
from_message_server_id: Option<i64>
},
{
...
}
]
}
```
**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<String>, // 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<String>
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<String>, // 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
}
```