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

API externe : la clé reste dans la cale

11 min de lecture
Dans cette leçon9

Avant chaque expédition, le canal #treasure-hunts pose la même question : quel temps fera-t-il au port ? Pirate's Cove ne connaît pas la météo. Il la demande à une API externe, c'est-à-dire au service de quelqu'un d'autre avec lequel ton appli dialogue sur le réseau. Un tel service veut savoir qui demande, il te remet donc une clé d'API : une longue chaîne de caractères qui sert de mot de passe à ton compte chez lui. Celui qui met la main sur la clé interroge le service à tes frais, jusqu'à épuiser le quota ou à faire gonfler la facture. Dans cette leçon, Claude Code ajoute un widget météo de sorte que la clé ne quitte jamais la cale, c'est-à-dire le serveur.

Ce que tu vas apprendre

  • demander une intégration d'API externe par un Route Handler, et non depuis le navigateur ;
  • vérifier dans Cursor et dans l'appli compilée où la clé a vraiment atterri ;
  • voir comment la route gère l'erreur du service avant que l'équipage ne la voie ;
  • interdire à Claude Code l'accès aux fichiers .env avec une règle deny.

Où vit la clé

Tu gardes les clés dans des variables d'environnement, c'est-à-dire des valeurs que l'appli reçoit de l'extérieur et non du code. Dans un projet Next.js, les valeurs locales se trouvent dans le fichier .env.local et le code les lit avec process.env.NOM. La documentation de Next.js dit clairement que les variables sans le préfixe NEXT_PUBLIC_ ne sont disponibles que dans l'environnement Node.js, donc sur le serveur. Une variable avec ce préfixe, Next.js l'écrit en dur à la compilation dans le JavaScript envoyé au navigateur. Pour une clé d'API, c'est une condamnation : quiconque ouvre la page peut la lire.

C'est pourquoi la météo est récupérée par un Route Handler, une route d'API côté serveur que tu connais depuis la leçon 8_3. Le navigateur n'interroge que ta route, et c'est seulement ensuite que la route interroge le service météo en y ajoutant la clé.

La clé d'OpenWeather

Pirate's Cove utilise l'API Current weather du service OpenWeather. D'après sa documentation, la clé se trouve sur la page du compte, dans l'onglet "API key". La documentation marque aussi les requêtes par nom de ville comme obsolètes et demande des coordonnées ; la conversion du nom en coordonnées revient à une API distincte, Geocoding. La guilde ne navigue que vers quelques ports connus : une liste de ports avec leurs coordonnées suffit, et une seule requête.

Tu colles la clé toi-même dans .env.local dans Cursor, jamais dans la conversation avec Claude. Tout ce que tu écris dans la session reste dans la conversation, et un agent qui connaît la valeur peut très bien l'écrire directement dans le code.

Demande pour Claude Code :

Ajoute un widget météo pour l'expédition dans le canal #treasure-hunts.
Récupère la météo chez OpenWeather (Current weather par coordonnées,
units=metric, lang=fr) dans un Route Handler app/api/weather/route.ts.
Prends la clé dans process.env.OPENWEATHER_API_KEY, sans NEXT_PUBLIC_.
Garde les ports avec leurs coordonnées dans lib/ports.ts. Le composant
client components/WeatherWidget.tsx appelle seulement /api/weather?city=<id du port>.
Gère toute réponse autre que 200. N'écris pas la clé dans le code, dans
les logs ni dans la réponse de la route. Ne crée pas .env.local, je le
remplirai moi-même. À la fin : lint, types, build et un curl sur la route
avec un port inconnu.

Ce que Claude a écrit : la liste des ports

Ouvre lib/ports.ts dans Cursor. Un port, c'est un identifiant, un nom et deux coordonnées :

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 },
];

La liste joue le rôle de registre des ports autorisés. Le navigateur n'envoie que l'id, et seul le serveur connaît les coordonnées : personne ne peut donc envoyer par ta route une requête de son choix sur ta clé.

Ce que Claude a écrit : la route

Ouvre app/api/weather/route.ts. La fonction GET reçoit un NextRequest, c'est-à-dire une requête dotée du champ pratique nextUrl pour lire les paramètres de l'adresse, et commence par deux gardiens :

const port = ports.find((p) => p.id === request.nextUrl.searchParams.get("city"));
if (!port) {
  return Response.json({ error: "Port inconnu" }, { status: 400 });
}

const key = process.env.OPENWEATHER_API_KEY;
if (!key) {
  return Response.json({ error: "Météo non configurée" }, { status: 503 });
}

Le premier rejette avec le code 400, c'est-à-dire "mauvaise requête", un port absent de la liste. Le second attrape l'absence de clé sur le serveur et en parle en termes généraux, sans nom de fichier ni valeur. Ensuite, la route compose l'adresse et interroge le service :

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: "fr", appid: key,
}).toString();

const res = await fetch(url);
if (!res.ok) {
  console.error(`OpenWeather a répondu ${res.status}`);
  return Response.json({ error: "Météo momentanément indisponible" }, { status: 502 });
}

URLSearchParams construit la partie de l'adresse après le point d'interrogation et encode seul les caractères spéciaux. fetch ne signale pas d'erreur pour une réponse 401 ou 404, il ne rejette que les erreurs réseau : c'est pourquoi la route vérifie res.ok. Seul le numéro de statut va dans le log, pas l'adresse avec la clé. L'équipage reçoit le code 502, qui veut dire "le service derrière moi a échoué", et une courte phrase en français. Pour finir, la route recopie de la réponse vers le type Weather de types/weather.ts seulement trois champs : le nom du port, la température arrondie par Math.round et la description de data.weather[0].description. Grâce à units=metric, la température arrive en degrés Celsius, et lang=fr traduit la description en français.

Ce que Claude a écrit : le widget

components/WeatherWidget.tsx commence par "use client", car il réagit au choix du port. La récupération se trouve dans un effet qui repart à chaque changement de 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: "Pas de connexion au serveur" });
    });
  return () => {
    ignore = true;
  };
}, [city]);

Le drapeau ignore vient de la documentation de React : les réponses du réseau peuvent revenir dans un autre ordre que celui de leur départ, et le résultat d'un ancien port n'écrase donc pas le nouveau. La documentation vide ici l'état tout de suite dans l'effet, mais la règle react-hooks/set-state-in-effect rejette cet appel, ce que npm run lint nous a montré. Claude a donc calculé le chargement à partir des données : const loading = result?.city !== city;.

La revue du capitaine

  1. Où est la clé. Ouvre dans Cursor la recherche dans tout le projet (Cmd+Shift+F sur Mac, Ctrl+Shift+F sous Windows et Linux). Le nom OPENWEATHER_API_KEY ne doit figurer que dans la route, NEXT_PUBLIC_ ne doit apparaître nulle part, et un fragment de la valeur de la clé ne doit figurer dans aucun fichier de code.
  2. Git ne voit pas le secret. Dans le .gitignore de create-next-app se trouve .env*. Chez nous, git status --short après l'ajout de .env.local n'a montré que les nouveaux fichiers de code.
  3. L'erreur ne fuit pas. Mets une fausse clé dans .env.local et interroge la route. OpenWeather a répondu chez nous 401 avec le message Invalid API key, et la route n'a rendu au navigateur que {"error":"Météo momentanément indisponible"} avec le code 502. Dans le log du serveur s'est inscrite la ligne OpenWeather a répondu 401. La requête ?city=tortuga a donné 400 et {"error":"Port inconnu"}.
  4. Erreur typique de l'agent. Un agent à qui tu as collé la clé dans la conversation l'écrit dans le code ou ajoute NEXT_PUBLIC_, car le fetch "marche" alors directement depuis le composant. Nous avons testé cette version : npm run lint et npx tsc --noEmit n'ont rien dit, et après npm run build la clé se trouvait dans le fichier .next/static/chunks/...js sous la forme appid=cle-de-la-cale-123. Ce dossier part dans chaque navigateur. Demande à Claude un grep -r d'un fragment de la clé dans .next/static après le build : le bon résultat, c'est zéro occurrence.

Une clé qui a un jour atterri dans le navigateur ou dans l'historique de Git, considère-la comme brûlée : génères-en une nouvelle sur la page du compte.

Paiements : la même règle

La guilde voudra un jour vendre le rôle VIP. Nous ne lançons pas d'intégration de paiement dans ce cours, mais la règle est la même que pour la météo, et la documentation de Stripe la décrit précisément. Pour la plupart des nouvelles intégrations, Stripe recommande le Payment Element, c'est-à-dire un formulaire de paiement prêt à l'emploi, avec l'API Checkout Sessions. L'objet de paiement (Checkout Session ou PaymentIntent) est créé par ton serveur avec la clé secrète, et le navigateur ne reçoit que la clé publique pour loadStripe et le client secret, la clé de ce seul paiement. Le montant est toujours fixé par le serveur, sinon le client choisirait lui-même son prix. L'argent ne bouge que lorsque la page déclenche la confirmation (confirm dans Checkout Sessions, stripe.confirmPayment dans PaymentIntents), et Stripe envoie le résultat du paiement à ton serveur par un événement webhook. Stripe ajoute encore une chose : la route qui crée les sessions de paiement cache la clé, mais ne se protège pas seule contre l'abus ; il lui faut donc la même serrure que les routes de la leçon 8_3.

Étape suivante : un verrou sur le coffre aux clés

Il reste un endroit d'où la clé peut fuir : Claude lui-même. D'après la documentation de Claude Code, la lecture de fichiers dans le dossier du projet ne demande aucun accord, même en mode Manual. Chez nous, en mode Manual, l'outil Read a rendu sans poser de question tout le contenu de .env.local. Le contenu du fichier entre alors dans la conversation, et de là il peut finir dans le code ou dans un log.

Demande pour Claude Code :

Ajoute à .claude/settings.json des règles permissions.deny qui interdisent
de lire .env et tout fichier .env.*. Essaie ensuite de lire .env.local
avec l'outil Read, puis avec la commande cat, et recopie les deux messages.

Ouvre .claude/settings.json. Dans la location 8, ce fichier de réglages du projet contenait un hook de formatage, et dans Pirate's Cove Claude ne fait que le créer :

{
  "permissions": {
    "deny": ["Read(./.env)", "Read(./.env.*)"]
  }
}

Read(./.env.*) est un motif à la syntaxe de .gitignore : l'astérisque couvre .env.local, .env.production et tout autre fichier qui commence ainsi. Tu fermerais de la même façon un dossier entier : Read(./secrets/**), où les deux astérisques couvrent tout l'intérieur, sous-dossiers compris. Chez nous, Read a répondu File is in a directory that is denied by your permission settings., et cat .env.local a reçu Permission to use Bash with command cat .env.local has been denied.. Le même test en mode auto s'est terminé par les deux mêmes refus.

La documentation dit précisément ce que couvre une telle règle. Elle agit dans tous les modes, y compris auto et bypassPermissions, et l'emporte sur toute règle allow. Elle bloque l'outil Read, et Claude Code s'efforce de l'étendre aux outils Grep et Glob ainsi qu'aux fichiers désignés par @. Elle interdit aussi aux outils Edit et Write de modifier ce fichier. Elle couvre les commandes que Claude Code reconnaît dans Bash, comme cat, head, tail, sed et tee, ainsi que les redirections < et >. Elle ne couvre pas une commande qui lit des fichiers sans les nommer, comme grep -r motif ., ni un script Python ou Node qui ouvre lui-même les fichiers. Un blocage dur pour tous les processus, seul le bac à sable au niveau du système le donne. C'est donc une première couche, pas la seule, et c'est justement pourquoi la clé ne vit de toute façon que dans .env.local.

Le fichier .claude/settings.json voyage dans le dépôt, et les règles deny d'un tel fichier agissent tout de suite chez quiconque clone le projet. Demande un commit, par exemple "Météo par Route Handler et règles deny pour .env".

Dans l'éditeur ci-dessous t'attend une simulation du widget avec le panneau réseau du navigateur : regarde ce que demande le navigateur, casse la clé et active l'erreur de l'agent avec NEXT_PUBLIC_.

Retiens : la clé de la cale, c'est le capitaine qui la porte, pas le perroquet sur son épaule, qui la répétera à tous ceux du port.

Code de cette leçon : App.jsx
// Météo pour l'expédition : le navigateur, ta route /api/weather et un faux OpenWeather.
// Tout fonctionne ici, sans réseau et sans vraie clé.
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 = 'cle-de-la-cale-123';
const skies = {
  '54.35': { temp: 7.6, description: 'couvert' },
  '25.06': { temp: 27.2, description: 'ciel dégagé' },
  '17.94': { temp: 29.4, description: 'faibles averses de pluie' },
};

// Faux OpenWeather : une mauvaise clé donne 401, la bonne donne la météo.
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 }] } };
}

// Ta route GET /api/weather?city=... avec les mêmes gardiens que dans la leçon.
function weatherRoute(city, serverEnv, log) {
  const port = ports.find((p) => p.id === city);
  if (!port) return { status: 400, body: { error: 'Port inconnu' } };
  const key = serverEnv.OPENWEATHER_API_KEY;
  if (!key) return { status: 503, body: { error: 'Météo non configurée' } };
  const res = openWeather(port.lat, key);
  if (res.status !== 200) {
    log('OpenWeather a répondu ' + res.status);
    return { status: 502, body: { error: 'Météo momentanément indisponible' } };
  }
  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 ? 'fausse-cle' : VALID_KEY };
    const log = (line) => setServerLog((prev) => [line, ...prev].slice(0, 4));
    let entry;
    let result;
    if (buggy) {
      // Erreur de l'agent : NEXT_PUBLIC_ écrit la clé dans le JavaScript du navigateur.
      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">Météo pour l&apos;expédition</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 (hors liste)</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)} /> Mauvaise clé dans .env.local sur le serveur</label>
        <label className="flex items-center gap-2"><input type="checkbox" checked={buggy} onChange={(e) => setBuggy(e.target.checked)} /> Erreur de l&apos;agent : clé dans NEXT_PUBLIC_, fetch direct depuis le composant</label>
      </div>

      <section className="rounded-lg border border-slate-300 bg-white p-3">
        <h2 className="font-bold">Panneau réseau du navigateur</h2>
        <p className="text-xs text-slate-500">Voilà ce que voit quiconque ouvre les outils du navigateur.</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 ? '  (clé visible !)' : ''}</li>
          ))}
        </ul>
      </section>

      <section className="rounded-lg border border-slate-300 bg-white p-3">
        <h2 className="font-bold">Log du serveur</h2>
        <ul className="mt-2 space-y-1 font-mono text-xs">
          {serverLog.map((line, i) => <li key={i}>{line}</li>)}
        </ul>
      </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 WeatherWidget obtient-il la météo d'OpenWeather ?

  2. 2. À quoi sert la variable ignore dans l'effet de WeatherWidget, que la fonction de nettoyage met à true ?

Tâches pratiques dans le jeu

  • Tri horizontal

    Ordonne la lecture de la description météo dans la route : data.weather[0].description

  • Tri vertical

    Ordonne le trajet de la demande météo, du clic à l'écran :

  1. QuestionQuiz : d'où le widget tire la météo
  2. Remets dans l'ordreOrdre : lire la description météo
  3. QuestionQuiz : le drapeau ignore dans l'effet
  4. Remets dans l'ordreOrdre : le trajet de la demande météo

Articles utiles