shardnest: Instructions file for Codex

AGENTS.md

This file provides guidance to Lingma (lingma.aliyun.com) when working with code in this repository.

项目概览

shardnest（钱包服务）——开源、自托管、非托管的钱包基础设施。用户本地部署 MCP server 管理密钥，平台零密钥材料。钱包密钥生成、Shamir 2-of-3 分片、签名、恢复全部在用户本地完成；任何符合 signed_request v1 协议的平台均可接入。完整设计见 docs/DES-016-self-custodial-wallet-service.md，安全模型见 docs/SECURITY.md。

常用命令

# 安装依赖（workspace，改动任意 package.json 后必须执行）
bun install

# 单包测试（开发主循环）
cd packages/<pkg> && bun test

# 单个测试文件 / 单个用例
cd packages/<pkg> && bun test ./test/commands.test.ts
cd packages/<pkg> && bun test -t "用例名关键词"

# 全量测试（6 包：core signer cli verify-sdk protocol mcp-server）
for p in core signer cli verify-sdk protocol mcp-server; do (cd packages/$p && bun test); done

# 类型检查
bunx tsc --noEmit

# CLI 冒烟（临时目录隔离，不污染真实钱包）
SHARDNEST_HOME=$(mktemp -d) bun packages/cli/src/index.ts init

架构大图

包分层与依赖方向（严格单向）

core（纯密码学，无 IO）
  ├─ shamir.ts   GF(2^8) SSS（生成元 3 建表；split/combine/reshare）
  └─ keys.ts     CSPRNG 熵（根）、BIP-39/44 派生私钥、keccak 地址、EIP-55、scrypt KEK
  └─ mnemonic.ts 熵↔24 词标准编码（@scure/bip39）、seed、BIP-32 m/44'/60'/0'/0/0 派生
signvault.ts   WalletVault：注入已派生私钥→EIP-191 签名→wipe（O4A：组合/派生在命令层）n_message）
  └─ unlock-session.ts  令牌会话：unlock（私钥）/passphrase（口令）两型，
                         0600 加密落盘 + 5min TTL + rename 原子消费（单次）
cli（命令实现，MCP 的库 API 经 src/api.ts 的 exports 字段暴露）
  ├─ commands.ts  init/restore/sign/unlock/地址校验/恢复码 CRC（sn1-<idx>-<hex>-<crc>）
  ├─ mailer.ts    SMTP 备份分片（片③）发送（SHARDNEST_SMTP_* 环境变量）
  └─ index.ts     CLI 入口（掩码输入 promptSecret）
verify-sdk（平台侧验签，verify-only 零密钥）
protocol（signed_request v1：平台背书签发/钱包验签；canonicalBytes length-prefixed 二进制）
mcp-server（薄壳：凭证不进 LLM，6 工具 + 双闸门接线；独立无密钥进程为路线图 P0-3）

凭证隔离（本仓库最核心的安全架构，勿破坏）

口令与恢复码永不经 LLM 上下文。三条通道：

凭证	通道	机制
口令	passphrase_token	CLI passphrase-token 本地输入 → unlock/passphrase-* 文件（0600/5min/单次）→ MCP 消费
恢复码输入	recovery_file_path	只传本地文件路径，内容由 MCP 进程从 recovery-codes.txt 读取
恢复码输出	recovery_codes_file	MCP 响应只含文件路径 + 邮箱状态，绝不含明文