@zarex/bun 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,97 @@
+# @zarex/bun
+
+Enveloppe Zarex pour le serveur HTTP natif de Bun (`Bun.serve`) — 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.
+
+## Installation
+
+```bash
+bun add @zarex/bun
+```
+
+## Démarrage rapide
+
+```ts
+import { zarexBun, shield, rateLimit } from "@zarex/bun";
+
+const wrap = zarexBun({
+  key: process.env.ZAREX_KEY!,
+  ipSource: "socket", // Bun donne l'adresse de la connexion : toutes les sources d'IP fonctionnent
+  rules: [shield(), rateLimit({ max: 100, window: "1m" })],
+});
+
+Bun.serve({
+  fetch: wrap(async (request) => new Response("ok")),
+});
+```
+
+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
+
+Bun expose nativement l'adresse de la connexion TCP via `server.requestIP(request)` — contrairement à Next.js ou à d'autres runtimes edge, **toutes** les valeurs d'`ipSource` fonctionnent ici, y compris `"socket"` (recommandé si rien ne se trouve devant votre serveur Bun) :
+
+| `ipSource` | Quand l'utiliser |
+|---|---|
+| `"socket"` | Pas de proxy devant Bun : l'adresse de la connexion TCP. |
+| `"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 devant Bun, ou leurs plages CIDR exactes. |
+
+## Options
+
+```ts
+zarexBun({
+  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 wrap = zarexBun({ ..., secureHeaders: true, responseGuard: true });
+```
+
+Appliqués automatiquement à toute réponse produite par votre gestionnaire — aucun appel supplémentaire à faire.
+
+### Identifiants personnalisés (`call`)
+
+```ts
+const wrap = zarexBun({
+  key, ipSource: "socket",
+  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/bun",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Zarex — Bun.serve",
   "license": "MIT",
   "publishConfig": {
@@ -27,7 +27,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@zarex/core": "^0.1.0"
+    "@zarex/core": "^0.1.1"
   },
   "scripts": {
     "build": "tsup"