@zarex/fastify 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,158 @@
+# @zarex/fastify
+
+Hook Zarex pour Fastify — protège votre application contre les bots, les abus de trafic, les injections (SQL, XSS, SSRF...) et les fuites de données sensibles, en quelques lignes.
+
+Compatible Fastify 4 et 5 (aucune dépendance à `fastify` à l'exécution). Fonctionne aussi avec NestJS (plateforme Fastify).
+
+## Installation
+
+```bash
+npm install @zarex/fastify
+```
+
+## Démarrage rapide
+
+```ts
+import Fastify from "fastify";
+import { zarexFastify, shield, rateLimit } from "@zarex/fastify";
+
+const app = Fastify();
+
+app.addHook(
+  "onRequest",
+  zarexFastify({
+    key: process.env.ZAREX_KEY!,
+    rules: [shield(), rateLimit({ max: 100, window: "1m" })],
+  })
+);
+
+app.get("/", async () => ({ ok: true }));
+app.listen({ port: 3000 });
+```
+
+Une requête refusée reçoit automatiquement `403 Forbidden` (ou `429 Too Many Requests` avec l'en-tête `retry-after` pour une limite de débit) — sans aucun code supplémentaire.
+
+**Fail-open** : si Zarex est injoignable, lent ou répond de façon inattendue, la requête passe toujours. Une panne chez Zarex ne doit jamais faire tomber votre application.
+
+### Avec NestJS (plateforme Fastify)
+
+```ts
+import type { FastifyInstance } from "fastify";
+(app.getHttpAdapter().getInstance() as FastifyInstance).addHook(
+  "onRequest",
+  zarexFastify({ key, rules: [shield()] })
+);
+```
+
+## L'adresse IP du visiteur
+
+Par défaut (`ipSource` non renseigné), l'adaptateur utilise `request.ip`, calculé par Fastify selon l'option [`trustProxy`](https://fastify.dev/docs/latest/Reference/Server/#trustproxy) de votre serveur :
+
+```ts
+const app = Fastify({ trustProxy: 1 }); // 1 proxy de confiance devant Fastify
+```
+
+Sans `trustProxy`, Fastify ignore `X-Forwarded-For` — configurez-le pour correspondre à **votre** infrastructure réelle, sinon tous vos visiteurs apparaissent sous la même adresse IP et toute règle de limite de débit basée sur l'IP devient inutile.
+
+## Options
+
+```ts
+zarexFastify({
+  key: string,              // obligatoire : clé API du projet
+  rules: Rule[],            // obligatoire : 1 à 10 règles, voir ci-dessous
+  ipSource?: IpSource,      // défaut "framework" (voir ci-dessus)
+  inspectBody?: boolean,    // défaut false — voir "Inspecter le corps"
+  secureHeaders?: boolean | SecureHeadersOptions,
+  responseGuard?: boolean | ResponseGuardOptions, // voir zarexFastifyOnSend ci-dessous
+  onDeny?: (req, reply, decision) => void,
+  onDegraded?: (req, decision) => void,
+  call?: (req) => ProtectCall | undefined,
+  timeoutMs?: number,       // défaut 500 ms
+  breaker?: BreakerOptions | false,
+})
+```
+
+### Inspecter le corps de la requête (`inspectBody`) — attention au hook choisi
+
+```ts
+// ⚠️ "onRequest" : Fastify n'a PAS ENCORE lu le corps à ce stade — inspectBody ne verrait jamais rien.
+app.addHook("onRequest", zarexFastify({ ..., inspectBody: true })); // piège
+
+// ✅ "preHandler" : le corps est déjà disponible.
+app.addHook("preHandler", zarexFastify({ ..., inspectBody: true }));
+```
+
+Si vous enregistrez le hook en `onRequest` avec `inspectBody: true` alors qu'une requête a manifestement un corps (`Content-Length` > 0), un avertissement unique s'affiche dans la console (`console.warn`) pour éviter que cette erreur passe inaperçue.
+
+### En-têtes de sécurité (`secureHeaders`)
+
+```ts
+app.addHook("onRequest", zarexFastify({ ..., secureHeaders: true }));
+```
+
+Ajoutés à **toutes** les réponses, y compris les refus. `true` applique des défauts prudents (HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy...). Retire aussi `x-powered-by`.
+
+### Surveillance des réponses (`responseGuard`) — un hook séparé
+
+```ts
+app.addHook("onSend", zarexFastifyOnSend({ responseGuard: true }));
+```
+
+Contrairement aux autres adaptateurs, Fastify demande d'enregistrer un **second hook** (`onSend`) pour surveiller les réponses de votre application et masquer (ou bloquer) les cartes bancaires, clés d'API, jetons JWT, mots de passe... qui s'y retrouveraient par erreur. Les flux (streams) ne sont pas analysés.
+
+### Identifiants personnalisés (`call`)
+
+```ts
+app.addHook(
+  "preHandler",
+  zarexFastify({
+    key,
+    rules: [rateLimit({ max: 100, window: "1m", characteristics: ["userId"] })],
+    call: (req) => ({ characteristics: { userId: (req as any).user?.id } }),
+  })
+);
+```
+
+Les valeurs sont hachées en SHA-256 avant l'envoi à Zarex. Une erreur dans cette fonction est silencieusement ignorée. `call` peut aussi fournir `tokensRequested`, `email`/`phone` ou `text` (voir [`@zarex/core`](https://www.npmjs.com/package/@zarex/core)).
+
+### Lire le résultat de la décision
+
+```ts
+app.get("/", async (req) => {
+  console.log(req.zarex?.verdict); // "ALLOW" | "DENY" | "ERROR"
+  return { ok: true };
+});
+```
+
+## Règles disponibles
+
+| Fonction | Résumé |
+|---|---|
+| `shield(opts?)` | Pare-feu applicatif : injection SQL, XSS, traversée de répertoires, SSRF, SSTI... |
+| `rateLimit({ max, window, ... })` | Limite de requêtes par visiteur sur une fenêtre de temps. |
+| `tokenBucket({ capacity, refillRate, interval })` | Budget de jetons avec pics autorisés. |
+| `detectBot(opts?)` | Détecte les robots connus, avec vérification DNS inversée. |
+| `requestFilter({ expressions, logic })` | Règles personnalisées sur IP, chemin, en-têtes, cookies, pays... |
+| `sensitiveInfo(opts?)` | Refuse une requête contenant une donnée sensible (nécessite `inspectBody`). |
+| `emailValidation(opts?)` | Valide un email donné via `call: () => ({ email })`. |
+| `phoneValidation(opts?)` | Valide un numéro donné, orienté opérateurs africains (MTN, Moov, Orange, Wave...). |
+| `promptInjection(opts?)` | Détecte les tentatives de manipulation d'un assistant IA, via `call: () => ({ text })`. |
+
+Chaque règle accepte `mode: "LIVE" | "DRY_RUN" | "OFF"`. Détails complets des options : voir [`@zarex/core`](https://www.npmjs.com/package/@zarex/core).
+
+## Réponse de refus personnalisée (`onDeny`)
+
+```ts
+zarexFastify({
+  ...,
+  onDeny: (req, reply, decision) => {
+    reply.code(403).send({ message: "Accès refusé", id: decision.id });
+  },
+});
+```
+
+Sans `onDeny`, la réponse par défaut est `403` (ou `429` + `retry-after`), au format `{ error: { code, message, request_id } }`.
+
+## Licence
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zarex/fastify",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Zarex — Fastify (et NestJS avec Fastify)",
   "license": "MIT",
   "publishConfig": {
@@ -27,7 +27,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@zarex/core": "^0.1.0"
+    "@zarex/core": "^0.1.1"
   },
   "peerDependencies": {
     "fastify": ">=4"