@aimarket/warden 0.7.0 → 0.8.1

package/docs/gates.es.md

@@ -0,0 +1,224 @@
+# La cadena de puertas
+
+> 🌐 [English](gates.md) · [Русский](gates.ru.md) · **Español** · [Français](gates.fr.md) · [中文](gates.zh.md)
+
+> [Seguridad y migración de 0.7.0](security-hardening.es.md).
+
+`Warden.vet(server, tools)` ejecuta una cadena ordenada y devuelve un solo veredicto. Esta página es
+todo el procedimiento de decisión: qué mira cada puerta, qué puede bloquear y cómo se construye el
+número final.
+
+```
+static-scan  →  threat-feed  →  origin  →  pinning
+ (gratis)        (gratis tras    (gratis)   (gratis)
+                  load)
+```
+
+El orden va de lo más barato y local primero. Nada en la cadena hace una petición de red: la única
+descarga que WARDEN llega a hacer es `ThreatFeed.load(url)`, que llamas tú, antes de examinar nada.
+
+## Cómo se ensambla un veredicto
+
+Cada puerta devuelve `{ findings, score, fatal? }`. La cadena:
+
+1. ejecuta todas las puertas en orden, acumulando hallazgos (cada puerta ve `prior`);
+2. multiplica las puntuaciones de las puertas — la compuesta es un **producto**, así que una puerta
+   mala arrastra al servidor hacia abajo en vez de quedar promediada por tres buenas;
+3. bloquea si alguna puerta devolvió `fatal`, o si algún hallazgo no advisory alcanza
+   `policy.blockAtSeverity`;
+4. corta la cadena **solo** ante un `fatal` explícito. Un hallazgo bloqueante pero no fatal deja que
+   las puertas restantes informen, para que el registro del *por qué* quede completo.
+
+```ts
+const SEVERITY_RANK = { info: 0, low: 1, medium: 2, high: 3, critical: 4 };
+```
+
+Si `policy.blockAtSeverity` no es una de esas cinco claves, el constructor registra un aviso y cae a
+`"high"`. Una errata ahí era antes el peor fallo posible: `rank >= undefined` es `false` en toda
+comparación, de modo que un umbral mal escrito desactivaba el bloqueo por completo, en silencio.
+
+### Dos ejes: severidad y nivel
+
+La severidad responde a *cuánta atención merece esto*. El **nivel** (tier) responde a *¿es esto un
+defecto?* — y es un dato del hallazgo (`advisory: true`), no una consecuencia de la severidad.
+
+Un hallazgo `advisory` se reporta, nunca bloquea y nunca cuesta una herramienta, con **cualquier**
+`blockAtSeverity`. Una herramienta cuyo esquema acepta un `api_key` merece que se la señale y no es un
+defecto; expresarlo bajando su severidad la volvía bloqueante para quien endureciera el umbral.
+
+## static-scan
+
+Escaneo local con regex sobre el `name`, la `description` y el `inputSchema` de cada herramienta. 26
+reglas en el conjunto **v7**: 15 `block`, 11 `advise`, y 15 de ellas llevan un **guard** de contexto:
+una comprobación con nombre que decide si una coincidencia es de verdad lo que la regla busca. Véase
+[el estudio de campo](mcp-survey.es.md), la ejecución sobre 1 108 servidores con la que se calibró v4.
+
+**v5: el texto se normaliza antes de que lo lea ninguna regla.** NFKC convierte letras de ancho completo,
+ligaduras y otras formas de compatibilidad en letras normales; los caracteres invisibles dentro de una
+palabra se eliminan; el bloque de etiquetas Unicode (copias invisibles de ASCII capaces de llevar una frase
+entera) se decodifica; y dentro de una palabra que mezcla latino con cirílico o griego, las letras sosias
+pasan a latinas, mientras que una palabra escrita entera en un solo alfabeto no se toca. Una regla escrita
+en inglés ya no se elude con letras de ancho completo, un espacio de ancho cero, etiquetas o una `о`
+cirílica, sea cual sea el idioma del texto. La normalización se publica como `fold` y forma parte del
+digest. Las dos reglas de cargas ocultas leen el texto **en bruto** (`raw: true`).
+
+Una tabla de regex no lee significado: una frase en un idioma para el que las reglas no están escritas queda
+fuera. v5 añade lo que no depende del idioma: la normalización, el par `TOOL_DEF_SECRET_EXFIL` (un almacén de
+secretos y una dirección externa a menos de 100 caracteres; solo de aviso, porque su única coincidencia en
+10 645 servidores reales era honesta), el bloque de etiquetas y los aislantes bidi en `TOOL_DEF_HIDDEN_UNICODE`;
+y HISTOR señala toda dirección externa que aparece por primera vez. Detectar por significado corresponde a un
+clasificador, no a esta tabla.
+
+v5 también elimina tres falsos positivos medidos: «send the user to https://…» (redirigir a una persona, guard
+`navigation`), «keep calling … without asking the user» (autonomía, guard `autonomy`) y el unificador de ancho
+cero dentro de un emoji. Sobre el corpus de 10 645 servidores v5 bloquea 56 donde v4 bloqueaba 63, y ninguno
+que v4 no bloqueara.
+
+**v7** elimina tres falsos positivos que el conjunto v6 aún daba sobre el corpus versionado del
+2026-10-01 ([el estudio de campo](mcp-survey.es.md)). «Private key/value memory» nombra un almacén
+clave-valor, no una clave privada (guard `keyValue`: un compuesto con barra o guion seguido de un
+sustantivo de almacén). «Find … without asking the user for ids» es una herramienta que resuelve sola
+un identificador (guard `autonomy`, que ahora también acepta un verbo de búsqueda cuando todo el
+objeto es un identificador). «The key is read from the MCP connection's X-API-Key header» es un
+servidor que describe su propia autenticación (guard `ownAuthHeader`: pasiva «is read from», una
+cabecera de la petición, no ajena, y la clave no se envía a ninguna parte). Además, `autonomy` ya no
+exime un «without asking the user» cuyo objeto es el consentimiento: «keep retrying the transfer
+without asking the user for approval» vuelve a bloquear. Sobre ese corpus v7 bloquea 3 servidores
+donde v6 bloqueaba 6, y el resto de hallazgos no cambia.
+
+Cada regla declara sobre cuál de esas tres **superficies** se ejecuta, y 17 de las 26 incluyen el
+nombre. Las cuatro que no lo hacen son las que se apoyan en un SUSTANTIVO
+(`TOOL_DEF_SECRET_REQUEST`, `TOOL_DEF_CREDENTIAL_PARAM`, `TOOL_DEF_ENV_REFERENCE`, `TOOL_DEF_SECRET_EXFIL`): un nombre es un
+identificador, `api_key` y `private_key` son partes ordinarias de uno, y rechazar
+`sign_with_private_key` sería cometer el error de calibración de v1 en una superficie nueva. Las
+reglas que se apoyan en una FRASE necesitan espacios y no pueden coincidir con `snake_case` en
+absoluto, y las dos reglas de carga oculta hablan de caracteres que nunca son legítimos en un
+nombre: esas se ejecutan en todas partes.
+
+Hasta v3 el nombre no lo escaneaba **nada**, así que una frase de inyección, un carácter de ancho
+cero o un blob base64 en el primer campo que lee el modelo no se reportaban en absoluto.
+
+La puntuación de la puerta es `1 − penalización(peor severidad bloqueante)`; los avisos nunca la
+afectan.
+
+| peor severidad bloqueante | ninguna | info | low | medium | high | critical |
+|---|---|---|---|---|---|---|
+| puntuación | 1 | 1 | 0.9 | 0.7 | 0.4 | 0 |
+
+| Código | Severidad | Nivel | ¿Nombre? | Qué detecta |
+|---|---|---|---|---|
+| `TOOL_DEF_INJECTION` | critical / high | block | ✅ | «ignore all previous instructions», «do not tell the user», etiquetas `<system>`, referencias al prompt del desarrollador |
+| `TOOL_DEF_SECRET_REQUEST` | critical | block | — | `private_key`, `seed_phrase`/`mnemonic`, rutas `~/.ssh` |
+| `TOOL_DEF_SECRET_HARVEST` | critical | block | ✅ | una herramienta cuyo cometido declarado es leer/volcar/revelar secretos |
+| `TOOL_DEF_EXFIL` | critical / high | block | ✅ | «post to https://…», «forward it to…», «exfiltrate», fraseo de subida a un host |
+| `TOOL_DEF_HIDDEN_UNICODE` | high | block | ✅ | caracteres de ancho cero y de control bidi — texto que el revisor no ve |
+| `TOOL_DEF_BASE64_BLOB` | high | block | ✅ | una tirada base64 de 120+ caracteres en un nombre, una descripción o un esquema |
+| `TOOL_DEF_DATA_URL` | high | block | ✅ | URLs `data:…;base64,` y `javascript:` |
+| `TOOL_DEF_CREDENTIAL_PARAM` | medium / low | advise | — | esquema o descripción que pide `api_key`, `password`, `secret`, tokens bearer |
+| `TOOL_DEF_ENV_REFERENCE` | medium | advise | — | `.env`, «environment variables» |
+| `TOOL_DEF_IMPERATIVE` | low / info | advise | ✅ | «you must», «instead of» — fraseo con forma de prompt, que por sí solo no prueba nada |
+
+`staticScanRuleset()` devuelve cada regla con **el fuente de su regex, sus flags y sus superficies**, para que un
+tercero pueda reejecutar exactamente la misma regla, más `{ version, digest }`, donde el digest es
+sha256 sobre la forma canónica RFC 8785 de la lista ordenada de reglas. La ordenación es por
+comparación de unidades de código, nunca `localeCompare`: una collation dependiente del locale haría
+que la misma tabla produjera un digest distinto en un host configurado de otra forma, que es justo la
+divergencia que el digest existe para detectar.
+
+## threat-feed
+
+Compara la identidad del servidor y las definiciones de herramientas con registros `ThreatRecord` — 11
+integrados más lo que haya añadido un feed firmado (ver [el contrato del feed](threat-feed.es.md)).
+
+- Cualquier coincidencia ⇒ puntuación de la puerta **0**.
+- `fatal` **solo** para un registro `critical` que coincide contra el *servidor*. Una coincidencia
+  crítica en una *herramienta* no es fatal, así que el resto de la cadena sigue informando y la culpa
+  queda circunscrita a esa herramienta — eso es lo que permite que un servidor casi correcto siga
+  funcionando con una herramienta en cuarentena.
+- `ThreatRecord.scope` elige la superficie: `server` (id/name/url/command/args), `tool`
+  (name/description/inputSchema) o `any` — el valor por defecto cuando el registro lo omite.
+
+Códigos integrados: `THREAT_TYPOSQUAT`, `THREAT_CRYPTO_DRAINER`, `THREAT_SEED_PHRASE`,
+`THREAT_SSH_KEY_READ`, `THREAT_ENV_EXFIL`, `THREAT_DESTRUCTIVE_CMD`, `THREAT_FORK_BOMB`.
+
+## origin
+
+¿Declaró el operador este servidor, o llegó desde un catálogo remoto (`McpServerRef.catalog` está
+puesto)?
+
+| `allowUnknownServers` | hallazgo | puntuación | fatal |
+|---|---|---|---|
+| `false` (fail-closed) | `SERVER_UNDECLARED`, high | 0 | sí |
+| `true` | `SERVER_UNDECLARED`, info | 1 | no |
+
+Este interruptor significaba antes «todavía no tiene puntuación de reputación», algo que ningún
+despliegue podía satisfacer: nunca se suministraron aristas de confianza al oráculo, así que todo
+servidor volvía sin avalar y `false` los bloqueaba todos. La procedencia de catálogo es un hecho que
+el host ya tiene en local, no necesita red y no puede provocar un bloqueo mutuo.
+
+## pinning
+
+Compara las definiciones actuales con la instantánea que aprobó el usuario. El hash es sha256 sobre la
+forma canónica RFC 8785 del conjunto de definiciones — la misma canonicalización que usa la firma del
+feed, no una segunda serialización.
+
+| Situación | Código | Severidad | Puntuación | Fatal |
+|---|---|---|---|---|
+| Aún sin pin (primer contacto) | `TOOL_DEF_UNPINNED` | info | 0.9 | no |
+| El hash difiere del pin | `TOOL_DEF_DRIFT` | high | 0 | con `pinToolDefs` |
+| Las definiciones no tienen forma canónica (sin pin) | `TOOL_DEF_UNCANONICAL` | medium | 0.5 | no |
+| Las definiciones no tienen forma canónica (con pin) | `TOOL_DEF_UNCANONICAL` | high | 0 | con `pinToolDefs` |
+
+El primer contacto cuesta 0.1, no un bloqueo: un servidor limpio, declarado y sin pin puntúa
+exactamente **0.9**, y `TOOL_DEF_UNPINNED` es `info` a propósito — con `blockAtSeverity: "info"`, un
+primer encuentro bloqueante haría que todo servidor fuera inservible para siempre, ya que nada puede
+fijarse antes de ser aprobado una vez.
+
+`warden.approve(server, tools)` escribe el pin a través de tu `PinStore`. Es idempotente.
+
+## Partición por herramienta
+
+`allowedTools` / `blockedTools` reparten las herramientas anunciadas:
+
+- una herramienta está **bloqueada** si un hallazgo no advisory la nombra (`finding.tool`) y alcanza
+  el umbral;
+- todas las demás quedan permitidas;
+- las herramientas sensibles (`policy.sensitiveToolPatterns`) siguen *permitidas*: quedan marcadas
+  para que el bucle de tu agente pueda exigir aprobación en cada llamada en tiempo de ejecución. Ver
+  `classifyTools` / `isSensitiveTool`.
+
+## Añadir una puerta
+
+`WardenGate` son tres líneas de interfaz, y `new Warden({ gates, policy, log })` toma la cadena
+directamente, así que puedes insertar la tuya sin hacer un fork:
+
+```ts
+import { Warden, StaticScanGate, ThreatGate, OriginGate, PinningGate } from "@aimarket/warden";
+import type { WardenGate, WardenGateInput, WardenGateResult } from "@aimarket/warden";
+
+class DenyByPublisher implements WardenGate {
+  readonly name = "publisher-allowlist";
+  async evaluate(input: WardenGateInput): Promise<WardenGateResult> {
+    const ok = ALLOWED.has(input.server.name);
+    return ok
+      ? { findings: [], score: 1 }
+      : { findings: [{ gate: this.name, severity: "high", code: "PUBLISHER_UNKNOWN",
+                       message: `${input.server.name} no es un editor permitido` }],
+          score: 0, fatal: true };
+  }
+}
+
+const warden = new Warden({
+  gates: [new StaticScanGate(), new ThreatGate(feed), new DenyByPublisher(), new OriginGate(), new PinningGate(store)],
+  policy,
+});
+```
+
+Dos reglas para una puerta propia: **nunca afirmes que un servicio remoto es inalcanzable si no
+enviaste realmente una petición** (`test/no-phantom-gate.test.ts` lo impone sobre las puertas que se
+envían) y devuelve una puntuación que puedas defender — una puerta que no midió nada debe devolver
+`1`, no un 0.6 «neutro», o penaliza a cada servidor por una medición que nunca hizo.
+
+## Las puertas en modo wrap
+
+`vetLaunch` precede al arranque. `initialize.instructions` pasa por static-scan y se elimina al bloquearse. `tools/list` reúne como máximo 32 páginas, 256 herramientas únicas y 1 MiB antes de `vet`; solo se exponen definiciones permitidas en una página. `list_changed` activa cuarentena inmediatamente y se reenvía solo tras verificar. Cada llamada vuelve a listar y compara con la definición mostrada al cliente. Un cambio durante la comprobación impide enviar; durante la ejecución retiene el resultado. Los mensajes transparentes tienen límite de 32 MiB. Las peticiones internas caducan a los 10 segundos. EOF cierra stdin del hijo, SIGTERM llega tras 5 segundos y SIGKILL antes de 10. Las peticiones del servidor y demás mensajes conservan ID y JSON original. Consulte README para política, TOFU, revisión humana y audit-only.

package/docs/gates.fr.md

@@ -0,0 +1,228 @@
+# La chaîne de portes
+
+> 🌐 [English](gates.md) · [Русский](gates.ru.md) · [Español](gates.es.md) · **Français** · [中文](gates.zh.md)
+
+> [Sécurité et migration 0.7.0](security-hardening.fr.md).
+
+`Warden.vet(server, tools)` exécute une chaîne ordonnée et renvoie un seul verdict. Cette page est
+toute la procédure de décision : ce que regarde chaque porte, ce qu'elle peut bloquer, et comment le
+nombre final se construit.
+
+```
+static-scan  →  threat-feed  →  origin  →  pinning
+ (gratuit)       (gratuit après  (gratuit)  (gratuit)
+                  load)
+```
+
+L'ordre va du moins coûteux et du plus local d'abord. Rien dans la chaîne n'effectue de requête réseau :
+le seul téléchargement que WARDEN émette jamais est `ThreatFeed.load(url)`, que vous appelez vous-même,
+avant tout examen.
+
+## Comment un verdict est assemblé
+
+Chaque porte renvoie `{ findings, score, fatal? }`. La chaîne :
+
+1. exécute toutes les portes dans l'ordre, en accumulant les constats (chaque porte voit `prior`) ;
+2. multiplie les scores des portes — le composite est un **produit**, donc une porte mauvaise tire tout
+   le serveur vers le bas au lieu d'être moyennée par trois bonnes ;
+3. bloque si une porte a renvoyé `fatal`, ou si un constat non advisory atteint
+   `policy.blockAtSeverity` ;
+4. n'interrompt la chaîne **que** sur un `fatal` explicite. Un constat bloquant mais non fatal laisse
+   les portes restantes rapporter, pour que la trace du *pourquoi* reste complète.
+
+```ts
+const SEVERITY_RANK = { info: 0, low: 1, medium: 2, high: 3, critical: 4 };
+```
+
+Si `policy.blockAtSeverity` n'est pas l'une de ces cinq clés, le constructeur journalise un
+avertissement et retombe sur `"high"`. Une coquille à cet endroit était auparavant la pire défaillance
+possible : `rank >= undefined` est `false` pour toute comparaison, donc un seuil mal orthographié
+désactivait silencieusement tout blocage.
+
+### Deux axes : sévérité et palier
+
+La sévérité répond à *quelle attention cela mérite-t-il*. Le **palier** (tier) répond à *est-ce un
+défaut ?* — et c'est une donnée portée par le constat (`advisory: true`), non une conséquence de la
+sévérité.
+
+Un constat `advisory` est rapporté, ne bloque jamais et ne coûte jamais un outil, avec **n'importe
+quel** `blockAtSeverity`. Un outil dont le schéma accepte une `api_key` mérite qu'on le signale et n'est
+pas un défaut ; l'exprimer en abaissant sa sévérité le rendait de nouveau bloquant pour quiconque
+durcissait le seuil.
+
+## static-scan
+
+Analyse locale par expressions régulières du `name`, de la `description` et de l'`inputSchema` de
+chaque outil. 26 règles dans le jeu **v7** : 15 `block`, 11 `advise`, et 15 d'entre elles portent un **guard** de
+contexte — une vérification nommée qui décide si une correspondance est vraiment ce que la règle
+cherche. Voir [l'étude de terrain](mcp-survey.fr.md), le passage sur 1 108 serveurs qui a calibré v4.
+
+**v5 : le texte est normalisé avant qu'aucune règle ne le lise.** NFKC ramène les lettres pleine chasse,
+les ligatures et autres formes de compatibilité à des lettres ordinaires ; les caractères invisibles à
+l'intérieur d'un mot sont retirés ; le bloc des balises Unicode (copies invisibles de l'ASCII, capables de
+porter une phrase entière) est décodé ; et dans un mot qui mêle le latin au cyrillique ou au grec, les
+lettres sosies deviennent latines — un mot écrit entièrement dans un seul alphabet n'est pas touché. Une
+règle écrite en anglais ne se contourne donc plus par la pleine chasse, une espace sans chasse, des balises
+ou un `о` cyrillique, quelle que soit la langue du texte. La normalisation est publiée comme `fold` et entre
+dans l'empreinte. Les deux règles de charges cachées lisent le texte **brut** (`raw: true`).
+
+Une table d'expressions régulières ne lit pas le sens : une formulation dans une langue pour laquelle les
+règles ne sont pas écrites lui échappe. v5 ajoute ce qui ne dépend pas de la langue : la normalisation, la
+paire `TOOL_DEF_SECRET_EXFIL` (un magasin de secrets et une adresse externe à moins de 100 caractères ;
+purement indicative, sa seule correspondance sur 10 645 serveurs réels étant honnête), le bloc des balises
+et les isolats bidi dans `TOOL_DEF_HIDDEN_UNICODE` ; et HISTOR signale toute adresse externe qui apparaît
+pour la première fois. Détecter le sens relève d'un classifieur, pas de cette table.
+
+v5 supprime aussi trois faux positifs mesurés : « send the user to https://… » (redirection d'une personne,
+guard `navigation`), « keep calling … without asking the user » (autonomie, guard `autonomy`) et le liant sans
+chasse à l'intérieur d'un emoji. Sur le corpus de 10 645 serveurs, v5 bloque 56 serveurs là où v4 en bloquait
+63, et aucun que v4 ne bloquait pas.
+
+**v7** supprime trois faux positifs que le jeu v6 produisait encore sur le corpus versionné du
+2026-10-01 ([l'étude de terrain](mcp-survey.fr.md)). « Private key/value memory » désigne un magasin
+clé-valeur, pas une clé privée (guard `keyValue` : un composé avec barre oblique ou trait d'union suivi
+d'un nom de magasin). « Find … without asking the user for ids » est un outil qui résout lui-même un
+identifiant (guard `autonomy`, qui accepte désormais aussi un verbe de recherche quand tout l'objet est
+un identifiant). « The key is read from the MCP connection's X-API-Key header » est un serveur qui
+décrit sa propre authentification (guard `ownAuthHeader` : passif « is read from », un en-tête de
+requête, pas celui d'un autre, et la clé n'est envoyée nulle part). En outre, `autonomy` n'exempte plus
+un « without asking the user » dont l'objet est le consentement : « keep retrying the transfer without
+asking the user for approval » bloque de nouveau. Sur ce corpus, v7 bloque 3 serveurs là où v6 en
+bloquait 6, et toutes les autres alertes sont inchangées.
+
+Chaque règle déclare sur laquelle de ces trois **surfaces** elle s'exécute, et 17 des 26 incluent le
+nom. Les quatre qui ne l'incluent pas sont celles qui reposent sur un NOM COMMUN
+(`TOOL_DEF_SECRET_REQUEST`, `TOOL_DEF_CREDENTIAL_PARAM`, `TOOL_DEF_ENV_REFERENCE`, `TOOL_DEF_SECRET_EXFIL`) : un nom d'outil
+est un identifiant, `api_key` et `private_key` en sont des morceaux ordinaires, et refuser
+`sign_with_private_key` reviendrait à commettre l'erreur de calibrage de v1 sur une nouvelle
+surface. Les règles reposant sur une PHRASE exigent des espaces et ne peuvent donc pas correspondre
+à du `snake_case`, et les deux règles de charge cachée portent sur des caractères qui ne sont jamais
+légitimes dans un nom : celles-là s'exécutent partout.
+
+Jusqu'à v3, le nom n'était analysé par **rien** : une phrase d'injection, un caractère de largeur
+nulle ou un blob base64 dans le premier champ que lit le modèle n'était pas rapporté du tout.
+
+Le score de la porte est `1 − pénalité(pire sévérité bloquante)` ; les constats indicatifs ne
+l'affectent jamais.
+
+| pire sévérité bloquante | aucune | info | low | medium | high | critical |
+|---|---|---|---|---|---|---|
+| score de la porte | 1 | 1 | 0.9 | 0.7 | 0.4 | 0 |
+
+| Code | Sévérité | Palier | Nom ? | Ce qu'il attrape |
+|---|---|---|---|---|
+| `TOOL_DEF_INJECTION` | critical / high | block | ✅ | « ignore all previous instructions », « do not tell the user », balises `<system>`, références au prompt développeur |
+| `TOOL_DEF_SECRET_REQUEST` | critical | block | — | `private_key`, `seed_phrase`/`mnemonic`, chemins `~/.ssh` |
+| `TOOL_DEF_SECRET_HARVEST` | critical | block | ✅ | un outil dont la mission déclarée est de lire/extraire/révéler des secrets |
+| `TOOL_DEF_EXFIL` | critical / high | block | ✅ | « post to https://… », « forward it to… », « exfiltrate », formulations d'upload vers un hôte |
+| `TOOL_DEF_HIDDEN_UNICODE` | high | block | ✅ | caractères de largeur nulle et de contrôle bidi — du texte que le relecteur ne voit pas |
+| `TOOL_DEF_BASE64_BLOB` | high | block | ✅ | une suite base64 de 120+ caractères dans un nom, une description ou un schéma |
+| `TOOL_DEF_DATA_URL` | high | block | ✅ | URLs `data:…;base64,` et `javascript:` |
+| `TOOL_DEF_CREDENTIAL_PARAM` | medium / low | advise | — | schéma ou description réclamant `api_key`, `password`, `secret`, jetons bearer |
+| `TOOL_DEF_ENV_REFERENCE` | medium | advise | — | `.env`, « environment variables » |
+| `TOOL_DEF_IMPERATIVE` | low / info | advise | ✅ | « you must », « instead of » — formulation en forme de prompt, qui à elle seule ne prouve rien |
+
+`staticScanRuleset()` renvoie chaque règle avec **la source de sa regex, ses drapeaux et ses surfaces**, pour qu'un
+tiers puisse rejouer exactement la même règle, plus `{ version, digest }`, où l'empreinte est un sha256
+sur la forme canonique RFC 8785 de la liste triée des règles. Le tri se fait par comparaison d'unités
+de code, jamais `localeCompare` : une collation dépendante de la locale ferait que la même table
+produise une empreinte différente sur un hôte configuré autrement — précisément la divergence que
+l'empreinte existe pour détecter.
+
+## threat-feed
+
+Confronte l'identité du serveur et les définitions d'outils à des `ThreatRecord` — 11 intégrés plus ce
+qu'un feed signé a ajouté (voir [le contrat du feed](threat-feed.fr.md)).
+
+- Toute correspondance ⇒ score de la porte **0**.
+- `fatal` **uniquement** pour un enregistrement `critical` correspondant au *serveur*. Une
+  correspondance critique sur un *outil* n'est pas fatale : le reste de la chaîne continue de
+  rapporter et la faute reste circonscrite à cet outil — c'est ce qui permet à un serveur globalement
+  correct de rester utilisable avec un outil en quarantaine.
+- `ThreatRecord.scope` choisit la surface : `server` (id/name/url/command/args), `tool`
+  (name/description/inputSchema) ou `any` — la valeur par défaut quand l'enregistrement l'omet.
+
+Codes intégrés : `THREAT_TYPOSQUAT`, `THREAT_CRYPTO_DRAINER`, `THREAT_SEED_PHRASE`,
+`THREAT_SSH_KEY_READ`, `THREAT_ENV_EXFIL`, `THREAT_DESTRUCTIVE_CMD`, `THREAT_FORK_BOMB`.
+
+## origin
+
+L'opérateur a-t-il déclaré ce serveur, ou provient-il d'un catalogue distant (`McpServerRef.catalog`
+est renseigné) ?
+
+| `allowUnknownServers` | constat | score | fatal |
+|---|---|---|---|
+| `false` (fail-closed) | `SERVER_UNDECLARED`, high | 0 | oui |
+| `true` | `SERVER_UNDECLARED`, info | 1 | non |
+
+Ce réglage signifiait auparavant « n'a pas encore de score de réputation », ce qu'aucun déploiement ne
+pouvait satisfaire : personne n'a jamais fourni d'arêtes de confiance à l'oracle, donc chaque serveur
+revenait non cautionné et `false` les bloquait tous. La provenance de catalogue est un fait que l'hôte
+détient déjà localement, ne demande aucun réseau et ne peut pas provoquer d'interblocage.
+
+## pinning
+
+Compare les définitions actuelles à l'instantané approuvé par l'utilisateur. L'empreinte est un sha256
+sur la forme canonique RFC 8785 du jeu de définitions — la même canonicalisation que la signature du
+feed, pas une seconde sérialisation.
+
+| Situation | Code | Sévérité | Score | Fatal |
+|---|---|---|---|---|
+| Pas encore de pin (premier contact) | `TOOL_DEF_UNPINNED` | info | 0.9 | non |
+| L'empreinte diffère du pin | `TOOL_DEF_DRIFT` | high | 0 | avec `pinToolDefs` |
+| Les définitions n'ont pas de forme canonique (sans pin) | `TOOL_DEF_UNCANONICAL` | medium | 0.5 | non |
+| Les définitions n'ont pas de forme canonique (avec pin) | `TOOL_DEF_UNCANONICAL` | high | 0 | avec `pinToolDefs` |
+
+Le premier contact coûte 0,1 et non un blocage : un serveur propre, déclaré et sans pin marque
+exactement **0,9**, et `TOOL_DEF_UNPINNED` est en `info` à dessein — avec `blockAtSeverity: "info"`, un
+premier regard bloquant rendrait tout serveur inutilisable à jamais, puisque rien ne peut être épinglé
+avant d'avoir été approuvé une fois.
+
+`warden.approve(server, tools)` écrit le pin via votre `PinStore`. L'opération est idempotente.
+
+## Partition par outil
+
+`allowedTools` / `blockedTools` répartissent les outils annoncés :
+
+- un outil est **bloqué** si un constat non advisory le nomme (`finding.tool`) et atteint le seuil ;
+- tous les autres outils sont autorisés ;
+- les outils sensibles (`policy.sensitiveToolPatterns`) restent *autorisés* : ils sont signalés pour que
+  la boucle de votre agent puisse exiger une approbation à chaque appel à l'exécution. Voir
+  `classifyTools` / `isSensitiveTool`.
+
+## Ajouter une porte
+
+`WardenGate` fait trois lignes d'interface, et `new Warden({ gates, policy, log })` prend la chaîne
+directement : vous pouvez insérer la vôtre sans forker.
+
+```ts
+import { Warden, StaticScanGate, ThreatGate, OriginGate, PinningGate } from "@aimarket/warden";
+import type { WardenGate, WardenGateInput, WardenGateResult } from "@aimarket/warden";
+
+class DenyByPublisher implements WardenGate {
+  readonly name = "publisher-allowlist";
+  async evaluate(input: WardenGateInput): Promise<WardenGateResult> {
+    const ok = ALLOWED.has(input.server.name);
+    return ok
+      ? { findings: [], score: 1 }
+      : { findings: [{ gate: this.name, severity: "high", code: "PUBLISHER_UNKNOWN",
+                       message: `${input.server.name} n'est pas un éditeur autorisé` }],
+          score: 0, fatal: true };
+  }
+}
+
+const warden = new Warden({
+  gates: [new StaticScanGate(), new ThreatGate(feed), new DenyByPublisher(), new OriginGate(), new PinningGate(store)],
+  policy,
+});
+```
+
+Deux règles pour une porte que vous écrivez : **ne prétendez jamais qu'un service distant est
+injoignable si vous n'avez pas réellement envoyé de requête** (`test/no-phantom-gate.test.ts` l'impose
+sur les portes livrées), et renvoyez un score que vous pouvez défendre — une porte qui n'a rien mesuré
+doit renvoyer `1`, pas un 0,6 « neutre », sinon elle taxe chaque serveur pour une mesure qu'elle n'a
+jamais prise.
+
+## Les portes en mode wrap
+
+`vetLaunch` précède le lancement. `initialize.instructions` passe par static-scan et est retiré en cas de blocage. `tools/list` collecte au plus 32 pages, 256 outils uniques et 1 MiB avant `vet` ; les définitions autorisées sont exposées en une page. `list_changed` déclenche immédiatement la quarantaine et n’est transmis qu’après vérification réussie. Chaque appel relit la liste et compare avec la définition montrée au client. Une modification pendant la vérification bloque l’envoi ; pendant l’exécution, elle retient la réponse. Les messages transparents sont limités à 32 MiB. Les requêtes internes expirent après 10 secondes. EOF ferme stdin de l’enfant, SIGTERM arrive après 5 secondes puis SIGKILL avant 10. Les requêtes du serveur et les autres messages gardent leurs ID et leur JSON original. Voir README pour politique, TOFU, révision humaine et audit-only.