@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,221 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The build-time check ladder of a commit re-drive (epic marmot-rewound-own-commit-no-signal, spec Design Decision 11),
|
|
3
|
+
* and the per-change-kind extension point it runs the kind-specific part through.
|
|
4
|
+
*
|
|
5
|
+
* Pure: it reads a state, the retained window and the stored changes of a re-drive record and returns verdicts and a
|
|
6
|
+
* payload contribution. Everything that reads the runtime, writes the store or dispatches belongs to `pipeline.ts`.
|
|
7
|
+
*
|
|
8
|
+
* The ladder, in order (the first two are the whole record's; the rest are per change):
|
|
9
|
+
* 1. stranded (the author's device removed for good, or the group fenced): decided by the drive, which owns the runtime;
|
|
10
|
+
* 2. not-admin (the author's ACCOUNT is not an active admin, AC-DRIVE-9): every undecided change is lost `not-admin`;
|
|
11
|
+
* 3. each undecided change through its kind's {@link RedriveChangeKind.check}: a lost reason, or `undefined` (survives).
|
|
12
|
+
* The surviving changes of a kind then each contribute to the one commit that is built ({@link RedriveChangeKind.contribute}).
|
|
13
|
+
*
|
|
14
|
+
* Extension point: {@link REDRIVE_CHANGE_KINDS} maps a change type to its handler. A story adding a kind adds ONE
|
|
15
|
+
* entry; the ladder, the drive and the durability around them are unchanged. A kind whose survivors are not independent of one
|
|
16
|
+
* another (the admin list) also gives {@link RedriveChangeKind.checkSet}, which runs over the survivors of the per-change check.
|
|
17
|
+
*/
|
|
18
|
+
import { GROUP_ADMIN_POLICY_COMPONENT_ID } from '@941design/marmot-engine/core';
|
|
19
|
+
import { validateAdminList } from '../account/index.js';
|
|
20
|
+
import { adminsOf, commitViewOf, holdsLeafKey, sameBytes, winnerHeldLeaf, winnerRemovedAccount } from '../history/index.js';
|
|
21
|
+
import { stagesComponentUpdate } from './component-update.js';
|
|
22
|
+
import { stagedAddLeafKeys } from '../invitations/index.js';
|
|
23
|
+
import { holdsLeafOfAny } from './group-remove-member.js';
|
|
24
|
+
/**
|
|
25
|
+
* Member removal (DD4 as amended, DD5, DD12). Already applied: the account holds no leaf. Reversed: the winning branch above
|
|
26
|
+
* the fork point REMOVED the account (captured at withdrawal as `winnerRemovedTarget`, extended with the current window's canonical
|
|
27
|
+
* edges) and the account holds a leaf now -- a deliberate re-add, also under the same device key (device keys are stable across
|
|
28
|
+
* KeyPackages). A target that merely rotated was never removed by the winner, so it is still removed (lineage needs no check of
|
|
29
|
+
* its own: the commit removes every leaf the account holds when it is built, `removeProposalsForAccounts`; `fork.leafKeys`
|
|
30
|
+
* only feeds the commit's leaf-key snapshot). When the window floor passed the fork point and nothing was captured the
|
|
31
|
+
* evidence is inconclusive: the standing decision wins (re-remove).
|
|
32
|
+
*/
|
|
33
|
+
const memberRemoved = {
|
|
34
|
+
check: ({ change, winnerRemovedTarget }, { state, window, windowTip, forkEpoch }) => {
|
|
35
|
+
if (!holdsLeafOfAny(state, [change.account]))
|
|
36
|
+
return 'already-applied';
|
|
37
|
+
if (winnerRemovedTarget === true || winnerRemovedAccount(change.account, forkEpoch, [window], windowTip))
|
|
38
|
+
return 'reversed';
|
|
39
|
+
return undefined;
|
|
40
|
+
},
|
|
41
|
+
contribute: (survivors) => ({
|
|
42
|
+
removeAccounts: survivors.map((s) => s.change.account),
|
|
43
|
+
removeAccountLeafKeys: [...new Set(survivors.flatMap((s) => s.fork.leafKeys))].sort(),
|
|
44
|
+
}),
|
|
45
|
+
};
|
|
46
|
+
/** `state`'s app-data dictionary; `undefined` when it cannot be read (never true of a state the engine accepted, but the ladder must not throw inside the drive). */
|
|
47
|
+
function dictionaryOf(state) {
|
|
48
|
+
try {
|
|
49
|
+
return commitViewOf(state).dictionary;
|
|
50
|
+
}
|
|
51
|
+
catch {
|
|
52
|
+
return undefined;
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
/** Bytes, or absence (`null`), of one component compared as the fork-point value is. */
|
|
56
|
+
const sameComponentBytes = (a, b) => (a === null || b === null ? a === b : sameBytes(a, b));
|
|
57
|
+
/**
|
|
58
|
+
* A component (the group profile `0x8001`, a generic one by id; DD3, DD11). Unchanged since the fork point (bytes, or absence, equal
|
|
59
|
+
* the fork-point value: a winner that changed it and changed it back counts as unchanged, AC-COMP-9) and no foreign update of it
|
|
60
|
+
* staged on the build state (AC-COMP-7, which keeps the build's `guardedComponentUpdate` from throwing): the change is re-applied
|
|
61
|
+
* with the withdrawn commit's bytes (or its deletion). Otherwise someone else's value stands (AC-COMP-2).
|
|
62
|
+
*/
|
|
63
|
+
const componentChanged = {
|
|
64
|
+
check: ({ change, fork }, { state }) => {
|
|
65
|
+
const dictionary = dictionaryOf(state);
|
|
66
|
+
if (dictionary === undefined || !sameComponentBytes(dictionary.get(change.componentId) ?? null, fork.component))
|
|
67
|
+
return 'concurrent-change';
|
|
68
|
+
return stagesComponentUpdate(state, change.componentId) ? 'concurrent-change' : undefined;
|
|
69
|
+
},
|
|
70
|
+
contribute: (survivors) => ({ components: survivors.map((s) => ({ id: s.change.componentId, data: s.data })) }),
|
|
71
|
+
};
|
|
72
|
+
/** The tip's admin list, lowercase and in list order; `undefined` when its policy does not decode (never true of a state the engine accepted). An absent policy is an empty list. */
|
|
73
|
+
function tipAdmins(state) {
|
|
74
|
+
const dictionary = dictionaryOf(state);
|
|
75
|
+
const admins = dictionary === undefined ? 'unreadable' : adminsOf(dictionary);
|
|
76
|
+
return admins === 'unreadable' ? undefined : [...(admins ?? [])];
|
|
77
|
+
}
|
|
78
|
+
/** The re-drive's admin list (DD3): the tip's list with each surviving per-member flip applied, a grant appended and a revoke dropped. */
|
|
79
|
+
function rebuiltAdmins(tip, survivors) {
|
|
80
|
+
const revoked = new Set(survivors.filter((s) => !s.change.admin).map((s) => s.change.account.toLowerCase()));
|
|
81
|
+
return [...new Set([...tip, ...survivors.filter((s) => s.change.admin).map((s) => s.change.account.toLowerCase())])].filter((a) => !revoked.has(a));
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* Admin flips, per member (DD3, DD11). A flip survives when the account's status at the tip is still its fork-point status (the
|
|
85
|
+
* winner flipped it, or flipped it and back: AC-COMP-3, AC-COMP-9), no foreign update of the admin list is staged (AC-COMP-7), and
|
|
86
|
+
* a grant names an account that still holds a leaf (AC-COMP-6). Together the survivors must give a list `validateAdminList` accepts
|
|
87
|
+
* (never empty): revokes that would empty it are lost, and so is the whole set if the rebuilt list is invalid for any other reason --
|
|
88
|
+
* decided here, before the budget gate, so no publish is spent on it and `validateAdminList` never throws inside the drive.
|
|
89
|
+
*/
|
|
90
|
+
const adminFlipped = {
|
|
91
|
+
check: ({ change, fork }, { state }) => {
|
|
92
|
+
const tip = tipAdmins(state);
|
|
93
|
+
if (tip === undefined || tip.includes(change.account.toLowerCase()) !== fork.admin)
|
|
94
|
+
return 'concurrent-change';
|
|
95
|
+
if (stagesComponentUpdate(state, GROUP_ADMIN_POLICY_COMPONENT_ID))
|
|
96
|
+
return 'concurrent-change';
|
|
97
|
+
if (change.admin && !holdsLeafOfAny(state, [change.account]))
|
|
98
|
+
return 'concurrent-change';
|
|
99
|
+
return undefined;
|
|
100
|
+
},
|
|
101
|
+
checkSet: (survivors, { state }) => {
|
|
102
|
+
const lost = new Map();
|
|
103
|
+
const tip = tipAdmins(state) ?? [];
|
|
104
|
+
let kept = survivors;
|
|
105
|
+
if (rebuiltAdmins(tip, kept).length === 0) {
|
|
106
|
+
for (const s of kept.filter((c) => !c.change.admin))
|
|
107
|
+
lost.set(s, 'concurrent-change');
|
|
108
|
+
kept = kept.filter((c) => !lost.has(c));
|
|
109
|
+
}
|
|
110
|
+
if (kept.length > 0) {
|
|
111
|
+
try {
|
|
112
|
+
validateAdminList(state.ratchetTree, rebuiltAdmins(tip, kept));
|
|
113
|
+
}
|
|
114
|
+
catch {
|
|
115
|
+
for (const s of kept)
|
|
116
|
+
lost.set(s, 'concurrent-change');
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
return lost;
|
|
120
|
+
},
|
|
121
|
+
contribute: (survivors, { state }) => ({ admins: rebuiltAdmins(tipAdmins(state) ?? [], survivors) }),
|
|
122
|
+
};
|
|
123
|
+
/** The rungs of an invite that need no KeyPackage check: already applied, then reversed. */
|
|
124
|
+
function memberAddedEvidence({ change, winnerHeldInvitee }, { state, window, windowTip, forkEpoch }) {
|
|
125
|
+
if (holdsLeafKey(commitViewOf(state), change.leafKey))
|
|
126
|
+
return 'already-applied';
|
|
127
|
+
if (winnerHeldInvitee === true || winnerHeldLeaf(change.leafKey, forkEpoch, [window], windowTip))
|
|
128
|
+
return 'reversed';
|
|
129
|
+
return undefined;
|
|
130
|
+
}
|
|
131
|
+
/**
|
|
132
|
+
* The invite changes whose KeyPackage the drive must still check (the facts' `invalidKeyPackages`): undecided, the author an
|
|
133
|
+
* admin, and neither already applied nor reversed -- the ladder would reach the validity rung for exactly these, so a consumer
|
|
134
|
+
* verifier is never called for a change that is lost anyway. Pure.
|
|
135
|
+
*/
|
|
136
|
+
export function changesNeedingKeyPackageCheck(stored, facts) {
|
|
137
|
+
if (!facts.authorIsAdmin)
|
|
138
|
+
return [];
|
|
139
|
+
return stored.filter((c) => c.verdict === undefined && c.change.type === 'member-added' && memberAddedEvidence(c, facts) === undefined);
|
|
140
|
+
}
|
|
141
|
+
/**
|
|
142
|
+
* An invite (DD16, AC-INV-3/4/6). The change names the invitee LEAF (`leafKey`), not only the account, so a second-device invite
|
|
143
|
+
* of an account that is already a member is told from the account itself. Ladder, in order:
|
|
144
|
+
* - already applied: the tip holds that leaf key (a re-invite, or the original back on the path);
|
|
145
|
+
* - reversed: the winning branch above the fork point held the leaf (captured at withdrawal as `winnerHeldInvitee`, extended
|
|
146
|
+
* with the current window) and the tip does not any more -- somebody removed the invitee, which the re-drive must not undo.
|
|
147
|
+
* Past the horizon with nothing captured the evidence is inconclusive and the standing decision wins (Add);
|
|
148
|
+
* - invalid KeyPackage: the stored KeyPackage is no longer accepted by the invitations path (AC-INV-4); decided here, before the
|
|
149
|
+
* budget gate, so no publish attempt is spent on it;
|
|
150
|
+
* - concurrent change: an Add of the same leaf is already staged on the build state (the commit would carry it by reference
|
|
151
|
+
* and the re-drive's own Add would be a second one).
|
|
152
|
+
* The survivors Add from the KeyPackage event the RECORD retained (never from the original marker, which may be pruned).
|
|
153
|
+
*/
|
|
154
|
+
const memberAdded = {
|
|
155
|
+
check: (stored, facts) => {
|
|
156
|
+
const { change, keyPackage } = stored;
|
|
157
|
+
const { state, invalidKeyPackages } = facts;
|
|
158
|
+
const evidence = memberAddedEvidence(stored, facts);
|
|
159
|
+
if (evidence !== undefined)
|
|
160
|
+
return evidence;
|
|
161
|
+
if (invalidKeyPackages.has(keyPackage.inviteeRef))
|
|
162
|
+
return 'invalid-keypackage';
|
|
163
|
+
if (stagedAddLeafKeys(state).has(change.leafKey))
|
|
164
|
+
return 'concurrent-change';
|
|
165
|
+
return undefined;
|
|
166
|
+
},
|
|
167
|
+
contribute: (survivors) => ({ invite: { invitees: survivors.map((s) => ({ event: s.keyPackage.event, inviteeRef: s.keyPackage.inviteeRef })) } }),
|
|
168
|
+
};
|
|
169
|
+
/** The handlers by change type: every kind has one, so a change is never lost for want of a handler. */
|
|
170
|
+
export const REDRIVE_CHANGE_KINDS = {
|
|
171
|
+
'member-removed': memberRemoved,
|
|
172
|
+
'member-added': memberAdded,
|
|
173
|
+
admin: adminFlipped,
|
|
174
|
+
component: componentChanged,
|
|
175
|
+
};
|
|
176
|
+
function handlerOf(change) {
|
|
177
|
+
return REDRIVE_CHANGE_KINDS[change.change.type];
|
|
178
|
+
}
|
|
179
|
+
/** Runs rungs 2 and 3 of the ladder over `stored` (rung 1, stranded, never reaches here). Pure. */
|
|
180
|
+
export function decideChanges(stored, facts) {
|
|
181
|
+
// Pass 1: each undecided change alone (not-admin, then its kind's check).
|
|
182
|
+
const lostNow = new Map();
|
|
183
|
+
for (const change of stored) {
|
|
184
|
+
if (change.verdict !== undefined)
|
|
185
|
+
continue;
|
|
186
|
+
const handler = handlerOf(change);
|
|
187
|
+
const reason = !facts.authorIsAdmin ? 'not-admin' : handler.check(change, facts);
|
|
188
|
+
if (reason !== undefined)
|
|
189
|
+
lostNow.set(change, reason);
|
|
190
|
+
}
|
|
191
|
+
// Pass 2: a kind whose survivors depend on one another decides over them together.
|
|
192
|
+
const undecided = () => stored.filter((c) => c.verdict === undefined && !lostNow.has(c));
|
|
193
|
+
for (const type of new Set(undecided().map((c) => c.change.type))) {
|
|
194
|
+
const ofKind = undecided().filter((c) => c.change.type === type);
|
|
195
|
+
const lost = handlerOf(ofKind[0]).checkSet?.(ofKind, facts);
|
|
196
|
+
for (const [change, reason] of lost ?? [])
|
|
197
|
+
lostNow.set(change, reason);
|
|
198
|
+
}
|
|
199
|
+
const newlyLost = [];
|
|
200
|
+
const changes = [];
|
|
201
|
+
const survivors = [];
|
|
202
|
+
for (const change of stored) {
|
|
203
|
+
const reason = lostNow.get(change);
|
|
204
|
+
if (change.verdict !== undefined)
|
|
205
|
+
changes.push(change);
|
|
206
|
+
else if (reason !== undefined) {
|
|
207
|
+
newlyLost.push({ change: change.change, reason });
|
|
208
|
+
changes.push({ ...change, verdict: reason });
|
|
209
|
+
}
|
|
210
|
+
else {
|
|
211
|
+
changes.push(change);
|
|
212
|
+
survivors.push(change);
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
let contribution = {};
|
|
216
|
+
for (const type of new Set(survivors.map((s) => s.change.type))) {
|
|
217
|
+
const ofKind = survivors.filter((s) => s.change.type === type);
|
|
218
|
+
contribution = { ...contribution, ...handlerOf(ofKind[0]).contribute(ofKind, facts) };
|
|
219
|
+
}
|
|
220
|
+
return { changes, newlyLost, survivors, contribution };
|
|
221
|
+
}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* "One AppDataUpdate per component" for an own commit that must not carry two. A commit carries every staged proposal by
|
|
3
|
+
* reference (first) and its own by value (after them), and the engine and ts-mls accept two updates of one component
|
|
4
|
+
* (receivers resolve to the last, the committer's own). Where that is harmless it is allowed: the admin list
|
|
5
|
+
* (`setAdmins`, the demotion of `departAsAdmin`), because teardown never commits a staged proposal, so a refusal there
|
|
6
|
+
* would block it for good (test/client/group-single-component-op.test.ts). Where AC-RENAME-9 requires it, the client
|
|
7
|
+
* refuses instead: `rename` (`0x8001`), before recording (a typed `send-rejected`, nothing written) and, for a record
|
|
8
|
+
* resumed after the staged proposal arrived, at build time.
|
|
9
|
+
*/
|
|
10
|
+
import { type ClientState, type Proposal } from '@941design/marmot-engine/mls';
|
|
11
|
+
import { MarmotError } from '../shared/index.js';
|
|
12
|
+
/** What a refusal names: the operation, the component in words, and the `details.reason` the caller reads. */
|
|
13
|
+
export interface ComponentUpdateGuard {
|
|
14
|
+
readonly componentId: number;
|
|
15
|
+
readonly groupId: string;
|
|
16
|
+
readonly operation: string;
|
|
17
|
+
/** e.g. `'group-profile'`. */
|
|
18
|
+
readonly what: string;
|
|
19
|
+
/** e.g. `'staged-profile-update'`. */
|
|
20
|
+
readonly reason: string;
|
|
21
|
+
}
|
|
22
|
+
/** Whether a proposal of `componentId`'s AppDataUpdate is staged in `state` — another member's or the local account's own. */
|
|
23
|
+
export declare function stagesComponentUpdate(state: ClientState, componentId: number): boolean;
|
|
24
|
+
/** The `send-rejected` of an own commit that would hold a second update of the guarded component. */
|
|
25
|
+
export declare function stagedComponentUpdateError(guard: ComponentUpdateGuard): MarmotError;
|
|
26
|
+
/** Throws {@link stagedComponentUpdateError} when `state` stages the guarded component's update. */
|
|
27
|
+
export declare function assertNoStagedComponentUpdate(state: ClientState, guard: ComponentUpdateGuard): void;
|
|
28
|
+
/**
|
|
29
|
+
* `build()` as a build-time engine action: evaluated against the state the commit is built on, it fails when the
|
|
30
|
+
* guarded component's update is staged there — the backstop of the pre-record check for a proposal that arrived
|
|
31
|
+
* after the call was recorded (a record resumed after a reload).
|
|
32
|
+
*/
|
|
33
|
+
export declare function guardedComponentUpdate(guard: ComponentUpdateGuard, build: () => Proposal): (context: {
|
|
34
|
+
readonly state: ClientState;
|
|
35
|
+
}) => Promise<Proposal>;
|
|
36
|
+
/**
|
|
37
|
+
* The AppDataUpdate that sets component `componentId` to `data` (`null`: removes its dictionary entry). The generic form of the
|
|
38
|
+
* typed builders (`groupProfileProposal`, `adminPolicyProposal`): what a commit's internal `components` field and a component
|
|
39
|
+
* change's re-drive are applied with. The bytes are not interpreted here; the engine validates them like any update.
|
|
40
|
+
*/
|
|
41
|
+
export declare function componentUpdateProposal(componentId: number, data: Uint8Array | null): Proposal;
|
|
42
|
+
/** The guard of an own commit's generic component update (the internal `components` field): a staged update of the same component is refused. */
|
|
43
|
+
export declare function genericComponentGuard(componentId: number, groupId: string): ComponentUpdateGuard;
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* "One AppDataUpdate per component" for an own commit that must not carry two. A commit carries every staged proposal by
|
|
3
|
+
* reference (first) and its own by value (after them), and the engine and ts-mls accept two updates of one component
|
|
4
|
+
* (receivers resolve to the last, the committer's own). Where that is harmless it is allowed: the admin list
|
|
5
|
+
* (`setAdmins`, the demotion of `departAsAdmin`), because teardown never commits a staged proposal, so a refusal there
|
|
6
|
+
* would block it for good (test/client/group-single-component-op.test.ts). Where AC-RENAME-9 requires it, the client
|
|
7
|
+
* refuses instead: `rename` (`0x8001`), before recording (a typed `send-rejected`, nothing written) and, for a record
|
|
8
|
+
* resumed after the staged proposal arrived, at build time.
|
|
9
|
+
*/
|
|
10
|
+
import { appDataUpdateProposalType } from '@941design/marmot-engine/mls';
|
|
11
|
+
import { MarmotError } from '../shared/index.js';
|
|
12
|
+
/** Whether a proposal of `componentId`'s AppDataUpdate is staged in `state` — another member's or the local account's own. */
|
|
13
|
+
export function stagesComponentUpdate(state, componentId) {
|
|
14
|
+
return Object.values(state.unappliedProposals).some(({ proposal }) => proposal.proposalType === appDataUpdateProposalType && 'appDataUpdate' in proposal && proposal.appDataUpdate.componentId === componentId);
|
|
15
|
+
}
|
|
16
|
+
/** The `send-rejected` of an own commit that would hold a second update of the guarded component. */
|
|
17
|
+
export function stagedComponentUpdateError(guard) {
|
|
18
|
+
return new MarmotError('send-rejected', `${guard.operation}: a ${guard.what} proposal is staged on group ${guard.groupId}; a commit never carries two ${guard.what} updates — commit that proposal first`, {
|
|
19
|
+
details: { groupId: guard.groupId, reason: guard.reason },
|
|
20
|
+
});
|
|
21
|
+
}
|
|
22
|
+
/** Throws {@link stagedComponentUpdateError} when `state` stages the guarded component's update. */
|
|
23
|
+
export function assertNoStagedComponentUpdate(state, guard) {
|
|
24
|
+
if (stagesComponentUpdate(state, guard.componentId))
|
|
25
|
+
throw stagedComponentUpdateError(guard);
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* `build()` as a build-time engine action: evaluated against the state the commit is built on, it fails when the
|
|
29
|
+
* guarded component's update is staged there — the backstop of the pre-record check for a proposal that arrived
|
|
30
|
+
* after the call was recorded (a record resumed after a reload).
|
|
31
|
+
*/
|
|
32
|
+
export function guardedComponentUpdate(guard, build) {
|
|
33
|
+
return (context) => {
|
|
34
|
+
if (stagesComponentUpdate(context.state, guard.componentId))
|
|
35
|
+
return Promise.reject(stagedComponentUpdateError(guard));
|
|
36
|
+
return Promise.resolve(build());
|
|
37
|
+
};
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* The AppDataUpdate that sets component `componentId` to `data` (`null`: removes its dictionary entry). The generic form of the
|
|
41
|
+
* typed builders (`groupProfileProposal`, `adminPolicyProposal`): what a commit's internal `components` field and a component
|
|
42
|
+
* change's re-drive are applied with. The bytes are not interpreted here; the engine validates them like any update.
|
|
43
|
+
*/
|
|
44
|
+
export function componentUpdateProposal(componentId, data) {
|
|
45
|
+
return {
|
|
46
|
+
proposalType: appDataUpdateProposalType,
|
|
47
|
+
appDataUpdate: data === null ? { componentId, operation: 'remove' } : { componentId, operation: 'update', update: data },
|
|
48
|
+
};
|
|
49
|
+
}
|
|
50
|
+
/** The guard of an own commit's generic component update (the internal `components` field): a staged update of the same component is refused. */
|
|
51
|
+
export function genericComponentGuard(componentId, groupId) {
|
|
52
|
+
return { componentId, groupId, operation: 'commit', what: `component 0x${componentId.toString(16)}`, reason: 'staged-component-update' };
|
|
53
|
+
}
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The one runner of `extensions.onConfirm` hooks (AC-PIPE-13, AC-MX-1): every site that persists a group state
|
|
3
|
+
* a hook must see — a confirmation (pipeline.ts `confirmRecord`), `groups.create` (`kind: 'create'`) and a
|
|
4
|
+
* Welcome adoption (`kind: 'join'`, group-runtime.ts) — calls it INSIDE the persisting group transaction, so a
|
|
5
|
+
* hook's writes through `tx` commit atomically with the state and a throw rolls the whole transaction back.
|
|
6
|
+
*
|
|
7
|
+
* `ConfirmContext.snapshot` is a lazy, memoized getter: the state is serialized and sealed only when a hook first
|
|
8
|
+
* reads it, so a transaction whose hooks never read it (and every transaction with no hook at all) pays no
|
|
9
|
+
* serialization. The ingest cursor's floor it carries is read once per run, and only when a hook is registered.
|
|
10
|
+
* The getter is readable only while the run's hooks are running — inside the transaction: the state objects it
|
|
11
|
+
* describes belong to the engine afterwards (ts-mls mutates them in place), so a later first read would describe
|
|
12
|
+
* whatever they had become. Read after that, it throws `transaction-closed`, like a settled transaction's views.
|
|
13
|
+
*/
|
|
14
|
+
import type { ClientState } from '@941design/marmot-engine/mls';
|
|
15
|
+
import type { AppliedNotification } from '../history/index.js';
|
|
16
|
+
import type { RetainedWindow } from '../history/index.js';
|
|
17
|
+
import type { GroupStoreTx } from '../storage/index.js';
|
|
18
|
+
import type { ConfirmHook, ConfirmKind } from './create-client.js';
|
|
19
|
+
import type { ReentrancyGuard } from './reentrancy-guard.js';
|
|
20
|
+
export interface ConfirmHookSite {
|
|
21
|
+
readonly groupId: string;
|
|
22
|
+
readonly guard: ReentrancyGuard;
|
|
23
|
+
/** The registry's live hook list (read once per run, in registration order). */
|
|
24
|
+
readonly hooks: readonly ConfirmHook[];
|
|
25
|
+
}
|
|
26
|
+
/** What the transaction persists: the group state and the rewind window whose tip it is. */
|
|
27
|
+
export interface PersistedGroup {
|
|
28
|
+
readonly state: ClientState;
|
|
29
|
+
readonly window: RetainedWindow;
|
|
30
|
+
}
|
|
31
|
+
export interface ConfirmHookRun {
|
|
32
|
+
readonly intentId: string;
|
|
33
|
+
readonly kind: ConfirmKind;
|
|
34
|
+
/** `ConfirmContext.epoch`: the epoch of the persisted state. */
|
|
35
|
+
readonly epoch: bigint;
|
|
36
|
+
readonly tx: GroupStoreTx;
|
|
37
|
+
/** What the transaction persists — called at most once, on the first `snapshot` read, while the hooks run. */
|
|
38
|
+
readonly persisted: () => PersistedGroup;
|
|
39
|
+
readonly notifications: readonly AppliedNotification[];
|
|
40
|
+
/** The group's account-index `createdAt` (client-clock ms), when known. */
|
|
41
|
+
readonly createdAt: number | undefined;
|
|
42
|
+
/** `ConfirmContext.forgetting` (AC-MX-6): the leaf keys a `devices.forget` commit removes; absent otherwise. */
|
|
43
|
+
readonly forgetting?: {
|
|
44
|
+
readonly leafKeys: readonly string[];
|
|
45
|
+
};
|
|
46
|
+
}
|
|
47
|
+
/** The ingest cursor's floor as the transaction sees it; a missing or unreadable cursor is simply not carried. */
|
|
48
|
+
export declare function cursorFloor(tx: GroupStoreTx): Promise<number | undefined>;
|
|
49
|
+
/** Runs every registered hook, in order, each in the group's `onConfirm` re-entrancy frame. A throw propagates. */
|
|
50
|
+
export declare function runConfirmHooks(site: ConfirmHookSite, run: ConfirmHookRun): Promise<void>;
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
import { MarmotError } from '../shared/index.js';
|
|
2
|
+
import { readIngestCursor } from './group-records.js';
|
|
3
|
+
import { sealGroupSnapshot } from './group-snapshot.js';
|
|
4
|
+
/** The ingest cursor's floor as the transaction sees it; a missing or unreadable cursor is simply not carried. */
|
|
5
|
+
export async function cursorFloor(tx) {
|
|
6
|
+
try {
|
|
7
|
+
return (await readIngestCursor(tx.artifact('ingestCursor')))?.since;
|
|
8
|
+
}
|
|
9
|
+
catch {
|
|
10
|
+
return undefined;
|
|
11
|
+
}
|
|
12
|
+
}
|
|
13
|
+
/** Runs every registered hook, in order, each in the group's `onConfirm` re-entrancy frame. A throw propagates. */
|
|
14
|
+
export async function runConfirmHooks(site, run) {
|
|
15
|
+
const hooks = [...site.hooks];
|
|
16
|
+
if (hooks.length === 0)
|
|
17
|
+
return;
|
|
18
|
+
const since = await cursorFloor(run.tx);
|
|
19
|
+
let open = true;
|
|
20
|
+
let sealed;
|
|
21
|
+
const snapshotOf = () => {
|
|
22
|
+
if (sealed !== undefined)
|
|
23
|
+
return sealed;
|
|
24
|
+
if (!open) {
|
|
25
|
+
throw new MarmotError('transaction-closed', 'ConfirmContext.snapshot: read after the confirming transaction\'s hooks returned; read it inside the hook', {
|
|
26
|
+
details: { groupId: site.groupId, intentId: run.intentId },
|
|
27
|
+
});
|
|
28
|
+
}
|
|
29
|
+
const { state, window } = run.persisted();
|
|
30
|
+
sealed = sealGroupSnapshot({
|
|
31
|
+
groupId: site.groupId,
|
|
32
|
+
state,
|
|
33
|
+
window,
|
|
34
|
+
...(run.createdAt === undefined ? {} : { createdAt: run.createdAt }),
|
|
35
|
+
...(since === undefined ? {} : { since }),
|
|
36
|
+
});
|
|
37
|
+
return sealed;
|
|
38
|
+
};
|
|
39
|
+
try {
|
|
40
|
+
for (const hook of hooks) {
|
|
41
|
+
const context = {
|
|
42
|
+
groupId: site.groupId,
|
|
43
|
+
intentId: run.intentId,
|
|
44
|
+
kind: run.kind,
|
|
45
|
+
epoch: run.epoch,
|
|
46
|
+
tx: run.tx,
|
|
47
|
+
notifications: run.notifications,
|
|
48
|
+
get snapshot() {
|
|
49
|
+
return snapshotOf();
|
|
50
|
+
},
|
|
51
|
+
...(run.forgetting === undefined ? {} : { forgetting: { leafKeys: [...run.forgetting.leafKeys] } }),
|
|
52
|
+
};
|
|
53
|
+
await site.guard.call(site.groupId, 'onConfirm', () => hook(context));
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
finally {
|
|
57
|
+
open = false;
|
|
58
|
+
}
|
|
59
|
+
}
|