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

Zewnętrzne API: klucz zostaje w ładowni

9 min czytania
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 .env regułą 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

  1. 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_KEY ma 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.
  2. Git nie widzi sekretu. W .gitignore z create-next-app stoi .env*. U nas git status --short po dodaniu .env.local pokazał tylko nowe pliki z kodem.
  3. Błąd nie wycieka. Wpisz do .env.local zmyślony klucz i zapytaj trasę. OpenWeather odpowiedział u nas 401 z komunikatem Invalid API key, a trasa oddała przeglądarce tylko {"error":"Pogoda chwilowo niedostępna"} z kodem 502. W logu serwera stanęła linia OpenWeather odpowiedział 401. Zapytanie o ?city=tortuga dało 400 i {"error":"Nieznany port"}.
  4. 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 lint i npx tsc --noEmit nie powiedziały nic, a po npm run build klucz siedział w pliku .next/static/chunks/...js jako appid=klucz-z-ladowni-123. Ten folder trafia do każdej przeglądarki. Poproś Claude o grep -r fragmentu klucza w .next/static po 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. 1. Jak WeatherWidget dostaje pogodę z OpenWeather?

  2. 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:

  1. PytanieQuiz: Skąd widżet bierze pogodę
  2. Ułóż w kolejnościSortowanie: Odczyt opisu pogody
  3. PytanieQuiz: Flaga ignore w efekcie
  4. Ułóż w kolejnościSortowanie: Droga zapytania o pogodę

Przydatne artykuły