@sammorrowdrums/mcpi-ext 0.2.0 → 1.0.0

package/dist/mcp/policy.js

@@ -0,0 +1,848 @@
+import { createHash } from "node:crypto";
+import { SKILLS_EXTENSION_NAME } from "../skills/sep2640/spec.js";
+/** A denial raised by the policy boundary before any upstream MCP request. */
+export class McpPolicyError extends Error {
+    reason;
+    source;
+    serverName;
+    toolName;
+    uri;
+    alternatives;
+    constructor(init) {
+        super(init.message);
+        this.name = "McpPolicyError";
+        this.reason = init.reason;
+        this.source = init.source;
+        this.serverName = init.serverName;
+        this.toolName = init.toolName;
+        this.uri = init.uri;
+        this.alternatives = init.alternatives ?? [];
+    }
+}
+const DEFAULT_AUDIT_LIMIT = 500;
+const NUL = "\u0000";
+/**
+ * The single MCP policy and dispatch boundary.
+ *
+ * Every execution path — deferred/direct proxy tools, Code Mode dispatch,
+ * tool-cli provider RPC, and skill resource reads — crosses this class exactly
+ * once per operation. Discovery, gating, argument validation, permission
+ * semantics, approval, cancellation, and audit all happen here, and nothing
+ * reaches an MCP server without passing through `dispatchToolCall` /
+ * `dispatchResourceRead` below.
+ */
+export class McpPolicy {
+    gateway;
+    approvals;
+    auditLimit;
+    onAudit;
+    /** Tools that require an approved skill grant before any path may call them. */
+    gatedTools = new Map();
+    /** Tools unlocked by an approved, activated skill grant. */
+    enabledTools = new Set();
+    /** Approved skill grant keys, bound to server origin plus grant content. */
+    approvedGrants = new Set();
+    /** Skill URIs registered per server origin, for `skill-load` authorization. */
+    skillUrisByServer = new Map();
+    /** URIs a server itself listed in the current discovery pass. */
+    discoveredUrisByServer = new Map();
+    /**
+     * Per-skill SEP-2640 resource allowlists, keyed by `serverName\0skillUri`.
+     *
+     * A skill's declared `resources` set is the *only* thing that authorizes a
+     * `skills-extension` read. Storing it per skill rather than per server means a
+     * file listed by skill A cannot be read while "loading" skill B.
+     */
+    extensionResourceUris = new Map();
+    audit = [];
+    sequence = 0;
+    constructor(options) {
+        this.gateway = options.gateway;
+        this.approvals = options.approvals;
+        this.auditLimit = options.auditLimit ?? DEFAULT_AUDIT_LIMIT;
+        this.onAudit = options.onAudit;
+    }
+    // ---------------------------------------------------------------------------
+    // Registration
+    // ---------------------------------------------------------------------------
+    /** Register discovered skills so their tools are gated and their URIs bound. */
+    registerSkills(skills) {
+        for (const skill of skills) {
+            const key = skillGrantKey(skill);
+            for (const tool of skill.allowedTools) {
+                let owners = this.gatedTools.get(tool);
+                if (!owners) {
+                    owners = new Set();
+                    this.gatedTools.set(tool, owners);
+                }
+                owners.add(skill.name);
+            }
+            let uris = this.skillUrisByServer.get(skill.serverName);
+            if (!uris) {
+                uris = new Set();
+                this.skillUrisByServer.set(skill.serverName, uris);
+            }
+            uris.add(skill.uri);
+            // Registration alone never approves; `key` is only recomputed on activation.
+            void key;
+        }
+    }
+    /**
+     * Bind a SEP-2640 skill's declared resource URIs so they become readable
+     * under the `skills-extension` source — and nothing else does.
+     *
+     * The set replaces any previous one for that skill, so a rotated listing
+     * narrows access immediately instead of accumulating stale grants.
+     */
+    registerSkillResources(serverName, skillUri, resourceUris) {
+        this.extensionResourceUris.set(extensionResourceKey(serverName, skillUri), new Set(resourceUris));
+    }
+    /** Every tool name currently gated behind an unapproved skill grant. */
+    getGatedToolNames() {
+        return [...this.gatedTools.keys()].filter((name) => !this.enabledTools.has(name)).sort();
+    }
+    /** Skills that gate `toolName`, for actionable block messages. */
+    getGatingSkills(toolName) {
+        return [...(this.gatedTools.get(toolName) ?? [])].sort();
+    }
+    /** True when a tool is discovered but still requires an approved skill grant. */
+    isGated(toolName) {
+        return this.gatedTools.has(toolName) && !this.enabledTools.has(toolName);
+    }
+    reset() {
+        this.gatedTools.clear();
+        this.enabledTools.clear();
+        this.approvedGrants.clear();
+        this.skillUrisByServer.clear();
+        this.discoveredUrisByServer.clear();
+        this.extensionResourceUris.clear();
+        this.audit.length = 0;
+    }
+    // ---------------------------------------------------------------------------
+    // Visibility (what tool-cli and other discovery surfaces may see)
+    // ---------------------------------------------------------------------------
+    getVisibleServers() {
+        return this.gateway.getConnectedServers();
+    }
+    /**
+     * The exact discovered schema set a discovery surface may see. Gated tools
+     * are omitted entirely, so a surface cannot learn a hidden tool's name or
+     * schema and then try to call it.
+     */
+    getVisibleTools(serverName) {
+        return this.gateway.getToolsForServer(serverName).filter((tool) => !this.isGated(tool.name));
+    }
+    // ---------------------------------------------------------------------------
+    // Skill grants
+    // ---------------------------------------------------------------------------
+    /**
+     * Activate an MCP-origin skill's `allowed-tools` grant.
+     *
+     * The grant is origin- and content-bound: the key covers the server name, the
+     * skill URI, and a digest of the exact tool list being granted. A previously
+     * approved identical grant is reused without re-prompting, so no path ever
+     * asks the user twice for the same authority. Declined, cancelled, and
+     * unavailable outcomes all leave the tools gated.
+     */
+    async activateSkillGrant(skill, signal) {
+        if (skill.allowedTools.length === 0) {
+            return { status: "granted", activatedTools: [] };
+        }
+        const key = skillGrantKey(skill);
+        if (this.approvedGrants.has(key)) {
+            this.enableTools(skill.allowedTools);
+            this.record({
+                source: "skill-load",
+                operation: "skill-grant",
+                serverName: skill.serverName,
+                uri: skill.uri,
+                decision: "allowed",
+                approval: "reused",
+            });
+            return { status: "reused", activatedTools: [...skill.allowedTools] };
+        }
+        if (signal?.aborted) {
+            this.record({
+                source: "skill-load",
+                operation: "skill-grant",
+                serverName: skill.serverName,
+                uri: skill.uri,
+                decision: "denied",
+                reason: "cancelled",
+                approval: "unavailable",
+            });
+            return {
+                status: "unavailable",
+                message: `Loading skill "${skill.name}" was cancelled before its tool grant could be approved. No tools were activated.`,
+            };
+        }
+        const granted = await this.requestApproval({
+            kind: "skill-grant",
+            source: "proxy",
+            serverName: skill.serverName,
+            skillName: skill.name,
+            grantedTools: [...skill.allowedTools],
+            title: `Activate MCP skill "${skill.name}"?`,
+            message: `MCP server "${skill.serverName}" offers skill "${skill.name}" (${skill.uri}).\n` +
+                `Approving activates these tools for this session:\n` +
+                skill.allowedTools.map((tool) => `  - ${tool}`).join("\n"),
+            ...(signal !== undefined ? { signal } : {}),
+        });
+        if (granted === true) {
+            this.approvedGrants.add(key);
+            this.enableTools(skill.allowedTools);
+            this.record({
+                source: "skill-load",
+                operation: "skill-grant",
+                serverName: skill.serverName,
+                uri: skill.uri,
+                decision: "allowed",
+                approval: "granted",
+            });
+            return { status: "granted", activatedTools: [...skill.allowedTools] };
+        }
+        const approval = granted === false ? "declined" : "unavailable";
+        this.record({
+            source: "skill-load",
+            operation: "skill-grant",
+            serverName: skill.serverName,
+            uri: skill.uri,
+            decision: "denied",
+            reason: granted === false ? "approval_declined" : "approval_unavailable",
+            approval,
+        });
+        const toolList = skill.allowedTools.join(", ");
+        return {
+            status: approval,
+            message: granted === false
+                ? `Activation of skill "${skill.name}" was declined, so its tools (${toolList}) remain unavailable. Call load_skill again and approve the prompt to activate them.`
+                : `Activation of skill "${skill.name}" needs explicit approval, but no interactive confirmation was available, so its tools (${toolList}) remain unavailable. Run this session interactively and call load_skill again to approve.`,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Tool calls
+    // ---------------------------------------------------------------------------
+    /**
+     * Authorize and dispatch a tool call. Every execution path funnels here, and
+     * upstream is reached only after all checks below pass.
+     */
+    async callTool(request) {
+        const { source, serverName, toolName, args, signal } = request;
+        const deny = (reason, message, alternatives) => {
+            this.record({
+                source,
+                operation: "tool",
+                serverName,
+                toolName,
+                decision: "denied",
+                reason,
+            });
+            return new McpPolicyError({
+                reason,
+                message,
+                source,
+                serverName,
+                toolName,
+                ...(alternatives !== undefined ? { alternatives } : {}),
+            });
+        };
+        if (!this.gateway.getConnectedServers().includes(serverName)) {
+            throw deny("server_not_connected", `MCP server "${serverName}" is not connected, so "${toolName}" cannot be called.`);
+        }
+        // Discovery check: an undiscovered tool name never reaches upstream.
+        const tool = this.gateway
+            .getToolsForServer(serverName)
+            .find((candidate) => candidate.name === toolName);
+        if (!tool) {
+            throw deny("tool_not_discovered", `Tool "${toolName}" was not discovered on MCP server "${serverName}". Only discovered tools can be called.`);
+        }
+        // Gating check: applies to every source, so no surface can bypass a skill
+        // grant by naming a tool it was never shown.
+        if (this.isGated(toolName)) {
+            const skills = this.getGatingSkills(toolName);
+            throw deny("tool_gated", `Tool "${toolName}" requires an approved skill grant first. Call load_skill with one of: ${skills.join(", ") || "(none)"}`, ["load_skill"]);
+        }
+        const invalid = validateToolArguments(tool.inputSchema, args);
+        if (invalid) {
+            throw deny("invalid_arguments", `Arguments for "${toolName}" do not satisfy its declared input schema: ${invalid}`);
+        }
+        if (signal?.aborted) {
+            throw deny("cancelled", `Call to "${toolName}" was cancelled before dispatch.`);
+        }
+        // Permission semantics. Code Mode keeps its strict read-only contract; the
+        // interactive paths use the same annotations to drive HITL.
+        const readOnly = isReadOnlyToolCall(tool);
+        // A tool activated by an approved skill grant is already covered by that
+        // approval, so it must not prompt again on every call.
+        const grantCovered = this.enabledTools.has(toolName);
+        let approval;
+        if (source === "code-mode") {
+            if (!readOnly) {
+                throw deny("permission_denied", `Tool "${toolName}" is visible for discovery but cannot be called from Code Mode. ` +
+                    "Use load_skill or tool-cli through the host's permission-aware path.", ["load_skill", "tool-cli"]);
+            }
+        }
+        else if (!readOnly && grantCovered) {
+            approval = "reused";
+        }
+        else if (!readOnly) {
+            const approved = await this.requestApproval({
+                kind: "tool-call",
+                source,
+                serverName,
+                toolName,
+                title: `Run MCP tool "${toolName}"?`,
+                message: formatToolApprovalMessage(source, serverName, tool, args),
+                ...(signal !== undefined ? { signal } : {}),
+            });
+            if (approved !== true) {
+                const reason = approved === false ? "approval_declined" : "approval_unavailable";
+                this.record({
+                    source,
+                    operation: "tool",
+                    serverName,
+                    toolName,
+                    decision: "denied",
+                    reason,
+                    approval: approved === false ? "declined" : "unavailable",
+                });
+                throw new McpPolicyError({
+                    reason,
+                    source,
+                    serverName,
+                    toolName,
+                    message: approved === false
+                        ? `Running "${toolName}" was declined, so it was not executed. Re-run the tool and approve the prompt if you want it to proceed.`
+                        : `Running "${toolName}" needs explicit approval because it is not annotated read-only, but no interactive confirmation was available, so it was not executed. Run this session interactively to approve it.`,
+                });
+            }
+            approval = "granted";
+        }
+        if (signal?.aborted) {
+            throw deny("cancelled", `Call to "${toolName}" was cancelled before dispatch.`);
+        }
+        const terminal = await this.gateway.callTool(serverName, toolName, args, signal);
+        this.record({
+            source,
+            operation: "tool",
+            serverName,
+            toolName,
+            decision: "allowed",
+            ...(approval !== undefined ? { approval } : {}),
+        });
+        return terminal;
+    }
+    // ---------------------------------------------------------------------------
+    // Skills extension (draft SEP-2640)
+    // ---------------------------------------------------------------------------
+    /**
+     * The server's declared settings for the draft skills extension, or
+     * `undefined` when it did not declare it.
+     *
+     * Resolved fresh on every call. The extension is negotiated in `initialize`,
+     * but a reconnect can change the answer, and caching "this server supports
+     * skills" would let a stale yes outlive the negotiation that produced it.
+     */
+    getSkillsExtension(serverName) {
+        if (!this.gateway.getConnectedServers().includes(serverName))
+            return undefined;
+        return this.gateway.getExtensionCapability(serverName, SKILLS_EXTENSION_NAME);
+    }
+    /** True when the server declared `directoryRead: true` on the extension. */
+    supportsSkillDirectoryRead(serverName) {
+        return this.getSkillsExtension(serverName)?.["directoryRead"] === true;
+    }
+    /**
+     * Draft SEP-2640 `skills/list`.
+     *
+     * Refused unless the server declared the extension: an undeclared method is
+     * not a method this host is entitled to probe for.
+     */
+    async listMcpSkills(serverName, cursor, signal) {
+        this.assertSkillsExtension(serverName, "skill-list");
+        if (signal?.aborted) {
+            throw this.denyExtension(serverName, "skill-list", "cancelled", "skills/list was cancelled.");
+        }
+        const result = await this.gateway.requestSkillsList(serverName, cursor, signal);
+        this.record({
+            source: "skills-extension",
+            operation: "skill-list",
+            serverName,
+            decision: "allowed",
+        });
+        return result;
+    }
+    /** Draft SEP-2640 `skills/get`. */
+    async getMcpSkill(serverName, uri, signal) {
+        this.assertSkillsExtension(serverName, "skill-get", uri);
+        if (signal?.aborted) {
+            throw this.denyExtension(serverName, "skill-get", "cancelled", `skills/get for ${uri} was cancelled.`, uri);
+        }
+        const result = await this.gateway.requestSkillsGet(serverName, uri, signal);
+        this.record({
+            source: "skills-extension",
+            operation: "skill-get",
+            serverName,
+            uri,
+            decision: "allowed",
+        });
+        return result;
+    }
+    /**
+     * Draft SEP-2640 `resources/directory/read`.
+     *
+     * Refused when the server declared the extension without `directoryRead`.
+     * The setting defaults to false, so silence means no.
+     */
+    async readSkillDirectory(serverName, uri, cursor, signal) {
+        this.assertSkillsExtension(serverName, "skill-directory", uri);
+        if (!this.supportsSkillDirectoryRead(serverName)) {
+            throw this.denyExtension(serverName, "skill-directory", "directory_read_unavailable", `MCP server "${serverName}" did not declare "directoryRead" on the skills extension, so ` +
+                `${uri} cannot be enumerated.`, uri);
+        }
+        if (signal?.aborted) {
+            throw this.denyExtension(serverName, "skill-directory", "cancelled", `Directory read of ${uri} was cancelled.`, uri);
+        }
+        const result = await this.gateway.requestDirectoryRead(serverName, uri, cursor, signal);
+        this.record({
+            source: "skills-extension",
+            operation: "skill-directory",
+            serverName,
+            uri,
+            decision: "allowed",
+        });
+        return result;
+    }
+    // ---------------------------------------------------------------------------
+    // Resources
+    // ---------------------------------------------------------------------------
+    /**
+     * List the resources visible to tool-cli.
+     *
+     * `skill://` is a separate authorization domain: those resources carry
+     * workflow instructions and grants, so they remain reachable only through
+     * skill discovery/load and can never be enumerated through the shell bridge.
+     */
+    async listResources(request) {
+        const { source, serverName, signal } = request;
+        const deny = (reason, message) => {
+            this.record({
+                source,
+                operation: "resource-list",
+                serverName,
+                decision: "denied",
+                reason,
+            });
+            return new McpPolicyError({ reason, message, source, serverName });
+        };
+        if (!this.gateway.getConnectedServers().includes(serverName)) {
+            throw deny("server_not_connected", `MCP server "${serverName}" is not connected.`);
+        }
+        if (signal?.aborted) {
+            throw deny("cancelled", `Listing resources on "${serverName}" was cancelled.`);
+        }
+        const resources = await this.gateway.listResources(serverName, signal);
+        const visible = resources.filter((resource) => !this.isSkillOwnedResource(serverName, resource.uri));
+        this.record({
+            source,
+            operation: "resource-list",
+            serverName,
+            decision: "allowed",
+        });
+        return visible;
+    }
+    /** List policy-visible resource templates for tool-cli. */
+    async listResourceTemplates(request) {
+        const { source, serverName, signal } = request;
+        const deny = (reason, message) => {
+            this.record({
+                source,
+                operation: "resource-templates",
+                serverName,
+                decision: "denied",
+                reason,
+            });
+            return new McpPolicyError({ reason, message, source, serverName });
+        };
+        if (!this.gateway.getConnectedServers().includes(serverName)) {
+            throw deny("server_not_connected", `MCP server "${serverName}" is not connected.`);
+        }
+        if (signal?.aborted) {
+            throw deny("cancelled", `Listing resource templates on "${serverName}" was cancelled.`);
+        }
+        const templates = await this.gateway.listResourceTemplates(serverName, signal);
+        const visible = templates.filter((template) => !this.isSkillOwnedResource(serverName, template.uriTemplate));
+        this.record({
+            source,
+            operation: "resource-templates",
+            serverName,
+            decision: "allowed",
+        });
+        return visible;
+    }
+    /**
+     * List a server's skill resources and remember them as this pass's discovery
+     * candidates. Only URIs seen here become readable under `skill-discovery`.
+     */
+    async listSkillResources(serverName, signal) {
+        if (!this.gateway.getConnectedServers().includes(serverName)) {
+            this.record({
+                source: "skill-discovery",
+                operation: "resource",
+                serverName,
+                decision: "denied",
+                reason: "server_not_connected",
+            });
+            throw new McpPolicyError({
+                reason: "server_not_connected",
+                message: `MCP server "${serverName}" is not connected.`,
+                source: "skill-discovery",
+                serverName,
+            });
+        }
+        if (signal?.aborted) {
+            this.record({
+                source: "skill-discovery",
+                operation: "resource-list",
+                serverName,
+                decision: "denied",
+                reason: "cancelled",
+            });
+            throw new McpPolicyError({
+                reason: "cancelled",
+                message: `Listing skill resources on "${serverName}" was cancelled.`,
+                source: "skill-discovery",
+                serverName,
+            });
+        }
+        const resources = await this.gateway.listResources(serverName, signal);
+        const skillResources = resources.filter(isSkillResourceUri);
+        this.discoveredUrisByServer.set(serverName, new Set(skillResources.map((r) => r.uri)));
+        this.record({
+            source: "skill-discovery",
+            operation: "resource-list",
+            serverName,
+            decision: "allowed",
+        });
+        return skillResources;
+    }
+    /**
+     * Authorize and dispatch a resource read using the same policy discipline as
+     * tool calls: origin binding, discovery, cancellation, and audit.
+     */
+    async readResource(request) {
+        const { source, serverName, uri, skillUri, signal } = request;
+        const deny = (reason, message) => {
+            this.record({
+                source,
+                operation: "resource",
+                serverName,
+                uri,
+                decision: "denied",
+                reason,
+            });
+            return new McpPolicyError({ reason, message, source, serverName, uri });
+        };
+        if (!this.gateway.getConnectedServers().includes(serverName)) {
+            throw deny("server_not_connected", `MCP server "${serverName}" is not connected, so ${uri} cannot be read.`);
+        }
+        // The legacy convention recognises skills by URI shape, so the shape is the
+        // outer bound of what it may read. SEP-2640 reads are authorized by exact
+        // membership in a skill's declared `resources` set — strictly narrower — so
+        // they do not need, and must not be limited by, a scheme heuristic.
+        if (source === "tool-cli" && this.isSkillOwnedResource(serverName, uri)) {
+            throw deny("resource_not_discovered", `Resource ${uri} belongs to the skill authorization surface and cannot be read through tool-cli. Use load_skill instead.`);
+        }
+        if (source !== "skills-extension" && source !== "tool-cli" && !hasSkillScheme(uri)) {
+            throw deny("resource_not_discovered", `Resource ${uri} is outside the skill resource surface this host authorizes.`);
+        }
+        if (source === "skills-extension") {
+            if (!skillUri) {
+                throw deny("resource_not_discovered", `Read of ${uri} did not name the skill whose declared resources authorize it.`);
+            }
+            if (!this.getSkillsExtension(serverName)) {
+                throw deny("extension_not_declared", `MCP server "${serverName}" does not declare the skills extension, so ${uri} cannot be read under it.`);
+            }
+        }
+        const allowed = source === "tool-cli" ? undefined : this.allowedReadUris(source, serverName, skillUri);
+        if (allowed !== undefined && !allowed.has(uri)) {
+            // Distinguish "belongs to a different origin" so the denial is actionable.
+            const otherOrigin = this.findOtherOrigin(uri, serverName, source);
+            if (otherOrigin) {
+                throw deny("resource_origin_mismatch", `Resource ${uri} belongs to MCP server "${otherOrigin}" and cannot be read through server "${serverName}".`);
+            }
+            throw deny("resource_not_discovered", source === "skills-extension"
+                ? `Resource ${uri} is not listed in the resources of skill ${skillUri ?? "(unknown)"} on MCP server "${serverName}".`
+                : `Resource ${uri} was not discovered as a skill on MCP server "${serverName}".`);
+        }
+        if (signal?.aborted) {
+            throw deny("cancelled", `Read of ${uri} was cancelled before dispatch.`);
+        }
+        const result = await this.gateway.readResource(serverName, uri, signal);
+        if (source === "tool-cli") {
+            const hidden = result.contents.find((content) => this.isSkillOwnedResource(serverName, content.uri));
+            if (hidden !== undefined) {
+                throw deny("resource_not_discovered", `MCP server "${serverName}" returned skill-owned resource ${hidden.uri} while reading ${uri}; the entire response was refused. Use load_skill for skill resources.`);
+            }
+        }
+        this.record({
+            source,
+            operation: "resource",
+            serverName,
+            uri,
+            decision: "allowed",
+        });
+        return result;
+    }
+    // ---------------------------------------------------------------------------
+    // Audit
+    // ---------------------------------------------------------------------------
+    getAuditLog() {
+        return [...this.audit];
+    }
+    // ---------------------------------------------------------------------------
+    // Internals
+    // ---------------------------------------------------------------------------
+    enableTools(tools) {
+        for (const tool of tools) {
+            this.enabledTools.add(tool);
+        }
+    }
+    allowedReadUris(source, serverName, skillUri) {
+        if (source === "skills-extension") {
+            if (!skillUri)
+                return new Set();
+            return (this.extensionResourceUris.get(extensionResourceKey(serverName, skillUri)) ??
+                new Set());
+        }
+        if (source === "skill-discovery") {
+            return this.discoveredUrisByServer.get(serverName) ?? new Set();
+        }
+        return this.skillUrisByServer.get(serverName) ?? new Set();
+    }
+    isSkillOwnedResource(serverName, uri) {
+        if (hasSkillScheme(uri) || this.skillUrisByServer.get(serverName)?.has(uri) === true) {
+            return true;
+        }
+        for (const [key, resourceUris] of this.extensionResourceUris) {
+            const owner = key.slice(0, key.indexOf(NUL));
+            if (owner === serverName && resourceUris.has(uri))
+                return true;
+        }
+        return false;
+    }
+    findOtherOrigin(uri, serverName, source) {
+        if (source === "tool-cli")
+            return undefined;
+        if (source === "skills-extension") {
+            // Extension allowlists are keyed by `serverName\0skillUri`, so a match on
+            // another origin is what turns "not listed here" into "listed elsewhere".
+            for (const [key, uris] of this.extensionResourceUris) {
+                const owner = key.slice(0, key.indexOf(NUL));
+                if (owner !== serverName && uris.has(uri))
+                    return owner;
+            }
+            return undefined;
+        }
+        const index = source === "skill-discovery" ? this.discoveredUrisByServer : this.skillUrisByServer;
+        for (const [candidate, uris] of index) {
+            if (candidate !== serverName && uris.has(uri))
+                return candidate;
+        }
+        return undefined;
+    }
+    /**
+     * Refuse an extension method unless the server is connected and declared the
+     * extension. Records the denial before throwing, like every other refusal.
+     */
+    assertSkillsExtension(serverName, operation, uri) {
+        if (!this.gateway.getConnectedServers().includes(serverName)) {
+            throw this.denyExtension(serverName, operation, "server_not_connected", `MCP server "${serverName}" is not connected.`, uri);
+        }
+        if (!this.gateway.getExtensionCapability(serverName, SKILLS_EXTENSION_NAME)) {
+            throw this.denyExtension(serverName, operation, "extension_not_declared", `MCP server "${serverName}" does not declare the "${SKILLS_EXTENSION_NAME}" extension, so ` +
+                `its skills methods are not available.`, uri);
+        }
+    }
+    denyExtension(serverName, operation, reason, message, uri) {
+        this.record({
+            source: "skills-extension",
+            operation,
+            serverName,
+            ...(uri !== undefined ? { uri } : {}),
+            decision: "denied",
+            reason,
+        });
+        return new McpPolicyError({
+            reason,
+            message,
+            source: "skills-extension",
+            serverName,
+            ...(uri !== undefined ? { uri } : {}),
+        });
+    }
+    async requestApproval(request) {
+        if (!this.approvals)
+            return undefined;
+        try {
+            return await this.approvals.confirm(request);
+        }
+        catch {
+            // A failed or cancelled prompt is never an approval.
+            return undefined;
+        }
+    }
+    record(record) {
+        const entry = {
+            ...record,
+            id: `mcp-policy-${++this.sequence}`,
+            timestampMs: Date.now(),
+        };
+        this.audit.push(entry);
+        if (this.audit.length > this.auditLimit) {
+            this.audit.splice(0, this.audit.length - this.auditLimit);
+        }
+        this.onAudit?.(entry);
+    }
+}
+/**
+ * A tool call is treated as read-only only when the server explicitly declares
+ * it read-only and does not also declare it destructive. This is the same
+ * predicate Code Mode uses for dispatch eligibility.
+ */
+export function isReadOnlyToolCall(tool) {
+    return tool.annotations?.readOnlyHint === true && tool.annotations.destructiveHint !== true;
+}
+function isSkillResourceUri(resource) {
+    return hasSkillScheme(resource.uri) && resource.uri.endsWith("/SKILL.md");
+}
+function hasSkillScheme(uri) {
+    return uri.slice(0, "skill://".length).toLowerCase() === "skill://";
+}
+function extensionResourceKey(serverName, skillUri) {
+    return `${serverName}${NUL}${skillUri}`;
+}
+function skillGrantKey(skill) {
+    const tools = [...skill.allowedTools].sort().join(" ");
+    const digest = createHash("sha256").update(tools).digest("hex").slice(0, 32);
+    // The fingerprint participates in the key so rotated content revokes approval.
+    // Legacy skills have none; they degrade to the previous origin+URI+tools key.
+    return [skill.serverName, skill.uri, digest, skill.contentFingerprint ?? ""].join(NUL);
+}
+function formatToolApprovalMessage(source, serverName, tool, args) {
+    const annotations = tool.annotations ?? {};
+    const flags = [];
+    if (annotations.readOnlyHint !== true)
+        flags.push("not annotated read-only");
+    if (annotations.destructiveHint === true)
+        flags.push("annotated destructive");
+    let preview;
+    try {
+        preview = JSON.stringify(args, null, 2) ?? "{}";
+    }
+    catch {
+        preview = "(arguments could not be serialized)";
+    }
+    if (preview.length > 2000)
+        preview = `${preview.slice(0, 2000)}\n… (truncated)`;
+    return [
+        `Requested by: ${source}`,
+        `MCP server: ${serverName}`,
+        `Tool: ${tool.name}${flags.length > 0 ? ` (${flags.join("; ")})` : ""}`,
+        "Arguments:",
+        preview,
+    ].join("\n");
+}
+/**
+ * Conservative, dependency-free structural validation of tool arguments.
+ *
+ * It rejects only what a server's own declared schema unambiguously forbids —
+ * missing required properties, undeclared properties under
+ * `additionalProperties: false`, and clearly mismatched primitive types — so
+ * schemas using `$ref`, `allOf`, or other composition keywords are not
+ * incorrectly refused. Returns a message when invalid, otherwise `undefined`.
+ */
+export function validateToolArguments(schema, args) {
+    if (args === null || typeof args !== "object" || Array.isArray(args)) {
+        return "arguments must be a JSON object";
+    }
+    if (!schema || typeof schema !== "object")
+        return undefined;
+    const record = args;
+    const schemaRecord = schema;
+    const required = collectRequired(schemaRecord);
+    const missing = required.filter((name) => record[name] === undefined);
+    if (missing.length > 0) {
+        return `missing required propert${missing.length === 1 ? "y" : "ies"}: ${missing.join(", ")}`;
+    }
+    const properties = asRecord(schemaRecord.properties);
+    if (schemaRecord.additionalProperties === false && properties) {
+        const declared = new Set(Object.keys(properties));
+        const patterns = asRecord(schemaRecord.patternProperties);
+        const patternKeys = patterns ? Object.keys(patterns).map((p) => new RegExp(p)) : [];
+        const unknown = Object.keys(record).filter((key) => !declared.has(key) && !patternKeys.some((re) => re.test(key)));
+        if (unknown.length > 0) {
+            return `unknown propert${unknown.length === 1 ? "y" : "ies"}: ${unknown.join(", ")}`;
+        }
+    }
+    if (properties) {
+        for (const [key, value] of Object.entries(record)) {
+            if (value === undefined)
+                continue;
+            const propSchema = asRecord(properties[key]);
+            const expected = propSchema?.type;
+            if (typeof expected !== "string")
+                continue;
+            if (!matchesJsonType(value, expected)) {
+                return `property "${key}" must be of type ${expected}`;
+            }
+        }
+    }
+    return undefined;
+}
+function collectRequired(schema) {
+    const names = new Set();
+    const push = (value) => {
+        if (!Array.isArray(value))
+            return;
+        for (const entry of value) {
+            if (typeof entry === "string")
+                names.add(entry);
+        }
+    };
+    push(schema.required);
+    // `allOf` composition is common in MCP schemas; honor top-level required only.
+    if (Array.isArray(schema.allOf)) {
+        for (const branch of schema.allOf) {
+            const record = asRecord(branch);
+            if (record)
+                push(record.required);
+        }
+    }
+    return [...names];
+}
+function matchesJsonType(value, expected) {
+    switch (expected) {
+        case "string":
+            return typeof value === "string";
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value);
+        case "boolean":
+            return typeof value === "boolean";
+        case "array":
+            return Array.isArray(value);
+        case "object":
+            return typeof value === "object" && value !== null && !Array.isArray(value);
+        case "null":
+            return value === null;
+        default:
+            return true;
+    }
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}