tallship/telodendria
1
0
Fork 0
forked from Telodendria/Telodendria
Code Issues Pull requests Projects Releases Packages Wiki Activity
telodendria/proposals/1.md
Jordan Bancino 58dae3a0c9 Remove user create Admin endpoint, and the associated privilege. 
If an admin wants to create a user, he or she should have the ISSUE_TOKEN
privilege. The admin can use that to create a one-time registration token,
and then just use the regular registration API with that token.
2023-02-27 18:02:35 +00:00

14 KiB
Raw Blame History

#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.

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "tokens": [
    {
      "name": "forbob",
      "created_by": "alice",
      "created_on": 1234567890123,
      "expires_on": 2147483647000,
      "used": 1,
      "uses": 3
    }
  ]
}

403 Response JSON Format:

{
  "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:

{
  "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:

{
  "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:

{
  "name": "OnlyClownsM7iAhUJD",
  "created_by": "donald",
  "created_on": 1234567890123,
  "expires_on": 2147484637000,
  "used": 0,
  "uses": 5
}

403 Response JSON Format:

{
  "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:

{
  "errcode": "M_FORBIDDEN",
  "error": "Forbidden access. Bad permissions or not authenticated."
}