@aimarket/warden 0.0.1 → 0.4.0

package/dist/pinning.js

@@ -0,0 +1,227 @@
+import { createHash } from "node:crypto";
+import { canonicalize, CanonicalizationError } from "./jcs.js";
+import { displaySafe } from "./sanitize.js";
+/**
+ * Tool-definition pinning + drift detection ("rug-pull" defence).
+ *
+ * A server can advertise benign tools at approval time and silently swap in a
+ * poisoned definition later. We hash the canonical tool-def set on approval and
+ * compare on every subsequent connection: a changed hash means the contract the
+ * user approved no longer holds, so (under policy.pinToolDefs) we block and force
+ * re-approval. First-contact servers are flagged UNPINNED so the chain knows the
+ * pin is established only when the user approves.
+ */
+export class PinningGate {
+    store;
+    name = "pinning";
+    constructor(store) {
+        this.store = store;
+    }
+    async evaluate(input) {
+        const pin = await this.store.getPin(input.server.id);
+        let hash;
+        try {
+            hash = canonicalToolsHash(input.tools);
+        }
+        catch (err) {
+            if (!(err instanceof CanonicalizationError))
+                throw err;
+            return this.uncanonical(input, pin, err);
+        }
+        const identityDrift = this.identityDrift(input, pin);
+        if (!pin) {
+            const finding = {
+                gate: this.name,
+                severity: "info",
+                code: "TOOL_DEF_UNPINNED",
+                message: `Server "${input.server.id}" has no pinned tool-def snapshot yet; it will be pinned on approval.`,
+                // Report-only by necessity, not by preference: a server at first contact
+                // cannot be anything but unpinned, and Warden.approve() runs only after
+                // vet() passes. Letting this finding block — which it did at
+                // blockAtSeverity "info" — makes first contact impossible for every
+                // server, so no pin can ever be created.
+                advisory: true,
+            };
+            // Neutral-to-good: unpinned isn't unsafe, it's just unestablished.
+            return { findings: [finding], score: 0.9 };
+        }
+        const findings = [];
+        if (pin.toolsHash !== hash) {
+            findings.push({
+                gate: this.name,
+                severity: "high",
+                code: "TOOL_DEF_DRIFT",
+                message: `Tool definitions for "${displaySafe(input.server.id)}" changed since approval ` +
+                    `(pinned ${short(pin.toolsHash)} → now ${short(hash)}). Possible rug-pull; re-approval required.`,
+            });
+        }
+        // Both are reported when both changed: "the tools moved AND so did the
+        // program serving them" is a different picture from either one alone, and
+        // returning on the first one found used to hide the second.
+        if (identityDrift)
+            findings.push(identityDrift);
+        if (findings.length > 0) {
+            return { findings, score: 0, fatal: input.policy.pinToolDefs === true };
+        }
+        return { findings: [], score: 1 };
+    }
+    /**
+     * Has the program behind this server changed since approval?
+     *
+     * Silent when the pin predates {@link PinnedServer.identityHash}: an absent
+     * value is "not recorded", never "changed". The next `approve()` records it.
+     */
+    identityDrift(input, pin) {
+        if (!pin?.identityHash)
+            return undefined;
+        const now = serverIdentityHash(input.server);
+        if (now === pin.identityHash)
+            return undefined;
+        return {
+            gate: this.name,
+            severity: "high",
+            code: "SERVER_IDENTITY_DRIFT",
+            message: `The launch identity of "${displaySafe(input.server.id)}" changed since approval ` +
+                `(pinned ${short(pin.identityHash)} → now ${short(now)}): transport, command, args, url or name ` +
+                `is not what was approved. The advertised tools may be identical while the program serving them is not.`,
+        };
+    }
+    /**
+     * The tool-def set has no canonical form (see {@link canonicalToolsHash}), so no
+     * hash can be produced for it. What that means depends on whether a pin exists:
+     *
+     * - **No pin yet** — nothing is being contradicted; the pin simply cannot be
+     *   established, which is a `medium` warning and not evidence of an attack.
+     * - **Pin exists** — the snapshot the user approved can no longer be re-verified,
+     *   which is indistinguishable from drift and is treated as drift. Otherwise a
+     *   server could disarm the rug-pull defence at will by adding one fractional
+     *   number to a schema.
+     */
+    uncanonical(input, pin, err) {
+        if (!pin) {
+            return {
+                findings: [
+                    {
+                        gate: this.name,
+                        severity: "medium",
+                        code: "TOOL_DEF_UNCANONICAL",
+                        message: `Tool definitions for "${displaySafe(input.server.id)}" have no canonical form (${err.message}), ` +
+                            `so no reproducible pin can be taken — drift detection is unavailable for this server.`,
+                    },
+                ],
+                score: 0.5,
+            };
+        }
+        return {
+            findings: [
+                {
+                    gate: this.name,
+                    severity: "high",
+                    code: "TOOL_DEF_UNCANONICAL",
+                    message: `Tool definitions for "${displaySafe(input.server.id)}" have no canonical form (${err.message}), so the pinned ` +
+                        `snapshot ${short(pin.toolsHash)} cannot be re-verified. Treated as drift; re-approval required.`,
+                },
+            ],
+            score: 0,
+            fatal: input.policy.pinToolDefs === true,
+        };
+    }
+    /**
+     * Persist the current tool-def set as the trusted snapshot for this server.
+     * Called by Warden.approve() once a user has accepted the connection.
+     *
+     * Throws {@link CanonicalizationError} when the set has no canonical form; the
+     * caller (`McpHost.connect`) already reports a pin failure as a degraded
+     * rug-pull defence rather than failing the connection.
+     */
+    async pin(server, tools) {
+        const pinned = {
+            serverId: server.id,
+            toolsHash: canonicalToolsHash(tools),
+            approvedAt: new Date().toISOString(),
+            toolNames: [...tools.map((t) => t.name)].sort(compareCodeUnits),
+            identityHash: serverIdentityHash(server),
+        };
+        await this.store.putPin(pinned);
+    }
+}
+/**
+ * Marker used where a tool-def hash is *recorded* rather than compared, and the set
+ * turned out to have no canonical form. It can never collide with a sha256 hex
+ * digest, so anything that later compares it simply reports a mismatch.
+ */
+export const UNCANONICAL_TOOLS_HASH = "uncanonical:non-canonical-tool-defs";
+/**
+ * sha256 over the canonical tool-def set: tools sorted by name, each reduced to
+ * the security-relevant fields (name, description, schema), serialised with
+ * {@link canonicalize} — RFC 8785 (JCS) as profiled in `awr/SPEC.md` §4.
+ *
+ * This digest is quoted in receipts and re-checked elsewhere (`argus verify`, the
+ * sealed mandate), so it has to be reproducible by an implementation that is not
+ * this one. Two consequences:
+ *
+ * - **Ordering is by UTF-16 code unit, never `localeCompare`.** `localeCompare`
+ *   depends on the host locale and ICU version — `["a", "B"]` sorts one way under
+ *   `en-US` and another under the C locale — so a digest built on it is not even
+ *   stable across two machines running this same code, let alone across languages.
+ *   JavaScript's `<`/`>` on strings compare UTF-16 code units, which is exactly
+ *   RFC 8785 §3.2.3's rule.
+ * - **Non-integer numbers are refused** (`AWR-CANON-001`, SPEC §4.3) rather than
+ *   serialised. Whether `1` is an integer or a double is a language accident that
+ *   silently changes the bytes, so a schema carrying e.g. `"multipleOf": 0.01` has
+ *   no canonical form here and this function throws
+ *   {@link CanonicalizationError}. Callers must handle that — refusing to emit a
+ *   digest is honest; emitting one nobody else can reproduce is not.
+ */
+export function canonicalToolsHash(tools) {
+    const canonical = [...tools]
+        .sort((a, b) => compareCodeUnits(a.name, b.name))
+        .map((t) => ({
+        name: t.name,
+        description: t.description ?? "",
+        inputSchema: t.inputSchema ?? {},
+    }));
+    return createHash("sha256").update(canonicalize(canonical), "utf8").digest("hex");
+}
+/**
+ * Like {@link canonicalToolsHash} but total: returns `undefined` instead of
+ * throwing, for call sites that record a hash rather than enforce one.
+ */
+export function tryCanonicalToolsHash(tools) {
+    try {
+        return canonicalToolsHash(tools);
+    }
+    catch (err) {
+        if (err instanceof CanonicalizationError)
+            return undefined;
+        throw err;
+    }
+}
+/**
+ * sha256 over the server's launch identity: transport, command, args, url, name.
+ *
+ * Deliberately NOT the whole `McpServerRef`: `catalog` is provenance rather than
+ * identity (the origin gate is what has an opinion about it), and `env` holds
+ * secrets that must not be hashed into a value stored on disk next to the pin.
+ *
+ * Missing fields serialize as empty rather than being omitted, so a server that
+ * gains a `url` reads as a change instead of hashing the same as before.
+ */
+export function serverIdentityHash(server) {
+    const identity = {
+        transport: server.transport,
+        command: server.command ?? "",
+        args: server.args ?? [],
+        url: server.url ?? "",
+        name: server.name,
+    };
+    return createHash("sha256").update(canonicalize(identity), "utf8").digest("hex");
+}
+/** RFC 8785 §3.2.3 ordering: arrays of UTF-16 code units as unsigned integers. */
+function compareCodeUnits(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function short(hash) {
+    return hash.slice(0, 12);
+}
+//# sourceMappingURL=pinning.js.map

package/dist/pinning.js.map

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

package/dist/sandbox.d.ts

@@ -0,0 +1,38 @@
+import type { ToolDef, WardenPolicy } from "./types.js";
+/**
+ * Runtime policy layer for tool execution.
+ *
+ * NOTE: this is the JS-level policy layer, not a true sandbox. It classifies
+ * tools, gates sensitive calls behind explicit approval, and watches egress for
+ * a tool trying to phone home. OS-level process isolation
+ * (seccomp / Landlock on Linux, sandbox-exec on macOS) is the v2 hardening that
+ * confines the actual child process; until then these helpers are the boundary
+ * the agent loop enforces in-process.
+ */
+/**
+ * True if a tool name matches any sensitive pattern in the policy. Patterns use
+ * `*` as a wildcard and match case-insensitively (e.g. "*delete*", "*transfer*").
+ * Sensitive tools are still allowed to be advertised — they just require explicit
+ * per-call approval before WARDEN lets them run.
+ */
+export declare function isSensitiveTool(toolName: string, policy: WardenPolicy): boolean;
+/** Split a server's advertised tools into sensitive vs. safe by policy. */
+export declare function classifyTools(tools: ToolDef[], policy: WardenPolicy): {
+    sensitive: string[];
+    safe: string[];
+};
+/**
+ * Outbound-request allowlist. Wrap any network egress a tool performs in
+ * `check()` — a tool that tries to reach a host outside the allowlist is the
+ * classic "phone home" exfiltration tell. Hostnames are matched case-insensitively
+ * and a leading "*." entry matches subdomains (e.g. "*.example.com").
+ */
+export declare class EgressGuard {
+    private readonly allow;
+    constructor(allowlist: string[]);
+    check(url: string): {
+        allowed: boolean;
+        reason?: string;
+    };
+}
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAExD;;;;;;;;;GASG;AAEH;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAG/E;AAED,2EAA2E;AAC3E,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,EAAE,EAChB,MAAM,EAAE,YAAY,GACnB;IAAE,SAAS,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAQzC;AAED;;;;;GAKG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAW;gBAErB,SAAS,EAAE,MAAM,EAAE;IAI/B,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;CAmB1D"}

package/dist/sandbox.js

@@ -0,0 +1,79 @@
+import { wildcardMatch } from "./glob.js";
+/**
+ * Runtime policy layer for tool execution.
+ *
+ * NOTE: this is the JS-level policy layer, not a true sandbox. It classifies
+ * tools, gates sensitive calls behind explicit approval, and watches egress for
+ * a tool trying to phone home. OS-level process isolation
+ * (seccomp / Landlock on Linux, sandbox-exec on macOS) is the v2 hardening that
+ * confines the actual child process; until then these helpers are the boundary
+ * the agent loop enforces in-process.
+ */
+/**
+ * True if a tool name matches any sensitive pattern in the policy. Patterns use
+ * `*` as a wildcard and match case-insensitively (e.g. "*delete*", "*transfer*").
+ * Sensitive tools are still allowed to be advertised — they just require explicit
+ * per-call approval before WARDEN lets them run.
+ */
+export function isSensitiveTool(toolName, policy) {
+    const name = toolName.toLowerCase();
+    return policy.sensitiveToolPatterns.some((pat) => globMatch(pat, name));
+}
+/** Split a server's advertised tools into sensitive vs. safe by policy. */
+export function classifyTools(tools, policy) {
+    const sensitive = [];
+    const safe = [];
+    for (const tool of tools) {
+        if (isSensitiveTool(tool.name, policy))
+            sensitive.push(tool.name);
+        else
+            safe.push(tool.name);
+    }
+    return { sensitive, safe };
+}
+/**
+ * Outbound-request allowlist. Wrap any network egress a tool performs in
+ * `check()` — a tool that tries to reach a host outside the allowlist is the
+ * classic "phone home" exfiltration tell. Hostnames are matched case-insensitively
+ * and a leading "*." entry matches subdomains (e.g. "*.example.com").
+ */
+export class EgressGuard {
+    allow;
+    constructor(allowlist) {
+        this.allow = allowlist.map((h) => h.trim().toLowerCase()).filter(Boolean);
+    }
+    check(url) {
+        let host;
+        try {
+            host = new URL(url).hostname.toLowerCase();
+        }
+        catch {
+            return { allowed: false, reason: `Unparseable URL: ${url}` };
+        }
+        if (this.allow.length === 0) {
+            return { allowed: false, reason: `Egress blocked (empty allowlist): ${host}` };
+        }
+        for (const entry of this.allow) {
+            if (entry === host)
+                return { allowed: true };
+            if (entry.startsWith("*.")) {
+                const suffix = entry.slice(1); // ".example.com"
+                if (host.endsWith(suffix) && host.length > suffix.length)
+                    return { allowed: true };
+            }
+        }
+        return { allowed: false, reason: `Host not in egress allowlist: ${host}` };
+    }
+}
+/**
+ * `*`-glob match (case-insensitive). Inputs are matched as whole strings.
+ *
+ * The pattern comes from the operator's policy, the value from the server being
+ * inspected. Compiling `*` into `.*` and running a regex made that pair a denial
+ * of service: an operator pattern with a dozen wildcards plus a 200-character
+ * tool name took 89 SECONDS to answer "not sensitive". See ./glob.ts.
+ */
+function globMatch(pattern, value) {
+    return wildcardMatch(pattern.toLowerCase(), value);
+}
+//# sourceMappingURL=sandbox.js.map

package/dist/sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG1C;;;;;;;;;GASG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB,EAAE,MAAoB;IACpE,MAAM,IAAI,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;IACpC,OAAO,MAAM,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;AAC1E,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,aAAa,CAC3B,KAAgB,EAChB,MAAoB;IAEpB,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,eAAe,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC;YAAE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;;YAC7D,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;AAC7B,CAAC;AAED;;;;;GAKG;AACH,MAAM,OAAO,WAAW;IACL,KAAK,CAAW;IAEjC,YAAY,SAAmB;QAC7B,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC5E,CAAC;IAED,KAAK,CAAC,GAAW;QACf,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;QAC7C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,oBAAoB,GAAG,EAAE,EAAE,CAAC;QAC/D,CAAC;QACD,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,qCAAqC,IAAI,EAAE,EAAE,CAAC;QACjF,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC/B,IAAI,KAAK,KAAK,IAAI;gBAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;YAC7C,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC3B,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,iBAAiB;gBAChD,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM;oBAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;YACrF,CAAC;QACH,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,iCAAiC,IAAI,EAAE,EAAE,CAAC;IAC7E,CAAC;CACF;AAED;;;;;;;GAOG;AACH,SAAS,SAAS,CAAC,OAAe,EAAE,KAAa;IAC/C,OAAO,aAAa,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,KAAK,CAAC,CAAC;AACrD,CAAC"}

package/dist/sanitize.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Make untrusted text safe to *display*.
+ *
+ * Every finding WARDEN emits quotes something the other side chose: a tool name,
+ * a server id, a catalog name, the `reason` string out of a signed threat feed.
+ * Those strings are then printed to a terminal by the host CLI, rendered in a
+ * dashboard, and stored in receipts. Interpolating them raw makes the firewall
+ * itself the delivery vehicle for a terminal-control payload:
+ *
+ *     tool name: <ESC>[2K<ESC>[1A + "overwritten  ~/.ssh"
+ *     finding:   Tool "<ESC>[2K<ESC>[1Aoverwritten  ~/.ssh": Server references ...
+ *
+ * Printed to a TTY that erases the current line and moves the cursor up, so the
+ * BLOCK line WARDEN had just written is overwritten by text the attacker chose.
+ * The same trick with zero-width and bidi characters makes a name read as
+ * something it is not.
+ *
+ * So control characters and invisible characters are replaced with a VISIBLE
+ * escape rather than stripped. Stripping would hide the very thing worth seeing:
+ * a name with an embedded U+202E should look suspicious in the report, not clean.
+ * Length is capped, because a finding message is a line of output, not somewhere
+ * a hostile server gets to paste a megabyte.
+ *
+ * This is display hygiene, not a security boundary. `WardenFinding.tool` keeps
+ * the RAW advertised name, because that is the key a host uses to filter its own
+ * tool list and a sanitized key would match nothing.
+ */
+/** Default cap for an interpolated fragment: long enough to be useful in a log line. */
+export declare const DEFAULT_DISPLAY_MAX = 200;
+/**
+ * Render `value` as a single-line, control-character-free fragment, escaping what
+ * cannot be shown and truncating past `max`.
+ *
+ * Exported so a host can apply it to the raw names it gets back in
+ * `allowedTools` / `blockedTools`, which are deliberately not sanitized.
+ */
+export declare function displaySafe(value: unknown, max?: number): string;
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/sanitize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../src/sanitize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAUH,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,GAAE,MAA4B,GAAG,MAAM,CASrF"}

package/dist/sanitize.js

@@ -0,0 +1,53 @@
+/**
+ * Make untrusted text safe to *display*.
+ *
+ * Every finding WARDEN emits quotes something the other side chose: a tool name,
+ * a server id, a catalog name, the `reason` string out of a signed threat feed.
+ * Those strings are then printed to a terminal by the host CLI, rendered in a
+ * dashboard, and stored in receipts. Interpolating them raw makes the firewall
+ * itself the delivery vehicle for a terminal-control payload:
+ *
+ *     tool name: <ESC>[2K<ESC>[1A + "overwritten  ~/.ssh"
+ *     finding:   Tool "<ESC>[2K<ESC>[1Aoverwritten  ~/.ssh": Server references ...
+ *
+ * Printed to a TTY that erases the current line and moves the cursor up, so the
+ * BLOCK line WARDEN had just written is overwritten by text the attacker chose.
+ * The same trick with zero-width and bidi characters makes a name read as
+ * something it is not.
+ *
+ * So control characters and invisible characters are replaced with a VISIBLE
+ * escape rather than stripped. Stripping would hide the very thing worth seeing:
+ * a name with an embedded U+202E should look suspicious in the report, not clean.
+ * Length is capped, because a finding message is a line of output, not somewhere
+ * a hostile server gets to paste a megabyte.
+ *
+ * This is display hygiene, not a security boundary. `WardenFinding.tool` keeps
+ * the RAW advertised name, because that is the key a host uses to filter its own
+ * tool list and a sanitized key would match nothing.
+ */
+/** Zero-width and bidi controls: invisible, therefore always escaped. */
+const INVISIBLE = "\\u200B-\\u200F\\u202A-\\u202E\\u2060\\u2066-\\u2069\\uFEFF";
+/** C0 controls, DEL, and C1 - the terminal-control range. */
+const CONTROL = "\\u0000-\\u001F\\u007F-\\u009F";
+const UNSAFE = new RegExp(`[${CONTROL}${INVISIBLE}]`, "g");
+/** Default cap for an interpolated fragment: long enough to be useful in a log line. */
+export const DEFAULT_DISPLAY_MAX = 200;
+/**
+ * Render `value` as a single-line, control-character-free fragment, escaping what
+ * cannot be shown and truncating past `max`.
+ *
+ * Exported so a host can apply it to the raw names it gets back in
+ * `allowedTools` / `blockedTools`, which are deliberately not sanitized.
+ */
+export function displaySafe(value, max = DEFAULT_DISPLAY_MAX) {
+    const text = typeof value === "string" ? value : String(value ?? "");
+    const escaped = text.replace(UNSAFE, (ch) => {
+        const code = ch.codePointAt(0) ?? 0;
+        return `\\u${code.toString(16).toUpperCase().padStart(4, "0")}`;
+    });
+    if (escaped.length <= max)
+        return escaped;
+    // Report the real length: "this name is 4 MB long" is itself worth knowing.
+    return `${escaped.slice(0, max)}... [truncated, ${text.length} chars]`;
+}
+//# sourceMappingURL=sanitize.js.map

package/dist/sanitize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.js","sourceRoot":"","sources":["../src/sanitize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,yEAAyE;AACzE,MAAM,SAAS,GAAG,6DAA6D,CAAC;AAEhF,6DAA6D;AAC7D,MAAM,OAAO,GAAG,gCAAgC,CAAC;AAEjD,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,OAAO,GAAG,SAAS,GAAG,EAAE,GAAG,CAAC,CAAC;AAE3D,wFAAwF;AACxF,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAEvC;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc,EAAE,MAAc,mBAAmB;IAC3E,MAAM,IAAI,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;IACrE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE;QAC1C,MAAM,IAAI,GAAG,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACpC,OAAO,MAAM,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;IAClE,CAAC,CAAC,CAAC;IACH,IAAI,OAAO,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,OAAO,CAAC;IAC1C,4EAA4E;IAC5E,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,mBAAmB,IAAI,CAAC,MAAM,SAAS,CAAC;AACzE,CAAC"}

package/dist/static-scan.d.ts

@@ -0,0 +1,110 @@
+import type { RulesetRef, Severity, WardenGate, WardenGateInput, WardenGateResult, WardenLogger } from "./types.js";
+/**
+ * Static tool-definition scanner.
+ *
+ * The MCP tool *description* and *input schema* are attacker-controlled text the
+ * model reads as trusted instructions — this is the tool-poisoning / prompt-
+ * injection surface. We scan that text (never the live tool output) for known
+ * signatures before a single token of it reaches the model. Cheap, deterministic,
+ * and runs first so later gates can reason about its findings.
+ *
+ * Rules are TIERED, and the tier is what decides blocking — not severity:
+ *
+ *   block  — no plausible benign reading in a tool definition. Blocks at the
+ *            policy threshold like any other finding.
+ *   advise — legitimately appears in honest tool definitions. Reported, never
+ *            blocks, never reduces the score, at any `blockAtSeverity`.
+ *
+ * Ruleset v1 had one tier, so `api_key` in a schema carried the same weight as
+ * "ignore all previous instructions". A GitHub-style server whose `create_issue`
+ * takes an `api_key` and mentions a personal access token scored 0.40 and had the
+ * tool blocked under the default policy — i.e. most real MCP servers were refused,
+ * which is how a scanner gets switched off entirely.
+ */
+type Tier = "block" | "advise";
+/**
+ * Which part of a tool definition a rule is meaningful against.
+ *
+ * `name` is an IDENTIFIER, not prose, and that difference decides the table
+ * below. A rule that keys on a noun - `api_key`, `private_key`, `.env` - matches
+ * ordinary identifiers (`sign_with_private_key` is a plausible wallet tool), so
+ * running it over names would refuse honest servers on their naming convention:
+ * exactly the ruleset v1 mistake, one surface over. A rule that keys on a PHRASE
+ * needs whitespace and cannot match `snake_case` at all, and the two hidden-payload
+ * rules are about characters that are never legitimate in a name.
+ *
+ * Names were scanned by nothing at all until ruleset v3, which meant zero-width
+ * characters and a base64 blob could sit in the one field that reaches the model
+ * first and WARDEN reported nothing.
+ */
+type Surface = "name" | "description" | "inputSchema";
+/**
+ * Ruleset version. Bump on ANY change to the table above — a scan result is only
+ * comparable to another scan made under the same version and digest.
+ *
+ * 1 — single tier; credential parameter names blocked real servers.
+ * 2 — block/advise tiers; exfil "send … to" anchored on an external destination;
+ *     TOOL_DEF_SECRET_HARVEST added so demoting the credential nouns does not
+ *     open a hole; advisory findings no longer affect the score.
+ * 3 — rules gained `surfaces`, and the tool NAME became a scanned surface. Until
+ *     v3 the name was scanned by nothing, so zero-width characters, a base64 blob
+ *     or an injection phrase in the one field that reaches the model first went
+ *     entirely unreported. Noun-keyed rules stay off the name on purpose: they
+ *     match ordinary identifiers, and refusing `sign_with_private_key` would be
+ *     the v1 calibration error committed on a new surface.
+ * 4 — calibrated against 1 108 live public MCP servers (docs/mcp-survey.md). v3
+ *     blocked 50 of them and only 4 held up on review, so v4 adds context
+ *     GUARDS — polarity, quotation, URI form, payload length, entropy, script
+ *     adjacency — and demotes four blocking rules the survey showed were
+ *     selecting for honest servers: the bare `exfiltrat*` noun, `system prompt`,
+ *     `do not tell the user`, and (in severity only) the credential nouns. A
+ *     rule's guards are part of this table and therefore of the digest.
+ */
+export declare const STATIC_SCAN_RULESET_VERSION = "4";
+export interface StaticScanRule {
+    code: string;
+    severity: Severity;
+    tier: Tier;
+    /** Which surfaces the rule is run against, so a re-run scans the same fields. */
+    surfaces: Surface[];
+    /** The regex source, so a third party can re-run the exact rule. */
+    source: string;
+    flags: string;
+    /**
+     * Which context guards this rule is subject to. Published because the regex
+     * alone no longer describes the rule: the same pattern with and without
+     * `polarity` reports different findings on the same text.
+     */
+    guards: string[];
+}
+export interface StaticScanRuleset extends RulesetRef {
+    rules: StaticScanRule[];
+}
+/**
+ * The rule table plus its digest, so a scan result stays checkable after the
+ * rules change.
+ *
+ * Sorted, so the digest depends on the rules and not on the order they happen to
+ * be declared in — and sorted by CODE-UNIT comparison, not `localeCompare`: the
+ * digest is a cross-machine identifier, and a locale-dependent collation would
+ * make the same rule table digest differently on a differently-configured host,
+ * which is exactly the divergence the digest exists to detect. The preimage is
+ * the RFC 8785 canonical form (see ./jcs.ts) so this file does not invent a
+ * second serialization of its own.
+ */
+export declare function staticScanRuleset(): StaticScanRuleset;
+/** Just the identity of the rule table, for embedding in a verdict. */
+export declare function staticScanRulesetRef(): RulesetRef;
+export declare class StaticScanGate implements WardenGate {
+    readonly name = "static-scan";
+    private readonly log;
+    /**
+     * @param log where dropped matches are reported. A guard silently discarding a
+     *   finding is the one behaviour in this gate that cannot be seen in the
+     *   verdict, so it is the one that most needs a debug line.
+     */
+    constructor(log?: WardenLogger);
+    evaluate(input: WardenGateInput): Promise<WardenGateResult>;
+}
+export {};
+//# sourceMappingURL=static-scan.d.ts.map

package/dist/static-scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-scan.d.ts","sourceRoot":"","sources":["../src/static-scan.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,UAAU,EACV,QAAQ,EAER,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,KAAK,IAAI,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE/B;;;;;;;;;;;;;;GAcG;AACH,KAAK,OAAO,GAAG,MAAM,GAAG,aAAa,GAAG,aAAa,CAAC;AAuZtD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAmB/C,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,IAAI,CAAC;IACX,iFAAiF;IACjF,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,iBAAkB,SAAQ,UAAU;IACnD,KAAK,EAAE,cAAc,EAAE,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,IAAI,iBAAiB,CAerD;AAOD,uEAAuE;AACvE,wBAAgB,oBAAoB,IAAI,UAAU,CAGjD;AAED,qBAAa,cAAe,YAAW,UAAU;IAC/C,QAAQ,CAAC,IAAI,iBAAiB;IAE9B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IAEnC;;;;OAIG;gBACS,GAAG,GAAE,YAA6B;IAIxC,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAoDlE"}