@zarex/express 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,150 @@
+# @zarex/express
+
+Middleware Zarex pour Express — 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 Express 4 et 5 (aucune dépendance à `express` à l'exécution).
+
+## Installation
+
+```bash
+npm install @zarex/express
+```
+
+## Démarrage rapide
+
+```ts
+import express from "express";
+import { zarex, shield, rateLimit } from "@zarex/express";
+
+const app = express();
+
+app.use(
+  zarex({
+    key: process.env.ZAREX_KEY!,
+    rules: [shield(), rateLimit({ max: 100, window: "1m" })],
+  })
+);
+
+app.get("/", (req, res) => res.send("ok"));
+app.listen(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.
+
+## L'adresse IP du visiteur
+
+Par défaut (`ipSource` non renseigné), l'adaptateur utilise `req.ip`, calculé par Express lui-même selon le réglage [`trust proxy`](https://expressjs.com/en/guide/behind-proxies.html) de votre application :
+
+```ts
+app.set("trust proxy", 1); // 1 proxy de confiance devant Express (ex. un load balancer)
+```
+
+Configurez `trust proxy` pour correspondre à **votre** infrastructure réelle — un mauvais réglage ici (ou son absence derrière un vrai proxy) fait passer tous vos visiteurs pour une seule et même adresse IP, ce qui casse silencieusement toute règle de limite de débit basée sur l'IP.
+
+## Options
+
+```ts
+zarex({
+  key: string,              // obligatoire : clé API du projet
+  rules: Rule[],            // obligatoire : 1 à 10 règles, voir ci-dessous
+  ipSource?: IpSource,      // défaut "express" (voir ci-dessus)
+  inspectBody?: boolean,    // défaut false — voir "Inspecter le corps"
+  secureHeaders?: boolean | SecureHeadersOptions,
+  responseGuard?: boolean | ResponseGuardOptions,
+  onDeny?: (req, res, 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`)
+
+```ts
+app.use(express.json()); // AVANT le middleware Zarex
+app.use(zarex({ ..., inspectBody: true }));
+```
+
+Par défaut, le corps n'est **jamais** transmis à Zarex (il peut contenir des mots de passe). Avec `inspectBody: true`, le middleware Zarex doit être placé **après** `express.json()` / `express.urlencoded()` pour que `req.body` soit déjà peuplé. Le SDK ne lit jamais le flux lui-même.
+
+### En-têtes de sécurité (`secureHeaders`)
+
+```ts
+zarex({ ..., secureHeaders: true }); // HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy...
+```
+
+Ajoutés à **toutes** les réponses, y compris les refus. `true` applique des défauts prudents ; passez un objet pour personnaliser (voir `SecureHeadersOptions` dans `@zarex/core`). Retire aussi l'en-tête `X-Powered-By`.
+
+### Surveillance des réponses (`responseGuard`)
+
+```ts
+zarex({ ..., responseGuard: true });
+```
+
+Surveille les réponses de **votre** application (`res.send` / `res.json`) et masque (ou bloque) les cartes bancaires, clés d'API, jetons JWT, mots de passe... qui s'y retrouveraient par erreur. Tout se passe sur votre serveur, rien n'est jamais envoyé à Zarex pour cette vérification.
+
+**Limite** : ne couvre pas `res.write()` / `res.end()` appelés directement, ni les flux (streams).
+
+### Identifiants personnalisés (`call`)
+
+```ts
+app.use(authMiddleware); // avant Zarex, pour que req.user existe
+app.use(
+  zarex({
+    key,
+    rules: [rateLimit({ max: 100, window: "1m", characteristics: ["userId"] })],
+    call: (req) => ({ characteristics: { userId: req.user?.id } }),
+  })
+);
+```
+
+Place le middleware Zarex **après** votre authentification pour que l'identifiant soit disponible. Les valeurs sont hachées en SHA-256 avant l'envoi à Zarex. Une erreur dans cette fonction est silencieusement ignorée (la requête continue, sans caractéristique personnalisée).
+
+`call` peut aussi fournir `tokensRequested` (règle `tokenBucket`), `email`/`phone` (validation) ou `text` (règles `sensitiveInfo`/`promptInjection`).
+
+### Lire le résultat de la décision
+
+```ts
+app.get("/", (req, res) => {
+  console.log(req.zarex?.verdict); // "ALLOW" | "DENY" | "ERROR"
+  res.send("ok");
+});
+```
+
+Disponible pour toute requête ayant traversé le middleware, qu'elle ait été autorisée ou non.
+
+## 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 (`"30s"`, `"1m"`, `"1h"`, `"1d"`). |
+| `tokenBucket({ capacity, refillRate, interval })` | Budget de jetons avec pics autorisés (ex. appels à un modèle d'IA). |
+| `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é via `call`, 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"` — `"DRY_RUN"` évalue et journalise sans jamais bloquer, pour observer une règle avant de l'activer. Détails complets des options de chaque règle : voir [`@zarex/core`](https://www.npmjs.com/package/@zarex/core).
+
+## Réponse de refus personnalisée (`onDeny`)
+
+```ts
+zarex({
+  ...,
+  onDeny: (req, res, decision) => {
+    res.status(403).json({ message: "Accès refusé", id: decision.id });
+  },
+});
+```
+
+Sans `onDeny`, la réponse par défaut est `403` (ou `429` + `Retry-After` pour une limite de débit), au format `{ error: { code, message, request_id } }`.
+
+## Licence
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zarex/express",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Zarex — middleware Express",
   "license": "MIT",
   "publishConfig": {
@@ -27,7 +27,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@zarex/core": "^0.1.0"
+    "@zarex/core": "^0.1.1"
   },
   "peerDependencies": {
     "express": ">=4"