# 架构

加密、文件身份与共享版本语义属于 Core，各适配器使用同一当前版本、冲突、保留与设备权限规则。

| 组件 | 职责 |
| --- | --- |
| `cipherfs-core` | 稳定 FileId/版本 DAG、redb 敏感字段与 CAS、设备签名日志、成员/密钥纪元、快照校验、本机内容策略、退休与导出 |
| `cipherfs-sync` | Directory/S3 不可变对象、pack、认证 Iroh/P2P 与配对、内容来源、独立后台循环和存放点 GC |
| `cipherfs-cli` / `cipherfs-fuse` | 命令和挂载语义，包括只读冲突视图 |
| `cipherfs-web` / `cipherfs-web-ui` | 会话绑定 HTTP/流式传输，设备/冲突/保留操作和 React UI |
| `cipherfs-ffi` / `cipherfs-python` / `cipherfs-go` | 本机文件/目录及恢复重设密码 API |

WebDAV 存放点和移动端仍待实现。早期的 WebDAV 网关、S3 网关和 TUI 原型已从源码树删除，最后版本在 git 历史提交 6f4408b。

## 索引与正文

每台设备追加独立序号、哈希链和因果依赖的不可变加密签名日志，无全局可变头、存放点锁或条件更新。单段及完整多段批次原子应用，已知 frontier 阻止重放回退。签名快照必须核对所覆盖原始输入的完整重放才能加速首次同步，本身不新增权限。

FileId 随移动保留，路径由版本导出，目录来自前缀，空目录仅在本机。并发内容/路径头保持可读，当前版本按统一规则选择，后续写入引用全部已知头。历史、垃圾箱和冲突是共享视图，不生成额外副本文件。

存放点同时承载密文 pack 和索引段，locator 将认证内容单元映射到包内范围。缺失/不完整对象等待重试，完整对象认证失败报损坏。Full 获取全部未退休正文，Partial 获取固定目录并保留有预算的读取缓存。正文位置与存放点确认描述已知持有者，和索引位置分开。

## 密钥与退休

DeviceId 是 Ed25519/Iroh 公共身份；密码与恢复封装保护随机本机存储密钥及设备 seed。主密钥是零纪元，后续纪元密钥随机生成，只向剩余成员与恢复密钥封装。撤销 cutoff 会重建所有已接纳效果，包括后续管理记录。配对使用一次性秘密和已有成员的 SAS 批准。

恢复初始化含独立 genesis 信任锚。恢复自加入可以立即读写，设备管理仍需独立已有成员批准后才能撤销、轮换或批准配对；所有已有设备丢失时，该限制同样存在。

退休共享、宽限期可取消，生效时再次保护当前/冲突/未发布版本。默认提案后第 30 天生效、第 31 天允许本机释放、第 38 天最早远端 GC，运行时快照继续延后本机释放。认证上传清单覆盖孤儿 pack，重打包先发布替换内容和 locator 再延迟删除旧包；因果版本元数据保留。

## 边界与决策

当前使用根子树；子树密钥派生不等于已实现子树授权。正文适配器流式有界，bytes Vec/Blob 为 O(对象/范围)，列表/历史/垃圾箱/冲突 Vec 为 O(返回项数)。Core 与 SyncedVault 提供有界列表/历史页，续页只持有值，每次读取当前视图；完整索引/成员状态、历史已访问/父版本 ID、head/争用者及单版本单元元数据仍可增长。冷启动权限证明与快照仍为上限 32MiB 的单对象，任意长历史/百万文件规模尚未验收。

完整离线明文导出要求 Full 正文已追上本机接纳的 frontier 且本机缓存完整；Partial/追赶中的设备报告所选正文缺失。导出固定选择并保留版本/正文，流式读取正文，选择元数据随规模增长。新目标及归档须能无损表示所选键，父路径无符号链接并支持锚定独占发布，原生名字/路径碰撞明确失败。writer/HTTP 流可能在晚发错误前输出认证前缀，失败后必须丢弃/中止输出；缓冲读取失败返回 Err。

见[已确认需求](requirements.zh.md)、[Rust 接入](rust-api.zh.md)和 [ADR](adr/README.zh.md)。仓库 `docs/IMPLEMENTATION_AUDIT.md` 保存当前决策和运行证据，旧 ADR 保留当时背景。