diff --git a/CHANGELOG.md b/CHANGELOG.md index addea359..257ed76c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,10 +9,11 @@ Versia Server `0.8.0` is fully backwards compatible with `0.7.0`. - Outbound federation, inbox processing and data fetching are now handled by a queue system (like most federated software). - Added an administration UI for managing the queue. - Upgraded Bun to `1.1.36`. -- Implemented support for the [Instance Messaging Extension](https://versia.pub/extensions/instance-messaging) -- Implement [Shared Inboxes](https://versia.pub/federation#inboxes) support. +- Implemented support for the [**Instance Messaging Extension**](https://versia.pub/extensions/instance-messaging) +- Implement [**Shared Inboxes**](https://versia.pub/federation#inboxes) support. - Allowed `
` and `` tags in Markdown. - Added `--password` flag to the user creation CLI. +- Overhaul [**Roles API**](https://server.versia.pub/api/roles) to allow for full role control (create, update, delete, assign). ## New Configuration Options @@ -86,7 +87,7 @@ Versia Server `0.7.0` is backwards compatible with `0.6.0`. However, some new fe A new plugin system for extending Versia Server has been added in this release! > [!NOTE] -> +> > This is an internal feature and is not documented. Support for third-party plugins will be given on a "if we have time" basis, until the API is fully stabilized and documented Plugins using this framework support: @@ -137,4 +138,4 @@ As a demonstration of the power of this system and an effort to modularize the c ## Miscellaneous - Remove Node.js from Docker build. -- Update all dependencies. \ No newline at end of file +- Update all dependencies. diff --git a/api/api/v1/roles/index.ts b/api/api/v1/roles/index.ts index 6e9e2f52..8e63a57d 100644 --- a/api/api/v1/roles/index.ts +++ b/api/api/v1/roles/index.ts @@ -6,7 +6,10 @@ import { ErrorSchema } from "~/types/api"; export const meta = applyConfig({ auth: { - required: true, + required: false, + methodOverrides: { + POST: true, + }, }, ratelimits: { duration: 60, diff --git a/docs/api/roles.md b/docs/api/roles.md index b908ea61..f685a3c2 100644 --- a/docs/api/roles.md +++ b/docs/api/roles.md @@ -1,12 +1,6 @@ # Roles API -> [!WARNING] -> -> This API is due to be reworked in the future. The current implementation is not final. -> -> Missing features include the ability to create and delete roles, as well as the ability to assign roles to other users. - -This API allows users to create, read, update, and delete instance custom roles. Custom roles can be used to grant users specific permissions, such as managing the instance, uploading custom emojis, or moderating content. +This API allows users to create, read, update, delete and assign instance custom roles. Custom roles can be used to grant users specific permissions, such as managing the instance, uploading custom emojis, or moderating content. ## Priorities @@ -109,19 +103,20 @@ interface Role { } ``` -## Get Roles +## Get All Roles ```http GET /api/v1/roles ``` -Get a list of all roles that the requesting user has. +Get a list of all roles on the instance. - **Returns**: Array of [`Role`](#role) -- **Authentication**: Required +- **Authentication**: Not required - **Permissions**: None - **Version History**: - `0.7.0`: Added. + - `0.8.0`: Now returns all instance roles. ### Example @@ -134,7 +129,7 @@ Authorization: Bearer ... #### `200 OK` -All roles owned by the user. +All roles on the instance. ```json [ @@ -294,48 +289,159 @@ Role data. } ``` -## Assign Role +## Create Role ```http -POST /api/v1/roles/:id +POST /api/v1/roles ``` -Assign a role to the user making the request. +Create a new role. -- **Returns**: `204 No Content` +- **Returns**: [`Role`](#role) - **Authentication**: Required - **Permissions**: `roles` - **Version History**: - - `0.7.0`: Added. + - `0.8.0`: Added. ### Request #### Example ```http -POST /api/v1/roles/364fd13f-28b5-4e88-badd-ce3e533f0d02 +POST /api/v1/roles Authorization: Bearer ... +Content-Type: application/json + +{ + "name": "Moderator", + "permissions": [ + "notes", + "accounts", + "likes", + "boosts", + "emojis", + "media", + "blocks", + "filters", + "mutes", + "reports", + "settings", + "roles", + "notifications", + "follows", + "impersonate", + "ignore_rate_limits", + "instance", + "instance:federation", + "instance:settings" + ], + "priority": 100, + "description": "Moderator role for managing content", + "visible": true, + "icon": "https://example.com/moderator.png" +} +``` + +### Response + +#### `201 Created` + +Role successfully created. + +```json +{ + "id": "364fd13f-28b5-4e88-badd-ce3e533f0d02", + "name": "Moderator", + "permissions": [ + "notes", + "accounts", + "likes", + "boosts", + "emojis", + "media", + "blocks", + "filters", + "mutes", + "reports", + "settings", + "roles", + "notifications", + "follows", + "impersonate", + "ignore_rate_limits", + "instance", + "instance:federation", + "instance:settings" + ], + "priority": 100, + "description": "Moderator role for managing content", + "visible": true, + "icon": "https://example.com/moderator.png" +} +``` + +## Update Role + +```http +PATCH /api/v1/roles/:id +``` + +Update a role's data. + +- **Returns**: `204 No Content` +- **Authentication**: Required +- **Permissions**: `roles` +- **Version History**: + - `0.8.0`: Added. + +### Request + +#### Example + +```http +PATCH /api/v1/roles/364fd13f-28b5-4e88-badd-ce3e533f0d02 +Authorization: Bearer ... +Content-Type: application/json + +{ + "name": "Moderator", + "permissions": [ + "notes", + "accounts", + "likes", + "boosts", + "emojis", + "media", + "blocks", + "filters", + "mutes", + ], + "priority": 10, + "description": "Moderator role for managing content", + "visible": true, + "icon": "https://example.com/moderator.png" +} ``` ### Response #### `204 No Content` -Role successfully assigned. +Role successfully updated. -## Remove Role +## Delete Role ```http DELETE /api/v1/roles/:id ``` -Remove a role from the user making the request. +Delete a role. - **Returns**: `204 No Content` - **Authentication**: Required - **Permissions**: `roles` - **Version History**: - - `0.7.0`: Added. + - `0.8.0`: Added. ### Request @@ -350,4 +456,124 @@ Authorization: Bearer ... #### `204 No Content` -Role successfully removed. \ No newline at end of file +Role successfully deleted. + +## Assign Role + +```http +POST /api/v1/accounts/:id/roles/:role_id +``` + +Assign a role to an account. + +- **Returns**: `204 No Content` +- **Authentication**: Required +- **Permissions**: `roles` +- **Version History**: + - `0.8.0`: Added. + +### Request + +#### Example + +```http +POST /api/v1/accounts/04608f74-6263-4a9a-bd7a-e778d4ac2ce4/roles/364fd13f-28b5-4e88-badd-ce3e533 +Authorization: Bearer ... +``` + +### Response + +#### `204 No Content` + +Role successfully assigned. + +## Unassign Role + +```http +DELETE /api/v1/accounts/:id/roles/:role_id +``` + +Unassign a role from an account. + +- **Returns**: `204 No Content` +- **Authentication**: Required +- **Permissions**: `roles` +- **Version History**: + - `0.8.0`: Added. + +### Request + +#### Example + +```http +DELETE /api/v1/accounts/04608f74-6263-4a9a-bd7a-e778d4ac2ce4/roles/364fd13f-28b5-4e88-badd-ce3e533 +Authorization: Bearer ... +``` + +### Response + +#### `204 No Content` + +Role successfully unassigned. + +## Get Account Roles + +```http +GET /api/v1/accounts/:id/roles +``` + +Get a list of roles assigned to an account. + +- **Returns**: Array of [`Role`](#role) +- **Authentication**: Not required +- **Permissions**: None +- **Version History**: + - `0.8.0`: Added. + +### Request + +#### Example + +```http +GET /api/v1/accounts/04608f74-6263-4a9a-bd7a-e778d4ac2ce4/roles +``` + +### Response + +#### `200 OK` + +Roles assigned to the account. + +```json +[ + { + "id": "364fd13f-28b5-4e88-badd-ce3e533f0d02", + "name": "Moderator", + "permissions": [ + "notes", + "accounts", + "likes", + "boosts", + "emojis", + "media", + "blocks", + "filters", + "mutes", + "reports", + "settings", + "roles", + "notifications", + "follows", + "impersonate", + "ignore_rate_limits", + "instance", + "instance:federation", + "instance:settings" + ], + "priority": 100, + "description": "Moderator role for managing content", + "visible": true, + "icon": "https://example.com/moderator.png" + } +] +```