@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,36 @@
|
|
|
1
|
+
import type { RemovalRecord } from '@941design/marmot-engine/engine';
|
|
2
|
+
import { type ClientState } from '@941design/marmot-engine/mls';
|
|
3
|
+
import type { KeyValueView } from '../storage/index.js';
|
|
4
|
+
/** Group extension holding the revisable removal (one record). */
|
|
5
|
+
export declare const REMOVAL_EXTENSION = "marmot.removal";
|
|
6
|
+
/**
|
|
7
|
+
* Default `removalSettleMs` (10 s). A sibling of the race was built at the same epoch, concurrently with the
|
|
8
|
+
* removal, so it is normally on the relays as soon as the removal is: the window covers its propagation, twice
|
|
9
|
+
* the convergence policy's longest convergence pass (`maxConvergencePassMs`, 5 s — the engine's own bound on
|
|
10
|
+
* collecting one race's input), one catch-up history page (`historyTimeoutMs`, 10 s) and its committer's first
|
|
11
|
+
* three publish retries (1 + 2 + 4 s backoff). It is also what a `leave()` / own-leaf `devices.forget` now waits
|
|
12
|
+
* after the removal before it purges, so it is kept short.
|
|
13
|
+
*/
|
|
14
|
+
export declare const DEFAULT_REMOVAL_SETTLE_MS = 10000;
|
|
15
|
+
/** The persisted removal: the engine's record and when it was first held (client clock). */
|
|
16
|
+
export interface HeldRemoval {
|
|
17
|
+
readonly record: RemovalRecord;
|
|
18
|
+
readonly removedAt: number;
|
|
19
|
+
}
|
|
20
|
+
/** The record's parent tag: the removal's identity across updates (a competing removal at the same parent keeps `removedAt`). */
|
|
21
|
+
export declare function parentTagOf(record: RemovalRecord): string;
|
|
22
|
+
export declare function readRemoval(view: KeyValueView): Promise<HeldRemoval | undefined>;
|
|
23
|
+
/** Writes (or replaces) the held removal inside the caller's transaction. */
|
|
24
|
+
export declare function writeRemoval(view: KeyValueView, held: HeldRemoval): Promise<void>;
|
|
25
|
+
export declare function clearRemoval(view: KeyValueView): Promise<void>;
|
|
26
|
+
/**
|
|
27
|
+
* What to persist after the engine's removal moved from `before` to `now`:
|
|
28
|
+
* `undefined` = unchanged (nothing to write), `null` = delete, else the new
|
|
29
|
+
* record — `removedAt` kept while the removal's parent is the same (a
|
|
30
|
+
* competing removal joined it), `nowMs` for a new removal.
|
|
31
|
+
*/
|
|
32
|
+
export declare function nextHeldRemoval(before: HeldRemoval | undefined, now: RemovalRecord | undefined, nowMs: number): HeldRemoval | null | undefined;
|
|
33
|
+
/** Client-clock time the held removal settles (`undefined`: none held). */
|
|
34
|
+
export declare function settlesAt(held: HeldRemoval | undefined, removalSettleMs: number): number | undefined;
|
|
35
|
+
/** Whether `state` is the tombstone of `held` (the stored removal belongs to the stored state). */
|
|
36
|
+
export declare function belongsTo(held: HeldRemoval | undefined, state: ClientState): held is HeldRemoval;
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* S20 (AC-ADMIN-10, AC-INV-4; BACKLOG same-epoch-fork-removal-divergence):
|
|
3
|
+
* the revisable removal of the local leaf.
|
|
4
|
+
*
|
|
5
|
+
* When two commits race at one epoch and only one of them removes this
|
|
6
|
+
* device's leaf, the device may apply either first. Its engines run the
|
|
7
|
+
* `removalConvergence` seam: a removal is a fork-recovery candidate like any
|
|
8
|
+
* other branch, and while one is held the engine keeps reading the group's
|
|
9
|
+
* input as fork material for it — so the device rewinds INTO the removal when
|
|
10
|
+
* the removing branch wins and OUT of it when a sibling wins.
|
|
11
|
+
*
|
|
12
|
+
* What the device decides by itself (ADR-017, removal finality, which marmot
|
|
13
|
+
* opts in to): it cannot read past a commit that removes it, so it scores
|
|
14
|
+
* the race at the fork point `P` with the removal as a virtual
|
|
15
|
+
* `removal:<digest>` edge (the engine's `#reconvergeWithRemovals`). That edge
|
|
16
|
+
* carries every leaf the removal removes, read from the tombstone's ratchet
|
|
17
|
+
* tree (R-1, the members' own facts), so the device scores as the members
|
|
18
|
+
* do: commits by a removed leaf — its own included — earn nothing at `P`,
|
|
19
|
+
* and on a finality tie the removal is preferred. A device still on a
|
|
20
|
+
* keeping branch, or on its own commits built there, therefore takes the
|
|
21
|
+
* removal from the removing commit alone, with no further message.
|
|
22
|
+
*
|
|
23
|
+
* What remains (ADR-017 AR-R3; liveness only, never a zombie): the device
|
|
24
|
+
* keeps its branch while the members keep the removal only when (i) members
|
|
25
|
+
* extended the removal with commits the device cannot read while the
|
|
26
|
+
* device's branch carries keeper-side finality of at least 2 (two commits by
|
|
27
|
+
* leaves present at `P` that the removal does not remove), or (ii) the guard
|
|
28
|
+
* failed: the keeping branch reaches more than `maxRewindCommits` past `P`
|
|
29
|
+
* (today's ordering decides), or the device's tip is past `P`'s horizon
|
|
30
|
+
* (nothing is eligible; it stays). There an own-leaf forget (its per-group
|
|
31
|
+
* `leave()`) times out and its tombstone LISTS the group. And AC-INV-4
|
|
32
|
+
* exclusion (ii): a winning sibling first delivered to this device after
|
|
33
|
+
* `removalSettleMs` (below) finds the removal settled.
|
|
34
|
+
*
|
|
35
|
+
* The removal the engine holds is persisted here — the group extension
|
|
36
|
+
* `marmot.removal`, written in the same transaction as the tombstone
|
|
37
|
+
* `clientState` it belongs to (and deleted in the one that leaves it) — with
|
|
38
|
+
* the client-clock time it was first held. It stays revisable for
|
|
39
|
+
* `removalSettleMs`; after that it is SETTLED: the engine drops it (input is
|
|
40
|
+
* `self-evicted` again, terminal in the ledger) and the record is deleted.
|
|
41
|
+
* `leave()` (and an own-leaf `devices.forget`) concludes `removed` — purge,
|
|
42
|
+
* tombstone — only once the removal is settled (teardown reads
|
|
43
|
+
* `LeaveView.removalSettlesAt`), so a winning sibling that arrives inside the
|
|
44
|
+
* window brings the device back instead of leaving a zombie.
|
|
45
|
+
*
|
|
46
|
+
* Why a time window: a removed device cannot read the members' later epochs,
|
|
47
|
+
* so nothing the group sends can tell it the race is over. The window covers
|
|
48
|
+
* the race's own propagation (see {@link DEFAULT_REMOVAL_SETTLE_MS}). The
|
|
49
|
+
* rollback horizon bounds the race by commits, not time: members still
|
|
50
|
+
* converge onto a sibling that arrives later, while `maxRewindCommits` (5)
|
|
51
|
+
* commits have not passed over it — a sibling first delivered to this device
|
|
52
|
+
* after its window (a committer offline for longer) is the residue no finite
|
|
53
|
+
* window closes.
|
|
54
|
+
*/
|
|
55
|
+
import { deserializeClientState, serializeClientState } from '@941design/marmot-engine/core';
|
|
56
|
+
import { decode, encode, mlsMessageDecoder, mlsMessageEncoder } from '@941design/marmot-engine/mls';
|
|
57
|
+
/** Group extension holding the revisable removal (one record). */
|
|
58
|
+
export const REMOVAL_EXTENSION = 'marmot.removal';
|
|
59
|
+
const KEY = 'removal';
|
|
60
|
+
/**
|
|
61
|
+
* Default `removalSettleMs` (10 s). A sibling of the race was built at the same epoch, concurrently with the
|
|
62
|
+
* removal, so it is normally on the relays as soon as the removal is: the window covers its propagation, twice
|
|
63
|
+
* the convergence policy's longest convergence pass (`maxConvergencePassMs`, 5 s — the engine's own bound on
|
|
64
|
+
* collecting one race's input), one catch-up history page (`historyTimeoutMs`, 10 s) and its committer's first
|
|
65
|
+
* three publish retries (1 + 2 + 4 s backoff). It is also what a `leave()` / own-leaf `devices.forget` now waits
|
|
66
|
+
* after the removal before it purges, so it is kept short.
|
|
67
|
+
*/
|
|
68
|
+
export const DEFAULT_REMOVAL_SETTLE_MS = 10_000;
|
|
69
|
+
function wire(message) {
|
|
70
|
+
return encode(mlsMessageEncoder, message);
|
|
71
|
+
}
|
|
72
|
+
function hex(bytes) {
|
|
73
|
+
let out = '';
|
|
74
|
+
for (const b of bytes)
|
|
75
|
+
out += b.toString(16).padStart(2, '0');
|
|
76
|
+
return out;
|
|
77
|
+
}
|
|
78
|
+
/** The record's parent tag: the removal's identity across updates (a competing removal at the same parent keeps `removedAt`). */
|
|
79
|
+
export function parentTagOf(record) {
|
|
80
|
+
return hex(record.parentState.confirmationTag);
|
|
81
|
+
}
|
|
82
|
+
export async function readRemoval(view) {
|
|
83
|
+
const raw = (await view.get(KEY));
|
|
84
|
+
if (typeof raw !== 'object' || raw === null || !(raw.p instanceof Uint8Array) || !Array.isArray(raw.c) || typeof raw.at !== 'number')
|
|
85
|
+
return undefined;
|
|
86
|
+
const commits = [];
|
|
87
|
+
for (const bytes of raw.c) {
|
|
88
|
+
if (!(bytes instanceof Uint8Array))
|
|
89
|
+
return undefined;
|
|
90
|
+
const message = decode(mlsMessageDecoder, bytes);
|
|
91
|
+
if (message === undefined)
|
|
92
|
+
return undefined;
|
|
93
|
+
commits.push(message);
|
|
94
|
+
}
|
|
95
|
+
if (commits.length === 0)
|
|
96
|
+
return undefined;
|
|
97
|
+
return { record: { parentState: deserializeClientState(raw.p), commits }, removedAt: raw.at };
|
|
98
|
+
}
|
|
99
|
+
/** Writes (or replaces) the held removal inside the caller's transaction. */
|
|
100
|
+
export async function writeRemoval(view, held) {
|
|
101
|
+
await view.put(KEY, { p: serializeClientState(held.record.parentState), c: held.record.commits.map(wire), at: held.removedAt });
|
|
102
|
+
}
|
|
103
|
+
export async function clearRemoval(view) {
|
|
104
|
+
await view.delete(KEY);
|
|
105
|
+
}
|
|
106
|
+
/**
|
|
107
|
+
* What to persist after the engine's removal moved from `before` to `now`:
|
|
108
|
+
* `undefined` = unchanged (nothing to write), `null` = delete, else the new
|
|
109
|
+
* record — `removedAt` kept while the removal's parent is the same (a
|
|
110
|
+
* competing removal joined it), `nowMs` for a new removal.
|
|
111
|
+
*/
|
|
112
|
+
export function nextHeldRemoval(before, now, nowMs) {
|
|
113
|
+
if (now === before?.record)
|
|
114
|
+
return undefined;
|
|
115
|
+
if (now === undefined)
|
|
116
|
+
return before === undefined ? undefined : null;
|
|
117
|
+
const removedAt = before !== undefined && parentTagOf(before.record) === parentTagOf(now) ? before.removedAt : nowMs;
|
|
118
|
+
return { record: now, removedAt };
|
|
119
|
+
}
|
|
120
|
+
/** Client-clock time the held removal settles (`undefined`: none held). */
|
|
121
|
+
export function settlesAt(held, removalSettleMs) {
|
|
122
|
+
return held === undefined ? undefined : held.removedAt + removalSettleMs;
|
|
123
|
+
}
|
|
124
|
+
/** Whether `state` is the tombstone of `held` (the stored removal belongs to the stored state). */
|
|
125
|
+
export function belongsTo(held, state) {
|
|
126
|
+
return held !== undefined && state.groupActiveState.kind === 'removedFromGroup' && parentTagOf(held.record) === hex(state.confirmationTag);
|
|
127
|
+
}
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import { type ClientState, type Proposal } from '@941design/marmot-engine/mls';
|
|
2
|
+
import { type RetainedWindow } from '../history/index.js';
|
|
3
|
+
import { MarmotError } from '../shared/index.js';
|
|
4
|
+
/** Throws `MarmotError('invalid-options')` (`details.reason: 'malformed-account'`) unless `account` is a 64-lowercase-hex pubkey string. */
|
|
5
|
+
export declare function assertAccountPubkey(operation: string, account: unknown): asserts account is string;
|
|
6
|
+
/** Whether `state`'s tree holds at least one leaf of any of `accounts`. */
|
|
7
|
+
export declare function holdsLeafOfAny(state: ClientState, accounts: readonly string[]): boolean;
|
|
8
|
+
/**
|
|
9
|
+
* One Remove per leaf of each of `accounts` in `state`'s tree, skipping every leaf a staged Remove or SelfRemove
|
|
10
|
+
* already targets (the commit carries that staged proposal by reference). Empty when the accounts hold no leaf, and
|
|
11
|
+
* also when every leaf they hold is already staged for removal; {@link holdsLeafOfAny} tells those two apart.
|
|
12
|
+
*/
|
|
13
|
+
export declare function removeProposalsForAccounts(state: ClientState, accounts: readonly string[]): Proposal[];
|
|
14
|
+
/** The signature keys (hex) of every leaf `account` holds in `state`: the snapshot a `removeMember` record keeps. */
|
|
15
|
+
export declare function leafKeysOfAccount(state: ClientState, account: string): string[];
|
|
16
|
+
/** Whether `state`'s tree still holds a leaf with one of the signature keys `leafKeys` (hex). */
|
|
17
|
+
export declare function holdsAnyLeafKey(state: ClientState, leafKeys: readonly string[]): boolean;
|
|
18
|
+
/**
|
|
19
|
+
* `seed` united with every key reached from one of its members by a signature-key succession edge of one of `accounts`
|
|
20
|
+
* (`fromLeafKey` to `toLeafKey`, followed transitively and in any order): the keys a leaf recorded under `seed` can carry
|
|
21
|
+
* by now. Edges of other accounts are ignored. Total, and it terminates on cycles.
|
|
22
|
+
*/
|
|
23
|
+
export declare function keysReachedBySuccession(seed: readonly string[], successions: Iterable<{
|
|
24
|
+
readonly account: string;
|
|
25
|
+
readonly fromLeafKey: string;
|
|
26
|
+
readonly toLeafKey: string;
|
|
27
|
+
}>, accounts: readonly string[]): Set<string>;
|
|
28
|
+
/**
|
|
29
|
+
* Whether `accounts` still hold a leaf a `removeMember` call recorded (`snapshot`: the leaf keys they held when it was
|
|
30
|
+
* called) — epic marmot-device-key-rotation, Design Decision 12. A leaf counts when it carries a snapshot key, or a key
|
|
31
|
+
* the snapshot's leaf was replaced by in place (a signature-key succession of the account on the canonical path of the
|
|
32
|
+
* retained `window`), or a key it was replaced FROM by a rotation the window shows only on an abandoned branch (the call
|
|
33
|
+
* saw the rotation, a rewind has since withdrawn it, and the same leaf is back on its earlier key). A same-device re-add
|
|
34
|
+
* under a key the lineage reaches counts too (admin-ops residual 5, unchanged); a leaf got by being Removed and Added again
|
|
35
|
+
* with a fresh KeyPackage has no succession edge and does not, so a membership added after the call stays "added later".
|
|
36
|
+
* `state` is the tree the commit will be built on (the engine's); `windowTip` is the window's own tip state (the exposed one).
|
|
37
|
+
* The window is read only when no snapshot key is held directly. An edge the window no longer retains (below its floor) is
|
|
38
|
+
* not seen: the match then falls back to the pre-S11 answer (the record is dropped as absent). Never throws.
|
|
39
|
+
*/
|
|
40
|
+
export declare function holdsSnapshotLeaf(state: ClientState, window: RetainedWindow, snapshot: readonly string[], accounts: readonly string[], windowTip?: ClientState): boolean;
|
|
41
|
+
/**
|
|
42
|
+
* The refusal of a commit that would remove `accounts` / `leafKeys` while a staged Add admits a leaf of the same account /
|
|
43
|
+
* the same leaf key: the commit carries that Add by reference, so the removed party would keep (or regain) a leaf in the
|
|
44
|
+
* very commit that removes it. `undefined` when no staged Add names them.
|
|
45
|
+
*/
|
|
46
|
+
export declare function stagedAddConflict(operation: string, groupId: string, state: ClientState, removed: {
|
|
47
|
+
readonly accounts?: readonly string[] | undefined;
|
|
48
|
+
readonly leafKeys?: readonly string[] | undefined;
|
|
49
|
+
}): MarmotError | undefined;
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `MarmotGroup.removeMember` helpers: the account argument's validation and the build-time expansion of an account
|
|
3
|
+
* into one Remove per leaf it holds NOW. The stored intent records the account (`removeAccounts`), never leaf indexes,
|
|
4
|
+
* so a record resumed after a reload removes whatever the account holds when the commit is built (Design Decision 4).
|
|
5
|
+
*/
|
|
6
|
+
import { getCredentialPubkey, getPubkeyLeafNodeIndexes, getPubkeyLeafNodes } from '@941design/marmot-engine/core';
|
|
7
|
+
import { defaultProposalTypes, nodeTypes, selfRemoveProposalType } from '@941design/marmot-engine/mls';
|
|
8
|
+
import { abandonedSuccessionsInWindow, successionsInWindow } from '../history/index.js';
|
|
9
|
+
import { MarmotError, isAccountPubkey } from '../shared/index.js';
|
|
10
|
+
/** Throws `MarmotError('invalid-options')` (`details.reason: 'malformed-account'`) unless `account` is a 64-lowercase-hex pubkey string. */
|
|
11
|
+
export function assertAccountPubkey(operation, account) {
|
|
12
|
+
if (!isAccountPubkey(account)) {
|
|
13
|
+
throw new MarmotError('invalid-options', `${operation}: account must be a 64-character lowercase hex pubkey`, { details: { reason: 'malformed-account' } });
|
|
14
|
+
}
|
|
15
|
+
}
|
|
16
|
+
/** Whether `state`'s tree holds at least one leaf of any of `accounts`. */
|
|
17
|
+
export function holdsLeafOfAny(state, accounts) {
|
|
18
|
+
return accounts.some((account) => getPubkeyLeafNodeIndexes(state, account).length > 0);
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* The leaf indexes a staged proposal of `state` already removes: the target of each staged Remove, and the sender of
|
|
22
|
+
* each staged SelfRemove. A commit carries those proposals by reference, so an own Remove of the same leaf would be a
|
|
23
|
+
* second removal of it.
|
|
24
|
+
*/
|
|
25
|
+
function stagedRemovalTargets(state) {
|
|
26
|
+
const targets = new Set();
|
|
27
|
+
for (const { proposal, senderLeafIndex } of Object.values(state.unappliedProposals)) {
|
|
28
|
+
if (proposal.proposalType === defaultProposalTypes.remove && 'remove' in proposal)
|
|
29
|
+
targets.add(Number(proposal.remove.removed));
|
|
30
|
+
else if (proposal.proposalType === selfRemoveProposalType && senderLeafIndex !== undefined)
|
|
31
|
+
targets.add(Number(senderLeafIndex));
|
|
32
|
+
}
|
|
33
|
+
return targets;
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* One Remove per leaf of each of `accounts` in `state`'s tree, skipping every leaf a staged Remove or SelfRemove
|
|
37
|
+
* already targets (the commit carries that staged proposal by reference). Empty when the accounts hold no leaf, and
|
|
38
|
+
* also when every leaf they hold is already staged for removal; {@link holdsLeafOfAny} tells those two apart.
|
|
39
|
+
*/
|
|
40
|
+
export function removeProposalsForAccounts(state, accounts) {
|
|
41
|
+
const staged = stagedRemovalTargets(state);
|
|
42
|
+
const out = [];
|
|
43
|
+
for (const account of accounts) {
|
|
44
|
+
for (const leafIndex of getPubkeyLeafNodeIndexes(state, account)) {
|
|
45
|
+
if (staged.has(leafIndex))
|
|
46
|
+
continue;
|
|
47
|
+
out.push({ proposalType: defaultProposalTypes.remove, remove: { removed: leafIndex } });
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
return out;
|
|
51
|
+
}
|
|
52
|
+
const toHex = (bytes) => Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
|
|
53
|
+
/** The signature keys (hex) of every leaf `account` holds in `state`: the snapshot a `removeMember` record keeps. */
|
|
54
|
+
export function leafKeysOfAccount(state, account) {
|
|
55
|
+
return getPubkeyLeafNodes(state, account).map((leaf) => toHex(leaf.signaturePublicKey));
|
|
56
|
+
}
|
|
57
|
+
/** Whether `state`'s tree still holds a leaf with one of the signature keys `leafKeys` (hex). */
|
|
58
|
+
export function holdsAnyLeafKey(state, leafKeys) {
|
|
59
|
+
const wanted = new Set(leafKeys);
|
|
60
|
+
const leafCount = Math.ceil(state.ratchetTree.length / 2);
|
|
61
|
+
for (let i = 0; i < leafCount; i++) {
|
|
62
|
+
const node = state.ratchetTree[2 * i];
|
|
63
|
+
if (node?.nodeType === nodeTypes.leaf && wanted.has(toHex(node.leaf.signaturePublicKey)))
|
|
64
|
+
return true;
|
|
65
|
+
}
|
|
66
|
+
return false;
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* `seed` united with every key reached from one of its members by a signature-key succession edge of one of `accounts`
|
|
70
|
+
* (`fromLeafKey` to `toLeafKey`, followed transitively and in any order): the keys a leaf recorded under `seed` can carry
|
|
71
|
+
* by now. Edges of other accounts are ignored. Total, and it terminates on cycles.
|
|
72
|
+
*/
|
|
73
|
+
export function keysReachedBySuccession(seed, successions, accounts) {
|
|
74
|
+
const listed = new Set(accounts);
|
|
75
|
+
const next = new Map();
|
|
76
|
+
for (const { account, fromLeafKey, toLeafKey } of successions) {
|
|
77
|
+
if (!listed.has(account))
|
|
78
|
+
continue;
|
|
79
|
+
const to = next.get(fromLeafKey);
|
|
80
|
+
if (to === undefined)
|
|
81
|
+
next.set(fromLeafKey, [toLeafKey]);
|
|
82
|
+
else
|
|
83
|
+
to.push(toLeafKey);
|
|
84
|
+
}
|
|
85
|
+
const reached = new Set(seed);
|
|
86
|
+
const queue = [...reached];
|
|
87
|
+
for (let key = queue.pop(); key !== undefined; key = queue.pop()) {
|
|
88
|
+
for (const to of next.get(key) ?? []) {
|
|
89
|
+
if (reached.has(to))
|
|
90
|
+
continue;
|
|
91
|
+
reached.add(to);
|
|
92
|
+
queue.push(to);
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
return reached;
|
|
96
|
+
}
|
|
97
|
+
/**
|
|
98
|
+
* Whether `accounts` still hold a leaf a `removeMember` call recorded (`snapshot`: the leaf keys they held when it was
|
|
99
|
+
* called) — epic marmot-device-key-rotation, Design Decision 12. A leaf counts when it carries a snapshot key, or a key
|
|
100
|
+
* the snapshot's leaf was replaced by in place (a signature-key succession of the account on the canonical path of the
|
|
101
|
+
* retained `window`), or a key it was replaced FROM by a rotation the window shows only on an abandoned branch (the call
|
|
102
|
+
* saw the rotation, a rewind has since withdrawn it, and the same leaf is back on its earlier key). A same-device re-add
|
|
103
|
+
* under a key the lineage reaches counts too (admin-ops residual 5, unchanged); a leaf got by being Removed and Added again
|
|
104
|
+
* with a fresh KeyPackage has no succession edge and does not, so a membership added after the call stays "added later".
|
|
105
|
+
* `state` is the tree the commit will be built on (the engine's); `windowTip` is the window's own tip state (the exposed one).
|
|
106
|
+
* The window is read only when no snapshot key is held directly. An edge the window no longer retains (below its floor) is
|
|
107
|
+
* not seen: the match then falls back to the pre-S11 answer (the record is dropped as absent). Never throws.
|
|
108
|
+
*/
|
|
109
|
+
export function holdsSnapshotLeaf(state, window, snapshot, accounts, windowTip = state) {
|
|
110
|
+
if (holdsAnyLeafKey(state, snapshot))
|
|
111
|
+
return true;
|
|
112
|
+
const canonical = successionsInWindow(window, windowTip);
|
|
113
|
+
const abandoned = abandonedSuccessionsInWindow(window, windowTip);
|
|
114
|
+
if (canonical.length === 0 && abandoned.length === 0)
|
|
115
|
+
return false;
|
|
116
|
+
const listed = new Set(accounts);
|
|
117
|
+
// Predecessors along abandoned edges (K -> K' with K' a snapshot key), transitively; then forward along canonical ones.
|
|
118
|
+
const seed = new Set(snapshot);
|
|
119
|
+
for (let grown = true; grown;) {
|
|
120
|
+
grown = false;
|
|
121
|
+
for (const e of abandoned) {
|
|
122
|
+
if (listed.has(e.account) && seed.has(e.toLeafKey) && !seed.has(e.fromLeafKey))
|
|
123
|
+
(seed.add(e.fromLeafKey), (grown = true));
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
return holdsAnyLeafKey(state, [...keysReachedBySuccession([...seed], canonical, accounts)]);
|
|
127
|
+
}
|
|
128
|
+
/** Each staged Add's KeyPackage leaf: its account (credential pubkey, when it has one) and signature key (hex). */
|
|
129
|
+
function stagedAddLeaves(state) {
|
|
130
|
+
const out = [];
|
|
131
|
+
for (const { proposal } of Object.values(state.unappliedProposals)) {
|
|
132
|
+
if (proposal.proposalType !== defaultProposalTypes.add || !('add' in proposal))
|
|
133
|
+
continue;
|
|
134
|
+
const leaf = proposal.add.keyPackage.leafNode;
|
|
135
|
+
let account;
|
|
136
|
+
try {
|
|
137
|
+
account = getCredentialPubkey(leaf.credential);
|
|
138
|
+
}
|
|
139
|
+
catch {
|
|
140
|
+
account = undefined;
|
|
141
|
+
}
|
|
142
|
+
out.push({ account, leafKey: toHex(leaf.signaturePublicKey) });
|
|
143
|
+
}
|
|
144
|
+
return out;
|
|
145
|
+
}
|
|
146
|
+
/**
|
|
147
|
+
* The refusal of a commit that would remove `accounts` / `leafKeys` while a staged Add admits a leaf of the same account /
|
|
148
|
+
* the same leaf key: the commit carries that Add by reference, so the removed party would keep (or regain) a leaf in the
|
|
149
|
+
* very commit that removes it. `undefined` when no staged Add names them.
|
|
150
|
+
*/
|
|
151
|
+
export function stagedAddConflict(operation, groupId, state, removed) {
|
|
152
|
+
const accounts = new Set(removed.accounts ?? []);
|
|
153
|
+
const leafKeys = new Set(removed.leafKeys ?? []);
|
|
154
|
+
for (const add of stagedAddLeaves(state)) {
|
|
155
|
+
const ofAccount = add.account !== undefined && accounts.has(add.account);
|
|
156
|
+
if (!ofAccount && !leafKeys.has(add.leafKey))
|
|
157
|
+
continue;
|
|
158
|
+
return new MarmotError('send-rejected', `${operation}: a staged Add proposal admits a ${ofAccount ? 'leaf of the account being removed' : 'leaf being removed'} on group ${groupId}; commit that proposal first (send({ type: 'commit' })) and retry`, {
|
|
159
|
+
details: { groupId, reason: ofAccount ? 'staged-add-of-removed-account' : 'staged-add-of-removed-leaf' },
|
|
160
|
+
});
|
|
161
|
+
}
|
|
162
|
+
return undefined;
|
|
163
|
+
}
|