oxspeak_server/permission.md

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.