Monogram安全设计指南：会话密钥保护、错误映射与隐私数据处理的最佳实践

Monogram 是一款 Android 原生 Telegram 客户端，它的"安全设计"贯穿三条主线：会话密钥保护（Android Keystore + AES-256-GCM）、错误映射（把服务器错误变成可操作信号）和隐私数据处理（缓存 TTL 清理与最小化日志）。这篇文章用通俗的方式拆解这三块机制，帮助新手理解一个严肃的即时通讯客户端如何在本地把"信任边界"划清楚。

一、会话密钥保护：真身密钥永不落盘

会话文件（session）里存着登录态快照、更新游标、媒体索引等敏感数据。Monogram 采用"双层加密"结构，核心思路只有一句：真正解密密钥只存在于内存，磁盘上只有被包裹的副本。

1.1 会话文件用 AES-256-GCM 加密

Rust 侧的加密实现在 session_crypto.rs：

• 使用AES-256-GCM：既加密又做完整性认证——文件被篡改或密钥不对，恢复会直接失败，而不是"解密出垃圾数据"；
• 每次加密都生成随机salt + nonce，文件头部带专属魔数标记，防止把明文文件误当密文处理；
• 解密结果用Zeroizing容器承载，用完后内存被主动清零（见 session_crypto.rs）。

1.2 Android Keystore 包裹数据密钥

Android 侧由 SessionKeyStore.kt 负责：

注意 SessionKeyStore.kt 的注释："只有随机数据密钥跨越 FFI 边界，Telegram 授权信息留在原生层"。即使应用进程被读内存，Telegram auth key 也从不经过 Kotlin/JVM 一侧。

1.3 前向保密：临时密钥用后即焚

媒体下载、并行读取通道使用的是通过auth.bindTempAuthKey绑定的短生命周期临时密钥：只存在进程内存中、到期作废、永不写盘。这意味着即便日后存量的永久密钥被破解，历史流量也无法被还原——这就是架构文档中"Fail closed / 前向保密"安全模型的落地。

此外，跨数据中心的导入密钥在 session_file.rs 中刻意重写了Debug输出：日志里只会出现key_len，密钥字节绝不进入任何日志或打印。

二、错误映射：把FLOOD_WAIT_X变成可自动恢复的信号

2.1 类型化错误，而不是原始字符串

服务端返回的错误如果直接透传字符串，UI 层就没法做差异化处理。Monogram 在 TelegramError.kt 定义了 13 种Kind分类（如Flood、Session、Peer、Media、Privacy、SeeOther……），并给出两个关键行为判断：

• canAutoRetry：FLOOD_WAIT等待 ≤ 5 秒时允许自动静默重试，用户无感知；
• requiresReauth：区分"会话真正死亡需重新登录"与"AUTH_KEY_PERM_EMPTY 只是前向保密切换"（见 TelegramError.kt）。

分类逻辑集中在classify()方法中，例如420/FLOOD_WAIT*→Flood，401+AUTH_KEY*→Session（见 TelegramError.kt）。

2.2 错误目录：从官方 JSON 自动生成

官方 Telegram 的完整错误表被"固化"为 TelegramErrorCatalog.kt，由脚本 gen_telegram_errors.py 从官方errors.json生成，注释明确写着"do not hand-edit rows"（禁止手改）。好处是：

• 错误码、匹配模式、官方描述三者和**协议层版本（layer）**严格同步；
• 未收录的未知码仍会降级为Kind.Generic，不会把原始字符串直接抛给用户；
• 有配套单测 TelegramErrorTest.kt 保证映射行为稳定。

原生层的 error.rs 则定义了 FFI 边界的最小错误集（未知句柄、需要二次验证等），错误信息同样只携带固定标签，不含敏感内容。

三、隐私数据处理：缓存会"过期"，日志会"失忆"

3.1 30 天缓存 TTL 自动清理

本地消息缓存不是只进不出。CacheTtl.kt 定义了策略：

• 消息/资料缓存30 天（CACHE_MESSAGE_TTL_SECONDS）过期后被清理；
• 但待发送（pending）和失败（failed）的行永不自动删除，避免误删用户未完成的草稿；
• 最新一页消息始终保留，被清理区间以"空洞（hole）"记录，保证拉取历史时不出现错位。

3.2 备份与导出：规则先行

系统级备份/换机迁移行为由声明式文件约束：

• backup_rules.xml：规定哪些数据允许备份；
• data_extraction_rules.xml：规定设备迁移时的导出范围。

3.3 日志最小化：什么绝对不会出现在日志里

架构文档的安全模型章节给出了硬性清单——日志与性能遥测只包含固定标签、错误类型、耗时区间和计数器，以下内容永远不会被记录：

消息正文、手机号、验证码、API hash、代理密码、会话内容。

配合 persist.rs 中的持久化机制（会话写入走独立线程、按代际去重、崩溃时只留旧版或新版完整文件），隐私数据在"落盘"这一环也被收敛到了最小面。

四、给开发者的安全设计清单 📋

这套设计对任何客户端开发者都有参考价值：先划信任边界（什么能跨越 FFI、什么能进日志），再用自动化手段（生成器、TTL、原子写）把边界固化为代码，而不是靠人肉约束。