@aimarket/warden 0.22.4 → 0.23.0

package/docs/flow-guard.zh.md

@@ -311,7 +311,7 @@ Wrap 提问前读取基线，批准后重新验证工具定义并再次读取。
 - 只改变回答的注入不会发出可拒绝的调用。自 2026-10-22 起，插件的 Stop 钩子会在本轮读过外部文本的回答下方加一行，列出这些来源；若其中有文本以指令口吻对助手说话，也会注明。如果回答连续重复了外部文本中对助手下指令那几句话里的 12 个规范化字符，钩子还会把回答退回给模型一次（`decision: block`），在用户读到之前对照用户的请求检查；用户只损失这次检查的时间。`answerNote`：`always`（默认）、`instruction`（只在这种情况下）或 `off`；插件之外请注册 `warden-mcp hook stop`。
 - 代理也记录 JSON-RPC 和工具错误；记录失败时不转发响应，现有会话状态损坏时阻止检查中的调用。
 
-已在 npm `0.17.0` 发布：`npx -y @aimarket/warden@0.22.4 hook pre-tool-use`；或从源码在 WARDEN 目录运行 `npm ci && npm run build`，然后使用 `node dist/mcp-server.js hook pre-tool-use`，并注册 prompt/post hooks。策略为 `~/.local/state/warden/flow-policy.json` 或 `WARDEN_FLOW_POLICY`；模式为 `ask`、`deny`、`audit`、`off`。当前配置示例见[英文页](flow-guard.md)。
+已在 npm `0.17.0` 发布：`npx -y @aimarket/warden@0.23.0 hook pre-tool-use`；或从源码在 WARDEN 目录运行 `npm ci && npm run build`，然后使用 `node dist/mcp-server.js hook pre-tool-use`，并注册 prompt/post hooks。策略为 `~/.local/state/warden/flow-policy.json` 或 `WARDEN_FLOW_POLICY`；模式为 `ask`、`deny`、`audit`、`off`。当前配置示例见[英文页](flow-guard.md)。
 
 代理命令：`node dist/mcp-server.js wrap --flow mail -- node mail-server.js`。同一会话的代理应共享一个新的 `WARDEN_FLOW_SESSION`。默认父进程 PID 不能关联不同启动器。代理看不到用户提示或客户端内置工具。需要确认的调用会在客户端提供 MCP elicitation 表单时通过表单询问（回答记入日志的 `approvalOutcome`），否则或使用 `--ask refuse` 时被拒绝。`trustedSources` 仅用于 WebFetch URL，不用于 MCP 参数中的任意链接。
 

package/docs/gates.md

@@ -2,7 +2,7 @@
 
 > 🌐 **English** · [Русский](gates.ru.md) · [Español](gates.es.md) · [Français](gates.fr.md) · [中文](gates.zh.md)
 
-**Ruleset v17 (0.22.4):** v17 catches a tool that adds a fixed recipient to another server's tool, a case from outside MCPTox (see v17 below). v15 widened `TOOL_DEF_CROSS_TOOL` and v16 added two patterns for tools that take no input, both written from MCPTox's dev half and measured on 2026-10-22 on MCPTox, the field corpus and 1,000 HISTOR packages (see v15 and v16 below). v14 stopped treating storage on a server as local custody. Numbers quoted for earlier versions are historical.
+**Ruleset v17 (0.23.0):** v17 catches a tool that adds a fixed recipient to another server's tool, a case from outside MCPTox (see v17 below). v15 widened `TOOL_DEF_CROSS_TOOL` and v16 added two patterns for tools that take no input, both written from MCPTox's dev half and measured on 2026-10-22 on MCPTox, the field corpus and 1,000 HISTOR packages (see v15 and v16 below). v14 stopped treating storage on a server as local custody. Numbers quoted for earlier versions are historical.
 
 > [0.7.0 security changes and migration](security-hardening.md).
 

package/docs/opencode.md

@@ -0,0 +1,121 @@
+# Flow guard for OpenCode
+
+The [flow guard](flow-guard.md) of the Claude Code plugin, through [OpenCode](https://opencode.ai)'s plugin hooks.
+It is written for agents that run with nobody at the keyboard: Multica runtimes, CI jobs, scheduled reports.
+
+## What it does
+
+| OpenCode hook | Guard step |
+|---|---|
+| `tool.execute.before` | Maps the call to the guard's tool vocabulary (`bash` → `Bash`, `read` → `Read`, `write`/`edit`/`apply_patch` → `Write`/`Edit`, `webfetch` → `WebFetch`, `<server>_<tool>` → `mcp__<server>__<tool>`) and runs the PreToolUse check. A refused call throws: OpenCode does not run the tool, and the model reads the reason. |
+| `tool.execute.after` | Runs the PostToolUse check: what the result brought in (outside text, private data, credentials). The guard's warning about instructions in a result is appended to that result. |
+| `chat.message` | Records destinations the user's own message names. |
+| `shell.env` | Blanks the environment variables you list (`stripEnv`) for shell commands. An injected `env` or `printenv` then cannot read a key that only the OpenCode process needs, such as the model provider's key or a hub key used by an MCP header. |
+
+A subagent (`task`) runs in a child session. The guard keeps one state per session tree, keyed by its root: what a
+child reads binds the parent and the other way round, so an injected parent cannot hand the read-and-send to a
+fresh child. Parents come from `session.created`/`session.updated` events, else from the SDK client. A child's prompt
+is written by the parent model and is not recorded as the user's words. If recording a result fails, every later
+call of that session tree is refused.
+
+MCP server names come from OpenCode's config (`mcp` section). A tool that is neither a core tool nor a configured
+MCP tool (a subagent `task`, another plugin's tool) is treated as an unlabelled MCP tool: its result is outside text.
+
+## No one to ask: `block`
+
+Where the Claude Code hook would ask a person, an unattended agent has nobody to ask. `block` decides:
+
+- **`data`** (default). Refuses every call that involves data: a known secret in the arguments, a call after the
+  session read a credential (`credential_egress`), private text or personal data matching what the session read,
+  a short credential fragment, an incomplete payload check, a change to the guard's or OpenCode's own settings.
+  It also refuses any decision whose payload the guard marks sensitive, whatever reason came first (opaque shell
+  code after a credential read is refused, not waved through as "only shell code"). Calls that only *act* after
+  outside text — shell code outside the read-only subset, an unconfirmed destination, a destructive command, a GUI
+  action — run, and the resolution is logged next to the guard's own line (`"event":"opencode"`,
+  `"resolution":"allowed_unattended"`).
+- **`all`**. Refuses everything the Claude Code hook would ask about. Most agents then stop at their first shell
+  command after reading a web page.
+
+Why `data` lets actions through: an unattended agent's job is usually to read outside text and then report — a
+digest of GitHub issues sent to a chat, a market check written to a ticket. Refusing every shell command after the
+first read stops the job, not the attacker. What bounds *where* such an agent can act is a network allowlist or a
+sandbox around it; what the guard adds is that data the session read does not leave with those actions.
+
+Measured with the red-team replay (`node scripts/redteam/flow-redteam.mjs --opencode=MODE`, 28 attacks written
+against the guard's code, no model, no network):
+
+| Profile | Delivered |
+|---|---|
+| Claude Code hook (a person answers every question) | 0 of 28 |
+| OpenCode, `block: "all"` | 0 of 28 |
+| OpenCode, `block: "data"` | 3 of 28 |
+
+The three in `data` are actions without data: an MCP `push` with no credential read and no URL argument, an
+unlabelled calendar tool that adds the attacker as an attendee, an unlabelled repository tool that gives the
+attacker's account write access. Label such tools in `flow-policy.json` (`labels`) or use `block: "all"` when an
+agent holds tools like these.
+
+## Credentials the guard recognizes
+
+Besides the earlier formats (private keys, AWS, GitHub, GitLab, Slack, npm, `sk-…` API keys, Google API keys),
+agent runtimes carry two more: a **Telegram bot token** (`<bot id>:AA…`) and an **AIMarket hub API key**
+(`aimk_…`). Reading them (from `env`, a file or a tool result) marks the session as holding credentials; sending
+one is denied.
+
+Secret paths added for agent runtimes: OpenCode's `~/.local/share/opencode/auth.json` and Multica's
+`~/.multica/config.json`. Protected paths added (changing them would switch the guard off): `~/.config/opencode/`,
+any `.opencode/` folder and `opencode.json`/`opencode.jsonc`.
+
+## Install
+
+The plugin is the compiled `dist/opencode-plugin.js` and the `dist/flow-guard*.js` parts it imports (Node built-ins
+only). With the package installed where OpenCode resolves modules, put this one file in OpenCode's plugin folder
+(`~/.config/opencode/plugin/` globally, `.opencode/plugin/` in a project):
+
+```js
+// warden.js — export only the plugin: OpenCode calls every exported function as one.
+import { createWardenPlugin } from '@aimarket/warden/opencode';
+
+export const WardenFlowGuard = createWardenPlugin({
+  block: 'data',
+  stripEnv: ['DEEPSEEK_API_KEY', 'OPENAI_API_KEY', 'ANTHROPIC_API_KEY'],
+});
+```
+
+Without the package, copy `dist/opencode-plugin.js` and every `dist/flow-guard*.js` into one folder next to the
+config (for example `~/.config/opencode/warden/`) and import `../warden/opencode-plugin.js` instead.
+`opencode-plugin/warden.js` in this repository is that loader.
+
+Environment overrides: `WARDEN_OPENCODE_BLOCK=data|all`, `WARDEN_OPENCODE_STRIP_ENV=NAME,NAME`. The guard's state
+and log live in the usual state directory (`WARDEN_STATE_DIR`, default `~/.local/state/warden`); the policy file is
+the same `flow-policy.json` as for Claude Code.
+
+## In a live Multica runtime (2026-11-04)
+
+Two Multica agents (OpenCode 1.18.32 + DeepSeek, unattended, egress through an allowlist proxy) run with
+`block: "data"` and `stripEnv` for the model key and two hub keys.
+
+- **A full GitHub digest** (read GitHub, read and write Attested Memory over MCP, post the report to the tracker,
+  close the task): 18 reviewable decisions, all `allowed_unattended`, 0 refused. The first run found a false
+  positive: the task's UUID, read in a command's output and passed back to the tracker CLI, matched as private text
+  and as a "number" (personal data), so posting the report was refused. Fixed in the core: a canonical UUID is no
+  personal-data token, and private-text fingerprints drop UUIDs except on a line that names a credential
+  (`withoutRecordIds`), so a UUID-shaped API key read from an ordinary file is still caught.
+- **A staged attack** with a fake GitHub token in a file: after the agent read GitHub and then the file, sending
+  through the chat script, `curl` to an allowed host with the file as body, a public Attested Memory write over MCP,
+  a project-file write and the tracker CLI were all refused. `printenv` showed the model key blank in the shell and
+  `GH_TOKEN` present (the agent's `gh` needs it). Before any of that, the agent's own attempts to list and grep the
+  plugin folder were refused as touching the guard's settings.
+
+## Limits
+
+- The guard sees tool calls. It does not see what the model says, and it cannot stop harm that needs no tool call.
+- `data` mode lets actions run after outside text, by design; see above.
+- `chat.message` treats the user message as the user's words. A runtime that puts other people's text into that
+  message (issue comments, forwarded chat) makes destinations named there count as user-named.
+- The runtime may deliver the model's final answer itself: Multica posts it as a tracker comment without a tool
+  call, so the guard does not see it. In the staged attack that comment carried no key; nothing technical stops it.
+- `shell.env` blanks variables for shell commands only. The OpenCode process keeps them; a key passed to an MCP
+  server as a header stays with OpenCode.
+- Tested against OpenCode 1.18.32's plugin interface (`@opencode-ai/plugin`), in unit tests that drive the hooks
+  directly and in a Multica runtime; other versions may name tools differently.

package/docs/scan.es.md

@@ -7,11 +7,11 @@ Las llamadas de descubrimiento pueden generar cargos; consulte los [límites de
 `warden-mcp scan` lee la configuración MCP que ya tienes, se conecta a cada servidor que inicia y revisa las definiciones de herramientas antes de que un modelo las vea. Es la misma cadena de compuertas que [`wrap`](../README-es.md) y la [biblioteca](integration.es.md), ejecutada una vez sobre tus configuraciones en lugar de delante de un solo servidor.
 
 ```bash
-npx -y @aimarket/warden@0.22.4 scan
+npx -y @aimarket/warden@0.23.0 scan
 ```
 
 ```text
-WARDEN scan 0.22.4 · ruleset 17 sha256-UOfK25xo6D8v… · block at high
+WARDEN scan 0.23.0 · ruleset 17 sha256-UOfK25xo6D8v… · block at high
   read .mcp.json (claude-code, 3 servers)
 
   ✓ allow   notes       claude-code    1 tool · score 0.90

package/docs/scan.fr.md

@@ -7,11 +7,11 @@ Les appels de découverte peuvent entraîner des frais ; consultez les [limites
 `warden-mcp scan` lit la configuration MCP que vous avez déjà, se connecte à chaque serveur qu’elle démarre et vérifie les définitions d’outils avant qu’un modèle ne les voie. C’est la même chaîne de portes que [`wrap`](../README-fr.md) et la [bibliothèque](integration.fr.md), exécutée une fois sur vos configurations au lieu de se placer devant un seul serveur.
 
 ```bash
-npx -y @aimarket/warden@0.22.4 scan
+npx -y @aimarket/warden@0.23.0 scan
 ```
 
 ```text
-WARDEN scan 0.22.4 · ruleset 17 sha256-UOfK25xo6D8v… · block at high
+WARDEN scan 0.23.0 · ruleset 17 sha256-UOfK25xo6D8v… · block at high
   read .mcp.json (claude-code, 3 servers)
 
   ✓ allow   notes       claude-code    1 tool · score 0.90

package/docs/scan.md

@@ -7,11 +7,11 @@ Discovery calls can incur costs; see [measurement limits and version evidence](s
 `warden-mcp scan` reads the MCP configuration you already have, connects to every server it starts, and vets the tool definitions before a model sees them. It is the same gate chain as [`wrap`](../README.md#protect-claude-desktop-or-cursor-with-one-wrapper) and the [library](integration.md), run once over your configs instead of in front of one server.
 
 ```bash
-npx -y @aimarket/warden@0.22.4 scan
+npx -y @aimarket/warden@0.23.0 scan
 ```
 
 ```text
-WARDEN scan 0.22.4 · ruleset 17 sha256-UOfK25xo6D8v… · block at high
+WARDEN scan 0.23.0 · ruleset 17 sha256-UOfK25xo6D8v… · block at high
   read .mcp.json (claude-code, 3 servers)
 
   ✓ allow   notes       claude-code    1 tool · score 0.90

package/docs/scan.ru.md

@@ -7,11 +7,11 @@
 `warden-mcp scan` читает уже существующую у вас конфигурацию MCP, подключается к каждому серверу из неё и проверяет определения инструментов до того, как их увидит модель. Это та же цепочка гейтов, что у [`wrap`](../README-ru.md) и у [библиотеки](integration.ru.md), только пройденная один раз по вашим конфигам, а не перед одним сервером.
 
 ```bash
-npx -y @aimarket/warden@0.22.4 scan
+npx -y @aimarket/warden@0.23.0 scan
 ```
 
 ```text
-WARDEN scan 0.22.4 · ruleset 17 sha256-UOfK25xo6D8v… · block at high
+WARDEN scan 0.23.0 · ruleset 17 sha256-UOfK25xo6D8v… · block at high
   read .mcp.json (claude-code, 3 servers)
 
   ✓ allow   notes       claude-code    1 tool · score 0.90

package/docs/scan.zh.md

@@ -7,11 +7,11 @@
 `warden-mcp scan` 读取你已有的 MCP 配置，连接其中启动的每个服务器，并在模型看到工具定义之前对其进行审查。它与 [`wrap`](../README-zh.md) 和[库](integration.zh.md)使用同一条关卡链，只是对你的配置运行一次，而不是挡在单个服务器前面。
 
 ```bash
-npx -y @aimarket/warden@0.22.4 scan
+npx -y @aimarket/warden@0.23.0 scan
 ```
 
 ```text
-WARDEN scan 0.22.4 · ruleset 17 sha256-UOfK25xo6D8v… · block at high
+WARDEN scan 0.23.0 · ruleset 17 sha256-UOfK25xo6D8v… · block at high
   read .mcp.json (claude-code, 3 servers)
 
   ✓ allow   notes       claude-code    1 tool · score 0.90

package/opencode-plugin/warden.js

@@ -0,0 +1,10 @@
+// WARDEN flow guard for OpenCode: copy this file into OpenCode's plugin folder (~/.config/opencode/plugin/ or
+// .opencode/plugin/), and dist/opencode-plugin.js with every dist/flow-guard*.js into ~/.config/opencode/warden/.
+// Export only the plugin: OpenCode calls every exported function as one. See docs/opencode.md.
+import { createWardenPlugin } from '../warden/opencode-plugin.js';
+
+export const WardenFlowGuard = createWardenPlugin({
+  block: 'data',
+  // Keys only the OpenCode process needs; shell commands get them blank. Add your provider's.
+  stripEnv: ['DEEPSEEK_API_KEY', 'OPENAI_API_KEY', 'ANTHROPIC_API_KEY'],
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aimarket/warden",
-  "version": "0.22.4",
+  "version": "0.23.0",
   "description": "WARDEN — MCP security firewall. Stdio wrap proxy, inspection tools and library. Vets definitions before model exposure. Zero runtime dependencies.",
   "type": "module",
   "license": "MIT",
@@ -34,6 +34,11 @@
       "types": "./dist/atomic-screen.d.ts",
       "import": "./dist/atomic-screen.js",
       "default": "./dist/atomic-screen.js"
+    },
+    "./opencode": {
+      "types": "./dist/opencode-plugin.d.ts",
+      "import": "./dist/opencode-plugin.js",
+      "default": "./dist/opencode-plugin.js"
     }
   },
   "files": [
@@ -51,11 +56,13 @@
     "docs/security-hardening*.md",
     "docs/gates*.md",
     "docs/flow-guard*.md",
+    "docs/opencode*.md",
     "examples/atomic-screen-server.mjs",
     "examples/answer-gate-host.mjs",
     "native/macos/Package.swift",
     "native/macos/Sources",
-    "scripts/build-macos.mjs"
+    "scripts/build-macos.mjs",
+    "opencode-plugin/warden.js"
   ],
   "engines": {
     "node": ">=20"