@aimarket/warden 0.0.1 → 0.4.0

package/README-ru.md

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

package/README-zh.md

@@ -0,0 +1,173 @@
+# WARDEN — MCP 安全防火墙
+
+<!-- aicom-readme-badges -->
+<p align="center">
+  <a href="https://github.com/alexar76/warden/actions/workflows/ci.yml"><img src="docs/badges/ci.svg" alt="CI" /></a>
+  <a href="https://www.npmjs.com/package/@aimarket/warden"><img src="https://img.shields.io/npm/v/@aimarket/warden?color=cb3837&label=npm" alt="npm 版本" /></a>
+  <img src="docs/badges/deps.svg" alt="零运行时依赖" />
+  <img src="docs/badges/tests.svg" alt="141 项测试通过" />
+  <img src="docs/badges/node.svg" alt="Node >= 20" />
+  <a href="LICENSE"><img src="docs/badges/license.svg" alt="许可证：MIT" /></a>
+</p>
+<!-- /aicom-readme-badges -->
+
+<p align="center">
+  <img src="docs/assets/hero.svg" alt="WARDEN — MCP security firewall: tool defs pass static-scan, threat-feed, origin, and pinning before a recorded verdict" width="920" />
+</p>
+
+
+> 🌐 [English](README.md) · [Русский](README-ru.md) · [Español](README-es.md) · [Français](README-fr.md) · **中文** · [术语表](https://github.com/alexar76/aicom/blob/main/docs/localization-glossary.md)
+
+MCP 服务器自己告诉你的智能体，它的工具是做什么的。智能体就信了——而这句话正是攻击面。工具描述就是第三方直接
+投递进模型上下文的提示词文本；而一个名叫 `api_key` 的 schema 字段，就是以 API 形式写出来的索要密钥的请求。
+
+WARDEN 在**该服务器的任何工具到达模型之前**审查它，并返回一份可以留档的裁定：允许/阻止、0..1 的评分、导致该
+评分的各项发现、按工具的划分，以及当时生效的确切规则表。
+
+```bash
+npm install @aimarket/warden
+```
+
+**零运行时依赖。** 整个包里唯一的 import 是 `node:crypto`。它就是 [ARGUS](https://github.com/alexar76/argus)
+里的那个防火墙，被单独抽出来，好让你把它放在自己的 MCP 宿主前面，而不必换用一个智能体。
+
+## 快速开始
+
+```ts
+import { Warden, ThreatFeed, silentLogger } from "@aimarket/warden";
+
+const threatFeed = new ThreatFeed({ feedPublicKey: process.env.FEED_PUBKEY });
+await threatFeed.load(process.env.FEED_URL); // 不传 URL → 只用内置拒绝列表，不联网
+
+const pins = new Map();
+const warden = Warden.create({
+  policy: {
+    blockAtSeverity: "high",
+    sensitiveToolPatterns: ["*delete*", "*transfer*", "*key*"],
+    allowUnknownServers: false, // 失败即关闭：只允许你声明过的服务器
+    pinToolDefs: true,
+  },
+  threatFeed,
+  store: {
+    getPin: async (id) => pins.get(id),
+    putPin: async (p) => void pins.set(p.serverId, p),
+  },
+  log: silentLogger(), // 或者你自己的 logger
+});
+
+const verdict = await warden.vet(server, await client.listTools());
+
+if (!verdict.allow) throw new Error(`被 ${verdict.decidedBy} 阻止`);
+const usable = verdict.allowedTools; // 被投毒的工具可以单独隔离
+await warden.approve(server, tools); // 把用户认可的内容固定（pin）下来
+```
+
+`vet()` **不发起任何网络请求**。WARDEN 唯一会发出的请求，是你把 URL 传给 `load()` 时主动要求的威胁情报
+（threat feed）下载。
+
+## 门控链
+
+```mermaid
+flowchart LR
+  T["服务器给出的<br/>工具定义"] --> S["static scan<br/>25 条规则"]
+  S --> F["threat feed<br/>11 条内置 + 已签名"]
+  F --> O["origin<br/>已声明 vs 来自目录"]
+  O --> P["pinning<br/>漂移 vs 已批准"]
+  P --> V["裁定<br/>allow · score · findings<br/>allowedTools / blockedTools"]
+```
+
+| 门控 | 判定什么 | 网络 | 是否 fatal |
+|---|---|---|---|
+| **static-scan** | 工具 `name`、`description` 与 `inputSchema` 中的注入、外泄、索要凭据，以及隐藏 Unicode/base64 迹象——25 条规则（v4），其中 15 条可阻止、10 条仅提示，17 条同时覆盖名称，12 条带有上下文 guard | 无 | 否 |
+| **threat-feed** | 已知恶意的服务器身份或工具：11 条内置记录，外加可选的已签名 feed | 仅 feed 下载 | 是，服务器范围的 `critical` |
+| **origin** | 该服务器是运营者声明的，还是来自远端目录 | 无 | 是，当 `allowUnknownServers: false` |
+| **pinning** | 工具定义是否仍与用户批准过的一致 | 无 | 是，当 `pinToolDefs: true` |
+
+综合评分是各门控贡献的**乘积**：一个门控出问题会把整台服务器拉下来，而不是被平均掉。严重级别与是否阻止是两
+个独立的维度：带 `advisory` 的发现会被报告，但在任何 `blockAtSeverity` 下都不会阻止连接、也不会牺牲任何工
+具——因为「这值得多少注意」和「这到底是不是缺陷」是两个不同的问题，而把后者编码成一个较低的严重级别，会让
+它对任何收紧阈值的人重新变成阻止性的。
+
+## 裁定就是为了留档
+
+```ts
+{
+  allow: false,
+  score: 0,
+  decidedBy: "threat-feed",
+  findings: [{ gate, severity, code: "THREAT_TOOL_MATCH", message, tool, advisory? }],
+  allowedTools: ["add"],
+  blockedTools: ["sweeper"],
+  rulesets: { staticScan: { version: "4", digest: "sha256-klRyTiD3…" } }
+}
+```
+
+`rulesets` 不是装饰。同一台服务器在更晚的规则表下会得到不同评分；如果既没有版本号、也没有对规则内容的摘要，
+就无法把这种情况与「服务器本身变了」区分开。缺了它们，留档的扫描结果不可复现。
+
+## 已签名的威胁情报 feed
+
+WARDEN 不会读取未签名的远端 feed。这个契约刻意做得很枯燥：
+
+```
+GET <你的 feed url>
+{ "records": [ {pattern, severity, code, reason, source, scope}, … ],
+  "timestamp": 1786205907380,   // epoch 毫秒，整数——必填
+  "signature": "f588d5a4…"      // 对 {records, timestamp} 的 RFC 8785
+}                               // 规范化形式做的 Ed25519 签名（hex）
+```
+
+会检查三项性质，且**任何一项失败都保留内置底线**，而不是退化成毫无防护：
+
+1. **真实性**——用你事先固定的公钥（`feedPublicKey`）做 Ed25519 验签；
+2. **新鲜度**——*被签名的* timestamp 必须落在 `maxAgeMs` 窗口内（默认 24 小时），这样提供该 URL 的一方就无法
+   重放几个月前的快照、悄悄抹掉此后新增的每一条记录。签名说明的是谁写了这份文件，从不说明它是何时交到你手上
+   的；
+3. **确定性**——RFC 8785 规范化字节，使发布方与验证方无论 JSON 键顺序如何都能对上。
+
+如果你需要一个可以让 `load()` 指向的目标，[MOMUS](https://github.com/alexar76/momus) 是该契约的参考发布方
+（`/warden/threat-feed`）。
+
+## 还包含
+
+- **`EgressGuard`**——出网白名单，用来包住工具发出的任何请求。工具去访问你从未列入的主机，正是典型的
+  phone-home 迹象。`*.example.com` 覆盖子域；空白名单会阻止一切，而不是放行一切。
+- **`isSensitiveTool` / `classifyTools`**——对必须逐次调用都要审批的工具做 glob 分类。敏感工具仍然是*已公布*
+  的，只是不能在无人看管的情况下运行。
+- **`canonicalize` / `parseJsonStrict`**——严格的 RFC 8785（JCS）实现，同时以 `@aimarket/warden/jcs` 导出，
+  便于把另一份实现逐字节对照验证。超出 `MAX_SAFE_JSON_INTEGER` 只接受整数、遇到孤立代理项直接拒绝（而不是转
+  义），且每次拒绝都带原因码。
+
+## 文档
+
+| | |
+|---|---|
+| [门控链](docs/gates.zh.md) | 每一个规则层级、每一个发现码、综合评分如何构成，以及如何新增一个门控 |
+| [已签名的威胁情报 feed](docs/threat-feed.zh.md) | 线上契约、三项检查，以及如何发布一个 WARDEN 会接受的 feed |
+| [集成指南](docs/integration.zh.md) | 如何把 WARDEN 接入自己的 MCP 宿主、策略取舍，以及应当留档什么 |
+| [实地普查：1 108 个公开 MCP 服务器](docs/mcp-survey.zh.md) | WARDEN 在真实的第三方工具定义上判了什么——拦截 50 个服务器，4 项成立，其余判错的六种方式 |
+
+## 它不是什么
+
+- **不是沙箱。** 这些都是进程内的 JS 判定。操作系统层面对 MCP 子进程的约束（seccomp/Landlock、
+  `sandbox-exec`）不在这里。
+- **不是模型。** 整条链上任何位置都不调用 LLM。这正是 `vet()` 快速、离线且确定的原因——也正因如此，静态扫描
+  是正则形态的，会漏掉任何规则都没覆盖的改写说法。
+- **不是信誉服务。** 早期版本里有一个门控，会向信任预言机索要一个它根本没有数据可算的评分，然后在一个请求都
+  没发出的情况下报告预言机不可达。该门控已被移除，并且只要有任何门控再次声称不可达，
+  `test/no-phantom-gate.test.ts` 就会失败。
+- **不能替代你亲自读工具定义。** 11 条内置威胁记录是底线，不是目录。
+
+## 开发
+
+```bash
+npm install && npm run build && npm test   # 141 项测试
+```
+
+`test/packaging.test.ts` 正是让标题保持诚实的东西：一旦出现运行时依赖、任何源文件从包外 import、或者入口点不
+再导出执行面，它就会失败。
+
+被 [ARGUS](https://github.com/alexar76/argus)（参考宿主）、[MOMUS](https://github.com/alexar76/momus)
+（发布方一侧）以及 AICOM 的 MCP 安全课程使用。
+
+MIT © AICOM (alexar76)

package/README.md

@@ -1,12 +1,185 @@
-# @aimarket/warden
+# WARDEN — MCP security firewall
 
-ARGUS WARDEN MCP firewall namespace
+<!-- aicom-readme-badges -->
+<p align="center">
+  <a href="https://github.com/alexar76/warden/actions/workflows/ci.yml"><img src="docs/badges/ci.svg" alt="CI" /></a>
+  <a href="https://www.npmjs.com/package/@aimarket/warden"><img src="https://img.shields.io/npm/v/@aimarket/warden?color=cb3837&label=npm" alt="npm version" /></a>
+  <img src="docs/badges/deps.svg" alt="Zero runtime dependencies" />
+  <img src="docs/badges/tests.svg" alt="141 tests passing" />
+  <img src="docs/badges/node.svg" alt="Node >= 20" />
+  <a href="LICENSE"><img src="docs/badges/license.svg" alt="License: MIT" /></a>
+</p>
+<!-- /aicom-readme-badges -->
 
-**Install the canonical package instead:**
+<p align="center">
+  <img src="docs/assets/hero.svg" alt="WARDEN — MCP security firewall: tool defs pass static-scan, threat-feed, origin, and pinning before a recorded verdict" width="920" />
+</p>
+
+
+> 🌐 **English** · [Русский](README-ru.md) · [Español](README-es.md) · [Français](README-fr.md) · [中文](README-zh.md) · [Glossary](https://github.com/alexar76/aicom/blob/main/docs/localization-glossary.md)
+
+An MCP server tells your agent what its tools do. The agent believes it — that sentence is the
+attack surface. A tool description is prompt text delivered by a third party straight into your
+model's context, and a schema field named `api_key` is a request for your secrets phrased as an API.
+
+WARDEN vets a server **before any of its tools reach the model**, and returns a verdict you can
+record: allow/block, a 0..1 score, the findings that produced it, a per-tool partition, and the
+exact rule table that was in force.
+
+```bash
+npm install @aimarket/warden
+```
+
+**Zero runtime dependencies.** The only import in the whole package is `node:crypto`. It is the
+firewall out of [ARGUS](https://github.com/alexar76/argus), extracted so you can put it in front of
+your own MCP host without adopting an agent.
+
+## Quick start
+
+```ts
+import { Warden, ThreatFeed, silentLogger } from "@aimarket/warden";
+
+const threatFeed = new ThreatFeed({ feedPublicKey: process.env.FEED_PUBKEY });
+await threatFeed.load(process.env.FEED_URL); // omit → built-in deny-list only, no network
+
+const pins = new Map();
+const warden = Warden.create({
+  policy: {
+    blockAtSeverity: "high",
+    sensitiveToolPatterns: ["*delete*", "*transfer*", "*key*"],
+    allowUnknownServers: false, // fail-closed: only servers you declared
+    pinToolDefs: true,
+  },
+  threatFeed,
+  store: {
+    getPin: async (id) => pins.get(id),
+    putPin: async (p) => void pins.set(p.serverId, p),
+  },
+  log: silentLogger(), // or your own logger
+});
+
+const verdict = await warden.vet(server, await client.listTools());
+
+if (!verdict.allow) throw new Error(`blocked by ${verdict.decidedBy}`);
+const usable = verdict.allowedTools; // a poisoned tool can be quarantined alone
+await warden.approve(server, tools); // pin what the user accepted
+```
+
+`vet()` performs **no network I/O**. The only request WARDEN ever makes is the threat-feed fetch you
+asked for by passing a URL to `load()`.
+
+## The gate chain
+
+```mermaid
+flowchart LR
+  T["tool defs<br/>from the server"] --> S["static scan<br/>25 rules"]
+  S --> F["threat feed<br/>11 built-ins + signed"]
+  F --> O["origin<br/>declared vs catalog"]
+  O --> P["pinning<br/>drift vs approval"]
+  P --> V["verdict<br/>allow · score · findings<br/>allowedTools / blockedTools"]
+```
+
+| Gate | What it decides | Network | Fatal? |
+|---|---|---|---|
+| **static-scan** | Injection, exfiltration, credential requests and hidden-Unicode/base64 tells in the tool `name`, its `description` and its `inputSchema` — 25 rules, v4, of which 15 can block and 10 are advisory-only, 17 also cover the name, and 12 carry a context guard | none | no |
+| **threat-feed** | Known-bad server identity or tool, from 11 built-in records plus an optional signed feed | only the feed fetch | yes, for a server-scoped `critical` |
+| **origin** | Whether the operator declared this server or it arrived from a remote catalog | none | yes, under `allowUnknownServers: false` |
+| **pinning** | Whether the tool defs still match what the user approved | none | yes, under `pinToolDefs: true` |
+
+The composite score is the **product** of gate contributions, so one bad gate drags the whole server
+down rather than being averaged away. Severity and blocking are separate axes: an `advisory` finding
+is reported and never blocks and never costs a tool, at any `blockAtSeverity` — because "how much
+attention does this deserve" and "is this a defect at all" are different questions, and encoding the
+second as a low severity made it blocking again for anyone who tightened the threshold.
+
+## The verdict is meant to be recorded
+
+```ts
+{
+  allow: false,
+  score: 0,
+  decidedBy: "threat-feed",
+  findings: [{ gate, severity, code: "THREAT_TOOL_MATCH", message, tool, advisory? }],
+  allowedTools: ["add"],
+  blockedTools: ["sweeper"],
+  rulesets: { staticScan: { version: "4", digest: "sha256-klRyTiD3…" } }
+}
+```
+
+`rulesets` is not decoration. The same server scores differently under a later rule table, and
+without the version *and* a digest over the rules there is no way to tell that apart from the server
+having changed. A stored scan without them is not reproducible.
+
+## Signed threat feed
+
+WARDEN will not read an unsigned remote feed. The contract is deliberately boring:
+
+```
+GET <your feed url>
+{ "records": [ {pattern, severity, code, reason, source, scope}, … ],
+  "timestamp": 1786205907380,   // epoch ms, integer — required
+  "signature": "f588d5a4…"      // Ed25519 (hex) over the RFC 8785 canonical
+}                               // form of {records, timestamp}
+```
+
+Three properties are checked, and **any failure keeps the built-in floor** rather than degrading to
+no protection:
+
+1. **authenticity** — Ed25519 against the key you pinned in advance (`feedPublicKey`);
+2. **freshness** — the *signed* timestamp must be inside `maxAgeMs` (24 h by default), so whoever
+   serves the URL cannot replay a months-old snapshot and silently erase every record added since.
+   A signature says who wrote a document, never when you were handed it;
+3. **determinism** — RFC 8785 canonical bytes, so publisher and verifier agree regardless of JSON
+   key order.
+
+[MOMUS](https://github.com/alexar76/momus) is a reference publisher of this contract
+(`/warden/threat-feed`) if you want something to point `load()` at.
+
+## Also in the box
+
+- **`EgressGuard`** — an outbound allowlist to wrap any request a tool makes. A tool reaching a host
+  you never listed is the classic phone-home tell. `*.example.com` matches subdomains; an empty
+  allowlist blocks everything rather than allowing everything.
+- **`isSensitiveTool` / `classifyTools`** — glob classification of tools that must require per-call
+  approval. Sensitive tools stay *advertised*; they just cannot run unattended.
+- **`canonicalize` / `parseJsonStrict`** — a strict RFC 8785 (JCS) implementation, also exported as
+  `@aimarket/warden/jcs` so another implementation can be byte-checked against it. Integers only
+  beyond `MAX_SAFE_JSON_INTEGER`, refusal (not escaping) on lone surrogates, and a reason code on
+  every refusal.
+
+## Documentation
+
+| | |
+|---|---|
+| [The gate chain](docs/gates.md) | Every rule tier, every finding code, how the composite score is built, and how to add a gate |
+| [The signed threat feed](docs/threat-feed.md) | The wire contract, the three checks, and how to publish a feed WARDEN will accept |
+| [Integration guide](docs/integration.md) | Wiring WARDEN into your own MCP host, policy choices, and what to record |
+| [Field survey: 1 108 public MCP servers](docs/mcp-survey.md) | What WARDEN decided on real third-party tool definitions — 50 servers blocked, 4 substantiated, and the six ways the rest were wrong |
+
+## What this is not
+
+- **Not a sandbox.** These are in-process JS decisions. OS-level confinement of the MCP child
+  process (seccomp/Landlock, `sandbox-exec`) is not here.
+- **Not a model.** No LLM is called anywhere in the chain. That is why `vet()` is fast, offline and
+  deterministic — and why the static scan is regex-shaped and will miss a paraphrase no rule covers.
+- **Not a reputation service.** An earlier version had a gate that asked a trust oracle for a score
+  it had no data to compute, then reported the oracle as unreachable without having sent a request.
+  It was removed, and `test/no-phantom-gate.test.ts` fails if any gate ever claims unreachability
+  again.
+- **Not a substitute for reading the tool defs.** 11 built-in threat records is a floor, not a
+  catalog.
+
+## Development
 
 ```bash
-npm install -g argus-warden
+npm install && npm run build && npm test   # 141 tests
 ```
 
-- Ecosystem: https://modeldev.modelmarket.dev
-- GitHub: https://github.com/alexar76/aicom
+`test/packaging.test.ts` is what keeps the headline honest: it fails if a runtime dependency appears,
+if any source file imports outside the package, or if the entry point stops exporting the
+enforcement surface.
+
+Used by [ARGUS](https://github.com/alexar76/argus) (the reference host), [MOMUS](https://github.com/alexar76/momus)
+(the publisher side), and the AICOM MCP-security course.
+
+MIT © AICOM (alexar76)

package/dist/glob.d.ts

@@ -0,0 +1,81 @@
+/**
+ * `*`-glob matching, without a regular expression.
+ *
+ * WARDEN matches two kinds of glob against attacker-controlled text: threat-feed
+ * patterns (a signed publisher chooses the pattern, a hostile server chooses the
+ * haystack) and `policy.sensitiveToolPatterns` (the operator chooses the pattern,
+ * the server chooses the tool name). Both used to compile `*` into `.*` and run a
+ * regex, which is a denial of service:
+ *
+ *     pattern  "*a*a*a*a*a*a*a*a*a*a*a*a*a*a*zzz"   (32 characters)
+ *     haystack "aaaa..."                            (220 characters)
+ *     -> 112 SECONDS inside one RegExp.test
+ *
+ * The engine has to try every way of distributing the wildcards over the haystack
+ * before it can conclude "no match" - exponential in the number of `*`. That
+ * mattered more than an ordinary performance bug: the threat feed's whole trust
+ * story is that a compromised publisher can only ever ADD protection, never
+ * remove it, and a record that hangs `vet()` forever removes all of it. The same
+ * shape let a hostile server freeze the agent inspecting it, by advertising a
+ * long enough tool name against an operator's own `*a*b*c*` pattern.
+ *
+ * The two-pointer algorithm below is the standard wildcard matcher: it walks the
+ * haystack once and remembers only the most recent `*` to fall back to, so the
+ * work is bounded by `pattern.length x value.length` with no backtracking tree to
+ * explode. The same 32/220 case returns in microseconds.
+ *
+ * Semantics, matching what the regex did: `*` matches any run of zero or more
+ * UTF-16 code units (including newlines - the old regex needed the `s` flag for
+ * that), every other character is literal, and the match is anchored at both
+ * ends. Case folding is the caller's job: both sides arrive already lowercased.
+ */
+export declare function wildcardMatch(pattern: string, value: string): boolean;
+/**
+ * How many wildcards a pattern may carry.
+ *
+ * The matcher above is not exponential, but `*`-heavy patterns still cost
+ * `pattern x value` per match and buy nothing: a real threat pattern names a
+ * command, a path or a keyword. A record with more than this many wildcards is
+ * refused rather than run - refusing an *addition* to the deny-list is the safe
+ * direction, and it is reported loudly.
+ */
+export declare const MAX_GLOB_WILDCARDS = 12;
+/** Count `*` in a pattern, for the record validator. */
+export declare function countWildcards(pattern: string): number;
+/**
+ * Largest gap an INTERIOR `*` in a threat pattern may span.
+ *
+ * A field survey of 1 108 public MCP servers (see docs/mcp-survey.md) found every
+ * multi-segment built-in firing on unrelated words that merely happened to appear
+ * in the same paragraph: `*drain*wallet*` matched an anti-drainer scanner because
+ * it says "drainer" in one clause and "wallet" in another, and `*seed*phrase*`
+ * matched "for a **seed** topic, returns suggested search **phrases**". A real
+ * threat pattern names something whose parts sit next to each other; 24 characters
+ * is roughly "a few words apart" and comfortably covers "wallet seed or recovery
+ * phrase".
+ */
+export declare const THREAT_MAX_GAP = 24;
+/**
+ * Threat-pattern matching: `wildcardMatch` plus two constraints that only make
+ * sense for a deny-list.
+ *
+ * 1. **Interior gaps are bounded** to {@link THREAT_MAX_GAP}. Leading and trailing
+ *    `*` stay unbounded — `*id_rsa*` must still find `id_rsa` anywhere.
+ * 2. **A segment that starts with a word character must start at a word boundary.**
+ *    `*sweep*funds*` matched an ENS floor-sweeping tool because `funds` sits inside
+ *    "re**funds**". Only the START is anchored: a pattern author writing `*drain*`
+ *    means "drainer" too, so anchoring the end as well would break ordinary
+ *    stemming.
+ *
+ * Kept separate from {@link wildcardMatch} on purpose. That function is also what
+ * `policy.sensitiveToolPatterns` runs on, where the operator wrote the pattern
+ * against their own tool names and plain glob semantics are what they expect.
+ *
+ * Completeness matters here in a way it does not for a display filter: a missed
+ * match is a deny-list entry that silently stopped working. So this explores every
+ * reachable position per segment (deduplicated, so the work stays bounded by
+ * `segments x value.length`) rather than taking the leftmost occurrence greedily,
+ * which would report "no match" for a pattern that does match further along.
+ */
+export declare function threatMatch(pattern: string, value: string): boolean;
+//# sourceMappingURL=glob.d.ts.map

package/dist/glob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../src/glob.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CA4BrE;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC,wDAAwD;AACxD,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMtD;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CA+BnE"}