@chenlipingjian-alt/dsh-plugin-guardian 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.en.md

@@ -0,0 +1,89 @@
+<!-- Writing guide: playbooks/reference/readme.md. Keep the same sections as README.md. -->
+
+# Plugin Guardian
+
+[简体中文](README.md) | English
+
+[![License](https://img.shields.io/github/license/local/dsh-plugin-guardian)](LICENSE) ![DSH](https://img.shields.io/badge/DSH-0.2.1--rc.3-blue)
+
+One sentence: a plugin buyer plus a security reviewer for DSH — search candidates for a request, audit a pinned commit item by item, install only after approval, then verify what actually landed, with checkable evidence at every step.
+
+## Features
+
+- **Bounded search.** Searches GitHub inside `topic:dsh-plugin` only, returning at most 3 candidates; when the topic has more hits than were returned it sets `truncated: true` instead of presenting a slice as the whole set. Each candidate carries repository full name, description, stars, last push, default branch, HEAD commit SHA and source URL.
+- **A fixed checklist.** Ten items against one pinned commit: provenance and topic-squatting signals, license, maintenance, dependency advisories (live OSV query), install-time scripts quoted verbatim, capabilities (shell/eval/filesystem/credential access), egress destinations, obfuscation and binaries, commit pinnability, DSH engine/bundle compatibility. Every item cites `file:line` or an API URL.
+- **A verdict that gates.** Each audit ends in recommend / caution / reject. Credential reads, unexplained egress, obfuscation or privilege escalation reject the candidate outright, and no later install call can override that.
+- **Install only on approval.** A dry run prints the candidate, commit, audit summary, command and expected changes, and issues a one-time token. The real install needs that token, the same `auditId` and the same commit SHA. Lifecycle scripts are **never** approved: a package that needs `install`/`postinstall` fails instead of running them, with no retry, no elevation and no bypass.
+- **Verification with evidence.** Six post-install checks: dependency integrity, source versus the audited commit, the bundle layer in the composed configuration, live plugin load state, an optional functional smoke call, and the permissions actually granted. Any failure returns `ok: false` with the failing evidence.
+
+## Install
+
+Requires DeepSeek Harness `0.2.1-rc.3`. Host-only bundle; any profile works (verified on `desktop`).
+
+```sh
+dsh plugin --profile desktop add github:local/dsh-plugin-guardian#v0.1.0
+```
+
+or from a local checkout:
+
+```sh
+dsh plugin --profile desktop add /absolute/path/dsh-plugin-guardian
+```
+
+Restart DSH afterwards and reload the page.
+
+## Usage
+
+1. State the need in one sentence, e.g. "a plugin that shows a plugin marketplace inside the session".
+2. `guardian_search` returns at most 3 candidates with their HEAD SHA.
+3. `guardian_audit` returns the ten-item table, an `auditId` and an `installSpec` pinned to that commit. A reject verdict ends the chain.
+4. `guardian_install` with `dryRun: true` returns the approval preview and a token; show it to the user.
+5. After the user explicitly approves, install with the same `auditId`, the same commit SHA and that token.
+6. `guardian_verify` checks the result item by item; pass `smokeTool` for an optional functional smoke call with temporary data.
+
+## Configuration
+
+| Key             | Default | Description                                             |
+| --------------- | ------- | ------------------------------------------------------- |
+| `enabled`       | `true`  | Enable the plugin.                                      |
+| `githubToken`   | `""`    | Optional GitHub token; falls back to `GITHUB_TOKEN`.    |
+| `maxCandidates` | `3`     | Candidates per search; the specification caps this at 3. |
+
+Defaults live in the packaged `cordis.patch.yml`. Without a token GitHub allows 60 API calls per hour; three candidates cost about four calls.
+
+Audits and install records are kept in `$DSH_HOME/guardian/ledger.json` (default `~/.dsh/guardian/ledger.json`), which binds an approval token to one commit and one verdict.
+
+## Update, rollback, uninstall
+
+Pin the version, then restart DSH:
+
+```sh
+dsh plugin --profile desktop add github:local/dsh-plugin-guardian#vX.Y.Z
+dsh plugin --profile desktop remove @chenlipingjian-alt/dsh-plugin-guardian
+```
+
+Uninstalling leaves no runtime data; delete `~/.dsh/guardian/ledger.json` to clear the audit history.
+
+## Privacy and data
+
+- No telemetry. Outbound destinations: `api.github.com` (search, metadata, tags), `codeload.github.com` (pinned commit archive for in-memory scanning), `api.osv.dev` (dependency advisories).
+- Archives are decompressed in memory only — never written to disk, never executed; code is matched as text.
+- No access to `~/.ssh`, `~/.aws`, `.npmrc`, `id_rsa` or any secret environment variable (only the optional `GITHUB_TOKEN` for quota).
+- The only local write is `$DSH_HOME/guardian/ledger.json`.
+
+## Compatibility
+
+See [docs/compatibility.md](docs/compatibility.md). Known limitation: `dsh --profile desktop --dump-config` is refused because the Electron application manages that profile exclusively, so verification uses the live plugin-manager view and says so in the report.
+
+## Development
+
+See [docs/development.md](docs/development.md) and [CONTRIBUTING.md](CONTRIBUTING.md); AI agents should read [AGENTS.md](AGENTS.md) first.
+
+```sh
+pnpm install
+pnpm verify   # typecheck + build + tests + package check
+```
+
+## License
+
+[Apache License 2.0](LICENSE)

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+<!-- 写作规范见 playbooks/reference/readme.md；与 README.en.md 保持相同章节。 -->
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Plugin Guardian
+
+简体中文 | [English](README.en.md)
+
+[![License](https://img.shields.io/github/license/local/dsh-plugin-guardian)](LICENSE) ![DSH](https://img.shields.io/badge/DSH-0.2.1--rc.3-blue)
+
+一句话：给 DSH 装上"插件采购员 + 安检员"——按需求搜候选、对固定 commit 逐项排雷、只在批准后安装、装完逐项核验，每一步都给出可核对的证据。
+
+## 功能
+
+- **搜索有边界**：只在 GitHub `topic:dsh-plugin` 内按关键词搜索，一次最多 3 个候选；命中总数多于返回数时明确标注 `truncated: true`，绝不把切片当成全集。每个候选带 repo 全名、描述、stars、最后 push、默认分支、HEAD commit SHA 与来源 URL。
+- **排查有清单**：对锁定 commit 执行固定的十项检查——来源与可疑抢注、许可证、维护状态、依赖漏洞（OSV 实时查询）、安装期脚本（逐字原文引用）、权限与能力（shell/eval/文件写入/凭证读取）、数据外传域名、代码混淆与二进制、commit 可固定性、DSH 引擎与 bundle 兼容性。每项都给出 `文件:行号` 或 API URL。
+- **判定有闸门**：结论为「推荐 / 谨慎 / 拒绝」。出现凭证读取、可疑外传、混淆代码、提权等红线直接判「拒绝」，此后任何安装调用都会被拒绝。
+- **安装有授权**：先输出安装预览（候选、commit、审计摘要、命令、预计变更）并发放一次性令牌；真正安装必须同时提供该令牌、同一个 `auditId` 与同一个 commit SHA。工具**永不批准**安装期脚本，需要构建脚本的包会失败并保持失败，不重试、不提权、不绕过。
+- **校核有证据**：装完检查六项——依赖完整性、来源与审计 commit 是否一致、配置层是否挂载、插件是否真正激活、可选的功能冒烟、实际权限是否超出声明。任一项失败即 `ok: false`，并给出失败证据。
+
+## 安装
+
+环境要求：DeepSeek Harness 版本满足 `0.2.1-rc.3`。本插件为 host-only bundle，可在任意 profile 中使用（已在 `desktop` 验证）。
+
+### 从 GitHub 安装
+
+固定到某个 Release tag：
+
+```sh
+dsh plugin --profile desktop add github:local/dsh-plugin-guardian#v0.1.0
+```
+
+安装后重启 DSH（桌面版请重启应用），刷新页面。命令会装到你平时使用的 DSH；如果你设置了自己的 `DSH_HOME`，请在同一个环境中运行。
+
+### 本地目录安装
+
+```sh
+dsh plugin --profile desktop add /绝对路径/dsh-plugin-guardian
+```
+
+从源码安装用于开发调试，见 [docs/development.md](docs/development.md)。
+
+## 使用
+
+四个工具构成一条链路，按顺序调用即可；也可以只调用其中一步。
+
+1. 用一句话说明需求，例如"我想要一个能在会话里显示插件市场的插件"。
+2. Agent 调用 `guardian_search`，得到不超过 3 个候选（带 HEAD SHA）。
+3. Agent 对候选调用 `guardian_audit`，得到十项清单、`auditId` 与锁定的 `installSpec`。
+   - 结论「拒绝」→ 到此为止，只报告失败项与证据。
+4. 决定安装时，Agent 先用 `guardian_install` 的 `dryRun: true` 拿到预览与令牌，把候选、commit、审计摘要、命令、预计变更展示给你。
+5. **你明确批准后**，Agent 才用同一个 `auditId`、同一个 commit SHA 和该令牌执行安装。
+6. Agent 调用 `guardian_verify` 逐项校核；提供 `smokeTool` 时可再做一次功能冒烟（请给临时数据）。
+
+## 配置
+
+| 键              | 默认值 | 说明                                                     |
+| --------------- | ------ | -------------------------------------------------------- |
+| `enabled`       | `true` | 启用插件。                                               |
+| `githubToken`   | `""`   | 可选 GitHub token；留空则读取环境变量 `GITHUB_TOKEN`。   |
+| `maxCandidates` | `3`    | 单次搜索返回的候选上限，规范上限为 3。                    |
+| `downloadTimeoutSeconds` | `120` | 固定 commit 归档的下载期限；超时即标 `download_truncated` + `audit_incomplete`，不给通过结论。 |
+| `installSource` | `github` | 审计时假定的安装来源：`github`（源码直装）或 `npm`（发布包）。决定 `prepare` 是否算安装期脚本。 |
+
+归档下载器尊重 `HTTPS_PROXY` / `HTTP_PROXY`（含 `https_proxy` / `http_proxy` 小写形式，支持 `user:pass@`），因为 Node 的全局 `fetch` 不读这些变量；GitHub API 与 OSV 仍走 `fetch`。
+
+配置保存在 profile 的 `cordis.patch.yml`（bundle 默认值在安装包的 `cordis.patch.yml` 中）。`githubToken` 以明文保存在该文件里；未认证时 GitHub 每小时仅 60 次 API 调用，搜索 3 个候选约用 4 次。
+
+审计与安装记录写入 `$DSH_HOME/guardian/ledger.json`（默认 `~/.dsh/guardian/ledger.json`），用于把审批令牌绑定到"某个 commit + 某次判定"。
+
+## 更新、回滚与卸载
+
+版本变更与升级说明见 [更新日志](https://github.com/chenlipingjian-alt/dsh-plugin-guardian/releases)。
+
+更新或回滚时请写明版本号，然后重启 DSH（新版本发布后 24 小时内，不带版本号的安装命令可能仍会装到旧版本）：
+
+```sh
+dsh plugin --profile desktop add github:local/dsh-plugin-guardian#vX.Y.Z
+```
+
+卸载：
+
+```sh
+dsh plugin --profile desktop remove @chenlipingjian-alt/dsh-plugin-guardian
+```
+
+卸载后不留下任何运行时数据；如需清除审计记录，可手动删除 `~/.dsh/guardian/ledger.json`。
+
+## 隐私与数据
+
+- 本插件不出站任何遥测。联网目的地只有：`api.github.com`（搜索、仓库元数据、tags）、`codeload.github.com`（下载锁定 commit 的归档用于内存扫描）、`api.osv.dev`（依赖漏洞查询）。
+- 审计时归档只解压到内存，不落盘、不执行；代码只做文本匹配。
+- 不读取 `~/.ssh`、`~/.aws`、`.npmrc`、`id_rsa` 等凭证文件，也不读取任何密钥型环境变量（只有可选的 `GITHUB_TOKEN` 用于提高 API 配额）。
+- 本地写入只有 `$DSH_HOME/guardian/ledger.json`。
+
+## 兼容性
+
+见 [docs/compatibility.md](docs/compatibility.md)。已知限制：`dsh --profile desktop --dump-config` 因 profile 由 Electron 应用独占管理而不可用，校核改用运行中的 plugin manager 视图，并在报告中注明。
+
+## 开发
+
+见 [docs/development.md](docs/development.md) 与 [CONTRIBUTING.md](CONTRIBUTING.md)。使用 AI agent 开发、发布或维护时，让它先读 [AGENTS.md](AGENTS.md)。
+
+```sh
+pnpm install
+pnpm verify   # typecheck + build + tests + package check
+```
+
+## 许可证
+
+[Apache License 2.0](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,11 @@
+# Host activation for the DSH bundle. Defaults live here so a fresh install
+# behaves the same as the schema defaults; users may override them in settings.
+- insert:
+    - id: '@chenlipingjian-alt/dsh-plugin-guardian'
+      name: '@chenlipingjian-alt/dsh-plugin-guardian'
+      config:
+        enabled: true
+        githubToken: ''
+        maxCandidates: 3
+        downloadTimeoutSeconds: 120
+        installSource: github

package/icon.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" role="img" aria-label="Plugin Guardian">
+  <defs>
+    <linearGradient id="guardian-shield" x1="16" y1="8" x2="112" y2="120" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#1D4ED8"/>
+      <stop offset="1" stop-color="#0B1220"/>
+    </linearGradient>
+  </defs>
+  <rect x="4" y="4" width="120" height="120" rx="30" fill="url(#guardian-shield)"/>
+  <path d="M64 20 102 34v30c0 22-15 36-38 44-23-8-38-22-38-44V34Z" fill="#FFFFFF" fill-opacity="0.14" stroke="#FFFFFF" stroke-width="5" stroke-linejoin="round"/>
+  <path d="M46 66l13 13 25-27" fill="none" stroke="#FFFFFF" stroke-width="9" stroke-linecap="round" stroke-linejoin="round"/>
+  <circle cx="93" cy="91" r="13" fill="#22C55E" stroke="#0B1220" stroke-width="4"/>
+  <path d="M87 91l4 4 8-9" fill="none" stroke="#0B1220" stroke-width="3.5" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>