dsh-encrypt 架构

本项目使用分层模块承载加密凭证生命周期，并保留 src/index.ts、src/vault.ts、src/web.ts、src/client.ts 作为兼容入口。兼容入口负责组合与导出，不再承载可复用的底层规则。

模块边界

层	目录	职责	允许依赖
领域	src/domain	常量、稳定错误码、文档和 Provider 类型、Valibot schema	src/shared、Valibot
应用	src/application	密码转换、记住登录、串行操作、状态视图策略	领域层、基础设施端口实现
基础设施	src/infrastructure	Node 密码学、磁盘文档、权限、运行时配置	领域层、共享校验
传输	src/transport	HTTP 结构类型、请求 schema、限量读取和边界错误	领域层、共享校验、Valibot
安全	src/security	字面量泄露匹配、HTTP 与 WebSocket 脱敏	LeakGuard 的窄接口
客户端	src/client	浏览器 SHA3、API、票据存储、界面状态映射	浏览器标准 API
共享	src/shared	无状态、无平台依赖的字符和文本校验	无项目内依赖

依赖方向以领域类型为中心。密码学模块不读取文件，文档模块不处理 HTTP，HTTP schema 不调用 Provider，客户端不导入 Node API。

Vault 组合

src/vault.ts 维持原有包导出。实际实现由以下模块组成：

1. domain/vault/model.ts 定义文档常量、类型和 VaultError。
2. domain/vault/schemas.ts 用 Valibot 校验持久化文档。
3. infrastructure/crypto/vault-crypto.ts 处理 Argon2id、scrypt、AES-GCM、SHA3 和密钥清零。
4. infrastructure/persistence/vault-document.ts 处理规范化序列化、结构校验和文档指纹。
5. application/password-service.ts 处理设密、解锁和密码证明。
6. application/remember-service.ts 处理票据签发、有效期和主密钥恢复。

每个模块都可以通过内存输入单独测试。磁盘文档格式、公开函数名和稳定错误码由兼容入口保持。

校验策略

项目使用两类校验：

• Valibot 校验 JSON、状态文件和 HTTP 请求等不可信结构。
• 显式字符扫描校验十六进制、凭证引用和版本文本。

项目不使用正则表达式。泄露检测使用不可变字面量 trie，并按“最早位置、最长值、互不重叠”选择匹配项。该实现不会把凭证内容拼进动态正则，也不会受到正则特殊字符影响。

@deepseek-ai/schemastery 只保留在 Cordis 的静态插件配置边界，因为该边界由宿主框架读取。业务输入和磁盘输入统一由 Valibot 校验。

并发与状态

OperationQueue 为文件修改提供失败隔离的串行顺序。Provider 的任务失败不会污染队列尾部，后续任务仍可运行。密码解锁入口限制待处理请求数量，已接收的请求再进入同一串行队列执行状态变更。

src/web.ts 只组合路由、访问检查和应用操作。共享 HTTP 结构及限量请求读取位于传输层；HTTP 与 WebSocket 输出脱敏位于安全层。

运行时状态文件按字段独立校验。一个损坏字段不会抹掉同文件内其他有效字段。Provider 只把加密记录保存在长期快照中；明文只存在于一次解析或回调期间。

变更规则

• 新磁盘字段必须先加入领域类型和 Valibot schema，再加入规范化指纹字段顺序。
• 新 HTTP 操作必须先定义精确请求 schema，禁止使用字符串强制转换接受错误类型。
• 新密码学能力必须留在 infrastructure/crypto，并通过领域类型返回结果。
• 新输出通道必须复用安全模块的字面量脱敏器，或明确记录无法扫描的二进制边界。
• 兼容入口的导出变更必须配套声明构建和回归测试。