@zarex/next 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,117 @@
+# @zarex/next
+
+Garde Zarex pour Next.js — fonctionne dans le middleware (runtime edge) **et** dans les route handlers. Aucune dépendance à `next` à l'exécution : utilise la `Request`/`Response` standard, sans risque d'incompatibilité de version.
+
+## Installation
+
+```bash
+npm install @zarex/next
+```
+
+## Démarrage rapide — middleware
+
+```ts
+// middleware.ts
+import { NextResponse } from "next/server";
+import { zarexNext, shield, rateLimit } from "@zarex/next";
+
+const guard = zarexNext({
+  key: process.env.ZAREX_KEY!,
+  ipSource: "vercel", // voir "L'adresse IP du visiteur" ci-dessous
+  rules: [shield(), rateLimit({ max: 100, window: "1m" })],
+});
+
+export async function middleware(request: Request) {
+  // `guard.finalize(...)` sur la réponse AUTORISÉE aussi, pas seulement sur un refus —
+  // sans cet appel, secureHeaders/responseGuard ne s'appliqueraient JAMAIS au trafic autorisé.
+  return (await guard(request)) ?? guard.finalize(NextResponse.next(), request);
+}
+```
+
+**Fail-open** : si Zarex est injoignable, lent ou répond de façon inattendue, la requête passe toujours.
+
+## Démarrage rapide — route handler
+
+```ts
+// app/api/produits/route.ts
+import { withZarex, shield } from "@zarex/next";
+
+export const GET = withZarex(
+  { key: process.env.ZAREX_KEY!, ipSource: "vercel", rules: [shield()] },
+  async (request) => Response.json({ produits: [] })
+);
+```
+
+Avec `withZarex`, `secureHeaders`/`responseGuard` s'appliquent automatiquement à la réponse — pas d'appel à `finalize` à faire soi-même.
+
+## L'adresse IP du visiteur — point important
+
+Le **middleware** Next.js ne voit jamais l'adresse de la connexion TCP (limite de la plateforme, pas du SDK). Seules les sources qui lisent un en-tête posé par la plateforme fonctionnent donc en middleware :
+
+| `ipSource` | Quand l'utiliser |
+|---|---|
+| `"vercel"` | Hébergé sur Vercel. |
+| `"fly"` | Hébergé sur Fly.io. |
+| `"auto"` | Détecte Vercel/Fly via les variables d'environnement du serveur. |
+| `"cloudflare"` | Derrière Cloudflare : lit `CF-Connecting-IP`, seulement si la connexion vient réellement de Cloudflare. |
+| `{ proxies: n }` / `{ trustedProxies: [...] }` | Un nombre connu de proxys de confiance, ou leurs plages CIDR exactes. |
+
+Hébergé ailleurs (nginx, Docker, un VPS...) sans que la plateforme ne pose un en-tête fiable : utiliser un route handler avec `withZarex` ne change rien à cette limite non plus, puisque la limite vient de Next.js lui-même, pas de l'adaptateur.
+
+## Options
+
+```ts
+zarexNext({
+  key: string,              // obligatoire : clé API du projet
+  rules: Rule[],            // obligatoire : 1 à 10 règles, voir ci-dessous
+  ipSource: IpSource,       // obligatoire — voir ci-dessus
+  inspectBody?: boolean,
+  secureHeaders?: boolean | SecureHeadersOptions,
+  responseGuard?: boolean | ResponseGuardOptions,
+  onDeny?: (request, decision) => Response | undefined,
+  onDegraded?: (request, decision) => void,
+  call?: (request: Request) => ProtectCall | undefined,
+  timeoutMs?: number,       // défaut 500 ms
+  breaker?: BreakerOptions | false,
+})
+```
+
+### En-têtes de sécurité et surveillance des réponses
+
+```ts
+const guard = zarexNext({ ..., secureHeaders: true, responseGuard: true });
+```
+
+En **middleware**, appelez bien `guard.finalize(response, request)` sur la réponse autorisée (voir l'exemple de démarrage rapide) — un avertissement s'affiche au démarrage (`console.warn`) si `secureHeaders`/`responseGuard` est configuré sans jamais appeler `finalize` sur le chemin autorisé, pour éviter que cette protection reste silencieusement inactive. En **route handler** (`withZarex`), c'est automatique.
+
+### Identifiants personnalisés (`call`)
+
+```ts
+zarexNext({
+  key, ipSource: "vercel",
+  rules: [rateLimit({ max: 100, window: "1m", characteristics: ["userId"] })],
+  call: (request) => ({ characteristics: { userId: request.headers.get("x-user-id") ?? undefined } }),
+});
+```
+
+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)).
+
+## 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).
+
+## Licence
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zarex/next",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Zarex — Next.js (middleware edge et route handlers)",
   "license": "MIT",
   "publishConfig": {
@@ -27,7 +27,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@zarex/core": "^0.1.0"
+    "@zarex/core": "^0.1.1"
   },
   "peerDependencies": {
     "next": ">=13"