Cours Vibe coding avec Claude Code · Module 9: Clone de Discord

Rôles et permissions : les tests d'abord, la serrure du serveur ensuite

10 min de lecture
Dans cette leçon11

Blackbeard s'est glissé sur le serveur de la guilde et inonde de spam le canal des annonces. Le simple mousse ne peut rien faire, le capitaine est absent, et la première officière Anne ne sait pas si elle a le droit d'expulser quelqu'un. Le serveur a besoin de règles claires : qui écrit dans les annonces, qui expulse, qui rend muet pour une heure. Discord écrit ces règles sous forme de bits de permissions dans les rôles et de surcharges dans les canaux. Dans cette leçon, Claude Code construit ce mécanisme et toi, tu le vérifies par des tests et sur le serveur, car ici l'agent écrit un code qui fonctionne à l'écran et laisse passer tout le monde en silence.

Ce que tu vas apprendre

  • décrire les permissions comme des bits et les calculer à partir des rôles et des surcharges du canal ;
  • demander d'abord les tests de la fonction hasPermission, et seulement ensuite son code ;
  • vérifier la permission dans un Route Handler et voir le 403 dans la réponse ;
  • demander à Claude une revue de toutes les routes, puis ouvrir toi-même chacune de celles qu'il signale.

Les permissions comme des bits

Chaque permission est un bit dans un nombre. 1 << 11 est un 1 décalé de 11 places, c'est-à-dire un nombre dont un seul bit est allumé. L'opérateur | (OR) combine les permissions, & (AND) vérifie qu'un bit est allumé, et & ~ éteint un bit. Ouvre types/permissions.ts :

export const Permission = {
  KICK_MEMBERS: 1 << 1,
  BAN_MEMBERS: 1 << 2,
  ADMINISTRATOR: 1 << 3,
  SEND_MESSAGES: 1 << 11,
  MANAGE_ROLES: 1 << 28,
  MODERATE_MEMBERS: 1 << 29, // 1 << 40 dans Discord
} as const;

C'est un extrait de la liste, et les valeurs sont celles de la documentation de Discord, à une exception près. MODERATE_MEMBERS, nécessaire pour le mutisme temporaire, a le bit 40 chez Discord. Or les opérateurs binaires de JavaScript calculent sur 32 bits : node -e "console.log(1 << 40)" a affiché 256 chez nous, c'est-à-dire un tout autre bit, et 1 << 31 donne un nombre négatif. Discord envoie les permissions sous forme de chaînes contenant de grands nombres et conseille des bibliothèques de grands nombres. Le clone a moins de permissions et tient donc dans les bits jusqu'à 30.

Une surcharge de canal, ce sont deux nombres : ce qu'on ajoute et ce qu'on retire.

export interface ChannelOverwrite {
  id: string; // id d'un rôle ou d'un membre
  type: "role" | "member";
  allow: number;
  deny: number;
}

Le canal #annonces reçoit deux surcharges : l'Équipage a deny: SEND_MESSAGES, et l'Officier allow: SEND_MESSAGES. Dans types/server.ts, le canal reçoit le champ overwrites?: ChannelOverwrite[].

Les règles de la documentation de Discord

La documentation de Discord décrit l'ordre du calcul : le propriétaire du serveur a tout ; pour les autres, on additionne les permissions de leurs rôles ; ADMINISTRATOR donne tout et ignore les surcharges du canal ; les surcharges de rôle commencent par retirer (deny), puis ajoutent (allow), et la surcharge d'un membre précis agit en dernier. Discord part en plus du rôle @everyone ; dans le clone, c'est le rôle Équipage qui joue ce rôle.

Demande pour Claude Code : les tests d'abord

Cette tâche a une seule bonne réponse pour chaque cas : elle se prête donc parfaitement aux tests de la leçon 4_1.

Demande pour Claude Code :

D'abord les tests de hasPermission(member, permission, server, channel?)
dans lib/permissions.test.ts, avec les types de @types/permissions.ts :
le propriétaire peut tout, ADMINISTRATOR ignore les surcharges du canal,
les bits des rôles s'additionnent, le deny d'un rôle retire le droit
d'écrire dans le canal, le allow d'un autre rôle l'emporte, car deny passe
avant allow, la surcharge d'un membre agit en dernier. Lance les tests
et montre l'échec. Ensuite lib/permissions.ts. Ne modifie pas les tests
pour les faire passer. Montre la commande et le résultat.

Le premier passage échoue, car la fonction n'existe pas encore. Chez nous, Vitest a écrit : Failed to resolve import "@/lib/permissions" from "lib/permissions.test.ts". Does the file exist?. Avant d'accepter le code, lis le fichier de tests dans Cursor et vérifie que chaque cas de la demande a son test.

Ce que Claude a écrit : hasPermission

Ouvre lib/permissions.ts. La première partie traite le propriétaire, la somme des rôles et l'administrateur :

if (member.id === server.ownerId) return true;

let permissions = 0;
for (const role of server.roles) {
  if (member.roleIds.includes(role.id)) permissions |= role.permissions;
}
if ((permissions & Permission.ADMINISTRATOR) === Permission.ADMINISTRATOR) return true;

|= ajoute les bits de chaque rôle du membre : Anne, avec les rôles Officier et Équipage, reçoit donc la somme des deux. L'administrateur sort de la fonction avant que le canal ait pu lui retirer quoi que ce soit. La deuxième partie, ce sont les surcharges :

permissions &= ~deny;
permissions |= allow;

const own = channel.overwrites.find((o) => o.type === "member" && o.id === member.id);
if (own) {
  permissions &= ~own.deny;
  permissions |= own.allow;
}
return (permissions & permission) === permission;

Plus haut, la boucle a rassemblé allow et deny de tous les rôles du membre. D'abord s'éteint tout ce que les rôles interdisent, puis s'allume ce qu'ils autorisent : Anne écrit donc dans #annonces alors que son rôle Équipage y est interdit. Le dernier mot revient à la surcharge du membre : Blackbeard a reçu dans #general son propre deny. Les 6 tests sont passés.

Erreur typique de l'agent : des noms au lieu de nombres

Une pente glissante : allow et deny sous forme de listes de noms, par exemple ["SEND_MESSAGES"]. C'est lisible pour un humain, mais TypeScript rejette ~deny sur une liste. Un agent qui veut faire taire l'erreur ajoutera Number(...) : Number(["SEND_MESSAGES"]) vaut NaN, ~NaN vaut -1, et x | NaN vaut x : les surcharges ne font donc plus rien, en silence. Chez nous, cette version est passée par npx tsc --noEmit et npm run lint, et les tests ont dit la vérité :

× le deny d'un rôle retire le droit d'écrire dans le canal
× la surcharge du membre s'applique en dernier
AssertionError: expected true to be false // Object.is equality
Tests  2 failed | 4 passed (6)

Le test "allow l'emporte" est passé par hasard, car l'Équipage a de toute façon le droit d'écrire. Les tests sur les interdictions sont donc les plus importants ici.

La serrure sur le serveur

La fonction n'est que la moitié du travail. Un bouton "Expulser" caché au mousse ne protège rien : n'importe qui peut envoyer une requête sans passer par ton écran.

Demande pour Claude Code :

Ajoute un Route Handler POST /api/members/[id]/kick. Prends le membre
connecté dans getCurrentMember() de @lib/session.ts, jamais dans le corps
de la requête. Vérifie côté serveur KICK_MEMBERS avec hasPermission, puis
la hiérarchie : on ne peut expulser ni le propriétaire ni quelqu'un dont
le rôle est égal ou supérieur. D'abord les tests dans route.test.ts à
côté : un membre ordinaire reçoit 403, un officier expulse un membre de
l'équipage, un officier n'expulse pas le capitaine.

Ouvre app/api/members/[id]/kick/route.ts. Le début de la fonction est la serrure :

export async function POST(_request: Request, ctx: RouteContext<"/api/members/[id]/kick">) {
  const { id } = await ctx.params;
  const me = await getCurrentMember();

  if (!hasPermission(me, Permission.KICK_MEMBERS, mainServer)) {
    return Response.json({ error: "Permission KICK_MEMBERS manquante" }, { status: 403 });
  }

Le code 403 signifie "je sais qui tu es, mais tu n'en as pas le droit". La fonction cherche ensuite le membre (404 s'il n'existe pas) et vérifie la hiérarchie avec outranks. La documentation de Discord décrit cette règle pour les bots : on ne peut expulser que quelqu'un dont le rôle le plus élevé est plus bas. Le test remplace lib/session.ts par vi.mock, et vérifie donc la route sans navigateur. Vérifie-la aussi en direct : dans lib/session.ts, mets jack comme membre connecté et tape dans la session :

!curl -i -X POST http://localhost:3000/api/members/blackbeard/kick

Chez nous, le serveur a répondu HTTP/1.1 403 Forbidden et {"error":"Permission KICK_MEMBERS manquante"}, et Anne, en essayant d'expulser le capitaine, a reçu un 403 avec {"error":"Cette personne a un rôle égal ou supérieur"}.

Les outils du modérateur en trois étapes

Tu confies les écrans séparément. RoleManager affiche les rôles triés par position décroissante, évidemment sur une copie : [...roles].sort(...). Chaque permission a une case à cocher :

const bit = Permission[name];
const granted = (selected.permissions & bit) === bit;
// onChange :
update({ permissions: granted ? selected.permissions & ~bit : selected.permissions | bit });

La variable s'appelle granted et non hasPermission, pour ne pas masquer la fonction de ce nom. L'enregistrement part vers PATCH /api/roles/[id], qui vérifie MANAGE_ROLES. ModeratorTools reçoit des décisions toutes prêtes, calculées sur le serveur depuis la page du membre :

const higher = outranks(me, target, mainServer);
const allowed = {
  kick: higher && hasPermission(me, Permission.KICK_MEMBERS, mainServer),
  timeout: higher && hasPermission(me, Permission.MODERATE_MEMBERS, mainServer),
};

Le mutisme temporaire a sa propre permission : selon la documentation de Discord, il demande MODERATE_MEMBERS et dure au plus 28 jours. Le composant lui-même est un Client Component avec le useState importé en haut de ce fichier : choix de l'action, motif (sans motif, "Confirmer" est désactivé) et durée.

Revue de toutes les routes

Après quelques demandes, trois routes se trouvent dans app/api. Chacune devrait avoir la même serrure, mais l'agent les a écrites à des moments différents.

Demande pour Claude Code :

Passe en revue toutes les routes de app/api et liste celles qui ne
vérifient pas la session ni le rôle de modérateur. Pour chacune, donne
le fichier et la ligne. Ne corrige encore rien.

Le rapport est un compte rendu, pas une preuve : ouvre dans Cursor chaque route signalée et chaque route oubliée. Chez nous, la route timeout appelait getCurrentMember() mais pas hasPermission. Jack, un simple mousse, a rendu Anne muette par là : HTTP/1.1 200 OK. Après la correction accompagnée d'un test, la même commande a donné {"error":"Permission MODERATE_MEMBERS manquante"} et un 403.

La revue du capitaine

  1. Des nombres, pas des noms. allow et deny sont des number, sans Number(...) ni as.
  2. Les interdictions dans les tests. Le test "deny retire" et le test de la surcharge du membre doivent exister et passer.
  3. Des bits jusqu'à 30. Pas de 1 << 31 ni au-dessus.
  4. Une serrure dans chaque route. Un bouton caché est une politesse, un 403 du serveur est une serrure.
  5. La preuve. Les tests, le lint, npx tsc --noEmit après npx next typegen (sans lui, RouteContext ne connaît pas les nouvelles routes) et npm run build.

Étape suivante

Demande un commit, par exemple "Permissions par bits, routes de modération avec contrôle côté serveur". Tu reviendras à la sécurité dans ce module : secrets, connexion et revue de toute la branche avant le déploiement.

Dans l'éditeur ci-dessous t'attend un calculateur de permissions : choisis un pirate, un canal et une permission, regarde chaque étape du calcul et active le bug de l'agent avec des noms à la place des nombres.

Retiens : un bouton caché n'est pas une serrure, et une serrure que personne n'a vérifiée par un test n'est qu'une serrure peinte sur la porte.

Code de cette leçon : App.jsx
// Calculateur de permissions de Pirate's Cove : les mêmes étapes que hasPermission dans lib/permissions.ts.
// L'interrupteur "bug de l'agent" garde allow et deny comme listes de noms converties par Number(...).
import { useState } from 'react';

const Permission = {
  KICK_MEMBERS: 1 << 1,
  BAN_MEMBERS: 1 << 2,
  ADMINISTRATOR: 1 << 3,
  SEND_MESSAGES: 1 << 11,
  MANAGE_ROLES: 1 << 28,
  MODERATE_MEMBERS: 1 << 29,
};

const server = {
  ownerId: 'redbeard',
  roles: [
    { id: 'capitaine', name: 'Capitaine', position: 3, permissions: Permission.ADMINISTRATOR },
    { id: 'officier', name: 'Officier', position: 2, permissions: Permission.KICK_MEMBERS | Permission.MODERATE_MEMBERS },
    { id: 'equipage', name: 'Équipage', position: 1, permissions: Permission.SEND_MESSAGES },
  ],
  members: [
    { id: 'redbeard', name: 'Capitaine Barbe-Rousse (propriétaire)', roleIds: [] },
    { id: 'mary', name: 'Mary Read (Capitaine)', roleIds: ['capitaine', 'equipage'] },
    { id: 'anne', name: 'Anne Bonny (Officier)', roleIds: ['officier', 'equipage'] },
    { id: 'jack', name: 'Jack Rackham (Équipage)', roleIds: ['equipage'] },
    { id: 'blackbeard', name: 'Blackbeard (Équipage)', roleIds: ['equipage'] },
  ],
};

const channels = [
  { id: 'aucun', name: '(aucun canal)', overwrites: [] },
  {
    id: 'annonces',
    name: '#annonces',
    overwrites: [
      { id: 'equipage', type: 'role', allow: 0, deny: Permission.SEND_MESSAGES, names: { allow: [], deny: ['SEND_MESSAGES'] } },
      { id: 'officier', type: 'role', allow: Permission.SEND_MESSAGES, deny: 0, names: { allow: ['SEND_MESSAGES'], deny: [] } },
    ],
  },
  {
    id: 'general',
    name: '#general',
    overwrites: [
      { id: 'blackbeard', type: 'member', allow: 0, deny: Permission.SEND_MESSAGES, names: { allow: [], deny: ['SEND_MESSAGES'] } },
    ],
  },
];

function bits(value, buggy, names) {
  return buggy ? Number(names) : value; // Number(['SEND_MESSAGES']) donne NaN
}

function explain(member, permission, channel, buggy) {
  const steps = [];
  if (member.id === server.ownerId) {
    steps.push('Propriétaire du serveur : tout est permis.');
    return { ok: true, steps };
  }
  let permissions = 0;
  for (const role of server.roles) {
    if (member.roleIds.includes(role.id)) {
      permissions |= role.permissions;
      steps.push('Le rôle ' + role.name + ' ajoute les bits : ' + role.permissions);
    }
  }
  if ((permissions & Permission.ADMINISTRATOR) === Permission.ADMINISTRATOR) {
    steps.push('ADMINISTRATOR : tout est permis, les surcharges du canal sont ignorées.');
    return { ok: true, steps };
  }
  if (channel.overwrites.length > 0) {
    let allow = 0;
    let deny = 0;
    for (const o of channel.overwrites) {
      if (o.type === 'role' && member.roleIds.includes(o.id)) {
        allow |= bits(o.allow, buggy, o.names.allow);
        deny |= bits(o.deny, buggy, o.names.deny);
      }
    }
    permissions &= ~deny;
    steps.push("D'abord le deny des rôles : il reste " + permissions);
    permissions |= allow;
    steps.push('Puis le allow des rôles : on a ' + permissions);
    const own = channel.overwrites.find((o) => o.type === 'member' && o.id === member.id);
    if (own) {
      permissions &= ~bits(own.deny, buggy, own.names.deny);
      permissions |= bits(own.allow, buggy, own.names.allow);
      steps.push('La surcharge du membre à la fin : on a ' + permissions);
    }
  }
  const ok = (permissions & permission) === permission;
  steps.push('Vérification du bit : (' + permissions + ' & ' + permission + ') === ' + permission + ' donne ' + ok);
  return { ok, steps };
}

export default function App() {
  const [memberId, setMemberId] = useState('jack');
  const [channelId, setChannelId] = useState('annonces');
  const [permName, setPermName] = useState('SEND_MESSAGES');
  const [buggy, setBuggy] = useState(false);
  const [response, setResponse] = useState(null);

  const member = server.members.find((m) => m.id === memberId);
  const channel = channels.find((c) => c.id === channelId);
  const result = explain(member, Permission[permName], channel, buggy);

  // Faux Route Handler POST /api/members/blackbeard/kick : le verrou côté serveur.
  function kickBlackbeard() {
    const allowed = explain(member, Permission.KICK_MEMBERS, channels[0], false).ok;
    setResponse(allowed ? '200 OK {"kicked":"blackbeard"}' : '403 Forbidden {"error":"Permission KICK_MEMBERS manquante"}');
  }

  return (
    <div className="min-h-screen space-y-4 bg-gray-100 p-4 text-gray-900">
      <div className="grid gap-3 sm:grid-cols-3">
        <label className="text-sm">
          Pirate
          <select value={memberId} onChange={(e) => { setMemberId(e.target.value); setResponse(null); }} className="mt-1 block w-full rounded border border-gray-300 bg-white p-1">
            {server.members.map((m) => <option key={m.id} value={m.id}>{m.name}</option>)}
          </select>
        </label>
        <label className="text-sm">
          Canal
          <select value={channelId} onChange={(e) => setChannelId(e.target.value)} className="mt-1 block w-full rounded border border-gray-300 bg-white p-1">
            {channels.map((c) => <option key={c.id} value={c.id}>{c.name}</option>)}
          </select>
        </label>
        <label className="text-sm">
          Permission
          <select value={permName} onChange={(e) => setPermName(e.target.value)} className="mt-1 block w-full rounded border border-gray-300 bg-white p-1">
            {Object.keys(Permission).map((name) => <option key={name} value={name}>{name} (1 &lt;&lt; {Math.log2(Permission[name])})</option>)}
          </select>
        </label>
      </div>

      <label className="flex items-center gap-2 text-sm">
        <input type="checkbox" checked={buggy} onChange={(e) => setBuggy(e.target.checked)} />
        Bug de l&apos;agent : allow et deny comme listes de noms avec Number(...)
      </label>

      <section className={'rounded-lg border p-4 ' + (result.ok ? 'border-green-600 bg-green-50' : 'border-red-600 bg-red-50')}>
        <h2 className="font-bold">hasPermission: {result.ok ? 'autorisé' : 'refusé'}</h2>
        <ol className="mt-2 list-decimal space-y-1 pl-5 text-sm">
          {result.steps.map((step, i) => <li key={i}>{step}</li>)}
        </ol>
      </section>

      <section className="space-y-2 rounded-lg border border-gray-300 bg-white p-4">
        <h2 className="font-bold">Le serveur vérifie une seconde fois</h2>
        <p className="text-sm">Le bouton envoie la requête au nom du pirate choisi, même si l&apos;écran l&apos;avait caché.</p>
        <button onClick={kickBlackbeard} className="rounded bg-red-600 px-3 py-1 text-white">POST /api/members/blackbeard/kick</button>
        {response && <pre className="rounded bg-gray-900 p-2 text-xs text-green-200">{response}</pre>}
      </section>
    </div>
  );
}

Tu as repéré une erreur dans cette leçon ?

Teste tes connaissances

Réponds aux questions de cette leçon. Choisis une réponse pour voir tout de suite si elle est correcte.

  1. 1. Comment Pirate's Cove calcule-t-il si un membre a le droit de faire quelque chose ?

  2. 2. Comment KICK_MEMBERS est-il écrit dans l'objet Permission ?

Voici 2 des 8 questions de cette leçon. Réponds aux autres dans le jeu.

Tâches pratiques dans le jeu

  • Clique dans l'ordre

    Clique pour construire l'entrée de l'objet Permission : ADMINISTRATOR: 1 << 3

  • Éditeur de code

    Interface de gestion des rôles

  • Tri horizontal

    Ordonne la ligne du Route Handler qui refuse un membre sans permission : return Response.json({ error: "Permission KICK_MEMBERS manquante" }, { status: 403 });

  • Tri vertical

    Ordonne les étapes de la fonction hasPermission dans l'ordre du code :

  • Clique dans l'ordre

    Clique pour construire la ligne qui éteint les bits interdits par les surcharges : permissions &= ~deny;

  • Tri horizontal

    Ordonne la vérification que le membre a un rôle donné : member.roleIds.includes(role.id)

  • Tri vertical

    Ordonne les étapes de revue des routes de app/api vues dans la leçon :

  • Éditeur de code

    Panneau de modération

  • Tri vertical

    Ordonne les étapes du fonctionnement de la fonction getHighestRole :

  • Tri horizontal

    Ordonne les arguments de l'appel dans le Route Handler : hasPermission(me, Permission.KICK_MEMBERS, mainServer)

  • Clique dans l'ordre

    Clique pour construire la vérification qu'une permission est activée : (permissions & permission) === permission

  1. QuestionQuiz : Calcul des permissions
  2. QuestionQuiz : Définition d'un bit de permission
  3. Clique dans l'ordreOrdre : définition du bit ADMINISTRATOR
  4. Exercice de codePratique : gestionnaire de rôles
  5. QuestionQuiz : hasPermission et ADMINISTRATOR
  6. Remets dans l'ordreOrdre : réponse 403
  7. Remets dans l'ordreOrdre : étapes de la fonction hasPermission
  8. QuestionQuiz : Ordre des surcharges du canal
  9. Clique dans l'ordreOrdre : extinction des bits interdits
  10. QuestionQuiz : Permission du mutisme
  11. Remets dans l'ordreOrdre : vérification du rôle d'un membre
  12. Remets dans l'ordreOrdre : revue des routes API
  13. Exercice de codePratique : outils de modération
  14. Remets dans l'ordreOrdre : étapes de getHighestRole
  15. Remets dans l'ordreOrdre : appel de hasPermission (ordre des arguments)
  16. QuestionQuiz : le champ position dans Role
  17. Clique dans l'ordreOrdre : vérifier un bit de permission
  18. QuestionQuiz : Discord et Slack
  19. QuestionQuiz : Membre hors ligne avec un rôle mis en avant

Articles utiles