@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,339 @@
1
+ /**
2
+ * Same-account enrolment (S8; ADR-003 Decision 3, AC-DEV-5, -6, -9, -11,
3
+ * -13): a new device of an account asks an online sibling to add it to
4
+ * groups, over the account's own inbox.
5
+ *
6
+ * Request (the new device, {@link requestEnrolment}): one fresh KeyPackage
7
+ * per requested group (S4 `keyPackages.create`, so the private halves live in
8
+ * the durable slot records the Welcome processor looks keys up in), one
9
+ * `expectWelcome` manifest per group — `(group, KeyPackageRef, sponsor = the
10
+ * account itself)`, deadline = the request's expiry — and then ONE
11
+ * `RUMOR_KINDS.ENROLMENT_REQUEST` rumor `{ sessionId, expiresAt, label,
12
+ * groups: [{ groupId, keyPackageEvent }] }`, gift-wrapped to the account and
13
+ * published to the account's inbox relays only (AC-DEV-13). The request id is
14
+ * that rumor's id. Manifests and the outbound record (with the wrap, once
15
+ * sealed) are durable before anything is published; an unpublished request
16
+ * is re-published by later inbox passes until it expires.
17
+ *
18
+ * Arrival (every sibling, {@link handleEnrolmentRumor} — the native handler
19
+ * S7's demux runs on the inbox queue): the author must be the account itself
20
+ * (seal-authenticated); the device's own requests are ignored; a request past
21
+ * its `expiresAt`, or whose id this client has recorded before (a replay under
22
+ * a fresh wrap, or after the seen-set evicted the first), produces no prompt;
23
+ * a session id may send several distinct requests, but beyond
24
+ * `promptRateLimit` prompted requests within a minute the rest are recorded as
25
+ * dropped — silently: no prompt, no event (AC-DEV-5). A request that passes is
26
+ * recorded `pending` together with the wrap's seen mark, and only then is its
27
+ * prompt emitted ({@link EnrolmentPrompt}, AC-DEV-9).
28
+ *
29
+ * Approval ({@link approveEnrolment}, the application's answer to a prompt):
30
+ * one durable approval record — every requested group's manifest
31
+ * `(group, KeyPackageRef, sponsor)` and a per-group outcome (AC-DEV-6) — is
32
+ * written before any commit; then, group by group, S5's durable invite of the
33
+ * requested KeyPackage (one Add per group, committed by this leaf even when it
34
+ * is not an admin — the same-account seams; its Welcome goes to the account's
35
+ * inbox relays). Each group's outcome is read back from the group itself —
36
+ * the device's leaf present → `enrolled`; an own commit still pending → wait;
37
+ * otherwise retried, and given up (`failed`) after {@link MAX_GROUP_ATTEMPTS}
38
+ * attempts — so a crash, a lost race or a commit that went terminal resolve
39
+ * the same way on the next pass. Once every group is terminal, the record
40
+ * turns `approved`, the device's label is bound to its leaf key in the
41
+ * registry, and — through `ctx.lifecycle.afterCommit`, after that transaction
42
+ * committed — `enrolmentApproved` fires (AC-INBOX-6). An approval notice
43
+ * rumor then tells the siblings, whose prompts for that request are closed.
44
+ *
45
+ * "Top up" (AC-DEV-11) is the same flow with the old device as the sibling:
46
+ * whichever sibling approves, the new leaf enters at the Welcome's epoch and
47
+ * holds no secret of an earlier one.
48
+ */
49
+ import { type NostrEvent, type Rumor } from '@941design/nostr-events/event';
50
+ import { type DispatchContext, type RumorDisposition } from '../inbox/index.js';
51
+ import type { AccountStoreTx } from '../storage/index.js';
52
+ import { type DeviceServiceDeps, type EnrolmentPrompt } from './device-deps.js';
53
+ /** Default `promptRateLimit`: prompted requests per session id per minute. */
54
+ export declare const DEFAULT_PROMPT_RATE_LIMIT = 3;
55
+ export declare const PROMPT_RATE_WINDOW_MS = 60000;
56
+ export declare const DEFAULT_ENROLMENT_EXPIRY_MINUTES = 10;
57
+ export declare const MAX_ENROLMENT_EXPIRY_MINUTES: number;
58
+ /** Most groups one request may name. */
59
+ export declare const MAX_ENROLMENT_GROUPS = 32;
60
+ /** Commit attempts per group before an approval gives that group up (`failed`). */
61
+ export declare const MAX_GROUP_ATTEMPTS = 3;
62
+ export interface EnrolmentRequestEntry {
63
+ readonly groupId: string;
64
+ readonly keyPackageEvent: NostrEvent;
65
+ }
66
+ export interface DecodedEnrolmentRequest {
67
+ readonly type: 'request';
68
+ readonly sessionId: string;
69
+ /** Unix seconds. */
70
+ readonly expiresAt: number;
71
+ readonly label: string;
72
+ readonly groups: readonly EnrolmentRequestEntry[];
73
+ /** The one leaf signature key (hex) every requested KeyPackage carries: the new device's key. */
74
+ readonly leafKey: string;
75
+ }
76
+ export interface DecodedEnrolmentApproval {
77
+ readonly type: 'approved';
78
+ readonly requestId: string;
79
+ readonly leafKey: string;
80
+ readonly groups: readonly string[];
81
+ }
82
+ /** Builds the enrolment-request rumor (unsigned, per NIP-59; its id is the request id). */
83
+ export declare function encodeEnrolmentRequestRumor(opts: {
84
+ readonly pubkey: string;
85
+ readonly createdAt: number;
86
+ readonly sessionId: string;
87
+ readonly expiresAt: number;
88
+ readonly label: string;
89
+ readonly groups: readonly EnrolmentRequestEntry[];
90
+ }): Rumor;
91
+ /** Builds the approval-notice rumor a sibling sends once it approved `requestId`. */
92
+ export declare function encodeEnrolmentApprovalRumor(opts: {
93
+ readonly pubkey: string;
94
+ readonly createdAt: number;
95
+ readonly requestId: string;
96
+ readonly leafKey: string;
97
+ readonly groups: readonly string[];
98
+ }): Rumor;
99
+ /**
100
+ * Parses an enrolment rumor. Never throws: anything malformed — a wrong kind,
101
+ * bad JSON or fields, a KeyPackage event that is not a valid kind-30443 event
102
+ * of the rumor's own author, two groups named twice, KeyPackages carrying
103
+ * different leaf keys — yields `undefined`.
104
+ */
105
+ export declare function decodeEnrolmentRumor(rumor: Rumor): DecodedEnrolmentRequest | DecodedEnrolmentApproval | undefined;
106
+ /**
107
+ * NIP-44 v2's plaintext limit (nostr-tools `nip44`: 1..65535 bytes, UTF-8).
108
+ * A NIP-59 gift wrap encrypts TWICE: the rumor JSON into the seal's content,
109
+ * then the seal event's JSON into the wrap's content. So the rumor must fit
110
+ * 65535 bytes itself AND the seal JSON it produces must:
111
+ *
112
+ * seal JSON = SEAL_JSON_OVERHEAD + base64(1 version + 32 nonce + 2 length
113
+ * + padded(rumor bytes) + 32 MAC)
114
+ *
115
+ * with NIP-44's padding (`calcPaddedLen`: 32 up to 32 bytes, else chunks of
116
+ * nextPow2/8, at least 32). That bounds the rumor JSON at 40 960 bytes (five
117
+ * 8 KiB chunks: 1 + 32 + 2 + 40 960 + 32 = 41 027 bytes → 54 704 base64 chars
118
+ * + overhead; six chunks, 49 152 bytes, would need 65 628 base64 chars).
119
+ */
120
+ export declare const NIP44_MAX_PLAINTEXT_BYTES = 65535;
121
+ /** Base64 characters of a NIP-44 v2 payload for a `plaintextBytes`-byte plaintext. */
122
+ export declare function nip44PayloadLength(plaintextBytes: number): number;
123
+ /** Whether a rumor whose JSON is `rumorBytes` bytes fits both NIP-44 layers of a gift wrap. */
124
+ export declare function fitsGiftWrap(rumorBytes: number): boolean;
125
+ /**
126
+ * Default relay event-size budget for a gift wrap this client publishes (`ClientOptions.maxGiftWrapBytes`):
127
+ * 64 KiB of event JSON, a common relay cap (and FakeRelay's frame bound). A request inside both NIP-44 bounds
128
+ * can still produce a ~74 KB wrap that such relays refuse — persisted and retried until it expires, never
129
+ * delivered — so it is refused up front instead.
130
+ */
131
+ export declare const DEFAULT_MAX_GIFT_WRAP_BYTES = 65536;
132
+ /**
133
+ * Upper bound on the event-JSON bytes of the gift wrap carrying a `rumorBytes`-byte rumor: the wrap's content
134
+ * is the NIP-44 payload of the seal's JSON (ASCII: base64 content, hex fields), itself carrying the rumor's payload.
135
+ */
136
+ export declare function giftWrapBytes(rumorBytes: number): number;
137
+ /**
138
+ * Per-group outcome of an approval: `pending` (not decided yet), `enrolled`
139
+ * (the device holds a leaf of the group), `not-a-member` (this client does not
140
+ * hold the group), `limit-reached` (the account already has
141
+ * `MAX_LEAVES_PER_ACCOUNT` leaves there), `failed` (every attempt failed).
142
+ */
143
+ export type EnrolmentGroupOutcome = 'pending' | 'enrolled' | 'not-a-member' | 'limit-reached' | 'failed';
144
+ /** An approval's per-group record: its manifest `(group, KeyPackageRef, sponsor)` and its progress. */
145
+ export interface ApprovalGroupRecord {
146
+ readonly groupId: string;
147
+ readonly keyPackageRef: string;
148
+ readonly sponsorAccount: string;
149
+ readonly outcome: EnrolmentGroupOutcome;
150
+ /** Attempts that ran and did not add the device (at most {@link MAX_GROUP_ATTEMPTS}). */
151
+ readonly attempts: number;
152
+ /** An Add was issued and its fate is not known yet: counted once it settles without the device (C4). */
153
+ readonly inflight?: boolean;
154
+ /**
155
+ * S4 (AC-RECHK-1): set by {@link reopenApprovalGroup} — this group's `enrolled` outcome was contradicted by a
156
+ * rewind (or by a fresh pre-finalize snapshot) and is being re-driven. `driveApproval` threads the request's
157
+ * `leafKey` into `DeviceGroupPort.addDevice` as `reopenedLeafKey` only when this is set, so an ordinary
158
+ * (never-reopened) Add never pays for the extra rewind-window walk.
159
+ */
160
+ readonly reopened?: boolean;
161
+ /**
162
+ * AC-RECHK-1 on retries (c4-reacts-after-canonical-remove-unchecked): an earlier attempt was issued and settled
163
+ * unobserved (C4 — its commit was still in the pipeline when its pass ended): its Add may have landed, and a
164
+ * sibling may have removed the leaf before any pass saw it. Set when C4 counts that attempt, never cleared:
165
+ * every later Add of this group carries the leaf key and `approvalEpoch` like a reopened re-drive, and never
166
+ * advances `approvalEpoch`. Persisted (not derived from `inflight`, which C4 clears) so a crash between the
167
+ * count and the retry does not lose it.
168
+ */
169
+ readonly retried?: boolean;
170
+ /**
171
+ * AC-RECHK-1: this group's tip epoch (`DeviceGroupPort.groupEpoch`,
172
+ * `Number(groupContext.epoch)`) as of when the approval was taken — set at `approveEnrolment` start; advanced
173
+ * once, in `driveApproval`, to the tip epoch at which an Add is built over a departure no newer than the approval
174
+ * (the one finalize supersedes, AC-RECHK-2), so that superseded forget's Remove and the states before it are
175
+ * never grounds for AC-RECHK-1 refusal; never updated by a reopen. Threaded into `DeviceGroupPort.addDevice` as `approvalEpoch` alongside
176
+ * `reopenedLeafKey` so `inviteIntent`'s rewind-window refusal is bounded to a canonical departure at or after
177
+ * it, never one strictly older (e.g. a `devices.forget` Remove that settled before the device re-enrolled).
178
+ * Absent when the group was not held at approval time (falls back to the whole window, unbounded).
179
+ */
180
+ readonly approvalEpoch?: number;
181
+ }
182
+ /** `pending`: prompted; `dropped`: rate-limited (never prompted); `approving` / `approved`; `closed`: siblings' approvals covered every requested group. */
183
+ export type InboundStatus = 'pending' | 'dropped' | 'approving' | 'approved' | 'closed';
184
+ export interface InboundRequestRecord {
185
+ readonly v: 1;
186
+ readonly requestId: string;
187
+ readonly sessionId: string;
188
+ readonly label: string;
189
+ /** The rumor's `created_at` (unix s). */
190
+ readonly createdAt: number;
191
+ readonly expiresAt: number;
192
+ /** Client clock (ms). */
193
+ readonly receivedAt: number;
194
+ readonly relays: readonly string[];
195
+ readonly leafKey: string;
196
+ readonly groups: readonly EnrolmentRequestEntry[];
197
+ readonly status: InboundStatus;
198
+ readonly approval?: readonly ApprovalGroupRecord[];
199
+ /** Counted (non-transient) failures of background passes over this approval (W1). */
200
+ readonly driverFailures?: number;
201
+ /** Set once {@link MAX_MAINTENANCE_FAILURES} passes failed: no longer resumed. */
202
+ readonly gaveUp?: string;
203
+ /** Groups a sibling's approval notice reported the device enrolled in; the prompt closes once they cover every requested group. */
204
+ readonly approvedGroups?: readonly string[];
205
+ /**
206
+ * S4 (AC-RECHK-2): client clock (ms) when {@link approveEnrolment} started this approval (`pending` ->
207
+ * `approving`). {@link reopenApprovalGroup} compares a departure's own time (the registry tombstone's `at`, or
208
+ * the forget record's `startedAt`) against this to decide whether the departure is a real, later-than-this-
209
+ * approval departure (refuse) or a stale one this approval's finalize supersedes (reopen). Absent on a record
210
+ * written before this field existed: treated as the oldest possible time (`0`), so a pre-S4 record keeps the
211
+ * old, strictly conservative "refuse any departed leaf" behaviour rather than silently loosening it.
212
+ */
213
+ readonly approvedAt?: number;
214
+ }
215
+ export interface OutboundRequestRecord {
216
+ readonly v: 1;
217
+ readonly requestId: string;
218
+ readonly sessionId: string;
219
+ readonly expiresAt: number;
220
+ readonly rumor: Rumor;
221
+ readonly wrap?: NostrEvent;
222
+ /** `failed`: sealing or publishing it failed {@link MAX_MAINTENANCE_FAILURES} counted times (W1). */
223
+ readonly status: 'pending' | 'sent' | 'failed';
224
+ readonly failures?: number;
225
+ }
226
+ /** Every request still awaiting this user's decision (prompted, unexpired, not approved anywhere yet), oldest first. */
227
+ export declare function pendingEnrolments(deps: DeviceServiceDeps): Promise<readonly EnrolmentPrompt[]>;
228
+ export interface RegistryBinding {
229
+ /** Binds `label` to `leafKey` in the device registry (inside the caller's transaction), keeping an existing entry's `enrolledAt`. */
230
+ bindLabel(tx: AccountStoreTx, leafKey: string, label: string, enrolledAt: number): Promise<void>;
231
+ /**
232
+ * AC-RECHK-2 (amended 2026-10-04): clears `leafKey`'s tombstone and
233
+ * deletes its forget record — settled (`forgotten`) OR still in progress (`forgetting`) — PROVIDED the
234
+ * departure's own time (`tombstone.at` / `forget.startedAt`) is not NEWER than `approvedAt`; a departure newer
235
+ * than the approval is never superseded (it is a genuinely later, still-relevant decision). Deleting an
236
+ * in-progress `forgetting` record effectively cancels it: `resumeForgets`'s own `status !== 'forgetting'`
237
+ * guards mean nothing resumes a record that is simply gone. No-op when neither record exists, or when the one
238
+ * that does is newer than the approval. Called from {@link finalizeApproval} whenever an approval for
239
+ * `leafKey` finalizes with at least one group enrolled.
240
+ */
241
+ supersedeDeparture(tx: AccountStoreTx, leafKey: string, approvedAt: number): Promise<void>;
242
+ }
243
+ /**
244
+ * The `RUMOR_KINDS.ENROLMENT_REQUEST` native handler (runs on the inbox
245
+ * queue; S7 demux slot). Never waits on a group operation.
246
+ */
247
+ export declare function handleEnrolmentRumor(deps: DeviceServiceDeps, registry: RegistryBinding, rumor: Rumor, ctx: DispatchContext): Promise<RumorDisposition>;
248
+ export interface EnrolmentRequestOptions {
249
+ /** Shown to the approving sibling (AC-DEV-9). At most 128 characters. */
250
+ readonly label: string;
251
+ /** Hex MLS group ids to join. */
252
+ readonly groupIds: readonly string[];
253
+ /** Reuse a session id to send another request of the same pairing session. Default: a fresh random id. */
254
+ readonly sessionId?: string;
255
+ /** Minutes until the request (and its manifests) expire. Default 10, at most 1440. */
256
+ readonly expiresInMinutes?: number;
257
+ }
258
+ export interface EnrolmentRequestHandle {
259
+ readonly requestId: string;
260
+ readonly sessionId: string;
261
+ /** Unix seconds. */
262
+ readonly expiresAt: number;
263
+ }
264
+ /**
265
+ * `devices.requestEnrolment(options)` on the new device. Resolves once the
266
+ * request reached a relay; rejects `publish-failed` (retryable — it is
267
+ * re-published by the device service's background retry and later inbox
268
+ * passes until it expires) when none accepted it.
269
+ */
270
+ export declare function requestEnrolment(deps: DeviceServiceDeps, rawOptions: unknown): Promise<EnrolmentRequestHandle>;
271
+ export interface EnrolmentApprovalOutcome {
272
+ readonly requestId: string;
273
+ /** The new device's leaf key. */
274
+ readonly leafKey: string;
275
+ /** Per requested group: see {@link EnrolmentGroupOutcome}. */
276
+ readonly perGroupOutcome: Readonly<Record<string, EnrolmentGroupOutcome>>;
277
+ /** Every group's outcome is terminal (`pending` appears nowhere). */
278
+ readonly settled: boolean;
279
+ }
280
+ /**
281
+ * S10 (V1 revisable settlement): the outcome of one `DeviceGroupPort.onRewind`
282
+ * reopen pass for a group — `reopened` (something changed; redrive),
283
+ * `blocked` (the group's own `stateInvalidated` withdrawal is itself
284
+ * convergence-relevant input, so the snapshot reads `syncing: true` right at
285
+ * the rewind notification; the caller retries after the quiescence window),
286
+ * or `clear` (no longer held, or nothing needed reopening).
287
+ */
288
+ export type RewindReopenResult = 'reopened' | 'blocked' | 'clear';
289
+ /**
290
+ * S10 (V1 revisable settlement): `DeviceGroupPort.onRewind`'s handler for
291
+ * enrolment approvals, called after `groupId` rewound off a branch it had
292
+ * applied. Every inbound approval whose status is `approving` or `approved`
293
+ * and whose recorded outcome for `groupId` was `enrolled` is re-checked
294
+ * against one fresh snapshot; a leaf the rewind withdrew is reopened
295
+ * ({@link reopenApprovalGroup}). See {@link RewindReopenResult}.
296
+ */
297
+ export declare function reopenApprovalsAfterRewind(deps: DeviceServiceDeps, groupId: string, passWithdrawnLeaves?: readonly string[]): Promise<RewindReopenResult>;
298
+ /** A commit the pipeline dropped because every relay of the group refused it, or it exhausted its publish attempts. */
299
+ export declare function isRefusedCommit(error: unknown): boolean;
300
+ /**
301
+ * How a group operation of a device intent failed: `permanent` — retrying
302
+ * cannot help (an invalid KeyPackage, a commit every relay refused);
303
+ * `transient` — explicitly so (a signer timeout, a store lease, a publish
304
+ * still being retried, the group busy with another own commit or a deferred
305
+ * proposal): not counted; `counted` — anything else.
306
+ */
307
+ export type GroupActFailure = 'permanent' | 'transient' | 'counted';
308
+ /**
309
+ * `inviteIntent`'s AC-RECHK-1 refusal reason (client/pipeline.ts `MarmotError('invalid-options', ..., { details:
310
+ * { reason } })`) — exported so pipeline.ts throws the exact same literal `classifyGroupActFailure` pins below,
311
+ * rather than two independently-typed string literals that could silently drift apart.
312
+ */
313
+ export declare const REOPENED_LEAF_STILL_CANONICAL = "reopened-leaf-still-canonical";
314
+ export declare function classifyGroupActFailure(error: unknown): GroupActFailure;
315
+ /** Errors after which a device intent stops (the next client or pass resumes it). */
316
+ export declare function stopsDeviceIntent(error: unknown): boolean;
317
+ /**
318
+ * `devices.approveEnrolment(requestId)`: starts (or continues) the approval
319
+ * and runs one pass over its groups. Resolves with the outcome as stored —
320
+ * groups still `pending` are settled by later passes (their commits are the
321
+ * pipeline's durable intents).
322
+ *
323
+ * Call it from application (UI) code, not from inside an inbox handler or
324
+ * `onApplicationRumor`: those run in an account-scope consumer frame, which
325
+ * the approval's `group.invite` inherits and rejects `reentrant` (ADR-013).
326
+ */
327
+ export declare function approveEnrolment(deps: DeviceServiceDeps, registry: RegistryBinding, requestId: unknown): Promise<EnrolmentApprovalOutcome>;
328
+ /**
329
+ * Background continuation (every inbox pass, and a timer while anything is
330
+ * pending): every `approving` approval gets one more pass, and every unsent
331
+ * own request is re-published. Resolves `true` while work is left.
332
+ */
333
+ export declare function resumeEnrolments(deps: DeviceServiceDeps, registry: RegistryBinding): Promise<boolean>;
334
+ /**
335
+ * The KeyPackage events of every request this client recorded for any key of `leafKey`'s lineage (a forget deletes
336
+ * them); `chain` names further keys known to belong to the device (a forget's chain, which may include successions
337
+ * only a group's view showed).
338
+ */
339
+ export declare function requestedKeyPackages(deps: DeviceServiceDeps, leafKey: string, chain?: readonly string[]): Promise<NostrEvent[]>;