docs/ENCRYPTED-NOTEBOOK.zh-CN.md
在 SiYuan 中实现"加密笔记本"——一种特殊笔记本，其 .sy 文档、assets 资源文件（含文件名）、数据库文件、SQLite 索引数据库（content + blocktree）都在磁盘上加密存储，需要主密码解锁才能查看内容。已有的普通笔记本完全不受影响。
| 维度 | 设计决策 |
|---|---|
| 加密范围 | .sy + assets（含文件名）+ 数据库文件 + SQLite 数据库（content + blocktree）全部加密 |
| 笔记本身份 | 动态 boxID + BoxConf.Encrypted: true 标志位 |
| 数量 | 支持多个加密笔记本 |
| 密码 | 共用主密码（KEK 包络，每个笔记本独立 DEK） |
| 解锁粒度 | 严格每笔记本单独解锁（KEK 用完即弃，每次跑 Argon2id ~1 秒） |
| SQLite 数据库方案 | 每个加密笔记本物理独立 SQLCipher SQLite 数据库，与全局 siyuan.db 隔离 |
| 隔离原则 | 每个加密笔记本是一个独立孤岛——与普通笔记本隔离，加密笔记本之间也互相隔离。数据、块引、数据库镜像、移动都不跨加密笔记本边界。解锁一个加密笔记本不影响其他加密笔记本的锁定状态。 |
| 全局功能 | 加密笔记本完全不参与（全局搜索/关系图/块引都看不到它） |
| 块引 | 笔记本内部正常引用；禁止跨加密边界引用（双向：普通↔加密、加密 A↔加密 B） |
| AI / LLM | 不做功能层隔离——解锁后与普通笔记本一样可读可搜；锁定后无可用 DEK 句柄且专用入口拒绝访问（详见 §13） |
| 跨边界移动 | 禁止——会破坏数据一致性且泄漏 |
| 数据库 | 笔记本级存储——加密笔记本的 数据库文件跟随笔记本目录，DEK 加密；禁止跨边界镜像 |
| 闪卡 / 间隔重复 | 不支持（功能限制） |
| 书签 | 不支持（功能限制） |
| 标签 | 不支持（功能限制） |
| 导入 | 支持——导入的 .sy.zip 和 Markdown 在落盘前用 DEK 加密，与手动创建的文档一致 |
| 启用/禁用 | 启用需设主密码；禁用需确认无现存加密笔记本，且无依赖当前密钥备份的内核可枚举历史或恢复快照；否则必须先明确永久清除这些恢复数据 |
| 重启行为 | 启动时强制关闭所有加密笔记本（受管 DEK 句柄仅存在于进程内存，重启后需重新派生），用户需重新解锁 |
| 已有笔记本 | 完全不动，零迁移 |
| 维度 | 普通笔记本 | 加密笔记本 |
|---|---|---|
| 创建 | 随时创建，无限制 | 需先启用加密功能（设主密码），创建时需验证主密码 |
| 打开（Mount） | 直接打开 | 需先输主密码解锁（每次 ~1 秒 Argon2id），应用取得受管 DEK 句柄 |
| 关闭（Unmount） | 关闭即不可见 | 关闭 = 锁定（停止新访问 + 等待或取消在途任务 + 从受管密钥缓存移除 DEK + 删除加密 SQLite 数据库 + 尽力清理内核管理的明文缓存和临时文件） |
| 重启后 | 保持上次打开状态 | 强制关闭，需重新输主密码解锁 |
| .sy 文件 | 明文 JSON 落盘 | AES-256-GCM 密文落盘，读时透明解密 |
| assets 文件 | 明文二进制，原始文件名 | AES-256-GCM 密文，文件名脱敏，原始名加密存储 |
| 数据库文件 | 全局 storage/av/<avID>.json（明文） | 笔记本级 <boxID>/storage/av/<avID>.json（DEK 加密） |
| content SQLite 数据库 | 写入全局 siyuan.db（明文） | 写入独立 siyuan-encrypted-<boxID>.db（SQLCipher 加密） |
| blocktree SQLite 数据库 | 写入全局 blocktree.db（明文） | 写入独立 siyuan-encrypted-<boxID>-blocktree.db（SQLCipher 加密） |
| 全局搜索 | 参与（FTS 命中） | 不参与（数据不在全局 SQLite 数据库） |
| 关系图 | 参与 | 不参与 |
| 块引 | 可被任意笔记本引用 | 笔记本内部正常引用；禁止跨加密边界引用（双向） |
| 移动文档（跨笔记本） | 支持 | 禁止跨加密边界 |
| 文档转标题（Doc2Heading） | 支持 | 禁止跨加密边界 |
| 数据库镜像（跨笔记本） | 支持 | 禁止跨加密边界 |
| 资源文件重命名 | 支持 | 不支持（脱敏文件名重命名会破坏映射） |
| 导入 | 支持 | 支持（.sy.zip 和 Markdown，落盘前自动 DEK 加密） |
| 笔记本内搜索 | 走全局 SQLite 数据库 | 走加密 SQLite 数据库 |
| 反链面板 | 走全局 SQLite 数据库 | 走加密 SQLite 数据库（含 mention 子查询） |
| 打开文档 / 大纲 / 面包屑 / 块信息 / 悬浮预览 | 走全局 SQLite 数据库 | 走加密 SQLite 数据库 |
| 数据库 | 走全局存储 + 全局 SQLite 数据库 | 走笔记本级存储（DEK 加密）+ 加密 SQLite 数据库 |
| 文件历史 | 支持 | 支持（密文 .sy 原样存历史目录；历史条目保留快照写入时的 boxID、对象类型和稳定文件基名，查看/回滚以三者作为 AAD 上下文解密） |
| 已删除笔记本历史 | 支持 | 支持（删除前整个目录密文备份，恢复时原样拷回；恢复还需要匹配的全局密钥备份和主密码） |
| 嵌入向量化 / 语义搜索 | 参与 | 不参与（加密数据不进全局 block_embeddings 表，嵌入流水线只读全局库；与解锁状态无关） |
| 智能体 / AI 对话 / MCP | 可读内容、可搜索 | 解锁后可用（可读块内容、列文档、笔记本内搜索）；锁定后不可达（详见 §13）。全局搜索/语义搜索不参与 |
| 内核 CLI | 可操作工作区数据 | 无论锁定或解锁，均不支持加密笔记本及其文件 |
| 闪卡 / 间隔重复 | 参与 | 不支持（功能限制） |
| 书签 | 参与（全局聚合） | 不支持（功能限制） |
| 标签 | 参与（全局聚合） | 不支持（功能限制） |
| 列表图标 | 用户自定义 emoji | 关闭时显示锁图标，打开后恢复 emoji |
| 导出（.sy.zip） | 支持 | 支持（解锁状态下导出明文，未解锁时拒绝；详见 §12 安全前提） |
| 数据同步 | dejavu 同步明文 | 不改（密文进密文出，闭环自洽） |
| 删除笔记本 | 删目录 | 删目录 + 删加密 SQLite 数据库 文件 + 删笔记本级数据库存储 |
| 重建索引 | 全量 | 启动时跳过（已关闭）；打开时全量重建到加密 SQLite 数据库 |
| /api/file/getFile + putFile | 可读写任意文件 | 拒绝读写加密笔记本下的任何文件（不只 .sy）以及内核管理的加密笔记本明文临时目录，防止密文泄漏或明文破坏；合法读写走专用 API |
核心区别总结：加密笔记本是"孤岛"——数据物理隔离、操作专用入口、完全不参与全局功能（全局搜索/关系图）、文档和 数据库文件不进出边界。笔记本内部功能（编辑、块引、反链、搜索、数据库、大纲、历史等）正常使用；解锁后 AI/LLM 也可用（与普通笔记本一致）。加密笔记本之间也互相隔离。普通笔记本完全不受影响。
用户主密码
│ Argon2id(全局 MasterSalt, 64MB/3次/4线程)
▼
KEK（密钥加密密钥，仅内存，用完即弃）
│ AES-256-GCM 包络
├─→ 解 BoxConf.WrappedDEK → DEK₁ → 加密笔记本 1 的 .sy/assets/数据库文件/SQLite 数据库
├─→ 解 BoxConf.WrappedDEK → DEK₂ → 加密笔记本 2
└─→ 解 BoxConf.WrappedDEK → DEK₃ → 加密笔记本 3
MasterSalt 是 KEK 派生的全局根基——主密码 + MasterSalt 经 Argon2id 派生 KEK，KEK 再解开各笔记本的 WrappedDEK。MasterSalt 丢失等于数据永久锁死：即使输入相同主密码，因 salt 变化派生出的 KEK 不同，旧 WrappedDEK 无法解开。为此引入备份与恢复机制。
备份：<DataDir>/.siyuan/notebook-crypto-backup.json，保存整套 NotebookCrypto（MasterSalt/KEKVerifier/KDFParams）。位于 DataDir 内，进入 dejavu 同步范围。启用加密笔记本、修改主密码时刷新；只有禁用前确认不存在现存加密笔记本，也不存在依赖该备份的内核可枚举历史或恢复快照，或用户明确选择永久清除这些恢复数据后，才能删除。备份文件按明文 JSON 存储（salt 不保密、verifier 是密文，与 conf/conf.json 的存储方式一致）。
恢复触发点（覆盖 conf.json 丢失 / 同步到新设备 / 导入 Data.zip 等场景）：
| 触发场景 | 函数 | 需要主密码？ | 说明 |
|---|---|---|---|
| 同步完成后（拉取到备份文件） | restoreNotebookCryptoConfigFromBackup | 否 | 把配置装回本机 conf.json 并置 Enabled=true，UI 显示"已启用、锁定" |
| 导入 Data.zip 后 | restoreNotebookCryptoConfigFromBackup | 否 | 同上，覆盖"备份随 Data.zip 到达本机但本机未启用"的情况 |
| 用户输主密码解锁（兜底） | tryRestoreNotebookCryptoFromBackup | 是 | deriveKEK 在本机 Enabled=false 时尝试恢复，校验主密码后返回 KEK |
| 用户手动启用（防呆） | tryRestoreNotebookCryptoFromBackup | 是 | 已存在加密笔记本时拒绝生成新 salt，改为从备份恢复并校验主密码 |
配置恢复 vs 密钥恢复分离：配置恢复只需读备份文件、装回 salt/verifier（不需主密码，因 salt 不保密、没主密码仍解不开数据）；密钥恢复才需主密码派生 KEK 并校验 verifier。这让同步/导入后能自动进入"已启用"状态，用户输主密码即可解锁。
手动导出/导入密钥：除自动同步外，用户可在 设置 → 访问授权 → 加密笔记本 手动导出/导入密钥备份，作为同步之外的独立恢复途径（如同步不可用、跨账号迁移、物理离线转存）。
| 操作 | 入口 | 说明 |
|---|---|---|
| 导出密钥 | 已启用状态下显示 | 把 notebook-crypto-backup.json 复制到 export 目录供下载，用户自行保管（API：/api/notebook/exportNotebookCryptoBackup） |
| 导入密钥 | 未启用状态下显示 | 选本地备份文件上传，校验合法后写回 <DataDir>/.siyuan/ 并装回本机配置（Enabled=true）。后续用该密钥对应的主密码解锁（API：/api/notebook/importNotebookCryptoBackup） |
导入防呆：本机已启用时拒绝导入（避免覆盖现有 salt 孤立 WrappedDEK），导入入口仅在未启用时露出。备份文件本身不含主密码（salt 不保密、verifier 是密文），导出/导入不涉及明文数据泄漏，解锁仍需主密码。
防呆守卫：EnableEncryptedNotebook 在磁盘上已存在加密笔记本（Encrypted=true 的笔记本）或内核可枚举的加密恢复数据时，禁止重新生成 MasterSalt（否则会孤立旧 WrappedDEK），改为优先从备份恢复；备份缺失才报错引导用户恢复 conf.json 或备份文件。DisableEncryptedNotebook 对称地扫描现存笔记本、已删除笔记本历史和本地恢复快照；存在依赖时必须拒绝禁用，除非用户明确选择永久清除这些恢复数据。同步端、离线介质和外部快照无法可靠枚举，用户若希望以后恢复这些副本，禁用前必须另行保留导出的匹配密钥备份。
前提条件：restoreNotebookCryptoConfigFromBackup 仅在本机 Enabled=false 时生效，不覆盖正在使用的本机配置。
<workspace>/
├── conf/conf.json ← 全局加密配置（MasterSalt/KEKVerifier）
├── storage/av/ ← 普通笔记本的 数据库文件（明文）
├── data/
│ ├── .siyuan/
│ │ └── notebook-crypto-backup.json ← NotebookCrypto 备份（MasterSalt/KEKVerifier，进同步范围，详见 §4.1）
│ ├── <boxID>/ ← 加密笔记本目录
│ │ ├── .siyuan/conf.json ← BoxConf（Encrypted=true + WrappedDEK)
│ │ ├── *.sy ← AES-256-GCM 密文
│ │ ├── assets/
│ │ │ ├── <uuid>-<blockID>.ext ← AES-256-GCM 密文，文件名已脱敏
│ │ │ └── .names.json ← 原始文件名映射（DEK 加密）
│ │ └── storage/av/
│ │ └── <avID>.json ← 数据库文件（DEK 加密）
│ └── <normalNotebookID>/ ← 普通笔记本（明文，不动）
├── history/ ← 历史目录（密文原样存储）
│ └── <timestamp>-update/
│ └── <boxID>/ ← 加密笔记本的历史（密文 .sy + 密文数据库文件）
└── temp/
├── siyuan.db ← 全局 SQLite（明文，不含加密笔记本数据）
├── blocktree.db ← 全局 blocktree（明文，不含加密笔记本数据）
├── siyuan-encrypted-<boxID>.db ← 加密笔记本 content SQLite 数据库（SQLCipher）
└── siyuan-encrypted-<boxID>-blocktree.db ← 加密笔记本 blocktree SQLite 数据库（SQLCipher）
普通笔记本操作：
前端 → API → 原函数 → 全局 blocktree.db → 全局 siyuan.db
加密笔记本操作（专用读路径，带 boxID）：
前端(带 notebook) → API handler 分流 → InBox 函数
→ 加密 blocktree SQLite 数据库 → 加密 content SQLite 数据库
写路径：集中收口，按笔记本选 SQLite 数据库。索引队列、blocktree 写函数、索引订正全部按笔记本路由。
读路径：三层 fall-through——handler 层按 notebook 参数分流；原函数转发到 InBox 版（普通路径传空 boxID）；底层 wrapper 按加密 SQLite 数据库 是否打开决定路由，空 boxID 必走全局 SQLite 数据库。
深度全路由原则：加密笔记本的读操作经过的每一个 sql 调用（含深层 helper：引用计数、块名/别名、子块递归、FTS 计数、高亮、mention 搜索、refs 定义查询等）都路由到加密 SQLite 数据库，绝不泄漏到全局 SQLite 数据库。
通用入口 fallback：GetBlockTree / ExistBlockTree / GetBlockTrees / LoadTreeByBlockID 等核心函数全局查不到时自动遍历已打开的加密笔记本。
.sy 透明加解密（filesys 层）：
DEKProvider 回调注入（避免循环依赖）.sy AAD 绑定 boxID、对象类型和稳定文件基名 <rootID>.sy，不包含父目录；文件基名必须与解密后根块 ID 一致，并在笔记本内全局唯一assets 加密：
<uuid>-<blockID>.<ext>，原始名存加密映射文件数据库文件加密：
<boxID>/storage/av/<avID>.json，普通笔记本仍存全局 storage/av/RenderAttributeView 从 blockID 反查 boxID 并预设归属blocks.msgpack文件历史：
编辑触发历史生成 → 密文 .sy 原样拷到历史目录
关闭/退出前自动生成历史 → 确保锁定后定时器无法生成时不丢历史
历史索引 → content 留空（密文不进搜索索引）
查看历史 → 读取快照 boxID + 对象类型 + 稳定文件基名，以三者构造原 AAD 解密（需笔记本已解锁）
回滚 → 按快照 AAD 解密历史 → 校验根块 ID 与文件基名一致 → 加载 tree → 文件基名不变时可原样恢复密文，变化时由 WriteTree 重新封装
已删除笔记本历史：
删除前 → 整个目录密文备份到历史目录
恢复 → 使用匹配的全局密钥备份和主密码验证 WrappedDEK 后，将密文目录原样拷回
密钥保留 → 只要内核管理的该类历史仍可恢复，就禁止删除其依赖的全局密钥备份；永久清除历史后才解除依赖
数据库历史：
生成 → 加密笔记本的 数据库文件从笔记本级目录拷到历史目录
查看 → 按快照记录的 boxID 与对象用途/标识解密，不使用历史目录绝对路径作为 AAD
回滚 → 加密笔记本的数据库文件/资源回滚到笔记本级目录
历史文件在历史目录中的父路径不是 AAD 的组成部分。每个历史条目必须以不可歧义的规范格式保留快照写入时的 boxID、对象类型和稳定文件基名或对象标识；可由固定历史目录布局编码，也可由随快照提交的元数据记录。文档只改变父目录时 AAD 上下文保持不变；文件基名改变时，既有历史仍使用旧基名认证解密。回滚时先验证密文、文件基名与解密后对象 ID 一致，再按目标父目录恢复；仅当目标文件基名变化时才按新基名重新封装。快照上下文缺失、格式不合法或与密文不匹配时必须拒绝查看和回滚，不得把密文当明文解析或使用当前文件基名替代快照基名。
加密笔记本的块引：笔记本内部正常使用，跨加密边界被禁止。三层防御：
(( 或 {{ 触发搜索时，请求带 notebook 参数，内核只搜该笔记本自己的加密 SQLite 数据库，结果不含其他笔记本的块。加密笔记本禁止文档跨加密边界移动（普通 ↔ 加密，双向）。
数据损坏风险：跨笔记本移动用文件系统 Rename 直搬 .sy 字节流，不经加解密转换。密文搬到普通目录不可读，明文搬到加密目录不可读。索引也无法跨库迁移。
同一加密笔记本内移动：.sy 密文 AAD 只绑定稳定文件基名，不绑定父目录。文件基名不变的移动按普通笔记本的同箱移动语义原样 Rename 密文，不需要重新封装根文档或子文档；只有文件基名本身变化时才使用旧基名验证解密并按新基名重新封装。移动完成后更新索引，失败处理与普通笔记本一致，不额外引入加密层级元数据。
安全泄漏风险（更关键）：从加密笔记本移动到普通笔记本时——文档正文脱离加密保护；关联 resources 必须一起搬出解密；绑定块与子文档的引用网被割裂或连带泄漏；索引元数据跨库迁移破坏隔离。
设计立场：加密笔记本是孤岛，内容不进出（从加密笔记本移出到普通笔记本会泄漏明文；反之会损坏密文）。
| 场景 | 交互 |
|---|---|
| 启用 | 设置 → 访问授权 → 加密笔记本区块 → 开关 → 设主密码（双输入 + 风险确认） |
| 禁用 | 仅在无现存加密笔记本且无依赖当前密钥备份的内核可枚举历史或恢复快照时支持关闭；否则拒绝，或要求用户明确永久清除这些恢复数据后再删除全局配置与备份 |
| 创建 | 文件面板"更多"菜单 → "新建加密笔记本" → 输名字 + 主密码 → 自动解锁并打开 |
| 图标 | 关闭（锁定）时显示锁图标；打开（解锁）后恢复用户 emoji |
| 解锁 | 点已关闭的加密笔记本 → 弹主密码框（🔓 解锁 xxx）→ 等 ~1 秒 → 打开 |
| 锁定 | 等于关闭：先阻止新操作，等待或取消在途任务，再移除受管 DEK 句柄、删除加密 SQLite 数据库，并尽力清理内核管理的明文缓存、临时文件和访问令牌。关闭前会自动保存未写入的编辑和文件历史 |
| 自动锁定 | 每个已解锁笔记本独立保存最近活动时间；认证用户在当前工作区产生真实界面交互时，统一刷新所有当前已解锁加密笔记本的活动时间。无界面客户端也可通过需要认证与管理员权限的显式保活接口执行同样的刷新；后台读取、同步、索引等非用户活动不自动保活 |
| 改密 | 设置 → 访问授权 → "修改主密码" |
| 移动文档 | 加密笔记本内部仅改变父目录时原样移动密文并更新索引；文件基名变化时重新封装；普通笔记本之间正常移动；跨加密边界（普通↔加密）被拒绝并提示 |
| 文档转标题 | 跨加密边界被拒绝并提示 |
| 块引 | 加密笔记本内部正常引用（搜索 (( 只搜本笔记本，反链面板正常显示）；跨加密边界（普通↔加密、加密 A↔加密 B）被阻止 |
| 数据库镜像 | 加密笔记本内部正常镜像；跨加密边界被禁止 |
| 资源文件重命名 | 不支持（脱敏文件名重命名会破坏映射） |
| 导入 | 支持：导入的 .sy.zip 或 Markdown 文件落盘前自动 DEK 加密 |
| 文件历史 | 支持（查看时需先解锁对应加密笔记本；历史索引不存明文内容） |
| 已删除笔记本 | 支持（密文备份，恢复需匹配的全局密钥备份与主密码；保留该历史时不得直接删除所依赖的密钥备份） |
| 导出 | 支持（与普通笔记本一致；需先解锁，导出的是明文。锁定状态下拒绝导出） |
| 同步 | 不改（密文进密文出，闭环自洽） |
安全前提：加密笔记本在关闭（锁定）状态下提供最强的应用级保护。锁定完成后，新操作被拒绝，受管 DEK 句柄和数据库连接已移除，内核管理的明文缓存、临时文件与令牌已尽力清理；这不承诺抹除 Go 运行时、操作系统交换区、崩溃转储或存储介质中的所有瞬时副本。打开（解锁）状态下，应用持有可用 DEK 句柄，此时已认证的应用内调用方——API、第三方插件、AI/LLM（含 MCP、智能体、语义搜索）——都可像读取普通笔记本一样读到明文内容。内核 CLI 是明确例外：无论锁定或解锁，都会拒绝加密笔记本及其原始文件。加密保护的是“静态数据”和“锁定后经受支持入口的不可达性”，不保护“解锁后对已认证调用方的可见性”。因此：解锁期间应视为“普通笔记本在使用”，并在用完后立即锁定。
保护（磁盘上密文）：
.sy 文档正文（已加密）不保护：
conf.json 里的 MasterSalt/KEKVerifier（设计可明文：salt 不保密，verifier 是密文）uuid-blockID.ext，但扩展名可见；同步端/历史快照中的旧密文也由各存储方自行保管，加密笔记本无法吊销其副本API 防护：
/api/file/getFile、/api/file/putFile、/api/file/copyFile、/api/file/renameFile、/api/file/removeFile：拒绝读写加密笔记本下的任何文件（不只 .sy），避免密文泄漏或明文破坏；合法读写走专用 API（已加密感知）<工作区>/data/<加密笔记本 ID>/ 下的直接路径；不能用于解锁、读写、导出或操作加密笔记本数据加密笔记本对 AI/LLM 的可见性完全由解锁状态决定，不做功能层隔离。
锁定状态下：AI/LLM（含 MCP、智能体、语义搜索、嵌入向量化）无法取得可用 DEK 句柄，所有加密笔记本专用入口都拒绝访问；独立数据库已关闭，磁盘内容为密文，因此这些调用方读不到加密内容。
解锁状态下：DEK 在内存，AI/LLM 可读加密笔记本内容、搜索笔记本内全文——MCP 工具能列出加密笔记本及其文档、读取块内容、笔记本内 FTS 搜索等。但全局搜索、语义搜索、嵌入向量化仍不参与（加密数据不进全局 block_embeddings/blocks 表，物理不可达），详见 §3 对比表。
设计立场：不在功能层做“对 AI 隐藏”的隔离，因为这种隔离既不彻底，又会让安全模型复杂难懂。锁定后受支持入口无法访问内容，但锁定不替代进程与操作系统层面的防护。用户只需理解一条规则：敏感内容用完即锁。
加密笔记本是孤岛，部分功能因其跨 notebook 特性或依赖全局聚合而未实现，属于功能边界，非性能或安全取舍。
uuid-blockID.ext，重命名会破坏原始名映射。| 操作 | 普通笔记本 | 加密笔记本 | 差异原因 |
|---|---|---|---|
| 解锁（Mount） | 即时 | ~1 秒延迟 | Argon2id 密钥派生（故意慢以抗暴力破解） |
| 打开文档 | 读盘 + 解析 JSON | 读盘 + AES-GCM 解密 + 解析 + 加密 SQLite 数据库 查询 | 多一次解密 + 加密 SQLite 数据库 查询 |
| 保存文档 | 渲染 JSON + 写盘 | 渲染 JSON + AES-GCM 加密 + 写盘 | 多一次加密 |
| 上传 assets | 流式写盘 | 全量读入内存 + 加密 + 写盘 | 无法流式加密；大文件有内存压力 |
| 浏览 assets | 直接 ServeFile | 读盘 + 解密 + 输出 | 每次请求都解密，无浏览器缓存 |
| 数据库渲染 | 全局 blocktree + 明文 JSON | 加密 blocktree + DEK 解密 JSON | 多一次 JSON 解密；批量 IAL 加载按笔记本路由 |
| 数据库保存 | 明文 JSON 写盘 | DEK 加密 + 写盘 | 多一次加密 |
| 笔记本内搜索 | FTS 查全局 SQLite 数据库 | FTS 查独立加密 SQLite 数据库 | SQLCipher page 级解密 ~5-10% 开销 |
| 数据库连接 | 1 个全局 | 1 个全局 + 每个解锁的加密笔记本 2 个 | 每加密 SQLite 数据库 连接池约 20 连接 |
| 锁定时 | 无额外开销 | 受管密钥句柄撤销，并尽力清理缓存与临时文件 | 下次操作冷启动延迟 |
性能影响总结：
本特性保护静态数据机密性和笔记本锁定后经受支持入口的不可访问性。设计假设攻击者可以取得工作空间、同步端或备份介质中的当前或历史密文，但不知道主密码，也不能在用户解锁期间控制运行中的应用或操作系统。AES-GCM 只提供单个加密对象的机密性、完整性和来源上下文认证，不提供可用性、版本新鲜度、回滚防护或已保留密文副本的删除。
下列场景不在本特性的保护范围内，界面和用户指南必须明确提示：
“锁定后仅剩密文”只表示内核管理的持久化工作空间中不应存在可读明文，并且受管临时文件、缓存和密钥句柄已经完成尽力清理；不包括用户明确导出到外部位置的文件，也不承诺抹除进程、操作系统或底层存储介质已经保留的瞬时或历史副本。
全局状态为 Disabled、Enabled 或 RecoveryRequired。正常稳态下，Disabled 不得存在现存加密笔记本或内核可枚举的密钥依赖；如果启动时在全局配置缺失或禁用的情况下发现加密笔记本或恢复数据，必须进入 RecoveryRequired，拒绝把它们当作普通笔记本，直到恢复匹配的密钥备份。Enabled 下每个加密笔记本独立处于 Locked、Unlocking、Unlocked、Locking 或 Error，应用启动后均从 Locked 开始。
| 转换 | 前置条件 | 成功后的不变量 | 失败处理 |
|---|---|---|---|
Locked → Unlocking → Unlocked | 主密码验证成功且密文配置匹配 | 可用 DEK 句柄仅存在于受管内存；专属数据库已打开；允许笔记本专用入口 | 撤销派生的 KEK/DEK 句柄、关闭已打开资源并回到 Locked |
Unlocked → Locking → Locked | 原子地关闭新操作准入，并等待在途操作结束或取消 | 无可用受管 DEK 句柄或数据库连接；内核管理的明文缓存、临时文件与令牌已尽力清理 | 保持拒绝访问并进入 Error，记录不含明文的诊断；继续重试清理，未恢复不变量前不得重新开放 |
Unlocked → Error | 密文认证失败、数据库打开失败或不变量被破坏 | 立即拒绝读写，绝不回退到普通笔记本路径 | 关闭资源，诊断信息不得含明文；用户只能锁定或重新解锁 |
| 改主密码 | 所有加密笔记本均为 Locked | 所有 WrappedDEK、全局配置和备份作为一个可恢复事务更新 | 保留旧配置和备份可用；不得出现仅能用新密码解锁的部分笔记本 |
每个笔记本使用同一个生命周期控制器管理状态、操作准入和活跃操作计数。读取、编辑、导出、预览、同步、索引、历史查看或恢复、AI/MCP 访问等操作只能在 Unlocked 时取得只读生命周期租约，并持有到解析完成、缓存发布、HTTP 响应或下载结束，以及异步结果登记完成。锁定与删除原子地把状态改为 Locking 并关闭新租约准入，然后取得排他租约，取消或等待所有在途操作，在排他租约内关闭数据库、清理缓存和临时产物并撤销受管 DEK 句柄；只有清理成功才发布 Locked。因此锁定完成后，不得再出现晚到的明文响应、缓存回填、临时文件或数据库重连。
全局配置锁必须先于任何笔记本生命周期锁获取；同时涉及多个笔记本时按 boxID 字典序获取生命周期锁；DEK 缓存、数据库、文件和其他子系统锁只能在生命周期锁之后获取，并在释放生命周期锁前释放。禁止逆序获取，禁止持有子系统锁时回取全局配置锁或其他较低层级锁。自动锁定按每个笔记本保存活动时间，但当前工作区的一次认证用户交互或显式保活会统一刷新所有已解锁笔记本；计时采用系统时钟并由周期任务检查，系统时钟调整可能相应提前或推迟触发时间，自动锁定是便利性保护而不是精确的安全计时边界。
持久化格式分层，不能把全局 KDF 配置、密钥包络和每个数据对象的封装混为一体：
.sy、资源、资源名称映射和数据库定义对象至少包含格式版本、算法标识、密码学安全随机生成且对同一用途密钥唯一的 nonce、密文和认证标签。当前格式的 AAD 按 格式版本 + boxID + 对象类型 + 稳定对象 ID 确定性构造，不包含父目录或绝对路径；.sy 的稳定对象 ID 是规范化文件基名 <rootID>.sy，资源使用脱敏磁盘文件基名，数据库定义使用 avID，固定单例文件使用版本化常量 ID。解密后必须验证对象内部 ID 与 AAD 对象 ID 一致，并拒绝同一笔记本内的重复对象 ID。AES-GCM nonce 由操作系统 CSPRNG 生成，随机源失败必须终止写入，并按标准规定限制每个用途密钥的调用规模；认证标签不能事后识别已经发生的 nonce 重用，因此不得宣称此类重用会被认证失败自动发现。NotebookCrypto 保存 KDF 算法、参数、MasterSalt、verifier 格式、KEK 包络版本和备份 HMAC 版本；BoxConf.WrappedDEK 保存每个笔记本的 DEK 包络。它们不随每个数据对象重复保存。SQLCipher 的主数据库、WAL、SHM、回滚日志、临时文件和备份副本都是受保护对象，必须放在受控目录并使用对应的用途密钥。锁定、崩溃恢复和历史快照必须枚举这些伴随文件；未加密 SQLite 页面、查询结果或诊断转储不得写入全局临时目录。
notebook-crypto-backup.json 是恢复材料而非秘密。文件带格式版本、备份 ID、创建时间、内容摘要和基于 KEK 的 HMAC；主密码派生 KEK 后，HMAC 缺失或不匹配必须拒绝恢复，不得作为兼容路径放行。恢复不得静默覆盖已启用配置。格式无效或与已有加密笔记本不匹配的备份进入错误状态，而不是生成新的 MasterSalt。
备份持久化遵循项目现有文件写入语义：全局 notebook-crypto-backup.json 通过同目录随机临时文件写入后原子替换，每个笔记本的 notebook-crypt-backup.json 使用文件锁保护的常规配置写入。两者都不额外承诺断电场景下的文件或目录 fsync 持久性；启动时校验无需密钥即可验证的结构和摘要，输入主密码后的恢复再校验 HMAC 以及密钥包络匹配关系。损坏或不匹配时安全拒绝，而不是生成替代密钥材料。
HMAC 只能证明备份内容未被不知道 KEK 的一方篡改，不能证明它是最新版本。当前范围不引入可信外部单调计数器，因此一个认证有效的历史备份或历史密文可能通过校验；BackupID 和 CreatedAt 只是供诊断和人工比较的信息，不是防回滚锚点。同步、历史或恢复流程不得把“认证成功”表述为“最新”或“来源可信”；真正防回滚需要独立可信状态，超出本设计范围。
同步端和离线备份被视为可丢失、可复制、可回滚但不能读取明文的存储。输入主密码前不能建立基于 KEK 的可信认证；用户应保留至少一份独立、版本化的密钥备份，并理解丢失主密码或全部匹配的 MasterSalt 备份均不可恢复。只要现存加密笔记本、已删除笔记本历史或内核可枚举的本地恢复快照仍依赖当前 NotebookCrypto，禁用功能就必须拒绝删除全局配置和备份；用户明确永久清除这些恢复数据后才可解除依赖。外部与远端副本无法可靠枚举，是否保留其匹配密钥备份由用户负责。
| 类别 | 是否可泄露 |
|---|---|
| 文档正文、属性值、资源原始名称、数据库单元格、索引文本 | 否 |
| boxID、目录结构、文件数量、密文大小、修改时间、资源扩展名、块 ID 时间信息 | 是 |
| 笔记本名称 | 是。笔记本列表与加密笔记本状态 API 在锁定时保留名称，以便用户识别要解锁的笔记本，因此笔记本名称不属于机密性保护边界 |
| 图标、排序、文档标题和数量、关系数量、标签、书签、历史与快照名称 | 锁定时默认不得暴露；若兼容性要求暴露，必须逐项在本表及界面中说明 |
不支持的闪卡、书签、标签、资源重命名、未使用资源清理和未使用数据库清理，必须在前端、HTTP API、插件 API、MCP 和导入流程中一致处理：对加密笔记本目标返回明确的“不支持”错误，不创建全局索引、全局属性或延迟任务；已有遗留数据不得被加载、聚合或写回。错误码和本地化文案应稳定，供调用方识别。
所有可能绕过专用读写路径的原始入口必须登记，包括文件 API、内核 CLI、MCP 文件工具、WebDAV、插件文件接口、导出下载 URL、预览 URL 和后台任务。登记表同时覆盖加密笔记本目录和内核管理的明文临时根目录；临时目录必须位于通用原始文件命名空间之外，或被所有原始文件 API 无条件拒绝，不能依赖当前笔记本是否仍存在或 Encrypted 标志是否仍可查询。新增入口时必须评审其是否可读取、写入、复制、重命名、删除或列举加密目录与受控临时目录。
当前实现状态：下文描述的持久化
encrypted-deny-access.json注册表与周期性清理 janitor 尚未实现。当前版本依赖（1）内存态导出令牌（managedEncryptedExports，1 小时过期，锁定或删除笔记本时撤销）；（2）WebDAV 层对整个temp/目录的无条件拒绝。内核崩溃后temp/export/残留明文暂无持久化追踪与重试清理，属已知限制。下文规格描述的是目标设计。
“全局”表示记录在笔记本已删除后仍独立于该笔记本生命周期生效，不表示跨设备同步。记录持久化在 <ConfDir>/encrypted-deny-access.json，位于 DataDir 和 dejavu 同步范围之外，仅管理本机受控临时产物。每项记录至少包含格式版本、随机产物 ID、boxID、受控根目录下的规范相对路径、用途、创建时间、最近重试时间、重试次数和不含原始内容或敏感路径的错误类别；文件使用临时写入、同步落盘、原子替换和目录同步更新。记录中的路径必须重新校验为受控临时根目录的后代，越界或格式损坏的记录不得用于删除任意文件，并触发安全错误和受控根目录重新扫描。
拒绝记录只保存清理状态和诊断信息，不是访问控制依据。文件 API、下载、预览、插件、MCP、WebDAV 和后台任务按规范路径无条件拒绝整个受控明文临时命名空间，即使笔记本、记录文件或单项记录已经不存在。清理器在应用启动、锁定或删除、导出结束或失败后立即运行，并周期性按有上限的指数退避重试；清理成功且确认路径不存在后原子删除对应记录，持续失败则保留记录并维持 Error 或全局拒绝状态，不得因超过重试次数自动放行。记录文件被人为删除、部分条目丢失或文件无法解析时，访问仍保持拒绝；启动和周期扫描从受控根目录残留重建记录后继续清理。只有产物已确认不存在且记录已提交删除，才算清理完成。
导出分为两类：用户主动选择的外部目的地允许产生明文，但开始前必须提示风险；内核管理的预览、转换、下载和中间产物只能位于带 boxID 的受控临时目录，并通过绑定用户、boxID、用途和有效期的最小权限令牌访问。锁定、取消、失败、应用退出和导出完成后都必须使令牌与异步结果立即失效，再尽力清理内核管理的明文；清理失败时，笔记本仍存在则进入 Error，笔记本已删除则保留全局拒绝访问标记，并由后台清理器重试，不能因笔记本已删除或锁定而让通用文件入口重新暴露该路径。日志、错误报告、缩略图、OCR/转换产物和剪贴板同样默认不得含明文，除非用户明确交给外部程序。
| 场景 | 预期结果 |
|---|---|
| 锁定后经 UI、HTTP、文件 API、CLI、MCP、WebDAV、插件、后台任务访问 | 除明确允许暴露的笔记本名称外，不能读取、写入、复制、删除或列举加密内容；错误不返回明文、密文或可推断文档标题的信息 |
| 解锁、锁定、应用重启和认证失败 | 只有 Unlocked 才能取得受管 DEK 句柄和数据库连接；失败和重启后入口拒绝访问，内核可控的明文缓存、临时文件与句柄完成尽力清理 |
| 锁定与响应生成、缓存发布、导出、预览、同步、索引或历史恢复并发 | 锁定在所有在途生命周期租约结束后才成功；成功后无晚到的明文响应、缓存回填、临时文件、可用令牌或数据库重连 |
| 同一加密笔记本内移动文档，随后清空缓存并重启 | 文件基名不变时密文保持不变并可按稳定对象 ID 认证解密；新父目录按普通笔记本语义生效，旧目录位置不存在，失败处理与普通笔记本一致 |
| 加密笔记本与普通笔记本、两个加密笔记本之间的引用、移动、镜像、资源和数据库操作 | 必须保持孤岛边界；拒绝时不得产生半完成文件、全局索引或关联数据 |
| 资源密文写入与名称映射更新任一步失败 | 整个逻辑事务失败并回滚；调用方收到错误，不留下可访问的孤儿资源、缺失映射或明文临时文件 |
| 删除加密笔记本后保留历史，再尝试禁用或恢复 | 存在密钥依赖时拒绝删除全局配置和备份；使用匹配备份与主密码可恢复，只有明确永久清除恢复数据后才允许解除依赖 |
| 文档生成历史后移动父目录或改变文件基名，再查看或回滚旧历史 | 使用历史条目记录的快照 boxID、对象类型和稳定文件基名认证解密；仅在目标基名变化时重新封装，缺失快照上下文时拒绝操作 |
| 文件、资源、数据库、WAL/SHM、历史、快照、日志和临时目录的磁盘检查 | 内核管理范围内不存在可读正文、资源内容、原始资源名称或 SQLite 明文页；清理失败的临时路径仍被所有入口拒绝 |
| 清理失败后删除或损坏全局拒绝访问记录，再重启和访问残留路径 | 受控明文临时命名空间仍被无条件拒绝；扫描重建记录并继续清理，记录缺失或损坏不会使路径失效放行 |
| 密文篡改、路径替换和备份损坏 | 认证或格式校验失败并安全拒绝；不回退普通路径、不生成新密钥材料、不静默覆盖配置 |
| nonce 随机源失败、达到用途密钥调用限制或事后发现 nonce 重用 | 随机源失败或达到限制时在加密前拒绝写入；AES-GCM 认证本身不能发现已发生的 nonce 重用，发现后必须按密钥泄露事件处理并轮换 DEK 后重新加密 |
| 回放认证有效的历史密文或密钥备份 | 可能被识别为有效旧版本，但不得被宣称为最新或来源可信；数据回退风险明确，当前设计不声称提供回滚防护 |
| 改主密码和 KEK 重新包络 | WrappedDEK 与备份原子更新；更新中断后旧配置仍可恢复使用；旧密码暴露风险提示正确；迁移前后数据与历史均可验证读取 |
| 多个笔记本并发操作与自动锁定 | 锁顺序无死锁；认证用户界面活动或显式保活统一刷新所有当前已解锁笔记本，后台任务不自动刷新；锁定中的笔记本不再接受新租约 |
强度建议：12 位以上，混合大小写 + 数字 + 符号。主密码越强，抗暴力破解能力越高（密码强度是唯一的安全防线，没有后门）。
重要：加密笔记本在锁定状态下提供最强的应用级保护，但锁定只会尽力清理应用可控的内存和临时数据，不承诺抹除操作系统或底层介质中的所有瞬时副本。解锁期间，已认证的应用内调用方（API、插件、AI/LLM 含 MCP）都能像读普通笔记本一样读到明文；内核 CLI 始终拒绝操作加密笔记本（详见 §12 安全前提）。
进入 设置 → 访问授权 → 修改主密码。改密只需重新包络各笔记本的 WrappedDEK，不重新加密文档数据，因此即时完成。改密后密钥备份会自动刷新并同步。
重要语义：改密采用 KEK 包络模式——DEK 本身不变，只是用新主密码派生的新 KEK 重新包络 WrappedDEK。这意味着改密不能吊销旧主密码的解密能力：如果旧主密码和旧 WrappedDEK（如同步端、备份、历史快照中保留的）同时泄露，仍能解出同一个 DEK，进而解当前数据。如果怀疑旧主密码已泄露，应迁移内容到新建的加密笔记本（新 DEK）而非仅改密。
加密笔记本的密文 .sy/assets/数据库文件会随数据同步（密文进密文出，闭环自洽）；全局密钥材料（MasterSalt 等）也会自动备份到同步目录。新设备同步后无需手动"启用"：
若新设备同步后笔记本仍显示锁定属正常——点开输主密码即可。
同步恢复可以校验备份完整性，但不能证明它是最新版本。请另外保留版本化的密钥备份；出现多个历史副本时，系统无法自动判定新鲜度，恢复前应由用户根据可信来源和时间信息确认版本。
.sy.zip 和 Markdown，内容在落盘前自动用 DEK 加密，与手动创建的文档一致.sy.zip、HTML、Word、PDF、Markdown 等格式均支持；锁定状态下拒绝导出无法恢复——这是设计使然（没有后门）。即使密文已同步到云端，没有主密码也解不开。务必牢记主密码，建议使用密码管理器保存。
若 conf/conf.json 与同步目录里的密钥备份同时丢失（极端情况），重新启用加密笔记本会被拒绝并提示恢复备份文件。只要能从其他已同步的设备或之前导出的密钥文件找回 notebook-crypto-backup.json，可通过未启用状态下显示的"导入密钥"按钮导入，或手动放回 <工作区>/data/.siyuan/ 后重新启用，即可用该密钥对应的主密码解锁。
恢复已删除加密笔记本的历史同样需要与其 WrappedDEK 匹配的全局密钥备份和主密码。只要仍要保留这类本地恢复能力，就不要永久清除其历史或匹配的密钥备份；禁用流程应在发现这类依赖时拒绝继续。