Kurs vibe coding z Claude Code · Moduł 9: Klon Discorda

Rangi i uprawnienia: najpierw testy, potem zamek na serwerze

8 min czytania
W tej lekcji11

Na serwer gildii wkradł się Blackbeard i zasypuje spamem kanał ogłoszeń. Zwykły majtek nic nie może zrobić, kapitana nie ma, a pierwsza oficer Anne nie wie, czy wolno jej kogoś wyrzucić. Serwer potrzebuje jasnych zasad: kto pisze w ogłoszeniach, kto wyrzuca, kto wycisza na godzinę. Discord zapisuje takie zasady jako bity uprawnień w rangach i nadpisania w kanałach. W tej lekcji Claude Code zbuduje ten mechanizm, a Ty sprawdzisz go testami i na serwerze, bo tu agent pisze kod, który działa na ekranie, a po cichu przepuszcza każdego.

Czego się nauczysz

  • opisać uprawnienia jako bity i policzyć je z rang i nadpisań kanału;
  • zlecić najpierw testy funkcji hasPermission, a dopiero potem jej kod;
  • sprawdzić uprawnienie w Route Handlerze i zobaczyć 403 w odpowiedzi;
  • poprosić Claude o przegląd wszystkich tras i samemu otworzyć każdą wskazaną.

Uprawnienia jako bity

Każde uprawnienie to jeden bit w liczbie. 1 << 11 to jedynka przesunięta o 11 miejsc, czyli liczba z jednym zapalonym bitem. Operator | (OR) łączy uprawnienia, & (AND) sprawdza, czy bit jest zapalony, a & ~ gasi bit. Otwórz 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, // w Discordzie 1 << 40
} as const;

To fragment listy, a wartości są takie jak w dokumentacji Discorda, z jednym wyjątkiem. MODERATE_MEMBERS, potrzebne do wyciszenia czasowego, ma w Discordzie bit 40. Operatory bitowe w JavaScripcie liczą jednak na 32 bitach: node -e "console.log(1 << 40)" wypisał u nas 256, czyli zupełnie inny bit, a 1 << 31 daje liczbę ujemną. Discord wysyła uprawnienia jako napisy z dużą liczbą i radzi biblioteki do dużych liczb. Klon ma mniej uprawnień, więc mieści się w bitach do 30.

Nadpisanie kanału to dwie liczby: co dodać i co zabrać.

export interface ChannelOverwrite {
  id: string; // id rangi albo członka
  type: "role" | "member";
  allow: number;
  deny: number;
}

Kanał #ogloszenia dostaje dwa nadpisania: Załoga ma deny: SEND_MESSAGES, a Oficer allow: SEND_MESSAGES. types/server.ts dostaje w kanale pole overwrites?: ChannelOverwrite[].

Zasady z dokumentacji Discorda

Dokumentacja Discorda opisuje kolejność liczenia: właściciel serwera ma wszystko; pozostałym sumuje się uprawnienia ich rang; ADMINISTRATOR daje wszystko i omija nadpisania kanału; nadpisania rang najpierw zabierają (deny), potem dodają (allow), a nadpisanie konkretnego członka działa na końcu. Discord zaczyna jeszcze od rangi @everyone; w klonie jej rolę gra ranga Załoga.

Polecenie dla Claude Code: testy najpierw

To zadanie ma jedną poprawną odpowiedź dla każdego przypadku, więc idealnie nadaje się na testy z lekcji 4_1.

Polecenie dla Claude Code:

Najpierw testy dla hasPermission(member, permission, server, channel?)
w lib/permissions.test.ts, z typami z @types/permissions.ts: właściciel
może wszystko, ADMINISTRATOR omija nadpisania kanału, bity rang się
sumują, deny z rangi zabiera prawo pisania w kanale, allow z innej rangi
wygrywa, bo deny idzie przed allow, nadpisanie członka działa na końcu.
Uruchom testy i pokaż porażkę. Potem lib/permissions.ts. Testów nie
zmieniaj, żeby przeszły. Pokaż komendę i wynik.

Pierwszy przebieg pada, bo funkcji jeszcze nie ma. U nas Vitest napisał: Failed to resolve import "@/lib/permissions" from "lib/permissions.test.ts". Does the file exist?. Zanim zaakceptujesz kod, przeczytaj w Cursorze plik testów i sprawdź, że każdy przypadek z polecenia ma swój test.

Co napisał Claude: hasPermission

Otwórz lib/permissions.ts. Pierwsza część to właściciel, suma rang i administrator:

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;

|= dokłada bity każdej rangi, którą ma członek, więc Anne z rangami Oficer i Załoga dostaje sumę obu. Administrator wychodzi z funkcji, zanim kanał zdąży mu cokolwiek zabrać. Druga część to nadpisania:

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;

Wyżej pętla zebrała allow i deny ze wszystkich rang członka. Najpierw gaśnie wszystko, czego rangi zabraniają, potem zapala się to, na co pozwalają, więc Anne pisze w #ogloszenia, choć jej Załoga ma tam zakaz. Ostatnie słowo ma nadpisanie członka: Blackbeard dostał w #general własny deny. Wszystkie 6 testów przeszło.

Typowy błąd agenta: nazwy zamiast liczb

Kusząca pomyłka to allow i deny jako listy nazw, na przykład ["SEND_MESSAGES"]. Czytelne dla człowieka, ale ~deny na liście TypeScript odrzuci. Agent, który chce uciszyć błąd, dopisze Number(...): Number(["SEND_MESSAGES"]) to NaN, ~NaN to -1, a x | NaN to x, więc nadpisania po cichu nic nie robią. U nas taka wersja przeszła npx tsc --noEmit i npm run lint, a testy powiedziały prawdę:

× deny z rangi zabiera prawo pisania w kanale
× nadpisanie członka działa na końcu
AssertionError: expected true to be false // Object.is equality
Tests  2 failed | 4 passed (6)

Test "allow wygrywa" przeszedł przypadkiem, bo Załoga i tak ma prawo pisania. Dlatego testy na zakazy są tu najważniejsze.

Zamek na serwerze

Funkcja to dopiero połowa. Przycisk "Wyrzuć" ukryty przed majtkiem nie chroni niczego: każdy może wysłać żądanie bez Twojego ekranu.

Polecenie dla Claude Code:

Dodaj Route Handler POST /api/members/[id]/kick. Zalogowanego członka
weź z getCurrentMember() z @lib/session.ts, nigdy z treści żądania.
Sprawdź na serwerze KICK_MEMBERS przez hasPermission, potem hierarchię:
nie wolno wyrzucić właściciela ani kogoś z równą albo wyższą rangą.
Najpierw testy w route.test.ts obok: zwykły członek dostaje 403, oficer
wyrzuca członka załogi, oficer nie wyrzuci kapitana.

Otwórz app/api/members/[id]/kick/route.ts. Początek funkcji to zamek:

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: "Brak uprawnienia KICK_MEMBERS" }, { status: 403 });
  }

Kod 403 znaczy "wiem, kim jesteś, ale nie wolno ci". Dalej funkcja szuka członka (404, gdy go nie ma) i sprawdza hierarchię funkcją outranks. Dokumentacja Discorda opisuje tę zasadę dla botów: wyrzucić można tylko kogoś, czyja najwyższa ranga stoi niżej. Test podmienia lib/session.ts przez vi.mock, więc sprawdza trasę bez przeglądarki. Sprawdź ją też na żywo: zmień w lib/session.ts zalogowanego na jack i wpisz w sesji:

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

U nas serwer odpowiedział HTTP/1.1 403 Forbidden i {"error":"Brak uprawnienia KICK_MEMBERS"}, a Anne próbująca wyrzucić kapitana dostała 403 z {"error":"Ta osoba ma równą albo wyższą rangę"}.

Narzędzia moderatora w trzech krokach

Ekrany zlecasz osobno. RoleManager pokazuje rangi posortowane malejąco po position, oczywiście na kopii: [...roles].sort(...). Przy każdym uprawnieniu stoi pole wyboru:

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

Zmienna nazywa się granted, a nie hasPermission, żeby nie zasłaniać funkcji o tej nazwie. Zapis idzie do PATCH /api/roles/[id], które sprawdza MANAGE_ROLES. ModeratorTools dostaje gotowe decyzje ze strony członka, liczone na serwerze:

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

Wyciszenie czasowe ma własne uprawnienie: według dokumentacji Discorda wymaga MODERATE_MEMBERS i trwa najwyżej 28 dni. Sam komponent jest Client Componentem z useState zaimportowanym na górze tego pliku: wybór akcji, powód (bez powodu "Potwierdź" jest wyłączony) i czas.

Przegląd wszystkich tras

Po kilku poleceniach w app/api stoją trzy trasy. Każda powinna mieć ten sam zamek, ale pisał je agent w różnych chwilach.

Polecenie dla Claude Code:

Przejrzyj wszystkie trasy w app/api i wypisz te, które nie sprawdzają
sesji i roli moderatora. Przy każdej podaj plik i linię. Niczego jeszcze
nie poprawiaj.

Raport to meldunek, nie dowód: otwórz w Cursorze każdą wskazaną trasę i każdą pominiętą. U nas trasa timeout wołała getCurrentMember(), ale nie hasPermission. Jack, zwykły majtek, wyciszył nią Anne: HTTP/1.1 200 OK. Po poprawce z testem ta sama komenda dała {"error":"Brak uprawnienia MODERATE_MEMBERS"} i 403.

Przegląd kapitana

  1. Liczby, nie nazwy. allow i deny to number, bez Number(...) i as.
  2. Zakazy w testach. Test "deny zabiera" i test nadpisania członka muszą istnieć i przechodzić.
  3. Bity do 30. Żadnego 1 << 31 ani wyżej.
  4. Zamek w każdej trasie. Ukryty przycisk to uprzejmość, 403 z serwera to zamek.
  5. Dowód. Testy, lint, npx tsc --noEmit po npx next typegen (bez niego RouteContext nie zna nowych tras) i npm run build.

Następny krok

Poproś o commit, na przykład "Uprawnienia bitowe, trasy moderacji z kontrolą na serwerze". Do bezpieczeństwa wrócisz jeszcze w tym module: sekrety, logowanie i przegląd całej gałęzi przed wdrożeniem.

W edytorze poniżej czeka kalkulator uprawnień: wybierz pirata, kanał i uprawnienie, zobacz każdy krok liczenia i włącz błąd agenta z nazwami zamiast liczb.

Pamiętaj: ukryty przycisk to nie zamek, a zamek, którego nikt nie sprawdził testem, to tylko zamek namalowany na drzwiach.

Kod do tej lekcji: App.jsx
// Kalkulator uprawnień Pirate's Cove: te same kroki co hasPermission w lib/permissions.ts.
// Przełącznik "błąd agenta" trzyma allow i deny jako listy nazw zamieniane przez 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: 'kapitan', name: 'Kapitan', position: 3, permissions: Permission.ADMINISTRATOR },
    { id: 'oficer', name: 'Oficer', position: 2, permissions: Permission.KICK_MEMBERS | Permission.MODERATE_MEMBERS },
    { id: 'zaloga', name: 'Załoga', position: 1, permissions: Permission.SEND_MESSAGES },
  ],
  members: [
    { id: 'redbeard', name: 'Kapitan Redbeard (właściciel)', roleIds: [] },
    { id: 'mary', name: 'Mary Read (Kapitan)', roleIds: ['kapitan', 'zaloga'] },
    { id: 'anne', name: 'Anne Bonny (Oficer)', roleIds: ['oficer', 'zaloga'] },
    { id: 'jack', name: 'Jack Rackham (Załoga)', roleIds: ['zaloga'] },
    { id: 'blackbeard', name: 'Blackbeard (Załoga)', roleIds: ['zaloga'] },
  ],
};

const channels = [
  { id: 'brak', name: '(bez kanału)', overwrites: [] },
  {
    id: 'ogloszenia',
    name: '#ogloszenia',
    overwrites: [
      { id: 'zaloga', type: 'role', allow: 0, deny: Permission.SEND_MESSAGES, names: { allow: [], deny: ['SEND_MESSAGES'] } },
      { id: 'oficer', 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']) to NaN
}

function explain(member, permission, channel, buggy) {
  const steps = [];
  if (member.id === server.ownerId) {
    steps.push('Właściciel serwera: wszystko wolno.');
    return { ok: true, steps };
  }
  let permissions = 0;
  for (const role of server.roles) {
    if (member.roleIds.includes(role.id)) {
      permissions |= role.permissions;
      steps.push('Ranga ' + role.name + ' dokłada bity: ' + role.permissions);
    }
  }
  if ((permissions & Permission.ADMINISTRATOR) === Permission.ADMINISTRATOR) {
    steps.push('ADMINISTRATOR: wszystko wolno, nadpisania kanału pominięte.');
    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('Najpierw deny rang: zostaje ' + permissions);
    permissions |= allow;
    steps.push('Potem allow rang: jest ' + 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('Nadpisanie członka na końcu: jest ' + permissions);
    }
  }
  const ok = (permissions & permission) === permission;
  steps.push('Sprawdzenie bitu: (' + permissions + ' & ' + permission + ') === ' + permission + ' daje ' + ok);
  return { ok, steps };
}

export default function App() {
  const [memberId, setMemberId] = useState('jack');
  const [channelId, setChannelId] = useState('ogloszenia');
  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);

  // Udawany Route Handler POST /api/members/blackbeard/kick: zamek na serwerze.
  function kickBlackbeard() {
    const allowed = explain(member, Permission.KICK_MEMBERS, channels[0], false).ok;
    setResponse(allowed ? '200 OK {"kicked":"blackbeard"}' : '403 Forbidden {"error":"Brak uprawnienia KICK_MEMBERS"}');
  }

  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">
          Pirat
          <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">
          Kanał
          <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">
          Uprawnienie
          <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)} />
        Błąd agenta: allow i deny jako listy nazw z 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 ? 'wolno' : 'nie wolno'}</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">Serwer sprawdza jeszcze raz</h2>
        <p className="text-sm">Przycisk wysyła żądanie jako wybrany pirat, nawet jeśli ekran by go ukrył.</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>
  );
}

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Jak Pirate's Cove liczy, czy członkowi wolno coś zrobić?

  2. 2. Jak w obiekcie Permission zapisano KICK_MEMBERS?

To 2 z 8 pytań do tej lekcji. Pozostałe rozwiążesz w grze.

Zadania praktyczne w grze

  • Klikanie w kolejności

    Klikaj, aby zbudować wpis z obiektu Permission: ADMINISTRATOR: 1 << 3

  • Edytor kodu

    Role management interface

  • Układanie w poziomie

    Ułóż linię z Route Handlera, która odmawia członkowi bez uprawnienia: return Response.json({ error: "Brak uprawnienia KICK_MEMBERS" }, { status: 403 });

  • Układanie w pionie

    Ułóż kroki funkcji hasPermission w kolejności z kodu:

  • Klikanie w kolejności

    Klikaj, aby zbudować linię, która gasi bity zakazane przez nadpisania: permissions &= ~deny;

  • Układanie w poziomie

    Ułóż sprawdzenie, czy członek ma daną rangę: member.roleIds.includes(role.id)

  • Układanie w pionie

    Ułóż kroki przeglądu tras w app/api z lekcji:

  • Edytor kodu

    Moderation panel

  • Układanie w pionie

    Ułóż kroki działania funkcji getHighestRole:

  • Układanie w poziomie

    Ułóż argumenty wywołania z Route Handlera: hasPermission(me, Permission.KICK_MEMBERS, mainServer)

  • Klikanie w kolejności

    Klikaj, aby zbudować sprawdzenie czy uprawnienie jest ustawione: (permissions & permission) === permission

  1. PytanieQuiz: Jak liczone są uprawnienia
  2. PytanieQuiz: Definicja bitu uprawnienia
  3. Kliknij w kolejnościSortowanie: Definicja bitu ADMINISTRATOR
  4. Zadanie z kodemPraktyka: Role manager
  5. PytanieQuiz: hasPermission i ADMINISTRATOR
  6. Ułóż w kolejnościSortowanie: Odpowiedź 403
  7. Ułóż w kolejnościSortowanie: Kroki funkcji hasPermission
  8. PytanieQuiz: Kolejność nadpisań kanału
  9. Kliknij w kolejnościSortowanie: Zgaszenie zakazanych bitów
  10. PytanieQuiz: Uprawnienie do wyciszenia
  11. Ułóż w kolejnościSortowanie: Sprawdzenie rangi członka
  12. Ułóż w kolejnościSortowanie: Przegląd tras API
  13. Zadanie z kodemPraktyka: Moderator tools
  14. Ułóż w kolejnościSortowanie: Kroki getHighestRole
  15. Ułóż w kolejnościSortowanie: Wywołanie hasPermission (kolejność argumentów)
  16. PytanieQuiz: Pole position w Role
  17. Kliknij w kolejnościSortowanie: Sprawdzenie bitu uprawnienia
  18. PytanieQuiz: Discord a Slack
  19. PytanieQuiz: Członek offline z wyróżnioną rangą

Przydatne artykuły