truestamp/truestamp-cli

# Truestamp CLI [](https://github.com/truestamp/truestamp-cli/actions/workflows/ci.yml) [](https://github.com/truestamp/truestamp-cli/releases/latest) [](https://pkg.go.dev/github.com/truestamp/truestamp-cli) [](./LICENSE) 使用 [Truestamp](https://truestamp.com) 进行加密时间戳的独立 Go CLI。端到端验证 Truestamp 证明包 —— 包括用户声明 (claims)、哈希链、Merkle 包含证明、Ed25519 签名以及公有区块链承诺 —— 完全不依赖于 Truestamp 服务。 以单个静态二进制文件形式发布。无需任何 runtime。 ## 📖 文档 - **[EXAMPLES.md](./EXAMPLES.md)** — 实操演示，包含每个子命令的真实且可直接复制的示例。包括 pipeline 方案、`--json` / `jq` 模式、CI 约定以及离线/物理隔离环境下的用法。**从这里开始了解 CLI 的功能。** - **[CONTRIBUTING.md](./CONTRIBUTING.md)** — 开发环境配置、测试分类及任务参考。 - **[CHANGELOG.md](./CHANGELOG.md)** — 版本发布说明。 - 各命令帮助文档：`truestamp --help`。 ## 安装说明 ### 安装脚本 (macOS, Linux) ``` curl -fsSL https://get.truestamp.com/install.sh | sh ``` 该脚本会检测您的操作系统/架构 (darwin/linux × amd64/arm64)，解析最新的发布版本，验证 SHA-256 校验和，将二进制文件安装到 `/usr/local/bin`（如果前者不可写，则安装到 `~/.local/bin`），并清除 macOS 的隔离属性，使二进制文件可以在没有 Gatekeeper 提示的情况下运行。之后若要升级，请运行 `truestamp upgrade`（它会匹配对应的安装方式 —— 对于安装脚本用户，这会下载新版本，验证 SHA-256 + cosign，并原地原子替换二进制文件）。重新运行 curl pipeline 也是可行的。 固定特定版本： ``` curl -fsSL https://get.truestamp.com/install.sh | TRUESTAMP_VERSION=vX.Y.Z sh ``` 安装到自定义目录： ``` curl -fsSL https://get.truestamp.com/install.sh | TRUESTAMP_INSTALL_DIR=~/bin sh ``` 包含相同说明的网页：[get.truestamp.com](https://get.truestamp.com)。 ### Homebrew (macOS 和 Linux) ``` brew install truestamp/tap/truestamp-cli ``` 升级： ``` brew upgrade truestamp/tap/truestamp-cli ``` ### Go install ``` go install github.com/truestamp/truestamp-cli/cmd/truestamp@latest ``` 在 `$GOBIN/truestamp` (默认 `~/go/bin/truestamp`) 处生成二进制文件。需要 Go 1.22 或更高版本。 必须要有 `/cmd/truestamp` 后缀，这样 `go` 工具链才会将二进制文件命名为 `truestamp`，而不是 `truestamp-cli` (Go 会从包路径的最后一个元素来派生二进制文件的名称)。 ### 直接下载 从 [Releases 页面](https://github.com/truestamp/truestamp-cli/releases/latest) 获取适合您平台的压缩包： - `truestamp-cli__darwin_arm64.tar.gz` — Apple Silicon - `truestamp-cli__darwin_amd64.tar.gz` — Intel Mac - `truestamp-cli__linux_amd64.tar.gz` - `truestamp-cli__linux_arm64.tar.gz` - `truestamp-cli__windows_amd64.zip` - `truestamp-cli__windows_arm64.zip` 解压并将 `truestamp` 放置到您的 `PATH` 路径下的某个位置。 ## 验证下载 每次 GitHub Release 都会在压缩包旁发布一个 `checksums.txt`。要手动验证下载： ``` # 从包含下载的 archive 和 checksums.txt 的目录中。 sha256sum -c checksums.txt --ignore-missing # GNU coreutils # 或者在 macOS 上没有 coreutils 的情况下： shasum -a 256 -c checksums.txt --ignore-missing ``` `install.sh` 安装程序和 Homebrew cask 都会自动验证 SHA-256 —— 本节仅在您自己下载 tar 压缩包时需要。 ## 快速开始 三个主要命令 —— `create`、`download`、`verify` —— 构成了 Truestamp 条目的完整生命周期。与 Truestamp API 通信的命令 (`create`, `download`) 需要 API 密钥 (`--api-key`, `TRUESTAMP_API_KEY`, 或配置文件)。`verify` 默认完全在本地运行。 ### 创建条目 Truestamp 支持两种提交模式。请根据您要加时间戳的对象的 形状选择合适的模式。 **External-hash 模式** —— 用于您可以保留的文件。该文件 永远不会离开您的设备；仅提交其 SHA-256。 ``` truestamp create document.pdf ``` 在底层，这会计算文件的 SHA-256，使用文件名 作为条目名称，并将哈希值注册到 Truestamp API，以便 将其包含在下一个区块中。 **Claims-as-source-of-truth 模式** —— 用于没有 文件的事物。书面声明、发明披露、带有日期的事实、 版本发布说明。声明 (claims) 内容本身就是被加时间戳的对象， 因此无需与证明一起保留任何文件。 ``` truestamp create -n "Invention" \ -d "On this day I claim the following novel approach as my own original work." ``` 在此模式下，服务器要求声明 (claims) 内容必须具有实际意义： 至少 32 个字符的描述 (或非空的 `--metadata`)。CLI 会在任何网络 往返之前在本地进行此项检查。 其他输入方式： ``` truestamp create --file document.pdf # External hash: explicit file truestamp create --file # External hash: interactive picker truestamp create -c claims.json # Either mode: claims from JSON file cat claims.json | truestamp create -C # Either mode: claims from stdin truestamp create -n "Q1 Report" --hash abc123... \ # External hash: build from flags -v public -t finance,reports truestamp create -n "Title" --metadata '{"k":"v"}' # Claims-only: metadata satisfies the rule ``` `--hash` 和 `--hash-type` 标志是共同必需的：提供这两者 (external-hash 模式) 或者都不提供 (claims-as-source-of-truth 模式)。 只提供其中一个将被拒绝。 用于脚本编写的 JSON 输出： ``` truestamp create document.pdf --json ``` 在 claims-as-source-of-truth 模式下，JSON 输出会省略 `hash` 和 `hash_type` 键；脚本可以使用 `jq 'has("hash")'` 来 根据模式进行分支处理。 ### 下载证明包 在条目被提交到区块后，通过其 ID 下载证明。条目 ID 是 ULID；熵观测 ID 是 UUIDv7；该命令会根据格式自动检测是哪一种： ``` truestamp download 01KNN33GX5E470CB9TRWAYF9DD ``` 选择格式和输出路径： ``` truestamp download -f cbor -o proof.cbor 01KNN33GX5E470CB9TRWAYF9DD truestamp download -o /tmp/proof.json 01KNN33GX5E470CB9TRWAYF9DD ``` 下载熵证明 (UUIDv7 会触发熵证明模式)： ``` truestamp download 019d6a32-13e6-72b0-97e5-3779231ea97b ``` ### 验证证明 ``` truestamp verify proof.json ``` 成功时退出码为 `0`，失败或结构错误时退出码为 `1`。 离线验证 (不调用 Truestamp、Stellar 或 Bitcoin API)： ``` truestamp verify proof.json --skip-external ``` 用于脚本编写的静默模式： ``` truestamp verify proof.json --silent && echo valid || echo invalid ``` 其他输入源： ``` truestamp verify https://example.com/proof.json # URL truestamp verify --file # Interactive file picker truestamp verify --url # Interactive URL prompt cat proof.json | truestamp verify # stdin pipe ``` ## 命令 ``` truestamp create [file] Create a new Truestamp item (submit claims / file hash) truestamp download Download a proof bundle for an item or entropy observation truestamp verify [proof] Verify a Truestamp proof bundle truestamp hash [path ...] Compute cryptographic digests (SHA-2 / SHA-3 / BLAKE2 / MD5 / SHA-1) truestamp encode [file] Encode raw bytes into hex / base64 / base64url truestamp decode [file] Decode hex / base64 / base64url into raw bytes truestamp jcs [file] Canonicalize JSON per RFC 8785 truestamp convert time [input] Convert timestamps across zones / Unix formats truestamp convert proof [file] Convert a proof bundle between JSON and CBOR truestamp convert id [value] Extract the embedded timestamp from a ULID or UUIDv7 truestamp convert keyid [pubkey] Derive the 4-byte Truestamp kid from an Ed25519 public key truestamp convert merkle [compact] Decode a compact base64url Merkle proof truestamp upgrade Upgrade the CLI to the latest release (install-method aware) truestamp config path Print the config file path truestamp config show Print the resolved configuration (API key masked) truestamp config init Create a default config file truestamp version Print detailed build and runtime info (includes detected install method) truestamp --version Terse one-line version truestamp completion Generate shell completions (bash, zsh, fish) ``` 运行 `truestamp --help` 以查看各命令的标志。 ### 可组合的 pipeline 所有操作都读取 stdin，支持带可选路径的 `--file` / `--url`，并打印到 stdout —— 因此这些命令可以作为 Unix 管道组合使用，并替代一大堆外部工具 (`sha256sum`, `shasum`, `xxd`, `base64`, `jq`, `date`)： ``` # 对文件计算 SHA-256，输出字节与 sha256sum / shasum 完全相同 truestamp hash doc.pdf # 选择不同的 algorithm（支持 14 种；请参阅 `truestamp hash --list`） truestamp hash -a blake2b-512 doc.pdf truestamp hash -a sha3-256 --style bsd doc.pdf # 本地重新计算 Truestamp claims_hash —— 旗舰级用例 truestamp hash --prefix 0x11 --jcs -a sha256 --style bare --no-filename < claims.json # 或者等效地，作为显式 pipeline： truestamp jcs < claims.json | truestamp hash --prefix 0x11 -a sha256 --style bare --no-filename # 在 wire formats 之间 round-trip proof 并进行端到端 verify truestamp convert proof --to cbor proof.json | truestamp verify --skip-external # 从 Ed25519 pubkey 派生 4 字节的 kid fingerprint truestamp convert keyid CTwMqDZnPd/QTLSq8aTeSD3a+j2DQxKcGfhhIYJQ65Y= # 无需调用 `date` 进行时区数学运算 truestamp convert time 1700000000 --to-zone America/New_York truestamp convert time "2024-06-15T12:00:00Z" --to-zone Asia/Kolkata # ULID / UUIDv7 时间戳提取 truestamp convert id 01KNN33GX5E470CB9TRWAYF9DD truestamp convert id 019cf813-99b8-730a-84f1-5a711a9c355e --to-zone Local ``` 每个命令都支持 `--json` (用于脚本的结构化输出) 和 `-s` / `--silent` (仅返回退出码)。`truestamp hash` 默认输出兼容 GNU `sha256sum` 的格式，`--style bsd` 则切换为 BSD `shasum --tag` 格式。 **更多示例：** [EXAMPLES.md](./EXAMPLES.md) 涵盖了每个子命令，提供可直接复制的方案、脚本模式、CI 约定和离线用法。 ## 升级 `truestamp upgrade` 命令能够感知安装方式 —— 它会检测二进制文件的安装方式 (Homebrew、`go install` 或 install.sh / 手动 tarball)，并针对每种方式执行正确的操作： | 安装方式 | `truestamp upgrade` 行为 | | -------------- | ---------------------------- | | Homebrew | 打印 `brew upgrade --cask truestamp/tap/truestamp-cli` (不触碰 Homebrew 前缀)。 | | `go install` | 打印 `go install github.com/truestamp/truestamp-cli/cmd/truestamp@latest`。 | | install.sh / 手动 | 下载最新版本的 tarball，验证 SHA-256 (强制，纯 Go) 和 cosign 签名 (尽力而为；如果设置了 `TRUESTAMP_REQUIRE_COSIGN=1` 则为强制；默认在 `$PATH` 中查找 `cosign`，或者在配置中使用 `cosign_path` 或通过 `TRUESTAMP_COSIGN_PATH` 环境变量指定绝对路径以防御 `$PATH` 劫持)，解压二进制文件，原子替换正在运行的可执行文件，并清除 macOS 的隔离 xattr。会保留之前二进制文件的 `.bak.` 备份 7 天。 | | Windows (任何方式) | 打印 `go install ...@latest`。在此版本中不支持 Windows 上的原地升级。 | 随时检查检测到的安装方式： ``` truestamp version # output includes `install ` ``` 标志： ``` truestamp upgrade --check # only report whether an upgrade is available (does not install) truestamp upgrade --yes # skip the interactive confirmation prompt truestamp upgrade --version v0.4.0 # pin to a specific release tag (also the opt-in path for pre-releases) ``` `--check` 退出码：`0` 已是最新，`1` 有可用升级，`2` 网络错误，`3` 最新版本是预发布版本 (不会自动安装；请传入 `--version ` 以显式安装)。 ### 被动升级提示 每 24 小时 (缓存在 `$XDG_CACHE_HOME/truestamp/upgrade-check.json`)，如果有更新的版本可用，其他命令会在 stderr 上打印一行提示。在 CI 环境中 (`CI`, `GITHUB_ACTIONS`, `GITLAB_CI`, `CIRCLECI`, `BUILDKITE`, `JENKINS_HOME`, `TF_BUILD`)、stderr 不是 TTY 时、当前版本是本地 `dev` 构建时，以及解析出的最新版本是预发布版本时，该提示会自动抑制。要选择退出： ``` truestamp --no-upgrade-check verify proof.json # 或者持久化地： export TRUESTAMP_NO_UPGRADE_CHECK=1 ``` 该提示始终在 stderr 上，因此绝不会污染 stdout (`truestamp verify proof.json > out.json` 用于脚本是安全的)。 ## 配置 设置按以下顺序解析 (后者覆盖前者)： 1. 编译时的默认值 2. 配置文件 (默认为 `~/.config/truestamp/config.toml`) 3. 环境变量 (`TRUESTAMP_*`) 4. CLI 标志 ### 全局标志 | 标志 | 环境变量 | 默认值 | | ---- | ------- | ------- | | `--config` | | `~/.config/truestamp/config.toml` | | `--api-url` | `TRUESTAMP_API_URL` | `https://www.truestamp.com/api/json` | | `--api-key` | `TRUESTAMP_API_KEY` | | | `--keyring-url` | `TRUESTAMP_KEYRING_URL` | `https://www.truestamp.com/.well-known/keyring.json` | | `--http-timeout` | `TRUESTAMP_HTTP_TIMEOUT` | `10s` | | `--no-color` | `NO_COLOR` | `false` | | `--no-upgrade-check` | `TRUESTAMP_NO_UPGRADE_CHECK` | `false` | | (仅限配置文件 / 环境变量：`cosign_path`) | `TRUESTAMP_COSIGN_PATH` | | `cosign_path` 指定 `truestamp upgrade` 用于验证发布工件签名的 `cosign` 二进制文件路径。留空 (默认) 表示“使用 `$PATH` 查找”；在强化环境中，请将其设置为绝对路径 (例如 `/opt/cosign/bin/cosign`)，以避免 `$PATH` 劫持。在配置加载时会拒绝相对路径。除非您实际运行了 `truestamp upgrade`，否则此设置无效。 ### 特定于 verify 的标志 | 标志 | 环境变量 | 默认值 | | ---- | ------- | ------- | | `--file [path]` | | | | `--url [url]` | | | | `--hash` | | | | `--silent` / `-s` | `TRUESTAMP_VERIFY_SILENT` | `false` | | `--json` | `TRUESTAMP_VERIFY_JSON` | `false` | | `--skip-external` | `TRUESTAMP_VERIFY_SKIP_EXTERNAL` | `false` | | `--skip-signatures` | `TRUESTAMP_VERIFY_SKIP_SIGNATURES` | `false` | ## 验证内容 1. 根据已发布的公钥环验证签名密钥 2. 证明结构 (必需字段、区块引用) 3. 主题哈希 —— 声明哈希 (`0x11`)、时间戳验证、条目哈希 (`0x13`) 4. 针对区块根的 RFC 6962 Merkle 包含证明 5. 区块哈希 (`0x32`) 推导 6. Epoch 证明：区块哈希 → 每个公有区块链承诺根 7. 对二进制 payload 的 Ed25519 证明签名 8. 时间顺序 (条目提交发生在区块之前) 9. 通过 Horizon API 验证 Stellar 承诺 (memo + ledger) 10. 通过本地加密验证 Bitcoin 承诺 (OP_RETURN, txid, 部分 Merkle 树) 加上可选的 Blockstream API 可通过 `--skip-external` 和 `--skip-signatures` 选择性地跳过。 ## 退出码 |代码 | 含义 | | ---- | ------- | | `0` | 成功。对于 `verify`，证明有效。对于 `upgrade --check`，CLI 已是最新。 | | `1` | 错误。验证失败、网络故障、无效输入或任何其他 runtime 错误。对于 `upgrade --check`，有更新的版本可用。 | | `2` | 留给其他命令将来使用 (用法 / 标志解析错误)。对于 `upgrade --check`，网络错误阻止了检查。 | | `3` | 仅用于 `upgrade --check`：最新版本是预发布版本，不会自动安装。请传入 `--version ` 以显式安装。 | 根据特定退出码进行分支处理的脚本应仅检查 `upgrade --check` 文档中记录的代码；对于其他命令，将任何非零值视为失败。 ## 贡献 开发环境配置、测试和发布流程详见 [`CONTRIBUTING.md`](./CONTRIBUTING.md)。安全问题请参阅 [`SECURITY.md`](./SECURITY.md)。行为规范详见 [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md)。 ## 相关项目 - [`truestamp/truestamp-v2`](https://github.com/truestamp/truestamp-v2) —— 生成此 CLI 所验证的证明的 Truestamp 服务。 - [`truestamp/homebrew-tap`](https://github.com/truestamp/homebrew-tap) —— 此 CLI 发布到的 Homebrew tap。 ## 许可证 MIT。请参阅 [LICENSE](./LICENSE)。 Copyright (c) 2019-2026 [Truestamp, Inc.](https://truestamp.com) All rights reserved.

标签：EVTX分析, Go, Homebrew安装, LNA, Ruby工具, Zenmap, 区块链, 密码学, 手动系统调用, 数据完整性, 日志审计, 时间戳