multicorn-shield 0.11.0 → 0.13.0

package/dist/openclaw-hook/handler.js

@@ -377,7 +377,6 @@ ${url}
 }
 async function waitForConsent(agentId, agentName, apiKey, baseUrl, scope, logger) {
   const dashboardUrl = deriveDashboardUrl(baseUrl);
-  console.error("[SHIELD] buildConsentUrl baseUrl:", baseUrl);
   const consentUrl = buildConsentUrl(agentName, dashboardUrl, scope);
   process.stderr.write(
     `[multicorn-shield] Opening consent page...

package/dist/openclaw-plugin/multicorn-shield.js

@@ -315,14 +315,6 @@ async function fetchGrantedScopes(agentId, apiKey, baseUrl, logger) {
 }
 async function checkActionPermission(payload, apiKey, baseUrl, logger) {
   try {
-    const requestBody = {
-      agent: payload.agent,
-      service: payload.service,
-      actionType: payload.actionType,
-      status: payload.status,
-      metadata: payload.metadata
-    };
-    console.error("[SHIELD-CLIENT] POST /api/v1/actions request: " + JSON.stringify(requestBody));
     const response = await fetch(`${baseUrl}/api/v1/actions`, {
       method: "POST",
       headers: {
@@ -333,22 +325,18 @@ async function checkActionPermission(payload, apiKey, baseUrl, logger) {
       signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
     });
     if (response.status === 201) {
-      console.error(
-        "[SHIELD-CLIENT] response status=201, returning approved (body not read - backend may have failed approval creation)"
-      );
+      console.error("[SHIELD-CLIENT] POST /api/v1/actions: 201 approved");
       return { status: "approved" };
     }
     if (response.status === 202) {
       const body = await response.json();
       const data = isApiSuccess(body) ? body.data : null;
-      console.error("[SHIELD-CLIENT] response status=202 body=" + JSON.stringify(data ?? body));
+      console.error("[SHIELD-CLIENT] POST /api/v1/actions: 202 pending");
       if (!isApiSuccess(body) || data === null) {
         return { status: "blocked" };
       }
       const approvalId = typeof data["approval_id"] === "string" ? data["approval_id"] : void 0;
-      console.error(
-        "[SHIELD-CLIENT] extracted: status=" + String(data["status"]) + " approval_id=" + (approvalId ?? "undefined")
-      );
+      console.error("[SHIELD-CLIENT] extracted: approval_id=" + (approvalId ?? "undefined"));
       if (approvalId === void 0) {
         return { status: "blocked" };
       }
@@ -439,7 +427,6 @@ ${url}
 }
 async function waitForConsent(agentId, agentName, apiKey, baseUrl, scope, logger) {
   const dashboardUrl = deriveDashboardUrl(baseUrl);
-  console.error("[SHIELD] buildConsentUrl baseUrl:", baseUrl);
   const consentUrl = buildConsentUrl(agentName, dashboardUrl, scope);
   process.stderr.write(
     `[multicorn-shield] Opening consent page...
@@ -509,7 +496,14 @@ function readConfig() {
   const resolvedBaseUrl = asString(cachedMulticornConfig?.baseUrl) ?? asString(process.env["MULTICORN_BASE_URL"]) ?? "https://api.multicorn.ai";
   const agentName = asString(pc["agentName"]) ?? process.env["MULTICORN_AGENT_NAME"] ?? agentNameFromOpenclawPlatform(cachedMulticornConfig) ?? asString(cachedMulticornConfig?.agentName) ?? null;
   const failMode = "closed";
-  return { apiKey: resolvedApiKey, baseUrl: resolvedBaseUrl, agentName, failMode };
+  let apiKey = resolvedApiKey;
+  if (apiKey.length > 0 && (!apiKey.startsWith("mcs_") || apiKey.length < 16)) {
+    pluginLogger?.error(
+      "Invalid API key format. Key must start with mcs_ and be at least 16 characters."
+    );
+    apiKey = "";
+  }
+  return { apiKey, baseUrl: resolvedBaseUrl, agentName, failMode };
 }
 function asString(value) {
   return typeof value === "string" && value.length > 0 ? value : void 0;

package/dist/openclaw-plugin/openclaw.plugin.json

@@ -8,7 +8,9 @@
     "additionalProperties": false,
     "properties": {
       "apiKey": {
-        "type": "string"
+        "type": "string",
+        "pattern": "^mcs_.{12,}$",
+        "minLength": 16
       },
       "baseUrl": {
         "type": "string"

package/dist/proxy.cjs

@@ -437,12 +437,186 @@ function mapMcpToolToScope(toolName) {
   return { service: head, permissionLevel, actionType };
 }
 
+// src/logger/action-logger.ts
+function createActionLogger(config) {
+  if (!config.apiKey || config.apiKey.trim().length === 0) {
+    throw new Error(
+      "[ActionLogger] API key is required. Provide it via the 'apiKey' config option."
+    );
+  }
+  const baseUrl = config.baseUrl ?? "https://api.multicorn.ai";
+  const timeout = config.timeout ?? 5e3;
+  if (!baseUrl.startsWith("https://") && !baseUrl.startsWith("http://localhost")) {
+    throw new Error(
+      `[ActionLogger] Base URL must use HTTPS for security. Received: "${baseUrl}". Use https:// or http://localhost for local development.`
+    );
+  }
+  const endpoint = `${baseUrl}/api/v1/actions`;
+  const batchEnabled = config.batchMode?.enabled ?? false;
+  const maxBatchSize = config.batchMode?.maxSize ?? 10;
+  const flushInterval = config.batchMode?.flushIntervalMs ?? 5e3;
+  const queue = [];
+  let flushTimer;
+  let isShutdown = false;
+  async function sendActions(actions) {
+    if (actions.length === 0) return;
+    const convertAction = (action) => ({
+      agent: action.agent,
+      service: action.service,
+      actionType: action.actionType,
+      status: action.status,
+      ...action.cost !== void 0 ? { cost: action.cost } : {},
+      ...action.metadata !== void 0 ? { metadata: action.metadata } : {}
+    });
+    const convertedActions = actions.map(convertAction);
+    const payload = batchEnabled ? { actions: convertedActions } : convertedActions[0];
+    let lastError;
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => {
+          controller.abort();
+        }, timeout);
+        const response = await fetch(endpoint, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "X-Multicorn-Key": config.apiKey
+          },
+          body: JSON.stringify(payload),
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        if (response.ok) {
+          return;
+        }
+        if (response.status >= 400 && response.status < 500) {
+          const body = await response.text().catch(() => "");
+          throw new Error(
+            `[ActionLogger] Client error (${String(response.status)}): ${response.statusText}. Response: ${body}. Check your API key and payload format.`
+          );
+        }
+        if (response.status >= 500 && attempt === 0) {
+          lastError = new Error(
+            `[ActionLogger] Server error (${String(response.status)}): ${response.statusText}. Retrying once...`
+          );
+          await sleep(100 * Math.pow(2, attempt));
+          continue;
+        }
+        throw new Error(
+          `[ActionLogger] Server error (${String(response.status)}) after retry: ${response.statusText}. Multicorn API may be experiencing issues.`
+        );
+      } catch (error) {
+        if (error instanceof Error) {
+          if (error.name === "AbortError") {
+            lastError = new Error(
+              `[ActionLogger] Request timeout after ${String(timeout)}ms. Increase the 'timeout' config option or check your network connection.`
+            );
+          } else if (error.message.includes("Client error") || error.message.includes("Server error")) {
+            lastError = error;
+          } else {
+            lastError = new Error(
+              `[ActionLogger] Network error: ${error.message}. Check your network connection and API endpoint.`
+            );
+          }
+        } else {
+          lastError = new Error(`[ActionLogger] Unknown error: ${String(error)}`);
+        }
+        if (attempt === 0 && !lastError.message.includes("Client error")) {
+          await sleep(100 * Math.pow(2, attempt));
+          continue;
+        }
+        break;
+      }
+    }
+    if (lastError) {
+      if (config.onError) {
+        config.onError(lastError);
+      }
+    }
+  }
+  async function flushQueue() {
+    if (queue.length === 0) return;
+    const actions = queue.map((item) => item.payload);
+    queue.length = 0;
+    await sendActions(actions);
+  }
+  function startFlushTimer() {
+    if (flushTimer !== void 0) return;
+    flushTimer = setInterval(() => {
+      flushQueue().catch(() => {
+      });
+    }, flushInterval);
+    const timer = flushTimer;
+    if (typeof timer.unref === "function") {
+      timer.unref();
+    }
+  }
+  function stopFlushTimer() {
+    if (flushTimer) {
+      clearInterval(flushTimer);
+      flushTimer = void 0;
+    }
+  }
+  if (batchEnabled) {
+    startFlushTimer();
+  }
+  return {
+    logAction(action) {
+      if (isShutdown) {
+        throw new Error(
+          "[ActionLogger] Cannot log action after shutdown. Create a new logger instance."
+        );
+      }
+      if (action.agent.trim().length === 0) {
+        throw new Error("[ActionLogger] Action must have a non-empty 'agent' field.");
+      }
+      if (action.service.trim().length === 0) {
+        throw new Error("[ActionLogger] Action must have a non-empty 'service' field.");
+      }
+      if (action.actionType.trim().length === 0) {
+        throw new Error("[ActionLogger] Action must have a non-empty 'actionType' field.");
+      }
+      if (action.status.trim().length === 0) {
+        throw new Error("[ActionLogger] Action must have a non-empty 'status' field.");
+      }
+      if (batchEnabled) {
+        queue.push({ payload: action, timestamp: Date.now() });
+        if (queue.length >= maxBatchSize) {
+          flushQueue().catch(() => {
+          });
+        }
+      } else {
+        sendActions([action]).catch(() => {
+        });
+      }
+      return Promise.resolve();
+    },
+    async flush() {
+      if (!batchEnabled) return;
+      await flushQueue();
+    },
+    async shutdown() {
+      if (isShutdown) return;
+      isShutdown = true;
+      stopFlushTimer();
+      if (batchEnabled) {
+        await flushQueue();
+      }
+    }
+  };
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 exports.ShieldAuthError = ShieldAuthError;
 exports.buildAuthErrorResponse = buildAuthErrorResponse;
 exports.buildBlockedResponse = buildBlockedResponse;
 exports.buildInternalErrorResponse = buildInternalErrorResponse;
 exports.buildServiceUnreachableResponse = buildServiceUnreachableResponse;
 exports.buildSpendingBlockedResponse = buildSpendingBlockedResponse;
+exports.createActionLogger = createActionLogger;
 exports.createLogger = createLogger;
 exports.deriveDashboardUrl = deriveDashboardUrl;
 exports.extractActionFromToolName = extractActionFromToolName;

package/dist/proxy.d.cts

@@ -68,6 +68,23 @@ declare const PERMISSION_LEVELS: {
     readonly Create: "create";
 };
 type PermissionLevel = (typeof PERMISSION_LEVELS)[keyof typeof PERMISSION_LEVELS];
+/**
+ * Lifecycle states for an action processed by the policy engine.
+ *
+ * - `approved`: action passed policy checks and was executed
+ * - `blocked`: action was denied by policy
+ * - `pending`: action is awaiting human approval
+ * - `flagged`: action was executed but flagged for review
+ * - `requires_approval`: action requires content review before execution
+ */
+declare const ACTION_STATUSES: {
+    readonly Approved: "approved";
+    readonly Blocked: "blocked";
+    readonly Pending: "pending";
+    readonly Flagged: "flagged";
+    readonly RequiresApproval: "requires_approval";
+};
+type ActionStatus = (typeof ACTION_STATUSES)[keyof typeof ACTION_STATUSES];
 /**
  * A single permission scope binding a service to an access level.
  *
@@ -232,4 +249,214 @@ interface McpToolScopeMapping {
  */
 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 };
+/**
+ * Action logging client for Multicorn Shield.
+ *
+ * Sends structured action events to the Multicorn hosted API, providing the
+ * observability backbone for Shield. Every agent action is logged with
+ * metadata, cost information, and status tracking.
+ *
+ * **Design principles:**
+ * - **Fire-and-forget**: Logging failures MUST NOT block the agent's action.
+ * - **Security (Jordan persona)**: API keys never logged, HTTPS enforced.
+ * - **Clear errors (Yuki persona)**: Descriptive messages for all failure modes.
+ * - **Clean async (The Team persona)**: Proper promise handling, no hanging requests.
+ *
+ * @module logger/action-logger
+ */
+
+/**
+ * Configuration options for the action logger client.
+ *
+ * @example
+ * ```ts
+ * const config: ActionLoggerConfig = {
+ *   apiKey: process.env.MULTICORN_API_KEY,
+ *   baseUrl: "https://api.multicorn.ai",
+ *   timeout: 5000,
+ *   batchMode: {
+ *     enabled: true,
+ *     maxSize: 10,
+ *     flushIntervalMs: 5000,
+ *   },
+ * };
+ * ```
+ */
+interface ActionLoggerConfig {
+    /**
+     * Multicorn API key for authentication.
+     * Passed as `X-Multicorn-Key` header. Never logged.
+     */
+    readonly apiKey: string;
+    /**
+     * Base URL for the Multicorn API.
+     * @default "https://api.multicorn.ai"
+     */
+    readonly baseUrl?: string;
+    /**
+     * Request timeout in milliseconds.
+     * @default 5000
+     */
+    readonly timeout?: number;
+    /**
+     * Optional batch mode configuration.
+     * When enabled, actions are queued and flushed periodically.
+     */
+    readonly batchMode?: BatchModeConfig;
+    /**
+     * Optional error handler for logging failures.
+     * Called asynchronously. Does not block the main action flow.
+     */
+    readonly onError?: (error: Error) => void;
+}
+/**
+ * Batch mode configuration.
+ *
+ * Actions are flushed when **either** condition is met:
+ * - The queue reaches `maxSize` actions, OR
+ * - `flushIntervalMs` milliseconds have elapsed since the last flush.
+ */
+interface BatchModeConfig {
+    /** Whether batch mode is enabled. */
+    readonly enabled: boolean;
+    /**
+     * Maximum number of actions to queue before forcing a flush.
+     * @default 10
+     */
+    readonly maxSize?: number;
+    /**
+     * Maximum time (ms) between flushes.
+     * @default 5000
+     */
+    readonly flushIntervalMs?: number;
+}
+/**
+ * A single action event to be logged.
+ *
+ * @example
+ * ```ts
+ * const action: ActionPayload = {
+ *   agent: "inbox-assistant",
+ *   service: "gmail",
+ *   actionType: "send_email",
+ *   status: "approved",
+ *   cost: 0.002,
+ *   metadata: {
+ *     recipient: "user@example.com",
+ *     subject: "Weekly report",
+ *   },
+ * };
+ * ```
+ */
+interface ActionPayload {
+    /** Agent identifier (e.g. "inbox-assistant"). */
+    readonly agent: string;
+    /** Service being accessed (e.g. "gmail", "slack"). */
+    readonly service: string;
+    /** Type of action performed (e.g. "send_email", "read_message"). */
+    readonly actionType: string;
+    /** Lifecycle status of the action. */
+    readonly status: ActionStatus;
+    /**
+     * Optional cost in USD incurred by this action.
+     * Present only for actions with usage-based pricing.
+     */
+    readonly cost?: number;
+    /**
+     * Optional structured metadata for additional context.
+     * Keys and values must be serializable to JSON.
+     */
+    readonly metadata?: Readonly<Record<string, string | number | boolean>>;
+}
+/**
+ * HTTP client for logging agent actions to the Multicorn Shield API.
+ *
+ * Supports both immediate and batched delivery modes. All network failures
+ * are handled gracefully to ensure logging never blocks the agent's execution.
+ *
+ * @example Basic usage (immediate mode)
+ * ```ts
+ * const logger = createActionLogger({
+ *   apiKey: process.env.MULTICORN_API_KEY!,
+ * });
+ *
+ * await logger.logAction({
+ *   agent: "email-assistant",
+ *   service: "gmail",
+ *   actionType: "send_email",
+ *   status: "approved",
+ *   cost: 0.002,
+ * });
+ * ```
+ *
+ * @example Batch mode with error handling
+ * ```ts
+ * const logger = createActionLogger({
+ *   apiKey: process.env.MULTICORN_API_KEY!,
+ *   batchMode: { enabled: true, maxSize: 10, flushIntervalMs: 5000 },
+ *   onError: (err) => console.error("[ActionLogger]", err.message),
+ * });
+ *
+ * // Actions are queued and flushed automatically
+ * logger.logAction({
+ *   agent: "inbox-assistant",
+ *   service: "gmail",
+ *   actionType: "read_message",
+ *   status: "approved",
+ * });
+ *
+ * // Force immediate flush
+ * await logger.flush();
+ *
+ * // Clean up resources
+ * logger.shutdown();
+ * ```
+ */
+interface ActionLogger {
+    /**
+     * Log a single action event.
+     *
+     * In immediate mode, sends the action to the API right away (non-blocking).
+     * In batch mode, queues the action and flushes when thresholds are met.
+     *
+     * @param action - The action event to log.
+     * @returns A promise that resolves when the action is sent (immediate mode)
+     *          or queued (batch mode). Rejects only on validation errors, not
+     *          network failures (those are passed to `onError`).
+     */
+    logAction(action: ActionPayload): Promise<void>;
+    /**
+     * Flush all queued actions immediately (batch mode only).
+     *
+     * In immediate mode, this is a no-op.
+     *
+     * @returns A promise that resolves when all queued actions have been sent.
+     */
+    flush(): Promise<void>;
+    /**
+     * Shut down the logger and clean up resources.
+     *
+     * Stops the flush timer (if in batch mode) and flushes any remaining actions.
+     * After calling `shutdown()`, the logger should not be used.
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * Create a new action logger client.
+ *
+ * @param config - Configuration options.
+ * @returns An {@link ActionLogger} instance.
+ * @throws {Error} If the API key is missing or the base URL is not HTTPS.
+ *
+ * @example
+ * ```ts
+ * const logger = createActionLogger({
+ *   apiKey: process.env.MULTICORN_API_KEY!,
+ *   baseUrl: "https://api.multicorn.ai",
+ *   timeout: 3000,
+ * });
+ * ```
+ */
+declare function createActionLogger(config: ActionLoggerConfig): ActionLogger;
+
+export { type ActionLogger, type ActionLoggerConfig, type ActionPayload, type AgentRecord, type JsonRpcError, type JsonRpcRequest, type JsonRpcResponse, type LogLevel, type PermissionLevel, type ProxyLogger, type Scope, ShieldAuthError, type ToolCallParams, buildAuthErrorResponse, buildBlockedResponse, buildInternalErrorResponse, buildServiceUnreachableResponse, buildSpendingBlockedResponse, createActionLogger, createLogger, deriveDashboardUrl, extractActionFromToolName, extractServiceFromToolName, extractToolCallParams, fetchGrantedScopes, findAgentByName, isValidLogLevel, mapMcpToolToScope, parseJsonRpcLine, registerAgent, validateScopeAccess };