Options du SDK
Toutes les options communes aux SDK Zarex, quel que soit votre framework.
Ces options se passent à la fonction de votre framework : withZarex / zarexNext, zarex, zarexFastify, zarexHandle ou zarexBun.
Options
| Option | Type | Rôle |
|---|---|---|
key | string | Obligatoire. La clé API du projet. Elle n'est jamais écrite dans les logs. |
rules | Rule[] | Obligatoire. De 1 à 10 règles. |
ipSource | voir L'adresse IP | Comment trouver l'adresse IP du visiteur. |
inspectBody | boolean | Transmettre le corps des requêtes (Shield, données sensibles). Défaut false. |
inspectCookies | boolean | Transmettre l'en-tête Cookie (Shield, filtres sur les cookies). Défaut false. |
extraHeaders | string[] | En-têtes supplémentaires à transmettre. Authorization et Set-Cookie ne sont jamais transmis. |
call | (requête) => ProtectCall | Données à fournir pour chaque requête : voir ci-dessous. |
onDeny | fonction | Remplace la réponse de refus par la vôtre. Avec Next.js, SvelteKit et Bun, elle doit renvoyer une Response (sinon : refus par défaut, la requête reste bloquée). |
onDegraded | fonction | Appelée quand Zarex n'a pas pu décider et que la requête a été laissée passer. |
secureHeaders | boolean ou objet | Ajoute les en-têtes de sécurité HTTP à vos réponses. |
responseGuard | boolean ou objet | Masque les données sensibles qui se retrouveraient dans vos réponses. |
timeoutMs | number | Délai maximal d'attente de la décision. Défaut 500 ms. Au-delà, la requête passe. |
breaker | objet ou false | Après plusieurs échecs consécutifs, laisse passer les requêtes sans attendre pendant une courte pause. false pour le désactiver. |
logger | { warn, error } ou false | Où écrire les avertissements du SDK. false pour les couper. |
Les données de call
call reçoit la requête de votre framework et renvoie, pour cette requête :
| Champ | Utilisé par |
|---|---|
characteristics | Limitation de débit et budget de jetons : identifiants du visiteur (par exemple { userId: "42" }), hachés avant l'envoi. |
tokensRequested | Budget de jetons : jetons consommés par la requête. Défaut 1. |
email | Validation d'e-mail. |
phone | Validation de téléphone. |
text | Données sensibles et injection de prompt. |
rules | Remplace les règles configurées, pour cette requête seulement. |
Une erreur dans call est ignorée : la requête continue, sans ces données.
Utilisation directe
Pour un contrôle total, ou hors des frameworks pris en charge, créez une instance et appelez protect vous-même :
import { createZarex, shield, rateLimit } from "@zarex/express"; // tous les paquets l'exportent
const zarex = createZarex({
key: process.env.ZAREX_KEY!,
ipSource: "socket",
rules: [shield(), rateLimit({ max: 100, window: "1m" })],
});
const decision = await zarex.protect(
{ method: "GET", path: "/api/produits", headers: { "user-agent": "…" }, socketIp: "41.7.7.7" },
{ characteristics: { userId: "42" } }
);
if (decision.denied) {
// refuser la requête
}protect ne lève jamais d'erreur : en cas de problème, la décision est allowed et degraded.