# encrypt-tool

**Repository Path**: LLS312885991/encrypt-tool

## Basic Information

- **Project Name**: encrypt-tool
- **Description**: 基于 Node.js 的跨平台命令行加密工具，支持文件、目录和文本的 AES-256-GCM 加解密，并提供 RSA、哈希和 PowerShell 补全能力。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-17
- **Last Updated**: 2026-08-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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` 补全。
- 解密先写临时文件或临时目录，完成容器完整性校验后再提交目标。

## 安装

```bash
npm install -g @roson_liu/encrypt-tool
```

本地开发：

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

## 发布到 npm 官方

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

```bash
npm version patch --no-git-tag-version
```

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

```bash
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 的版本：

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

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

```powershell
$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](ROADMAP.md)。执行 `npm publish` 前必须确认版本号、登录账号、registry 和授权范围。

## 命令概览

```text
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 补全。 |

## 大小与资源限制

以下是面向用户的实际使用上限，具体结构级预算见[技术文档](assets/encrypt-tool-技术文档.md)。

| 使用方式 | 大致可处理大小 |
| --- | --- |
| 普通文件加密/解密 | 约 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。

## 文件加密与解密

```bash
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，适合备份、传输和整体恢复。非交互环境未指定模式时默认使用该模式。

```bash
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。该模式当前仍按顺序整体恢复，不支持随机解密单个文件。

```bash
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](ROADMAP.md)。

## 文本加密与解密

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

```bash
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 不需要密码，也不会生成加密容器。

```bash
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 辅助命令

```bash
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 字节。
- 当前没有签名/验签命令。

## 查看公开容器信息

```bash
encrypt-tool info ./docs.enc
```

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

## PowerShell 补全

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

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

```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 等结构级限制见[技术文档](assets/encrypt-tool-技术文档.md)。
- 当前容器格式版本为 `1`，魔数为 `ETC1`。
- 修改 record 布局、AAD、nonce、manifest、entry metadata 或 footer 语义时必须升级容器格式版本并增加兼容测试。

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

## 开发与发布验证

```bash
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](ROADMAP.md#发布前验证清单)。

## 相关文档

- [assets/encrypt-tool-产品说明.md](assets/encrypt-tool-产品说明.md)：产品能力、使用场景和能力边界。
- [assets/encrypt-tool-技术文档.md](assets/encrypt-tool-技术文档.md)：当前实现、协议和技术边界。
- [ROADMAP.md](ROADMAP.md)：维护人员使用的待实现事项和发布前清单。