Kurs vibe coding z Claude Code · Moduł 9: Klon Discorda
Zewnętrzne API: klucz zostaje w ładowni
W tej lekcji9
Przed każdą wyprawą na kanale #treasure-hunts pada to samo pytanie: jaka będzie pogoda w porcie? Pirate's Cove sam pogody nie zna. Pyta o nią zewnętrzne API, czyli cudzą usługę, z którą Twoja aplikacja rozmawia przez sieć. Taka usługa chce wiedzieć, kto pyta, więc wydaje Ci klucz API: długi napis, który działa jak hasło do Twojego konta w tej usłudze. Kto zdobędzie klucz, ten pyta na Twój rachunek, aż wyczerpie limit albo nabije opłaty. W tej lekcji Claude Code doda widżet pogody tak, żeby klucz nigdy nie opuścił ładowni, czyli serwera.
Czego się nauczysz
- zlecić integrację z zewnętrznym API przez Route Handler, a nie z przeglądarki;
- sprawdzić w Cursorze i w zbudowanej aplikacji, gdzie naprawdę trafił klucz;
- zobaczyć, jak trasa obsługuje błąd usługi, zanim ten błąd zobaczy załoga;
- zablokować Claude Code dostęp do plików
.envregułądeny.
Gdzie mieszka klucz
Klucze trzymasz w zmiennych środowiskowych, czyli wartościach, które aplikacja dostaje z zewnątrz, a nie z kodu. W projekcie Next.js lokalne wartości stoją w pliku .env.local, a kod czyta je przez process.env.NAZWA. Dokumentacja Next.js mówi wprost, że zmienne bez przedrostka NEXT_PUBLIC_ są dostępne tylko w środowisku Node.js, czyli na serwerze. Zmienną z tym przedrostkiem Next.js wpisuje przy budowaniu na sztywno do JavaScriptu wysyłanego do przeglądarki. Dla klucza API to wyrok: każdy, kto otworzy stronę, może go przeczytać.
Dlatego pogodę pobiera Route Handler, czyli trasa API na serwerze, którą znasz z lekcji 8_3. Przeglądarka pyta tylko Twoją trasę, a dopiero trasa pyta usługę pogodową, dokładając klucz.
Klucz od OpenWeather
Pirate's Cove korzysta z Current weather API serwisu OpenWeather. Według jego dokumentacji klucz znajdziesz na stronie konta, w zakładce "API key". Dokumentacja oznacza też zapytania po nazwie miasta jako przestarzałe i prosi o współrzędne, a nazwę miasta zamienia na współrzędne osobne Geocoding API. Gildia pływa do kilku znanych portów, więc wystarczy lista portów ze współrzędnymi i jedno zapytanie.
Klucz wklejasz sam do .env.local w Cursorze, nigdy do rozmowy z Claude. Wszystko, co napiszesz w sesji, zostaje w rozmowie, a agent, który zna wartość, potrafi ją wpisać prosto do kodu.
Polecenie dla Claude Code:
Dodaj widżet pogody dla wyprawy na kanale #treasure-hunts.
Pogodę pobieraj z OpenWeather (Current weather po współrzędnych,
units=metric, lang=pl) w Route Handlerze app/api/weather/route.ts.
Klucz bierz z process.env.OPENWEATHER_API_KEY, bez NEXT_PUBLIC_.
Porty ze współrzędnymi trzymaj w lib/ports.ts. Komponent kliencki
components/WeatherWidget.tsx woła tylko /api/weather?city=<id portu>.
Obsłuż odpowiedź inną niż 200. Klucza nie wpisuj w kod, w logi ani
w odpowiedź trasy. Pliku .env.local nie twórz, uzupełnię go sam.
Na koniec lint, typy, build i curl na trasę z nieznanym portem.Co napisał Claude: lista portów
Otwórz w Cursorze lib/ports.ts. Port to identyfikator, nazwa i dwie współrzędne:
export const ports: Port[] = [
{ id: "gdansk", name: "Gdańsk", lat: 54.35, lon: 18.65 },
{ id: "nassau", name: "Nassau", lat: 25.06, lon: -77.35 },
{ id: "port-royal", name: "Port Royal", lat: 17.94, lon: -76.84 },
];Lista działa jak rejestr dozwolonych portów. Przeglądarka przysyła tylko id, a współrzędne zna wyłącznie serwer, więc nikt nie wyśle przez Twoją trasę dowolnego zapytania na Twój klucz.
Co napisał Claude: trasa
Otwórz app/api/weather/route.ts. Funkcja GET dostaje NextRequest, czyli żądanie z wygodnym polem nextUrl do czytania parametrów adresu, i zaczyna od dwóch strażników:
const port = ports.find((p) => p.id === request.nextUrl.searchParams.get("city"));
if (!port) {
return Response.json({ error: "Nieznany port" }, { status: 400 });
}
const key = process.env.OPENWEATHER_API_KEY;
if (!key) {
return Response.json({ error: "Pogoda nie jest skonfigurowana" }, { status: 503 });
}Pierwszy odrzuca port spoza listy kodem 400, czyli "złe żądanie". Drugi łapie brak klucza na serwerze i mówi o tym ogólnie, bez nazwy pliku i bez wartości. Dalej trasa składa adres i pyta usługę:
const url = new URL("https://api.openweathermap.org/data/2.5/weather");
url.search = new URLSearchParams({
lat: String(port.lat), lon: String(port.lon), units: "metric", lang: "pl", appid: key,
}).toString();
const res = await fetch(url);
if (!res.ok) {
console.error(`OpenWeather odpowiedział ${res.status}`);
return Response.json({ error: "Pogoda chwilowo niedostępna" }, { status: 502 });
}URLSearchParams buduje część adresu po znaku zapytania i sam koduje znaki specjalne. fetch nie zgłasza błędu przy odpowiedzi 401 czy 404, odrzuca tylko błędy sieci, dlatego trasa sprawdza res.ok. Do logu trafia sam numer statusu, a nie adres z kluczem. Załoga dostaje kod 502, który znaczy "usługa za mną zawiodła", i krótkie zdanie po polsku. Na końcu trasa przepisuje z odpowiedzi do typu Weather z types/weather.ts tylko trzy pola: nazwę portu, temperaturę zaokrągloną Math.round i opis z data.weather[0].description. Dzięki units=metric temperatura przychodzi w stopniach Celsjusza, a lang=pl tłumaczy opis.
Co napisał Claude: widżet
components/WeatherWidget.tsx ma "use client", bo reaguje na wybór portu. Pobieranie siedzi w efekcie, który rusza przy każdej zmianie city:
useEffect(() => {
let ignore = false;
fetch(`/api/weather?city=${city}`)
.then(async (res) => {
const body = await res.json();
if (!ignore) setResult(res.ok ? { city, weather: body } : { city, error: body.error });
})
.catch(() => {
if (!ignore) setResult({ city, error: "Brak połączenia z serwerem" });
});
return () => {
ignore = true;
};
}, [city]);Flaga ignore pochodzi z dokumentacji Reacta: odpowiedzi z sieci mogą wrócić w innej kolejności, niż poszły, więc wynik dla starego portu nie nadpisze nowego. Dokumentacja czyści w tym miejscu stan od razu w efekcie, ale reguła react-hooks/set-state-in-effect odrzuca takie wywołanie, co u nas pokazał npm run lint. Claude policzył więc ładowanie z danych: const loading = result?.city !== city;.
Przegląd kapitana
- Gdzie jest klucz. Otwórz w Cursorze wyszukiwanie w całym projekcie (Cmd+Shift+F na Macu, Ctrl+Shift+F na Windowsie i Linuksie). Nazwa
OPENWEATHER_API_KEYma stać tylko w trasie,NEXT_PUBLIC_nie ma się pojawić nigdzie, a fragment wartości klucza nie może wystąpić w żadnym pliku z kodem. - Git nie widzi sekretu. W
.gitignorezcreate-next-appstoi.env*. U nasgit status --shortpo dodaniu.env.localpokazał tylko nowe pliki z kodem. - Błąd nie wycieka. Wpisz do
.env.localzmyślony klucz i zapytaj trasę. OpenWeather odpowiedział u nas401z komunikatemInvalid API key, a trasa oddała przeglądarce tylko{"error":"Pogoda chwilowo niedostępna"}z kodem 502. W logu serwera stanęła liniaOpenWeather odpowiedział 401. Zapytanie o?city=tortugadało 400 i{"error":"Nieznany port"}. - Typowy błąd agenta. Agent, któremu wkleiłeś klucz w rozmowie, wpisuje go do kodu albo dopisuje
NEXT_PUBLIC_, bo wtedy fetch "działa" prosto z komponentu. Sprawdziliśmy taką wersję:npm run lintinpx tsc --noEmitnie powiedziały nic, a ponpm run buildklucz siedział w pliku.next/static/chunks/...jsjakoappid=klucz-z-ladowni-123. Ten folder trafia do każdej przeglądarki. Poproś Claude ogrep -rfragmentu klucza w.next/staticpo buildzie: dobre trafienie to zero trafień.
Klucz, który raz trafił do przeglądarki albo do historii Gita, traktuj jak spalony: wygeneruj nowy na stronie konta.
Płatności: ta sama zasada
Gildia chce kiedyś sprzedawać rangę VIP. Integracji płatności w tym kursie nie uruchamiamy, ale zasada jest ta sama co przy pogodzie, a dokumentacja Stripe opisuje ją dokładnie. Dla większości nowych integracji Stripe poleca Payment Element, czyli gotowy formularz płatności, razem z Checkout Sessions API. Obiekt płatności (Checkout Session albo PaymentIntent) tworzy Twój serwer z tajnym kluczem, a przeglądarka dostaje tylko klucz publiczny do loadStripe i client secret, czyli klucz tej jednej płatności. Kwotę zawsze ustala serwer, bo inaczej klient sam wybrałby sobie cenę. Pieniądze ruszają dopiero wtedy, gdy strona wywoła potwierdzenie (confirm w Checkout Sessions, stripe.confirmPayment w PaymentIntents), a wynik płatności Stripe wysyła Twojemu serwerowi zdarzeniem webhook. Stripe dodaje jeszcze jedno: trasa, która tworzy sesje płatności, chowa klucz, ale nie chroni się sama przed nadużyciem, więc potrzebuje tego samego zamka co trasy z lekcji 8_3.
Następny krok: zamek na skrzyni z kluczami
Zostało jedno miejsce, z którego klucz może wyciec: sam Claude. Według dokumentacji Claude Code odczyt plików w katalogu projektu nie wymaga zgody nawet w trybie Manual. U nas w trybie Manual narzędzie Read bez pytania zwróciło całą treść .env.local. Treść pliku trafia wtedy do rozmowy, a stamtąd może wylądować w kodzie albo w logu.
Polecenie dla Claude Code:
Dodaj do .claude/settings.json reguły permissions.deny, które zabronią
czytać .env i każdy plik .env.*. Potem spróbuj odczytać .env.local
narzędziem Read, a potem komendą cat, i przepisz oba komunikaty.Otwórz .claude/settings.json. W lokacji 8 ten plik ustawień projektu trzymał hook formatujący, a w Pirate's Cove Claude dopiero go tworzy:
{
"permissions": {
"deny": ["Read(./.env)", "Read(./.env.*)"]
}
}Read(./.env.*) to wzorzec w składni .gitignore: gwiazdka obejmuje .env.local, .env.production i każdy inny plik o takim początku. Tak samo zamkniesz cały folder: Read(./secrets/**), gdzie dwie gwiazdki obejmują wszystko w środku, razem z podfolderami. U nas Read odpowiedział File is in a directory that is denied by your permission settings., a cat .env.local dostało Permission to use Bash with command cat .env.local has been denied.. Ten sam test w trybie auto skończył się tymi samymi dwoma odmowami.
Dokumentacja mówi dokładnie, co taka reguła obejmuje. Działa w każdym trybie, także w auto i bypassPermissions, i wygrywa z każdą regułą allow. Blokuje narzędzie Read, a narzędzia Grep i Glob oraz pliki wskazane przez @ Claude Code stara się nią objąć w miarę możliwości. Zabrania też narzędziom Edit i Write zmieniać ten plik. Obejmuje komendy, które Claude Code rozpoznaje w Bashu, takie jak cat, head, tail, sed i tee, oraz przekierowania < i >. Nie obejmuje komendy, która czyta pliki bez nazywania ich, takiej jak grep -r wzorzec ., ani skryptu w Pythonie czy Node, który sam otwiera pliki. Twardą blokadę dla wszystkich procesów daje dopiero sandbox na poziomie systemu. To więc pierwsza warstwa, nie jedyna, i właśnie dlatego klucz i tak mieszka tylko w .env.local.
Plik .claude/settings.json jedzie w repozytorium, a reguły deny z takiego pliku działają od razu u każdego, kto sklonuje projekt. Poproś o commit, na przykład "Pogoda przez Route Handler i reguły deny dla .env".
W edytorze poniżej czeka symulacja widżetu z panelem sieci przeglądarki: zobacz, o co pyta przeglądarka, zepsuj klucz i włącz błąd agenta z NEXT_PUBLIC_.
Pamiętaj: klucz do ładowni nosi kapitan, nie papuga na ramieniu, która powtórzy go każdemu w porcie.
Kod do tej lekcji: App.jsx
// Pogoda na wyprawę: przeglądarka, Twoja trasa /api/weather i udawany OpenWeather.
// Wszystko działa tutaj, bez sieci i bez prawdziwego klucza.
import { useState } from 'react';
const ports = [
{ id: 'gdansk', name: 'Gdańsk', lat: 54.35, lon: 18.65 },
{ id: 'nassau', name: 'Nassau', lat: 25.06, lon: -77.35 },
{ id: 'port-royal', name: 'Port Royal', lat: 17.94, lon: -76.84 },
];
const VALID_KEY = 'klucz-z-ladowni-123';
const skies = {
'54.35': { temp: 7.6, description: 'zachmurzenie duże' },
'25.06': { temp: 27.2, description: 'bezchmurnie' },
'17.94': { temp: 29.4, description: 'słabe przelotne opady deszczu' },
};
// Udawany OpenWeather: zły klucz daje 401, dobry daje pogodę.
function openWeather(lat, appid) {
if (appid !== VALID_KEY) {
return { status: 401, body: { cod: 401, message: 'Invalid API key.' } };
}
const sky = skies[String(lat)];
return { status: 200, body: { main: { temp: sky.temp }, weather: [{ description: sky.description }] } };
}
// Twoja trasa GET /api/weather?city=... z tymi samymi strażnikami co w lekcji.
function weatherRoute(city, serverEnv, log) {
const port = ports.find((p) => p.id === city);
if (!port) return { status: 400, body: { error: 'Nieznany port' } };
const key = serverEnv.OPENWEATHER_API_KEY;
if (!key) return { status: 503, body: { error: 'Pogoda nie jest skonfigurowana' } };
const res = openWeather(port.lat, key);
if (res.status !== 200) {
log('OpenWeather odpowiedział ' + res.status);
return { status: 502, body: { error: 'Pogoda chwilowo niedostępna' } };
}
return { status: 200, body: { port: port.name, temp: Math.round(res.body.main.temp), description: res.body.weather[0].description } };
}
export default function App() {
const [badKey, setBadKey] = useState(false);
const [buggy, setBuggy] = useState(false);
const [network, setNetwork] = useState([]);
const [serverLog, setServerLog] = useState([]);
const [shown, setShown] = useState(null);
function check(city) {
const serverEnv = { OPENWEATHER_API_KEY: badKey ? 'nieprawdziwy-klucz' : VALID_KEY };
const log = (line) => setServerLog((prev) => [line, ...prev].slice(0, 4));
let entry;
let result;
if (buggy) {
// Błąd agenta: NEXT_PUBLIC_ wpisuje klucz do JavaScriptu przeglądarki.
const port = ports.find((p) => p.id === city);
const publicKey = serverEnv.OPENWEATHER_API_KEY;
const res = openWeather(port.lat, publicKey);
entry = { url: 'https://api.openweathermap.org/data/2.5/weather?lat=' + port.lat + '&lon=' + port.lon + '&appid=' + publicKey, status: res.status, leak: true };
result = res.status === 200
? { port: port.name, temp: Math.round(res.body.main.temp), description: res.body.weather[0].description }
: { error: res.body.message };
} else {
const res = weatherRoute(city, serverEnv, log);
entry = { url: '/api/weather?city=' + city, status: res.status, leak: false };
result = res.body;
}
setNetwork((prev) => [entry, ...prev].slice(0, 5));
setShown(result);
}
return (
<div className="min-h-screen space-y-4 bg-slate-100 p-4 font-sans text-slate-900">
<section className="space-y-2 rounded-lg bg-slate-800 p-4 text-slate-100">
<h1 className="font-bold">Pogoda na wyprawę</h1>
<div className="flex flex-wrap gap-2">
{ports.map((p) => (
<button key={p.id} onClick={() => check(p.id)} className="rounded bg-indigo-600 px-3 py-1">{p.name}</button>
))}
<button onClick={() => check('tortuga')} className="rounded border border-slate-400 px-3 py-1">Tortuga (spoza listy)</button>
</div>
{shown && shown.error && <p className="text-red-300">{shown.error}</p>}
{shown && !shown.error && <p><span className="text-2xl font-bold">{shown.temp}°C</span> {shown.port}: {shown.description}</p>}
</section>
<div className="space-y-1 text-sm">
<label className="flex items-center gap-2"><input type="checkbox" checked={badKey} onChange={(e) => setBadKey(e.target.checked)} /> Zły klucz w .env.local na serwerze</label>
<label className="flex items-center gap-2"><input type="checkbox" checked={buggy} onChange={(e) => setBuggy(e.target.checked)} /> Błąd agenta: klucz w NEXT_PUBLIC_, fetch prosto z komponentu</label>
</div>
<section className="rounded-lg border border-slate-300 bg-white p-3">
<h2 className="font-bold">Panel sieci przeglądarki</h2>
<p className="text-xs text-slate-500">Tyle widzi każdy, kto otworzy narzędzia przeglądarki.</p>
<ul className="mt-2 space-y-1 font-mono text-xs">
{network.map((n, i) => (
<li key={i} className={n.leak ? 'text-red-700' : 'text-slate-800'}>GET {n.url} → {n.status}{n.leak ? ' (klucz widoczny!)' : ''}</li>
))}
</ul>
</section>
<section className="rounded-lg border border-slate-300 bg-white p-3">
<h2 className="font-bold">Log serwera</h2>
<ul className="mt-2 space-y-1 font-mono text-xs">
{serverLog.map((line, i) => <li key={i}>{line}</li>)}
</ul>
</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 WeatherWidget dostaje pogodę z OpenWeather?
2. Po co w efekcie WeatherWidget zmienna ignore, którą funkcja sprzątająca ustawia na true?
Zadania praktyczne w grze
- Układanie w poziomie
Ułóż odczyt opisu pogody w trasie: data.weather[0].description
- Układanie w pionie
Ułóż drogę zapytania o pogodę od kliknięcia do ekranu: