@aimarket/warden 0.0.1 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to `@aimarket/warden`.
+
+## 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, at the same ruleset version (`v2`,
+digest `sha256-gWC14PR4kUylkJaAGMnIYYX6tPhZTJ60cSB61UZxuWc=`), with the same 85 behavioural tests
+that guarded it there.
+
+### 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.
+
+### 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,184 @@
+# 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="95 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 -->
+
+> 🌐 [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 `description` e `inputSchema` — 25 reglas, v2, de las cuales 18 pueden bloquear y 7 son solo de aviso | 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: "2", digest: "sha256-gWC14PR4…" } }
+}
+```
+
+`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 |
+
+## 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   # 95 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,184 @@
+# 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="95 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 -->
+
+> 🌐 [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 `description` et `inputSchema` — 25 règles, v2, dont 18 peuvent bloquer et 7 sont purement indicatives | 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: "2", digest: "sha256-gWC14PR4…" } }
+}
+```
+
+`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 |
+
+## 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   # 95 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)

package/README-ru.md

@@ -0,0 +1,183 @@
+# WARDEN — файрвол безопасности 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="Zero runtime dependencies" />
+  <img src="docs/badges/tests.svg" alt="95 tests passing" />
+  <img src="docs/badges/node.svg" alt="Node >= 20" />
+  <a href="LICENSE"><img src="docs/badges/license.svg" alt="License: MIT" /></a>
+</p>
+<!-- /aicom-readme-badges -->
+
+> 🌐 [English](README.md) · **Русский** · [Español](README-es.md) · [Français](README-fr.md) · [中文](README-zh.md) · [Глоссарий](https://github.com/alexar76/aicom/blob/main/docs/localization-glossary.md)
+
+MCP-сервер сам сообщает вашему агенту, что делают его инструменты. Агент этому верит — и вот эта
+фраза и есть поверхность атаки. Описание инструмента — это текст промпта, который третья сторона
+доставляет прямо в контекст модели, а поле схемы с именем `api_key` — это запрос ваших секретов,
+сформулированный как API.
+
+WARDEN проверяет сервер **до того, как его инструменты дойдут до модели**, и возвращает вердикт,
+который можно записать: allow/block, оценку 0..1, найденные проблемы, разбиение по инструментам и
+точную таблицу правил, которая действовала в момент проверки.
+
+```bash
+npm install @aimarket/warden
+```
+
+**Ноль рантайм-зависимостей.** Единственный импорт во всём пакете — `node:crypto`. Это файрвол из
+[ARGUS](https://github.com/alexar76/argus), вынесенный отдельно, чтобы его можно было поставить
+перед своим MCP-хостом, не переезжая на агента.
+
+## Быстрый старт
+
+```ts
+import { Warden, ThreatFeed, silentLogger } from "@aimarket/warden";
+
+const threatFeed = new ThreatFeed({ feedPublicKey: process.env.FEED_PUBKEY });
+await threatFeed.load(process.env.FEED_URL); // без URL → только встроенный deny-list, без сети
+
+const pins = new Map();
+const warden = Warden.create({
+  policy: {
+    blockAtSeverity: "high",
+    sensitiveToolPatterns: ["*delete*", "*transfer*", "*key*"],
+    allowUnknownServers: false, // fail-closed: только объявленные вами серверы
+    pinToolDefs: true,
+  },
+  threatFeed,
+  store: {
+    getPin: async (id) => pins.get(id),
+    putPin: async (p) => void pins.set(p.serverId, p),
+  },
+  log: silentLogger(), // или ваш собственный логгер
+});
+
+const verdict = await warden.vet(server, await client.listTools());
+
+if (!verdict.allow) throw new Error(`заблокировано гейтом ${verdict.decidedBy}`);
+const usable = verdict.allowedTools; // отравленный инструмент можно изолировать в одиночку
+await warden.approve(server, tools); // зафиксировать (pin) то, что подтвердил пользователь
+```
+
+`vet()` **не делает сетевых запросов**. Единственный запрос, который WARDEN вообще выполняет, — это
+загрузка threat feed, о которой вы попросили сами, передав URL в `load()`.
+
+## Цепочка гейтов
+
+```mermaid
+flowchart LR
+  T["определения<br/>инструментов"] --> S["static scan<br/>25 правил"]
+  S --> F["threat feed<br/>11 встроенных + подписанный"]
+  F --> O["origin<br/>объявлен или из каталога"]
+  O --> P["pinning<br/>дрейф против подтверждения"]
+  P --> V["вердикт<br/>allow · score · findings<br/>allowedTools / blockedTools"]
+```
+
+| Гейт | Что решает | Сеть | Fatal? |
+|---|---|---|---|
+| **static-scan** | Инъекции, эксфильтрация, запросы учётных данных, скрытый Unicode и base64-признаки в `description` и `inputSchema` — 25 правил, версия 2, из них 18 могут блокировать и 7 только сообщают | нет | нет |
+| **threat-feed** | Известный плохой сервер или инструмент: 11 встроенных записей плюс опциональный подписанный feed | только загрузка feed | да, для `critical` на уровне сервера |
+| **origin** | Объявил ли оператор этот сервер, или он пришёл из удалённого каталога | нет | да, при `allowUnknownServers: false` |
+| **pinning** | Совпадают ли определения инструментов с тем, что подтвердил пользователь | нет | да, при `pinToolDefs: true` |
+
+Composite score — это **произведение** вкладов гейтов: один плохой гейт тянет весь сервер вниз, а не
+усредняется. Severity и блокировка — разные оси: находка с `advisory` сообщается, но никогда не
+блокирует и никогда не стоит инструмента, при любом `blockAtSeverity`. Потому что «сколько внимания
+это заслуживает» и «дефект ли это вообще» — разные вопросы, а кодирование второго через низкую
+severity снова делало находку блокирующей для всех, кто ужесточил порог.
+
+## Вердикт рассчитан на то, чтобы его записали
+
+```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: "2", digest: "sha256-gWC14PR4…" } }
+}
+```
+
+`rulesets` — не украшение. Один и тот же сервер получит другую оценку под более поздней таблицей
+правил, и без версии *и* дайджеста по правилам невозможно отличить это от того, что изменился сам
+сервер. Сохранённый скан без них невоспроизводим.
+
+## Подписанный threat feed
+
+WARDEN не станет читать неподписанный удалённый feed. Контракт намеренно скучный:
+
+```
+GET <ваш feed url>
+{ "records": [ {pattern, severity, code, reason, source, scope}, … ],
+  "timestamp": 1786205907380,   // epoch ms, целое — обязательно
+  "signature": "f588d5a4…"      // Ed25519 (hex) по канонической форме
+}                               // RFC 8785 от {records, timestamp}
+```
+
+Проверяются три свойства, и **любой сбой сохраняет встроенный минимум**, а не деградирует до полного
+отсутствия защиты:
+
+1. **подлинность** — Ed25519 против ключа, закреплённого заранее (`feedPublicKey`);
+2. **свежесть** — *подписанный* timestamp должен попадать в окно `maxAgeMs` (по умолчанию 24 ч),
+   чтобы тот, кто раздаёт URL, не мог подсунуть снимок месячной давности и молча стереть все
+   добавленные с тех пор записи. Подпись говорит, кто написал документ, но никогда — когда его вам
+   вручили;
+3. **детерминизм** — канонические байты RFC 8785, чтобы издатель и проверяющий совпадали независимо
+   от порядка ключей в JSON.
+
+[MOMUS](https://github.com/alexar76/momus) — референсный издатель этого контракта
+(`/warden/threat-feed`), если нужно, на что направить `load()`.
+
+## Что ещё внутри
+
+- **`EgressGuard`** — allowlist исходящих запросов, которым можно обернуть любой запрос инструмента.
+  Инструмент, тянущийся к хосту, которого вы не перечисляли, — классический признак phone-home.
+  `*.example.com` совпадает с поддоменами; пустой allowlist блокирует всё, а не разрешает всё.
+- **`isSensitiveTool` / `classifyTools`** — glob-классификация инструментов, которые обязаны требовать
+  подтверждения на каждый вызов. Чувствительные инструменты остаются *объявленными* — они просто не
+  могут выполняться без присмотра.
+- **`canonicalize` / `parseJsonStrict`** — строгая реализация RFC 8785 (JCS), экспортируется и как
+  `@aimarket/warden/jcs`, чтобы другую реализацию можно было сверить с ней побайтово. Только целые
+  за пределами `MAX_SAFE_JSON_INTEGER`, отказ (а не экранирование) на одиночных суррогатах и код
+  причины на каждом отказе.
+
+## Документация
+
+| | |
+|---|---|
+| [Цепочка гейтов](docs/gates.ru.md) | Все уровни правил, все коды находок, как складывается composite score и как добавить свой гейт |
+| [Подписанный threat feed](docs/threat-feed.ru.md) | Контракт на проводе, три проверки и как публиковать feed, который WARDEN примет |
+| [Руководство по интеграции](docs/integration.ru.md) | Как встроить WARDEN в свой MCP-хост, выбор политики и что записывать |
+
+## Чем это не является
+
+- **Не песочница.** Это внутрипроцессные решения на JS. Изоляции дочернего MCP-процесса на уровне ОС
+  (seccomp/Landlock, `sandbox-exec`) здесь нет.
+- **Не модель.** В цепочке нигде не вызывается LLM. Именно поэтому `vet()` быстрый, офлайновый и
+  детерминированный — и именно поэтому static scan имеет форму регулярок и пропустит перефразировку,
+  которую не покрывает ни одно правило.
+- **Не сервис репутации.** В более ранней версии был гейт, который спрашивал у trust-оракула оценку,
+  для вычисления которой у того не было данных, а затем сообщал, что оракул недоступен, так и не
+  отправив запроса. Гейт удалён, и `test/no-phantom-gate.test.ts` падает, если какой-нибудь гейт
+  снова заявит о недоступности.
+- **Не замена чтению определений инструментов.** 11 встроенных записей об угрозах — это минимум, а не
+  каталог.
+
+## Разработка
+
+```bash
+npm install && npm run build && npm test   # 95 тестов
+```
+
+`test/packaging.test.ts` — то, что удерживает заголовок честным: он падает, если появляется
+рантайм-зависимость, если какой-то файл импортирует что-то за пределами пакета или если точка входа
+перестаёт экспортировать поверхность энфорсмента.
+
+Используется в [ARGUS](https://github.com/alexar76/argus) (референсный хост),
+[MOMUS](https://github.com/alexar76/momus) (сторона издателя) и в курсе AICOM по безопасности MCP.
+
+MIT © AICOM (alexar76)