@zarex/core 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,92 @@
+# @zarex/core
+
+Moteur partagé du SDK Zarex — détection locale des données sensibles, résolution fiable de l'IP du visiteur, en-têtes de sécurité, surveillance des réponses, et la logique commune à tous les adaptateurs de framework.
+
+> **Dans la plupart des cas, vous n'installez pas ce paquet directement.** Installez plutôt l'adaptateur de votre framework — [`@zarex/express`](https://www.npmjs.com/package/@zarex/express), [`@zarex/fastify`](https://www.npmjs.com/package/@zarex/fastify), [`@zarex/next`](https://www.npmjs.com/package/@zarex/next), [`@zarex/sveltekit`](https://www.npmjs.com/package/@zarex/sveltekit) ou [`@zarex/bun`](https://www.npmjs.com/package/@zarex/bun) — qui dépend déjà de `@zarex/core` et réexporte tout ce dont vous avez besoin. Ce paquet est utile si vous construisez votre propre intégration pour un framework non couvert.
+
+## Qu'est-ce que Zarex ?
+
+Zarex est une plateforme de sécurité applicative : un service qui protège une application web contre les bots, les abus de trafic, les injections (SQL, XSS, SSRF…) et les fuites de données sensibles. Le SDK s'installe dans votre application ; aucune autre configuration d'infrastructure n'est nécessaire.
+
+**Fail-open** : si Zarex est injoignable, lent, ou répond de façon inattendue, la requête du visiteur passe toujours. Une panne chez Zarex ne doit jamais faire tomber votre application.
+
+## Ce que fait ce paquet
+
+| Domaine | Export principal |
+|---|---|
+| Orchestration des règles | `createZarex(options)` → instance avec `.protect(input, call?)` |
+| Règles disponibles | `shield`, `rateLimit`, `tokenBucket`, `detectBot`, `requestFilter`, `sensitiveInfo`, `emailValidation`, `phoneValidation`, `promptInjection` |
+| Résolution de l'IP visiteur | `createIpResolver(source)` |
+| Détection locale de données sensibles | `detectSensitive`, `findSensitive`, `maskSensitive` |
+| En-têtes autorisés à transmettre | `selectHeaders`, `DEFAULT_FORWARDED_HEADERS`, `NEVER_FORWARD` |
+| En-têtes de sécurité HTTP | `secureHeaders`, `prepareSecureHeaders`, `withSecureHeaders` |
+| Surveillance des réponses sortantes | `guardResponseText`, `applyGuard`, `normalizeGuardOptions` |
+| Aide aux adaptateurs web standards (`Request`/`Response`) | `guardWebRequest`, `protectWebRequest`, `createWebFinalizer` |
+
+## Utilisation directe (cas avancé)
+
+```ts
+import { createZarex, shield, rateLimit } from "@zarex/core";
+
+const zarex = createZarex({
+  key: process.env.ZAREX_KEY!,
+  ipSource: "socket", // obligatoire — voir IpSource ci-dessous
+  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",
+});
+
+if (decision.denied) {
+  // decision.verdict === "DENY", decision.deniedBy donne la règle responsable
+}
+```
+
+### `ZarexOptions`
+
+| Option | Type | Description |
+|---|---|---|
+| `key` | `string` | **Obligatoire.** Clé API du projet (jamais journalisée). |
+| `rules` | `Rule[]` | **Obligatoire.** 1 à 10 règles, dans l'ordre d'évaluation. |
+| `ipSource` | `IpSource` | **Obligatoire.** Comment trouver l'IP du visiteur — un mauvais choix fait passer tous vos visiteurs pour une seule adresse. |
+| `timeoutMs` | `number` | Délai maximal avant que la requête ne passe quand même (défaut 500 ms, fail-open). |
+| `breaker` | `BreakerOptions \| false` | Disjoncteur (défaut : 5 échecs → 10 s de pause). `false` pour le désactiver. |
+| `inspectCookies` | `boolean` | Transmettre aussi l'en-tête `Cookie` au Shield (défaut `false` : il contient les sessions de vos visiteurs). |
+| `extraHeaders` | `string[]` | En-têtes additionnels à transmettre (jamais `Authorization` ni `Set-Cookie`, quoi qu'il arrive). |
+| `baseUrl` | `string` | Inutile en usage normal. À ne définir que pour les tests ou un environnement local. |
+
+### `IpSource`
+
+| Valeur | Quand l'utiliser |
+|---|---|
+| `"socket"` | Pas de proxy devant votre application : l'adresse de la connexion TCP. |
+| `"express"` / `"framework"` | Laissez le framework (Express, Fastify, SvelteKit…) calculer l'IP — utilisé automatiquement par les adaptateurs correspondants. |
+| `"cloudflare"` | Derrière Cloudflare : lit `CF-Connecting-IP`, seulement si la connexion vient réellement de Cloudflare. |
+| `"vercel"` / `"fly"` | Hébergé sur Vercel / Fly.io : lit l'en-tête posé par la plateforme. |
+| `"auto"` | Détecte Vercel/Fly via les variables d'environnement du serveur. |
+| `{ proxies: n }` | `n` proxys de confiance devant votre application (comptés depuis la droite de `X-Forwarded-For`). |
+| `{ trustedProxies: ["10.0.0.0/8", ...] }` | Plages CIDR exactes de vos proxys. |
+
+## Règles disponibles
+
+| Fonction | Résumé |
+|---|---|
+| `shield(opts?)` | Pare-feu applicatif : injection SQL, XSS, traversée de répertoires, SSRF, SSTI… |
+| `rateLimit(opts)` | Limite le nombre de requêtes par visiteur sur une fenêtre de temps. |
+| `tokenBucket(opts)` | 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 pour les robots prétendant être Google/Bing. |
+| `requestFilter(opts)` | Règles personnalisées (`champ opérateur valeur`) sur IP, chemin, en-têtes, cookies, pays... |
+| `sensitiveInfo(opts?)` | Refuse une requête contenant une donnée sensible (carte bancaire, clé API, mot de passe...). |
+| `emailValidation(opts?)` | Valide un email donné via `protect(..., { email })` (jetable, sans MX, faute de frappe...). |
+| `phoneValidation(opts?)` | Valide un numéro donné via `protect(..., { phone })`, orienté opérateurs africains. |
+| `promptInjection(opts?)` | Détecte les tentatives de manipuler un assistant IA, dans un texte donné via `protect(..., { text })`. |
+
+Chaque fonction accepte `mode: "LIVE" | "DRY_RUN" | "OFF"` (défaut `"LIVE"`) — `"DRY_RUN"` évalue et journalise sans jamais bloquer, utile pour observer une règle avant de l'activer.
+
+## Licence
+
+MIT