@aimarket/warden 0.6.0 → 0.8.0

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.

package/docs/gates.md

@@ -0,0 +1,219 @@
+# The gate chain
+
+> 🌐 **English** · [Русский](gates.ru.md) · [Español](gates.es.md) · [Français](gates.fr.md) · [中文](gates.zh.md)
+
+> [0.7.0 security changes and migration](security-hardening.md).
+
+`Warden.vet(server, tools)` runs an ordered chain and returns one verdict. This page is the whole
+decision procedure: what each gate looks at, what it may block, and how the number at the end is
+built.
+
+```
+static-scan  →  threat-feed  →  origin  →  pinning
+ (free)         (free after     (free)      (free)
+                 load)
+```
+
+The order is cheapest-and-most-local first. Nothing in the chain performs a network request — the
+only fetch WARDEN ever makes is `ThreatFeed.load(url)`, which you call yourself, before vetting.
+
+## How a verdict is assembled
+
+Each gate returns `{ findings, score, fatal? }`. The chain:
+
+1. runs every gate in order, accumulating findings (each gate sees `prior`);
+2. multiplies the gate scores — the composite is a **product**, so one bad gate drags the server down
+   instead of being averaged away by three good ones;
+3. blocks if any gate returned `fatal`, or if any non-advisory finding reaches
+   `policy.blockAtSeverity`;
+4. short-circuits **only** on an explicit `fatal`. A blocking-but-not-fatal finding still lets the
+   remaining gates report, so the record of *why* stays complete.
+
+```ts
+const SEVERITY_RANK = { info: 0, low: 1, medium: 2, high: 3, critical: 4 };
+```
+
+If `policy.blockAtSeverity` is not one of those five keys, the constructor logs a warning and falls
+back to `"high"`. A typo there used to be the worst possible failure: `rank >= undefined` is `false`
+for every comparison, so a misspelled threshold silently disabled blocking altogether.
+
+### Two axes: severity and tier
+
+Severity answers *how much attention does this deserve*. The **tier** answers *is this a defect at
+all* — and it is data on the finding (`advisory: true`), not a consequence of severity.
+
+An `advisory` finding is reported, never blocks, and never costs a tool, at **any**
+`blockAtSeverity`. A tool whose schema takes an `api_key` is worth pointing at and is not a defect;
+expressing that by lowering its severity would have made it blocking again for anyone who tightened
+the threshold.
+
+## static-scan
+
+Local regex scan over each tool's `name`, its `description` and its `inputSchema`. 26 rules in
+ruleset **v7**: 15 `block`, 11 `advise`, and 15 of them carry a context **guard** — a named
+check that decides whether a match is really the thing the rule is looking for. See
+[the field survey](mcp-survey.md) for the 1 108-server run that calibrated v4.
+
+**v5: the text is folded before any rule reads it.** NFKC maps fullwidth letters, ligatures and
+other compatibility forms to plain ones; invisible characters inside a word are dropped; the Unicode
+TAG block (invisible copies of ASCII that can carry a whole sentence) is decoded to the ASCII it
+hides; and inside a word that mixes Latin with Cyrillic or Greek, look-alike letters are mapped to
+Latin — a word written wholly in one script is left alone. A rule written in English therefore cannot
+be dodged by `ｉｇｎｏｒｅ`, a zero-width space inside the word, tag characters, or a Cyrillic `о`, in any
+language the surrounding text is written in. The fold is published as `fold` beside the rules and is
+part of the digest. The two hidden-payload rules read the **raw** text (`raw: true`), because they
+look for exactly what the fold removes.
+
+What a regex table cannot do is read meaning: a phrasing in a language the rules were not written in
+is outside it. v5 adds what does not depend on the language — the fold above, the
+`TOOL_DEF_SECRET_EXFIL` pair (a secret store and an external address within 100 characters of each
+other, advisory because its only hit on 10 645 live servers was honest), the Unicode-tag block and
+bidi isolates in `TOOL_DEF_HIDDEN_UNICODE` — and HISTOR reports any outside address that newly
+appears in a server's definitions. Meaning-based detection belongs to a classifier, not to this table.
+
+v5 also removes three measured false positives: "send the user to https://…" (a redirect of a
+person, guard `navigation`), "keep calling … without asking the user" (autonomy, guard `autonomy`),
+and a zero-width joiner inside an emoji sequence. On the 10 645-server corpus v5 blocks 56 servers
+where v4 blocked 63, and blocks none that v4 did not.
+
+**v7** removes three false positives that ruleset v6 still had on the committed 2026-10-01 corpus
+([the field survey](mcp-survey.md)). "Private key/value memory" names a key-value store, not a
+private key (guard `keyValue`: a slash or hyphen compound followed by a store noun). "Find … without
+asking the user for ids" is a tool resolving an identifier itself (guard `autonomy`, which now also
+accepts a lookup verb with an identifier as the whole object). "The key is read from the MCP
+connection's X-API-Key header" is a server describing its own authentication (guard
+`ownAuthHeader`: passive "is read from", a request header, nobody else's, nothing moved onward).
+`autonomy` also no longer exempts a "without asking the user" whose object is consent: "keep
+retrying the transfer without asking the user for approval" blocks again. On that corpus v7 blocks 3
+servers where v6 blocked 6, and every other finding is unchanged.
+
+Every rule declares which of those three **surfaces** it runs on, and 17 of the 26 include the name.
+The four that do not are the noun-keyed ones (`TOOL_DEF_SECRET_REQUEST`,
+`TOOL_DEF_CREDENTIAL_PARAM`, `TOOL_DEF_ENV_REFERENCE`, `TOOL_DEF_SECRET_EXFIL`): a name is an identifier, `api_key` and
+`private_key` are ordinary parts of one, and refusing `sign_with_private_key` would be the ruleset
+v1 calibration error committed on a new surface. Phrase-keyed rules need whitespace and so cannot
+match `snake_case` at all, and the two hidden-payload rules are about characters that are never
+legitimate in a name — those run everywhere.
+
+Until v3 the name was scanned by **nothing**, which meant an injection phrase, a zero-width
+character or a base64 blob in the first field the model reads went entirely unreported.
+
+Gate score is `1 − penalty(worst blocking severity)`; advisory hits never affect it.
+
+| worst blocking severity | none | info | low | medium | high | critical |
+|---|---|---|---|---|---|---|
+| gate score | 1 | 1 | 0.9 | 0.7 | 0.4 | 0 |
+
+| Code | Severity | Tier | Name? | What it catches |
+|---|---|---|---|---|
+| `TOOL_DEF_INJECTION` | critical / high | block | ✅ | "ignore all previous instructions", "do not tell the user", `<system>` tags, references to the developer prompt |
+| `TOOL_DEF_SECRET_REQUEST` | critical | block | — | `private_key`, `seed_phrase`/`mnemonic`, `~/.ssh` paths |
+| `TOOL_DEF_SECRET_HARVEST` | critical | block | ✅ | a tool whose stated job is to read/dump/reveal secrets |
+| `TOOL_DEF_EXFIL` | critical / high | block | ✅ | "post to https://…", "forward it to…", "exfiltrate", upload-to-host phrasing |
+| `TOOL_DEF_HIDDEN_UNICODE` | high | block | ✅ | zero-width, bidi control and isolate characters, and the Unicode-tag block — text the reviewer cannot see |
+| `TOOL_DEF_BASE64_BLOB` | high | block | ✅ | a 120+ character base64 run in a name, description or schema |
+| `TOOL_DEF_DATA_URL` | high | block | ✅ | `data:…;base64,` and `javascript:` URLs |
+| `TOOL_DEF_CREDENTIAL_PARAM` | medium / low | advise | — | schema or description asking for `api_key`, `password`, `secret`, bearer tokens |
+| `TOOL_DEF_ENV_REFERENCE` | medium | advise | — | `.env`, "environment variables" |
+| `TOOL_DEF_SECRET_EXFIL` | medium | advise | — | a secret store (`.env`, `~/.ssh/…`, `~/.aws/credentials`) and a URL, e-mail or host within 100 characters — the language-independent shape of "read this, send it there" |
+| `TOOL_DEF_IMPERATIVE` | low / info | advise | ✅ | "you must", "instead of" — prompt-shaped phrasing, not proof of anything |
+
+`staticScanRuleset()` returns every rule with its **regex source, flags, surfaces, guards and `raw` flag**, and
+the `fold` identity, so a third party can re-run the exact rule, plus `{ version, digest }` where the digest is sha256 over the RFC 8785
+canonical form of the sorted rule list. Sorting is by code-unit comparison, never `localeCompare`: a
+locale-dependent collation would make the same table digest differently on a differently-configured
+host, which is exactly the divergence the digest exists to detect.
+
+## threat-feed
+
+Matches server identity and tool definitions against `ThreatRecord`s — 11 built-in plus whatever a
+signed feed added (see [the feed contract](threat-feed.md)).
+
+- Any match ⇒ gate score **0**.
+- `fatal` **only** for a `critical` record matched against the *server*. A critical match on one
+  *tool* is not fatal, so the rest of the chain still reports and the blame stays scoped to that tool
+  — which is what lets a mostly-fine server keep working with one tool quarantined.
+- `ThreatRecord.scope` selects the surface: `server` (id/name/url/command/args), `tool`
+  (name/description/inputSchema), or `any` — the default when a record omits it.
+
+Built-in codes: `THREAT_TYPOSQUAT`, `THREAT_CRYPTO_DRAINER`, `THREAT_SEED_PHRASE`,
+`THREAT_SSH_KEY_READ`, `THREAT_ENV_EXFIL`, `THREAT_DESTRUCTIVE_CMD`, `THREAT_FORK_BOMB`.
+
+## origin
+
+Did the operator declare this server, or did it arrive from a remote catalog (`McpServerRef.catalog`
+is set)?
+
+| `allowUnknownServers` | finding | score | fatal |
+|---|---|---|---|
+| `false` (fail-closed) | `SERVER_UNDECLARED`, high | 0 | yes |
+| `true` | `SERVER_UNDECLARED`, info | 1 | no |
+
+This knob used to mean "has no reputation score yet", which no deployment could satisfy — nothing
+ever supplied trust edges to the oracle, so every server came back unvouched and `false` blocked all
+of them. Catalog provenance is a fact the host already holds locally, needs no network, and cannot
+deadlock.
+
+## pinning
+
+Compares the current tool defs against the snapshot the user approved. The hash is sha256 over the
+RFC 8785 canonical form of the tool-def set — the same canonicalization the feed signature uses, not
+a second serialization.
+
+| Situation | Code | Severity | Score | Fatal |
+|---|---|---|---|---|
+| No pin yet (first contact) | `TOOL_DEF_UNPINNED` | info | 0.9 | no |
+| Hash differs from the pin | `TOOL_DEF_DRIFT` | high | 0 | under `pinToolDefs` |
+| Tool defs have no canonical form (unpinned) | `TOOL_DEF_UNCANONICAL` | medium | 0.5 | no |
+| Tool defs have no canonical form (pinned) | `TOOL_DEF_UNCANONICAL` | high | 0 | under `pinToolDefs` |
+
+First contact costs 0.1, not a block: a clean, declared, unpinned server scores exactly **0.9**, and
+`TOOL_DEF_UNPINNED` is `info` on purpose — at `blockAtSeverity: "info"` a blocking first sight would
+make every server unusable forever, since nothing can be pinned before it is approved once.
+
+`warden.approve(server, tools)` writes the pin through your `PinStore`. It is idempotent.
+
+## Per-tool partition
+
+`allowedTools` / `blockedTools` split the advertised tools:
+
+- a tool is **blocked** if a non-advisory finding names it (`finding.tool`) and reaches the threshold;
+- every other tool is allowed;
+- sensitive tools (`policy.sensitiveToolPatterns`) stay *allowed* — they are flagged so your agent
+  loop can demand per-call approval at run time. See `classifyTools` / `isSensitiveTool`.
+
+## Adding a gate
+
+`WardenGate` is three lines of interface, and `new Warden({ gates, policy, log })` takes the chain
+directly, so you can insert your own without forking:
+
+```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} is not an allowed publisher` }],
+          score: 0, fatal: true };
+  }
+}
+
+const warden = new Warden({
+  gates: [new StaticScanGate(), new ThreatGate(feed), new DenyByPublisher(), new OriginGate(), new PinningGate(store)],
+  policy,
+});
+```
+
+Two rules for a gate you write: **never claim a remote service is unreachable unless you actually
+sent a request** (`test/no-phantom-gate.test.ts` enforces this over the shipped gates), and return a
+score you can defend — a gate that measured nothing must return `1`, not a "neutral" 0.6, or it taxes
+every server for a measurement it never took.
+
+## Wrap and the gates
+
+`vetLaunch` runs before spawn. `initialize.instructions` is scanned with the existing static gate and stripped on a blocking verdict. `tools/list` collects at most 32 pages, 256 unique tools and 1 MiB before `vet`; only allowed definitions are exposed in one page. `list_changed` immediately quarantines the server; notifications are forwarded only after a successful refresh. Every call re-lists and compares the definition with the last list shown to the client. A change during verification rejects dispatch; during execution it withholds the response. Transparent frames have a separate 32 MiB limit. Internal page requests time out after 10 seconds. EOF closes child stdin, sends SIGTERM after 5 seconds and SIGKILL just before 10 seconds. Server-to-client requests and unrelated message bodies retain their IDs and raw JSON. See the README for policy, TOFU, human review and audit-only limitations.