officialunofficial/mkit

# mkit  [](#license) [](https://crates.io/crates/mkit-cli) [](https://docs.rs/mkit-core) [](https://codecov.io/gh/officialunofficial/mkit) 一个使用 Rust 编写的基于内容寻址的版本控制工具包。 `mkit` 是一个通用的、基于内容寻址的 VCS（版本控制系统） — 具备类似 Git 的 commit、ref 和 transport — 并带有一个原生的、与谓词无关的证明子系统（位于 DSSE 信封中的 in-toto v1 Statement），允许任何下游服务将见证签名附加到 commit 上。[`rust/tests/golden/`](rust/tests/golden/) 下的黄金向量固定了 v1 的磁盘和传输格式。 ## 状态 **Alpha (pre-1.0)。** v1 的传输和磁盘格式在整个 0.x 版本系列中是稳定的；API、CLI 标志和未固定的内部实现可能会在任何 0.x 版本中发生变化。请参阅 [`CHANGELOG.md`](CHANGELOG.md) 获取破坏性变更记录。 **MSRV** 为 Rust 1.95.0，固定在 [`rust/rust-toolchain.toml`](rust/rust-toolchain.toml) 中。CHANGELOG 记录了 MSRV 的提升；除非特定功能另有要求，否则策略为“当前稳定版减去一个版本”。 ## 快速开始 ``` # 从 crates.io 安装 CLI（有关其他渠道，请参阅下方的“安装”） cargo install mkit-cli # 进行你的第一次签名提交 mkit init # create .mkit/ in the current dir mkit keygen # generate an Ed25519 signing key echo hello > hi.txt mkit add hi.txt mkit commit -m "first commit" # 推送到远程仓库（严格的 scheme — mkit+{file,https,s3,ssh,enc}://） mkit remote add origin mkit+file:///srv/mkit/my-repo mkit push origin # first push records `origin` as the branch upstream mkit push # subsequent pushes go to the recorded upstream ``` 直接运行 `mkit push` 会将当前分支推送到其记录的 upstream，并且除非您传递 `--force-with-lease` 或 `--force`，否则它将拒绝非快进（non-fast-forward）更新；`mkit push --all` 会以相同的 CAS 安全性镜像每个本地分支。`mkit remote add `（不带名称）出于向后兼容性考虑，仍会配置默认的扁平远程仓库。 完整的 CLI 参考：[`docs/CLI.md`](docs/CLI.md)。 ## 安装 选择其中一种。包含验证步骤的详细指南位于 [`docs/INSTALL.md`](docs/INSTALL.md)。 ### 快速安装（已签名的发布二进制文件） ``` curl mkit.sh | sh ``` 这会检测您的操作系统和架构，下载匹配的已签名发布归档文件，默认验证其 cosign 签名，并将 `mkit` 安装到 `~/.local/bin`。等效的显式形式为：`curl -sSfL https://mkit.sh/install.sh | sh`；附加 `-s -- --version v0.3.0` 可固定到特定的发布版本。 在原生 Windows 上（PowerShell，不使用 WSL/Git-Bash），请改用 PowerShell 安装程序： ``` irm https://mkit.sh/install.ps1 | iex ``` ### 从源码构建 ``` cargo install --git https://github.com/officialunofficial/mkit mkit-cli ``` 需要 Rust 1.95（rustup 会在首次构建时从 `rust/rust-toolchain.toml` 中获取它）。将 `mkit` 放入 `~/.cargo/bin/`。 ### 从 GitHub Releases 下载 在每个 `v*.*.*` 标签上，提供针对 Linux（x86_64 和 arm64）、macOS（arm64 和 x86_64）以及 Windows（x86_64）的 Cosign 签名归档： ``` VERSION=0.3.0 TARGET=aarch64-apple-darwin curl -LO "https://github.com/officialunofficial/mkit/releases/download/v${VERSION}/mkit-${VERSION}-${TARGET}.tar.gz" tar -xzf "mkit-${VERSION}-${TARGET}.tar.gz" ``` 验证步骤 — cosign bundle、`SHA256SUMS`、SBOM — 位于 [`docs/INSTALL.md`](docs/INSTALL.md) 中。 ### WASM (npm) ``` bun add @makechain/mkit-wasm # or: npm i @makechain/mkit-wasm ``` 使用 `@makechain` 作用域是刻意为之（Makechain 是 Official Unofficial, Inc. 的一个内部团队，不是一个独立的实体）。TypeScript 和 Cloudflare Workers 的示例位于 [`docs/INSTALL.md`](docs/INSTALL.md#wasm--npm)。 ### 硬件签名器（可选） 外部签名器是独立的二进制文件，mkit 通过 [v1 stdio 协议](docs/specs/SPEC-EXTERNAL-SIGNER.md) 驱动它们。签名器 crate 位于 `rust/` 顶级 Cargo workspace 之外的 [`contrib/signers/`](contrib/signers/) 下，因此安装路径是 `git clone` 加上 `cargo install --path .`： ``` git clone https://github.com/officialunofficial/mkit cd mkit/contrib/signers cargo install --path mkit-sign-file # any platform cargo install --path mkit-sign-tpm --features tpm2 # Linux/Windows TPM 2.0 cargo install --path mkit-sign-ctap # FIDO2 / CTAP-HID # Apple Secure Enclave (macOS, Swift): cd mkit-sign-se && swift build -c release \ && cp .build/release/mkit-sign-se /usr/local/bin/ ``` 每个签名器在 [`contrib/signers/`](contrib/signers/) 下都有各自的 README。 ## Keystore 签名密钥存储在可插拔的 keystore vault 中。开箱即用时，mkit 支持： - **software** / **software-raw** — 磁盘上静态加密的软件 vault；跨平台的基础后端。 - **macos-keychain**, **windows-credential**, **linux-secret-service** — 可用时的原生操作系统 keychain。 - **systemd-creds** — 具备该功能的 Linux 主机上 systemd 的加密凭据存储。 - **yubikey** — 通过 PIV / OpenPGP 小程序提供硬件支持。 - **external signers** — 使用 [v1 stdio 协议](docs/specs/SPEC-EXTERNAL-SIGNER.md) 进行通信的独立子进程二进制文件；参考签名器位于 [`contrib/signers/`](/.dsse`；任何使用 [v1 stdio 协议](docs/specs/SPEC-EXTERNAL-SIGNER.md) 的签名器都可以生成它： ``` ┌──────────────────────────────┐ │ mkit attest │ │ (in-toto v1 + DSSE) │ └──────────┬───────────────────┘ │ ┌────────────────┴────────────────┐ ▼ ▼ ┌─────────────────┐ ┌──────────────────────┐ │ repo-key signer │ │ external signer │ │ (Ed25519 from │ │ (subprocess, stdio │ │ .mkit/keys) │ │ protocol; TPM, │ │ │ │ FIDO2/CTAP, SE,…) │ └─────────────────┘ └──────────────────────┘ implemented today, at parity ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ┆ keyless / sigstore — roadmap, not implemented ┆ ┆ (OIDC → short-lived cert; `SigstoreSigner` returns ┆ ┆ `Error::SigstoreNotImplemented` unconditionally) ┆ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ``` 证明携带 commit hash 作为 in-toto 的 `subject`，因此它们可以使用现成的工具（cosign、in-toto-go、自定义验证器）进行验证。任何生成带有 in-toto v1 Statement 的有效 DSSE envelope 的实体都可以对 mkit commit 进行证明；反之，mkit 的证明可被任何符合标准的验证器使用。 多签名者 envelope（一个 envelope，N 个签名）开箱即用 — 请参阅 [`docs/specs/SPEC-ATTESTATIONS.md`](docs/specs/SPEC-ATTESTATIONS.md) §6。 多算法证明流程： ``` mkit keygen --algorithm p256 --print-pubkey mkit attest --algorithm ed25519 \ --additional-signer "algorithm=p256,signer=repo-key" \ --predicate-type https://example.com/sign-off/v1 mkit verify-attest --trust-roots .mkit/attest-trust-roots.toml ``` `verify-attest` 会报告 `UnknownKeyid`，直到每个签名者的密钥被注册为信任根（`mkit trust add --trust-roots .mkit/attest-trust-roots.toml --kind `） — p256 附加签名者的 keyid 是上面 `--print-pubkey` 的输出，但 ed25519 `repo-key` 签名者的证明 keyid 是 `blake3:` 加上其公钥的 BLAKE3 摘要，而不是原始公钥本身；可以从生成的 `.dsse` envelope 的 `keyid` 字段读取它，或者参阅 [`docs/specs/SPEC-ATTESTATIONS.md`](docs/specs/SPEC-ATTESTATIONS.md) §6.5 获取完整的信任根操作指南。 ## 身份与推送认证 **.mkit/keys/default.key** 是一个原始的 Ed25519 seed。相同的 seed 涵盖： - commit / remix 签名 ([`docs/specs/SPEC-SIGNING.md`](docs/specs/SPEC-SIGNING.md)); - 通过 `repo-key` 签名者进行 DSSE 证明签名 ([`docs/specs/SPEC-ATTESTATIONS.md`](docs/specs/SPEC-ATTESTATIONS.md) §6.2); - SSH transport 认证 — OpenSSH 8.0+ 接受原始的 Ed25519 seed 作为 `id_ed25519`，因此相同的密钥可以认证通过 `mkit+ssh://` 进行的 `mkit push`。 对于 `mkit+ssh://` 推送授权，惯用的模式是 Git 的模式：服务器端的 `sshd` 运行 `KeysCommand`，将传入的公钥映射到账户，并且 `mkit serve` 作为该账户执行。mkit 核心**不附带自定义的推送认证协议** — SSH 的 KEX 已经完成了 nonce/签名交换，并且 `AuthorizedKeysCommand` 是用于 `pubkey → account` 的标准服务器端 hook。下游服务可以通过该 hook 接入自己的身份模型（例如，pubkey → 链上所有者地址），而无需更改传输协议。请参阅 [`docs/SSH-SECURITY.md`](docs/SSH-SECURITY.md) 了解 transport 信任模型。 ## CLI 人体工程学 每个子命令都通过 `clap-derive` 解析参数，并遵循 [`docs/CLI.md`](docs/CLI.md) 中记录的 POSIX 约定： - **stdout = 数据, stderr = 诊断信息。** 在干净的 tree 中执行 `mkit status > /tmp/out` 会生成一个空文件；横幅和进度信息会输出到 stderr。 - **在所有读取类命令上提供 `--porcelain` / `--format=json` 模式**（`status`, `log`, `branch`, `blame`, `remote`, `config`）。 - **退出代码遵循 BSD `sysexits(3)`。** Shell 脚本可以区分用户输入错误（64）和暂时性的 transport 失败（75），而无需解析 stderr。 - **信号：** SIGINT/SIGTERM 设置一个由长时间运行的操作轮询的优雅关闭标志。SIGPIPE 被忽略；像 `mkit log | head -1` 这样的 pipeline 可以干净地退出。 ## 性能 mkit 通过 **BLAKE3** hash 命名每个对象，并将大文件拆分为内容定义的 chunk，因此对大文件的小幅修改在磁盘、传输和实际消耗时间（wall-clock time）上只花费修改那部分的成本 — 而不是整个文件。 真正重要的比较是端到端的：使用 `hyperfine` 实时测量真实的 `add`、`commit` 和 `push` 操作，并与 Git 进行正面交锋。这些结果及其完整方法论位于[性能页面](https://mkit.sh/performance)。mkit 在处理大文件及其修改方面明显领先，而在日常操作上与 Git 的运行速度大致相当。 组件微基准测试 — 按算法划分的签名吞吐量，以及针对 `git2` 和 `git` CLI 的 object-commit/pack-create — 位于 [`benchmarks/charts/`](benchmarks/charts/)。具体数值会因硬件、内核、文件系统和缓存状态而异。在 1 MiB 文件大小下创建 packfile，这是 mkit 分块和并行设计所针对的场景：   使用以下命令在本地重现： ``` # 显式命名 bench 目标。`--workspace -- --quick` # 形式会失败：--quick 对于 lib unittest 目标不是有效的选项。 cargo bench -p mkit-benches --bench hashing --bench sign_verify \ --bench object_commit --bench pack_create -- --quick cargo run -p mkit-benches --bin render-charts ``` ## 文档 指南和操作文档位于 [`docs/`](docs/)；传输格式和子系统规范位于 [`docs/specs/`](docs/specs/README.md)。 每个规范都带有自己的 `status:` 标题，反映该文档的确定程度；无论标题如何，[`rust/tests/golden/`](rust/tests/golden/) 下的测试向量都固定了它们描述的 v1 传输和磁盘格式，这些格式在整个 0.x 系列中保持稳定。 | 文档 | 目标受众 | |---|---| | [`docs/INSTALL.md`](docs/INSTALL.md) | 最终用户 — 安装通道、验证、硬件签名器 | | [`docs/CLI.md`](docs/CLI.md) | 最终用户 — 子命令、环境变量、退出代码 | | [`docs/GUIDE-GIT-WORKFLOWS.md`](docs/GUIDE-GIT-WORKFLOWS.md) | 最终用户 — 从 git 迁移、跟踪 git upstream、推送工作回去 | | [`docs/specs/`](docs/specs/README.md) | 实现者和集成商 — 传输格式和子系统规范，带有一行摘要的索引 | | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | 贡献者 — 模块分层和设计说明 | | [`docs/PARITY.md`](docs/PARITY.md) | 贡献者 — v1 范围门、机器输出契约和跟踪的差异（按命令划分的矩阵是 web `/parity` 页面） | | [`docs/PROFILING.md`](docs/PROFILING.md) | 贡献者 — 基准测试和分析工作流 | | [`docs/FUZZ.md`](docs/FUZZ.md) | 贡献者 — fuzz harness 约定 | | [`docs/STYLE-GUIDE.md`](docs/STYLE-GUIDE.md) | 贡献者 — 文档和 commit 的写作风格 | | [`docs/SSH-SECURITY.md`](docs/SSH-SECURITY.md) | 运维人员 — SSH transport 信任模型 | | [`docs/THREAT-MODEL.md`](docs/THREAT-MODEL.md) | 运维人员和审查者 — 信任边界和安全假设 | | [`apps/repo-worker/README.md#run-your-own-instance-self-hosting`](apps/repo-worker/README.md#run-your-own-instance-self-hosting) | 运维人员 — 自托管匿名多人仓库服务器：Cloudflare 套餐/成本要求、R2 bucket 和路由覆盖 | | [`docs/RELEASE.md`](docs/RELEASE.md) | 维护者 — 发布手册：清单、签名、可重现性、供应链、crates.io | ## 构建 ``` cd rust cargo build --release # mkit binary → target/release/mkit cargo test --workspace # all crates cargo fmt --check # formatting gate (CI-enforced) cargo clippy --all-targets -- -D warnings # lint gate ``` ## License 在以下两个许可之下进行双重许可： - MIT License ([`LICENSE-MIT`](LICENSE-MIT)) - Apache License, Version 2.0 ([`LICENSE-APACHE`](LICENSE-APACHE)) 由您选择。除非您明确声明，否则为本项目故意提交的任何贡献均应按上述方式进行双重许可，不附加任何额外的条款或条件。 mkit 由 Official Unofficial, Inc. 发布；mkit 的名称和商标归该公司所有。

标签：Rust, 内容寻址, 可视化界面, 安全可观测性, 版本控制, 签名认证, 网络流量审计, 通知系统