From c8c4c705a5c2a597b92e365a06c6ca26263bbfe2 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Sat, 4 Mar 2023 20:26:16 +0000 Subject: [PATCH] Convert proposals to man pages. --- TODO.txt | 2 +- proposals/1.md | 433 -------------------------------------------- proposals/admin.7 | 446 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 447 insertions(+), 434 deletions(-) delete mode 100644 proposals/1.md create mode 100644 proposals/admin.7 diff --git a/TODO.txt b/TODO.txt index cefa19a..22898f5 100644 --- a/TODO.txt +++ b/TODO.txt @@ -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 ----------------- diff --git a/proposals/1.md b/proposals/1.md deleted file mode 100644 index e5d70de..0000000 --- a/proposals/1.md +++ /dev/null @@ -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." -} -``` - diff --git a/proposals/admin.7 b/proposals/admin.7 new file mode 100644 index 0000000..eff0ce8 --- /dev/null +++ b/proposals/admin.7 @@ -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