toolmoat 0.0.0-stage → 0.1.0

package/dist/patterns/indicators.js

@@ -0,0 +1,85 @@
+/**
+ * Credential and secret files whose contents are valuable to an attacker:
+ * SSH keys, cloud credentials, package registry tokens and so on.
+ */
+export const SENSITIVE_CRED_PATHS = [
+    { id: 'ssh-private-key', name: 'SSH private key', regex: /\.ssh[/\\]id_[a-z0-9]+\b/i },
+    { id: 'ssh-identity', name: 'SSH identity key', regex: /\.ssh[/\\][a-z0-9_.-]{0,40}(?:_rsa|_ed25519|_ecdsa|_dsa|\.pem)\b/i },
+    { id: 'aws-credentials', name: 'AWS credentials file', regex: /\.aws[/\\]credentials\b/i },
+    { id: 'gcloud-adc', name: 'gcloud application default credentials', regex: /application_default_credentials\.json/i },
+    { id: 'gcloud-credentials-db', name: 'gcloud credentials database', regex: /gcloud[/\\][a-z0-9_.-]{0,30}credentials\.db/i },
+    { id: 'azure-dir', name: 'Azure credential directory', regex: /\.azure[/\\]/i },
+    { id: 'kube-config', name: 'Kubernetes config', regex: /\.kube[/\\]config\b/i },
+    { id: 'docker-config', name: 'Docker config (registry auth)', regex: /\.docker[/\\]config\.json\b/i },
+    { id: 'netrc', name: '.netrc credentials', regex: /\.netrc\b/i },
+    { id: 'git-credentials', name: 'git stored credentials', regex: /\.git-credentials\b/i },
+    { id: 'npmrc', name: 'npm credentials (.npmrc)', regex: /\.npmrc\b/i },
+    { id: 'pypirc', name: 'PyPI credentials (.pypirc)', regex: /\.pypirc\b/i },
+    { id: 'gnupg', name: 'GnuPG keyring directory', regex: /\.gnupg[/\\]/i },
+    { id: 'etc-shadow', name: '/etc/shadow password hashes', regex: /\/etc\/shadow\b/ },
+];
+/**
+ * AI-agent and developer-tool config files that store API keys, OAuth tokens
+ * or that, once rewritten, make an injection persistent. The config scanner
+ * reuses this list for its own path matching.
+ */
+export const AGENT_CONFIG_PATHS = [
+    { id: 'claude-json', name: '~/.claude.json', regex: /\.claude\.json\b/i },
+    { id: 'claude-credentials', name: 'Claude credentials', regex: /\.claude[/\\]\.credentials\.json\b/i },
+    { id: 'claude-settings', name: 'Claude settings', regex: /\.claude[/\\]settings(?:\.local)?\.json\b/i },
+    { id: 'claude-desktop-config', name: 'Claude Desktop config', regex: /claude_desktop_config\.json\b/i },
+    { id: 'codex-auth', name: 'Codex auth', regex: /\.codex[/\\]auth\.json\b/i },
+    { id: 'codex-config', name: 'Codex config', regex: /\.codex[/\\]config\.toml\b/i },
+    { id: 'gh-hosts', name: 'GitHub CLI hosts', regex: /gh[/\\]hosts\.yml\b/i },
+    { id: 'openai-config', name: 'OpenAI config directory', regex: /\.config[/\\]openai\b/i },
+    { id: 'cursor-mcp', name: 'Cursor MCP config', regex: /\.cursor[/\\]mcp\.json\b/i },
+    { id: 'gemini-settings', name: 'Gemini settings', regex: /\.gemini[/\\]settings\.json\b/i },
+    { id: 'mcp-json', name: '.mcp.json', regex: /(?:^|[/\\])\.mcp\.json\b/i },
+    { id: 'claude-md', name: 'CLAUDE.md agent instructions', regex: /\bCLAUDE\.md\b/ },
+    { id: 'agents-md', name: 'AGENTS.md agent instructions', regex: /\bAGENTS\.md\b/ },
+    { id: 'claude-skills-dir', name: '~/.claude/skills', regex: /\.claude[/\\]skills\b/i },
+    { id: 'claude-plugins-dir', name: '~/.claude/plugins', regex: /\.claude[/\\]plugins\b/i },
+    { id: 'git-hooks-dir', name: '.git/hooks', regex: /\.git[/\\]hooks\b/i },
+];
+/**
+ * Hosts and URL shapes used to exfiltrate stolen data: webhook sinks, request
+ * bins, tunnels, out-of-band interaction services and anonymous file drops.
+ */
+export const EXFIL_HOSTS = [
+    { id: 'discord-webhook', name: 'Discord webhook', regex: /discord(?:app)?\.com\/api\/webhooks\//i, severity: 'high' },
+    { id: 'telegram-bot', name: 'Telegram bot API', regex: /api\.telegram\.org\/bot[^\s/"']{0,80}\/send(?:Message|Document|Photo)/i, severity: 'high' },
+    { id: 'webhook-site', name: 'webhook.site sink', regex: /\bwebhook\.site\//i, severity: 'high' },
+    { id: 'requestbin', name: 'RequestBin', regex: /\brequestbin\.[a-z]{2,10}\b/i, severity: 'high' },
+    { id: 'pipedream', name: 'Pipedream endpoint', regex: /\b[a-z0-9-]{1,40}\.m\.pipedream\.net\b/i, severity: 'high' },
+    { id: 'ngrok', name: 'ngrok tunnel', regex: /\b[a-z0-9-]{1,40}\.ngrok(?:-free)?\.(?:app|io)\b/i, severity: 'high' },
+    { id: 'cloudflare-tunnel', name: 'Cloudflare quick tunnel', regex: /\b[a-z0-9-]{1,60}\.trycloudflare\.com\b/i, severity: 'high' },
+    { id: 'interactsh', name: 'interact.sh OOB', regex: /\binteract\.sh\b/i, severity: 'high' },
+    { id: 'oast', name: 'OAST OOB domain', regex: /\b[a-z0-9.-]{1,60}\.oast\.(?:pro|live|site|fun|me|online)\b/i, severity: 'high' },
+    { id: 'burp-collaborator', name: 'Burp Collaborator', regex: /\b[a-z0-9.-]{0,60}burpcollaborator\.net\b/i, severity: 'high' },
+    { id: 'pastebin-api', name: 'Pastebin API', regex: /pastebin\.com\/(?:api|raw)\//i, severity: 'high' },
+    { id: 'transfer-sh', name: 'transfer.sh drop', regex: /(?:https?:\/\/)?transfer\.sh\/[A-Za-z0-9]/i, severity: 'high' },
+    { id: 'file-io', name: 'file.io drop', regex: /(?:https?:\/\/)?file\.io\/[A-Za-z0-9]/i, severity: 'high' },
+    { id: '0x0', name: '0x0.st drop', regex: /\b0x0\.st\b/i, severity: 'high' },
+    { id: 'temp-sh', name: 'temp.sh drop', regex: /(?:https?:\/\/)?temp\.sh\/[A-Za-z0-9]/i, severity: 'high' },
+    { id: 'termbin', name: 'termbin.com drop', regex: /\btermbin\.com\b/i, severity: 'high' },
+    { id: 'gofile', name: 'gofile.io drop', regex: /\bgofile\.io\b/i, severity: 'high' },
+    { id: 'bashupload', name: 'bashupload.com drop', regex: /\bbashupload\.com\b/i, severity: 'high' },
+];
+/**
+ * Living-off-the-land binaries abused to download and run payloads on Windows.
+ * Exported as plain names for other modules that want to match them.
+ */
+export const LOLBINS = [
+    'certutil',
+    'bitsadmin',
+    'mshta',
+    'regsvr32',
+    'rundll32',
+    'wmic',
+    'installutil',
+    'msbuild',
+    'cscript',
+    'wscript',
+    'curl',
+    'certreq',
+];

package/dist/patterns/secrets.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Credential patterns shared by the TM-SEC rules, report redaction and the
+ * proxy's egress guard. Every pattern must be linear-time: no nested
+ * quantifiers and bounded repetition only.
+ */
+export interface SecretPattern {
+    id: string;
+    name: string;
+    regex: RegExp;
+}
+export declare const SECRET_PATTERNS: readonly SecretPattern[];
+export interface SecretHit {
+    patternId: string;
+    name: string;
+    index: number;
+    length: number;
+}
+export declare function findSecrets(text: string, limit?: number): SecretHit[];
+/** Keeps the first 4 characters of each secret so a reader can recognise it, and masks the rest. */
+export declare function redactSecrets(text: string): string;

package/dist/patterns/secrets.js

@@ -0,0 +1,70 @@
+export const SECRET_PATTERNS = [
+    { id: 'private-key', name: 'Private key block', regex: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY(?: BLOCK)?-----/ },
+    { id: 'aws-access-key', name: 'AWS access key id', regex: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/ },
+    { id: 'github-token', name: 'GitHub token', regex: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,255}\b/ },
+    { id: 'github-fine-grained', name: 'GitHub fine-grained token', regex: /\bgithub_pat_[A-Za-z0-9_]{22,255}\b/ },
+    { id: 'anthropic-key', name: 'Anthropic API key', regex: /\bsk-ant-(?:api|admin|oat)[0-9]{2}-[A-Za-z0-9_-]{40,255}/ },
+    { id: 'openai-key', name: 'OpenAI API key', regex: /\bsk-(?:proj-|svcacct-|admin-)?[A-Za-z0-9_-]{20,255}T3BlbkFJ[A-Za-z0-9_-]{20,255}\b/ },
+    { id: 'openai-project-key', name: 'OpenAI project key', regex: /\bsk-proj-[A-Za-z0-9_-]{40,255}\b/ },
+    { id: 'google-api-key', name: 'Google API key', regex: /\bAIza[0-9A-Za-z_-]{35}\b/ },
+    { id: 'slack-token', name: 'Slack token', regex: /\bxox[abposr]-[A-Za-z0-9-]{10,255}\b/ },
+    { id: 'slack-webhook', name: 'Slack webhook URL', regex: /https:\/\/hooks\.slack\.com\/services\/T[A-Za-z0-9_]{6,20}\/B[A-Za-z0-9_]{6,20}\/[A-Za-z0-9_]{20,40}/ },
+    { id: 'stripe-live-key', name: 'Stripe live key', regex: /\b(?:sk|rk)_live_[A-Za-z0-9]{20,255}\b/ },
+    { id: 'npm-token', name: 'npm access token', regex: /\bnpm_[A-Za-z0-9]{36}\b/ },
+    { id: 'huggingface-token', name: 'Hugging Face token', regex: /\bhf_[A-Za-z0-9]{34,40}\b/ },
+    { id: 'gitlab-token', name: 'GitLab token', regex: /\bglpat-[A-Za-z0-9_-]{20,64}\b/ },
+    { id: 'telegram-bot-token', name: 'Telegram bot token', regex: /\b[0-9]{8,10}:AA[A-Za-z0-9_-]{33}\b/ },
+    { id: 'google-oauth-secret', name: 'Google OAuth client secret', regex: /\bGOCSPX-[A-Za-z0-9_-]{20,40}\b/ },
+    { id: 'groq-key', name: 'Groq API key', regex: /\bgsk_[A-Za-z0-9]{40,60}\b/ },
+    { id: 'xai-key', name: 'xAI API key', regex: /\bxai-[A-Za-z0-9]{40,120}\b/ },
+    { id: 'digitalocean-token', name: 'DigitalOcean token', regex: /\bdo[oprt]_v1_[a-f0-9]{64}\b/ },
+    { id: 'supabase-token', name: 'Supabase access token', regex: /\bsbp_[a-f0-9]{40}\b/ },
+    { id: 'sendgrid-key', name: 'SendGrid API key', regex: /\bSG\.[A-Za-z0-9_-]{16,32}\.[A-Za-z0-9_-]{32,64}\b/ },
+    { id: 'mailgun-key', name: 'Mailgun API key', regex: /\bkey-[0-9a-f]{32}\b/ },
+    { id: 'shopify-token', name: 'Shopify access token', regex: /\bshp(?:at|ca|pa|ss)_[a-fA-F0-9]{32}\b/ },
+    { id: 'twilio-sid', name: 'Twilio account SID', regex: /\bAC[0-9a-fA-F]{32}\b/ },
+    { id: 'twilio-api-key', name: 'Twilio API key SID', regex: /\bSK[0-9a-fA-F]{32}\b/ },
+    { id: 'azure-storage-key', name: 'Azure storage account key', regex: /AccountKey=[A-Za-z0-9+/]{86}==/ },
+    { id: 'discord-bot-token', name: 'Discord bot token', regex: /\b[MNO][A-Za-z0-9_-]{23,25}\.[A-Za-z0-9_-]{6}\.[A-Za-z0-9_-]{27,40}\b/ },
+    { id: 'jwt', name: 'JSON Web Token', regex: /\beyJ[A-Za-z0-9_-]{10,2000}\.eyJ[A-Za-z0-9_-]{10,4000}\.[A-Za-z0-9_-]{10,2000}/ },
+];
+export function findSecrets(text, limit = 50) {
+    const hits = [];
+    for (const pattern of SECRET_PATTERNS) {
+        const re = new RegExp(pattern.regex.source, pattern.regex.flags.includes('g') ? pattern.regex.flags : `${pattern.regex.flags}g`);
+        let match;
+        while (hits.length < limit && (match = re.exec(text)) !== null) {
+            hits.push({ patternId: pattern.id, name: pattern.name, index: match.index, length: match[0].length });
+            if (match[0].length === 0)
+                re.lastIndex++;
+        }
+    }
+    hits.sort((a, b) => a.index - b.index);
+    return dropOverlaps(hits);
+}
+function dropOverlaps(sorted) {
+    const out = [];
+    let end = -1;
+    for (const hit of sorted) {
+        if (hit.index >= end) {
+            out.push(hit);
+            end = hit.index + hit.length;
+        }
+    }
+    return out;
+}
+/** Keeps the first 4 characters of each secret so a reader can recognise it, and masks the rest. */
+export function redactSecrets(text) {
+    const hits = findSecrets(text, 1000);
+    if (hits.length === 0)
+        return text;
+    let out = '';
+    let cursor = 0;
+    for (const hit of hits) {
+        out += text.slice(cursor, hit.index);
+        const secret = text.slice(hit.index, hit.index + hit.length);
+        out += hit.patternId === 'private-key' ? secret : `${secret.slice(0, 4)}${'*'.repeat(8)}[redacted]`;
+        cursor = hit.index + hit.length;
+    }
+    return out + text.slice(cursor);
+}

package/dist/proxy/audit.d.ts

@@ -0,0 +1,53 @@
+import type { FindingSummary } from './lockfile.js';
+export type AuditEventName = 'start' | 'tools/list' | 'pinned' | 'blocked' | 'changed' | 'new' | 'flagged' | 'call' | 'secret' | 'injection' | 'server-request' | 'exit';
+export interface SecretSummary {
+    patternId: string;
+    name: string;
+}
+/** One JSONL line of the audit log. Argument values appear only with --log-args, and then redacted. */
+export interface AuditEvent {
+    ts: string;
+    server: string;
+    event: AuditEventName;
+    tool?: string;
+    decision?: string;
+    findings?: Array<FindingSummary | SecretSummary>;
+    /** Size of the JSON-encoded tool arguments. */
+    argBytes?: number;
+    args?: unknown;
+    /** Method of a server-to-client request. */
+    method?: string;
+    /** Short human-readable context, such as a block reason or a tool count. */
+    detail?: string;
+    /** Exit code of the server process. */
+    code?: number;
+}
+export type AuditInput = Omit<AuditEvent, 'ts' | 'server'>;
+/** Where the firewall reports events. Implementations must never throw. */
+export interface AuditSink {
+    write(event: AuditInput): void;
+}
+/**
+ * Append-only JSONL audit log written through a non-blocking stream. Any
+ * failure (unwritable directory, full disk) disables logging with one
+ * warning instead of disturbing the proxy.
+ */
+export declare class AuditLog implements AuditSink {
+    readonly file: string;
+    private readonly server;
+    private readonly warn;
+    private stream;
+    private failed;
+    constructor(file: string, server: string, warn?: (message: string) => void);
+    write(event: AuditInput): void;
+    /** Flushes and closes the stream. Resolves even when the log is broken or slow. */
+    close(timeoutMs?: number): Promise<void>;
+    private fail;
+}
+/** An audit sink that keeps events in memory, for tests and embedding. */
+export declare class MemoryAudit implements AuditSink {
+    readonly events: AuditInput[];
+    write(event: AuditInput): void;
+}
+/** Arguments as they may appear in the log with --log-args: secrets redacted, size capped. */
+export declare function loggableArgs(argsJson: string): unknown;

package/dist/proxy/audit.js

@@ -0,0 +1,79 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { redactSecrets } from '../patterns/secrets.js';
+const MAX_LOGGED_ARGS = 16 * 1024;
+/**
+ * Append-only JSONL audit log written through a non-blocking stream. Any
+ * failure (unwritable directory, full disk) disables logging with one
+ * warning instead of disturbing the proxy.
+ */
+export class AuditLog {
+    file;
+    server;
+    warn;
+    stream;
+    failed = false;
+    constructor(file, server, warn = () => { }) {
+        this.file = file;
+        this.server = server;
+        this.warn = warn;
+        try {
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            this.stream = fs.createWriteStream(file, { flags: 'a' });
+            this.stream.on('error', (error) => this.fail(error));
+        }
+        catch (error) {
+            this.fail(error);
+        }
+    }
+    write(event) {
+        if (this.failed || !this.stream)
+            return;
+        try {
+            this.stream.write(`${JSON.stringify({ ts: new Date().toISOString(), server: this.server, ...event })}\n`);
+        }
+        catch (error) {
+            this.fail(error);
+        }
+    }
+    /** Flushes and closes the stream. Resolves even when the log is broken or slow. */
+    close(timeoutMs = 2000) {
+        const stream = this.stream;
+        this.stream = undefined;
+        if (!stream || this.failed)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const timer = setTimeout(resolve, timeoutMs);
+            timer.unref();
+            stream.end(() => {
+                clearTimeout(timer);
+                resolve();
+            });
+        });
+    }
+    fail(error) {
+        if (this.failed)
+            return;
+        this.failed = true;
+        this.warn(`audit log disabled, cannot write ${this.file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** An audit sink that keeps events in memory, for tests and embedding. */
+export class MemoryAudit {
+    events = [];
+    write(event) {
+        this.events.push(event);
+    }
+}
+/** Arguments as they may appear in the log with --log-args: secrets redacted, size capped. */
+export function loggableArgs(argsJson) {
+    const redacted = redactSecrets(argsJson);
+    if (redacted.length > MAX_LOGGED_ARGS)
+        return `${redacted.slice(0, MAX_LOGGED_ARGS)}…[truncated]`;
+    try {
+        return JSON.parse(redacted);
+    }
+    catch {
+        return redacted;
+    }
+}

package/dist/proxy/canonical.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Canonical JSON for hashing and comparing tool definitions that come from an
+ * untrusted server. Same output as sorting keys and calling JSON.stringify,
+ * except that a key named "__proto__" is kept: assigning to it on a plain
+ * object sets the prototype instead of creating a property, so a schema
+ * carrying one would hash the same whatever it contained under that key, while
+ * the client still receives it.
+ */
+export declare function canonicalJson(value: unknown): string;
+/** The value for an own key only, so names such as "constructor" or "toString" are never mistaken for entries. */
+export declare function getOwn<T>(record: Readonly<Record<string, T>>, key: string): T | undefined;
+/** Sets an own property even for the key "__proto__" (plain assignment would replace the prototype). */
+export declare function setOwn<T>(record: Record<string, T>, key: string, value: T): void;

package/dist/proxy/canonical.js

@@ -0,0 +1,34 @@
+/**
+ * Canonical JSON for hashing and comparing tool definitions that come from an
+ * untrusted server. Same output as sorting keys and calling JSON.stringify,
+ * except that a key named "__proto__" is kept: assigning to it on a plain
+ * object sets the prototype instead of creating a property, so a schema
+ * carrying one would hash the same whatever it contained under that key, while
+ * the client still receives it.
+ */
+export function canonicalJson(value) {
+    return JSON.stringify(sortKeys(value));
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value !== null && typeof value === 'object') {
+        const source = value;
+        const out = {};
+        for (const key of Object.keys(source).sort()) {
+            const child = source[key];
+            if (child !== undefined)
+                Object.defineProperty(out, key, { value: sortKeys(child), enumerable: true, writable: true, configurable: true });
+        }
+        return out;
+    }
+    return value;
+}
+/** The value for an own key only, so names such as "constructor" or "toString" are never mistaken for entries. */
+export function getOwn(record, key) {
+    return Object.hasOwn(record, key) ? record[key] : undefined;
+}
+/** Sets an own property even for the key "__proto__" (plain assignment would replace the prototype). */
+export function setOwn(record, key, value) {
+    Object.defineProperty(record, key, { value, enumerable: true, writable: true, configurable: true });
+}

package/dist/proxy/diff.d.ts

@@ -0,0 +1,22 @@
+export type DiffOp = {
+    type: 'same' | 'removed' | 'added';
+    line: string;
+};
+/**
+ * Line diff based on a longest common subsequence. Common prefix and suffix
+ * are stripped first, so typical edits (an appended block in a description)
+ * cost almost nothing.
+ */
+export declare function diffLines(before: readonly string[], after: readonly string[]): DiffOp[];
+export interface Hunk {
+    ops: DiffOp[];
+}
+/** Groups a diff into hunks of changes with `context` unchanged lines around each. */
+export declare function hunks(ops: readonly DiffOp[], context?: number): Hunk[];
+/**
+ * Pretty-prints a tool definition for review: canonical key order, two-space
+ * indent, and strings that contain newlines spread over several lines so a
+ * diff shows exactly which lines of a description were added. The output is
+ * for humans and is not meant to be parsed back as JSON.
+ */
+export declare function prettyDefinition(value: unknown): string[];

package/dist/proxy/diff.js

@@ -0,0 +1,124 @@
+import { canonicalJson } from './canonical.js';
+/** Above this many LCS cells the middle of the diff is shown as a plain replace, keeping memory bounded. */
+const MAX_LCS_CELLS = 4_000_000;
+/**
+ * Line diff based on a longest common subsequence. Common prefix and suffix
+ * are stripped first, so typical edits (an appended block in a description)
+ * cost almost nothing.
+ */
+export function diffLines(before, after) {
+    let start = 0;
+    while (start < before.length && start < after.length && before[start] === after[start])
+        start++;
+    let endA = before.length;
+    let endB = after.length;
+    while (endA > start && endB > start && before[endA - 1] === after[endB - 1]) {
+        endA--;
+        endB--;
+    }
+    const ops = before.slice(0, start).map((line) => ({ type: 'same', line }));
+    ops.push(...diffMiddle(before.slice(start, endA), after.slice(start, endB)));
+    ops.push(...before.slice(endA).map((line) => ({ type: 'same', line })));
+    return ops;
+}
+function diffMiddle(a, b) {
+    const n = a.length;
+    const m = b.length;
+    if (n === 0 || m === 0 || (n + 1) * (m + 1) > MAX_LCS_CELLS) {
+        return [...a.map((line) => ({ type: 'removed', line })), ...b.map((line) => ({ type: 'added', line }))];
+    }
+    const width = m + 1;
+    const table = new Uint32Array((n + 1) * width);
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            table[i * width + j] = a[i] === b[j] ? table[(i + 1) * width + j + 1] + 1 : Math.max(table[(i + 1) * width + j], table[i * width + j + 1]);
+        }
+    }
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j]) {
+            ops.push({ type: 'same', line: a[i] });
+            i++;
+            j++;
+        }
+        else if (table[(i + 1) * width + j] >= table[i * width + j + 1]) {
+            ops.push({ type: 'removed', line: a[i++] });
+        }
+        else {
+            ops.push({ type: 'added', line: b[j++] });
+        }
+    }
+    while (i < n)
+        ops.push({ type: 'removed', line: a[i++] });
+    while (j < m)
+        ops.push({ type: 'added', line: b[j++] });
+    return ops;
+}
+/** Groups a diff into hunks of changes with `context` unchanged lines around each. */
+export function hunks(ops, context = 3) {
+    const changed = ops.map((op, index) => (op.type === 'same' ? -1 : index)).filter((index) => index !== -1);
+    const out = [];
+    let current;
+    for (const index of changed) {
+        const from = Math.max(0, index - context);
+        const to = Math.min(ops.length - 1, index + context);
+        if (current && from <= current.to + 1)
+            current.to = to;
+        else {
+            if (current)
+                out.push({ ops: ops.slice(current.from, current.to + 1) });
+            current = { from, to };
+        }
+    }
+    if (current)
+        out.push({ ops: ops.slice(current.from, current.to + 1) });
+    return out;
+}
+/**
+ * Pretty-prints a tool definition for review: canonical key order, two-space
+ * indent, and strings that contain newlines spread over several lines so a
+ * diff shows exactly which lines of a description were added. The output is
+ * for humans and is not meant to be parsed back as JSON.
+ */
+export function prettyDefinition(value) {
+    const normalized = value === undefined ? null : JSON.parse(canonicalJson(value));
+    const lines = [];
+    emit(normalized, '', '', '', lines);
+    return lines;
+}
+function emit(value, indent, prefix, suffix, lines) {
+    if (Array.isArray(value)) {
+        if (value.length === 0) {
+            lines.push(`${indent}${prefix}[]${suffix}`);
+            return;
+        }
+        lines.push(`${indent}${prefix}[`);
+        value.forEach((item, index) => emit(item, `${indent}  `, '', index < value.length - 1 ? ',' : '', lines));
+        lines.push(`${indent}]${suffix}`);
+        return;
+    }
+    if (value !== null && typeof value === 'object') {
+        const entries = Object.entries(value);
+        if (entries.length === 0) {
+            lines.push(`${indent}${prefix}{}${suffix}`);
+            return;
+        }
+        lines.push(`${indent}${prefix}{`);
+        entries.forEach(([key, child], index) => emit(child, `${indent}  `, `${JSON.stringify(key)}: `, index < entries.length - 1 ? ',' : '', lines));
+        lines.push(`${indent}}${suffix}`);
+        return;
+    }
+    if (typeof value === 'string' && value.includes('\n')) {
+        const parts = value.split('\n');
+        parts.forEach((part, index) => {
+            const body = JSON.stringify(part).slice(1, -1);
+            const open = index === 0 ? `${indent}${prefix}"` : `${indent}  `;
+            const close = index === parts.length - 1 ? `"${suffix}` : '\\n';
+            lines.push(`${open}${body}${close}`);
+        });
+        return;
+    }
+    lines.push(`${indent}${prefix}${JSON.stringify(value)}${suffix}`);
+}

package/dist/proxy/fingerprint.d.ts

@@ -0,0 +1,34 @@
+import type { EngineOptions } from '../scan/engine.js';
+import type { Finding, Rule } from '../types.js';
+/** The parts of an MCP tool that shape what the model sees and does. Only these are pinned. */
+export declare const FINGERPRINT_FIELDS: readonly ['name', 'title', 'description', 'inputSchema', 'outputSchema', 'annotations'];
+/** A tool definition reduced to the pinned fields, with keys in canonical order. */
+export type ToolDefinition = Record<string, unknown>;
+/** Picks the pinned fields of a raw tool object and normalizes key order so equal tools compare equal. */
+export declare function toolDefinition(tool: Record<string, unknown>): ToolDefinition;
+/** sha256 of the canonical JSON of the pinned fields: stable under key reordering, sensitive to any other change. */
+export declare function fingerprint(definition: ToolDefinition): string;
+export interface ModelText {
+    text: string;
+    /** True when the definition was too big to read to the end. */
+    truncated: boolean;
+}
+/**
+ * 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 declare function modelVisibleText(definition: ToolDefinition): string;
+/** Like modelVisibleText, and says when the definition was too big to read completely. Walks iteratively, so depth is no limit. */
+export declare function collectModelText(definition: ToolDefinition): ModelText;
+/** Synthetic path under which a live tool is reported, e.g. mcp://github/create_issue. */
+export declare function toolPath(server: string, tool: string): string;
+/** Runs the scanner's tool-definition rules over a tool's model-visible text. */
+export declare function scanTool(server: string, definition: ToolDefinition, rules: readonly Rule[], onRuleError?: EngineOptions['onRuleError']): Finding[];
+/** Runs the same rules over text a tool returned, which can carry injected instructions too. */
+export declare function scanToolOutput(server: string, tool: string, text: string, rules: readonly Rule[], onRuleError?: EngineOptions['onRuleError']): Finding[];
+/** Scans the `instructions` of a server's initialize result, which many clients add to the model's context. */
+export declare function scanServerInstructions(server: string, text: string, rules: readonly Rule[], onRuleError?: EngineOptions['onRuleError']): Finding[];