@aimarket/warden 0.0.1 → 0.3.0

package/README-zh.md

@@ -0,0 +1,167 @@
+# 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="95 项测试通过" />
+  <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 -->
+
+> 🌐 [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** | `description` 与 `inputSchema` 中的注入、外泄、索要凭据，以及隐藏 Unicode/base64 迹象——25 条规则（v2），其中 18 条可阻止、7 条仅提示 | 无 | 否 |
+| **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: "2", digest: "sha256-gWC14PR4…" } }
+}
+```
+
+`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 宿主、策略取舍，以及应当留档什么 |
+
+## 它不是什么
+
+- **不是沙箱。** 这些都是进程内的 JS 判定。操作系统层面对 MCP 子进程的约束（seccomp/Landlock、
+  `sandbox-exec`）不在这里。
+- **不是模型。** 整条链上任何位置都不调用 LLM。这正是 `vet()` 快速、离线且确定的原因——也正因如此，静态扫描
+  是正则形态的，会漏掉任何规则都没覆盖的改写说法。
+- **不是信誉服务。** 早期版本里有一个门控，会向信任预言机索要一个它根本没有数据可算的评分，然后在一个请求都
+  没发出的情况下报告预言机不可达。该门控已被移除，并且只要有任何门控再次声称不可达，
+  `test/no-phantom-gate.test.ts` 就会失败。
+- **不能替代你亲自读工具定义。** 11 条内置威胁记录是底线，不是目录。
+
+## 开发
+
+```bash
+npm install && npm run build && npm test   # 95 项测试
+```
+
+`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,179 @@
-# @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="95 tests passing" />
+  <img src="docs/badges/node.svg" alt="Node >= 20" />
+  <a href="LICENSE"><img src="docs/badges/license.svg" alt="License: MIT" /></a>
+</p>
+<!-- /aicom-readme-badges -->
 
-**Install the canonical package instead:**
+> 🌐 **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 `description` and `inputSchema` — 25 rules, v2, of which 18 can block and 7 are advisory-only | 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: "2", digest: "sha256-gWC14PR4…" } }
+}
+```
+
+`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 |
+
+## 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   # 95 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/index.d.ts

@@ -0,0 +1,73 @@
+import type { McpServerRef, PinStore, ToolDef, WardenGate, WardenLogger, WardenPolicy, WardenVerdict } from "./types.js";
+import { ThreatFeed } from "./threat-feed.js";
+export { StaticScanGate, staticScanRuleset, staticScanRulesetRef, STATIC_SCAN_RULESET_VERSION, } from "./static-scan.js";
+export { PinningGate, canonicalToolsHash, tryCanonicalToolsHash, UNCANONICAL_TOOLS_HASH } from "./pinning.js";
+export { OriginGate } from "./origin.js";
+export { ThreatFeed, ThreatGate, DEFAULT_FEED_MAX_AGE_MS, FEED_CLOCK_SKEW_MS } from "./threat-feed.js";
+export { EgressGuard, isSensitiveTool, classifyTools } from "./sandbox.js";
+export { canonicalize, parseJsonStrict, CanonicalizationError, MAX_SAFE_JSON_INTEGER } from "./jcs.js";
+export type { CanonicalizationCode } from "./jcs.js";
+export type { StaticScanRule, StaticScanRuleset } from "./static-scan.js";
+export type { ThreatFeedOptions } from "./threat-feed.js";
+export { silentLogger } from "./logger.js";
+export * from "./types.js";
+export interface WardenInit {
+    gates: WardenGate[];
+    policy: WardenPolicy;
+    /** Where decisions are reported. Defaults to `silentLogger()`. */
+    log?: WardenLogger;
+}
+export interface WardenCreateDeps {
+    store: PinStore;
+    policy: WardenPolicy;
+    /**
+     * The known-bad feed. Required, not defaulted: a `ThreatFeed` the host never
+     * loaded still carries the built-in floor, but silently constructing one here
+     * would hide from the host that no external intel is in play.
+     */
+    threatFeed: ThreatFeed;
+    log?: WardenLogger;
+}
+/**
+ * WARDEN — the MCP security firewall.
+ *
+ * Every MCP server is vetted through an ordered gate chain before its tools are
+ * exposed to the agent: cheap static scanning first, then the known-bad threat
+ * feed, then network reputation, then drift/pinning. Findings accumulate across
+ * gates; the verdict is allow/block plus a composite 0..1 safety score and a
+ * per-tool partition so a mostly-trusted server can have one poisoned tool
+ * quarantined without severing the whole connection.
+ */
+export declare class Warden {
+    private readonly gates;
+    private readonly policy;
+    private readonly log;
+    constructor(init: WardenInit);
+    /**
+     * Guard against config typos that silently disable blocking. If blockAtSeverity
+     * isn't a valid Severity key, SEVERITY_RANK[bad] is undefined and every
+     * comparison `number >= undefined` is false — zero blocks, zero warnings.
+     */
+    private validatePolicy;
+    /** Build the standard gate chain: static → threat → origin → pinning. */
+    static create(deps: WardenCreateDeps): Warden;
+    /**
+     * Vet a server and its advertised tools. Runs every gate in order, short-
+     * circuiting only on a fatal gate result. A connection is blocked if any gate
+     * is fatal or any finding reaches policy.blockAtSeverity.
+     */
+    vet(server: McpServerRef, tools: ToolDef[]): Promise<WardenVerdict>;
+    /**
+     * Record the user's approval: pin the current tool defs so future drift is
+     * detected. Idempotent — re-approving just refreshes the snapshot.
+     */
+    approve(server: McpServerRef, tools: ToolDef[]): Promise<void>;
+    /**
+     * A tool is blocked if a finding naming it reaches the block threshold.
+     * Sensitive tools (per policy) stay allowed but are surfaced as flagged so the
+     * agent loop can demand per-call approval at run time.
+     */
+    private partitionTools;
+    private sensitiveCount;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,QAAQ,EAER,OAAO,EAEP,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,EACd,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAE,UAAU,EAAc,MAAM,kBAAkB,CAAC;AAI1D,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAC9G,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACvG,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC3E,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AACvG,YAAY,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AACrD,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1E,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,cAAc,YAAY,CAAC;AAU3B,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,MAAM,EAAE,YAAY,CAAC;IACrB,kEAAkE;IAClE,GAAG,CAAC,EAAE,YAAY,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,QAAQ,CAAC;IAChB,MAAM,EAAE,YAAY,CAAC;IACrB;;;;OAIG;IACH,UAAU,EAAE,UAAU,CAAC;IACvB,GAAG,CAAC,EAAE,YAAY,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEvB,IAAI,EAAE,UAAU;IAO5B;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAYtB,yEAAyE;IACzE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM;IAU7C;;;;OAIG;IACG,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC;IAuDzE;;;OAGG;IACG,OAAO,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAUpE;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAoBtB,OAAO,CAAC,cAAc;CAGvB"}

package/dist/index.js

@@ -0,0 +1,163 @@
+import { StaticScanGate, staticScanRulesetRef } from "./static-scan.js";
+import { PinningGate } from "./pinning.js";
+import { OriginGate } from "./origin.js";
+import { ThreatGate } from "./threat-feed.js";
+import { classifyTools } from "./sandbox.js";
+import { silentLogger } from "./logger.js";
+export { StaticScanGate, staticScanRuleset, staticScanRulesetRef, STATIC_SCAN_RULESET_VERSION, } from "./static-scan.js";
+export { PinningGate, canonicalToolsHash, tryCanonicalToolsHash, UNCANONICAL_TOOLS_HASH } from "./pinning.js";
+export { OriginGate } from "./origin.js";
+export { ThreatFeed, ThreatGate, DEFAULT_FEED_MAX_AGE_MS, FEED_CLOCK_SKEW_MS } from "./threat-feed.js";
+export { EgressGuard, isSensitiveTool, classifyTools } from "./sandbox.js";
+export { canonicalize, parseJsonStrict, CanonicalizationError, MAX_SAFE_JSON_INTEGER } from "./jcs.js";
+export { silentLogger } from "./logger.js";
+export * from "./types.js";
+const SEVERITY_RANK = {
+    info: 0,
+    low: 1,
+    medium: 2,
+    high: 3,
+    critical: 4,
+};
+/**
+ * WARDEN — the MCP security firewall.
+ *
+ * Every MCP server is vetted through an ordered gate chain before its tools are
+ * exposed to the agent: cheap static scanning first, then the known-bad threat
+ * feed, then network reputation, then drift/pinning. Findings accumulate across
+ * gates; the verdict is allow/block plus a composite 0..1 safety score and a
+ * per-tool partition so a mostly-trusted server can have one poisoned tool
+ * quarantined without severing the whole connection.
+ */
+export class Warden {
+    gates;
+    policy;
+    log;
+    constructor(init) {
+        this.gates = init.gates;
+        this.policy = init.policy;
+        this.log = (init.log ?? silentLogger()).child("warden");
+        this.validatePolicy();
+    }
+    /**
+     * Guard against config typos that silently disable blocking. If blockAtSeverity
+     * isn't a valid Severity key, SEVERITY_RANK[bad] is undefined and every
+     * comparison `number >= undefined` is false — zero blocks, zero warnings.
+     */
+    validatePolicy() {
+        const valid = ["info", "low", "medium", "high", "critical"];
+        if (!valid.includes(this.policy.blockAtSeverity)) {
+            const fallback = "high";
+            this.log.warn(`WARDEN: invalid blockAtSeverity "${String(this.policy.blockAtSeverity)}" ` +
+                `(expected one of ${valid.join(", ")}) — falling back to "${fallback}" to keep blocking enabled`);
+            this.policy.blockAtSeverity = fallback;
+        }
+    }
+    /** Build the standard gate chain: static → threat → origin → pinning. */
+    static create(deps) {
+        const gates = [
+            new StaticScanGate(),
+            new ThreatGate(deps.threatFeed),
+            new OriginGate(),
+            new PinningGate(deps.store),
+        ];
+        return new Warden({ gates, policy: deps.policy, log: deps.log });
+    }
+    /**
+     * Vet a server and its advertised tools. Runs every gate in order, short-
+     * circuiting only on a fatal gate result. A connection is blocked if any gate
+     * is fatal or any finding reaches policy.blockAtSeverity.
+     */
+    async vet(server, tools) {
+        const findings = [];
+        const scores = [];
+        let allow = true;
+        let decidedBy;
+        const blockThreshold = SEVERITY_RANK[this.policy.blockAtSeverity];
+        for (const gate of this.gates) {
+            const result = await gate.evaluate({
+                server,
+                tools,
+                prior: [...findings],
+                policy: this.policy,
+            });
+            findings.push(...result.findings);
+            scores.push(clamp01(result.score));
+            // Advisory findings never block, at any threshold — see WardenFinding.advisory.
+            const tripped = result.findings.some((f) => !f.advisory && SEVERITY_RANK[f.severity] >= blockThreshold);
+            if (result.fatal || tripped) {
+                if (allow) {
+                    allow = false;
+                    decidedBy = gate.name;
+                }
+                if (result.fatal) {
+                    this.log.warn(`gate "${gate.name}" returned fatal for server ${server.id}`);
+                    break; // short-circuit only on an explicit fatal
+                }
+            }
+        }
+        // Composite score: product of gate contributions (one bad gate drags it down).
+        const score = scores.reduce((acc, s) => acc * s, 1);
+        const { allowedTools, blockedTools } = this.partitionTools(tools, findings, blockThreshold);
+        if (!allow) {
+            this.log.warn(`BLOCK ${server.id} (decidedBy=${decidedBy}, score=${score.toFixed(3)}, findings=${findings.length})`);
+        }
+        else {
+            this.log.info(`ALLOW ${server.id} (score=${score.toFixed(3)}, sensitive=${blockedTools.length === 0 ? this.sensitiveCount(tools) : "?"})`);
+        }
+        return {
+            allow,
+            score: clamp01(score),
+            decidedBy,
+            findings,
+            allowedTools,
+            blockedTools,
+            rulesets: { staticScan: staticScanRulesetRef() },
+        };
+    }
+    /**
+     * Record the user's approval: pin the current tool defs so future drift is
+     * detected. Idempotent — re-approving just refreshes the snapshot.
+     */
+    async approve(server, tools) {
+        const pinning = this.gates.find((g) => g instanceof PinningGate);
+        if (!pinning) {
+            this.log.warn("approve() called but no PinningGate in the chain; nothing to pin");
+            return;
+        }
+        await pinning.pin(server, tools);
+        this.log.info(`pinned tool defs for ${server.id} (${tools.length} tools)`);
+    }
+    /**
+     * A tool is blocked if a finding naming it reaches the block threshold.
+     * Sensitive tools (per policy) stay allowed but are surfaced as flagged so the
+     * agent loop can demand per-call approval at run time.
+     */
+    partitionTools(tools, findings, blockThreshold) {
+        const blockedByFinding = new Set();
+        for (const f of findings) {
+            if (f.advisory)
+                continue; // report-only, never costs a tool
+            if (f.tool && SEVERITY_RANK[f.severity] >= blockThreshold)
+                blockedByFinding.add(f.tool);
+        }
+        const allowedTools = [];
+        const blockedTools = [];
+        for (const tool of tools) {
+            if (blockedByFinding.has(tool.name))
+                blockedTools.push(tool.name);
+            else
+                allowedTools.push(tool.name);
+        }
+        return { allowedTools, blockedTools };
+    }
+    sensitiveCount(tools) {
+        return classifyTools(tools, this.policy).sensitive.length;
+    }
+}
+function clamp01(n) {
+    if (!Number.isFinite(n))
+        return 0;
+    return Math.max(0, Math.min(1, n));
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}