@zarex/sveltekit 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,107 @@
+# @zarex/sveltekit
+
+Hook Zarex pour SvelteKit — 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.
+
+Aucune dépendance à `@sveltejs/kit` à l'exécution.
+
+## Installation
+
+```bash
+npm install @zarex/sveltekit
+```
+
+## Démarrage rapide
+
+```ts
+// src/hooks.server.ts
+import { zarexHandle, shield, rateLimit } from "@zarex/sveltekit";
+
+export const handle = zarexHandle({
+  key: process.env.ZAREX_KEY!,
+  rules: [shield(), rateLimit({ max: 100, window: "1m" })],
+});
+```
+
+Avec d'autres hooks (`sequence`) :
+
+```ts
+import { sequence } from "@sveltejs/kit/hooks";
+import { zarexHandle } from "@zarex/sveltekit";
+
+export const handle = sequence(zarexHandle({ key, rules: [shield()] }), maHandle);
+```
+
+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 `event.getClientAddress()`, calculé par SvelteKit selon la configuration de **votre** adaptateur de déploiement (`adapter-node` : variables `ADDRESS_HEADER` et `XFF_DEPTH` ; `adapter-vercel`, etc. — voir la documentation de votre adaptateur). Un mauvais réglage ici fait passer tous vos visiteurs pour une seule adresse IP.
+
+## Options
+
+```ts
+zarexHandle({
+  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,
+  secureHeaders?: boolean | SecureHeadersOptions,
+  responseGuard?: boolean | ResponseGuardOptions,
+  onDeny?: (event, decision) => Response | undefined,
+  onDegraded?: (event, decision) => void,
+  call?: (event) => ProtectCall | undefined,
+  timeoutMs?: number,       // défaut 500 ms
+  breaker?: BreakerOptions | false,
+})
+```
+
+### En-têtes de sécurité et surveillance des réponses
+
+```ts
+export const handle = zarexHandle({ ..., secureHeaders: true, responseGuard: true });
+```
+
+Appliqués automatiquement à toute réponse (y compris celle que `resolve(event)` aurait produite) — aucun appel supplémentaire à faire, contrairement au middleware Next.js.
+
+### Identifiants personnalisés (`call`)
+
+```ts
+export const handle = zarexHandle({
+  key,
+  rules: [rateLimit({ max: 100, window: "1m", characteristics: ["userId"] })],
+  call: (event) => ({ characteristics: { userId: event.locals.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
+// dans une route +page.server.ts ou +server.ts
+export function load({ locals }) {
+  console.log(locals.zarex?.verdict); // "ALLOW" | "DENY" | "ERROR"
+}
+```
+
+## 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/sveltekit",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Zarex — SvelteKit (hook handle)",
   "license": "MIT",
   "publishConfig": {
@@ -27,7 +27,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@zarex/core": "^0.1.0"
+    "@zarex/core": "^0.1.1"
   },
   "peerDependencies": {
     "@sveltejs/kit": ">=1"