@intutic/shared-types 2.2.0 → 2.3.0

package/dist/mcpRegistryRecord.js

@@ -0,0 +1,229 @@
+"use strict";
+/**
+ * The workspace's MCP server registry decisions, as the gates apply them.
+ *
+ * An owner or admin approves or blocks each MCP server on the MCP Servers
+ * page, disables tools within one, and sets what happens to a server nobody
+ * has decided on (`mcpDefaultPolicy`); a high-risk tool-set change can send a
+ * server back to the queue. The control plane serves those decisions as
+ * `mcpRegistry` on `GET /api/v1/policy/resolve`. The MCP proxy applies them to
+ * the servers it fronts; the sync daemon writes them into the policy snapshot
+ * as an `@mcp_registry` record so the harness hook gates apply them to every
+ * `mcp__<server>__<tool>` call, the servers no proxy fronts included.
+ *
+ * {@link evaluateMcpRegistry} is the one decision. The MCP proxy and the
+ * control plane's hook gate call it, the JavaScript hook gates embed its
+ * source ({@link MCP_REGISTRY_JS_SOURCE}), `@intutic/gate` carries a
+ * byte-identical copy of this file, and the bash gates and `intutic-clawde`
+ * run its Python transliteration (`intutic_clawde/gate/mcp_registry.py`);
+ * `fixtures/mcp-registry-vectors.json` holds all of them to the same codes,
+ * rule ids and reasons.
+ *
+ * The workspace's `mcpAllowedServers` list rides beside it as an
+ * `@mcp_allowlist` record ({@link evaluateMcpAllowlist}). Both records sit
+ * inside the snapshot's digest, and a gate that finds the snapshot unverified
+ * (its digest broken or missing, or another workspace's) trusts neither: it
+ * refuses every MCP call with {@link mcpSnapshotUnverifiedRefusal}, at `block`
+ * even in an observe-only workspace. An edit that widens either record, or
+ * deletes one, therefore admits nothing. A policy activates only when it
+ * verifies; the sync daemon restores the last snapshot it verified.
+ *
+ * Self-contained (no imports) so `@intutic/gate`, which has no workspace
+ * dependencies, can carry the copy.
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCP_ALLOWLIST_RECORD_TAG = exports.MCP_SNAPSHOT_UNVERIFIED_JS_SOURCE = exports.MCP_ALLOWLIST_JS_SOURCE = exports.MCP_REGISTRY_RECORD_TAG = exports.MCP_REGISTRY_JS_SOURCE = void 0;
+exports.evaluateMcpRegistry = evaluateMcpRegistry;
+exports.parseMcpRegistryRecord = parseMcpRegistryRecord;
+exports.isUnrestrictedMcpRegistry = isUnrestrictedMcpRegistry;
+exports.encodeMcpRegistryRecord = encodeMcpRegistryRecord;
+exports.decodeMcpRegistryRecord = decodeMcpRegistryRecord;
+exports.evaluateMcpAllowlist = evaluateMcpAllowlist;
+exports.mcpSnapshotUnverifiedRefusal = mcpSnapshotUnverifiedRefusal;
+exports.encodeMcpAllowlistRecord = encodeMcpAllowlistRecord;
+exports.decodeMcpAllowlistRecord = decodeMcpAllowlistRecord;
+/**
+ * Decides one MCP tool call against the registry: a blocked server, then a
+ * held one, then — under `deny` — one not approved, then a disabled tool.
+ * Null lets the call continue.
+ *
+ * Self-contained (no imports, no module state) because the JavaScript hook
+ * gates run it as emitted source.
+ */
+function evaluateMcpRegistry(registry, serverName, toolName) {
+    if (registry.blockedServers.indexOf(serverName) !== -1) {
+        return {
+            code: 'SERVER_BLOCKED',
+            ruleId: 'mcp_registry.' + serverName,
+            reason: 'MCP server "' + serverName + '" is blocked in this workspace\'s MCP server registry. ' +
+                'An owner or admin can change that on the MCP Servers page.',
+        };
+    }
+    if (registry.heldServers.indexOf(serverName) !== -1) {
+        return {
+            code: 'SERVER_HELD',
+            ruleId: 'mcp_registry.' + serverName,
+            reason: 'MCP server "' + serverName + '" changed its tools in a way scored high risk, and this workspace ' +
+                'holds such a server until it is approved again. It is waiting in the approval queue on the MCP ' +
+                'Servers page for an owner or admin.',
+        };
+    }
+    if (registry.defaultPolicy === 'deny' && registry.approvedServers.indexOf(serverName) === -1) {
+        return {
+            code: 'SERVER_NOT_APPROVED',
+            ruleId: 'mcpDefaultPolicy',
+            reason: 'MCP server "' + serverName + '" is not approved in this workspace\'s MCP server registry, ' +
+                'and the workspace refuses unapproved servers (mcpDefaultPolicy: deny). It is waiting in ' +
+                'the approval queue on the MCP Servers page for an owner or admin.',
+        };
+    }
+    const disabled = Object.prototype.hasOwnProperty.call(registry.disabledTools, serverName)
+        ? registry.disabledTools[serverName]
+        : undefined;
+    if (disabled && disabled.indexOf(toolName) !== -1) {
+        return {
+            code: 'TOOL_DISABLED',
+            ruleId: 'mcp_registry.' + serverName + '.' + toolName,
+            reason: 'Tool "' + toolName + '" is disabled on MCP server "' + serverName + '" in this workspace\'s ' +
+                'MCP server registry. An owner or admin can re-enable it on the MCP Servers page.',
+        };
+    }
+    return null;
+}
+/** {@link evaluateMcpRegistry} as source, for the JavaScript hook gates. */
+exports.MCP_REGISTRY_JS_SOURCE = evaluateMcpRegistry.toString();
+function stringList(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === 'string') : [];
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Reads `mcpRegistry` as the control plane sends it. Null for anything that is
+ * not a registry object; wrong-typed lists read as empty, and any default but
+ * `deny` reads as `allow`, the control plane's own reading of the setting.
+ */
+function parseMcpRegistryRecord(value) {
+    if (!isPlainObject(value))
+        return null;
+    const disabledTools = {};
+    if (isPlainObject(value['disabledTools'])) {
+        for (const [server, tools] of Object.entries(value['disabledTools'])) {
+            const list = stringList(tools);
+            if (list.length > 0)
+                disabledTools[server] = list;
+        }
+    }
+    return {
+        defaultPolicy: value['defaultPolicy'] === 'deny' ? 'deny' : 'allow',
+        approvedServers: stringList(value['approvedServers']),
+        blockedServers: stringList(value['blockedServers']),
+        heldServers: stringList(value['heldServers']),
+        disabledTools,
+    };
+}
+/** Whether a registry refuses nothing: no snapshot record is written for one. */
+function isUnrestrictedMcpRegistry(registry) {
+    return (registry.defaultPolicy === 'allow' &&
+        registry.blockedServers.length === 0 &&
+        registry.heldServers.length === 0 &&
+        Object.keys(registry.disabledTools).length === 0);
+}
+/**
+ * First column of the record's line in `policy-snapshot.rules`. A data line,
+ * like `@sso_groups`, so the digest every gate recomputes covers it; two
+ * columns, so every rule parser (which needs six) skips it.
+ */
+exports.MCP_REGISTRY_RECORD_TAG = '@mcp_registry';
+function toBase64(text) {
+    let binary = '';
+    for (const byte of new TextEncoder().encode(text))
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+function fromBase64(b64) {
+    return new TextDecoder('utf-8', { fatal: true }).decode(Uint8Array.from(atob(b64), (c) => c.charCodeAt(0)));
+}
+/** The record as one `.rules` line: the tag, a tab, base64 of its JSON. */
+function encodeMcpRegistryRecord(registry) {
+    return `${exports.MCP_REGISTRY_RECORD_TAG}\t${toBase64(JSON.stringify(registry))}`;
+}
+/** Reads a record line back; null for any other line or a damaged one. */
+function decodeMcpRegistryRecord(line) {
+    const [tag, b64, ...rest] = line.split('\t');
+    if (tag !== exports.MCP_REGISTRY_RECORD_TAG || !b64 || rest.length > 0)
+        return null;
+    try {
+        return parseMcpRegistryRecord(JSON.parse(fromBase64(b64)));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Decides one MCP call's server against the allowlist. Null lets the call
+ * continue; a refusal under `shadow` is recorded, not enforced, by the caller.
+ *
+ * Self-contained, like {@link evaluateMcpRegistry}, because the JavaScript
+ * hook gates run it as emitted source.
+ */
+function evaluateMcpAllowlist(allowlist, serverName) {
+    if (allowlist.servers.indexOf(serverName) !== -1)
+        return null;
+    return {
+        code: 'SERVER_NOT_ALLOWED',
+        ruleId: 'mcp_allowlist',
+        reason: 'MCP server "' + serverName + '" is not on the MCP server allowlist for this workspace',
+    };
+}
+/** {@link evaluateMcpAllowlist} as source, for the JavaScript hook gates. */
+exports.MCP_ALLOWLIST_JS_SOURCE = evaluateMcpAllowlist.toString();
+/**
+ * Refuses one MCP call because the policy snapshot failed its digest or
+ * workspace check. Neither the registry's approvals nor the allowlist's
+ * servers can be vouched for then, and a deleted record is indistinguishable
+ * from one the workspace never set, so the snapshot admits no MCP server at
+ * all. Every gate that reads the snapshot refuses with this, at `block`.
+ *
+ * Self-contained, like {@link evaluateMcpRegistry}, because the JavaScript
+ * hook gates run it as emitted source.
+ */
+function mcpSnapshotUnverifiedRefusal(serverName) {
+    return {
+        code: 'POLICY_SNAPSHOT_UNVERIFIED',
+        ruleId: 'policy_snapshot',
+        reason: 'MCP server "' + serverName + '" is refused because the policy snapshot on this machine failed its ' +
+            'integrity check, so its MCP server registry and allowlist admit no server until the sync daemon ' +
+            'restores a verified snapshot',
+    };
+}
+/** {@link mcpSnapshotUnverifiedRefusal} as source, for the JavaScript hook gates. */
+exports.MCP_SNAPSHOT_UNVERIFIED_JS_SOURCE = mcpSnapshotUnverifiedRefusal.toString();
+/**
+ * First column of the allowlist's line in `policy-snapshot.rules`. A data
+ * line, so the digest covers it and a server added to the list by hand fails
+ * the check; three columns, so every rule parser skips it.
+ */
+exports.MCP_ALLOWLIST_RECORD_TAG = '@mcp_allowlist';
+/**
+ * The allowlist as one `.rules` line: the tag, the severity and the server
+ * names joined by commas, tab-separated. Plain text, so the bash gates read
+ * it with parameter expansion; the snapshot writer drops a name holding
+ * whitespace or a comma.
+ */
+function encodeMcpAllowlistRecord(allowlist) {
+    return `${exports.MCP_ALLOWLIST_RECORD_TAG}\t${allowlist.severity}\t${allowlist.servers.join(',')}`;
+}
+/**
+ * Reads an allowlist line back; null for any other line. A severity other
+ * than `shadow` reads as `block`, so a damaged one refuses.
+ */
+function decodeMcpAllowlistRecord(line) {
+    const [tag, severity, servers, ...rest] = line.split('\t');
+    if (tag !== exports.MCP_ALLOWLIST_RECORD_TAG || severity === undefined || servers === undefined || rest.length > 0)
+        return null;
+    return { severity: severity === 'shadow' ? 'shadow' : 'block', servers: servers.split(',').filter(Boolean) };
+}
+//# sourceMappingURL=mcpRegistryRecord.js.map

package/dist/mcpRegistryRecord.js.map

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

package/dist/mcpToolRisk.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Risk score for a change to an MCP server's tool set.
+ *
+ * When a server the registry already knows declares a different tool set — a
+ * tool added or removed, a description or input schema changed — the control
+ * plane scores the change with {@link scoreToolSetChange} and stores the score
+ * and its reasons on the registry's change record
+ * (`services/control-plane/src/services/mcpRegistryService.ts`).
+ *
+ * Rules only, no model: the same two tool sets always produce the same score
+ * and the same reasons, in the same order, so a score can be reproduced from
+ * the stored definitions and argued with. Each rule adds points:
+ *
+ * | rule                   | points | when                                                         |
+ * |------------------------|--------|--------------------------------------------------------------|
+ * | `description_poisoned` | 60     | a new or changed description matches a poisoning pattern it did not match before |
+ * | `new_tool_capability`  | 20–40  | a new tool's name or description implies write, network, exec or credential access (per capability) |
+ * | `capability_gained`    | 20–40  | a changed tool implies a capability it did not before (per capability) |
+ * | `confirmation_removed` | 35     | a changed tool lost a confirmation or dry-run argument, or stopped requiring or defaulting it |
+ * | `schema_widened`       | 15     | a changed tool accepts more than before: new arguments, fewer required ones, lifted enums, patterns or limits |
+ * | `tool_added`           | 5      | a new tool none of the rules above flag                      |
+ * | `description_changed`  | 5      | a changed description none of the rules above flag          |
+ *
+ * Capability points: exec 40, credential 40, network 25, write 20. A removed
+ * tool adds nothing: it narrows what an agent can do. The score is the sum,
+ * capped at 100; 50 or more is `high`, 20 or more `medium`, anything above 0
+ * `low`.
+ *
+ * @module
+ */
+/** One tool as a server declares it in `tools/list`. */
+export interface McpToolDefinition {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+}
+/**
+ * How much of a definition the registry keeps. A longer description is cut
+ * here (its scanned prefix is what the risk score sees); a larger input
+ * schema is left out. Real servers' tools sit far below both.
+ */
+export declare const MAX_TOOL_DESCRIPTION_CHARS = 8192;
+export declare const MAX_TOOL_SCHEMA_CHARS = 16384;
+/**
+ * One `tools/list` entry as the registry stores it: the name, the description
+ * cut to {@link MAX_TOOL_DESCRIPTION_CHARS}, and the input schema when it is an
+ * object no larger than {@link MAX_TOOL_SCHEMA_CHARS} serialised. `null` for an
+ * entry without a name.
+ */
+export declare function normalizeToolDefinition(raw: unknown): McpToolDefinition | null;
+export type McpToolCapability = 'exec' | 'credential' | 'network' | 'write';
+export type McpToolRiskRule = 'description_poisoned' | 'new_tool_capability' | 'capability_gained' | 'confirmation_removed' | 'schema_widened' | 'tool_added' | 'description_changed';
+export type McpToolRiskLevel = 'none' | 'low' | 'medium' | 'high';
+export interface McpToolRiskReason {
+    rule: McpToolRiskRule;
+    tool: string;
+    points: number;
+    /** What the rule saw, in words. */
+    detail: string;
+}
+export interface McpToolSetChange {
+    added: string[];
+    removed: string[];
+    /** Tools present before and after whose description or input schema differs. */
+    changed: string[];
+    /** 0–100. */
+    score: number;
+    level: McpToolRiskLevel;
+    /** Sorted by tool, then rule. */
+    reasons: McpToolRiskReason[];
+}
+export declare const MCP_TOOL_RISK_HIGH = 50;
+export declare const MCP_TOOL_RISK_MEDIUM = 20;
+export declare const MCP_TOOL_CAPABILITY_POINTS: Readonly<Record<McpToolCapability, number>>;
+export declare function riskLevelOf(score: number): McpToolRiskLevel;
+/**
+ * Compares the tool set a server declared before with the one it declares
+ * now. Tools are matched by name; order and duplicate names (the first wins)
+ * do not affect the result.
+ */
+export declare function scoreToolSetChange(previous: readonly McpToolDefinition[], next: readonly McpToolDefinition[]): McpToolSetChange;
+//# sourceMappingURL=mcpToolRisk.d.ts.map

package/dist/mcpToolRisk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpToolRisk.d.ts","sourceRoot":"","sources":["../src/mcpToolRisk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,wDAAwD;AACxD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAED;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,OAAQ,CAAA;AAC/C,eAAO,MAAM,qBAAqB,QAAS,CAAA;AAE3C;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,iBAAiB,GAAG,IAAI,CAY9E;AAED,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,YAAY,GAAG,SAAS,GAAG,OAAO,CAAA;AAE3E,MAAM,MAAM,eAAe,GACvB,sBAAsB,GACtB,qBAAqB,GACrB,mBAAmB,GACnB,sBAAsB,GACtB,gBAAgB,GAChB,YAAY,GACZ,qBAAqB,CAAA;AAEzB,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEjE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,eAAe,CAAA;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,gFAAgF;IAChF,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,aAAa;IACb,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,gBAAgB,CAAA;IACvB,iCAAiC;IACjC,OAAO,EAAE,iBAAiB,EAAE,CAAA;CAC7B;AAED,eAAO,MAAM,kBAAkB,KAAK,CAAA;AACpC,eAAO,MAAM,oBAAoB,KAAK,CAAA;AAEtC,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAKlF,CAAA;AA4LD,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAI3D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EACtC,IAAI,EAAE,SAAS,iBAAiB,EAAE,GACjC,gBAAgB,CAmElB"}

package/dist/mcpToolRisk.js

@@ -0,0 +1,334 @@
+"use strict";
+/**
+ * Risk score for a change to an MCP server's tool set.
+ *
+ * When a server the registry already knows declares a different tool set — a
+ * tool added or removed, a description or input schema changed — the control
+ * plane scores the change with {@link scoreToolSetChange} and stores the score
+ * and its reasons on the registry's change record
+ * (`services/control-plane/src/services/mcpRegistryService.ts`).
+ *
+ * Rules only, no model: the same two tool sets always produce the same score
+ * and the same reasons, in the same order, so a score can be reproduced from
+ * the stored definitions and argued with. Each rule adds points:
+ *
+ * | rule                   | points | when                                                         |
+ * |------------------------|--------|--------------------------------------------------------------|
+ * | `description_poisoned` | 60     | a new or changed description matches a poisoning pattern it did not match before |
+ * | `new_tool_capability`  | 20–40  | a new tool's name or description implies write, network, exec or credential access (per capability) |
+ * | `capability_gained`    | 20–40  | a changed tool implies a capability it did not before (per capability) |
+ * | `confirmation_removed` | 35     | a changed tool lost a confirmation or dry-run argument, or stopped requiring or defaulting it |
+ * | `schema_widened`       | 15     | a changed tool accepts more than before: new arguments, fewer required ones, lifted enums, patterns or limits |
+ * | `tool_added`           | 5      | a new tool none of the rules above flag                      |
+ * | `description_changed`  | 5      | a changed description none of the rules above flag          |
+ *
+ * Capability points: exec 40, credential 40, network 25, write 20. A removed
+ * tool adds nothing: it narrows what an agent can do. The score is the sum,
+ * capped at 100; 50 or more is `high`, 20 or more `medium`, anything above 0
+ * `low`.
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCP_TOOL_CAPABILITY_POINTS = exports.MCP_TOOL_RISK_MEDIUM = exports.MCP_TOOL_RISK_HIGH = exports.MAX_TOOL_SCHEMA_CHARS = exports.MAX_TOOL_DESCRIPTION_CHARS = void 0;
+exports.normalizeToolDefinition = normalizeToolDefinition;
+exports.riskLevelOf = riskLevelOf;
+exports.scoreToolSetChange = scoreToolSetChange;
+const toolPoison_js_1 = require("./toolPoison.js");
+/**
+ * How much of a definition the registry keeps. A longer description is cut
+ * here (its scanned prefix is what the risk score sees); a larger input
+ * schema is left out. Real servers' tools sit far below both.
+ */
+exports.MAX_TOOL_DESCRIPTION_CHARS = 8_192;
+exports.MAX_TOOL_SCHEMA_CHARS = 16_384;
+/**
+ * One `tools/list` entry as the registry stores it: the name, the description
+ * cut to {@link MAX_TOOL_DESCRIPTION_CHARS}, and the input schema when it is an
+ * object no larger than {@link MAX_TOOL_SCHEMA_CHARS} serialised. `null` for an
+ * entry without a name.
+ */
+function normalizeToolDefinition(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const entry = raw;
+    const name = entry['name'];
+    if (typeof name !== 'string' || name.length === 0 || name.length > 256)
+        return null;
+    const def = { name };
+    if (typeof entry['description'] === 'string')
+        def.description = entry['description'].slice(0, exports.MAX_TOOL_DESCRIPTION_CHARS);
+    const schema = entry['inputSchema'];
+    if (schema !== null && typeof schema === 'object' && !Array.isArray(schema) && JSON.stringify(schema).length <= exports.MAX_TOOL_SCHEMA_CHARS) {
+        def.inputSchema = schema;
+    }
+    return def;
+}
+exports.MCP_TOOL_RISK_HIGH = 50;
+exports.MCP_TOOL_RISK_MEDIUM = 20;
+exports.MCP_TOOL_CAPABILITY_POINTS = {
+    exec: 40,
+    credential: 40,
+    network: 25,
+    write: 20,
+};
+const RULE_POINTS = {
+    description_poisoned: 60,
+    confirmation_removed: 35,
+    schema_widened: 15,
+    tool_added: 5,
+    description_changed: 5,
+};
+const CAPABILITIES = ['exec', 'credential', 'network', 'write'];
+/** Words in a tool's name that name a capability. Matched against whole name tokens. */
+const NAME_TOKENS = {
+    exec: new Set(['exec', 'execute', 'run', 'shell', 'bash', 'sh', 'cmd', 'command', 'commands', 'spawn', 'eval', 'script', 'terminal', 'subprocess']),
+    credential: new Set(['credential', 'credentials', 'secret', 'secrets', 'password', 'passwords', 'passwd', 'token', 'tokens', 'apikey', 'auth', 'oauth', 'login', 'keychain', 'vault', 'ssh']),
+    network: new Set(['http', 'https', 'url', 'fetch', 'request', 'webhook', 'download', 'upload', 'curl', 'wget', 'browse', 'navigate', 'email', 'mail', 'smtp', 'socket', 'send']),
+    write: new Set(['write', 'delete', 'remove', 'rm', 'update', 'create', 'modify', 'edit', 'insert', 'drop', 'truncate', 'overwrite', 'move', 'rename', 'push', 'commit', 'deploy', 'publish', 'put', 'patch', 'upsert', 'append', 'merge', 'set']),
+};
+/**
+ * Phrases in a description that name a capability. Narrower than the name
+ * tokens on purpose: descriptions are prose, where "update" or "token" turn up
+ * in tools that neither write nor touch credentials.
+ */
+const DESCRIPTION_PATTERNS = {
+    exec: /\b(execut(e|es|ing)\b|runs? (an? |any |arbitrary )?(shell |system |terminal )?commands?\b|shell commands?\b|spawn(s|ing)? (a |new )?process|arbitrary code\b)/i,
+    credential: /\b(read|reads|return|returns|get|gets|list|lists|retriev\w*|fetch\w*|export\w*|dump\w*|access\w*)\b[^.]{0,40}\b(credentials?|passwords?|secrets?|api[ _-]?keys?|access tokens?|private keys?|ssh keys?)\b/i,
+    network: /(https?:\/\/|\bhttp requests?\b|\bfetch(es)? (a |the |any )?(url|web ?page)s?\b|\bwebhooks?\b|\bdownloads?\b|\buploads?\b|\bsends? (an? )?(email|e-mail|message|request)s?\b)/i,
+    write: /\b(write|writes|delete|deletes|remove|removes|overwrite|overwrites|modif(y|ies)|truncate|truncates|drop|drops)\b[^.]{0,40}\b(files?|director(y|ies)|records?|rows?|tables?|database|repositor(y|ies)|branch(es)?|data)\b/i,
+};
+/** Argument names that ask for confirmation or a dry run, compared lowercased with `_` and `-` removed. */
+const CONFIRMATION_ARGS = new Set([
+    'confirm', 'confirmed', 'confirmation', 'requireconfirmation', 'dryrun', 'preview', 'approval', 'approve', 'approved', 'safemode',
+]);
+function nameTokens(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean);
+}
+function capabilitiesOf(tool) {
+    const tokens = nameTokens(tool.name);
+    const found = new Set();
+    for (const cap of CAPABILITIES) {
+        if (tokens.some((t) => NAME_TOKENS[cap].has(t)))
+            found.add(cap);
+        else if (tool.description && DESCRIPTION_PATTERNS[cap].test(tool.description))
+            found.add(cap);
+    }
+    return found;
+}
+function isConfirmationArg(name) {
+    return CONFIRMATION_ARGS.has(name.toLowerCase().replace(/[_-]/g, ''));
+}
+/** JSON with object keys sorted, so equal schemas compare equal whatever their key order. */
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(',')}]`;
+    if (value !== null && typeof value === 'object') {
+        const obj = value;
+        return `{${Object.keys(obj).sort().map((k) => `${JSON.stringify(k)}:${stableJson(obj[k])}`).join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+function asSchema(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+function propertiesOf(schema) {
+    return asSchema(schema['properties']) ?? {};
+}
+function requiredOf(schema) {
+    return Array.isArray(schema['required']) ? schema['required'].filter((r) => typeof r === 'string') : [];
+}
+function typesOf(schema) {
+    const t = schema['type'];
+    if (typeof t === 'string')
+        return [t];
+    if (Array.isArray(t))
+        return t.filter((x) => typeof x === 'string');
+    return null;
+}
+/** Upper bounds whose removal or increase accepts more input. */
+const UPPER_BOUNDS = ['maxLength', 'maximum', 'exclusiveMaximum', 'maxItems', 'maxProperties'];
+/** Lower bounds whose removal or decrease accepts more input. */
+const LOWER_BOUNDS = ['minLength', 'minimum', 'exclusiveMinimum', 'minItems', 'minProperties'];
+/**
+ * Everything `next` accepts that `prev` did not, as phrases — and, separately,
+ * the confirmation arguments `next` weakened. Recurses into nested object
+ * properties and array items; `at` is the argument path for the phrases.
+ */
+function compareSchemas(prev, next, at, widened, confirmations) {
+    const label = (name) => (at ? `${at}.${name}` : name);
+    const here = at ? `\`${at}\`` : 'the input';
+    const prevTypes = typesOf(prev);
+    const nextTypes = typesOf(next);
+    if (prevTypes && (!nextTypes || nextTypes.some((t) => !prevTypes.includes(t)))) {
+        widened.push(`${here} accepts ${nextTypes ? nextTypes.filter((t) => !prevTypes.includes(t)).join(', ') : 'any type'} now`);
+    }
+    if ('enum' in prev) {
+        const before = Array.isArray(prev['enum']) ? prev['enum'].map(stableJson) : [];
+        const after = Array.isArray(next['enum']) ? next['enum'].map(stableJson) : null;
+        if (!after)
+            widened.push(`${here} lost its list of allowed values`);
+        else if (after.some((v) => !before.includes(v)))
+            widened.push(`${here} allows new values`);
+    }
+    if ('const' in prev && stableJson(prev['const']) !== stableJson(next['const'])) {
+        widened.push(`${here} is no longer fixed to ${stableJson(prev['const'])}`);
+    }
+    if (typeof prev['pattern'] === 'string' && prev['pattern'] !== next['pattern']) {
+        widened.push(`${here} ${typeof next['pattern'] === 'string' ? 'has a different' : 'lost its'} pattern`);
+    }
+    for (const bound of UPPER_BOUNDS) {
+        const b = prev[bound];
+        if (typeof b === 'number' && !(typeof next[bound] === 'number' && next[bound] <= b)) {
+            widened.push(`${here} ${typeof next[bound] === 'number' ? 'raised' : 'dropped'} its ${bound}`);
+        }
+    }
+    for (const bound of LOWER_BOUNDS) {
+        const b = prev[bound];
+        if (typeof b === 'number' && !(typeof next[bound] === 'number' && next[bound] >= b)) {
+            widened.push(`${here} ${typeof next[bound] === 'number' ? 'lowered' : 'dropped'} its ${bound}`);
+        }
+    }
+    if (prev['additionalProperties'] === false && next['additionalProperties'] !== false) {
+        widened.push(`${here} accepts arguments it does not declare`);
+    }
+    const prevProps = propertiesOf(prev);
+    const nextProps = propertiesOf(next);
+    const prevRequired = requiredOf(prev);
+    const nextRequired = new Set(requiredOf(next));
+    for (const name of Object.keys(nextProps).sort()) {
+        if (!(name in prevProps))
+            widened.push(`new argument \`${label(name)}\``);
+    }
+    for (const name of Object.keys(prevProps).sort()) {
+        const confirmation = isConfirmationArg(name);
+        if (!(name in nextProps)) {
+            if (confirmation)
+                confirmations.push(`\`${label(name)}\` was removed`);
+            continue;
+        }
+        const prevProp = asSchema(prevProps[name]);
+        const nextProp = asSchema(nextProps[name]);
+        if (prevRequired.includes(name) && !nextRequired.has(name)) {
+            if (confirmation)
+                confirmations.push(`\`${label(name)}\` is no longer required`);
+            else
+                widened.push(`\`${label(name)}\` is no longer required`);
+        }
+        if (confirmation && prevProp?.['default'] === true && nextProp?.['default'] !== true) {
+            confirmations.push(`\`${label(name)}\` no longer defaults to true`);
+        }
+        if (prevProp && nextProp)
+            compareSchemas(prevProp, nextProp, label(name), widened, confirmations);
+        else if (prevProp && !nextProp)
+            widened.push(`\`${label(name)}\` lost its schema`);
+    }
+    const prevItems = asSchema(prev['items']);
+    const nextItems = asSchema(next['items']);
+    if (prevItems && nextItems)
+        compareSchemas(prevItems, nextItems, at ? `${at}[]` : '[]', widened, confirmations);
+    else if (prevItems && !nextItems)
+        widened.push(`${here} lost its item schema`);
+}
+function capabilityList(caps) {
+    const set = new Set(caps);
+    return CAPABILITIES.filter((c) => set.has(c));
+}
+const CAPABILITY_WORDS = {
+    exec: 'command execution',
+    credential: 'credential access',
+    network: 'network access',
+    write: 'write access',
+};
+function indexByName(tools) {
+    const map = new Map();
+    for (const t of tools)
+        if (typeof t.name === 'string' && t.name && !map.has(t.name))
+            map.set(t.name, t);
+    return map;
+}
+function riskLevelOf(score) {
+    if (score >= exports.MCP_TOOL_RISK_HIGH)
+        return 'high';
+    if (score >= exports.MCP_TOOL_RISK_MEDIUM)
+        return 'medium';
+    return score > 0 ? 'low' : 'none';
+}
+/**
+ * Compares the tool set a server declared before with the one it declares
+ * now. Tools are matched by name; order and duplicate names (the first wins)
+ * do not affect the result.
+ */
+function scoreToolSetChange(previous, next) {
+    const before = indexByName(previous);
+    const after = indexByName(next);
+    const added = [...after.keys()].filter((n) => !before.has(n)).sort();
+    const removed = [...before.keys()].filter((n) => !after.has(n)).sort();
+    const changed = [];
+    const reasons = [];
+    const reason = (rule, tool, points, detail) => reasons.push({ rule, tool, points, detail });
+    for (const name of added) {
+        const tool = after.get(name);
+        const start = reasons.length;
+        const poison = tool.description ? (0, toolPoison_js_1.scanToolDescription)(tool.description) : [];
+        if (poison.length > 0) {
+            reason('description_poisoned', name, RULE_POINTS.description_poisoned, `new tool's description matches ${poison.join(', ')}`);
+        }
+        for (const cap of capabilityList(capabilitiesOf(tool))) {
+            reason('new_tool_capability', name, exports.MCP_TOOL_CAPABILITY_POINTS[cap], `new tool implies ${CAPABILITY_WORDS[cap]}`);
+        }
+        if (reasons.length === start)
+            reason('tool_added', name, RULE_POINTS.tool_added, 'new tool');
+    }
+    for (const name of [...after.keys()].filter((n) => before.has(n)).sort()) {
+        const prev = before.get(name);
+        const cur = after.get(name);
+        const descriptionChanged = (prev.description ?? '') !== (cur.description ?? '');
+        const schemaChanged = stableJson(prev.inputSchema ?? null) !== stableJson(cur.inputSchema ?? null);
+        if (!descriptionChanged && !schemaChanged)
+            continue;
+        changed.push(name);
+        const start = reasons.length;
+        if (descriptionChanged && cur.description) {
+            const was = new Set(prev.description ? (0, toolPoison_js_1.scanToolDescription)(prev.description) : []);
+            const now = (0, toolPoison_js_1.scanToolDescription)(cur.description).filter((p) => !was.has(p));
+            if (now.length > 0) {
+                reason('description_poisoned', name, RULE_POINTS.description_poisoned, `description now matches ${now.join(', ')}`);
+            }
+        }
+        const hadCaps = capabilitiesOf(prev);
+        for (const cap of capabilityList(capabilitiesOf(cur))) {
+            if (!hadCaps.has(cap)) {
+                reason('capability_gained', name, exports.MCP_TOOL_CAPABILITY_POINTS[cap], `now implies ${CAPABILITY_WORDS[cap]}`);
+            }
+        }
+        if (schemaChanged) {
+            const widened = [];
+            const confirmations = [];
+            compareSchemas(asSchema(prev.inputSchema) ?? {}, asSchema(cur.inputSchema) ?? {}, '', widened, confirmations);
+            if (confirmations.length > 0) {
+                reason('confirmation_removed', name, RULE_POINTS.confirmation_removed, confirmations.join('; '));
+            }
+            if (widened.length > 0)
+                reason('schema_widened', name, RULE_POINTS.schema_widened, widened.join('; '));
+        }
+        if (reasons.length === start && descriptionChanged) {
+            reason('description_changed', name, RULE_POINTS.description_changed, 'description changed');
+        }
+    }
+    const order = (r) => [r.tool, r.rule, r.detail];
+    reasons.sort((a, b) => {
+        const [x, y] = [order(a), order(b)];
+        for (let i = 0; i < x.length; i++)
+            if (x[i] !== y[i])
+                return x[i] < y[i] ? -1 : 1;
+        return 0;
+    });
+    const score = Math.min(100, reasons.reduce((sum, r) => sum + r.points, 0));
+    return { added, removed, changed: changed.sort(), score, level: riskLevelOf(score), reasons };
+}
+//# sourceMappingURL=mcpToolRisk.js.map