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.0

For 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.tgz

For 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/。