dsh-plugin-gate
dsh-plugin-gate 是一个独立的 DSH 安装前门禁插件。它在安装插件之前静态物化并审查 npm、Git 或本地插件源，不修改 DSH 宿主源码，也不执行被审查插件的生命周期代码。
实现有意复用两个上游的安全设计：
- OpenAI Codex：npm
pack --ignore-scripts、有界 tar 解包、package manifest/路径规则、不可变安装 pin。 - Claude Code 插件市场：GitHub HTTPS host allowlist、commit SHA pin、marketplace invariant 检查、官方只读 policy reviewer prompt/schema。
能力对照
| 门禁层 | 来源 | 本插件行为 |
|---|---|---|
| npm 物化 | Codex npm_source | 只 npm pack --ignore-scripts，要求精确版本，不安装依赖，不运行 scripts；记录 tarball SHA256 |
| npm tar 解包 | Codex plugin_bundle_archive | 限制压缩/解压大小；拒绝绝对路径、..、盘符、symlink、hardlink、非常规类型；要求唯一 package/ 根 |
| manifest/路径 | Codex manifest 规则 | package.json 必须是常规文件且不超过 1 MiB；版本和 dsh.bundle.patch 路径受限；realpath 不允许逃逸插件根 |
| Git 物化 | Claude marketplace action | 仅允许 HTTPS GitHub/GitLab/Bitbucket 及其子域；必须 40 位 commit SHA；fetch + checkout + rev-parse 复验 |
| catalog invariant | Claude I1-I11 | 名称、描述、排序、去重、HTTPS、SHA、路径、隐藏 Unicode、shell 元字符；I7 是上游仓库流程约束，不适用于独立插件 |
| DSH manifest | Claude I8 的 DSH 适配 | 物化结果必须有有效 package.json 与 cordis.patch.yml |
| policy scan | Claude official prompt/schema | 调用 claude -p --bare，只允许 Read,Glob,Grep，输出 schema 校验和脱敏；结果按内容 SHA 与 policy hash 缓存 |
| 本地源 | DSH 适配 | 先复制到私有 staging 快照；拒绝 symlink/非常规文件；扫描与 fingerprint 都作用于快照 |
补充边界：
- npm catalog 源必须提供精确 semver；直接 CLI 源同样拒绝 range/tag。
- npm、Git 和本地物化结果都会生成 payload 内容 SHA256；npm 的不可变安装 pin 另外记录 tarball SHA256。
- Git 子进程使用隔离环境，忽略用户/系统 Git config、credential helper 与 smudge filter，只保留 HTTPS 协议。
- tar 解包校验 header checksum、PAX record 结构、路径与 entry/size 上限；本地和 Git 快照复制同样有文件数与字节数上限。
安装
dsh-plugin-gate is distributed from GitHub; it is not published to npm.
For a mutable but convenient installation, use the release tag:
dsh plugin --profile web add github:youkongling/dsh-plugin-gate#v0.1.0For a registry-free immutable installation, use the GitHub Release tarball:
dsh plugin --profile web add https://github.com/youkongling/dsh-plugin-gate/releases/download/v0.1.0/dsh-plugin-gate-0.1.0.tgzFor review-before-install, pin the exact 40-character commit SHA:
dsh plugin --profile web add "github:youkongling/dsh-plugin-gate#$(git ls-remote https://github.com/youkongling/dsh-plugin-gate.git HEAD | cut -f1)"Restart the profile after installation.
使用
独立 CLI
# 只跑确定性检查；适合本地开发
./bin/dsh-plugin-gate.js /absolute/path/to/plugin --no-policy
# npm 源必须精确到版本
./bin/dsh-plugin-gate.js npm:<package>@<exact-version>
# Git 源必须 pin 到 40 位 commit SHA
./bin/dsh-plugin-gate.js 'git:https://github.com/<owner>/<repo>#<40-char-sha>'
# 完整机器可读报告
./bin/dsh-plugin-gate.js npm:<package>@<exact-version> --json退出码：
0：通过门禁1：门禁拒绝2：CLI 参数错误或物化流程抛错
也可以检查 Claude marketplace 兼容 catalog：
./bin/dsh-plugin-gate.js --catalog marketplace.json <plugin-name>DSH 插件
安装到指定 profile：
dsh plugin --profile web add /absolute/path/to/dsh-plugin-gate安装后提供：
- 斜杠命令：
/plugin-gate <source-spec> - Tool：
plugin_gate
plugin_gate 返回结构化结果，即使目标插件未通过门禁，也会保留 passes、findings、contentSha256、installPin 与 policy 结果。
Policy 模式
- 默认：policy 结果强制生效。找不到 Claude CLI、超时、输出不合法或 verdict 为 false 都不能通过。
--no-policy：跳过 LLM policy，只执行确定性供应链与路径检查。enforcePolicy: false：policy 结果仅作为 advisory，不影响确定性检查结论。
policy verdict cache key 同时包含：
- 目标内容身份（npm tarball SHA / Git commit / 本地内容 SHA）
- catalog source 对象
- 官方 prompt、schema 与 DSH 附录的 hash
因此 policy 或扫描对象变化会自动失效缓存。cache 默认保存 30 天。 cache 文件以 0600 写入；结构不完整或时间非法的 entry 不会被信任。
Reviewer 进程只继承白名单环境变量（PATH、HOME、语言变量和 Anthropic 认证变量），不会接收 DSH 的其他模型 key、云厂商凭据或 session secret。报告中的 key/token/password/secret 形态字符串会被脱敏。
威胁模型与边界
这个插件是安装前门禁，不是形式化安全证明：
1. 被审查插件的生命周期代码不会被执行；物化只使用 npm pack、Git、文件复制和 tar 解析。 2. Policy reviewer 是 LLM 判断，可能被 prompt injection 误导；它不能替代确定性规则，也不是安全边界。 3. npm registry、Git host 与 TLS 证书仍然是被信任的外部供应链环节。 4. 本插件审查 tarball/checkout 中的 payload，不递归安装或执行目标 package 声明的依赖；实际安装依赖仍需额外的锁定与审计策略。 5. 本地源会先做私有快照，避免“扫描路径”和“报告 fingerprint”指向不同内容；但无法防御操作系统级别的恶意并发篡改。 6. Policy scan 需要 claude CLI 和有效认证；没有 reviewer 时按未通过处理。 7. Git host 必须支持按 commit SHA 的 shallow fetch；不支持该能力的仓库会被安全拒绝。
开发与测试
npm test测试覆盖 tar 攻击样本、Claude invariant、manifest 逃逸、本地 symlink、policy schema/脱敏、cache 失效、DSH 入口注册与结构化输出。
License
Apache License 2.0。来源与衍生说明见 NOTICE；上游参考副本保留在 assets/upstream/。