mcp-tool-shop-org/repomesh

日本語 | 中文 | Español | Français | हिन्दी | Italiano | Português (BR)

Syntropic repo network — append-only ledger, node manifests, and scoring for distributed repo coordination. ## 这是什么？ RepoMesh 将一系列 repo 转化为一个协作网络。每个 repo 都是一个**节点**，包含： - 一个 **manifest** (`node.json`)，声明其提供和消费的内容 - 广播至 append-only ledger 的**签名事件** - 为所有节点和功能建立索引的 **registry** - 定义对信任而言何为“完成”的 **profile** 该网络强制执行三个不变量： 1. **确定性输出** — 相同的输入，相同的产出 2. **可验证的来源** — 每个发布都经过签名和证明 3. **可组合的合约** — 接口是版本化且机器可读的 ## 快速开始（1 条命令 + 2 个 secret） ``` npx @mcptoolshop/repomesh init --repo your-org/your-repo --profile open-source # 用于 CI piping 的 JSON 输出： npx @mcptoolshop/repomesh init --repo your-org/your-repo --profile open-source --json ``` 这会生成你需要的一切： - `node.json` — 你的节点 manifest - `repomesh.profile.json` — 你选择的 profile - `.github/workflows/repomesh-broadcast.yml` — 发布广播工作流 - Ed25519 签名密钥对（私钥保留在本地） 然后向你的 repo 添加两个 secret： 1. `REPOMESH_SIGNING_KEY` — 你的 PEM 格式私钥（由 init 命令打印） 2. `REPOMESH_LEDGER_TOKEN` — 对此 repo 拥有 `contents:write` + `pull-requests:write` 权限的 GitHub PAT 发布一个版本。信任会自动收敛。 ### CLI Flags 所有命令均接受：`--quiet`、`--verbose`、`--debug`、`--no-color`。`init` 命令还支持 `--json` 以用于机器可读的输出。 可用 Shell 补全： ``` repomesh completion bash >> ~/.bashrc repomesh completion zsh >> ~/.zshrc ``` ### 环境覆盖 | 变量 | 用途 | |----------|---------| | `REPOMESH_LEDGER_URL` | 覆盖 ledger endpoint | | `REPOMESH_MANIFESTS_URL` | 覆盖 manifests endpoint | | `REPOMESH_FETCH_TIMEOUT` | 拉取超时时间（以 ms 为单位） | ### Profile | Profile | 证据 | 保障检查 | 适用场景 | |---------|----------|-----------------|----------| | `baseline` | 可选 | 无要求 | 内部工具、实验 | | `open-source` | SBOM + provenance | 许可证审计 + 安全扫描 | OSS 默认 | | `regulated` | SBOM + provenance | 许可证 + 安全 + 可重现性 | 合规关键型 | ### 检查信任 ``` node registry/scripts/verify-trust.mjs --repo your-org/your-repo ``` 显示完整性评分、保障评分、基于 profile 的建议。 ### 覆盖 无需 fork 验证器即可进行针对特定 repo 的定制： ``` // repomesh.overrides.json { "license": { "allowlistAdd": ["WTFPL"] }, "security": { "ignoreVulns": [{ "id": "GHSA-xxx", "justification": "Not reachable" }] } } ``` ## Repo 结构 ``` repomesh/ profiles/ # Trust profiles (baseline, open-source, regulated) schemas/ # Source of truth for all schemas ledger/ # Append-only signed event log events/events.jsonl # The ledger itself nodes/ # Registered node manifests + profiles scripts/ # Validation + verification tooling attestor/ # Universal attestor (sbom, provenance, sig chain) verifiers/ # Independent verifier nodes license/ # License compliance scanner security/ # Vulnerability scanner (OSV.dev) anchor/xrpl/ # XRPL anchoring (Merkle roots + testnet posting) manifests/ # Committed partition manifests (append-only) scripts/ # compute-root, post-anchor, verify-anchor policy/ # Network policy checks (semver, hash uniqueness) registry/ # Network index (auto-generated from ledger) nodes.json # All registered nodes trust.json # Trust scores per release (integrity + assurance) anchors.json # Anchor index (partitions + release anchoring) badges/ # SVG trust badges per repo snippets/ # Markdown verification snippets per repo pages/ # Static site generator (GitHub Pages) docs/ # Public verification docs tools/ # Developer UX tools repomesh.mjs # CLI entrypoint templates/ # Workflow templates for joining ``` ## 手动加入（5 分钟） ### 1. 创建你的节点 manifest 将 `node.json` 添加到你的 repo 根目录： ``` { "id": "your-org/your-repo", "kind": "compute", "description": "What your repo does", "provides": ["your.capability.v1"], "consumes": [], "interfaces": [ { "name": "your-interface", "version": "v1", "schemaPath": "./schemas/your.v1.json" } ], "invariants": { "deterministicBuild": true, "signedReleases": true, "semver": true, "changelog": true }, "maintainers": [ { "name": "your-name", "keyId": "ci-yourrepo-2026", "publicKey": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----" } ] } ``` ### 2. 生成签名密钥对 ``` openssl genpkey -algorithm ED25519 -out repomesh-private.pem openssl pkey -in repomesh-private.pem -pubout -out repomesh-public.pem ``` 将 PEM 格式的公钥放入你的 `node.json` maintainers 条目中。 将私钥作为 GitHub repo secret 存储（`REPOMESH_SIGNING_KEY`）。 ### 3. 向网络注册 向此 repo 提交一个 PR 以添加你的节点 manifest： ``` ledger/nodes///node.json ledger/nodes///repomesh.profile.json ``` ### 4. 添加广播工作流 将 `templates/repomesh-broadcast.yml` 复制到你 repo 的 `.github/workflows/` 目录下。 设置 `REPOMESH_LEDGER_TOKEN` secret（一个对此 repo 拥有 contents:write + pull-requests:write 权限的 fine-grained PAT）。 现在，每次发布都会自动向 ledger 广播一个已签名的 `ReleasePublished` 事件。 ## Ledger 规则 - **Append-only** — 现有行是不可变的 - **Schema 合法** — 每个事件都会根据 `schemas/event.schema.json` 进行验证 - **签名合法** — 每个事件都由已注册的节点维护者签名 - **唯一** — 不允许重复的 `(repo, version, type)` 条目 - **时间戳正常** — 不能是未来 1 小时之后或过去 1 年之前的时间 ## 事件类型 Ledger 目前会发出以下 **live（活跃）** 事件类型。其余为 **保留/计划中** — schema 接受它们，但尚无节点发出。我们在此列出它们以展示路线图，但不暗示已具备尚不存在的覆盖范围（对信任产品保持正门诚实）。 **Live（目前已发出）：** | 类型 | 何时 | |------|------| | `ReleasePublished` | 发布新版本时 | | `AttestationPublished` | attestor 验证发布时 | | `ledger.anchor` | anchor 节点封装分区时（Merkle root + XRPL memo） | | `attestation.dispute` | 受信任节点提出异议时（降级裁定结果） | | `KeyRotation` | 维护者密钥轮换至后继者时（前瞻性 — 过去的签名保持有效） | | `KeyRevocation` | 维护者密钥被撤销时（泄密 = 追溯无效，RFC 5280） | **保留/计划中（尚未发出）：** | 类型 | 预期含义 | |------|------------------| | `BreakingChangeDetected` | 引入了破坏性变更 | | `HealthCheckFailed` | 节点未通过自身的健康检查 | | `DependencyVulnFound` | 在依赖项中发现漏洞 | | `InterfaceUpdated` | 接口 schema 发生变化 | | `PolicyViolation` | 违反了网络策略 | ## 密钥轮换与撤销 维护者密钥具有生命周期。密钥可以**轮换**至后继者或被**撤销**，且验证是**具有时间意识**的：只有在密钥处于签名可信时间（即 XRPL anchor 的关闭时间，也就是 ledger 已使用的可信时钟）有效时，该签名才受信任。 ``` # 轮换到后继 key（已退役 key 的过往签名仍然有效） npx @mcptoolshop/repomesh key rotate --repo your-org/your-repo \ --retiring mike-2026-01 --new-key mike-2026-06 --public-key new.pem # 撤销被入侵的 key（在失效日期及之后的签名将被拒绝） npx @mcptoolshop/repomesh key revoke --repo your-org/your-repo \ --key mike-2026-01 --reason compromise --invalid-after 2026-06-18T00:00:00Z ``` - **常规轮换**是*前瞻性*的 — 被废弃密钥过去的签名依然有效；它仅仅是停止为新发布签名。 - **密钥泄露**是*追溯性*的（RFC 5280 §5.3.2） — 任何可证明的 anchor 时间处于/晚于失效日期的签名都会被拒绝，并且无法被证明早于该日期的签名也会被拒绝。 - **没有**生命周期字段的密钥会被 grandfathered（永远有效），因此现有节点的验证保持不变。 - 撤销是已签名的 `KeyRevocation` 事件；唯一密钥已泄露的单密钥节点，可通过 **governance**（`trustedPolicy`）节点对撤销进行签名来恢复。信任关键型节点应注册 **≥2 个密钥**（TUF §6.1）。 - 即使面对被篡改的 `node.json`，撤销操作也会从已签名、锚定至 XRPL 的事件中重新施加 — 被剥离的 manifest 无法复活已撤销的密钥。请参阅[威胁模型](docs/threat-model.md)了解边界情况（针对规范的 ledger 进行验证；在对撤销敏感的检查中使用 `--anchored`）。 ## 节点类型 | 类型 | 角色 | |------|------| | `registry` | 为节点和功能建立索引 | | `attestor` | 验证声明（构建、合规） | | `policy` | 强制执行规则（评分、门控） | | `oracle` | 提供外部数据 | | `compute` | 执行工作（转换、构建） | | `settlement` | 最终化状态 | | `governance` | 制定决策 | | `identity` | 签发/验证凭证 | ## 公开验证 任何人都可以使用一条命令验证发布 — **无需 clone**，CLI 会为你拉取公共 ledger： ``` npx @mcptoolshop/repomesh verify-release --repo mcp-tool-shop-org/shipcheck --version 1.0.4 --anchored ``` 此操作检查： 1. `ReleasePublished` 事件存在，并且由注册到**该 repo 自身** `node.json` 的密钥签名（Ed25519） — 注册到其他 repo 的密钥无法验证它。 2. 满足该 repo 的信任 profile：存在每个 profile 要求的证明（SBOM、provenance、许可证、安全），由受信任的 attestor 签名，并且其最新结果为 `pass`，且至少有一个**独立的** attestor。仅有自我签名且没有独立证明的发布会报告 `UNVERIFIED`，绝不报告 `PASS`。 3. 使用 `--anchored` 时：重新计算分区的 Merkle root 并与 manifest 匹配，并且 — 当网络可达时 — 获取并断言链上的 XRPL 交易（`validated` + `tesSUCCESS`，签名账户位于 trusted-anchor 允许列表中，且链上 memo 绑定至本地 root/manifest-hash/count）。离线时，它会报告 `XRPL NOT verified` 而不是伪造交易；严格的 `--anchored` 会因此失败（使用 `--anchored-or-local` 接受本地验证的 manifest 而无需链上证明）。 对于 CI 门控，使用 `--format ` 选择输出格式（`--json` 是 `--format json` 的别名）： ``` npx @mcptoolshop/repomesh verify-release --repo mcp-tool-shop-org/shipcheck --version 1.0.4 --anchored --format json ``` **退出代码**派生自三态判定结果，因此 CI 步骤可以直接根据其进行门控： | 退出码 | 判定 | 含义 | |------|---------|---------| | `0` | PASS | 真实且有保障（或通过 `--fail-on=fail` 放宽至 UNVERIFIED 时）。 | | `1` | FAIL | 硬失败 — 伪造/错误 repo 的签名、不在允许列表中的 attestor，或必需的检查失败。 | | `3` | UNVERIFIED | 软失败 — 尚未 anchor、没有独立见证人，或缺少必需的检查。 | | `2` | — | 使用错误或内部崩溃。 | `--fail-on ` 设置严格程度。默认的 `unverified` 在 FAIL 和 UNVERIFIED 时均会失败；`--fail-on=fail` 允许 UNVERIFIED 通过（退出码为 0，并带有警告），适用于 warn 模式采纳。 使用 `verify-all` 在一次 ledger 加载中验证整个批次，并使用 `--local` 对本地 clone 进行离线验证： ``` # 信任索引中的每次发布，warn-mode npx @mcptoolshop/repomesh verify-all --from-registry --fail-on fail # 离线针对本地 ledger checkout npx @mcptoolshop/repomesh verify-release --repo org/repo --version 1.0.0 --local ./repomesh ``` 使用内置的 composite action **在 CI 中对其进行门控** — 请参阅[使用 GitHub Action](docs/verification.md#using-the-github-action)： ``` - uses: mcp-tool-shop-org/repomesh/.github/actions/verify@v1 with: repo: ${{ github.repository }} version: ${{ github.event.release.tag_name }} anchored: "true" ``` 请参阅 [docs/verification.md](docs/verification.md) 获取完整的验证指南、威胁模型和核心概念。 ### 信任徽章 Repo 可以从 registry 嵌入信任徽章： ``` [](https://mcp-tool-shop-org.github.io/repomesh/repos/mcp-tool-shop-org/shipcheck/) [](https://mcp-tool-shop-org.github.io/repomesh/repos/mcp-tool-shop-org/shipcheck/) [](https://mcp-tool-shop-org.github.io/repomesh/repos/mcp-tool-shop-org/shipcheck/) ``` ## 信任与验证 ### 验证发布 ``` npx @mcptoolshop/repomesh verify-release --repo mcp-tool-shop-org/shipcheck --version 1.0.4 --anchored ``` ### 证明发布 ``` node attestor/scripts/attest-release.mjs --scan-new # process all unattested releases node attestor/scripts/attest-release.mjs --scan-new --dry-run # preview without writing ``` 检查项：`sbom.present`、`provenance.present`、`signature.chain` ### 运行验证器 ``` node verifiers/license/scripts/verify-license.mjs --scan-new node verifiers/security/scripts/verify-security.mjs --scan-new ``` 安全验证器阈值（最大 CVE 数量、允许的严重性等级）通过 `verifiers/security/config.json` 进行配置驱动。 ### 运行策略检查 ``` node policy/scripts/check-policy.mjs ``` 检查项：semver 单调性、产出哈希唯一性、必需的功能。 ## 安全与威胁模型 RepoMesh 涉及 **ledger 事件**（已签名的 JSON）、**节点 manifest**（公钥 + 功能）、**registry 索引**（自动生成的信任分数）以及 **XRPL testnet**（anchor 交易）。它**不会**触及成员 repo 的源代码、私钥、用户凭证或浏览数据。私钥绝不会离开 CI runner。网络访问仅限于 GitHub API（创建 PR）、XRPL testnet（锚定）和 OSV.dev（漏洞查找）。**不收集或发送任何遥测数据** — 零分析、零崩溃报告、零 phone-home。请参阅 [SECURITY.md](SECURITY.md) 了解完整范围、所需权限和漏洞报告流程，并参阅[威胁模型](docs/threat-model.md)了解密钥生命周期信任边界（为什么 `node.json` 的真实性取决于其来源，以及为什么对撤销敏感的验证应使用 `--anchored`）。 强化措施： - 插入变量数据的子进程调用使用带数组参数的 `execFileSync`；其余的 `execSync` 调用使用静态、常量的命令字符串 — 不存在 shell 注入向量。 - Ledger 和 registry 的 JSON 解析封装在 `try`/`catch` 中，并带有结构化、带行号的错误信息；格式错误的行将被跳过并出来，绝不会因原始堆栈导致工具崩溃。 - 所有文件操作均防止路径遍历（解析 + 边界检查）。 - 全程使用 ReDoS 安全的解析方式（无无限正则表达式）。 - PEM 私钥通过 `.gitignore` 排除，绝不打印到 stdout 或 CI 日志中，并以仅所有者可读写（`0600`）的权限写入。 ## 测试 完整的 `node --test` 测试套件涵盖了 Ed25519 签名、schema 验证、Merkle tree 完整性（v1 + RFC-6962 v2）、append-only 不变量、路径遍历防护、anchor 验证、trusted-attestor 允许列表，以及跨 CLI、ledger、anchor、verifier 和工具层的输入验证。 ``` # 运行所有套件并从汇总页脚读取确切的 pass/fail 计数： node --test $(git ls-files '*.test.mjs') ``` 测试数量会随着套件的添加而增加 — 运行上述命令以获取当前总数，而不是依赖一个会过时的数字。 ## 许可证 MIT 由 MCP Tool Shop 构建

标签：GNU通用公共许可证, MITM代理, Node.js, SOC Prime, 仓库管理, 信任机制, 分布式协调, 审计日志, 开发工具, 暗色界面, 自定义脚本