@zarex/express 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kodjogbe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,150 @@
-# Temporary Holding Version
+# @zarex/express
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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/dist/index.cjs

@@ -0,0 +1,174 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CLOUDFLARE_RANGES: () => import_core2.CLOUDFLARE_RANGES,
+  PRIVATE_NETWORKS: () => import_core2.PRIVATE_NETWORKS,
+  createZarex: () => import_core2.createZarex,
+  detectBot: () => import_core2.detectBot,
+  emailValidation: () => import_core2.emailValidation,
+  phoneValidation: () => import_core2.phoneValidation,
+  promptInjection: () => import_core2.promptInjection,
+  rateLimit: () => import_core2.rateLimit,
+  requestFilter: () => import_core2.requestFilter,
+  secureHeaders: () => import_core2.secureHeaders,
+  sensitiveInfo: () => import_core2.sensitiveInfo,
+  shield: () => import_core2.shield,
+  tokenBucket: () => import_core2.tokenBucket,
+  withSecureHeaders: () => import_core2.withSecureHeaders,
+  zarex: () => zarex
+});
+module.exports = __toCommonJS(index_exports);
+var import_core = require("@zarex/core");
+var import_core2 = require("@zarex/core");
+var decoder = new TextDecoder("utf-8");
+function installResponseGuard(res, guard) {
+  const original = res.send;
+  if (typeof original !== "function") return;
+  res.send = function guardedSend(body) {
+    let next = body;
+    try {
+      const ct = String((typeof res.get === "function" ? res.get("Content-Type") : void 0) ?? "");
+      const isString = typeof body === "string";
+      const isBytes = body instanceof Uint8Array;
+      if (isString && (ct === "" || (0, import_core.isScannableContentType)(ct)) || isBytes && (0, import_core.isScannableContentType)(ct)) {
+        const text = isString ? body : decoder.decode(body);
+        const r = (0, import_core.applyGuard)(text, ct || "text/html", guard);
+        if (r.action === "masked") next = r.body;
+        else if (r.action === "blocked" && !res.headersSent) {
+          res.status(500);
+          res.set("Content-Type", "application/json; charset=utf-8");
+          next = r.body;
+        }
+      }
+    } catch {
+      next = body;
+    }
+    return original.call(this, next);
+  };
+}
+function bodyToString(body) {
+  if (body === void 0 || body === null) return void 0;
+  if (typeof body === "string") return body;
+  if (typeof body === "object" && typeof body.toString === "function" && body.constructor?.name === "Buffer") {
+    return body.toString("utf8");
+  }
+  try {
+    const s = JSON.stringify(body);
+    return typeof s === "string" ? s : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function defaultDeny(_req, res, d) {
+  const limited = d.deniedBy?.ruleType === "RATE_LIMIT" || d.deniedBy?.ruleType === "TOKEN_BUCKET";
+  if (res.headersSent) return;
+  if (limited) {
+    if (d.retryAfterSeconds !== void 0) res.set("Retry-After", String(d.retryAfterSeconds));
+    res.status(429).json({ error: { code: "rate_limited", message: "Too many requests", request_id: d.id } });
+  } else {
+    res.status(403).json({ error: { code: "forbidden", message: "Request blocked", request_id: d.id } });
+  }
+}
+function zarex(options, extra = {}) {
+  const isInstance = typeof options.protect === "function";
+  const opts = isInstance ? extra : options;
+  const instance = isInstance ? options : (0, import_core.createZarex)({ ...options, ipSource: options.ipSource ?? "express" });
+  const prepared = (0, import_core.prepareSecureHeaders)(opts.secureHeaders);
+  const guard = (0, import_core.normalizeGuardOptions)(opts.responseGuard);
+  return async function zarexMiddleware(req, res, next) {
+    let decision;
+    try {
+      if (prepared) {
+        const set = (0, import_core.isLocalHost)(req.hostname ?? (typeof req.headers["host"] === "string" ? req.headers["host"] : void 0)) ? prepared.http : prepared.https;
+        for (const [k, v] of Object.entries(set)) res.set(k, v);
+        if (prepared.removePoweredBy) res.removeHeader?.("X-Powered-By");
+      }
+      if (guard) installResponseGuard(res, guard);
+    } catch {
+    }
+    try {
+      let trustProxy;
+      try {
+        const v = req.app?.get?.("trust proxy");
+        trustProxy = v === void 0 ? void 0 : Boolean(v) && v !== "false";
+      } catch {
+        trustProxy = void 0;
+      }
+      const host = typeof req.headers["host"] === "string" ? req.headers["host"] : req.hostname;
+      const body = opts.inspectBody ? bodyToString(req.body) : void 0;
+      let call;
+      try {
+        call = opts.call?.(req);
+      } catch {
+        call = void 0;
+      }
+      decision = await instance.protect({
+        method: req.method,
+        path: req.originalUrl ?? req.url ?? "/",
+        host,
+        headers: req.headers,
+        socketIp: req.socket?.remoteAddress,
+        expressIp: req.ip,
+        expressTrustProxy: trustProxy,
+        body
+      }, call);
+      req.zarex = decision;
+    } catch {
+      next();
+      return;
+    }
+    if (decision.denied) {
+      try {
+        (opts.onDeny ?? defaultDeny)(req, res, decision);
+      } catch (err) {
+        next(err);
+      }
+      return;
+    }
+    if (decision.degraded && opts.onDegraded) {
+      try {
+        opts.onDegraded(req, decision);
+      } catch {
+      }
+    }
+    next();
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CLOUDFLARE_RANGES,
+  PRIVATE_NETWORKS,
+  createZarex,
+  detectBot,
+  emailValidation,
+  phoneValidation,
+  promptInjection,
+  rateLimit,
+  requestFilter,
+  secureHeaders,
+  sensitiveInfo,
+  shield,
+  tokenBucket,
+  withSecureHeaders,
+  zarex
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import {\r\n  applyGuard,\r\n  createZarex,\r\n  isLocalHost,\r\n  isScannableContentType,\r\n  normalizeGuardOptions,\r\n  prepareSecureHeaders,\r\n  type Decision,\r\n  type ProtectCall,\r\n  type ResponseGuardOptions,\r\n  type SecureHeadersOptions,\r\n  type Zarex,\r\n  type ZarexOptions,\r\n} from \"@zarex/core\";\r\n\r\n/**\r\n * Types minimaux d'Express : on ne dépend pas de `express` à l'exécution, donc\r\n * le middleware fonctionne avec Express 4 et 5 (et tout framework compatible).\r\n */\r\nexport interface ExpressLikeRequest {\r\n  method: string;\r\n  originalUrl?: string;\r\n  url?: string;\r\n  ip?: string | undefined;\r\n  headers: Record<string, string | string[] | undefined>;\r\n  socket?: { remoteAddress?: string | undefined } | undefined;\r\n  hostname?: string;\r\n  body?: unknown;\r\n  secure?: boolean;\r\n  app?: { get?(setting: string): unknown };\r\n  zarex?: Decision;\r\n}\r\nexport interface ExpressLikeResponse {\r\n  status(code: number): this;\r\n  set(name: string, value: string): this;\r\n  json(body: unknown): unknown;\r\n  send?(body?: unknown): unknown;\r\n  get?(name: string): string | undefined;\r\n  getHeader?(name: string): unknown;\r\n  removeHeader?(name: string): void;\r\n  headersSent?: boolean;\r\n}\r\nexport type NextFn = (err?: unknown) => void;\r\n\r\nexport interface ExpressZarexOptions extends Omit<ZarexOptions, \"ipSource\"> {\r\n  /**\r\n   * Défaut : \"express\" — l'adresse est celle qu'Express calcule (`req.ip`), selon\r\n   * `app.set(\"trust proxy\", …)`. C'est la méthode la plus sûre avec Express :\r\n   * configurez « trust proxy » pour VOTRE infrastructure (voir la doc Express).\r\n   */\r\n  ipSource?: ZarexOptions[\"ipSource\"];\r\n  /**\r\n   * Transmettre le corps de la requête au Shield (défaut false : il peut contenir\r\n   * des mots de passe). Nécessite que le middleware soit placé APRÈS express.json() /\r\n   * express.urlencoded(). Le SDK ne lit jamais le flux lui-même.\r\n   */\r\n  inspectBody?: boolean;\r\n  /**\r\n   * En-têtes de sécurité (HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy…), ajoutés à TOUTES les réponses,\r\n   * y compris les refus. `true` = défauts prudents ; sinon voir SecureHeadersOptions. Retire aussi X-Powered-By.\r\n   */\r\n  secureHeaders?: SecureHeadersOptions | boolean;\r\n  /**\r\n   * Surveille les réponses de votre application (res.send / res.json) : masque (ou bloque) les cartes bancaires,\r\n   * clés d'API, jetons JWT, mots de passe… qui s'y trouveraient par erreur. Tout se passe sur votre serveur.\r\n   * LIMITE : ne couvre ni res.write()/res.end() directs, ni les flux (streams).\r\n   */\r\n  responseGuard?: ResponseGuardOptions | boolean;\r\n  /** Réponse personnalisée en cas de refus. Si absente : 429 (limite de débit) ou 403. */\r\n  onDeny?: (req: ExpressLikeRequest, res: ExpressLikeResponse, decision: Decision) => void;\r\n  /** Appelé quand le moteur n'a pas pu décider (la requête passe). */\r\n  onDegraded?: (req: ExpressLikeRequest, decision: Decision) => void;\r\n  /**\r\n   * Identifiants / jetons propres à chaque requête, ex. `(req) => ({ characteristics: { userId: req.user?.id } })`.\r\n   * Placez alors le middleware APRÈS votre authentification. Une erreur dans cette fonction est ignorée.\r\n   */\r\n  call?: (req: ExpressLikeRequest) => ProtectCall | undefined;\r\n}\r\n\r\nconst decoder = new TextDecoder(\"utf-8\");\r\n\r\n/** Enveloppe res.send : les corps TEXTE (string / octets texte) passent par la surveillance. Ne lève jamais. */\r\nfunction installResponseGuard(res: ExpressLikeResponse, guard: ResponseGuardOptions): void {\r\n  const original = res.send;\r\n  if (typeof original !== \"function\") return;\r\n  res.send = function guardedSend(this: ExpressLikeResponse, body?: unknown): unknown {\r\n    let next: unknown = body;\r\n    try {\r\n      const ct = String((typeof res.get === \"function\" ? res.get(\"Content-Type\") : undefined) ?? \"\");\r\n      const isString = typeof body === \"string\";\r\n      const isBytes = body instanceof Uint8Array;\r\n      // Une chaîne sans type déclaré est du texte (Express la servira en text/html).\r\n      if ((isString && (ct === \"\" || isScannableContentType(ct))) || (isBytes && isScannableContentType(ct))) {\r\n        const text = isString ? (body as string) : decoder.decode(body as Uint8Array);\r\n        const r = applyGuard(text, ct || \"text/html\", guard);\r\n        if (r.action === \"masked\") next = r.body;\r\n        else if (r.action === \"blocked\" && !res.headersSent) {\r\n          res.status(500);\r\n          res.set(\"Content-Type\", \"application/json; charset=utf-8\");\r\n          next = r.body;\r\n        }\r\n      }\r\n    } catch {\r\n      next = body; // jamais casser la réponse de l'application\r\n    }\r\n    return (original as (b?: unknown) => unknown).call(this, next);\r\n  };\r\n}\r\n\r\nfunction bodyToString(body: unknown): string | undefined {\r\n  if (body === undefined || body === null) return undefined;\r\n  if (typeof body === \"string\") return body;\r\n  if (typeof body === \"object\" && typeof (body as { toString?: unknown }).toString === \"function\" && (body as { constructor?: { name?: string } }).constructor?.name === \"Buffer\") {\r\n    return (body as { toString(enc: string): string }).toString(\"utf8\");\r\n  }\r\n  try {\r\n    const s = JSON.stringify(body);\r\n    return typeof s === \"string\" ? s : undefined;\r\n  } catch {\r\n    return undefined;\r\n  }\r\n}\r\n\r\n/** Réponse de refus par défaut : générique, sans détail interne. */\r\nfunction defaultDeny(_req: ExpressLikeRequest, res: ExpressLikeResponse, d: Decision): void {\r\n  const limited = d.deniedBy?.ruleType === \"RATE_LIMIT\" || d.deniedBy?.ruleType === \"TOKEN_BUCKET\";\r\n  if (res.headersSent) return;\r\n  if (limited) {\r\n    if (d.retryAfterSeconds !== undefined) res.set(\"Retry-After\", String(d.retryAfterSeconds));\r\n    res.status(429).json({ error: { code: \"rate_limited\", message: \"Too many requests\", request_id: d.id } });\r\n  } else {\r\n    res.status(403).json({ error: { code: \"forbidden\", message: \"Request blocked\", request_id: d.id } });\r\n  }\r\n}\r\n\r\n/**\r\n * Middleware Express.\r\n *\r\n *   app.use(zarex({ key: process.env.ZAREX_KEY!, baseUrl: process.env.ZAREX_URL!, rules: [shield(), rateLimit({ max: 100, window: \"1m\" })] }));\r\n *\r\n * Fail-open : si Zarex est injoignable, lent ou répond mal, la requête passe.\r\n * Le résultat est disponible dans `req.zarex`.\r\n */\r\nexport function zarex(options: ExpressZarexOptions | Zarex, extra: Pick<ExpressZarexOptions, \"inspectBody\" | \"onDeny\" | \"onDegraded\" | \"call\" | \"secureHeaders\" | \"responseGuard\"> = {}) {\r\n  const isInstance = typeof (options as Zarex).protect === \"function\";\r\n  const opts = (isInstance ? extra : options) as ExpressZarexOptions;\r\n  const instance: Zarex = isInstance\r\n    ? (options as Zarex)\r\n    : createZarex({ ...(options as ExpressZarexOptions), ipSource: (options as ExpressZarexOptions).ipSource ?? \"express\" });\r\n\r\n  // Préparés UNE fois : une option invalide est signalée au démarrage, pas à la première requête.\r\n  const prepared = prepareSecureHeaders(opts.secureHeaders);\r\n  const guard = normalizeGuardOptions(opts.responseGuard);\r\n\r\n  return async function zarexMiddleware(req: ExpressLikeRequest, res: ExpressLikeResponse, next: NextFn): Promise<void> {\r\n    let decision: Decision | undefined;\r\n    try {\r\n      if (prepared) {\r\n        const set = isLocalHost(req.hostname ?? (typeof req.headers[\"host\"] === \"string\" ? (req.headers[\"host\"] as string) : undefined)) ? prepared.http : prepared.https;\r\n        for (const [k, v] of Object.entries(set)) res.set(k, v);\r\n        if (prepared.removePoweredBy) res.removeHeader?.(\"X-Powered-By\");\r\n      }\r\n      if (guard) installResponseGuard(res, guard);\r\n    } catch {\r\n      /* les protections de réponse ne doivent jamais casser la requête */\r\n    }\r\n    try {\r\n      let trustProxy: boolean | undefined;\r\n      try {\r\n        const v = req.app?.get?.(\"trust proxy\");\r\n        trustProxy = v === undefined ? undefined : Boolean(v) && v !== \"false\";\r\n      } catch {\r\n        trustProxy = undefined;\r\n      }\r\n      const host = typeof req.headers[\"host\"] === \"string\" ? (req.headers[\"host\"] as string) : req.hostname;\r\n      const body = opts.inspectBody ? bodyToString(req.body) : undefined;\r\n      let call: ProtectCall | undefined;\r\n      try {\r\n        call = opts.call?.(req);\r\n      } catch {\r\n        call = undefined;\r\n      }\r\n      decision = await instance.protect({\r\n        method: req.method,\r\n        path: req.originalUrl ?? req.url ?? \"/\",\r\n        host,\r\n        headers: req.headers,\r\n        socketIp: req.socket?.remoteAddress,\r\n        expressIp: req.ip,\r\n        expressTrustProxy: trustProxy,\r\n        body,\r\n      }, call);\r\n      req.zarex = decision;\r\n    } catch {\r\n      // protect() ne lève pas, mais quoi qu'il arrive : la requête du client passe.\r\n      next();\r\n      return;\r\n    }\r\n\r\n    if (decision.denied) {\r\n      try {\r\n        (opts.onDeny ?? defaultDeny)(req, res, decision);\r\n      } catch (err) {\r\n        // Toujours propager par next(err), même si des en-têtes ont déjà été écrits : Express gère ce\r\n        // cas lui-même (son gestionnaire d'erreur par défaut referme la connexion sans tenter d'écrire\r\n        // une 2ᵉ réponse). Le garde-fou précédent (`if (!res.headersSent)`) empêchait tout appel à\r\n        // next() dans ce cas précis : un onDeny qui écrivait partiellement la réponse puis levait\r\n        // laissait la requête bloquée indéfiniment, sans aucune trace (audit du 04/11/2026, voir\r\n        // AUDIT_SECURITE_COMPLET.md).\r\n        next(err);\r\n      }\r\n      return;\r\n    }\r\n    if (decision.degraded && opts.onDegraded) {\r\n      try {\r\n        opts.onDegraded(req, decision);\r\n      } catch {\r\n        /* le rappel du développeur ne doit pas casser la requête */\r\n      }\r\n    }\r\n    next();\r\n  };\r\n}\r\n\r\nexport {\r\n  shield,\r\n  rateLimit,\r\n  tokenBucket,\r\n  detectBot,\r\n  requestFilter,\r\n  sensitiveInfo,\r\n  emailValidation,\r\n  phoneValidation,\r\n  promptInjection,\r\n  secureHeaders,\r\n  withSecureHeaders,\r\n  createZarex,\r\n  PRIVATE_NETWORKS,\r\n  CLOUDFLARE_RANGES,\r\n} from \"@zarex/core\";\r\nexport type { SecureHeadersOptions, ResponseGuardOptions, ResponseGuardEvent } from \"@zarex/core\";\r\nexport type { Decision, Zarex, ZarexOptions, IpSource, Rule } from \"@zarex/core\";"],"mappings":"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","names":["import_core"]}

package/dist/index.d.cts

@@ -0,0 +1,80 @@
+import { Decision, ZarexOptions, SecureHeadersOptions, ResponseGuardOptions, ProtectCall, Zarex } from '@zarex/core';
+export { CLOUDFLARE_RANGES, Decision, IpSource, PRIVATE_NETWORKS, ResponseGuardEvent, ResponseGuardOptions, Rule, SecureHeadersOptions, Zarex, ZarexOptions, createZarex, detectBot, emailValidation, phoneValidation, promptInjection, rateLimit, requestFilter, secureHeaders, sensitiveInfo, shield, tokenBucket, withSecureHeaders } from '@zarex/core';
+
+/**
+ * Types minimaux d'Express : on ne dépend pas de `express` à l'exécution, donc
+ * le middleware fonctionne avec Express 4 et 5 (et tout framework compatible).
+ */
+interface ExpressLikeRequest {
+    method: string;
+    originalUrl?: string;
+    url?: string;
+    ip?: string | undefined;
+    headers: Record<string, string | string[] | undefined>;
+    socket?: {
+        remoteAddress?: string | undefined;
+    } | undefined;
+    hostname?: string;
+    body?: unknown;
+    secure?: boolean;
+    app?: {
+        get?(setting: string): unknown;
+    };
+    zarex?: Decision;
+}
+interface ExpressLikeResponse {
+    status(code: number): this;
+    set(name: string, value: string): this;
+    json(body: unknown): unknown;
+    send?(body?: unknown): unknown;
+    get?(name: string): string | undefined;
+    getHeader?(name: string): unknown;
+    removeHeader?(name: string): void;
+    headersSent?: boolean;
+}
+type NextFn = (err?: unknown) => void;
+interface ExpressZarexOptions extends Omit<ZarexOptions, "ipSource"> {
+    /**
+     * Défaut : "express" — l'adresse est celle qu'Express calcule (`req.ip`), selon
+     * `app.set("trust proxy", …)`. C'est la méthode la plus sûre avec Express :
+     * configurez « trust proxy » pour VOTRE infrastructure (voir la doc Express).
+     */
+    ipSource?: ZarexOptions["ipSource"];
+    /**
+     * Transmettre le corps de la requête au Shield (défaut false : il peut contenir
+     * des mots de passe). Nécessite que le middleware soit placé APRÈS express.json() /
+     * express.urlencoded(). Le SDK ne lit jamais le flux lui-même.
+     */
+    inspectBody?: boolean;
+    /**
+     * En-têtes de sécurité (HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy…), ajoutés à TOUTES les réponses,
+     * y compris les refus. `true` = défauts prudents ; sinon voir SecureHeadersOptions. Retire aussi X-Powered-By.
+     */
+    secureHeaders?: SecureHeadersOptions | boolean;
+    /**
+     * Surveille les réponses de votre application (res.send / res.json) : masque (ou bloque) les cartes bancaires,
+     * clés d'API, jetons JWT, mots de passe… qui s'y trouveraient par erreur. Tout se passe sur votre serveur.
+     * LIMITE : ne couvre ni res.write()/res.end() directs, ni les flux (streams).
+     */
+    responseGuard?: ResponseGuardOptions | boolean;
+    /** Réponse personnalisée en cas de refus. Si absente : 429 (limite de débit) ou 403. */
+    onDeny?: (req: ExpressLikeRequest, res: ExpressLikeResponse, decision: Decision) => void;
+    /** Appelé quand le moteur n'a pas pu décider (la requête passe). */
+    onDegraded?: (req: ExpressLikeRequest, decision: Decision) => void;
+    /**
+     * Identifiants / jetons propres à chaque requête, ex. `(req) => ({ characteristics: { userId: req.user?.id } })`.
+     * Placez alors le middleware APRÈS votre authentification. Une erreur dans cette fonction est ignorée.
+     */
+    call?: (req: ExpressLikeRequest) => ProtectCall | undefined;
+}
+/**
+ * Middleware Express.
+ *
+ *   app.use(zarex({ key: process.env.ZAREX_KEY!, baseUrl: process.env.ZAREX_URL!, rules: [shield(), rateLimit({ max: 100, window: "1m" })] }));
+ *
+ * Fail-open : si Zarex est injoignable, lent ou répond mal, la requête passe.
+ * Le résultat est disponible dans `req.zarex`.
+ */
+declare function zarex(options: ExpressZarexOptions | Zarex, extra?: Pick<ExpressZarexOptions, "inspectBody" | "onDeny" | "onDegraded" | "call" | "secureHeaders" | "responseGuard">): (req: ExpressLikeRequest, res: ExpressLikeResponse, next: NextFn) => Promise<void>;
+
+export { type ExpressLikeRequest, type ExpressLikeResponse, type ExpressZarexOptions, type NextFn, zarex };

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+import { Decision, ZarexOptions, SecureHeadersOptions, ResponseGuardOptions, ProtectCall, Zarex } from '@zarex/core';
+export { CLOUDFLARE_RANGES, Decision, IpSource, PRIVATE_NETWORKS, ResponseGuardEvent, ResponseGuardOptions, Rule, SecureHeadersOptions, Zarex, ZarexOptions, createZarex, detectBot, emailValidation, phoneValidation, promptInjection, rateLimit, requestFilter, secureHeaders, sensitiveInfo, shield, tokenBucket, withSecureHeaders } from '@zarex/core';
+
+/**
+ * Types minimaux d'Express : on ne dépend pas de `express` à l'exécution, donc
+ * le middleware fonctionne avec Express 4 et 5 (et tout framework compatible).
+ */
+interface ExpressLikeRequest {
+    method: string;
+    originalUrl?: string;
+    url?: string;
+    ip?: string | undefined;
+    headers: Record<string, string | string[] | undefined>;
+    socket?: {
+        remoteAddress?: string | undefined;
+    } | undefined;
+    hostname?: string;
+    body?: unknown;
+    secure?: boolean;
+    app?: {
+        get?(setting: string): unknown;
+    };
+    zarex?: Decision;
+}
+interface ExpressLikeResponse {
+    status(code: number): this;
+    set(name: string, value: string): this;
+    json(body: unknown): unknown;
+    send?(body?: unknown): unknown;
+    get?(name: string): string | undefined;
+    getHeader?(name: string): unknown;
+    removeHeader?(name: string): void;
+    headersSent?: boolean;
+}
+type NextFn = (err?: unknown) => void;
+interface ExpressZarexOptions extends Omit<ZarexOptions, "ipSource"> {
+    /**
+     * Défaut : "express" — l'adresse est celle qu'Express calcule (`req.ip`), selon
+     * `app.set("trust proxy", …)`. C'est la méthode la plus sûre avec Express :
+     * configurez « trust proxy » pour VOTRE infrastructure (voir la doc Express).
+     */
+    ipSource?: ZarexOptions["ipSource"];
+    /**
+     * Transmettre le corps de la requête au Shield (défaut false : il peut contenir
+     * des mots de passe). Nécessite que le middleware soit placé APRÈS express.json() /
+     * express.urlencoded(). Le SDK ne lit jamais le flux lui-même.
+     */
+    inspectBody?: boolean;
+    /**
+     * En-têtes de sécurité (HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy…), ajoutés à TOUTES les réponses,
+     * y compris les refus. `true` = défauts prudents ; sinon voir SecureHeadersOptions. Retire aussi X-Powered-By.
+     */
+    secureHeaders?: SecureHeadersOptions | boolean;
+    /**
+     * Surveille les réponses de votre application (res.send / res.json) : masque (ou bloque) les cartes bancaires,
+     * clés d'API, jetons JWT, mots de passe… qui s'y trouveraient par erreur. Tout se passe sur votre serveur.
+     * LIMITE : ne couvre ni res.write()/res.end() directs, ni les flux (streams).
+     */
+    responseGuard?: ResponseGuardOptions | boolean;
+    /** Réponse personnalisée en cas de refus. Si absente : 429 (limite de débit) ou 403. */
+    onDeny?: (req: ExpressLikeRequest, res: ExpressLikeResponse, decision: Decision) => void;
+    /** Appelé quand le moteur n'a pas pu décider (la requête passe). */
+    onDegraded?: (req: ExpressLikeRequest, decision: Decision) => void;
+    /**
+     * Identifiants / jetons propres à chaque requête, ex. `(req) => ({ characteristics: { userId: req.user?.id } })`.
+     * Placez alors le middleware APRÈS votre authentification. Une erreur dans cette fonction est ignorée.
+     */
+    call?: (req: ExpressLikeRequest) => ProtectCall | undefined;
+}
+/**
+ * Middleware Express.
+ *
+ *   app.use(zarex({ key: process.env.ZAREX_KEY!, baseUrl: process.env.ZAREX_URL!, rules: [shield(), rateLimit({ max: 100, window: "1m" })] }));
+ *
+ * Fail-open : si Zarex est injoignable, lent ou répond mal, la requête passe.
+ * Le résultat est disponible dans `req.zarex`.
+ */
+declare function zarex(options: ExpressZarexOptions | Zarex, extra?: Pick<ExpressZarexOptions, "inspectBody" | "onDeny" | "onDegraded" | "call" | "secureHeaders" | "responseGuard">): (req: ExpressLikeRequest, res: ExpressLikeResponse, next: NextFn) => Promise<void>;
+
+export { type ExpressLikeRequest, type ExpressLikeResponse, type ExpressZarexOptions, type NextFn, zarex };

package/dist/index.js

@@ -0,0 +1,157 @@
+// src/index.ts
+import {
+  applyGuard,
+  createZarex,
+  isLocalHost,
+  isScannableContentType,
+  normalizeGuardOptions,
+  prepareSecureHeaders
+} from "@zarex/core";
+import {
+  shield,
+  rateLimit,
+  tokenBucket,
+  detectBot,
+  requestFilter,
+  sensitiveInfo,
+  emailValidation,
+  phoneValidation,
+  promptInjection,
+  secureHeaders,
+  withSecureHeaders,
+  createZarex as createZarex2,
+  PRIVATE_NETWORKS,
+  CLOUDFLARE_RANGES
+} from "@zarex/core";
+var decoder = new TextDecoder("utf-8");
+function installResponseGuard(res, guard) {
+  const original = res.send;
+  if (typeof original !== "function") return;
+  res.send = function guardedSend(body) {
+    let next = body;
+    try {
+      const ct = String((typeof res.get === "function" ? res.get("Content-Type") : void 0) ?? "");
+      const isString = typeof body === "string";
+      const isBytes = body instanceof Uint8Array;
+      if (isString && (ct === "" || isScannableContentType(ct)) || isBytes && isScannableContentType(ct)) {
+        const text = isString ? body : decoder.decode(body);
+        const r = applyGuard(text, ct || "text/html", guard);
+        if (r.action === "masked") next = r.body;
+        else if (r.action === "blocked" && !res.headersSent) {
+          res.status(500);
+          res.set("Content-Type", "application/json; charset=utf-8");
+          next = r.body;
+        }
+      }
+    } catch {
+      next = body;
+    }
+    return original.call(this, next);
+  };
+}
+function bodyToString(body) {
+  if (body === void 0 || body === null) return void 0;
+  if (typeof body === "string") return body;
+  if (typeof body === "object" && typeof body.toString === "function" && body.constructor?.name === "Buffer") {
+    return body.toString("utf8");
+  }
+  try {
+    const s = JSON.stringify(body);
+    return typeof s === "string" ? s : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function defaultDeny(_req, res, d) {
+  const limited = d.deniedBy?.ruleType === "RATE_LIMIT" || d.deniedBy?.ruleType === "TOKEN_BUCKET";
+  if (res.headersSent) return;
+  if (limited) {
+    if (d.retryAfterSeconds !== void 0) res.set("Retry-After", String(d.retryAfterSeconds));
+    res.status(429).json({ error: { code: "rate_limited", message: "Too many requests", request_id: d.id } });
+  } else {
+    res.status(403).json({ error: { code: "forbidden", message: "Request blocked", request_id: d.id } });
+  }
+}
+function zarex(options, extra = {}) {
+  const isInstance = typeof options.protect === "function";
+  const opts = isInstance ? extra : options;
+  const instance = isInstance ? options : createZarex({ ...options, ipSource: options.ipSource ?? "express" });
+  const prepared = prepareSecureHeaders(opts.secureHeaders);
+  const guard = normalizeGuardOptions(opts.responseGuard);
+  return async function zarexMiddleware(req, res, next) {
+    let decision;
+    try {
+      if (prepared) {
+        const set = isLocalHost(req.hostname ?? (typeof req.headers["host"] === "string" ? req.headers["host"] : void 0)) ? prepared.http : prepared.https;
+        for (const [k, v] of Object.entries(set)) res.set(k, v);
+        if (prepared.removePoweredBy) res.removeHeader?.("X-Powered-By");
+      }
+      if (guard) installResponseGuard(res, guard);
+    } catch {
+    }
+    try {
+      let trustProxy;
+      try {
+        const v = req.app?.get?.("trust proxy");
+        trustProxy = v === void 0 ? void 0 : Boolean(v) && v !== "false";
+      } catch {
+        trustProxy = void 0;
+      }
+      const host = typeof req.headers["host"] === "string" ? req.headers["host"] : req.hostname;
+      const body = opts.inspectBody ? bodyToString(req.body) : void 0;
+      let call;
+      try {
+        call = opts.call?.(req);
+      } catch {
+        call = void 0;
+      }
+      decision = await instance.protect({
+        method: req.method,
+        path: req.originalUrl ?? req.url ?? "/",
+        host,
+        headers: req.headers,
+        socketIp: req.socket?.remoteAddress,
+        expressIp: req.ip,
+        expressTrustProxy: trustProxy,
+        body
+      }, call);
+      req.zarex = decision;
+    } catch {
+      next();
+      return;
+    }
+    if (decision.denied) {
+      try {
+        (opts.onDeny ?? defaultDeny)(req, res, decision);
+      } catch (err) {
+        next(err);
+      }
+      return;
+    }
+    if (decision.degraded && opts.onDegraded) {
+      try {
+        opts.onDegraded(req, decision);
+      } catch {
+      }
+    }
+    next();
+  };
+}
+export {
+  CLOUDFLARE_RANGES,
+  PRIVATE_NETWORKS,
+  createZarex2 as createZarex,
+  detectBot,
+  emailValidation,
+  phoneValidation,
+  promptInjection,
+  rateLimit,
+  requestFilter,
+  secureHeaders,
+  sensitiveInfo,
+  shield,
+  tokenBucket,
+  withSecureHeaders,
+  zarex
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import {\r\n  applyGuard,\r\n  createZarex,\r\n  isLocalHost,\r\n  isScannableContentType,\r\n  normalizeGuardOptions,\r\n  prepareSecureHeaders,\r\n  type Decision,\r\n  type ProtectCall,\r\n  type ResponseGuardOptions,\r\n  type SecureHeadersOptions,\r\n  type Zarex,\r\n  type ZarexOptions,\r\n} from \"@zarex/core\";\r\n\r\n/**\r\n * Types minimaux d'Express : on ne dépend pas de `express` à l'exécution, donc\r\n * le middleware fonctionne avec Express 4 et 5 (et tout framework compatible).\r\n */\r\nexport interface ExpressLikeRequest {\r\n  method: string;\r\n  originalUrl?: string;\r\n  url?: string;\r\n  ip?: string | undefined;\r\n  headers: Record<string, string | string[] | undefined>;\r\n  socket?: { remoteAddress?: string | undefined } | undefined;\r\n  hostname?: string;\r\n  body?: unknown;\r\n  secure?: boolean;\r\n  app?: { get?(setting: string): unknown };\r\n  zarex?: Decision;\r\n}\r\nexport interface ExpressLikeResponse {\r\n  status(code: number): this;\r\n  set(name: string, value: string): this;\r\n  json(body: unknown): unknown;\r\n  send?(body?: unknown): unknown;\r\n  get?(name: string): string | undefined;\r\n  getHeader?(name: string): unknown;\r\n  removeHeader?(name: string): void;\r\n  headersSent?: boolean;\r\n}\r\nexport type NextFn = (err?: unknown) => void;\r\n\r\nexport interface ExpressZarexOptions extends Omit<ZarexOptions, \"ipSource\"> {\r\n  /**\r\n   * Défaut : \"express\" — l'adresse est celle qu'Express calcule (`req.ip`), selon\r\n   * `app.set(\"trust proxy\", …)`. C'est la méthode la plus sûre avec Express :\r\n   * configurez « trust proxy » pour VOTRE infrastructure (voir la doc Express).\r\n   */\r\n  ipSource?: ZarexOptions[\"ipSource\"];\r\n  /**\r\n   * Transmettre le corps de la requête au Shield (défaut false : il peut contenir\r\n   * des mots de passe). Nécessite que le middleware soit placé APRÈS express.json() /\r\n   * express.urlencoded(). Le SDK ne lit jamais le flux lui-même.\r\n   */\r\n  inspectBody?: boolean;\r\n  /**\r\n   * En-têtes de sécurité (HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy…), ajoutés à TOUTES les réponses,\r\n   * y compris les refus. `true` = défauts prudents ; sinon voir SecureHeadersOptions. Retire aussi X-Powered-By.\r\n   */\r\n  secureHeaders?: SecureHeadersOptions | boolean;\r\n  /**\r\n   * Surveille les réponses de votre application (res.send / res.json) : masque (ou bloque) les cartes bancaires,\r\n   * clés d'API, jetons JWT, mots de passe… qui s'y trouveraient par erreur. Tout se passe sur votre serveur.\r\n   * LIMITE : ne couvre ni res.write()/res.end() directs, ni les flux (streams).\r\n   */\r\n  responseGuard?: ResponseGuardOptions | boolean;\r\n  /** Réponse personnalisée en cas de refus. Si absente : 429 (limite de débit) ou 403. */\r\n  onDeny?: (req: ExpressLikeRequest, res: ExpressLikeResponse, decision: Decision) => void;\r\n  /** Appelé quand le moteur n'a pas pu décider (la requête passe). */\r\n  onDegraded?: (req: ExpressLikeRequest, decision: Decision) => void;\r\n  /**\r\n   * Identifiants / jetons propres à chaque requête, ex. `(req) => ({ characteristics: { userId: req.user?.id } })`.\r\n   * Placez alors le middleware APRÈS votre authentification. Une erreur dans cette fonction est ignorée.\r\n   */\r\n  call?: (req: ExpressLikeRequest) => ProtectCall | undefined;\r\n}\r\n\r\nconst decoder = new TextDecoder(\"utf-8\");\r\n\r\n/** Enveloppe res.send : les corps TEXTE (string / octets texte) passent par la surveillance. Ne lève jamais. */\r\nfunction installResponseGuard(res: ExpressLikeResponse, guard: ResponseGuardOptions): void {\r\n  const original = res.send;\r\n  if (typeof original !== \"function\") return;\r\n  res.send = function guardedSend(this: ExpressLikeResponse, body?: unknown): unknown {\r\n    let next: unknown = body;\r\n    try {\r\n      const ct = String((typeof res.get === \"function\" ? res.get(\"Content-Type\") : undefined) ?? \"\");\r\n      const isString = typeof body === \"string\";\r\n      const isBytes = body instanceof Uint8Array;\r\n      // Une chaîne sans type déclaré est du texte (Express la servira en text/html).\r\n      if ((isString && (ct === \"\" || isScannableContentType(ct))) || (isBytes && isScannableContentType(ct))) {\r\n        const text = isString ? (body as string) : decoder.decode(body as Uint8Array);\r\n        const r = applyGuard(text, ct || \"text/html\", guard);\r\n        if (r.action === \"masked\") next = r.body;\r\n        else if (r.action === \"blocked\" && !res.headersSent) {\r\n          res.status(500);\r\n          res.set(\"Content-Type\", \"application/json; charset=utf-8\");\r\n          next = r.body;\r\n        }\r\n      }\r\n    } catch {\r\n      next = body; // jamais casser la réponse de l'application\r\n    }\r\n    return (original as (b?: unknown) => unknown).call(this, next);\r\n  };\r\n}\r\n\r\nfunction bodyToString(body: unknown): string | undefined {\r\n  if (body === undefined || body === null) return undefined;\r\n  if (typeof body === \"string\") return body;\r\n  if (typeof body === \"object\" && typeof (body as { toString?: unknown }).toString === \"function\" && (body as { constructor?: { name?: string } }).constructor?.name === \"Buffer\") {\r\n    return (body as { toString(enc: string): string }).toString(\"utf8\");\r\n  }\r\n  try {\r\n    const s = JSON.stringify(body);\r\n    return typeof s === \"string\" ? s : undefined;\r\n  } catch {\r\n    return undefined;\r\n  }\r\n}\r\n\r\n/** Réponse de refus par défaut : générique, sans détail interne. */\r\nfunction defaultDeny(_req: ExpressLikeRequest, res: ExpressLikeResponse, d: Decision): void {\r\n  const limited = d.deniedBy?.ruleType === \"RATE_LIMIT\" || d.deniedBy?.ruleType === \"TOKEN_BUCKET\";\r\n  if (res.headersSent) return;\r\n  if (limited) {\r\n    if (d.retryAfterSeconds !== undefined) res.set(\"Retry-After\", String(d.retryAfterSeconds));\r\n    res.status(429).json({ error: { code: \"rate_limited\", message: \"Too many requests\", request_id: d.id } });\r\n  } else {\r\n    res.status(403).json({ error: { code: \"forbidden\", message: \"Request blocked\", request_id: d.id } });\r\n  }\r\n}\r\n\r\n/**\r\n * Middleware Express.\r\n *\r\n *   app.use(zarex({ key: process.env.ZAREX_KEY!, baseUrl: process.env.ZAREX_URL!, rules: [shield(), rateLimit({ max: 100, window: \"1m\" })] }));\r\n *\r\n * Fail-open : si Zarex est injoignable, lent ou répond mal, la requête passe.\r\n * Le résultat est disponible dans `req.zarex`.\r\n */\r\nexport function zarex(options: ExpressZarexOptions | Zarex, extra: Pick<ExpressZarexOptions, \"inspectBody\" | \"onDeny\" | \"onDegraded\" | \"call\" | \"secureHeaders\" | \"responseGuard\"> = {}) {\r\n  const isInstance = typeof (options as Zarex).protect === \"function\";\r\n  const opts = (isInstance ? extra : options) as ExpressZarexOptions;\r\n  const instance: Zarex = isInstance\r\n    ? (options as Zarex)\r\n    : createZarex({ ...(options as ExpressZarexOptions), ipSource: (options as ExpressZarexOptions).ipSource ?? \"express\" });\r\n\r\n  // Préparés UNE fois : une option invalide est signalée au démarrage, pas à la première requête.\r\n  const prepared = prepareSecureHeaders(opts.secureHeaders);\r\n  const guard = normalizeGuardOptions(opts.responseGuard);\r\n\r\n  return async function zarexMiddleware(req: ExpressLikeRequest, res: ExpressLikeResponse, next: NextFn): Promise<void> {\r\n    let decision: Decision | undefined;\r\n    try {\r\n      if (prepared) {\r\n        const set = isLocalHost(req.hostname ?? (typeof req.headers[\"host\"] === \"string\" ? (req.headers[\"host\"] as string) : undefined)) ? prepared.http : prepared.https;\r\n        for (const [k, v] of Object.entries(set)) res.set(k, v);\r\n        if (prepared.removePoweredBy) res.removeHeader?.(\"X-Powered-By\");\r\n      }\r\n      if (guard) installResponseGuard(res, guard);\r\n    } catch {\r\n      /* les protections de réponse ne doivent jamais casser la requête */\r\n    }\r\n    try {\r\n      let trustProxy: boolean | undefined;\r\n      try {\r\n        const v = req.app?.get?.(\"trust proxy\");\r\n        trustProxy = v === undefined ? undefined : Boolean(v) && v !== \"false\";\r\n      } catch {\r\n        trustProxy = undefined;\r\n      }\r\n      const host = typeof req.headers[\"host\"] === \"string\" ? (req.headers[\"host\"] as string) : req.hostname;\r\n      const body = opts.inspectBody ? bodyToString(req.body) : undefined;\r\n      let call: ProtectCall | undefined;\r\n      try {\r\n        call = opts.call?.(req);\r\n      } catch {\r\n        call = undefined;\r\n      }\r\n      decision = await instance.protect({\r\n        method: req.method,\r\n        path: req.originalUrl ?? req.url ?? \"/\",\r\n        host,\r\n        headers: req.headers,\r\n        socketIp: req.socket?.remoteAddress,\r\n        expressIp: req.ip,\r\n        expressTrustProxy: trustProxy,\r\n        body,\r\n      }, call);\r\n      req.zarex = decision;\r\n    } catch {\r\n      // protect() ne lève pas, mais quoi qu'il arrive : la requête du client passe.\r\n      next();\r\n      return;\r\n    }\r\n\r\n    if (decision.denied) {\r\n      try {\r\n        (opts.onDeny ?? defaultDeny)(req, res, decision);\r\n      } catch (err) {\r\n        // Toujours propager par next(err), même si des en-têtes ont déjà été écrits : Express gère ce\r\n        // cas lui-même (son gestionnaire d'erreur par défaut referme la connexion sans tenter d'écrire\r\n        // une 2ᵉ réponse). Le garde-fou précédent (`if (!res.headersSent)`) empêchait tout appel à\r\n        // next() dans ce cas précis : un onDeny qui écrivait partiellement la réponse puis levait\r\n        // laissait la requête bloquée indéfiniment, sans aucune trace (audit du 04/11/2026, voir\r\n        // AUDIT_SECURITE_COMPLET.md).\r\n        next(err);\r\n      }\r\n      return;\r\n    }\r\n    if (decision.degraded && opts.onDegraded) {\r\n      try {\r\n        opts.onDegraded(req, decision);\r\n      } catch {\r\n        /* le rappel du développeur ne doit pas casser la requête */\r\n      }\r\n    }\r\n    next();\r\n  };\r\n}\r\n\r\nexport {\r\n  shield,\r\n  rateLimit,\r\n  tokenBucket,\r\n  detectBot,\r\n  requestFilter,\r\n  sensitiveInfo,\r\n  emailValidation,\r\n  phoneValidation,\r\n  promptInjection,\r\n  secureHeaders,\r\n  withSecureHeaders,\r\n  createZarex,\r\n  PRIVATE_NETWORKS,\r\n  CLOUDFLARE_RANGES,\r\n} from \"@zarex/core\";\r\nexport type { SecureHeadersOptions, ResponseGuardOptions, ResponseGuardEvent } from \"@zarex/core\";\r\nexport type { Decision, Zarex, ZarexOptions, IpSource, Rule } from \"@zarex/core\";"],"mappings":"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","names":["createZarex"]}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@zarex/express",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Zarex — middleware Express",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@zarex/core": "^0.1.1"
+  },
+  "peerDependencies": {
+    "express": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsup"
+  }
 }