@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.
Files changed (192) hide show
  1. package/CHANGELOG.md +709 -0
  2. package/LICENSE +21 -0
  3. package/README.md +33 -2
  4. package/dist/account/admin.d.ts +72 -0
  5. package/dist/account/admin.js +209 -0
  6. package/dist/account/device-deps.d.ts +379 -0
  7. package/dist/account/device-deps.js +36 -0
  8. package/dist/account/device-lineage.d.ts +199 -0
  9. package/dist/account/device-lineage.js +390 -0
  10. package/dist/account/device-registry.d.ts +93 -0
  11. package/dist/account/device-registry.js +1290 -0
  12. package/dist/account/device-rotation.d.ts +61 -0
  13. package/dist/account/device-rotation.js +827 -0
  14. package/dist/account/enrolment.d.ts +339 -0
  15. package/dist/account/enrolment.js +1247 -0
  16. package/dist/account/identity-proof.d.ts +79 -0
  17. package/dist/account/identity-proof.js +264 -0
  18. package/dist/account/index.d.ts +17 -0
  19. package/dist/account/index.js +16 -0
  20. package/dist/account/restore-rotation.d.ts +21 -0
  21. package/dist/account/restore-rotation.js +22 -0
  22. package/dist/account/same-account-authorization.d.ts +86 -0
  23. package/dist/account/same-account-authorization.js +180 -0
  24. package/dist/account/teardown.d.ts +127 -0
  25. package/dist/account/teardown.js +856 -0
  26. package/dist/client/before-create-group.d.ts +18 -0
  27. package/dist/client/before-create-group.js +65 -0
  28. package/dist/client/before-publish-hooks.d.ts +121 -0
  29. package/dist/client/before-publish-hooks.js +180 -0
  30. package/dist/client/client-config.d.ts +42 -0
  31. package/dist/client/client-config.js +13 -0
  32. package/dist/client/commit-redrive.d.ts +68 -0
  33. package/dist/client/commit-redrive.js +221 -0
  34. package/dist/client/component-update.d.ts +43 -0
  35. package/dist/client/component-update.js +53 -0
  36. package/dist/client/confirm-hooks.d.ts +50 -0
  37. package/dist/client/confirm-hooks.js +59 -0
  38. package/dist/client/create-client.d.ts +1022 -0
  39. package/dist/client/create-client.js +1125 -0
  40. package/dist/client/group-disband.d.ts +28 -0
  41. package/dist/client/group-disband.js +64 -0
  42. package/dist/client/group-history.d.ts +435 -0
  43. package/dist/client/group-history.js +1295 -0
  44. package/dist/client/group-profile.d.ts +31 -0
  45. package/dist/client/group-profile.js +62 -0
  46. package/dist/client/group-records.d.ts +485 -0
  47. package/dist/client/group-records.js +1034 -0
  48. package/dist/client/group-removal.d.ts +36 -0
  49. package/dist/client/group-removal.js +127 -0
  50. package/dist/client/group-remove-member.d.ts +49 -0
  51. package/dist/client/group-remove-member.js +163 -0
  52. package/dist/client/group-runtime.d.ts +388 -0
  53. package/dist/client/group-runtime.js +2701 -0
  54. package/dist/client/group-snapshot.d.ts +98 -0
  55. package/dist/client/group-snapshot.js +453 -0
  56. package/dist/client/history-pages.d.ts +107 -0
  57. package/dist/client/history-pages.js +194 -0
  58. package/dist/client/inbox-send.d.ts +19 -0
  59. package/dist/client/inbox-send.js +71 -0
  60. package/dist/client/index.d.ts +21 -0
  61. package/dist/client/index.js +13 -0
  62. package/dist/client/ingest.d.ts +82 -0
  63. package/dist/client/ingest.js +1550 -0
  64. package/dist/client/lifecycle-events.d.ts +63 -0
  65. package/dist/client/lifecycle-events.js +35 -0
  66. package/dist/client/opaque-candidates.d.ts +81 -0
  67. package/dist/client/opaque-candidates.js +169 -0
  68. package/dist/client/own-change-outbox.d.ts +66 -0
  69. package/dist/client/own-change-outbox.js +156 -0
  70. package/dist/client/pending-leaf.d.ts +116 -0
  71. package/dist/client/pending-leaf.js +378 -0
  72. package/dist/client/permissions.d.ts +9 -0
  73. package/dist/client/permissions.js +12 -0
  74. package/dist/client/pipeline.d.ts +554 -0
  75. package/dist/client/pipeline.js +3545 -0
  76. package/dist/client/reentrancy-guard.d.ts +96 -0
  77. package/dist/client/reentrancy-guard.js +153 -0
  78. package/dist/client/rekey.d.ts +58 -0
  79. package/dist/client/rekey.js +149 -0
  80. package/dist/client/transport-policy.d.ts +181 -0
  81. package/dist/client/transport-policy.js +214 -0
  82. package/dist/history/equivocation.d.ts +55 -0
  83. package/dist/history/equivocation.js +113 -0
  84. package/dist/history/fencing.d.ts +25 -0
  85. package/dist/history/fencing.js +61 -0
  86. package/dist/history/hex.d.ts +3 -0
  87. package/dist/history/hex.js +10 -0
  88. package/dist/history/index.d.ts +73 -0
  89. package/dist/history/index.js +31 -0
  90. package/dist/history/notifications.d.ts +270 -0
  91. package/dist/history/notifications.js +264 -0
  92. package/dist/history/ordering-key.d.ts +24 -0
  93. package/dist/history/ordering-key.js +101 -0
  94. package/dist/history/own-change-fork.d.ts +112 -0
  95. package/dist/history/own-change-fork.js +196 -0
  96. package/dist/history/own-change.d.ts +106 -0
  97. package/dist/history/own-change.js +146 -0
  98. package/dist/history/policy.d.ts +48 -0
  99. package/dist/history/policy.js +52 -0
  100. package/dist/history/retained-window.d.ts +215 -0
  101. package/dist/history/retained-window.js +565 -0
  102. package/dist/inbox/demux.d.ts +90 -0
  103. package/dist/inbox/demux.js +78 -0
  104. package/dist/inbox/handler-registry.d.ts +42 -0
  105. package/dist/inbox/handler-registry.js +37 -0
  106. package/dist/inbox/index.d.ts +11 -0
  107. package/dist/inbox/index.js +10 -0
  108. package/dist/inbox/seen-set.d.ts +82 -0
  109. package/dist/inbox/seen-set.js +202 -0
  110. package/dist/inbox/subscription.d.ts +236 -0
  111. package/dist/inbox/subscription.js +644 -0
  112. package/dist/index.d.ts +10 -0
  113. package/dist/index.js +9 -0
  114. package/dist/invitations/competing-welcome.d.ts +223 -0
  115. package/dist/invitations/competing-welcome.js +128 -0
  116. package/dist/invitations/decline.d.ts +61 -0
  117. package/dist/invitations/decline.js +143 -0
  118. package/dist/invitations/expect-welcome.d.ts +66 -0
  119. package/dist/invitations/expect-welcome.js +138 -0
  120. package/dist/invitations/index.d.ts +16 -0
  121. package/dist/invitations/index.js +16 -0
  122. package/dist/invitations/invite.d.ts +303 -0
  123. package/dist/invitations/invite.js +966 -0
  124. package/dist/invitations/offers.d.ts +79 -0
  125. package/dist/invitations/offers.js +115 -0
  126. package/dist/invitations/on-proposal.d.ts +47 -0
  127. package/dist/invitations/on-proposal.js +40 -0
  128. package/dist/invitations/pending-proposal-policy.d.ts +52 -0
  129. package/dist/invitations/pending-proposal-policy.js +139 -0
  130. package/dist/invitations/proposal-deadline.d.ts +133 -0
  131. package/dist/invitations/proposal-deadline.js +164 -0
  132. package/dist/invitations/relay-planes.d.ts +43 -0
  133. package/dist/invitations/relay-planes.js +70 -0
  134. package/dist/invitations/welcome-processor.d.ts +253 -0
  135. package/dist/invitations/welcome-processor.js +1180 -0
  136. package/dist/key-packages/device-key.d.ts +131 -0
  137. package/dist/key-packages/device-key.js +272 -0
  138. package/dist/key-packages/device-rotation-records.d.ts +83 -0
  139. package/dist/key-packages/device-rotation-records.js +173 -0
  140. package/dist/key-packages/group-refs.d.ts +40 -0
  141. package/dist/key-packages/group-refs.js +79 -0
  142. package/dist/key-packages/index.d.ts +18 -0
  143. package/dist/key-packages/index.js +18 -0
  144. package/dist/key-packages/key-package-ref.d.ts +16 -0
  145. package/dist/key-packages/key-package-ref.js +21 -0
  146. package/dist/key-packages/observation-stream.d.ts +4 -0
  147. package/dist/key-packages/observation-stream.js +120 -0
  148. package/dist/key-packages/offer-rumor.d.ts +26 -0
  149. package/dist/key-packages/offer-rumor.js +69 -0
  150. package/dist/key-packages/publisher.d.ts +174 -0
  151. package/dist/key-packages/publisher.js +1247 -0
  152. package/dist/key-packages/select-key-package.d.ts +24 -0
  153. package/dist/key-packages/select-key-package.js +90 -0
  154. package/dist/key-packages/slot-manager.d.ts +167 -0
  155. package/dist/key-packages/slot-manager.js +327 -0
  156. package/dist/key-packages/validate-key-package-event.d.ts +3 -0
  157. package/dist/key-packages/validate-key-package-event.js +49 -0
  158. package/dist/media/cache.d.ts +14 -0
  159. package/dist/media/cache.js +10 -0
  160. package/dist/media/index.d.ts +52 -0
  161. package/dist/media/index.js +71 -0
  162. package/dist/mls.d.ts +15 -0
  163. package/dist/mls.js +15 -0
  164. package/dist/shared/account-pubkey.d.ts +4 -0
  165. package/dist/shared/account-pubkey.js +10 -0
  166. package/dist/shared/errors.d.ts +21 -0
  167. package/dist/shared/errors.js +85 -0
  168. package/dist/shared/hex.d.ts +4 -0
  169. package/dist/shared/hex.js +13 -0
  170. package/dist/shared/index.d.ts +14 -0
  171. package/dist/shared/index.js +14 -0
  172. package/dist/shared/kinds.d.ts +8 -0
  173. package/dist/shared/kinds.js +28 -0
  174. package/dist/shared/publish-classification.d.ts +26 -0
  175. package/dist/shared/publish-classification.js +31 -0
  176. package/dist/storage/envelope.d.ts +39 -0
  177. package/dist/storage/envelope.js +201 -0
  178. package/dist/storage/index.d.ts +227 -0
  179. package/dist/storage/index.js +459 -0
  180. package/dist/storage/indexeddb/idb-types.d.ts +68 -0
  181. package/dist/storage/indexeddb/idb-types.js +1 -0
  182. package/dist/storage/indexeddb/index.d.ts +17 -0
  183. package/dist/storage/indexeddb/index.js +141 -0
  184. package/dist/storage/lease.d.ts +41 -0
  185. package/dist/storage/lease.js +117 -0
  186. package/dist/storage/memory/deterministic-signer.d.ts +27 -0
  187. package/dist/storage/memory/deterministic-signer.js +65 -0
  188. package/dist/storage/memory/index.d.ts +32 -0
  189. package/dist/storage/memory/index.js +87 -0
  190. package/dist/storage/memory/lock-manager.d.ts +8 -0
  191. package/dist/storage/memory/lock-manager.js +71 -0
  192. 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
+ }