mirror of
https://github.com/yaklang/yaklang-chrome-extension.git
synced 2026-09-26 05:01:53 +08:00
Enhance architecture documentation and update project dependencies. Introduce new features for browser recording, page callables, and transform capabilities. Improve build scripts and permissions for better functionality.
This commit is contained in:
go0p
@@ -0,0 +1,589 @@
|
||||
# Browser Profile 自动推断与 AI 协作架构
|
||||
|
||||
## 1. 产品决定
|
||||
|
||||
自动推断 Profile 不是明文网关的辅助功能，而是浏览器现场的默认完成路径。
|
||||
|
||||
用户不应先理解混淆变量、复制密钥、编写包装函数，再手工配置参数路径和输出映射。正常流程必须从一次真实业务操作开始：
|
||||
|
||||
```text
|
||||
用户执行登录 / 查询 / 提交
|
||||
-> Recorder 生成有界业务 Trace
|
||||
-> 确定性推断器关联明文点、页面调用和请求字段
|
||||
-> 已知模式直接生成候选
|
||||
-> 未知模式请求 AI 解释业务帧和参数语义
|
||||
-> 必要时引导用户再执行一次操作以捕获业务闭包
|
||||
-> 编译为文档绑定的 Profile
|
||||
-> 使用录制样本做页面内回放校验
|
||||
```
|
||||
|
||||
手写 JavaScript 保留为高级模式，不再作为主流程或文档中的首选方案。
|
||||
|
||||
本设计不包含“发送真实 HTTP 请求验证”。真实请求仍由 Yak / Web Fuzzer 的既有数据面负责。本阶段只负责发现、推断、捕获、编译和页面内样本校验。
|
||||
|
||||
## 2. 用户结果
|
||||
|
||||
以一次 CryptoJS 调用为例，默认界面应展示：
|
||||
|
||||
```text
|
||||
已识别请求转换
|
||||
|
||||
POST /api/login
|
||||
JSON 明文 -> CryptoJS.AES.encrypt -> body.encryptedData
|
||||
|
||||
输入 argument 0 <- 请求明文 JSON
|
||||
Key argument 1 <- 页面内 WordArray · 16 B
|
||||
IV options.iv <- 页面内 WordArray · 16 B
|
||||
模式 CBC / Pkcs7
|
||||
输出 toString -> URL encode -> encryptedData
|
||||
|
||||
证据 4 项 · 高置信度
|
||||
[生成 Profile]
|
||||
```
|
||||
|
||||
`_0x67b862` 一类混淆名称只能出现在折叠的原始证据中。主界面使用 `Key`、`IV`、`明文输入`、`请求字段` 等语义角色。
|
||||
|
||||
用户应能回答三个问题：
|
||||
|
||||
1. 插件为什么认为这是加密链路；
|
||||
2. 哪些结论是确定事实，哪些是推测；
|
||||
3. 还需要用户执行什么操作才能完成 Profile。
|
||||
|
||||
## 3. 设计原则
|
||||
|
||||
### 3.1 证据先于 AI
|
||||
|
||||
指纹相等、请求字段解析、调用顺序、运行时对象类型和调用栈属于确定性证据。AI 不重复判断这些事实，只消费其结构化结果。
|
||||
|
||||
### 3.2 AI 不能成为执行边界
|
||||
|
||||
AI 可以：
|
||||
|
||||
- 给业务 frame 排序；
|
||||
- 将参数标注为 payload、key、iv、nonce、timestamp 或 signature；
|
||||
- 从有限源码片段中解释序列化和包装步骤；
|
||||
- 在多个候选之间给出理由；
|
||||
- 建议下一次捕获点。
|
||||
|
||||
AI 不可以：
|
||||
|
||||
- 直接提交任意 JavaScript 作为生产 Profile；
|
||||
- 引用不存在的事件、frame、参数或页面函数；
|
||||
- 读取或输出 key、Cookie、token、密码等原始值；
|
||||
- 绕过 grant、document、origin 或人工接管状态；
|
||||
- 将猜测标记为已经验证的事实。
|
||||
|
||||
### 3.3 页面是执行环境，不是密钥导出器
|
||||
|
||||
Key、IV、CryptoKey、key promise、WASM 实例和闭包变量继续保留在原页面。Profile 只保存页面内 opaque callable 引用和经过校验的参数映射。
|
||||
|
||||
### 3.4 已知模式不依赖 AI，未知模式不依赖库清单
|
||||
|
||||
WebCrypto、CryptoJS、JSEncrypt 以及后续 sm-crypto、node-forge 等已知模式，连同 URLSearchParams、JSON、FormData 和常见编码链，应优先由确定性规则推断。AI 只处理业务语义和未知代码，避免增加延迟、成本和不确定性。
|
||||
|
||||
录制协议只暴露统一的 `crypto` 事件，库差异进入结构化 `adapterId / providerKind / family / operation / algorithm / mode / padding / encoding / state / key metadata`。推断器、时间线、Deep Capture 和 Agent 不再分别判断 `webcrypto`、`cryptojs` 等事件类型。新增密码库时只扩展 MAIN-world adapter、扩展自带的 manifest 和受限元数据归一化器，不扩展整条产品协议。
|
||||
|
||||
已知 adapter 只负责提供更准确的参数角色、算法和状态语义，不是通用性的唯一来源。对于 ESM/Webpack 闭包、Worker、WASM 或完全未知的业务封装，系统必须从请求/消息边界和调用栈恢复上层业务 callable；算法尚未命名不能单独成为 `insufficient-evidence`。adapter 协议的开放化、Worker/MessagePort 边界、高价值库优先级与反靶场特化验收见 [`FRONTEND_CRYPTO_GENERALIZATION_ROADMAP.md`](FRONTEND_CRYPTO_GENERALIZATION_ROADMAP.md)。
|
||||
|
||||
### 3.5 无兼容负担
|
||||
|
||||
插件尚未正式投入使用。页面配方、运行时适配器和 Transform Profile 可以直接收敛到新模型，不保留旧数据迁移或双写逻辑。
|
||||
|
||||
## 4. 总体架构
|
||||
|
||||
```text
|
||||
MAIN-world Recorder
|
||||
| bounded events + opaque handles + semantic argument metadata
|
||||
v
|
||||
Evidence Normalizer
|
||||
| request fields / call slots / encodings / exact & normalized links
|
||||
v
|
||||
Evidence Graph
|
||||
| proven edges + supported edges + hypotheses
|
||||
+-----------------------+
|
||||
| |
|
||||
v v
|
||||
Deterministic Inference AI Analysis
|
||||
| known patterns | frame ranking / semantic labels / unknown code
|
||||
+-----------+-------------+
|
||||
v
|
||||
Candidate Merger
|
||||
| schema validation + evidence reference validation
|
||||
v
|
||||
Pipeline Compiler v2
|
||||
| page callable graph, no arbitrary generated code
|
||||
v
|
||||
Local Sample Replay
|
||||
| deterministic compare or structural assertions
|
||||
v
|
||||
Document-bound Profile
|
||||
```
|
||||
|
||||
推断计算在扩展后台完成。Yakit、Options 和 AI Agent 读取同一候选结构，不各自实现一套启发式规则。
|
||||
|
||||
## 5. Evidence Graph
|
||||
|
||||
### 5.1 节点
|
||||
|
||||
```ts
|
||||
type EvidenceNode =
|
||||
| RecordingEventNode
|
||||
| RecordedValueNode
|
||||
| RequestFieldNode
|
||||
| CallableNode
|
||||
| CallArgumentNode
|
||||
| StackFrameNode
|
||||
| SourceExcerptNode
|
||||
```
|
||||
|
||||
节点只使用录制会话内稳定 ID。原始敏感值不是图节点属性。
|
||||
|
||||
### 5.2 边
|
||||
|
||||
```ts
|
||||
type EvidenceStrength = "proven" | "supported" | "hypothesis"
|
||||
|
||||
type EvidenceEdgeKind =
|
||||
| "exact-value"
|
||||
| "normalized-value"
|
||||
| "parent-call"
|
||||
| "same-trace"
|
||||
| "stack-frame"
|
||||
| "argument-role"
|
||||
| "request-destination"
|
||||
```
|
||||
|
||||
- `exact-value`：同一录制盐下的指纹完全相同；
|
||||
- `normalized-value`：经过有界白名单转换后相同，例如 URL decode、JSON field extraction 或 Base64 表示；
|
||||
- `parent-call`：Recorder 的同步父调用关系；
|
||||
- `same-trace`：弱证据，只证明时间和用户操作相关；
|
||||
- `hypothesis`：只能由 AI 或启发式产生，必须列出依据。
|
||||
|
||||
### 5.3 请求边界归一化
|
||||
|
||||
网络事件在边界处解析，不全局 Hook `JSON.stringify` 或 `encodeURIComponent`：
|
||||
|
||||
- JSON：递归提取最多 64 层、100,000 节点；
|
||||
- `application/x-www-form-urlencoded`：字段级 URL decode；
|
||||
- `FormData`：字段名、字符串值和文件元数据；
|
||||
- Headers：规范化名称但保留原始大小写用于展示；
|
||||
- Query：字段级解析；
|
||||
- 原始 body：保留整体指纹和类型。
|
||||
|
||||
归一化候选只允许白名单操作并设置总预算。不得对每个值进行无界编码组合爆炸。
|
||||
|
||||
### 5.4 参数语义
|
||||
|
||||
Recorder 对已知库记录参数角色而不是变量名：
|
||||
|
||||
```ts
|
||||
interface CallArgumentEvidence {
|
||||
index: number
|
||||
role: "data" | "key" | "iv" | "algorithm" | "options" | "signature" |
|
||||
"salt" | "nonce" | "aad" | "unknown"
|
||||
dataType: string
|
||||
byteLength?: number
|
||||
replaceable: boolean
|
||||
retained: boolean
|
||||
summary?: string
|
||||
}
|
||||
```
|
||||
|
||||
例如 CryptoJS AES：
|
||||
|
||||
- `argument 0`：data，可替换；
|
||||
- `argument 1`：key，不导出，页面内保留；
|
||||
- `argument 2`：options，提取 mode、padding 和 IV 长度，不提取 IV 值。
|
||||
|
||||
例如 JSEncrypt RSA：
|
||||
|
||||
- `argument 0`：UTF-8 data，可替换；对象输入按稳定 JSON 序列化后再交给原函数；
|
||||
- receiver：保留实际 JSEncrypt 实例，不重建、不导出；
|
||||
- key：只记录 public/private、模数位数和本次录制随机加盐的指纹；
|
||||
- padding：记录 `PKCS1-v1_5` 等可解释元数据；
|
||||
- output：记录 Base64 形态并与 JSON/Form/Header/Query 请求字段做 exact link；
|
||||
- 公私钥 PEM、模数、指数和页面实例永不进入候选或 AI 上下文。
|
||||
|
||||
如果一次 RSA 输出精确进入一个请求字段，且原函数、receiver 和参数模板仍在当前 document 中，候选可以直接进入 `ready`，不要求用户填写函数表达式或先进入 Deep Capture。
|
||||
|
||||
## 6. 统一 Page Callable
|
||||
|
||||
当前页面配方和深度捕获适配器表达的是同一概念：在当前文档中可重复调用的页面函数。两套注册表应合并为 `BrowserPageCallable`。
|
||||
|
||||
```ts
|
||||
interface BrowserPageCallable {
|
||||
id: string
|
||||
kind: "recorded-call" | "business-closure" | "global-function"
|
||||
name: string
|
||||
target: BrowserTarget
|
||||
lifecycle: "document"
|
||||
inputSlots: CallableInputSlot[]
|
||||
output: CallableOutputShape
|
||||
provenance: {
|
||||
recordingId?: string
|
||||
traceId?: string
|
||||
eventId?: string
|
||||
frameId?: string
|
||||
sourceUrl?: string
|
||||
lineNumber?: number
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`recorded-call` 保存原函数、receiver、固定参数模板和可替换槽位；`business-closure` 保存 CDP 暂停时捕获的业务函数与闭包；两者使用同一执行、授权、生命周期和审计接口。
|
||||
|
||||
Profile 不再引用 `recipeId` 或 `adapterId`，只引用 `callableId`。
|
||||
|
||||
## 7. Pipeline v2
|
||||
|
||||
手工 JavaScript 中常见的 JSON 序列化、编码、调用和封装应变成可审计的类型化节点：
|
||||
|
||||
```ts
|
||||
type PipelineNode =
|
||||
| { kind: "context.read"; path: string }
|
||||
| { kind: "builtin"; operation: BuiltinOperation; inputs: NodeRef[]; options?: object }
|
||||
| { kind: "page.call"; callableId: string; arguments: NodeRef[] }
|
||||
| { kind: "output.write"; destination: string; source: NodeRef; encoding: ValueEncoding }
|
||||
```
|
||||
|
||||
首批 `BuiltinOperation`：
|
||||
|
||||
```text
|
||||
value.literal
|
||||
json.stringify
|
||||
json.parse
|
||||
text.toString
|
||||
url.encode
|
||||
url.decode
|
||||
base64.encode
|
||||
base64.decode
|
||||
hex.encode
|
||||
hex.decode
|
||||
object.pick
|
||||
object.compose
|
||||
form.compose
|
||||
```
|
||||
|
||||
`value.literal` 只允许字符串、数字、布尔值或 `null`，用于编译器生成固定的协议元数据，例如表单
|
||||
`Content-Type`。它不接受输入，也不能持有函数、对象或页面秘密。
|
||||
|
||||
每个节点有明确输入输出类型和大小预算。未知操作不能通过 AI 临时创造；用户确实需要自定义代码时，进入独立的高级节点，并沿用程序 Eval 的高风险授权。
|
||||
|
||||
## 8. 推断候选
|
||||
|
||||
候选不是立即生效的 Profile：
|
||||
|
||||
```ts
|
||||
interface BrowserProfileInferenceCandidate {
|
||||
id: string
|
||||
recordingId: string
|
||||
traceId: string
|
||||
target: BrowserTarget
|
||||
request: { eventId: string; method: string; url: string }
|
||||
direction: "request" | "response"
|
||||
status: "ready" | "capture-required" | "mapping-required" | "insufficient-evidence"
|
||||
confidence: { score: number; level: "high" | "medium" | "low" }
|
||||
summary: string
|
||||
pipeline: PipelineNodeDraft[]
|
||||
evidence: InferenceEvidenceRef[]
|
||||
missing: InferenceMissingStep[]
|
||||
aiContext: BrowserInferenceAIContext
|
||||
}
|
||||
```
|
||||
|
||||
置信度不是 AI 的主观百分比。分数由固定规则产生，并在 UI 中解释：
|
||||
|
||||
- 请求字段与加密输出 exact link：强加分；
|
||||
- 可重复 callable 已保留：强加分；
|
||||
- 同一用户 Trace 且顺序正确：中等加分；
|
||||
- 仅时间接近：弱加分；
|
||||
- 多个同分候选：降分；
|
||||
- 缺少输入映射或输出封装：状态不能为 ready。
|
||||
|
||||
## 9. 自动业务函数捕获
|
||||
|
||||
低层 `CryptoJS.AES.encrypt` 或 `crypto.subtle.encrypt` 往往不足以构造完整线上报文。推断器应把它作为断点入口，然后寻找上层业务函数。
|
||||
|
||||
```text
|
||||
候选指出需要业务 callable
|
||||
-> 用户点击“自动捕获完整加密流程”
|
||||
-> 插件在已知低层调用处 arm 一次性断点
|
||||
-> 用户重复相同操作
|
||||
-> 页面暂停并立即显示控制面
|
||||
-> 后台排除 Hook/依赖帧，并使用多来源共同祖先提示排序页面帧
|
||||
-> 纯函数用 selected-frame；负责 DOM 取值/组包/发送的函数用 request-transaction
|
||||
-> 页面立即恢复
|
||||
-> 新明文映射到参数或页面控件，仅返回被拦截的线上 envelope
|
||||
```
|
||||
|
||||
录制器只从每个来源事件的有界同步栈提取页面帧提示，并对 `functionName + script URL` 求交集；支持来源更多、平均深度更浅的共同祖先优先。捕获入口选择最早已确认的密码来源，而不是已经离开上层异步函数后的 Fetch 边界。后台再结合真实 CDP `scriptId`、函数位置、来源分类和副作用检查做最终选择，因此前端不能通过提交 URL、行号或函数名把任意对象伪装成推荐帧。
|
||||
|
||||
当最高候选唯一、可解析且未发现副作用时，默认路径使用 `selected-frame`。如果多个密码来源的最近共同页面祖先本身包含网络、DOM 或条件导航，系统不会跳过它去选更外层的事件 handler，而是建立 `request-transaction`：保留真实函数、receiver 和固定参数，在页面内替换明文控件，拦截唯一的目标 Fetch/XHR/Beacon/Form，校验所有预期输出字段后回滚 DOM。
|
||||
|
||||
存储副作用、多个或未授权请求、无法唯一绑定函数、或共同祖先证据并列时，系统保持页面暂停并解释原因。函数引用表达式只存在于高级模式。页面暂停不等待远程 AI；AI 只能在页面恢复后基于同一份有界证据做解释和候选补丁。
|
||||
|
||||
函数捕获后，后台从 `Function.prototype.toString` 恢复包括默认参数在内的有序参数名。单参数业务函数默认读取整个逻辑 Body；多参数且名称可靠时，引导配置生成 `body.<parameter>` 读取节点；`arg0` 这类占位名不会被冒充为已确认字段。Options 同时从已授权暂停帧的 local/block/closure scope 取同名原始值，构造一次性的本地回放 Body。完整暂停作用域始终只存在于当前会话；只有用户明确生成并保存明文网关后，选中的短时样本才会复制到独立的本机回放草稿。该草稿按 `profileId + request/response` 隔离，不写入 Profile、Bridge、审计、Yak/AI、诊断或导出，并可由用户单独清空。
|
||||
|
||||
### 9.1 多密码调用按请求建图
|
||||
|
||||
一个请求可能同时包含 AES ciphertext、RSA-encrypted session key、HMAC signature、nonce 和 timestamp。即使每个低层输出都与请求字段精确匹配，也不能把这些调用分别保存后独立回放：它们可能共享同一随机 key、IV、nonce 或闭包状态。
|
||||
|
||||
推断器因此按请求边界合并多个来源，生成一个 request-level candidate：
|
||||
|
||||
```text
|
||||
plaintext -----------------> AES.encrypt ----------> body.data
|
||||
dynamic AES key -----------> JSEncrypt.encrypt ----> body.encryptedKey
|
||||
canonical request fields --> HMAC.sign ------------> header.X-Sign
|
||||
|
|
||||
+-- 同一上层业务 callable 保证动态值一致
|
||||
```
|
||||
|
||||
界面展示每个密码调用及其线上目标，但状态固定为 `capture-required`。用户点击“自动捕获完整加密流程”时，Deep Capture 优先在仍保留上层业务调用栈的密码来源处武装断点，并捕获一次上层业务封装；系统不会把多个看似 ready 的低层调用拆成多个可执行 Profile，也不会误导用户反复缩短已经足够短的录制操作。
|
||||
|
||||
### 9.2 请求事务的输入与输出契约
|
||||
|
||||
`request-transaction` 对明文只暴露一个 `body` 输入槽，对 Pipeline 返回被页面业务代码生成的整个请求 Body。因此 AES + RSA 之类多输出流程会直接编译为：
|
||||
|
||||
```text
|
||||
context.read(body)
|
||||
-> page.call(sendDataAesRsa 请求事务)
|
||||
-> output.write(body)
|
||||
```
|
||||
|
||||
事务保留暂停现场的 URL/event/receiver 等固定参数。逻辑 Body 是对象时，先按 input `name/id` 向页面控件做同名映射；参数名明确是 `payload/data/body/request/params/input` 时才直接替换参数。已混淆的单参数如果其保留值解析后等于目标 URL，必须继续保留，不得被明文对象覆盖。
|
||||
|
||||
## 10. AI Agent 集成
|
||||
|
||||
### 10.1 绑定资源
|
||||
|
||||
Yakit 从浏览器集成页启动 AI 分析时，附加一个类型化资源：
|
||||
|
||||
```text
|
||||
AttachedResourceInfo.type = browser_session
|
||||
AttachedResourceInfo.key = context
|
||||
```
|
||||
|
||||
Value 只在 Yak 进程内解析，包含 device、grant、document、selected trace 和 candidate ID。渲染给模型的内容只包含安全摘要，不暴露 device token、grant secret 或录制值。
|
||||
|
||||
资源必须绑定：
|
||||
|
||||
```text
|
||||
timeline session
|
||||
AI task
|
||||
deviceId
|
||||
grantId
|
||||
tabId + frameId + documentId + origin
|
||||
expiresAt
|
||||
```
|
||||
|
||||
### 10.2 Agent 工具
|
||||
|
||||
不要把几十个 Bridge RPC 原样暴露给模型，也不要提供通用 `method + params` 工具。首批提供三个领域工具：
|
||||
|
||||
```text
|
||||
browser_observe
|
||||
page summary / actionable nodes / trace / inference / status / diff
|
||||
|
||||
browser_inference
|
||||
list candidates / inspect evidence / arm capture / choose callable /
|
||||
propose mapping / compile candidate / local replay
|
||||
|
||||
browser_act
|
||||
stable node action / tab activation / human handoff
|
||||
```
|
||||
|
||||
工具回调从当前 AI task 的 `browser_session` 资源解析绑定，AI 参数中不存在 `deviceId`、`grantId` 或任意 Bridge method。
|
||||
|
||||
`browser_observe` 默认只读；`browser_inference` 的读取和推断无需额外确认，arm debugger、创建 callable 和发布 Profile 使用现有细分 scope；`browser_act` 遵循 Agent review policy 和人机接管状态。
|
||||
|
||||
### 10.3 AI 输出 Schema
|
||||
|
||||
AI 只能返回候选补丁：
|
||||
|
||||
```ts
|
||||
interface AIInferencePatch {
|
||||
candidateId: string
|
||||
labels: Array<{ evidenceId: string; role: SemanticRole; reason: string }>
|
||||
preferredFrameId?: string
|
||||
argumentBindings?: Array<{ slotId: string; contextPath: string; reason: string }>
|
||||
suggestedBuiltins?: Array<{ operation: BuiltinOperation; evidenceIds: string[] }>
|
||||
unresolved: string[]
|
||||
}
|
||||
```
|
||||
|
||||
Candidate Merger 必须验证所有 ID 存在、document 未变化、操作在白名单内、映射路径合法。验证失败只产生新的待处理项，不能退化为执行 AI 代码。
|
||||
|
||||
## 11. UI / UX
|
||||
|
||||
录制是入口，自动推断是录制完成后的主结果。三列工作台保持不变：
|
||||
|
||||
```text
|
||||
Trace 列 | 数据流与候选 | 推断证据 / 下一步
|
||||
```
|
||||
|
||||
右侧主区域按状态显示：
|
||||
|
||||
- `ready`：一键生成 Profile；
|
||||
- `capture-required`：解释原因并提供“自动捕获完整加密流程”；
|
||||
- `mapping-required`：只让用户选择少量无法确定的明文字段；
|
||||
- `insufficient-evidence`：建议重新录制，并明确缺少哪类证据。
|
||||
|
||||
证据采用三种强度：
|
||||
|
||||
- 已证实：实线和明确措辞；
|
||||
- 有支持：普通文本并展示依据；
|
||||
- 待确认：虚线或次级文本，不使用成功色。
|
||||
|
||||
AI 是候选的解释者，不单独占据一个聊天面板。主要入口是“让 AI 深入分析”，结果回填到同一证据区域。需要继续对话时再打开 Yakit AI 会话，并携带相同 `browser_session` 资源。
|
||||
|
||||
手工 Pipeline 编辑器移入“高级编辑”，默认只展示推断出的可读流程和少量可修改字段。
|
||||
|
||||
默认 Profile 编辑器不是节点画布，而是三个业务决定：
|
||||
|
||||
```text
|
||||
1. 明文从哪里来
|
||||
2. 交给哪个页面函数
|
||||
3. 线上结果写到哪里
|
||||
```
|
||||
|
||||
当第三步选择“写入表单字段”并填写 `encryptedData` 时，编译器自动生成
|
||||
`form.compose(keys=["encryptedData"])`、固定 Content-Type、Header 输出和 Body 输出。用户不需要看到或填写
|
||||
`keys`、节点 ID、输入引用和输出引用。已有非规范 DAG 不会被静默改写，只能继续在高级模式中编辑，或由用户明确替换为引导流程。
|
||||
|
||||
## 12. 性能预算
|
||||
|
||||
- 单次快照最多 500 事件、每事件 48 个 evidence；
|
||||
- 图构建使用 fingerprint/path 索引，目标复杂度 `O(E + V)`；
|
||||
- normalized link 每值最多生成 8 个白名单变体；
|
||||
- 候选最多 16 个，发送给 AI 的候选最多 3 个；
|
||||
- scope 每次最多 8 个 frame，源码片段按需读取并限制总字节；
|
||||
- 推断结果按 `recordingId + event revision` 缓存，增量追加事件时只处理新增部分；
|
||||
- 不在页面主线程执行全量源码搜索、AST 构建或全局 JSON/URL 编码 Hook；
|
||||
- Pipeline 在目标 document 内一次执行完成，每次请求/响应只跨扩展到页面边界一次，不按节点往返；
|
||||
- 页面暂停路径绝不等待网络或 AI。
|
||||
|
||||
## 13. 隐私与授权
|
||||
|
||||
- 默认推断只使用指纹、类型、长度、路径、算法摘要和源码位置；
|
||||
- 敏感录制预览即使被用户开启，也不自动进入 AI context；
|
||||
- Key、IV、CryptoKey 和闭包值只显示语义、类型与长度；
|
||||
- 源码片段可能包含硬编码 secret，发送 AI 前先进行字面量脱敏并由用户授权；
|
||||
- 推断读取使用 `browser.recording.read`；
|
||||
- scope/source 深入读取使用 `browser.debugger.read`；
|
||||
- arm/resume 与 callable 创建使用 `browser.debugger.control`；
|
||||
- callable 创建、执行与本地回放使用 `browser.callable.execute`；从暂停 frame 捕获 callable 还需要 `browser.debugger.control`；
|
||||
- Profile 发布使用 `browser.transform.manage`；
|
||||
- document、origin 或 grant 变化后候选立即标记 stale，不静默重绑。
|
||||
|
||||
## 14. 生命周期与恢复
|
||||
|
||||
Profile 是 document-bound。刷新后不能继续调用旧闭包，但推断定义可以保留为恢复计划：
|
||||
|
||||
```text
|
||||
页面刷新
|
||||
-> callable stale
|
||||
-> Profile disabled
|
||||
-> 插件按原 operation / script / route 重新 arm
|
||||
-> 用户正常执行一次业务操作
|
||||
-> 重新捕获 callable
|
||||
-> 本地样本校验
|
||||
-> 用户确认后重新启用
|
||||
```
|
||||
|
||||
恢复计划不保存 key 或源码计算结果，只保存捕获入口、业务 frame 特征、参数语义和映射结构。
|
||||
|
||||
## 15. 分阶段实现
|
||||
|
||||
### P0：证据与候选基线
|
||||
|
||||
- [已完成] 使用统一 `crypto` 事件记录 WebCrypto / CryptoJS / JSEncrypt / sm-crypto / node-forge 的 adapter、provider kind、family、调用、参数角色、类型、长度和 state/retained 状态；
|
||||
- [已完成] MAIN-world 密码适配器注册表支持稳定 adapter 与运行时晚加载 adapter；
|
||||
- [已完成] JSEncrypt RSA encrypt/decrypt/sign/verify 保留真实 receiver，并仅输出公私钥类型、位数和加盐指纹；
|
||||
- [已完成] 为 CryptoJS 结果补充安全的字符串表示 evidence；
|
||||
- [已完成] 从 exact link、请求字段和调用顺序生成只读候选；
|
||||
- [已完成] Options / Yakit 展示置信度、证据和缺失步骤；
|
||||
- [已完成] 候选结构可通过 `browser.recording.get` 提供给 Agent。
|
||||
|
||||
### P1：统一 Callable 与 Pipeline v2
|
||||
|
||||
- [已完成] 删除 recipe / adapter 双模型，不保留旧方法别名或迁移分支；
|
||||
- [已完成] 页面 callable 使用统一注册表、来源信息、生命周期和命名 input slot schema；
|
||||
- [已完成] Pipeline v2 使用有序 DAG，并加入类型化 context.read / builtin / page.call / output.write 节点；
|
||||
- [已完成] builtin 限定为 JSON、文本、URL、Base64、Hex、对象和表单组合白名单；
|
||||
- [已完成] 输出支持 body、字段级 body、header 和 query，并由 Yak 二次限制 URL 只能改变 query；
|
||||
- [已完成] 单条 exact value link 且保留可执行调用句柄的 stateless/receiver 模式可直接编译候选；stateful/stream 模式必须捕获上层 callable；
|
||||
- [已完成] 同一请求的多个密码来源合并为 request-level candidate，并强制捕获上层业务 callable 以保持动态值关系；
|
||||
- [已完成] JSON 字段、表单字段、Header、Query 和完整 Body 会编译为对应的引导式输出，不要求用户理解 DAG；
|
||||
- [已完成] 录制短时样本自动填入 Options/Yakit 明文网关本地回放，并允许编辑后恢复原样本；
|
||||
- 为页面内回放生成确定性/结构性断言。
|
||||
|
||||
### P2：自动业务函数捕获
|
||||
|
||||
- [已完成] 候选一键 arm，并在已有捕获等待或页面暂停时拒绝覆盖；
|
||||
- [已完成] 业务 frame 使用来源、边界距离、函数可解析性、副作用、命名和作用域信息做确定性排序；
|
||||
- 参数槽位与 request context 自动映射；
|
||||
- 文档刷新后的引导式重新捕获。
|
||||
|
||||
### P3：Yak AI Agent
|
||||
|
||||
- `browser_session` attached resource；
|
||||
- task-bound 三个 Agent 工具；
|
||||
- AIInferencePatch schema 与 Candidate Merger；
|
||||
- Yakit 从候选直接启动带上下文的 AI 会话；
|
||||
- Agent 操作写入现有 session timeline。
|
||||
|
||||
### P4：复杂应用
|
||||
|
||||
- Axios/interceptor、GraphQL、WebSocket frame、protobuf 与自定义 serializer；
|
||||
- [已完成] 按通用化路线迁移 adapter host，加入 sm-crypto、node-forge 与 Beacon/Worker/MessagePort 边界，并通过随机 ESM + WASM holdout；
|
||||
- jsrsasign、jose 与后续现代密码生态按真实样本继续推进；
|
||||
- sourcemap 存在时的业务 frame 增强；
|
||||
- 多候选对比和跨操作共用 callable 识别。
|
||||
|
||||
P4 的实现顺序、协议草案、性能门禁和随机化测试矩阵以 [`FRONTEND_CRYPTO_GENERALIZATION_ROADMAP.md`](FRONTEND_CRYPTO_GENERALIZATION_ROADMAP.md) 为准。
|
||||
|
||||
## 16. 验收夹具
|
||||
|
||||
至少覆盖：
|
||||
|
||||
1. 固定 CryptoJS AES，混淆变量名，JSON 字段输出；
|
||||
2. 真实 JSEncrypt RSA + form-urlencoded `data` 字段，独立服务端用私钥解密验收；保留实例 receiver，停止录制后对象明文仍可回放；
|
||||
3. RSA 候选和 AI 上下文只包含 key 类型、位数与加盐指纹，不包含 PEM 或模数；
|
||||
4. WebCrypto AES-GCM + HMAC，闭包内不可导出 key 和动态 nonce/IV；
|
||||
5. AES + RSA + HMAC 同请求多来源图，不允许拆分低层调用回放；
|
||||
6. 动态 key promise，页面刷新后重新捕获；
|
||||
7. Axios interceptor 中的请求签名；
|
||||
8. Form URL encode 和 Header signature；
|
||||
9. 自定义业务 wrapper，低层库调用不足以构造完整报文；
|
||||
10. 未知函数与多个同分业务 frame，AI 只能补全候选，不能直接执行代码；
|
||||
11. WASM 导出函数，只能观察输入输出和业务 wrapper；
|
||||
12. 敏感预览开启时，AI payload、审计和诊断仍不含原始值；
|
||||
13. 500 事件 / 24,000 evidence 的性能与内存预算。
|
||||
|
||||
## 17. 目标目录
|
||||
|
||||
```text
|
||||
src/features/browser-recording/
|
||||
evidence.ts
|
||||
recorder.ts
|
||||
|
||||
src/features/browser-inference/
|
||||
graph.ts
|
||||
normalize.ts
|
||||
rules/
|
||||
candidates.ts
|
||||
compiler.ts
|
||||
ai-context.ts
|
||||
|
||||
src/features/browser-callable/
|
||||
registry.ts
|
||||
execute.ts
|
||||
lifecycle.ts
|
||||
|
||||
src/features/browser-transform/
|
||||
pipeline-v2.ts
|
||||
profile.ts
|
||||
replay.ts
|
||||
```
|
||||
|
||||
Yak 侧将 `browser_session` 资源解析和 Agent 工具放在独立包中，依赖一个最小的 Bridge caller interface，避免 `common/ai` 直接依赖 gRPC Server。
|
||||
@@ -0,0 +1,259 @@
|
||||
# Browser Transform Gateway
|
||||
|
||||
## 1. Product contract
|
||||
|
||||
The Browser Transform Gateway exists for one concrete testing workflow:
|
||||
|
||||
> The operator edits and fuzzes meaningful plaintext in Yakit, while the live authenticated browser page performs the same encryption, signing, serialization, dynamic-parameter generation, or response decryption that the production application performs.
|
||||
|
||||
The result sent on the network must be accepted by the real server. A fixed codec demo, copied JavaScript function, or standalone mock key does not satisfy this contract.
|
||||
|
||||
The primary workflow is:
|
||||
|
||||
```text
|
||||
real browser operation
|
||||
-> Recorder correlates user input, crypto calls, and network requests
|
||||
-> an exact recorded call is retained directly when it already covers the required transform
|
||||
-> otherwise Deep Capture pauses at the relevant higher-level business call
|
||||
-> operator retains the real in-scope function as a page callable
|
||||
-> operator composes callables and typed nodes into a request/response transform profile
|
||||
-> Yakit Web Fuzzer remains a plaintext editor
|
||||
-> Yak asks the selected live browser to transform the request immediately before sending
|
||||
-> Yak sends the resulting wire packet
|
||||
-> Yak optionally asks the browser to transform the wire response
|
||||
-> Yakit displays plaintext and preserves a separate wire view
|
||||
```
|
||||
|
||||
The browser is therefore an execution environment, not a passive code source. Non-extractable `CryptoKey` objects, closure variables, key promises, runtime tokens, random generators, timestamps, WASM instances, and application serializers remain in the page that already owns them.
|
||||
|
||||
There are two valid discovery outcomes:
|
||||
|
||||
1. **Direct recorded callable.** One observed primitive already accepts the logical plaintext and its output is proven to enter one wire destination. For example, `JSEncrypt.encrypt` with its real instance receiver can map an object body to form field `data`. The operator generates the guided gateway directly; no function expression or debugger pause is required.
|
||||
2. **Business callable.** A request combines multiple primitives or surrounding serialization/dynamic state. AES ciphertext, RSA-wrapped key, signature, nonce, timestamp, and request canonicalization are treated as one request graph, then Deep Capture retains the higher-level closure. The extension never replays those low-level calls independently merely because each output has an exact field link.
|
||||
|
||||
## 2. Relationship to JS-RPC and JS-Forward
|
||||
|
||||
JS-RPC, JS-Forward, browser-side hook tools, and this gateway share the same basic idea: forward values into a browser JavaScript environment and receive transformed values back. The important product difference is the ownership and workflow around that call.
|
||||
|
||||
| Concern | Traditional forwarding setup | Browser Transform Gateway |
|
||||
| --- | --- | --- |
|
||||
| Function discovery | User locates and exposes a function manually | Recorder and Deep Capture lead from a real request to the relevant business frame |
|
||||
| Runtime environment | Usually a manually maintained browser tab or injected service | Explicitly selected, paired, document-bound authenticated tab |
|
||||
| Data-plane integration | External HTTP port or custom script modifies packets | Native Web Fuzzer pre-send and post-response hooks in the owning Yak gRPC process |
|
||||
| Request editing | Often ciphertext-oriented or script-oriented | Plaintext is the canonical editable request |
|
||||
| Observability | Tool-specific logs | Plaintext request, wire request, wire response, plaintext response, and step timing |
|
||||
| Lifecycle | Caller must notice stale pages/functions | Navigation and refresh fail with document/origin errors; no silent retargeting |
|
||||
| Authorization | Commonly a shared local endpoint | Paired device, task, grant, target, scope, and capability schema |
|
||||
|
||||
An external forwarding port can be added later as another Yak data-plane adapter for Burp/Fiddler compatibility. It must reuse the same profile execution contract and must not become a second configuration or authorization system.
|
||||
|
||||
Research notes and comparisons are retained in [`study.md`](study.md). They inform discovery and UX, but the production acceptance criterion is always whether a server accepts the transformed packet.
|
||||
|
||||
## 3. Component responsibilities
|
||||
|
||||
### Browser extension
|
||||
|
||||
- discovers page-side data flow through Recorder;
|
||||
- captures a real business closure through Chromium Deep Capture;
|
||||
- stores only document-bound callable metadata and transform profiles;
|
||||
- keeps an optional replay draft per profile and direction in extension-local storage after the operator saves a gateway;
|
||||
- validates route, method, origin, document, function binding, paths, and output mappings;
|
||||
- executes an ordered Pipeline v2 DAG in the live MAIN world;
|
||||
- sends the complete validated DAG and packet through one extension-to-page round trip instead of crossing the boundary for every node;
|
||||
- returns bounded URL/body/header mutations plus per-node duration;
|
||||
- never exports closure bindings or key material.
|
||||
|
||||
The replay draft is deliberately not a field of the transform profile. It may contain a plaintext account, password,
|
||||
token, request headers, or a selected short capture sample. It is keyed by `profileId + request/response`, stays in
|
||||
`browser.storage.local`, and is excluded from profile export, Bridge/RPC capabilities, Yak/AI context, audit, and
|
||||
diagnostics. Deleting a profile deletes both directional drafts. The editor autosaves at most 256 KiB per direction;
|
||||
larger input remains usable in the current Options page but replaces no persisted value.
|
||||
|
||||
### Yak engine
|
||||
|
||||
- performs profile preflight through the Bridge owned by the current gRPC process;
|
||||
- composes the browser transform with existing Web Fuzzer hot-patch hooks;
|
||||
- calls the selected browser immediately before the real request and immediately after the real response;
|
||||
- fails closed before network transmission if request conversion fails;
|
||||
- emits an explicit synthetic `598 Browser Transform Failed` response if response conversion fails;
|
||||
- preserves logical and wire packets separately in every Fuzzer result and history item.
|
||||
|
||||
### Yakit
|
||||
|
||||
- lists only online paired browsers and profiles visible to the active grant;
|
||||
- provides the full profile editor in Browser Integration;
|
||||
- lets Web Fuzzer select one browser/profile pair without leaving the request workflow;
|
||||
- keeps `RequestRaw` and `ResponseRaw` as the canonical plaintext editor/display values;
|
||||
- exposes `WireRequestRaw` and `WireResponseRaw` through a stable side-by-side comparison;
|
||||
- restores the selected browser/profile when reopening Fuzzer history.
|
||||
|
||||
## 4. Transform profile
|
||||
|
||||
A profile is intentionally document-bound and contains:
|
||||
|
||||
- a name and enabled state;
|
||||
- `tabId + frameId + documentId + origin`;
|
||||
- allowed HTTP methods and a bounded wildcard URL pattern;
|
||||
- an optional request pipeline;
|
||||
- an optional response pipeline;
|
||||
- `failMode: closed`;
|
||||
- a bounded per-profile concurrency limit from 1 to 8.
|
||||
|
||||
Method, URL, headers, body, captured short sample, and the last local replay result are not profile fields. The first
|
||||
five can be restored from the separate local-only replay draft; execution results and errors are never persisted.
|
||||
|
||||
At least one direction must be enabled. Every enabled direction contains at least one node and one `output.write` node.
|
||||
|
||||
A path-only URL pattern such as `/api/*` or `*/api/login` is restricted to the bound page origin. Cross-origin APIs must be intentional: use a full pattern such as `https://api.example.test/*`. This prevents a broadly reusable path rule from turning a page-held key into a cross-origin signing oracle.
|
||||
|
||||
### Pipeline v2 nodes
|
||||
|
||||
Each node has a stable ID and may reference only an earlier node. This makes the data flow explicit and prevents cycles or undeclared reads. The supported node kinds are:
|
||||
|
||||
| Node | Purpose |
|
||||
| --- | --- |
|
||||
| `context.read` | Read a safe path from the immutable input context |
|
||||
| `builtin` | Apply one whitelisted JSON/text/URL/Base64/Hex/object/form operation |
|
||||
| `page.call` | Invoke one document-bound `BrowserPageCallable` with referenced arguments |
|
||||
| `output.write` | Write a referenced value to an allowed packet destination |
|
||||
|
||||
The normal editor presents these nodes through a three-step guided compiler: choose the plaintext source, choose the
|
||||
live page callable, and choose the wire destination. The ordered DAG is an implementation detail under “Advanced
|
||||
Pipeline”; operators do not manually select node references for common request encryption.
|
||||
|
||||
For example, choosing `form field` with the name `encryptedData` compiles to:
|
||||
|
||||
```text
|
||||
context.read(body)
|
||||
-> page.call(recorded AES callable)
|
||||
-> form.compose(keys=["encryptedData"])
|
||||
-> output.write(body)
|
||||
|
||||
value.literal("application/x-www-form-urlencoded")
|
||||
-> output.write(header.Content-Type)
|
||||
```
|
||||
|
||||
`value.literal` is a bounded whitelist operation that accepts only a primitive value and no inputs. It exists so the
|
||||
compiler can express fixed protocol metadata without arbitrary JavaScript. Existing non-canonical DAGs remain in the
|
||||
advanced editor and are never silently rewritten.
|
||||
|
||||
`context.read` accepts these safe roots:
|
||||
|
||||
```text
|
||||
method
|
||||
url
|
||||
statusCode
|
||||
headers.content-type
|
||||
body
|
||||
body.account
|
||||
body.password
|
||||
text
|
||||
bodyBase64
|
||||
query
|
||||
query.name
|
||||
```
|
||||
|
||||
Missing node IDs, forward references, duplicate IDs, malformed paths, and prototype traversal segments are rejected. Arbitrary JavaScript is not a Pipeline node.
|
||||
|
||||
The background validates the profile, route, origin and live document before dispatch. The selected document then evaluates the complete bounded DAG locally, including all `page.call` nodes, and returns one structured result. This keeps multi-node profiles from multiplying `scripting.executeScript` latency and keeps the Pipeline executor out of the always-on Service Worker bundle.
|
||||
|
||||
### Output nodes
|
||||
|
||||
An `output.write` maps a prior node result to exactly one supported destination:
|
||||
|
||||
```text
|
||||
body replace the complete body
|
||||
body.password update a JSON body field
|
||||
header.X-Sign set a header; null/undefined removes it
|
||||
query.signature set a URL query field; null/undefined removes it
|
||||
```
|
||||
|
||||
Output encoding is explicit: `auto`, `text`, `json`, or `base64`. Header names and values reject CR/LF injection. JSON and form field mapping preserve their structured wire format and never mutate object prototypes. The extension can return a query-mutated URL, but Yak independently verifies that scheme, hostname, effective port and path are unchanged before replacing the request target.
|
||||
|
||||
## 5. Ordering
|
||||
|
||||
Request execution order is deliberate:
|
||||
|
||||
```text
|
||||
plaintext request in Web Fuzzer
|
||||
-> user beforeRequest hot patch
|
||||
-> browser request transform
|
||||
-> actual wire request
|
||||
```
|
||||
|
||||
Response execution uses the inverse boundary:
|
||||
|
||||
```text
|
||||
actual wire response
|
||||
-> browser response transform
|
||||
-> user afterRequest hot patch
|
||||
-> plaintext response in Web Fuzzer
|
||||
```
|
||||
|
||||
This allows ordinary Web Fuzzer mutation logic to work on meaningful application data. The browser transform remains the last operation before transmission and the first operation after receipt.
|
||||
|
||||
Redirected requests are transformed independently. A redirect to a route outside the selected profile fails closed instead of leaking a plaintext request to an unintended endpoint.
|
||||
|
||||
## 6. Failure and lifecycle semantics
|
||||
|
||||
The request path never falls back to sending plaintext. Profile lookup failure, offline device, expired grant, stale document, changed origin, unavailable callable, route mismatch, illegal URL mutation, queue overflow, invalid mapping, timeout, and page exception all abort transmission.
|
||||
|
||||
The response path never presents undecoded wire data as if it were plaintext. It returns an explicit transformation failure while preserving the wire response for diagnosis.
|
||||
|
||||
Profiles are not portable secrets. They may remain visible after a navigation so the operator can understand what became stale, but execution requires the exact current document and all referenced page callables. A reload intentionally requires recapture and rebinding.
|
||||
|
||||
Local replay drafts can contain secrets even though profiles do not. Navigation or a temporarily stale callable keeps
|
||||
the draft intact so the operator does not lose work. The operator can clear the current direction explicitly, and
|
||||
deleting its owning profile removes both request and response drafts. The draft does not make a stale callable
|
||||
executable and is never silently rebound to another origin.
|
||||
|
||||
Chromium is required for capturing closure-bound business callables. Firefox keeps Recorder-created callables but does not advertise or display the Transform Gateway and Deep Capture workspaces.
|
||||
|
||||
## 7. Bounds and performance
|
||||
|
||||
- request and response bodies are limited to 8 MiB;
|
||||
- a profile has at most 64 nodes per direction;
|
||||
- a builtin or page-call node has at most 64 input references;
|
||||
- a profile queue is bounded to 128 waiting operations;
|
||||
- per-profile concurrency is 1, 2, 4, or 8 in the UI;
|
||||
- page-callable output is lossless within bounds; cycles, functions, symbols, excessive depth/nodes, and oversized values fail explicitly;
|
||||
- parsed and mapped JSON is limited to 64 levels and 100,000 nodes before a page function is invoked;
|
||||
- previews may be truncated, execution values are never silently truncated;
|
||||
- Bridge messages remain under the existing 16 MiB aggregate limit and use chunking above 512 KiB.
|
||||
|
||||
Concurrency must reflect the page function's state model. Use `1` when the application mutates shared counters, nonce state, or token caches. Higher values are appropriate only after verifying that the retained business function is re-entrant.
|
||||
|
||||
## 8. Authorization
|
||||
|
||||
Transform capabilities are separated by intent:
|
||||
|
||||
| Capability | Scope |
|
||||
| --- | --- |
|
||||
| `browser.transform.profile.list` | `browser.transform.read` |
|
||||
| `browser.transform.profile.save/delete` | `browser.transform.manage` |
|
||||
| `browser.transform.execute` | `browser.transform.execute` |
|
||||
|
||||
The Bridge router revalidates the profile target against the active grant for list, save, delete, and execute. An existing profile ID cannot be rebound to another page document.
|
||||
|
||||
## 9. Acceptance criteria
|
||||
|
||||
The production fixture uses live request and response functions that close over non-extractable AES-GCM and HMAC keys. The request function creates a new timestamp, nonce, and IV per call, encrypts a JSON login payload, and signs the resulting envelope. The server returns a second AES-GCM envelope that only the retained page response function opens. Acceptance requires all of the following:
|
||||
|
||||
1. A plaintext account/password packet is transformed through the retained page closure.
|
||||
2. The wire packet does not contain the plaintext password.
|
||||
3. The independent test server verifies HMAC, decrypts AES-GCM, and recovers the original request values.
|
||||
4. The server returns an encrypted response with no plaintext password, and the retained page closure restores it to JSON.
|
||||
5. Repeated calls produce different nonce and IV values.
|
||||
6. A mismatched path or implicit cross-origin URL fails closed.
|
||||
7. Web Fuzzer preserves and displays both plaintext and wire packets in both directions.
|
||||
8. Refreshing the bound document invalidates execution rather than silently using a new page.
|
||||
|
||||
Extension browser E2E covers the real page and server boundary. Yak unit tests cover hook ordering, request/response conversion, trace preservation, and failure behavior. Yakit TypeScript verification covers the integrated selector, editor, and packet comparison surfaces.
|
||||
|
||||
The browser E2E suite also covers the direct RSA path independently: the real JSEncrypt browser bundle receives a generated RSA public key, its Base64 ciphertext is linked to `application/x-www-form-urlencoded` field `data`, and a separate HTTP test server holding the private key must decrypt and recover the original JSON. Raw key material must remain absent from the candidate/AI context. After recording stops, both Bridge- and UI-created callables must still invoke the retained receiver with a new structured plaintext value whose ciphertext the server-side decryptor can open.
|
||||
|
||||
## 10. Current boundary
|
||||
|
||||
The first production data-plane integration is Yakit Web Fuzzer. Direct Burp/Fiddler interception, WebSocket frame transformation, streaming bodies, and unattended cross-document callable recovery remain outside the current contract. They should be built as explicit extensions of this gateway, not as hidden fallbacks.
|
||||
|
||||
Automatic Profile inference is now part of the core product path rather than a later convenience. Recorder evidence, retained page callables, deterministic rules and task-bound AI analysis must lead from one real browser operation to an explainable Profile candidate. The architecture, evidence contract, AI boundary and phased implementation are defined in [`AUTO_PROFILE_INFERENCE_ARCHITECTURE.md`](AUTO_PROFILE_INFERENCE_ARCHITECTURE.md).
|
||||
@@ -0,0 +1,149 @@
|
||||
# Deep Capture Architecture
|
||||
|
||||
## Product boundary
|
||||
|
||||
Deep Capture is for an authorized tester who can reproduce a real browser operation but does not want to rebuild a site's frontend encryption environment in a separate JS-RPC service.
|
||||
|
||||
The user chooses the business action and reproduces it once. Request-level inference selects the capture boundary and, when the evidence is unique, the background selects and retains the relevant business frame automatically. The user chooses a stack frame only when candidates are ambiguous; a function expression is an advanced fallback. The extension supplies the browser-only parts: the live document, lexical scope, non-extractable keys, dynamically generated IV/nonce/timestamp values, function receiver and authenticated session.
|
||||
|
||||
This is deliberately not a promise to autonomously solve QR codes, CAPTCHA, MFA, device confirmation or every obfuscated application. Those steps remain visible human actions. The product goal is to remove avoidable environment reconstruction after the user reaches the real business operation.
|
||||
|
||||
## Workflow
|
||||
|
||||
```text
|
||||
Real user operation
|
||||
-> lightweight Recorder discovers a Trace and target operation
|
||||
-> Deep Capture arms one crypto function or request breakpoint
|
||||
-> Chromium pauses at the next real invocation
|
||||
-> call frames become visible immediately
|
||||
-> local / closure / module scopes are collected in parallel
|
||||
-> shared stack hints and CDP metadata rank page business frames
|
||||
-> a pure frame becomes a business closure; a send/DOM frame becomes a request transaction
|
||||
-> function object + receiver + fixed call-frame arguments stay inside the live document
|
||||
-> page resumes
|
||||
-> plaintext maps to formal parameters or matching page controls
|
||||
-> a request transaction captures the target envelope without sending it
|
||||
-> extension, Yakit or Yak invokes the page callable with new JSON arguments
|
||||
-> dynamic browser behavior and server validation remain real
|
||||
```
|
||||
|
||||
The Recorder is the discovery/index layer. It records bounded interactions, requests, Beacon/WebSocket/Worker/MessagePort activity, unified WebCrypto/CryptoJS/JSEncrypt/sm-crypto/node-forge crypto calls, transforms, Trace membership, exact value links and explicitly correlated channel links. A recorded-call callable replays one eligible stateless or receiver-bound primitive by replacing its named data argument while retaining the original function, receiver and fixed argument template. Stateful sessions remain evidence and are promoted to their enclosing business closure.
|
||||
|
||||
Deep Capture is the runtime/context layer. It captures a business function from a paused lexical environment, so one business-closure callable may preserve several internal crypto calls, closure variables, key promises, dynamic parameters and serialization steps. If the closest common business function also reads DOM controls, builds the request and calls Fetch/XHR/Beacon/Form, the same frame is retained as a `request-transaction` instead of being skipped in favor of an outer click handler. Both sources use the same registry and execution protocol while retaining distinct provenance and input-slot metadata.
|
||||
|
||||
## Chromium implementation
|
||||
|
||||
The background service uses `chrome.debugger` and these Chrome DevTools Protocol domains:
|
||||
|
||||
- `Runtime` resolves the live wrapper function and reads object properties;
|
||||
- `Debugger` enables pauses, function-call breakpoints, call frames, scopes and `evaluateOnCallFrame`;
|
||||
- `DOMDebugger` installs a one-shot XHR/fetch URL breakpoint;
|
||||
- `Network` prepares the session for later request correlation without intercepting traffic in this phase.
|
||||
|
||||
Crypto capture does not depend on a source `debugger` statement. Production minifiers may remove that statement, and page CSP may block dynamic code construction. Instead, the recorder exposes the exact installed adapter or communication-boundary wrapper by its opaque `wrapperHandleId`. The background sets `Debugger.setBreakpointOnFunctionCall` on that object and removes the breakpoint on the first pause. Request-only unknown code can still use a bounded XHR/fetch URL breakpoint.
|
||||
|
||||
Chrome may omit `callFrame.url` for ESM/module frames. The service therefore maintains a per-tab, 4,096-entry LRU-style `Debugger.scriptParsed` index and resolves the frame source from `location.scriptId`. This makes dynamically named ESM chunks first-class capture targets without scanning a bundler cache or exposing their exports on `window`.
|
||||
|
||||
Request capture uses `DOMDebugger.setXHRBreakpoint` with a bounded URL substring. It is also one-shot.
|
||||
|
||||
The current implementation supports Chromium main documents. Firefox does not request `debugger`, does not advertise Deep Capture Bridge capabilities and continues to provide Recorder-created callables.
|
||||
|
||||
## Pause control plane
|
||||
|
||||
A paused page cannot execute `scripting.executeScript`. Status, keepalive, resume, detach and callable creation must therefore never depend on an injected document probe.
|
||||
|
||||
During a pause, target authorization uses only:
|
||||
|
||||
- the grant's tab/frame/document/origin tuple;
|
||||
- `tabs` and `webNavigation` state;
|
||||
- extension session storage owned by the background;
|
||||
- CDP commands on the already attached target.
|
||||
|
||||
Page execution is used only before the pause to install/resolve a target function and after the pause to list, invoke or delete retained callables. This separation prevents the debugger control plane from deadlocking on the page it controls.
|
||||
|
||||
## Two-stage collection
|
||||
|
||||
The pause event publishes a stack skeleton before reading scope properties. This gives UI and Bridge clients an immediately observable `paused` state and lets them extend the deadline. Scope collection then fills the first eight frames in parallel.
|
||||
|
||||
Current bounds are:
|
||||
|
||||
| Resource | Bound |
|
||||
| --- | ---: |
|
||||
| Pause watchdog | 45 seconds |
|
||||
| Call frames | 14 |
|
||||
| Frames with scope expansion | 8 |
|
||||
| Scopes per frame | 6 |
|
||||
| Variables per scope | 48 |
|
||||
| Variable preview | 512 characters |
|
||||
| Expandable variable detail | 4,096 characters per variable |
|
||||
| Expandable detail per scope | 16,384 characters |
|
||||
| Page callable arguments | 64 JSON values |
|
||||
| Function expression | 4,096 characters |
|
||||
|
||||
The extension UI sends keepalive every 10 seconds while paused. Yakit uses `browser.deep_capture.keepalive` as its paused-state poll. If all control surfaces disappear, the alarm watchdog resumes the page automatically.
|
||||
|
||||
Every frame carries an explicit `sourceKind`: `extension-hook`, `page`, or `library`. Exact recorder/debugger wrapper names and extension URLs are classified as extension hooks; dependency/runtime URLs are classified as libraries; remaining frames are page code. Request-level inference contributes bounded common-ancestor hints from multiple source stacks. The background combines those hints with frame depth, CDP script identity, function location and risk inspection; the UI cannot supply trusted source metadata. Options and Yakit display the labels and reasons, and prevent an extension hook or dependency frame from being captured as a business callable. Scope rows are keyboard-operable expanders: the list keeps a compact preview, while the expanded block shows a bounded value or function-source detail with copy actions. This makes injected wrappers visibly different from application functions without exporting unbounded debugger data.
|
||||
|
||||
## Unified page callable
|
||||
|
||||
`browser.callable.create` with `source: deep-capture` has three explicit strategies. `selected-frame` resolves a pure function from the stored current call frame and rejects network/DOM/navigation/storage side effects. `request-transaction` retains the closest request-building business frame and its bounded request contract. `expression` remains an advanced fallback and passes the pure-function inspection gate. Client-provided source URLs and line numbers are not accepted. The returned function object and its frame receiver are placed in the shared `BrowserPageCallable` registry keyed by an opaque UUID. Recorder-created calls use the same registry with `source: recording`. Only metadata crosses the extension boundary:
|
||||
|
||||
- callable ID, name and kind;
|
||||
- ordered input slots and output type/encoding;
|
||||
- function name;
|
||||
- source URL and line;
|
||||
- recording/Trace/event provenance when available;
|
||||
- creation time;
|
||||
- for a request transaction, expected method, URL reference, output destinations and allowed boundary kinds;
|
||||
- `document` lifecycle.
|
||||
|
||||
Formal parameter names are recovered from bounded function source, including parameters after the first default value, and become ordered input slots. Fixed parameter values and `this` are retained by reading the named parameters from the actual CDP call frame; the debugger evaluation wrapper's `arguments` object is never used as business input. Options may correlate those names with values already present in the authorized paused scope to initialize a local replay Body. That short-lived sample never enters Bridge payloads, audit records, callable metadata or profile storage.
|
||||
|
||||
A request transaction exposes one logical `body` input. Execution snapshots bounded form controls and DOM mutations, maps object fields to matching input names/IDs, and temporarily replaces Fetch, XHR send, Beacon and Form submit boundaries. Exactly one request must match the configured method and URL after resolving relative URLs against the current document. The body must contain every inferred destination, such as `body.encryptedData`, `body.encryptedKey` and `body.encryptedIv`. The real transport is never called; controls and observed DOM mutations are rolled back in `finally`. Multiple requests, another URL, an unsupported/file body, timeout, over-budget data or missing fields fail closed. Ordinary business closures also receive runtime transport guards so a transitive helper cannot silently send a request that shallow source inspection missed.
|
||||
|
||||
The registry does not export closure bindings, `CryptoKey` material or the function source. `browser.callable.execute` calls the retained function in the MAIN world and returns a bounded structured result. ArrayBuffer and typed-array results are normalized to byte metadata plus Base64. Execution results are lossless within the 8 MiB string/byte, 100,000-node and depth-32 bounds; cycles, functions, symbols and oversized structures fail explicitly. Only UI previews are truncated.
|
||||
|
||||
Page callables are the execution primitive used by the [Browser Transform Gateway](BROWSER_TRANSFORM_GATEWAY.md). Deep Capture discovers and retains the real business function; a Pipeline v2 profile reads plaintext request/response context, invokes one or more callables and writes explicit results back to the wire packet.
|
||||
|
||||
Navigation, reload or document destruction removes the registry naturally. Explicit deletion removes one callable. Callable IDs are not portable credentials.
|
||||
|
||||
## Authorization and lifecycle
|
||||
|
||||
Deep Capture adds three independent scopes:
|
||||
|
||||
| Scope | Allows |
|
||||
| --- | --- |
|
||||
| `browser.debugger.read` | Read status, call frames and scopes |
|
||||
| `browser.debugger.control` | Attach, arm, keep alive, resume, detach and capture a function from a paused frame |
|
||||
| `browser.callable.execute` | Create, execute and delete live-document page callables |
|
||||
|
||||
Remote calls remain bound to the active grant's tab, main frame, document, origin and expiry. A grant cannot control a local or different grant's debugger session. Grant replacement, expiry and revocation detach sessions owned by that grant. Tab closure removes session state. Chrome DevTools and an extension debugger may compete for the same target; the UI reports the attach/detach failure rather than silently changing targets.
|
||||
|
||||
## Real acceptance fixture
|
||||
|
||||
The production E2E fixture uses a local authenticated page with:
|
||||
|
||||
- native WebCrypto rather than a string mock;
|
||||
- non-extractable AES-GCM and HMAC keys imported inside a closure;
|
||||
- a local `buildLoginEnvelope` function that is not placed on `window`;
|
||||
- dynamic timestamp, nonce and IV values;
|
||||
- encrypted account/password JSON;
|
||||
- an HMAC over envelope fields;
|
||||
- server-side HMAC verification and AES-GCM decryption.
|
||||
|
||||
The test records a real operation containing AES-GCM and HMAC, infers their common `buildLoginEnvelope` ancestor, pauses on the earliest confirmed crypto source, automatically captures the selected frame, restores both `password` and defaulted `account` parameters, generates `body.password` and `body.account` bindings from the paused sample, and executes the complete local Pipeline. Independent server validation also invokes the closure with new credentials, asserts different nonce/IV values and accepts the generated envelope. A hash stub or a hard-coded frontend demo does not satisfy this acceptance criterion.
|
||||
|
||||
A second real-browser fixture covers the mixed AES + RSA request transaction at `127.0.0.1:82`. Three exact output links must select `sendDataAesRsa`, not its outer `onclick`. The test supplies new username/password values through the page controls, captures `encryptedData`, `encryptedKey` and `encryptedIv`, proves that neither deep-capture recovery nor callable replay added a browser request, and sends the captured envelope independently to the fixture server for acceptance.
|
||||
|
||||
## Known limits
|
||||
|
||||
- Chromium Deep Capture only; Firefox remains on recording and recorded-call page callables.
|
||||
- Main document only in the current phase. Cross-frame debugging needs an explicit CDP target/session design rather than silently reusing frame grants.
|
||||
- Source-map remapping is not implemented; URLs and generated line/column values come from CDP.
|
||||
- Highly optimized, native, WASM-heavy or deliberately anti-debugging applications may expose incomplete names or scopes.
|
||||
- Runtime transport interception covers dynamic global Fetch, XHR, Beacon and Form boundaries. A function that captured a private transport reference before interception, sends inside another Worker/realm, performs unconditional direct navigation, or mutates storage through an unobserved helper is not claimed as safely automatic; the current system must block on detected evidence or report the failed/stale transaction.
|
||||
- DOM rollback is bounded and best-effort. It is not a general browser transaction or a replacement for a disposable test profile.
|
||||
- The tester may need to select a function-valued scope variable or use the advanced in-scope expression when an anonymous or optimized frame cannot be resolved uniquely.
|
||||
- The callable intentionally stays document-bound. Portable code generation requires a separate reviewed artifact model and cannot assume captured closure/key objects are serializable.
|
||||
|
||||
References: [Chrome Debugger API](https://developer.chrome.com/docs/extensions/reference/api/debugger), [CDP Debugger domain](https://chromedevtools.github.io/devtools-protocol/tot/Debugger/), and [CDP DOMDebugger domain](https://chromedevtools.github.io/devtools-protocol/tot/DOMDebugger/).
|
||||
@@ -0,0 +1,615 @@
|
||||
# 前端密码能力通用化重构与适配器路线
|
||||
|
||||
> 状态：G0–G4 已完成并通过真实浏览器/独立验证器验收；G5 按真实样本继续推进
|
||||
>
|
||||
> 更新时间：2026-07-21
|
||||
>
|
||||
> 关联文档：[`AUTO_PROFILE_INFERENCE_ARCHITECTURE.md`](AUTO_PROFILE_INFERENCE_ARCHITECTURE.md)、[`DEEP_CAPTURE_ARCHITECTURE.md`](DEEP_CAPTURE_ARCHITECTURE.md)、[`BROWSER_TRANSFORM_GATEWAY.md`](BROWSER_TRANSFORM_GATEWAY.md)、[`study.md`](study.md)
|
||||
|
||||
## 1. 结论
|
||||
|
||||
当前实现的**数据模型、请求推断和 G4 高价值协议覆盖是通用的；WASM、流式协议与长尾生态仍需由真实样本继续驱动**。
|
||||
|
||||
现有靶场体验顺滑，主要因为它同时满足了三个有利条件：
|
||||
|
||||
1. 使用全局可访问的 `window.CryptoJS` 或 `window.JSEncrypt`；
|
||||
2. 加密后通过常规 Fetch/Form 请求发送；
|
||||
3. 密码调用输出可以和请求字段建立精确值关联。
|
||||
|
||||
生产代码并没有依赖 `127.0.0.1:82`、`/encrypt/aes.php`、`/encrypt/rsa.php`、固定用户名、固定密码或固定业务字段。请求字段推断也已经支持 JSON、Form、Header、Query 和完整 Body。因此当前实现不是为靶场硬编码的结果。
|
||||
|
||||
但“没有靶场硬编码”不等于“已经覆盖真实世界”。当前 MAIN-world 录制器通过有界 manifest 为以下可访问对象安装语义 Hook：
|
||||
|
||||
- 当前页面 Realm 的 `SubtleCrypto`；
|
||||
- `CryptoJS`、`JSEncrypt`、`sm-crypto` 与 `node-forge`；
|
||||
- `jsrsasign` 的 Signature/JWS/JWT/JWK；
|
||||
- 页面显式暴露的 `jose` 高层 builder 与 verify/decrypt 函数。
|
||||
|
||||
没有全局导出的 ESM/Webpack 闭包、Worker 内密码运算、WASM 和完全未知的业务封装不会通过侵入 bundler cache 强行发现；它们继续走请求/消息边界、WebCrypto、证据图和 Deep Capture 业务闭包恢复。这是正式的通用路径，不是失败后的临时兜底。
|
||||
|
||||
因此本轮重构采用以下产品判断：
|
||||
|
||||
> 已知库适配器是语义加速器，不是产品能力的地基。请求与消息边界、业务函数恢复、文档绑定 callable 和服务端认可的真实回放，才是通用能力的地基。
|
||||
|
||||
最终验收不是“界面显示识别到 AES/RSA”，而是：
|
||||
|
||||
```text
|
||||
用户执行一次真实操作
|
||||
-> 插件定位明文、页面业务调用和线上目标
|
||||
-> 已知库时给出准确算法语义，未知库时仍能定位业务封装
|
||||
-> 页面保留 key / IV / nonce / receiver / closure / WASM 状态
|
||||
-> Yakit Web Fuzzer 编辑明文
|
||||
-> 浏览器生成真实线上报文
|
||||
-> 独立服务端成功解密、验签或接受请求
|
||||
```
|
||||
|
||||
算法名称可以暂时未知，业务链路不能因此不可用。
|
||||
|
||||
## 2. 重构目标与非目标
|
||||
|
||||
### 2.1 目标
|
||||
|
||||
- 支持全局库、打包闭包、混淆函数、Worker 消息边界和 WASM 外围业务函数；
|
||||
- 已知密码库接入同一 adapter contract，不再把逻辑堆入 MAIN-world 录制器；
|
||||
- 未知库也可以从请求/消息边界进入 Deep Capture，恢复上层业务 callable；
|
||||
- 自动 Profile 以请求为中心，保留 AES + RSA + HMAC + timestamp 等同一业务上下文；
|
||||
- 页面秘密始终留在页面对象、闭包、CryptoKey 或 WASM 内存中，不通过协议导出；
|
||||
- 适配器安装、事件归一化、证据建图、AI 分析和 Profile 执行各自独立；
|
||||
- 使用随机化、跨打包形态的真实服务端夹具证明没有按图索骥；
|
||||
- 在录制开启时保持有界开销，录制停止后完整恢复页面 API 且不存在后台轮询。
|
||||
|
||||
### 2.2 非目标
|
||||
|
||||
- 不追求穷举所有 JavaScript 密码库；
|
||||
- 不要求先还原算法、密钥或混淆源码才能使用明文网关；
|
||||
- 不把页面 key、PEM、CryptoKey、闭包变量或 WASM 内存导出到扩展、Yak 或 AI；
|
||||
- 不在页面主线程进行全量源码搜索、全局对象枚举或 AST 扫描；
|
||||
- 不为某个站点、接口路径、字段名或靶场流程维护特殊规则；
|
||||
- 不保留旧 provider 枚举、旧录制协议或旧适配器目录的迁移兼容层。
|
||||
|
||||
## 3. 四层通用架构
|
||||
|
||||
```text
|
||||
L0 业务边界探针
|
||||
Fetch / XHR / Form / sendBeacon / WebSocket / Worker / MessagePort / Navigation
|
||||
|
|
||||
| 有界输入输出、调用顺序、同步/异步栈、值关联
|
||||
v
|
||||
L1 通用运行时边界
|
||||
WebCrypto / random / encoding / WebAssembly 装载 / serializer 边界
|
||||
|
|
||||
| 原生算法元数据、TypedArray 形态、opaque object
|
||||
v
|
||||
L2 已知语义适配器
|
||||
CryptoJS / JSEncrypt / sm-crypto / node-forge / jsrsasign / jose / sodium ...
|
||||
|
|
||||
| 参数角色、模式、padding、state model、可复跑能力
|
||||
v
|
||||
L3 未知业务函数恢复
|
||||
请求断点 -> 页面业务帧排序 -> closure callable -> 自动 Profile
|
||||
```
|
||||
|
||||
四层不是按顺序全部执行的流水线。L0 始终提供兜底证据；L1/L2 提供更强语义和更精确的断点；L3 在低层 primitive 不足、库不可见或业务封装复杂时恢复完整现场。
|
||||
|
||||
### 3.1 L0：业务边界是最低保证
|
||||
|
||||
请求和消息边界回答三个最重要的问题：
|
||||
|
||||
1. 哪段值真正离开了页面；
|
||||
2. 它被写入 Body、字段、Header、Query、WebSocket frame 还是 Worker 消息；
|
||||
3. 哪个页面调用链在边界之前构造了它。
|
||||
|
||||
现有 Fetch/XHR/Form/WebSocket 继续保留，并补齐：
|
||||
|
||||
- `navigator.sendBeacon`；
|
||||
- `Worker.prototype.postMessage`；
|
||||
- `MessagePort.prototype.postMessage`；
|
||||
- `SharedWorker.port` 消息边界；
|
||||
- 有界同步栈和可用时的异步栈来源；
|
||||
- TypedArray、ArrayBuffer、Blob、FormData 和 transferable 的结构化摘要；
|
||||
- 同一 Trace 内从输入、消息到请求的精确/归一化值关联。
|
||||
|
||||
页面侧边界看不到 Worker 内部每一步是事实，不应伪装成已识别。即使 Worker 内部无法安装密码适配器，插件仍可关联“页面明文消息 -> Worker 返回值 -> 请求字段”，并以消息边界或调用 Worker 的页面业务函数作为 callable 捕获入口。
|
||||
|
||||
Service Worker 内部运算不属于普通页面 MAIN world。第一阶段只保证通过 `webRequest` 和页面消息/请求边界观察真实线上结果；更深的 Worker/Service Worker 调试目标支持需要独立评估 CDP Target 生命周期，不能和页面适配器混为一个实现。
|
||||
|
||||
### 3.2 L1：通用运行时边界
|
||||
|
||||
首批运行时探针包括：
|
||||
|
||||
- WebCrypto `SubtleCrypto`；
|
||||
- `crypto.getRandomValues` 和 `randomUUID` 的调用关系摘要，不记录随机原值；
|
||||
- `TextEncoder` / `TextDecoder`、Base64、Hex 等有界编码链；
|
||||
- `WebAssembly.instantiate` / `instantiateStreaming` 的模块与实例身份摘要；
|
||||
- 请求边界处的 JSON、Form、Query 和 Header 结构化解析。
|
||||
|
||||
不得全局 Hook 每一次 `JSON.stringify`、`encodeURIComponent` 或遍历所有 WASM exports。高频通用函数只在请求边界归一化，或在已确定的 Trace/Deep Capture 窗口内按需观察，避免让正常页面承担持续成本。
|
||||
|
||||
WASM 的第一目标不是反编译算法，而是保留调用它的页面业务 wrapper、输入输出关联和实例生命周期。只要该 wrapper 能在原页面复跑，明文网关就不需要导出 WASM 内存或重写算法。
|
||||
|
||||
### 3.3 L2：已知语义适配器
|
||||
|
||||
适配器负责把“某个函数被调用”解释成统一语义：
|
||||
|
||||
- provider/adapter 身份；
|
||||
- symmetric、asymmetric、digest、MAC、signature、KDF 或 key-management family；
|
||||
- data、key、iv、nonce、aad、signature、options 等参数角色；
|
||||
- algorithm、mode、padding、input/output encoding；
|
||||
- stateless、receiver-bound、stateful-session、streaming 或 async-ready 状态模型；
|
||||
- 是否可以安全保留原函数、receiver 和参数模板作为 recorded-call callable。
|
||||
|
||||
适配器不负责请求字段推断、UI 文案、AI prompt、Profile 编译或 Bridge RPC。新增库不应修改这些下游层。
|
||||
|
||||
### 3.4 L3：未知业务函数恢复
|
||||
|
||||
“不知道是哪一个库”不能成为终点。通用回退流程是：
|
||||
|
||||
```text
|
||||
请求/消息边界已定位
|
||||
-> 武装下一次相同边界
|
||||
-> 用户重复一次真实操作
|
||||
-> 立即发布有界调用栈
|
||||
-> 排除 extension hook 和已知依赖 frame
|
||||
-> 结合参数相关性、请求接近度、源码位置、同步/异步父栈给业务 frame 排序
|
||||
-> 捕获完整业务 closure callable
|
||||
-> 页面恢复
|
||||
-> 用短时样本做页面内回放
|
||||
```
|
||||
|
||||
页面函数叫 `encryptPayload`、`pack`、`request` 或 `_0x3f2a` 都不影响流程。AI 可以解释 frame 和参数语义，但只能返回引用既有 evidence 的候选补丁，不能生成并直接执行任意代码。
|
||||
|
||||
## 4. 适配器协议重构
|
||||
|
||||
### 4.1 删除封闭 provider 枚举
|
||||
|
||||
当前 `BrowserCryptoProvider` 是 `webcrypto | cryptojs | jsencrypt | forge | custom` 的封闭联合。继续添加库会迫使协议、归一化器、UI 和测试重复修改。
|
||||
|
||||
新协议使用有界 adapter ID 和稳定 provider kind：
|
||||
|
||||
```ts
|
||||
type BrowserCryptoProviderKind =
|
||||
| "native"
|
||||
| "library"
|
||||
| "business"
|
||||
| "wasm"
|
||||
| "unknown"
|
||||
|
||||
interface BrowserRecordingCrypto {
|
||||
adapterId: string // 受限 slug，例如 "webcrypto"、"sm-crypto"
|
||||
providerKind: BrowserCryptoProviderKind
|
||||
family: BrowserCryptoFamily
|
||||
operation: string // 适配器内部稳定 operation ID
|
||||
algorithm?: string
|
||||
mode?: string
|
||||
padding?: string
|
||||
inputEncoding?: BrowserPageCallableValueEncoding
|
||||
outputEncoding?: BrowserPageCallableValueEncoding
|
||||
state?: {
|
||||
model: "stateless" | "receiver" | "session" | "stream" | "async-ready"
|
||||
correlationId?: string
|
||||
phase?: "create" | "init" | "update" | "final" | "one-shot"
|
||||
}
|
||||
key?: {
|
||||
kind: "public" | "private" | "secret" | "unknown"
|
||||
bits?: number
|
||||
fingerprint?: string
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`adapterId`、`operation` 和所有字符串必须限长并按字符集校验。UI 显示名来自扩展自带的 adapter manifest，不信任页面提供的 HTML 或展示文本。未知 ID 使用安全的纯文本回退标签。
|
||||
|
||||
Deep Capture 不再依赖 `CryptoJS.AES.encrypt` 这类展示字符串查找函数，而是绑定录制器已经保留的 wrapper handle：
|
||||
|
||||
```text
|
||||
adapterId + operation + wrapperHandleId + documentId
|
||||
```
|
||||
|
||||
这样库被混淆、别名导出或方法名重复时，也不会武装错误函数。
|
||||
|
||||
### 4.2 统一 adapter contract
|
||||
|
||||
```ts
|
||||
interface PageCryptoAdapter {
|
||||
manifest: {
|
||||
id: string
|
||||
displayName: string
|
||||
providerKind: BrowserCryptoProviderKind
|
||||
dynamic: boolean
|
||||
}
|
||||
discover(context: AdapterDiscoveryContext): AdapterTarget[]
|
||||
install(target: AdapterTarget, host: AdapterHost): AdapterInstallation
|
||||
}
|
||||
|
||||
interface AdapterInstallation {
|
||||
id: string
|
||||
operations: InstalledOperation[]
|
||||
restore(): void
|
||||
}
|
||||
|
||||
interface AdapterHost {
|
||||
wrap(input: WrapOperationInput): InstalledOperation
|
||||
emit(input: NormalizedCryptoCall): void
|
||||
retain(input: RetainedCallInput): string | undefined
|
||||
fingerprint(value: unknown): ValueEvidence[]
|
||||
}
|
||||
```
|
||||
|
||||
公共 `wrap` 基础设施必须统一处理：
|
||||
|
||||
- 原 property descriptor、原函数和原 receiver；
|
||||
- 同步返回、Promise resolve/reject 和库返回 `false/null` 的语义；
|
||||
- re-entrancy 防护，避免适配器调用辅助方法时递归记录；
|
||||
- 参数与输出大小预算；
|
||||
- wrapper handle 与 Deep Capture 一次性断点；
|
||||
- 页面后续替换函数时不覆盖页面的新值；
|
||||
- restore 只恢复自己仍然拥有的 descriptor；
|
||||
- 停止、清空、导航、grant 撤销和异常安装时的幂等清理。
|
||||
|
||||
适配器只能使用 host 提供的 evidence、emit 和 retain 能力，不各自维护事件队列、Trace、指纹算法或 callable registry。
|
||||
|
||||
### 4.3 状态型与流式 API
|
||||
|
||||
不能把所有库都按 `encrypt(data, key) -> ciphertext` 的一次函数处理。
|
||||
|
||||
例如 node-forge 常见调用链是：
|
||||
|
||||
```text
|
||||
createCipher -> start -> update -> finish -> output
|
||||
```
|
||||
|
||||
jsrsasign 的签名流程可能是：
|
||||
|
||||
```text
|
||||
new Signature -> init -> updateString/updateHex -> sign
|
||||
```
|
||||
|
||||
这些调用需要同一 `correlationId` 和 phase 序列。只有满足以下条件才允许生成 recorded-call callable：
|
||||
|
||||
- 可替换明文输入明确；
|
||||
- 原 receiver/session 仍有效；
|
||||
- 重放不会复用已经消费的流状态；
|
||||
- 输出与请求目标存在 proven link；
|
||||
- 调用没有网络、DOM、导航等额外副作用。
|
||||
|
||||
不满足时适配器只提供语义证据，并把候选标记为 `capture-required`，由 Deep Capture 保留上层一次性业务封装。
|
||||
|
||||
### 4.4 晚加载与打包形态
|
||||
|
||||
现有每秒扫描动态全局库的方式需要替换为有界调度：
|
||||
|
||||
- 录制开始时立即检查一次已知全局路径；
|
||||
- 捕获动态 `<script>` load 后检查相关 adapter；
|
||||
- 在交互、请求或消息边界前执行去重后的轻量 ensure；
|
||||
- 必要时使用短期指数退避检查，达到预算后停止；
|
||||
- 录制停止后不存在 timer 或扫描；
|
||||
- 不枚举整个 `window`，只访问 manifest 声明的有界路径。
|
||||
|
||||
ESM/Webpack 闭包没有全局路径时，适配器不得尝试侵入 bundler module cache。此时依赖 L0 边界和 L3 业务函数恢复；这不是降级错误，而是设计好的通用路径。
|
||||
|
||||
## 5. 高价值库路线
|
||||
|
||||
优先级根据真实安全测试价值、浏览器出现频率、与现有能力互补程度和接入复杂度确定，不按 npm 下载量机械排序。
|
||||
|
||||
| 优先级 | 能力 | 主要价值 | 适配重点 | 产品行为 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| P0 | WebCrypto、CryptoJS、JSEncrypt | 当前基线 | 迁移到新 contract，行为不回退 | 继续支持 direct callable 与业务捕获 |
|
||||
| P1 | `sm-crypto` | 国内系统常见 SM2/SM3/SM4 | mode、cipher mode、签名选项、编码与 key 摘要 | 一次函数可直连；组合链按请求捕获 |
|
||||
| P1 | `node-forge` | RSA/PKI、AES、digest、HMAC、证书工具覆盖广 | receiver、cipher session、buffer、start/update/finish | 状态型默认捕获上层业务 callable |
|
||||
| P2 | `jsrsasign` | RSA-PSS、ECDSA、JWS/JWT/JWK/X.509 | constructor session、update/sign/verify、编码 | 签名 envelope 以请求级候选处理 |
|
||||
| P2 | `jose` | 现代 JWS/JWE/JWT/JWK/JWKS | Promise、WebCrypto、高层协议对象、ESM | 优先保留高层 async callable |
|
||||
| P3 | `libsodium.js` | secretbox/box/sign、XChaCha、现代密码原语 | `sodium.ready`、TypedArray、JS/WASM 双实现 | async-ready adapter + 业务 wrapper |
|
||||
| P3 | `TweetNaCl.js` | box/secretbox/sign 的轻量实现 | nonce/key TypedArray 与固定长度元数据 | 一次调用与请求字段关联 |
|
||||
| P3 | `noble-*` | 现代曲线、hash、cipher 的模块化 ESM | 无全局对象、纯 ESM、细分包 | 以通用边界为主，显式导出时增强语义 |
|
||||
| P4 | `OpenPGP.js` | PGP 消息、签名、密钥与流式处理 | async、stream、复杂对象和大数据预算 | 捕获高层业务调用，不展开低层原语 |
|
||||
|
||||
第一轮实际编码范围固定为：
|
||||
|
||||
1. 适配器基础设施与现有三种 provider 迁移；
|
||||
2. Worker/MessagePort/sendBeacon 边界和未知业务函数回退；
|
||||
3. `sm-crypto`；
|
||||
4. `node-forge`。
|
||||
|
||||
`jsrsasign` 和 `jose` 紧随第一轮，但必须等状态模型和 async callable 在前两种新适配器上验证稳定后再进入。`libsodium.js`、TweetNaCl、noble 和 OpenPGP 不阻塞第一轮发布。
|
||||
|
||||
不优先为 SJCL、asmCrypto.js 等历史库建立专用 adapter。它们仍可走未知业务 callable；只有真实用户样本证明专用语义能显著降低操作成本时再加入。
|
||||
|
||||
### 5.1 非密码但必须纳入链路的转换
|
||||
|
||||
真实报文还常包含 serializer/compression，而不仅是密码 primitive：
|
||||
|
||||
- Axios interceptor；
|
||||
- protobuf / protobufjs；
|
||||
- MessagePack；
|
||||
- gzip/deflate/pako；
|
||||
- canonical JSON、参数排序、时间戳、requestId；
|
||||
- URL/Form/Header 拼装。
|
||||
|
||||
这些能力不伪装成 crypto adapter。它们进入独立 transform/serializer evidence，最终与 crypto event 一起组成 request-level graph。明文网关必须保留整个 envelope，而不是只复跑某一个 AES 函数。
|
||||
|
||||
## 6. 目录设计
|
||||
|
||||
重构前 `page-recorder-main-world.ts` 同时包含录制状态、请求 Hook、密码库 Hook、指纹、callable 和执行逻辑，接近 1,500 行。G1–G3 已把 adapter contract/registry、五个库 adapter、通信边界、业务 frame 排序和 retained-call 预算移出入口；Fetch/XHR/Form/WebSocket、evidence/trace 与编码探针仍按下面的目标目录继续做物理拆分：
|
||||
|
||||
```text
|
||||
src/entrypoints/page-recorder-main-world.ts
|
||||
只负责启动、协议握手和生命周期编排
|
||||
|
||||
src/features/browser-recording/main-world/
|
||||
recorder-host.ts
|
||||
event-budget.ts
|
||||
evidence.ts
|
||||
trace.ts
|
||||
retained-call.ts
|
||||
boundaries/
|
||||
fetch.ts
|
||||
xhr.ts
|
||||
form.ts
|
||||
beacon.ts
|
||||
websocket.ts
|
||||
worker-message.ts
|
||||
navigation.ts
|
||||
runtime/
|
||||
webcrypto.ts
|
||||
encoding.ts
|
||||
wasm.ts
|
||||
|
||||
src/features/browser-crypto/adapters/
|
||||
contract.ts
|
||||
registry.ts
|
||||
wrapper.ts
|
||||
webcrypto.ts
|
||||
cryptojs.ts
|
||||
jsencrypt.ts
|
||||
sm-crypto.ts
|
||||
node-forge.ts
|
||||
jsrsasign.ts
|
||||
jose.ts
|
||||
|
||||
src/features/browser-inference/
|
||||
graph.ts
|
||||
normalize.ts
|
||||
business-frame-ranker.ts
|
||||
rules/
|
||||
candidates.ts
|
||||
compiler.ts
|
||||
ai-context.ts
|
||||
```
|
||||
|
||||
WXT 仍将这些模块编译进一个 MAIN-world entrypoint；拆文件是为了责任边界、独立测试和 tree-shaking，不意味着跨 world 增加消息往返。
|
||||
|
||||
## 7. 自动推断与 UI 契约
|
||||
|
||||
### 7.1 已知库
|
||||
|
||||
用户看到：
|
||||
|
||||
```text
|
||||
已识别：sm-crypto SM2.encrypt
|
||||
明文：argument 0
|
||||
线上目标：body.data
|
||||
证据：精确值关联 + 同一 Trace + 页面 callable 可用
|
||||
```
|
||||
|
||||
### 7.2 未知库或闭包模块
|
||||
|
||||
用户看到：
|
||||
|
||||
```text
|
||||
已定位：请求发送前的页面封装函数
|
||||
算法：尚未命名，不影响继续捕获
|
||||
线上目标：header.X-Sign + body.payload
|
||||
下一步：重复一次操作，插件将保留完整页面函数
|
||||
```
|
||||
|
||||
不得显示“未支持该密码库，所以无法继续”。只要 L0/L3 仍有路径，就应清楚说明已经知道什么、还缺什么，以及用户只需要完成哪一个真实动作。
|
||||
|
||||
### 7.3 候选状态
|
||||
|
||||
- `ready`：单一、无副作用、可复跑的调用已经与一个线上目标形成 proven link；
|
||||
- `capture-required`：状态型 API、多密码调用、动态 key/nonce、未知闭包或完整 envelope 需要上层业务 callable；
|
||||
- `mapping-required`：页面能力已保留，但明文来源或线上目标存在多个同分候选；
|
||||
- `insufficient-evidence`：没有请求/消息边界或没有可验证的数据关联。
|
||||
|
||||
“算法未知”本身不构成 `insufficient-evidence`。
|
||||
|
||||
## 8. 防止靶场特化的测试矩阵
|
||||
|
||||
### 8.1 夹具维度
|
||||
|
||||
每种核心能力至少覆盖三种发布形态：
|
||||
|
||||
1. UMD/global；
|
||||
2. Vite/Webpack/Rollup ESM closure；
|
||||
3. Worker 或 WASM 外围业务 wrapper。
|
||||
|
||||
夹具按 seed 随机生成：
|
||||
|
||||
- URL 和接口路径；
|
||||
- JSON/Form/Header/Query 字段名；
|
||||
- 函数名、变量名和模块 chunk 名；
|
||||
- JSON 嵌套深度与字段顺序；
|
||||
- 编码链；
|
||||
- 同一页面上的无关密码调用数量；
|
||||
- 请求使用 Fetch、XHR、Form、sendBeacon 或 WebSocket；
|
||||
- 跳转、SPA 路由和 BFCache 行为。
|
||||
|
||||
测试只保存 seed 和预期语义，不把固定字段名写入生产推断规则。采用 pairwise 组合覆盖主要交互，不构造不可维护的完整笛卡尔积。
|
||||
|
||||
### 8.2 正向场景
|
||||
|
||||
- CryptoJS AES、WebCrypto AES-GCM/HMAC、JSEncrypt RSA 当前能力不回退；
|
||||
- sm-crypto 的 SM2 加密/签名、SM3、SM4 CBC；
|
||||
- node-forge RSA 与 stateful AES cipher；
|
||||
- AES session key + RSA wrapped key + HMAC + timestamp 的同请求 envelope；
|
||||
- ESM 闭包内未知库只凭请求边界恢复业务 callable；
|
||||
- Worker 内处理通过 postMessage 输入输出建立关联；
|
||||
- WASM 内部算法未知，但页面 wrapper 可以生成服务端认可的报文；
|
||||
- 请求加密和响应解密共用同一文档现场；
|
||||
- 页面刷新后 callable 明确 stale，并能按恢复计划重新捕获。
|
||||
|
||||
### 8.3 反例场景
|
||||
|
||||
- 库已加载但从未参与目标请求；
|
||||
- 同一种加密调用发生多次，只有一个输出进入请求；
|
||||
- 两个输出内容相同但属于不同 Trace；
|
||||
- 加密结果经过 Base64、URL encode、JSON/Form 包装后才进入请求；
|
||||
- 页面在 Hook 后替换函数，停止录制不得覆盖页面新函数；
|
||||
- 适配器安装一半失败，其他适配器和页面原 API 必须正常；
|
||||
- 重放业务函数可能发送网络、修改 DOM 或触发导航时禁止 direct callable；
|
||||
- 多个同分业务 frame 时不得以高置信度自动选中；
|
||||
- key、PEM、CryptoKey、nonce 原值、闭包 secret 不得进入事件、AI、审计或诊断导出。
|
||||
|
||||
### 8.4 独立验收
|
||||
|
||||
每个可以发布为 Profile 的夹具都必须由独立服务端进行最终验证：
|
||||
|
||||
- 加密：服务端持有解密材料并恢复用户编辑后的明文；
|
||||
- 签名：服务端使用独立验证逻辑通过签名；
|
||||
- 响应解密：浏览器收到真实密文，Yakit 最终看到预期明文；
|
||||
- 动态参数：连续回放的 nonce/IV/requestId 不得被错误固定；
|
||||
- 失败路径：浏览器离线、document 变化或 callable 丢失时 fail closed，绝不发送明文。
|
||||
|
||||
至少保留一个实现完成前不向推断规则暴露字段/路径的 holdout fixture。它必须只依赖 adapter contract、边界证据和业务函数恢复通过验收。
|
||||
|
||||
### 8.5 生产源码泄漏门禁
|
||||
|
||||
构建审计增加 fixture leakage 检查：生产模块不得出现靶场 host、固定 endpoint、固定测试账号、seed 或专用字段映射。测试、E2E server 和文档示例可以出现这些值，但必须物理隔离于生产 bundle。
|
||||
|
||||
## 9. 性能与稳定性门禁
|
||||
|
||||
- 录制未开启时不安装密码/边界 wrapper，不运行 adapter timer；
|
||||
- 录制停止后 descriptor、listener、timer 和 retained handle 完整清理；
|
||||
- 不枚举整个 `window`，adapter discovery 只访问 manifest 声明路径；
|
||||
- 单次事件、单值、单 Trace 和整个 Session 沿用硬预算，超过后计数并丢弃而不是继续分配；
|
||||
- TypedArray/ArrayBuffer 指纹按大小预算处理，大对象只读取头尾有界片段和总长度；
|
||||
- 请求边界归一化为 `O(payload bytes + evidence nodes)`，变体数量固定上限；
|
||||
- event 到 background/UI 使用批量刷新，不因每个密码 primitive 触发 React 重渲染；
|
||||
- wrapper 不改变原 Promise、异常、`this`、property descriptor 和返回值语义；
|
||||
- 建立录制关闭、空闲录制、1,000 次小调用、10 次 1 MiB 调用和达到事件上限后的基准；
|
||||
- 重构前先记录基线，Enterprise Chromium E2E 对 recorder 自身耗时、事件/handle 内存预算和页面返回语义设置回归阈值；包体积继续作为观测指标，不作为替代运行时性能的硬门槛。
|
||||
|
||||
## 10. 分阶段实施
|
||||
|
||||
### G0：重构基线与测量
|
||||
|
||||
- [x] 固化当前 93 项测试和 Chrome Store、Chrome Enterprise、Firefox MV2、Firefox AMO MV3 四渠道构建结果；
|
||||
- [x] 为 recorder 关闭、运行、停止、1,000 次调用、10 次 1 MiB 调用和上限耗尽建立真实浏览器性能门禁；
|
||||
- [x] 增加 production fixture leakage 审计；
|
||||
- [x] 把现有 WebCrypto/CryptoJS/JSEncrypt E2E 设为不可回退基线。
|
||||
|
||||
### G1：协议与 adapter host
|
||||
|
||||
- [x] 删除封闭 `BrowserCryptoProvider` 和旧 `call` 展示字符串匹配；
|
||||
- [x] 引入 adapter manifest、开放但有界的 `adapterId`、provider kind 和 state model；
|
||||
- [x] 抽出 wrapper/descriptor restore、Promise、动态 session discovery、evidence 和 retained-call 预算逻辑；
|
||||
- [x] 将 WebCrypto、CryptoJS、JSEncrypt 迁入独立 adapter；
|
||||
- [x] 从 MAIN-world 入口拆出 adapter registry、五个库 adapter、通信边界和 retained-call 预算，不保留旧 adapter 分支；
|
||||
- [x] Deep Capture 改为 wrapper handle 精确武装。
|
||||
|
||||
### G2：通用边界与未知函数路径
|
||||
|
||||
- [x] 增加 sendBeacon、Worker、SharedWorker 和 MessagePort 边界；
|
||||
- [x] 记录有界同步来源、异步 Worker/MessagePort Trace 继承和 channel correlation；
|
||||
- [x] 建立业务 frame 确定性排序器，并区分 extension hook、依赖库与页面代码；
|
||||
- [x] 允许从未知请求/消息边界一键捕获业务 callable；
|
||||
- [x] 算法未知时仍可生成可解释的 `capture-required` 候选；
|
||||
- [x] 加入随机 ESM closure、真实 Worker 和 WASM instance holdout fixture；模块函数不暴露到 `window`，仍可被保留和复跑。
|
||||
|
||||
### G3：第一批高价值适配器
|
||||
|
||||
- [x] `sm-crypto`：SM2 encrypt/decrypt/sign/verify、SM3、SM4 encrypt/decrypt；
|
||||
- [x] `node-forge`：RSA、digest/HMAC、对称 cipher session 与 buffer 输出；
|
||||
- [x] 状态型 operation correlation、动态 session/output 方法发现和 replay eligibility 判定；
|
||||
- [x] 独立服务端通过 SM2/SM4/RSA/AES/digest/HMAC/签名验收；
|
||||
- [x] 全局库、拆分全局、真实 minified bundle、闭包与随机混淆变量共用同一 evidence graph 和推断规则。
|
||||
|
||||
### G3.5：自动恢复完整业务闭包
|
||||
|
||||
- [x] 多个密码调用按请求合并后，从各来源的有界同步栈提取共同页面祖先，不依赖接口路径、字段名或靶场函数名；
|
||||
- [x] 以最早仍位于业务闭包内的已确认密码调用作为一次性断点入口，并把共同祖先作为 `frameHints` 交给后台确定性排序器；
|
||||
- [x] `selected-frame` 由后台使用真实 CDP frame、函数位置和作用域绑定解析函数对象，不接受 UI 伪造的源码 URL 或行号；
|
||||
- [x] 唯一且无副作用的页面业务帧自动保存为 `business-closure`；最近共同祖先本身负责 DOM 取值、组包和发请求时，保存为 `request-transaction`，不再跳过它去选外层 `onclick`；
|
||||
- [x] 从函数源码恢复包括默认参数在内的有序参数名；单参数默认接收整个逻辑 Body，多参数且名称可靠时自动编译 `body.<parameter>` 输入映射；
|
||||
- [x] 暂停帧的固定参数按已解析参数名从 CDP 作用域取值，不使用调试器包装层 `arguments`；混淆参数只有在无 DOM 映射、不是目标 URL 且无更强语义时才可尝试接收逻辑 Body；
|
||||
- [x] 从已授权暂停现场的 local/block/closure scope 生成一次性本地回放样本；完整暂停作用域不持久化，只有用户明确保存明文网关时选中的短时样本进入独立、有界、可清理的本机回放草稿，且不进入 Profile、Bridge、审计、Yak/AI、诊断或导出；
|
||||
- [x] `request-transaction` 在 MAIN world 中临时拦截 Fetch/XHR/Beacon/Form，精确校验 method + origin/path/query，把逻辑 Body 映射到同名表单控件，并在执行后回滚控件与有界 DOM 变更；
|
||||
- [x] 事务只接受唯一目标请求，多请求、未授权 URL、超时、超 8 MiB Body 或缺少任一预期输出字段都 fail closed；普通 callable 在运行时也会拦截透传的网络/Form 副作用；
|
||||
- [x] 真实 Chromium E2E 从 AES-GCM + HMAC 两个低层调用自动恢复 `buildLoginEnvelope`，生成双参数明文网关并执行完整 Pipeline。
|
||||
- [x] 真实 `127.0.0.1:82` AES + RSA 流程自动选中 `sendDataAesRsa` 而非 `onclick`，回放产生 `encryptedData/encryptedKey/encryptedIv`，浏览器零真实泄漏请求，独立服务端接受新明文产生的 envelope。
|
||||
|
||||
### G4：协议与现代密码生态
|
||||
|
||||
- [x] `jsrsasign` 的 Signature/JWS/JWT/JWK 语义；
|
||||
- [x] `jose` 的 SignJWT/CompactSign/CompactEncrypt 和对应 verify/decrypt；
|
||||
- [x] Axios interceptor 产生的最终请求、JSON/Query canonicalization 和 Header signature request graph；
|
||||
- [x] async callable、constructor session 和多输出 envelope 验收。
|
||||
|
||||
### G5：WASM、流式与长尾
|
||||
|
||||
- [ ] libsodium.js async-ready + JS/WASM 双形态；
|
||||
- [ ] TweetNaCl 和 noble 系列；
|
||||
- [ ] OpenPGP.js streaming；
|
||||
- [ ] protobuf/MessagePack/compression transform evidence；
|
||||
- [ ] 根据真实样本而不是库清单决定后续专用 adapter。
|
||||
|
||||
实施顺序是硬约束：G1/G2 没有通过通用 holdout 之前，不以继续堆叠库 Hook 代替架构重构。
|
||||
|
||||
### G0–G3.5 验收记录（2026-07-21）
|
||||
|
||||
- 单元/协议测试：26 个测试文件、116 项测试全部通过；
|
||||
- 类型检查：TypeScript `--noEmit` 通过；
|
||||
- 构建：Chrome Store、Chrome Enterprise、Firefox MV2、Firefox AMO MV3 全部通过；
|
||||
- 生产审计：权限、执行渠道、fixture signature 泄漏检查通过；包体积只保留为 advisory；
|
||||
- 真实浏览器：Chrome Store User Scripts、Chrome Enterprise User Scripts、Chrome Enterprise injected fallback 三条全流程 E2E 均通过；
|
||||
- 语义 adapter：真实 `sm-crypto` 和真实 minified `node-forge` 浏览器包参与录制，独立 Node 服务端完成解密、摘要比对或验签；这些包只属于 dev/E2E 依赖，不进入插件生产运行时；
|
||||
- 未知库 holdout：每轮随机生成 ESM 模块 URL、业务函数名、请求 URL 和 JSON 字段，业务函数不挂载到 `window`，闭包持有真实 `WebAssembly.Instance`；Deep Capture 通过 `scriptParsed` 的有界 `scriptId -> URL` 索引恢复来源、确定性选中纯业务帧并保存 callable，随后由独立服务端接受新明文生成的报文；
|
||||
- Worker holdout：页面明文消息、异步 Worker 返回值和后续 Fetch 保持同一 Trace，消息通道只作为 correlated evidence，不伪装成 exact value link；
|
||||
- 自动业务闭包：AES-GCM 与 HMAC 的来源栈共同指向未挂载到 `window` 的 `buildLoginEnvelope`；一次重现后自动捕获 `password/account` 两个参数，使用暂停现场样本生成 `body.password/body.account` 映射，并在本地执行完整四节点 Pipeline；
|
||||
- 请求事务：混淆 AES + RSA 页面的三个密码调用共同指向直接读 DOM 并 Fetch 的 `sendDataAesRsa`；自动捕获后用新账号密码生成三字段 envelope，浏览器请求计数不增加，独立 Node 请求获得服务端 `success=true`；
|
||||
- 性能样本（当前 WSL/Chromium 三种执行通道，作为回归参考而非跨机器 SLA）：录制关闭时 1,000 次轻量调用约 0.2–0.3 ms，录制开启约 34.0–46.4 ms，10 次 1 MiB 调用约 284.5–308.3 ms；自动化 E2E 使用宽松绝对门禁抵抗机器抖动；
|
||||
- 内存门禁：事件数、单值、单 handle 和全部 retained handles 同时有界；3 MiB 单次输入仍可留下元数据事件，但不会生成长期持有页面参数的 replay handle；
|
||||
- 清理：停止后 Fetch、XHR、WebSocket、Beacon、Worker、MessagePort、WebCrypto 和所有库方法恢复为页面原函数，timer/listener/channel context 清空。
|
||||
|
||||
### G4 验收记录（2026-07-21）
|
||||
|
||||
- callable 协议升级为显式 `resultMode + timeoutMs`；同步、Promise 与自动模式不再依赖隐式 `Promise.resolve`，异步超时后释放网络/DOM 防护 Hook，迟到结果不会重新写回；
|
||||
- `request-transaction` 使用显式 `shape=envelope + paths`，声明路径必须与请求边界的 `expectedDestinations` 完全一致，空字段集、缺字段、重复请求、越权 URL 和超时继续 fail closed；
|
||||
- evidence graph 新增 `state` link：`create -> init -> update -> final` 共享 correlation ID，但不伪装成 exact value；最终签名或密文进入请求时仍保持字段级 exact proof，不会把会话阶段误拆成多个输出源；
|
||||
- JSON.stringify、URLSearchParams sort/toString 与 Axios request-builder 作为独立 transform evidence 进入图；只有活动 Trace 才记录，每个 Trace 最多 32 个准备阶段，不遍历 bundler cache；
|
||||
- 真实 `jsrsasign 11.1.3` 完成 RSA Signature 会话与 JWK 隐私验收，真实 `jose 6.2.3` 完成 SignJWT、CompactSign、CompactEncrypt 及独立 verify/decrypt；测试依赖不进入生产运行时；
|
||||
- 专项 Headless Chrome 加载真实 jsrsasign 浏览器包和真实 jose ESM，记录到构造器/异步阶段、JSON/Axios 与 Header 签名边界；Node 独立验证器接受页面签名、JWT 和 JWE，停止后 JSON、Axios 与协议构造器全部恢复；
|
||||
- 单元/协议测试：31 个测试文件、135 项测试全部通过；TypeScript `--noEmit` 与 Chrome MV3 生产构建通过；生产产物未包含靶场 URL、固定凭据、私钥或测试库实现；
|
||||
- `jsrsasign` 官方已公告进入停止支持周期，因此 Adapter 仅用于识别和复用目标页面已有实现，不代表建议新系统采用该库，也不会把它打进插件运行时。
|
||||
|
||||
## 11. 完成定义
|
||||
|
||||
本路线不能以“新增了几个库名称”宣布完成。至少同时满足：
|
||||
|
||||
- 现有三种 provider 全部迁移到独立 contract，MAIN-world entrypoint 不再拥有库特定实现；
|
||||
- sm-crypto 和 node-forge 通过真实服务器加密/解密/验签；
|
||||
- jsrsasign 与 jose 的状态/异步协议通过真实浏览器和独立验签/解密；
|
||||
- 一个没有专用 adapter 的 ESM 闭包夹具仍能从请求边界恢复业务 callable；
|
||||
- 一个 Worker 或 WASM 夹具在不知道内部算法实现的情况下生成服务端认可报文；
|
||||
- 全局库、闭包库、混淆命名使用同一 evidence graph 和 Profile compiler；
|
||||
- 随机化 URL、字段、变量名后无需修改生产规则；
|
||||
- 多密码 envelope 保持动态 key/IV/nonce/signature 一致性；
|
||||
- key material 不离开页面现场；
|
||||
- 录制停止后无残留 Hook/timer，性能基准无未解释回退；
|
||||
- Options、Yakit 与 AI 使用同一候选，不各自维护库特判。
|
||||
|
||||
## 12. 调研依据
|
||||
|
||||
以下资料用于确认库的官方能力面和接入形态，链接是调研依据，不表示必须把这些包作为插件运行时依赖打入生产包：
|
||||
|
||||
- [Web Cryptography API（W3C）](https://www.w3.org/TR/WebCryptoAPI/)
|
||||
- [CryptoJS](https://github.com/brix/crypto-js)
|
||||
- [JSEncrypt](https://github.com/travist/jsencrypt)
|
||||
- [sm-crypto](https://github.com/JuneAndGreen/sm-crypto)
|
||||
- [node-forge](https://github.com/digitalbazaar/forge)
|
||||
- [jsrsasign](https://github.com/kjur/jsrsasign)
|
||||
- [jose](https://github.com/panva/jose)
|
||||
- [libsodium.js](https://github.com/jedisct1/libsodium.js)
|
||||
- [TweetNaCl.js](https://github.com/dchest/tweetnacl-js)
|
||||
- [noble-hashes](https://github.com/paulmillr/noble-hashes)、[noble-curves](https://github.com/paulmillr/noble-curves)、[noble-ciphers](https://github.com/paulmillr/noble-ciphers)
|
||||
- [OpenPGP.js](https://github.com/openpgpjs/openpgpjs)
|
||||
+6
-3
@@ -5,18 +5,21 @@ Every permission maps to a shipped, user-facing feature. Future functionality is
|
||||
| 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. |
|
||||
| `storage` | Store split settings, active session, bounded audit, aggregate metrics and profile-scoped local Transform Gateway replay drafts. | Audit, action timeline, metrics and each local replay draft can be cleared; replay drafts are excluded from diagnostics and deleted with their profile. |
|
||||
| `unlimitedStorage` | Keep large imported proxy-rule subscriptions and compiled artifacts in extension-owned IndexedDB without evicting unrelated settings. | Sources are visible, refreshable and removable; runtime artifacts are bounded and revisioned. |
|
||||
| `alarms` | Refresh enabled proxy subscriptions and enforce the Deep Capture pause watchdog after Service Worker suspension. | Source intervals are configured in Options; a paused page automatically resumes after 45 seconds without keepalive. |
|
||||
| `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. |
|
||||
| `scripting` | Run packaged frame probes, stable-node operations, the document-bound browser recorder, live-document page callables and bounded plaintext/wire transforms. | Page operations are explicit and scoped; raw recording previews, callable execution and transform read/manage/execute use independent scopes. |
|
||||
| `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. |
|
||||
| `debugger` (Chromium) | Install one-shot CDP function/request breakpoints, read bounded call frames/scopes, and resume or detach a paused page. | Deep Capture is explicit, main-document-only, separately scoped, visibly attached and protected by a 45-second auto-resume watchdog. |
|
||||
| `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.
|
||||
`activeTab` is intentionally not requested. Firefox builds do not request `debugger`, do not advertise Deep Capture/Transform Gateway capabilities and show the Recorder/callable workflow instead. 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/).
|
||||
|
||||
+13
-5
@@ -1,6 +1,6 @@
|
||||
# Yakit Browser Agent Privacy Policy
|
||||
|
||||
Effective date: 2026-07-17
|
||||
Effective date: 2026-07-22
|
||||
|
||||
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.
|
||||
|
||||
@@ -13,7 +13,11 @@ Depending on the command the user selects and the grant scopes they enable, the
|
||||
- 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;
|
||||
- temporary business Traces covering page interactions, Fetch/XHR/Form/WebSocket/WebCrypto/CryptoJS and common transforms; bounded value previews require a separate sensitive scope;
|
||||
- document-bound recorded-call page functions that retain opaque function/key references without exporting key material;
|
||||
- during an explicitly armed Chromium Deep Capture, bounded call-frame names, source locations, `this` previews, and local/closure/module variable names, types and previews from the paused main document;
|
||||
- document-bound business-closure page functions that retain a selected in-scope function and receiver inside page memory, plus bounded invocation arguments and results when the user or granted engine executes them;
|
||||
- per-gateway local replay drafts containing the method, URL, headers, editable body and explicitly selected short sample used to validate a saved request or response transform;
|
||||
- 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.
|
||||
|
||||
@@ -30,20 +34,24 @@ The Native Host is a local transport to that loopback Yak Bridge. Bridge v3 stil
|
||||
## 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.
|
||||
- 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 and captured requests are session-scoped.
|
||||
- Per-document fingerprint seeds, retained function/key handles and page-callable function objects remain only in that document's page memory. Starting a new recording, clearing it, grant expiry/revocation or a hard reload destroys recorder handles. A document restored from the browser's Back/Forward Cache retains its own heap and can resume those handles; a newly loaded document cannot. Manual stop keeps created callables only for the current live document.
|
||||
- Recording previews are off by default and bounded when explicitly enabled. A live document keeps them in page memory. A user-started tab/frame recording may copy bounded document segments and navigation events to extension-only `storage.session`, allowing the Session to continue through login redirects without persisting values. There is at most one recording Session per target; it is removed by a new recording, explicit clear, tab close, or browser-session end. A document-bound Agent grant does not automatically continue recording into a new document. Session data is never written to persistent extension storage and never included in audit or AI request-analysis payloads.
|
||||
- Deep Capture status and bounded pause previews are session-scoped so a suspended Service Worker can still resume or detach the correct tab. The page auto-resumes after 45 seconds unless an open control surface explicitly extends the deadline. Detach, tab closure, grant replacement, expiry or revocation removes the owned debugger session state.
|
||||
- When the user explicitly generates and saves a Transform Gateway, the selected short sample and subsequent local-replay edits may be copied into a separate profile-and-direction-scoped `storage.local` draft. This draft is limited to 256 KiB, is not part of the portable profile, and is never included in Bridge/RPC calls, Yak or AI context, audit, diagnostics, or profile export. Request and response drafts are independent. The user can clear either draft, and deleting the gateway deletes both. Other paused scope values remain session-only and are not copied.
|
||||
- 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.
|
||||
The user selects the tab/frame, scopes and expiration for every Agent grant and can pause, resume or revoke it. Sensitive network fields, recording previews, callable execution, debugger read/control and program Eval each require separate controls or scopes. Deep Capture must be armed for a named crypto operation or request substring and pauses only the next match. Recording defaults to per-recording salted correlation fingerprints with no raw value preview. Cookie values are hidden by default. Exports are redacted by default. A Transform Gateway replay draft is visibly marked as local-only and can be cleared independently without deleting the gateway. 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.
|
||||
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. A grant cannot control a debugger session owned locally or by another grant. Pause status/keepalive/resume do not execute code in the paused page. 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.
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Yakit Browser Agent 产品与架构路线
|
||||
|
||||
> 状态：Phase 1-4 源码、构建、测试与审核产物已完成；仅剩外部账号、签名与商店人工审核
|
||||
> 更新时间：2026-07-17
|
||||
> 状态：Phase 1-4 生产基线已完成；前端密码通用化 Phase 3.2 的 G0-G3.5 已实施，G4-G5 按真实样本继续；外部分发仍受账号、签名与商店人工审核约束
|
||||
> 更新时间：2026-07-21
|
||||
> 适用仓库：`yaklang-chrome-extension`、Yak `common/browser`/`common/yak/yakurl` 与 Yakit 浏览器集成页
|
||||
|
||||
## 0. 2026-07-17 实施快照
|
||||
@@ -18,14 +18,14 @@
|
||||
- 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 分发、日志、结果、取消和错误回程；
|
||||
- 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 浮动工作台仅在展开时加载；
|
||||
- 常驻 content script 从约 480KB 降到 Store 约 11.1 KiB；React 浮动工作台仅在展开时加载；
|
||||
- Chrome Store/User Scripts 与 injected bridge 均通过真实 Chromium E2E；
|
||||
- 构建预算、商店执行策略和资源暴露策略已经加入自动审计。
|
||||
- content/background/MAIN world/总包体积继续作为可观测的参考指标，但不再阻断构建；商店执行策略、权限和资源暴露策略仍由自动审计硬性校验。
|
||||
- grant target 已绑定 `tabId + frameId + documentId + origin`，同源刷新返回 `stale_document`，跨来源导航返回 `origin_changed`；
|
||||
- Bridge 已支持 cancel、8 请求并发上限、重复 ID 拒绝、16 MiB 收发上限和断线清理；
|
||||
- 人工接管具备 `waiting_for_user -> completed/cancelled` 状态、三处 UI 提示和扩展到 Yak 的事件回程；
|
||||
@@ -40,13 +40,16 @@
|
||||
- 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 分析上下文已完成；
|
||||
- 交互/Fetch/XHR/Form/Beacon/WebSocket/Worker/SharedWorker/MessagePort/统一密码调用/转换独立 MAIN-world 录制器、业务 Trace、每次录制随机加盐的值关联、文档绑定页面函数、敏感值独立 scope、Yak PoC 与无值 AI 分析上下文已完成；密码调用已收敛为开放但有界的统一 `crypto` 协议和 adapter registry，覆盖 WebCrypto、CryptoJS、JSEncrypt、sm-crypto 与 node-forge；
|
||||
- Chromium `chrome.debugger` 深度捕获、一次性函数/请求断点、两阶段 stack/scope 采集、45 秒自动恢复、页面闭包运行时适配器与 Options/Yakit 工作台已完成；Firefox 明确不声明该能力；
|
||||
- 浏览器明文网关已完成：插件提供文档绑定的多步 request/response 页面函数链，Yak Web Fuzzer 在发送前加密/签名、响应后解密，Yakit 保持明文编辑并提供明文/线上报文对照；失败不会回退发送明文；
|
||||
- Cookie 三格式导入导出、UA 请求头边界、PAC 分流/认证/冲突/统计已完成；
|
||||
- Popup 已改为固定图标 rail：概览、代理、Cookie Editor、User-Agent 四个模块保持稳定位置；顶部仅保留 Yak SVG、当前页面和带 Tooltip 的引擎状态点。Cookie Editor 与 User-Agent 面向当前标签页提供快速操作：敏感值默认隐藏、显式显示、当前站点新增/编辑/删除 Cookie，以及内置/自定义 UA 预设的应用、刷新和恢复默认；Options 的“常用工具”分组承载完整 Cookie 清单、导入导出、CHIPS 属性、站点绑定和自定义预设管理；
|
||||
- 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 确定性包测试已完成。
|
||||
- Vitest 116 项、四渠道构建与 fixture 泄漏审计、Store/Enterprise Chromium E2E、Trace 精确/通道关联、跨页面录制与浏览器后退、停止后页面函数复跑、JSEncrypt RSA receiver 保真回放与 `form.data` 自动 Profile、真实 AES-GCM/HMAC 闭包捕获、AES + RSA 请求事务与独立服务端验签、自动共同祖先捕获与参数级明文网关、sm-crypto/node-forge 独立服务端验收、随机 ESM + WASM 闭包和 Worker holdout、明文网关双向转换与服务端验证、Service Worker 重启验证、Native Messaging v3 真实链路与 Yak Go 确定性包测试已完成。
|
||||
|
||||
外部发布动作不属于源码可自动完成的状态：开发者账号、签名证书、稳定隐私政策 URL、Windows/macOS/Linux 真机签名包、Chrome Web Store/AMO 上传、审查往返与批准。执行清单位于 `docs/store-review/RELEASE_CHECKLIST.md`。
|
||||
|
||||
@@ -56,11 +59,12 @@
|
||||
|
||||
- WXT、React、Chrome MV3 与 Firefox 构建链路已经建立；
|
||||
- Popup、Options 和网页悬浮面板使用统一的品牌与 UI 体系；
|
||||
- Popup 负责 1-2 步完成当前标签页的高频动作，Options 负责可搜索、可批量、可审计的深度管理；两者共用同一 runtime request map 和 background capability handler，不复制浏览器 API 逻辑；
|
||||
- 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、敏感网络与观测值分别授权；
|
||||
- 只读、表达式 Eval、程序 Eval、敏感网络、录制值预览、页面函数、调试读取/控制与页面函数执行分别授权；
|
||||
- 扫码、MFA、CAPTCHA 接管和 Agent 暂停/恢复/撤销已经形成可观察状态机；
|
||||
- 生产剩余风险已经收敛为外部签名、真机兼容与商店审核，而不是未实现的核心架构。
|
||||
|
||||
@@ -426,7 +430,7 @@ Frames and shadow roots
|
||||
Authentication signals
|
||||
Storage inventory
|
||||
Network request summary
|
||||
Crypto/signing observations
|
||||
Crypto/signing recording and page callables
|
||||
Relevant excerpts on demand
|
||||
```
|
||||
|
||||
@@ -454,7 +458,7 @@ captureId + documentId + frameId + nodeId
|
||||
|
||||
### 6.1 浏览器请求到 Yakit 工作流
|
||||
|
||||
浏览器请求到 Yakit 的生产链路已经闭环：`webRequest` 捕获 Fetch/XHR/Form navigation，用户显式开启敏感字段后生成 HTTP/1.1 重放包，并通过带回执的 Bridge 在 Yakit 中打开 Web Fuzzer、生成可运行 Yak PoC，或生成不含认证值的 AI 分析上下文。AI Agent 可结合附近的 WebCrypto/CryptoJS/WebSocket 观测分析鉴权、签名、重放和对象级越权风险。
|
||||
浏览器请求到 Yakit 的生产链路已经闭环：`webRequest` 捕获 Fetch/XHR/Form navigation，用户显式开启敏感字段后生成 HTTP/1.1 重放包，并通过带回执的 Bridge 在 Yakit 中打开 Web Fuzzer、生成可运行 Yak PoC，或生成不含认证值的 AI 分析上下文。AI Agent 可结合关联 Trace 中统一建模的 WebCrypto/CryptoJS/JSEncrypt/sm-crypto/node-forge 密码事件、Worker/MessagePort 通道和 WebSocket 事件分析鉴权、签名、重放和对象级越权风险。
|
||||
|
||||
优先完成：
|
||||
|
||||
@@ -468,18 +472,31 @@ captureId + documentId + frameId + nodeId
|
||||
|
||||
这是浏览器插件与 Yakit 结合最直接的产品价值。
|
||||
|
||||
### 6.2 前端加密与签名观测
|
||||
### 6.2 浏览器现场、前端加密与页面函数
|
||||
|
||||
在明确授权期间临时观测：
|
||||
这部分不再是平铺的 Hook 日志，而是围绕一次真实业务操作组织：
|
||||
|
||||
- `fetch` / XHR；
|
||||
- WebSocket；
|
||||
- `crypto.subtle`；
|
||||
- 常见 CryptoJS；
|
||||
- 请求签名前后的字段；
|
||||
- 调用栈和脚本来源。
|
||||
```text
|
||||
点击 / 提交
|
||||
-> 业务 Trace
|
||||
-> 页面转换 / WebCrypto / CryptoJS / JSEncrypt / sm-crypto / node-forge
|
||||
-> Fetch / XHR / WebSocket
|
||||
-> 精确值关联
|
||||
-> 保留页面调用句柄
|
||||
-> 用新输入验证页面函数
|
||||
```
|
||||
|
||||
上述能力已经通过独立 WXT MAIN-world entrypoint 落地。观测器使用最多 200 条的有界 ring buffer，默认只记录算法、方向、大小、调用栈和脚本来源；短时值预览需要独立敏感 scope，授权到期、撤销或用户停止时恢复原始页面 API 并销毁预览。
|
||||
独立 `page-recorder-main-world.js` 已覆盖 click/submit、Fetch/XHR/Form/Beacon、WebSocket、Worker/SharedWorker/MessagePort、统一密码 adapter 和 Base64 编解码。WebCrypto、CryptoJS、JSEncrypt、sm-crypto 与 node-forge 不再是不同事件类型，而是使用同一 `crypto` envelope；库、算法族、调用名、padding、编码、状态 phase/correlation 和有界 key 元数据由 adapter 提供。默认不返回原始值，只发送路径、大小、编码和每个文档随机加盐的指纹；早期输出和后续输入指纹相同才建立 `exact` link，跨异步消息只建立明确标注的 `correlated` channel link。短时值预览需要 `browser.recording.sensitive.read`，单值最多 8 KiB。用户发起的录制现在是标签页/Frame 级 Session：完整跳转、刷新、历史前进后退、SPA History 与 fragment 都成为 Trace 事件；旧文档片段封存在扩展专属 `storage.session`，新文档观察器沿用 Session 身份和全局顺序继续录制。该 Session 不进入持久化存储、审计或 AI 请求分析，并在新录制、清空、标签页关闭或浏览器会话结束时删除。
|
||||
|
||||
满足 replay eligibility 的一次调用会保留原函数、receiver、参数模板和页面内 key 对象的 opaque handle；状态型/流式调用默认作为证据，引导捕获其上层一次性业务闭包。JSEncrypt、sm-crypto 与 node-forge 只公开密钥类型、位数和本次录制加盐指纹，不导出 PEM、私钥、模数或实例。handle 同时受数量、单条 2 MiB 和总计 8 MiB 预算约束，超限调用保留元数据但不成为 callable。录制调用与深度捕获闭包都注册为统一 `BrowserPageCallable`，`browser.callable.*` 不导出密钥，只允许在同一 live document 中使用显式参数槽调用。手动停止录制会恢复页面 API，但 callable 仍可验证；完整导航后 callable 属于历史文档，BFCache 恢复时可重新使用，硬刷新或新文档则会真实销毁闭包。Grant 拥有的录制不会跨文档自动扩权。
|
||||
|
||||
Options 与 Yakit 都使用 Session -> Trace -> 执行链/证据/页面函数的三列工作台。录制时间线与执行卡片统一为从早到晚，编号和相对时间表达执行顺序，精确值关联使用独立视觉语义，跳转卡片承担文档边界。Yakit 不新增成组 gRPC 接口，而是通过 `ExecuteBrowserExtensionTask` 的 `capability.call` schema 调用 `browser.recording.*`、`browser.callable.*` 和 `browser.transform.*`。
|
||||
|
||||
生产级深度模式不把低层 WebCrypto primitive 当成最终能力。用户从 Trace 选择自动推断候选，插件比较多个密码来源的有界调用栈，寻找最近共同页面祖先，并通过 Chromium CDP 在最早仍保留业务栈的真实调用处暂停。后台用真实 script/function location、作用域绑定和副作用门禁唯一解析业务 frame：纯业务函数以 `selected-frame` 保存；如果该函数同时读 DOM、组装多密码字段并发出请求，则以 `request-transaction` 保留，回放时在页面内映射新明文、拦截唯一目标请求、校验预期输出并回滚 DOM，不会因为浅层副作用检查而误选外层 `onclick`。函数表达式只作为歧义场景的高级入口；暂停作用域默认只存在于当前会话，不进入 Bridge、审计或 Profile。只有用户明确生成并保存明文网关后，被选中的短时样本才会复制到 `profileId + direction` 关联的本机私有回放草稿；该草稿不进入 Bridge、Yak/AI、诊断或导出。页面恢复后，Options、Yakit 或 Yak 可用新 JSON 参数重复调用。
|
||||
|
||||
暂停控制面只依赖 grant 身份、`webNavigation`、session 状态和 CDP，不向已暂停页面执行脚本。UI 持续 keepalive，失去控制面后 alarm 在 45 秒自动恢复页面。`browser.debugger.read`、`browser.debugger.control` 和 `browser.callable.execute` 独立授权；grant 替换、过期、撤销和标签页关闭释放其拥有的会话。完整设计和边界见 `docs/DEEP_CAPTURE_ARCHITECTURE.md`。
|
||||
|
||||
真实验收夹具使用闭包内不可导出的 AES-GCM/HMAC key、动态 timestamp/nonce/IV、本地 `buildLoginEnvelope` 与 `openLoginResponse` 业务函数。只有捕获请求与响应闭包后，用新账号/密码生成不同随机参数，通过服务端验签解密，并将服务端密文响应还原为明文 JSON，才算完成；字符串 hash mock 不算深度能力验收。
|
||||
|
||||
### 6.3 登录态工作区
|
||||
|
||||
@@ -542,16 +559,22 @@ completed / cancelled / expired
|
||||
|
||||
完整设备指纹伪装不属于当前插件承诺；如果未来引入，必须作为独立能力重新设计 scope、页面注入生命周期和浏览器兼容测试，不能与单一 UA header 规则混为一谈。
|
||||
|
||||
### 代理规则
|
||||
### 代理与自动切换
|
||||
|
||||
- [已完成] 优先级与拖动排序；
|
||||
- [已完成] 冲突检测；
|
||||
- [已完成] 当前 URL 命中预览；
|
||||
- [已完成] PAC 编译结果查看；
|
||||
- [已完成] 代理出口、自动切换、规则订阅三个稳定工作区；
|
||||
- [已完成] 结构化 host/URL 条件、手动规则与订阅源的确定性顺序；
|
||||
- [已完成] AutoProxy/GFWList、SwitchyOmega Conditions、域名与 hosts 列表解析；
|
||||
- [已完成] GitHub blob 转 raw、ETag/Last-Modified、定时更新、失败保留上一可用 revision；
|
||||
- [已完成] IndexedDB 512 条分块、分页读取、流式搜索与八份 PAC artifact 上限；
|
||||
- [已完成] host exact/suffix 共享 trie、正则慢路径预编译、4 MB PAC 安全预算和 50,000 域名回归测试；
|
||||
- [已完成] 当前 URL 路由解释、Popup 将当前 hostname 指定到任意固定出口或恢复自动判断、全局模式与站点规则分层、悬浮面板快切；
|
||||
- [已完成] 编译、浏览器应用与运行态提交串行化，过期下载结果丢弃；
|
||||
- [已完成] 代理认证，用户名持久化、密码仅保存在浏览器 session；
|
||||
- [已完成] JSON 导入导出，不包含代理密码；
|
||||
- [已完成] 有界 JSON 导入导出，不包含代理密码；
|
||||
- [已完成] 默认出口和 fail-open/fail-closed 行为；
|
||||
- [已完成] 规则命中统计。
|
||||
- [已完成] 移除每请求规则命中统计，PAC 成为唯一请求热路径。
|
||||
|
||||
详细不变量与性能边界见 `docs/PROXY_ARCHITECTURE.md`。
|
||||
|
||||
## 8. UI/UX 改进
|
||||
|
||||
@@ -608,13 +631,16 @@ src/
|
||||
options/
|
||||
agent.content/
|
||||
page-main-world.ts
|
||||
page-recorder-main-world.ts
|
||||
|
||||
features/
|
||||
proxy/
|
||||
cookies/
|
||||
identity/
|
||||
page-context/
|
||||
page-observation/
|
||||
browser-recording/
|
||||
deep-capture/
|
||||
browser-transform/
|
||||
network-capture/
|
||||
grants/
|
||||
handoff/
|
||||
@@ -652,6 +678,8 @@ src/
|
||||
- [已完成] Bridge envelope、extension RequestMap 与 managed policy validation；
|
||||
- [已完成] Grant scope/策略判断与 expression/program Eval serializer；
|
||||
- [已完成] Cookie URL/脱敏交换与 UA DNR 规则生成。
|
||||
- [已完成] Deep Capture matcher、adapter 参数上限与 Chromium/Firefox capability 声明。
|
||||
- [已完成] Transform profile/path/output schema、多步映射、路由匹配、原型链与 Header 注入拒绝。
|
||||
|
||||
### 协议测试
|
||||
|
||||
@@ -660,6 +688,8 @@ src/
|
||||
- [已完成] 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，只有不可交互的临时测试副本预授权）。
|
||||
- [已完成] debugger read/control/adapter 独立 scope、会话所有权、暂停期无页面脚本控制面与 grant 撤销清理。
|
||||
- [已完成] transform read/manage/execute 独立 scope、profile target 越权、Web Fuzzer request/response hook 顺序与 fail-closed。
|
||||
|
||||
### 浏览器 E2E
|
||||
|
||||
@@ -667,6 +697,8 @@ src/
|
||||
- [已完成] Firefox MV2 injected 与 Firefox MV3 AMO invoke-only 构建/静态策略审计；
|
||||
- [已完成] CSP 严格页面、SPA、同源/跨源 iframe 与 open Shadow DOM；
|
||||
- [已完成] 页面伪造消息不扩权、Service Worker 停启保留 session、标签页关闭/导航 Eval fail-closed；
|
||||
- [已完成] WebCrypto 函数调用断点、业务 frame/scope、闭包适配器动态 nonce/IV 与服务端 HMAC/AES-GCM 验证；
|
||||
- [已完成] 明文登录请求经 document-bound profile 转为不含明文的动态线上报文，并通过独立服务端 HMAC 验签与 AES-GCM 解密；服务端 AES-GCM 密文响应经页面闭包还原；路径不匹配与隐式跨 Origin 调用失败关闭；
|
||||
- [已完成] 320px、390px 和桌面视口 UI、面板边界与资源像素/加载检查。
|
||||
|
||||
当前容器没有 Firefox 可执行程序或 macOS/Windows 环境；Firefox 真机安装、AMO 签名包和三平台 Native Host 签名属于 `RELEASE_CHECKLIST.md` 的外部发布门禁，不能用 Chromium 模拟结果冒充通过。
|
||||
@@ -698,10 +730,60 @@ src/
|
||||
- [已完成] frame/document/node 引用与显式跨 frame 授权；
|
||||
- [已完成] open Shadow DOM；
|
||||
- [已完成] IndexedDB/CacheStorage inventory；
|
||||
- [已完成] Fetch/XHR/Form/WebSocket/WebCrypto/CryptoJS 有界观测与独立敏感 scope；
|
||||
- [已完成] 交互/Fetch/XHR/Form/Beacon/WebSocket/Worker/SharedWorker/MessagePort/统一 `crypto` 事件有界录制、Trace/value/channel link 与独立敏感 scope；WebCrypto、CryptoJS、JSEncrypt、sm-crypto、node-forge 通过同一 adapter contract 接入；
|
||||
- [已完成] 标签页级录制 Session：登录跳转、刷新、历史前进后退与 SPA 路由成为有序 Trace 事件，新文档自动接续；BFCache 恢复旧函数现场，硬加载保留证据并准确标记闭包失效；
|
||||
- [已完成] 文档绑定页面函数创建、停止后复跑、刷新/撤销失效与 Options/Yakit 专用工作台；
|
||||
- [已完成] Options/Yakit 页面函数生命周期管理：统一列出来源、引用数量、删除影响与二次确认；
|
||||
- [已完成] Chromium Deep Capture、45 秒 watchdog、两阶段 stack/scope、业务闭包 callable 与 Options/Yakit 同构工作台；
|
||||
- [已完成] Deep Capture 为插件 Hook、页面函数和依赖库标记来源，默认选择页面业务帧，并支持点击展开有界作用域值/函数源码；
|
||||
- [已完成] Browser Transform Gateway：Pipeline v2 有序 DAG、多参数、多输出请求与响应转换、并发门控、Bridge 能力、Yak Web Fuzzer 原生数据面、Yakit 配置与明文/线上对照；
|
||||
- [已完成] 登录态工作区；
|
||||
- [已完成] Cookie、UA 请求头边界和代理规则完善。
|
||||
|
||||
### Phase 3.1：自动推断 Profile 与 AI 浏览器协作
|
||||
|
||||
- [已完成] WebCrypto / CryptoJS / JSEncrypt / sm-crypto / node-forge 参数角色、请求字段、exact value link 与 state correlation 形成统一推断证据；
|
||||
- [已完成] JSEncrypt RSA 保留真实实例 receiver 与固定参数，只公开 key 类型、位数和加盐指纹；单字段 exact link 可直接生成 Form/JSON/Header/Query 明文网关；
|
||||
- [已完成] AES/RSA/HMAC 等多个密码输出进入同一请求时合并为 request-level candidate，界面逐项展示目标字段并要求捕获上层业务 callable，避免拆分后破坏随机 key/IV/nonce 一致性；
|
||||
- [已完成] 高置信度候选在 Options / Yakit 展示证据、参数语义与缺失步骤，并可一键武装对应的深度捕获入口；
|
||||
- [已完成] 页面录制调用与深度捕获闭包合并为统一 Page Callable，不保留旧模型迁移或方法别名；
|
||||
- [已完成] Pipeline v2 使用类型化 context.read / builtin / page.call / output.write 节点，节点只能引用前序结果；
|
||||
- [已完成] JSON、FormData、URLSearchParams、form-urlencoded 与 query 建立通用字段级证据，不依赖站点 URL 或字段名称；
|
||||
- [已完成] 单条精确值链且保留调用句柄的已知加密调用可从一次录制直接生成可解释候选；
|
||||
- [已完成] Options 与 Yakit 默认使用“明文来源 → 页面能力 → 线上目标”三步引导，自动编译 form.compose、字段名、Content-Type 与底层引用；
|
||||
- [已完成] 自动把录制短时样本带入明文网关本地回放，并允许一键恢复原样本；保存网关后按 Profile/请求响应方向自动保存本机私有草稿，切换工作区或目标标签页可恢复，删除网关联动清理，且草稿不进入 Bridge、Yak/AI、诊断或导出；
|
||||
- [已完成] 多来源同步栈推断共同业务祖先，一键以后台可信 `selected-frame` 捕获完整闭包；参数名自动形成字段级 Body 映射，完整暂停作用域保持非持久化，只有用户明确保存网关时选中的短时样本可进入有界本机私有草稿；
|
||||
- [已完成] 共同业务祖先直接负责 DOM 取值与发包时自动生成 `request-transaction`，严格拦截 method/URL、保留混淆后的固定 URL 参数，并以 AES + RSA 真实服务端验签、零浏览器请求泄漏验收；
|
||||
- [待完成] 为页面内回放生成确定性或结构性断言；
|
||||
- [已完成] 低层加密调用或未知请求/消息边界可一键进入业务 frame 捕获，确定性排序页面闭包并保留完整 envelope / signature callable；
|
||||
- [待完成] Yakit AI ReAct 使用 task-bound `browser_session` 附加资源和领域工具读取页面、分析候选、驱动捕获；
|
||||
- [待完成] AI 只能返回引用现有 evidence 的候选补丁，不能直接发布任意代码；
|
||||
- [待完成] 混淆 CryptoJS、不可导出 WebCrypto key、刷新重捕获与 AI 候选补丁夹具。
|
||||
|
||||
完整设计见 `docs/AUTO_PROFILE_INFERENCE_ARCHITECTURE.md`。
|
||||
|
||||
### Phase 3.2：前端密码能力通用化
|
||||
|
||||
当前统一 `crypto` event、Evidence Graph、Page Callable 与 request-level Profile compiler 已通过 global、真实 minified bundle、随机 ESM closure、Worker 和 WASM 外围业务 wrapper 验收。已知库 adapter 负责增强语义；算法未知时，请求/消息边界和业务 callable 恢复仍是最低保证。
|
||||
|
||||
本阶段将已知库 adapter 定义为语义加速器，把请求/消息边界与业务 callable 恢复定义为最低保证：
|
||||
|
||||
- [已完成] 记录 recorder 关闭/1,000 次小调用/10 次 1 MiB 调用/预算耗尽性能与 93 项测试基线，并加入生产源码 fixture leakage 审计；
|
||||
- [已完成] 删除封闭 provider 枚举和展示字符串函数匹配，改为有界 `adapterId + providerKind + operation + wrapperHandleId + state model`；
|
||||
- [已完成] 从 MAIN-world recorder 拆出 adapter registry、五个独立 adapter、通信边界和 retained-call 双预算基础设施，不保留旧 adapter 分支；
|
||||
- [待完成] 继续把 Fetch/XHR/Form/WebSocket、evidence/trace 与编码运行时从 MAIN-world 编排入口物理拆开；该项只改善维护边界，不阻塞已经通过的运行时通用性验收；
|
||||
- [已完成] WebCrypto、CryptoJS、JSEncrypt 迁移到同一独立 adapter contract，不保留旧分支；
|
||||
- [已完成] 增加 sendBeacon、Worker、SharedWorker、MessagePort 边界和有界同步/异步来源；
|
||||
- [已完成] 从未知请求/消息边界自动排序页面业务 frame，并允许在算法未命名时捕获完整 closure callable；
|
||||
- [已完成] 第一批高价值 adapter：sm-crypto 的 SM2/SM3/SM4 与 node-forge 的 RSA/digest/HMAC/stateful cipher；
|
||||
- [待完成] 第二批 adapter：jsrsasign 与 jose；后续按真实样本推进 libsodium.js、TweetNaCl、noble 和 OpenPGP.js；
|
||||
- [待完成] serializer/compression 使用独立 transform evidence 接入 Axios interceptor、protobuf、MessagePack 与 pako，不伪装成密码调用；
|
||||
- [已完成] 使用随机 URL、字段和函数名的 global/minified bundle/ESM closure/Worker/WASM holdout，已发布 callable 由独立服务端解密、验签或校验；
|
||||
- [已完成] 没有专用 adapter 的 ESM + WASM holdout 仅靠通用 WebCrypto 边界、业务 frame 排序和 closure 恢复完成服务端认可的重放；
|
||||
- [已完成] 录制停止后无 wrapper/timer/listener/channel context 残留，活跃录制的 CPU、输入大小、事件数和 retained memory 进入真实浏览器回归门禁。
|
||||
|
||||
实施顺序固定为“adapter host 与协议 -> 通用边界与未知函数 -> sm-crypto/node-forge -> 其余语义 adapter”。不得用继续堆叠库名称代替通用能力。完整决策、协议草案、目录设计、库优先级、测试矩阵和完成定义见 `docs/FRONTEND_CRYPTO_GENERALIZATION_ROADMAP.md`。
|
||||
|
||||
### Phase 4：分发与运营
|
||||
|
||||
- [已完成] Native Host 可执行程序、framing proxy、Chrome/Firefox argv 来源校验、Linux/macOS/Windows 安装器与 Chromium 真实传输 E2E；
|
||||
@@ -723,6 +805,9 @@ src/
|
||||
- User Scripts 未开启时给出明确降级和开启路径；
|
||||
- Agent 默认使用 structured commands，Eval 是最后手段；
|
||||
- 用户能看见、暂停、恢复和撤销 Agent 对浏览器的操作；
|
||||
- 深度捕获命中后控制面立即可见，不依赖暂停页面执行脚本，控制面丢失时页面在 45 秒内自动恢复；
|
||||
- 默认不记录或导出 Cookie、token、Eval 参数和页面正文；
|
||||
- Chrome Store、Enterprise User Scripts 与 Enterprise injected fallback 关键路径有真实 Chromium E2E；Firefox 真机安装/运行是发布前外部门禁，不能由 Chromium 或静态审计替代；
|
||||
- 前端加密深度能力必须通过不可导出 key、动态参数和服务端验签/解密的真实夹具，不能用固定字符串 mock 代替；
|
||||
- Web Fuzzer 启用浏览器明文网关后，request transform 任何失败都不得发送明文；UI 必须分别保留逻辑明文与实际线上报文；
|
||||
- Native Host 与 Yakit 实例身份、版本和连接状态可信。
|
||||
|
||||
@@ -0,0 +1,115 @@
|
||||
# Proxy Routing Architecture
|
||||
|
||||
> Status: production baseline, 2026-07-18
|
||||
|
||||
## Product boundary
|
||||
|
||||
The proxy workspace solves three browser-level tasks:
|
||||
|
||||
1. maintain reusable proxy endpoints;
|
||||
2. select an endpoint directly or through deterministic automatic routing;
|
||||
3. consume large community rule lists without moving list traversal into the request path.
|
||||
|
||||
`Yakit MITM` is a built-in HTTP proxy endpoint. The extension can route a site to it, but does not start, stop, configure, or introspect Yak MITM. MITM traffic policy remains owned by Yak/Yakit. This keeps browser routing independent from engine lifecycle and still allows the extension rules to act as an inexpensive upstream filter.
|
||||
|
||||
## Runtime model
|
||||
|
||||
```text
|
||||
Options / Popup / floating panel
|
||||
|
|
||||
| typed runtime request + Valibot validation
|
||||
v
|
||||
Background proxy service
|
||||
|
|
||||
+-- settings.proxy.v1
|
||||
| endpoints, manual rules, source summaries, runtime state
|
||||
|
|
||||
+-- IndexedDB: yakit-proxy-rules
|
||||
| source revisions, 512-rule chunks, compiled PAC artifacts
|
||||
|
|
||||
+-- compiler
|
||||
| manual branches + source host tries + precompiled regex slow path
|
||||
v
|
||||
browser.proxy.settings
|
||||
|
|
||||
v
|
||||
FindProxyForURL(url, host)
|
||||
```
|
||||
|
||||
IndexedDB is not queried by `FindProxyForURL`. It is an asset repository for download, editing, search, paging, export, and compilation. The browser receives one immutable PAC snapshot, so a request never waits for extension messaging, storage, React, or a service worker wake-up.
|
||||
|
||||
## Routing order
|
||||
|
||||
Automatic routing has one explicit order:
|
||||
|
||||
1. enabled manual rules, ordered by `order`;
|
||||
2. enabled rule sources, ordered by `order`;
|
||||
3. the configured default endpoint.
|
||||
|
||||
Within a source without custom SwitchyOmega results, exclusion rules are evaluated before positive rules. A source exclusion uses `bypassProfileId`; a positive rule uses `matchProfileId`. SwitchyOmega lists with `@with result` retain file order and resolve `+name` against an endpoint ID or display name. An unknown or non-routable result is an application error, never a silent fallback.
|
||||
|
||||
Only `direct` and `fixed_servers` endpoints may be automatic-routing results. `system` and external `pac_script` profiles can be selected directly, but cannot be nested inside the generated PAC.
|
||||
|
||||
## Supported source formats
|
||||
|
||||
- AutoProxy and base64-encoded GFWList syntax, including `@@` exclusions;
|
||||
- SwitchyOmega Conditions, including typed host/URL wildcard and regex conditions plus `@with result`;
|
||||
- plain domain lists;
|
||||
- hosts files with IPv4/IPv6 followed by one or more hostnames.
|
||||
|
||||
Auto detection is intentionally conservative. Unsupported cosmetic Adblock rules are ignored and counted. Invalid domains and regular expressions are reported with bounded diagnostics. A downloaded revision with zero usable rules is rejected.
|
||||
|
||||
GitHub `/blob/` URLs are converted to `raw.githubusercontent.com`. Updates use `ETag` and `Last-Modified` validators, run on a 30-minute browser alarm, and honor each source's update interval. A source is limited to 10 MB.
|
||||
|
||||
## Storage and memory
|
||||
|
||||
`source-revisions` stores the original decoded content and metadata. `rule-chunks` stores normalized rules in 512-item chunks indexed by source and revision. Normal paging reads only intersecting chunks. Search streams chunks with an IndexedDB cursor and retains only the requested result page in memory.
|
||||
|
||||
`compiled-artifacts` caches PAC output by a deterministic configuration revision. Only the eight newest artifacts are retained. Source updates are staged under a new revision; the old revision remains referenced until parse, compile, browser application, and state commit succeed. Obsolete revisions are pruned after a successful commit.
|
||||
|
||||
Configuration exchange includes source content for reproducibility, excludes proxy passwords, limits each source to 10 MB, and limits aggregate embedded source content to 25 MB.
|
||||
|
||||
## PAC compiler
|
||||
|
||||
Manual rules are expected to stay small and compile to ordered conditions. Large host-exact and host-suffix source rules compile into reversed-label tries shared by result group. URL wildcard and regex rules are created once as top-level `RegExp` objects rather than reconstructed per request.
|
||||
|
||||
The generated artifact is rejected above 4 MB. It warns above 1 MB or when more than 1,000 conditions enter the regex slow path. Regular expressions are compiled and validated before `browser.proxy.settings` changes.
|
||||
|
||||
The regression suite compiles and executes a 50,000-domain source. This protects the central performance property: large domain lists add trie data, not 50,000 sequential `if` statements and not 50,000 extension-side listeners.
|
||||
|
||||
## Atomicity and failure behavior
|
||||
|
||||
All state mutations use the shared background mutation queue. Applying automatic routing compiles from the exact state held inside that queue, changes `browser.proxy.settings`, and commits the matching runtime revision before the next edit can enter.
|
||||
|
||||
A rule-source response is discarded if its URL or format changed while the request was in flight. Download, parse, compile, PAC-size, endpoint-resolution, and browser-API failures leave the preceding source revision and live PAC in place. The UI exposes the error and labels the source as using its previous version.
|
||||
|
||||
Deleting an active fixed endpoint is rejected. Saving an active endpoint reapplies it immediately. Import switches the browser and state to direct mode together; imported automatic rules remain explicitly dirty until the user applies them.
|
||||
|
||||
## Browser limitations
|
||||
|
||||
Chrome may pass only scheme, hostname, and port to PAC for HTTPS URLs. Host conditions are therefore the reliable default. URL path, query, keyword, and regex conditions remain available for HTTP and browser-dependent cases, and the editor displays this limitation beside URL conditions.
|
||||
|
||||
Proxy authentication credentials are separate from durable settings. Usernames are part of an endpoint; passwords live in `storage.session` and an in-memory cache. `onAuthRequired` selects credentials by proxy challenger host and port. No request-level rule hit collector is installed.
|
||||
|
||||
## UI ownership
|
||||
|
||||
- Popup: see the live mode, explain the current site's route, assign the exact current hostname to any Direct/HTTP(S)/SOCKS/Yakit MITM endpoint, restore subscription/default routing, and switch the browser's global mode independently.
|
||||
- Options / Proxy endpoints: maintain Direct, System, fixed HTTP(S)/SOCKS, PAC, bypass, and session authentication settings.
|
||||
- Options / Automatic routing: inspect applied/dirty state, choose defaults, explain a URL, edit and reorder manual rules, and view compilation metrics.
|
||||
- Options / Rule subscriptions: add, update, enable, reorder, search, page, import, and export rule sources.
|
||||
- Floating panel: switch to automatic routing or a fixed endpoint without loading the management workspace.
|
||||
|
||||
These surfaces share the same runtime request handlers. There is no UI-only proxy implementation.
|
||||
|
||||
## Verification
|
||||
|
||||
Required checks for changes to this subsystem:
|
||||
|
||||
```bash
|
||||
pnpm compile
|
||||
pnpm test
|
||||
pnpm build
|
||||
pnpm verify:ui
|
||||
```
|
||||
|
||||
Unit tests cover condition families, real PAC execution, exclusions, source-result validation, parser formats, and 50,000-domain compilation. Browser E2E verifies runtime schemas, direct mode, deterministic reorder/preview, fail-open PAC output, session authentication, automatic application, screenshots, and service-worker recovery.
|
||||
@@ -2,7 +2,13 @@
|
||||
|
||||
## 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.
|
||||
Yakit Browser Agent provides consent-gated browser context, frontend-crypto analysis and request workflows for authorized security testing with a local Yak/Yakit engine. Cookie, proxy, UA, browser-recording, Chromium Deep Capture and request tools support that single authenticated-browser testing workflow; they do not provide unrelated browsing, advertising or content features.
|
||||
|
||||
## Debugger permission
|
||||
|
||||
Chromium packages request `debugger` for an explicit Deep Capture workflow. The extension attaches only after the user or a separately scoped local-engine grant arms one named crypto operation or request substring. It installs a one-shot function/XHR breakpoint, publishes bounded call-frame/scope previews, and lets the user retain one in-scope function as a current-document page callable. The page automatically resumes after 45 seconds without keepalive. Grant expiry/revocation, tab closure and explicit detach release the session. Firefox packages do not request or advertise this capability.
|
||||
|
||||
No browsing session is debugged continuously, no traffic is intercepted through CDP in this phase, and key objects/function closures remain inside the target document.
|
||||
|
||||
## Remote code policy
|
||||
|
||||
@@ -18,7 +24,7 @@ Chrome's MV3 policy names User Scripts as an API permitted to execute remote log
|
||||
|
||||
## 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).
|
||||
The listing and privacy form must disclose authentication information, browsing activity, website content, Cookie/storage data, request data and local Native Messaging transmission. A user-saved Transform Gateway may keep a bounded, independently clearable plaintext replay draft in extension-local storage; that draft is not included in Bridge/Yak/AI traffic, diagnostics, audit or profile export. 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
|
||||
|
||||
@@ -29,7 +35,9 @@ The listing and privacy form must disclose authentication information, browsing
|
||||
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.
|
||||
8. Record one real WebCrypto operation, choose Deep Capture, arm the selected operation and repeat it. Verify the page visibly pauses, a business frame/scope appears, and **仅恢复页面** immediately releases it.
|
||||
9. Capture an in-scope function, run it with a new JSON argument, then reload the page and verify its document-bound callable is gone.
|
||||
10. Inspect the Store artifact: no `page-main-world.js`, no `activeTab`, `debugger` is present only in Chromium, and `nativeMessaging` is optional.
|
||||
|
||||
Automated equivalent: `pnpm verify:ui:store`.
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
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.
|
||||
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`. Firefox packages also do not request Chromium's `debugger` permission or advertise Deep Capture/business-closure capabilities. They retain structured context, document-bound node commands, request capture, browser recording and recorded-call page functions, Cookie/UA/proxy tools and human handoff. Local or enterprise Firefox builds can use the injected page-execution adapter outside the public AMO channel, but Deep Capture remains Chromium-only.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
@@ -8,7 +8,8 @@ The extension's use of this data complies with the following commitments:
|
||||
- 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.
|
||||
- Sensitive request fields and recording previews are off by default. Page-callable execution, debugger read/control and program Eval have separate high-risk scopes. Deep Capture is one-shot and auto-resumes after 45 seconds without an active control surface. Cookie exports are redacted by default.
|
||||
- After the user explicitly saves a Transform Gateway, its bounded plaintext replay draft may remain in extension-local storage for that profile and request/response direction. It is visibly local-only, independently clearable, deleted with the profile, and excluded from Bridge/Yak/AI messages, diagnostics, audit and profile export.
|
||||
- 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/).
|
||||
|
||||
Reference in New Issue
Block a user