@vaultys/mcp-agent 0.1.0

package/dist/src/policyMiddleware.js

@@ -0,0 +1,194 @@
+/**
+ * Policy Middleware — wraps every MCP tool call through ExecutionManager.
+ *
+ * For each tool invocation the middleware:
+ *   1. Maps the MCP tool name + arguments → taxonomy capability strings
+ *   2. Creates and signs an ExecutionIntent via the server's IdManager
+ *   3. Evaluates the intent against the loaded signed PolicyBundle
+ *   4. If allowed, executes the real handler and signs a receipt
+ *   5. If denied, returns a denial message and signs a deny receipt
+ *
+ * All receipts are persisted to ./audit/ as JSON files.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ExecutionManager } from "@vaultys/id";
+/**
+ * Default mappings from MCP tool names to taxonomy capabilities.
+ *
+ * Scopes must match the format used in the policy's scope patterns.
+ * For filesystem tools: full resolved paths (e.g. "/workspace/src/file.ts")
+ * For process tools: the binary name (e.g. "ls", "npm")
+ * For network tools: the hostname (e.g. "api.example.com")
+ *
+ * The `workspaceRoot` parameter is passed to `extractScope` so that filesystem
+ * tools can resolve relative paths to absolute paths matching the policy globs.
+ */
+export const DEFAULT_TOOL_MAPPINGS = {
+    read_file: {
+        capability: "fs.read",
+        extractScope: (args, workspaceRoot) => {
+            const raw = String(args.path ?? args.file ?? "");
+            return resolveWorkspacePath(raw, workspaceRoot);
+        },
+    },
+    write_file: {
+        capability: "fs.write",
+        extractScope: (args, workspaceRoot) => {
+            const raw = String(args.path ?? args.file ?? "");
+            return resolveWorkspacePath(raw, workspaceRoot);
+        },
+    },
+    list_directory: {
+        capability: "fs.list",
+        extractScope: (args, workspaceRoot) => {
+            const raw = String(args.path ?? args.directory ?? ".");
+            return resolveWorkspacePath(raw, workspaceRoot);
+        },
+    },
+    run_command: {
+        capability: "proc.exec",
+        extractScope: (args) => {
+            const cmd = String(args.command ?? "");
+            // Extract the binary name (first token)
+            return cmd.split(/\s+/)[0] ?? cmd;
+        },
+    },
+    fetch_url: {
+        capability: "net.egress.http",
+        extractScope: (args) => {
+            try {
+                return new URL(String(args.url ?? "")).hostname;
+            }
+            catch {
+                return String(args.url ?? "");
+            }
+        },
+    },
+};
+/**
+ * Resolve a tool argument path to an absolute path rooted at workspaceRoot.
+ * This ensures capability strings like "fs.read:/workspace/subdir/file.txt"
+ * match policy glob patterns like "/workspace/**".
+ */
+function resolveWorkspacePath(raw, workspaceRoot) {
+    if (!raw)
+        return workspaceRoot ?? "/workspace";
+    if (path.isAbsolute(raw))
+        return raw;
+    return path.join(workspaceRoot ?? "/workspace", raw);
+}
+// ── Audit persistence ──
+const AUDIT_DIR = path.resolve("audit");
+function ensureAuditDir() {
+    if (!fs.existsSync(AUDIT_DIR)) {
+        fs.mkdirSync(AUDIT_DIR, { recursive: true });
+    }
+}
+function persistReceipt(jobId, receipt, meta) {
+    ensureAuditDir();
+    const record = {
+        job_id: jobId,
+        timestamp: new Date().toISOString(),
+        ...meta,
+        receipt,
+    };
+    const filePath = path.join(AUDIT_DIR, `${jobId}.json`);
+    fs.writeFileSync(filePath, JSON.stringify(record, null, 2));
+}
+/**
+ * Create policy-enforced middleware that wraps MCP tool handlers.
+ */
+export function createPolicyMiddleware(options) {
+    const { serverIdManager, signedPolicy, toolMappings = DEFAULT_TOOL_MAPPINGS, workspaceRoot = process.cwd(), } = options;
+    const em = new ExecutionManager(serverIdManager);
+    /**
+     * Wrap a tool call: evaluate policy, run handler if allowed, sign receipt.
+     */
+    async function enforce(toolName, args, handler) {
+        const mapping = toolMappings[toolName];
+        // Build capability strings
+        const requestedCaps = [];
+        let argv = [];
+        if (mapping) {
+            const scope = mapping.extractScope(args, workspaceRoot);
+            requestedCaps.push(`${mapping.capability}:${scope}`);
+            argv = toolName === "run_command"
+                ? String(args.command ?? "").split(/\s+/)
+                : [toolName, scope];
+        }
+        else {
+            // Unknown tool → treat as a catch-all with the tool name as capability
+            requestedCaps.push(`tool.${toolName}`);
+            argv = [toolName];
+        }
+        // Create and sign the intent
+        const intent = await em.createIntent({
+            tool: toolName,
+            argv,
+            cwd: workspaceRoot,
+            requested_caps: requestedCaps,
+        });
+        // Evaluate against the policy
+        const evaluation = em.evaluateIntent(intent, signedPolicy);
+        if (evaluation.decision === "deny") {
+            // Sign a deny receipt
+            const denyOutcome = {
+                started: new Date().toISOString(),
+                ended: new Date().toISOString(),
+                exit_code: -1,
+                stdout_hash: "",
+                stderr_hash: "",
+            };
+            const receipt = await em.signReceipt(intent, signedPolicy, denyOutcome);
+            persistReceipt(intent.job_id, receipt, {
+                tool: toolName,
+                args,
+                decision: "deny",
+                denied_caps: evaluation.denied_caps,
+            });
+            const reason = evaluation.denied_caps?.join(", ") ?? "unknown";
+            console.error(`[POLICY DENY] ${toolName}: ${reason}`);
+            return {
+                decision: "deny",
+                content: [{ type: "text", text: `⛔ DENIED by policy: ${reason}` }],
+                receipt,
+                jobId: intent.job_id,
+            };
+        }
+        // Policy allows → execute
+        console.error(`[POLICY ALLOW] ${toolName}: ${requestedCaps.join(", ")}`);
+        const started = new Date().toISOString();
+        let stdout = "";
+        let exitCode = 0;
+        try {
+            stdout = await handler();
+        }
+        catch (err) {
+            stdout = err.message ?? String(err);
+            exitCode = 1;
+        }
+        const ended = new Date().toISOString();
+        const outcome = {
+            started,
+            ended,
+            exit_code: exitCode,
+            stdout_hash: Buffer.from(stdout).toString("base64").slice(0, 64),
+        };
+        const receipt = await em.signReceipt(intent, signedPolicy, outcome);
+        persistReceipt(intent.job_id, receipt, {
+            tool: toolName,
+            args,
+            decision: "allow",
+            allowed_caps: evaluation.allowed_caps,
+            constraints: evaluation.constraints,
+        });
+        return {
+            decision: "allow",
+            content: [{ type: "text", text: stdout }],
+            receipt,
+            jobId: intent.job_id,
+        };
+    }
+    return { enforce, em };
+}

package/dist/src/resources/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * MCP Resources — expose policy, identity, and audit trail as readable resources.
+ *
+ * Resources:
+ *   vaultys://policy/current    — the active signed policy (JSON)
+ *   vaultys://identity/server   — the server's VaultysID DID + public key info
+ *   vaultys://receipts/list     — summary of all signed receipts
+ *   vaultys://receipt/{id}      — individual receipt (verifiable)
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { PolicyBundle } from "@vaultys/id";
+import type { IdManager } from "@vaultys/id";
+export declare function registerResources(server: McpServer, serverIdManager: IdManager, signedPolicy: PolicyBundle): void;

package/dist/src/resources/index.js

@@ -0,0 +1,80 @@
+/**
+ * MCP Resources — expose policy, identity, and audit trail as readable resources.
+ *
+ * Resources:
+ *   vaultys://policy/current    — the active signed policy (JSON)
+ *   vaultys://identity/server   — the server's VaultysID DID + public key info
+ *   vaultys://receipts/list     — summary of all signed receipts
+ *   vaultys://receipt/{id}      — individual receipt (verifiable)
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+const AUDIT_DIR = path.resolve("audit");
+export function registerResources(server, serverIdManager, signedPolicy) {
+    // ── Current Policy ──
+    server.resource("current-policy", "vaultys://policy/current", { mimeType: "application/json", description: "The active signed policy bundle" }, async () => {
+        const { signature, ...policyWithoutSig } = signedPolicy;
+        return {
+            contents: [{
+                    uri: "vaultys://policy/current",
+                    mimeType: "application/json",
+                    text: JSON.stringify({
+                        ...policyWithoutSig,
+                        signature_present: !!signature,
+                        signature_length: signature?.length ?? 0,
+                    }, null, 2),
+                }],
+        };
+    });
+    // ── Server Identity ──
+    server.resource("server-identity", "vaultys://identity/server", { mimeType: "application/json", description: "The server's VaultysID (DID + key info)" }, async () => {
+        const vid = serverIdManager.vaultysId;
+        return {
+            contents: [{
+                    uri: "vaultys://identity/server",
+                    mimeType: "application/json",
+                    text: JSON.stringify({
+                        did: vid.did,
+                        fingerprint: vid.fingerprint,
+                        type: vid.type === 0 ? "person" : "machine",
+                        algorithm: vid.keyManager.constructor.name,
+                    }, null, 2),
+                }],
+        };
+    });
+    // ── Receipt List ──
+    server.resource("receipts-list", "vaultys://receipts/list", { mimeType: "application/json", description: "Summary of all signed execution receipts" }, async () => {
+        const receipts = listReceiptFiles();
+        return {
+            contents: [{
+                    uri: "vaultys://receipts/list",
+                    mimeType: "application/json",
+                    text: JSON.stringify({
+                        total: receipts.length,
+                        receipts: receipts.map((r) => ({
+                            job_id: r.job_id,
+                            timestamp: r.timestamp,
+                            tool: r.tool,
+                            decision: r.decision,
+                        })),
+                    }, null, 2),
+                }],
+        };
+    });
+}
+function listReceiptFiles() {
+    if (!fs.existsSync(AUDIT_DIR))
+        return [];
+    return fs.readdirSync(AUDIT_DIR)
+        .filter((f) => f.endsWith(".json"))
+        .map((f) => {
+        try {
+            return JSON.parse(fs.readFileSync(path.join(AUDIT_DIR, f), "utf-8"));
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((r) => r !== null)
+        .sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+}

package/dist/src/server.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * VaultysID Policy-Enforced MCP Server
+ *
+ * Stdio transport — plug directly into Claude Desktop, Cursor, or any MCP client.
+ *
+ * Zero-config: just run `npx @vaultys/mcp-agent` — a default policy is
+ * auto-generated on first start. Customize with `vaultys-mcp-init`.
+ *
+ * Every tool call goes through:
+ *   tool invocation → capability mapping → policy evaluation → execute/deny → signed receipt
+ *
+ * Environment variables:
+ *   WORKSPACE_ROOT      — working directory for file/shell operations (default: cwd)
+ *   POLICY_FILE         — path to a custom signed policy file
+ *   AUTHORITY_FILE      — path to the authority identity export
+ *   VAULTYS_CONFIG_DIR  — config directory (default: ~/.vaultys-mcp)
+ */
+export {};

package/dist/src/server.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * VaultysID Policy-Enforced MCP Server
+ *
+ * Stdio transport — plug directly into Claude Desktop, Cursor, or any MCP client.
+ *
+ * Zero-config: just run `npx @vaultys/mcp-agent` — a default policy is
+ * auto-generated on first start. Customize with `vaultys-mcp-init`.
+ *
+ * Every tool call goes through:
+ *   tool invocation → capability mapping → policy evaluation → execute/deny → signed receipt
+ *
+ * Environment variables:
+ *   WORKSPACE_ROOT      — working directory for file/shell operations (default: cwd)
+ *   POLICY_FILE         — path to a custom signed policy file
+ *   AUTHORITY_FILE      — path to the authority identity export
+ *   VAULTYS_CONFIG_DIR  — config directory (default: ~/.vaultys-mcp)
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { autoInit, getConfigDir } from "./autoInit.js";
+import { createPolicyMiddleware } from "./policyMiddleware.js";
+import { registerFilesystemTools } from "./tools/filesystem.js";
+import { registerShellTool } from "./tools/shell.js";
+import { registerNetworkTool } from "./tools/network.js";
+import { registerResources } from "./resources/index.js";
+// ── Configuration ──
+const WORKSPACE_ROOT = path.resolve(process.env.WORKSPACE_ROOT ?? process.cwd());
+// ── Main ──
+async function main() {
+    console.error(`[VaultysID] Config dir: ${getConfigDir()}`);
+    // 1. Auto-initialize (identity + policy — generates defaults on first run)
+    const { serverIdm, signedPolicy, authorityDid } = await autoInit(WORKSPACE_ROOT);
+    // 2. Check time bounds
+    const now = Date.now();
+    if (signedPolicy.not_before && now < signedPolicy.not_before) {
+        console.error(`[VaultysID] ERROR: Policy is not yet valid`);
+        process.exit(1);
+    }
+    if (signedPolicy.not_after) {
+        const remaining = Math.round((signedPolicy.not_after - now) / 60000);
+        console.error(`[VaultysID] Policy expires in ${remaining} minutes`);
+    }
+    // 3. Ensure workspace exists
+    if (!fs.existsSync(WORKSPACE_ROOT)) {
+        fs.mkdirSync(WORKSPACE_ROOT, { recursive: true });
+    }
+    console.error(`[VaultysID] Workspace: ${WORKSPACE_ROOT}`);
+    // 4. Create policy middleware
+    const middleware = createPolicyMiddleware({
+        serverIdManager: serverIdm,
+        signedPolicy,
+        workspaceRoot: WORKSPACE_ROOT,
+    });
+    // 5. Create MCP Server
+    const mcpServer = new McpServer({
+        name: "vaultys-mcp-agent",
+        version: "0.1.0",
+    }, {
+        capabilities: {
+            resources: {},
+            tools: {},
+        },
+    });
+    // 6. Register tools (all wrapped by policy middleware)
+    registerFilesystemTools(mcpServer, middleware, WORKSPACE_ROOT);
+    registerShellTool(mcpServer, middleware, WORKSPACE_ROOT);
+    registerNetworkTool(mcpServer, middleware);
+    // 7. Register resources (audit trail, policy, identity)
+    registerResources(mcpServer, serverIdm, signedPolicy);
+    // 8. Connect via stdio transport
+    const transport = new StdioServerTransport();
+    await mcpServer.connect(transport);
+    console.error(`[VaultysID] MCP server running on stdio`);
+    console.error(`[VaultysID] Server DID: ${serverIdm.vaultysId.did}`);
+    if (authorityDid) {
+        console.error(`[VaultysID] Authority DID: ${authorityDid}`);
+    }
+    console.error(`[VaultysID] Tools: read_file, write_file, list_directory, run_command, fetch_url`);
+    console.error(`[VaultysID] Resources: vaultys://policy/current, vaultys://identity/server, vaultys://receipts/list`);
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/src/tools/filesystem.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Filesystem MCP tools — read_file, write_file, list_directory
+ *
+ * All operations are sandboxed to the workspace root via policy evaluation.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { createPolicyMiddleware } from "../policyMiddleware.js";
+type Middleware = ReturnType<typeof createPolicyMiddleware>;
+export declare function registerFilesystemTools(server: McpServer, middleware: Middleware, workspaceRoot: string): void;
+export {};

package/dist/src/tools/filesystem.js

@@ -0,0 +1,44 @@
+/**
+ * Filesystem MCP tools — read_file, write_file, list_directory
+ *
+ * All operations are sandboxed to the workspace root via policy evaluation.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { z } from "zod";
+export function registerFilesystemTools(server, middleware, workspaceRoot) {
+    // ── read_file ──
+    server.tool("read_file", "Read a file from the workspace. Returns the file contents.", { path: z.string().describe("Relative or absolute path to the file") }, async (args) => {
+        const result = await middleware.enforce("read_file", args, async () => {
+            const filePath = path.resolve(workspaceRoot, args.path);
+            return fs.readFileSync(filePath, "utf-8");
+        });
+        return { content: result.content, isError: result.decision === "deny" };
+    });
+    // ── write_file ──
+    server.tool("write_file", "Write content to a file in the workspace.", {
+        path: z.string().describe("Relative or absolute path to the file"),
+        content: z.string().describe("Content to write to the file"),
+    }, async (args) => {
+        const result = await middleware.enforce("write_file", args, async () => {
+            const filePath = path.resolve(workspaceRoot, args.path);
+            const dir = path.dirname(filePath);
+            if (!fs.existsSync(dir))
+                fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(filePath, args.content, "utf-8");
+            return `File written: ${args.path} (${args.content.length} bytes)`;
+        });
+        return { content: result.content, isError: result.decision === "deny" };
+    });
+    // ── list_directory ──
+    server.tool("list_directory", "List the contents of a directory in the workspace.", { path: z.string().describe("Relative or absolute path to the directory").default(".") }, async (args) => {
+        const result = await middleware.enforce("list_directory", args, async () => {
+            const dirPath = path.resolve(workspaceRoot, args.path);
+            const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+            return entries
+                .map((e) => `${e.isDirectory() ? "📁" : "📄"} ${e.name}`)
+                .join("\n");
+        });
+        return { content: result.content, isError: result.decision === "deny" };
+    });
+}

package/dist/src/tools/network.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Network MCP tool — fetch_url
+ *
+ * Fetches content from a URL with policy enforcement on the hostname.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { createPolicyMiddleware } from "../policyMiddleware.js";
+type Middleware = ReturnType<typeof createPolicyMiddleware>;
+export declare function registerNetworkTool(server: McpServer, middleware: Middleware): void;
+export {};

package/dist/src/tools/network.js

@@ -0,0 +1,25 @@
+/**
+ * Network MCP tool — fetch_url
+ *
+ * Fetches content from a URL with policy enforcement on the hostname.
+ */
+import { z } from "zod";
+export function registerNetworkTool(server, middleware) {
+    server.tool("fetch_url", "Fetch content from a URL. Subject to egress policy.", {
+        url: z.string().url().describe("The URL to fetch"),
+        method: z.enum(["GET", "POST", "PUT", "DELETE"]).default("GET").describe("HTTP method"),
+        body: z.string().optional().describe("Request body (for POST/PUT)"),
+    }, async (args) => {
+        const result = await middleware.enforce("fetch_url", args, async () => {
+            const init = { method: args.method };
+            if (args.body && (args.method === "POST" || args.method === "PUT")) {
+                init.body = args.body;
+                init.headers = { "Content-Type": "application/json" };
+            }
+            const response = await fetch(args.url, init);
+            const text = await response.text();
+            return `HTTP ${response.status} ${response.statusText}\n\n${text.slice(0, 10000)}`;
+        });
+        return { content: result.content, isError: result.decision === "deny" };
+    });
+}

package/dist/src/tools/shell.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shell MCP tool — run_command
+ *
+ * Executes shell commands with policy enforcement.
+ * Shell metacharacters are blocked by the `no_shell_features` constraint.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { createPolicyMiddleware } from "../policyMiddleware.js";
+type Middleware = ReturnType<typeof createPolicyMiddleware>;
+export declare function registerShellTool(server: McpServer, middleware: Middleware, workspaceRoot: string): void;
+export {};

package/dist/src/tools/shell.js

@@ -0,0 +1,26 @@
+/**
+ * Shell MCP tool — run_command
+ *
+ * Executes shell commands with policy enforcement.
+ * Shell metacharacters are blocked by the `no_shell_features` constraint.
+ */
+import { execSync } from "node:child_process";
+import { z } from "zod";
+export function registerShellTool(server, middleware, workspaceRoot) {
+    server.tool("run_command", "Run a shell command in the workspace directory. Subject to policy constraints.", {
+        command: z.string().describe("The command to execute (e.g. 'ls -la')"),
+        timeout: z.number().describe("Timeout in milliseconds").default(30000),
+    }, async (args) => {
+        const result = await middleware.enforce("run_command", args, async () => {
+            const output = execSync(args.command, {
+                cwd: workspaceRoot,
+                timeout: args.timeout,
+                encoding: "utf-8",
+                maxBuffer: 1024 * 1024, // 1MB
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            return output;
+        });
+        return { content: result.content, isError: result.decision === "deny" };
+    });
+}

package/dist/srp-grant-policy.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * SRP Policy Grant CLI
+ *
+ * Uses the VaultysID Secure Remote Protocol (SRP) to establish a policy
+ * agreement between a producer (authority) and an executor (MCP server).
+ * This is the canonical VaultysID pattern — both sides exchange certificates,
+ * and the policy is cryptographically bound to the SRP metadata.
+ *
+ * This replaces the manual file-based grant-policy.ts when both parties
+ * can communicate over a channel (e.g. in-process via MemoryChannel,
+ * or over a network via WebSocket/TCP).
+ *
+ * Usage:
+ *   pnpm srp-grant   # runs a local in-process SRP handshake
+ *
+ * What happens:
+ *   1. Producer and executor identities are loaded or created
+ *   2. A MemoryChannel (bidirectional) connects them
+ *   3. grantPolicy() and acceptPolicy() run concurrently
+ *   4. Both sides store the agreed policy + SRP certificate
+ *   5. The executor can now evaluate intents against the stored policy
+ */
+export {};