@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.
- package/CHANGELOG.md +739 -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 +190 -0
- package/dist/account/teardown.js +878 -0
- package/dist/client/admission-cleanup.d.ts +197 -0
- package/dist/client/admission-cleanup.js +635 -0
- package/dist/client/adoption-proof.d.ts +39 -0
- package/dist/client/adoption-proof.js +102 -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 +182 -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 +92 -0
- package/dist/client/commit-redrive.js +274 -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 +55 -0
- package/dist/client/confirm-hooks.js +74 -0
- package/dist/client/create-client.d.ts +1126 -0
- package/dist/client/create-client.js +1232 -0
- package/dist/client/group-availability.d.ts +182 -0
- package/dist/client/group-availability.js +301 -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 +461 -0
- package/dist/client/group-history.js +1365 -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 +522 -0
- package/dist/client/group-records.js +1117 -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 +415 -0
- package/dist/client/group-runtime.js +2811 -0
- package/dist/client/group-snapshot.d.ts +104 -0
- package/dist/client/group-snapshot.js +474 -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 +24 -0
- package/dist/client/index.js +13 -0
- package/dist/client/ingest.d.ts +82 -0
- package/dist/client/ingest.js +1584 -0
- package/dist/client/invitation-outcomes.d.ts +50 -0
- package/dist/client/invitation-outcomes.js +135 -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 +82 -0
- package/dist/client/opaque-candidates.js +170 -0
- package/dist/client/own-change-outbox.d.ts +66 -0
- package/dist/client/own-change-outbox.js +158 -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 +583 -0
- package/dist/client/pipeline.js +3666 -0
- package/dist/client/reentrancy-guard.d.ts +102 -0
- package/dist/client/reentrancy-guard.js +159 -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/admission-lineage.d.ts +186 -0
- package/dist/history/admission-lineage.js +589 -0
- package/dist/history/equivocation.d.ts +55 -0
- package/dist/history/equivocation.js +113 -0
- package/dist/history/fencing.d.ts +66 -0
- package/dist/history/fencing.js +121 -0
- package/dist/history/hex.d.ts +3 -0
- package/dist/history/hex.js +10 -0
- package/dist/history/index.d.ts +74 -0
- package/dist/history/index.js +32 -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 +118 -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 +67 -0
- package/dist/invitations/decline.js +149 -0
- package/dist/invitations/delivery-evidence.d.ts +288 -0
- package/dist/invitations/delivery-evidence.js +766 -0
- package/dist/invitations/expect-welcome.d.ts +66 -0
- package/dist/invitations/expect-welcome.js +138 -0
- package/dist/invitations/index.d.ts +18 -0
- package/dist/invitations/index.js +18 -0
- package/dist/invitations/invitation-outcome.d.ts +110 -0
- package/dist/invitations/invitation-outcome.js +210 -0
- package/dist/invitations/invite.d.ts +358 -0
- package/dist/invitations/invite.js +1102 -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 +272 -0
- package/dist/invitations/welcome-processor.js +1241 -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 +28 -0
- package/dist/shared/errors.js +96 -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 +237 -0
- package/dist/storage/index.js +491 -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 +54 -0
- package/dist/storage/lease.js +168 -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,1117 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Persisted record codecs for the group runtime (S3): the `clientState`
|
|
3
|
+
* codec, the account-level group index, pending-intent records, the
|
|
4
|
+
* terminal ledger and the kind-445 ingest cursor. Pure `KeyValueView` codec
|
|
5
|
+
* helpers — no engine calls, no transport, no re-entrancy guard
|
|
6
|
+
* (`group-runtime.ts` / `pipeline.ts` / `ingest.ts` own those). Every helper
|
|
7
|
+
* accepts a `KeyValueView`, so it works identically against a store's own
|
|
8
|
+
* scope-level view or a transaction's `tx` view.
|
|
9
|
+
*/
|
|
10
|
+
import { OWN_CHANGE_LOST_REASONS } from '../history/index.js';
|
|
11
|
+
import { deserializeClientState, GROUP_ADMIN_POLICY_COMPONENT_ID, GROUP_PROFILE_COMPONENT_ID, serializeClientState } from '@941design/marmot-engine/core';
|
|
12
|
+
import { decodeStoredWelcomes, encodeStoredWelcomes } from '../invitations/index.js';
|
|
13
|
+
import { MarmotError } from '../shared/index.js';
|
|
14
|
+
import { assertGroupProfile } from './group-profile.js';
|
|
15
|
+
import { isAccountPubkey, isHex64 } from '../shared/index.js';
|
|
16
|
+
import { CURSOR_KEY } from './transport-policy.js';
|
|
17
|
+
/** A fresh random pending-intent id (hex). Shared by every writer of `pendingIntents` — pipeline.ts's own
|
|
18
|
+
* intents and group-history.ts's atomic self-update re-enqueue (AC-RACE-1) alike. */
|
|
19
|
+
export function randomIntentId() {
|
|
20
|
+
const bytes = new Uint8Array(16);
|
|
21
|
+
globalThis.crypto.getRandomValues(bytes);
|
|
22
|
+
return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
|
|
23
|
+
}
|
|
24
|
+
// ---------------------------------------------------------------------------
|
|
25
|
+
// clientState (GroupStore `clientState` artifact, key 'current')
|
|
26
|
+
// ---------------------------------------------------------------------------
|
|
27
|
+
const CLIENT_STATE_KEY = 'current';
|
|
28
|
+
/** Whether the group has a persisted `ClientState` (nothing is decoded: a presence check for listings). */
|
|
29
|
+
export async function hasGroupState(view) {
|
|
30
|
+
return (await view.get(CLIENT_STATE_KEY)) !== undefined;
|
|
31
|
+
}
|
|
32
|
+
/** Reads the group's persisted `ClientState`, or `undefined` when the group has never been created/joined locally. */
|
|
33
|
+
export async function readGroupState(view) {
|
|
34
|
+
const raw = await view.get(CLIENT_STATE_KEY);
|
|
35
|
+
if (raw === undefined)
|
|
36
|
+
return undefined;
|
|
37
|
+
if (!(raw instanceof Uint8Array)) {
|
|
38
|
+
throw new MarmotError('store-failed', 'clientState: stored value is not bytes', { details: { key: CLIENT_STATE_KEY, malformed: true } });
|
|
39
|
+
}
|
|
40
|
+
return deserializeClientState(raw);
|
|
41
|
+
}
|
|
42
|
+
/** Persists `state` as the group's current `ClientState`. */
|
|
43
|
+
export async function writeGroupState(view, state) {
|
|
44
|
+
await view.put(CLIENT_STATE_KEY, serializeClientState(state));
|
|
45
|
+
}
|
|
46
|
+
// ---------------------------------------------------------------------------
|
|
47
|
+
// Unfinished-restore marker (group extension `marmot.restorePending`, key 'current') — AC-MX-2
|
|
48
|
+
// ---------------------------------------------------------------------------
|
|
49
|
+
/**
|
|
50
|
+
* The group extension marking a `groups.restore` adoption whose self-update has not confirmed yet: written in the
|
|
51
|
+
* adoption transaction (with the snapshot's `clientState`), deleted in the confirmation transaction of an own
|
|
52
|
+
* self-update (pipeline.ts `confirmRecord`) — so a crash, or a dispose that could not wait for the group's queue,
|
|
53
|
+
* never leaves a half-restored group that a later client over the same stores would hold as if restored. A later
|
|
54
|
+
* client resumes such a group (group-runtime.ts `resumeRestore`: started by its startup scan and by every entry point
|
|
55
|
+
* that would read the group as held) — never discards it outright: the restore's self-update may already be on the
|
|
56
|
+
* relays, and only its record in these stores can confirm it.
|
|
57
|
+
*/
|
|
58
|
+
export const RESTORE_PENDING_EXTENSION = 'marmot.restorePending';
|
|
59
|
+
const RESTORE_PENDING_KEY = 'current';
|
|
60
|
+
/** Marks the group as adopted by a restore whose self-update has not confirmed. */
|
|
61
|
+
export async function writeRestorePending(view, at) {
|
|
62
|
+
await view.put(RESTORE_PENDING_KEY, { v: 1, at });
|
|
63
|
+
}
|
|
64
|
+
/** Whether the group is marked as an unfinished restore (any stored value counts: the safe side is to resume). */
|
|
65
|
+
export async function readRestorePending(view) {
|
|
66
|
+
return (await view.get(RESTORE_PENDING_KEY)) !== undefined;
|
|
67
|
+
}
|
|
68
|
+
/** Clears the unfinished-restore mark (a no-op when absent). */
|
|
69
|
+
export async function clearRestorePending(view) {
|
|
70
|
+
await view.delete(RESTORE_PENDING_KEY);
|
|
71
|
+
}
|
|
72
|
+
// ---------------------------------------------------------------------------
|
|
73
|
+
// Restore adoptions in progress (AccountStore extension `marmot.restoring`, keyed by group id) — AC-MX-2
|
|
74
|
+
// ---------------------------------------------------------------------------
|
|
75
|
+
/**
|
|
76
|
+
* The account extension naming every `groups.restore` adoption that has not got its account group-index entry yet.
|
|
77
|
+
* The startup scan otherwise walks the group index only, and the adoption writes the group store (snapshot state,
|
|
78
|
+
* key material, the {@link RESTORE_PENDING_EXTENSION} mark) BEFORE that entry: a crash in between would leave a
|
|
79
|
+
* group store no later client ever finds. So the adoption runs as three transactions, each a separate one (never
|
|
80
|
+
* nested — the cross-scope lock order is group → account, and this order starts on the account):
|
|
81
|
+
* 1. account: this record (nothing of the group written yet);
|
|
82
|
+
* 2. group: the snapshot's state, rewind window, cursor and the unfinished-restore mark;
|
|
83
|
+
* 3. account: the group-index entry, and this record deleted — atomically.
|
|
84
|
+
* Every crash point leaves a state the scan finds and settles (group-runtime.ts `settleRestoringRecord`): after 1, a
|
|
85
|
+
* record without a mark (dropped); after 2, a marked group without an index entry (discarded — nothing was ever
|
|
86
|
+
* recorded for it — its group store wiped, then this record); after 3, an indexed marked group (resumed).
|
|
87
|
+
*
|
|
88
|
+
* A failed restore's take-back (group-runtime.ts `clearAdoptedGroup`) runs the reverse, with this record as its
|
|
89
|
+
* durable cleanup marker: 1. account: this record (re-)written; 2. group: the store cleared; 3. account: the
|
|
90
|
+
* group-index entry and this record deleted — atomically. After 1 the group is still marked (resumed); after 2 the
|
|
91
|
+
* record names an empty group store (no state, no mark) whose index entry the scan deletes with the record — never
|
|
92
|
+
* an index entry left naming a group nothing holds and no scan revisits.
|
|
93
|
+
*/
|
|
94
|
+
export const RESTORING_EXTENSION = 'marmot.restoring';
|
|
95
|
+
/** Records that `groupId` is being adopted by a restore (step 1 above). */
|
|
96
|
+
export async function writeRestoringRecord(view, groupId, at) {
|
|
97
|
+
await view.put(groupId, { v: 1, at });
|
|
98
|
+
}
|
|
99
|
+
/** Deletes `groupId`'s restore record (a no-op when absent). */
|
|
100
|
+
export async function clearRestoringRecord(view, groupId) {
|
|
101
|
+
await view.delete(groupId);
|
|
102
|
+
}
|
|
103
|
+
/** Every group id with a restore record (any stored value counts: the safe side is to settle it). */
|
|
104
|
+
export async function listRestoringRecords(view) {
|
|
105
|
+
return view.keys();
|
|
106
|
+
}
|
|
107
|
+
// ---------------------------------------------------------------------------
|
|
108
|
+
// Post-load ratchet-skip marker (group extension `marmot.ratchetSkip`, key 'current') — AC-RATCH-1
|
|
109
|
+
// ---------------------------------------------------------------------------
|
|
110
|
+
/**
|
|
111
|
+
* The group extension holding the last post-load ratchet skip: written in the staging transaction of the skipped
|
|
112
|
+
* application message (next to the advanced `clientState`), marked `delivered` once a relay accepted an own
|
|
113
|
+
* application message at or after the skipped generation on the same epoch state. A load re-arms the skip unless
|
|
114
|
+
* the marker names the loaded epoch state, is undelivered, and the loaded ratchet already holds the skipped
|
|
115
|
+
* generation — so skips never pile up while nothing reaches a relay (every receiver's gap stays within one margin
|
|
116
|
+
* plus the undelivered messages), while a restore of a state without that marker (an older backup) still skips.
|
|
117
|
+
*/
|
|
118
|
+
export const RATCHET_SKIP_EXTENSION = 'marmot.ratchetSkip';
|
|
119
|
+
const RATCHET_SKIP_KEY = 'current';
|
|
120
|
+
/** The stored marker; `undefined` when absent or unreadable (an unreadable marker re-arms the skip, the safe side for reuse). */
|
|
121
|
+
export async function readRatchetSkipMarker(view) {
|
|
122
|
+
const raw = await view.get(RATCHET_SKIP_KEY);
|
|
123
|
+
if (typeof raw !== 'object' || raw === null || Array.isArray(raw) || raw instanceof Uint8Array)
|
|
124
|
+
return undefined;
|
|
125
|
+
const r = raw;
|
|
126
|
+
if (typeof r.epoch !== 'bigint' || typeof r.tag !== 'string' || typeof r.generation !== 'number' || typeof r.delivered !== 'boolean')
|
|
127
|
+
return undefined;
|
|
128
|
+
return { epoch: r.epoch, tag: r.tag, generation: r.generation, delivered: r.delivered };
|
|
129
|
+
}
|
|
130
|
+
export async function writeRatchetSkipMarker(view, marker) {
|
|
131
|
+
await view.put(RATCHET_SKIP_KEY, { epoch: marker.epoch, tag: marker.tag, generation: marker.generation, delivered: marker.delivered });
|
|
132
|
+
}
|
|
133
|
+
/**
|
|
134
|
+
* Marks the stored marker delivered when `ordering` (an own application message a relay just accepted) was sent on
|
|
135
|
+
* the marker's epoch state at or after its skipped generation. A message whose generation could not be read
|
|
136
|
+
* (`-1`) or with no ordering key never marks it. Returns whether it marked it.
|
|
137
|
+
*/
|
|
138
|
+
export async function markRatchetSkipDelivered(view, ordering) {
|
|
139
|
+
if (ordering === undefined)
|
|
140
|
+
return false;
|
|
141
|
+
const marker = await readRatchetSkipMarker(view);
|
|
142
|
+
if (marker === undefined || marker.delivered)
|
|
143
|
+
return false;
|
|
144
|
+
if (ordering.epoch !== marker.epoch || ordering.acceptedDigest !== marker.tag || ordering.generation < marker.generation)
|
|
145
|
+
return false;
|
|
146
|
+
await writeRatchetSkipMarker(view, { ...marker, delivered: true });
|
|
147
|
+
return true;
|
|
148
|
+
}
|
|
149
|
+
/**
|
|
150
|
+
* Whether a load of a state at (`epoch`, `tag`) whose own ratchet's next generation is `nextGeneration` re-arms the
|
|
151
|
+
* post-load skip, given the stored `marker`.
|
|
152
|
+
*/
|
|
153
|
+
export function ratchetSkipArmed(marker, epoch, tag, nextGeneration) {
|
|
154
|
+
if (marker === undefined || marker.delivered)
|
|
155
|
+
return true;
|
|
156
|
+
// An undelivered skip of THIS epoch state the loaded ratchet already holds: skipping again would only widen the
|
|
157
|
+
// gap receivers must jump. Any other epoch state (an epoch change, a rewind) or an older state re-arms.
|
|
158
|
+
return !(marker.epoch === epoch && marker.tag === tag && nextGeneration > marker.generation);
|
|
159
|
+
}
|
|
160
|
+
/** Removes the group's persisted `ClientState` (undoes a `groups.create` that could not be indexed). */
|
|
161
|
+
export async function deleteGroupState(view) {
|
|
162
|
+
await view.delete(CLIENT_STATE_KEY);
|
|
163
|
+
}
|
|
164
|
+
// ---------------------------------------------------------------------------
|
|
165
|
+
// Account-level group index (AccountStore extension `marmot.groups`) — the
|
|
166
|
+
// account artifact set (AC-STORE-9) has no dedicated group-list artifact, so
|
|
167
|
+
// S3 uses an extension namespace for it (see spec Amendments / AC-STORE-9).
|
|
168
|
+
// ---------------------------------------------------------------------------
|
|
169
|
+
export const GROUP_INDEX_EXTENSION = 'marmot.groups';
|
|
170
|
+
function malformedIndex(groupId) {
|
|
171
|
+
return new MarmotError('store-failed', `group index: malformed entry for ${groupId}`, { details: { groupId, malformed: true } });
|
|
172
|
+
}
|
|
173
|
+
export async function readGroupIndexEntry(view, groupId) {
|
|
174
|
+
const raw = await view.get(groupId);
|
|
175
|
+
if (raw === undefined)
|
|
176
|
+
return undefined;
|
|
177
|
+
if (typeof raw !== 'object' || raw === null || Array.isArray(raw) || typeof raw.createdAt !== 'number') {
|
|
178
|
+
throw malformedIndex(groupId);
|
|
179
|
+
}
|
|
180
|
+
const adoptedBy = raw.adoptedBy;
|
|
181
|
+
return { createdAt: raw.createdAt, ...(typeof adoptedBy === 'string' ? { adoptedBy } : {}) };
|
|
182
|
+
}
|
|
183
|
+
export async function writeGroupIndexEntry(view, groupId, entry) {
|
|
184
|
+
await view.put(groupId, { createdAt: entry.createdAt, ...(entry.adoptedBy === undefined ? {} : { adoptedBy: entry.adoptedBy }) });
|
|
185
|
+
}
|
|
186
|
+
/** Every indexed group id. */
|
|
187
|
+
export async function listGroupIndex(view) {
|
|
188
|
+
return view.keys();
|
|
189
|
+
}
|
|
190
|
+
const isHexString = (v) => typeof v === 'string' && v.length > 0 && v.length % 2 === 0 && /^[0-9a-f]+$/.test(v);
|
|
191
|
+
/** Strict decoder of an {@link AdmissionTarget}: exactly its members, each well-formed; `fail` builds the error. */
|
|
192
|
+
export function decodeAdmissionTarget(raw, at, fail) {
|
|
193
|
+
if (!isObject(raw))
|
|
194
|
+
throw fail(`${at} not an object`);
|
|
195
|
+
onlyMembers(raw, ['candidateId', 'anchor', 'acceptedAtTag', 'account'], at, fail);
|
|
196
|
+
const { candidateId, anchor, acceptedAtTag, account } = raw;
|
|
197
|
+
if (!isHex64(candidateId))
|
|
198
|
+
throw fail(`${at}.candidateId invalid`);
|
|
199
|
+
if (!isHexString(acceptedAtTag))
|
|
200
|
+
throw fail(`${at}.acceptedAtTag invalid`);
|
|
201
|
+
if (!isAccountPubkey(account))
|
|
202
|
+
throw fail(`${at}.account invalid`);
|
|
203
|
+
if (!isObject(anchor))
|
|
204
|
+
throw fail(`${at}.anchor invalid`);
|
|
205
|
+
onlyMembers(anchor, ['addDigest', 'addTag', 'commitEventId', 'leafIndex', 'leafKey'], `${at}.anchor`, fail);
|
|
206
|
+
const { addDigest, addTag, commitEventId, leafIndex, leafKey } = anchor;
|
|
207
|
+
if (!isHex64(addDigest) || !isHexString(addTag) || typeof commitEventId !== 'string' || commitEventId.length === 0 || typeof leafIndex !== 'number' || !Number.isSafeInteger(leafIndex) || leafIndex < 0 || !isHexString(leafKey)) {
|
|
208
|
+
throw fail(`${at}.anchor invalid`);
|
|
209
|
+
}
|
|
210
|
+
return { candidateId, anchor: { addDigest, addTag, commitEventId, leafIndex, leafKey }, acceptedAtTag, account };
|
|
211
|
+
}
|
|
212
|
+
/** The `Storable` form of an {@link AdmissionTarget} (re-checked: a mis-shaped write is refused like a mis-shaped read). */
|
|
213
|
+
export function encodeAdmissionTarget(target, fail) {
|
|
214
|
+
const { anchor } = target;
|
|
215
|
+
const raw = {
|
|
216
|
+
candidateId: target.candidateId,
|
|
217
|
+
anchor: { addDigest: anchor.addDigest, addTag: anchor.addTag, commitEventId: anchor.commitEventId, leafIndex: anchor.leafIndex, leafKey: anchor.leafKey },
|
|
218
|
+
acceptedAtTag: target.acceptedAtTag,
|
|
219
|
+
account: target.account,
|
|
220
|
+
};
|
|
221
|
+
decodeAdmissionTarget(raw, 'removeAdmission', fail);
|
|
222
|
+
return raw;
|
|
223
|
+
}
|
|
224
|
+
/**
|
|
225
|
+
* A commit re-drive record (S1): the durable record a withdrawal writes for a withdrawn own commit — a `commit` carrying
|
|
226
|
+
* `changes` (DD15; the decoder and the encoder enforce `changes` => `{ type: 'commit' }` + `reenqueuedFrom`). The
|
|
227
|
+
* self-update re-enqueue paths (AC-RACE-1) must neither pick it up nor count it among their siblings.
|
|
228
|
+
*/
|
|
229
|
+
export function isCommitRedrive(record) {
|
|
230
|
+
return record.changes !== undefined;
|
|
231
|
+
}
|
|
232
|
+
function malformed(intentId, detail, cause) {
|
|
233
|
+
return new MarmotError('store-failed', `pendingIntents/${intentId}: malformed record (${detail})`, { details: { intentId, malformed: true }, ...(cause === undefined ? {} : { cause }) });
|
|
234
|
+
}
|
|
235
|
+
function decodeStorableIntent(intentId, raw) {
|
|
236
|
+
if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
|
|
237
|
+
throw malformed(intentId, 'intent not an object');
|
|
238
|
+
const type = raw.type;
|
|
239
|
+
switch (type) {
|
|
240
|
+
case 'application': {
|
|
241
|
+
const rumor = raw.rumor;
|
|
242
|
+
if (rumor === undefined)
|
|
243
|
+
throw malformed(intentId, 'intent.rumor missing');
|
|
244
|
+
return { type: 'application', rumor: rumor };
|
|
245
|
+
}
|
|
246
|
+
case 'proposal': {
|
|
247
|
+
const proposal = raw.proposal;
|
|
248
|
+
if (proposal === undefined)
|
|
249
|
+
throw malformed(intentId, 'intent.proposal missing');
|
|
250
|
+
return { type: 'proposal', proposal: proposal };
|
|
251
|
+
}
|
|
252
|
+
case 'commit': {
|
|
253
|
+
const invite = raw.invite;
|
|
254
|
+
const removeLeafKeys = raw.removeLeafKeys;
|
|
255
|
+
if (removeLeafKeys !== undefined && (!Array.isArray(removeLeafKeys) || !removeLeafKeys.every((k) => typeof k === 'string'))) {
|
|
256
|
+
throw malformed(intentId, 'intent.removeLeafKeys invalid');
|
|
257
|
+
}
|
|
258
|
+
const admins = raw.admins;
|
|
259
|
+
if (admins !== undefined && (!Array.isArray(admins) || admins.length === 0 || !admins.every((k) => typeof k === 'string'))) {
|
|
260
|
+
throw malformed(intentId, 'intent.admins invalid');
|
|
261
|
+
}
|
|
262
|
+
const removeAccounts = raw.removeAccounts;
|
|
263
|
+
if (removeAccounts !== undefined && (!Array.isArray(removeAccounts) || removeAccounts.length === 0 || !removeAccounts.every(isAccountPubkey))) {
|
|
264
|
+
throw malformed(intentId, 'intent.removeAccounts invalid');
|
|
265
|
+
}
|
|
266
|
+
const removeAccountLeafKeys = raw.removeAccountLeafKeys;
|
|
267
|
+
if ((removeAccounts === undefined) !== (removeAccountLeafKeys === undefined) ||
|
|
268
|
+
(removeAccountLeafKeys !== undefined && (!Array.isArray(removeAccountLeafKeys) || removeAccountLeafKeys.length === 0 || !removeAccountLeafKeys.every(isHex64)))) {
|
|
269
|
+
throw malformed(intentId, 'intent.removeAccountLeafKeys invalid');
|
|
270
|
+
}
|
|
271
|
+
const origin = raw.origin;
|
|
272
|
+
if (origin !== undefined && origin !== 'approval')
|
|
273
|
+
throw malformed(intentId, 'intent.origin invalid');
|
|
274
|
+
const componentsRaw = raw.components;
|
|
275
|
+
const components = componentsRaw === undefined ? undefined : checkComponents(componentsRaw, (detail) => malformed(intentId, detail));
|
|
276
|
+
const profileRaw = raw.profile;
|
|
277
|
+
checkNoProfileClash(profileRaw !== undefined, components, (detail) => malformed(intentId, detail));
|
|
278
|
+
const removeAdmissionRaw = raw.removeAdmission;
|
|
279
|
+
const removeAdmission = removeAdmissionRaw === undefined ? undefined : decodeAdmissionTarget(removeAdmissionRaw, 'intent.removeAdmission', (detail) => malformed(intentId, detail));
|
|
280
|
+
// S5 (SC-5): a scoped cleanup is exclusive with every other member of a commit intent.
|
|
281
|
+
if (removeAdmission !== undefined && Object.entries(raw).some(([k, v]) => k !== 'type' && k !== 'removeAdmission' && v !== undefined))
|
|
282
|
+
throw malformed(intentId, 'intent.removeAdmission beside another member');
|
|
283
|
+
let profile;
|
|
284
|
+
if (profileRaw !== undefined) {
|
|
285
|
+
const { name, description } = (typeof profileRaw === 'object' && profileRaw !== null ? profileRaw : {});
|
|
286
|
+
if (typeof name !== 'string' || typeof description !== 'string')
|
|
287
|
+
throw malformed(intentId, 'intent.profile invalid');
|
|
288
|
+
// A record the pipeline wrote always passed `rename`'s validation; one outside the component's limits was altered at rest,
|
|
289
|
+
// and the encoder would throw when it is built — it is refused here instead, as a malformed intent.
|
|
290
|
+
try {
|
|
291
|
+
assertGroupProfile('intent.profile', name, description);
|
|
292
|
+
}
|
|
293
|
+
catch (cause) {
|
|
294
|
+
throw malformed(intentId, 'intent.profile outside the group-profile limits', cause);
|
|
295
|
+
}
|
|
296
|
+
profile = { name, description };
|
|
297
|
+
}
|
|
298
|
+
return {
|
|
299
|
+
type: 'commit',
|
|
300
|
+
...(invite === undefined ? {} : { invite: decodeInviteIntent(intentId, invite) }),
|
|
301
|
+
...(removeLeafKeys === undefined ? {} : { removeLeafKeys: removeLeafKeys }),
|
|
302
|
+
...(admins === undefined ? {} : { admins: admins }),
|
|
303
|
+
...(profile === undefined ? {} : { profile }),
|
|
304
|
+
...(removeAccounts === undefined ? {} : { removeAccounts: removeAccounts, removeAccountLeafKeys: removeAccountLeafKeys }),
|
|
305
|
+
...(origin === undefined ? {} : { origin }),
|
|
306
|
+
...(components === undefined ? {} : { components }),
|
|
307
|
+
...(removeAdmission === undefined ? {} : { removeAdmission }),
|
|
308
|
+
};
|
|
309
|
+
}
|
|
310
|
+
case 'self-update': {
|
|
311
|
+
const after = raw.after;
|
|
312
|
+
if (after !== undefined && typeof after !== 'string')
|
|
313
|
+
throw malformed(intentId, 'intent.after invalid');
|
|
314
|
+
const rekey = decodeRekey(intentId, raw.rekey);
|
|
315
|
+
return { type: 'self-update', ...(after === undefined ? {} : { after }), ...(rekey === undefined ? {} : { rekey }) };
|
|
316
|
+
}
|
|
317
|
+
default:
|
|
318
|
+
throw malformed(intentId, `unknown intent.type ${JSON.stringify(type)}`);
|
|
319
|
+
}
|
|
320
|
+
}
|
|
321
|
+
/** AC-REKEY-1: `{ target }` with a 64-char lower-case hex target and nothing else; any other shape is `malformed`. */
|
|
322
|
+
function decodeRekey(intentId, raw) {
|
|
323
|
+
if (raw === undefined)
|
|
324
|
+
return undefined;
|
|
325
|
+
if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
|
|
326
|
+
throw malformed(intentId, 'intent.rekey invalid');
|
|
327
|
+
const keys = Object.keys(raw);
|
|
328
|
+
const target = raw.target;
|
|
329
|
+
if (keys.length !== 1 || keys[0] !== 'target' || typeof target !== 'string' || !isHex64(target))
|
|
330
|
+
throw malformed(intentId, 'intent.rekey invalid');
|
|
331
|
+
return { target };
|
|
332
|
+
}
|
|
333
|
+
/**
|
|
334
|
+
* The `components` rule, shared by the decoder and the writer: a non-empty array of `{ id, data }` (no other member),
|
|
335
|
+
* `id` an integer in the u16 range, `data` bytes or `null`, ids unique.
|
|
336
|
+
*/
|
|
337
|
+
function checkComponents(raw, fail) {
|
|
338
|
+
if (!Array.isArray(raw) || raw.length === 0)
|
|
339
|
+
throw fail('intent.components invalid');
|
|
340
|
+
const out = raw.map((entry) => {
|
|
341
|
+
if (!isObject(entry))
|
|
342
|
+
throw fail('intent.components entry invalid');
|
|
343
|
+
onlyMembers(entry, ['id', 'data'], 'intent.components entry', fail);
|
|
344
|
+
const { id, data } = entry;
|
|
345
|
+
if (typeof id !== 'number' || !isComponentId(id) || !isBytesOrNull(data))
|
|
346
|
+
throw fail('intent.components entry invalid');
|
|
347
|
+
return { id, data };
|
|
348
|
+
});
|
|
349
|
+
if (new Set(out.map((c) => c.id)).size !== out.length)
|
|
350
|
+
throw fail('intent.components invalid');
|
|
351
|
+
// The admin list has its own typed field (`admins`, validated against the tree): a raw update of it would bypass that.
|
|
352
|
+
if (out.some((c) => c.id === GROUP_ADMIN_POLICY_COMPONENT_ID))
|
|
353
|
+
throw fail('intent.components names the admin policy (use intent.admins)');
|
|
354
|
+
return out;
|
|
355
|
+
}
|
|
356
|
+
/** `profile` and a `components` entry for the same component would be two AppDataUpdates of `0x8001` in one commit (AC-RENAME-9). */
|
|
357
|
+
function checkNoProfileClash(hasProfile, components, fail) {
|
|
358
|
+
if (hasProfile && components?.some((c) => c.id === GROUP_PROFILE_COMPONENT_ID) === true)
|
|
359
|
+
throw fail('intent.components names the group profile beside intent.profile');
|
|
360
|
+
}
|
|
361
|
+
function decodeInviteIntent(intentId, raw) {
|
|
362
|
+
const invitees = typeof raw === 'object' && raw !== null ? raw.invitees : undefined;
|
|
363
|
+
if (!Array.isArray(invitees) || invitees.length === 0)
|
|
364
|
+
throw malformed(intentId, 'intent.invite.invitees invalid');
|
|
365
|
+
return {
|
|
366
|
+
invitees: invitees.map((entry) => {
|
|
367
|
+
const { event, inviteeRef } = (typeof entry === 'object' && entry !== null ? entry : {});
|
|
368
|
+
if (typeof event !== 'object' || event === null || typeof inviteeRef !== 'string')
|
|
369
|
+
throw malformed(intentId, 'intent.invite invitee invalid');
|
|
370
|
+
return { event: event, inviteeRef };
|
|
371
|
+
}),
|
|
372
|
+
};
|
|
373
|
+
}
|
|
374
|
+
function encodeStorableIntent(intentId, intent) {
|
|
375
|
+
switch (intent.type) {
|
|
376
|
+
case 'application':
|
|
377
|
+
return { type: 'application', rumor: intent.rumor };
|
|
378
|
+
case 'proposal':
|
|
379
|
+
return { type: 'proposal', proposal: intent.proposal };
|
|
380
|
+
case 'commit': {
|
|
381
|
+
checkNoProfileClash(intent.profile !== undefined, intent.components, (detail) => malformed(intentId, detail));
|
|
382
|
+
if (intent.removeAdmission !== undefined && Object.entries(intent).some(([k, v]) => k !== 'type' && k !== 'removeAdmission' && v !== undefined))
|
|
383
|
+
throw malformed(intentId, 'intent.removeAdmission beside another member');
|
|
384
|
+
return {
|
|
385
|
+
type: 'commit',
|
|
386
|
+
...(intent.invite === undefined ? {} : { invite: { invitees: intent.invite.invitees.map((i) => ({ event: i.event, inviteeRef: i.inviteeRef })) } }),
|
|
387
|
+
...(intent.removeLeafKeys === undefined ? {} : { removeLeafKeys: [...intent.removeLeafKeys] }),
|
|
388
|
+
...(intent.admins === undefined ? {} : { admins: [...intent.admins] }),
|
|
389
|
+
...(intent.profile === undefined ? {} : { profile: { name: intent.profile.name, description: intent.profile.description } }),
|
|
390
|
+
...(intent.removeAccounts === undefined ? {} : { removeAccounts: [...intent.removeAccounts], removeAccountLeafKeys: [...(intent.removeAccountLeafKeys ?? [])] }),
|
|
391
|
+
...(intent.origin === undefined ? {} : { origin: intent.origin }),
|
|
392
|
+
...(intent.components === undefined ? {} : { components: checkComponents(intent.components, (detail) => malformed(intentId, detail)) }),
|
|
393
|
+
...(intent.removeAdmission === undefined ? {} : { removeAdmission: encodeAdmissionTarget(intent.removeAdmission, (detail) => malformed(intentId, detail)) }),
|
|
394
|
+
};
|
|
395
|
+
}
|
|
396
|
+
case 'self-update':
|
|
397
|
+
return {
|
|
398
|
+
type: 'self-update',
|
|
399
|
+
...(intent.after === undefined ? {} : { after: intent.after }),
|
|
400
|
+
...(intent.rekey === undefined ? {} : { rekey: { target: intent.rekey.target } }),
|
|
401
|
+
};
|
|
402
|
+
}
|
|
403
|
+
}
|
|
404
|
+
function decodePending(intentId, raw) {
|
|
405
|
+
if (raw === undefined)
|
|
406
|
+
return undefined;
|
|
407
|
+
if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
|
|
408
|
+
throw malformed(intentId, 'pending not an object');
|
|
409
|
+
const r = raw;
|
|
410
|
+
const kind = r.kind;
|
|
411
|
+
if (kind !== 'proposal' && kind !== 'commit' && kind !== 'selfUpdate')
|
|
412
|
+
throw malformed(intentId, 'pending.kind invalid');
|
|
413
|
+
const newState = r.newState;
|
|
414
|
+
if (!(newState instanceof Uint8Array))
|
|
415
|
+
throw malformed(intentId, 'pending.newState missing');
|
|
416
|
+
const parentState = r.parentState;
|
|
417
|
+
if (parentState !== undefined && !(parentState instanceof Uint8Array))
|
|
418
|
+
throw malformed(intentId, 'pending.parentState invalid');
|
|
419
|
+
const commitMessage = r.commitMessage;
|
|
420
|
+
if (commitMessage !== undefined && !(commitMessage instanceof Uint8Array))
|
|
421
|
+
throw malformed(intentId, 'pending.commitMessage invalid');
|
|
422
|
+
const ownCommit = r.ownCommit;
|
|
423
|
+
if (ownCommit !== undefined && !(ownCommit instanceof Uint8Array))
|
|
424
|
+
throw malformed(intentId, 'pending.ownCommit invalid');
|
|
425
|
+
return {
|
|
426
|
+
kind,
|
|
427
|
+
newState,
|
|
428
|
+
...(parentState === undefined ? {} : { parentState }),
|
|
429
|
+
...(commitMessage === undefined ? {} : { commitMessage }),
|
|
430
|
+
...(ownCommit === undefined ? {} : { ownCommit }),
|
|
431
|
+
};
|
|
432
|
+
}
|
|
433
|
+
function encodePending(pending) {
|
|
434
|
+
return {
|
|
435
|
+
kind: pending.kind,
|
|
436
|
+
newState: pending.newState,
|
|
437
|
+
...(pending.parentState === undefined ? {} : { parentState: pending.parentState }),
|
|
438
|
+
...(pending.commitMessage === undefined ? {} : { commitMessage: pending.commitMessage }),
|
|
439
|
+
...(pending.ownCommit === undefined ? {} : { ownCommit: pending.ownCommit }),
|
|
440
|
+
};
|
|
441
|
+
}
|
|
442
|
+
export function decodePendingIntentRecord(intentId, raw) {
|
|
443
|
+
if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
|
|
444
|
+
throw malformed(intentId, 'record not an object');
|
|
445
|
+
const r = raw;
|
|
446
|
+
if (r.v !== 1)
|
|
447
|
+
throw malformed(intentId, 'v mismatch');
|
|
448
|
+
if (typeof r.intentId !== 'string' || r.intentId !== intentId)
|
|
449
|
+
throw malformed(intentId, 'intentId mismatch');
|
|
450
|
+
if (typeof r.seq !== 'number')
|
|
451
|
+
throw malformed(intentId, 'seq missing');
|
|
452
|
+
const kind = r.kind;
|
|
453
|
+
if (kind !== 'application' && kind !== 'proposal' && kind !== 'commit' && kind !== 'self-update')
|
|
454
|
+
throw malformed(intentId, 'kind invalid');
|
|
455
|
+
const state = r.state;
|
|
456
|
+
if (state !== 'pending-publish' && state !== 'pending-confirm' && state !== 'awaiting-sync')
|
|
457
|
+
throw malformed(intentId, 'state invalid');
|
|
458
|
+
if (typeof r.parentEpoch !== 'bigint')
|
|
459
|
+
throw malformed(intentId, 'parentEpoch missing');
|
|
460
|
+
if (typeof r.attempts !== 'number')
|
|
461
|
+
throw malformed(intentId, 'attempts missing');
|
|
462
|
+
const pending = decodePending(intentId, r.pending);
|
|
463
|
+
const welcomes = r.welcomes === undefined ? undefined : decodeStoredWelcomes(`pendingIntents/${intentId}`, r.welcomes);
|
|
464
|
+
const ordering = decodeOrdering(r.ordering);
|
|
465
|
+
if (r.reenqueuedFrom !== undefined && typeof r.reenqueuedFrom !== 'string')
|
|
466
|
+
throw malformed(intentId, 'reenqueuedFrom not a string');
|
|
467
|
+
if (r.retryAt !== undefined && typeof r.retryAt !== 'number')
|
|
468
|
+
throw malformed(intentId, 'retryAt not a number');
|
|
469
|
+
const failPending = (detail) => malformed(intentId, detail);
|
|
470
|
+
const changes = r.changes === undefined ? undefined : decodeStoredOwnChanges(r.changes, 'changes', failPending, true);
|
|
471
|
+
assertChangesPair(changes, r.forkEpoch, failPending);
|
|
472
|
+
const intent = decodeStorableIntent(intentId, r.intent);
|
|
473
|
+
if (changes !== undefined)
|
|
474
|
+
assertRedriveShape(kind, intent, r.reenqueuedFrom, failPending);
|
|
475
|
+
return {
|
|
476
|
+
v: 1,
|
|
477
|
+
intentId,
|
|
478
|
+
seq: r.seq,
|
|
479
|
+
kind,
|
|
480
|
+
state,
|
|
481
|
+
parentEpoch: r.parentEpoch,
|
|
482
|
+
intent,
|
|
483
|
+
...(r.envelope === undefined ? {} : { envelope: r.envelope }),
|
|
484
|
+
...(pending === undefined ? {} : { pending }),
|
|
485
|
+
...(welcomes === undefined ? {} : { welcomes }),
|
|
486
|
+
...(ordering === undefined ? {} : { ordering }),
|
|
487
|
+
attempts: r.attempts,
|
|
488
|
+
...(r.reenqueuedFrom === undefined ? {} : { reenqueuedFrom: r.reenqueuedFrom }),
|
|
489
|
+
...(r.retryAt === undefined ? {} : { retryAt: r.retryAt }),
|
|
490
|
+
...(changes === undefined ? {} : { changes }),
|
|
491
|
+
...(r.forkEpoch === undefined ? {} : { forkEpoch: r.forkEpoch }),
|
|
492
|
+
};
|
|
493
|
+
}
|
|
494
|
+
function decodeOrdering(raw) {
|
|
495
|
+
if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
|
|
496
|
+
return undefined;
|
|
497
|
+
const o = raw;
|
|
498
|
+
if (typeof o.account !== 'string' || typeof o.leafIndex !== 'number' || typeof o.epoch !== 'bigint' || typeof o.generation !== 'number' || typeof o.acceptedDigest !== 'string')
|
|
499
|
+
return undefined;
|
|
500
|
+
return Object.freeze({ account: o.account, leafIndex: o.leafIndex, epoch: o.epoch, generation: o.generation, acceptedDigest: o.acceptedDigest });
|
|
501
|
+
}
|
|
502
|
+
export function encodePendingIntentRecord(record) {
|
|
503
|
+
const failRecord = (detail) => malformed(record.intentId, detail);
|
|
504
|
+
assertChangesPair(record.changes, record.forkEpoch, failRecord);
|
|
505
|
+
if (record.changes !== undefined)
|
|
506
|
+
assertRedriveShape(record.kind, record.intent, record.reenqueuedFrom, failRecord);
|
|
507
|
+
return {
|
|
508
|
+
v: 1,
|
|
509
|
+
intentId: record.intentId,
|
|
510
|
+
seq: record.seq,
|
|
511
|
+
kind: record.kind,
|
|
512
|
+
state: record.state,
|
|
513
|
+
parentEpoch: record.parentEpoch,
|
|
514
|
+
intent: encodeStorableIntent(record.intentId, record.intent),
|
|
515
|
+
...(record.envelope === undefined ? {} : { envelope: record.envelope }),
|
|
516
|
+
...(record.pending === undefined ? {} : { pending: encodePending(record.pending) }),
|
|
517
|
+
...(record.welcomes === undefined ? {} : { welcomes: encodeStoredWelcomes(record.welcomes) }),
|
|
518
|
+
...(record.ordering === undefined
|
|
519
|
+
? {}
|
|
520
|
+
: { ordering: { account: record.ordering.account, leafIndex: record.ordering.leafIndex, epoch: record.ordering.epoch, generation: record.ordering.generation, acceptedDigest: record.ordering.acceptedDigest } }),
|
|
521
|
+
attempts: record.attempts,
|
|
522
|
+
...(record.reenqueuedFrom === undefined ? {} : { reenqueuedFrom: record.reenqueuedFrom }),
|
|
523
|
+
...(record.retryAt === undefined ? {} : { retryAt: record.retryAt }),
|
|
524
|
+
...(record.changes === undefined ? {} : { changes: encodeStoredOwnChanges(record.changes, true) }),
|
|
525
|
+
...(record.forkEpoch === undefined ? {} : { forkEpoch: record.forkEpoch }),
|
|
526
|
+
};
|
|
527
|
+
}
|
|
528
|
+
export async function readPendingIntentRecord(view, intentId) {
|
|
529
|
+
const raw = await view.get(intentId);
|
|
530
|
+
if (raw === undefined)
|
|
531
|
+
return undefined;
|
|
532
|
+
return decodePendingIntentRecord(intentId, raw);
|
|
533
|
+
}
|
|
534
|
+
export async function writePendingIntentRecord(view, record) {
|
|
535
|
+
await view.put(record.intentId, encodePendingIntentRecord(record));
|
|
536
|
+
}
|
|
537
|
+
export async function deletePendingIntentRecord(view, intentId) {
|
|
538
|
+
await view.delete(intentId);
|
|
539
|
+
}
|
|
540
|
+
/** Every pending-intent record, ordered by `seq` (ascending — creation order). */
|
|
541
|
+
export async function listPendingIntentRecords(view) {
|
|
542
|
+
const ids = await view.keys();
|
|
543
|
+
const records = [];
|
|
544
|
+
for (const id of ids) {
|
|
545
|
+
const record = await readPendingIntentRecord(view, id);
|
|
546
|
+
if (record !== undefined)
|
|
547
|
+
records.push(record);
|
|
548
|
+
}
|
|
549
|
+
records.sort((a, b) => a.seq - b.seq);
|
|
550
|
+
return records;
|
|
551
|
+
}
|
|
552
|
+
/** `{ intentId, state, kind }` for every pending intent, ordered by `seq` (AC-PIPE-1). */
|
|
553
|
+
export async function listPendingIntentSummaries(view) {
|
|
554
|
+
const records = await listPendingIntentRecords(view);
|
|
555
|
+
return records.map((r) => ({ intentId: r.intentId, state: r.state, kind: r.kind }));
|
|
556
|
+
}
|
|
557
|
+
/** The next `seq` to assign: max existing `seq` + 1 (1 when the group has no pending intents yet). */
|
|
558
|
+
export async function nextSeq(view) {
|
|
559
|
+
const records = await listPendingIntentRecords(view);
|
|
560
|
+
let max = 0;
|
|
561
|
+
for (const r of records)
|
|
562
|
+
if (r.seq > max)
|
|
563
|
+
max = r.seq;
|
|
564
|
+
return max + 1;
|
|
565
|
+
}
|
|
566
|
+
function malformedQueued(queueId, detail) {
|
|
567
|
+
return new MarmotError('store-failed', `queuedRumors/${queueId}: malformed record (${detail})`, { details: { queueId, malformed: true } });
|
|
568
|
+
}
|
|
569
|
+
export function decodeQueuedRumorRecord(queueId, raw) {
|
|
570
|
+
if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
|
|
571
|
+
throw malformedQueued(queueId, 'record not an object');
|
|
572
|
+
const r = raw;
|
|
573
|
+
if (r.v !== 1 || r.queueId !== queueId)
|
|
574
|
+
throw malformedQueued(queueId, 'header');
|
|
575
|
+
if (typeof r.seq !== 'number' || typeof r.queuedAt !== 'number')
|
|
576
|
+
throw malformedQueued(queueId, 'seq/queuedAt');
|
|
577
|
+
if (typeof r.rumor !== 'object' || r.rumor === null)
|
|
578
|
+
throw malformedQueued(queueId, 'rumor');
|
|
579
|
+
if (r.barrier !== undefined && typeof r.barrier !== 'bigint')
|
|
580
|
+
throw malformedQueued(queueId, 'barrier');
|
|
581
|
+
return {
|
|
582
|
+
v: 1,
|
|
583
|
+
queueId,
|
|
584
|
+
seq: r.seq,
|
|
585
|
+
rumor: r.rumor,
|
|
586
|
+
...(r.barrier === undefined ? {} : { barrier: r.barrier }),
|
|
587
|
+
queuedAt: r.queuedAt,
|
|
588
|
+
};
|
|
589
|
+
}
|
|
590
|
+
export async function writeQueuedRumorRecord(view, record) {
|
|
591
|
+
await view.put(record.queueId, {
|
|
592
|
+
v: 1,
|
|
593
|
+
queueId: record.queueId,
|
|
594
|
+
seq: record.seq,
|
|
595
|
+
rumor: record.rumor,
|
|
596
|
+
...(record.barrier === undefined ? {} : { barrier: record.barrier }),
|
|
597
|
+
queuedAt: record.queuedAt,
|
|
598
|
+
});
|
|
599
|
+
}
|
|
600
|
+
export async function readQueuedRumorRecord(view, queueId) {
|
|
601
|
+
const raw = await view.get(queueId);
|
|
602
|
+
return raw === undefined ? undefined : decodeQueuedRumorRecord(queueId, raw);
|
|
603
|
+
}
|
|
604
|
+
/** Every queued rumor, in queue order. */
|
|
605
|
+
export async function listQueuedRumorRecords(view) {
|
|
606
|
+
const records = [];
|
|
607
|
+
for (const id of await view.keys()) {
|
|
608
|
+
const record = await readQueuedRumorRecord(view, id);
|
|
609
|
+
if (record !== undefined)
|
|
610
|
+
records.push(record);
|
|
611
|
+
}
|
|
612
|
+
records.sort((a, b) => a.seq - b.seq);
|
|
613
|
+
return records;
|
|
614
|
+
}
|
|
615
|
+
function malformedLedger(eventId) {
|
|
616
|
+
return new MarmotError('store-failed', `terminalLedger/${eventId}: malformed entry`, { details: { eventId, malformed: true } });
|
|
617
|
+
}
|
|
618
|
+
/** `ownCommitRoot` needs `node` and excludes `selfUpdateIntentId` / `rekey` — enforced by the reader and the writer alike. */
|
|
619
|
+
const ownCommitRootInvalid = (e) => e.ownCommitRoot !== undefined && (e.node === undefined || e.selfUpdateIntentId !== undefined || e.rekey !== undefined);
|
|
620
|
+
export async function readTerminalLedgerEntry(view, eventId) {
|
|
621
|
+
const raw = await view.get(eventId);
|
|
622
|
+
if (raw === undefined)
|
|
623
|
+
return undefined;
|
|
624
|
+
if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
|
|
625
|
+
throw malformedLedger(eventId);
|
|
626
|
+
const r = raw;
|
|
627
|
+
if (typeof r.disposition !== 'string' ||
|
|
628
|
+
typeof r.at !== 'number' ||
|
|
629
|
+
(r.createdAt !== undefined && typeof r.createdAt !== 'number') ||
|
|
630
|
+
(r.node !== undefined && typeof r.node !== 'string') ||
|
|
631
|
+
(r.selfUpdateIntentId !== undefined && typeof r.selfUpdateIntentId !== 'string') ||
|
|
632
|
+
(r.attempts !== undefined && typeof r.attempts !== 'number') ||
|
|
633
|
+
(r.rekey !== undefined && (typeof r.rekey !== 'string' || !isHex64(r.rekey))) ||
|
|
634
|
+
(r.ownCommitRoot !== undefined && typeof r.ownCommitRoot !== 'string')) {
|
|
635
|
+
throw malformedLedger(eventId);
|
|
636
|
+
}
|
|
637
|
+
if (ownCommitRootInvalid(r))
|
|
638
|
+
throw malformedLedger(eventId);
|
|
639
|
+
return {
|
|
640
|
+
disposition: r.disposition,
|
|
641
|
+
at: r.at,
|
|
642
|
+
...(r.createdAt === undefined ? {} : { createdAt: r.createdAt }),
|
|
643
|
+
...(r.node === undefined ? {} : { node: r.node }),
|
|
644
|
+
...(r.selfUpdateIntentId === undefined ? {} : { selfUpdateIntentId: r.selfUpdateIntentId }),
|
|
645
|
+
...(r.attempts === undefined ? {} : { attempts: r.attempts }),
|
|
646
|
+
...(r.rekey === undefined ? {} : { rekey: r.rekey }),
|
|
647
|
+
...(r.ownCommitRoot === undefined ? {} : { ownCommitRoot: r.ownCommitRoot }),
|
|
648
|
+
};
|
|
649
|
+
}
|
|
650
|
+
export async function writeTerminalLedgerEntry(view, eventId, entry) {
|
|
651
|
+
if (ownCommitRootInvalid(entry))
|
|
652
|
+
throw malformedLedger(eventId);
|
|
653
|
+
await view.put(eventId, {
|
|
654
|
+
disposition: entry.disposition,
|
|
655
|
+
at: entry.at,
|
|
656
|
+
...(entry.createdAt === undefined ? {} : { createdAt: entry.createdAt }),
|
|
657
|
+
...(entry.node === undefined ? {} : { node: entry.node }),
|
|
658
|
+
...(entry.selfUpdateIntentId === undefined ? {} : { selfUpdateIntentId: entry.selfUpdateIntentId }),
|
|
659
|
+
...(entry.attempts === undefined ? {} : { attempts: entry.attempts }),
|
|
660
|
+
...(entry.rekey === undefined ? {} : { rekey: entry.rekey }),
|
|
661
|
+
...(entry.ownCommitRoot === undefined ? {} : { ownCommitRoot: entry.ownCommitRoot }),
|
|
662
|
+
});
|
|
663
|
+
}
|
|
664
|
+
/**
|
|
665
|
+
* Retention: deletes every entry whose event `created_at` is below
|
|
666
|
+
* `belowCreatedAt`. The ingest cursor's `since` bounds what a relay can
|
|
667
|
+
* still redeliver, so an entry far below it no longer dedups anything the
|
|
668
|
+
* sync loop fetches; an older event fed to `ingest()` by hand falls back on
|
|
669
|
+
* the engine's own past-epoch / duplicate rules. Entries without a
|
|
670
|
+
* `createdAt` are kept, and so is every entry whose `node` is in `retained`
|
|
671
|
+
* (the stored rewind window's nodes, `retainedLedgerNodes`): a fork flip
|
|
672
|
+
* through that node still needs it for withdrawal detection and the
|
|
673
|
+
* self-update re-enqueue / cancel (ledger-retention-vs-rewind-horizon).
|
|
674
|
+
* Returns the number deleted.
|
|
675
|
+
*/
|
|
676
|
+
export async function pruneTerminalLedger(view, belowCreatedAt, retained = new Set()) {
|
|
677
|
+
let pruned = 0;
|
|
678
|
+
for (const eventId of await view.keys()) {
|
|
679
|
+
const entry = await readTerminalLedgerEntry(view, eventId);
|
|
680
|
+
if (entry?.createdAt !== undefined && entry.createdAt < belowCreatedAt && (entry.node === undefined || !retained.has(entry.node))) {
|
|
681
|
+
await view.delete(eventId);
|
|
682
|
+
pruned += 1;
|
|
683
|
+
}
|
|
684
|
+
}
|
|
685
|
+
return pruned;
|
|
686
|
+
}
|
|
687
|
+
const isObject = (raw) => typeof raw === 'object' && raw !== null && !Array.isArray(raw) && !(raw instanceof Uint8Array);
|
|
688
|
+
/** A component id: an integer in the u16 range. */
|
|
689
|
+
const isComponentId = (v) => Number.isInteger(v) && v >= 0 && v <= 0xffff;
|
|
690
|
+
const isForkEpoch = (v) => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0;
|
|
691
|
+
const isBytesOrNull = (v) => v === null || v instanceof Uint8Array;
|
|
692
|
+
function onlyMembers(obj, allowed, where, fail) {
|
|
693
|
+
for (const k of Object.keys(obj))
|
|
694
|
+
if (obj[k] !== undefined && !allowed.includes(k))
|
|
695
|
+
throw fail(`${where}.${k} not allowed`);
|
|
696
|
+
}
|
|
697
|
+
export function decodeOwnChange(raw, at, fail) {
|
|
698
|
+
if (!isObject(raw))
|
|
699
|
+
throw fail(`${at} not an object`);
|
|
700
|
+
switch (raw.type) {
|
|
701
|
+
case 'member-removed':
|
|
702
|
+
onlyMembers(raw, ['type', 'account'], at, fail);
|
|
703
|
+
if (!isAccountPubkey(raw.account))
|
|
704
|
+
throw fail(`${at}.account invalid`);
|
|
705
|
+
return { type: 'member-removed', account: raw.account };
|
|
706
|
+
case 'member-added':
|
|
707
|
+
onlyMembers(raw, ['type', 'account', 'leafKey'], at, fail);
|
|
708
|
+
if (!isAccountPubkey(raw.account) || !isHex64(raw.leafKey))
|
|
709
|
+
throw fail(`${at} member-added invalid`);
|
|
710
|
+
return { type: 'member-added', account: raw.account, leafKey: raw.leafKey };
|
|
711
|
+
case 'admin':
|
|
712
|
+
onlyMembers(raw, ['type', 'account', 'admin'], at, fail);
|
|
713
|
+
if (!isAccountPubkey(raw.account) || typeof raw.admin !== 'boolean')
|
|
714
|
+
throw fail(`${at} admin invalid`);
|
|
715
|
+
return { type: 'admin', account: raw.account, admin: raw.admin };
|
|
716
|
+
case 'component':
|
|
717
|
+
onlyMembers(raw, ['type', 'componentId'], at, fail);
|
|
718
|
+
if (typeof raw.componentId !== 'number' || !isComponentId(raw.componentId))
|
|
719
|
+
throw fail(`${at}.componentId invalid`);
|
|
720
|
+
return { type: 'component', componentId: raw.componentId };
|
|
721
|
+
case 'admission-removed':
|
|
722
|
+
onlyMembers(raw, ['type', 'account', 'leafKey', 'candidateId'], at, fail);
|
|
723
|
+
if (!isAccountPubkey(raw.account) || !isHexString(raw.leafKey) || !isHex64(raw.candidateId))
|
|
724
|
+
throw fail(`${at} admission-removed invalid`);
|
|
725
|
+
return { type: 'admission-removed', account: raw.account, leafKey: raw.leafKey, candidateId: raw.candidateId };
|
|
726
|
+
default:
|
|
727
|
+
throw fail(`${at}.type unknown`);
|
|
728
|
+
}
|
|
729
|
+
}
|
|
730
|
+
/**
|
|
731
|
+
* Strict decoder of one {@link StoredOwnChange}: a wrong type anywhere is a `store-failed` error built by `fail` (so
|
|
732
|
+
* the pending record and the marker each report under their own key). Shared by both records.
|
|
733
|
+
*/
|
|
734
|
+
export function decodeStoredOwnChange(raw, at, fail, allowVerdict = true) {
|
|
735
|
+
if (!isObject(raw))
|
|
736
|
+
throw fail(`${at} not an object`);
|
|
737
|
+
const change = decodeOwnChange(raw.change, `${at}.change`, fail);
|
|
738
|
+
const forkRaw = raw.fork;
|
|
739
|
+
if (!isObject(forkRaw))
|
|
740
|
+
throw fail(`${at}.fork invalid`);
|
|
741
|
+
if (!allowVerdict && raw.verdict !== undefined)
|
|
742
|
+
throw fail(`${at}.verdict not allowed`);
|
|
743
|
+
if (raw.winnerHeldInvitee !== undefined && typeof raw.winnerHeldInvitee !== 'boolean')
|
|
744
|
+
throw fail(`${at}.winnerHeldInvitee invalid`);
|
|
745
|
+
if (raw.winnerRemovedTarget !== undefined && typeof raw.winnerRemovedTarget !== 'boolean')
|
|
746
|
+
throw fail(`${at}.winnerRemovedTarget invalid`);
|
|
747
|
+
// Per kind: exactly the members that belong to it (a member of another kind is refused, a required one must be present).
|
|
748
|
+
const members = (obj, allowed, where) => {
|
|
749
|
+
for (const k of Object.keys(obj))
|
|
750
|
+
if (obj[k] !== undefined && !allowed.includes(k))
|
|
751
|
+
throw fail(`${where}.${k} not allowed for ${change.type}`);
|
|
752
|
+
};
|
|
753
|
+
members(raw, change.type === 'component'
|
|
754
|
+
? ['change', 'data', 'fork', 'verdict']
|
|
755
|
+
: change.type === 'member-added'
|
|
756
|
+
? ['change', 'fork', 'winnerHeldInvitee', 'keyPackage', 'verdict']
|
|
757
|
+
: change.type === 'member-removed'
|
|
758
|
+
? ['change', 'fork', 'winnerRemovedTarget', 'verdict']
|
|
759
|
+
: change.type === 'admission-removed'
|
|
760
|
+
? ['change', 'fork', 'target', 'verdict']
|
|
761
|
+
: ['change', 'fork', 'verdict'], at);
|
|
762
|
+
let data;
|
|
763
|
+
let keyPackage;
|
|
764
|
+
let target;
|
|
765
|
+
const fork = {};
|
|
766
|
+
switch (change.type) {
|
|
767
|
+
case 'component':
|
|
768
|
+
if (!isBytesOrNull(raw.data))
|
|
769
|
+
throw fail(`${at}.data invalid`);
|
|
770
|
+
if (!isBytesOrNull(forkRaw.component))
|
|
771
|
+
throw fail(`${at}.fork.component invalid`);
|
|
772
|
+
members(forkRaw, ['component'], `${at}.fork`);
|
|
773
|
+
data = raw.data;
|
|
774
|
+
fork.component = forkRaw.component;
|
|
775
|
+
break;
|
|
776
|
+
case 'admin':
|
|
777
|
+
if (typeof forkRaw.admin !== 'boolean')
|
|
778
|
+
throw fail(`${at}.fork.admin invalid`);
|
|
779
|
+
members(forkRaw, ['admin'], `${at}.fork`);
|
|
780
|
+
fork.admin = forkRaw.admin;
|
|
781
|
+
break;
|
|
782
|
+
case 'member-removed':
|
|
783
|
+
if (!Array.isArray(forkRaw.leafKeys) || !forkRaw.leafKeys.every(isHex64))
|
|
784
|
+
throw fail(`${at}.fork.leafKeys invalid`);
|
|
785
|
+
members(forkRaw, ['leafKeys'], `${at}.fork`);
|
|
786
|
+
fork.leafKeys = [...forkRaw.leafKeys];
|
|
787
|
+
break;
|
|
788
|
+
case 'member-added':
|
|
789
|
+
if (typeof forkRaw.held !== 'boolean')
|
|
790
|
+
throw fail(`${at}.fork.held invalid`);
|
|
791
|
+
members(forkRaw, ['held'], `${at}.fork`);
|
|
792
|
+
fork.held = forkRaw.held;
|
|
793
|
+
if (!isObject(raw.keyPackage))
|
|
794
|
+
throw fail(`${at}.keyPackage invalid`);
|
|
795
|
+
members(raw.keyPackage, ['event', 'inviteeRef'], `${at}.keyPackage`);
|
|
796
|
+
if (!isObject(raw.keyPackage.event) || typeof raw.keyPackage.inviteeRef !== 'string')
|
|
797
|
+
throw fail(`${at}.keyPackage invalid`);
|
|
798
|
+
keyPackage = { event: raw.keyPackage.event, inviteeRef: raw.keyPackage.inviteeRef };
|
|
799
|
+
break;
|
|
800
|
+
case 'admission-removed':
|
|
801
|
+
members(forkRaw, [], `${at}.fork`);
|
|
802
|
+
target = decodeAdmissionTarget(raw.target, `${at}.target`, fail);
|
|
803
|
+
// The change names exactly its target (I16): the same candidate, account and leaf.
|
|
804
|
+
if (target.candidateId !== change.candidateId || target.account !== change.account || target.anchor.leafKey !== change.leafKey)
|
|
805
|
+
throw fail(`${at}.target does not match the change`);
|
|
806
|
+
break;
|
|
807
|
+
}
|
|
808
|
+
const verdict = raw.verdict;
|
|
809
|
+
if (verdict !== undefined && verdict !== 'reapplied' && !OWN_CHANGE_LOST_REASONS.includes(verdict))
|
|
810
|
+
throw fail(`${at}.verdict invalid`);
|
|
811
|
+
return {
|
|
812
|
+
change,
|
|
813
|
+
...(data === undefined ? {} : { data }),
|
|
814
|
+
fork,
|
|
815
|
+
...(raw.winnerHeldInvitee === undefined ? {} : { winnerHeldInvitee: raw.winnerHeldInvitee }),
|
|
816
|
+
...(raw.winnerRemovedTarget === undefined ? {} : { winnerRemovedTarget: raw.winnerRemovedTarget }),
|
|
817
|
+
...(keyPackage === undefined ? {} : { keyPackage }),
|
|
818
|
+
...(target === undefined ? {} : { target }),
|
|
819
|
+
...(verdict === undefined ? {} : { verdict: verdict }),
|
|
820
|
+
};
|
|
821
|
+
}
|
|
822
|
+
/** The `Storable` form of a {@link StoredOwnChange}; absent members stay absent (so a decode re-encodes identically). */
|
|
823
|
+
export function encodeStoredOwnChange(c, allowVerdict = true) {
|
|
824
|
+
const loose = c;
|
|
825
|
+
const raw = {
|
|
826
|
+
change: { ...loose.change },
|
|
827
|
+
...(loose.data === undefined ? {} : { data: loose.data }),
|
|
828
|
+
fork: {
|
|
829
|
+
...(loose.fork.component === undefined ? {} : { component: loose.fork.component }),
|
|
830
|
+
...(loose.fork.admin === undefined ? {} : { admin: loose.fork.admin }),
|
|
831
|
+
...(loose.fork.leafKeys === undefined ? {} : { leafKeys: [...loose.fork.leafKeys] }),
|
|
832
|
+
...(loose.fork.held === undefined ? {} : { held: loose.fork.held }),
|
|
833
|
+
},
|
|
834
|
+
...(loose.winnerHeldInvitee === undefined ? {} : { winnerHeldInvitee: loose.winnerHeldInvitee }),
|
|
835
|
+
...(loose.winnerRemovedTarget === undefined ? {} : { winnerRemovedTarget: loose.winnerRemovedTarget }),
|
|
836
|
+
...(loose.keyPackage === undefined ? {} : { keyPackage: { event: loose.keyPackage.event, inviteeRef: loose.keyPackage.inviteeRef } }),
|
|
837
|
+
...(loose.target === undefined ? {} : { target: encodeAdmissionTarget(loose.target, (detail) => new MarmotError('store-failed', `StoredOwnChange: refusing to write a malformed change (${detail})`, { details: { malformed: true } })) }),
|
|
838
|
+
...(loose.verdict === undefined ? {} : { verdict: loose.verdict }),
|
|
839
|
+
};
|
|
840
|
+
// Defense in depth against a mis-shaped write that got past the type (a cast, untyped JS): the write-time check is the read-time rule.
|
|
841
|
+
decodeStoredOwnChange(raw, 'change', (detail) => new MarmotError('store-failed', `StoredOwnChange: refusing to write a malformed change (${detail})`, { details: { malformed: true } }), allowVerdict);
|
|
842
|
+
return raw;
|
|
843
|
+
}
|
|
844
|
+
function decodeStoredOwnChanges(raw, at, fail, allowVerdict) {
|
|
845
|
+
if (!Array.isArray(raw) || raw.length === 0)
|
|
846
|
+
throw fail(`${at} not a non-empty array`);
|
|
847
|
+
return raw.map((entry, i) => decodeStoredOwnChange(entry, `${at}[${String(i)}]`, fail, allowVerdict));
|
|
848
|
+
}
|
|
849
|
+
function encodeStoredOwnChanges(changes, allowVerdict) {
|
|
850
|
+
return changes.map((c) => encodeStoredOwnChange(c, allowVerdict));
|
|
851
|
+
}
|
|
852
|
+
/** `changes` and `forkEpoch` are written together (the removeAccounts / removeAccountLeafKeys convention); `changes` is never empty and `forkEpoch` a non-negative integer. */
|
|
853
|
+
function assertChangesPair(changes, forkEpoch, fail) {
|
|
854
|
+
if (forkEpoch !== undefined && !isForkEpoch(forkEpoch))
|
|
855
|
+
throw fail('forkEpoch not a non-negative integer');
|
|
856
|
+
if ((changes === undefined) !== (forkEpoch === undefined))
|
|
857
|
+
throw fail('changes and forkEpoch go together');
|
|
858
|
+
if (changes !== undefined && changes.length === 0)
|
|
859
|
+
throw fail('changes empty');
|
|
860
|
+
}
|
|
861
|
+
/**
|
|
862
|
+
* DD15: a record carrying `changes` is a re-drive record — a `commit` that re-enqueues a withdrawn own commit
|
|
863
|
+
* (`reenqueuedFrom` set) whose intent is exactly `{ type: 'commit' }`: no other member (invite, removals, admins,
|
|
864
|
+
* profile, origin, components).
|
|
865
|
+
*/
|
|
866
|
+
function assertRedriveShape(kind, intent, reenqueuedFrom, fail) {
|
|
867
|
+
if (kind !== 'commit' || intent.type !== 'commit')
|
|
868
|
+
throw fail('changes only on a commit record');
|
|
869
|
+
if (reenqueuedFrom === undefined)
|
|
870
|
+
throw fail('changes without reenqueuedFrom');
|
|
871
|
+
if (Object.entries(intent).some(([k, v]) => k !== 'type' && v !== undefined))
|
|
872
|
+
throw fail('changes with an intent beyond { type: commit }');
|
|
873
|
+
}
|
|
874
|
+
/**
|
|
875
|
+
* The group extension holding one {@link OwnCommitMarker} per confirmed own commit, keyed by the commit's event id —
|
|
876
|
+
* the same key as its terminal-ledger entry (whose `ownCommitRoot` flags it). Written by the confirming transaction
|
|
877
|
+
* (S9); read when a rewind withdraws the commit.
|
|
878
|
+
*/
|
|
879
|
+
export const OWN_COMMIT_EXTENSION = 'marmot.own-commit';
|
|
880
|
+
/** A declared set is non-empty: `removed` / `components` / `admissions` non-empty arrays (accounts, u16 ids, targets; no duplicates), `admins` only as `true`. */
|
|
881
|
+
function checkDeclared(raw, fail) {
|
|
882
|
+
if (!isObject(raw))
|
|
883
|
+
throw fail('declared not an object');
|
|
884
|
+
onlyMembers(raw, ['removed', 'admins', 'components', 'admissions'], 'declared', fail);
|
|
885
|
+
const { removed, admins, components } = raw;
|
|
886
|
+
let admissions;
|
|
887
|
+
if (raw.admissions !== undefined) {
|
|
888
|
+
if (!Array.isArray(raw.admissions) || raw.admissions.length === 0)
|
|
889
|
+
throw fail('declared.admissions invalid');
|
|
890
|
+
admissions = raw.admissions.map((t, i) => decodeAdmissionTarget(t, `declared.admissions[${String(i)}]`, fail));
|
|
891
|
+
if (new Set(admissions.map((t) => t.candidateId)).size !== admissions.length)
|
|
892
|
+
throw fail('declared.admissions invalid');
|
|
893
|
+
}
|
|
894
|
+
if (removed !== undefined && (!Array.isArray(removed) || removed.length === 0 || !removed.every(isAccountPubkey) || new Set(removed).size !== removed.length))
|
|
895
|
+
throw fail('declared.removed invalid');
|
|
896
|
+
if (admins !== undefined && admins !== true)
|
|
897
|
+
throw fail('declared.admins invalid');
|
|
898
|
+
if (components !== undefined && (!Array.isArray(components) || components.length === 0 || !components.every((id) => typeof id === 'number' && isComponentId(id)) || new Set(components).size !== components.length)) {
|
|
899
|
+
throw fail('declared.components invalid');
|
|
900
|
+
}
|
|
901
|
+
if (removed === undefined && admins === undefined && components === undefined && admissions === undefined)
|
|
902
|
+
throw fail('declared empty');
|
|
903
|
+
return {
|
|
904
|
+
...(removed === undefined ? {} : { removed: [...removed] }),
|
|
905
|
+
...(admins === undefined ? {} : { admins: true }),
|
|
906
|
+
...(components === undefined ? {} : { components: [...components] }),
|
|
907
|
+
...(admissions === undefined ? {} : { admissions }),
|
|
908
|
+
};
|
|
909
|
+
}
|
|
910
|
+
function malformedMarker(eventId, detail) {
|
|
911
|
+
return new MarmotError('store-failed', `${OWN_COMMIT_EXTENSION}/${eventId}: malformed record (${detail})`, { details: { eventId, malformed: true } });
|
|
912
|
+
}
|
|
913
|
+
export function decodeOwnCommitMarker(eventId, raw) {
|
|
914
|
+
const fail = (detail) => malformedMarker(eventId, detail);
|
|
915
|
+
if (!isObject(raw))
|
|
916
|
+
throw fail('record not an object');
|
|
917
|
+
if (raw.v !== 1)
|
|
918
|
+
throw fail('v mismatch');
|
|
919
|
+
if (typeof raw.root !== 'string')
|
|
920
|
+
throw fail('root missing');
|
|
921
|
+
if (typeof raw.node !== 'string')
|
|
922
|
+
throw fail('node missing');
|
|
923
|
+
if (typeof raw.attempts !== 'number')
|
|
924
|
+
throw fail('attempts missing');
|
|
925
|
+
let invitees;
|
|
926
|
+
if (raw.invitees !== undefined) {
|
|
927
|
+
if (!Array.isArray(raw.invitees) || raw.invitees.length === 0)
|
|
928
|
+
throw fail('invitees not a non-empty array');
|
|
929
|
+
invitees = raw.invitees.map((entry) => {
|
|
930
|
+
if (!isObject(entry) || !isObject(entry.event) || typeof entry.inviteeRef !== 'string' || !isHex64(entry.leafKey))
|
|
931
|
+
throw fail('invitee invalid');
|
|
932
|
+
return { event: entry.event, inviteeRef: entry.inviteeRef, leafKey: entry.leafKey };
|
|
933
|
+
});
|
|
934
|
+
}
|
|
935
|
+
const declared = raw.declared === undefined ? undefined : checkDeclared(raw.declared, fail);
|
|
936
|
+
const changes = raw.changes === undefined ? undefined : decodeStoredOwnChanges(raw.changes, 'changes', fail, false);
|
|
937
|
+
assertChangesPair(changes, raw.forkEpoch, fail);
|
|
938
|
+
return {
|
|
939
|
+
v: 1,
|
|
940
|
+
root: raw.root,
|
|
941
|
+
node: raw.node,
|
|
942
|
+
attempts: raw.attempts,
|
|
943
|
+
...(invitees === undefined ? {} : { invitees }),
|
|
944
|
+
...(declared === undefined ? {} : { declared }),
|
|
945
|
+
...(changes === undefined ? {} : { changes }),
|
|
946
|
+
...(raw.forkEpoch === undefined ? {} : { forkEpoch: raw.forkEpoch }),
|
|
947
|
+
};
|
|
948
|
+
}
|
|
949
|
+
export function encodeOwnCommitMarker(marker, eventId = '?') {
|
|
950
|
+
assertChangesPair(marker.changes, marker.forkEpoch, (detail) => malformedMarker(eventId, detail));
|
|
951
|
+
if (marker.invitees !== undefined && marker.invitees.length === 0)
|
|
952
|
+
throw malformedMarker(eventId, 'invitees empty');
|
|
953
|
+
for (const i of marker.invitees ?? [])
|
|
954
|
+
if (!isObject(i.event) || !isHex64(i.leafKey))
|
|
955
|
+
throw malformedMarker(eventId, 'invitee invalid');
|
|
956
|
+
const checked = marker.declared === undefined ? undefined : checkDeclared(marker.declared, (detail) => malformedMarker(eventId, detail));
|
|
957
|
+
const declared = checked === undefined
|
|
958
|
+
? undefined
|
|
959
|
+
: {
|
|
960
|
+
...(checked.removed === undefined ? {} : { removed: [...checked.removed] }),
|
|
961
|
+
...(checked.admins === undefined ? {} : { admins: true }),
|
|
962
|
+
...(checked.components === undefined ? {} : { components: [...checked.components] }),
|
|
963
|
+
...(checked.admissions === undefined ? {} : { admissions: checked.admissions.map((t) => encodeAdmissionTarget(t, (detail) => malformedMarker(eventId, detail))) }),
|
|
964
|
+
};
|
|
965
|
+
return {
|
|
966
|
+
v: 1,
|
|
967
|
+
root: marker.root,
|
|
968
|
+
node: marker.node,
|
|
969
|
+
attempts: marker.attempts,
|
|
970
|
+
...(marker.invitees === undefined ? {} : { invitees: marker.invitees.map((i) => ({ event: i.event, inviteeRef: i.inviteeRef, leafKey: i.leafKey })) }),
|
|
971
|
+
...(declared === undefined ? {} : { declared }),
|
|
972
|
+
...(marker.changes === undefined ? {} : { changes: encodeStoredOwnChanges(marker.changes, false) }),
|
|
973
|
+
...(marker.forkEpoch === undefined ? {} : { forkEpoch: marker.forkEpoch }),
|
|
974
|
+
};
|
|
975
|
+
}
|
|
976
|
+
/** `view` is the group's `OWN_COMMIT_EXTENSION` namespace. */
|
|
977
|
+
export async function readOwnCommitMarker(view, eventId) {
|
|
978
|
+
const raw = await view.get(eventId);
|
|
979
|
+
if (raw === undefined)
|
|
980
|
+
return undefined;
|
|
981
|
+
return decodeOwnCommitMarker(eventId, raw);
|
|
982
|
+
}
|
|
983
|
+
export async function writeOwnCommitMarker(view, eventId, marker) {
|
|
984
|
+
await view.put(eventId, encodeOwnCommitMarker(marker, eventId));
|
|
985
|
+
}
|
|
986
|
+
/**
|
|
987
|
+
* DD9: the part of its root's publish budget a commit re-drive record holds that no marker does yet — its failed
|
|
988
|
+
* publishes and re-mints (`attempts`) and, while a relay-accepted publish awaits its confirm (`pending-confirm`), the
|
|
989
|
+
* one publish that confirm would have counted.
|
|
990
|
+
*/
|
|
991
|
+
export function redriveSpendOf(record) {
|
|
992
|
+
return record.attempts + (record.state === 'pending-confirm' ? 1 : 0);
|
|
993
|
+
}
|
|
994
|
+
/** DD9: the highest spend any marker of `root` in `view` (the `OWN_COMMIT_EXTENSION` namespace) records; 0 when none. */
|
|
995
|
+
export async function rootMarkerSpend(view, root) {
|
|
996
|
+
let spend = 0;
|
|
997
|
+
for (const eventId of await view.keys()) {
|
|
998
|
+
const marker = await readOwnCommitMarker(view, eventId);
|
|
999
|
+
if (marker !== undefined && marker.root === root)
|
|
1000
|
+
spend = Math.max(spend, marker.attempts);
|
|
1001
|
+
}
|
|
1002
|
+
return spend;
|
|
1003
|
+
}
|
|
1004
|
+
/**
|
|
1005
|
+
* DD9: raises every marker of `root` in `view` — or only those of `eventIds` — to at least `spend` attempts (max-based,
|
|
1006
|
+
* idempotent), so a later restore or withdrawal seeds its record from the marker instead of a fresh budget.
|
|
1007
|
+
*/
|
|
1008
|
+
export async function raiseRootSpend(view, root, spend, eventIds) {
|
|
1009
|
+
for (const eventId of eventIds ?? (await view.keys())) {
|
|
1010
|
+
const marker = await readOwnCommitMarker(view, eventId);
|
|
1011
|
+
if (marker !== undefined && marker.root === root && marker.attempts < spend)
|
|
1012
|
+
await writeOwnCommitMarker(view, eventId, { ...marker, attempts: spend });
|
|
1013
|
+
}
|
|
1014
|
+
}
|
|
1015
|
+
export async function deleteOwnCommitMarker(view, eventId) {
|
|
1016
|
+
await view.delete(eventId);
|
|
1017
|
+
}
|
|
1018
|
+
/**
|
|
1019
|
+
* Marker retention follows the node (DD6, AC-MARK-4): deletes every marker whose `node` is not in `retained` (the
|
|
1020
|
+
* stored rewind window's nodes, `retainedLedgerNodes`) — whether or not its terminal-ledger entry still exists: a
|
|
1021
|
+
* node that left the window can no longer be abandoned or restored by a fork flip, so its marker has nothing left to
|
|
1022
|
+
* serve. `retained` is required so a caller cannot prune against an empty window by omission. Returns the number
|
|
1023
|
+
* deleted. Called by the ingest ledger prune, in its transaction (S9).
|
|
1024
|
+
*/
|
|
1025
|
+
export async function pruneOwnCommitMarkers(markers, retained) {
|
|
1026
|
+
let pruned = 0;
|
|
1027
|
+
for (const eventId of await markers.keys()) {
|
|
1028
|
+
const marker = await readOwnCommitMarker(markers, eventId);
|
|
1029
|
+
if (marker !== undefined && !retained.has(marker.node)) {
|
|
1030
|
+
await markers.delete(eventId);
|
|
1031
|
+
pruned += 1;
|
|
1032
|
+
}
|
|
1033
|
+
}
|
|
1034
|
+
return pruned;
|
|
1035
|
+
}
|
|
1036
|
+
// ---------------------------------------------------------------------------
|
|
1037
|
+
// Ingest cursor (GroupStore `ingestCursor` artifact, key {@link CURSOR_KEY})
|
|
1038
|
+
// ---------------------------------------------------------------------------
|
|
1039
|
+
function malformedCursor() {
|
|
1040
|
+
return new MarmotError('store-failed', 'ingestCursor: malformed entry', { details: { key: CURSOR_KEY, malformed: true } });
|
|
1041
|
+
}
|
|
1042
|
+
function decodeHoldMap(raw) {
|
|
1043
|
+
if (raw === undefined)
|
|
1044
|
+
return undefined;
|
|
1045
|
+
if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
|
|
1046
|
+
throw malformedCursor();
|
|
1047
|
+
const map = {};
|
|
1048
|
+
for (const [id, at] of Object.entries(raw)) {
|
|
1049
|
+
if (typeof at !== 'number')
|
|
1050
|
+
throw malformedCursor();
|
|
1051
|
+
map[id] = at;
|
|
1052
|
+
}
|
|
1053
|
+
return map;
|
|
1054
|
+
}
|
|
1055
|
+
/**
|
|
1056
|
+
* Reads the group's persisted kind-445 ingest cursor, or `undefined` when
|
|
1057
|
+
* history has never been synced. `pins`, `busy` and `resume` are optional: a
|
|
1058
|
+
* record written before those tiers existed decodes with every hold in the
|
|
1059
|
+
* evictable tier, and without a resume window.
|
|
1060
|
+
*/
|
|
1061
|
+
export async function readIngestCursor(view) {
|
|
1062
|
+
const raw = await view.get(CURSOR_KEY);
|
|
1063
|
+
if (raw === undefined)
|
|
1064
|
+
return undefined;
|
|
1065
|
+
if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
|
|
1066
|
+
throw malformedCursor();
|
|
1067
|
+
const r = raw;
|
|
1068
|
+
if (typeof r.since !== 'number' || (r.high !== undefined && typeof r.high !== 'number'))
|
|
1069
|
+
throw malformedCursor();
|
|
1070
|
+
const holds = decodeHoldMap(r.holds);
|
|
1071
|
+
const pins = decodeHoldMap(r.pins);
|
|
1072
|
+
const busy = decodeHoldMap(r.busy);
|
|
1073
|
+
const resume = decodeResume(r.resume);
|
|
1074
|
+
return {
|
|
1075
|
+
since: r.since,
|
|
1076
|
+
...(r.high === undefined ? {} : { high: r.high }),
|
|
1077
|
+
...(holds === undefined ? {} : { holds }),
|
|
1078
|
+
...(pins === undefined ? {} : { pins }),
|
|
1079
|
+
...(busy === undefined ? {} : { busy }),
|
|
1080
|
+
...(resume === undefined ? {} : { resume }),
|
|
1081
|
+
};
|
|
1082
|
+
}
|
|
1083
|
+
function decodeResume(raw) {
|
|
1084
|
+
if (raw === undefined)
|
|
1085
|
+
return undefined;
|
|
1086
|
+
if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
|
|
1087
|
+
throw malformedCursor();
|
|
1088
|
+
const { from, until, above } = raw;
|
|
1089
|
+
if (typeof from !== 'number' || (until !== undefined && typeof until !== 'number'))
|
|
1090
|
+
throw malformedCursor();
|
|
1091
|
+
if (above !== undefined && (!Array.isArray(above) || !above.every((top) => typeof top === 'number')))
|
|
1092
|
+
throw malformedCursor();
|
|
1093
|
+
return {
|
|
1094
|
+
from,
|
|
1095
|
+
...(until === undefined ? {} : { until }),
|
|
1096
|
+
...(above === undefined || above.length === 0 ? {} : { above: [...above] }),
|
|
1097
|
+
};
|
|
1098
|
+
}
|
|
1099
|
+
/** Persists `cursor` as the group's kind-445 ingest cursor. */
|
|
1100
|
+
export async function writeIngestCursor(view, cursor) {
|
|
1101
|
+
await view.put(CURSOR_KEY, {
|
|
1102
|
+
since: cursor.since,
|
|
1103
|
+
...(cursor.high === undefined ? {} : { high: cursor.high }),
|
|
1104
|
+
...(cursor.holds === undefined ? {} : { holds: { ...cursor.holds } }),
|
|
1105
|
+
...(cursor.pins === undefined ? {} : { pins: { ...cursor.pins } }),
|
|
1106
|
+
...(cursor.busy === undefined ? {} : { busy: { ...cursor.busy } }),
|
|
1107
|
+
...(cursor.resume === undefined
|
|
1108
|
+
? {}
|
|
1109
|
+
: {
|
|
1110
|
+
resume: {
|
|
1111
|
+
from: cursor.resume.from,
|
|
1112
|
+
...(cursor.resume.until === undefined ? {} : { until: cursor.resume.until }),
|
|
1113
|
+
...(cursor.resume.above === undefined || cursor.resume.above.length === 0 ? {} : { above: [...cursor.resume.above] }),
|
|
1114
|
+
},
|
|
1115
|
+
}),
|
|
1116
|
+
});
|
|
1117
|
+
}
|