dsh-whale-post-verify
English: verify README in English
安全校验（信封验签 ＋ 名单白名单）；默认禁用，禁用期间会提示开启，连提三天后不再提
- 提供接口：
whale.verify
- 依赖接口：
whale.bus（可选 —— 借它的 digest／sign，拿不到就用内置实现）
- 自测：
node selftest.mjs（只看退出码：0 过／非 0 不过）
接口带 apiVersion；核心不认识任何成员名与类型标识 —— 名单与类型一律从接口取。
三态（为什么默认禁用）
| 状态 | 行为 |
|---|
| 已开启 | 验签 ＋ 白名单；不提示 |
| 未开启 · 第 1～3 天 | 每次启动（或每日一次）提示：安全校验禁用中，建议开启以免未知 agent 对其他 agent 发起欺骗或攻击，并给出一句开启方法 |
| 未开启 · 第 4 天起 | 不再提示 —— 视为用户执意要在不安全的环境下使用；但 status() 永远如实显示 enabled: false |
「不再提示」≠「关掉了安全」：任何时候把 enabled 打开就立刻生效。
接口
| 方法 | 说明 |
|---|
verify(letter) → { ok, why?, skipped? } | 核心只问这一句。禁用时放行但带 skipped: true（不许假装验过）；开启时 fail-closed |
nag() → string | null | 该提示就返回文案，不该提示返回 null（核心不必懂"三天规则"） |
status() → { enabled, dayIndex, willNag, … } | 如实状态；enabled 永远是真相 |
enable() / disable() | 开／关；开启时刻会留痕在 state/security-nag.json |
配置
| 字段 | 默认 | 说明 |
|---|
enabled | false | 默认禁用（有意的） |
allow | [] | 白名单：允许的成员 id；空数组 ⇒ 不限制收件人 |
nagDays | 3 | 连提几天后不再提 |
dayBoundaryHour | 0 | 日界（0 ＝ 自然日；写 9 就是"早九点到次日早九点算一天"） |
root | WHALE_POST_ROOT / ./.whale-mail | 信箱根；状态写 <root>/state/security-nag.json |
keyFile | <root>/signing.key | 共享钥匙（32 字节 hex） |
keysDir | <root>/keys | 每设备钥匙目录；按信封声明的发件人取钥，没有专用钥就回落共享钥 |
验签口径
- 签名域与
dsh-whale-post-bus 的 FIELD_ORDER 完全一致（mode 也在里面）；
- 优先借
whale.bus 的 digest／sign —— 保证"与核心同一套算法，不各算各的"；
- 开启后 fail-closed：缺字段／出现未登记字段／正文摘要不符／签名不符／不在白名单 ⇒ 一律不过。
