@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,40 @@
1
+ /**
2
+ * KeyPackage → group refs (AccountStore `keyPackageGroupRefs`, AC-STORE-9;
3
+ * S9): the KeyPackages this account minted FOR a group — a
4
+ * `keyPackages.offer({ groupId })`, or one of an enrolment request's
5
+ * per-group KeyPackages — keyed by the KeyPackage event id, so
6
+ * `group.destroy()` can publish kind-5 for them (AC-ADMIN-7). Plus the purge
7
+ * of the key material a group's teardown leaves in the slot records: the
8
+ * `superseded` init keys a joined Welcome's KeyPackage keeps for the grace
9
+ * window.
10
+ */
11
+ import type { AccountStoreTx } from '../storage/index.js';
12
+ export interface KeyPackageGroupRef {
13
+ /** The KeyPackage's kind-30443 event id (a `forget()` ref). */
14
+ readonly ref: string;
15
+ readonly groupId: string;
16
+ /** Client clock (ms). */
17
+ readonly at: number;
18
+ }
19
+ /** Records that the KeyPackage `ref` (its event id) was minted for `groupId`. */
20
+ export declare function recordKeyPackageGroupRef(tx: AccountStoreTx, entry: KeyPackageGroupRef): Promise<void>;
21
+ /** The refs recorded for `groupId`. A malformed entry is skipped (it names no group). */
22
+ export declare function keyPackageRefsOfGroup(tx: AccountStoreTx, groupId: string): Promise<string[]>;
23
+ /** Deletes every ref recorded for `groupId`. */
24
+ export declare function purgeKeyPackageGroupRefs(tx: AccountStoreTx, groupId: string): Promise<void>;
25
+ /**
26
+ * Whether the private key of KeyPackageRef `keyPackageRef` must not be kept
27
+ * as a `superseded` (grace-window) generation: its group was destroyed. S4's
28
+ * rotate settlement asks this in the transaction that would retain it.
29
+ */
30
+ export declare function isKeyUnretained(tx: AccountStoreTx, keyPackageRef: string): Promise<boolean>;
31
+ /**
32
+ * Drops the retained (`superseded`, grace-window) private keys whose
33
+ * KeyPackageRef is in `keyPackageRefs` — the keys of KeyPackages a group's
34
+ * Welcome consumed — and marks each ref "never retain": a rotate-after-consume
35
+ * still in flight (the consumed key still the slot's current one) then drops
36
+ * the key when it settles instead of moving it into `superseded` (S9 C2).
37
+ * The caller passes only refs no other invitation relies on; a last-resort
38
+ * KeyPackage's refs are skipped here whatever the caller passes (S9 AA1).
39
+ */
40
+ export declare function purgeRetainedKeyPackageKeys(tx: AccountStoreTx, keyPackageRefs: readonly string[], nowMs: number): Promise<void>;
@@ -0,0 +1,79 @@
1
+ import { listSlots, writeSlot } from './slot-manager.js';
2
+ const REFS = 'keyPackageGroupRefs';
3
+ function decodeRef(key, raw) {
4
+ if (typeof raw !== 'object' || raw === null)
5
+ return undefined;
6
+ const { groupId, at } = raw;
7
+ return typeof groupId === 'string' && typeof at === 'number' ? { ref: key, groupId, at } : undefined;
8
+ }
9
+ /** Records that the KeyPackage `ref` (its event id) was minted for `groupId`. */
10
+ export async function recordKeyPackageGroupRef(tx, entry) {
11
+ await tx.artifact(REFS).put(entry.ref, { groupId: entry.groupId, at: entry.at });
12
+ }
13
+ /** The refs recorded for `groupId`. A malformed entry is skipped (it names no group). */
14
+ export async function keyPackageRefsOfGroup(tx, groupId) {
15
+ const view = tx.artifact(REFS);
16
+ const out = [];
17
+ for (const key of await view.keys())
18
+ if (decodeRef(key, await view.get(key))?.groupId === groupId)
19
+ out.push(key);
20
+ return out;
21
+ }
22
+ /** Deletes every ref recorded for `groupId`. */
23
+ export async function purgeKeyPackageGroupRefs(tx, groupId) {
24
+ const view = tx.artifact(REFS);
25
+ for (const ref of await keyPackageRefsOfGroup(tx, groupId))
26
+ await view.delete(ref);
27
+ }
28
+ /** Prefix of the "never retain" markers {@link purgeRetainedKeyPackageKeys} leaves (same artifact, no groupId: never a ref). */
29
+ const UNRETAINED = 'unretained:';
30
+ /** A marker outlives any rotation it could meet (S4 retries a rotation for as long as its KeyPackage lives). */
31
+ const UNRETAINED_TTL_MS = 30 * 24 * 60 * 60 * 1000;
32
+ /**
33
+ * Whether the private key of KeyPackageRef `keyPackageRef` must not be kept
34
+ * as a `superseded` (grace-window) generation: its group was destroyed. S4's
35
+ * rotate settlement asks this in the transaction that would retain it.
36
+ */
37
+ export async function isKeyUnretained(tx, keyPackageRef) {
38
+ return (await tx.artifact(REFS).get(`${UNRETAINED}${keyPackageRef}`)) !== undefined;
39
+ }
40
+ /**
41
+ * Drops the retained (`superseded`, grace-window) private keys whose
42
+ * KeyPackageRef is in `keyPackageRefs` — the keys of KeyPackages a group's
43
+ * Welcome consumed — and marks each ref "never retain": a rotate-after-consume
44
+ * still in flight (the consumed key still the slot's current one) then drops
45
+ * the key when it settles instead of moving it into `superseded` (S9 C2).
46
+ * The caller passes only refs no other invitation relies on; a last-resort
47
+ * KeyPackage's refs are skipped here whatever the caller passes (S9 AA1).
48
+ */
49
+ export async function purgeRetainedKeyPackageKeys(tx, keyPackageRefs, nowMs) {
50
+ if (keyPackageRefs.length === 0)
51
+ return;
52
+ const view = tx.artifact('keyPackages');
53
+ const slots = await listSlots(view);
54
+ // AA1: a last-resort KeyPackage is shared by design (many inviters' Welcomes): its key is never marked or dropped.
55
+ const lastResort = new Set();
56
+ for (const slot of slots.filter((r) => r.lastResort)) {
57
+ for (const ref of [slot.currentRef, ...slot.published.map((e) => e.keyPackageRef), ...slot.superseded.map((e) => e.keyPackageRef)])
58
+ if (ref !== undefined)
59
+ lastResort.add(ref);
60
+ }
61
+ const refs = new Set(keyPackageRefs.filter((ref) => !lastResort.has(ref)));
62
+ if (refs.size === 0)
63
+ return;
64
+ const markers = tx.artifact(REFS);
65
+ for (const key of await markers.keys()) {
66
+ if (!key.startsWith(UNRETAINED))
67
+ continue;
68
+ const at = (await markers.get(key))?.at;
69
+ if (typeof at !== 'number' || at + UNRETAINED_TTL_MS < nowMs)
70
+ await markers.delete(key);
71
+ }
72
+ for (const ref of refs)
73
+ await markers.put(`${UNRETAINED}${ref}`, { at: nowMs });
74
+ for (const record of slots) {
75
+ const superseded = record.superseded.filter((s) => !refs.has(s.keyPackageRef));
76
+ if (superseded.length !== record.superseded.length)
77
+ await writeSlot(view, { ...record, superseded });
78
+ }
79
+ }
@@ -0,0 +1,18 @@
1
+ /**
2
+ * `key-packages` module barrel (S4): slot manager, publisher,
3
+ * `selectKeyPackage`, observation stream, offer-rumor codec. Not
4
+ * re-exported from the package root (`src/index.ts`) — `MarmotClient
5
+ * .keyPackages.*` is the public surface (docs/client-api.md); this barrel
6
+ * is the in-repo seam other `marmot` modules import through, per
7
+ * architecture.md's dependencies_allowed table (`client` now, `invitations`
8
+ * / `account` from S5 / S8 on).
9
+ */
10
+ export { createKeyPackage, rotateKeyPackage, purgeAllExpiredSuperseded, resumePendingIntents, probeParkedUnconfirmed, createParkedProbeState, type ParkedProbeState, forgetKeyPackage, retireKeyPackagesSignedWith, DEFAULT_CIPHERSUITE_NAME, type KeyPackageRetirementBlockReason, type KeyPackageRetirementOutcome, keyPackageStatus, listKeyPackages, countKeyPackages, fetchKeyPackageEvents, resolveWriteRelays, RESUME_BACKOFF_MS, type CreateKeyPackageOptions, type KeyPackageEventVerifier, type KeyPackagesDeps, type KeyPackagesRelayOptions, } from './publisher.js';
11
+ export { DEVICE_KEY_ENTRY, deviceProofSigner, ensureDeviceSigningKey, prepareDeviceKeyRotation, readDeviceSigningKey, withDeviceSignatureKey, type DeviceSigningKey, type PreparedDeviceKeyRotation, type PrepareDeviceKeyRotationInput, } from './device-key.js';
12
+ export { ROTATED_PREFIX, ROTATION_PREFIX, deviceKeyLinkKey, deviceKeyRotationKey, findOpenDeviceKeyRotation, isLeafKeyHex, moveRegistryEntry, readAllDeviceKeyLinks, readAllDeviceKeyRotations, readDeviceKeyLink, readDeviceKeyRotation, writeDeviceKeyLink, writeDeviceKeyRotation, type DeviceKeyLinkRecord, type DeviceKeyLinkSource, type DeviceKeyRotationGroup, type DeviceKeyRotationGroupOutcome, type DeviceKeyRotationRecord, type DeviceKeyRotationStatus, } from './device-rotation-records.js';
13
+ export { selectKeyPackage, type SelectedKeyPackage } from './select-key-package.js';
14
+ export { observeKeyPackages } from './observation-stream.js';
15
+ export { keyPackageRefsOfGroup, purgeKeyPackageGroupRefs, purgeRetainedKeyPackageKeys, recordKeyPackageGroupRef, type KeyPackageGroupRef } from './group-refs.js';
16
+ export { validateKeyPackageEvent } from './validate-key-package-event.js';
17
+ export { encodeKeyPackageOfferRumor, decodeKeyPackageOfferRumor, type DecodedKeyPackageOffer, type EncodeKeyPackageOfferRumorOptions } from './offer-rumor.js';
18
+ export { generateSlotId, computeKeyPackageRefHex, findPrivateKeyPackage, findKeyPackageEventByRef, type KeyPackageSlotRecord, type PendingIntent, type PublishedEntry, type SupersededEntry, } from './slot-manager.js';
@@ -0,0 +1,18 @@
1
+ /**
2
+ * `key-packages` module barrel (S4): slot manager, publisher,
3
+ * `selectKeyPackage`, observation stream, offer-rumor codec. Not
4
+ * re-exported from the package root (`src/index.ts`) — `MarmotClient
5
+ * .keyPackages.*` is the public surface (docs/client-api.md); this barrel
6
+ * is the in-repo seam other `marmot` modules import through, per
7
+ * architecture.md's dependencies_allowed table (`client` now, `invitations`
8
+ * / `account` from S5 / S8 on).
9
+ */
10
+ export { createKeyPackage, rotateKeyPackage, purgeAllExpiredSuperseded, resumePendingIntents, probeParkedUnconfirmed, createParkedProbeState, forgetKeyPackage, retireKeyPackagesSignedWith, DEFAULT_CIPHERSUITE_NAME, keyPackageStatus, listKeyPackages, countKeyPackages, fetchKeyPackageEvents, resolveWriteRelays, RESUME_BACKOFF_MS, } from './publisher.js';
11
+ export { DEVICE_KEY_ENTRY, deviceProofSigner, ensureDeviceSigningKey, prepareDeviceKeyRotation, readDeviceSigningKey, withDeviceSignatureKey, } from './device-key.js';
12
+ export { ROTATED_PREFIX, ROTATION_PREFIX, deviceKeyLinkKey, deviceKeyRotationKey, findOpenDeviceKeyRotation, isLeafKeyHex, moveRegistryEntry, readAllDeviceKeyLinks, readAllDeviceKeyRotations, readDeviceKeyLink, readDeviceKeyRotation, writeDeviceKeyLink, writeDeviceKeyRotation, } from './device-rotation-records.js';
13
+ export { selectKeyPackage } from './select-key-package.js';
14
+ export { observeKeyPackages } from './observation-stream.js';
15
+ export { keyPackageRefsOfGroup, purgeKeyPackageGroupRefs, purgeRetainedKeyPackageKeys, recordKeyPackageGroupRef } from './group-refs.js';
16
+ export { validateKeyPackageEvent } from './validate-key-package-event.js';
17
+ export { encodeKeyPackageOfferRumor, decodeKeyPackageOfferRumor } from './offer-rumor.js';
18
+ export { generateSlotId, computeKeyPackageRefHex, findPrivateKeyPackage, findKeyPackageEventByRef, } from './slot-manager.js';
@@ -0,0 +1,16 @@
1
+ /**
2
+ * `keyPackageRefOf(event)` — the hex KeyPackageRef (RFC 9420 §5.2 `make_key_package_ref`, MIP-00) of a kind-30443
3
+ * KeyPackage event: what `invitations.expectWelcome()` takes as `keyPackageRef`, and what `keyPackages.rotate()` /
4
+ * `forget()` accept besides the event id. Public (package root) so a consumer holding the event that
5
+ * `keyPackages.create()` / `offer()` returned — or one fetched from a relay — needs no `@941design/marmot/mls`
6
+ * derivation of its own (marmot-public-keypackage-ref).
7
+ *
8
+ * It derives; it does not verify: the event's signature and the KeyPackage's own validity are not checked (an
9
+ * invitee's KeyPackage is validated where it is used — `group.invite()`).
10
+ */
11
+ import type { NostrEvent } from '@941design/nostr-events/event';
12
+ /**
13
+ * The hex KeyPackageRef of `event`'s KeyPackage. Rejects `invalid-options` when `event` is not a kind-30443
14
+ * event whose content decodes as a framed MLS KeyPackage (`mls_key_package` wire format, base64).
15
+ */
16
+ export declare function keyPackageRefOf(event: NostrEvent): Promise<string>;
@@ -0,0 +1,21 @@
1
+ import { getKeyPackage } from '@941design/marmot-engine/core';
2
+ import { MarmotError } from '../shared/index.js';
3
+ import { computeKeyPackageRefHex } from './slot-manager.js';
4
+ const KEY_PACKAGE_KIND = 30443;
5
+ /**
6
+ * The hex KeyPackageRef of `event`'s KeyPackage. Rejects `invalid-options` when `event` is not a kind-30443
7
+ * event whose content decodes as a framed MLS KeyPackage (`mls_key_package` wire format, base64).
8
+ */
9
+ export async function keyPackageRefOf(event) {
10
+ if (typeof event !== 'object' || event === null || event.kind !== KEY_PACKAGE_KIND || typeof event.content !== 'string') {
11
+ throw new MarmotError('invalid-options', 'keyPackageRefOf: not a kind-30443 KeyPackage event');
12
+ }
13
+ let keyPackage;
14
+ try {
15
+ keyPackage = getKeyPackage(event);
16
+ }
17
+ catch (cause) {
18
+ throw new MarmotError('invalid-options', 'keyPackageRefOf: the event content is not an MLS KeyPackage', { cause });
19
+ }
20
+ return computeKeyPackageRefHex(keyPackage);
21
+ }
@@ -0,0 +1,4 @@
1
+ import type { NostrEvent } from '@941design/nostr-events/event';
2
+ import { type KeyPackagesDeps } from './publisher.js';
3
+ /** Opens the observation subscription; returns its `unsubscribe`. */
4
+ export declare function observeKeyPackages(deps: KeyPackagesDeps, account: string, listener: (event: NostrEvent) => void): () => void;
@@ -0,0 +1,120 @@
1
+ /**
2
+ * `client.keyPackages.observe(account, listener)` (AC-KP-6): one live
3
+ * subscription for `account`'s kind-30443 events, each qualifying event
4
+ * reaching `listener` exactly once — even under relay redelivery (the
5
+ * transport contract makes no at-most-once promise) or a relay ignoring the
6
+ * filter it was asked.
7
+ *
8
+ * Gate-remediation F9: validity now goes through the SAME
9
+ * `validateKeyPackageEvent` predicate `select-key-package.ts` uses (single
10
+ * owner, no second copy of the kind/signature/credential checks), a
11
+ * qualifying event also passes the consumer's `verifier` when one is
12
+ * configured (ADR-008, same as the group ingest path), and the subscribe
13
+ * relays are resolved the same way `create()` resolves its publish relays
14
+ * (`resolveWriteRelays`) — for `relays.mode === 'discover'` that means
15
+ * `account`'s OWN newest kind-10002 write set, not necessarily the caller's.
16
+ * `'fixed'` mode stays synchronous (no discovery round-trip needed), so the
17
+ * subscription opens before `observe()` returns, as it always has.
18
+ *
19
+ * Gate-remediation R4: a `resolveWriteRelays` failure in `'discover'` mode
20
+ * falls back to `relays.defaults` rather than leaving `observe()` silently
21
+ * unsubscribed; the consumer's `listener` is called inside a try/catch so a
22
+ * throw from it never becomes an unhandled rejection; `deps.verifier` is
23
+ * already routed through `guard.call(ACCOUNT_SCOPE, 'verifier', ...)` by
24
+ * `client/create-client.ts` (matching `client/ingest.ts`'s own verifier
25
+ * call) — this module still wraps the call itself in a try/catch as
26
+ * defence-in-depth (e.g. against a `reentrant` rejection).
27
+ *
28
+ * Gate-remediation round 6 (F3): `open()` itself — `deps.subscription(...)`
29
+ * followed by `.subscribe(...)` — can throw (a misbehaving transport, or a
30
+ * consumer-supplied one in a test). Two call sites, two different
31
+ * obligations:
32
+ * - `'fixed'` mode calls `open()` SYNCHRONOUSLY, directly from
33
+ * `observeKeyPackages`'s own execution — it is not detached, so a throw
34
+ * here is left to propagate straight out to `observe()`'s own caller,
35
+ * exactly like any other synchronous `observe()` failure (e.g. a bad
36
+ * argument). This is a deliberate choice, not an oversight: swallowing
37
+ * it would silently hand back a no-op `unsubscribe` with no observation
38
+ * ever having started, which is worse than a loud synchronous failure
39
+ * the caller can catch and act on.
40
+ * - `'discover'` mode calls `open()` from inside a DETACHED `.then()` —
41
+ * `resolveWriteRelays(...)` is awaited with nothing left holding the
42
+ * promise chain once `observeKeyPackages` itself has already returned
43
+ * its `unsubscribe` function. A throw from `open()` here MUST be caught
44
+ * — otherwise it becomes an unhandled rejection with no caller able to
45
+ * do anything about it. Nothing extra needs tearing down on that catch:
46
+ * `open()` only ever assigns `subscriptionHandle` AFTER `.subscribe()`
47
+ * returns successfully, so a throw from either `deps.subscription(...)`
48
+ * or `.subscribe(...)` never leaves a partial/dangling handle behind —
49
+ * there is nothing to unsubscribe.
50
+ * - `open()`'s existing `if (disposed) return` guard (unchanged) already
51
+ * covers dispose-during-discovery: if `dispose()` runs while
52
+ * `resolveWriteRelays` is still in flight, `subscriptionHandle` stays
53
+ * `undefined` (nothing to tear down at dispose time), and when
54
+ * discovery finally resolves, `open()`'s own guard sees `disposed` and
55
+ * never creates a subscription at all.
56
+ */
57
+ import { ADDRESSABLE_KEY_PACKAGE_KIND } from '@941design/marmot-engine/core';
58
+ import { resolveWriteRelays } from './publisher.js';
59
+ import { validateKeyPackageEvent } from './validate-key-package-event.js';
60
+ /** Opens the observation subscription; returns its `unsubscribe`. */
61
+ export function observeKeyPackages(deps, account, listener) {
62
+ const seen = new Set();
63
+ let disposed = false;
64
+ let subscriptionHandle;
65
+ async function handle(event) {
66
+ if (event.pubkey !== account)
67
+ return; // a relay is not obliged to honour the filter it was asked
68
+ if (seen.has(event.id))
69
+ return;
70
+ if (validateKeyPackageEvent(event) === undefined)
71
+ return; // F2/F9: kind, signature, credential<->pubkey — single owner
72
+ if (deps.verifier !== undefined) {
73
+ let ok;
74
+ try {
75
+ ok = await deps.verifier(event);
76
+ }
77
+ catch {
78
+ ok = false;
79
+ }
80
+ if (!ok)
81
+ return;
82
+ }
83
+ if (disposed || seen.has(event.id))
84
+ return; // re-check: the verifier awaited, a duplicate (or unsubscribe) may have landed meanwhile
85
+ seen.add(event.id);
86
+ try {
87
+ listener(event);
88
+ }
89
+ catch {
90
+ // A throwing consumer listener must not surface as an unhandled
91
+ // rejection out of this async chain (R4) — mirrors create-client.ts's
92
+ // own `emit()`, which swallows a throwing client-event listener.
93
+ }
94
+ }
95
+ function open(relays) {
96
+ if (disposed)
97
+ return;
98
+ const subscription = deps.subscription([...relays], { kinds: [ADDRESSABLE_KEY_PACKAGE_KIND], authors: [account] });
99
+ subscriptionHandle = subscription.subscribe({ next: (event) => void handle(event) });
100
+ }
101
+ if (deps.relays.mode === 'fixed') {
102
+ open(deps.relays.defaults); // synchronous, not detached — a throw here propagates to observe()'s own caller (documented above)
103
+ }
104
+ else {
105
+ void resolveWriteRelays(deps, account)
106
+ .catch(() => [...deps.relays.defaults]) // R4: a discovery failure falls back to defaults rather than leaving observe() silently unsubscribed
107
+ .then((relays) => {
108
+ try {
109
+ open(relays);
110
+ }
111
+ catch {
112
+ // F3: detached — never let a throw from open() become an unhandled rejection (documented above).
113
+ }
114
+ });
115
+ }
116
+ return () => {
117
+ disposed = true;
118
+ subscriptionHandle?.unsubscribe();
119
+ };
120
+ }
@@ -0,0 +1,26 @@
1
+ import { type NostrEvent, type Rumor } from '@941design/nostr-events/event';
2
+ export interface EncodeKeyPackageOfferRumorOptions {
3
+ /** The offering account's pubkey (the rumor's `pubkey`; the gift wrap's seal proves authorship separately). */
4
+ readonly pubkey: string;
5
+ /** The full signed kind-30443 event being offered. */
6
+ readonly keyPackageEvent: NostrEvent;
7
+ /** The group the offer targets — carried only inside this rumor, never as a tag on `keyPackageEvent`. */
8
+ readonly groupId: string;
9
+ /** Unix seconds. Required (not defaulted to the wall clock) so the codec stays pure and deterministic. */
10
+ readonly createdAt: number;
11
+ }
12
+ export interface DecodedKeyPackageOffer {
13
+ readonly keyPackageEvent: NostrEvent;
14
+ readonly groupId: string;
15
+ }
16
+ /** Builds the offer rumor (unsigned; no `sig`, per NIP-59). */
17
+ export declare function encodeKeyPackageOfferRumor(opts: EncodeKeyPackageOfferRumorOptions): Rumor;
18
+ /**
19
+ * Parses an offer rumor's payload. Never throws (D-08 typed-reject
20
+ * convention): malformed content, a wrong `kind`, a missing/malformed
21
+ * `keyPackageEvent`, a missing/empty `groupId`, or a `keyPackageEvent`
22
+ * authored by someone OTHER than the rumor's own `pubkey` (gate-remediation
23
+ * F11 — otherwise anyone could relay a stranger's KeyPackage inside a rumor
24
+ * claiming to be its offerer) all yield `undefined`.
25
+ */
26
+ export declare function decodeKeyPackageOfferRumor(rumor: Rumor): DecodedKeyPackageOffer | undefined;
@@ -0,0 +1,69 @@
1
+ /**
2
+ * The "KeyPackage offer" rumor codec (AC-KP-7; spec Design Decision 5):
3
+ * a targeted KeyPackage travels as a rumor carrying the full serialised
4
+ * (signed) kind-30443 event plus the target group id, gift-wrapped to one
5
+ * recipient — never as a group-identifying tag on the public kind-30443
6
+ * event itself. This module builds/parses the {@link Rumor} only; wrapping
7
+ * it in a NIP-59 gift wrap and sending it is the inviter/enrolment flow's
8
+ * job (S5 / S8).
9
+ *
10
+ * `RUMOR_KINDS.KEYPACKAGE_OFFER` is the S1-pinned constant (AC-API-8); this
11
+ * file never spells `4461` (enforced by kinds.test.ts's source-tree scan).
12
+ */
13
+ import { ADDRESSABLE_KEY_PACKAGE_KIND } from '@941design/marmot-engine/core';
14
+ import { getEventHash } from '@941design/nostr-events/event';
15
+ import { RUMOR_KINDS } from '../shared/index.js';
16
+ /** Builds the offer rumor (unsigned; no `sig`, per NIP-59). */
17
+ export function encodeKeyPackageOfferRumor(opts) {
18
+ const payload = { v: 1, keyPackageEvent: opts.keyPackageEvent, groupId: opts.groupId };
19
+ const unsigned = {
20
+ pubkey: opts.pubkey,
21
+ kind: RUMOR_KINDS.KEYPACKAGE_OFFER,
22
+ created_at: opts.createdAt,
23
+ tags: [],
24
+ content: JSON.stringify(payload),
25
+ };
26
+ return { ...unsigned, id: getEventHash(unsigned) };
27
+ }
28
+ function isNostrEventShape(value) {
29
+ if (typeof value !== 'object' || value === null)
30
+ return false;
31
+ const e = value;
32
+ return (typeof e['id'] === 'string' &&
33
+ typeof e['pubkey'] === 'string' &&
34
+ e['kind'] === ADDRESSABLE_KEY_PACKAGE_KIND &&
35
+ typeof e['created_at'] === 'number' &&
36
+ typeof e['sig'] === 'string' &&
37
+ Array.isArray(e['tags']));
38
+ }
39
+ /**
40
+ * Parses an offer rumor's payload. Never throws (D-08 typed-reject
41
+ * convention): malformed content, a wrong `kind`, a missing/malformed
42
+ * `keyPackageEvent`, a missing/empty `groupId`, or a `keyPackageEvent`
43
+ * authored by someone OTHER than the rumor's own `pubkey` (gate-remediation
44
+ * F11 — otherwise anyone could relay a stranger's KeyPackage inside a rumor
45
+ * claiming to be its offerer) all yield `undefined`.
46
+ */
47
+ export function decodeKeyPackageOfferRumor(rumor) {
48
+ if (rumor.kind !== RUMOR_KINDS.KEYPACKAGE_OFFER)
49
+ return undefined;
50
+ let parsed;
51
+ try {
52
+ parsed = JSON.parse(rumor.content);
53
+ }
54
+ catch {
55
+ return undefined;
56
+ }
57
+ if (typeof parsed !== 'object' || parsed === null)
58
+ return undefined;
59
+ const payload = parsed;
60
+ if (payload['v'] !== 1)
61
+ return undefined;
62
+ if (!isNostrEventShape(payload['keyPackageEvent']))
63
+ return undefined;
64
+ if (typeof payload['groupId'] !== 'string' || payload['groupId'].length === 0)
65
+ return undefined;
66
+ if (payload['keyPackageEvent'].pubkey !== rumor.pubkey)
67
+ return undefined;
68
+ return { keyPackageEvent: payload['keyPackageEvent'], groupId: payload['groupId'] };
69
+ }
@@ -0,0 +1,174 @@
1
+ import { type CiphersuiteName } from '@941design/marmot-engine/mls';
2
+ import { type EventTemplate, type Filter, type NostrEvent } from '@941design/nostr-events/event';
3
+ import type { PublishResponse, RequestWithDeadlineResult, Subscribable } from '@941design/nostr-events/transport/contract';
4
+ import type { AccountStoreTx } from '../storage/index.js';
5
+ export declare const DEFAULT_CIPHERSUITE_NAME: CiphersuiteName;
6
+ export declare const RESUME_BACKOFF_MS = 30000;
7
+ export interface KeyPackagesRelayOptions {
8
+ readonly defaults: readonly string[];
9
+ readonly mode: 'discover' | 'fixed';
10
+ }
11
+ /** Matches `client/create-client.ts`'s `EventVerifier` structurally, without importing it (boundary rule). */
12
+ export type KeyPackageEventVerifier = (event: NostrEvent) => boolean | Promise<boolean>;
13
+ /**
14
+ * Everything `publisher.ts`/`observation-stream.ts` need from the client,
15
+ * already narrowed and — for `getPublicKey`/`signEvent`/`publish`/
16
+ * `requestWithDeadline`/`subscription`/`transaction`/`verifier` — already
17
+ * wrapped through the client's `ReentrancyGuard` and account-key signer by
18
+ * the caller (`client/create-client.ts`). This module never imports the
19
+ * guard or signer types itself.
20
+ */
21
+ export interface KeyPackagesDeps {
22
+ readonly clock: {
23
+ now(): number;
24
+ };
25
+ /** Milliseconds (AC-KP-3). */
26
+ readonly graceWindowMs: number;
27
+ readonly relays: KeyPackagesRelayOptions;
28
+ /** Deadline for the 10002 write-relay discovery request (`relays.mode === 'discover'`). */
29
+ readonly historyTimeoutMs: number;
30
+ /**
31
+ * Consumer-supplied event check (ADR-008), run on every event `observe()`
32
+ * would otherwise emit (F9). Already routed through
33
+ * `guard.call(ACCOUNT_SCOPE, 'verifier', ...)` by the caller
34
+ * (gate-remediation R4) — this module never touches the guard itself.
35
+ */
36
+ readonly verifier: KeyPackageEventVerifier | undefined;
37
+ getPublicKey(): Promise<string>;
38
+ signEvent(template: EventTemplate): Promise<NostrEvent>;
39
+ publish(relays: readonly string[], event: NostrEvent): Promise<Record<string, PublishResponse>>;
40
+ requestWithDeadline(relays: readonly string[], filters: Filter | Filter[], opts: {
41
+ timeoutMs: number;
42
+ }): Promise<RequestWithDeadlineResult>;
43
+ subscription(relays: readonly string[], filters: Filter | Filter[]): Subscribable<NostrEvent>;
44
+ /** This client's parked-event probe state ({@link probeParkedUnconfirmed}); one per client, created with {@link createParkedProbeState}. */
45
+ readonly parkedProbe: ParkedProbeState;
46
+ /** `AccountStore.transaction`, already routed through `guard.call(ACCOUNT_SCOPE, 'store', ...)` (F6) — every store access in this module goes through this, never a raw store reference. */
47
+ transaction<T>(fn: (tx: AccountStoreTx) => Promise<T> | T): Promise<T>;
48
+ }
49
+ /** Per-client, mutable state of {@link probeParkedUnconfirmed}. */
50
+ export interface ParkedProbeState {
51
+ /** A probe completed (or found nothing parked) since this client was built. */
52
+ done: boolean;
53
+ /** Client clock (ms) of the last probe attempt; retries wait {@link RESUME_BACKOFF_MS}. */
54
+ lastAttemptMs: number | undefined;
55
+ inFlight: boolean;
56
+ }
57
+ export declare function createParkedProbeState(): ParkedProbeState;
58
+ export interface CreateKeyPackageOptions {
59
+ readonly relays?: readonly string[];
60
+ readonly lastResort?: boolean;
61
+ }
62
+ /**
63
+ * Resolves the write-relay set for `pubkey`: an explicit `override` wins;
64
+ * else `relays.mode === 'fixed'` uses `relays.defaults` directly; else
65
+ * (`'discover'`) fetches `pubkey`'s newest VALID (signature- and, when
66
+ * configured, verifier-passing — C2) kind-10002 and takes its `write` set,
67
+ * falling back to `relays.defaults` on timeout/absence/no valid candidate/
68
+ * empty write set. Shared by `create()`, `rotate()` (F12: rotate re-resolves
69
+ * on every call) and `observeKeyPackages` (F9: "the same way create does"),
70
+ * parameterised on `pubkey` so `observe(account, ...)` resolves the
71
+ * OBSERVED account's relays, not necessarily the caller's own.
72
+ */
73
+ export declare function resolveWriteRelays(deps: KeyPackagesDeps, pubkey: string, override?: readonly string[]): Promise<string[]>;
74
+ /**
75
+ * AC-KPL-1 after a crash or reload: an accepted event can stay parked in
76
+ * `unconfirmed` when the process stopped after a concurrent terminal resume
77
+ * parked it but before the accepting attempt committed. Until one probe
78
+ * completes on this client, asks the slots' relays for every `unconfirmed`
79
+ * event id in one batched request within `historyTimeoutMs`, and settles
80
+ * each event a relay returns (signature-checked, id-matched) through
81
+ * {@link settleParkedAcceptance}, oldest `created_at` first per slot. The
82
+ * probe counts as done only when the request completed without timing out
83
+ * (or nothing was parked); a failed or timed-out probe is retried at most
84
+ * once per {@link RESUME_BACKOFF_MS}, and meanwhile the entries simply stay
85
+ * in `unconfirmed` (reaped at `notAfter * 1000 + graceWindowMs`). Run by
86
+ * `create()`/`rotate()` and the inbox pass, never by `list()`/`count()`, so
87
+ * reads never wait on a relay.
88
+ */
89
+ export declare function probeParkedUnconfirmed(deps: KeyPackagesDeps): Promise<void>;
90
+ /**
91
+ * Resolves every slot's pending intent, if any and if due (R2(4) backoff), by (re)publishing its already-signed event — idempotent, so a duplicate republish is harmless.
92
+ * Exported for S6: every inbox pass runs it, so an idle client still settles a rotation whose publish failed.
93
+ */
94
+ export declare function resumePendingIntents(deps: KeyPackagesDeps): Promise<void>;
95
+ /**
96
+ * Round 6 stop-rule fix: also reaps `unconfirmed` entries past their OWN
97
+ * KeyPackage lifetime (`reapExpiredUnconfirmed`), alongside the existing
98
+ * `superseded` grace-window purge — one pass, one write per changed record.
99
+ * Exported for S6: every inbox pass runs this same purge.
100
+ */
101
+ export declare function purgeAllExpiredSuperseded(deps: KeyPackagesDeps): Promise<void>;
102
+ /**
103
+ * S9 (`group.destroy()`): where `ref`'s KeyPackage stands locally — `absent`
104
+ * (no slot holds it: never minted here, already deleted, or superseded by a
105
+ * rotation), `deleting` (a `forget()`'s kind-5 is durably pending on its
106
+ * slot), or `present`.
107
+ */
108
+ export declare function keyPackageStatus(deps: Pick<KeyPackagesDeps, 'transaction'>, ref: string): Promise<'absent' | 'deleting' | 'present'>;
109
+ export declare function createKeyPackage(deps: KeyPackagesDeps, options?: CreateKeyPackageOptions): Promise<NostrEvent>;
110
+ export declare function rotateKeyPackage(deps: KeyPackagesDeps, ref: string): Promise<NostrEvent>;
111
+ export declare function forgetKeyPackage(deps: KeyPackagesDeps, ref: string): Promise<void>;
112
+ /**
113
+ * S8 (`devices.forget`): every valid kind-30443 event `pubkey` has on its
114
+ * write relays (resolved like `create` resolves them) — each one passed
115
+ * {@link validateKeyPackageEvent} and the consumer verifier. `timedOut`:
116
+ * the answer may be incomplete. `relays` is where it was asked (a deletion
117
+ * goes there too).
118
+ */
119
+ export declare function fetchKeyPackageEvents(deps: KeyPackagesDeps, pubkey: string): Promise<{
120
+ readonly events: readonly NostrEvent[];
121
+ readonly relays: readonly string[];
122
+ readonly timedOut: boolean;
123
+ }>;
124
+ export declare function listKeyPackages(deps: KeyPackagesDeps): Promise<readonly NostrEvent[]>;
125
+ export declare function countKeyPackages(deps: KeyPackagesDeps): Promise<number>;
126
+ /** Why one slot of a retirement is not finished; the next run (or a resume) retries it. */
127
+ export type KeyPackageRetirementBlockReason = 'pending-intent' | 'publish-failed' | 'no-relays' | 'no-current' | 'delete-pending' | 'relay-unreachable';
128
+ export interface KeyPackageRetirementOutcome {
129
+ /** Slots whose KeyPackage was replaced by one carrying the device key in this call. */
130
+ readonly replaced: readonly string[];
131
+ /** Slots whose retired-key events got an accepted kind-5 in this call. */
132
+ readonly deleted: readonly string[];
133
+ /** Slots with retired-key material this call could not finish. Empty when the retirement is complete. */
134
+ readonly blocked: readonly {
135
+ readonly dSlot: string;
136
+ readonly reason: KeyPackageRetirementBlockReason;
137
+ }[];
138
+ }
139
+ /**
140
+ * Replaces every KeyPackage whose leaf signature key is in `keys` (Design
141
+ * Decision 10, AC-KP-1..5) — the last-resort slot included — by one carrying
142
+ * the device key and its stored proof, and then kind-5 deletes the retired-key
143
+ * events.
144
+ *
145
+ * Per slot, in order: (1) a slot whose current KeyPackage, or any possibly-live
146
+ * `unconfirmed` one that can still be live at the address (not replaced by the
147
+ * current event, not deleted) carries a retired key is `rotate()`d — the replacement is
148
+ * minted with the device key (`ensureDeviceSigningKey` = `self`) and published
149
+ * under the same `d` address, so the relay's addressable replacement swaps it in
150
+ * and there is never a moment with no advertised KeyPackage; (2) only once the
151
+ * replacement is accepted, a kind-5 over the retired events' IDS (`e` tags
152
+ * only — an address-scoped deletion would take the replacement with it) is
153
+ * signed once and sent only to relays known to hold the replacement (the current
154
+ * event is re-published first; the accepting relays count) plus the slot relays
155
+ * that left the write set, and recorded per relay in the slot's `deletions`; a
156
+ * relay still missing is retried by the next run. A deleted `unconfirmed`
157
+ * candidate moves to `superseded`. The superseded
158
+ * private material stays resolvable for the usual grace window
159
+ * (`findPrivateKeyPackage`), so a Welcome built against the old KeyPackage still
160
+ * joins. Signer cost per slot: the replacement event and the deletion — at most
161
+ * two, whatever the number of held groups.
162
+ *
163
+ * Idempotent and resumable: every step rests on the slot's durable record, so a
164
+ * run that stopped at any await boundary, run again, ends where an uninterrupted
165
+ * one would — a slot already on the device key is skipped, a deletion already
166
+ * recorded is not repeated. A slot it cannot finish (a stuck pending intent, no
167
+ * relay accepting) is reported in `blocked`, never thrown; any other error
168
+ * propagates.
169
+ *
170
+ * `keys` are 64-hex leaf keys. Rejects `invalid-options` when there is no device
171
+ * key yet (`reason: 'no-device-key'`) or when `keys` names the device key itself
172
+ * (`reason: 'retire-current-key'`).
173
+ */
174
+ export declare function retireKeyPackagesSignedWith(deps: KeyPackagesDeps, keys: readonly string[]): Promise<KeyPackageRetirementOutcome>;