@usekova/mcp-server 0.1.0 → 2.0.0

package/dist/index.js

@@ -1,9 +1,666 @@
 "use strict";
-/**
- * @stele/mcp-server — Model Context Protocol server that exposes
- * Stele tools to any AI agent.
- *
- * @packageDocumentation
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=index.js.map
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  JSON_RPC_ERRORS: () => JSON_RPC_ERRORS,
+  SteleServer: () => SteleServer,
+  createAuthMiddleware: () => createAuthMiddleware
+});
+module.exports = __toCommonJS(index_exports);
+var import_sdk = require("@usekova/sdk");
+var import_crypto2 = require("@usekova/crypto");
+
+// src/types.ts
+var JSON_RPC_ERRORS = {
+  /** Invalid JSON was received by the server. */
+  PARSE_ERROR: -32700,
+  /** The JSON sent is not a valid Request object. */
+  INVALID_REQUEST: -32600,
+  /** The method does not exist or is not available. */
+  METHOD_NOT_FOUND: -32601,
+  /** Invalid method parameter(s). */
+  INVALID_PARAMS: -32602,
+  /** Internal JSON-RPC error. */
+  INTERNAL_ERROR: -32603
+};
+
+// src/auth.ts
+var import_crypto = require("@usekova/crypto");
+function createAuthMiddleware(options) {
+  const apiKeys = new Set(options.apiKeys ?? []);
+  const trustedKeys = new Set(options.trustedKeys ?? []);
+  const rateLimitPerMinute = options.rateLimitPerMinute ?? 0;
+  const clientRates = /* @__PURE__ */ new Map();
+  const knownClients = /* @__PURE__ */ new Set();
+  function authenticate(headers) {
+    const now = (0, import_crypto.timestamp)();
+    const apiKey = headers["x-api-key"];
+    if (apiKey) {
+      if (!apiKeys.has(apiKey)) {
+        throw new Error("Invalid API key");
+      }
+      const clientId = `apikey:${(0, import_crypto.sha256String)(apiKey).slice(0, 16)}`;
+      knownClients.add(clientId);
+      return {
+        clientId,
+        authMethod: "api-key",
+        timestamp: now
+      };
+    }
+    const publicKeyHex = headers["x-public-key"];
+    const signatureHex = headers["x-signature"];
+    const payload = headers["x-signature-payload"];
+    if (publicKeyHex && signatureHex && payload) {
+      if (!trustedKeys.has(publicKeyHex)) {
+        throw new Error("Untrusted public key");
+      }
+      const clientId = `sig:${publicKeyHex.slice(0, 16)}`;
+      knownClients.add(clientId);
+      return {
+        clientId,
+        authMethod: "signature",
+        timestamp: now
+      };
+    }
+    if (apiKeys.size === 0 && trustedKeys.size === 0) {
+      const clientId = "anonymous";
+      knownClients.add(clientId);
+      return {
+        clientId,
+        authMethod: "none",
+        timestamp: now
+      };
+    }
+    throw new Error("Authentication required");
+  }
+  function isRateLimited(clientId) {
+    if (rateLimitPerMinute <= 0) {
+      return false;
+    }
+    const now = Date.now();
+    const windowMs = 6e4;
+    let window = clientRates.get(clientId);
+    if (!window) {
+      window = { timestamps: [] };
+      clientRates.set(clientId, window);
+    }
+    window.timestamps = window.timestamps.filter(
+      (ts) => now - ts < windowMs
+    );
+    if (window.timestamps.length >= rateLimitPerMinute) {
+      return true;
+    }
+    window.timestamps.push(now);
+    return false;
+  }
+  function revokeKey(key) {
+    apiKeys.delete(key);
+    trustedKeys.delete(key);
+  }
+  function listClients() {
+    return Array.from(knownClients);
+  }
+  return {
+    authenticate,
+    isRateLimited,
+    revokeKey,
+    listClients
+  };
+}
+
+// src/index.ts
+var TOOL_DEFINITIONS = [
+  {
+    name: "create_covenant",
+    description: "Create a new signed covenant document with CCL constraints between an issuer and beneficiary.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        issuer: {
+          type: "object",
+          description: 'The issuing party. Must have id, publicKey, and role="issuer".',
+          properties: {
+            id: { type: "string", description: "Unique identifier for the issuer." },
+            publicKey: { type: "string", description: "Hex-encoded Ed25519 public key." },
+            role: { type: "string", description: 'Must be "issuer".', enum: ["issuer"] },
+            name: { type: "string", description: "Optional human-readable name." }
+          },
+          required: ["id", "publicKey", "role"]
+        },
+        beneficiary: {
+          type: "object",
+          description: 'The beneficiary party. Must have id, publicKey, and role="beneficiary".',
+          properties: {
+            id: { type: "string", description: "Unique identifier for the beneficiary." },
+            publicKey: { type: "string", description: "Hex-encoded Ed25519 public key." },
+            role: { type: "string", description: 'Must be "beneficiary".', enum: ["beneficiary"] },
+            name: { type: "string", description: "Optional human-readable name." }
+          },
+          required: ["id", "publicKey", "role"]
+        },
+        constraints: {
+          type: "string",
+          description: `CCL constraint source text (e.g. "permit read on '**'").`
+        },
+        privateKeyHex: {
+          type: "string",
+          description: "Hex-encoded issuer private key for signing."
+        }
+      },
+      required: ["issuer", "beneficiary", "constraints", "privateKeyHex"]
+    }
+  },
+  {
+    name: "verify_covenant",
+    description: "Verify a covenant document by running all specification checks (signature, expiry, CCL syntax, etc.).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        covenantId: {
+          type: "string",
+          description: "The ID of the covenant document in the store to verify."
+        }
+      },
+      required: ["covenantId"]
+    }
+  },
+  {
+    name: "evaluate_action",
+    description: "Evaluate whether a specific action on a resource is permitted by a covenant's CCL constraints.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        covenantId: {
+          type: "string",
+          description: "The ID of the covenant document to evaluate against."
+        },
+        action: {
+          type: "string",
+          description: 'The action to evaluate (e.g. "read", "write", "file.delete").'
+        },
+        resource: {
+          type: "string",
+          description: 'The resource path to evaluate (e.g. "/data", "/files/**").'
+        },
+        context: {
+          type: "object",
+          description: "Optional evaluation context with additional variables for condition matching."
+        }
+      },
+      required: ["covenantId", "action", "resource"]
+    }
+  },
+  {
+    name: "create_identity",
+    description: "Create a new agent identity with model attestation, capabilities, and deployment context.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        operatorIdentifier: {
+          type: "string",
+          description: "Optional human-readable operator identifier."
+        },
+        model: {
+          type: "object",
+          description: "Model attestation describing the AI model.",
+          properties: {
+            provider: { type: "string", description: 'Model provider (e.g. "anthropic").' },
+            modelId: { type: "string", description: 'Model identifier (e.g. "claude-3").' },
+            modelVersion: { type: "string", description: "Optional model version." }
+          },
+          required: ["provider", "modelId"]
+        },
+        capabilities: {
+          type: "array",
+          description: "List of capability strings this agent has.",
+          items: { type: "string" }
+        },
+        deployment: {
+          type: "object",
+          description: "Deployment context describing where the agent runs.",
+          properties: {
+            runtime: { type: "string", description: 'Runtime type (e.g. "process", "container", "wasm").', enum: ["wasm", "container", "tee", "firecracker", "process", "browser"] },
+            region: { type: "string", description: "Optional deployment region." },
+            provider: { type: "string", description: "Optional cloud provider." }
+          },
+          required: ["runtime"]
+        },
+        privateKeyHex: {
+          type: "string",
+          description: "Optional hex-encoded operator private key. A new key pair is generated if omitted."
+        }
+      },
+      required: ["model", "capabilities", "deployment"]
+    }
+  },
+  {
+    name: "parse_ccl",
+    description: "Parse CCL (Covenant Constraint Language) source text and return the structured document.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        source: {
+          type: "string",
+          description: "The CCL source text to parse."
+        }
+      },
+      required: ["source"]
+    }
+  },
+  {
+    name: "list_covenants",
+    description: "List all covenant documents currently in the store, optionally filtered by issuer or beneficiary.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        issuerId: {
+          type: "string",
+          description: "Optional filter: only return covenants from this issuer."
+        },
+        beneficiaryId: {
+          type: "string",
+          description: "Optional filter: only return covenants for this beneficiary."
+        }
+      }
+    }
+  }
+];
+var SteleServer = class {
+  /** The backing store for covenant documents. */
+  store;
+  /** The SDK client used for operations. */
+  client;
+  /** Server name. */
+  name;
+  /** Server version. */
+  version;
+  constructor(store, options) {
+    this.store = store;
+    this.client = new import_sdk.KovaClient();
+    this.name = options?.name ?? "stele-mcp-server";
+    this.version = options?.version ?? "0.1.0";
+  }
+  // ── Tool listing ────────────────────────────────────────────────────────────
+  /**
+   * Return all available tool definitions with their JSON Schema input schemas.
+   */
+  listTools() {
+    return [...TOOL_DEFINITIONS];
+  }
+  // ── Tool execution ──────────────────────────────────────────────────────────
+  /**
+   * Call a named tool with the given arguments.
+   *
+   * @param name - The tool name (must match one of the tool definitions).
+   * @param args - The tool arguments matching the tool's input schema.
+   * @returns A {@link ToolResult} containing the output or error.
+   */
+  async callTool(name, args) {
+    switch (name) {
+      case "create_covenant":
+        return this._createCovenant(args);
+      case "verify_covenant":
+        return this._verifyCovenant(args);
+      case "evaluate_action":
+        return this._evaluateAction(args);
+      case "create_identity":
+        return this._createIdentity(args);
+      case "parse_ccl":
+        return this._parseCCL(args);
+      case "list_covenants":
+        return this._listCovenants(args);
+      default:
+        return {
+          content: [{ type: "text", text: `Unknown tool: ${name}` }],
+          isError: true
+        };
+    }
+  }
+  // ── JSON-RPC 2.0 message handler ────────────────────────────────────────────
+  /**
+   * Handle a JSON-RPC 2.0 message and return the appropriate response.
+   *
+   * Supports the following MCP methods:
+   * - `initialize` -- Returns server info and capabilities
+   * - `tools/list` -- Returns available tool definitions
+   * - `tools/call` -- Executes a tool and returns the result
+   * - `ping` -- Returns a pong
+   *
+   * @param message - A parsed JSON-RPC request object.
+   * @returns A JSON-RPC response object.
+   */
+  async handleMessage(message) {
+    if (!message || typeof message !== "object") {
+      return this._errorResponse(null, JSON_RPC_ERRORS.INVALID_REQUEST, "Invalid request object");
+    }
+    if (message.jsonrpc !== "2.0") {
+      return this._errorResponse(
+        message.id ?? null,
+        JSON_RPC_ERRORS.INVALID_REQUEST,
+        'Invalid jsonrpc version, expected "2.0"'
+      );
+    }
+    if (typeof message.method !== "string" || message.method.length === 0) {
+      return this._errorResponse(
+        message.id ?? null,
+        JSON_RPC_ERRORS.INVALID_REQUEST,
+        "Missing or invalid method"
+      );
+    }
+    const id = message.id ?? null;
+    switch (message.method) {
+      case "initialize":
+        return this._successResponse(id, {
+          protocolVersion: "2024-11-05",
+          capabilities: {
+            tools: {},
+            resources: {},
+            prompts: {}
+          },
+          serverInfo: {
+            name: this.name,
+            version: this.version
+          }
+        });
+      case "ping":
+        return this._successResponse(id, {});
+      case "tools/list":
+        return this._successResponse(id, {
+          tools: this.listTools()
+        });
+      case "tools/call": {
+        const params = message.params;
+        if (!params || typeof params.name !== "string") {
+          return this._errorResponse(id, JSON_RPC_ERRORS.INVALID_PARAMS, "Missing required param: name");
+        }
+        const toolName = params.name;
+        const toolArgs = params.arguments ?? {};
+        const toolDef = TOOL_DEFINITIONS.find((t) => t.name === toolName);
+        if (!toolDef) {
+          return this._errorResponse(id, JSON_RPC_ERRORS.INVALID_PARAMS, `Unknown tool: ${toolName}`);
+        }
+        const result = await this.callTool(toolName, toolArgs);
+        return this._successResponse(id, result);
+      }
+      case "notifications/initialized":
+        return this._successResponse(id, {});
+      case "resources/list":
+        return this._successResponse(id, { resources: [] });
+      case "resources/templates/list":
+        return this._successResponse(id, { resourceTemplates: [] });
+      case "prompts/list":
+        return this._successResponse(id, { prompts: [] });
+      default:
+        return this._errorResponse(id, JSON_RPC_ERRORS.METHOD_NOT_FOUND, `Unknown method: ${message.method}`);
+    }
+  }
+  // ── Tool implementations ──────────────────────────────────────────────────
+  async _createCovenant(args) {
+    try {
+      const issuer = args.issuer;
+      const beneficiary = args.beneficiary;
+      const constraints = args.constraints;
+      const privateKeyHex = args.privateKeyHex;
+      if (!issuer || !issuer.id || !issuer.publicKey || !issuer.role) {
+        return this._toolError("Missing required field: issuer (must have id, publicKey, role)");
+      }
+      if (!beneficiary || !beneficiary.id || !beneficiary.publicKey || !beneficiary.role) {
+        return this._toolError("Missing required field: beneficiary (must have id, publicKey, role)");
+      }
+      if (!constraints || typeof constraints !== "string") {
+        return this._toolError("Missing required field: constraints");
+      }
+      if (!privateKeyHex || typeof privateKeyHex !== "string") {
+        return this._toolError("Missing required field: privateKeyHex");
+      }
+      const { fromHex: fromHex2 } = await import("@usekova/crypto");
+      const privateKey = fromHex2(privateKeyHex);
+      const doc = await this.client.createCovenant({
+        issuer: {
+          id: issuer.id,
+          publicKey: issuer.publicKey,
+          role: "issuer",
+          name: issuer.name
+        },
+        beneficiary: {
+          id: beneficiary.id,
+          publicKey: beneficiary.publicKey,
+          role: "beneficiary",
+          name: beneficiary.name
+        },
+        constraints,
+        privateKey
+      });
+      await this.store.put(doc);
+      return this._toolSuccess({
+        id: doc.id,
+        version: doc.version,
+        issuer: doc.issuer,
+        beneficiary: doc.beneficiary,
+        constraints: doc.constraints,
+        createdAt: doc.createdAt
+      });
+    } catch (err) {
+      return this._toolError(`Failed to create covenant: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  async _verifyCovenant(args) {
+    try {
+      const covenantId = args.covenantId;
+      if (!covenantId || typeof covenantId !== "string") {
+        return this._toolError("Missing required field: covenantId");
+      }
+      const doc = await this.store.get(covenantId);
+      if (!doc) {
+        return this._toolError(`Covenant not found: ${covenantId}`);
+      }
+      const result = await this.client.verifyCovenant(doc);
+      return this._toolSuccess({
+        valid: result.valid,
+        checks: result.checks
+      });
+    } catch (err) {
+      return this._toolError(`Failed to verify covenant: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  async _evaluateAction(args) {
+    try {
+      const covenantId = args.covenantId;
+      const action = args.action;
+      const resource = args.resource;
+      const context = args.context;
+      if (!covenantId || typeof covenantId !== "string") {
+        return this._toolError("Missing required field: covenantId");
+      }
+      if (!action || typeof action !== "string") {
+        return this._toolError("Missing required field: action");
+      }
+      if (!resource || typeof resource !== "string") {
+        return this._toolError("Missing required field: resource");
+      }
+      const doc = await this.store.get(covenantId);
+      if (!doc) {
+        return this._toolError(`Covenant not found: ${covenantId}`);
+      }
+      const result = await this.client.evaluateAction(doc, action, resource, context);
+      return this._toolSuccess({
+        permitted: result.permitted,
+        matchedRule: result.matchedRule,
+        reason: result.reason,
+        severity: result.severity
+      });
+    } catch (err) {
+      return this._toolError(`Failed to evaluate action: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  async _createIdentity(args) {
+    try {
+      const model = args.model;
+      const capabilities = args.capabilities;
+      const deployment = args.deployment;
+      const privateKeyHex = args.privateKeyHex;
+      const operatorIdentifier = args.operatorIdentifier;
+      if (!model || !model.provider || !model.modelId) {
+        return this._toolError("Missing required field: model (must have provider, modelId)");
+      }
+      if (!capabilities || !Array.isArray(capabilities)) {
+        return this._toolError("Missing required field: capabilities (must be an array)");
+      }
+      if (!deployment || !deployment.runtime) {
+        return this._toolError("Missing required field: deployment (must have runtime)");
+      }
+      let keyPair;
+      if (privateKeyHex) {
+        const { keyPairFromPrivateKeyHex } = await import("@usekova/crypto");
+        keyPair = await keyPairFromPrivateKeyHex(privateKeyHex);
+      } else {
+        keyPair = await (0, import_crypto2.generateKeyPair)();
+      }
+      const identity = await this.client.createIdentity({
+        operatorKeyPair: keyPair,
+        operatorIdentifier,
+        model: {
+          provider: model.provider,
+          modelId: model.modelId,
+          modelVersion: model.modelVersion
+        },
+        capabilities,
+        deployment: {
+          runtime: deployment.runtime,
+          region: deployment.region,
+          provider: deployment.provider
+        }
+      });
+      return this._toolSuccess({
+        id: identity.id,
+        operatorPublicKey: identity.operatorPublicKey,
+        operatorIdentifier: identity.operatorIdentifier,
+        model: identity.model,
+        capabilities: identity.capabilities,
+        version: identity.version,
+        createdAt: identity.createdAt
+      });
+    } catch (err) {
+      return this._toolError(`Failed to create identity: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  async _parseCCL(args) {
+    try {
+      const source = args.source;
+      if (!source || typeof source !== "string") {
+        return this._toolError("Missing required field: source");
+      }
+      const doc = this.client.parseCCL(source);
+      return this._toolSuccess({
+        statements: doc.statements.length,
+        permits: doc.permits.length,
+        denies: doc.denies.length,
+        obligations: doc.obligations.length,
+        limits: doc.limits.length,
+        details: doc.statements.map((s) => {
+          if (s.type === "limit") {
+            return {
+              type: s.type,
+              action: s.action,
+              count: s.count,
+              periodSeconds: s.periodSeconds,
+              severity: s.severity
+            };
+          }
+          return {
+            type: s.type,
+            action: s.action,
+            resource: "resource" in s ? s.resource : void 0,
+            severity: s.severity
+          };
+        })
+      });
+    } catch (err) {
+      return this._toolError(`CCL parse error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  async _listCovenants(args) {
+    try {
+      const issuerId = args.issuerId;
+      const beneficiaryId = args.beneficiaryId;
+      const filter = {};
+      if (issuerId) filter.issuerId = issuerId;
+      if (beneficiaryId) filter.beneficiaryId = beneficiaryId;
+      const docs = await this.store.list(
+        Object.keys(filter).length > 0 ? filter : void 0
+      );
+      return this._toolSuccess({
+        count: docs.length,
+        covenants: docs.map((doc) => ({
+          id: doc.id,
+          issuer: { id: doc.issuer.id, name: doc.issuer.name },
+          beneficiary: { id: doc.beneficiary.id, name: doc.beneficiary.name },
+          constraints: doc.constraints,
+          createdAt: doc.createdAt
+        }))
+      });
+    } catch (err) {
+      return this._toolError(`Failed to list covenants: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  // ── Response helpers ──────────────────────────────────────────────────────
+  _successResponse(id, result) {
+    return {
+      jsonrpc: "2.0",
+      result,
+      id
+    };
+  }
+  _errorResponse(id, code, message, data) {
+    return {
+      jsonrpc: "2.0",
+      error: { code, message, data },
+      id
+    };
+  }
+  _toolSuccess(data) {
+    return {
+      content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+    };
+  }
+  _toolError(message) {
+    return {
+      content: [{ type: "text", text: message }],
+      isError: true
+    };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  JSON_RPC_ERRORS,
+  SteleServer,
+  createAuthMiddleware
+});