@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.
- package/CHANGELOG.md +709 -0
- package/LICENSE +21 -0
- package/README.md +33 -2
- package/dist/account/admin.d.ts +72 -0
- package/dist/account/admin.js +209 -0
- package/dist/account/device-deps.d.ts +379 -0
- package/dist/account/device-deps.js +36 -0
- package/dist/account/device-lineage.d.ts +199 -0
- package/dist/account/device-lineage.js +390 -0
- package/dist/account/device-registry.d.ts +93 -0
- package/dist/account/device-registry.js +1290 -0
- package/dist/account/device-rotation.d.ts +61 -0
- package/dist/account/device-rotation.js +827 -0
- package/dist/account/enrolment.d.ts +339 -0
- package/dist/account/enrolment.js +1247 -0
- package/dist/account/identity-proof.d.ts +79 -0
- package/dist/account/identity-proof.js +264 -0
- package/dist/account/index.d.ts +17 -0
- package/dist/account/index.js +16 -0
- package/dist/account/restore-rotation.d.ts +21 -0
- package/dist/account/restore-rotation.js +22 -0
- package/dist/account/same-account-authorization.d.ts +86 -0
- package/dist/account/same-account-authorization.js +180 -0
- package/dist/account/teardown.d.ts +127 -0
- package/dist/account/teardown.js +856 -0
- package/dist/client/before-create-group.d.ts +18 -0
- package/dist/client/before-create-group.js +65 -0
- package/dist/client/before-publish-hooks.d.ts +121 -0
- package/dist/client/before-publish-hooks.js +180 -0
- package/dist/client/client-config.d.ts +42 -0
- package/dist/client/client-config.js +13 -0
- package/dist/client/commit-redrive.d.ts +68 -0
- package/dist/client/commit-redrive.js +221 -0
- package/dist/client/component-update.d.ts +43 -0
- package/dist/client/component-update.js +53 -0
- package/dist/client/confirm-hooks.d.ts +50 -0
- package/dist/client/confirm-hooks.js +59 -0
- package/dist/client/create-client.d.ts +1022 -0
- package/dist/client/create-client.js +1125 -0
- package/dist/client/group-disband.d.ts +28 -0
- package/dist/client/group-disband.js +64 -0
- package/dist/client/group-history.d.ts +435 -0
- package/dist/client/group-history.js +1295 -0
- package/dist/client/group-profile.d.ts +31 -0
- package/dist/client/group-profile.js +62 -0
- package/dist/client/group-records.d.ts +485 -0
- package/dist/client/group-records.js +1034 -0
- package/dist/client/group-removal.d.ts +36 -0
- package/dist/client/group-removal.js +127 -0
- package/dist/client/group-remove-member.d.ts +49 -0
- package/dist/client/group-remove-member.js +163 -0
- package/dist/client/group-runtime.d.ts +388 -0
- package/dist/client/group-runtime.js +2701 -0
- package/dist/client/group-snapshot.d.ts +98 -0
- package/dist/client/group-snapshot.js +453 -0
- package/dist/client/history-pages.d.ts +107 -0
- package/dist/client/history-pages.js +194 -0
- package/dist/client/inbox-send.d.ts +19 -0
- package/dist/client/inbox-send.js +71 -0
- package/dist/client/index.d.ts +21 -0
- package/dist/client/index.js +13 -0
- package/dist/client/ingest.d.ts +82 -0
- package/dist/client/ingest.js +1550 -0
- package/dist/client/lifecycle-events.d.ts +63 -0
- package/dist/client/lifecycle-events.js +35 -0
- package/dist/client/opaque-candidates.d.ts +81 -0
- package/dist/client/opaque-candidates.js +169 -0
- package/dist/client/own-change-outbox.d.ts +66 -0
- package/dist/client/own-change-outbox.js +156 -0
- package/dist/client/pending-leaf.d.ts +116 -0
- package/dist/client/pending-leaf.js +378 -0
- package/dist/client/permissions.d.ts +9 -0
- package/dist/client/permissions.js +12 -0
- package/dist/client/pipeline.d.ts +554 -0
- package/dist/client/pipeline.js +3545 -0
- package/dist/client/reentrancy-guard.d.ts +96 -0
- package/dist/client/reentrancy-guard.js +153 -0
- package/dist/client/rekey.d.ts +58 -0
- package/dist/client/rekey.js +149 -0
- package/dist/client/transport-policy.d.ts +181 -0
- package/dist/client/transport-policy.js +214 -0
- package/dist/history/equivocation.d.ts +55 -0
- package/dist/history/equivocation.js +113 -0
- package/dist/history/fencing.d.ts +25 -0
- package/dist/history/fencing.js +61 -0
- package/dist/history/hex.d.ts +3 -0
- package/dist/history/hex.js +10 -0
- package/dist/history/index.d.ts +73 -0
- package/dist/history/index.js +31 -0
- package/dist/history/notifications.d.ts +270 -0
- package/dist/history/notifications.js +264 -0
- package/dist/history/ordering-key.d.ts +24 -0
- package/dist/history/ordering-key.js +101 -0
- package/dist/history/own-change-fork.d.ts +112 -0
- package/dist/history/own-change-fork.js +196 -0
- package/dist/history/own-change.d.ts +106 -0
- package/dist/history/own-change.js +146 -0
- package/dist/history/policy.d.ts +48 -0
- package/dist/history/policy.js +52 -0
- package/dist/history/retained-window.d.ts +215 -0
- package/dist/history/retained-window.js +565 -0
- package/dist/inbox/demux.d.ts +90 -0
- package/dist/inbox/demux.js +78 -0
- package/dist/inbox/handler-registry.d.ts +42 -0
- package/dist/inbox/handler-registry.js +37 -0
- package/dist/inbox/index.d.ts +11 -0
- package/dist/inbox/index.js +10 -0
- package/dist/inbox/seen-set.d.ts +82 -0
- package/dist/inbox/seen-set.js +202 -0
- package/dist/inbox/subscription.d.ts +236 -0
- package/dist/inbox/subscription.js +644 -0
- package/dist/index.d.ts +10 -0
- package/dist/index.js +9 -0
- package/dist/invitations/competing-welcome.d.ts +223 -0
- package/dist/invitations/competing-welcome.js +128 -0
- package/dist/invitations/decline.d.ts +61 -0
- package/dist/invitations/decline.js +143 -0
- package/dist/invitations/expect-welcome.d.ts +66 -0
- package/dist/invitations/expect-welcome.js +138 -0
- package/dist/invitations/index.d.ts +16 -0
- package/dist/invitations/index.js +16 -0
- package/dist/invitations/invite.d.ts +303 -0
- package/dist/invitations/invite.js +966 -0
- package/dist/invitations/offers.d.ts +79 -0
- package/dist/invitations/offers.js +115 -0
- package/dist/invitations/on-proposal.d.ts +47 -0
- package/dist/invitations/on-proposal.js +40 -0
- package/dist/invitations/pending-proposal-policy.d.ts +52 -0
- package/dist/invitations/pending-proposal-policy.js +139 -0
- package/dist/invitations/proposal-deadline.d.ts +133 -0
- package/dist/invitations/proposal-deadline.js +164 -0
- package/dist/invitations/relay-planes.d.ts +43 -0
- package/dist/invitations/relay-planes.js +70 -0
- package/dist/invitations/welcome-processor.d.ts +253 -0
- package/dist/invitations/welcome-processor.js +1180 -0
- package/dist/key-packages/device-key.d.ts +131 -0
- package/dist/key-packages/device-key.js +272 -0
- package/dist/key-packages/device-rotation-records.d.ts +83 -0
- package/dist/key-packages/device-rotation-records.js +173 -0
- package/dist/key-packages/group-refs.d.ts +40 -0
- package/dist/key-packages/group-refs.js +79 -0
- package/dist/key-packages/index.d.ts +18 -0
- package/dist/key-packages/index.js +18 -0
- package/dist/key-packages/key-package-ref.d.ts +16 -0
- package/dist/key-packages/key-package-ref.js +21 -0
- package/dist/key-packages/observation-stream.d.ts +4 -0
- package/dist/key-packages/observation-stream.js +120 -0
- package/dist/key-packages/offer-rumor.d.ts +26 -0
- package/dist/key-packages/offer-rumor.js +69 -0
- package/dist/key-packages/publisher.d.ts +174 -0
- package/dist/key-packages/publisher.js +1247 -0
- package/dist/key-packages/select-key-package.d.ts +24 -0
- package/dist/key-packages/select-key-package.js +90 -0
- package/dist/key-packages/slot-manager.d.ts +167 -0
- package/dist/key-packages/slot-manager.js +327 -0
- package/dist/key-packages/validate-key-package-event.d.ts +3 -0
- package/dist/key-packages/validate-key-package-event.js +49 -0
- package/dist/media/cache.d.ts +14 -0
- package/dist/media/cache.js +10 -0
- package/dist/media/index.d.ts +52 -0
- package/dist/media/index.js +71 -0
- package/dist/mls.d.ts +15 -0
- package/dist/mls.js +15 -0
- package/dist/shared/account-pubkey.d.ts +4 -0
- package/dist/shared/account-pubkey.js +10 -0
- package/dist/shared/errors.d.ts +21 -0
- package/dist/shared/errors.js +85 -0
- package/dist/shared/hex.d.ts +4 -0
- package/dist/shared/hex.js +13 -0
- package/dist/shared/index.d.ts +14 -0
- package/dist/shared/index.js +14 -0
- package/dist/shared/kinds.d.ts +8 -0
- package/dist/shared/kinds.js +28 -0
- package/dist/shared/publish-classification.d.ts +26 -0
- package/dist/shared/publish-classification.js +31 -0
- package/dist/storage/envelope.d.ts +39 -0
- package/dist/storage/envelope.js +201 -0
- package/dist/storage/index.d.ts +227 -0
- package/dist/storage/index.js +459 -0
- package/dist/storage/indexeddb/idb-types.d.ts +68 -0
- package/dist/storage/indexeddb/idb-types.js +1 -0
- package/dist/storage/indexeddb/index.d.ts +17 -0
- package/dist/storage/indexeddb/index.js +141 -0
- package/dist/storage/lease.d.ts +41 -0
- package/dist/storage/lease.js +117 -0
- package/dist/storage/memory/deterministic-signer.d.ts +27 -0
- package/dist/storage/memory/deterministic-signer.js +65 -0
- package/dist/storage/memory/index.d.ts +32 -0
- package/dist/storage/memory/index.js +87 -0
- package/dist/storage/memory/lock-manager.d.ts +8 -0
- package/dist/storage/memory/lock-manager.js +71 -0
- 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;
|