Vue générale
Protégez votre application en quelques minutes : une clé, un paquet, une règle.
À la fin de ce guide, votre application est protégée par le Shield (pare-feu applicatif) et par une limite de débit, d'abord en mode test, puis pour de vrai.
Les étapes
Créez une clé API
Créez un compte, puis un projet. Dans Clés API, cliquez sur Nouvelle clé et choisissez l'environnement :
| Environnement | La clé commence par | À utiliser |
|---|---|---|
| Test | zarex_test_ | En local et en préproduction |
| Production | zarex_live_ | Sur votre site en ligne |
Copiez la clé tout de suite
Elle n'est affichée qu'une seule fois : Zarex n'en conserve qu'une empreinte. En cas de perte, révoquez-la et créez-en une autre.
Ajoutez la clé à votre environnement
Dans le fichier d'environnement de votre application (.env.local avec Next.js, .env ailleurs) :
ZAREX_KEY=zarex_test_...Gardez la clé secrète
Ne la commitez jamais dans Git, et ne l'exposez jamais au navigateur : avec Next.js, pas de préfixe NEXT_PUBLIC_. Elle ne sert que côté serveur.
Installez le SDK
npm install @zarex/nextAjoutez vos premières règles
On commence en DRY_RUN : les règles sont évaluées et journalisées, mais ne bloquent rien. Vous voyez ce qu'elles feraient, sans risque pour vos visiteurs.
import { withZarex, shield, rateLimit } from "@zarex/next";
export const GET = withZarex(
{
key: process.env.ZAREX_KEY!,
ipSource: "vercel", // voir « L'adresse IP du visiteur » ci-dessous
rules: [
shield({ mode: "DRY_RUN" }),
rateLimit({ mode: "DRY_RUN", max: 100, window: "1m" }),
],
},
async () => Response.json({ produits: [] })
);Vérifiez dans le dashboard
Lancez votre application, faites quelques requêtes, puis ouvrez le Journal des décisions du dashboard : chaque requête y apparaît, avec son verdict et la règle concernée.
Pour voir le Shield à l'œuvre, envoyez une tentative d'injection SQL à une route protégée (avec l'exemple Next.js : /api/produits) :
curl "http://localhost:3000/?id=1%27%20OR%20%271%27=%271"En DRY_RUN, la requête passe quand même : le journal montre ce que le Shield aurait fait.
Passez en LIVE
Quand le journal vous convient, retirez mode: "DRY_RUN" : sans option mode, une règle est en LIVE, elle bloque pour de vrai.
rules: [shield(), rateLimit({ max: 100, window: "1m" })],En production, utilisez une clé zarex_live_. Une requête refusée reçoit automatiquement une réponse 403, ou 429 avec l'en-tête Retry-After pour une limite de débit.
L'adresse IP du visiteur
La limite de débit compte les requêtes par visiteur : Zarex doit donc connaître sa vraie adresse IP. Un mauvais réglage fait passer tous vos visiteurs pour une seule adresse.
Next.js ne donne jamais l'adresse de la connexion : Zarex la lit dans un en-tête écrit par votre hébergeur ou votre proxy. Sur Vercel, Fly.io et Cloudflare Workers, ipSource peut être omis : la plateforme est détectée automatiquement. Ailleurs, il est obligatoire, et l'application refuse de démarrer sans lui plutôt que de deviner :
| Hébergement | ipSource |
|---|---|
| Vercel, Fly.io, Cloudflare Workers | Rien à faire. |
| VPS ou Docker derrière nginx ou Caddy | { header: "x-real-ip" } |
| Cloudflare devant votre serveur | { header: "cf-connecting-ip" } |
En local, next dev ne fournit pas d'en-tête d'adresse : les requêtes ne sont pas vérifiées. Détails : Next.js.