forked from lda/telodendria
Apply #45
This commit is contained in:
parent
5b77236e82
commit
a4ec6cf6c7
1 changed files with 484 additions and 0 deletions
484
proposals/1.md
Normal file
484
proposals/1.md
Normal file
|
|
@ -0,0 +1,484 @@
|
|||
# #1: Suggestion on a Telodendria Admin API.
|
||||
This is a suggestion of how the admin API should work; it is subject to
|
||||
heavy changes.
|
||||
|
||||
It also acts as a suggestion on how suggestions should be written. It
|
||||
might not be accepted, or the format might be changed heavily.
|
||||
|
||||
## "Admin" users.
|
||||
Like in Synapse, there should be a field dictating if the user is an
|
||||
admin, and unlike Synapse, there should be privilege levels.
|
||||
|
||||
In the `[dataroot]/users/[user].json` file, there should be a field
|
||||
called `"privileges"` which contains a list of strings.
|
||||
|
||||
```json
|
||||
{
|
||||
"devices": {
|
||||
"foobar": { ... }
|
||||
},
|
||||
"salt": "salt goes here",
|
||||
"deactivated": false,
|
||||
"createdOn": 1700000000000,
|
||||
"password": "hash goes here",
|
||||
"privileges": [
|
||||
"DEACTIVATE",
|
||||
"ISSUE_TOKENS"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Privileges list
|
||||
Here are all of the admin privileges a user can have:
|
||||
|
||||
- DEACTIVATE:
|
||||
This allows an user to deactivate/reactivate any users using
|
||||
the DELETE /_admin/disable/[localpart] endpoint
|
||||
|
||||
- ISSUE_TOKENS:
|
||||
This allows users to create, modify and delete registration
|
||||
tokens.
|
||||
|
||||
- CREATE_USERS:
|
||||
Allows users with such privilege to create new users even if
|
||||
registration is completely turned off.
|
||||
|
||||
- ALL:
|
||||
Users with this privilege can use *any* admin endpoint(and some
|
||||
others)
|
||||
|
||||
**THIS PRIVILEGE SHOULD ONLY BE USED WITH *TRUSTED* USERS.**
|
||||
|
||||
## Admin endpoints
|
||||
|
||||
### GET `/_admin/privileges`
|
||||
|
||||
|Requires token|Rate limited|
|
||||
|--------------|------------|
|
||||
|YES |YES |
|
||||
|
||||
|
||||
|Error response|Description |
|
||||
|--------------|------------------------|
|
||||
|200 |User was sucessfully |
|
||||
| |deactivated. |
|
||||
|
||||
200 Response JSON Format:
|
||||
|
||||
|Field |Type |Description |
|
||||
|-----------|-----------|-------------------------------------------------|
|
||||
|privileges |list |The same data structure as in `users/[user].json`|
|
||||
|
||||
200 Response Example:
|
||||
```json
|
||||
{
|
||||
"privileges": [
|
||||
"DEACTIVATE",
|
||||
"REMOVE_DEVICES"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### DELETE `/_admin/deactivate/[localpart]`
|
||||
|
||||
|Requires token|Rate limited|Permissions|
|
||||
|--------------|------------|-----------|
|
||||
|YES |YES |DEACTIVATE |
|
||||
|
||||
Description:
|
||||
Deactivates a local user, optionally with a reason.
|
||||
|
||||
Request JSON Format:
|
||||
|
||||
|Field |Type |Description |Required|
|
||||
|-----------|-----------|---------------------|--------|
|
||||
|reason |string |A reason why the |NO |
|
||||
| | |user was deactivated.| |
|
||||
|
||||
Request Example:
|
||||
```json
|
||||
{
|
||||
"reason": "Being mean in a lot of rooms."
|
||||
}
|
||||
```
|
||||
|
||||
|Error response|Description |
|
||||
|--------------|------------------------|
|
||||
|200 |User was sucessfully |
|
||||
| |deactivated. |
|
||||
|--------------|------------------------|
|
||||
|403 |User does not have the |
|
||||
| |DEACTIVATE permission |
|
||||
|
||||
200 Response JSON Format:
|
||||
|
||||
|Field |Type |Description |
|
||||
|-----------|-----------|-----------------------|
|
||||
|user |localpart |The deactivated user's |
|
||||
| | |localpart |
|
||||
|-----------|-----------|-----------------------|
|
||||
|reason |string |The reason the user |
|
||||
| | |was deactivacted. |
|
||||
| | |Defaults to: |
|
||||
| | |"Deactivated by admin" |
|
||||
|-----------|-----------|-----------------------|
|
||||
|banned_by |localpart |The localpart of the |
|
||||
| | |admin who deactivated |
|
||||
| | |the user.
|
||||
|
||||
403 Response JSON Format:
|
||||
|
||||
|Field |Type |Description |
|
||||
|-----------|-----------|-----------------------|
|
||||
|errcode |string |Set to "M_FORBIDDEN" |
|
||||
|-----------|-----------|-----------------------|
|
||||
|error |string |Human-readable explain-|
|
||||
| | |ation of the privilege |
|
||||
| | |issue. |
|
||||
|
||||
200 Response Example:
|
||||
```json
|
||||
{
|
||||
"user": "evan",
|
||||
"reason": "Being mean in a lot of rooms",
|
||||
"banned_by": "alice"
|
||||
}
|
||||
```
|
||||
|
||||
403 Response Example:
|
||||
```
|
||||
{
|
||||
"errcode": "M_FORBIDDEN",
|
||||
"error": "Forbidden access. Bad permissions or not authenticated."
|
||||
}
|
||||
```
|
||||
|
||||
### PUT `/_admin/deactivate/[localpart]`
|
||||
|
||||
|Requires token|Rate limited|Permissions|
|
||||
|--------------|------------|-----------|
|
||||
|YES |YES |DEACTIVATE |
|
||||
|
||||
Description:
|
||||
Reactivates a local user.
|
||||
|
||||
|Error response|Description |
|
||||
|--------------|------------------------|
|
||||
|204 |User was sucessfully |
|
||||
| |reactivated. |
|
||||
|--------------|------------------------|
|
||||
|403 |User does not have the |
|
||||
| |DEACTIVATE permission |
|
||||
|
||||
403 Response JSON Format:
|
||||
|
||||
|Field |Type |Description |
|
||||
|-----------|-----------|-----------------------|
|
||||
|errcode |string |Set to "M_FORBIDDEN" |
|
||||
|-----------|-----------|-----------------------|
|
||||
|error |string |Human-readable explain-|
|
||||
| | |ation of the privilege |
|
||||
| | |issue. |
|
||||
|
||||
403 Response Example:
|
||||
```
|
||||
{
|
||||
"errcode": "M_FORBIDDEN",
|
||||
"error": "Forbidden access. Bad permissions or not authenticated."
|
||||
}
|
||||
```
|
||||
|
||||
### GET `/_admin/tokens`
|
||||
|
||||
|Requires token|Rate limited|Permissions |
|
||||
|--------------|------------|------------|
|
||||
|YES |YES |ISSUE_TOKENS|
|
||||
|
||||
Description:
|
||||
Gets a list of *all* tokens present, and additional information.
|
||||
|
||||
|
||||
|Error response|Description |
|
||||
|--------------|---------------------------|
|
||||
|200 |Token list was sucessfully |
|
||||
| |retrieved |
|
||||
|--------------|---------------------------|
|
||||
|403 |User does not have the |
|
||||
| |ISSUE_TOKENS permission. |
|
||||
|
||||
200 Response JSON Format:
|
||||
|
||||
|Field |Type |Description |
|
||||
|-----------|----------------------|-----------------------|
|
||||
|tokens |list[`TokenInfo`] |A list of tokens and |
|
||||
| | |other information. |
|
||||
|
||||
`TokenInfo` JSON Format:
|
||||
|
||||
|Field |Type |Description |
|
||||
|-----------|----------------------|-------------------------|
|
||||
|name |string |The token's name. |
|
||||
|-----------|----------------------|-------------------------|
|
||||
|created_by |localpart |The user who has created |
|
||||
| | |the token's localpart |
|
||||
|-----------|----------------------|-------------------------|
|
||||
|created_on |timestamp |The creation date of the |
|
||||
| | |token. |
|
||||
|-----------|----------------------|-------------------------|
|
||||
|expires_on |timestamp |The token's expiry date |
|
||||
| | |NOTE: If token does not |
|
||||
| | |expire, it is set to 0 |
|
||||
|-----------|----------------------|-------------------------|
|
||||
|used |integer |The number of times the |
|
||||
| | |token was used |
|
||||
|-----------|----------------------|-------------------------|
|
||||
|uses |integer |The number of uses for a |
|
||||
| | |token. |
|
||||
| | |NOTE: If token has unli- |
|
||||
| | |mited mumber of uses, |
|
||||
| | |set to 0 |
|
||||
|
||||
403 Response JSON Format:
|
||||
|
||||
|Field |Type |Description |
|
||||
|-----------|-----------|-----------------------|
|
||||
|errcode |string |Set to "M_FORBIDDEN" |
|
||||
|-----------|-----------|-----------------------|
|
||||
|error |string |Human-readable explain-|
|
||||
| | |ation of the privilege |
|
||||
| | |issue. |
|
||||
|
||||
200 Response Example:
|
||||
```json
|
||||
{
|
||||
"tokens": [
|
||||
{
|
||||
"name": "forbob",
|
||||
"created_by": "alice",
|
||||
"created_on": 1234567890123,
|
||||
"expires_on": 2147483647000,
|
||||
"used": 1,
|
||||
"uses": 3
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
403 Response JSON Format:
|
||||
```json
|
||||
{
|
||||
"errcode": "M_FORBIDDEN",
|
||||
"error": "Forbidden access. Bad permissions or not authenticated."
|
||||
}
|
||||
```
|
||||
|
||||
### GET `/_admin/tokens/[token]`
|
||||
|
||||
|Requires token|Rate limited|Permissions |
|
||||
|--------------|------------|------------|
|
||||
|YES |YES |ISSUE_TOKENS|
|
||||
|
||||
Description:
|
||||
Returns information about a specific registration token.
|
||||
|
||||
|error response|description |
|
||||
|--------------|---------------------------|
|
||||
|200 |token info was sucessfully |
|
||||
| |retrieved |
|
||||
|--------------|---------------------------|
|
||||
|403 |user does not have the |
|
||||
| |ISSUE_TOKENS permission. |
|
||||
|--------------|---------------------------|
|
||||
|404 |Token does not exist. |
|
||||
|
||||
200 Response JSON Format:
|
||||
|
||||
|Field |Type |Description |
|
||||
|-----------|----------------------|-------------------------|
|
||||
|name |string |The token's name. |
|
||||
|-----------|----------------------|-------------------------|
|
||||
|created_by |localpart |The user who has created |
|
||||
| | |the token's localpart |
|
||||
|-----------|----------------------|-------------------------|
|
||||
|created_on |timestamp |The creation date of the |
|
||||
| | |token. |
|
||||
|-----------|----------------------|-------------------------|
|
||||
|expires_on |timestamp |The token's expiry date |
|
||||
| | |NOTE: If token does not |
|
||||
| | |expire, it is not set. |
|
||||
|-----------|----------------------|-------------------------|
|
||||
|used |integer |The number of times the |
|
||||
| | |token was used |
|
||||
|-----------|----------------------|-------------------------|
|
||||
|uses |integer |The number of uses for |
|
||||
| | |the token. |
|
||||
| | |NOTE: If token has unli- |
|
||||
| | |mited mumber of uses, it |
|
||||
| | |is not set. |
|
||||
|
||||
200 Response Example:
|
||||
```json
|
||||
{
|
||||
"name": "forbob",
|
||||
"created_by": "alice",
|
||||
"created_on": 1234567890123,
|
||||
"used": 1,
|
||||
"uses": 3
|
||||
}
|
||||
```
|
||||
|
||||
### POST `/_admin/tokens`
|
||||
|
||||
|Requires token|Rate limited|Permissions |
|
||||
|--------------|------------|------------|
|
||||
|YES |YES |ISSUE_TOKENS|
|
||||
|
||||
Description:
|
||||
Adds a registration token, and setup expiry date and max uses.
|
||||
|
||||
Request JSON Format:
|
||||
|
||||
|Field |Type |Description |Required|
|
||||
|-----------|-----------|----------------------|--------|
|
||||
|expires |timestamp |The timestamp for this|NO |
|
||||
| | |token's expiry. | |
|
||||
|-----------|-----------|----------------------|--------|
|
||||
|max_uses |integer |The maximum number of |NO |
|
||||
| | |uses for this token | |
|
||||
|-----------|-----------|----------------------|--------|
|
||||
|name |string |A name for the token. |NO |
|
||||
| | |If none is set, a ran-| |
|
||||
| | |domly generated string| |
|
||||
| | |is made. | |
|
||||
|
||||
Request Example:
|
||||
```json
|
||||
{
|
||||
"name": "OnlyClownsM7iAhUJD",
|
||||
"expires": 2147484637000,
|
||||
"max_uses": 5
|
||||
}
|
||||
```
|
||||
|
||||
|Error response|Description |
|
||||
|--------------|---------------------------|
|
||||
|200 |Token was sucessfully crea-|
|
||||
| |ted |
|
||||
|--------------|---------------------------|
|
||||
|403 |User does not have the |
|
||||
| |ISSUE_TOKENS permission. |
|
||||
|
||||
200 Response JSON Format:
|
||||
|
||||
|Field |Type |Description |
|
||||
|-----------|----------------------|-------------------------|
|
||||
|name |string |The token's name. |
|
||||
|-----------|----------------------|-------------------------|
|
||||
|created_by |localpart |The user who has created |
|
||||
| | |the token's localpart |
|
||||
|-----------|----------------------|-------------------------|
|
||||
|created_on |timestamp |The creation date of the |
|
||||
| | |token. |
|
||||
|-----------|----------------------|-------------------------|
|
||||
|expires_on |timestamp |The token's expiry date |
|
||||
| | |NOTE: If token does not |
|
||||
| | |expire, it is not set. |
|
||||
|-----------|----------------------|-------------------------|
|
||||
|used |integer |The number of times the |
|
||||
| | |token was used |
|
||||
|-----------|----------------------|-------------------------|
|
||||
|uses |integer |The number of uses for |
|
||||
| | |the token. |
|
||||
| | |NOTE: If token has unli- |
|
||||
| | |mited mumber of uses, it |
|
||||
| | |is not set. |
|
||||
|
||||
200 Response Example:
|
||||
```json
|
||||
{
|
||||
"name": "OnlyClownsM7iAhUJD",
|
||||
"created_by": "donald",
|
||||
"created_on": 1234567890123,
|
||||
"expires_on": 2147484637000,
|
||||
"used": 0,
|
||||
"uses": 5
|
||||
}
|
||||
```
|
||||
|
||||
403 Response JSON Format:
|
||||
```json
|
||||
{
|
||||
"errcode": "M_FORBIDDEN",
|
||||
"error": "Forbidden access. Bad permissions or not authenticated."
|
||||
}
|
||||
```
|
||||
|
||||
### DELETE /_admin/tokens/[tokenname]
|
||||
|
||||
|Requires token|Rate limited|Permissions |
|
||||
|--------------|------------|------------|
|
||||
|YES |YES |ISSUE_TOKENS|
|
||||
|
||||
Description:
|
||||
Deletes an existing registration token.
|
||||
|
||||
|Error response|Description |
|
||||
|--------------|---------------------------|
|
||||
|204 |Token was sucessfully dele-|
|
||||
| |ted |
|
||||
|--------------|---------------------------|
|
||||
|403 |User does not have the |
|
||||
| |ISSUE_TOKENS permission. |
|
||||
|
||||
403 Response JSON Format:
|
||||
```json
|
||||
{
|
||||
"errcode": "M_FORBIDDEN",
|
||||
"error": "Forbidden access. Bad permissions or not authenticated."
|
||||
}
|
||||
```
|
||||
|
||||
### POST /_admin/user/create
|
||||
|
||||
|Requires token|Rate limited|Permissions |
|
||||
|--------------|------------|------------|
|
||||
|YES |YES |CREATE_USERS|
|
||||
|
||||
Description:
|
||||
Creates a new user with password login.
|
||||
**NOTE**: This does not make the user login.
|
||||
|
||||
Request JSON Format:
|
||||
|
||||
|Field |Type |Description |Required|
|
||||
|-------------|-----------|----------------------|--------|
|
||||
|name |localpart |The created user's lo-|YES |
|
||||
| | |calpart. | |
|
||||
|-------------|-----------|----------------------|--------|
|
||||
|password |string |The created user's |YES |
|
||||
| | |password. | |
|
||||
|
||||
Request Example:
|
||||
```json
|
||||
{
|
||||
"name": "edward",
|
||||
"password": "verysecurepassworddontworryaboutittoomuch"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|Error response|Description |
|
||||
|--------------|-----------------------------|
|
||||
|204 |User was sucessfully created.|
|
||||
|--------------|-----------------------------|
|
||||
|403 |User does not have the |
|
||||
| |CREATE_USERS permission. |
|
||||
|
||||
403 Response JSON Format:
|
||||
|
||||
```json
|
||||
{
|
||||
"errcode": "M_FORBIDDEN",
|
||||
"error": "Forbidden access. Bad permissions or not authenticated."
|
||||
}
|
||||
```
|
||||
Loading…
Reference in a new issue