digstore

一个 Git 形态、经过加密的、内容寻址的存储，可编译为单一的自我防御 WebAssembly 模块。

`digstore` 为你提供了 Git 风格的命令 —— `init`、`add`、`commit`、`log`、`clone`、 `push`、`pull` —— 用于一个**静态加密**并编译为**单一 `.wasm` 文件**的存储。 该文件既是你的数据，也是控制其访问权限的服务器。存储或中继它的主机只能看到由 哈希寻址的密文；它无法读取其携带的内容。 你使用 URN 对内容进行寻址，而 URN *就是* 密钥：它既能定位又能 解密。递给某人一个 URN，他们就可以读取该资源；如果没有它，他们将无法读取， 而且无需管理单独的密码或访问列表。 与 Git 不同，digstore 专为**构建输出**而非仓库源码设计 —— 你只需将存储指向 类似 `dist/` 的目录，它就会捕获其中的内容。 ## 安装 ### Windows (安装程序) 1. 从 [Releases](https://github.com/DIG-Network/digstore/releases) 页面下载 `DigStore *-setup.exe`（或 `.msi`）。 2. 运行它。它会按用户进行安装（无管理员提示）并将 `digstore` 添加到你的 `PATH` 中。 3. 打开一个**新**终端并检查其是否正常工作： digstore --version ### 从源码构建 (任意平台) 你需要 [Rust](https://rustup.rs)（通过 `rust-toolchain.toml` 锁定在 1.94.1 版本）。 CLI 中内嵌了一个 WebAssembly guest，因此请先构建它： ``` rustup target add wasm32-unknown-unknown cargo build -p digstore-guest --target wasm32-unknown-unknown --release cargo build -p digstore-cli --release ``` 二进制文件位于 `target/release/digstore`（在 Windows 上为 `digstore.exe`）。将其复制 到你 `PATH` 中的某个位置。 ## 快速开始 ``` mkdir my-project && cd my-project digstore init # create a .dig workspace + a "default" store echo "hello" > readme.txt digstore add readme.txt --key readme digstore commit -m "first generation" digstore log # list generations (each root hash = a commit) digstore urn readme.txt # preview the URN a file will have — no guessing # 读回一个 resource (store id + root 来自 `digstore log --json`): digstore cat urn:dig:chia::/readme ``` 命令会从你所在的位置向上查找来发现 `.dig/` 工作区（就像 Git 一样）。`add`/`urn` 在存储的**内容根目录**（默认为当前目录；通常是一个构建目录 —— 见下文）上运行，并且资源键始终 相对于该根目录，因此无论你从哪个子目录运行， URN 都是稳定的。 ## 每个项目包含多个存储 一个项目可以在一个 `.dig/` 工作区中容纳多个存储（“capsules”），每个存储都有 各自的内容、密钥和历史记录。 ``` digstore init site --dir dist # a store named "site" that captures ./dist digstore init docs --dir build/docs digstore stores # list stores; * marks the active one + capacity digstore use site # switch the active store digstore --store site add -A # stage everything under dist/ into "site" digstore staged # what's staged + size + remaining headroom digstore unstage # clear staging digstore commit -m "v1" # seal a generation; writes a local urns.json index ``` - **存储选择：** `--store ` > 活动存储 (`use`) > 如果只有 一个存储，则为该单个存储。 - **内容根目录：** 每个存储捕获一个构建目录（默认：当前 目录；在 `init` 时使用 `--dir` 设置，或通过 `digstore dir ` 设置）。`-C/--cwd ` 为单个命令覆盖此设置。 - **单存储上限：** 每个存储的暂存内容上限为 **128 MB**， 在 `add` 时强制执行（并在 `commit` 时进行防御性检查）；剩余容量可通过 `add`、`status`、`staged` 和 `stores` 显示。 - **URN 清单：** `commit` 会写入本地 `urns.json` / `urns.txt` —— 这是 发布者针对该代际的每一个可共享 URN 的索引。 ## 内容如何寻址：URN 每个资源都由一个 URN 命名。该 URN 单独即可定位**并**解密它： ``` urn:dig::[:][/] ``` | 部分 | 含义 | |---|---| | `` | 链标识符，例如 `chia` | | `` | 你的 64 位十六进制存储 ID（必填） | | `` | 可选：锁定特定代际；省略则为当前代际 | | `` | 可选：哪个资源（内容根目录的相对路径） | `digstore urn [PATHS]` 会预览文件针对活动存储*将具有*的确切 URN（及检索密钥）—— 这样你就可以在提交前进行检查，而无需猜测。 ## 公开与私有存储 ``` digstore init # public: anyone with the URN can read digstore init --private # private: URN locates, but reading also needs a secret salt ``` - **公开** —— 该 URN 足以进行解密。 - **私有** —— 解密还需要发布者持有并通过带外方式共享的 secret salt。在执行 `cat`/`checkout` 时通过 `--salt ` 传入。 ## 通过远程进行共享 远程是一个用于存储和提供 `.wasm` 模块服务的 HTTPS endpoint。 ``` # publisher digstore remote add origin https://example.com/stores/ digstore push origin # consumer (全新目录) digstore clone https://example.com/stores/ digstore cat urn:dig:chia::/readme digstore pull origin # later: fetch the publisher's newer generation ``` `clone`/`pull` 会在安装**之前验证**它们下载的内容：该模块必须 与你请求的存储 ID 匹配，并且提供的根必须带有发布者的 签名。恶意或损坏的服务器无法向你提供伪造的内容 —— 该命令将会 执行失败。远程必须是 `https://`（仅对 `localhost` 允许使用普通的 `http://`）。 ## 链上锚定 (Chia 主网) 每个存储都**锚定在 Chia 主网上**。`digstore init` 会在链上铸造一个空的存储 singleton，并且该 singleton 的 **launcher id 会成为存储 ID**。 随后，每次执行 `digstore commit` 都会通过链上更新将该新代际的根推送到该 singleton，并在本地完成该代际的最终确认**之前阻塞，直到更新得到确认**。 ### 1. 设置钱包 seed digstore 会将加密的 BIP-39 seed 保存在 `~/.dig/seed.enc` 中。 ``` digstore seed generate # create a new mnemonic (shown once — back it up) # 或 digstore seed import # import an existing mnemonic digstore seed status # is a seed present / unlocked? digstore lock # clear the cached-unlock session ``` 该 seed 使用密码进行加密（Argon2id + AES-256-GCM）。解锁后，它会被缓存一段可配置的 TTL；`DIGSTORE_PASSPHRASE` 以非交互方式（用于 CI/脚本）提供密码。全局设置位于 `~/.dig/config.toml`（`coinset_url`、`unlock_ttl`、`fee`）。 ### 2. 为钱包充值 铸造和更新同时需要消耗 XCH（交易手续费）和 DIG（DIG token，一种 Chia CAT）。由你的 seed 派生的钱包**同时**需要这两者。运行 `digstore balance` 以查看你当前可用的 XCH (mojos)、DIG（3 位小数显示）以及钱包 接收地址。如果其中任何一个不足，`init`/`commit` 将会阻塞，提前披露确切的花费，并打印**接收地址**以便充值： ``` insufficient funds: need mojos, have ; fund xch1… ``` XCH 和 DIG 都在同一个 `xch1…` 接收地址接收（DIG 作为 CAT）。 将资金发送到那里，等待其确认，然后重试。 ### 3. Init 进行铸造，commit 进行锚定 ``` digstore init # mints the store singleton; store id = launcher id # blocks until the mint confirms on mainnet digstore add readme.txt --key readme digstore commit -m "first generation" # pushes the new root on-chain; blocks until # confirmed, then finalizes the generation locally ``` 这两个命令都接受 `--wait-timeout `（默认为 `300`），用于设置等待 确认的时间。在确认超时的情况下，该存储将保持**待定**状态（并且本地 代际*不会*被最终确认）—— 它是可恢复的，并未丢失。 ### 4. 恢复 / 检查锚定 ``` digstore anchor # resume a pending anchor: confirm the chain coin # and flip the store to confirmed (idempotent) digstore anchor status # read-only: show the store's anchor state digstore anchor status --json # machine-readable state ``` 每个存储的锚定状态（网络、存储 ID / launcher、coin id、状态、上一个根、 上一个 tx id、确认高度）都会记录在存储的 `anchor.toml` 中。 编译后的 `.dig` 模块还直接在其 data section 中嵌入了链上指针（网络、launcher/store id、 当前 coin id、确认高度以及 coinset endpoint 提示）。`digstore anchor status` 会将其与本地 `anchor.toml` 状态一起展示 （使用 `--json` 获取机器可读的输出）；`digstore anchor inspect ` 可在无需本地工作区的情况下，从任何模块文件中转储该 指针。嵌入的 coinset URL 仅作为提示 —— 本地配置和标志 始终具有优先权。 ## 命令参考 | 命令 | 功能说明 | |---|---| | `digstore init [name] [--dir ] [--private] [--wait-timeout ]` | 创建存储（默认名称为 `default`）；在主网上铸造其 singleton（存储 ID = launcher id）；`--dir` 设置其内容根目录 | | `digstore stores` | 列出存储及其活动标记、根、内容根目录、容量 | | `digstore use ` | 设置活动存储 | | `digstore dir []` | 显示或设置活动存储的内容根目录 | | `digstore add [-A] [--key ]` | 暂存文件（`-A` = 整个内容根目录） | | `digstore staged` / `digstore unstage` | 列出暂存区 / 清空暂存区 | | `digstore commit [-m ] [--wait-timeout ]` | 封装新代际，在主网上锚定其根（阻塞直到确认），编译模块，写入 URN 清单 | | `digstore status` | 显示暂存/已修改/未跟踪的内容及容量 | | `digstore log [--limit N]` / `digstore diff ` | 列出 / 比较代际 | | `digstore urn [PATHS…] [--root ]` | 预览文件将拥有的 URN | | `digstore cat [--salt ] [--verify-proof]` | 通过 URN 读取资源 | | `digstore checkout --out [--salt ]` | 将整个代际写入目录 | | `digstore remote add\|list\|remove …` | 管理远程 | | `digstore clone ` / `push [remote]` / `pull [remote]` | 与远程同步（已验证） | | `digstore anchor [--wait-timeout ]` | 恢复待定的链上锚定（确认 coin，翻转为已确认） | | `digstore anchor status [--json]` | 显示活动存储的锚定状态 + 内嵌的模块链指针（只读） | | `digstore anchor inspect [--json]` | 转储任意模块文件中内嵌的链上指针（只读，无需工作区） | | `digstore balance [--json]` | 显示可用的 XCH (mojos) 和 DIG（3 位小数）+ 钱包接收地址（只读） | | `digstore seed generate\|import\|status` / `digstore lock` | 管理用于锚定的加密钱包 seed | 全局标志：`--store `（指定特定存储），`-C/--cwd ` （此命令的操作目录），`--dig-dir `（工作区位置）， `--json`（机器可读），`--quiet`，`--verbose`，`--color `。 ### 钱包 seed `digstore seed generate|import|status` 和 `digstore lock` 用于管理加密的 BIP-39 钱包 seed，该 seed 用于链上锚定 —— 详情请参阅 上方的[链上锚定](#on-chain-anchoring-chia-mainnet)。 ## 这能为你带来什么 - **静态加密。** 内容使用从其 URN 派生的密钥进行加密。 没有任何地方存储可供恢复的密钥 —— 丢失 URN，即丢失读取权限。 - **对提供商不可见的托管。** 无论谁托管你的存储，持有的都只是由哈希作为 密钥的密文；他们无法扫描它或读取请求。 - **经过验证的下载。** `clone`/`pull` 会拒绝不是真正的、经过发布者签名的存储 内容。 - **统一且独立。** 存储就是一个单一的 `.wasm`，被填充至统一的 大小，因此其字节不会泄露有关其包含内容多少的信息。复制它即可进行 备份；运行它即可提供服务。 ## 安全性 安全态势、应用的加固措施以及已知的残留风险均记录 在 [`SECURITY.md`](SECURITY.md) 中。请私下向 维护者报告漏洞，而不是公开提出 issue。 ## 贡献 构建、测试和贡献指南位于 [`CONTRIBUTING.md`](CONTRIBUTING.md) 中。 ## 许可证 基于 [GNU General Public License v2.0](LICENSE) 授权 —— 这与 Git 的许可证相同。