@carloswon/cairn-memory 0.0.0-stage → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (225) hide show
  1. package/CHANGELOG.md +81 -0
  2. package/LICENSE +21 -0
  3. package/README.md +158 -2
  4. package/dist/src/agents/adapters.d.ts +82 -0
  5. package/dist/src/agents/adapters.js +209 -0
  6. package/dist/src/agents/adapters.js.map +1 -0
  7. package/dist/src/agents/config.d.ts +82 -0
  8. package/dist/src/agents/config.js +603 -0
  9. package/dist/src/agents/config.js.map +1 -0
  10. package/dist/src/agents/cordisPatch.d.ts +89 -0
  11. package/dist/src/agents/cordisPatch.js +201 -0
  12. package/dist/src/agents/cordisPatch.js.map +1 -0
  13. package/dist/src/agents/index.d.ts +2 -0
  14. package/dist/src/agents/index.js +3 -0
  15. package/dist/src/agents/index.js.map +1 -0
  16. package/dist/src/core/errors.d.ts +36 -0
  17. package/dist/src/core/errors.js +74 -0
  18. package/dist/src/core/errors.js.map +1 -0
  19. package/dist/src/core/hash.d.ts +14 -0
  20. package/dist/src/core/hash.js +48 -0
  21. package/dist/src/core/hash.js.map +1 -0
  22. package/dist/src/core/ids.d.ts +10 -0
  23. package/dist/src/core/ids.js +41 -0
  24. package/dist/src/core/ids.js.map +1 -0
  25. package/dist/src/core/index.d.ts +6 -0
  26. package/dist/src/core/index.js +7 -0
  27. package/dist/src/core/index.js.map +1 -0
  28. package/dist/src/core/scope.d.ts +78 -0
  29. package/dist/src/core/scope.js +181 -0
  30. package/dist/src/core/scope.js.map +1 -0
  31. package/dist/src/core/secrets.d.ts +13 -0
  32. package/dist/src/core/secrets.js +122 -0
  33. package/dist/src/core/secrets.js.map +1 -0
  34. package/dist/src/core/time.d.ts +7 -0
  35. package/dist/src/core/time.js +18 -0
  36. package/dist/src/core/time.js.map +1 -0
  37. package/dist/src/core/types.d.ts +139 -0
  38. package/dist/src/core/types.js +30 -0
  39. package/dist/src/core/types.js.map +1 -0
  40. package/dist/src/governance/apply.d.ts +64 -0
  41. package/dist/src/governance/apply.js +160 -0
  42. package/dist/src/governance/apply.js.map +1 -0
  43. package/dist/src/governance/archive.d.ts +29 -0
  44. package/dist/src/governance/archive.js +52 -0
  45. package/dist/src/governance/archive.js.map +1 -0
  46. package/dist/src/governance/dedup.d.ts +21 -0
  47. package/dist/src/governance/dedup.js +23 -0
  48. package/dist/src/governance/dedup.js.map +1 -0
  49. package/dist/src/governance/index.d.ts +16 -0
  50. package/dist/src/governance/index.js +17 -0
  51. package/dist/src/governance/index.js.map +1 -0
  52. package/dist/src/governance/propose.d.ts +78 -0
  53. package/dist/src/governance/propose.js +150 -0
  54. package/dist/src/governance/propose.js.map +1 -0
  55. package/dist/src/index.d.ts +15 -0
  56. package/dist/src/index.js +24 -0
  57. package/dist/src/index.js.map +1 -0
  58. package/dist/src/interfaces/app-service.d.ts +292 -0
  59. package/dist/src/interfaces/app-service.js +743 -0
  60. package/dist/src/interfaces/app-service.js.map +1 -0
  61. package/dist/src/interfaces/cli/main.d.ts +2 -0
  62. package/dist/src/interfaces/cli/main.js +854 -0
  63. package/dist/src/interfaces/cli/main.js.map +1 -0
  64. package/dist/src/interfaces/console/assets/page.d.ts +18 -0
  65. package/dist/src/interfaces/console/assets/page.js +39 -0
  66. package/dist/src/interfaces/console/assets/page.js.map +1 -0
  67. package/dist/src/interfaces/console/assets/ui-css.d.ts +11 -0
  68. package/dist/src/interfaces/console/assets/ui-css.js +119 -0
  69. package/dist/src/interfaces/console/assets/ui-css.js.map +1 -0
  70. package/dist/src/interfaces/console/assets/ui-js.d.ts +14 -0
  71. package/dist/src/interfaces/console/assets/ui-js.js +1098 -0
  72. package/dist/src/interfaces/console/assets/ui-js.js.map +1 -0
  73. package/dist/src/interfaces/console/assets/url-state.d.ts +9 -0
  74. package/dist/src/interfaces/console/assets/url-state.js +45 -0
  75. package/dist/src/interfaces/console/assets/url-state.js.map +1 -0
  76. package/dist/src/interfaces/console/export.d.ts +46 -0
  77. package/dist/src/interfaces/console/export.js +84 -0
  78. package/dist/src/interfaces/console/export.js.map +1 -0
  79. package/dist/src/interfaces/console/model.d.ts +372 -0
  80. package/dist/src/interfaces/console/model.js +731 -0
  81. package/dist/src/interfaces/console/model.js.map +1 -0
  82. package/dist/src/interfaces/console/review-store.d.ts +142 -0
  83. package/dist/src/interfaces/console/review-store.js +342 -0
  84. package/dist/src/interfaces/console/review-store.js.map +1 -0
  85. package/dist/src/interfaces/console/security.d.ts +76 -0
  86. package/dist/src/interfaces/console/security.js +105 -0
  87. package/dist/src/interfaces/console/security.js.map +1 -0
  88. package/dist/src/interfaces/console/server.d.ts +45 -0
  89. package/dist/src/interfaces/console/server.js +476 -0
  90. package/dist/src/interfaces/console/server.js.map +1 -0
  91. package/dist/src/interfaces/console/suggestions.d.ts +112 -0
  92. package/dist/src/interfaces/console/suggestions.js +511 -0
  93. package/dist/src/interfaces/console/suggestions.js.map +1 -0
  94. package/dist/src/interfaces/console/text.d.ts +4 -0
  95. package/dist/src/interfaces/console/text.js +18 -0
  96. package/dist/src/interfaces/console/text.js.map +1 -0
  97. package/dist/src/interfaces/mcp/server.d.ts +4 -0
  98. package/dist/src/interfaces/mcp/server.js +480 -0
  99. package/dist/src/interfaces/mcp/server.js.map +1 -0
  100. package/dist/src/jobs/index.d.ts +6 -0
  101. package/dist/src/jobs/index.js +7 -0
  102. package/dist/src/jobs/index.js.map +1 -0
  103. package/dist/src/jobs/remote.d.ts +42 -0
  104. package/dist/src/jobs/remote.js +34 -0
  105. package/dist/src/jobs/remote.js.map +1 -0
  106. package/dist/src/jobs/worker.d.ts +67 -0
  107. package/dist/src/jobs/worker.js +169 -0
  108. package/dist/src/jobs/worker.js.map +1 -0
  109. package/dist/src/onboarding/auto.d.ts +88 -0
  110. package/dist/src/onboarding/auto.js +399 -0
  111. package/dist/src/onboarding/auto.js.map +1 -0
  112. package/dist/src/onboarding/batches.d.ts +103 -0
  113. package/dist/src/onboarding/batches.js +219 -0
  114. package/dist/src/onboarding/batches.js.map +1 -0
  115. package/dist/src/onboarding/discover.d.ts +54 -0
  116. package/dist/src/onboarding/discover.js +369 -0
  117. package/dist/src/onboarding/discover.js.map +1 -0
  118. package/dist/src/onboarding/import.d.ts +69 -0
  119. package/dist/src/onboarding/import.js +279 -0
  120. package/dist/src/onboarding/import.js.map +1 -0
  121. package/dist/src/onboarding/index.d.ts +24 -0
  122. package/dist/src/onboarding/index.js +22 -0
  123. package/dist/src/onboarding/index.js.map +1 -0
  124. package/dist/src/onboarding/judgement.d.ts +50 -0
  125. package/dist/src/onboarding/judgement.js +121 -0
  126. package/dist/src/onboarding/judgement.js.map +1 -0
  127. package/dist/src/onboarding/policy.d.ts +86 -0
  128. package/dist/src/onboarding/policy.js +249 -0
  129. package/dist/src/onboarding/policy.js.map +1 -0
  130. package/dist/src/projection/brief.d.ts +112 -0
  131. package/dist/src/projection/brief.js +200 -0
  132. package/dist/src/projection/brief.js.map +1 -0
  133. package/dist/src/projection/index.d.ts +1 -0
  134. package/dist/src/projection/index.js +2 -0
  135. package/dist/src/projection/index.js.map +1 -0
  136. package/dist/src/projection/markdown.d.ts +82 -0
  137. package/dist/src/projection/markdown.js +313 -0
  138. package/dist/src/projection/markdown.js.map +1 -0
  139. package/dist/src/retrieval/export.d.ts +80 -0
  140. package/dist/src/retrieval/export.js +215 -0
  141. package/dist/src/retrieval/export.js.map +1 -0
  142. package/dist/src/retrieval/index.d.ts +5 -0
  143. package/dist/src/retrieval/index.js +6 -0
  144. package/dist/src/retrieval/index.js.map +1 -0
  145. package/dist/src/retrieval/search.d.ts +37 -0
  146. package/dist/src/retrieval/search.js +294 -0
  147. package/dist/src/retrieval/search.js.map +1 -0
  148. package/dist/src/store/archives.d.ts +94 -0
  149. package/dist/src/store/archives.js +135 -0
  150. package/dist/src/store/archives.js.map +1 -0
  151. package/dist/src/store/audit.d.ts +57 -0
  152. package/dist/src/store/audit.js +131 -0
  153. package/dist/src/store/audit.js.map +1 -0
  154. package/dist/src/store/backup.d.ts +36 -0
  155. package/dist/src/store/backup.js +90 -0
  156. package/dist/src/store/backup.js.map +1 -0
  157. package/dist/src/store/blocks.d.ts +64 -0
  158. package/dist/src/store/blocks.js +104 -0
  159. package/dist/src/store/blocks.js.map +1 -0
  160. package/dist/src/store/conflicts.d.ts +52 -0
  161. package/dist/src/store/conflicts.js +112 -0
  162. package/dist/src/store/conflicts.js.map +1 -0
  163. package/dist/src/store/db.d.ts +44 -0
  164. package/dist/src/store/db.js +162 -0
  165. package/dist/src/store/db.js.map +1 -0
  166. package/dist/src/store/device.d.ts +46 -0
  167. package/dist/src/store/device.js +111 -0
  168. package/dist/src/store/device.js.map +1 -0
  169. package/dist/src/store/index.d.ts +14 -0
  170. package/dist/src/store/index.js +15 -0
  171. package/dist/src/store/index.js.map +1 -0
  172. package/dist/src/store/memories.d.ts +133 -0
  173. package/dist/src/store/memories.js +442 -0
  174. package/dist/src/store/memories.js.map +1 -0
  175. package/dist/src/store/migrate.d.ts +32 -0
  176. package/dist/src/store/migrate.js +87 -0
  177. package/dist/src/store/migrate.js.map +1 -0
  178. package/dist/src/store/open.d.ts +53 -0
  179. package/dist/src/store/open.js +203 -0
  180. package/dist/src/store/open.js.map +1 -0
  181. package/dist/src/store/outbox.d.ts +65 -0
  182. package/dist/src/store/outbox.js +137 -0
  183. package/dist/src/store/outbox.js.map +1 -0
  184. package/dist/src/store/plans.d.ts +137 -0
  185. package/dist/src/store/plans.js +243 -0
  186. package/dist/src/store/plans.js.map +1 -0
  187. package/dist/src/store/schema.d.ts +46 -0
  188. package/dist/src/store/schema.js +544 -0
  189. package/dist/src/store/schema.js.map +1 -0
  190. package/dist/src/store/scopes.d.ts +44 -0
  191. package/dist/src/store/scopes.js +220 -0
  192. package/dist/src/store/scopes.js.map +1 -0
  193. package/dist/src/store/write-guard.d.ts +10 -0
  194. package/dist/src/store/write-guard.js +10 -0
  195. package/dist/src/store/write-guard.js.map +1 -0
  196. package/dist/src/sync/apply.d.ts +24 -0
  197. package/dist/src/sync/apply.js +130 -0
  198. package/dist/src/sync/apply.js.map +1 -0
  199. package/dist/src/sync/cryptoutil.d.ts +86 -0
  200. package/dist/src/sync/cryptoutil.js +339 -0
  201. package/dist/src/sync/cryptoutil.js.map +1 -0
  202. package/dist/src/sync/events.d.ts +69 -0
  203. package/dist/src/sync/events.js +78 -0
  204. package/dist/src/sync/events.js.map +1 -0
  205. package/dist/src/sync/obs-store.d.ts +41 -0
  206. package/dist/src/sync/obs-store.js +325 -0
  207. package/dist/src/sync/obs-store.js.map +1 -0
  208. package/dist/src/sync/orchestrate.d.ts +37 -0
  209. package/dist/src/sync/orchestrate.js +84 -0
  210. package/dist/src/sync/orchestrate.js.map +1 -0
  211. package/dist/src/sync/pull.d.ts +24 -0
  212. package/dist/src/sync/pull.js +150 -0
  213. package/dist/src/sync/pull.js.map +1 -0
  214. package/dist/src/sync/push.d.ts +19 -0
  215. package/dist/src/sync/push.js +227 -0
  216. package/dist/src/sync/push.js.map +1 -0
  217. package/dist/src/sync/syncd-store.d.ts +31 -0
  218. package/dist/src/sync/syncd-store.js +92 -0
  219. package/dist/src/sync/syncd-store.js.map +1 -0
  220. package/dist/src/sync/vault.d.ts +37 -0
  221. package/dist/src/sync/vault.js +53 -0
  222. package/dist/src/sync/vault.js.map +1 -0
  223. package/docs/cairn-security.md +267 -0
  224. package/docs/cairn-usage.md +919 -0
  225. package/package.json +71 -4
@@ -0,0 +1,339 @@
1
+ /**
2
+ * Cairn 云同步 E2EE 工具(design D3 / spec「加密中继与密钥主权」)。
3
+ *
4
+ * 密文线格式(版本化;禁止自造算法,全部使用可审计纯 JS 库 @noble/ciphers、@noble/hashes):
5
+ *
6
+ * [version(1B)] [nonce(24B)] [XChaCha20-Poly1305 ciphertext || Poly1305 tag(16B)]
7
+ *
8
+ * - version 即 CIPHER_VERSION(当前 1);不匹配 → E_VALIDATION 'cipher_version_mismatch'。
9
+ * - nonce 每次加密用 CSPRNG 随机生成 24B(XChaCha 扩展 nonce,随机 nonce 安全)。
10
+ * - AAD = UTF8(`v1|${vaultId}|${spaceId}|${kind}|${objectId}`),把每段密文绑定到
11
+ * vault/space/kind/object:任一字段不匹配 → Poly1305 校验失败 →
12
+ * E_VALIDATION 'auth_tag_invalid'(密文不能被搬到别的 chunk/manifest 位置)。
13
+ * - space 数据密钥 = HKDF-SHA256(vaultKey, salt='cairn-space-key', info=`v1|${spaceId}`):
14
+ * vault 主密钥不直接加密任何数据,泄露面按 space 隔离(tests 有字面量锚定测试)。
15
+ *
16
+ * 信任边界(诚实声明,构想 §12.2):
17
+ * - keys.json 中的 vaultKey 是本地明文,与 SQLite 数据库文件处于同等信任边界;
18
+ * 文件权限只防误读,不防拿到磁盘的人;设备级保护依赖磁盘加密与账户隔离。
19
+ * - 恢复材料(CAIRN1.…)同样是密钥明文的编码形态,抄写保存,丢失即远端不可恢复。
20
+ * - 所有错误信息为稳定短语,绝不包含密钥字节(hex/base64)或记忆内容。
21
+ */
22
+ import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
23
+ import { randomBytes } from 'node:crypto';
24
+ import { join } from 'node:path';
25
+ import { xchacha20poly1305 } from '@noble/ciphers/chacha.js';
26
+ import { hkdf } from '@noble/hashes/hkdf.js';
27
+ import { sha256 } from '@noble/hashes/sha2.js';
28
+ import { err } from '../core/errors.js';
29
+ import { canonicalJson } from '../core/hash.js';
30
+ import { isUuid, uuidv7 } from '../core/ids.js';
31
+ import { nowIso } from '../core/time.js';
32
+ /** 密文格式版本号(线格式首字节)。未来算法更换/密钥轮换时递增并引入 keyId(design D3)。 */
33
+ export const CIPHER_VERSION = 1;
34
+ const VERSION_LEN = 1;
35
+ /** XChaCha20 扩展 nonce 长度。 */
36
+ const NONCE_LEN = 24;
37
+ /** Poly1305 认证标签长度。 */
38
+ const TAG_LEN = 16;
39
+ /** vaultKey / spaceKey 均为 32 字节。 */
40
+ const KEY_LEN = 32;
41
+ /** 最小合法密文长度:版本(1) + nonce(24) + 空 plaintext 的 tag(16)。 */
42
+ const MIN_BLOB_LEN = VERSION_LEN + NONCE_LEN + TAG_LEN;
43
+ /** HKDF salt 固定串。info 携带协议版本与 spaceId;tests/sync 有字面量锚定测试防止无意变更。 */
44
+ const SPACE_KEY_SALT = 'cairn-space-key';
45
+ const KEYS_FILE = 'keys.json';
46
+ const KEYS_FORMAT = 'cairn-vault-keys';
47
+ const KEYS_VERSION = 1;
48
+ /** 恢复材料前缀(CAIRN1.<base64url(canonicalJson)>)。 */
49
+ const RECOVERY_PREFIX = 'CAIRN1.';
50
+ const RECOVERY_FORMAT = 'cairn-vault-recovery';
51
+ const RECOVERY_VERSION = 1;
52
+ const textEncoder = new TextEncoder();
53
+ /** 生成新 vault 密钥集:vaultId 为 UUIDv7(时间可排序),vaultKey 为 32B CSPRNG 随机。 */
54
+ export function generateVaultKeys() {
55
+ // Uint8Array.from 复制一份,脱离 Buffer 内部池化语义,保证返回纯 Uint8Array。
56
+ return {
57
+ vaultId: uuidv7(),
58
+ vaultKey: Uint8Array.from(randomBytes(KEY_LEN)),
59
+ createdAt: nowIso(),
60
+ };
61
+ }
62
+ /**
63
+ * 派生 space 数据密钥:HKDF-SHA256(vaultKey, salt='cairn-space-key', info=`v1|${spaceId}`)。
64
+ * 确定性:同 vaultKey + 同 spaceId 永远得到同一 spaceKey(跨设备无需协商)。
65
+ */
66
+ export function deriveSpaceKey(vaultKey, spaceId) {
67
+ if (!(vaultKey instanceof Uint8Array) || vaultKey.length !== KEY_LEN) {
68
+ throw err('E_VALIDATION', 'vault_key_invalid_length', {
69
+ expected: KEY_LEN,
70
+ got: vaultKey instanceof Uint8Array ? vaultKey.length : null,
71
+ });
72
+ }
73
+ if (typeof spaceId !== 'string' || spaceId.length === 0) {
74
+ throw err('E_VALIDATION', 'space_id_invalid');
75
+ }
76
+ return hkdf(sha256, vaultKey, textEncoder.encode(SPACE_KEY_SALT), textEncoder.encode(`v1|${spaceId}`), KEY_LEN);
77
+ }
78
+ /**
79
+ * 加密一个同步对象。输出 = [versionByte(1)] + [nonce(24)] + [ciphertext+tag]。
80
+ * AAD = UTF8(`v1|${vaultId}|${spaceId}|${kind}|${objectId}`)。
81
+ */
82
+ export function encryptObject(plaintext, spaceKey, aad) {
83
+ assertAad(aad);
84
+ assertSpaceKey(spaceKey);
85
+ if (!(plaintext instanceof Uint8Array)) {
86
+ throw err('E_VALIDATION', 'plaintext_invalid');
87
+ }
88
+ const nonce = randomBytes(NONCE_LEN);
89
+ const ciphertext = xchacha20poly1305(spaceKey, nonce, aadBytes(aad)).encrypt(plaintext);
90
+ const out = new Uint8Array(VERSION_LEN + NONCE_LEN + ciphertext.length);
91
+ out[0] = CIPHER_VERSION;
92
+ out.set(nonce, VERSION_LEN);
93
+ out.set(ciphertext, VERSION_LEN + NONCE_LEN);
94
+ return out;
95
+ }
96
+ /**
97
+ * 解密一个同步对象。
98
+ * - 版本字节不匹配 → E_VALIDATION 'cipher_version_mismatch';
99
+ * - blob 过短 → E_VALIDATION 'cipher_blob_too_short';
100
+ * - tag 校验失败或 AAD 不匹配 → E_VALIDATION 'auth_tag_invalid'。
101
+ */
102
+ export function decryptObject(blob, spaceKey, aad) {
103
+ assertAad(aad);
104
+ assertSpaceKey(spaceKey);
105
+ if (!(blob instanceof Uint8Array) || blob.length < MIN_BLOB_LEN) {
106
+ throw err('E_VALIDATION', 'cipher_blob_too_short', {
107
+ got: blob instanceof Uint8Array ? blob.length : null,
108
+ minLength: MIN_BLOB_LEN,
109
+ });
110
+ }
111
+ const version = blob[0];
112
+ if (version !== CIPHER_VERSION) {
113
+ throw err('E_VALIDATION', 'cipher_version_mismatch', { got: version, expected: CIPHER_VERSION });
114
+ }
115
+ const nonce = blob.subarray(VERSION_LEN, VERSION_LEN + NONCE_LEN);
116
+ const ciphertext = blob.subarray(VERSION_LEN + NONCE_LEN);
117
+ try {
118
+ return xchacha20poly1305(spaceKey, nonce, aadBytes(aad)).decrypt(ciphertext);
119
+ }
120
+ catch {
121
+ // noble 对 tag 不匹配 / AAD 不匹配 / 密钥错误统一抛 'invalid tag';
122
+ // 对外只暴露稳定错误短语,不透传内部细节(也不含密钥材质)。
123
+ throw err('E_VALIDATION', 'auth_tag_invalid');
124
+ }
125
+ }
126
+ /**
127
+ * 保存 vault 密钥到 `dataDir/keys.json`。
128
+ *
129
+ * - 已存在时拒绝覆盖(E_IO 'keys_already_exist'):防止误覆盖丢密钥;
130
+ * 写入用 flag 'wx'(已存在即失败的原子语义,覆盖并发窗口)。
131
+ * - POSIX:显式 chmod 0600('wx' 新建 + mode 0600 下 umask 只能再去位,结果仍为 0600,chmod 为兜底)。
132
+ * - Windows 局限(诚实边界,构想 §12.2):Node 的 fs.chmodSync 在 Windows 上只能切换
133
+ * 只读位,不对应 POSIX 0600;NTFS ACL 无法用 POSIX 模式表达,因此 Windows 下不做 chmod。
134
+ * keys.json 的 vaultKey 是本地明文,与 SQLite 库文件同等信任边界:文件权限不等于加密,
135
+ * 设备级保护依赖磁盘加密(BitLocker)与账户隔离,而非这里的文件模式。
136
+ */
137
+ export function saveKeys(dataDir, keys) {
138
+ if (typeof dataDir !== 'string' || dataDir.length === 0) {
139
+ throw err('E_VALIDATION', 'data_dir_invalid');
140
+ }
141
+ assertVaultKeys(keys);
142
+ mkdirSync(dataDir, { recursive: true });
143
+ const path = join(dataDir, KEYS_FILE);
144
+ if (existsSync(path)) {
145
+ throw err('E_IO', 'keys_already_exist', { path });
146
+ }
147
+ const body = canonicalJson({
148
+ createdAt: keys.createdAt,
149
+ format: KEYS_FORMAT,
150
+ vaultId: keys.vaultId,
151
+ vaultKey: toBase64(keys.vaultKey),
152
+ version: KEYS_VERSION,
153
+ });
154
+ try {
155
+ writeFileSync(path, body + '\n', { encoding: 'utf8', flag: 'wx', mode: 0o600 });
156
+ }
157
+ catch (e) {
158
+ const code = e?.code;
159
+ if (code === 'EEXIST') {
160
+ throw err('E_IO', 'keys_already_exist', { path });
161
+ }
162
+ throw err('E_IO', 'keys_write_failed', { path, cause: code ?? null });
163
+ }
164
+ if (process.platform !== 'win32') {
165
+ chmodSync(path, 0o600);
166
+ }
167
+ }
168
+ /**
169
+ * 读取 vault 密钥。目录/文件不存在、JSON 损坏、字段缺失或密钥长度不符 → null
170
+ * (调用方按「缺少 vault 密钥」路径处理,如提示导出过的恢复材料)。
171
+ */
172
+ export function loadKeys(dataDir) {
173
+ const path = join(dataDir, KEYS_FILE);
174
+ if (!existsSync(path)) {
175
+ return null;
176
+ }
177
+ let text;
178
+ try {
179
+ text = readFileSync(path, 'utf8');
180
+ }
181
+ catch {
182
+ return null;
183
+ }
184
+ let obj;
185
+ try {
186
+ obj = JSON.parse(text);
187
+ }
188
+ catch {
189
+ return null;
190
+ }
191
+ if (obj === null || typeof obj !== 'object') {
192
+ return null;
193
+ }
194
+ const rec = obj;
195
+ if (rec['format'] !== KEYS_FORMAT || rec['version'] !== KEYS_VERSION) {
196
+ return null;
197
+ }
198
+ const vaultId = rec['vaultId'];
199
+ const vaultKey = rec['vaultKey'];
200
+ const createdAt = rec['createdAt'];
201
+ if (typeof vaultId !== 'string' || !isUuid(vaultId)) {
202
+ return null;
203
+ }
204
+ if (typeof vaultKey !== 'string' || typeof createdAt !== 'string') {
205
+ return null;
206
+ }
207
+ const keyBytes = decodeBase64Key(vaultKey);
208
+ if (keyBytes === null || Number.isNaN(Date.parse(createdAt))) {
209
+ return null;
210
+ }
211
+ return { vaultId, vaultKey: keyBytes, createdAt };
212
+ }
213
+ /**
214
+ * 导出人类可抄写的恢复材料:`CAIRN1.<base64url(canonicalJson)>`,
215
+ * 规范化 JSON 内含 { createdAt, format, vaultId, vaultKey(base64), version }。
216
+ * 这是密钥明文的编码形态——抄写保存,丢失即远端不可恢复(spec:密钥丢失场景)。
217
+ */
218
+ export function exportRecoveryMaterial(keys) {
219
+ assertVaultKeys(keys);
220
+ const body = canonicalJson({
221
+ createdAt: keys.createdAt,
222
+ format: RECOVERY_FORMAT,
223
+ vaultId: keys.vaultId,
224
+ vaultKey: toBase64(keys.vaultKey),
225
+ version: RECOVERY_VERSION,
226
+ });
227
+ return RECOVERY_PREFIX + Buffer.from(body, 'utf8').toString('base64url');
228
+ }
229
+ /** 恢复材料的逆操作;前缀/编码/字段完整性任一不合法 → E_VALIDATION 'recovery_material_invalid'。 */
230
+ export function importRecoveryMaterial(text) {
231
+ if (typeof text !== 'string') {
232
+ throwRecoveryInvalid();
233
+ }
234
+ const trimmed = text.trim();
235
+ if (!trimmed.startsWith(RECOVERY_PREFIX)) {
236
+ throwRecoveryInvalid();
237
+ }
238
+ const payload = trimmed.slice(RECOVERY_PREFIX.length);
239
+ // base64url 字符集严格校验(Buffer 的 base64 解码是宽容的,需自行把关)。
240
+ if (!/^[A-Za-z0-9_-]+$/.test(payload)) {
241
+ throwRecoveryInvalid();
242
+ }
243
+ let body;
244
+ try {
245
+ body = Buffer.from(payload, 'base64url').toString('utf8');
246
+ }
247
+ catch {
248
+ throwRecoveryInvalid();
249
+ }
250
+ let obj;
251
+ try {
252
+ obj = JSON.parse(body);
253
+ }
254
+ catch {
255
+ throwRecoveryInvalid();
256
+ }
257
+ if (obj === null || typeof obj !== 'object') {
258
+ throwRecoveryInvalid();
259
+ }
260
+ const rec = obj;
261
+ if (rec['format'] !== RECOVERY_FORMAT || rec['version'] !== RECOVERY_VERSION) {
262
+ throwRecoveryInvalid();
263
+ }
264
+ const vaultId = rec['vaultId'];
265
+ const vaultKey = rec['vaultKey'];
266
+ const createdAt = rec['createdAt'];
267
+ if (typeof vaultId !== 'string' || !isUuid(vaultId)) {
268
+ throwRecoveryInvalid();
269
+ }
270
+ if (typeof vaultKey !== 'string' || typeof createdAt !== 'string') {
271
+ throwRecoveryInvalid();
272
+ }
273
+ const keyBytes = decodeBase64Key(vaultKey);
274
+ if (keyBytes === null || Number.isNaN(Date.parse(createdAt))) {
275
+ throwRecoveryInvalid();
276
+ }
277
+ return { vaultId, vaultKey: keyBytes, createdAt };
278
+ }
279
+ // ---------------------------------------------------------------------------
280
+ // 内部辅助
281
+ // ---------------------------------------------------------------------------
282
+ function assertAad(aad) {
283
+ if (aad === null ||
284
+ typeof aad !== 'object' ||
285
+ typeof aad.vaultId !== 'string' ||
286
+ aad.vaultId.length === 0 ||
287
+ typeof aad.spaceId !== 'string' ||
288
+ aad.spaceId.length === 0 ||
289
+ typeof aad.objectId !== 'string' ||
290
+ aad.objectId.length === 0 ||
291
+ (aad.kind !== 'chunk' && aad.kind !== 'manifest')) {
292
+ throw err('E_VALIDATION', 'aad_invalid');
293
+ }
294
+ }
295
+ function assertSpaceKey(spaceKey) {
296
+ if (!(spaceKey instanceof Uint8Array) || spaceKey.length !== KEY_LEN) {
297
+ throw err('E_VALIDATION', 'space_key_invalid_length', {
298
+ expected: KEY_LEN,
299
+ got: spaceKey instanceof Uint8Array ? spaceKey.length : null,
300
+ });
301
+ }
302
+ }
303
+ function assertVaultKeys(keys) {
304
+ if (keys === null ||
305
+ typeof keys !== 'object' ||
306
+ typeof keys.vaultId !== 'string' ||
307
+ !isUuid(keys.vaultId) ||
308
+ !(keys.vaultKey instanceof Uint8Array) ||
309
+ keys.vaultKey.length !== KEY_LEN ||
310
+ typeof keys.createdAt !== 'string' ||
311
+ Number.isNaN(Date.parse(keys.createdAt))) {
312
+ throw err('E_VALIDATION', 'vault_keys_invalid');
313
+ }
314
+ }
315
+ function aadBytes(aad) {
316
+ return textEncoder.encode(`v1|${aad.vaultId}|${aad.spaceId}|${aad.kind}|${aad.objectId}`);
317
+ }
318
+ function toBase64(bytes) {
319
+ return Buffer.from(bytes).toString('base64');
320
+ }
321
+ /**
322
+ * 解码 keys.json / 恢复材料中的 vaultKey(标准 base64,32 字节)。
323
+ * 宽容缺省 padding;长度不符或编码非规范化形态 → null。
324
+ */
325
+ function decodeBase64Key(s) {
326
+ const raw = Buffer.from(s, 'base64');
327
+ if (raw.length !== KEY_LEN) {
328
+ return null;
329
+ }
330
+ const canonical = raw.toString('base64');
331
+ if (s !== canonical && s !== canonical.replace(/=+$/, '')) {
332
+ return null;
333
+ }
334
+ return Uint8Array.from(raw);
335
+ }
336
+ function throwRecoveryInvalid() {
337
+ throw err('E_VALIDATION', 'recovery_material_invalid');
338
+ }
339
+ //# sourceMappingURL=cryptoutil.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cryptoutil.js","sourceRoot":"","sources":["../../../src/sync/cryptoutil.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,69 @@
1
+ import { MemoryKind, Authority, Sensitivity } from '../core/types.js';
2
+ /**
3
+ * 同步事件模型(design D2 / 构想 §10.1):每设备每空间的追加事件链。
4
+ * 修订以【内容哈希链】对账(parentHash = 被替换修订的规范化内容哈希),
5
+ * 因为修订 id 在各设备本地生成、不可跨设备引用。
6
+ */
7
+ export declare const SYNC_EVENT_VERSION = 1;
8
+ export interface SyncUpsertPayload {
9
+ revisionId: string;
10
+ content: string;
11
+ contentHash: string;
12
+ parentHash: string | null;
13
+ kind: MemoryKind;
14
+ authority: Authority;
15
+ scopeId: string;
16
+ sensitivity: Sensitivity;
17
+ confidence: number;
18
+ observedAt: string;
19
+ createdAt: string;
20
+ expiresAt: string | null;
21
+ sourceAgent: string | null;
22
+ createdBy: string;
23
+ reason: string | null;
24
+ }
25
+ export interface SyncTombstonePayload {
26
+ /** 遗忘时的内容哈希(tombstone 行记录)。 */
27
+ lastContentHash: string;
28
+ /** 推送端已知的全部修订内容哈希——跨设备记忆身份对齐(本地 id 不可跨设备引用)。 */
29
+ knownHashes: string[];
30
+ }
31
+ export interface SyncEvent {
32
+ deviceId: string;
33
+ seq: number;
34
+ type: 'memory_upsert' | 'memory_tombstone';
35
+ /** 推送端本地记忆 id;跨设备对账以内容哈希血统为准(见 SyncTombstonePayload)。 */
36
+ memoryId: string;
37
+ occurredAt: string;
38
+ payload: SyncUpsertPayload | SyncTombstonePayload | null;
39
+ }
40
+ /** 打包前校验:内容哈希必须与正文一致(传输完整性内建于事件)。 */
41
+ export declare function validateUpsertEvent(ev: SyncEvent): void;
42
+ export interface ChunkMeta {
43
+ key: string;
44
+ seqFrom: number;
45
+ seqTo: number;
46
+ plaintextSha256: string;
47
+ eventCount: number;
48
+ }
49
+ /** chunk 对象 key(内容寻址:seqFrom + 明文哈希)。 */
50
+ export declare function chunkKey(deviceId: string, seqFrom: number, plaintextSha256: string): string;
51
+ export declare function packChunk(deviceId: string, events: SyncEvent[]): {
52
+ plaintext: Uint8Array;
53
+ meta: ChunkMeta;
54
+ };
55
+ export declare function unpackChunk(plaintext: Uint8Array, deviceId: string, meta: ChunkMeta): SyncEvent[];
56
+ export interface ManifestDoc {
57
+ v: number;
58
+ vaultId: string;
59
+ spaceKey: string;
60
+ deviceId: string;
61
+ generation: number;
62
+ headSeq: number;
63
+ chunks: ChunkMeta[];
64
+ updatedAt: string;
65
+ }
66
+ export declare function emptyManifest(vaultId: string, spaceKey: string, deviceId: string): ManifestDoc;
67
+ /** 新代次校验:headSeq 必须严格推进(单写者自防回退)。 */
68
+ export declare function nextManifest(current: ManifestDoc, addedChunks: ChunkMeta[]): ManifestDoc;
69
+ export declare function manifestKey(deviceId: string): string;
@@ -0,0 +1,78 @@
1
+ import { gzipSync, gunzipSync } from 'node:zlib';
2
+ import { sha256Hex, normalizeContent } from '../core/hash.js';
3
+ import { err } from '../core/errors.js';
4
+ /**
5
+ * 同步事件模型(design D2 / 构想 §10.1):每设备每空间的追加事件链。
6
+ * 修订以【内容哈希链】对账(parentHash = 被替换修订的规范化内容哈希),
7
+ * 因为修订 id 在各设备本地生成、不可跨设备引用。
8
+ */
9
+ export const SYNC_EVENT_VERSION = 1;
10
+ /** 打包前校验:内容哈希必须与正文一致(传输完整性内建于事件)。 */
11
+ export function validateUpsertEvent(ev) {
12
+ if (ev.type !== 'memory_upsert' || !ev.payload || !('content' in ev.payload)) {
13
+ throw err('E_VALIDATION', `事件 ${ev.memoryId}#${ev.seq} 不是 upsert,无法校验内容哈希`);
14
+ }
15
+ const actual = contentHashOf(ev.payload.content);
16
+ if (actual !== ev.payload.contentHash) {
17
+ throw err('E_VALIDATION', `事件 ${ev.memoryId}#${ev.seq} 内容哈希不一致`, {
18
+ expected: ev.payload.contentHash,
19
+ actual,
20
+ });
21
+ }
22
+ }
23
+ function contentHashOf(text) {
24
+ return sha256Hex(normalizeContent(text));
25
+ }
26
+ /** chunk 对象 key(内容寻址:seqFrom + 明文哈希)。 */
27
+ export function chunkKey(deviceId, seqFrom, plaintextSha256) {
28
+ return `devices/${deviceId}/chunks/${seqFrom}-${plaintextSha256}.bin`;
29
+ }
30
+ export function packChunk(deviceId, events) {
31
+ if (events.length === 0)
32
+ throw err('E_VALIDATION', 'chunk 不能为空');
33
+ const seqs = events.map((e) => e.seq);
34
+ const seqFrom = Math.min(...seqs);
35
+ const seqTo = Math.max(...seqs);
36
+ const doc = { v: SYNC_EVENT_VERSION, deviceId, events };
37
+ const json = Buffer.from(JSON.stringify(doc), 'utf8');
38
+ const plaintext = gzipSync(json);
39
+ const plaintextSha256 = sha256Hex(json);
40
+ return { plaintext, meta: { key: chunkKey(deviceId, seqFrom, plaintextSha256), seqFrom, seqTo, plaintextSha256, eventCount: events.length } };
41
+ }
42
+ export function unpackChunk(plaintext, deviceId, meta) {
43
+ const json = gunzipSync(Buffer.from(plaintext));
44
+ const doc = JSON.parse(json.toString('utf8'));
45
+ if (doc.v !== SYNC_EVENT_VERSION)
46
+ throw err('E_VALIDATION', `chunk 版本不兼容: ${doc.v}`);
47
+ if (doc.deviceId !== deviceId)
48
+ throw err('E_VALIDATION', `chunk 设备不匹配: ${doc.deviceId} ≠ ${deviceId}`);
49
+ if (sha256Hex(json) !== meta.plaintextSha256)
50
+ throw err('E_VALIDATION', 'chunk 明文哈希不一致');
51
+ return doc.events;
52
+ }
53
+ export function emptyManifest(vaultId, spaceKey, deviceId) {
54
+ return { v: SYNC_EVENT_VERSION, vaultId, spaceKey, deviceId, generation: 0, headSeq: 0, chunks: [], updatedAt: new Date(0).toISOString() };
55
+ }
56
+ /** 新代次校验:headSeq 必须严格推进(单写者自防回退)。 */
57
+ export function nextManifest(current, addedChunks) {
58
+ if (addedChunks.length === 0)
59
+ throw err('E_VALIDATION', '没有新 chunk 可发布');
60
+ const headSeq = Math.max(current.headSeq, ...addedChunks.map((c) => c.seqTo));
61
+ if (headSeq <= current.headSeq) {
62
+ throw err('E_VALIDATION', `headSeq 不推进:${current.headSeq} → ${headSeq}`);
63
+ }
64
+ return {
65
+ v: SYNC_EVENT_VERSION,
66
+ vaultId: current.vaultId,
67
+ spaceKey: current.spaceKey,
68
+ deviceId: current.deviceId,
69
+ generation: current.generation + 1,
70
+ headSeq,
71
+ chunks: [...current.chunks, ...addedChunks],
72
+ updatedAt: new Date().toISOString(),
73
+ };
74
+ }
75
+ export function manifestKey(deviceId) {
76
+ return `devices/${deviceId}/manifests/manifest.json`;
77
+ }
78
+ //# sourceMappingURL=events.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"events.js","sourceRoot":"","sources":["../../../src/sync/events.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,41 @@
1
+ import type { RemoteStore } from '../jobs/remote.js';
2
+ export interface ObsRemoteConfig {
3
+ /** OBS endpoint,形如 https://obs.cn-east-3.myhuaweicloud.com;也兼容已带桶名的虚拟主机形态。 */
4
+ endpoint: string;
5
+ /** 桶名;既用于拼虚拟主机域名,也用于 CanonicalizedResource 的 /<bucket> 前缀。 */
6
+ bucket: string;
7
+ /** 对象 key 公共前缀(调用方 key 均相对该前缀),如 'cairn/';按原样拼接,不自动补斜杠。 */
8
+ prefix: string;
9
+ accessKeyId: string;
10
+ secretAccessKey: string;
11
+ }
12
+ export interface ObsRemoteStoreOptions {
13
+ /** 默认 globalThis.fetch;测试注入假件即可离线运行,全部 HTTP 都经过该注入点。 */
14
+ fetchImpl?: typeof fetch;
15
+ /** 默认 () => new Date();测试注入固定时钟以锁定 Date 头与签名向量。 */
16
+ now?: () => Date;
17
+ }
18
+ export declare class ObsRemoteStore implements RemoteStore {
19
+ #private;
20
+ readonly configured = true;
21
+ constructor(cfg: ObsRemoteConfig, opts?: ObsRemoteStoreOptions);
22
+ getObject(key: string): Promise<Uint8Array | null>;
23
+ putImmutable(key: string, bytes: Uint8Array, hash: string): Promise<void>;
24
+ list(prefix: string, cursor?: string): Promise<{
25
+ keys: string[];
26
+ nextCursor?: string;
27
+ }>;
28
+ getManifest(space: string, device: string): Promise<Uint8Array | null>;
29
+ putManifest(space: string, device: string, manifest: unknown, expectedGeneration: number): Promise<void>;
30
+ /**
31
+ * 删除对象(内部维护能力,供后续 purge 使用;不放入 RemoteStore 接口)。
32
+ * 404 视为已删除(幂等)。
33
+ */
34
+ deleteObject(key: string): Promise<void>;
35
+ }
36
+ /**
37
+ * 从环境变量构造 ObsRemoteStore:OBS_ENDPOINT / OBS_BUCKET / OBS_PREFIX /
38
+ * OBS_ACCESS_KEY_ID / OBS_SECRET_ACCESS_KEY。任一缺失或为空返回 null(诚实降级,
39
+ * 由调用方落到 NotConfiguredRemote 语义);endpoint 形态非法则抛 E_CONFIG_IO(错误配置应显式暴露)。
40
+ */
41
+ export declare function obsRemoteFromEnv(env?: Record<string, string | undefined>): ObsRemoteStore | null;