[](https://github.com/al-Zamakhshari/maknoon/releases)
[](https://github.com/al-Zamakhshari/maknoon/actions/workflows/ci.yml)
[](LICENSE)
[](https://goreportcard.com/report/github.com/al-Zamakhshari/maknoon)
Maknoon 是一个后量子密码学引擎和 MCP 网关 —— 一个约 12 MB 的单一二进制文件，允许 AI agent 和 CLI 用户加密数据、管理密钥、签署文档以及发布可验证的身份，所有这些都受到保护，免受经典和量子对手的威胁。
## 功能
| | 规范 |
|---|---|
| **混合 PQC 加密** | ML-KEM-768 + X25519 (NIST 标准)。保守选项：FrodoKEM-640 |
| **后量子签名** | ML-DSA-87；M-of-N 阈值聚合 |
| **加密保险库** | Argon2id 保护的密钥；法定人数解锁；暴力破解锁定；导出/导入 |
| **身份注册表** | WKD (HTTPS 静态文件) 和 DNS TXT — 无需基础设施 |
| **RAID 隐私保护** | Reed-Solomon 分片分散；与 rclone 结合实现多云分发 |
| **取证审计日志** | 哈希链式、ML-DSA-87 签名的操作日志；篡改检测 |
| **MCP Server** | 通过 stdio 或 SSE 为 AI agent 提供 45 种 PQC 工具；支持 `gh skill install` |
| **会话密钥加密** | 派生一次，加密数千个文件，无单文件 KDF 开销 |
## 安装
```
# Homebrew (macOS / Linux)
brew install al-Zamakhshari/tap/maknoon
# GitHub Releases — 适用于 linux/darwin/windows amd64/arm64 的预编译二进制文件
# https://github.com/al-Zamakhshari/maknoon/releases
# 从源码构建
git clone https://github.com/al-Zamakhshari/maknoon
cd maknoon && make build
```
**初次使用 Maknoon？** 请从 [5 分钟快速入门](docs/getting-started/QUICKSTART.md)开始。
`mkn` 作为简短别名与二进制文件一起被所有包管理器安装。要手动添加它：
```
alias mkn=maknoon # add to ~/.bashrc or ~/.zshrc
```
## 快速入门
### 加密和解密
```
# 生成 keypair
maknoon keygen -o alice
# 对称 (passphrase)
maknoon encrypt report.pdf -o report.pdf.makn
maknoon decrypt report.pdf.makn -o report.pdf
# 非对称 — 多接收者 (通过 WKD 或 DNS 解析密钥)
maknoon encrypt report.pdf -p @alice@corp.com -p @bob@corp.com -o report.pdf.makn
maknoon decrypt report.pdf.makn -k alice.kem.key -o report.pdf
# 检查 header 而不解密
maknoon info report.pdf.makn --json
```
### 保险库 — 加密密钥存储
```
maknoon vault set DEPLOY_TOKEN --vault prod
maknoon vault get DEPLOY_TOKEN --vault prod
# 导出 / 导入以在机器之间迁移
maknoon vault export --vault prod -o prod.vault.makn
maknoon vault import --vault restored -i prod.vault.makn
# Quorum 治理的机构 vault (3-of-5 解锁)
maknoon vault init-institutional --vault corp --threshold 3 --shares 5
```
### 身份 — 发布和解析
```
# 通过 HTTPS 发布你的公钥 (WKD — 无需更改 DNS)
maknoon keygen -o alice
maknoon identity publish @alice@example.com --wkd
# → 将生成的 JSON 上传至：
# https://example.com/.well-known/maknoon/alice.json
# 通过 DNS 自动发布 (deSEC.io)
maknoon identity publish @alice@example.com --desec
# 其他人现在可以直接向你加密
maknoon encrypt secret.txt -p @alice@example.com -o secret.makn
```
### 阈值签名
```
maknoon sign contract.pdf -k alice.sig.key -o alice.sig
maknoon sign contract.pdf -k bob.sig.key -o bob.sig
maknoon sign aggregate alice.sig bob.sig -o combined.sig
maknoon verify contract.pdf --signature combined.sig \
-p alice.sig.pub -p bob.sig.pub --threshold 2
```
### 结合 rclone 的 RAID 隐私保护
将加密文件分片并跨云服务提供商分发。任意 N-of-(N+M) 个分片即可重建原始文件 —— 没有任何单一提供商能看到完整文件。
```
# Fragment 为 5 个数据 + 3 个 parity shards；在本地保留 manifest
maknoon encrypt classified.pdf -o classified.makn
maknoon fragment classified.makn --data 5 --parity 3 \
--output /tmp/shards/ --output-manifest ~/manifests/classified.json
# 分布在三个提供商中
rclone sync /tmp/shards/ s3:my-bucket/shards/
rclone copy /tmp/shards/shard_005.maknf gcs:backup/shards/
rclone copy /tmp/shards/shard_006.maknf azure:container/shards/
maknoon shred /tmp/shards/
# 恢复：获取任意 5 个 shards，根据 manifest 验证 SHA-256
rclone copy s3:my-bucket/shards/ /tmp/recover/
cp ~/manifests/classified.json /tmp/recover/manifest.json
maknoon reassemble /tmp/recover/ --output classified.makn --verify
maknoon decrypt classified.makn -o classified.pdf
```
有关完整的 rclone 工作流，请参阅[分片分发指南](docs/user-guides/fragment-distribution.md)。
### 使用会话密钥进行批量加密
Argon2id 仅运行一次；所有文件共享派生密钥 —— 消除了大规模操作时每文件 26 ms 的 KDF 开销。
```
KEY=$(maknoon session derive --passphrase "$PASS")
for f in documents/*.pdf; do
maknoon encrypt "$f" --session-key "$KEY" -o "${f}.makn"
done
```
## AI Agent 集成
### 安装 agent 技能
```
gh skill install al-Zamakhshari/maknoon maknoon
```
这将在您的 agent 主机（Claude Code、Cursor 等）中配置 Maknoon 的 MCP server，并从 [`.github/skills/maknoon/SKILL.md`](.github/skills/maknoon/SKILL.md) 加载操作说明。
### 手动 MCP 配置
**stdio** (Claude Desktop, Cursor)：
```
{
"mcpServers": {
"maknoon": {
"command": "maknoon",
"args": ["mcp", "--transport", "stdio"],
"env": { "MAKNOON_PASSPHRASE": "your-passphrase" }
}
}
}
```
**SSE** (远程 agent，Kubernetes)：
```
maknoon serve --address :8443 --tls-cert cert.pem --tls-key key.pem
```
**从 CLI 调用工具** (脚本 / CI)：
```
maknoon call encrypt_file --addr localhost:8443 \
--args '{"input":"report.pdf","output":"report.pdf.makn"}'
```
### MCP 工具分类（45 个工具）
| 类别 | 工具 |
|---|---|
| **crypto** | `encrypt_file`, `decrypt_file`, `sign_file`, `verify_file`, `inspect_file`, `shred_file`, `reencrypt_file`, `gen_passphrase`, `gen_password` |
| **vault** | `vault_get/set/list/delete/rename`, `vault_set_blob/get_blob` (agent memory), `vault_split/recover`, `vault_init_institutional`, `vault_status`, `vault_check_shards` |
| **identity** | `identity_keygen/list/info/rename/delete/split/combine/publish`, `contact_add/list/delete`, `resolve_identity`, `aggregate_signatures` |
| **dispersal** | `fragment_file`, `reassemble_file` |
| **config** | `config_list/update/init`, `diagnostic`, `audit_export`, `audit_verify` |
| **profiles** | `profiles_list/gen/rm` |
### Agent 交互示例
Agent 调用 `profiles_list` 以确认可用的配置文件，通过 `resolve_identity` 解析 alice 的密钥，然后调用带有 `recursive=true` 和 `public_keys="@alice@corp.com"` 的 `encrypt_file`。用户可以看到结果；而密钥材料保留在 Maknoon 内部。
对于批量操作，行为良好的 agent 会首先调用 `session_derive`（约 60 ms 的 Argon2id 仅执行一次），然后在所有 `encrypt_file` 调用中重复使用该会话密钥 —— 从而将 1,000 个文件的加密开销从约 60 秒减少至总计约 30 ms 的 KDF 开销。
### 安全性：提示词注入
使用 Maknoon 的 agent 可能会被恶意文档欺骗，从而在攻击者控制的路径上调用 `decrypt_file` 并泄露结果。缓解措施：
- **Agent 模式沙盒**：当通过 MCP 启动时，Maknoon 将文件访问限制在 `$HOME`、保险库目录和 `/tmp` 中
- **审计追踪**：每次工具调用都会通过 SHA-256 链接和 ML-DSA-87 签名进行记录 —— 运行 `maknoon audit verify` 以检测篡改
- **密码短语范围限定**：仅为 agent 需要的特定保险库设置 `MAKNOON_PASSPHRASE`；切勿暴露身份私钥
## 安全
### 设计原则
- **恒定内存流式处理** — 以有限的 RSS 加密任意大的文件
- **显式清零** — 所有密钥材料保存在 `memguard` 锁定的缓冲区中；使用后清零
- **身份过期** — 发布的记录在 48 小时后过期；拒绝重放过期记录
- **保险库锁定** — 10 次解锁失败将触发 15 分钟的锁定
- **Agent 模式沙盒** — 作为 MCP server 运行时，文件路径限制在 home/vault/tmp
- **取证审计** — 每次操作均通过 SHA-256 哈希链和 ML-DSA-87 签名进行记录
```
maknoon audit export # view operation history
maknoon audit verify # verify log integrity (detect tampering)
```
### 性能
| 操作 | 吞吐量 | 备注 |
|---|---|---|
| 加密 10 MB (8 个工作线程) | ~384 MB/s | 接近内存带宽 |
| 加密 100 MB | ~3.3 GB/s | 大缓冲区均摊 |
| 会话密钥加密 1 KB | ~2,000 MB/s | 无单文件 KDF |
| 加密 1 KB (带 KDF) | ~0.04 MB/s | 26 ms 的 Argon2id 占主导 |
| ML-DSA-87 签名/验证 | ~1 ms | 每次操作 |
在您的硬件上运行 `make bench` 进行测量。
### 漏洞披露
安全问题：**akhallaf@gmail.com** — 参见 [SECURITY.md](SECURITY.md)。
## Maknoon 不适用于什么
- **不是 VPN** — 请使用 [WireGuard](https://www.wireguard.com) 或 [Tailscale](https://tailscale.com) 进行加密隧道传输
- **不是聊天应用** — 请使用 Signal 或 Matrix 客户端进行安全消息传递
- **不是云备份工具** — 分片分散为您提供纠删码；rclone 为您提供云传输
## 文档
| | |
|---|---|
| [安装与硬件强化](docs/getting-started/INSTALL.md) | TPM 2.0，SSD 上的安全删除 |
| [架构](docs/architecture/overview.md) | 流式管道，MCP 传输，身份注册表 |
| [威胁模型](docs/architecture/threat-model.md) | 算法选择，已知局限性 |
| [CLI 参考](docs/integration/cli-reference.md) | 所有命令和标志 |
| [MCP server](docs/integration/mcp-server.md) | 工具 schema，SSE 设置 |
| [会话密钥](docs/user-guides/session-keys.md) | 无需单文件 KDF 开销的批量加密 |
| [分片 + rclone](docs/user-guides/fragment-distribution.md) | 结合云分发的 RAID 隐私保护 |
| [远程 agent](docs/user-guides/remote-agent.md) | `maknoon call`，SSE server，PQC TLS |
| [更新日志](CHANGELOG.md) | 发布历史 |
| [贡献](CONTRIBUTING.md) | 开发设置，安全要求，PR 流程 |
## 许可证
MIT — 由 [al-Zamakhshari](https://github.com/al-Zamakhshari) 创建。