Convert proposals to man pages.

This commit is contained in:
Jordan Bancino 2023-03-04 20:26:16 +00:00
parent 8c2ed1c8f1
commit c8c4c705a5
3 changed files with 447 additions and 434 deletions

View file

@ -28,7 +28,7 @@ Milestone: v0.2.0
[ ] Db functions
[ ] Uia (move docs from Matrix)
[ ] Convert proposals to man pages
[x] Convert proposals to man pages
Milestone: v0.3.0
-----------------

View file

@ -1,433 +0,0 @@
# #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 /_telodendria/admin/disable/[localpart] endpoint
- ISSUE_TOKENS:
This allows users to create, modify and delete registration
tokens.
- 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 `/_telodendria/admin/privileges`
Get the priviledges of the user that owns the provided access token.
|Requires token|Rate limited|
|--------------|------------|
|YES |YES |
|Error response|Description |
|--------------|------------------------|
|200 |Privileges successfully |
| |returned. |
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 `/_telodendria/admin/deactivate/[localpart]`
Deactivates a local user, optionally with a reason.
|Requires token|Rate limited|Permissions|
|--------------|------------|-----------|
|YES |YES |DEACTIVATE |
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 `/_telodendria/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 `/_telodendria/admin/tokens`
Gets a list of *all* tokens present, and additional information.
|Requires token|Rate limited|Permissions |
|--------------|------------|------------|
|YES |YES |ISSUE_TOKENS|
|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 `/_telodendria/admin/tokens/[token]`
Returns information about a specific registration token.
|Requires token|Rate limited|Permissions |
|--------------|------------|------------|
|YES |YES |ISSUE_TOKENS|
|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 `/_telodendria/admin/tokens`
Adds a registration token, and setup expiry date and max uses.
|Requires token|Rate limited|Permissions |
|--------------|------------|------------|
|YES |YES |ISSUE_TOKENS|
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 /_telodendria/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."
}
```

446
proposals/admin.7 Normal file
View file

@ -0,0 +1,446 @@
.Dd $Mdocdate: March 4 2023 $
.Dt ADMIN 7
.Os Telodendria Project
.Sh NAME
.Nm Admin
.Nd Suggestion on a Telodendria Admin API
.Sh DESCRIPTION
.Pp
This is a suggestion of how the admin API should work; it is subject
to heavy changes.
.Pp
It also acts as a suggestion on how suggestions should be written. It
might not be accepted, or the format might be changed heavily.
.Ss Admin Users
.Pp
Like in Synapse, there should be a field dictating if the user is an
admin, and unlike Synapse, there should be privilege levels.
.Pp
In the
.Pa users/[user].json
file, there should be a field called
.Dv privileges
which contains a list of strings.
.Bd -literal -offset indent
{
"devices": {
"foobar": { ... }
},
"salt": "salt goes here",
"deactivated": false,
"createdOn": 1700000000000,
"password": "hash goes here",
"privileges": [
"DEACTIVATE",
"ISSUE_TOKENS"
]
}
.Ed
.Ss Privileges list
.Pp
Here are all of the admin privileges a user can have:
.Bl -tag -width Ds
.It Dv DEACTIVATE
This allows an user to deactivate any users using
the
.Dv DELETE /_telodendria/admin/disable/[localpart]
endpoint.
.It Dv ISSUE_TOKENS
This allows users to create, modify and delete registration
tokens.
.It Dv ALL
Users with this privilege can use
.Em any
admin endpoint(and some others).
.Em THIS PRIVILEGE SHOULD ONLY BE USED WITH TRUSTED USERS.
.Sh API ENDPOINTS
.Ss GET /_telodendria/admin/privileges
.Pp
Get the priviledges of the user that owns the provided access token.
.Pp
.TS
tab(;) allbox center;
l l.
Requires Token;Rate Limited
Yes;Yes
.TE
.Pp
.TS
tab(;) allbox center;
l l.
Error Response;Description
200;Privileges successfully returned.
.TE
.Pp
200 Response JSON Format:
.Pp
.TS
tab(;) allbox center;
l l l.
Field;Type;Description
privileges;list;The same data structure described in the database.
.TE
.Pp
200 Response Example:
.Bd -literal -offset indent
{
"privileges": [
"DEACTIVATE",
"REMOVE_DEVICES"
]
}
.Ed
.Ss DELETE /_telodendria/admin/deactivate/[localpart]
.Pp
Deactivates a local user, optionally with a reason.
.Pp
.TS
tab(;) allbox center;
l l l.
Requires Token;Rate Limited;Permissions
Yes;Yes;DEACTIVATE
.TE
.Pp
Request JSON Format:
.Pp
.TS
tab(;) allbox center;
l l l l.
Field;Type;Description;Required
reason;string;A reason why the user was deactivated;No
.TE
.Pp
Request Example:
.Bd -literal -offset indent
{
"reason": "Being mean in a lot of rooms."
}
.Ed
.Pp
.TS
tab(;) allbox center;
l l.
Error Response;Description
200;User was successfully deactivated.
403;User does not have the DEACTIVATE permission.
.TE
.Pp
200 Response JSON Format:
.Pp
.TS
tab(;) allbox center;
l l l.
Field;Type;Description
user;localpart;The deactivated user's localpart
reason;string;T{
The reason why the user was deactivated.
Defaults to: ``Deactivated by admin''
T}
banned_by;localpart;T{
The localpart of the admin who deactivated the user.
T}
.TE
.Pp
403 Response JSON Format:
.Pp
.TS
tab(;) allbox center;
l l l.
Field;Type;Description
errcode;string;Set to ``M_FORBIDDEN''
error;string;Human-readable explanation of the privilege issue.
.TE
.Pp
200 Response Example:
.Bd -literal -offset indent
{
"user": "evan",
"reason": "Being mean in a lot of rooms",
"banned_by": "alice"
}
.Ed
.Pp
403 Response Example:
.Bd -literal -offset indent
{
"errcode": "M_FORBIDDEN",
"error": "Forbidden access. Bad permissions or not authenticated."
}
.Ed
.Ss PUT /_telodendria/admin/deactivate/[localpart]
.TS
tab(;) allbox center;
l l.
Requires Token;Rate Limited;Permissions
Yes;Yes;DEACTIVATE
.TE
.Pp
.Em Description:
Reactivates a local user.
.Pp
.TS
tab(;) allbox center;
l l.
Error Response;Description
204;User was successfully reactivated.
403;User does not have the DEACTIVATE permission.
.TE
.Pp
403 Response JSON Format:
.Pp
.TS
tab(;) allbox center;
l l l.
Field;Type;Description
errcode;string;Set to ``M_FORBIDDEN''
error;string;Human-readable explanation of the privilege issue.
.TE
.Pp
403 Response Example:
.Bd -literal -offset indent
{
"errcode": "M_FORBIDDEN",
"error": "Forbidden access. Bad permissions or not authenticated."
}
.Ed
.Ss GET /_telodendria/admin/tokens
.Pp
Gets a list of
.Em all
tokens present, and additional information.
.Pp
.TS
tab(;) allbox center;
l l l.
Requires Token;Rate Limited;Permissions
Yes;Yes;ISSUE_TOKENS
.TE
.Pp
.TS
tab(;) allbox center;
l l.
Error Response;Description
200;Token list was successfully retrieved.
403;User does not have the ISSUE_TOKENS permission.
.TE
.Pp
200 Response JSON Format:
.Pp
.TS
tab(;) allbox center;
l l l.
Field;Type;Description
tokens;list[TokenInfo];A list of tokens and other information.
.TE
.Pp
.Dv TokenInfo
JSON Format:
.Pp
.TS
tab(;) allbox center;
l l l.
Field;Type;Description
name;string;The token's name.
created_by;localpart; The user who has created token.
created_on;timestamp;The creation date of the token.
expires_on;timestamp;T{
The token's expiration date, or 0 if it does not
expire.
T}
used;integer;The number of times the token was used.
uses;integer;T{
The number of uses remaining for the token, or -1 if
there are an unlimited number of uses remaining.
.TE
.Pp
403 Response JSON Format:
.Pp
.TS
tab(;) allbox center;
l l l.
Field;Type;Description
errcode;string;Set to ``M_FORBIDDEN''
error;string;Human-readable explanation of the privilege issue.
.TE
.Pp
200 Response Example:
.Bd -literal -offset indent
{
"tokens": [
{
"name": "forbob",
"created_by": "alice",
"created_on": 1234567890123,
"expires_on": 2147483647000,
"used": 1,
"uses": 3
}
]
}
.Ed
.Pp
403 Response JSON Format:
.Bd -literal -offset indent
{
"errcode": "M_FORBIDDEN",
"error": "Forbidden access. Bad permissions or not authenticated."
}
.Ed
.Ss GET /_telodendria/admin/tokens/[token]
.Pp
Returns information about a specific registration token.
.Pp
.TS
tab(;) allbox center;
l l l.
Requires Token;Rate Limited;Permissions
Yes;Yes;ISSUE_TOKENS
.TE
.Pp
.TS
tab(;) allbox center;
l l.
Error Response;Description
200;Token information successfully retrieved.
403;User does not have the ISSUE_TOKENS permission.
404;The specified token does not exist.
.TE
.Pp
200 Response JSON Format:
.Pp
.TS
tab(;) allbox center;
l l l.
Field;Type;Description
name;string;The token's name.
created_by;localpart;The user who created the token.
created_on;timestamp;The creation date of the token.
expires_on;timestamp;The token's expiration date, if provided.
used;integer;The number of times the token was used.
uses;integer;T{
The number of remaining uses for the token, if set.
Otherwise, there are unlimited uses remaining.
T}
.TE
.Pp
200 Response Example:
.Bd -literal -offset indent
{
"name": "forbob",
"created_by": "alice",
"created_on": 1234567890123,
"used": 1,
"uses": 3
}
.Ed
.Ss POST /_telodendria/admin/tokens
.Pp
Adds a registration token, and setup expiry date and max uses.
.Pp
.TS
tab(;) allbox center;
l l l.
Requires Token;Rate Limited;Permissions
Yes;Yes;ISSUE_TOKENS
.TE
.Pp
Request JSON Format:
.Pp
.TS
tab(;) allbox center;
l l l l.
Field;Type;Description;Required
lifetime;timestamp;T{
How long this token should be good for
T};NO
max_uses;integer;T{
The maximum number of uses for this token
T};NO
name;string;T{
A name for the token. If none is provided, then a name
is randomly generated.
T};NO
.TE
.Pp
Request Example:
.Bd -literal -offset indent
{
"name": "OnlyClownsM7iAhUJD",
"expires": 2147484637000,
"max_uses": 5
}
.Ed
.Pp
.TS
tab(;) allbox center;
l l.
Error Response;Description
200;Token was successfully created.
403;User does not have the ISSUE_TOKENS permission.
.TE
.Pp
200 Response JSON Format:
.Pp
.TS
tab(;) allbox center;
l l l.
Field;Type;Description
name;string;The token's name.
created_by;localpart;The user who created the token.
created_on;timestamp;The creation date of the token.
expires_on;timestamp;T{
The token's expiration date, if set. If not set, the
token never expires.
T}
used;integer;The number of times the token was used.
uses;integer;T{
The number of uses remaining for the token, if set. If
not set, the token has an unlimited number of uses.
T}
.TE
.Pp
200 Response Example:
.Bd -literal -offset indent
{
"name": "OnlyClownsM7iAhUJD",
"created_by": "donald",
"created_on": 1234567890123,
"expires_on": 2147484637000,
"used": 0,
"uses": 5
}
.Ed
.Pp
403 Response JSON Format:
.Bd -literal -offset indent
{
"errcode": "M_FORBIDDEN",
"error": "Forbidden access. Bad permissions or not authenticated."
}
.Ed
.Ss DELETE /_telodendria/admin/tokens/[tokenname]
.TS
tab(;) allbox center;
l l l.
Requires Token;Rate Limited;Permissions
Yes;Yes;ISSUE_TOKENS
.TE
.Pp
.Em Description:
Deletes an existing registration token.
.Pp
.TS
tab(;) allbox center;
l l.
Error Response;Description
204;Token was successfully deleted.
403;User does not have the ISSUE_TOKENS permission.
.TE
.Pp
403 Response JSON Format:
.Bd -literal -offset indent
{
"errcode": "M_FORBIDDEN",
"error": "Forbidden access. Bad permissions or not authenticated."
}
.Ed