@aimarket/warden 0.0.1 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,206 @@
+# Changelog
+
+All notable changes to `@aimarket/warden`.
+
+## 0.4.0 — 2026-08-24
+
+Calibrated against the ecosystem, not against fixtures. WARDEN was pointed at every public MCP
+server it could legitimately reach — 1 108 of them answered a live `tools/list` with 17 491 tool
+definitions — and the result is written up in [`docs/mcp-survey.md`](docs/mcp-survey.md).
+
+Ruleset `v3` blocked 50 of those 1 108 servers. Four held up on review. The other 46 were blocked
+for saying the right thing: *"Never send a private key"*, *"the private key never leaves your
+machine"*, a security scanner listing the attacks it detects, a Persian tool description spelled with
+the ZERO WIDTH NON-JOINER its language requires. A scanner with that false-positive profile does not
+get tuned by its users; it gets uninstalled.
+
+Ruleset **v4** brings blocking from 50 servers down to **6** on the same corpus, with all four real
+findings still caught.
+
+### Rules read context now
+
+Rules gained **guards** — named context checks that decide whether a match is the thing the rule is
+looking for. A guard is part of the published rule table and therefore of the digest: the same regex
+with and without `polarity` is a different ruleset, and a recorded verdict has to be able to say
+which one it was.
+
+- **`polarity`** — a credential noun inside a refusal is a promise, not a request. This one
+  distinction accounted for 390 of the 492 blocking findings in the survey.
+- **`mention`** — a phrase in quotes, in backticks, or as a bare JSON `enum` value is cited, not said.
+- **`detection`** — a secret named as the object of `detect`/`scan`/`find`/`leaked` is what a scanner
+  looks for, not what it wants.
+- **`identifierFragment`** — `mnemonic` inside `bip39-mnemonic-checksum` is that identifier's name.
+- **`harvestTarget`** — a harvest instruction says *whose* secret or *where* it lives. Without it,
+  "Obtain a permanent anonymous API key" read as theft rather than issuance.
+- **`uri`** — `javascript:` is now matched case-**sensitively** and needs a payload. Under `/i` it
+  matched the word *JavaScript* followed by a colon, i.e. every language list ever written.
+- **`payload`** — a `data:…;base64,` URI with fewer than 32 characters behind the comma is the format
+  being documented.
+- **`blob`** — `/` is in the base64 alphabet, so a JSON Schema `$ref` pointer read as a hidden blob.
+  Now gated on entropy and on schema keywords.
+- **`zeroWidth`** — U+200C/U+200D adjacent to Arabic, Persian or Indic script is orthography. U+200B,
+  U+FEFF and the bidi overrides still block.
+- **`publicKeyPath`** — `authorized_keys`, `known_hosts` and `*.pub` are public by definition.
+
+### Rules demoted from block to advise
+
+Each of these was measured selecting for honest servers. They are still reported.
+
+- **`exfiltrat*`** as a bare noun. An attacker does not name the attack; a defender names it in every
+  sentence. All three hits were defensive tools. The anchored *"send X to <external destination>"*
+  rules keep the blocking weight.
+- **`system prompt` / `developer message`**. 15 findings across 6 servers, every one an LLM proxy,
+  persona manager or agent-configuration tool that declares a `system` parameter because setting a
+  system prompt is its job.
+- **`do not tell the user`**. Four real uses, four of them the opposite of concealment — *"no refund
+  is issued automatically … do not tell the user a refund is coming"*. A blocking rule needs a
+  concealment target that refers to the tool's own action; the bare phrase carries none.
+- The **credential nouns** keep blocking but drop from `critical` to `high`: still over the default
+  threshold, no longer zeroing the gate score. One noun in a schema template shared by 377 tools
+  should not read as "maximally compromised".
+
+### Threat feed
+
+- Wildcard threat patterns now use `threatMatch`: **interior gaps are bounded** to 24 characters and
+  a segment starting with a letter must **start on a word boundary**. `*sweep*funds*` was matching
+  `funds` inside "re**funds**", and `*drain*wallet*` was joining two words from different clauses.
+  Leading and trailing `*` stay unbounded, and `_`/`-` count as boundaries so a `seed_phrase` schema
+  field still matches. `policy.sensitiveToolPatterns` keeps plain glob semantics — that is the
+  operator's own pattern against their own tool names.
+
+### Findings say what they matched
+
+- Every finding message now quotes the matched text: `… signature (\b(?:read|extract|…) at "obtain
+  the redacted credential"`. Without it a reviewer cannot tell which alternative of an alternation
+  fired, or on what. Recovering that by hand is most of the work of judging a finding, and it cost
+  hours in the survey itself.
+- Dropped matches are logged at `debug` with the guard's reason, because a guard silently discarding a
+  finding is the one behaviour in this gate that a verdict cannot show.
+
+### Release gate
+
+- `npm run check:ruleset` fails if the version in `package.json` is already on the registry with a
+  different ruleset ref, and runs in CI and in `prepublishOnly`. **0.3.0 was published carrying
+  ruleset v2 sixty-four seconds before the extraction commit, v3 landed in the source 52 minutes
+  later, and nothing republished** — so `npm install @aimarket/warden@0.3.0` handed strangers a
+  scanner with no rules on the tool-name surface while the README in that same tarball documented v3.
+  Measured after the fact, that cost nothing on the 1 108-server corpus; the ambiguity in every
+  recorded verdict was the real defect.
+
+### Tests
+
+- `test/field-survey-regression.test.ts` — 19 cases built from the survey's real text. Both
+  directions: the 46 false positives must not block, and the four real findings must.
+
+## 0.3.0 — 2026-08-24
+
+First standalone release. The gates, the threat feed, the pinning store contract and the RFC 8785
+canonicalizer were extracted from [ARGUS](https://github.com/alexar76/argus) 0.3.0, where they had
+lived as `src/warden/`. The version number is deliberately continuous with the agent that shipped
+them, not reset to 0.1.0: this is the same enforcement code, with the same behavioural tests that
+guarded it there. The extraction itself changed no rule — it moved ruleset `v2` byte for byte — and
+the security review below, run before this package was ever published, is what took the rules to
+`v3` and closed six holes in the machinery around them.
+
+### Why it moved
+
+A host that wants an MCP firewall had to install an agent — with an MCP SDK, a wallet library and a
+post-quantum keystore in tow — to get one. This package has **zero runtime dependencies** and imports
+nothing but `node:crypto`.
+
+### Changed for standalone use
+
+- **Host seams are narrowed and named.** Pinning needs `PinStore` (`getPin`/`putPin`) instead of
+  ARGUS's full `MemoryStore`, and logging needs `WardenLogger` instead of ARGUS's `Logger`. Both are
+  structural, so an existing host store/logger usually satisfies them unchanged.
+- **`log` is now optional** on `WardenInit` and `WardenCreateDeps`, defaulting to the new
+  `silentLogger()`. A host with no logger of its own still gets enforcement — verdicts are returned as
+  data from `vet()`, never inferred from log output.
+- **`threatFeed` stays required.** Constructing one silently would hide from the host that no external
+  intel is in play.
+- **Subpath export `@aimarket/warden/jcs`** so another implementation can be byte-checked against the
+  canonicalizer without pulling in the gate chain.
+- **Types are exported from the entry point** (`WardenPolicy`, `WardenVerdict`, `WardenFinding`,
+  `ThreatRecord`, `ToolDef`, …). ARGUS now re-exports them from here rather than declaring its own
+  copies, so a change on this side breaks its build instead of drifting silently.
+- No behavioural change to any gate. The rule table, the severities, the tiers, the score arithmetic
+  and every finding code are the ones ARGUS 0.3.0 shipped.
+
+### Security review before first release
+
+The extracted code was read end to end and the findings reproduced. Six were real; all six are fixed
+here and each has a regression test in `test/hardening.test.ts` that fails on the code as extracted.
+
+- **Denial of service through glob matching (critical).** Threat-feed patterns and
+  `policy.sensitiveToolPatterns` compiled `*` into `.*` and ran a regex. A 32-character pattern
+  against a 220-character haystack took **112 seconds**; the sensitive-tool path took **89 seconds**
+  from a long tool name. A signed feed record could therefore hang every connection check, which is
+  precisely what the feed's trust model says a publisher must not be able to do — "a compromised
+  publisher can only add protection" is false if one record stops the firewall answering. Replaced
+  with a linear two-pointer matcher (`src/glob.ts`): the same case now returns in about a
+  millisecond. Feed records are additionally refused past `MAX_GLOB_WILDCARDS` (12), and a feed is
+  refused past 2000 records.
+- **Terminal injection through finding messages (high).** Tool names, server ids, catalog names and
+  a feed's `reason` string were interpolated raw into `finding.message`, which hosts print to a TTY
+  and store in receipts. A tool named `<ESC>[2K<ESC>[1A…` overwrote the BLOCK line WARDEN had just
+  written. Control characters and invisible characters are now escaped visibly (`src/sanitize.ts`,
+  exported as `displaySafe`) — escaped rather than stripped, because a name containing `U+202E`
+  should look suspicious in the report, not clean. `finding.tool` deliberately keeps the raw name:
+  it is the key a host filters its tool list with.
+- **The tool NAME was scanned by nothing (high).** An injection phrase, a zero-width character or a
+  base64 blob in the first field the model reads produced zero findings. Ruleset **v3** gives every
+  rule a `surfaces` list and adds the name to 17 of the 25 — every phrase-keyed and hidden-payload
+  rule. The three noun-keyed codes stay off the name on purpose (`sign_with_private_key` is a
+  plausible tool, and refusing it would be the v1 calibration error on a new surface).
+- **A gate that threw took the whole verdict with it (high).** `vet()` rejected, so the host got no
+  verdict at all — not even the findings the earlier gates had already produced — and a
+  full-disk pin store or a bug in a custom gate decided whether the connection was blocked. A throw
+  is now a `GATE_ERROR` finding at `high` with a zero score: a gate that crashed cleared nothing.
+- **A frozen policy crashed the constructor (medium).** The `blockAtSeverity` typo fallback assigned
+  into the caller's own object, so `Object.freeze(policy)` — a reasonable thing for a host to do —
+  raised a `TypeError` out of `new Warden()` under ESM strict mode. The policy is now normalized
+  into a private copy and the caller's object is never touched.
+- **Pinning covered the advertisement but not the program (medium).** Tool-def pinning caught a
+  server that changed what it advertises, not one that kept the advertisement and changed the
+  command behind it — which a remote **catalog** can do to an already-approved id. `PinnedServer`
+  gained an optional `identityHash` (transport, command, args, url, name) and a
+  `SERVER_IDENTITY_DRIFT` finding. `env` is excluded on purpose: it holds secrets, and the pin is
+  written to disk. Pins from before the field exists stay silent — absent is "not recorded", never
+  "changed".
+
+Two smaller fixes came out of the same pass: a `feedPublicKey` that parses but is not an Ed25519 key
+is now refused with a warning instead of failing inside `verify()` and being logged at `debug`
+(indistinguishable from "the feed had nothing new"), and an oversized feed body is now streamed and
+aborted at the cap instead of being buffered whole by `res.text()` — `content-length` is advisory,
+so the old check was one missing header away from being no check at all.
+
+Two things the review deliberately did **not** change: `EgressGuard` passed every case put to it
+(userinfo tricks, `file:`/`data:` schemes, suffix confusion, case folding), and the scan's cost over
+large tool definitions is linear (500 tools × 240 KB in 1.3 s), so no truncation was introduced for
+a problem that does not exist.
+
+### Added
+
+- `test/packaging.test.ts` — fails if a runtime dependency appears, if any source file imports outside
+  the package, or if the entry point stops exporting the enforcement surface. The zero-dependency claim
+  is the reason this package exists, so it is a test and not a sentence in a README.
+- `test/docs.test.ts` — resolves every relative link across the five-language doc set and holds the
+  quoted test count to what the runner actually reports.
+- `test/no-phantom-gate.test.ts` — the gate-chain half of ARGUS's regression guard for a removed
+  reputation gate: vetting opens no socket, and no gate may report a service as unreachable without
+  having sent a request. (The oracle-side half stayed with the oracle client, in ARGUS.)
+- Documentation in English, Russian, Spanish, French and Chinese: the gate chain, the signed threat-feed
+  contract, and an integration guide.
+
+### Upgrading from ARGUS internals
+
+If you imported the gates through ARGUS's source tree, the mapping is mechanical:
+
+| Before | After |
+|---|---|
+| `src/warden/index.js` | `@aimarket/warden` |
+| `src/warden/sandbox.js` | `@aimarket/warden` (`EgressGuard`, `isSensitiveTool`, `classifyTools`) |
+| `src/warden/pinning.js` | `@aimarket/warden` (`PinningGate`, `canonicalToolsHash`, …) |
+| `src/warden/jcs.js` | `@aimarket/warden/jcs` or the root export |
+| `MemoryStore` (for pins) | `PinStore` |
+| `Logger` | `WardenLogger` |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AICOM (alexar76)
+
+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-es.md

@@ -0,0 +1,190 @@
+# WARDEN — cortafuegos de seguridad para MCP
+
+<!-- aicom-readme-badges -->
+<p align="center">
+  <a href="https://github.com/alexar76/warden/actions/workflows/ci.yml"><img src="docs/badges/ci.svg" alt="CI" /></a>
+  <a href="https://www.npmjs.com/package/@aimarket/warden"><img src="https://img.shields.io/npm/v/@aimarket/warden?color=cb3837&label=npm" alt="npm version" /></a>
+  <img src="docs/badges/deps.svg" alt="Cero dependencias de ejecución" />
+  <img src="docs/badges/tests.svg" alt="141 pruebas en verde" />
+  <img src="docs/badges/node.svg" alt="Node >= 20" />
+  <a href="LICENSE"><img src="docs/badges/license.svg" alt="Licencia: MIT" /></a>
+</p>
+<!-- /aicom-readme-badges -->
+
+<p align="center">
+  <img src="docs/assets/hero.svg" alt="WARDEN — MCP security firewall: tool defs pass static-scan, threat-feed, origin, and pinning before a recorded verdict" width="920" />
+</p>
+
+
+> 🌐 [English](README.md) · [Русский](README-ru.md) · **Español** · [Français](README-fr.md) · [中文](README-zh.md) · [Glosario](https://github.com/alexar76/aicom/blob/main/docs/localization-glossary.md)
+
+Un servidor MCP le dice a tu agente qué hacen sus herramientas. El agente se lo cree — y esa frase
+es la superficie de ataque. La descripción de una herramienta es texto de prompt que un tercero
+entrega directamente al contexto de tu modelo, y un campo de esquema llamado `api_key` es una
+petición de tus secretos redactada como si fuera una API.
+
+WARDEN examina un servidor **antes de que ninguna de sus herramientas llegue al modelo**, y devuelve
+un veredicto que puedes registrar: permitir/bloquear, una puntuación 0..1, los hallazgos que la
+produjeron, una partición por herramienta y la tabla de reglas exacta que estaba en vigor.
+
+```bash
+npm install @aimarket/warden
+```
+
+**Cero dependencias de ejecución.** El único import de todo el paquete es `node:crypto`. Es el
+cortafuegos de [ARGUS](https://github.com/alexar76/argus), extraído para que puedas ponerlo delante
+de tu propio host MCP sin adoptar un agente.
+
+## Inicio rápido
+
+```ts
+import { Warden, ThreatFeed, silentLogger } from "@aimarket/warden";
+
+const threatFeed = new ThreatFeed({ feedPublicKey: process.env.FEED_PUBKEY });
+await threatFeed.load(process.env.FEED_URL); // sin URL → solo la lista de denegación integrada, sin red
+
+const pins = new Map();
+const warden = Warden.create({
+  policy: {
+    blockAtSeverity: "high",
+    sensitiveToolPatterns: ["*delete*", "*transfer*", "*key*"],
+    allowUnknownServers: false, // fail-closed: solo los servidores que declaraste
+    pinToolDefs: true,
+  },
+  threatFeed,
+  store: {
+    getPin: async (id) => pins.get(id),
+    putPin: async (p) => void pins.set(p.serverId, p),
+  },
+  log: silentLogger(), // o tu propio logger
+});
+
+const verdict = await warden.vet(server, await client.listTools());
+
+if (!verdict.allow) throw new Error(`bloqueado por ${verdict.decidedBy}`);
+const usable = verdict.allowedTools; // una herramienta envenenada puede quedar aislada sola
+await warden.approve(server, tools); // fija (pin) lo que el usuario aceptó
+```
+
+`vet()` **no hace ninguna petición de red**. La única petición que WARDEN llega a hacer es la
+descarga del threat feed que tú pediste al pasar una URL a `load()`.
+
+## La cadena de puertas
+
+```mermaid
+flowchart LR
+  T["definiciones<br/>de herramientas"] --> S["static scan<br/>25 reglas"]
+  S --> F["threat feed<br/>11 integradas + firmado"]
+  F --> O["origin<br/>declarado vs catálogo"]
+  O --> P["pinning<br/>deriva vs aprobación"]
+  P --> V["veredicto<br/>allow · score · findings<br/>allowedTools / blockedTools"]
+```
+
+| Puerta | Qué decide | Red | ¿Fatal? |
+|---|---|---|---|
+| **static-scan** | Inyección, exfiltración, peticiones de credenciales y señales de Unicode oculto/base64 en el `name`, la `description` y el `inputSchema` de la herramienta — 25 reglas, v4, de las cuales 15 pueden bloquear y 10 son solo de aviso, 17 cubren también el nombre y 12 llevan un guard de contexto | ninguna | no |
+| **threat-feed** | Identidad de servidor o herramienta conocida como maliciosa: 11 registros integrados más un feed firmado opcional | solo la descarga del feed | sí, para un `critical` con alcance de servidor |
+| **origin** | Si el operador declaró este servidor o llegó desde un catálogo remoto | ninguna | sí, con `allowUnknownServers: false` |
+| **pinning** | Si las definiciones de herramientas siguen coincidiendo con lo que el usuario aprobó | ninguna | sí, con `pinToolDefs: true` |
+
+La puntuación compuesta es el **producto** de las contribuciones de cada puerta: una puerta mala
+arrastra al servidor entero en lugar de promediarse. Severidad y bloqueo son ejes distintos: un
+hallazgo `advisory` se reporta y nunca bloquea ni cuesta una herramienta, con cualquier
+`blockAtSeverity` — porque «cuánta atención merece esto» y «¿es esto un defecto?» son preguntas
+distintas, y codificar la segunda como una severidad baja volvía a hacerla bloqueante para quien
+endureciera el umbral.
+
+## El veredicto está pensado para quedar registrado
+
+```ts
+{
+  allow: false,
+  score: 0,
+  decidedBy: "threat-feed",
+  findings: [{ gate, severity, code: "THREAT_TOOL_MATCH", message, tool, advisory? }],
+  allowedTools: ["add"],
+  blockedTools: ["sweeper"],
+  rulesets: { staticScan: { version: "4", digest: "sha256-klRyTiD3…" } }
+}
+```
+
+`rulesets` no es decoración. El mismo servidor puntúa distinto bajo una tabla de reglas posterior, y
+sin la versión *y* un digest sobre las reglas no hay forma de distinguir eso de que el servidor haya
+cambiado. Un escaneo guardado sin ellos no es reproducible.
+
+## Threat feed firmado
+
+WARDEN no leerá un feed remoto sin firma. El contrato es deliberadamente aburrido:
+
+```
+GET <la url de tu feed>
+{ "records": [ {pattern, severity, code, reason, source, scope}, … ],
+  "timestamp": 1786205907380,   // epoch ms, entero — obligatorio
+  "signature": "f588d5a4…"      // Ed25519 (hex) sobre la forma canónica
+}                               // RFC 8785 de {records, timestamp}
+```
+
+Se comprueban tres propiedades, y **cualquier fallo conserva el suelo integrado** en lugar de
+degradar a ninguna protección:
+
+1. **autenticidad** — Ed25519 contra la clave que fijaste de antemano (`feedPublicKey`);
+2. **frescura** — el timestamp *firmado* debe caer dentro de `maxAgeMs` (24 h por defecto), para que
+   quien sirve la URL no pueda reproducir una instantánea de hace meses y borrar en silencio cada
+   registro añadido desde entonces. Una firma dice quién escribió un documento, nunca cuándo te lo
+   entregaron;
+3. **determinismo** — bytes canónicos RFC 8785, para que editor y verificador coincidan sin importar
+   el orden de las claves JSON.
+
+[MOMUS](https://github.com/alexar76/momus) es un editor de referencia de este contrato
+(`/warden/threat-feed`) si necesitas algo a lo que apuntar con `load()`.
+
+## También incluido
+
+- **`EgressGuard`** — una lista de permitidos de salida con la que envolver cualquier petición que
+  haga una herramienta. Una herramienta que alcanza un host que nunca listaste es la señal clásica de
+  phone-home. `*.example.com` cubre subdominios; una lista vacía lo bloquea todo, no lo permite todo.
+- **`isSensitiveTool` / `classifyTools`** — clasificación por glob de las herramientas que deben
+  exigir aprobación en cada llamada. Las herramientas sensibles siguen *anunciadas*: simplemente no
+  pueden ejecutarse sin supervisión.
+- **`canonicalize` / `parseJsonStrict`** — una implementación estricta de RFC 8785 (JCS), exportada
+  también como `@aimarket/warden/jcs` para poder comparar otra implementación byte a byte. Solo
+  enteros más allá de `MAX_SAFE_JSON_INTEGER`, rechazo (no escapado) de surrogados solitarios y un
+  código de motivo en cada rechazo.
+
+## Documentación
+
+| | |
+|---|---|
+| [La cadena de puertas](docs/gates.es.md) | Cada nivel de regla, cada código de hallazgo, cómo se construye la puntuación compuesta y cómo añadir una puerta |
+| [El threat feed firmado](docs/threat-feed.es.md) | El contrato en el cable, las tres comprobaciones y cómo publicar un feed que WARDEN acepte |
+| [Guía de integración](docs/integration.es.md) | Cómo conectar WARDEN a tu propio host MCP, elecciones de política y qué registrar |
+| [Estudio de campo: 1 108 servidores MCP públicos](docs/mcp-survey.es.md) | Qué decidió WARDEN sobre definiciones de herramienta reales de terceros — 50 servidores bloqueados, 4 sustentados, y las seis formas en que el resto se equivocó |
+
+## Lo que esto no es
+
+- **No es un sandbox.** Son decisiones JS dentro del proceso. Aquí no hay confinamiento del proceso
+  hijo MCP a nivel de sistema operativo (seccomp/Landlock, `sandbox-exec`).
+- **No es un modelo.** En ninguna parte de la cadena se llama a un LLM. Por eso `vet()` es rápido,
+  offline y determinista — y por eso el escaneo estático tiene forma de regex y se le escapará una
+  paráfrasis que ninguna regla cubra.
+- **No es un servicio de reputación.** Una versión anterior tenía una puerta que pedía a un oráculo
+  de confianza una puntuación para la que no tenía datos, y luego informaba de que el oráculo era
+  inalcanzable sin haber enviado ninguna petición. Se eliminó, y
+  `test/no-phantom-gate.test.ts` falla si alguna puerta vuelve a declarar inalcanzabilidad.
+- **No sustituye a leer las definiciones de herramientas.** 11 registros integrados de amenazas son
+  un suelo, no un catálogo.
+
+## Desarrollo
+
+```bash
+npm install && npm run build && npm test   # 141 pruebas
+```
+
+`test/packaging.test.ts` es lo que mantiene honesto el titular: falla si aparece una dependencia de
+ejecución, si algún fichero fuente importa fuera del paquete o si el punto de entrada deja de
+exportar la superficie de aplicación.
+
+Usado por [ARGUS](https://github.com/alexar76/argus) (el host de referencia),
+[MOMUS](https://github.com/alexar76/momus) (el lado editor) y el curso de seguridad MCP de AICOM.
+
+MIT © AICOM (alexar76)

package/README-fr.md

@@ -0,0 +1,190 @@
+# WARDEN — pare-feu de sécurité MCP
+
+<!-- aicom-readme-badges -->
+<p align="center">
+  <a href="https://github.com/alexar76/warden/actions/workflows/ci.yml"><img src="docs/badges/ci.svg" alt="CI" /></a>
+  <a href="https://www.npmjs.com/package/@aimarket/warden"><img src="https://img.shields.io/npm/v/@aimarket/warden?color=cb3837&label=npm" alt="version npm" /></a>
+  <img src="docs/badges/deps.svg" alt="Zéro dépendance d'exécution" />
+  <img src="docs/badges/tests.svg" alt="141 tests au vert" />
+  <img src="docs/badges/node.svg" alt="Node >= 20" />
+  <a href="LICENSE"><img src="docs/badges/license.svg" alt="Licence : MIT" /></a>
+</p>
+<!-- /aicom-readme-badges -->
+
+<p align="center">
+  <img src="docs/assets/hero.svg" alt="WARDEN — MCP security firewall: tool defs pass static-scan, threat-feed, origin, and pinning before a recorded verdict" width="920" />
+</p>
+
+
+> 🌐 [English](README.md) · [Русский](README-ru.md) · [Español](README-es.md) · **Français** · [中文](README-zh.md) · [Glossaire](https://github.com/alexar76/aicom/blob/main/docs/localization-glossary.md)
+
+Un serveur MCP indique lui-même à votre agent ce que font ses outils. L'agent le croit — et cette
+phrase est la surface d'attaque. La description d'un outil est du texte de prompt qu'un tiers livre
+directement dans le contexte de votre modèle, et un champ de schéma nommé `api_key` est une demande
+de vos secrets formulée comme une API.
+
+WARDEN examine un serveur **avant qu'aucun de ses outils n'atteigne le modèle**, et renvoie un verdict
+que vous pouvez consigner : autoriser/bloquer, un score 0..1, les constats qui l'ont produit, une
+partition par outil et la table de règles exacte qui était en vigueur.
+
+```bash
+npm install @aimarket/warden
+```
+
+**Zéro dépendance d'exécution.** Le seul import de tout le paquet est `node:crypto`. C'est le pare-feu
+d'[ARGUS](https://github.com/alexar76/argus), extrait pour que vous puissiez le placer devant votre
+propre hôte MCP sans adopter d'agent.
+
+## Démarrage rapide
+
+```ts
+import { Warden, ThreatFeed, silentLogger } from "@aimarket/warden";
+
+const threatFeed = new ThreatFeed({ feedPublicKey: process.env.FEED_PUBKEY });
+await threatFeed.load(process.env.FEED_URL); // sans URL → uniquement la liste de refus intégrée, sans réseau
+
+const pins = new Map();
+const warden = Warden.create({
+  policy: {
+    blockAtSeverity: "high",
+    sensitiveToolPatterns: ["*delete*", "*transfer*", "*key*"],
+    allowUnknownServers: false, // fail-closed : uniquement les serveurs que vous avez déclarés
+    pinToolDefs: true,
+  },
+  threatFeed,
+  store: {
+    getPin: async (id) => pins.get(id),
+    putPin: async (p) => void pins.set(p.serverId, p),
+  },
+  log: silentLogger(), // ou votre propre logger
+});
+
+const verdict = await warden.vet(server, await client.listTools());
+
+if (!verdict.allow) throw new Error(`bloqué par ${verdict.decidedBy}`);
+const usable = verdict.allowedTools; // un outil empoisonné peut être isolé seul
+await warden.approve(server, tools); // épingler (pin) ce que l'utilisateur a accepté
+```
+
+`vet()` **n'effectue aucune requête réseau**. La seule requête que WARDEN émet jamais est le
+téléchargement du threat feed que vous avez demandé en passant une URL à `load()`.
+
+## La chaîne de portes
+
+```mermaid
+flowchart LR
+  T["définitions<br/>des outils"] --> S["static scan<br/>25 règles"]
+  S --> F["threat feed<br/>11 intégrées + signé"]
+  F --> O["origin<br/>déclaré vs catalogue"]
+  O --> P["pinning<br/>dérive vs approbation"]
+  P --> V["verdict<br/>allow · score · findings<br/>allowedTools / blockedTools"]
+```
+
+| Porte | Ce qu'elle décide | Réseau | Fatale ? |
+|---|---|---|---|
+| **static-scan** | Injection, exfiltration, demandes d'identifiants et indices d'Unicode masqué/base64 dans le `name`, la `description` et l'`inputSchema` de l'outil — 25 règles, v4, dont 15 peuvent bloquer et 10 sont purement indicatives, 17 couvrent aussi le nom et 12 portent un guard de contexte | aucun | non |
+| **threat-feed** | Identité de serveur ou outil connu comme malveillant : 11 enregistrements intégrés plus un feed signé optionnel | seulement le téléchargement du feed | oui, pour un `critical` de portée serveur |
+| **origin** | Si l'opérateur a déclaré ce serveur ou s'il provient d'un catalogue distant | aucun | oui, avec `allowUnknownServers: false` |
+| **pinning** | Si les définitions d'outils correspondent encore à ce que l'utilisateur a approuvé | aucun | oui, avec `pinToolDefs: true` |
+
+Le score composite est le **produit** des contributions de chaque porte : une seule porte mauvaise
+entraîne tout le serveur vers le bas au lieu d'être moyennée. Sévérité et blocage sont deux axes
+distincts : un constat `advisory` est rapporté et ne bloque jamais et ne coûte jamais un outil, quel
+que soit `blockAtSeverity` — parce que « quelle attention cela mérite-t-il » et « est-ce un défaut »
+sont deux questions différentes, et encoder la seconde par une sévérité basse la rendait de nouveau
+bloquante pour quiconque durcissait le seuil.
+
+## Le verdict est fait pour être consigné
+
+```ts
+{
+  allow: false,
+  score: 0,
+  decidedBy: "threat-feed",
+  findings: [{ gate, severity, code: "THREAT_TOOL_MATCH", message, tool, advisory? }],
+  allowedTools: ["add"],
+  blockedTools: ["sweeper"],
+  rulesets: { staticScan: { version: "4", digest: "sha256-klRyTiD3…" } }
+}
+```
+
+`rulesets` n'est pas un ornement. Le même serveur obtient un autre score sous une table de règles
+plus récente, et sans la version *et* une empreinte des règles, rien ne permet de distinguer cela
+d'un serveur qui a changé. Un scan conservé sans elles n'est pas reproductible.
+
+## Threat feed signé
+
+WARDEN ne lira pas un feed distant non signé. Le contrat est délibérément ennuyeux :
+
+```
+GET <l'url de votre feed>
+{ "records": [ {pattern, severity, code, reason, source, scope}, … ],
+  "timestamp": 1786205907380,   // epoch ms, entier — obligatoire
+  "signature": "f588d5a4…"      // Ed25519 (hex) sur la forme canonique
+}                               // RFC 8785 de {records, timestamp}
+```
+
+Trois propriétés sont vérifiées, et **tout échec conserve le socle intégré** au lieu de dégrader vers
+une absence de protection :
+
+1. **authenticité** — Ed25519 contre la clé que vous avez épinglée à l'avance (`feedPublicKey`) ;
+2. **fraîcheur** — le timestamp *signé* doit tomber dans `maxAgeMs` (24 h par défaut), afin que celui
+   qui sert l'URL ne puisse pas rejouer un instantané vieux de plusieurs mois et effacer en silence
+   chaque enregistrement ajouté depuis. Une signature dit qui a écrit un document, jamais quand il
+   vous a été remis ;
+3. **déterminisme** — octets canoniques RFC 8785, pour que l'éditeur et le vérificateur s'accordent
+   quel que soit l'ordre des clés JSON.
+
+[MOMUS](https://github.com/alexar76/momus) est un éditeur de référence de ce contrat
+(`/warden/threat-feed`) si vous cherchez une cible pour `load()`.
+
+## Également inclus
+
+- **`EgressGuard`** — une liste blanche de sortie pour envelopper toute requête émise par un outil.
+  Un outil qui joint un hôte que vous n'avez jamais listé est le signe classique du phone-home.
+  `*.example.com` couvre les sous-domaines ; une liste vide bloque tout, au lieu de tout autoriser.
+- **`isSensitiveTool` / `classifyTools`** — classification par glob des outils qui doivent exiger une
+  approbation à chaque appel. Les outils sensibles restent *annoncés* : ils ne peuvent simplement pas
+  s'exécuter sans surveillance.
+- **`canonicalize` / `parseJsonStrict`** — une implémentation stricte de RFC 8785 (JCS), également
+  exportée sous `@aimarket/warden/jcs` afin qu'une autre implémentation puisse être vérifiée octet par
+  octet. Entiers uniquement au-delà de `MAX_SAFE_JSON_INTEGER`, refus (et non échappement) des
+  surrogates isolés, et un code de motif sur chaque refus.
+
+## Documentation
+
+| | |
+|---|---|
+| [La chaîne de portes](docs/gates.fr.md) | Chaque niveau de règle, chaque code de constat, la construction du score composite et comment ajouter une porte |
+| [Le threat feed signé](docs/threat-feed.fr.md) | Le contrat sur le fil, les trois vérifications, et comment publier un feed que WARDEN acceptera |
+| [Guide d'intégration](docs/integration.fr.md) | Brancher WARDEN sur votre propre hôte MCP, choix de politique, et quoi consigner |
+| [Étude de terrain : 1 108 serveurs MCP publics](docs/mcp-survey.fr.md) | Ce que WARDEN a décidé sur de vraies définitions d'outil tierces — 50 serveurs bloqués, 4 étayés, et les six façons dont le reste était faux |
+
+## Ce que ce n'est pas
+
+- **Pas un sandbox.** Ce sont des décisions JS intra-processus. Le confinement du processus enfant MCP
+  au niveau du système d'exploitation (seccomp/Landlock, `sandbox-exec`) n'est pas ici.
+- **Pas un modèle.** Aucun LLM n'est appelé dans la chaîne. C'est pourquoi `vet()` est rapide, hors
+  ligne et déterministe — et pourquoi le scan statique a la forme d'expressions régulières et laissera
+  passer une paraphrase qu'aucune règle ne couvre.
+- **Pas un service de réputation.** Une version antérieure avait une porte qui demandait à un oracle
+  de confiance un score qu'il n'avait aucune donnée pour calculer, puis signalait l'oracle comme
+  injoignable sans avoir envoyé la moindre requête. Elle a été supprimée, et
+  `test/no-phantom-gate.test.ts` échoue si une porte déclare de nouveau une injoignabilité.
+- **Pas un substitut à la lecture des définitions d'outils.** 11 enregistrements de menaces intégrés
+  sont un socle, pas un catalogue.
+
+## Développement
+
+```bash
+npm install && npm run build && npm test   # 141 tests
+```
+
+`test/packaging.test.ts` est ce qui tient l'accroche honnête : il échoue si une dépendance d'exécution
+apparaît, si un fichier source importe hors du paquet, ou si le point d'entrée cesse d'exporter la
+surface d'application.
+
+Utilisé par [ARGUS](https://github.com/alexar76/argus) (l'hôte de référence),
+[MOMUS](https://github.com/alexar76/momus) (le côté éditeur) et le cours AICOM sur la sécurité MCP.
+
+MIT © AICOM (alexar76)