toolmoat 0.0.0-stage → 0.1.0

package/dist/proxy/fingerprint.js

@@ -0,0 +1,140 @@
+import { scanFile } from '../scan/engine.js';
+import { sha256 } from '../util/hash.js';
+import { canonicalJson } from './canonical.js';
+/** The parts of an MCP tool that shape what the model sees and does. Only these are pinned. */
+export const FINGERPRINT_FIELDS = ['name', 'title', 'description', 'inputSchema', 'outputSchema', 'annotations'];
+/** Picks the pinned fields of a raw tool object and normalizes key order so equal tools compare equal. */
+export function toolDefinition(tool) {
+    const picked = {};
+    for (const field of FINGERPRINT_FIELDS) {
+        if (tool[field] !== undefined)
+            picked[field] = tool[field];
+    }
+    return JSON.parse(canonicalJson(picked));
+}
+/** sha256 of the canonical JSON of the pinned fields: stable under key reordering, sensitive to any other change. */
+export function fingerprint(definition) {
+    return sha256(canonicalJson(definition));
+}
+/** Visiting more values than this means the definition cannot be read completely; see scanTool. */
+const MAX_NODES = 500_000;
+/** Keywords whose value is data the model reads as it is: every string below one counts. */
+const VALUE_KEYS = new Set(['default', 'const', 'enum', 'examples']);
+/** Schema keywords whose string is structure rather than prose. Every other string in a definition reaches the model. */
+const STRUCTURAL_KEYS = new Set([
+    'type', 'required', 'format', 'pattern', 'contentEncoding', 'contentMediaType',
+    '$schema', '$ref', '$id', '$anchor', '$dynamicRef', '$dynamicAnchor',
+]);
+/** Keywords whose object value maps names to schemas, so its keys are parameter names and not keywords. */
+const NAME_MAPS = new Set(['properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas']);
+/**
+ * Collects every string of a tool definition that ends up in the model's
+ * context: name, title, description, annotation titles and, inside the input
+ * and output schemas, every string except structural keywords (type, format,
+ * pattern, $ref...): descriptions, titles, comments, vendor extensions,
+ * parameter names, defaults, enums and examples, at any depth. Each piece goes
+ * on its own paragraph.
+ */
+export function modelVisibleText(definition) {
+    return collectModelText(definition).text;
+}
+/** Like modelVisibleText, and says when the definition was too big to read completely. Walks iteratively, so depth is no limit. */
+export function collectModelText(definition) {
+    const parts = [];
+    for (const key of ['name', 'title', 'description']) {
+        const value = definition[key];
+        if (typeof value === 'string' && value)
+            parts.push(value);
+    }
+    let nodes = 0;
+    let truncated = false;
+    const stack = [definition.outputSchema, definition.inputSchema, definition.annotations].map((value) => ({ value, data: false, names: false }));
+    while (stack.length > 0) {
+        const { value, data, names } = stack.pop();
+        if (++nodes > MAX_NODES) {
+            truncated = true;
+            break;
+        }
+        if (typeof value === 'string') {
+            if (value)
+                parts.push(value);
+            continue;
+        }
+        if (value === null || typeof value !== 'object')
+            continue;
+        if (Array.isArray(value)) {
+            for (let i = value.length - 1; i >= 0; i--)
+                stack.push({ value: value[i], data, names: false });
+            continue;
+        }
+        const record = value;
+        const entries = Object.entries(record);
+        if (!names && !data && isPlainObject(record.properties)) {
+            const propertyNames = Object.keys(record.properties);
+            if (propertyNames.length > 0)
+                parts.push(`Parameters: ${propertyNames.join(', ')}`);
+        }
+        for (let i = entries.length - 1; i >= 0; i--) {
+            const [key, child] = entries[i];
+            if (names) {
+                stack.push({ value: child, data: false, names: false });
+            }
+            else if (typeof child === 'string') {
+                if (data || !STRUCTURAL_KEYS.has(key))
+                    stack.push({ value: child, data, names: false });
+            }
+            else if (Array.isArray(child) && child.every((item) => typeof item === 'string')) {
+                const strings = child.filter((item) => item.length > 0);
+                if ((data || !STRUCTURAL_KEYS.has(key)) && strings.length > 0)
+                    parts.push(strings.join('\n'));
+            }
+            else {
+                stack.push({ value: child, data: data || VALUE_KEYS.has(key), names: !data && NAME_MAPS.has(key) && isPlainObject(child) });
+            }
+        }
+    }
+    return { text: parts.join('\n\n'), truncated };
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** Synthetic path under which a live tool is reported, e.g. mcp://github/create_issue. */
+export function toolPath(server, tool) {
+    return `mcp://${server}/${tool}`;
+}
+/** Runs the scanner's tool-definition rules over a tool's model-visible text. */
+export function scanTool(server, definition, rules, onRuleError) {
+    const name = typeof definition.name === 'string' ? definition.name : '';
+    const path = toolPath(server, name);
+    const { text, truncated } = collectModelText(definition);
+    const file = { kind: 'tool-definition', path, displayPath: path, target: server, content: text };
+    const findings = scanFile(file, onRuleError ? { rules, onRuleError } : { rules });
+    if (truncated)
+        findings.push(unreadableFinding(server, path));
+    return findings;
+}
+/** A definition the scanner could not read to the end may hide text in the part it skipped, so it is treated as flagged. */
+function unreadableFinding(server, path) {
+    return {
+        ruleId: 'TM-PROXY-001',
+        severity: 'high',
+        category: 'obfuscation',
+        title: 'Tool definition too large to inspect',
+        message: `The definition has more than ${MAX_NODES} values, so toolmoat cannot check all of it for hidden instructions`,
+        file: path,
+        target: server,
+        remediation: 'Review the definition with toolmoat diff and approve it only if the server is trusted.',
+    };
+}
+/** Runs the same rules over text a tool returned, which can carry injected instructions too. */
+export function scanToolOutput(server, tool, text, rules, onRuleError) {
+    return scanText(server, `${toolPath(server, tool)}#output`, text, rules, onRuleError);
+}
+/** Scans the `instructions` of a server's initialize result, which many clients add to the model's context. */
+export function scanServerInstructions(server, text, rules, onRuleError) {
+    return scanText(server, `mcp://${server}#instructions`, text, rules, onRuleError);
+}
+function scanText(server, path, text, rules, onRuleError) {
+    const file = { kind: 'tool-definition', path, displayPath: path, target: server, content: text };
+    return scanFile(file, onRuleError ? { rules, onRuleError } : { rules });
+}

package/dist/proxy/firewall.d.ts

@@ -0,0 +1,132 @@
+import type { Rule } from '../types.js';
+import type { AuditSink, SecretSummary } from './audit.js';
+import type { FindingSummary, PendingReason } from './lockfile.js';
+import type { Mode, OnNew } from './policy.js';
+export interface ProxyOptions {
+    /** Server id in the lockfile. */
+    server: string;
+    /** The server's command line as recorded in the lockfile. */
+    commandLine: string;
+    lockPath: string;
+    /** Default enforce. */
+    mode?: Mode;
+    /** Default block. */
+    onNew?: OnNew;
+    /** Secret pattern ids (see SECRET_PATTERNS) that the egress guard lets through. */
+    allowSecrets?: readonly string[];
+    /** Rules for scanning tool definitions and tool output. Default: allRules. */
+    rules?: readonly Rule[];
+    audit?: AuditSink;
+    /** Record tool-call arguments in the audit log, after secret redaction. */
+    logArgs?: boolean;
+    /** Receives one-line diagnostics. Default: stderr with an [toolmoat] prefix. */
+    diag?: (message: string) => void;
+    now?: () => Date;
+}
+/** What to do with one line read from a peer. */
+export interface Routed {
+    /** Forward the original bytes unchanged. */
+    passOriginal: boolean;
+    /** Lines to forward after the original, or instead of it when passOriginal is false. */
+    onward: string[];
+    /** Lines to send back to the peer the line came from. */
+    back: string[];
+}
+type BlockReason = PendingReason | 'unlisted' | 'lockfile';
+/**
+ * The protocol half of the runtime firewall. It sees every JSON-RPC line in
+ * both directions and decides what is forwarded, rewritten or answered
+ * locally: tool lists are fingerprinted against the lockfile and scanned,
+ * held tools are hidden from the model and their calls refused, tool-call
+ * arguments go through the egress guard, and tool output and the server's
+ * initialize instructions are scanned for injected instructions. It does no process or stream IO, so it can be driven
+ * directly from tests.
+ */
+export declare class Firewall {
+    private readonly server;
+    private readonly commandLine;
+    private readonly lockPath;
+    private readonly mode;
+    private readonly onNew;
+    private readonly allowSecrets;
+    private readonly rules;
+    private readonly sink;
+    private readonly logArgs;
+    private readonly diagSink;
+    private readonly now;
+    private readonly listRequests;
+    private readonly callRequests;
+    private readonly initRequests;
+    private readonly lastSeen;
+    private readonly reported;
+    private blocked;
+    private allowed;
+    private startEntry;
+    private entryExists;
+    private listed;
+    private trustOnFirstUse;
+    private clientReady;
+    /** The lockfile could not be read during a listing and every tool was hidden because of it. */
+    private lockBroken;
+    private scans;
+    /** Tool calls that arrived while the first tool list was still on its way; decided once it lands. */
+    private held;
+    /** Throws LockfileError when the lockfile exists but cannot be read: the proxy must not start unverified. */
+    constructor(options: ProxyOptions);
+    /** Tools waiting for review in the lockfile stay held until they are approved. */
+    private holdPending;
+    /** Handles one line from the MCP client on its way to the server. */
+    fromClient(text: string): Routed;
+    /** Handles one line from the MCP server on its way to the client. */
+    fromServer(text: string): Routed;
+    /**
+     * A server line that looks like JSON but does not parse cannot be checked, and a more lenient
+     * reader at the other end (another JSON parser, a client that trims or repairs lines) might still
+     * accept it as a tool list. In enforce mode it never reaches the client.
+     */
+    private unparseable;
+    /** Decides the calls held during the first listing: refusals go to the client, the rest on to the server. */
+    private releaseHeld;
+    /**
+     * Called when the lockfile changes on disk, typically after `toolmoat
+     * approve`. Held tools whose current definition is now pinned are released,
+     * and the client is asked to reload its tool list so the model sees them.
+     * Returns the lines to send to the client.
+     */
+    lockChanged(): string[];
+    /** Resolves when background scans of tool output and server instructions have finished. */
+    idle(): Promise<void>;
+    /** Returns a reply to send back instead of forwarding, 'hold' to park the message, or undefined to forward it. */
+    private onClientMessage;
+    private onToolCall;
+    private callBlock;
+    private leakedSecrets;
+    private onServerMessage;
+    private onToolList;
+    private lockfileFailure;
+    /** Records decisions in the lockfile. A listing that changes nothing does not even take the file lock. */
+    private persist;
+    private updateState;
+    private report;
+    private reportOnce;
+    private scheduleOutputScan;
+    private scheduleInstructionsScan;
+    /** Queues a background scan; traffic never waits for it. Reports high and critical findings only. */
+    private scheduleScan;
+    private readEntry;
+    /** A rule that throws is skipped for that text; say so once, since its check is missing from every later decision. */
+    private readonly onRuleError;
+    private audit;
+    private diag;
+    private label;
+}
+/** The text a tool result puts in front of the model: text items, embedded text resources, resource links and structured content. */
+export declare function outputText(result: unknown): string;
+/** The text the model gets instead of a tool result when a call to a held tool is refused. */
+export declare function blockedCallText(server: string, tool: string, block: {
+    reason: BlockReason;
+    findings: readonly FindingSummary[];
+}): string;
+/** The text the model gets when the egress guard refuses a call. Names the credential type, never the value. */
+export declare function secretCallText(server: string, tool: string, secrets: readonly SecretSummary[]): string;
+export {};