@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,180 @@
1
+ /**
2
+ * Same-account authorisation (S8; ADR-003, ADR-002 engine seams) — what lets
3
+ * a second device of an account join a group without an admin, and what
4
+ * bounds it.
5
+ *
6
+ * 1. `clientConfig` ({@link sameAccountClientConfig}): ts-mls's default
7
+ * `compareKeyPackageToLeafNode` treats a KeyPackage whose CREDENTIAL
8
+ * equals an existing leaf's as "already a member", so a sibling
9
+ * device's Add (same Nostr account, same basic credential) is refused
10
+ * on both the send and the receive path. Marmot compares signature keys
11
+ * only (ADR-003 Decision 2); every engine this client builds, and every
12
+ * Welcome join, runs with it (a mismatch between members is a silent
13
+ * fork hazard, AC-VENDOR-6).
14
+ * 2. The same-account rules, applied on BOTH paths:
15
+ * - a leaf may commit Adds of KeyPackages whose credential names its
16
+ * own account, and Removes of other leaves of its own account, even
17
+ * when it is not an admin ({@link createSameAccountAuthorizeCommit}
18
+ * on the send path, {@link createSameAccountAdminPolicy} on the
19
+ * receive path); every other part of the commit is judged by the
20
+ * vendored admin rule unchanged;
21
+ * - no commit may carry more than {@link MAX_ADDS_PER_ACCOUNT_PER_COMMIT}
22
+ * Adds for one account, nor leave one account with more than
23
+ * {@link MAX_LEAVES_PER_ACCOUNT} leaves — whoever commits it (an admin
24
+ * adding a sixth leaf is refused just the same).
25
+ * 3. The compensating control ADR-003 names — proof-v2 validation of every
26
+ * leaf on the receive path — is S3's `identity-proof.ts` gate, consumed
27
+ * here (it wraps these callbacks, it is not re-implemented).
28
+ */
29
+ import { decideCommitAuthorization, defaultMarmotClientConfig, getCredentialPubkey } from '@941design/marmot-engine/core';
30
+ import { createAdminCommitPolicyCallback } from '@941design/marmot-engine/engine';
31
+ import { defaultProposalTypes, nodeTypes, } from '@941design/marmot-engine/mls';
32
+ import { projectCommitLeaves } from './identity-proof.js';
33
+ /** ADR-003: at most four same-account Adds in one commit. */
34
+ export const MAX_ADDS_PER_ACCOUNT_PER_COMMIT = 4;
35
+ /** ADR-003: at most five leaves per account in a group. */
36
+ export const MAX_LEAVES_PER_ACCOUNT = 5;
37
+ function bytesEqual(a, b) {
38
+ if (a.length !== b.length)
39
+ return false;
40
+ let diff = 0;
41
+ for (let i = 0; i < a.length; i++)
42
+ diff |= a[i] ^ b[i];
43
+ return diff === 0;
44
+ }
45
+ /**
46
+ * The ts-mls `ClientConfig` every `marmot` engine and Welcome join uses: the
47
+ * Marmot default with `compareKeyPackageToLeafNode` comparing signature keys
48
+ * only (a device — one signature key — still never holds two leaves of one
49
+ * group; a sibling device of the same account is a new member).
50
+ */
51
+ export const sameAccountClientConfig = Object.freeze({
52
+ ...defaultMarmotClientConfig,
53
+ keyPackageEqualityConfig: Object.freeze({
54
+ compareKeyPackages: (a, b) => bytesEqual(a.leafNode.signaturePublicKey, b.leafNode.signaturePublicKey),
55
+ compareKeyPackageToLeafNode: (a, b) => bytesEqual(a.leafNode.signaturePublicKey, b.signaturePublicKey),
56
+ }),
57
+ });
58
+ function leafAt(ratchetTree, leafIndex) {
59
+ const node = ratchetTree[2 * leafIndex];
60
+ return node?.nodeType === nodeTypes.leaf ? node.leaf : undefined;
61
+ }
62
+ function accountOf(leaf) {
63
+ if (leaf === undefined)
64
+ return undefined;
65
+ try {
66
+ return getCredentialPubkey(leaf.credential);
67
+ }
68
+ catch {
69
+ return undefined;
70
+ }
71
+ }
72
+ /**
73
+ * The per-commit and per-group limits over the commit's exact proposal union
74
+ * against `ratchetTree` (the parent epoch's tree): `undefined` when both
75
+ * hold. Adds are counted by the credential they name; leaves over the
76
+ * projected (post-commit) leaf set, for the accounts the commit adds to.
77
+ */
78
+ export function checkSameAccountLimits(ratchetTree, proposals) {
79
+ const adds = new Map();
80
+ for (const { proposal } of proposals) {
81
+ if (proposal.proposalType !== defaultProposalTypes.add || !('add' in proposal))
82
+ continue;
83
+ const account = accountOf(proposal.add.keyPackage.leafNode);
84
+ if (account === undefined)
85
+ continue; // not a Marmot identity: the proof gate rejects it
86
+ const count = (adds.get(account) ?? 0) + 1;
87
+ if (count > MAX_ADDS_PER_ACCOUNT_PER_COMMIT)
88
+ return { reason: 'too-many-adds', account, adds: count };
89
+ adds.set(account, count);
90
+ }
91
+ if (adds.size === 0)
92
+ return undefined;
93
+ const leaves = new Map();
94
+ for (const { leaf } of projectCommitLeaves(ratchetTree, proposals)) {
95
+ const account = accountOf(leaf);
96
+ // Only the accounts this commit adds to: it cannot be blamed for a count it does not change.
97
+ if (account === undefined || !adds.has(account))
98
+ continue;
99
+ const count = (leaves.get(account) ?? 0) + 1;
100
+ if (count > MAX_LEAVES_PER_ACCOUNT)
101
+ return { reason: 'too-many-leaves', account, leaves: count };
102
+ leaves.set(account, count);
103
+ }
104
+ return undefined;
105
+ }
106
+ /**
107
+ * Whether one proposal is a same-account change of `actorAccount`: an Add of
108
+ * a KeyPackage naming that account, or a Remove of ANOTHER leaf of it (a
109
+ * leaf never removes itself — that is SelfRemove, judged by the admin rule).
110
+ */
111
+ export function isSameAccountChange(ratchetTree, actorAccount, actorLeafIndex, entry) {
112
+ const { proposal } = entry;
113
+ if (proposal.proposalType === defaultProposalTypes.add && 'add' in proposal) {
114
+ return accountOf(proposal.add.keyPackage.leafNode) === actorAccount;
115
+ }
116
+ if (proposal.proposalType === defaultProposalTypes.remove && 'remove' in proposal) {
117
+ const removed = Number(proposal.remove.removed);
118
+ return removed !== actorLeafIndex && accountOf(leafAt(ratchetTree, removed)) === actorAccount;
119
+ }
120
+ return false;
121
+ }
122
+ /**
123
+ * The engine's `authorizeCommit` seam (send path) over the tree `ratchetTree()`
124
+ * returns (the engine's current state — the commit's parent): the limits
125
+ * first, then the vendored rule; a non-admin's union is authorised when what
126
+ * remains after taking out its same-account changes is something the
127
+ * vendored rule lets a non-admin commit (nothing, its own Update, or
128
+ * SelfRemoves). The typed decision carries only the vendored reason; the
129
+ * client checks the limits itself before it builds a commit, so a refusal
130
+ * here is a backstop.
131
+ */
132
+ export function createSameAccountAuthorizeCommit(ratchetTree) {
133
+ return (args) => {
134
+ const tree = ratchetTree();
135
+ if (checkSameAccountLimits(tree, args.proposals) !== undefined)
136
+ return { authorized: false, reason: 'non-admin-proposal-union' };
137
+ const vendored = decideCommitAuthorization(args);
138
+ if (vendored.authorized)
139
+ return vendored;
140
+ const rest = args.proposals.filter((p) => !isSameAccountChange(tree, args.actorPubkey, args.actorLeafIndex, p));
141
+ if (rest.length === args.proposals.length)
142
+ return vendored;
143
+ // Nothing else, or only what a non-admin may commit alone.
144
+ if (rest.length === 0)
145
+ return { authorized: true };
146
+ return decideCommitAuthorization({ ...args, proposals: rest });
147
+ };
148
+ }
149
+ /**
150
+ * The receive-path counterpart, as an `adminPolicyCallback` factory wrapping
151
+ * `inner` (default: the vendored `createAdminCommitPolicyCallback`): a commit
152
+ * breaking a limit is rejected, whoever sent it; a non-admin committer's
153
+ * same-account changes are taken out of the proposal list `inner` judges, so
154
+ * `inner` decides only the rest (an empty rest is accepted by it). Proposals
155
+ * (not commits) go to `inner` unchanged. Wrapped in turn by S3's
156
+ * `createProofEnforcingAdminPolicy`, which checks every projected leaf's
157
+ * proof first (AC-DEV-3).
158
+ */
159
+ export function createSameAccountAdminPolicy(inner = createAdminCommitPolicyCallback) {
160
+ return (args) => {
161
+ const innerCallback = inner(args);
162
+ return (incoming) => {
163
+ if (incoming.kind !== 'commit')
164
+ return innerCallback(incoming);
165
+ if (checkSameAccountLimits(args.ratchetTree, incoming.proposals) !== undefined)
166
+ return 'reject';
167
+ const sender = incoming.senderLeafIndex;
168
+ if (sender === undefined)
169
+ return innerCallback(incoming);
170
+ const senderIndex = Number(sender);
171
+ const actor = accountOf(leafAt(args.ratchetTree, senderIndex));
172
+ if (actor === undefined || args.adminPubkeys.includes(actor))
173
+ return innerCallback(incoming);
174
+ const rest = incoming.proposals.filter((p) => !isSameAccountChange(args.ratchetTree, actor, senderIndex, p));
175
+ if (rest.length === incoming.proposals.length)
176
+ return innerCallback(incoming);
177
+ return innerCallback({ ...incoming, proposals: rest });
178
+ };
179
+ };
180
+ }
@@ -0,0 +1,127 @@
1
+ import type { AccountStoreTx } from '../storage/index.js';
2
+ /** Account extension namespace of teardown intents. */
3
+ export declare const TEARDOWN_EXTENSION = "marmot.teardown";
4
+ /** Default `leaveTimeoutMs`: how long `leave()` waits for a peer's commit before purging anyway. */
5
+ export declare const DEFAULT_LEAVE_TIMEOUT_MS = 60000;
6
+ export type TeardownKind = 'leave' | 'abandon' | 'destroy';
7
+ /**
8
+ * How a teardown ended its `leaving` phase: `removed` (the leaf left the tree),
9
+ * `sole-member` (nothing to send), `timed-out` (the deadline passed first),
10
+ * `last-admin` (the leaf could not leave: its account is the last active
11
+ * admin), `abandoned` (an `abandon()`/`destroy()` took it over); absent for
12
+ * a plain `abandon()`/`destroy()`.
13
+ */
14
+ export type TeardownOutcome = 'removed' | 'sole-member' | 'timed-out' | 'last-admin' | 'abandoned';
15
+ /** What the `leaving` phase reads from the group, on its queue. */
16
+ export interface LeaveView {
17
+ /** False once the local leaf was removed. */
18
+ readonly member: boolean;
19
+ /** The local leaf is the group's only occupied leaf. */
20
+ readonly soleMember: boolean;
21
+ /** The local account is a listed admin. */
22
+ readonly admin: boolean;
23
+ /** The local account holds another leaf of the group. */
24
+ readonly accountHasOtherLeaf: boolean;
25
+ /** AC-ADMIN-2 for the local account. */
26
+ readonly lastActiveAdmin: boolean;
27
+ /** The local leaf's own SelfRemove proposal is staged at the current epoch. */
28
+ readonly selfRemoveStaged: boolean;
29
+ /** An own commit-kind intent (proposal, commit, self-update) is still recorded: its fate decides first. */
30
+ readonly ownIntentPending: boolean;
31
+ /**
32
+ * S20: present while `member` is false and the removal is still revisable — the client-clock time it settles.
33
+ * Until then a same-epoch sibling may still rewind the leaf back into the group (BACKLOG
34
+ * same-epoch-fork-removal-divergence), so the leave waits for it before concluding `removed`.
35
+ */
36
+ readonly removalSettlesAt?: number;
37
+ }
38
+ /** The group operations teardown needs; `client` implements them (account never imports client). */
39
+ export interface TeardownGroupPort {
40
+ /** The group's current state as the leave sees it, loading the group; `undefined` when it is not held. */
41
+ view(groupId: string): Promise<LeaveView | undefined>;
42
+ /** The local leaf's SelfRemove proposal through the pipeline (rejects like `send`). */
43
+ proposeSelfRemove(groupId: string): Promise<void>;
44
+ /** One commit dropping the local account from the admin list (rejects like `send`). */
45
+ demote(groupId: string): Promise<void>;
46
+ /**
47
+ * Retires the group runtime and deletes everything of the group's `GroupStore`; idempotent, publishes nothing.
48
+ * Inside the ONE serialized group operation that clears the store — after every operation queued before it —
49
+ * it first reads the epoch of the stored state and awaits `beforeClear(epoch)` (the watermark), then clears
50
+ * (F2). `beforeClear` is not called when no state is stored any more.
51
+ */
52
+ purge(groupId: string, beforeClear: (epoch: bigint) => Promise<void>): Promise<void>;
53
+ /** Calls `listener` whenever the group's exposed state changes; returns the unsubscribe. */
54
+ watch(groupId: string, listener: () => void): () => void;
55
+ }
56
+ export interface TeardownDeps {
57
+ readonly clock: {
58
+ now(): number;
59
+ };
60
+ readonly timers: {
61
+ set(callback: () => void, ms: number): unknown;
62
+ clear(handle: unknown): void;
63
+ };
64
+ readonly leaveTimeoutMs: number;
65
+ /** AC-KP-3's grace window: how long a consumed KeyPackage's key serves other invitations' Welcomes. */
66
+ readonly graceWindowMs: number;
67
+ /** `AccountStore.transaction`, routed through the re-entrancy guard. */
68
+ transaction<T>(fn: (tx: AccountStoreTx) => Promise<T> | T): Promise<T>;
69
+ readonly groups: TeardownGroupPort;
70
+ /** The account extension holding the group index (`client`'s `marmot.groups`). */
71
+ readonly groupIndexExtension: string;
72
+ /** S4 `keyPackages.forget(ref)` (a durable kind-5 on the slot) and where a ref stands. */
73
+ forgetKeyPackage(ref: string): Promise<void>;
74
+ keyPackageStatus(ref: string): Promise<'absent' | 'deleting' | 'present'>;
75
+ /** S4's resume of pending KeyPackage intents (re-publishes a pending kind-5). */
76
+ resumeKeyPackageIntents(): Promise<void>;
77
+ /** A group's teardown settled (its `leaving` phase ended): the device service's own-leaf forget may continue. */
78
+ onSettled(groupId: string): void;
79
+ onMaintenanceFailed(failure: {
80
+ readonly invitationId: string;
81
+ readonly kind: 'teardown' | 'keypackage-deletion';
82
+ readonly reason: string;
83
+ }): void;
84
+ /** Runs `fn` outside every re-entrancy frame (a background driver must not inherit its starter's). */
85
+ detached<T>(fn: () => T): T;
86
+ isDisposed(): boolean;
87
+ }
88
+ export interface TeardownService {
89
+ /** AC-ADMIN-6; refused `last-admin` (nothing written) when the local leaf is the last leaf of the last active admin. */
90
+ leave(groupId: string): Promise<void>;
91
+ /** AC-ADMIN-3: `last-admin`, then `use-forget`, checked before anything is written; `invalid-options` for a non-admin. */
92
+ depart(groupId: string): Promise<void>;
93
+ /** AC-ADMIN-5. */
94
+ abandon(groupId: string): Promise<void>;
95
+ /** AC-ADMIN-7. */
96
+ destroy(groupId: string): Promise<void>;
97
+ /** AC-ADMIN-10's per-group `leave()` (no precondition refuses it); resolves with the request id once it is recorded. */
98
+ startLeave(groupId: string): Promise<string>;
99
+ /**
100
+ * Whether a Welcome bringing `groupId` back at `epoch` must be refused: this client purged the group and the
101
+ * Welcome's state is not newer than the one it deleted (an interrupted or redelivered join of the old group).
102
+ * A later re-invitation (a higher epoch) is not refused.
103
+ */
104
+ refusesJoin(groupId: string, epoch: bigint): Promise<boolean>;
105
+ /** Completes the group's interrupted purge, if one is recorded, before a Welcome may bring the group back. */
106
+ finishPurge(groupId: string): Promise<void>;
107
+ /**
108
+ * Whether this device is itself tearing the group down: an intent (`leave()`, an own-leaf `devices.forget`,
109
+ * `abandon()`, `destroy()`) is recorded for it in its leaving or purging phase, given up or not. Such a removal of the local leaf is not announced as `groupRemoved`.
110
+ */
111
+ tearingDown(groupId: string): Promise<boolean>;
112
+ /** A started leave's outcome as `devices.forget` reports it. */
113
+ leaveOutcome(requestId: string): Promise<'pending' | 'removed' | 'timed-out'>;
114
+ /** Drives every unfinished intent in the background (never awaited by the caller). */
115
+ resumeInBackground(): void;
116
+ dispose(): void;
117
+ }
118
+ /**
119
+ * Account extension of per-group purge watermarks: `groupId` → `{ epoch, at }`, the highest epoch this client
120
+ * purged of the group. Kept apart from the teardown records (pruned after 7 days) so a delayed Welcome of the old
121
+ * group is refused for as long as one could still be joined: a Welcome needs its KeyPackage's private key, and a
122
+ * KeyPackage lives at most `MAX_KEY_PACKAGE_LIFETIME` (engine: 7 261 200 s ≈ 84 days) — so a watermark is pruned
123
+ * after {@link WATERMARK_RETENTION_MS} (90 days, with margin); a later purge of the group replaces it.
124
+ */
125
+ export declare const PURGE_WATERMARK_EXTENSION = "marmot.purged";
126
+ export declare const WATERMARK_RETENTION_MS: number;
127
+ export declare function createTeardownService(deps: TeardownDeps): TeardownService;