@opentrust/guards 7.3.3

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@opentrust/guards",
+  "version": "7.3.3",
+  "description": "AI agent security plugin for OpenClaw: prompt injection detection, PII sanitization, and monitoring",
+  "type": "module",
+  "main": "index.ts",
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.mjs",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "openclaw",
+    "opentrust",
+    "prompt-injection",
+    "security",
+    "ai-safety",
+    "guard",
+    "data-sanitization"
+  ],
+  "author": "OpenTrust",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/opentrust/opentrust#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/opentrust/opentrust.git",
+    "directory": "guards"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "index.ts",
+    "plugin/",
+    "agent/",
+    "memory/",
+    "platform-client/",
+    "dist/",
+    "scripts/",
+    "openclaw.plugin.json",
+    "tsconfig.json"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.19.13",
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.9"
+  }
+}

package/platform-client/index.ts

@@ -0,0 +1,241 @@
+/**
+ * DashboardClient — 与 OpenTrust Dashboard 通信的 SDK
+ *
+ * 功能：
+ * - Agent 注册和更新
+ * - 心跳保活
+ * - 内容检测请求
+ * - 工具调用观测上报
+ * - 权限查询
+ *
+ * 同时支持本地嵌入式和远程独立部署的 Dashboard
+ */
+
+import type {
+  DashboardClientConfig,
+  DashboardDetectRequest,
+  DashboardDetectResponse,
+  AgentRegisterRequest,
+  ToolCallObservationRequest,
+  AgentPermission,
+} from "./types.js";
+
+/**
+ * Dashboard 客户端类
+ *
+ * 使用方式：
+ * ```ts
+ * const client = new DashboardClient({
+ *   dashboardUrl: "http://localhost:53667",
+ *   sessionToken: "sk-og-xxx",
+ * });
+ * await client.registerAgent({ name: "My Agent" });
+ * client.startHeartbeat(60_000);
+ * ```
+ */
+export class DashboardClient {
+  private config: Required<DashboardClientConfig>;
+
+  /**
+   * 创建 Dashboard 客户端
+   * @param config - 客户端配置
+   */
+  constructor(config: DashboardClientConfig) {
+    this.config = {
+      dashboardUrl: config.dashboardUrl.replace(/\/$/, ""), // 移除尾部斜杠
+      sessionToken: config.sessionToken,
+      agentId: config.agentId ?? "",
+      timeoutMs: config.timeoutMs ?? 30000,
+    };
+  }
+
+  /**
+   * 获取当前 Agent ID
+   */
+  get agentId(): string {
+    return this.config.agentId;
+  }
+
+  /**
+   * 发送 HTTP 请求
+   * 自动添加认证头和超时控制
+   *
+   * @param path - API 路径
+   * @param options - 请求选项
+   * @returns 响应数据
+   */
+  private async request<T>(path: string, options: RequestInit = {}): Promise<T> {
+    // 超时控制
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.config.timeoutMs);
+
+    try {
+      const headers: Record<string, string> = {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.config.sessionToken}`,
+        ...((options.headers as Record<string, string>) || {}),
+      };
+
+      const res = await fetch(`${this.config.dashboardUrl}${path}`, {
+        ...options,
+        headers,
+        signal: controller.signal,
+      });
+
+      if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Dashboard API ${res.status}: ${text}`);
+      }
+
+      return (await res.json()) as T;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  // ── 检测 API ───────────────────────────────────────
+
+  /**
+   * 发送内容检测请求
+   * 检测消息内容是否包含安全风险
+   *
+   * @param req - 检测请求
+   * @returns 检测结果
+   */
+  async detect(req: DashboardDetectRequest): Promise<DashboardDetectResponse> {
+    return this.request<DashboardDetectResponse>("/api/detect", {
+      method: "POST",
+      body: JSON.stringify({
+        ...req,
+        agentId: req.agentId || this.config.agentId || undefined,
+      }),
+    });
+  }
+
+  // ── Agent 管理 API ────────────────────────────────
+
+  /**
+   * 注册 Agent
+   * 如果同名 Agent 已存在，则更新；否则创建新的
+   *
+   * @param req - 注册请求
+   * @returns 注册结果
+   */
+  async registerAgent(req: AgentRegisterRequest): Promise<{ success: boolean; data?: { id: string } }> {
+    // 检查是否已存在同名 Agent（实现 upsert 语义）
+    try {
+      const list = await this.request<{ success: boolean; data: { id: string; name: string }[] }>("/api/agents");
+      if (list.success && list.data) {
+        const existing = list.data.find((a) => a.name === req.name);
+        if (existing) {
+          // 更新已有 Agent
+          this.config.agentId = existing.id;
+          await this.request(`/api/agents/${existing.id}`, {
+            method: "PUT",
+            body: JSON.stringify({
+              status: "active",
+              ...(req.provider && { provider: req.provider }),
+              ...(req.metadata && { metadata: req.metadata }),
+            }),
+          }).catch(() => {}); // 更新失败不影响返回
+          return { success: true, data: { id: existing.id } };
+        }
+      }
+    } catch { /* 查询失败时继续创建 */ }
+
+    // 创建新 Agent
+    const result = await this.request<{ success: boolean; data?: { id: string } }>("/api/agents", {
+      method: "POST",
+      body: JSON.stringify(req),
+    });
+    if (result.success && result.data?.id) this.config.agentId = result.data.id;
+    return result;
+  }
+
+  /**
+   * 发送心跳
+   * 告知 Dashboard 该 Agent 仍然活跃
+   */
+  async heartbeat(): Promise<void> {
+    if (!this.config.agentId) return;
+    await this.request(`/api/agents/${this.config.agentId}/heartbeat`, { method: "POST" });
+  }
+
+  /**
+   * 更新 Agent Profile
+   * 同步 Agent 的元数据到 Dashboard
+   *
+   * @param profile - Profile 数据
+   */
+  async updateProfile(profile: Record<string, unknown>): Promise<void> {
+    if (!this.config.agentId) return;
+    await this.request(`/api/agents/${this.config.agentId}`, {
+      method: "PUT",
+      body: JSON.stringify({ metadata: profile }),
+    });
+  }
+
+  /**
+   * 启动心跳定时器
+   * 定期发送心跳保持 Agent 活跃状态
+   *
+   * @param intervalMs - 心跳间隔（毫秒），默认 60 秒
+   * @returns 定时器句柄
+   */
+  startHeartbeat(intervalMs = 60_000): NodeJS.Timeout {
+    return setInterval(() => { this.heartbeat().catch(() => {}); }, intervalMs);
+  }
+
+  // ── 工具调用观测 API ───────────────────────────────
+
+  /**
+   * 上报工具调用
+   * 记录 Agent 的工具使用情况，用于安全分析
+   *
+   * @param data - 工具调用数据
+   */
+  async reportToolCall(data: ToolCallObservationRequest): Promise<void> {
+    await this.request("/api/observations", { method: "POST", body: JSON.stringify(data) });
+  }
+
+  /**
+   * 获取 Agent 权限列表
+   * 查询 Agent 访问过的资源和权限模式
+   *
+   * @param agentId - Agent ID（可选，默认使用当前 Agent）
+   * @returns 权限列表
+   */
+  async getPermissions(agentId?: string): Promise<AgentPermission[]> {
+    const id = agentId || this.config.agentId;
+    if (!id) return [];
+    const result = await this.request<{ success: boolean; data: AgentPermission[] }>(
+      `/api/observations/agents/${id}/permissions`,
+    );
+    return result.data ?? [];
+  }
+
+  // ── 健康检查 API ───────────────────────────────────
+
+  /**
+   * 检查 Dashboard 健康状态
+   * @returns 是否健康
+   */
+  async checkHealth(): Promise<boolean> {
+    try {
+      const res = await fetch(`${this.config.dashboardUrl}/health`);
+      const json = (await res.json()) as { status: string };
+      return json.status === "ok";
+    } catch {
+      return false;
+    }
+  }
+}
+
+// 导出类型
+export {
+  type DashboardClientConfig,
+  type DashboardDetectRequest,
+  type DashboardDetectResponse,
+  type ToolCallObservationRequest,
+  type AgentPermission,
+} from "./types.js";

package/platform-client/types.ts

@@ -0,0 +1,132 @@
+/**
+ * Dashboard API 通信类型定义
+ */
+
+/**
+ * 检测请求
+ * 发送消息内容进行安全检测
+ */
+export type DashboardDetectRequest = {
+  /** 消息列表 */
+  messages: unknown[];
+  /** 消息格式 */
+  format?: "openai" | "anthropic" | "gemini" | "raw";
+  /** 角色类型 */
+  role?: "system" | "user" | "assistant" | "tool";
+  /** Agent ID */
+  agentId?: string;
+};
+
+/**
+ * 检测响应
+ * 返回消息内容的安全评估结果
+ */
+export type DashboardDetectResponse = {
+  /** 请求是否成功 */
+  success: boolean;
+  /** 检测数据 */
+  data?: {
+    /** 是否安全 */
+    safe: boolean;
+    /** 判定结果 */
+    verdict: "safe" | "unsafe";
+    /** 风险类别 */
+    categories: string[];
+    /** 敏感度评分 */
+    sensitivity_score: number;
+    /** 检测发现列表 */
+    findings: Array<{ scanner: string; name: string; description: string }>;
+    /** 检测耗时（毫秒） */
+    latency_ms: number;
+    /** 请求 ID */
+    request_id: string;
+    /** 策略动作 */
+    policy_action?: "block" | "alert" | "log";
+  };
+  /** 是否被阻断 */
+  blocked?: boolean;
+  /** 错误信息 */
+  error?: string;
+};
+
+/**
+ * Agent 注册请求
+ */
+export type AgentRegisterRequest = {
+  /** Agent 名称 */
+  name: string;
+  /** Agent 描述 */
+  description?: string;
+  /** AI 模型提供商 */
+  provider?: string;
+  /** 附加元数据 */
+  metadata?: Record<string, unknown>;
+};
+
+/**
+ * Dashboard 客户端配置
+ */
+export type DashboardClientConfig = {
+  /** Dashboard API 地址 */
+  dashboardUrl: string;
+  /** 认证 Token（通常是 Core 平台的 API Key） */
+  sessionToken: string;
+  /** Agent ID（可选，注册后自动设置） */
+  agentId?: string;
+  /** 请求超时时间（毫秒） */
+  timeoutMs?: number;
+};
+
+/**
+ * 工具调用观测请求
+ * 用于上报 Agent 的工具使用情况
+ */
+export type ToolCallObservationRequest = {
+  /** Agent ID */
+  agentId: string;
+  /** 会话 Key */
+  sessionKey?: string;
+  /** 工具名称 */
+  toolName: string;
+  /** 调用参数 */
+  params?: Record<string, unknown>;
+  /** 调用阶段 */
+  phase: "before" | "after";
+  /** 执行结果 */
+  result?: unknown;
+  /** 错误信息 */
+  error?: string;
+  /** 执行耗时（毫秒） */
+  durationMs?: number;
+  /** 是否被阻断 */
+  blocked?: boolean;
+  /** 阻断原因 */
+  blockReason?: string;
+};
+
+/**
+ * Agent 权限记录
+ * 表示 Agent 对某个资源的访问权限
+ */
+export type AgentPermission = {
+  /** 记录 ID */
+  id: string;
+  /** Agent ID */
+  agentId: string;
+  /** 工具名称 */
+  toolName: string;
+  /** 权限类别 */
+  category: string | null;
+  /** 访问模式 */
+  accessPattern: string | null;
+  /** 访问目标列表 */
+  targetsJson: string[];
+  /** 调用次数 */
+  callCount: number;
+  /** 错误次数 */
+  errorCount: number;
+  /** 首次访问时间 */
+  firstSeen: string;
+  /** 最近访问时间 */
+  lastSeen: string;
+};

package/plugin/commands.ts

@@ -0,0 +1,151 @@
+/**
+ * og_status / og_activate 命令处理器
+ *
+ * 提供两个用户命令：
+ * - og_status: 显示 OpenTrust 连接状态、凭证信息
+ * - og_activate: 注册新 Agent 或显示激活状态
+ */
+
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { Logger } from "../agent/types.js";
+import type { PluginState } from "./state.js";
+import type { CoreCredentials } from "../agent/config.js";
+import {
+  registerWithCore,
+} from "../agent/config.js";
+import type { DashboardClient } from "../platform-client/index.js";
+
+/**
+ * 注册用户命令
+ *
+ * @param api - OpenClaw 插件 API
+ * @param log - 日志器
+ * @param state - 插件状态
+ * @param config - 插件配置
+ * @param initDashboardClient - Dashboard 客户端初始化函数
+ */
+export function registerCommands(
+  api: OpenClawPluginApi,
+  log: Logger,
+  state: PluginState,
+  config: Required<import("../agent/types.js").OpenClawGuardConfig>,
+  initDashboardClient: (creds: CoreCredentials) => void,
+): void {
+  // ── og_status 命令：显示状态 ───────────────────────
+  api.registerCommand({
+    name: "og_status",
+    description: "Show OpenTrust status",
+    requireAuth: true,
+    handler: async () => {
+      const creds = state.coreCredentials;
+      const lines = ["**OpenTrust Status**", ""];
+
+      if (creds) {
+        // 显示 Agent 基本信息
+        lines.push(`- Agent ID:  ${creds.agentId}`);
+        lines.push(`- API Key:   ${creds.apiKey.slice(0, 12)}...`); // 只显示前 12 位
+
+        if (creds.email) {
+          // 已激活状态
+          lines.push(`- Email:     ${creds.email}`);
+          lines.push(`- Status:    active`);
+        } else if (creds.claimUrl) {
+          // 待激活状态
+          lines.push(`- Status:    pending activation`);
+          lines.push(`- Activate:  ${creds.claimUrl}`);
+        } else {
+          // 已激活但无邮箱（本地模式）
+          lines.push(`- Status:    active`);
+        }
+
+        lines.push(`- Login:     ${config.coreUrl}/login`);
+      } else {
+        // 正在注册
+        lines.push("- Status:    registering...");
+      }
+
+      // 显示配置信息
+      lines.push("", `- blockOnRisk: ${config.blockOnRisk}`);
+
+      return { text: lines.join("\n") };
+    },
+  });
+
+  // ── og_activate 命令：注册或显示激活状态 ────────────
+  api.registerCommand({
+    name: "og_activate",
+    description: "Register or show activation status",
+    requireAuth: true,
+    handler: async () => {
+      // 情况 1: 已完全激活
+      if (state.coreCredentials?.email) {
+        return {
+          text: [
+            "**OpenTrust: Active**", "",
+            `Agent ID: ${state.coreCredentials.agentId}`,
+            `Email:    ${state.coreCredentials.email}`, "",
+            "Behavioral detection is active.", "",
+            `Login: ${config.coreUrl}/login`,
+          ].join("\n"),
+        };
+      }
+
+      // 情况 2: 已注册但待激活
+      if (state.coreCredentials?.claimUrl) {
+        return {
+          text: [
+            "**OpenTrust: Pending Activation**", "",
+            `Agent ID: ${state.coreCredentials.agentId}`, "",
+            "Enter your email to activate:",
+            `  ${state.coreCredentials.claimUrl}`, "",
+            "After activation you get **30,000 free** detections.", "",
+            `Login: ${config.coreUrl}/login`,
+          ].join("\n"),
+        };
+      }
+
+      // 情况 3: 未注册，执行注册流程
+      try {
+        log.info(`Registering with ${config.coreUrl}...`);
+        const result = await registerWithCore(
+          config.agentName,
+          "OpenClaw AI Agent secured by OpenTrust",
+          config.coreUrl,
+        );
+
+        // 保存注册结果
+        state.lastRegisterResult = result;
+        state.coreCredentials = result.credentials;
+        state.behaviorDetector!.setCredentials(result.credentials);
+
+        // 初始化 Dashboard 客户端
+        initDashboardClient(result.credentials);
+
+        log.info("Registration successful!");
+
+        return {
+          text: [
+            "**OpenTrust: Activate Your Agent**", "",
+            `Agent ID: ${result.credentials.agentId}`, "",
+            "Enter your email to activate:",
+            `  ${result.activateUrl}`, "",
+            "After activation you get **30,000 free** detections.", "",
+            `Login: ${result.loginUrl}`,
+          ].join("\n"),
+        };
+      } catch (err) {
+        // 注册失败
+        return {
+          text: [
+            "**OpenTrust: Registration Failed**", "",
+            `Could not reach ${config.coreUrl}.`,
+            `Error: ${err}`, "",
+            "Possible fixes:",
+            "- Set `coreUrl` in plugin config to point to your instance",
+            "- Or set `apiKey` directly in plugin config to skip registration",
+          ].join("\n"),
+        };
+      }
+    },
+  });
+}