Kurs vibe coding z Claude Code · Moduł 9: Klon Discorda
Rangi i uprawnienia: najpierw testy, potem zamek na serwerze
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/kickU 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
- Liczby, nie nazwy.
allowidenytonumber, bezNumber(...)ias. - Zakazy w testach. Test "deny zabiera" i test nadpisania członka muszą istnieć i przechodzić.
- Bity do 30. Żadnego
1 << 31ani wyżej. - Zamek w każdej trasie. Ukryty przycisk to uprzejmość, 403 z serwera to zamek.
- Dowód. Testy, lint,
npx tsc --noEmitponpx next typegen(bez niegoRouteContextnie zna nowych tras) inpm 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 << {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. Jak Pirate's Cove liczy, czy członkowi wolno coś zrobić?
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
Zadania po tej lekcji
- PytanieQuiz: Jak liczone są uprawnienia
- PytanieQuiz: Definicja bitu uprawnienia
- Kliknij w kolejnościSortowanie: Definicja bitu ADMINISTRATOR
- Zadanie z kodemPraktyka: Role manager
- PytanieQuiz: hasPermission i ADMINISTRATOR
- Ułóż w kolejnościSortowanie: Odpowiedź 403
- Ułóż w kolejnościSortowanie: Kroki funkcji hasPermission
- PytanieQuiz: Kolejność nadpisań kanału
- Kliknij w kolejnościSortowanie: Zgaszenie zakazanych bitów
- PytanieQuiz: Uprawnienie do wyciszenia
- Ułóż w kolejnościSortowanie: Sprawdzenie rangi członka
- Ułóż w kolejnościSortowanie: Przegląd tras API
- Zadanie z kodemPraktyka: Moderator tools
- Ułóż w kolejnościSortowanie: Kroki getHighestRole
- Ułóż w kolejnościSortowanie: Wywołanie hasPermission (kolejność argumentów)
- PytanieQuiz: Pole position w Role
- Kliknij w kolejnościSortowanie: Sprawdzenie bitu uprawnienia
- PytanieQuiz: Discord a Slack
- PytanieQuiz: Członek offline z wyróżnioną rangą