@carfiedli/runtime-guardrail 0.1.19

package/dist/types.d.ts

@@ -0,0 +1,224 @@
+/** 护盾阶段：observe=仅观察 | shadow=影子模式 | enforce_high=仅拦截高危 | enforce_all=全量拦截 */
+export type ShieldStage = "observe" | "shadow" | "enforce_high" | "enforce_all";
+/** 失败模式：open=失败时放行 | closed=失败时拦截 */
+export type ShieldFailMode = "open" | "closed";
+/** 检测面（触发钩子的位置）：ingress=入口 | llm=大模型请求 | tool=工具调用 | egress=出口 | persist=持久化 */
+export type ShieldSurface = "ingress" | "llm" | "tool" | "egress" | "persist";
+/** 严重等级：low=低 | medium=中 | high=高 | critical=严重 */
+export type ShieldSeverity = "low" | "medium" | "high" | "critical";
+/** 规则动作：allow=放行 | redact=脱敏 | block=拦截 */
+export type ShieldRuleAction = "allow" | "redact" | "block";
+/** 钩子动作：在规则动作基础上增加 hold=暂停等待审批 */
+export type ShieldHookAction = ShieldRuleAction | "hold";
+/** 审批状态：pending=待审批 | approved=已批准 | rejected=已拒绝 | expired=已过期 | cancelled=已取消 */
+export type ShieldApprovalStatus = "pending" | "approved" | "rejected" | "expired" | "cancelled";
+/** 审批决策：approved=批准 | rejected=拒绝 */
+export type ShieldApprovalDecision = "approved" | "rejected";
+/** 审批类别：external-send=外发 | deploy=部署 | permission-change=权限变更 | model-override=模型覆盖 | unknown=未知 */
+export type ShieldApprovalCategory = "external-send" | "deploy" | "permission-change" | "model-override" | "unknown";
+/** 运行暂停状态：pending=等待中 | approved_waiting_resume=已批准待恢复 | resumed=已恢复 | rejected/expired/cancelled */
+export type ShieldRunHoldStatus = "pending" | "approved_waiting_resume" | "resumed" | "rejected" | "expired" | "cancelled";
+/** 规则命中记录：记录哪条规则被触发、执行了什么动作、严重等级和原因 */
+export type ShieldMatch = {
+    ruleId: string;
+    action: Exclude<ShieldRuleAction, "allow">;
+    severity: ShieldSeverity;
+    reason?: string;
+};
+/** 脱敏操作描述：指定哪个字段被替换成什么值 */
+export type ShieldRedaction = {
+    ruleId?: string;
+    /** 被脱敏的字段路径 */
+    field: string;
+    /** 脱敏后的替换值 */
+    replacement: string;
+};
+/** 钩子级别的脱敏修改描述 */
+export type ShieldHookModification = {
+    type: "redact";
+    /** 被修改的目标字段 */
+    target: string;
+    /** 替换后的值 */
+    replacement: string;
+    ruleId?: string;
+};
+/** 编译后的护盾规则：完整描述一条安全规则的匹配条件和执行动作 */
+export type CompiledShieldRule = {
+    id: string;
+    action: Exclude<ShieldRuleAction, "allow">;
+    severity: ShieldSeverity;
+    /** 生效的检测面，"any" 表示全部 */
+    surface: ShieldSurface | "any";
+    /** 匹配目标（字段路径或模式） */
+    target: string;
+    /** 脱敏替换值 */
+    replacement: string;
+    reason?: string;
+};
+/** 策略评估发现项：一条检测器发现的安全问题 */
+export type ShieldPolicyFinding = {
+    /** 检测器名称 */
+    detector: string;
+    /** 原因代码（如 prompt_injection, sensitive_action 等） */
+    reasonCode: string;
+    severity: ShieldSeverity;
+    /** 问题摘要 */
+    summary: string;
+    /** 标签 */
+    tags: string[];
+    /** 证据数据 */
+    evidence?: Record<string, unknown>;
+    /** 关联的规则 ID 列表 */
+    ruleIds?: string[];
+};
+/** 策略评估输入：传给策略评估器的上下文信息，包含检测面、Agent 信息、请求内容等 */
+export type ShieldPolicyInput = {
+    surface: ShieldSurface;
+    agentId?: string;
+    runId?: string;
+    sessionId?: string;
+    sessionKey?: string;
+    /** LLM 提供商 */
+    provider?: string;
+    /** 模型名称 */
+    model?: string;
+    /** 用户提示词 */
+    prompt?: string;
+    /** 系统提示词 */
+    systemPrompt?: string;
+    /** 历史消息列表 */
+    historyMessages?: unknown[];
+    /** 消息内容 */
+    message?: unknown;
+    /** 工具名称 */
+    toolName?: string;
+    /** 工具参数 */
+    toolParams?: Record<string, unknown>;
+    /** 工具返回结果 */
+    toolResult?: unknown;
+    /** 技能名称列表 */
+    skillNames?: string[];
+};
+/** 审批请求：当策略需要人工审批时创建的请求记录 */
+export type ShieldApprovalRequest = {
+    approvalId: string;
+    incidentId: string;
+    createdAt: number;
+    status: ShieldApprovalStatus;
+    category: ShieldApprovalCategory;
+    severity: ShieldSeverity;
+    reason: string;
+    tags: string[];
+    agentId?: string;
+    runId?: string;
+    sessionId?: string;
+    toolName?: string;
+    resolvedAt?: number;
+    note?: string;
+    resolvedBy?: string;
+    /** 审批来源（如外部系统） */
+    source?: string;
+    /** 外部审批系统的审批 ID */
+    externalApprovalId?: string;
+};
+/** 运行暂停记录：当工具调用需要审批时暂停执行的完整记录 */
+export type ShieldRunHold = {
+    holdId: string;
+    approvalId: string;
+    incidentId: string;
+    createdAt: number;
+    status: ShieldRunHoldStatus;
+    category: ShieldApprovalCategory;
+    severity: ShieldSeverity;
+    reason: string;
+    agentId?: string;
+    runId?: string;
+    sessionId?: string;
+    /** 被暂停的工具名称 */
+    toolName: string;
+    /** 被暂停的工具参数 */
+    toolParams?: Record<string, unknown>;
+    /** 工具参数的哈希值（用于唯一标识） */
+    toolParamsHash: string;
+    /** 暂停时所处的护盾阶段 */
+    stageAtHold: ShieldStage;
+    /** 暂停时的失败模式 */
+    failModeAtHold: ShieldFailMode;
+    source?: string;
+    externalApprovalId?: string;
+    resolvedAt?: number;
+    expiredAt?: number;
+    cancelledAt?: number;
+    cancelledBy?: string;
+    resumedAt?: number;
+    resumeRequestedAt?: number;
+    resumedBy?: string;
+    note?: string;
+};
+/** 安全事件记录：每次策略评估产生的安全事件 */
+export type ShieldIncident = {
+    id: string;
+    timestamp: number;
+    surface: ShieldSurface;
+    agentId?: string;
+    runId?: string;
+    sessionId?: string;
+    /** 原始动作（策略评估的原始结果） */
+    rawAction: ShieldRuleAction;
+    /** 生效动作（考虑模拟模式等因素后的实际动作） */
+    effectiveAction: ShieldRuleAction;
+    blockReason?: string;
+    severity: ShieldSeverity;
+    tags: string[];
+    /** 采样数据（用于调试/审计） */
+    sample?: Record<string, unknown>;
+};
+/** 策略评估结果：策略评估器返回的完整结果，包含动作、脱敏、匹配规则、审批请求等 */
+export type ShieldPolicyResult = {
+    /** 原始动作（策略原始判定） */
+    rawAction: ShieldRuleAction;
+    /** 生效动作（考虑阶段/模拟后的实际动作） */
+    effectiveAction: ShieldRuleAction;
+    severity: ShieldSeverity;
+    blockReason?: string;
+    /** 是否为模拟拦截（仅记录不实际拦截） */
+    simulatedBlock: boolean;
+    /** 是否为模拟脱敏 */
+    simulatedRedaction: boolean;
+    /** 脱敏操作列表 */
+    redactions: ShieldRedaction[];
+    /** 各字段脱敏后的完整值，供宿主侧真正改写消息/持久化内容 */
+    redactedTexts?: Record<string, string>;
+    /** 命中的规则列表 */
+    matched: ShieldMatch[];
+    /** 已应用的例外规则 ID 列表 */
+    appliedExceptions: string[];
+    /** 脱敏规则列表 */
+    redactionRules: CompiledShieldRule[];
+    tags: string[];
+    /** 评估耗时（毫秒） */
+    durationMs: number;
+    /** 检测发现列表 */
+    findings?: ShieldPolicyFinding[];
+    /** 钩子修改列表 */
+    modifications?: ShieldHookModification[];
+    /** 审批请求（如需人工审批） */
+    approvalRequest?: ShieldApprovalRequest;
+    /** 运行暂停请求 */
+    runHold?: ShieldRunHold;
+};
+/** 钩子结果：返回给宿主平台的最终结果，包含动作、修改、发现和审计日志 */
+export type ShieldHookResult = {
+    /** 最终动作 */
+    action: ShieldHookAction;
+    /** 需要应用的修改（如脱敏） */
+    modifications: ShieldHookModification[];
+    /** 决策动作（与 action 一致） */
+    decision: ShieldHookAction;
+    /** 决策原因描述 */
+    reason: string;
+    /** 检测发现列表 */
+    findings: ShieldPolicyFinding[];
+    /** 审计日志数据 */
+    auditLog: Record<string, unknown> | null;
+};

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const RUNTIME_GUARDRAIL_VERSION = "0.1.19";

package/openclaw.plugin.json

@@ -0,0 +1,76 @@
+{
+  "id": "runtime-guardrail",
+  "name": "Runtime Guardrail",
+  "description": "OpenClaw runtime guardrail plugin with remote policy, bundled guardrail config, skills upload, and telemetry.",
+  "version": "0.1.19",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "skillsUpload": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": {
+            "type": "boolean"
+          },
+          "force": {
+            "type": "boolean"
+          },
+          "timeoutMs": {
+            "type": "number"
+          },
+          "contentType": {
+            "type": "string"
+          }
+        }
+      },
+      "remoteGuard": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "configPath": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    }
+  },
+  "uiHints": {
+    "skillsUpload.enabled": {
+      "label": "启用 Skills 上传",
+      "group": "Skills 上传",
+      "order": 10
+    },
+    "skillsUpload.force": {
+      "label": "强制上传",
+      "help": "忽略本地去重缓存，强制重新打包并上传。",
+      "group": "Skills 上传",
+      "order": 20,
+      "advanced": true
+    },
+    "skillsUpload.timeoutMs": {
+      "label": "上传超时（毫秒）",
+      "group": "Skills 上传",
+      "order": 30,
+      "advanced": true,
+      "placeholder": "10000"
+    },
+    "skillsUpload.contentType": {
+      "label": "上传 Content-Type",
+      "group": "Skills 上传",
+      "order": 40,
+      "advanced": true,
+      "placeholder": "application/zip"
+    },
+    "remoteGuard.configPath": {
+      "label": "远端配置文件路径",
+      "help": "默认读取插件随包发布的 remote-guard-config.json；仅在需要覆盖基础静态配置时再指定自定义路径。",
+      "group": "远端配置",
+      "order": 100,
+      "advanced": true,
+      "placeholder": "/absolute/path/to/remote-guard-config.json"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@carfiedli/runtime-guardrail",
+  "version": "0.1.19",
+  "description": "OpenClaw runtime guardrail plugin with remote policy, bundled guardrail config, skills upload, and telemetry.",
+  "license": "UNLICENSED",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "runtime-guardrailctl": "scripts/runtime-guardrailctl.mjs"
+  },
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "remote-guard-config.json",
+    "scripts/runtime-guardrailctl.mjs",
+    "README.md",
+    "README.hooks-security.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "build:tsc": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "sync:plugin-version": "node scripts/sync-plugin-version.mjs",
+    "verify:plugin-version": "node scripts/sync-plugin-version.mjs --check",
+    "verify:release": "npm run sync:plugin-version && npm run clean && npm run check && npm run build",
+    "prepack": "npm run sync:plugin-version && npm run clean && npm run build",
+    "prepublishOnly": "npm run verify:release",
+    "publish": "node scripts/publish-internal.mjs",
+    "publish:dry-run": "node scripts/publish-internal.mjs --dry-run",
+    "publish:public": "npm run build && node scripts/publish-public.mjs",
+    "publish:public:dry-run": "npm run build && node scripts/publish-public.mjs --dry-run",
+    "demo": "RUNTIME_GUARDRAIL_POLICY_MODE=remote npx tsx demo/run.ts",
+    "smoke:openclaw": "npm run smoke:openclaw:remote",
+    "smoke:openclaw:remote": "openclaw gateway call shield.status --json | cat",
+    "openclaw:install:global": "node scripts/runtime-guardrailctl.mjs install --global",
+    "openclaw:update:global": "node scripts/runtime-guardrailctl.mjs update --global",
+    "openclaw:set-api-key:global": "node scripts/runtime-guardrailctl.mjs set-api-key --global",
+    "sync:openclaw": "bash scripts/sync-openclaw-extension.sh",
+    "sync:openclaw:current": "bash scripts/sync-openclaw-current.sh",
+    "sync:openclaw:current:restart": "bash scripts/sync-openclaw-current.sh --restart",
+    "fe": "cd frontend && npm run dev",
+    "build:fe": "cd frontend && tea build",
+    "fe:simple": "browser-sync start --server 'frontend/vanilla' --files 'frontend/vanilla/**/*' --port 8080"
+  },
+  "dependencies": {
+    "json5": "^2.2.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "browser-sync": "^3.0.4",
+    "esbuild": "^0.27.4",
+    "tsx": "^4.21.0",
+    "typescript": "^5.6.3",
+    "vitest": "^4.0.18"
+  }
+}

package/remote-guard-config.json

@@ -0,0 +1,30 @@
+{
+  "enabled": true,
+  "server": {
+    "ip": "116.31.68.64",
+    "port": 80,
+    "path": "/v1/ai-guard",
+    "corPresignPath": "/v1/upload/presign",
+    "detectPath": "/v1/skill-detection/submit"
+  },
+  "websocket": {
+    "port": 80,
+    "protocol": "ws"
+  },
+  "auth": {
+    "key": ""
+  },
+  "identity": {
+    "agentId": "carfiedli_agent_001"
+  },
+  "telemetry": {
+    "enabled": true,
+    "heartbeatIntervalMs": 60000,
+    "dataReportIntervalMs": 600000
+  },
+  "options": {
+    "timeoutMs": 60000,
+    "syncHookTimeoutMs": 500,
+    "skillsStateDir": ".tmp-skills-state"
+  }
+}