@941design/marmot 0.0.0-stage → 0.2.0-alpha.1

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 (206) hide show
  1. package/CHANGELOG.md +739 -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 +190 -0
  25. package/dist/account/teardown.js +878 -0
  26. package/dist/client/admission-cleanup.d.ts +197 -0
  27. package/dist/client/admission-cleanup.js +635 -0
  28. package/dist/client/adoption-proof.d.ts +39 -0
  29. package/dist/client/adoption-proof.js +102 -0
  30. package/dist/client/before-create-group.d.ts +18 -0
  31. package/dist/client/before-create-group.js +65 -0
  32. package/dist/client/before-publish-hooks.d.ts +121 -0
  33. package/dist/client/before-publish-hooks.js +182 -0
  34. package/dist/client/client-config.d.ts +42 -0
  35. package/dist/client/client-config.js +13 -0
  36. package/dist/client/commit-redrive.d.ts +92 -0
  37. package/dist/client/commit-redrive.js +274 -0
  38. package/dist/client/component-update.d.ts +43 -0
  39. package/dist/client/component-update.js +53 -0
  40. package/dist/client/confirm-hooks.d.ts +55 -0
  41. package/dist/client/confirm-hooks.js +74 -0
  42. package/dist/client/create-client.d.ts +1126 -0
  43. package/dist/client/create-client.js +1232 -0
  44. package/dist/client/group-availability.d.ts +182 -0
  45. package/dist/client/group-availability.js +301 -0
  46. package/dist/client/group-disband.d.ts +28 -0
  47. package/dist/client/group-disband.js +64 -0
  48. package/dist/client/group-history.d.ts +461 -0
  49. package/dist/client/group-history.js +1365 -0
  50. package/dist/client/group-profile.d.ts +31 -0
  51. package/dist/client/group-profile.js +62 -0
  52. package/dist/client/group-records.d.ts +522 -0
  53. package/dist/client/group-records.js +1117 -0
  54. package/dist/client/group-removal.d.ts +36 -0
  55. package/dist/client/group-removal.js +127 -0
  56. package/dist/client/group-remove-member.d.ts +49 -0
  57. package/dist/client/group-remove-member.js +163 -0
  58. package/dist/client/group-runtime.d.ts +415 -0
  59. package/dist/client/group-runtime.js +2811 -0
  60. package/dist/client/group-snapshot.d.ts +104 -0
  61. package/dist/client/group-snapshot.js +474 -0
  62. package/dist/client/history-pages.d.ts +107 -0
  63. package/dist/client/history-pages.js +194 -0
  64. package/dist/client/inbox-send.d.ts +19 -0
  65. package/dist/client/inbox-send.js +71 -0
  66. package/dist/client/index.d.ts +24 -0
  67. package/dist/client/index.js +13 -0
  68. package/dist/client/ingest.d.ts +82 -0
  69. package/dist/client/ingest.js +1584 -0
  70. package/dist/client/invitation-outcomes.d.ts +50 -0
  71. package/dist/client/invitation-outcomes.js +135 -0
  72. package/dist/client/lifecycle-events.d.ts +63 -0
  73. package/dist/client/lifecycle-events.js +35 -0
  74. package/dist/client/opaque-candidates.d.ts +82 -0
  75. package/dist/client/opaque-candidates.js +170 -0
  76. package/dist/client/own-change-outbox.d.ts +66 -0
  77. package/dist/client/own-change-outbox.js +158 -0
  78. package/dist/client/pending-leaf.d.ts +116 -0
  79. package/dist/client/pending-leaf.js +378 -0
  80. package/dist/client/permissions.d.ts +9 -0
  81. package/dist/client/permissions.js +12 -0
  82. package/dist/client/pipeline.d.ts +583 -0
  83. package/dist/client/pipeline.js +3666 -0
  84. package/dist/client/reentrancy-guard.d.ts +102 -0
  85. package/dist/client/reentrancy-guard.js +159 -0
  86. package/dist/client/rekey.d.ts +58 -0
  87. package/dist/client/rekey.js +149 -0
  88. package/dist/client/transport-policy.d.ts +181 -0
  89. package/dist/client/transport-policy.js +214 -0
  90. package/dist/history/admission-lineage.d.ts +186 -0
  91. package/dist/history/admission-lineage.js +589 -0
  92. package/dist/history/equivocation.d.ts +55 -0
  93. package/dist/history/equivocation.js +113 -0
  94. package/dist/history/fencing.d.ts +66 -0
  95. package/dist/history/fencing.js +121 -0
  96. package/dist/history/hex.d.ts +3 -0
  97. package/dist/history/hex.js +10 -0
  98. package/dist/history/index.d.ts +74 -0
  99. package/dist/history/index.js +32 -0
  100. package/dist/history/notifications.d.ts +270 -0
  101. package/dist/history/notifications.js +264 -0
  102. package/dist/history/ordering-key.d.ts +24 -0
  103. package/dist/history/ordering-key.js +101 -0
  104. package/dist/history/own-change-fork.d.ts +112 -0
  105. package/dist/history/own-change-fork.js +196 -0
  106. package/dist/history/own-change.d.ts +118 -0
  107. package/dist/history/own-change.js +146 -0
  108. package/dist/history/policy.d.ts +48 -0
  109. package/dist/history/policy.js +52 -0
  110. package/dist/history/retained-window.d.ts +215 -0
  111. package/dist/history/retained-window.js +565 -0
  112. package/dist/inbox/demux.d.ts +90 -0
  113. package/dist/inbox/demux.js +78 -0
  114. package/dist/inbox/handler-registry.d.ts +42 -0
  115. package/dist/inbox/handler-registry.js +37 -0
  116. package/dist/inbox/index.d.ts +11 -0
  117. package/dist/inbox/index.js +10 -0
  118. package/dist/inbox/seen-set.d.ts +82 -0
  119. package/dist/inbox/seen-set.js +202 -0
  120. package/dist/inbox/subscription.d.ts +236 -0
  121. package/dist/inbox/subscription.js +644 -0
  122. package/dist/index.d.ts +10 -0
  123. package/dist/index.js +9 -0
  124. package/dist/invitations/competing-welcome.d.ts +223 -0
  125. package/dist/invitations/competing-welcome.js +128 -0
  126. package/dist/invitations/decline.d.ts +67 -0
  127. package/dist/invitations/decline.js +149 -0
  128. package/dist/invitations/delivery-evidence.d.ts +288 -0
  129. package/dist/invitations/delivery-evidence.js +766 -0
  130. package/dist/invitations/expect-welcome.d.ts +66 -0
  131. package/dist/invitations/expect-welcome.js +138 -0
  132. package/dist/invitations/index.d.ts +18 -0
  133. package/dist/invitations/index.js +18 -0
  134. package/dist/invitations/invitation-outcome.d.ts +110 -0
  135. package/dist/invitations/invitation-outcome.js +210 -0
  136. package/dist/invitations/invite.d.ts +358 -0
  137. package/dist/invitations/invite.js +1102 -0
  138. package/dist/invitations/offers.d.ts +79 -0
  139. package/dist/invitations/offers.js +115 -0
  140. package/dist/invitations/on-proposal.d.ts +47 -0
  141. package/dist/invitations/on-proposal.js +40 -0
  142. package/dist/invitations/pending-proposal-policy.d.ts +52 -0
  143. package/dist/invitations/pending-proposal-policy.js +139 -0
  144. package/dist/invitations/proposal-deadline.d.ts +133 -0
  145. package/dist/invitations/proposal-deadline.js +164 -0
  146. package/dist/invitations/relay-planes.d.ts +43 -0
  147. package/dist/invitations/relay-planes.js +70 -0
  148. package/dist/invitations/welcome-processor.d.ts +272 -0
  149. package/dist/invitations/welcome-processor.js +1241 -0
  150. package/dist/key-packages/device-key.d.ts +131 -0
  151. package/dist/key-packages/device-key.js +272 -0
  152. package/dist/key-packages/device-rotation-records.d.ts +83 -0
  153. package/dist/key-packages/device-rotation-records.js +173 -0
  154. package/dist/key-packages/group-refs.d.ts +40 -0
  155. package/dist/key-packages/group-refs.js +79 -0
  156. package/dist/key-packages/index.d.ts +18 -0
  157. package/dist/key-packages/index.js +18 -0
  158. package/dist/key-packages/key-package-ref.d.ts +16 -0
  159. package/dist/key-packages/key-package-ref.js +21 -0
  160. package/dist/key-packages/observation-stream.d.ts +4 -0
  161. package/dist/key-packages/observation-stream.js +120 -0
  162. package/dist/key-packages/offer-rumor.d.ts +26 -0
  163. package/dist/key-packages/offer-rumor.js +69 -0
  164. package/dist/key-packages/publisher.d.ts +174 -0
  165. package/dist/key-packages/publisher.js +1247 -0
  166. package/dist/key-packages/select-key-package.d.ts +24 -0
  167. package/dist/key-packages/select-key-package.js +90 -0
  168. package/dist/key-packages/slot-manager.d.ts +167 -0
  169. package/dist/key-packages/slot-manager.js +327 -0
  170. package/dist/key-packages/validate-key-package-event.d.ts +3 -0
  171. package/dist/key-packages/validate-key-package-event.js +49 -0
  172. package/dist/media/cache.d.ts +14 -0
  173. package/dist/media/cache.js +10 -0
  174. package/dist/media/index.d.ts +52 -0
  175. package/dist/media/index.js +71 -0
  176. package/dist/mls.d.ts +15 -0
  177. package/dist/mls.js +15 -0
  178. package/dist/shared/account-pubkey.d.ts +4 -0
  179. package/dist/shared/account-pubkey.js +10 -0
  180. package/dist/shared/errors.d.ts +28 -0
  181. package/dist/shared/errors.js +96 -0
  182. package/dist/shared/hex.d.ts +4 -0
  183. package/dist/shared/hex.js +13 -0
  184. package/dist/shared/index.d.ts +14 -0
  185. package/dist/shared/index.js +14 -0
  186. package/dist/shared/kinds.d.ts +8 -0
  187. package/dist/shared/kinds.js +28 -0
  188. package/dist/shared/publish-classification.d.ts +26 -0
  189. package/dist/shared/publish-classification.js +31 -0
  190. package/dist/storage/envelope.d.ts +39 -0
  191. package/dist/storage/envelope.js +201 -0
  192. package/dist/storage/index.d.ts +237 -0
  193. package/dist/storage/index.js +491 -0
  194. package/dist/storage/indexeddb/idb-types.d.ts +68 -0
  195. package/dist/storage/indexeddb/idb-types.js +1 -0
  196. package/dist/storage/indexeddb/index.d.ts +17 -0
  197. package/dist/storage/indexeddb/index.js +141 -0
  198. package/dist/storage/lease.d.ts +54 -0
  199. package/dist/storage/lease.js +168 -0
  200. package/dist/storage/memory/deterministic-signer.d.ts +27 -0
  201. package/dist/storage/memory/deterministic-signer.js +65 -0
  202. package/dist/storage/memory/index.d.ts +32 -0
  203. package/dist/storage/memory/index.js +87 -0
  204. package/dist/storage/memory/lock-manager.d.ts +8 -0
  205. package/dist/storage/memory/lock-manager.js +71 -0
  206. package/package.json +66 -3
@@ -0,0 +1,491 @@
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 { CURRENT_CODEC_VERSIONS, openEnvelope, openEnvelopeUnchecked, sealEnvelope, } from './envelope.js';
72
+ import { acquireLease, onLeaseEnded, runLeaseEndListener, setReleaseBarrier, validateLeaseTimeout } from './lease.js';
73
+ export { CURRENT_CODEC_VERSIONS, ENVELOPE_FORMAT, decodePayload, encodePayload, openEnvelope, sealEnvelope, } from './envelope.js';
74
+ export { DEFAULT_LEASE_TIMEOUT_MS, acquireLease, defaultLockManager, } from './lease.js';
75
+ // ---------------------------------------------------------------------------
76
+ // Artifacts (AC-STORE-9; ADR-007 §1 extended by the spec's Amendments)
77
+ // ---------------------------------------------------------------------------
78
+ export const GROUP_ARTIFACTS = Object.freeze([
79
+ 'clientState',
80
+ 'ingestCursor',
81
+ 'terminalLedger',
82
+ 'rewindTree',
83
+ 'removalMarker',
84
+ 'pendingIntents',
85
+ 'queuedRumors',
86
+ 'leafBackup',
87
+ 'retainedHistory',
88
+ ]);
89
+ export const ACCOUNT_ARTIFACTS = Object.freeze([
90
+ 'keyPackages',
91
+ 'keyPackageGroupRefs',
92
+ 'invites',
93
+ 'pendingInvitations',
94
+ 'enrolmentManifests',
95
+ 'enrolmentSessions',
96
+ 'deviceRegistry',
97
+ 'inboxSeenSet',
98
+ 'syncKeyVersions',
99
+ 'wipeMarker',
100
+ ]);
101
+ /** Object-store / bucket name holding every `extension(id)` view (the `extension/*` artifact). */
102
+ export const EXTENSION_BUCKET = 'extension';
103
+ /** Every bucket a backend must provide: both artifact lists plus {@link EXTENSION_BUCKET}. */
104
+ export const ALL_BUCKETS = Object.freeze([...GROUP_ARTIFACTS, ...ACCOUNT_ARTIFACTS, EXTENSION_BUCKET]);
105
+ /** The key the wipe marker lives under in the `wipeMarker` artifact. */
106
+ export const WIPE_MARKER_KEY = 'current';
107
+ const ACCOUNT_PATTERN = /^[0-9a-f]{64}$/;
108
+ function validateAccount(account, where) {
109
+ if (typeof account !== 'string' || !ACCOUNT_PATTERN.test(account)) {
110
+ throw new MarmotError('invalid-options', `${where}: account must be a 64-character lowercase hex pubkey`);
111
+ }
112
+ return account;
113
+ }
114
+ function validateName(value, what) {
115
+ if (typeof value !== 'string' || value.length === 0)
116
+ throw new MarmotError('invalid-options', `${what} must be a non-empty string`);
117
+ return value;
118
+ }
119
+ function validateKey(key) {
120
+ if (typeof key !== 'string')
121
+ throw new MarmotError('invalid-options', 'store key must be a string');
122
+ return key;
123
+ }
124
+ class SerialQueue {
125
+ #tail = Promise.resolve();
126
+ run(task) {
127
+ const result = this.#tail.then(task, task);
128
+ this.#tail = result.catch(() => undefined);
129
+ return result;
130
+ }
131
+ }
132
+ function rowId(bucket, path) {
133
+ return JSON.stringify([bucket, ...path]);
134
+ }
135
+ function samePrefix(path, prefix) {
136
+ return path.length === prefix.length + 1 && prefix.every((p, i) => path[i] === p);
137
+ }
138
+ /** Builds a {@link StorageBackend} over a driver — how the reference backends, and any consumer backend, are made. */
139
+ export function createStorageBackend(driver, options = {}) {
140
+ const defaultTimeout = validateLeaseTimeout(options.leaseTimeoutMs, 'storage backend');
141
+ const versions = options.codecVersions ?? CURRENT_CODEC_VERSIONS;
142
+ const clock = options.clock ?? { now: () => Date.now() };
143
+ // Leases this backend instance issued, and the one handle each opened (INV-NO-SINGLETONS: per instance).
144
+ const issued = new WeakSet();
145
+ const handles = new WeakMap();
146
+ async function acquire(account, opts) {
147
+ validateAccount(account, 'acquireLease');
148
+ const timeoutMs = opts?.leaseTimeoutMs === undefined ? defaultTimeout : validateLeaseTimeout(opts.leaseTimeoutMs, 'acquireLease');
149
+ const lease = await acquireLease(driver.locks, driver.lockName(account), account, { timeoutMs });
150
+ issued.add(lease);
151
+ return lease;
152
+ }
153
+ function open(account, lease) {
154
+ validateAccount(account, 'open');
155
+ if (lease === undefined || lease === null || !issued.has(lease) || lease.account !== account || !lease.held) {
156
+ throw new MarmotError('no-lease', `open: no live lease of this backend for account ${account}`, { details: { account } });
157
+ }
158
+ let handle = handles.get(lease);
159
+ if (handle === undefined) {
160
+ handle = createHandle(driver, account, lease, versions, clock);
161
+ handles.set(lease, handle);
162
+ }
163
+ return handle;
164
+ }
165
+ return {
166
+ acquireLease: acquire,
167
+ open,
168
+ async openForWrite(account, opts) {
169
+ return open(account, await acquire(account, opts));
170
+ },
171
+ };
172
+ }
173
+ function createHandle(driver, account, lease, versions, clock) {
174
+ let closed = false;
175
+ // Bumped once a wipe has committed; a transaction that began before the
176
+ // wipe must not flush afterwards and resurrect wiped rows.
177
+ let wipeGeneration = 0;
178
+ // The account-wide commit gate (module comment): every flush of every scope runs here, one at a time.
179
+ const commitGate = new SerialQueue();
180
+ // Every release of this lease (close(), stores.lease.release(), or the caller's own reference) first
181
+ // stops new writes and lets a flush already committing finish; flushes queued behind it reject no-lease.
182
+ // The lease-end listeners (AccountStore.onLeaseEnded): fired once, on the first of the release barrier (right after
183
+ // writes stop) and the lease's own end signal (a steal runs no barrier).
184
+ // One entry per registration (not per function): registering the same function twice fires it twice, and each
185
+ // unregister removes only its own registration.
186
+ const leaseEndListeners = new Set();
187
+ let leaseEndFired = false;
188
+ function fireLeaseEnded() {
189
+ if (leaseEndFired)
190
+ return;
191
+ leaseEndFired = true;
192
+ const listeners = [...leaseEndListeners];
193
+ leaseEndListeners.clear();
194
+ // A throwing listener, or an async one that rejects, never breaks the release, nor the other listeners.
195
+ for (const { listener } of listeners)
196
+ runLeaseEndListener(listener);
197
+ }
198
+ setReleaseBarrier(lease, async () => {
199
+ closed = true;
200
+ fireLeaseEnded();
201
+ await commitGate.run(async () => { });
202
+ });
203
+ onLeaseEnded(lease, fireLeaseEnded);
204
+ function assertLease() {
205
+ if (closed || !lease.held) {
206
+ throw new MarmotError('no-lease', `store for account ${account} is not held under a live lease`, { details: { account } });
207
+ }
208
+ }
209
+ async function readRow(bucket, path) {
210
+ try {
211
+ return await driver.read(account, bucket, path);
212
+ }
213
+ catch (err) {
214
+ throw new MarmotError('store-failed', `read of ${bucket} failed`, { cause: err });
215
+ }
216
+ }
217
+ async function listKeys(bucket, prefix) {
218
+ try {
219
+ return await driver.keys(account, bucket, prefix);
220
+ }
221
+ catch (err) {
222
+ throw new MarmotError('store-failed', `key listing of ${bucket} failed`, { cause: err });
223
+ }
224
+ }
225
+ function decode(internals, key, raw) {
226
+ try {
227
+ return openEnvelope(key, raw, versions);
228
+ }
229
+ catch (err) {
230
+ const error = err;
231
+ for (const listener of [...internals.listeners]) {
232
+ try {
233
+ listener({ key, error });
234
+ }
235
+ catch {
236
+ // A throwing listener must not change the read's outcome.
237
+ }
238
+ }
239
+ throw error;
240
+ }
241
+ }
242
+ /** A transaction's buffer and the views over it. */
243
+ class Tx {
244
+ internals;
245
+ open = true;
246
+ cleared = false;
247
+ /** `GroupStore.clear()`: every row of this scope goes, before the buffered writes. */
248
+ scopeCleared = false;
249
+ buffer = new Map();
250
+ constructor(internals) {
251
+ this.internals = internals;
252
+ }
253
+ assertOpen() {
254
+ if (!this.open)
255
+ throw new MarmotError('transaction-closed', 'store transaction already settled; writes after it are not part of it');
256
+ }
257
+ view(bucket, prefix, labelPrefix) {
258
+ const tx = this;
259
+ return {
260
+ async get(rawKey) {
261
+ tx.assertOpen();
262
+ const key = validateKey(rawKey);
263
+ const path = [...prefix, key];
264
+ const buffered = tx.buffer.get(rowId(bucket, path));
265
+ if (buffered !== undefined)
266
+ return buffered.envelope === null ? undefined : openEnvelope(`${labelPrefix}/${key}`, buffered.envelope, versions);
267
+ if (tx.cleared || tx.scopeCleared)
268
+ return undefined;
269
+ const raw = await readRow(bucket, path);
270
+ return raw === undefined ? undefined : decode(tx.internals, `${labelPrefix}/${key}`, raw);
271
+ },
272
+ async put(rawKey, value) {
273
+ tx.assertOpen();
274
+ const key = validateKey(rawKey);
275
+ const path = [...prefix, key];
276
+ tx.buffer.set(rowId(bucket, path), { bucket, path, envelope: sealEnvelope(value, versions) });
277
+ },
278
+ async delete(rawKey) {
279
+ tx.assertOpen();
280
+ const key = validateKey(rawKey);
281
+ const path = [...prefix, key];
282
+ tx.buffer.set(rowId(bucket, path), { bucket, path, envelope: null });
283
+ },
284
+ async keys() {
285
+ tx.assertOpen();
286
+ const present = new Set(tx.cleared || tx.scopeCleared ? [] : await listKeys(bucket, prefix));
287
+ for (const write of tx.buffer.values()) {
288
+ if (write.bucket !== bucket || !samePrefix(write.path, prefix))
289
+ continue;
290
+ const key = write.path[write.path.length - 1];
291
+ if (write.envelope === null)
292
+ present.delete(key);
293
+ else
294
+ present.add(key);
295
+ }
296
+ return [...present].sort();
297
+ },
298
+ };
299
+ }
300
+ scopeApi() {
301
+ const { scope, label, artifacts } = this.internals;
302
+ return {
303
+ artifact: (name) => {
304
+ if (!artifacts.includes(name))
305
+ throw new MarmotError('invalid-options', `unknown artifact ${JSON.stringify(name)} for ${label}`);
306
+ return this.view(name, [scope], `${label}/${name}`);
307
+ },
308
+ extension: (rawId) => {
309
+ const id = validateName(rawId, 'extension id');
310
+ return this.view(EXTENSION_BUCKET, [scope, id], `${label}/extension/${id}`);
311
+ },
312
+ };
313
+ }
314
+ writes() {
315
+ const out = this.cleared ? [{ type: 'clear' }] : this.scopeCleared ? [{ type: 'clearScope', scope: this.internals.scope }] : [];
316
+ for (const w of this.buffer.values()) {
317
+ out.push(w.envelope === null ? { type: 'delete', bucket: w.bucket, path: w.path } : { type: 'put', bucket: w.bucket, path: w.path, envelope: w.envelope });
318
+ }
319
+ return out;
320
+ }
321
+ }
322
+ function runTransaction(internals, fn, setup) {
323
+ if (typeof fn !== 'function')
324
+ return Promise.reject(new MarmotError('invalid-options', 'transaction(fn): fn must be a function'));
325
+ if (internals.inSyncFn) {
326
+ // Queueing would wait on the transaction whose `fn` is making this call.
327
+ return Promise.reject(new MarmotError('reentrant', `${internals.label}: store-level write from inside a running transaction on the same store; use the transaction's tx view`, {
328
+ details: { scope: internals.label },
329
+ }));
330
+ }
331
+ return internals.queue.run(async () => {
332
+ assertLease();
333
+ const generation = wipeGeneration;
334
+ const tx = new Tx(internals);
335
+ setup?.(tx);
336
+ let result;
337
+ try {
338
+ let pending;
339
+ internals.inSyncFn = true;
340
+ try {
341
+ pending = fn(tx.scopeApi());
342
+ }
343
+ finally {
344
+ internals.inSyncFn = false;
345
+ }
346
+ result = await pending;
347
+ }
348
+ finally {
349
+ tx.open = false;
350
+ }
351
+ const writes = tx.writes();
352
+ if (writes.length === 0) {
353
+ assertCommittable(generation);
354
+ return result;
355
+ }
356
+ await commitGate.run(async () => {
357
+ // Re-checked inside the gate, immediately before the commit (ADR-013; module comment: commit gate).
358
+ assertCommittable(generation);
359
+ try {
360
+ await driver.commit(account, writes);
361
+ }
362
+ catch (err) {
363
+ throw new MarmotError('store-failed', `commit for account ${account} failed; no write was applied`, { cause: err });
364
+ }
365
+ // Only a wipe that actually committed invalidates transactions begun before it.
366
+ if (tx.cleared)
367
+ wipeGeneration++;
368
+ });
369
+ return result;
370
+ });
371
+ }
372
+ /** Throws unless a transaction that began at wipe `generation` may still commit: lease live, no wipe since. */
373
+ function assertCommittable(generation) {
374
+ assertLease();
375
+ if (generation !== wipeGeneration) {
376
+ throw new MarmotError('transaction-closed', `account ${account} was wiped while the transaction ran; its writes were dropped`);
377
+ }
378
+ }
379
+ function makeScope(scope, label, artifacts) {
380
+ const internals = { scope, label, artifacts, queue: new SerialQueue(), listeners: new Set(), inSyncFn: false };
381
+ /** A store-level view: reads go straight to the backend, each write is its own transaction. */
382
+ function autoView(select) {
383
+ const reader = () => {
384
+ assertLease();
385
+ const tx = new Tx(internals);
386
+ return select(tx.scopeApi());
387
+ };
388
+ return {
389
+ get: (key) => Promise.resolve().then(() => reader().get(key)),
390
+ keys: () => Promise.resolve().then(() => reader().keys()),
391
+ put: (key, value) => runTransaction(internals, (tx) => select(tx).put(key, value)),
392
+ delete: (key) => runTransaction(internals, (tx) => select(tx).delete(key)),
393
+ };
394
+ }
395
+ const base = {
396
+ artifact(name) {
397
+ if (!artifacts.includes(name))
398
+ throw new MarmotError('invalid-options', `unknown artifact ${JSON.stringify(name)} for ${label}`);
399
+ return autoView((tx) => tx.artifact(name));
400
+ },
401
+ extension(rawId) {
402
+ const id = validateName(rawId, 'extension id');
403
+ return autoView((tx) => tx.extension(id));
404
+ },
405
+ onIncompatible(listener) {
406
+ if (typeof listener !== 'function')
407
+ throw new MarmotError('invalid-options', 'onIncompatible: listener must be a function');
408
+ internals.listeners.add(listener);
409
+ return () => {
410
+ internals.listeners.delete(listener);
411
+ };
412
+ },
413
+ };
414
+ return { internals, base };
415
+ }
416
+ const accountScope = makeScope('account', `account:${account}`, ACCOUNT_ARTIFACTS);
417
+ const accountStore = {
418
+ account,
419
+ artifact: (name) => accountScope.base.artifact(name),
420
+ extension: (id) => accountScope.base.extension(id),
421
+ onIncompatible: (listener) => accountScope.base.onIncompatible(listener),
422
+ transaction: (fn) => runTransaction(accountScope.internals, fn),
423
+ async wipe(opts) {
424
+ const reason = opts?.reason;
425
+ if (reason !== 'incompatible' && reason !== 'application') {
426
+ throw new MarmotError('invalid-options', "wipe: reason must be 'incompatible' or 'application'");
427
+ }
428
+ const at = clock.now();
429
+ await runTransaction(accountScope.internals, async (tx) => {
430
+ await tx.artifact('wipeMarker').put(WIPE_MARKER_KEY, { at, reason });
431
+ }, (tx) => {
432
+ tx.cleared = true;
433
+ });
434
+ return Object.freeze({ engine: versions.engine, tsMls: versions.tsMls, at, reason });
435
+ },
436
+ async wipeMarker() {
437
+ const key = `${accountScope.internals.label}/wipeMarker/${WIPE_MARKER_KEY}`;
438
+ const raw = await readRow('wipeMarker', ['account', WIPE_MARKER_KEY]);
439
+ if (raw === undefined)
440
+ return undefined;
441
+ const { stamp, value } = openEnvelopeUnchecked(key, raw);
442
+ const v = value;
443
+ if (typeof v !== 'object' || v === null || typeof v.at !== 'number' || (v.reason !== 'incompatible' && v.reason !== 'application')) {
444
+ throw new MarmotError('envelope-mismatch', `stored artifact ${key}: malformed wipe marker`, { details: { key, reason: 'malformed' } });
445
+ }
446
+ return Object.freeze({ engine: stamp.engine, tsMls: stamp.tsMls, at: v.at, reason: v.reason });
447
+ },
448
+ onLeaseEnded(listener) {
449
+ if (typeof listener !== 'function')
450
+ throw new MarmotError('invalid-options', 'onLeaseEnded: listener must be a function');
451
+ if (leaseEndFired) {
452
+ // As for a listener fired by the release.
453
+ runLeaseEndListener(listener);
454
+ return () => undefined;
455
+ }
456
+ const registration = { listener };
457
+ leaseEndListeners.add(registration);
458
+ return () => {
459
+ leaseEndListeners.delete(registration);
460
+ };
461
+ },
462
+ };
463
+ const groups = new Map();
464
+ function groupFactory(rawGroupId) {
465
+ const groupId = validateName(rawGroupId, 'groupId');
466
+ let store = groups.get(groupId);
467
+ if (store === undefined) {
468
+ const scope = makeScope(`group:${groupId}`, `group:${groupId}`, GROUP_ARTIFACTS);
469
+ store = {
470
+ groupId,
471
+ artifact: (name) => scope.base.artifact(name),
472
+ extension: (id) => scope.base.extension(id),
473
+ onIncompatible: (listener) => scope.base.onIncompatible(listener),
474
+ transaction: (fn) => runTransaction(scope.internals, fn),
475
+ clear: () => runTransaction(scope.internals, () => undefined, (tx) => {
476
+ tx.scopeCleared = true;
477
+ }),
478
+ };
479
+ groups.set(groupId, store);
480
+ }
481
+ return store;
482
+ }
483
+ return {
484
+ account: accountStore,
485
+ groupFactory,
486
+ lease,
487
+ close() {
488
+ return lease.release();
489
+ },
490
+ };
491
+ }
@@ -0,0 +1,68 @@
1
+ /**
2
+ * The structural subset of IndexedDB this backend uses. `@941design/marmot`
3
+ * compiles without the DOM lib, so these stand in for the DOM's
4
+ * `IDBFactory` & co.; the real browser objects and `fake-indexeddb`'s
5
+ * satisfy them.
6
+ *
7
+ * Two rules keep native `window.indexedDB` / `IDBKeyRange` (and
8
+ * `fake-indexeddb`'s exports) structurally assignable WITHOUT casts, even
9
+ * though this package compiles without `lib: dom`:
10
+ * 1. Event-handler properties (`onsuccess` & co.) are typed
11
+ * `(this: any, ev: any) => any`, not `(this: unknown, ev: unknown) =>
12
+ * unknown` — a property-typed function is checked contravariantly on its
13
+ * `this`/parameter types under `strictFunctionTypes`, and native DOM
14
+ * handlers declare a concrete `this`/event type that `unknown` there
15
+ * would reject; `any` opts out of that check for a callback signature
16
+ * this backend only ever assigns, never calls with a synthetic `this`.
17
+ * 2. `IDBValidKeyLike` mirrors the DOM lib's own
18
+ * `IDBValidKey = number | string | Date | BufferSource | IDBValidKey[]`
19
+ * (`ArrayBufferView` is an ES lib type, not DOM-only, so it's in scope
20
+ * here) rather than narrowing to the `string[]` paths this backend
21
+ * actually passes — the interface describes what native IndexedDB
22
+ * accepts, not what this backend happens to send.
23
+ */
24
+ export type IDBValidKeyLike = number | string | Date | ArrayBuffer | ArrayBufferView | IDBValidKeyLike[];
25
+ export interface IDBRequestLike<T> {
26
+ readonly result: T;
27
+ readonly error: unknown;
28
+ onsuccess: ((this: any, ev: any) => any) | null;
29
+ onerror: ((this: any, ev: any) => any) | null;
30
+ }
31
+ export interface IDBOpenDBRequestLike extends IDBRequestLike<IDBDatabaseLike> {
32
+ onupgradeneeded: ((this: any, ev: any) => any) | null;
33
+ onblocked: ((this: any, ev: any) => any) | null;
34
+ }
35
+ export interface IDBObjectStoreLike {
36
+ get(key: IDBValidKeyLike): IDBRequestLike<unknown>;
37
+ getAllKeys(query?: unknown): IDBRequestLike<IDBValidKeyLike[]>;
38
+ put(value: unknown, key: IDBValidKeyLike): IDBRequestLike<unknown>;
39
+ /** A key, or a key range (`IDBKeyRangeStaticLike.bound`). */
40
+ delete(query: IDBValidKeyLike | unknown): IDBRequestLike<unknown>;
41
+ clear(): IDBRequestLike<unknown>;
42
+ }
43
+ export interface IDBTransactionLike {
44
+ readonly error: unknown;
45
+ objectStore(name: string): IDBObjectStoreLike;
46
+ abort(): void;
47
+ oncomplete: ((this: any, ev: any) => any) | null;
48
+ onerror: ((this: any, ev: any) => any) | null;
49
+ onabort: ((this: any, ev: any) => any) | null;
50
+ }
51
+ export interface IDBDatabaseLike {
52
+ readonly objectStoreNames: {
53
+ contains(name: string): boolean;
54
+ readonly length: number;
55
+ item(index: number): string | null;
56
+ };
57
+ createObjectStore(name: string): unknown;
58
+ transaction(storeNames: string | string[], mode: 'readonly' | 'readwrite'): IDBTransactionLike;
59
+ close(): void;
60
+ onversionchange: ((this: any, ev: any) => any) | null;
61
+ onclose: ((this: any, ev: any) => any) | null;
62
+ }
63
+ export interface IDBFactoryLike {
64
+ open(name: string, version?: number): IDBOpenDBRequestLike;
65
+ }
66
+ export interface IDBKeyRangeStaticLike {
67
+ bound(lower: unknown, upper: unknown, lowerOpen?: boolean, upperOpen?: boolean): unknown;
68
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,17 @@
1
+ import { type BackendOptions, type StorageBackend } from '../index.js';
2
+ import { type LockManagerLike } from '../lease.js';
3
+ import type { IDBFactoryLike, IDBKeyRangeStaticLike } from './idb-types.js';
4
+ export type { IDBDatabaseLike, IDBFactoryLike, IDBKeyRangeStaticLike, IDBObjectStoreLike, IDBOpenDBRequestLike, IDBRequestLike, IDBTransactionLike, IDBValidKeyLike, } from './idb-types.js';
5
+ export declare const DEFAULT_DB_PREFIX = "marmot:";
6
+ export declare const DB_VERSION = 1;
7
+ export interface IndexedDbStorageOptions extends BackendOptions {
8
+ /** Defaults to `globalThis.indexedDB`. */
9
+ readonly indexedDB?: IDBFactoryLike;
10
+ /** Defaults to `globalThis.IDBKeyRange`. */
11
+ readonly IDBKeyRange?: IDBKeyRangeStaticLike;
12
+ /** Defaults to `navigator.locks`. Required where the host has no Web Locks. */
13
+ readonly locks?: LockManagerLike;
14
+ /** Database name prefix; the account pubkey is appended. Default `'marmot:'`. */
15
+ readonly dbPrefix?: string;
16
+ }
17
+ export declare function createIndexedDbStorage(options?: IndexedDbStorageOptions): StorageBackend;