Update project structure and dependencies; add architecture documentation and improve build scripts. Introduce new versioning and permissions for enhanced functionality.

2026-09-26 05:01:53 +08:00 · 2026-08-06 15:11:35 +08:00
parent c8380de521
commit 0371a8b802
113 changed files with 15944 additions and 6556 deletions
@@ -0,0 +1,38 @@
+# Enterprise Deployment
+
+The extension includes `managed-storage-schema.json`. Managed values are read-only and rechecked by background command handlers, not only reflected in disabled UI controls.
+
+Supported policies:
+
+| Key | Type | Effect |
+| --- | --- | --- |
+| `bridgeTransport` | `native` or `websocket` | Locks transport. |
+| `bridgeEndpoint` | string | Locks the explicit loopback WebSocket endpoint. |
+| `nativeHost` | string | Locks the Native Messaging host name. |
+| `autoConnect` | boolean | Locks startup connection behavior. |
+| `disableWebSocket` | boolean | Requires Native Messaging. |
+| `floatingPanelEnabled` | boolean | Enables or disables the page panel. |
+| `maxGrantMinutes` | integer, 5-1440 | Caps every grant even if the UI requests longer. |
+| `grantAllowedOrigins` | origin array | Rejects grants containing any other origin. |
+| `allowProgramEval` | boolean | Can prohibit the independent program Eval scope. |
+
+Example managed policy values:
+
+```json
+{
+  "bridgeTransport": "native",
+  "nativeHost": "com.yaklang.browser_agent",
+  "autoConnect": true,
+  "disableWebSocket": true,
+  "maxGrantMinutes": 60,
+  "grantAllowedOrigins": ["https://security-lab.example"],
+  "allowProgramEval": false,
+  "floatingPanelEnabled": true
+}
+```
+
+Chrome/Edge administrators distribute these values using the platform's extension managed-storage policy and can force-install the signed extension ID. Firefox administrators use the `3rdparty.Extensions` policy for the add-on ID `[email protected]`. Native Host registration remains an operating-system deployment step; see [native-host/README.md](../native-host/README.md).
+
+The Chrome enterprise package prefers User Scripts MAIN for CSP-compatible page execution and retains the packaged injected bridge as a fallback when User Scripts is unavailable. Administrators should enable User Scripts for the extension in managed Chrome deployments when strict-site CSP execution is required; the fallback remains suitable for explicitly managed sites whose CSP permits it.
+
+Device pairing identities are deliberately excluded from managed storage. Pair each extension installation locally through Yakit. The extension keeps its non-extractable private key in IndexedDB and Yak stores only the approved public device identity, so a broadly readable policy backend never becomes a credential store.
@@ -0,0 +1,22 @@
+# Permission Inventory
+
+Every permission maps to a shipped, user-facing feature. Future functionality is not a reason to retain an unused permission.
+
+| Permission | Purpose | User control |
+| --- | --- | --- |
+| `proxy` | Apply direct/system/fixed/PAC profiles and deterministic routing rules. | Profiles and rules are visible and switchable; passwords are session-only. |
+| `storage` | Store split settings, active session, bounded audit and aggregate metrics. | Audit, action timeline and metrics can be cleared; diagnostics export is explicit. |
+| `tabs` | Resolve the exact user-selected tab and open Options/Yakit workflow pages. | Grant and target picker identify the tab. |
+| `scripting` | Run packaged frame probes, stable-node operations and page observation. | Page operations are explicit and scoped. |
+| `cookies` | Provide the Cookie Editor and explicitly granted authentication context. | Values are hidden and exports redacted by default. |
+| `declarativeNetRequest` | Change the real outbound User-Agent request header. | Named UA rules are visible and removable. |
+| `webRequest` | Capture bounded Fetch/XHR/Form metadata and proxy rule hits. | Capture starts explicitly; headers/body are off by default. |
+| `webNavigation` | Track frame/document identity and SPA/document lifecycle. | Used to reject stale or cross-origin targets. |
+| `webRequestAuthProvider` (Chrome) / `webRequestBlocking` (Firefox) | Answer proxy authentication challenges. | Username is in the profile; password is browser-session-only. |
+| `userScripts` (Chrome Store/Enterprise) | Execute user/Agent-selected page code through Chrome's documented MAIN-world User Scripts API. | Chrome also requires the user to enable Allow User Scripts; expression/program grants are separate. |
+| `nativeMessaging` (optional) | Connect to the installed local Yakit Native Host. | Requested only when the user selects Native Host in Options. |
+| `<all_urls>` host access | Support authenticated testing on the HTTP(S) site selected by the user, the floating task control, frame inventory and request capture. | Site panel rules and task-bound grants narrow actual Agent access. Browser-internal pages remain unavailable. |
+
+`activeTab` is intentionally not requested. Firefox AMO does not request `userScripts`; its public build is invoke-only and excludes general page function invocation/Eval. Chrome Store does not package the injected Eval bridge.
+
+References: [Chrome minimum permission policy FAQ](https://developer.chrome.com/docs/webstore/program-policies/user-data-faq), [Chrome MV3 requirements](https://developer.chrome.com/docs/webstore/program-policies/mv3-requirements), and [Mozilla Add-on Policies](https://extensionworkshop.com/documentation/publish/add-on-policies/).
@@ -0,0 +1,54 @@
+# Yakit Browser Agent Privacy Policy
+
+Effective date: 2026-07-17
+
+Yakit Browser Agent is a browser security-testing extension that connects browser context selected by the user to a Yak/Yakit engine running on the same computer. This policy describes the extension source in this repository and its official packaged builds.
+
+## Data the extension handles
+
+Depending on the command the user selects and the grant scopes they enable, the extension can handle:
+
+- page URL, title, frame and document identity;
+- bounded page text, forms, interactive element metadata, open Shadow DOM metadata, and authentication signals;
+- Cookie metadata and values, including HttpOnly cookies exposed by the browser Cookies API;
+- localStorage/sessionStorage keys, IndexedDB database/store/key inventory, and CacheStorage names; database and cache values are not collected;
+- request URL, method, timing and status, plus request headers, Cookie and body only when sensitive capture is explicitly enabled;
+- temporary Fetch/XHR/Form/WebSocket/WebCrypto/CryptoJS observations; value previews require a separate sensitive scope;
+- proxy, User-Agent header, floating-panel and Bridge settings;
+- local operational metrics such as aggregate Bridge latency, connection errors, capability duration and Service Worker starts.
+
+## How data is used
+
+Data is used only to provide user-facing browser security workflows: inspect an authenticated page, operate explicitly selected elements, replay a selected request in Yakit, analyze authentication/signing behavior, or let an Agent continue after user-controlled QR/MFA/CAPTCHA handling. It is not used for advertising, credit decisions, user profiling, sale, or unrelated analytics.
+
+## Data transmission
+
+The extension has no developer-operated telemetry or analytics endpoint. Browser context is sent only after a user creates a time-limited grant or invokes a clearly labeled workflow. The destination is the user-configured Native Messaging host or an explicit loopback WebSocket endpoint. The default is `ws://127.0.0.1:64333/extension`.
+
+The Native Host is a local transport to that loopback Yak Bridge. Bridge v3 still verifies the paired extension identity, browser extension Origin, task, grant, target and capability scopes. A website cannot access this channel.
+
+## Local storage and retention
+
+- Proxy, User-Agent, Bridge and floating-panel settings remain until the user changes them or removes the extension.
+- The paired engine public identity and device ID are local settings. The extension's non-extractable P-256 private key remains in extension-owned IndexedDB; no reusable bearer token is stored. Proxy passwords, active grants, handoffs, action timelines, captured requests and observation values are session-scoped.
+- Audit storage retains at most 500 metadata-only records. It omits page content, URLs, request parameters, Cookie/token values, Eval code, arguments and results.
+- Context and request buffers are bounded and replaced or cleared by document, grant and session lifecycle.
+- Operational metrics are aggregate local counters. They are included only when the user explicitly exports a diagnostics file.
+
+## User control
+
+The user selects the tab/frame, scopes and expiration for every Agent grant and can pause, resume or revoke it. Sensitive network fields, observation values and program Eval each require separate controls or scopes. Cookie values are hidden by default. Exports are redacted by default. The floating panel can be disabled globally, restricted to active tasks, or controlled with an allowlist/denylist.
+
+Removing the extension deletes browser-managed extension storage. The Native Host installer has an uninstall option that removes its per-user manifests and copied executable.
+
+## Security
+
+The WebSocket Bridge accepts explicit loopback hosts only. First-time pairing requires the user to compare a six-digit code in the extension and Yakit. Later handshakes use mutually verified P-256 signatures and identify the engine, extension installation, connection and resumable session. Revoking a paired device closes its active connection. Grants bind task, tab, frame, document, origin, scopes and expiry. Messages have runtime schemas, concurrency limits, cancellation, bounded payloads and chunk reassembly limits.
+
+No system can guarantee absolute security. Do not use the extension against systems you are not authorized to test, and do not include secrets in public bug reports.
+
+## Changes and contact
+
+Material policy changes must accompany a product update and updated store disclosures. Questions or security reports can be opened at [yaklang/yaklang issues](https://github.com/yaklang/yaklang/issues); use a private security-reporting channel for sensitive vulnerability details.
+
+Official policy references: [Chrome Web Store User Data FAQ](https://developer.chrome.com/docs/webstore/program-policies/user-data-faq), [Chrome Limited Use guidance](https://developer.chrome.com/docs/webstore/user_data), and [Mozilla Add-on Policies](https://extensionworkshop.com/documentation/publish/add-on-policies/).
@@ -0,0 +1,728 @@
+# Yakit Browser Agent 产品与架构路线
+
+> 状态：Phase 1-4 源码、构建、测试与审核产物已完成；仅剩外部账号、签名与商店人工审核
+> 更新时间：2026-07-17
+> 适用仓库：`yaklang-chrome-extension`、Yak `common/browser`/`common/yak/yakurl` 与 Yakit 浏览器集成页
+
+## 0. 2026-07-17 实施快照
+
+本项目尚未正式发布，因此当前重构不承担旧状态、旧消息或旧 Bridge 协议的迁移兼容。破坏性变更直接形成新的生产基线，避免长期保留双字段、双协议和回退分支。
+
+本轮已经落地：
+
+- 状态模型直接切换到 v7；代理、UA、Bridge、面板设置与 grant/Bridge/action session 分域存储，不读取旧聚合 key；
+- content script、嵌入式 floating page、Popup/Options 三类发送者使用不同的标签页绑定策略；
+- Options 顶栏显式选择目标标签页，从 Popup/悬浮面板进入时携带 `tabId`；
+- RequestMap + Valibot 严格校验 extension runtime 消息和 Bridge method params；
+- 授权改为 `targets + origin + scopes + taskId + expiresAt`，跨来源导航后失效；
+- background 状态写入串行化，避免并发 `get -> modify -> set` 丢更新；
+- Bridge v3 使用 `engine challenge -> extension auth -> hello_ack`，以双方 P-256 身份签名绑定 extension Origin、installation、engine、connection、session、task 与 grant；
+- Yak gRPC 默认托管 loopback Bridge；Yakit 复用 `RequestYakURL` 的 `browser-extension://` schema 完成配对窗口、审批、重命名和撤销，没有增加成组 gRPC RPC；
+- Bridge 运行时支持多浏览器同时在线并按 `deviceId` 隔离路由；Yakit 点击设备行可进入能力调用/Yak 脚本工作台，单一 `ExecuteBrowserExtensionTask` 流式 RPC 负责 schema 分发、日志、结果、取消和错误回程；
+- 浏览器 Yak 任务在拥有 Bridge 的 gRPC 进程内执行，请求级注入选中设备的 `browser.ExtensionCall`，并限制脚本体积、并发、超时、单事件和总输出；不再借用会 fork 子进程的通用 Exec Yak 链路；
+- 插件与 Yakit 展示同一六位校验码，审批后自动连接；不再配置、复制或轮换 bearer token，设备撤销会立即断开当前会话；
+- 页面执行抽象为 Chrome User Scripts MAIN、受管 injected MAIN fallback 与 Firefox AMO invoke-only 渠道；
+- 默认 production/store 构建使用 User Scripts，物理移除 `page-main-world.js`；enterprise 使用 User Scripts 优先并保留 injected fallback，dev 与 Firefox MV2 保留 injected bridge；
+- 常驻 content script 从约 480KB 降到 Store 约 10.4 KiB；React 浮动工作台仅在展开时加载；
+- Chrome Store/User Scripts 与 injected bridge 均通过真实 Chromium E2E；
+- 构建预算、商店执行策略和资源暴露策略已经加入自动审计。
+- grant target 已绑定 `tabId + frameId + documentId + origin`，同源刷新返回 `stale_document`，跨来源导航返回 `origin_changed`；
+- Bridge 已支持 cancel、8 请求并发上限、重复 ID 拒绝、16 MiB 收发上限和断线清理；
+- 人工接管具备 `waiting_for_user -> completed/cancelled` 状态、三处 UI 提示和扩展到 Yak 的事件回程；
+- 审计流使用独立 storage key，最多保留 500 条脱敏元数据，Options 提供操作记录视图；
+- Store 与 Enterprise E2E 已覆盖接管完成事件、取消、审计脱敏和 document 边界。
+- 基于 `webRequest` 的 document-bound Fetch/XHR 捕获已经落地，默认只保存有界元数据；请求头、Cookie 和 body 需要显式开启；
+- Options 已提供网络时间线、原始请求检查器和复制功能；
+- 插件与 Yak 已支持双向 request/response，`yakit.web_fuzzer.open` 会保存配置、打开 Yakit Web Fuzzer 并返回 `pageId`；
+- Store E2E 已验证真实 HttpOnly Cookie、请求头、POST body、Agent scope 读取、Web Fuzzer 回执和审计不泄漏。
+- 页面上下文已从最多 500 KiB HTML 改为有界结构化快照，正文摘要上限 20 KiB，可操作节点上限 400；
+- `captureId + documentId + frameId + nodeId` 稳定引用、`browser.node.inspect/action` 和 `stale_node` 已落地；
+- open Shadow DOM 遍历、认证信号、context diff 与登录态工作区已经完成，并通过真实 Chromium 节点写入/点击测试。
+- main/同源/跨源 frame inventory、显式 frame 授权与跨 frame context 已完成；
+- IndexedDB database/store/key 概况、CacheStorage 名称清单和 SPA history/fragment 生命周期已完成，数据库与 Cache 值不会被采集。
+- Fetch/XHR/Form/WebSocket/WebCrypto/CryptoJS 独立 MAIN-world 观测器、敏感值独立 scope、Yak PoC 与无值 AI 分析上下文已完成；
+- Cookie 三格式导入导出、UA 请求头边界、PAC 分流/认证/冲突/统计已完成；
+- Bridge v3 已支持 512 KiB 阈值分片、16 MiB 总上限、心跳延迟、设备签名认证和逻辑 session 恢复；
+- expression/program Eval 独立 scope、Agent session action timeline 与暂停/恢复/撤销已完成；
+- 任务型 Overview、320/390px 导航、站点策略/活动任务/全屏/快捷展开悬浮面板已完成；
+- Native Host 可执行程序、Linux/macOS/Windows 安装器、企业 managed policy、本地指标、脱敏诊断、权限/隐私/Limited Use/商店审核包已完成；
+- Vitest 23 项、四渠道构建审计、Store/Enterprise Chromium E2E、Service Worker 重启验证、Native Messaging v3 真实链路与 Yak Go 确定性包测试已完成。
+
+外部发布动作不属于源码可自动完成的状态：开发者账号、签名证书、稳定隐私政策 URL、Windows/macOS/Linux 真机签名包、Chrome Web Store/AMO 上传、审查往返与批准。执行清单位于 `docs/store-review/RELEASE_CHECKLIST.md`。
+
+## 1. 当前判断
+
+当前版本已经从一年前的实验性浏览器插件演进为可提交审核的生产候选基线：
+
+- WXT、React、Chrome MV3 与 Firefox 构建链路已经建立；
+- Popup、Options 和网页悬浮面板使用统一的品牌与 UI 体系；
+- Yak/Yakit 原始品牌资产已经恢复；
+- 代理、Cookie、User-Agent、页面上下文和 Bridge 已经形成基础能力；
+- Chrome Store User Scripts、Enterprise User Scripts + injected fallback 与 Firefox AMO invoke-only 发布边界已经物理分包；
+- Bridge v3、Yakit 配对控制面、Native Host、task/grant/session 身份和授权有效期已经打通；
+- 只读、表达式 Eval、程序 Eval、敏感网络与观测值分别授权；
+- 扫码、MFA、CAPTCHA 接管和 Agent 暂停/恢复/撤销已经形成可观察状态机；
+- 生产剩余风险已经收敛为外部签名、真机兼容与商店审核，而不是未实现的核心架构。
+
+## 2. 产品北极星
+
+Yakit Browser Agent 不应该被设计成另一个通用浏览器工具箱。
+
+Cookie Editor、UA 修改、编码解码和代理切换都是辅助功能。产品真正有差异化的价值是：
+
+> 将用户真实登录后的浏览器环境，以明确授权、可观察、可暂停、可人工接管、可审计的方式交给 Yakit 和 AI Agent。
+
+所有架构和 UI 决策都应服务于以下主流程：
+
+```text
+用户选择目标标签页
+    -> 创建与 AI task 绑定的授权
+    -> Agent 读取结构化页面和认证上下文
+    -> 捕获请求、签名或加密逻辑
+    -> 发送到 Yakit Fuzzer / Repeater / AI
+    -> 遇到二维码、MFA、CAPTCHA 时请求人工接管
+    -> 用户完成并显式恢复任务
+    -> Agent 获取新上下文并继续
+    -> 授权到期或用户主动撤销
+```
+
+## 3. P0：继续扩展功能前必须处理
+
+### 3.1 请求必须绑定发送者标签页
+
+原实现的 background handler 忽略 `runtime.MessageSender`，content script 发出的 `tab.active`、`context.capture` 等请求会重新查询当前活动标签页。本轮已经完成 sender、frame 与 document 级绑定。
+
+这会造成一个真实风险：后台标签页加载 content script 时，如果用户已经切到另一个标签页，悬浮面板可能显示、授权或采集错误的页面。
+
+目标规则：
+
+```text
+content script 请求
+    -> 默认使用 sender.tab.id + sender.frameId + sender.documentId
+
+popup / options 请求
+    -> 必须显式传 tabId，或由 UI 明确选择 active tab
+
+Bridge 请求
+    -> 必须显式传 tabId，并验证它属于当前 grant
+```
+
+所有页面能力都应接受统一目标：
+
+```ts
+interface BrowserTarget {
+  tabId: number;
+  frameId?: number;
+  documentId?: string;
+}
+```
+
+导航后旧 `documentId` 应返回 `stale_document`，不能静默操作新页面。
+
+### 3.2 授权从两级改为 capability scopes
+
+原有 `read | control` 太粗。当前状态已经保存具体 scope，UI 的“只读/控制”仅作为创建 scope 集合的快捷预设；Eval 表达式与程序已经拆成独立 scope。
+
+建议 scope：
+
+```text
+context.read
+cookies.read
+storage.read
+network.read
+page.invoke
+page.eval.expression
+page.eval.program
+page.interact
+proxy.read
+proxy.write
+human.takeover
+```
+
+授权至少包含：
+
+```ts
+interface BrowserGrant {
+  id: string;
+  taskId: string;
+  agentId?: string;
+  targets: BrowserTarget[];
+  origins: string[];
+  scopes: CapabilityScope[];
+  createdAt: number;
+  expiresAt: number;
+}
+```
+
+`page.eval.program` 应独立授权。首次高风险执行应允许用户预览代码和目标 origin。
+
+### 3.3 消息协议必须运行时校验
+
+TypeScript 类型不会校验来自 runtime、content script、Native Messaging 或 WebSocket 的真实数据。
+
+当前已建立严格 request map：
+
+```ts
+interface RequestMap {
+  'context.eval': {
+    input: EvalRequest;
+    output: PageEvalResult;
+  };
+  'proxy.switch': {
+    input: { id: string };
+    output: ExtensionState;
+  };
+}
+```
+
+配合 Zod、Valibot 或等价 schema 校验：
+
+- Bridge envelope 和 protocol version；
+- `tabId`、`frameId`、`documentId`；
+- Eval 代码长度、模式、超时和并发数量；
+- Cookie URL、domain、path 和 expiration；
+- 代理 host、port、scheme、PAC 数据；
+- loopback WebSocket endpoint、配对状态、双方公钥与签名 envelope；
+- Grant scope、origin、task 和有效期；
+- 单请求和返回值大小。
+
+### 3.4 Storage 避免并发覆盖
+
+原有状态写入为 `get -> modify -> set`，并发写可能丢失更新。当前已经串行化所有跨域 mutation，按代理、UA、Bridge、面板拆分长期 key，并把 grant/handoff、Bridge session、Agent timeline、代理密码/统计放入 session key；审计和本地聚合指标使用独立有界 key。
+
+当前按领域拆 key：
+
+```text
+settings.proxy
+settings.userAgent
+settings.bridge
+ui.floatingPanel
+session.activeGrant
+session.audit
+```
+
+写操作由 background 串行执行。临时会话与长期配置分开存储。
+
+### 3.5 Bridge 必须有正式握手
+
+目标握手：
+
+```text
+engine signed challenge
+    -> extension verifies paired engine identity
+    -> extension signed auth (origin + installation + task/grant)
+    -> engine verifies paired device identity
+    -> hello_ack + protocol/capability negotiation
+    -> ready
+```
+
+在收到 `hello_ack` 之前不能显示“引擎已连接”。
+
+Bridge v3 已具备双方 P-256 身份校验、Origin/installation 绑定、protocol/capability/版本协商、request cancel、8 个并发请求上限、16 MiB 总上限和有界事件回程；超过 512 KiB 的消息按 256 KiB 分片。握手携带 installation/task/grant/resume session，回执携带 engine identity/instance/connection/session 身份；心跳记录序号、时间和延迟。断线中的具体调用明确失败，重连恢复逻辑 task/grant session 身份，不伪装恢复已经中断的调用栈。
+
+## 4. Eval 发布策略
+
+### 4.1 先区分“构建渠道”和“执行机制”
+
+`store`、`enterprise`、`dev` 是三个发布渠道，不是三个完全独立的 JavaScript 语义。
+
+底层执行机制主要有三种：
+
+1. 当前的 injected MAIN-world bridge；
+2. `userScripts.execute({ world: "MAIN" })`；
+3. 仅允许预定义的 `page.invoke` / structured commands。
+
+推荐矩阵：
+
+| 构建渠道 | 首选执行机制 | 备用机制 |
+| --- | --- | --- |
+| Chrome Web Store | User Scripts MAIN | Invoke-only |
+| Enterprise managed | User Scripts MAIN | 受管策略允许的 injected bridge |
+| Local development | Injected MAIN bridge | User Scripts MAIN 对照测试 |
+| Firefox MV3 AMO | Invoke-only / structured commands | 无通用 Eval 回退 |
+| Firefox 本地/受管 | Injected bridge | Invoke-only |
+| Firefox MV2 | Injected bridge | Invoke-only |
+
+### 4.2 三种渠道的使用效果是否完全一样
+
+结论：目标能力可以接近，但不完全一样。
+
+#### A. 当前 injected MAIN-world bridge
+
+执行链路：
+
+```text
+Bridge/background
+    -> isolated content script
+    -> CustomEvent
+    -> packaged page-main-world.js
+    -> indirect eval(code)
+```
+
+优点：
+
+- 可以访问页面真实 `window`、闭包外全局对象和页面函数；
+- 可以等待 Promise；
+- 可以自定义循环对象、DOM Node、BigInt 等序列化；
+- Chrome、现有 Firefox MV2 构建都可使用；
+- 开发时不依赖用户开启 User Scripts 权限。
+
+不足：
+
+- 页面可以观察、修改或干扰 MAIN world 逻辑；
+- 页面可以伪造 CustomEvent 响应；
+- 请求和返回需要自己维护关联、超时、序列化；
+- 同步死循环无法中断；
+- 从 Bridge 获取代码再调用 `eval()` 很可能不符合 Chrome Web Store MV3 政策；
+- 更适合本地开发、自托管或受管环境，不适合作为公开商店版默认机制。
+
+#### B. User Scripts MAIN
+
+执行链路：
+
+```text
+background
+    -> browser.userScripts.execute({
+         target,
+         world: "MAIN",
+         js: [{ code }]
+       })
+    -> browser InjectionResult[]
+```
+
+与当前方案相同或接近的部分：
+
+- `world: "MAIN"` 可以访问页面真实 `window` 和页面全局函数；
+- 可以执行动态代码；
+- 可以指定 tab、frame 或 document；
+- 可以等待 Promise；
+- 可以返回每个 frame 的执行结果；
+- 可以在代码外包一层统一 serializer，保持现有 `PageEvalResult` 格式。
+
+统一语义为：`expression` 自动返回表达式值；`program` 是 async 函数体，必须显式 `return` 才产生返回值，否则为 `undefined`。这避免在 Store MAIN world 内二次调用 `eval`，也让 User Scripts 与 injected fallback 的程序行为一致。
+
+不同点：
+
+- Chrome 需要 `userScripts` permission；
+- Chrome 138+ 用户必须在扩展详情页开启 “Allow User Scripts”；
+- Firefox 技术上提供 `userScripts`，但当前 AMO 政策将其限定为用户脚本管理器；本产品公开 Firefox 包不使用该 API；
+- Chrome 的一次性 `userScripts.execute()` 需要 Chrome 135+；
+- 当前项目 Firefox 输出是 MV2，不能直接复用 Firefox 的新 MV3 User Scripts 路径；
+- Chrome 和 Firefox 的返回值 clone/serialization 细节不同，跨浏览器应主动返回 JSON string 或统一 envelope；
+- MAIN world 依旧能被页面观察和干扰，User Scripts 不是可信执行环境；
+- User Scripts 的 one-shot injection 与当前常驻事件桥生命周期不同。
+
+因此，在支持的浏览器上，以下使用体验可以做到基本一致：
+
+```text
+输入代码
+选择目标标签页/frame
+访问页面 window
+等待 Promise
+得到统一 PageEvalResult
+```
+
+但权限开启流程、版本覆盖、frame result、错误格式和底层生命周期不会完全相同。
+
+特别注意：`world: "USER_SCRIPT"` 不是当前 Eval 的等价替代。它与页面隔离，不能直接读取页面框架、加密库和业务全局变量。Yakit 需要复用页面签名或登录态逻辑时，必须选择 `MAIN`。
+
+#### C. Invoke-only / structured commands
+
+示例：
+
+```text
+page.invoke
+dom.query
+dom.click
+form.fill
+network.findRequest
+storage.get
+```
+
+优点：
+
+- 权限最容易解释；
+- 审计和参数脱敏更容易；
+- 对 AI 更稳定，减少生成任意代码；
+- 更容易通过公开商店审核；
+- 可以对每种能力做明确 schema 和测试。
+
+不足：
+
+- 不能等价替代任意 Eval；
+- 遇到未知框架、混淆代码、临时加密逻辑时能力受限；
+- 需要持续扩充结构化命令。
+
+因此 Invoke-only 应该是 Agent 的首选路径，而不是删除 Eval 后的完全替代。
+
+### 4.3 推荐的统一 Eval API
+
+上层不应知道底层是 User Scripts 还是 injected bridge：
+
+```ts
+interface PageExecutionAdapter {
+  availability(): Promise<ExecutionAvailability>;
+  execute(request: PageExecutionRequest): Promise<PageExecutionResult[]>;
+}
+```
+
+请求：
+
+```ts
+interface PageExecutionRequest {
+  target: BrowserTarget;
+  mode: 'expression' | 'program';
+  code: string;
+  timeoutMs: number;
+  maxResultBytes: number;
+}
+```
+
+Adapter：
+
+```text
+ChromeUserScriptsAdapter
+FirefoxUserScriptsAdapter
+InjectedMainWorldAdapter
+InvokeOnlyAdapter
+```
+
+UI 和 Bridge 始终调用同一个 `page.execute` capability。Adapter 根据构建渠道、浏览器版本、User Scripts 是否开启以及当前 grant 自动选择。
+
+### 4.4 Chrome Web Store 风险
+
+Chrome MV3 政策明确将以下行为列为常见违规：
+
+- 使用 `eval()` 执行从远程来源获得的字符串；
+- 构建解释器执行从远程来源获得的复杂命令；
+- 让扩展完整功能无法从提交代码中被审核者理解。
+
+政策明确列出的远程逻辑执行豁免 API 是：
+
+- Debugger API；
+- User Scripts API。
+
+官方资料：
+
+- [Additional Requirements for Manifest V3](https://developer.chrome.com/docs/webstore/program-policies/mv3-requirements)
+- [chrome.userScripts](https://developer.chrome.com/docs/extensions/reference/api/userScripts)
+- [Enabling chrome.userScripts is changing](https://developer.chrome.com/blog/chrome-userscript)
+- [MDN userScripts](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts)
+- [MDN userScripts.execute](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts/execute)
+
+源码预审、实际 Store 包审计、隐私/Limited Use/权限说明和 reviewer test packet 已完成；正式批准仍必须通过 Chrome Web Store 开发者账号上传和人工审核，不能由本地测试替代。
+
+## 5. Page Context 目标模型
+
+页面上下文已经从“一次返回完整 HTML”切换为有界结构化快照，并完成 frame 与浏览器存储 inventory。
+
+建议层次：
+
+```text
+Page summary
+Accessibility/DOM action tree
+Forms and actionable elements
+Frames and shadow roots
+Authentication signals
+Storage inventory
+Network request summary
+Crypto/signing observations
+Relevant excerpts on demand
+```
+
+必须补齐：
+
+- [已完成] main frame、同源 frame、跨源 frame 清单；
+- [已完成] `frameId`、`documentId` 和 origin；
+- [已完成] open Shadow Root 遍历；
+- [已完成] IndexedDB database/store/key 概况；
+- [已完成] CacheStorage 概况；
+- [已完成] SPA route 和 document 生命周期；
+- [已完成] 页面登录状态信号；
+- [已完成] 结构化可操作元素引用；
+- [已完成] context diff，而不是每次返回完整快照。
+
+元素引用建议：
+
+```text
+captureId + documentId + frameId + nodeId
+```
+
+页面变化后返回 `stale_node`，不能退化为可能误命中的 CSS selector。
+
+## 6. 高价值产品功能
+
+### 6.1 浏览器请求到 Yakit 工作流
+
+浏览器请求到 Yakit 的生产链路已经闭环：`webRequest` 捕获 Fetch/XHR/Form navigation，用户显式开启敏感字段后生成 HTTP/1.1 重放包，并通过带回执的 Bridge 在 Yakit 中打开 Web Fuzzer、生成可运行 Yak PoC，或生成不含认证值的 AI 分析上下文。AI Agent 可结合附近的 WebCrypto/CryptoJS/WebSocket 观测分析鉴权、签名、重放和对象级越权风险。
+
+优先完成：
+
+```text
+捕获 fetch / XHR / form 请求
+    -> 发送到 Web Fuzzer
+    -> 发送到 Repeater
+    -> 生成 Yak PoC
+    -> 交给 AI 分析鉴权、签名和越权风险
+```
+
+这是浏览器插件与 Yakit 结合最直接的产品价值。
+
+### 6.2 前端加密与签名观测
+
+在明确授权期间临时观测：
+
+- `fetch` / XHR；
+- WebSocket；
+- `crypto.subtle`；
+- 常见 CryptoJS；
+- 请求签名前后的字段；
+- 调用栈和脚本来源。
+
+上述能力已经通过独立 WXT MAIN-world entrypoint 落地。观测器使用最多 200 条的有界 ring buffer，默认只记录算法、方向、大小、调用栈和脚本来源；短时值预览需要独立敏感 scope，授权到期、撤销或用户停止时恢复原始页面 API 并销毁预览。
+
+### 6.3 登录态工作区
+
+建立可见 session：
+
+```text
+目标 origin
+关联标签页
+账号线索
+Cookie/Storage 概况
+CSRF/token 来源
+当前代理环境
+共享给哪个 Agent/task
+授权和过期时间
+最近上下文变化
+```
+
+默认不导出原始认证值。快照导出必须显式确认并支持脱敏。
+
+### 6.4 人机接管状态机
+
+当前已经完成可运行闭环：Agent 创建 `browser.handoff.request`，插件在目标标签页、Popup 和 Options 显示 `waiting_for_user`，用户完成或取消后发送 `browser.handoff.changed`，Yak 通过 `ExtensionWaitEvent` 消费；独立 Agent runtime 同时记录 running/paused/revoked 与有界 action timeline。
+
+目标状态：
+
+```text
+agent_running
+needs_human
+waiting_for_human
+human_resumed
+agent_resuming
+completed / cancelled / expired
+```
+
+流程：
+
+1. Agent 说明需要扫码、MFA、CAPTCHA 或设备确认的原因；
+2. 扩展聚焦目标标签页并显示任务；
+3. Agent 停止读取敏感内容和重复轮询；
+4. 用户完成操作并点击“已完成”；
+5. 扩展发送 `human_resumed`；
+6. Agent 获取新 context diff 并继续。
+
+## 7. 现有工具完善方向
+
+### Cookie Editor
+
+- [已完成] 搜索、排序和过滤；
+- [已完成] 批量删除；
+- [已完成] 编辑现有 Cookie；
+- [已完成] JSON/Netscape/Raw Set-Cookie 有界导入导出，默认脱敏，原始值导出需显式开启；
+- [已完成] Partitioned Cookie；
+- [已完成] SameSite 与过期时间；Priority/SameParty 可在交换格式中识别和展示，浏览器 Cookies API 无法写回时返回明确 warning；
+- [已完成] 按 domain/path 分组；
+- [已完成] 默认隐藏 value，点击后显示。
+
+### User-Agent 与设备身份
+
+当前产品明确选择第一种边界：UI 已命名为 “User-Agent 请求头”，只承诺通过 DNR 修改真实网络请求头，不暗示页面 JS、timezone、viewport、touch 或 geolocation 已被完整伪装。
+
+完整设备指纹伪装不属于当前插件承诺；如果未来引入，必须作为独立能力重新设计 scope、页面注入生命周期和浏览器兼容测试，不能与单一 UA header 规则混为一谈。
+
+### 代理规则
+
+- [已完成] 优先级与拖动排序；
+- [已完成] 冲突检测；
+- [已完成] 当前 URL 命中预览；
+- [已完成] PAC 编译结果查看；
+- [已完成] 代理认证，用户名持久化、密码仅保存在浏览器 session；
+- [已完成] JSON 导入导出，不包含代理密码；
+- [已完成] 默认出口和 fail-open/fail-closed 行为；
+- [已完成] 规则命中统计。
+
+## 8. UI/UX 改进
+
+### 8.1 字号
+
+已清除 8px/9px 字号；正文、辅助说明、表格和技术元数据按下面基线执行，并由 320/390/桌面截图验证。
+
+目标：
+
+- 工作台正文不低于 12px；
+- 辅助说明不低于 11px；
+- 表格正文 12px；
+- tag、时间戳、技术元数据最低 10px；
+- 不再使用 8px。
+
+### 8.2 Overview 改为当前任务工作台
+
+Overview 已改为任务工作台，第一屏展示：
+
+```text
+当前站点与登录环境
+当前代理和流量状态
+正在共享给哪个 Agent
+Agent 最近动作
+需要用户完成的步骤
+抓请求 / 采集上下文 / 发送 Fuzzer
+```
+
+### 8.3 移动和窄视口导航
+
+窄视口使用不换行的横向滚动导航；320px 与 390px E2E 检查 document overflow 和导航标签换行。
+
+### 8.4 悬浮面板
+
+已完成：
+
+- 当前站点单独隐藏；
+- allowlist/denylist；
+- 仅在活动 task 中显示；
+- 快捷键展开；
+- 页面全屏、演示、视频场景自动收起；
+- 与网页边缘控件冲突时调整位置；
+- 显示当前 task 和授权风险，而不仅是代理状态。
+
+## 9. 目标代码目录
+
+```text
+src/
+  app/background/
+    index.ts
+  entrypoints/
+    background.ts
+    popup/
+    options/
+    agent.content/
+    page-main-world.ts
+
+  features/
+    proxy/
+    cookies/
+    identity/
+    page-context/
+    page-observation/
+    network-capture/
+    grants/
+    handoff/
+    diagnostics/
+    agent-runtime/
+    engine-bridge/
+    floating-panel/
+
+  platform/
+    browser/
+    storage/
+    messaging/
+    policy/
+
+  protocol/
+  components/ui/
+  components/brand/
+  shared/errors.ts
+```
+
+原则：
+
+- WXT background entrypoint 只负责注册并调用 `app/background`；
+- 每个高风险 feature 拥有 service，纯编译器/交换器与测试放在 feature 内；
+- browser API 通过 platform adapter 隔离；
+- background 应用 router 只编排 domain service，不在 entrypoint 内实现浏览器业务；
+- UI、Bridge 和测试共享同一份协议 schema。
+
+## 10. 测试策略
+
+### 单元测试
+
+- [已完成] PAC compiler、URL pattern 和冲突优先级；
+- [已完成] 无迁移 clean bootstrap、storage 分域和并发写；
+- [已完成] Bridge envelope、extension RequestMap 与 managed policy validation；
+- [已完成] Grant scope/策略判断与 expression/program Eval serializer；
+- [已完成] Cookie URL/脱敏交换与 UA DNR 规则生成。
+
+### 协议测试
+
+- [已完成] pairing code、engine challenge、extension auth、hello_ack、身份字段和 protocol version mismatch；
+- [已完成] read/program scope、origin/tab/frame/document 越权；
+- [已完成] timeout/cancel、并发、重复 ID、payload 上限与双向 chunk；
+- [已完成] 设备审批/撤销、断线 session 恢复、task 到期/撤销与 Native Host framing；
+- [已完成] Chromium `connectNative` -> Go Host -> loopback Yak Bridge -> Bridge v3 challenge/auth/identity/heartbeat 的真实端到端验证（生产包仍为 optional permission，只有不可交互的临时测试副本预授权）。
+
+### 浏览器 E2E
+
+- [已完成] Chrome Store/User Scripts 与 Enterprise User Scripts + injected fallback 模式；
+- [已完成] Firefox MV2 injected 与 Firefox MV3 AMO invoke-only 构建/静态策略审计；
+- [已完成] CSP 严格页面、SPA、同源/跨源 iframe 与 open Shadow DOM；
+- [已完成] 页面伪造消息不扩权、Service Worker 停启保留 session、标签页关闭/导航 Eval fail-closed；
+- [已完成] 320px、390px 和桌面视口 UI、面板边界与资源像素/加载检查。
+
+当前容器没有 Firefox 可执行程序或 macOS/Windows 环境；Firefox 真机安装、AMO 签名包和三平台 Native Host 签名属于 `RELEASE_CHECKLIST.md` 的外部发布门禁，不能用 Chromium 模拟结果冒充通过。
+
+## 11. 分阶段落地
+
+### Phase 1：安全与架构基线
+
+- [已完成] sender tab/frame/document 绑定与 stale-document；
+- [已完成] RequestMap 和运行时 schema；
+- [已完成] Storage 分域、session/local 生命周期与串行写；
+- [已完成] capability scopes 与 origin 绑定；
+- [已完成] Bridge hello_ack 和版本协商；
+- [已完成] Store/enterprise/dev 构建渠道；
+- [已完成] PageExecutionAdapter；
+- [已完成] Chrome User Scripts MAIN，并通过浏览器 E2E。
+
+### Phase 2：核心产品闭环
+
+- [已完成] Fetch/XHR request capture；
+- [已完成] 发送 Yakit Web Fuzzer/Repeater 工作区；
+- [已完成] task-bound grant；
+- [已完成] human handoff 状态机；
+- [已完成] context diff；
+- [已完成] Agent action timeline、暂停/恢复/撤销与脱敏持久审计。
+
+### Phase 3：浏览器现场深度
+
+- [已完成] frame/document/node 引用与显式跨 frame 授权；
+- [已完成] open Shadow DOM；
+- [已完成] IndexedDB/CacheStorage inventory；
+- [已完成] Fetch/XHR/Form/WebSocket/WebCrypto/CryptoJS 有界观测与独立敏感 scope；
+- [已完成] 登录态工作区；
+- [已完成] Cookie、UA 请求头边界和代理规则完善。
+
+### Phase 4：分发与运营
+
+- [已完成] Native Host 可执行程序、framing proxy、Chrome/Firefox argv 来源校验、Linux/macOS/Windows 安装器与 Chromium 真实传输 E2E；
+- [已完成] managed storage schema、后台强制企业策略与 UI 锁定状态；
+- [已完成] Chrome Store 实包自动预审和 reviewer packet；实际上传/批准为外部门禁；
+- [已完成] Firefox MV3 AMO invoke-only 实包与 review packet；真机/签名/批准为外部门禁；
+- [已完成] 权限说明、隐私政策和 Limited Use 披露；
+- [已完成] 脱敏审计、session action timeline 与显式诊断导出；
+- [已完成] Service Worker 启动、Bridge 连接错误、心跳延迟和 capability 聚合指标（仅本地，不远传）。
+
+## 12. 验收原则
+
+正式产品版本至少满足：
+
+- 不会因 active tab 切换而操作错误页面；
+- 每个高风险能力都能追溯到 user、task、grant、target 和 scope；
+- 页面不能通过伪造普通消息扩展自己的权限；
+- Store build 不通过通用 `eval(remoteCode)` 执行 Bridge 代码；
+- User Scripts 未开启时给出明确降级和开启路径；
+- Agent 默认使用 structured commands，Eval 是最后手段；
+- 用户能看见、暂停、恢复和撤销 Agent 对浏览器的操作；
+- 默认不记录或导出 Cookie、token、Eval 参数和页面正文；
+- Chrome Store、Enterprise User Scripts 与 Enterprise injected fallback 关键路径有真实 Chromium E2E；Firefox 真机安装/运行是发布前外部门禁，不能由 Chromium 或静态审计替代；
+- Native Host 与 Yakit 实例身份、版本和连接状态可信。
@@ -0,0 +1,43 @@
+# Chrome Web Store Review Packet
+
+## Single purpose
+
+Yakit Browser Agent provides consent-gated browser context and request workflows for authorized security testing with a local Yak/Yakit engine. Cookie, proxy, UA, observation and request tools support that single authenticated-browser testing workflow; they do not provide unrelated browsing, advertising or content features.
+
+## Remote code policy
+
+The Store build is produced by `pnpm build:store`.
+
+- It requires Chrome 138+ and uses the documented `userScripts.execute({ world: "MAIN" })` path.
+- `page-main-world.js` is absent from the package and web-accessible resources.
+- Expression and program Eval use independent grant scopes; program mode is not in the default control preset.
+- If Allow User Scripts is disabled, the UI reports the condition and does not fall back to injected Eval.
+- Page results are untrusted and bounded. Structured context/node commands are preferred.
+
+Chrome's MV3 policy names User Scripts as an API permitted to execute remote logic when used for its documented purpose: [Additional Requirements for Manifest V3](https://developer.chrome.com/docs/webstore/program-policies/mv3-requirements).
+
+## User data and Limited Use
+
+The listing and privacy form must disclose authentication information, browsing activity, website content, Cookie/storage data, request data and local Native Messaging transmission. Data is handled only for the user-facing security workflow, sent only to the user's explicit local endpoint, never sold, never used for advertising, and not sent to developer analytics. Local processing still requires disclosure under the [User Data FAQ](https://developer.chrome.com/docs/webstore/program-policies/user-data-faq).
+
+## Reviewer test
+
+1. Build with `pnpm build:store` and load `.output/chrome-mv3-store`.
+2. Enable Allow User Scripts on the extension details page.
+3. Open an HTTP(S) page, Options, and select the target tab.
+4. Create a five-minute read grant and verify context succeeds but Eval is denied.
+5. Create a control grant. Expression Eval succeeds; program Eval remains denied until separately enabled.
+6. Start metadata-only request capture. Headers/body appear only after their explicit switches are enabled.
+7. Trigger and complete a handoff; verify the action timeline and audit contain metadata only.
+8. Inspect the Store artifact: no `page-main-world.js`, no `activeTab`, and `nativeMessaging` is optional.
+
+Automated equivalent: `pnpm verify:ui:store`.
+
+## Submission fields still requiring owner action
+
+- Developer account ownership and verified contact details.
+- Stable privacy-policy URL hosting `docs/PRIVACY_POLICY.md`.
+- Final signed extension ID for Native Host allowlisting.
+- Store screenshots/promotional assets selected from `.artifacts/ui`.
+- Privacy questionnaire answers matching this packet.
+- Actual upload, reviewer correspondence and approval.
@@ -0,0 +1,13 @@
+# Firefox AMO Review Packet
+
+The public Firefox artifact is `pnpm build:firefox:amo`, producing Firefox MV3 in `.output/firefox-mv3-store`.
+
+Mozilla's current Add-on Policies reserve `userScripts` for user-script managers. Yakit Browser Agent is not marketed as one, so the AMO artifact does not request `userScripts`, does not package `page-main-world.js`, and does not advertise `browser.invoke` or `browser.eval`. It retains structured context, document-bound node commands, request capture, observation, Cookie/UA/proxy tools and human handoff. Local or enterprise Firefox builds can use the injected adapter outside the public AMO channel.
+
+The manifest targets Firefox 140+ and declares required built-in data consent categories: authentication information, browsing activity, website activity and website content. There is no remote technical/user-interaction telemetry; operational metrics stay local until the user exports a diagnostics file.
+
+Official references: [Mozilla Add-on Policies](https://extensionworkshop.com/documentation/publish/add-on-policies/) and [Firefox built-in data consent](https://extensionworkshop.com/documentation/develop/firefox-builtin-data-consent/).
+
+Reviewer steps mirror the Chrome structured-command flow but must confirm that no function-call/Eval tabs or Bridge capabilities are present. Native Messaging remains optional and any data sent to the local host remains subject to the same disclosure and user controls.
+
+Owner-only remaining work: AMO account, signed submission, source-code archive if requested, hosted privacy URL, reviewer correspondence and approval.
@@ -0,0 +1,14 @@
+# Limited Use Disclosure
+
+Yakit Browser Agent handles browsing activity, website content, authentication information, Cookie/browser-storage data and selected network request data only to provide its prominently disclosed authenticated-browser security-testing features.
+
+The extension's use of this data complies with the following commitments:
+
+- Data is used only to display browser context to the user, execute the user's bounded security workflow, or transmit an explicitly granted operation to the user's local Yak/Yakit engine.
+- Data is not sold or transferred for advertising, marketing, creditworthiness, lending, or unrelated profiling.
+- Humans do not read user data except when the user deliberately includes a redacted diagnostic artifact in a support request, or when required for security, abuse prevention or law.
+- There is no developer-operated telemetry endpoint. Aggregate operational metrics remain on device.
+- Sensitive request fields and observation values are off by default. Cookie exports are redacted by default. Program Eval has a separate high-risk scope.
+- The local Native Host receives only the same purpose-bound messages the user authorized; it is not an independent data collector.
+
+Store privacy-form answers, listing text and the hosted privacy policy must remain consistent with this disclosure and actual packaged behavior. See the [Chrome Limited Use guidance](https://developer.chrome.com/docs/webstore/user_data) and [Mozilla Add-on Policies](https://extensionworkshop.com/documentation/publish/add-on-policies/).
@@ -0,0 +1,28 @@
+# Release Checklist
+
+## Automated gates
+
+- `pnpm verify:production`
+- `pnpm verify:ui:store`
+- `pnpm verify:ui:enterprise`
+- `pnpm verify:ui:enterprise:fallback`
+- `pnpm verify:native` (real Chromium -> Native Host -> Yak Bridge transport; temporary test copy pre-grants the otherwise optional browser permission)
+- `go test ./common/browser/... ./common/ai/aid/aitool/buildinaitools/yakscripttools` in Yak
+- Store package has no injected Eval bridge.
+- Firefox AMO package has no `page-main-world.js`, `userScripts`, `browser.invoke` or `browser.eval` capability.
+- Required permissions match `docs/PERMISSIONS.md`; Native Messaging is optional.
+- Windows manifests are written as UTF-8 without BOM and Chrome, Chromium, Edge, Brave and Firefox registrations are per-user.
+- Diagnostic and audit fixtures contain no secrets, URLs, request payloads or Eval source.
+
+## Human gates
+
+- Review listing text, screenshots and single-purpose statement.
+- Host and link the privacy policy.
+- Complete Chrome privacy/Limited Use and Firefox data consent declarations.
+- Build/sign Native Host binaries for Windows, macOS and Linux; scan and publish checksums.
+- Replace unpacked extension IDs in Native Host manifests with signed IDs.
+- Test current stable Chrome, Firefox, Windows, macOS and Linux packages on real machines.
+- Run `go test ./common/ai/aid/aitool/buildinaitools/...` against a seeded, writable Yakit profile database; the recursive integration package expects existing built-in tools and is not a clean-profile unit test.
+- Submit to Chrome Web Store and AMO, answer reviewer questions, and record approval/version IDs.
+
+The human gates require external accounts, signing keys, store systems and operating systems. They cannot be truthfully marked approved from a source workspace; the repository contains the implementation and reviewer artifacts needed to execute them.