@roson_liu/encrypt-tool

v0.8.2

Published

2 months ago

Cross-platform CLI encryption tool for files, directories, text, and RSA helper workflows

0High
0Medium
0Low

roson_liu

encrypt decrypt cli rsa aes security aes-256-gcm scrypt cross-platform

Encrypt Tool

跨平台 Node.js 命令行加密工具，支持文件、目录、文本、Hash、RSA-OAEP 和公开容器信息查看。

特性

文件加密与解密，输出单个 .enc 容器文件。
目录加密支持 archive 和 per-file 两种模式。
使用 AES-256-GCM 认证加密和 scrypt 密码派生。
加密容器的原始名称、目录 entry metadata 和统计 footer 位于认证后的加密记录中。
文本命令支持标准输入输出，输入和输出上限为 16 MiB。
RSA 只支持公钥加密、私钥解密，算法为 RSA-OAEP-SHA256。
Hash 支持文件、文本和标准输入。
支持中文和英文提示及 CLI help。
支持安装和卸载 PowerShell Tab 补全。
解密先写临时文件或临时目录，完成容器完整性校验后再提交目标。

安装

npm install -g @roson_liu/encrypt-tool

本地开发：

npm install
npm run build
node dist/cli.js --help

发布到 npm 官方

发布前必须先递增版本号，并同步更新 package.json 与 package-lock.json。推荐使用 npm 自动同步两个文件：

npm version patch --no-git-tag-version

根据变更范围也可以使用 minor 或 major。然后登录 npm 官方 registry 并完成发布检查：

npm login --registry=https://registry.npmjs.org
npm whoami --registry=https://registry.npmjs.org
npm run build
npm test
npm run pack:check
npm run smoke:install
npm audit --omit=dev --registry=https://registry.npmjs.org
npm publish --access public --registry=https://registry.npmjs.org

npm publish 会自动执行 prepublishOnly，因此发布前会再次执行完整测试、打包检查和安装 smoke test；生产依赖审计仍需按上面的发布清单单独执行。

@roson_liu/encrypt-tool 是 scoped package，首次公开发布需要 --access public。发布完成后可以核对官方 registry 的版本：

npm view @roson_liu/encrypt-tool version --registry=https://registry.npmjs.org

发布后还应验证用户实际安装到的 npm 包。设置 SMOKE_PACKAGE_SPEC 时，smoke test 会安装指定的 registry 版本；不设置时则打包并安装当前工作区版本：

$publishedVersion = npm.cmd view @roson_liu/encrypt-tool version --registry=https://registry.npmjs.org
$env:SMOKE_PACKAGE_SPEC="@roson_liu/encrypt-tool@$publishedVersion"
npm run smoke:install

完整发布约束和待验证事项见 ROADMAP.md。执行 npm publish 前必须确认版本号、登录账号、registry 和授权范围。

命令概览

encrypt-tool enc [input]
encrypt-tool dec [input]
encrypt-tool info [input]
encrypt-tool text enc|dec
encrypt-tool hash [input]
encrypt-tool rsa gen|enc|dec
encrypt-tool completion install|uninstall powershell

encrypt、decrypt、inspect、digest、gen-key、text encrypt 和 text decrypt 等别名也可用。RSA 的 enc 位置参数是待处理的文本，不是文件路径。

| 命令 | 用途 | | --- | --- | | enc / encrypt | 将文件或目录加密为带认证的 .enc 容器。 | | dec / decrypt | 解密 .enc 容器并恢复文件或目录内容。 | | info / inspect | 查看公开 .enc 元数据，不解密受保护内容。 | | text enc / text dec | 将小文本与 Base64URL 密文互相转换。 | | hash / digest | 计算文件、文本或标准输入摘要。 | | rsa gen / rsa enc / rsa dec | 生成 RSA 密钥，或使用 RSA-OAEP-SHA256 处理小文本。 | | completion install / completion uninstall | 安装或卸载 PowerShell Tab 补全。 |

大小与资源限制

以下是面向用户的实际使用上限，具体结构级预算见技术文档。

| 使用方式 | 大致可处理大小 | | --- | --- | | 普通文件加密/解密 | 约 64 GiB 以内 | | archive 目录加密/解密 | 目录内普通文件合计约 64 GiB 以内，最多约 100 万个文件/目录项 | | per-file 目录加密/解密 | 所有文件合计约 64 GiB 以内；大量小文件可能先达到条目数量上限 | | 文本加密/解密 | 最大 16 MiB | | RSA 文本加密 | 不用于文件；2048/3072/4096 位密钥分别约支持 190/318/446 字节 |

表中的“约 64 GiB”会受到容器结构开销和文件数量影响，不代表原始明文一定可以完整达到 64 GiB。超出限制时，加密会失败并清理临时输出，解密会拒绝容器并清理临时恢复目录。

所有限制同时生效，任意一项先达到上限都会停止处理。默认 16 MiB 分块下，64 GiB 容器预算大约只容纳 4,096 个满容量 data record；1,000,000 条 record/entry 上限主要用于限制大量小文件和 metadata，不会把总容量扩大到 16 TiB。

文件加密与解密

encrypt-tool enc ./a.txt --password-file ./password.txt -o ./a.txt.enc
encrypt-tool dec ./a.txt.enc --password-file ./password.txt -o ./a.txt

工具不提供 --password <value>，避免密码进入 shell 历史。密码文件读取后只去除末尾连续的 CR/LF，普通空格会保留。

非交互环境缺少输入路径或密码文件时会直接失败，不会等待交互式提示。

目录加密

两种目录模式的输入和最终输出相同，区别在于 .enc 内部的组织方式。

`archive` 模式

把目录内容作为 tar.gz 流整体写入一个 archive entry，适合备份、传输和整体恢复。非交互环境未指定模式时默认使用该模式。

encrypt-tool enc ./docs --mode archive --password-file ./password.txt -o ./docs.enc
encrypt-tool dec ./docs.enc --password-file ./password.txt -o ./docs

`per-file` 模式

在同一个 .enc 容器内为目录和文件写入加密 entry metadata，普通文件内容使用对应 entry 的 data records。该模式当前仍按顺序整体恢复，不支持随机解密单个文件。

encrypt-tool enc ./docs --mode per-file --password-file ./password.txt -o ./docs.enc
encrypt-tool dec ./docs.enc --password-file ./password.txt -o ./docs

当前目录安全规则：

顶层输入符号链接被拒绝。
per-file 源目录中的符号链接被明确拒绝。
解密拒绝绝对路径、路径穿越和已知输出路径中的 symlink/junction。
当前主要支持普通文件和目录；单文件及 archive/per-file 源目录中的符号链接、硬链接和特殊文件会明确拒绝，archive 解密不会恢复普通文件的执行权限；跨平台权限恢复和完整 TOCTOU 原子性仍不属于当前已验证能力，相关事项见 ROADMAP.md。

文本加密与解密

文本命令适合小内容，最大输入/输出为 16 MiB，详见大小与资源限制。非交互运行必须提供密码文件。

echo "hello" | encrypt-tool text enc --password-file ./password.txt
echo "<ciphertext>" | encrypt-tool text dec --password-file ./password.txt

加密结果是完整 .enc 容器的 Base64URL 表示。文本解密会使用系统临时目录保存密文中间文件，并在完成后清理。

Hash / Digest

Hash 不需要密码，也不会生成加密容器。

encrypt-tool hash ./a.txt
encrypt-tool hash --text "hello" --alg sha512
echo "hello" | encrypt-tool digest --encoding base64

支持的算法：

md5
sha1
sha224
sha256
sha384
sha512
blake2b512
blake2s256

支持的输出编码：

hex
base64
base64url

MD5 和 SHA-1 主要用于兼容旧系统，不建议作为新的安全校验算法。

RSA 辅助命令

encrypt-tool rsa gen -o ./keys
encrypt-tool rsa enc "hello" --key ./keys/public.pem
encrypt-tool rsa dec "<base64-ciphertext>" --key ./keys/private.pem

当前规则：

rsa enc 只接受公钥。
rsa dec 只接受私钥。
使用 RSA-OAEP-SHA256。
RSA 只适合小内容，不用于大文件和目录。
2048 位密钥的 OAEP-SHA256 明文上限为 190 字节；3072 位为 318 字节；4096 位为 446 字节。
当前没有签名/验签命令。

查看公开容器信息

encrypt-tool info ./docs.enc

info 不需要密码，只读取公开 header，输出类型、模式、容器版本、算法、KDF、分块大小和密码要求。它不验证 manifest、footer 或完整正文，也不会显示原始文件名、目录结构、文件大小和时间戳。

PowerShell 补全

encrypt-tool completion install powershell
encrypt-tool completion uninstall powershell

重新打开终端后，可以使用：

encrypt-tool <Tab>
encrypt-tool enc --<Tab>
encrypt-tool rsa <Tab>

常用选项

| 选项 | 说明 | | --- | --- | | -o, --out <path> | 指定输出路径 | | -m, --mode <archive\|per-file> | 指定目录加密模式 | | --password-file <path> | 从文件读取密码 | | -f, --force | 覆盖已有输出 | | -y, --yes | 跳过确认提示，但不能单独覆盖已有输出 | | --no-progress | 禁用进度显示 | | --lang <locale> | 指定 zh-CN 或 en-US |

安全与边界

请使用足够强的密码；工具不会替代密码管理和密码分发。
空密码会被拒绝，但当前不强制密码长度或复杂度。
AES-GCM record、manifest、entry metadata 和 footer 都会参与认证。
每个 record 使用独立 nonce 和 authTag。
解密失败时临时输出会清理；提交过程仍需结合操作系统和并发环境评估原子性。
文件、目录和文本的用户侧大小限制见上面的大小与资源限制，record/chunk 等结构级限制见技术文档。
当前容器格式版本为 1，魔数为 ETC1。
修改 record 布局、AAD、nonce、manifest、entry metadata 或 footer 语义时必须升级容器格式版本并增加兼容测试。

version: 1 表示 .enc 容器协议版本，不是 AES 的算法版本。当前 v1 容器使用 AES-256-GCM 记录加密和 scrypt 密码派生。

开发与发布验证

npm run build
npm test
npm run pack:check
npm run smoke:install
npm audit --omit=dev --registry=https://registry.npmjs.org

npm run smoke:install 会在隔离临时目录中安装并执行 CLI；npm run ci 会统一执行测试、打包检查、安装 smoke test、生产依赖审计和完整依赖审计。开发修改应执行上述验证；不要使用 npm audit fix --force 直接引入未评估的 breaking change。

发布前的版本递增、官方 registry 发布命令和待验证事项见 ROADMAP.md。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme