@aimarket/warden 0.7.0 → 0.8.1

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.

package/docs/gates.ru.md

@@ -0,0 +1,225 @@
+# Цепочка гейтов
+
+> 🌐 [English](gates.md) · **Русский** · [Español](gates.es.md) · [Français](gates.fr.md) · [中文](gates.zh.md)
+
+> [Изменения безопасности 0.7.0 и миграция](security-hardening.ru.md).
+
+`Warden.vet(server, tools)` прогоняет упорядоченную цепочку и возвращает один вердикт. Эта страница —
+вся процедура принятия решения: на что смотрит каждый гейт, что он может заблокировать и как
+складывается итоговое число.
+
+```
+static-scan  →  threat-feed  →  origin  →  pinning
+ (бесплатно)     (бесплатно      (бесплатно) (бесплатно)
+                  после load)
+```
+
+Порядок — от самого дешёвого и самого локального. Ни один гейт в цепочке не делает сетевых запросов:
+единственная загрузка, которую WARDEN вообще выполняет, — это `ThreatFeed.load(url)`, и её вызываете
+вы сами, до проверки.
+
+## Как собирается вердикт
+
+Каждый гейт возвращает `{ findings, score, fatal? }`. Цепочка:
+
+1. прогоняет все гейты по порядку, накапливая находки (каждый гейт видит `prior`);
+2. перемножает оценки гейтов — composite score это **произведение**, поэтому один плохой гейт тянет
+   сервер вниз, а не усредняется тремя хорошими;
+3. блокирует, если какой-то гейт вернул `fatal` или если какая-то не-advisory находка достигает
+   `policy.blockAtSeverity`;
+4. обрывает цепочку **только** на явном `fatal`. Блокирующая, но не фатальная находка позволяет
+   остальным гейтам отчитаться, чтобы запись о том, *почему*, осталась полной.
+
+```ts
+const SEVERITY_RANK = { info: 0, low: 1, medium: 2, high: 3, critical: 4 };
+```
+
+Если `policy.blockAtSeverity` не один из этих пяти ключей, конструктор пишет предупреждение и
+откатывается на `"high"`. Опечатка здесь раньше была худшим из возможных отказов: `rank >= undefined`
+ложно при любом сравнении, поэтому неправильно написанный порог молча отключал блокировку целиком.
+
+### Две оси: severity и tier
+
+Severity отвечает на вопрос *сколько внимания это заслуживает*. **Tier** отвечает на вопрос *дефект
+ли это вообще* — и он является данными на находке (`advisory: true`), а не следствием severity.
+
+Находка с `advisory` сообщается, никогда не блокирует и никогда не стоит инструмента — при **любом**
+`blockAtSeverity`. Инструмент, чья схема принимает `api_key`, стоит того, чтобы на него указали, и не
+является дефектом; выражение этого через понижение severity снова делало бы его блокирующим для всех,
+кто ужесточил порог.
+
+## static-scan
+
+Локальное regex-сканирование `name`, `description` и `inputSchema` каждого инструмента. 26 правил в
+наборе **v7**: 15 `block`, 11 `advise`, и у 15 из них есть контекстный **guard** — именованная
+проверка, решающая, действительно ли совпадение — то, что правило ищет. См.
+[полевой обзор](mcp-survey.ru.md) — прогон по 1 108 серверам, на котором калибровался v4.
+
+**v5: текст приводится к обычному виду до того, как его читает любое правило.** NFKC превращает
+широкие буквы, лигатуры и другие совместимые формы в обычные; невидимые символы внутри слова
+выбрасываются; блок Unicode-тегов (невидимые копии ASCII, в которых можно спрятать целое предложение)
+расшифровывается; внутри слова, где латиница смешана с кириллицей или греческим, буквы-двойники
+заменяются латинскими, а слово целиком на одном алфавите не трогается. Английское правило больше не
+обходится широкими буквами, пробелом нулевой ширины, тегами или кириллической `о` — на каком бы языке
+ни был окружающий текст. Идентификатор свёртки публикуется как `fold` и входит в дайджест. Два правила
+скрытых нагрузок читают **сырой** текст (`raw: true`): они ищут именно то, что свёртка убирает.
+
+Смысл регэксп-таблица не читает: формулировка на языке, для которого правила не написаны, вне её.
+v5 добавляет то, что от языка не зависит: свёртку, пару `TOOL_DEF_SECRET_EXFIL` (хранилище секретов и
+внешний адрес в пределах 100 символов; только уведомляет — её единственное срабатывание на 10 645
+живых серверах оказалось честным), блок тегов и изоляты направления в `TOOL_DEF_HIDDEN_UNICODE`, а
+HISTOR показывает каждый внешний адрес, впервые появившийся в определениях сервера. Распознавание по
+смыслу — задача классификатора, а не этой таблицы.
+
+Ещё v5 убирает три измеренных ложных срабатывания: «send the user to https://…» (переход человека,
+guard `navigation`), «keep calling … without asking the user» (самостоятельная работа, guard
+`autonomy`) и соединитель нулевой ширины внутри эмодзи. На корпусе из 10 645 серверов v5 блокирует 56
+там, где v4 блокировал 63, и не блокирует ни одного, которого не блокировал v4.
+
+**v7** убирает три ложных срабатывания, которые ruleset v6 ещё давал на закоммиченном корпусе
+2026-10-01 ([полевое обследование](mcp-survey.ru.md)). «Private key/value memory» — хранилище
+ключ-значение, а не закрытый ключ (guard `keyValue`: составное слово через косую черту или дефис и
+следом слово-хранилище). «Find … without asking the user for ids» — инструмент сам находит
+идентификатор (guard `autonomy` теперь принимает и глагол поиска, если весь объект просьбы —
+идентификатор). «The key is read from the MCP connection's X-API-Key header» — сервер описывает
+собственную аутентификацию (guard `ownAuthHeader`: пассив «is read from», заголовок запроса, не чужой,
+ключ никуда не передаётся дальше). Кроме того, `autonomy` больше не освобождает «without asking the
+user», если объект — согласие: «keep retrying the transfer without asking the user for approval» снова
+блокируется. На этом корпусе v7 блокирует 3 сервера там, где v6 блокировал 6, остальные находки не
+меняются.
+
+Каждое правило объявляет, на каких из этих трёх **поверхностей** оно работает; 17 из 26 включают
+имя. Четыре, которые не включают, — это правила, завязанные на существительное
+(`TOOL_DEF_SECRET_REQUEST`, `TOOL_DEF_CREDENTIAL_PARAM`, `TOOL_DEF_ENV_REFERENCE`, `TOOL_DEF_SECRET_EXFIL`): имя — это
+идентификатор, `api_key` и `private_key` — его обычные части, и блокировать
+`sign_with_private_key` означало бы повторить ошибку калибровки v1 на новой поверхности. Правила,
+завязанные на фразу, требуют пробелов и потому не могут совпасть с `snake_case` вовсе, а два
+правила о скрытой нагрузке — про символы, которые в имени не легитимны никогда: эти работают везде.
+
+До v3 имя не сканировалось **ничем** — то есть инъекционная фраза, zero-width символ или
+base64-блоб в первом поле, которое читает модель, не попадали в отчёт совсем.
+
+Оценка гейта — `1 − штраф(худшая блокирующая severity)`; advisory-срабатывания на неё не влияют.
+
+| худшая блокирующая severity | нет | info | low | medium | high | critical |
+|---|---|---|---|---|---|---|
+| оценка гейта | 1 | 1 | 0.9 | 0.7 | 0.4 | 0 |
+
+| Код | Severity | Tier | Имя? | Что ловит |
+|---|---|---|---|---|
+| `TOOL_DEF_INJECTION` | critical / high | block | ✅ | «ignore all previous instructions», «do not tell the user», теги `<system>`, ссылки на developer prompt |
+| `TOOL_DEF_SECRET_REQUEST` | critical | block | — | `private_key`, `seed_phrase`/`mnemonic`, пути `~/.ssh` |
+| `TOOL_DEF_SECRET_HARVEST` | critical | block | ✅ | инструмент, чья заявленная задача — читать/выгружать/раскрывать секреты |
+| `TOOL_DEF_EXFIL` | critical / high | block | ✅ | «post to https://…», «forward it to…», «exfiltrate», формулировки про upload на хост |
+| `TOOL_DEF_HIDDEN_UNICODE` | high | block | ✅ | zero-width и bidi-управляющие символы — текст, которого рецензент не видит |
+| `TOOL_DEF_BASE64_BLOB` | high | block | ✅ | цепочка base64 от 120 символов в имени, описании или схеме |
+| `TOOL_DEF_DATA_URL` | high | block | ✅ | URL вида `data:…;base64,` и `javascript:` |
+| `TOOL_DEF_CREDENTIAL_PARAM` | medium / low | advise | — | схема или описание просит `api_key`, `password`, `secret`, bearer-токены |
+| `TOOL_DEF_ENV_REFERENCE` | medium | advise | — | `.env`, «environment variables» |
+| `TOOL_DEF_IMPERATIVE` | low / info | advise | ✅ | «you must», «instead of» — формулировки в форме промпта, сами по себе ничего не доказывающие |
+
+`staticScanRuleset()` возвращает каждое правило вместе с **исходником регулярки, флагами и поверхностями**, чтобы
+третья сторона могла перезапустить ровно то же правило, плюс `{ version, digest }`, где digest —
+sha256 по канонической форме RFC 8785 отсортированного списка правил. Сортировка — сравнением
+code-unit, никогда не `localeCompare`: зависящая от локали коллация давала бы для одной и той же
+таблицы разный digest на по-разному настроенном хосте, а это ровно то расхождение, для обнаружения
+которого digest и существует.
+
+## threat-feed
+
+Сопоставляет идентичность сервера и определения инструментов с записями `ThreatRecord` — 11
+встроенных плюс то, что добавил подписанный feed (см. [контракт feed](threat-feed.ru.md)).
+
+- Любое совпадение ⇒ оценка гейта **0**.
+- `fatal` **только** для записи `critical`, совпавшей с *сервером*. Критическое совпадение на одном
+  *инструменте* не фатально: остальная цепочка всё равно отчитывается, а вина остаётся привязанной к
+  этому инструменту — именно это позволяет в основном нормальному серверу продолжать работать с одним
+  изолированным инструментом.
+- `ThreatRecord.scope` выбирает поверхность: `server` (id/name/url/command/args), `tool`
+  (name/description/inputSchema) или `any` — значение по умолчанию, когда запись его не указывает.
+
+Встроенные коды: `THREAT_TYPOSQUAT`, `THREAT_CRYPTO_DRAINER`, `THREAT_SEED_PHRASE`,
+`THREAT_SSH_KEY_READ`, `THREAT_ENV_EXFIL`, `THREAT_DESTRUCTIVE_CMD`, `THREAT_FORK_BOMB`.
+
+## origin
+
+Объявил ли оператор этот сервер, или он пришёл из удалённого каталога (заполнено
+`McpServerRef.catalog`)?
+
+| `allowUnknownServers` | находка | оценка | fatal |
+|---|---|---|---|
+| `false` (fail-closed) | `SERVER_UNDECLARED`, high | 0 | да |
+| `true` | `SERVER_UNDECLARED`, info | 1 | нет |
+
+Раньше этот переключатель означал «ещё нет оценки репутации», чего не могло выполнить ни одно
+развёртывание: оракулу никто никогда не передавал trust-рёбра, поэтому каждый сервер возвращался
+непоручённым, и `false` блокировал их все. Происхождение из каталога — факт, которым хост уже
+располагает локально, он не требует сети и не может привести к дедлоку.
+
+## pinning
+
+Сравнивает текущие определения инструментов со снимком, который подтвердил пользователь. Хеш — sha256
+по канонической форме RFC 8785 набора определений; та же канонизация, что у подписи feed, а не вторая
+сериализация.
+
+| Ситуация | Код | Severity | Оценка | Fatal |
+|---|---|---|---|---|
+| Pin ещё нет (первый контакт) | `TOOL_DEF_UNPINNED` | info | 0.9 | нет |
+| Хеш отличается от pin | `TOOL_DEF_DRIFT` | high | 0 | при `pinToolDefs` |
+| У определений нет канонической формы (без pin) | `TOOL_DEF_UNCANONICAL` | medium | 0.5 | нет |
+| У определений нет канонической формы (с pin) | `TOOL_DEF_UNCANONICAL` | high | 0 | при `pinToolDefs` |
+
+Первый контакт стоит 0.1, а не блокировки: чистый объявленный сервер без pin получает ровно **0.9**, а
+`TOOL_DEF_UNPINNED` имеет severity `info` намеренно — при `blockAtSeverity: "info"` блокирующий первый
+взгляд сделал бы любой сервер навсегда непригодным, ведь ничего нельзя зафиксировать до того, как это
+хоть раз подтвердили.
+
+`warden.approve(server, tools)` записывает pin через ваш `PinStore`. Операция идемпотентна.
+
+## Разбиение по инструментам
+
+`allowedTools` / `blockedTools` делят объявленные инструменты:
+
+- инструмент **заблокирован**, если не-advisory находка называет его (`finding.tool`) и достигает
+  порога;
+- все остальные инструменты разрешены;
+- чувствительные инструменты (`policy.sensitiveToolPatterns`) остаются *разрешёнными* — они помечены,
+  чтобы цикл вашего агента мог требовать подтверждение на каждый вызов во время работы. См.
+  `classifyTools` / `isSensitiveTool`.
+
+## Как добавить свой гейт
+
+`WardenGate` — интерфейс из трёх строк, а `new Warden({ gates, policy, log })` принимает цепочку
+напрямую, поэтому свой гейт можно вставить без форка:
+
+```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} не входит в список разрешённых издателей` }],
+          score: 0, fatal: true };
+  }
+}
+
+const warden = new Warden({
+  gates: [new StaticScanGate(), new ThreatGate(feed), new DenyByPublisher(), new OriginGate(), new PinningGate(store)],
+  policy,
+});
+```
+
+Два правила для гейта, который вы пишете сами: **никогда не заявляйте, что удалённый сервис
+недоступен, если вы действительно не отправили запрос** (`test/no-phantom-gate.test.ts` следит за этим
+на поставляемых гейтах) и возвращайте оценку, которую можете защитить — гейт, который ничего не
+измерил, должен вернуть `1`, а не «нейтральные» 0.6, иначе он штрафует каждый сервер за измерение,
+которого не проводил.
+
+## Гейты в режиме wrap
+
+`vetLaunch` вызывается до запуска процесса. `initialize.instructions` проходит существующий static-scan и удаляется при блокирующей находке. `tools/list` собирает не более 32 страниц, 256 уникальных инструментов и 1 MiB, затем вызывает `vet`; клиент получает проверенные определения одной страницей. `list_changed` немедленно включает карантин; уведомление уходит клиенту только после успешной проверки. Перед каждым вызовом список перечитывается, а определение сравнивается с последним показанным клиенту. Изменение во время проверки запрещает отправку; во время выполнения скрывает ответ. Сквозные сообщения ограничены отдельно — 32 MiB. Таймаут внутреннего запроса списка — 10 секунд. При EOF закрывается stdin дочернего, через 5 секунд отправляется SIGTERM, перед истечением 10 секунд — SIGKILL. Встречные запросы и прочие сообщения сохраняют ID и исходный JSON. Политика, TOFU, ручное одобрение и ограничения audit-only описаны в README.

package/docs/gates.zh.md

@@ -0,0 +1,178 @@
+# 门控链
+
+> 🌐 [English](gates.md) · [Русский](gates.ru.md) · [Español](gates.es.md) · [Français](gates.fr.md) · **中文**
+
+> [0.7.0 安全更新与迁移](security-hardening.zh.md).
+
+`Warden.vet(server, tools)` 会按顺序跑完一条门控链，并返回单一裁定。本页就是完整的判定过程：每个门控看什么、
+它可以阻止什么，以及最后那个数字是怎么算出来的。
+
+```
+static-scan  →  threat-feed  →  origin  →  pinning
+ （免费）        （load 之后     （免费）    （免费）
+                  免费）
+```
+
+顺序是「最便宜、最本地的先来」。链上没有任何环节发起网络请求——WARDEN 唯一会发出的下载是
+`ThreatFeed.load(url)`，而那是你自己在审查之前调用的。
+
+## 裁定是怎么拼出来的
+
+每个门控返回 `{ findings, score, fatal? }`。整条链：
+
+1. 按顺序运行每个门控，累积发现（每个门控都能看到 `prior`）；
+2. 把各门控的评分**相乘**——综合评分是乘积，所以一个坏门控会把整台服务器拉下来，而不是被三个好门控平均掉；
+3. 若任一门控返回 `fatal`，或任一非 advisory 的发现达到 `policy.blockAtSeverity`，则阻止；
+4. **只有**遇到显式 `fatal` 才短路。会阻止但不 fatal 的发现仍让后续门控继续报告，这样「为什么」的记录才完整。
+
+```ts
+const SEVERITY_RANK = { info: 0, low: 1, medium: 2, high: 3, critical: 4 };
+```
+
+如果 `policy.blockAtSeverity` 不是这五个键之一，构造函数会写一条警告并回退到 `"high"`。这里的一个拼写错误
+曾是最糟糕的故障模式：`rank >= undefined` 在任何比较中都为 `false`，于是一个拼错的阈值会悄无声息地把阻止功能
+整个关掉。
+
+### 两个维度：严重级别与层级
+
+严重级别回答的是*这值得多少注意*。**层级**（tier）回答的是*这到底算不算缺陷*——而它是发现上的一项数据
+（`advisory: true`），不是严重级别的推论。
+
+带 `advisory` 的发现会被报告，但在**任何** `blockAtSeverity` 下都不会阻止连接、也不会牺牲任何工具。一个 schema
+里接受 `api_key` 的工具值得被指出来，但它不是缺陷；用「降低严重级别」来表达这一点，会让它对任何收紧阈值的人重新
+变成阻止性的。
+
+## static-scan
+
+对每个工具的 `name`、`description` 与 `inputSchema` 做本地正则扫描。规则集 **v7** 共 26 条规则（其中 15 条带有上下文 **guard**——一项具名检查，用于判断某次命中是否真是该规则要找的东西；参见[实地普查](mcp-survey.zh.md)，即校准 v4 的 1 108 台服务器实测）：
+15 条 `block`，11 条 `advise`。
+
+**v5：任何规则读取文本之前，先对文本做归一化。** NFKC 把全角字母、连字和其他兼容形式变成普通字母；单词内部的不可见字符被删除；Unicode 标签区块（ASCII 的不可见副本，能藏下一整句话）被解码；在拉丁字母与西里尔或希腊字母混写的单词里，形近字母被换成拉丁字母，而整词只用一种文字写成的单词保持不变。于是，无论周围文本是什么语言，英文规则都不能再被全角字母、词内零宽空格、标签字符或西里尔字母 `о` 绕过。归一化以 `fold` 的形式与规则一起发布，并计入 digest。两条隐藏载荷规则读取**原始**文本（`raw: true`）。
+
+正则表格读不懂含义：用规则没有覆盖的语言写成的说法不在它的范围内。v5 增加了与语言无关的部分：归一化；`TOOL_DEF_SECRET_EXFIL` 组合（机密存放位置与外部地址相距不超过 100 个字符；仅提示，因为它在 10 645 台真实服务器上唯一的命中是正当用途）；`TOOL_DEF_HIDDEN_UNICODE` 纳入标签区块和双向隔离符；HISTOR 会标出服务器定义中新出现的任何外部地址。按含义识别属于分类器的工作，而不是这张表的工作。
+
+v5 还消除了三类实测误报：“send the user to https://…”（引导用户跳转，guard `navigation`）、“keep calling … without asking the user”（自主运行，guard `autonomy`），以及表情符号序列中的零宽连接符。在 10 645 台服务器的语料上，v4 阻止 63 台，v5 阻止 56 台，且没有新增任何 v4 未阻止的服务器。
+
+**v7** 消除了规则集 v6 在已提交的 2026-10-01 语料上仍有的三处误报（[实地普查](mcp-survey.zh.md)）。“Private key/value memory” 指键值存储，而非私钥（guard `keyValue`：以斜杠或连字符构成的复合词，后接表示存储的名词）。“Find … without asking the user for ids” 是工具自行解析标识符（guard `autonomy` 现在也接受查找类动词，前提是被索要的对象整体就是标识符）。“The key is read from the MCP connection's X-API-Key header” 是服务器在描述自己的认证方式（guard `ownAuthHeader`：被动语态 “is read from”、来源是请求头、不是他人的请求头、密钥未被转交他处）。此外，当 “without asking the user” 的对象是“同意”时，`autonomy` 不再豁免：“keep retrying the transfer without asking the user for approval” 重新被阻止。在该语料上，v6 阻止 6 台服务器，v7 阻止 3 台，其余所有发现均不变。
+
+每条规则都声明自己在这三个**面**中的哪些上运行，26 条里有 17 条包含名称。不包含名称的那四条是以**名词**为
+锚的规则（`TOOL_DEF_SECRET_REQUEST`、`TOOL_DEF_CREDENTIAL_PARAM`、`TOOL_DEF_ENV_REFERENCE`、`TOOL_DEF_SECRET_EXFIL`）：名称是标识
+符，`api_key` 和 `private_key` 是标识符里再普通不过的组成部分，而拒绝 `sign_with_private_key` 等于把 v1 的
+校准错误换个面重犯一次。以**短语**为锚的规则需要空白字符，因此根本无法匹配 `snake_case`；而两条隐藏载荷规则
+针对的字符在名称里从来都不合法——这些都在所有面上运行。
+
+在 v3 之前，名称**根本没有被任何规则扫描过**：注入短语、零宽字符或 base64 串出现在模型最先读到的那个字段里，
+完全不会被报告。
+
+门控评分为 `1 − 惩罚(最严重的阻止性 severity)`；advisory 命中永远不影响它。
+
+| 最严重的阻止性 severity | 无 | info | low | medium | high | critical |
+|---|---|---|---|---|---|---|
+| 门控评分 | 1 | 1 | 0.9 | 0.7 | 0.4 | 0 |
+
+| 代码 | 严重级别 | 层级 | 名称？ | 捕捉什么 |
+|---|---|---|---|---|
+| `TOOL_DEF_INJECTION` | critical / high | block | ✅ | 「ignore all previous instructions」「do not tell the user」、`<system>` 标签、对 developer prompt 的引用 |
+| `TOOL_DEF_SECRET_REQUEST` | critical | block | — | `private_key`、`seed_phrase`/`mnemonic`、`~/.ssh` 路径 |
+| `TOOL_DEF_SECRET_HARVEST` | critical | block | ✅ | 自称职责就是读取/导出/披露密钥的工具 |
+| `TOOL_DEF_EXFIL` | critical / high | block | ✅ | 「post to https://…」「forward it to…」「exfiltrate」、上传到某主机的措辞 |
+| `TOOL_DEF_HIDDEN_UNICODE` | high | block | ✅ | 零宽字符与双向控制字符——审阅者看不见的文本 |
+| `TOOL_DEF_BASE64_BLOB` | high | block | ✅ | 名称、描述或 schema 里长达 120+ 字符的 base64 串 |
+| `TOOL_DEF_DATA_URL` | high | block | ✅ | `data:…;base64,` 与 `javascript:` 形式的 URL |
+| `TOOL_DEF_CREDENTIAL_PARAM` | medium / low | advise | — | schema 或描述索要 `api_key`、`password`、`secret`、bearer 令牌 |
+| `TOOL_DEF_ENV_REFERENCE` | medium | advise | — | `.env`、「environment variables」 |
+| `TOOL_DEF_IMPERATIVE` | low / info | advise | ✅ | 「you must」「instead of」——提示词形态的措辞，单独并不能证明任何事 |
+
+`staticScanRuleset()` 会连同**正则源码、flags 与所扫描的面** 一起返回每条规则，好让第三方能重跑一模一样的规则；同时返回
+`{ version, digest }`，其中 digest 是对已排序规则列表的 RFC 8785 规范化形式做的 sha256。排序按 code-unit 比较，
+绝不用 `localeCompare`：依赖 locale 的排序会让同一张规则表在配置不同的主机上算出不同的摘要，而这正是摘要本身
+要检测的分歧。
+
+## threat-feed
+
+把服务器身份和工具定义与 `ThreatRecord` 比对——11 条内置，加上已签名 feed 追加的内容（见
+[feed 契约](threat-feed.zh.md)）。
+
+- 任何命中 ⇒ 门控评分 **0**。
+- **只有**当 `critical` 记录命中*服务器*时才 `fatal`。命中某个*工具*的 critical 不是 fatal，于是链上其余门控
+  仍会报告，责任也仍限定在那个工具上——这正是让一台大体正常的服务器在隔离掉一个工具后继续可用的原因。
+- `ThreatRecord.scope` 选择比对面：`server`（id/name/url/command/args）、`tool`
+  （name/description/inputSchema），或 `any`——记录省略该字段时的默认值。
+
+内置代码：`THREAT_TYPOSQUAT`、`THREAT_CRYPTO_DRAINER`、`THREAT_SEED_PHRASE`、`THREAT_SSH_KEY_READ`、
+`THREAT_ENV_EXFIL`、`THREAT_DESTRUCTIVE_CMD`、`THREAT_FORK_BOMB`。
+
+## origin
+
+这台服务器是运营者声明过的，还是来自远端目录（`McpServerRef.catalog` 有值）？
+
+| `allowUnknownServers` | 发现 | 评分 | fatal |
+|---|---|---|---|
+| `false`（失败即关闭） | `SERVER_UNDECLARED`，high | 0 | 是 |
+| `true` | `SERVER_UNDECLARED`，info | 1 | 否 |
+
+这个开关过去的含义是「还没有信誉评分」，而没有任何部署能满足它：从来没有人给预言机提供过信任边，于是每台服务器
+回来都是「无人担保」，`false` 就把它们全都拦住了。而「来自目录」是宿主本地已经掌握的事实，不需要网络，也不可能
+死锁。
+
+## pinning
+
+把当前的工具定义与用户批准过的快照做比较。哈希是对定义集合的 RFC 8785 规范化形式做的 sha256——与 feed 签名用的是
+同一套规范化，而不是第二种序列化。
+
+| 情形 | 代码 | 严重级别 | 评分 | Fatal |
+|---|---|---|---|---|
+| 尚无 pin（首次接触） | `TOOL_DEF_UNPINNED` | info | 0.9 | 否 |
+| 哈希与 pin 不一致 | `TOOL_DEF_DRIFT` | high | 0 | 当 `pinToolDefs` |
+| 工具定义没有规范形式（无 pin） | `TOOL_DEF_UNCANONICAL` | medium | 0.5 | 否 |
+| 工具定义没有规范形式（有 pin） | `TOOL_DEF_UNCANONICAL` | high | 0 | 当 `pinToolDefs` |
+
+首次接触的代价是 0.1，而不是阻止：一台干净、已声明、尚无 pin 的服务器恰好得 **0.9**，而 `TOOL_DEF_UNPINNED`
+被刻意定为 `info`——在 `blockAtSeverity: "info"` 下，若首次相见就阻止，那么任何服务器都将永远不可用，因为在被
+批准过一次之前，什么都无法固定。
+
+`warden.approve(server, tools)` 通过你的 `PinStore` 写入 pin。该操作是幂等的。
+
+## 按工具划分
+
+`allowedTools` / `blockedTools` 把已公布的工具分成两部分：
+
+- 若某条非 advisory 的发现点名了某个工具（`finding.tool`）并达到阈值，则该工具**被阻止**；
+- 其余工具全部允许；
+- 敏感工具（`policy.sensitiveToolPatterns`）仍然是*被允许的*——它们只是被标记出来，好让你的智能体主循环在运行时
+  对每次调用要求审批。参见 `classifyTools` / `isSensitiveTool`。
+
+## 新增一个门控
+
+`WardenGate` 只是三行接口，而 `new Warden({ gates, policy, log })` 直接接受整条链，所以你可以插入自己的门控而
+不必 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} 不在允许的发布者名单中` }],
+          score: 0, fatal: true };
+  }
+}
+
+const warden = new Warden({
+  gates: [new StaticScanGate(), new ThreatGate(feed), new DenyByPublisher(), new OriginGate(), new PinningGate(store)],
+  policy,
+});
+```
+
+自己写门控时有两条规矩：**没有真的发出请求，就绝不宣称远端服务不可达**
+（`test/no-phantom-gate.test.ts` 会对随包发布的门控强制这一点）；以及返回一个你能站得住脚的评分——什么都没测量的
+门控必须返回 `1`，而不是一个「中性」的 0.6，否则它就是在为一次从未做过的测量惩罚每一台服务器。
+
+## wrap 模式的检查流程
+
+启动子进程前调用 `vetLaunch`。`initialize.instructions` 使用现有 static-scan，遇到阻止判定时删除。`tools/list` 最多读取 32 页、256 个唯一工具及 1 MiB，然后调用 `vet`；允许的定义以单页返回。`list_changed` 立即隔离服务器，只有重新检查成功才转发。每次调用前重新读取列表，与客户端最后看到的定义比较。检查期间变更阻止发送；执行期间变更则隐藏响应。透传消息另有 32 MiB 上限，内部请求超时为 10 秒。EOF 关闭子进程 stdin，5 秒后 SIGTERM，10 秒前 SIGKILL。服务器反向请求及其他消息保留 ID 和原始 JSON。策略、TOFU、人工审批及 audit-only 限制参见 README。