@vaultys/mcp-agent 0.1.0

package/dist/grant-policy.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * Grant Policy CLI
+ *
+ * Creates an authority identity and signs a policy bundle.
+ * Outputs:
+ *   - policy.signed.json       — the signed policy (loaded by the MCP server)
+ *   - authority.identity.json  — the authority's public key (for verification)
+ *   - authority.secret.json    — the authority's full identity (keep safe!)
+ *
+ * Usage:
+ *   pnpm grant-policy                          # uses policy.example.json, 24h validity
+ *   pnpm grant-policy -- --policy custom.json  # custom policy file
+ *   pnpm grant-policy -- --hours 2             # 2-hour validity window
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ExecutionManager, MemoryStorage, IdManager } from "@vaultys/id";
+// ── Parse args ──
+const args = process.argv.slice(2);
+function getArg(name, defaultValue) {
+    const idx = args.indexOf(`--${name}`);
+    if (idx !== -1 && args[idx + 1])
+        return args[idx + 1];
+    return defaultValue;
+}
+const policyFile = getArg("policy", "policy.example.json");
+const hours = parseInt(getArg("hours", "24"), 10);
+const workspaceRoot = path.resolve(getArg("workspace", "workspace"));
+const AUTHORITY_IDENTITY_FILE = "authority.secret.json";
+const AUTHORITY_PUBLIC_FILE = "authority.identity.json";
+const SIGNED_POLICY_FILE = "policy.signed.json";
+async function main() {
+    // 1. Load or create authority identity
+    let authorityIdm;
+    if (fs.existsSync(AUTHORITY_IDENTITY_FILE)) {
+        const data = fs.readFileSync(AUTHORITY_IDENTITY_FILE, "utf-8");
+        const store = MemoryStorage().fromString(data);
+        const loaded = await IdManager.fromStore(store);
+        if (!loaded)
+            throw new Error("Failed to load authority identity");
+        authorityIdm = loaded;
+        authorityIdm.setProtocolVersion(1);
+        console.log(`✓ Loaded authority identity: ${authorityIdm.vaultysId.did}`);
+    }
+    else {
+        const store = MemoryStorage();
+        authorityIdm = await IdManager.fromStore(store);
+        authorityIdm.setProtocolVersion(1);
+        fs.writeFileSync(AUTHORITY_IDENTITY_FILE, store.toString());
+        console.log(`✓ Generated authority identity: ${authorityIdm.vaultysId.did}`);
+        console.log(`  Saved to: ${AUTHORITY_IDENTITY_FILE}`);
+    }
+    // 2. Export authority public identity for the server
+    // VaultysId.id contains the full public identity (can be reconstructed with VaultysId.fromId)
+    const vid = authorityIdm.vaultysId;
+    fs.writeFileSync(AUTHORITY_PUBLIC_FILE, JSON.stringify({
+        did: vid.did,
+        id: Buffer.from(vid.id).toString("base64"),
+        fingerprint: vid.fingerprint,
+    }, null, 2));
+    console.log(`✓ Authority public identity saved to: ${AUTHORITY_PUBLIC_FILE}`);
+    // 3. Load policy template
+    if (!fs.existsSync(policyFile)) {
+        console.error(`✗ Policy file not found: ${policyFile}`);
+        process.exit(1);
+    }
+    const policyTemplate = JSON.parse(fs.readFileSync(policyFile, "utf-8"));
+    console.log(`✓ Loaded policy template: ${policyFile}`);
+    // 3a. Substitute {{WORKSPACE}} placeholder with the actual workspace path
+    if (policyTemplate.scopes) {
+        for (const [key, patterns] of Object.entries(policyTemplate.scopes)) {
+            if (Array.isArray(patterns)) {
+                policyTemplate.scopes[key] = patterns.map((p) => p.replace(/\{\{WORKSPACE\}\}/g, workspaceRoot));
+            }
+        }
+    }
+    console.log(`  Workspace root: ${workspaceRoot}`);
+    // 4. Add time bounds
+    const now = Date.now();
+    const policy = {
+        ...policyTemplate,
+        not_before: now,
+        not_after: now + hours * 3600_000,
+    };
+    console.log(`  Valid from: ${new Date(policy.not_before).toISOString()}`);
+    console.log(`  Expires:    ${new Date(policy.not_after).toISOString()}`);
+    console.log(`  Duration:   ${hours} hours`);
+    // 5. Sign the policy
+    const em = new ExecutionManager(authorityIdm);
+    const signed = await em.signPolicy(policy);
+    // 6. Serialize (convert Buffer signature to base64 string for JSON storage)
+    const serializable = {
+        ...signed,
+        signature: signed.signature ? Buffer.from(signed.signature).toString("base64") : undefined,
+    };
+    fs.writeFileSync(SIGNED_POLICY_FILE, JSON.stringify(serializable, null, 2));
+    console.log(`\n✓ Signed policy saved to: ${SIGNED_POLICY_FILE}`);
+    // Summary
+    console.log("\n┌──────────────────────────────────────────────┐");
+    console.log("│  Policy signed successfully!                 │");
+    console.log("├──────────────────────────────────────────────┤");
+    console.log(`│  Authority DID: ${authorityIdm.vaultysId.did.slice(0, 30)}...│`);
+    console.log("│                                              │");
+    console.log("│  To start the MCP server:                    │");
+    console.log("│    pnpm start                                │");
+    console.log("│                                              │");
+    console.log("│  Files generated:                            │");
+    console.log(`│    ${SIGNED_POLICY_FILE.padEnd(41)}│`);
+    console.log(`│    ${AUTHORITY_PUBLIC_FILE.padEnd(41)}│`);
+    console.log(`│    ${AUTHORITY_IDENTITY_FILE.padEnd(41)}│`);
+    console.log("└──────────────────────────────────────────────┘");
+}
+main().catch((err) => {
+    console.error("Error:", err);
+    process.exit(1);
+});

package/dist/src/audit.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Audit Verify CLI
+ *
+ * Walks through all signed receipts in ./audit/ and verifies each one.
+ * Also detects tampering by re-verifying broker signatures.
+ *
+ * Usage:
+ *   pnpm audit                      # verify all receipts
+ *   pnpm audit -- --tamper <id>     # tamper with a receipt then verify (demo)
+ */
+export {};

package/dist/src/audit.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * Audit Verify CLI
+ *
+ * Walks through all signed receipts in ./audit/ and verifies each one.
+ * Also detects tampering by re-verifying broker signatures.
+ *
+ * Usage:
+ *   pnpm audit                      # verify all receipts
+ *   pnpm audit -- --tamper <id>     # tamper with a receipt then verify (demo)
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ExecutionManager, IdManager, MemoryStorage } from "@vaultys/id";
+const AUDIT_DIR = path.resolve("audit");
+const IDENTITY_FILE = "server.identity.json";
+function loadServerPublicKey() {
+    if (!fs.existsSync(IDENTITY_FILE)) {
+        console.error("⚠ No server identity found. Cannot verify receipts.");
+        return null;
+    }
+    // We need the server's serialized identity to extract the public key.
+    // For verification we only need the public key, but the serialized format has it.
+    // We'll load it as a full IdManager to get the VaultysId.
+    return null; // Will use async version
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const tamperIdx = args.indexOf("--tamper");
+    const tamperId = tamperIdx !== -1 ? args[tamperIdx + 1] : null;
+    console.log("╔══════════════════════════════════════════════════╗");
+    console.log("║  VaultysID Audit Trail Verifier                 ║");
+    console.log("╚══════════════════════════════════════════════════╝");
+    console.log();
+    // Load server identity for signature verification
+    let serverVaultysId = null;
+    if (fs.existsSync(IDENTITY_FILE)) {
+        // Read the serialized identity to extract the VaultysId
+        const data = fs.readFileSync(IDENTITY_FILE, "utf-8");
+        const store = MemoryStorage().fromString(data);
+        const idm = await IdManager.fromStore(store);
+        if (idm) {
+            serverVaultysId = idm.vaultysId;
+            console.log(`Server DID: ${serverVaultysId.did}`);
+        }
+    }
+    if (!serverVaultysId) {
+        console.error("⚠  Cannot load server identity — signature verification disabled");
+    }
+    console.log();
+    // Load all receipts
+    if (!fs.existsSync(AUDIT_DIR)) {
+        console.log("No audit records found. Run some tool calls first!");
+        return;
+    }
+    const files = fs.readdirSync(AUDIT_DIR).filter((f) => f.endsWith(".json")).sort();
+    if (files.length === 0) {
+        console.log("No audit records found. Run some tool calls first!");
+        return;
+    }
+    console.log(`Found ${files.length} receipt(s)\n`);
+    // Optionally tamper with a receipt for demo purposes
+    if (tamperId) {
+        const tamperFile = path.join(AUDIT_DIR, `${tamperId}.json`);
+        if (fs.existsSync(tamperFile)) {
+            const record = JSON.parse(fs.readFileSync(tamperFile, "utf-8"));
+            record.receipt.exec.exit_code = 999; // Tamper!
+            fs.writeFileSync(tamperFile, JSON.stringify(record, null, 2));
+            console.log(`🔧 TAMPERED with receipt ${tamperId} (changed exit_code to 999)\n`);
+        }
+        else {
+            console.error(`⚠  Receipt ${tamperId} not found for tampering`);
+        }
+    }
+    let passed = 0;
+    let failed = 0;
+    let skipped = 0;
+    for (const file of files) {
+        const filePath = path.join(AUDIT_DIR, file);
+        let record;
+        try {
+            record = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+        }
+        catch {
+            console.log(`  ⚠  ${file}: invalid JSON`);
+            skipped++;
+            continue;
+        }
+        const receipt = record.receipt;
+        const jobId = record.job_id;
+        const decision = record.decision;
+        const tool = record.tool;
+        // Restore Buffer types for signature
+        if (receipt.broker_signature && typeof receipt.broker_signature === "string") {
+            receipt.broker_signature = Buffer.from(receipt.broker_signature, "base64");
+        }
+        let verified = false;
+        let sigStatus = "⏭  no key";
+        if (serverVaultysId) {
+            verified = ExecutionManager.verifyReceipt(receipt, serverVaultysId);
+            sigStatus = verified ? "✅ VALID" : "❌ INVALID";
+            if (verified)
+                passed++;
+            else
+                failed++;
+        }
+        else {
+            skipped++;
+        }
+        const decisionIcon = decision === "allow" ? "🟢" : "🔴";
+        console.log(`  ${sigStatus}  ${decisionIcon} ${tool.padEnd(16)}  ${jobId}  ${record.timestamp}`);
+        if (!verified && serverVaultysId) {
+            console.log(`           ⚠  Signature verification FAILED — possible tampering!`);
+        }
+    }
+    console.log();
+    console.log("─".repeat(52));
+    console.log(`  Results: ${passed} verified, ${failed} FAILED, ${skipped} skipped`);
+    if (failed > 0) {
+        console.log();
+        console.log("  ⚠  TAMPERING DETECTED in one or more receipts!");
+        console.log("  ⚠  The audit trail has been compromised.");
+    }
+    else if (passed > 0) {
+        console.log();
+        console.log("  ✅ All receipts verified — audit trail is intact.");
+    }
+    console.log();
+}
+main().catch((err) => {
+    console.error("Error:", err);
+    process.exit(1);
+});

package/dist/src/autoInit.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Auto-initialization for zero-config startup.
+ *
+ * When the server starts without a signed policy, this module generates
+ * a self-signed default policy so `npx @vaultys/mcp-agent` works immediately.
+ *
+ * Config directory defaults to ~/.vaultys-mcp/ (overridable via VAULTYS_CONFIG_DIR).
+ */
+import { IdManager } from "@vaultys/id";
+import type { PolicyBundle } from "@vaultys/id";
+export declare function getConfigDir(): string;
+export declare function ensureConfigDir(): string;
+export declare function configPath(filename: string): string;
+/**
+ * Build a policy with resolved workspace path and time bounds.
+ */
+export declare function buildPolicy(workspaceRoot: string, hours?: number): Omit<PolicyBundle, "signature">;
+/**
+ * Load or create a persisted IdManager from a file.
+ */
+export declare function loadOrCreateIdentity(filePath: string): Promise<{
+    idm: IdManager;
+    created: boolean;
+}>;
+/**
+ * Sign and persist a policy. Returns the signed policy and authority IdManager.
+ */
+export declare function signAndPersistPolicy(workspaceRoot: string, hours?: number): Promise<{
+    signedPolicy: PolicyBundle;
+    authorityIdm: IdManager;
+}>;
+/**
+ * Auto-initialize: load existing policy or generate a default one.
+ * Returns all the artifacts needed to start the server.
+ */
+export declare function autoInit(workspaceRoot: string): Promise<{
+    serverIdm: IdManager;
+    signedPolicy: PolicyBundle;
+    authorityDid: string;
+}>;

package/dist/src/autoInit.js

@@ -0,0 +1,169 @@
+/**
+ * Auto-initialization for zero-config startup.
+ *
+ * When the server starts without a signed policy, this module generates
+ * a self-signed default policy so `npx @vaultys/mcp-agent` works immediately.
+ *
+ * Config directory defaults to ~/.vaultys-mcp/ (overridable via VAULTYS_CONFIG_DIR).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { ExecutionManager, MemoryStorage, IdManager } from "@vaultys/id";
+// ── Config directory ──
+export function getConfigDir() {
+    return process.env.VAULTYS_CONFIG_DIR ?? path.join(os.homedir(), ".vaultys-mcp");
+}
+export function ensureConfigDir() {
+    const dir = getConfigDir();
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    return dir;
+}
+// ── Paths ──
+export function configPath(filename) {
+    return path.join(getConfigDir(), filename);
+}
+// ── Default policy ──
+const DEFAULT_POLICY_TEMPLATE = {
+    version: "1.0",
+    scopes: {
+        "fs.read": ["{{WORKSPACE}}/**"],
+        "fs.write": ["{{WORKSPACE}}/**"],
+        "fs.list": ["{{WORKSPACE}}/**"],
+        "proc.exec": ["ls", "cat", "echo", "wc", "head", "tail", "grep", "find", "pwd", "date", "whoami"],
+        "net.egress.http": ["*"],
+    },
+    denied: ["secrets.*", "pkg.system", "proc.privilege"],
+    constraints: {
+        max_runtime: 300,
+        no_shell_features: true,
+    },
+};
+/**
+ * Build a policy with resolved workspace path and time bounds.
+ */
+export function buildPolicy(workspaceRoot, hours = 24 * 365) {
+    const now = Date.now();
+    // Deep-clone and substitute workspace
+    const scopes = {};
+    for (const [key, patterns] of Object.entries(DEFAULT_POLICY_TEMPLATE.scopes)) {
+        scopes[key] = patterns.map((p) => p.replace(/\{\{WORKSPACE\}\}/g, workspaceRoot));
+    }
+    return {
+        ...DEFAULT_POLICY_TEMPLATE,
+        scopes,
+        not_before: now,
+        not_after: now + hours * 3600_000,
+    };
+}
+/**
+ * Load or create a persisted IdManager from a file.
+ */
+export async function loadOrCreateIdentity(filePath) {
+    if (fs.existsSync(filePath)) {
+        const data = fs.readFileSync(filePath, "utf-8");
+        const store = MemoryStorage().fromString(data);
+        const idm = await IdManager.fromStore(store);
+        idm.setProtocolVersion(1);
+        return { idm, created: false };
+    }
+    const store = MemoryStorage();
+    const idm = await IdManager.fromStore(store);
+    idm.setProtocolVersion(1);
+    fs.writeFileSync(filePath, store.toString());
+    return { idm, created: true };
+}
+/**
+ * Sign and persist a policy. Returns the signed policy and authority IdManager.
+ */
+export async function signAndPersistPolicy(workspaceRoot, hours) {
+    const dir = ensureConfigDir();
+    // Load or create authority
+    const { idm: authorityIdm, created } = await loadOrCreateIdentity(configPath("authority.secret.json"));
+    if (created) {
+        console.error(`[VaultysID] Generated authority identity: ${authorityIdm.vaultysId.did}`);
+    }
+    // Export public key
+    const vid = authorityIdm.vaultysId;
+    fs.writeFileSync(configPath("authority.identity.json"), JSON.stringify({
+        did: vid.did,
+        id: Buffer.from(vid.id).toString("base64"),
+        fingerprint: vid.fingerprint,
+    }, null, 2));
+    // Build and sign
+    const policy = buildPolicy(workspaceRoot, hours);
+    const em = new ExecutionManager(authorityIdm);
+    const signedPolicy = await em.signPolicy(policy);
+    // Persist (serialize Buffer signature to base64 for JSON)
+    const serializable = {
+        ...signedPolicy,
+        signature: signedPolicy.signature
+            ? Buffer.from(signedPolicy.signature).toString("base64")
+            : undefined,
+    };
+    fs.writeFileSync(configPath("policy.signed.json"), JSON.stringify(serializable, null, 2));
+    return { signedPolicy, authorityIdm };
+}
+/**
+ * Auto-initialize: load existing policy or generate a default one.
+ * Returns all the artifacts needed to start the server.
+ */
+export async function autoInit(workspaceRoot) {
+    const dir = ensureConfigDir();
+    // 1. Server identity
+    const { idm: serverIdm, created: serverCreated } = await loadOrCreateIdentity(configPath("server.identity.json"));
+    if (serverCreated) {
+        console.error(`[VaultysID] Generated server identity: ${serverIdm.vaultysId.did}`);
+    }
+    else {
+        console.error(`[VaultysID] Loaded server identity: ${serverIdm.vaultysId.did}`);
+    }
+    // 2. Policy — try to load existing, otherwise auto-generate
+    const policyPath = process.env.POLICY_FILE ?? configPath("policy.signed.json");
+    const authorityPath = process.env.AUTHORITY_FILE ?? configPath("authority.identity.json");
+    let signedPolicy;
+    let authorityDid = "";
+    if (fs.existsSync(policyPath)) {
+        const raw = JSON.parse(fs.readFileSync(policyPath, "utf-8"));
+        if (raw.signature && typeof raw.signature === "string") {
+            raw.signature = Buffer.from(raw.signature, "base64");
+        }
+        signedPolicy = raw;
+        console.error(`[VaultysID] Loaded policy (version ${signedPolicy.version})`);
+        // Verify if authority key is available
+        if (fs.existsSync(authorityPath)) {
+            const authRaw = JSON.parse(fs.readFileSync(authorityPath, "utf-8"));
+            const { VaultysId } = await import("@vaultys/id");
+            const authVid = VaultysId.fromId(Buffer.from(authRaw.id, "base64"));
+            const valid = ExecutionManager.verifyPolicy(signedPolicy, authVid);
+            if (!valid) {
+                console.error(`[VaultysID] WARNING: Policy signature verification FAILED`);
+            }
+            else {
+                console.error(`[VaultysID] Policy signature verified ✓`);
+            }
+            authorityDid = authVid.did;
+        }
+        // Check expiry
+        const now = Date.now();
+        if (signedPolicy.not_after && now > signedPolicy.not_after) {
+            console.error(`[VaultysID] Policy expired — regenerating...`);
+            const result = await signAndPersistPolicy(workspaceRoot);
+            signedPolicy = result.signedPolicy;
+            authorityDid = result.authorityIdm.vaultysId.did;
+            console.error(`[VaultysID] New policy generated (expires in 1 year)`);
+        }
+    }
+    else {
+        // Auto-generate default policy
+        console.error(`[VaultysID] No policy found — generating default policy...`);
+        const result = await signAndPersistPolicy(workspaceRoot);
+        signedPolicy = result.signedPolicy;
+        authorityDid = result.authorityIdm.vaultysId.did;
+        console.error(`[VaultysID] Default policy generated at ${policyPath}`);
+        console.error(`[VaultysID] Run 'vaultys-mcp-init' to customize`);
+    }
+    return { serverIdm, signedPolicy, authorityDid };
+}

package/dist/src/policyMiddleware.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 { ExecutionManager } from "@vaultys/id";
+import type { PolicyBundle, SignedReceipt } from "@vaultys/id";
+import type { IdManager } from "@vaultys/id";
+export interface CapabilityMapping {
+    /** Taxonomy prefix, e.g. "fs.read" */
+    capability: string;
+    /** Extract the scope string from the tool arguments. workspaceRoot is provided for path resolution. */
+    extractScope: (args: Record<string, unknown>, workspaceRoot?: string) => string;
+}
+/**
+ * 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 declare const DEFAULT_TOOL_MAPPINGS: Record<string, CapabilityMapping>;
+export interface PolicyMiddlewareOptions {
+    serverIdManager: IdManager;
+    signedPolicy: PolicyBundle;
+    toolMappings?: Record<string, CapabilityMapping>;
+    workspaceRoot?: string;
+}
+export interface ToolCallResult {
+    decision: "allow" | "deny";
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    receipt?: SignedReceipt;
+    jobId?: string;
+}
+/**
+ * Create policy-enforced middleware that wraps MCP tool handlers.
+ */
+export declare function createPolicyMiddleware(options: PolicyMiddlewareOptions): {
+    enforce: (toolName: string, args: Record<string, unknown>, handler: () => Promise<string>) => Promise<ToolCallResult>;
+    em: ExecutionManager;
+};