@941design/marmot 0.0.0-stage → 0.2.0-alpha.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 (192) hide show
  1. package/CHANGELOG.md +709 -0
  2. package/LICENSE +21 -0
  3. package/README.md +33 -2
  4. package/dist/account/admin.d.ts +72 -0
  5. package/dist/account/admin.js +209 -0
  6. package/dist/account/device-deps.d.ts +379 -0
  7. package/dist/account/device-deps.js +36 -0
  8. package/dist/account/device-lineage.d.ts +199 -0
  9. package/dist/account/device-lineage.js +390 -0
  10. package/dist/account/device-registry.d.ts +93 -0
  11. package/dist/account/device-registry.js +1290 -0
  12. package/dist/account/device-rotation.d.ts +61 -0
  13. package/dist/account/device-rotation.js +827 -0
  14. package/dist/account/enrolment.d.ts +339 -0
  15. package/dist/account/enrolment.js +1247 -0
  16. package/dist/account/identity-proof.d.ts +79 -0
  17. package/dist/account/identity-proof.js +264 -0
  18. package/dist/account/index.d.ts +17 -0
  19. package/dist/account/index.js +16 -0
  20. package/dist/account/restore-rotation.d.ts +21 -0
  21. package/dist/account/restore-rotation.js +22 -0
  22. package/dist/account/same-account-authorization.d.ts +86 -0
  23. package/dist/account/same-account-authorization.js +180 -0
  24. package/dist/account/teardown.d.ts +127 -0
  25. package/dist/account/teardown.js +856 -0
  26. package/dist/client/before-create-group.d.ts +18 -0
  27. package/dist/client/before-create-group.js +65 -0
  28. package/dist/client/before-publish-hooks.d.ts +121 -0
  29. package/dist/client/before-publish-hooks.js +180 -0
  30. package/dist/client/client-config.d.ts +42 -0
  31. package/dist/client/client-config.js +13 -0
  32. package/dist/client/commit-redrive.d.ts +68 -0
  33. package/dist/client/commit-redrive.js +221 -0
  34. package/dist/client/component-update.d.ts +43 -0
  35. package/dist/client/component-update.js +53 -0
  36. package/dist/client/confirm-hooks.d.ts +50 -0
  37. package/dist/client/confirm-hooks.js +59 -0
  38. package/dist/client/create-client.d.ts +1022 -0
  39. package/dist/client/create-client.js +1125 -0
  40. package/dist/client/group-disband.d.ts +28 -0
  41. package/dist/client/group-disband.js +64 -0
  42. package/dist/client/group-history.d.ts +435 -0
  43. package/dist/client/group-history.js +1295 -0
  44. package/dist/client/group-profile.d.ts +31 -0
  45. package/dist/client/group-profile.js +62 -0
  46. package/dist/client/group-records.d.ts +485 -0
  47. package/dist/client/group-records.js +1034 -0
  48. package/dist/client/group-removal.d.ts +36 -0
  49. package/dist/client/group-removal.js +127 -0
  50. package/dist/client/group-remove-member.d.ts +49 -0
  51. package/dist/client/group-remove-member.js +163 -0
  52. package/dist/client/group-runtime.d.ts +388 -0
  53. package/dist/client/group-runtime.js +2701 -0
  54. package/dist/client/group-snapshot.d.ts +98 -0
  55. package/dist/client/group-snapshot.js +453 -0
  56. package/dist/client/history-pages.d.ts +107 -0
  57. package/dist/client/history-pages.js +194 -0
  58. package/dist/client/inbox-send.d.ts +19 -0
  59. package/dist/client/inbox-send.js +71 -0
  60. package/dist/client/index.d.ts +21 -0
  61. package/dist/client/index.js +13 -0
  62. package/dist/client/ingest.d.ts +82 -0
  63. package/dist/client/ingest.js +1550 -0
  64. package/dist/client/lifecycle-events.d.ts +63 -0
  65. package/dist/client/lifecycle-events.js +35 -0
  66. package/dist/client/opaque-candidates.d.ts +81 -0
  67. package/dist/client/opaque-candidates.js +169 -0
  68. package/dist/client/own-change-outbox.d.ts +66 -0
  69. package/dist/client/own-change-outbox.js +156 -0
  70. package/dist/client/pending-leaf.d.ts +116 -0
  71. package/dist/client/pending-leaf.js +378 -0
  72. package/dist/client/permissions.d.ts +9 -0
  73. package/dist/client/permissions.js +12 -0
  74. package/dist/client/pipeline.d.ts +554 -0
  75. package/dist/client/pipeline.js +3545 -0
  76. package/dist/client/reentrancy-guard.d.ts +96 -0
  77. package/dist/client/reentrancy-guard.js +153 -0
  78. package/dist/client/rekey.d.ts +58 -0
  79. package/dist/client/rekey.js +149 -0
  80. package/dist/client/transport-policy.d.ts +181 -0
  81. package/dist/client/transport-policy.js +214 -0
  82. package/dist/history/equivocation.d.ts +55 -0
  83. package/dist/history/equivocation.js +113 -0
  84. package/dist/history/fencing.d.ts +25 -0
  85. package/dist/history/fencing.js +61 -0
  86. package/dist/history/hex.d.ts +3 -0
  87. package/dist/history/hex.js +10 -0
  88. package/dist/history/index.d.ts +73 -0
  89. package/dist/history/index.js +31 -0
  90. package/dist/history/notifications.d.ts +270 -0
  91. package/dist/history/notifications.js +264 -0
  92. package/dist/history/ordering-key.d.ts +24 -0
  93. package/dist/history/ordering-key.js +101 -0
  94. package/dist/history/own-change-fork.d.ts +112 -0
  95. package/dist/history/own-change-fork.js +196 -0
  96. package/dist/history/own-change.d.ts +106 -0
  97. package/dist/history/own-change.js +146 -0
  98. package/dist/history/policy.d.ts +48 -0
  99. package/dist/history/policy.js +52 -0
  100. package/dist/history/retained-window.d.ts +215 -0
  101. package/dist/history/retained-window.js +565 -0
  102. package/dist/inbox/demux.d.ts +90 -0
  103. package/dist/inbox/demux.js +78 -0
  104. package/dist/inbox/handler-registry.d.ts +42 -0
  105. package/dist/inbox/handler-registry.js +37 -0
  106. package/dist/inbox/index.d.ts +11 -0
  107. package/dist/inbox/index.js +10 -0
  108. package/dist/inbox/seen-set.d.ts +82 -0
  109. package/dist/inbox/seen-set.js +202 -0
  110. package/dist/inbox/subscription.d.ts +236 -0
  111. package/dist/inbox/subscription.js +644 -0
  112. package/dist/index.d.ts +10 -0
  113. package/dist/index.js +9 -0
  114. package/dist/invitations/competing-welcome.d.ts +223 -0
  115. package/dist/invitations/competing-welcome.js +128 -0
  116. package/dist/invitations/decline.d.ts +61 -0
  117. package/dist/invitations/decline.js +143 -0
  118. package/dist/invitations/expect-welcome.d.ts +66 -0
  119. package/dist/invitations/expect-welcome.js +138 -0
  120. package/dist/invitations/index.d.ts +16 -0
  121. package/dist/invitations/index.js +16 -0
  122. package/dist/invitations/invite.d.ts +303 -0
  123. package/dist/invitations/invite.js +966 -0
  124. package/dist/invitations/offers.d.ts +79 -0
  125. package/dist/invitations/offers.js +115 -0
  126. package/dist/invitations/on-proposal.d.ts +47 -0
  127. package/dist/invitations/on-proposal.js +40 -0
  128. package/dist/invitations/pending-proposal-policy.d.ts +52 -0
  129. package/dist/invitations/pending-proposal-policy.js +139 -0
  130. package/dist/invitations/proposal-deadline.d.ts +133 -0
  131. package/dist/invitations/proposal-deadline.js +164 -0
  132. package/dist/invitations/relay-planes.d.ts +43 -0
  133. package/dist/invitations/relay-planes.js +70 -0
  134. package/dist/invitations/welcome-processor.d.ts +253 -0
  135. package/dist/invitations/welcome-processor.js +1180 -0
  136. package/dist/key-packages/device-key.d.ts +131 -0
  137. package/dist/key-packages/device-key.js +272 -0
  138. package/dist/key-packages/device-rotation-records.d.ts +83 -0
  139. package/dist/key-packages/device-rotation-records.js +173 -0
  140. package/dist/key-packages/group-refs.d.ts +40 -0
  141. package/dist/key-packages/group-refs.js +79 -0
  142. package/dist/key-packages/index.d.ts +18 -0
  143. package/dist/key-packages/index.js +18 -0
  144. package/dist/key-packages/key-package-ref.d.ts +16 -0
  145. package/dist/key-packages/key-package-ref.js +21 -0
  146. package/dist/key-packages/observation-stream.d.ts +4 -0
  147. package/dist/key-packages/observation-stream.js +120 -0
  148. package/dist/key-packages/offer-rumor.d.ts +26 -0
  149. package/dist/key-packages/offer-rumor.js +69 -0
  150. package/dist/key-packages/publisher.d.ts +174 -0
  151. package/dist/key-packages/publisher.js +1247 -0
  152. package/dist/key-packages/select-key-package.d.ts +24 -0
  153. package/dist/key-packages/select-key-package.js +90 -0
  154. package/dist/key-packages/slot-manager.d.ts +167 -0
  155. package/dist/key-packages/slot-manager.js +327 -0
  156. package/dist/key-packages/validate-key-package-event.d.ts +3 -0
  157. package/dist/key-packages/validate-key-package-event.js +49 -0
  158. package/dist/media/cache.d.ts +14 -0
  159. package/dist/media/cache.js +10 -0
  160. package/dist/media/index.d.ts +52 -0
  161. package/dist/media/index.js +71 -0
  162. package/dist/mls.d.ts +15 -0
  163. package/dist/mls.js +15 -0
  164. package/dist/shared/account-pubkey.d.ts +4 -0
  165. package/dist/shared/account-pubkey.js +10 -0
  166. package/dist/shared/errors.d.ts +21 -0
  167. package/dist/shared/errors.js +85 -0
  168. package/dist/shared/hex.d.ts +4 -0
  169. package/dist/shared/hex.js +13 -0
  170. package/dist/shared/index.d.ts +14 -0
  171. package/dist/shared/index.js +14 -0
  172. package/dist/shared/kinds.d.ts +8 -0
  173. package/dist/shared/kinds.js +28 -0
  174. package/dist/shared/publish-classification.d.ts +26 -0
  175. package/dist/shared/publish-classification.js +31 -0
  176. package/dist/storage/envelope.d.ts +39 -0
  177. package/dist/storage/envelope.js +201 -0
  178. package/dist/storage/index.d.ts +227 -0
  179. package/dist/storage/index.js +459 -0
  180. package/dist/storage/indexeddb/idb-types.d.ts +68 -0
  181. package/dist/storage/indexeddb/idb-types.js +1 -0
  182. package/dist/storage/indexeddb/index.d.ts +17 -0
  183. package/dist/storage/indexeddb/index.js +141 -0
  184. package/dist/storage/lease.d.ts +41 -0
  185. package/dist/storage/lease.js +117 -0
  186. package/dist/storage/memory/deterministic-signer.d.ts +27 -0
  187. package/dist/storage/memory/deterministic-signer.js +65 -0
  188. package/dist/storage/memory/index.d.ts +32 -0
  189. package/dist/storage/memory/index.js +87 -0
  190. package/dist/storage/memory/lock-manager.d.ts +8 -0
  191. package/dist/storage/memory/lock-manager.js +71 -0
  192. package/package.json +66 -3
@@ -0,0 +1,201 @@
1
+ /**
2
+ * Versioned envelope codec (ADR-007 §3, AC-STORE-2).
3
+ *
4
+ * Every artifact a store persists is an envelope
5
+ * `{ v, engine, tsMls, payload }`: `engine` and `tsMls` stamp the
6
+ * `marmot-engine` that wrote it — `ENGINE_VERSION`, its stored-state format
7
+ * (`state.<N>`, not the code build; ADR-007 amendment 2026-11-09), and
8
+ * `TS_MLS_PIN` — and `payload` is the value's encoded text.
9
+ * `openEnvelope` compares the stamp BEFORE it touches `payload`, so an
10
+ * artifact written under another state format or ts-mls build is refused without
11
+ * being decoded — a stale serialized `ClientState` never reaches the engine.
12
+ *
13
+ * The payload encoding is JSON extended with three tags so the values the
14
+ * client persists round-trip exactly: `bigint` (epochs), `Uint8Array`
15
+ * (serialized MLS state, keys) and `-0`. Object keys that start with `$` are
16
+ * escaped with one more `$`, so no application value can forge a tag.
17
+ */
18
+ import { ENGINE_VERSION, TS_MLS_PIN } from '@941design/marmot-engine/version';
19
+ import { MarmotError } from '../shared/index.js';
20
+ export const ENVELOPE_FORMAT = 1;
21
+ export const CURRENT_CODEC_VERSIONS = Object.freeze({ engine: ENGINE_VERSION, tsMls: TS_MLS_PIN });
22
+ // ---------------------------------------------------------------------------
23
+ // Payload encoding
24
+ // ---------------------------------------------------------------------------
25
+ const TAG_BIGINT = '$bigint';
26
+ const TAG_BYTES = '$bytes';
27
+ const TAG_NEGZERO = '$negzero';
28
+ const TAGS = new Set([TAG_BIGINT, TAG_BYTES, TAG_NEGZERO]);
29
+ function invalidValue(message) {
30
+ return new MarmotError('invalid-options', `store value: ${message}`);
31
+ }
32
+ function isPlainObject(value) {
33
+ const proto = Object.getPrototypeOf(value);
34
+ return proto === Object.prototype || proto === null;
35
+ }
36
+ /**
37
+ * Sets an own data property. Plain assignment would treat a `__proto__` key
38
+ * as the prototype setter (dropping the member, or swapping the prototype);
39
+ * a stored value must round-trip every own key it had.
40
+ */
41
+ function defineMember(target, key, value) {
42
+ Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
43
+ }
44
+ function toJson(value, ancestors) {
45
+ switch (typeof value) {
46
+ case 'string':
47
+ case 'boolean':
48
+ return value;
49
+ case 'number':
50
+ if (!Number.isFinite(value))
51
+ throw invalidValue(`non-finite number ${String(value)}`);
52
+ return Object.is(value, -0) ? { [TAG_NEGZERO]: true } : value;
53
+ case 'bigint':
54
+ return { [TAG_BIGINT]: value.toString() };
55
+ case 'object': {
56
+ if (value === null)
57
+ return null;
58
+ if (value instanceof Uint8Array)
59
+ return { [TAG_BYTES]: toHex(value) };
60
+ if (ancestors.has(value))
61
+ throw invalidValue('cyclic structure');
62
+ ancestors.add(value);
63
+ try {
64
+ if (Array.isArray(value)) {
65
+ // Indexed loop, not map(): map() skips holes, which JSON would then turn into null.
66
+ const items = [];
67
+ for (let i = 0; i < value.length; i++) {
68
+ if (!(i in value))
69
+ throw invalidValue('sparse array element');
70
+ const item = value[i];
71
+ if (item === undefined)
72
+ throw invalidValue('undefined array element');
73
+ items.push(toJson(item, ancestors));
74
+ }
75
+ return items;
76
+ }
77
+ if (!isPlainObject(value))
78
+ throw invalidValue(`unsupported object type ${value.constructor?.name ?? 'unknown'}`);
79
+ const out = {};
80
+ for (const [key, member] of Object.entries(value)) {
81
+ if (member === undefined)
82
+ continue;
83
+ defineMember(out, key.startsWith('$') ? `$${key}` : key, toJson(member, ancestors));
84
+ }
85
+ return out;
86
+ }
87
+ finally {
88
+ ancestors.delete(value);
89
+ }
90
+ }
91
+ default:
92
+ throw invalidValue(`unsupported type ${typeof value}`);
93
+ }
94
+ }
95
+ function fromJson(json) {
96
+ if (json === null || typeof json !== 'object')
97
+ return json;
98
+ if (Array.isArray(json))
99
+ return json.map(fromJson);
100
+ const keys = Object.keys(json);
101
+ if (keys.length === 1 && TAGS.has(keys[0])) {
102
+ const tag = keys[0];
103
+ const body = json[tag];
104
+ if (tag === TAG_BIGINT && typeof body === 'string' && /^-?\d+$/.test(body))
105
+ return BigInt(body);
106
+ if (tag === TAG_BYTES && typeof body === 'string')
107
+ return fromHex(body);
108
+ if (tag === TAG_NEGZERO && body === true)
109
+ return -0;
110
+ throw new SyntaxError(`malformed ${tag} tag`);
111
+ }
112
+ const out = {};
113
+ for (const key of keys) {
114
+ // Escaped keys start with `$$`; a single `$` outside a tag object is never written.
115
+ if (key.startsWith('$') && !key.startsWith('$$'))
116
+ throw new SyntaxError(`unescaped key ${key}`);
117
+ defineMember(out, key.startsWith('$') ? key.slice(1) : key, fromJson(json[key]));
118
+ }
119
+ return out;
120
+ }
121
+ /** Encodes a value to payload text. Throws `invalid-options` for a value outside {@link Storable}. */
122
+ export function encodePayload(value) {
123
+ if (value === undefined)
124
+ throw invalidValue('undefined');
125
+ return JSON.stringify(toJson(value, new Set()));
126
+ }
127
+ /** Decodes payload text written by {@link encodePayload}. Throws `SyntaxError` on malformed text. */
128
+ export function decodePayload(payload) {
129
+ return fromJson(JSON.parse(payload));
130
+ }
131
+ const HEX = '0123456789abcdef';
132
+ function toHex(bytes) {
133
+ let out = '';
134
+ for (const b of bytes)
135
+ out += HEX[b >> 4] + HEX[b & 15];
136
+ return out;
137
+ }
138
+ function fromHex(hex) {
139
+ if (hex.length % 2 !== 0 || !/^[0-9a-f]*$/.test(hex))
140
+ throw new SyntaxError('malformed hex');
141
+ const out = new Uint8Array(hex.length / 2);
142
+ for (let i = 0; i < out.length; i++)
143
+ out[i] = parseInt(hex.slice(2 * i, 2 * i + 2), 16);
144
+ return out;
145
+ }
146
+ // ---------------------------------------------------------------------------
147
+ // Envelopes
148
+ // ---------------------------------------------------------------------------
149
+ /** Wraps a value for storage, stamped with `versions` (default: this build). */
150
+ export function sealEnvelope(value, versions = CURRENT_CODEC_VERSIONS) {
151
+ return Object.freeze({ v: ENVELOPE_FORMAT, engine: versions.engine, tsMls: versions.tsMls, payload: encodePayload(value) });
152
+ }
153
+ function mismatch(key, reason, message, extra = {}, cause) {
154
+ return new MarmotError('envelope-mismatch', `stored artifact ${key}: ${message}`, {
155
+ ...(cause === undefined ? {} : { cause }),
156
+ details: { key, reason, ...extra },
157
+ });
158
+ }
159
+ function isEnvelopeShape(raw) {
160
+ if (typeof raw !== 'object' || raw === null)
161
+ return false;
162
+ const r = raw;
163
+ return r['v'] === ENVELOPE_FORMAT && typeof r['engine'] === 'string' && typeof r['tsMls'] === 'string' && typeof r['payload'] === 'string';
164
+ }
165
+ /**
166
+ * Checks a stored envelope's stamp against `versions` and only then decodes
167
+ * its payload. Throws `envelope-mismatch` with `details.reason`:
168
+ * `'version'` when the stamp differs (payload never decoded), `'malformed'`
169
+ * when the record is not a well-formed envelope or its payload does not decode.
170
+ */
171
+ export function openEnvelope(key, raw, versions = CURRENT_CODEC_VERSIONS) {
172
+ if (!isEnvelopeShape(raw))
173
+ throw mismatch(key, 'malformed', 'not a v1 envelope');
174
+ if (raw.engine !== versions.engine || raw.tsMls !== versions.tsMls) {
175
+ throw mismatch(key, 'version', `written by engine ${raw.engine} / ts-mls ${raw.tsMls}, this build is engine ${versions.engine} / ts-mls ${versions.tsMls}`, {
176
+ found: { engine: raw.engine, tsMls: raw.tsMls },
177
+ expected: { engine: versions.engine, tsMls: versions.tsMls },
178
+ });
179
+ }
180
+ try {
181
+ return decodePayload(raw.payload);
182
+ }
183
+ catch (err) {
184
+ throw mismatch(key, 'malformed', 'payload does not decode', {}, err);
185
+ }
186
+ }
187
+ /**
188
+ * Reads an envelope WITHOUT the stamp check. Only for the wipe marker, whose
189
+ * whole purpose is to be readable by a later build (it records which build
190
+ * wiped); its payload schema is frozen at `{ at, reason }`.
191
+ */
192
+ export function openEnvelopeUnchecked(key, raw) {
193
+ if (!isEnvelopeShape(raw))
194
+ throw mismatch(key, 'malformed', 'not a v1 envelope');
195
+ try {
196
+ return { stamp: { engine: raw.engine, tsMls: raw.tsMls }, value: decodePayload(raw.payload) };
197
+ }
198
+ catch (err) {
199
+ throw mismatch(key, 'malformed', 'payload does not decode', {}, err);
200
+ }
201
+ }
@@ -0,0 +1,227 @@
1
+ /**
2
+ * `@941design/marmot/storage` — the ADR-007 storage contract.
3
+ *
4
+ * Two scopes: a {@link GroupStore} per group and an {@link AccountStore} per
5
+ * account, each with `transaction(fn)`. A transaction is a buffered unit of
6
+ * work: reads go to the backend (seeing the transaction's own writes first),
7
+ * writes are buffered, and when `fn` settles the buffer is flushed in ONE
8
+ * backend transaction — or dropped if `fn` threw. `fn` may therefore await
9
+ * anything (a `Signer.nip44` call, a relay round-trip); an IndexedDB
10
+ * transaction would auto-commit across such an await, a buffer does not
11
+ * (AC-STORE-1).
12
+ *
13
+ * Every value is persisted inside a versioned envelope (./envelope.ts); a
14
+ * read of an envelope stamped with another engine state format (or ts-mls pin) rejects
15
+ * `envelope-mismatch` and is reported to `onIncompatible` listeners
16
+ * (AC-STORE-2). Stores are only obtainable through a lease (./lease.ts,
17
+ * AC-STORE-3). Backends plug in as a {@link StorageDriver}; the reference
18
+ * ones live on the `storage/indexeddb` and `storage/memory` subpaths, and
19
+ * this module never imports them (AC-STORE-7).
20
+ *
21
+ * Re-entrancy rule (DD13 / ADR-013). Inside `fn`, use the `tx` view — never
22
+ * the store itself. A same-scope store-level write (`transaction()`,
23
+ * `artifact(x)/extension(id).put/delete()`, `AccountStore.wipe()`) made
24
+ * while `fn`'s synchronous part runs — the call to `fn` itself, up to its
25
+ * first `await` — rejects `reentrant` without queueing: JavaScript is
26
+ * single-threaded, so such a call can only come from `fn` or a callee of
27
+ * it, and queueing it behind the running transaction would deadlock the
28
+ * scope. After `fn` has awaited, a same-scope store-level write cannot be
29
+ * told apart from an independent concurrent caller (the platform has no
30
+ * portable async context), and rejecting every write that overlaps a
31
+ * running transaction would make independent callers on one scope fail
32
+ * depending on timing; so it queues behind the running transaction as any
33
+ * concurrent write does. Awaiting such a call from inside `fn` therefore
34
+ * never settles — a caller bug the `tx` view exists to avoid. Store-level
35
+ * reads never queue and are always allowed. Other scopes (another group,
36
+ * the account store from a group transaction) are unaffected.
37
+ *
38
+ * Cross-scope lock order. Scopes are totally ordered group → account. From
39
+ * inside a transaction's `fn`, code may `await` a transaction or a
40
+ * store-level write on a scope LATER in that order than the scope `fn` is
41
+ * running on (a group transaction awaiting an account-store write) — but
42
+ * never on a scope EARLIER in the order (an account transaction must never
43
+ * await a group-store write). This is a documentation-only convention for
44
+ * now; this module does not detect or enforce it. The order exists to rule
45
+ * out a cross-scope deadlock cycle: suppose a group transaction's `fn`
46
+ * awaited a write on the account store (the allowed direction) while, on
47
+ * that account store, a transaction queued ahead of it in turn awaited a
48
+ * store-level write on that same group (the forbidden direction). Each
49
+ * side would then be waiting on a queue only the other side's completion
50
+ * can drain — the group transaction can't finish until its account-store
51
+ * await settles, and that queued account transaction can't even start
52
+ * until the group scope is free — so neither queue ever advances. Holding
53
+ * every await to the group → account direction and never the reverse means
54
+ * no scope ever waits, even transitively, on a scope earlier in the order,
55
+ * which breaks the cycle by construction.
56
+ *
57
+ * Commit gate. A driver guarantees each commit is atomic, not that commits
58
+ * complete in the order they were issued. So the flush — the only step that
59
+ * calls `driver.commit` — is serialised across the whole account (every
60
+ * scope of one handle) by one commit gate, and the lease and wipe
61
+ * generation are re-checked inside the gate immediately before the commit:
62
+ * a group write can therefore never land after a wipe it began before. Only
63
+ * the flush enters the gate, never `fn`, and a gated flush awaits nothing
64
+ * but `driver.commit`, so the gate is the innermost lock of the group →
65
+ * account order and cannot close a cycle. `close()` stops accepting work,
66
+ * waits for the gate to drain (a flush already queued there rejects
67
+ * `no-lease` unapplied), and only then releases the lease, so no write of a
68
+ * closed handle lands after another handle holds the lease.
69
+ */
70
+ import { MarmotError } from '../shared/index.js';
71
+ import { type CodecVersions, type Envelope, type Storable } from './envelope.js';
72
+ import { type Lease, type LockManagerLike } from './lease.js';
73
+ export { CURRENT_CODEC_VERSIONS, ENVELOPE_FORMAT, decodePayload, encodePayload, openEnvelope, sealEnvelope, type CodecVersions, type Envelope, type Storable, } from './envelope.js';
74
+ export { DEFAULT_LEASE_TIMEOUT_MS, acquireLease, defaultLockManager, type Lease, type LockLike, type LockManagerLike, type LockRequestOptions, } from './lease.js';
75
+ export declare const GROUP_ARTIFACTS: readonly ["clientState", "ingestCursor", "terminalLedger", "rewindTree", "removalMarker", "pendingIntents", "queuedRumors", "leafBackup", "retainedHistory"];
76
+ export declare const ACCOUNT_ARTIFACTS: readonly ["keyPackages", "keyPackageGroupRefs", "invites", "pendingInvitations", "enrolmentManifests", "enrolmentSessions", "deviceRegistry", "inboxSeenSet", "syncKeyVersions", "wipeMarker"];
77
+ export type GroupArtifact = (typeof GROUP_ARTIFACTS)[number];
78
+ export type AccountArtifact = (typeof ACCOUNT_ARTIFACTS)[number];
79
+ /** Object-store / bucket name holding every `extension(id)` view (the `extension/*` artifact). */
80
+ export declare const EXTENSION_BUCKET = "extension";
81
+ /** Every bucket a backend must provide: both artifact lists plus {@link EXTENSION_BUCKET}. */
82
+ export declare const ALL_BUCKETS: readonly string[];
83
+ /** The key the wipe marker lives under in the `wipeMarker` artifact. */
84
+ export declare const WIPE_MARKER_KEY = "current";
85
+ /**
86
+ * A key-value view over one artifact or one extension namespace. Inside a
87
+ * transaction, `put`/`delete` are buffered synchronously at call time (so an
88
+ * un-awaited call still belongs to the transaction) and reads see them.
89
+ * Outside a transaction, each `put`/`delete` is its own transaction.
90
+ */
91
+ export interface KeyValueView {
92
+ get(key: string): Promise<Storable | undefined>;
93
+ put(key: string, value: Storable): Promise<void>;
94
+ delete(key: string): Promise<void>;
95
+ /** Keys present, sorted by UTF-16 code unit order. */
96
+ keys(): Promise<string[]>;
97
+ }
98
+ export interface IncompatibleEvent {
99
+ /** Artifact key, e.g. `group:<id>/clientState/<key>` or `account:<pubkey>/extension/<id>/<key>`. */
100
+ readonly key: string;
101
+ /** Always code `envelope-mismatch`. */
102
+ readonly error: MarmotError;
103
+ }
104
+ export type IncompatibleListener = (event: IncompatibleEvent) => void;
105
+ export interface StoreScope<A extends string> {
106
+ artifact(name: A): KeyValueView;
107
+ /** Namespaced view for one extension id (the `extension/*` artifact); ids never see each other's keys. */
108
+ extension(id: string): KeyValueView;
109
+ }
110
+ export type GroupStoreTx = StoreScope<GroupArtifact>;
111
+ export type AccountStoreTx = StoreScope<AccountArtifact>;
112
+ export interface GroupStore extends StoreScope<GroupArtifact> {
113
+ readonly groupId: string;
114
+ /**
115
+ * Runs `fn` as one atomic unit of work; see the module comment. Transactions on one store run one at a time.
116
+ * A same-store write issued while `fn` runs synchronously rejects `reentrant` (module comment: re-entrancy rule).
117
+ */
118
+ transaction<T>(fn: (tx: GroupStoreTx) => Promise<T> | T): Promise<T>;
119
+ /** Called (before the read rejects) whenever a read meets an envelope from another engine state format or ts-mls pin. */
120
+ onIncompatible(listener: IncompatibleListener): () => void;
121
+ /**
122
+ * Deletes everything stored for this group — every artifact AND every
123
+ * `extension(id)` namespace, whatever ids were written — in ONE backend
124
+ * transaction (S9 teardown, AC-ADMIN-5). Other groups and the account are
125
+ * untouched. Queued like a transaction; a same-store call from inside a
126
+ * running transaction's `fn` rejects `reentrant`.
127
+ */
128
+ clear(): Promise<void>;
129
+ }
130
+ export type WipeReason = 'incompatible' | 'application';
131
+ export interface WipeMarker {
132
+ /** `ENGINE_VERSION` (the engine state format) of the build that performed the wipe. */
133
+ readonly engine: string;
134
+ /** `TS_MLS_PIN` of the build that performed the wipe. */
135
+ readonly tsMls: string;
136
+ readonly at: number;
137
+ /** `'incompatible'` after an engine/ts-mls change, `'application'` for an explicit application wipe. */
138
+ readonly reason: WipeReason;
139
+ }
140
+ export interface AccountStore extends StoreScope<AccountArtifact> {
141
+ /** Account pubkey (64 lowercase hex); every key of this store is namespaced by it. */
142
+ readonly account: string;
143
+ transaction<T>(fn: (tx: AccountStoreTx) => Promise<T> | T): Promise<T>;
144
+ /**
145
+ * Deletes everything stored for this account — its artifacts, every group's
146
+ * artifacts and all extensions — and records a {@link WipeMarker} in the
147
+ * same backend transaction (ADR-001: the application wipes by marker).
148
+ */
149
+ wipe(opts: {
150
+ readonly reason: WipeReason;
151
+ }): Promise<WipeMarker>;
152
+ /** The last wipe's marker, readable whatever build wrote it. */
153
+ wipeMarker(): Promise<WipeMarker | undefined>;
154
+ onIncompatible(listener: IncompatibleListener): () => void;
155
+ }
156
+ /** What `openForWrite` yields; `{ account, groupFactory }` is `createMarmotClient`'s `stores` option. */
157
+ export interface WritableStores {
158
+ readonly account: AccountStore;
159
+ /** Same `GroupStore` object for the same id within one `WritableStores`. */
160
+ readonly groupFactory: (groupId: string) => GroupStore;
161
+ readonly lease: Lease;
162
+ /** Stops accepting writes (they reject `no-lease`), waits for a commit already in progress, then releases the lease. Idempotent. */
163
+ close(): Promise<void>;
164
+ }
165
+ export interface OpenOptions {
166
+ /** How long to wait for the lease before rejecting `lease-held`. Defaults to the backend's. */
167
+ readonly leaseTimeoutMs?: number;
168
+ }
169
+ export interface StorageBackend {
170
+ /** Acquires the (backend instance, account) lease; rejects `lease-held` after `leaseTimeoutMs`. */
171
+ acquireLease(account: string, opts?: OpenOptions): Promise<Lease>;
172
+ /** Opens the stores for writing under `lease`; throws `no-lease` unless it is a live lease this backend issued for `account`. */
173
+ open(account: string, lease: Lease): WritableStores;
174
+ /** `acquireLease` + `open`. */
175
+ openForWrite(account: string, opts?: OpenOptions): Promise<WritableStores>;
176
+ }
177
+ /**
178
+ * A row address: `bucket` is an artifact name or {@link EXTENSION_BUCKET};
179
+ * `path` is `[scope, key]` for artifacts and `[scope, extensionId, key]` for
180
+ * extensions, where scope is `'account'` or `'group:<groupId>'`.
181
+ */
182
+ export type StorageWrite = {
183
+ readonly type: 'put';
184
+ readonly bucket: string;
185
+ readonly path: readonly string[];
186
+ readonly envelope: Envelope;
187
+ } | {
188
+ readonly type: 'delete';
189
+ readonly bucket: string;
190
+ readonly path: readonly string[];
191
+ }
192
+ /** Removes every row of the account, in every bucket. Always first in a write list. */
193
+ | {
194
+ readonly type: 'clear';
195
+ }
196
+ /**
197
+ * Removes every row, in every bucket, whose path starts with `scope`
198
+ * (`'group:<groupId>'`): the scope's artifacts and all its extension
199
+ * namespaces. Always first in a write list.
200
+ */
201
+ | {
202
+ readonly type: 'clearScope';
203
+ readonly scope: string;
204
+ };
205
+ /** The per-platform part of a backend. Every account is its own namespace. */
206
+ export interface StorageDriver {
207
+ readonly locks: LockManagerLike;
208
+ /** Lock name of the account's lease. */
209
+ lockName(account: string): string;
210
+ /** The stored record at `path` (unvalidated), or `undefined`. */
211
+ read(account: string, bucket: string, path: readonly string[]): Promise<unknown>;
212
+ /** The last path component of every row whose path is `prefix` plus one component. */
213
+ keys(account: string, bucket: string, prefix: readonly string[]): Promise<string[]>;
214
+ /** Applies all writes in ONE backend transaction: all or none. */
215
+ commit(account: string, writes: readonly StorageWrite[]): Promise<void>;
216
+ }
217
+ export interface BackendOptions {
218
+ readonly leaseTimeoutMs?: number;
219
+ /** Stamp written into and required of envelopes. Defaults to this build; override only to simulate another build. */
220
+ readonly codecVersions?: CodecVersions;
221
+ /** Clock for the wipe marker's `at`. Defaults to `Date.now`. */
222
+ readonly clock?: {
223
+ now(): number;
224
+ };
225
+ }
226
+ /** Builds a {@link StorageBackend} over a driver — how the reference backends, and any consumer backend, are made. */
227
+ export declare function createStorageBackend(driver: StorageDriver, options?: BackendOptions): StorageBackend;