111 lines
9.0 KiB
Markdown
111 lines
9.0 KiB
Markdown
# Routes HTTP du backend et permissions
|
||
|
||
Ce document décrit les routes déclarées dans `src/routes` et leurs contrôles d’accès. Les chemins incluent les préfixes de montage définis dans `src/routes/mod.rs`.
|
||
|
||
## Règles générales
|
||
|
||
- **Authentification** : les routes sous `/api` listées comme protégées passent par `require_auth`. Un JWT valide doit être transmis comme `Authorization: Bearer <token>`, cookie `token` (ou `jwt` reconnu par le middleware) ou paramètre de requête `token`. L’absence d’identification valide entraîne `401 Unauthorized`.
|
||
- **Permissions fines** : elles sont évaluées par les handlers à partir des permissions du serveur/canal ou de contrôles d’appartenance. Un utilisateur authentifié qui n’a pas le droit requis reçoit généralement `403 Forbidden`.
|
||
- **Superuser** : les opérations de gestion globale des utilisateurs l’exigent. Les droits de serveur et de canal s’appliquent par ressource; ne pas déduire qu’un superuser les contourne automatiquement.
|
||
- **Accès conditionnel** : « membre » signifie appartenir au serveur concerné ou, pour une conversation/canal DM, être autorisé par le contrôle d’appartenance propre à cette ressource.
|
||
- **WebSocket** : les routes `/ws` sont des upgrades HTTP `GET`; leurs handlers extraient `CurrentUser`, donc elles requièrent aussi une authentification.
|
||
|
||
## API (`/api`)
|
||
|
||
Les routes ci-dessous, sauf mention contraire, sont protégées par l’authentification globale.
|
||
|
||
| Méthode | Route | Permission / condition supplémentaire |
|
||
|---|---|---|
|
||
| `POST` | `/api/auth/login` | Publique; identifiants valides requis pour obtenir une session/cookie. |
|
||
| `POST` | `/api/auth/bearer-login` | Publique; identifiants valides requis pour obtenir un bearer token. |
|
||
| `GET` | `/api/auth/me` | JWT valide. |
|
||
| `POST` | `/api/join` | Publique; inscription soumise à la validation et, selon la configuration, au jeton d’initialisation; un serveur cible avec mot de passe ne peut pas être rejoint par ce flux. |
|
||
| `GET` | `/api/servers` | JWT; renvoie les serveurs de l’utilisateur. |
|
||
| `POST` | `/api/servers` | JWT; création d’un serveur. |
|
||
| `GET` | `/api/servers/{id}` | Membre du serveur. |
|
||
| `PUT` | `/api/servers/{id}` | `MANAGE_SERVER` sur le serveur. |
|
||
| `DELETE` | `/api/servers/{id}` | `MANAGE_SERVER` sur le serveur. |
|
||
| `POST` | `/api/servers/{id}/join` | JWT; logique d’adhésion au serveur (conditions d’accès/mot de passe vérifiées par le handler). |
|
||
| `GET` | `/api/servers/{server_id}/tree` | Membre du serveur. |
|
||
| `GET` | `/api/servers/{server_id}/permissions/users` | `MANAGE_SERVER` sur le serveur. |
|
||
| `GET`, `PUT`, `DELETE` | `/api/servers/{server_id}/permissions/users/{user_id}` | `MANAGE_SERVER`; consultation, attribution ou retrait des permissions de l’utilisateur ciblé. |
|
||
| `GET`, `PUT`, `DELETE` | `/api/servers/{server_id}/permissions/roles/{role_id}` | `MANAGE_SERVER`; consultation, attribution ou retrait des permissions du rôle ciblé. |
|
||
| `PUT` | `/api/server-item-orders/reorder` | `MANAGE_CHANNELS` **et** `MANAGE_CATEGORIES` sur le serveur ciblé. |
|
||
| `GET` | `/api/categories` | `server_id` requis; membre du serveur. |
|
||
| `GET` | `/api/categories/{id}` | Membre du serveur associé à la catégorie. |
|
||
| `POST`, `PUT`, `DELETE` | `/api/categories`, `/api/categories/{id}` | `MANAGE_CATEGORIES` sur le serveur associé. |
|
||
| `GET` | `/api/channels` | `server_id` requis et appartenance au serveur; seuls les canaux avec `READ_CHANNEL` sont renvoyés. |
|
||
| `GET` | `/api/channels/{id}` | `READ_CHANNEL` sur le canal. |
|
||
| `POST` | `/api/channels` | `MANAGE_CHANNELS` sur le serveur. |
|
||
| `PUT`, `DELETE` | `/api/channels/{id}` | `MANAGE_CHANNELS` sur le serveur du canal. |
|
||
| `GET` | `/api/channels/{channel_id}/permissions` | `MANAGE_CHANNEL` sur le canal. |
|
||
| `GET`, `PUT`, `DELETE` | `/api/channels/{channel_id}/permissions/users/{user_id}` | `MANAGE_CHANNEL`; lecture, attribution ou retrait de permissions utilisateur. |
|
||
| `GET`, `PUT`, `DELETE` | `/api/channels/{channel_id}/permissions/roles/{role_id}` | `MANAGE_CHANNEL`; lecture, attribution ou retrait de permissions de rôle. |
|
||
| `GET` | `/api/channels/{channel_id}/read-state` | JWT; état de lecture de l’utilisateur courant pour le canal. |
|
||
| `PUT` | `/api/channels/{channel_id}/read-state` | JWT; modification de l’état de lecture de l’utilisateur courant pour le canal. |
|
||
| `GET` | `/api/conversations` | JWT; ne renvoie que les conversations accessibles à l’utilisateur courant. |
|
||
| `POST` | `/api/conversations` | JWT; création avec les participants fournis. |
|
||
| `POST` | `/api/conversations/{id}/fork` | JWT et accès/membership à la conversation source. |
|
||
| `GET` | `/api/roles` | `server_id` requis; membre du serveur. |
|
||
| `GET` | `/api/roles/{id}` | Membre du serveur du rôle. |
|
||
| `POST` | `/api/roles` | `MANAGE_ROLES` sur le serveur ciblé. |
|
||
| `PUT`, `DELETE` | `/api/roles/{id}` | `MANAGE_ROLES` sur le serveur du rôle. |
|
||
| `GET` | `/api/roles/{id}/members` | Membre du serveur du rôle. |
|
||
| `PUT`, `DELETE` | `/api/roles/{id}/members/{user_id}` | `MANAGE_ROLES` sur le serveur du rôle. |
|
||
| `GET` | `/api/messages` | `channel_id` requis et `READ_CHANNEL` sur le canal. |
|
||
| `POST` | `/api/messages` | `SEND_MESSAGE` sur le canal; les pièces jointes nécessitent également `ATTACH_FILES`. |
|
||
| `GET` | `/api/messages/{id}` | `READ_CHANNEL` sur le canal du message. |
|
||
| `PUT` | `/api/messages/{id}` | `EDIT_OWN_MESSAGE` pour son propre message; `EDIT_OTHERS_MESSAGES` pour celui d’un autre utilisateur. |
|
||
| `DELETE` | `/api/messages/{id}` | `DELETE_OWN_MESSAGE` pour son propre message; `DELETE_OTHERS_MESSAGES` pour celui d’un autre utilisateur. |
|
||
| `POST` | `/api/messages/{message_id}/reactions` | `ADD_REACTIONS` sur le canal du message. |
|
||
| `DELETE` | `/api/messages/{message_id}/reactions/{emoji_id}` | `ADD_REACTIONS` sur le canal du message. |
|
||
| `POST` | `/api/attachments` | `ATTACH_FILES` sur le canal indiqué dans l’upload. |
|
||
| `GET` | `/api/emojis` | JWT; liste limitée aux emojis accessibles aux serveurs de l’utilisateur. |
|
||
| `POST` | `/api/emojis` | `MANAGE_SERVER` sur le serveur ciblé. |
|
||
| `GET` | `/api/emojis/{id}` | Appartenance au serveur associé; emojis globaux selon leur disponibilité. |
|
||
| `GET` | `/api/emojis/{id}/asset` | Même contrôle d’accès que la lecture de l’emoji. |
|
||
| `PUT`, `DELETE` | `/api/emojis/{id}` | `MANAGE_SERVER` sur le serveur de l’emoji. |
|
||
| `GET` | `/api/users` | Superuser uniquement. |
|
||
| `POST` | `/api/users` | Superuser uniquement. |
|
||
| `GET`, `PUT`, `DELETE` | `/api/users/{id}` | Superuser uniquement. |
|
||
|
||
## Routes avec contrôle d’accès propre au handler
|
||
|
||
Ces routes ne sont pas incluses dans le groupe `require_auth` de `/api`; leurs handlers appliquent leur propre authentification et autorisation.
|
||
|
||
| Méthode | Route | Permission / condition supplémentaire |
|
||
|---|---|---|
|
||
| `GET` | `/api/attachments/{id}/file` | Authentification obligatoire; `READ_CHANNEL` sur le canal lié à la pièce jointe. |
|
||
|
||
## WebSocket (`/ws`)
|
||
|
||
| Méthode | Route | Permission / condition supplémentaire |
|
||
|---|---|---|
|
||
| `GET` | `/ws/gateway` | JWT valide via `CurrentUser`. |
|
||
| `GET` | `/ws/voice` | JWT valide via `CurrentUser`; droits vocaux vérifiés ensuite lors des messages/offres liés aux canaux. |
|
||
| `GET` | `/ws/rtc/{channel_id}` | JWT valide; le canal doit exister, être vocal et l’utilisateur doit être membre du serveur associé. |
|
||
|
||
## Documentation et services transverses
|
||
|
||
| Méthode | Route | Permission / condition supplémentaire |
|
||
|---|---|---|
|
||
| `GET` | `/swagger` et routes d’interface Swagger associées | Interface de documentation générée par Swagger UI; aucun contrôle de permission déclaré dans le routeur. |
|
||
| `GET` | `/api-docs/openapi.json` | Spécification OpenAPI servie par Swagger UI; aucun contrôle de permission déclaré dans le routeur. |
|
||
|
||
## Signification des permissions utilisées
|
||
|
||
| Permission | Portée / effet |
|
||
|---|---|
|
||
| `MANAGE_SERVER` | Modifier les paramètres du serveur et gérer ses permissions. |
|
||
| `MANAGE_ROLES` | Créer, modifier, supprimer des rôles et gérer leurs membres. |
|
||
| `MANAGE_CATEGORIES` | Créer, modifier et supprimer des catégories. |
|
||
| `MANAGE_CHANNELS` | Créer, modifier et supprimer des canaux. |
|
||
| `READ_CHANNEL` | Voir le canal et son contenu. |
|
||
| `SEND_MESSAGE` | Envoyer un message. |
|
||
| `EDIT_OWN_MESSAGE` / `EDIT_OTHERS_MESSAGES` | Modifier respectivement ses messages / ceux d’autres utilisateurs. |
|
||
| `DELETE_OWN_MESSAGE` / `DELETE_OTHERS_MESSAGES` | Supprimer respectivement ses messages / ceux d’autres utilisateurs. |
|
||
| `ADD_REACTIONS` | Ajouter ou retirer une réaction sur un message accessible. |
|
||
| `ATTACH_FILES` | Ajouter ou télécharger une pièce jointe selon le contrôle appliqué par la route. |
|
||
| `MANAGE_CHANNEL` | Gérer les permissions d’un canal. |
|
||
|
||
Les permissions disponibles dans le domaine comprennent aussi les droits de membres (`KICK_MEMBERS`, `BAN_MEMBERS`, `MANAGE_MEMBERS`, `VIEW_MEMBERS`) et de voix (`JOIN_VOICE`, `SPEAK`, `STREAM`, `MUTE_SELF`, `MUTE_OTHERS`, `MOVE_OTHERS`, `DISCONNECT_OTHERS`, `MANAGE_VOICE_CHANNEL`). Leur présence dans le modèle n’implique pas qu’une route HTTP dédiée existe. |