Add files via upload

docs/en-US/plugin-development.md

@@ -2,17 +2,69 @@
 
 [中文](../zh-CN/plugin-development.md)
 
-Plugins can integrate with CyberStrikeAI through HTTP APIs, MCP servers, or resource packs such as tools, roles, Skills, and agents.
+Plugins live under `plugins/`. The repo ships two reference implementations: **Burp Suite extension** and **Chromium DevTools extension**. Integrations typically use HTTP APIs, MCP servers, or resource packs (tools, roles, Skills, agents).
+
+## Layout
+
+```text
+plugins/
+  README.md
+  burp-suite/cyberstrikeai-burp-extension/
+  browser-extension/cyberstrikeai-browser-extension/
+```
 
 ## Plugin Layers
 
 | Layer | Example | Benefit | Cost |
 | --- | --- | --- | --- |
-| API plugin | Burp extension calls `/api/eino-agent` | simple UI integration | depends on API/auth |
+| API plugin | Burp / browser extension calling Agent Stream | simple UI integration | depends on API/auth |
 | MCP plugin | exposes tools to Agent | Agent can call it | needs schema and safety design |
 | Resource pack | ships tools/roles/skills/agents | simple and versionable | less interactive |
 
-Do not start with MCP unless the Agent must actively call your capability.
+Do not start with MCP unless the Agent must actively call your capability. For “send this HTTP request to AI”, an API plugin is enough.
+
+## Burp Suite Extension
+
+Java extension under `plugins/burp-suite/cyberstrikeai-burp-extension/`. Typical flow: read HTTP from Burp → format prompt → call CyberStrikeAI SSE → show Progress/Final in a Burp tab.
+
+Build: JDK + Gradle/Maven → `bash build-mvn.sh` → `dist/cyberstrikeai-burp-extension.jar`.
+
+## Browser Extension (Chromium DevTools)
+
+MV3 DevTools extension under `plugins/browser-extension/cyberstrikeai-browser-extension/`. Aligned with the Burp plugin: capture Network traffic → HTTP/1.1 prompt → SSE output. Full docs: `README.md` / `README.zh-CN.md` in that directory.
+
+Load unpacked at `chrome://extensions/`, or `bash package.sh` → `dist/cyberstrikeai-browser-extension.zip`.
+
+### Auth best practices (browser)
+
+Server `POST /api/auth/login` returns `{ token, expires_at }`. There is **no refresh token** — do not assume silent renewal. Reference: `lib/auth-session.js`, `lib/api.js`, `panel/panel.js`.
+
+| Practice | Description |
+| --- | --- |
+| Session storage | Store token + `expires_at` in `chrome.storage.session`; never persist password |
+| Remaining time | Show `OK · 11h 30m left`; warn when <30min |
+| Local check | Re-check `expires_at` + `GET /api/auth/validate` every 30s |
+| Server probe | Immediate probe when DevTools panel becomes visible |
+| Unreachable | Show warning; keep token during transient outage |
+| 401/403 | Clear token (server restart clears in-memory sessions) |
+| Before Send | `ensureAuthReady()` before SSE |
+| Permissions | `optional_host_permissions` — request origin on Validate |
+
+After extension reload, close DevTools completely and reopen F12 (stale panel context).
+
+### Data and performance (browser)
+
+- Caps: 200 captures/tab, 20 tabs, 512KB progress/run.
+- Default XHR/Fetch only; use pause toggle when not capturing.
+- Truncate or summarize large bodies before sending to Agent.
+
+## API Integration
+
+- Login: `POST /api/auth/login`, then `GET /api/auth/validate`.
+- Persist `expires_at`; re-login when expired (no silent refresh).
+- Prefer `/api/eino-agent/stream` or `/api/multi-agent/stream` (SSE).
+- Large files: `/api/chat-uploads`, then reference in message.
+- Full spec: `/api-docs` or `/api/openapi/spec`.
 
 ## API Plugin Payload
 
@@ -51,12 +103,18 @@ Specific schemas make HITL and Agent behavior safer.
 Plugins should not bypass platform controls:
 
 - no hidden destructive local commands;
-- no plaintext long-lived credentials;
+- no plaintext long-lived credentials (password only for login; token in session storage);
 - no default third-party data exfiltration;
-- no dependency on browser state to bypass login.
+- no dependency on browser state to bypass login;
+- on 401/403, clear session and require re-auth — do not silently retry.
 
 ## Source Anchors
 
 - Burp plugin: `plugins/burp-suite/cyberstrikeai-burp-extension/src/main/java/burp/`
+- Browser extension: `plugins/browser-extension/cyberstrikeai-browser-extension/`
+  - Auth: `lib/auth-session.js`, `lib/api.js`, `lib/storage.js`
+  - UI: `panel/panel.js`
+  - Capture: `devtools.js`, `background/service-worker.js`
 - OpenAPI: `internal/handler/openapi.go`
 - External MCP: `internal/handler/external_mcp.go`
+- Web auth reference: `web/static/js/auth.js`

docs/zh-CN/plugin-development.md

@@ -1,6 +1,6 @@
 # 插件开发
 
-CyberStrikeAI 当前仓库中的插件主要位于 `plugins/`，示例是 Burp Suite 扩展。插件通常通过 HTTP API、MCP 或本地文件与主应用集成。
+CyberStrikeAI 当前仓库中的插件主要位于 `plugins/`，已有 **Burp Suite 扩展**与 **Chromium 浏览器扩展** 两个参考实现。插件通常通过 HTTP API、MCP 或本地文件与主应用集成。
 
 ## 目录
 
@@ -14,6 +14,17 @@ plugins/
       README.zh-CN.md
       build.gradle
       pom.xml
+  browser-extension/
+    cyberstrikeai-browser-extension/
+      manifest.json
+      devtools.js
+      background/service-worker.js
+      panel/
+      popup/
+      lib/
+      README.md
+      README.zh-CN.md
+      package.sh
 ```
 
 ## 插件类型
@@ -40,12 +51,54 @@ Burp 插件目录包含 Java 源码和构建脚本。典型能力：
 - Gradle 或 Maven 可用。
 - CyberStrikeAI 服务地址和认证配置正确。
 
+## 浏览器扩展（Chromium DevTools）
+
+浏览器扩展目录为 MV3 DevTools 扩展，与 Burp 插件能力对齐：捕获 HTTP 流量 → 格式化 Prompt → SSE 流式输出 AI 结果。完整安装与 UI 说明见 `plugins/browser-extension/cyberstrikeai-browser-extension/README.zh-CN.md`。
+
+典型能力：
+
+- 在 DevTools **Network** 中捕获 XHR/Fetch（可暂停）。
+- 原始 HAR 存内存；展示与 AI Prompt 归一化为 **HTTP/1.1**（与 Burp 一致）。
+- 调用 CyberStrikeAI 登录、Validate、Agent Stream API。
+- DevTools 面板展示 Progress / Final；Popup 只读连接状态。
+
+构建与加载：
+
+- 无需编译：`chrome://extensions/` → 加载已解压 → 选择 `cyberstrikeai-browser-extension/`。
+- 打包：`bash package.sh` → `dist/cyberstrikeai-browser-extension.zip`。
+
+### 浏览器插件认证最佳实践
+
+服务端 `POST /api/auth/login` 返回 `{ token, expires_at }`，**无 refresh token**，插件不应假设 Token 会自动续期。参考实现见 `lib/auth-session.js`、`lib/api.js`、`panel/panel.js`：
+
+| 实践 | 说明 |
+| --- | --- |
+| Session 存储 | Token 与 `expires_at` 存 `chrome.storage.session`（关浏览器失效），Password 不落盘 |
+| 剩余时间 | 状态栏显示 `OK · 剩余 11h 30m`；剩余 <30min 警告 |
+| 本地检测 | 每 30s 检查 `expires_at` 并调用 `GET /api/auth/validate` |
+| 服务端探测 | 切回 DevTools 面板 / 窗口聚焦时立即探测 |
+| 服务不可达 | 显示「无法连接服务」，不清 Token（便于服务重启中） |
+| 401/403 | 清空 Token、展开连接栏（服务重启后 session 内存清空） |
+| Send 前校验 | 调用 `ensureAuthReady()`，避免过期 Token 发起 SSE |
+| 按需授权 | `optional_host_permissions`，Validate 时请求目标 origin |
+
+扩展重载后 DevTools 面板上下文可能失效：需 **关闭 DevTools → 重载扩展 → 再开 F12**。
+
+### 浏览器插件数据与性能边界
+
+插件侧应设内存上限，避免 DevTools 长时间开启拖垮浏览器：
+
+- 捕获：200 条 / Tab，20 个 Tab 槽；Progress 512KB / run。
+- 默认 **XHR/Fetch only** + 静态资源预过滤；不需要捕获时用 **已暂停**。
+- 大响应走截断或摘要后再进 Prompt，不要整包塞进消息。
+
 ## API 对接建议
 
 插件调用主应用时：
 
-- 先登录或使用受控认证方式。
-- 优先调用 `/api/eino-agent` 或 `/api/eino-agent/stream`。
+- 先 `POST /api/auth/login`，再 `GET /api/auth/validate` 确认会话。
+- 保存 `expires_at`，过期后重新登录（无 silent refresh）。
+- 优先调用 `/api/eino-agent/stream` 或 `/api/multi-agent/stream`（SSE）。
 - 大文件通过 `/api/chat-uploads` 上传，再在消息中引用。
 - 查询结果或漏洞可写入 `/api/vulnerabilities`。
 - 项目信息可写入 `/api/projects/:id/facts`。
@@ -103,11 +156,11 @@ MCP 工具设计建议：
 
 | 层次 | 例子 | 优点 | 代价 |
 | --- | --- | --- | --- |
-| API 插件 | Burp 扩展调用 `/api/eino-agent` | 易实现，适合 UI 集成 | 依赖认证和 API 稳定性 |
+| API 插件 | Burp / 浏览器扩展调用 Agent Stream | 易实现，适合 UI 集成 | 依赖认证和 API 稳定性 |
 | MCP 插件 | 提供新工具给 Agent | Agent 可主动调用 | 需要 schema 和安全设计 |
 | 资源包插件 | 交付 tools/roles/skills/agents | 最简单，可版本化 | 交互能力弱 |
 
-插件一开始不必做成 MCP。如果只是“把 Burp 请求交给 AI 分析”，API 插件更直接；如果要让 Agent 主动调用 Burp 扫描或查询结果，再做 MCP。
+插件一开始不必做成 MCP。如果只是“把 Burp / 浏览器里的 HTTP 请求交给 AI 分析”，API 插件更直接；如果要让 Agent 主动调用 Burp 扫描或查询结果，再做 MCP。
 
 ## API 插件请求设计
 
@@ -146,12 +199,18 @@ schema 越具体，HITL 越容易判断风险，Agent 也越不容易发散。
 插件不要绕过平台安全控制：
 
 - 不要直接执行本机高风险命令而不暴露给 HITL。
-- 不要在插件内保存明文长期凭证。
+- 不要在插件内保存明文长期凭证（Password 仅用于登录，Token 用 session 存储）。
 - 不要默认把目标数据发给第三方服务。
 - 不要依赖浏览器本地状态绕过登录。
+- 收到 401/403 应清空会话并提示重新认证，不要静默重试或忽略。
 
 ## 源码锚点
 
 - Burp 插件 Java 代码：`plugins/burp-suite/cyberstrikeai-burp-extension/src/main/java/burp/`
+- 浏览器扩展：`plugins/browser-extension/cyberstrikeai-browser-extension/`
+  - 认证：`lib/auth-session.js`、`lib/api.js`、`lib/storage.js`
+  - 主 UI：`panel/panel.js`
+  - 捕获：`devtools.js`、`background/service-worker.js`
 - OpenAPI：`internal/handler/openapi.go`
 - 外部 MCP：`internal/handler/external_mcp.go`
+- Web 端认证参考：`web/static/js/auth.js`