dsh-js-reverse-plugin 0.1.0

package/skills/js-ast-deobfuscation/references/validation-contract.md

@@ -0,0 +1,604 @@
+# 验收契约
+
+模型分析在被验证前只是候选解释。每个准备步骤、transform 和动态结论都必须按其产物类型与证据模式验收。
+
+本文件主要负责当前已选步骤的单步 transform、动态证据、A/B、确定性、停止和关闭验收；G1～G4 章节只供后续审计准备证据或恢复异常状态，普通首轮不读取本文。方法与范围必须由入口阶段先行确定；本文不继续加载其他 reference。
+
+## 目录
+
+- [1. 验收记录的共同字段](#1-验收记录的共同字段)
+- [2. G1：冻结原始输入](#2-g1冻结原始输入)
+- [3. G2：Prettier 格式化派生副本](#3-g2prettier-格式化派生副本)
+- [4. G3：完整直读验收](#4-g3完整直读验收)
+- [5. G4：首轮画像验收](#5-g4首轮画像验收)
+- [6. 产物类型](#6-产物类型)
+- [7. Transform 执行前契约](#7-transform-执行前契约)
+- [8. Transform 通用验收](#8-transform-通用验收)
+- [9. 高风险变换的附加验收](#9-高风险变换的附加验收)
+- [10. 动态证据验收](#10-动态证据验收)
+- [11. 无 probe / 有 probe A/B](#11-无-probe--有-probe-ab)
+- [12. 确定性与可重放性](#12-确定性与可重放性)
+- [13. 验收失败分流](#13-验收失败分流)
+- [14. 单步报告](#14-单步报告)
+- [15. 关闭与交接验收](#15-关闭与交接验收)
+- [16. 最终自检](#16-最终自检)
+
+## 1. 验收记录的共同字段
+
+所有验收记录使用真实执行值，不保留模板占位符。
+
+至少包含：
+
+```text
+question_id / step_id
+日期与执行者
+输入、输出、transform 路径与 hash
+原始目标路径与 hash
+用户批准范围
+证据模式
+产物类型
+执行命令与退出状态
+工具及精确版本
+Observed / Inferred / Unknown
+风险与明确未证明结论
+验收状态
+```
+
+验收状态只能是：
+
+```text
+PASS
+FAIL
+BLOCKED
+NOT_APPLICABLE（必须说明原因）
+```
+
+不能用“看起来没问题”“应该安全”代替证据。
+
+## 2. G1：冻结原始输入
+
+G1 通过前不得修改或覆盖原始输入。
+
+记录：
+
+```text
+原始路径
+文件大小
+原始 hash
+来源
+语法模式
+换行与编码信息
+隔离工作区
+原始运行目标
+格式化与后续派生视图位置
+```
+
+验收：
+
+- 原始路径可定位。
+- hash 使用明确算法并保存完整值。
+- 派生工作区不与原始路径混淆。
+- 后续运行目标与分析视图角色已区分。
+- 复制后再次核对原始 hash。
+- 报告中不存在“将在原文件上直接格式化或插桩”的步骤。
+
+需要行为证据时，优先使用固定 hash 的原始目标。使用其他执行副本时必须单独声明。
+
+## 3. G2：Prettier 格式化派生副本
+
+Prettier 只生成阅读与 AST 分析副本，不提供语义正确证明。
+
+### 3.1 工具验收
+
+记录：
+
+```text
+Node 版本
+包管理器与版本
+Prettier 安装位置和精确版本
+package.json 与锁文件
+配置文件
+parser
+完整格式化命令
+退出状态
+```
+
+要求：
+
+- 复用可追溯的项目本地版本，或在案例工作区本地安装。
+- 不依赖未记录的全局 Prettier。
+- 不因缺失 Prettier 静默改用其他 formatter。
+- 不把安装选择转嫁给用户。
+
+### 3.2 输入输出验收
+
+记录：
+
+```text
+格式化输入路径与 hash
+格式化输出路径与 hash
+原始 hash 格式化前后校验
+输出 parse 结果
+parser 尝试与错误
+```
+
+要求：
+
+- 只格式化派生副本。
+- 原始文件 hash 保持不变。
+- 格式化输出能够由声明 parser 重新解析。
+- 格式化失败时不通过补括号、删语句或改原文越过硬门。
+
+Node、包管理器、Prettier 或正确候选 parser 均不可用时，状态为 `FORMAT_BLOCKED`。必须保留原始 hash、尝试命令、工具版本、错误位置和最小解决方向。
+
+若样本存在 self-defending、源码文本校验或 hash 校验，格式化副本仍只供分析；行为证据继续指向固定 hash 的原始目标。
+
+## 4. G3：完整直读验收
+
+必须按连续区间直接读取完整的格式化 JavaScript，不能只看开头、中段和结尾。
+
+阅读记录至少包含：
+
+```text
+文件总行数或总字节数
+连续阅读区间
+区间之间的空白及原因
+入口、导出和公开 API 锚点
+长字符串、长数组和异常结构锚点
+网络、存储、动态代码和 VM 边界锚点
+高频 helper、decoder 和模块加载器锚点
+代表性源码片段
+```
+
+验收：
+
+- 阅读区间覆盖整个文件。
+- 没有未经说明的区间缺口。
+- 候选模式均有真实源码锚点。
+- 先记录源码事实，再使用 AST、搜索和统计复核。
+- 自动摘要、正则或 AST 计数没有替代直接阅读。
+
+文件过大允许分块，但所有分块合并后必须覆盖完整文件。
+
+## 5. G4：首轮画像验收
+
+首轮画像只能称为“当前分析视图中可见的模式清单”。
+
+### 5.1 计数口径
+
+必须分开：
+
+```text
+模式家族数量：可区分的结构类型数。
+出现次数：某一家族匹配的节点、调用点或区域数。
+影响范围：实际受阻的入口、模块、函数、数据流或区间。
+```
+
+每个数字标记为精确值、下界或估计值，并说明统计方法。
+
+### 5.2 每个模式行
+
+至少包含：
+
+```text
+模式 ID 与中性名称
+代表性源码锚点
+出现次数及口径
+影响范围与主要消费者
+与其他模式的依赖
+混淆 / 压缩 / 编译 / 打包器 / 第三方 / VM 分类
+Observed / Inferred / Unknown
+置信度与反证
+高价值候选的具体问题
+证据模式与最小方法
+收益、风险和初步优先级
+建议处理 / 询问 / 跳过 / blocked / handoff
+```
+
+验收：
+
+- 模式家族数和出现次数未混用。
+- 基础设施、第三方、编译产物和 VM 结构未自动计为混淆。
+- `Observed / Inferred / Unknown` 已分开。
+- 每个高价值候选都有具体问题、证据缺口和最小方法。
+- 初步优先级有源码依据，不只按出现次数排序。
+- 字符串隐藏已经检查；无法确认时记录 `Unknown`。
+- 报告明确画像会在新层暴露后更新。
+
+每个通过验收的语义步骤后，重新直读最新视图并更新画像、计数、依赖和优先级。
+
+## 6. 产物类型
+
+每一步只声明一种主要产物类型。
+
+### 6.1 `executable-js`
+
+承诺仍为可执行 JavaScript。
+
+必须验收：
+
+- parse 与适用的语法检查。
+- 作用域、binding 和引用完整性。
+- 声明入口与关键行为测试。
+- 不相关行为没有意外变化。
+- 运行环境和输入与声明一致。
+
+### 6.2 `analysis-js`
+
+用于阅读和继续 AST 分析，不默认替代原始程序运行。
+
+必须验收：
+
+- 尽量可解析；不可解析时说明原因和替代视图。
+- 原始位置到派生位置的映射。
+- transform 命中、修改、跳过和残留。
+- 事实、推断和中性标注可区分。
+
+不得因分析视图不可独立运行就追加无关环境修补。
+
+### 6.3 `annotated-view`
+
+包含注释、中性名称和边界说明。
+
+必须验收：
+
+- 每项标注有来源。
+- 观察事实与模型解释分开。
+- 注释或标注不会被报告成原始源码。
+- 不把该视图当作行为证据目标。
+
+### 6.4 `pseudocode`
+
+只表达结构或语义，不是 JavaScript。
+
+必须验收：
+
+- 明确标记非 JavaScript。
+- 每个重要结论可回溯到原始或派生位置。
+- 不运行 JavaScript 语法检查冒充验收。
+- 未证明细节保留为 `Unknown`。
+
+## 7. Transform 执行前契约
+
+用户批准后、执行前记录：
+
+```text
+step goal
+question_id / concrete question
+user decision
+input
+expected output type
+observed facts
+hypothesis
+evidence mode
+match scope
+mutation scope
+explicit non-goals
+safety preconditions
+risk
+validation plan
+stop condition
+```
+
+要求：
+
+- 一步只处理一种明确的 transform 家族。
+- match scope 和 mutation scope 分开。
+- 不把“尽量多命中”写成目标。
+- 验收计划能检测越界修改。
+- 动态或 hybrid 步骤补充运行目标、trigger、L0～L4、映射和覆盖计划。
+
+## 8. Transform 通用验收
+
+### 8.1 结构与数量
+
+记录：
+
+- 输入、输出和 transform hash。
+- 匹配、修改、跳过和残留数量。
+- 每类跳过和残留的原因。
+- 相关指标的前后值。
+- 与本步无关的关键指标。
+
+指标必须服务于本步问题。代码变短、命中数减少或语法通过都不能单独证明成功。
+
+### 8.2 Parse、语法与映射
+
+- 对 JavaScript 产物执行适用的 parse。
+- `node --check` 只作为语法门，不是语义证明。
+- 记录原始位置、输入视图位置和输出视图位置。
+- 映射应使用稳定节点、结构路径、source map 或逐步映射表。
+- 不能稳定映射的修改不得宣称可追溯。
+
+### 8.3 Binding 与引用
+
+至少检查：
+
+- 声明、读、写、调用和更新引用。
+- shadow binding 是否保持不变。
+- 新名称是否与可见 binding 冲突。
+- 别名和闭包引用是否仍然成立。
+- 动态属性和反射是否可能绕过静态引用。
+- 删除后是否仍有未处理引用。
+
+按标识符文本全局替换不能通过验收。
+
+### 8.4 副作用与异常
+
+检查：
+
+- getter、setter、Proxy 和隐式转换。
+- 调用、构造、赋值和全局状态。
+- 求值次数与求值顺序。
+- `this`、`arguments` 和调用形式。
+- `throw / catch / finally`、提前返回和终止路径。
+- 短路、条件分支和动态代码。
+
+删除前必须证明被删结构没有仍需保留的副作用，或明确把删除列为高风险用户决策。
+
+### 8.5 行为检查
+
+只在安全、可授权且与产物类型相关时使用。
+
+可选检查：
+
+- 对纯函数进行冻结输入的前后输出比较。
+- 比较局部 helper 或 decoder 的结果。
+- 比较声明的公开导出、异常或外部输出。
+- 比较固定输入下的已知行为摘要。
+
+不得执行派生分析视图并把结果冒充原始目标行为。`node:vm` 也不得描述为不可信代码的安全沙箱。
+
+## 9. 高风险变换的附加验收
+
+以下步骤至少视为高风险：
+
+- `eval`、`Function` 或动态载荷改写。
+- 反调试、环境检测或全局代码删除。
+- 控制流展开和非平凡分支删除。
+- 函数替换、stub 或入口改变。
+- 高语义命名。
+- 依赖单次动态观测的批量写回。
+
+除通用验收外，还要求：
+
+```text
+用户明确批准
+替代方案与不处理后果
+所有语义前提
+引用和副作用专项检查
+异常与终止路径检查
+适用的前后行为对照
+回滚或上一个通过版本
+未覆盖路径
+```
+
+控制流步骤还要证明 dispatcher 顺序、case 完整性、fall-through、`break / continue / return / throw` 和异常处理。
+
+重命名步骤还要证明唯一 binding、新名无冲突、声明与引用数量守恒、shadow 未改；若声称只改变名称，可使用忽略 Identifier 名称的结构指纹辅助验证。
+
+## 10. 动态证据验收
+
+每个动态或 hybrid 结论记录：
+
+```text
+question_id
+原始目标路径与运行前后 hash
+实际执行文件与 hash
+运行时、版本、mode 和环境摘要
+输入、配置、时间和随机数
+前置状态、entry 和 trigger
+观测层级 L0～L4
+trigger / probe / instrumented 路径与 hash
+runtime patched: true / false
+完整重放命令
+原始 stdout / stderr / 日志
+观察到的值、顺序、次数、异常和栈
+源码映射
+覆盖路径与未覆盖路径
+Observed / Inferred / Unknown
+明确非结论
+是否足以支持当前变换
+```
+
+验收：
+
+- 原始文件 hash 前后不变。
+- 实际执行对象没有被含糊写成“目标代码”。
+- 日志保留原始版本，不只保存解析摘要。
+- L3 标记 `runtime patched`。
+- L4 仅运行独立副本，并明确证据降级。
+- 结果映射到原始位置和当前 AST 视图。
+- 输入、环境、trigger 和覆盖与问题契约一致。
+- 单次运行没有被推广为全部输入或路径。
+- 属性读取、模块存在和 API 调用没有被自动解释为最终算法依赖。
+
+动态事实不足以支持 mutation scope 时，缩小修改范围或保持 `blocked`。
+
+## 11. 无 probe / 有 probe A/B
+
+L3 runtime Hook 必须保留 A/B。L1 调试器或其他可能显著影响时序的观测也应进行适用对照。
+
+### 11.1 对照条件
+
+A 与 B 尽量固定：
+
+- 同一原始目标 hash。
+- 同一运行时和版本。
+- 同一输入、配置和前置状态。
+- 同一时间、随机数策略和网络条件。
+- 同一 trigger、次数、超时和事件循环推进。
+
+唯一计划差异应是 probe 或 Hook。
+
+### 11.2 比较内容
+
+至少比较：
+
+- 是否完成或超时。
+- 返回值与异常。
+- 公开输出和外部副作用。
+- 调用顺序与次数。
+- 被观测参数和值。
+- 与当前问题相关的日志。
+- 明显时序和资源差异。
+
+### 11.3 解释
+
+- A/B 一致只降低已观察范围内的干扰疑虑，不证明绝对无影响。
+- A/B 不一致时，先把差异作为证据记录，不能选择性忽略。
+- 无 probe 基线无法取得目标值，不等于无法比较其他公开行为。
+- Hook 无法隐藏的可观察差异必须进入风险和非结论。
+
+## 12. 确定性与可重放性
+
+### 12.1 机械产物
+
+相同输入、工具版本、配置和命令重复执行时，应得到：
+
+- 相同输出 hash，或已解释的非语义差异。
+- 相同匹配、修改、跳过和残留数量。
+- 相同映射和报告关键字段。
+- 相同退出状态。
+
+若输出含时间戳、绝对路径或不稳定排序，先消除非必要不确定性；不能消除时单独标记。
+
+### 12.2 动态结果
+
+能够冻结的输入和环境应重复运行。结果不一致时记录：
+
+- 变化字段。
+- 时间、随机数、调度、网络或宿主状态。
+- 变化是否影响当前问题。
+- 可以支持的最窄结论。
+
+不可重复的单次观察可以保留为 `Observed`，但不能被包装成确定性规律。
+
+### 12.3 可重放包
+
+至少保存：
+
+```text
+输入与 hash
+工具和版本
+配置
+transform / trigger / probe
+命令
+原始日志
+输出与 hash
+验证报告
+```
+
+## 13. 验收失败分流
+
+出现以下情况视为失败或阻塞：
+
+- parse 或适用语法检查失败。
+- 匹配范围漂移。
+- 修改了 mutation scope 之外的结构。
+- 删除后仍有引用或副作用未解释。
+- shadow、binding 或别名关系改变。
+- 不相关指标意外变化。
+- 动态事实与静态假设冲突。
+- A/B 出现未解释差异。
+- 重复运行不一致且影响当前结论。
+- 映射或覆盖不足。
+
+失败后：
+
+1. 保留上一个通过版本。
+2. 保存失败输入、输出、日志和事实。
+3. 缩小步骤、修正假设、重新取证或停止。
+4. 不连续追加例外直到“看起来通过”。
+5. 不自动进入下一个 transform。
+6. 需要扩大风险、执行范围或证据模式时重新交给用户决定。
+
+新混淆层暴露不是 transform 自动失败，但必须重新画像，不能沿用旧候选列表直接继续。
+
+## 14. 单步报告
+
+通过或失败都要报告：
+
+```text
+步骤目标与具体问题
+用户批准范围
+输入、输出、transform 与 hash
+证据模式和产物类型
+Observed / Inferred / Unknown
+匹配、修改、跳过和残留
+引用、binding、shadow、别名和副作用检查
+动态环境、补丁、A/B 和覆盖（如适用）
+确定性与可重放结果
+原始到派生映射
+验收状态和失败事实
+仍未证明的结论
+最新画像变化
+下一候选或停止状态
+```
+
+不要只报告“syntax passed”“命中全部”或“代码变短”。
+
+## 15. 关闭与交接验收
+
+### 15.1 进入关闭候选
+
+只有同时满足以下条件，才能建议关闭 AST 阶段：
+
+- 用户的具体问题已经回答，或当前约定分析深度已有明确成果。
+- 影响当前方向的主要隐藏层已处理、明确 blocked 或准备 handoff。
+- 当前阶段需要的入口、数据流、外部输出或稳定坐标已经按相关性建立。
+- 所有接受步骤都有证据、映射和验收记录。
+- 所有剩余问题已分类。
+- 没有未经用户评审的高收益、高置信 AST 候选。
+- 最新视图更适合阅读、搜索、定位、观测或交接。
+
+第三方短名仍存在、分析视图不可独立运行或 VM 未还原，不是拒绝关闭的理由。
+
+### 15.2 关闭建议
+
+必须展示：
+
+```text
+用户原始请求与当前工作目标
+已经证明什么
+最新分析视图与 hash
+仍然存在什么
+blocked 与 handoff 项
+为什么建议停止
+继续的可选收益、成本与风险
+交接方向
+```
+
+只有用户确认后才能标记 `COMPLETE`。
+
+### 15.3 交接验收
+
+交接包至少包含：
+
+- 原始目标和最新视图 hash。
+- 分步 transform 与映射。
+- 已知入口、输入、输出和公开 API。
+- 静态与动态证据。
+- 运行环境、trigger、补丁与覆盖。
+- 跳过和 blocked 项。
+- 未证明依赖。
+- 下一阶段具体问题。
+
+交接是正确结束，不是验证失败。
+
+## 16. 最终自检
+
+- [ ] G1 原始输入已冻结且 hash 未变。
+- [ ] G2 使用可追溯的本地 Prettier，格式化副本可解析。
+- [ ] G3 直接阅读区间覆盖完整格式化文件。
+- [ ] G4 区分模式家族数、出现次数和影响范围。
+- [ ] 高价值候选均有具体问题、证据模式和最小方法。
+- [ ] 每一步声明产物类型和用户批准范围。
+- [ ] Parse、引用、binding、shadow、别名、副作用和异常检查按需完成。
+- [ ] 动态证据记录 L0～L4、hash、trigger、原始日志、映射和覆盖。
+- [ ] L3 有 `runtime patched` 标记和 A/B。
+- [ ] L4 只修改独立副本且证据已降级。
+- [ ] 确定性或不确定性边界已记录。
+- [ ] 验收失败保留上一个通过版本。
+- [ ] 关闭前不存在未经用户评审的高收益候选。
+- [ ] `COMPLETE` 只在用户确认后使用。