multicorn-shield 0.2.1 → 0.4.0

package/dist/proxy.d.cts

@@ -0,0 +1,235 @@
+import { Writable } from 'node:stream';
+
+/**
+ * JSON-RPC message parsing and tool call interception for the MCP proxy.
+ *
+ * Handles the MCP stdio transport (newline-delimited JSON-RPC 2.0). Provides
+ * types, parsers, and response builders used by the proxy to intercept
+ * `tools/call` requests before they reach the wrapped MCP server.
+ *
+ * @module proxy/interceptor
+ */
+interface JsonRpcRequest {
+    readonly jsonrpc: "2.0";
+    readonly id: string | number | null;
+    readonly method: string;
+    readonly params?: unknown;
+}
+interface JsonRpcResponse {
+    readonly jsonrpc: "2.0";
+    readonly id: string | number | null;
+    readonly result?: unknown;
+    readonly error?: JsonRpcError;
+}
+interface JsonRpcError {
+    readonly code: number;
+    readonly message: string;
+}
+interface ToolCallParams {
+    readonly name: string;
+    readonly arguments: Record<string, unknown>;
+}
+declare function parseJsonRpcLine(line: string): JsonRpcRequest | null;
+declare function extractToolCallParams(request: JsonRpcRequest): ToolCallParams | null;
+declare function buildBlockedResponse(id: string | number | null, service: string, permissionLevel: string, dashboardUrl: string): JsonRpcResponse;
+declare function buildSpendingBlockedResponse(id: string | number | null, reason: string, dashboardUrl: string): JsonRpcResponse;
+/**
+ * Internal error: Shield could not verify permissions due to an exception.
+ * Use when the proxy hits an unhandled error (fail-closed).
+ */
+declare function buildInternalErrorResponse(id: string | number | null): JsonRpcResponse;
+/**
+ * Service unreachable: Shield could not verify permissions (DNS, network, timeout).
+ * Distinct code (-32003) so callers can tell apart from permission-denied (-32000).
+ */
+declare function buildServiceUnreachableResponse(id: string | number | null, dashboardUrl: string): JsonRpcResponse;
+/**
+ * API key invalid or revoked (401/403 from service).
+ * Distinct code (-32004) so callers can tell apart from permission-denied (-32000).
+ */
+declare function buildAuthErrorResponse(id: string | number | null): JsonRpcResponse;
+declare function extractServiceFromToolName(toolName: string): string;
+declare function extractActionFromToolName(toolName: string): string;
+
+/**
+ * Permission levels that can be granted on a service scope.
+ *
+ * - `read`: observe data without modification
+ * - `write`: create or modify data
+ * - `execute`: trigger side-effects (e.g. send an email, make a payment)
+ * - `publish`: make existing content publicly accessible (e.g. deploy, publish, make live)
+ * - `create`: create new content that is immediately public (e.g. tweet, public commit, forum post)
+ */
+declare const PERMISSION_LEVELS: {
+    readonly Read: "read";
+    readonly Write: "write";
+    readonly Execute: "execute";
+    readonly Publish: "publish";
+    readonly Create: "create";
+};
+type PermissionLevel = (typeof PERMISSION_LEVELS)[keyof typeof PERMISSION_LEVELS];
+/**
+ * A single permission scope binding a service to an access level.
+ *
+ * For example, `{ service: "gmail", permissionLevel: "write" }` grants
+ * write access to the Gmail integration.
+ */
+interface Scope {
+    readonly service: string;
+    readonly permissionLevel: PermissionLevel;
+}
+
+/**
+ * Structured JSON logger for the MCP proxy.
+ *
+ * Writes to stderr only. Stdout is reserved for the MCP JSON-RPC transport.
+ * Log output is newline-delimited JSON so it can be parsed by log aggregators.
+ *
+ * @module proxy/logger
+ */
+
+declare const LOG_LEVELS: {
+    readonly debug: 0;
+    readonly info: 1;
+    readonly warn: 2;
+    readonly error: 3;
+};
+type LogLevel = keyof typeof LOG_LEVELS;
+interface ProxyLogger {
+    debug(msg: string, data?: Record<string, unknown>): void;
+    info(msg: string, data?: Record<string, unknown>): void;
+    warn(msg: string, data?: Record<string, unknown>): void;
+    error(msg: string, data?: Record<string, unknown>): void;
+}
+declare function createLogger(level: LogLevel, output?: Writable): ProxyLogger;
+declare function isValidLogLevel(value: unknown): value is LogLevel;
+
+/**
+ * Agent registration, scope fetching, consent flow, and scope caching.
+ *
+ * Handles the full lifecycle of connecting a proxy to the Multicorn service:
+ * finding or creating an agent record, fetching its granted scopes, and
+ * triggering the browser consent flow when the agent has no scopes yet.
+ *
+ * Scopes are cached in `~/.multicorn/scopes.json` for offline resilience
+ * and refreshed from the service every 60 seconds while the proxy runs.
+ * Cache is account-aware (keyed by agent name + API key).
+ *
+ * @module proxy/consent
+ */
+
+/**
+ * Derives the dashboard URL from the API base URL.
+ * - http://localhost:8080 -> http://localhost:5173
+ * - https://api.multicorn.ai -> https://app.multicorn.ai
+ * - Other URLs: replace "api" with "app" in the hostname, or use default
+ */
+declare function deriveDashboardUrl(baseUrl: string): string;
+/**
+ * Thrown when the Shield API returns 401 or 403 (API key invalid or revoked).
+ * Used so resolveAgentRecord can detect auth failure without ad-hoc property casts.
+ */
+declare class ShieldAuthError extends Error {
+    constructor(message: string);
+}
+interface AgentRecord {
+    readonly id: string;
+    readonly name: string;
+    readonly scopes: readonly Scope[];
+    /** Set when the service returned 401/403; proxy must block with auth error message. */
+    readonly authInvalid?: boolean;
+}
+
+declare function findAgentByName(agentName: string, apiKey: string, baseUrl: string): Promise<AgentRecord | null>;
+declare function registerAgent(agentName: string, apiKey: string, baseUrl: string, platform?: string): Promise<string>;
+declare function fetchGrantedScopes(agentId: string, apiKey: string, baseUrl: string): Promise<readonly Scope[]>;
+
+/**
+ * Scope validation engine.
+ *
+ * Given a set of granted scopes and a requested action, determines whether
+ * the action is permitted. Returns a structured result with a human-readable
+ * reason when access is denied. No silent failures, no implicit grants.
+ *
+ * **Design principle (Jordan persona):** Every permission must be explicitly
+ * granted. `read` does **not** imply `write`; `write` does **not** imply
+ * `execute`. There is no wildcard or superuser bypass.
+ *
+ * @module scopes/scope-validator
+ */
+
+/**
+ * The outcome of a scope validation check.
+ *
+ * - When `allowed` is `true`, no `reason` is present.
+ * - When `allowed` is `false`, `reason` contains a descriptive explanation
+ *   of why the action was denied.
+ *
+ * @example
+ * ```ts
+ * const result = validateScopeAccess(granted, requested);
+ * if (!result.allowed) {
+ *   console.warn(`Denied: ${result.reason}`);
+ * }
+ * ```
+ */
+interface ValidationResult {
+    /** Whether the requested action is permitted by the granted scopes. */
+    readonly allowed: boolean;
+    /**
+     * Human-readable explanation of why the action was denied.
+     * Only present when `allowed` is `false`.
+     */
+    readonly reason?: string;
+}
+/**
+ * Check whether a single requested scope is covered by the granted set.
+ *
+ * Matching is **exact**: the granted set must contain an entry with the
+ * same `service` **and** `permissionLevel`. No implicit escalation is
+ * performed (e.g. `write` does not subsume `read`).
+ *
+ * @param grantedScopes - The scopes the agent has been granted via consent.
+ * @param requested - The scope required by the action the agent wants to perform.
+ * @returns A {@link ValidationResult} indicating whether access is allowed.
+ *
+ * @example
+ * ```ts
+ * const granted = [
+ *   { service: "gmail", permissionLevel: "read" },
+ *   { service: "gmail", permissionLevel: "write" },
+ * ];
+ *
+ * validateScopeAccess(granted, { service: "gmail", permissionLevel: "read" });
+ * // → { allowed: true }
+ *
+ * validateScopeAccess(granted, { service: "gmail", permissionLevel: "execute" });
+ * // → { allowed: false, reason: "Permission \"execute\" is not granted …" }
+ *
+ * validateScopeAccess(granted, { service: "slack", permissionLevel: "read" });
+ * // → { allowed: false, reason: "No permissions granted for service \"slack\" …" }
+ * ```
+ */
+declare function validateScopeAccess(grantedScopes: readonly Scope[], requested: Scope): ValidationResult;
+
+/**
+ * Maps MCP tool names (stdio servers, Claude Desktop) to Shield service and permission level.
+ *
+ * Uses explicit tables for common MCP servers (filesystem, terminal, browser) and the same
+ * integration-style prefix rules as OpenClaw's tool-mapper for names like `gmail_send_email`.
+ *
+ * @module mcp-tool-mapper
+ */
+
+interface McpToolScopeMapping {
+    readonly service: string;
+    readonly permissionLevel: PermissionLevel;
+    /** Original tool name for audit logs. */
+    readonly actionType: string;
+}
+/**
+ * Maps an MCP `tools/call` tool name to Shield `service` + `permissionLevel` for scope checks.
+ */
+declare function mapMcpToolToScope(toolName: string): McpToolScopeMapping;
+
+export { type AgentRecord, type JsonRpcError, type JsonRpcRequest, type JsonRpcResponse, type LogLevel, type ProxyLogger, ShieldAuthError, type ToolCallParams, buildAuthErrorResponse, buildBlockedResponse, buildInternalErrorResponse, buildServiceUnreachableResponse, buildSpendingBlockedResponse, createLogger, deriveDashboardUrl, extractActionFromToolName, extractServiceFromToolName, extractToolCallParams, fetchGrantedScopes, findAgentByName, isValidLogLevel, mapMcpToolToScope, parseJsonRpcLine, registerAgent, validateScopeAccess };

package/dist/proxy.d.ts

@@ -0,0 +1,235 @@
+import { Writable } from 'node:stream';
+
+/**
+ * JSON-RPC message parsing and tool call interception for the MCP proxy.
+ *
+ * Handles the MCP stdio transport (newline-delimited JSON-RPC 2.0). Provides
+ * types, parsers, and response builders used by the proxy to intercept
+ * `tools/call` requests before they reach the wrapped MCP server.
+ *
+ * @module proxy/interceptor
+ */
+interface JsonRpcRequest {
+    readonly jsonrpc: "2.0";
+    readonly id: string | number | null;
+    readonly method: string;
+    readonly params?: unknown;
+}
+interface JsonRpcResponse {
+    readonly jsonrpc: "2.0";
+    readonly id: string | number | null;
+    readonly result?: unknown;
+    readonly error?: JsonRpcError;
+}
+interface JsonRpcError {
+    readonly code: number;
+    readonly message: string;
+}
+interface ToolCallParams {
+    readonly name: string;
+    readonly arguments: Record<string, unknown>;
+}
+declare function parseJsonRpcLine(line: string): JsonRpcRequest | null;
+declare function extractToolCallParams(request: JsonRpcRequest): ToolCallParams | null;
+declare function buildBlockedResponse(id: string | number | null, service: string, permissionLevel: string, dashboardUrl: string): JsonRpcResponse;
+declare function buildSpendingBlockedResponse(id: string | number | null, reason: string, dashboardUrl: string): JsonRpcResponse;
+/**
+ * Internal error: Shield could not verify permissions due to an exception.
+ * Use when the proxy hits an unhandled error (fail-closed).
+ */
+declare function buildInternalErrorResponse(id: string | number | null): JsonRpcResponse;
+/**
+ * Service unreachable: Shield could not verify permissions (DNS, network, timeout).
+ * Distinct code (-32003) so callers can tell apart from permission-denied (-32000).
+ */
+declare function buildServiceUnreachableResponse(id: string | number | null, dashboardUrl: string): JsonRpcResponse;
+/**
+ * API key invalid or revoked (401/403 from service).
+ * Distinct code (-32004) so callers can tell apart from permission-denied (-32000).
+ */
+declare function buildAuthErrorResponse(id: string | number | null): JsonRpcResponse;
+declare function extractServiceFromToolName(toolName: string): string;
+declare function extractActionFromToolName(toolName: string): string;
+
+/**
+ * Permission levels that can be granted on a service scope.
+ *
+ * - `read`: observe data without modification
+ * - `write`: create or modify data
+ * - `execute`: trigger side-effects (e.g. send an email, make a payment)
+ * - `publish`: make existing content publicly accessible (e.g. deploy, publish, make live)
+ * - `create`: create new content that is immediately public (e.g. tweet, public commit, forum post)
+ */
+declare const PERMISSION_LEVELS: {
+    readonly Read: "read";
+    readonly Write: "write";
+    readonly Execute: "execute";
+    readonly Publish: "publish";
+    readonly Create: "create";
+};
+type PermissionLevel = (typeof PERMISSION_LEVELS)[keyof typeof PERMISSION_LEVELS];
+/**
+ * A single permission scope binding a service to an access level.
+ *
+ * For example, `{ service: "gmail", permissionLevel: "write" }` grants
+ * write access to the Gmail integration.
+ */
+interface Scope {
+    readonly service: string;
+    readonly permissionLevel: PermissionLevel;
+}
+
+/**
+ * Structured JSON logger for the MCP proxy.
+ *
+ * Writes to stderr only. Stdout is reserved for the MCP JSON-RPC transport.
+ * Log output is newline-delimited JSON so it can be parsed by log aggregators.
+ *
+ * @module proxy/logger
+ */
+
+declare const LOG_LEVELS: {
+    readonly debug: 0;
+    readonly info: 1;
+    readonly warn: 2;
+    readonly error: 3;
+};
+type LogLevel = keyof typeof LOG_LEVELS;
+interface ProxyLogger {
+    debug(msg: string, data?: Record<string, unknown>): void;
+    info(msg: string, data?: Record<string, unknown>): void;
+    warn(msg: string, data?: Record<string, unknown>): void;
+    error(msg: string, data?: Record<string, unknown>): void;
+}
+declare function createLogger(level: LogLevel, output?: Writable): ProxyLogger;
+declare function isValidLogLevel(value: unknown): value is LogLevel;
+
+/**
+ * Agent registration, scope fetching, consent flow, and scope caching.
+ *
+ * Handles the full lifecycle of connecting a proxy to the Multicorn service:
+ * finding or creating an agent record, fetching its granted scopes, and
+ * triggering the browser consent flow when the agent has no scopes yet.
+ *
+ * Scopes are cached in `~/.multicorn/scopes.json` for offline resilience
+ * and refreshed from the service every 60 seconds while the proxy runs.
+ * Cache is account-aware (keyed by agent name + API key).
+ *
+ * @module proxy/consent
+ */
+
+/**
+ * Derives the dashboard URL from the API base URL.
+ * - http://localhost:8080 -> http://localhost:5173
+ * - https://api.multicorn.ai -> https://app.multicorn.ai
+ * - Other URLs: replace "api" with "app" in the hostname, or use default
+ */
+declare function deriveDashboardUrl(baseUrl: string): string;
+/**
+ * Thrown when the Shield API returns 401 or 403 (API key invalid or revoked).
+ * Used so resolveAgentRecord can detect auth failure without ad-hoc property casts.
+ */
+declare class ShieldAuthError extends Error {
+    constructor(message: string);
+}
+interface AgentRecord {
+    readonly id: string;
+    readonly name: string;
+    readonly scopes: readonly Scope[];
+    /** Set when the service returned 401/403; proxy must block with auth error message. */
+    readonly authInvalid?: boolean;
+}
+
+declare function findAgentByName(agentName: string, apiKey: string, baseUrl: string): Promise<AgentRecord | null>;
+declare function registerAgent(agentName: string, apiKey: string, baseUrl: string, platform?: string): Promise<string>;
+declare function fetchGrantedScopes(agentId: string, apiKey: string, baseUrl: string): Promise<readonly Scope[]>;
+
+/**
+ * Scope validation engine.
+ *
+ * Given a set of granted scopes and a requested action, determines whether
+ * the action is permitted. Returns a structured result with a human-readable
+ * reason when access is denied. No silent failures, no implicit grants.
+ *
+ * **Design principle (Jordan persona):** Every permission must be explicitly
+ * granted. `read` does **not** imply `write`; `write` does **not** imply
+ * `execute`. There is no wildcard or superuser bypass.
+ *
+ * @module scopes/scope-validator
+ */
+
+/**
+ * The outcome of a scope validation check.
+ *
+ * - When `allowed` is `true`, no `reason` is present.
+ * - When `allowed` is `false`, `reason` contains a descriptive explanation
+ *   of why the action was denied.
+ *
+ * @example
+ * ```ts
+ * const result = validateScopeAccess(granted, requested);
+ * if (!result.allowed) {
+ *   console.warn(`Denied: ${result.reason}`);
+ * }
+ * ```
+ */
+interface ValidationResult {
+    /** Whether the requested action is permitted by the granted scopes. */
+    readonly allowed: boolean;
+    /**
+     * Human-readable explanation of why the action was denied.
+     * Only present when `allowed` is `false`.
+     */
+    readonly reason?: string;
+}
+/**
+ * Check whether a single requested scope is covered by the granted set.
+ *
+ * Matching is **exact**: the granted set must contain an entry with the
+ * same `service` **and** `permissionLevel`. No implicit escalation is
+ * performed (e.g. `write` does not subsume `read`).
+ *
+ * @param grantedScopes - The scopes the agent has been granted via consent.
+ * @param requested - The scope required by the action the agent wants to perform.
+ * @returns A {@link ValidationResult} indicating whether access is allowed.
+ *
+ * @example
+ * ```ts
+ * const granted = [
+ *   { service: "gmail", permissionLevel: "read" },
+ *   { service: "gmail", permissionLevel: "write" },
+ * ];
+ *
+ * validateScopeAccess(granted, { service: "gmail", permissionLevel: "read" });
+ * // → { allowed: true }
+ *
+ * validateScopeAccess(granted, { service: "gmail", permissionLevel: "execute" });
+ * // → { allowed: false, reason: "Permission \"execute\" is not granted …" }
+ *
+ * validateScopeAccess(granted, { service: "slack", permissionLevel: "read" });
+ * // → { allowed: false, reason: "No permissions granted for service \"slack\" …" }
+ * ```
+ */
+declare function validateScopeAccess(grantedScopes: readonly Scope[], requested: Scope): ValidationResult;
+
+/**
+ * Maps MCP tool names (stdio servers, Claude Desktop) to Shield service and permission level.
+ *
+ * Uses explicit tables for common MCP servers (filesystem, terminal, browser) and the same
+ * integration-style prefix rules as OpenClaw's tool-mapper for names like `gmail_send_email`.
+ *
+ * @module mcp-tool-mapper
+ */
+
+interface McpToolScopeMapping {
+    readonly service: string;
+    readonly permissionLevel: PermissionLevel;
+    /** Original tool name for audit logs. */
+    readonly actionType: string;
+}
+/**
+ * Maps an MCP `tools/call` tool name to Shield `service` + `permissionLevel` for scope checks.
+ */
+declare function mapMcpToolToScope(toolName: string): McpToolScopeMapping;
+
+export { type AgentRecord, type JsonRpcError, type JsonRpcRequest, type JsonRpcResponse, type LogLevel, type ProxyLogger, ShieldAuthError, type ToolCallParams, buildAuthErrorResponse, buildBlockedResponse, buildInternalErrorResponse, buildServiceUnreachableResponse, buildSpendingBlockedResponse, createLogger, deriveDashboardUrl, extractActionFromToolName, extractServiceFromToolName, extractToolCallParams, fetchGrantedScopes, findAgentByName, isValidLogLevel, mapMcpToolToScope, parseJsonRpcLine, registerAgent, validateScopeAccess };