@941design/marmot 0.0.0-stage → 0.2.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (206) hide show
  1. package/CHANGELOG.md +739 -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 +190 -0
  25. package/dist/account/teardown.js +878 -0
  26. package/dist/client/admission-cleanup.d.ts +197 -0
  27. package/dist/client/admission-cleanup.js +635 -0
  28. package/dist/client/adoption-proof.d.ts +39 -0
  29. package/dist/client/adoption-proof.js +102 -0
  30. package/dist/client/before-create-group.d.ts +18 -0
  31. package/dist/client/before-create-group.js +65 -0
  32. package/dist/client/before-publish-hooks.d.ts +121 -0
  33. package/dist/client/before-publish-hooks.js +182 -0
  34. package/dist/client/client-config.d.ts +42 -0
  35. package/dist/client/client-config.js +13 -0
  36. package/dist/client/commit-redrive.d.ts +92 -0
  37. package/dist/client/commit-redrive.js +274 -0
  38. package/dist/client/component-update.d.ts +43 -0
  39. package/dist/client/component-update.js +53 -0
  40. package/dist/client/confirm-hooks.d.ts +55 -0
  41. package/dist/client/confirm-hooks.js +74 -0
  42. package/dist/client/create-client.d.ts +1126 -0
  43. package/dist/client/create-client.js +1232 -0
  44. package/dist/client/group-availability.d.ts +182 -0
  45. package/dist/client/group-availability.js +301 -0
  46. package/dist/client/group-disband.d.ts +28 -0
  47. package/dist/client/group-disband.js +64 -0
  48. package/dist/client/group-history.d.ts +461 -0
  49. package/dist/client/group-history.js +1365 -0
  50. package/dist/client/group-profile.d.ts +31 -0
  51. package/dist/client/group-profile.js +62 -0
  52. package/dist/client/group-records.d.ts +522 -0
  53. package/dist/client/group-records.js +1117 -0
  54. package/dist/client/group-removal.d.ts +36 -0
  55. package/dist/client/group-removal.js +127 -0
  56. package/dist/client/group-remove-member.d.ts +49 -0
  57. package/dist/client/group-remove-member.js +163 -0
  58. package/dist/client/group-runtime.d.ts +415 -0
  59. package/dist/client/group-runtime.js +2811 -0
  60. package/dist/client/group-snapshot.d.ts +104 -0
  61. package/dist/client/group-snapshot.js +474 -0
  62. package/dist/client/history-pages.d.ts +107 -0
  63. package/dist/client/history-pages.js +194 -0
  64. package/dist/client/inbox-send.d.ts +19 -0
  65. package/dist/client/inbox-send.js +71 -0
  66. package/dist/client/index.d.ts +24 -0
  67. package/dist/client/index.js +13 -0
  68. package/dist/client/ingest.d.ts +82 -0
  69. package/dist/client/ingest.js +1584 -0
  70. package/dist/client/invitation-outcomes.d.ts +50 -0
  71. package/dist/client/invitation-outcomes.js +135 -0
  72. package/dist/client/lifecycle-events.d.ts +63 -0
  73. package/dist/client/lifecycle-events.js +35 -0
  74. package/dist/client/opaque-candidates.d.ts +82 -0
  75. package/dist/client/opaque-candidates.js +170 -0
  76. package/dist/client/own-change-outbox.d.ts +66 -0
  77. package/dist/client/own-change-outbox.js +158 -0
  78. package/dist/client/pending-leaf.d.ts +116 -0
  79. package/dist/client/pending-leaf.js +378 -0
  80. package/dist/client/permissions.d.ts +9 -0
  81. package/dist/client/permissions.js +12 -0
  82. package/dist/client/pipeline.d.ts +583 -0
  83. package/dist/client/pipeline.js +3666 -0
  84. package/dist/client/reentrancy-guard.d.ts +102 -0
  85. package/dist/client/reentrancy-guard.js +159 -0
  86. package/dist/client/rekey.d.ts +58 -0
  87. package/dist/client/rekey.js +149 -0
  88. package/dist/client/transport-policy.d.ts +181 -0
  89. package/dist/client/transport-policy.js +214 -0
  90. package/dist/history/admission-lineage.d.ts +186 -0
  91. package/dist/history/admission-lineage.js +589 -0
  92. package/dist/history/equivocation.d.ts +55 -0
  93. package/dist/history/equivocation.js +113 -0
  94. package/dist/history/fencing.d.ts +66 -0
  95. package/dist/history/fencing.js +121 -0
  96. package/dist/history/hex.d.ts +3 -0
  97. package/dist/history/hex.js +10 -0
  98. package/dist/history/index.d.ts +74 -0
  99. package/dist/history/index.js +32 -0
  100. package/dist/history/notifications.d.ts +270 -0
  101. package/dist/history/notifications.js +264 -0
  102. package/dist/history/ordering-key.d.ts +24 -0
  103. package/dist/history/ordering-key.js +101 -0
  104. package/dist/history/own-change-fork.d.ts +112 -0
  105. package/dist/history/own-change-fork.js +196 -0
  106. package/dist/history/own-change.d.ts +118 -0
  107. package/dist/history/own-change.js +146 -0
  108. package/dist/history/policy.d.ts +48 -0
  109. package/dist/history/policy.js +52 -0
  110. package/dist/history/retained-window.d.ts +215 -0
  111. package/dist/history/retained-window.js +565 -0
  112. package/dist/inbox/demux.d.ts +90 -0
  113. package/dist/inbox/demux.js +78 -0
  114. package/dist/inbox/handler-registry.d.ts +42 -0
  115. package/dist/inbox/handler-registry.js +37 -0
  116. package/dist/inbox/index.d.ts +11 -0
  117. package/dist/inbox/index.js +10 -0
  118. package/dist/inbox/seen-set.d.ts +82 -0
  119. package/dist/inbox/seen-set.js +202 -0
  120. package/dist/inbox/subscription.d.ts +236 -0
  121. package/dist/inbox/subscription.js +644 -0
  122. package/dist/index.d.ts +10 -0
  123. package/dist/index.js +9 -0
  124. package/dist/invitations/competing-welcome.d.ts +223 -0
  125. package/dist/invitations/competing-welcome.js +128 -0
  126. package/dist/invitations/decline.d.ts +67 -0
  127. package/dist/invitations/decline.js +149 -0
  128. package/dist/invitations/delivery-evidence.d.ts +288 -0
  129. package/dist/invitations/delivery-evidence.js +766 -0
  130. package/dist/invitations/expect-welcome.d.ts +66 -0
  131. package/dist/invitations/expect-welcome.js +138 -0
  132. package/dist/invitations/index.d.ts +18 -0
  133. package/dist/invitations/index.js +18 -0
  134. package/dist/invitations/invitation-outcome.d.ts +110 -0
  135. package/dist/invitations/invitation-outcome.js +210 -0
  136. package/dist/invitations/invite.d.ts +358 -0
  137. package/dist/invitations/invite.js +1102 -0
  138. package/dist/invitations/offers.d.ts +79 -0
  139. package/dist/invitations/offers.js +115 -0
  140. package/dist/invitations/on-proposal.d.ts +47 -0
  141. package/dist/invitations/on-proposal.js +40 -0
  142. package/dist/invitations/pending-proposal-policy.d.ts +52 -0
  143. package/dist/invitations/pending-proposal-policy.js +139 -0
  144. package/dist/invitations/proposal-deadline.d.ts +133 -0
  145. package/dist/invitations/proposal-deadline.js +164 -0
  146. package/dist/invitations/relay-planes.d.ts +43 -0
  147. package/dist/invitations/relay-planes.js +70 -0
  148. package/dist/invitations/welcome-processor.d.ts +272 -0
  149. package/dist/invitations/welcome-processor.js +1241 -0
  150. package/dist/key-packages/device-key.d.ts +131 -0
  151. package/dist/key-packages/device-key.js +272 -0
  152. package/dist/key-packages/device-rotation-records.d.ts +83 -0
  153. package/dist/key-packages/device-rotation-records.js +173 -0
  154. package/dist/key-packages/group-refs.d.ts +40 -0
  155. package/dist/key-packages/group-refs.js +79 -0
  156. package/dist/key-packages/index.d.ts +18 -0
  157. package/dist/key-packages/index.js +18 -0
  158. package/dist/key-packages/key-package-ref.d.ts +16 -0
  159. package/dist/key-packages/key-package-ref.js +21 -0
  160. package/dist/key-packages/observation-stream.d.ts +4 -0
  161. package/dist/key-packages/observation-stream.js +120 -0
  162. package/dist/key-packages/offer-rumor.d.ts +26 -0
  163. package/dist/key-packages/offer-rumor.js +69 -0
  164. package/dist/key-packages/publisher.d.ts +174 -0
  165. package/dist/key-packages/publisher.js +1247 -0
  166. package/dist/key-packages/select-key-package.d.ts +24 -0
  167. package/dist/key-packages/select-key-package.js +90 -0
  168. package/dist/key-packages/slot-manager.d.ts +167 -0
  169. package/dist/key-packages/slot-manager.js +327 -0
  170. package/dist/key-packages/validate-key-package-event.d.ts +3 -0
  171. package/dist/key-packages/validate-key-package-event.js +49 -0
  172. package/dist/media/cache.d.ts +14 -0
  173. package/dist/media/cache.js +10 -0
  174. package/dist/media/index.d.ts +52 -0
  175. package/dist/media/index.js +71 -0
  176. package/dist/mls.d.ts +15 -0
  177. package/dist/mls.js +15 -0
  178. package/dist/shared/account-pubkey.d.ts +4 -0
  179. package/dist/shared/account-pubkey.js +10 -0
  180. package/dist/shared/errors.d.ts +28 -0
  181. package/dist/shared/errors.js +96 -0
  182. package/dist/shared/hex.d.ts +4 -0
  183. package/dist/shared/hex.js +13 -0
  184. package/dist/shared/index.d.ts +14 -0
  185. package/dist/shared/index.js +14 -0
  186. package/dist/shared/kinds.d.ts +8 -0
  187. package/dist/shared/kinds.js +28 -0
  188. package/dist/shared/publish-classification.d.ts +26 -0
  189. package/dist/shared/publish-classification.js +31 -0
  190. package/dist/storage/envelope.d.ts +39 -0
  191. package/dist/storage/envelope.js +201 -0
  192. package/dist/storage/index.d.ts +237 -0
  193. package/dist/storage/index.js +491 -0
  194. package/dist/storage/indexeddb/idb-types.d.ts +68 -0
  195. package/dist/storage/indexeddb/idb-types.js +1 -0
  196. package/dist/storage/indexeddb/index.d.ts +17 -0
  197. package/dist/storage/indexeddb/index.js +141 -0
  198. package/dist/storage/lease.d.ts +54 -0
  199. package/dist/storage/lease.js +168 -0
  200. package/dist/storage/memory/deterministic-signer.d.ts +27 -0
  201. package/dist/storage/memory/deterministic-signer.js +65 -0
  202. package/dist/storage/memory/index.d.ts +32 -0
  203. package/dist/storage/memory/index.js +87 -0
  204. package/dist/storage/memory/lock-manager.d.ts +8 -0
  205. package/dist/storage/memory/lock-manager.js +71 -0
  206. package/package.json +66 -3
@@ -0,0 +1,358 @@
1
+ /**
2
+ * Inviter side of the invitation flow (AC-INVITE-1, AC-INVITE-2, AC-INVITE-5,
3
+ * AC-INVITE-6): invitee validation, the Add proposals and Welcome rumors of
4
+ * one invite commit, and the durable per-invitee Welcome delivery.
5
+ *
6
+ * The commit itself is an ordinary durable intent of the client pipeline
7
+ * (`client/pipeline.ts`): its record carries the invitees' KeyPackage events
8
+ * from the start and, from staging on, the Welcome rumors built from the
9
+ * engine's MLS Welcome — atomically with the commit envelope. Once a relay
10
+ * accepted the commit, the pipeline hands the rumors to this module
11
+ * ({@link InvitationsService.recordCommitted}): one `invites` record per
12
+ * commit, one delivery per invitee, each intent -> publish -> confirm:
13
+ *
14
+ * 1. resolve the invitee's inbox relays (`relay-planes.ts`); a transient
15
+ * lookup leaves the delivery `retryable` with nothing published;
16
+ * 2. gift-wrap the stored rumor (the seal is signed by the account key,
17
+ * outside any transaction) and store the wrap before publishing it;
18
+ * 3. publish; the classified outcome is written back after re-reading the
19
+ * record and checking the wrap is still the one published.
20
+ *
21
+ * Automatic retries re-publish the stored wrap byte-identically; only
22
+ * `retry()` (`group.retryWelcome`) re-wraps the same rumor — the invitee
23
+ * recognises the second copy of one Welcome (AC-WEL-2). Nothing here ever
24
+ * builds a commit. Deliveries run on the service's own serial queue, outside
25
+ * the group's operation queue: a remote signer waiting on its user must not
26
+ * stall the group.
27
+ */
28
+ import type { NostrEvent, Rumor } from '@941design/nostr-events/event';
29
+ import type { Signer } from '@941design/nostr-events/signer';
30
+ import type { Filter } from '@941design/nostr-events/event';
31
+ import type { RequestWithDeadlineResult } from '@941design/nostr-events/transport/contract';
32
+ import { type ClientState, type Proposal, type Welcome } from '@941design/marmot-engine/mls';
33
+ import { MarmotError } from '../shared/index.js';
34
+ import type { AccountStoreTx, Storable } from '../storage/index.js';
35
+ import { type AddAnchor, type DeclineCandidate, type DeclineCandidatePage, type DeliveryEvidence } from './delivery-evidence.js';
36
+ import { type InboxRelayDeps } from './relay-planes.js';
37
+ export interface Invitee {
38
+ /** The invitee's KeyPackageRef (hex) — `retryWelcome`'s `inviteeRef`. */
39
+ readonly inviteeRef: string;
40
+ readonly pubkey: string;
41
+ readonly keyPackageEventId: string;
42
+ readonly event: NostrEvent;
43
+ }
44
+ /**
45
+ * Validates the KeyPackage events of one `invite()` call, in order: the
46
+ * consumer verifier, then S4's selection rule (`selectKeyPackage` — kind,
47
+ * signature, credential/author binding, lifetime on the client clock, proof,
48
+ * baseline capabilities), then the group's own requirements (cipher suite,
49
+ * required capabilities). Any failure rejects the whole call with
50
+ * `invalid-options` before anything is recorded.
51
+ */
52
+ export declare function validateInvitees(keyPackages: unknown, opts: {
53
+ readonly verify: ((event: NostrEvent) => Promise<boolean>) | undefined;
54
+ readonly nowSeconds: number;
55
+ readonly state: ClientState;
56
+ }): Promise<Invitee[]>;
57
+ /** One Add proposal per invitee, in order. */
58
+ export declare function addProposalsFor(events: readonly NostrEvent[]): Proposal[];
59
+ /** Who a Welcome goes to. `keyPackageEventId` is absent when the KeyPackage event is not known (a staged Add whose event no relay has). */
60
+ export interface WelcomeRecipient {
61
+ readonly inviteeRef: string;
62
+ readonly pubkey: string;
63
+ readonly keyPackageEventId?: string;
64
+ }
65
+ /** Deadline of the one batched KeyPackage-event lookup for a commit's staged Adds: short, since a miss only drops the optional `e` tag. */
66
+ export declare const STAGED_ADD_LOOKUP_TIMEOUT_MS = 2000;
67
+ /** The leaf signature keys (hex) of the Adds staged in `state`: an own commit over them carries those Adds by reference. */
68
+ export declare function stagedAddLeafKeys(state: ClientState): Set<string>;
69
+ /** Whether `state` stages any Add proposal (an own commit over it admits a member). */
70
+ export declare function hasStagedAdds(state: ClientState): boolean;
71
+ /**
72
+ * The Welcome recipients of the Adds staged in `state`: account (the leaf
73
+ * credential's identity) and KeyPackageRef, plus the id of the kind-30443
74
+ * event that carried the KeyPackage — a staged proposal carries only the
75
+ * KeyPackage itself. ONE batched lookup on `relays` for every staged Add's
76
+ * account (one deadline), each result verified (the single KeyPackage-event
77
+ * validator, then `verify`) and matched to its Add by KeyPackageRef. When no
78
+ * relay has it (a rotated slot, a timeout, a failed lookup) the recipient has
79
+ * no event id and its Welcome carries no `e` tag: `e` names an event, and a
80
+ * made-up id would send other clients after a reference that does not exist;
81
+ * the invitee matches a Welcome by the KeyPackageRef in its secrets.
82
+ */
83
+ export declare function stagedAddRecipients(state: ClientState, opts: {
84
+ readonly relays: readonly string[];
85
+ readonly lookupTimeoutMs: number;
86
+ readonly request: (relays: string[], filter: Filter, opts: {
87
+ timeoutMs: number;
88
+ }) => Promise<RequestWithDeadlineResult>;
89
+ readonly verify: ((event: NostrEvent) => Promise<boolean>) | undefined;
90
+ }): Promise<WelcomeRecipient[]>;
91
+ /** The recipients among `candidates` the MLS Welcome actually holds a secret for (by KeyPackageRef), de-duplicated. */
92
+ export declare function recipientsOfWelcome(welcome: Welcome, candidates: readonly WelcomeRecipient[]): WelcomeRecipient[];
93
+ export interface StoredWelcome {
94
+ readonly inviteeRef: string;
95
+ readonly pubkey: string;
96
+ /** Absent when the KeyPackage event is unknown: the rumor then carries no `e` tag. */
97
+ readonly keyPackageEventId?: string;
98
+ /** The kind-`RUMOR_KINDS.WELCOME` rumor, authored by the inviter's account. */
99
+ readonly rumor: Rumor;
100
+ }
101
+ /** Name of the Welcome rumor tag carrying the digest of the commit the Welcome belongs to (epic marmot-welcome-race-joiner). */
102
+ export declare const WELCOME_COMMIT_TAG = "commit";
103
+ /**
104
+ * One Welcome rumor per invitee over the commit's single MLS Welcome (it holds
105
+ * a secret for every new member), each tagged with the group's relays after the
106
+ * commit, — when known — that invitee's KeyPackage event id (`e`), and the
107
+ * `['commit', <digest hex>]` tag: the lowercase hex `commitDigest` of the
108
+ * published commit's MLS bytes (`commit`, the bytes the pipeline publishes and
109
+ * `confirmRecord` digests). A joiner holding another Welcome for the same group
110
+ * needs that digest to rank the two branches the way the members do; the rumor
111
+ * id is recomputed over the tagged draft. The tag is appended last, so every
112
+ * other tag keeps its place and value.
113
+ */
114
+ export declare function buildWelcomeRumors(opts: {
115
+ readonly welcome: Welcome;
116
+ /** The encoded MLS message of the published commit (`encode(mlsMessageEncoder, commitMessage)`). */
117
+ readonly commit: Uint8Array;
118
+ readonly author: string;
119
+ readonly groupRelays: readonly string[];
120
+ readonly invitees: readonly WelcomeRecipient[];
121
+ }): StoredWelcome[];
122
+ /**
123
+ * The commit digest a Welcome rumor carries (`['commit', <64 lowercase hex>]`), or `undefined` when the rumor
124
+ * has no such tag, has more than one tag named `commit` (whatever their values), or its value is not 64
125
+ * lowercase hex. Total: never throws, for any tag order, extra tags and malformed input — an untagged
126
+ * (pre-epic or foreign) Welcome is an ordinary input, not an error. Entries after the value are ignored.
127
+ */
128
+ export declare function welcomeCommitTagOf(rumor: Rumor): string | undefined;
129
+ /** `Storable` codec of a staged commit record's Welcome list (the pipeline stores it; this module owns its shape). */
130
+ export declare function encodeStoredWelcomes(welcomes: readonly StoredWelcome[]): Storable;
131
+ export declare function decodeStoredWelcomes(where: string, raw: unknown): StoredWelcome[];
132
+ /**
133
+ * `declined` (AC-HYG-3): the invitee declined the Welcome — terminal: never
134
+ * re-published, automatically or by `retryWelcome`.
135
+ */
136
+ export type WelcomeDeliveryStatus = 'pending' | 'retryable' | 'delivered' | 'failed' | 'declined';
137
+ /** `InviteeDelivery.reason` of a `delivered` delivery whose invite commit a rewind abandoned: the invitee may hold a membership of a branch the group left. */
138
+ export declare const DELIVERED_ON_ABANDONED_BRANCH = "delivered-on-abandoned-branch";
139
+ export interface InviteeDelivery extends StoredWelcome {
140
+ /** The gift wrap last stored for publishing (kept once it may be live). */
141
+ readonly wrap?: NostrEvent;
142
+ /** Relays of the last publish attempt. */
143
+ readonly relays?: readonly string[];
144
+ readonly status: WelcomeDeliveryStatus;
145
+ /** Failed publishes (they count toward `maxPublishAttempts`). */
146
+ readonly attempts: number;
147
+ /** Consecutive timed-out relay-list lookups (backoff only — never toward `maxPublishAttempts`). */
148
+ readonly lookupRetries?: number;
149
+ readonly reason?: string;
150
+ /**
151
+ * Client clock (ms) of the delivery's last move to `delivered` or `declined` (AC-HYG-2's retention runs from it;
152
+ * absent on records written before it existed, which count from `committedAt`).
153
+ */
154
+ readonly settledAt?: number;
155
+ }
156
+ export interface InviteRecord {
157
+ readonly v: 1;
158
+ readonly inviteId: string;
159
+ readonly groupId: string;
160
+ readonly commitEventId: string;
161
+ /**
162
+ * The confirmation tag of the state the invite commit produced (the commit's node in the group's retained window),
163
+ * so a rewind that abandons that node can find the record without an event-id-to-node map. Absent on records
164
+ * written before it existed (those are never withdrawn automatically).
165
+ */
166
+ readonly commitTag?: string;
167
+ /** Client clock (ms) of the handoff. */
168
+ readonly committedAt: number;
169
+ readonly invitees: readonly InviteeDelivery[];
170
+ }
171
+ /** Default `ClientOptions.inviteRetentionMs` (AC-HYG-2): 30 days. */
172
+ export declare const DEFAULT_INVITE_RETENTION_MS: number;
173
+ /** Decodes the record stored under `key` (`<groupId>/<inviteId>`); its header must name the same group and invite. */
174
+ export declare function decodeInviteRecord(key: string, raw: unknown): InviteRecord;
175
+ /**
176
+ * S9 teardown (`abandon()`/`destroy()`): deletes the `invites` records of
177
+ * `groupId` — its Welcome deliveries end with the group. Its records are
178
+ * found by key (AC-HYG-2), whether they decode or not; a record still keyed
179
+ * `<inviteId>` (written before AC-HYG-2, not migrated yet) is matched on its
180
+ * raw `groupId` field.
181
+ */
182
+ export declare function purgeGroupInvites(tx: AccountStoreTx, groupId: string): Promise<void>;
183
+ /**
184
+ * `invitations.declineCandidates` (epic marmot-invitation-outcomes S3, SC-13): one page of the account's decline
185
+ * candidates, read in the caller's (read-only) account transaction. Writes nothing.
186
+ */
187
+ export declare function declineCandidatePage(tx: AccountStoreTx, opts: {
188
+ readonly account: string;
189
+ readonly after?: string;
190
+ readonly limit: number;
191
+ }): Promise<DeclineCandidatePage>;
192
+ /**
193
+ * `invitations.cleanupDisposition` (epic marmot-invitation-outcomes S4, SC-3 I9, I9a): the delivery and candidate named
194
+ * by a cleanup reference, read in the caller's (read-only) account transaction — the candidate exactly as the scan
195
+ * returns it — plus the identity of the delivery's invite commit while its `invites` record is retained (what lazy
196
+ * legacy anchor resolution needs). `undefined` when the store holds no such delivery. Writes nothing.
197
+ */
198
+ export declare function cleanupCandidateOf(tx: AccountStoreTx, opts: {
199
+ readonly account: string;
200
+ readonly groupId: string;
201
+ readonly candidateId: string;
202
+ }): Promise<{
203
+ readonly delivery: DeliveryEvidence;
204
+ readonly candidate?: DeclineCandidate;
205
+ readonly invite?: {
206
+ readonly commitEventId: string;
207
+ readonly commitTag?: string;
208
+ };
209
+ } | undefined>;
210
+ /**
211
+ * Whether {@link cleanupCandidateOf} would name a candidate for that identity — the routing read of
212
+ * `invitations.cleanupDisposition`, which resolves no candidate set. Writes nothing.
213
+ */
214
+ export declare function cleanupCandidateExists(tx: AccountStoreTx, opts: {
215
+ readonly groupId: string;
216
+ readonly candidateId: string;
217
+ }): Promise<boolean>;
218
+ /** One invitee's Welcome delivery, as `invite()` / `retryWelcome()` report it (AC-INVITE-2). */
219
+ export interface WelcomeOutcome {
220
+ readonly inviteeRef: string;
221
+ readonly pubkey: string;
222
+ /** The KeyPackage event the Welcome names; absent for a staged Add whose event no relay had. */
223
+ readonly keyPackageEventId?: string;
224
+ /**
225
+ * `retryable` deliveries are re-attempted automatically; `failed` ones only by `retryWelcome`; `declined` ones
226
+ * (the invitee declined, AC-HYG-3) never again.
227
+ */
228
+ readonly status: 'delivered' | 'retryable' | 'failed' | 'declined';
229
+ /** Relays of the last publish attempt (empty when nothing was published). */
230
+ readonly relays: readonly string[];
231
+ /** Why it is not delivered (`nip17-timed-out`, `no-inbox-relays`, `publish-failed`, `publish-refused`, …). */
232
+ readonly reason?: string;
233
+ /** `no-inbox-relays`, `publish-failed` (retryable) or `send-rejected` (failed). */
234
+ readonly error?: MarmotError;
235
+ }
236
+ export declare function toWelcomeOutcome(delivery: WelcomeRecipient & {
237
+ readonly status: WelcomeDeliveryStatus;
238
+ readonly reason?: string;
239
+ readonly relays?: readonly string[];
240
+ }, cause?: unknown): WelcomeOutcome;
241
+ export interface InvitationsDeps extends InboxRelayDeps {
242
+ readonly clock: {
243
+ now(): number;
244
+ };
245
+ readonly timers: {
246
+ set(callback: () => void, ms: number): unknown;
247
+ clear(handle: unknown): void;
248
+ };
249
+ /** Failed publishes after which a Welcome delivery goes `failed`. */
250
+ readonly maxPublishAttempts: number;
251
+ /** The account-key signer (seals the gift wrap), every member already routed through the re-entrancy guard. */
252
+ readonly signer: Signer;
253
+ /** `AccountStore.transaction`, already routed through the re-entrancy guard. */
254
+ transaction<T>(fn: (tx: AccountStoreTx) => Promise<T> | T): Promise<T>;
255
+ isDisposed(): boolean;
256
+ /** Called once a delivery went `failed` (after the write committed): the application may `retryWelcome` it. */
257
+ readonly onFailed?: (failure: {
258
+ readonly groupId: string;
259
+ readonly inviteeRef: string;
260
+ readonly reason: string;
261
+ }) => void;
262
+ /** AC-HYG-2: how long (client-clock ms) a record whose every delivery is delivered or declined is kept after it settled. */
263
+ readonly inviteRetentionMs: number;
264
+ /**
265
+ * AC-HYG-3: called once per delivery that went `declined` (after the write committed). The second argument
266
+ * carries the delivery's stable candidate identity (epic marmot-invitation-outcomes S3, `welcomeDeclined.candidateId`).
267
+ */
268
+ readonly onDeclined?: (declined: {
269
+ readonly groupId: string;
270
+ readonly inviteeRef: string;
271
+ }, identity: {
272
+ readonly candidateId: string;
273
+ }) => void;
274
+ /**
275
+ * Epic marmot-invitation-outcomes S3: called once per candidate whose decline evidence changed — a new candidate or
276
+ * a higher `rev` (after the write committed). A late match beyond retention, an ambiguity and a refinement are each
277
+ * reported here; `onDeclined` keeps its own timing.
278
+ */
279
+ readonly onCandidate?: (candidate: DeclineCandidate) => void;
280
+ /** The account pubkey the cleanup references name (`AccountStore.account`); read from the signer when absent. */
281
+ readonly account?: string;
282
+ /** Called once per delivery {@link InvitationsService.restoreCommit} put back to `pending` (after the write committed). */
283
+ readonly onRestored?: (restored: {
284
+ readonly groupId: string;
285
+ readonly inviteeRef: string;
286
+ }) => void;
287
+ }
288
+ export interface InvitationsService {
289
+ /** Hands a relay-accepted invite commit's Welcomes over for delivery; a record already present keeps its progress. */
290
+ recordCommitted(input: {
291
+ readonly inviteId: string;
292
+ readonly groupId: string;
293
+ readonly commitEventId: string;
294
+ /** The confirmation tag of the state the commit produced (see {@link InviteRecord.commitTag}). */
295
+ readonly commitTag?: string;
296
+ readonly welcomes: readonly StoredWelcome[];
297
+ /** Epic marmot-invitation-outcomes S3 (SC-1): the Add anchor of each delivery, by KeyPackageRef (absent: unanchored). */
298
+ readonly anchors?: ReadonlyMap<string, AddAnchor>;
299
+ }): Promise<void>;
300
+ /**
301
+ * The group's invite commits a rewind may have to withdraw or restore: `open` (a delivery still `pending` or
302
+ * `retryable`) and/or `withdrawn` (a delivery `failed` with reason `commit-withdrawn`), `delivered` (a delivery already published and not yet
303
+ * marked) and/or `deliveredAbandoned` (marked {@link DELIVERED_ON_ABANDONED_BRANCH}). `commitTag` is absent for a
304
+ * record written before it was stored.
305
+ */
306
+ trackedCommits(groupId: string): Promise<ReadonlyArray<{
307
+ readonly commitEventId: string;
308
+ readonly commitTag?: string;
309
+ readonly open: boolean;
310
+ readonly withdrawn: boolean;
311
+ readonly delivered: boolean;
312
+ readonly deliveredAbandoned: boolean;
313
+ }>>;
314
+ /**
315
+ * The invite commit `commitEventId` was withdrawn by a rewind (its branch lost a same-epoch race): every delivery of
316
+ * its record that is still `pending` or `retryable` goes `failed` with reason `commit-withdrawn`, its backoff timer
317
+ * is cleared, and `onFailed` fires for each. A delivery already `delivered`, `failed` or `declined` is untouched. A
318
+ * publish already in flight is not recallable: if its relay accepts it the delivery reads `delivered` (the invitee
319
+ * then decides the Welcome like any competing one); a refused or failed one leaves `failed`/`commit-withdrawn` as it
320
+ * was. A delivery already `delivered` stays `delivered` and is marked `reason: 'delivered-on-abandoned-branch'` (once; a restore of the commit
321
+ * clears the mark silently). The mark is silent unless the caller says `signalDelivered`: only the caller knows whether something follows the
322
+ * withdrawal that re-delivers (a re-drive's new Welcome, an approval's re-issue) -- `onFailed` then fires once with that reason for the invitees
323
+ * that may be stranded on the abandoned branch. Idempotent. If the commit returns to the canonical path later, {@link restoreCommit} puts the deliveries back;
324
+ * to send one on request in the meantime, `retryWelcome` (re-sends the stored Welcome; no new commit) is the remedy,
325
+ * not a re-invite.
326
+ */
327
+ withdrawCommit(groupId: string, commitEventId: string, opts?: {
328
+ readonly signalDelivered?: boolean;
329
+ }): Promise<void>;
330
+ /**
331
+ * The commit returned to the canonical path (equivocation credit, a longer branch): its deliveries that
332
+ * {@link withdrawCommit} failed (`failed`/`commit-withdrawn` only) go back to `pending` and are delivered in the
333
+ * background; `onRestored` fires for each. Idempotent; a delivery failed for another reason is untouched.
334
+ */
335
+ restoreCommit(groupId: string, commitEventId: string): Promise<void>;
336
+ /** One delivery pass over every undelivered invitee of the invite; the outcome of every invitee (empty when no record exists). */
337
+ deliver(groupId: string, inviteId: string): Promise<readonly WelcomeOutcome[]>;
338
+ deliverInBackground(groupId: string, inviteId: string): void;
339
+ /** Re-wraps and re-publishes `inviteeRef`'s Welcome of the group's latest invite naming it — never a new commit. */
340
+ retry(groupId: string, inviteeRef: string): Promise<WelcomeOutcome>;
341
+ /** Resumes, in the background, every unfinished delivery of the group's invites (after a reload); prunes its expired records first. */
342
+ resumeGroup(groupId: string): void;
343
+ /**
344
+ * AC-HYG-3: native bookkeeping of an inbound DECLINE rumor (additive — the inbox still delivers it to
345
+ * `onApplicationRumor`). `rumor.pubkey` is the seal author (NIP-59 unwrap binds the two). The candidate set is
346
+ * every delivery of the content's group whose invitee is that author and whose Welcome has the content's welcome id
347
+ * (`welcomeIdOf`: SHA-256 of the MLS Welcome bytes) — from the delivery evidence, so it outlives retention (epic
348
+ * marmot-invitation-outcomes S3, spec DD2/DD3). Without a selector every in-retention delivery of the set goes
349
+ * `declined` — terminal, no further publish; with a valid `keyPackageRef` selector only the selected one does;
350
+ * with an invalid one nothing happens. Row flips and the decline evidence are written in ONE transaction;
351
+ * `onDeclined` fires once for each delivery that changed and `onCandidate` once per candidate whose evidence
352
+ * changed. Any other author, an unknown welcome id or a malformed content changes nothing. A delivery already
353
+ * `declined` (a redelivered or repeated decline) is not reported again.
354
+ */
355
+ recordDecline(rumor: Rumor): Promise<void>;
356
+ dispose(): void;
357
+ }
358
+ export declare function createInvitationsService(deps: InvitationsDeps): InvitationsService;