如何使用 MongoDB CSFLE 加密 LangGraph 检查点
内容提要
文章介绍如何用MongoDB客户端字段级加密（CSFLE）保护LangGraph检查点数据。默认检查点以Base64明文存储，数据库管理员或入侵者可读取敏感消息。作者通过自定义CipherProtocol，在写入MongoDBSaver前用AWS KMS支持的CSFLE加密序列化负载，恢复运行时再解密，无密钥者只能看到密文。线程ID等路由元数据仍可见，需避免含个人信息；若需加密字段可查询，应改用可查询加密。
延伸解读
Base64 不是加密：默认检查点的风险
文章指出，LangGraph 默认将检查点序列化后以 BSON Binary 存储，在数据库客户端中显示为 Base64 字符串。Base64 只是编码，并非加密，任何能读取文档的人无需密钥即可解码还原明文。这意味着数据库管理员或入侵者可直接读取用户消息、工具结果等敏感内容。因此，仅靠角色权限、静态加密和 TLS 无法阻止特权用户查看明文，需要应用层加密来保护检查点负载。
显式 CSFLE 与随机加密的取舍
示例采用显式 CSFLE，通过 ClientEncryption 直接调用 encrypt/decrypt 原语，而非依赖 JSON Schema 自动加密。由于检查点负载作为不透明二进制整体加密，且不需要在密文内查询，作者选择随机加密算法（AEAD_AES_256_CBC_HMAC_SHA_512_Random），使相同明文产生不同密文，提供更强机密性。若使用确定性加密，虽支持等值查询，但会暴露频率模式，不适合此场景。
加密后仍可见的元数据与查询限制
集成 CSFLE 后，检查点负载（包括用户消息和代理响应）变为密文，但路由和序列化元数据（如 thread_id、checkpoint_id、命名空间）可能仍以明文可见，因为运行时依赖这些字段定位和恢复检查点。文章提醒，应避免在 thread_id 等元数据中放入个人身份信息（PII）。此外，LangGraph 始终将检查点持久化为二进制块，负载无法用作查询过滤器；若需对加密数据做等值、范围或子串查询，应改用 MongoDB 可查询加密。
Q&A
为什么需要加密 LangGraph 的检查点数据？
LangGraph 检查点默认以 Base64 明文存储，数据库管理员或入侵者可直接读取敏感消息。加密可保护终端用户数据，满足安全与合规要求。
MongoDB CSFLE 如何保护 LangGraph 检查点？
通过自定义 CipherProtocol，在写入 MongoDBSaver 前用 CSFLE 加密序列化负载，恢复运行时再解密。无密钥者只能看到密文。
Base64 编码能保护检查点数据吗？
不能。Base64 只是编码，不是加密，任何人无需密钥即可解码。CSFLE 用密文替换可逆的 Base64 表示。
使用 CSFLE 加密检查点后，哪些数据仍然可见？
线程 ID、检查点 ID、命名空间等路由元数据可能仍可见，因为运行时依赖它们定位检查点。应避免在 thread_id 等字段中包含个人信息。
如果需要对加密字段进行查询，应该用什么方案？
应改用 MongoDB Queryable Encryption，它支持对加密数据进行等值、范围、前缀、后缀或子串查询。CSFLE 加密的负载作为不透明值，无法用于查询过滤。
实现 CSFLE 加密 LangGraph 检查点需要哪些前提条件？
需要 MongoDB 部署和连接字符串、用于 CSFLE 数据加密密钥的密钥保管库命名空间、别名为 langgraph_csfle_key 的数据加密密钥（DEK），以及运行时环境中的 KMS 凭证。
