From 043c2e9e3338c102ae0ed856a4fa4b321f7c81db Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Fri, 8 Sep 2023 23:26:47 -0400 Subject: [PATCH] Add privileges documentation. --- docs/user/admin/README.md | 14 ++++ docs/user/admin/privileges.md | 141 ++++++++++++++++++++++++++++++++++ 2 files changed, 155 insertions(+) create mode 100644 docs/user/admin/privileges.md diff --git a/docs/user/admin/README.md b/docs/user/admin/README.md index de5f617..827ef10 100644 --- a/docs/user/admin/README.md +++ b/docs/user/admin/README.md @@ -20,3 +20,17 @@ request. - [Server Statistics](stats.md) - [Process Control](proc.md) +## API Conventions + +Unless otherwise indicated, HTTP response codes that are not `200 Ok` +will be accompanied by a standard Matrix API error. Consult the Matrix +specification for the format of these errors. The following error +conditions are assumed to be possible for all API endpoints listed +in the Administrator API documentation: + +| Response Code | Description | +|---------------|-------------| +| 400 | The user is not authenticated, did not provide a valid JSON object, or provided a JSON object with invalid or missing parameters.| +| 403 | The user does not have the privileges necessary to carry out the requested action.| +| 500 | A fatal server error occurred. Check the logs for more information.| + diff --git a/docs/user/admin/privileges.md b/docs/user/admin/privileges.md new file mode 100644 index 0000000..35dea36 --- /dev/null +++ b/docs/user/admin/privileges.md @@ -0,0 +1,141 @@ +# Administrator API: Privileges + +This document describes the privilege model and the API endpoints that +allow administrators to modify privileges for users. + +## List Of Privileges + +A local user can have any of the following privileges. Unless otherwise +indicated, these privileges only grant access to certain parts of the +administrator API; the regular Matrix API is unaffected. + +- **DEACTIVATE:** Allows a user to deactivate any other local users. +- **ISSUE_TOKENS:** Allows a user to create, modify, and delete +registration tokens. +- **CONFIG:** Allows a user to modify the Telodendria server daemon's +configuration. +- **GRANT_PRIVILEGES:** Allows a user to modify his or her own +privileges or the privileges of other local users. +- **ALIAS:** Allows a user to modify room aliases created by other +users. By default, users can only manage their own room aliases, but +an administrator may wish to take over an alias or remove an offensive +alias. +- **PROC_CONTROL:** Allows a user to get statistics on the running +process, as well as shutdown and resetart the Telodendria daemon +itself. Typically this will pair well with **CONFIG**, because there +are certain configuration options that require the process to be +restarted to take full effect. + +There is also a special "pseudo-privilege": + +- **ALL:* Grants a user all of the aforementioned privileges, as well +as privileges that do not yet exist. That is, if an update to +Telodendria adds more privileges, users with this privilege will +automatically gain those new privileges in addition to having all the +existing privileges. This privilege should only be used with +fully-trusted users. It is typical for a server administrator to not +fully trust anyone else, and be the only one that holds an account with +this privilege level. + +## API Endpoints + +The following API endpoints are implemented for managing privileges. + +### **GET** `/_telodendria/admin/privileges/[localpart]` + +Retrieve the permissions for a user. If the localpart is omitted, then +retrieve the privileges for the user that owns the access token being +used. Note that the owner of the access token must have the +**GRANT_PRIVILEGES** privilege to use this endpoint. + +| Requires Token | Rate Limited | +|----------------|--------------| +| Yes | Yes | + +| Response Code | Description | +|---------------|-------------| +| 200 | The privileges were successfully retrieved.| + +#### 200 Response Format + +| Field | Type | Description | +|-------|------|-------------| +| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.| + +### **POST** `/_telodendria/admin/privileges/[localpart]` + +Update the privileges of a local user by replacing the privileges array +with the one specified in the request. Like the **GET** version of this +endpoint, the localpart can be omitted to operate on the user that +owns the access token. + +| Requires Token | Rate Limited | +|----------------|--------------| +| Yes | Yes | + +| Response Code | Description | +|---------------|-------------| +| 200 | The privileges were successfully replaced.| + +#### Request Format + +| Field | Type | Description | +|-------|------|-------------| +| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.| + +#### 200 Response Format + +| Field | Type | Description | +|-------|------|-------------| +| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.| + +### **PUT** `/_telodendria/admin/privileges/[localpart] + +Update the privileges of a local user by adding the privileges +specified in the request to the users existing privileges. + +| Requires Token | Rate Limited | +|----------------|--------------| +| Yes | Yes | + +| Response Code | Description | +|---------------|-------------| +| 200 | The privileges were successfully added.| + +#### Request Format + +| Field | Type | Description | +|-------|------|-------------| +| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.| + +#### 200 Response Format + +| Field | Type | Description | +|-------|------|-------------| +| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.| + +### **DELETE** `/_telodendria/admin/privileges/[localpart]` + +Update the privileges of a local user by removing the privileges +specified in the request from the user's existing privileges. + +| Requires Token | Rate Limited | +|----------------|--------------| +| Yes | Yes | + +| Response Code | Description | +|---------------|-------------| +| 200 | The privileges were successfully removed.| + +#### Request Format + +| Field | Type | Description | +|-------|------|-------------| +| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.| + +#### 200 Response Format + +| Field | Type | Description | +|-------|------|-------------| +| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.| +