Anpio Key
Anpio Key 是一个跑在本机的服务，替 AI Agent 保管 did:wba 私钥，只按管理员签发的许可（grant）签名。私钥不出服务进程，Agent 拿不到，也不能让服务签它没被批准的东西。
- 数据面没有任何读取或导出私钥的操作；默认构建里连
export-seed 子命令都不存在。
- 每次签名都要一张 grant：哪把钥匙、哪个操作、什么目标、多久、几次。
- 超出范围、过期、次数用光、被撤销、机器重启，都会拒绝。
- 新增的签名路各自一个开关，默认关；开过哪一路，启动审计里有记录。
它解决什么问题
Agent 要代表你访问网站、发消息、建会话，对方用 did:wba 验证签名。把私钥交给 Agent，一次提示注入、一个坏依赖或一条误发的日志就可能把私钥带走。
Anpio Key 把私钥留在本机服务里，Agent 只拿到签名结果。管理员和 Agent 使用不同的系统账号和不同的本地 socket；能签什么由服务端逐次判断，不由 Agent 自己声明。
现在能做什么
Agent 能请求的（数据面）
| 操作 | 用途 | 钥匙角色 | 默认 |
|---|
GET_CAPABILITIES | 能力协商：operations、用途、grant 类型 | 无 | 开 |
LIST_AUTHORIZED_KEYS | 当前主体获准使用的钥匙 | 无 | 开 |
GET_GRANT_STATUS | 查 grant 的期限和剩余次数 | 无 | 开 |
GET_DOCUMENT | 取公开 DID 文档 | 无 | 开 |
SIGN_HTTP | RFC 9421 HTTP 请求签名 | hot | 开 |
GET_REQUEST_STATUS | 用原 request_id 查结果 | 无 | 开 |
SIGN_ORIGIN_PROOF | ANP origin proof（消息、登录等事实） | hot | 关 |
RENEW_GRANT | 续 session grant；只延期，不增加次数 | — | 开 |
SIGN_PURPOSE | 设备/应用用途断言 | device_signing | 关（逐用途） |
ECDH | X25519 协商，返回共享密钥 | key_agreement | 关 |
SIGN_OBJECT_PROOF | W3C DataIntegrityProof 对象 proof | device_signing | 关 |
SIGN_DOCUMENT_PROOF | DID 文档 proof | root | 关 |
基线六个操作永远在 operations 里；带“关”的操作只有对应 features 开关打开时才出现，关着时发过去是 OPERATION_DISABLED。客户端只看 operations 里有没有名字，不按版本号猜。
各操作的字段、编码、默认关清单和错误码见 接入说明 §11。ECDH 是唯一会把秘密交给调用方的操作：共享密钥不落库，同一个 request_id 重放拿不到第二次。
管理员能做的（管理面）
- 钥匙：
key create 生成一把命名钥匙（名字可自取），当场显示一次 24 词，确认抄好后读两遍口令；key list 看名字、指纹与解锁状态；key rotate 同名换钥；key unlock 在人类终端读口令。钥匙不必先有 DID，也没有任何导出路径。
- 身份：DID、handle、文档与注册由
anpio-cli did create 一条命令完成；要让本服务保管钥匙就由管理员在终端加 --key anpio-key。坐标脚本 spec / keygen / publish 已隐藏为兼容别名，只用于迁移，verify-doc 继续核对文档归属。
- 恢复：
import-mnemonic 用一个 24 词助记词恢复 key-1（根绑定键）、hot、{device}-sign、{device}-agreement 四类键；import-archive 恢复归档里的单把钥匙。
- 授权：所有变更走
prepare / commit 两步，先看 effect、摘要和期限，再提交批准。策略有 v1 和 v2 两种，v2 按 purpose 分字段。
- 解锁：
admin unlock 只让指定热钥匙可用；解锁不等于授权，签名仍要 grant。
- 能力令牌：默认关。打开后管理员可以给一个已登记主体签一张字符串，绑死
(主体, DID)，让跑在管理员账号下的 Agent 直接走 capability.sock；服务端只存哈希，明文只在签发回包里出现一次。grant 仍照旧检查，revoke 立即生效、重启后令牌仍在而 grant 作废。见能力令牌。
- 设备入组：
IssueDeviceKeys 铸 {device}-sign 与 {device}-agreement，ReissueDocument 把两个公钥写进文档，EnrollVault 登记，ConfirmRole 确认 device_signing 和 key_agreement。撤销用 ReissueDocument 的 remove，两把一起退休。四步顺序不能换，见 接入说明 §7.4。
- 轮换与注册：
RotateHotKey 轮换热钥匙，RegistrationChallenge 完成注册 proof，add-recovery-key 预置恢复键，add-agreement-key 新增 X25519 协商键。
- 换根：
e1_ 身份的 DID 就是根公钥的指纹，所以没有“原地换根、DID 不变”的操作。换根就是换身份，步骤见 接入说明 §7.5。
IssueDeviceKeys 铸的是随机种子，不在助记词里；后铸的设备键只能靠归档带走。助记词恢复出来的是当初 keygen 铸的那四把。
密钥类别
| 角色 | 是什么 | 能做什么 |
|---|
root | DID 的绑定键，路径段由它的指纹决定 | 文档重签、设备入组/撤销、注册 proof、SIGN_DOCUMENT_PROOF |
hot | 日常签名钥匙 | SIGN_HTTP、SIGN_ORIGIN_PROOF |
device_signing | 绑定唯一用途的设备键 | SIGN_PURPOSE、SIGN_OBJECT_PROOF |
key_agreement | X25519 协商键 | ECDH |
recovery / challenge | 生命周期用的辅助角色 | 管理面操作 |
角色在管理面确认，绑定信封、公钥和文档摘要，改一次就定死。私钥只在解封后驻留服务内存；硬件根（TPM / Secure Enclave）保护的是解封材料，签名仍在服务进程内完成。
五分钟试用
这一步走开发模式，所有东西都在你的账号下运行，不建立安全边界。需要 Rust 1.88+。它不是受保护安装的签名路：受保护服务只按 grant 签名，开发开关不开启任何服务端授权。
cargo install --path .
mkdir -p /tmp/keyd-lab
anpio-key --root /tmp/keyd-lab key create --name bot
anpio-key --root /tmp/keyd-lab key list --json # 记下 thumbprint
key create 会先在终端显示 24 个词，确认抄好后输入两遍口令，然后打印名字、指纹和公钥。它不建 DID——身份是 anpio-cli did create 的事，见下一节。
要让这把钥匙签名，开发模式的守护进程必须显式打开命名签名路：
anpio-key --root /tmp/keyd-lab serve --development --allow-named-key-signing
换一个终端解锁并签名。keyid 里的 DID 段必须带着这把钥匙的指纹：
anpio-key --root /tmp/keyd-lab key unlock --name bot
anpio-key --root /tmp/keyd-lab sign --key bot \
--keyid did:wba:example.com:user:mybot:<thumbprint>#key-1 \
--method GET --url https://service.example.net/orders/42
输出是两行签名头：
Signature-Input: sig1=("@method" "@target-uri" "@authority");created=...;expires=...;keyid="did:wba:..."
Signature: sig1=:...:
把这两行原样放进 HTTP 请求头，不能改任何一个字符。上面这个 DID 只是让签名头长得对；对方要能查验身份，得先由 anpio-cli did create 建出真身份并注册文档。试完关掉：
anpio-key --root /tmp/keyd-lab stop
正式安装
Linux 上一条命令装好受保护服务：
git clone https://github.com/eccstartup/anpio-key.git && cd anpio-key
./install.sh
先看计划不改系统：./install.sh --dry-run；物理 TPM 加 --tpm-device。安装器创建服务、管理员与 Agent 三个系统账号、受保护配置和 systemd 单元，不生成身份、不收口令、不发 grant。已经是这个状态时再跑一次只会打印状态并退出 0，不构建、不提权。
日常命令：
./install.sh --status # 只读：状态、是否运行、已装二进制摘要
./install.sh --verify # 只读验收；失败退出 3
./install.sh --upgrade # 换二进制，保留配置和状态；摘要相同不重启
./install.sh --uninstall # 停服务、删二进制和单元，保留配置、状态和账号
状态不符退出 2（半成品安装、卸载后只剩配置），缺前置退出 4（cargo、python3、systemd）。
装完之后建身份。在装了受保护服务的机器上，新身份直接 provision 进服务：加 --key anpio-key，全程一次口令确认。CLI 准备 ProvisionIdentity（坐标、device、策略、grant），服务的 complete-secret-operation --new-secret 在你的终端读两遍新口令，铸根钥匙、设备签名钥匙和 X25519 协商钥匙，用同一口令封存并解锁，AddKeys + 发布策略 + 发 grant 在一个事务里完成；CLI 再用根钥匙签文档、把第一份文档 InstallDocument 进 vault、注册 handle，最后打印给 Agent 管理员的 did attach 命令。之后 agent 自己签名，不再问人。
anpio-cli did create --host awiki.me --handle mybot --email [email protected] \
--agent mybot --key anpio-key
已有身份（钥匙还在本地 store）走接管：macOS 上是 sudo ./install.sh --adopt，见下文。不带 --key anpio-key 时钥匙由 CLI 本机保管，不进入服务。
授权是独立的一步，只在手工重建时需要：接管和 provision 都会自动发好 grant。手工重建时用完整 kid 指名钥匙、用 --purpose 区分用途：anpio-key grant create --kid '<did>#<agent>/<profile>-sign' --target URL（HTTP，Hot 角色）和 anpio-key grant create --kid '<did>#key-1' --purpose document-proof（文档 proof，Root 角色）；purpose（设备断言）、origin-proof-agent/-group/-service、object-proof、ecdh 也各有名字。命令打印摘要、确认一次，然后走 prepare / commit；anpio-cli key grant <id> --purpose http|document-proof|… 把编号记进 store。命名钥匙（没有受保护服务的开发路径）不进 catalog，只能在开发 daemon 上签。
已有身份或钥匙的迁移按本机使用指南：keygen 生成四把、migrate-vault 离线迁入、EnrollVault / ConfirmRole 登记、发布策略，再建 grant。这条老路仍然是一步式的：
This is the beginning of the README. Read the rest at the original. Read the full README ↗
