@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.
- package/CHANGELOG.md +739 -0
- package/LICENSE +21 -0
- package/README.md +33 -2
- package/dist/account/admin.d.ts +72 -0
- package/dist/account/admin.js +209 -0
- package/dist/account/device-deps.d.ts +379 -0
- package/dist/account/device-deps.js +36 -0
- package/dist/account/device-lineage.d.ts +199 -0
- package/dist/account/device-lineage.js +390 -0
- package/dist/account/device-registry.d.ts +93 -0
- package/dist/account/device-registry.js +1290 -0
- package/dist/account/device-rotation.d.ts +61 -0
- package/dist/account/device-rotation.js +827 -0
- package/dist/account/enrolment.d.ts +339 -0
- package/dist/account/enrolment.js +1247 -0
- package/dist/account/identity-proof.d.ts +79 -0
- package/dist/account/identity-proof.js +264 -0
- package/dist/account/index.d.ts +17 -0
- package/dist/account/index.js +16 -0
- package/dist/account/restore-rotation.d.ts +21 -0
- package/dist/account/restore-rotation.js +22 -0
- package/dist/account/same-account-authorization.d.ts +86 -0
- package/dist/account/same-account-authorization.js +180 -0
- package/dist/account/teardown.d.ts +190 -0
- package/dist/account/teardown.js +878 -0
- package/dist/client/admission-cleanup.d.ts +197 -0
- package/dist/client/admission-cleanup.js +635 -0
- package/dist/client/adoption-proof.d.ts +39 -0
- package/dist/client/adoption-proof.js +102 -0
- package/dist/client/before-create-group.d.ts +18 -0
- package/dist/client/before-create-group.js +65 -0
- package/dist/client/before-publish-hooks.d.ts +121 -0
- package/dist/client/before-publish-hooks.js +182 -0
- package/dist/client/client-config.d.ts +42 -0
- package/dist/client/client-config.js +13 -0
- package/dist/client/commit-redrive.d.ts +92 -0
- package/dist/client/commit-redrive.js +274 -0
- package/dist/client/component-update.d.ts +43 -0
- package/dist/client/component-update.js +53 -0
- package/dist/client/confirm-hooks.d.ts +55 -0
- package/dist/client/confirm-hooks.js +74 -0
- package/dist/client/create-client.d.ts +1126 -0
- package/dist/client/create-client.js +1232 -0
- package/dist/client/group-availability.d.ts +182 -0
- package/dist/client/group-availability.js +301 -0
- package/dist/client/group-disband.d.ts +28 -0
- package/dist/client/group-disband.js +64 -0
- package/dist/client/group-history.d.ts +461 -0
- package/dist/client/group-history.js +1365 -0
- package/dist/client/group-profile.d.ts +31 -0
- package/dist/client/group-profile.js +62 -0
- package/dist/client/group-records.d.ts +522 -0
- package/dist/client/group-records.js +1117 -0
- package/dist/client/group-removal.d.ts +36 -0
- package/dist/client/group-removal.js +127 -0
- package/dist/client/group-remove-member.d.ts +49 -0
- package/dist/client/group-remove-member.js +163 -0
- package/dist/client/group-runtime.d.ts +415 -0
- package/dist/client/group-runtime.js +2811 -0
- package/dist/client/group-snapshot.d.ts +104 -0
- package/dist/client/group-snapshot.js +474 -0
- package/dist/client/history-pages.d.ts +107 -0
- package/dist/client/history-pages.js +194 -0
- package/dist/client/inbox-send.d.ts +19 -0
- package/dist/client/inbox-send.js +71 -0
- package/dist/client/index.d.ts +24 -0
- package/dist/client/index.js +13 -0
- package/dist/client/ingest.d.ts +82 -0
- package/dist/client/ingest.js +1584 -0
- package/dist/client/invitation-outcomes.d.ts +50 -0
- package/dist/client/invitation-outcomes.js +135 -0
- package/dist/client/lifecycle-events.d.ts +63 -0
- package/dist/client/lifecycle-events.js +35 -0
- package/dist/client/opaque-candidates.d.ts +82 -0
- package/dist/client/opaque-candidates.js +170 -0
- package/dist/client/own-change-outbox.d.ts +66 -0
- package/dist/client/own-change-outbox.js +158 -0
- package/dist/client/pending-leaf.d.ts +116 -0
- package/dist/client/pending-leaf.js +378 -0
- package/dist/client/permissions.d.ts +9 -0
- package/dist/client/permissions.js +12 -0
- package/dist/client/pipeline.d.ts +583 -0
- package/dist/client/pipeline.js +3666 -0
- package/dist/client/reentrancy-guard.d.ts +102 -0
- package/dist/client/reentrancy-guard.js +159 -0
- package/dist/client/rekey.d.ts +58 -0
- package/dist/client/rekey.js +149 -0
- package/dist/client/transport-policy.d.ts +181 -0
- package/dist/client/transport-policy.js +214 -0
- package/dist/history/admission-lineage.d.ts +186 -0
- package/dist/history/admission-lineage.js +589 -0
- package/dist/history/equivocation.d.ts +55 -0
- package/dist/history/equivocation.js +113 -0
- package/dist/history/fencing.d.ts +66 -0
- package/dist/history/fencing.js +121 -0
- package/dist/history/hex.d.ts +3 -0
- package/dist/history/hex.js +10 -0
- package/dist/history/index.d.ts +74 -0
- package/dist/history/index.js +32 -0
- package/dist/history/notifications.d.ts +270 -0
- package/dist/history/notifications.js +264 -0
- package/dist/history/ordering-key.d.ts +24 -0
- package/dist/history/ordering-key.js +101 -0
- package/dist/history/own-change-fork.d.ts +112 -0
- package/dist/history/own-change-fork.js +196 -0
- package/dist/history/own-change.d.ts +118 -0
- package/dist/history/own-change.js +146 -0
- package/dist/history/policy.d.ts +48 -0
- package/dist/history/policy.js +52 -0
- package/dist/history/retained-window.d.ts +215 -0
- package/dist/history/retained-window.js +565 -0
- package/dist/inbox/demux.d.ts +90 -0
- package/dist/inbox/demux.js +78 -0
- package/dist/inbox/handler-registry.d.ts +42 -0
- package/dist/inbox/handler-registry.js +37 -0
- package/dist/inbox/index.d.ts +11 -0
- package/dist/inbox/index.js +10 -0
- package/dist/inbox/seen-set.d.ts +82 -0
- package/dist/inbox/seen-set.js +202 -0
- package/dist/inbox/subscription.d.ts +236 -0
- package/dist/inbox/subscription.js +644 -0
- package/dist/index.d.ts +10 -0
- package/dist/index.js +9 -0
- package/dist/invitations/competing-welcome.d.ts +223 -0
- package/dist/invitations/competing-welcome.js +128 -0
- package/dist/invitations/decline.d.ts +67 -0
- package/dist/invitations/decline.js +149 -0
- package/dist/invitations/delivery-evidence.d.ts +288 -0
- package/dist/invitations/delivery-evidence.js +766 -0
- package/dist/invitations/expect-welcome.d.ts +66 -0
- package/dist/invitations/expect-welcome.js +138 -0
- package/dist/invitations/index.d.ts +18 -0
- package/dist/invitations/index.js +18 -0
- package/dist/invitations/invitation-outcome.d.ts +110 -0
- package/dist/invitations/invitation-outcome.js +210 -0
- package/dist/invitations/invite.d.ts +358 -0
- package/dist/invitations/invite.js +1102 -0
- package/dist/invitations/offers.d.ts +79 -0
- package/dist/invitations/offers.js +115 -0
- package/dist/invitations/on-proposal.d.ts +47 -0
- package/dist/invitations/on-proposal.js +40 -0
- package/dist/invitations/pending-proposal-policy.d.ts +52 -0
- package/dist/invitations/pending-proposal-policy.js +139 -0
- package/dist/invitations/proposal-deadline.d.ts +133 -0
- package/dist/invitations/proposal-deadline.js +164 -0
- package/dist/invitations/relay-planes.d.ts +43 -0
- package/dist/invitations/relay-planes.js +70 -0
- package/dist/invitations/welcome-processor.d.ts +272 -0
- package/dist/invitations/welcome-processor.js +1241 -0
- package/dist/key-packages/device-key.d.ts +131 -0
- package/dist/key-packages/device-key.js +272 -0
- package/dist/key-packages/device-rotation-records.d.ts +83 -0
- package/dist/key-packages/device-rotation-records.js +173 -0
- package/dist/key-packages/group-refs.d.ts +40 -0
- package/dist/key-packages/group-refs.js +79 -0
- package/dist/key-packages/index.d.ts +18 -0
- package/dist/key-packages/index.js +18 -0
- package/dist/key-packages/key-package-ref.d.ts +16 -0
- package/dist/key-packages/key-package-ref.js +21 -0
- package/dist/key-packages/observation-stream.d.ts +4 -0
- package/dist/key-packages/observation-stream.js +120 -0
- package/dist/key-packages/offer-rumor.d.ts +26 -0
- package/dist/key-packages/offer-rumor.js +69 -0
- package/dist/key-packages/publisher.d.ts +174 -0
- package/dist/key-packages/publisher.js +1247 -0
- package/dist/key-packages/select-key-package.d.ts +24 -0
- package/dist/key-packages/select-key-package.js +90 -0
- package/dist/key-packages/slot-manager.d.ts +167 -0
- package/dist/key-packages/slot-manager.js +327 -0
- package/dist/key-packages/validate-key-package-event.d.ts +3 -0
- package/dist/key-packages/validate-key-package-event.js +49 -0
- package/dist/media/cache.d.ts +14 -0
- package/dist/media/cache.js +10 -0
- package/dist/media/index.d.ts +52 -0
- package/dist/media/index.js +71 -0
- package/dist/mls.d.ts +15 -0
- package/dist/mls.js +15 -0
- package/dist/shared/account-pubkey.d.ts +4 -0
- package/dist/shared/account-pubkey.js +10 -0
- package/dist/shared/errors.d.ts +28 -0
- package/dist/shared/errors.js +96 -0
- package/dist/shared/hex.d.ts +4 -0
- package/dist/shared/hex.js +13 -0
- package/dist/shared/index.d.ts +14 -0
- package/dist/shared/index.js +14 -0
- package/dist/shared/kinds.d.ts +8 -0
- package/dist/shared/kinds.js +28 -0
- package/dist/shared/publish-classification.d.ts +26 -0
- package/dist/shared/publish-classification.js +31 -0
- package/dist/storage/envelope.d.ts +39 -0
- package/dist/storage/envelope.js +201 -0
- package/dist/storage/index.d.ts +237 -0
- package/dist/storage/index.js +491 -0
- package/dist/storage/indexeddb/idb-types.d.ts +68 -0
- package/dist/storage/indexeddb/idb-types.js +1 -0
- package/dist/storage/indexeddb/index.d.ts +17 -0
- package/dist/storage/indexeddb/index.js +141 -0
- package/dist/storage/lease.d.ts +54 -0
- package/dist/storage/lease.js +168 -0
- package/dist/storage/memory/deterministic-signer.d.ts +27 -0
- package/dist/storage/memory/deterministic-signer.js +65 -0
- package/dist/storage/memory/index.d.ts +32 -0
- package/dist/storage/memory/index.js +87 -0
- package/dist/storage/memory/lock-manager.d.ts +8 -0
- package/dist/storage/memory/lock-manager.js +71 -0
- package/package.json +66 -3
|
@@ -0,0 +1,1126 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `createMarmotClient` and the typed client surface (docs/client-api.md).
|
|
3
|
+
*
|
|
4
|
+
* Construction is synchronous and side-effect free towards the consumer's
|
|
5
|
+
* collaborators: it validates options, wraps the account signer with
|
|
6
|
+
* `nostr-events`' `withSignerBudget` (AC-API-5, ADR-009) and narrows the
|
|
7
|
+
* transport to the three `TransportContract` members (AC-API-4). It never
|
|
8
|
+
* calls the signer or the transport.
|
|
9
|
+
*
|
|
10
|
+
* No member is a stub: AC-FIX-6 (S11) sweeps the built package and fails on
|
|
11
|
+
* any `not-implemented` MarmotError.
|
|
12
|
+
*/
|
|
13
|
+
import type { MarmotGroupEngineOptions } from '@941design/marmot-engine/engine';
|
|
14
|
+
import type { NostrEvent, Rumor } from '@941design/nostr-events/event';
|
|
15
|
+
import { type Signer } from '@941design/nostr-events/signer';
|
|
16
|
+
import { type BudgetPolicy } from '@941design/nostr-events/signer/budget';
|
|
17
|
+
import type { PermissionDeclaration } from '@941design/nostr-events/signer/permissions';
|
|
18
|
+
import type { TransportContract } from '@941design/nostr-events/transport/contract';
|
|
19
|
+
import type { AppliedNotification, GroupNotification, HistoryBackend, LeafEquivocationNotification, OrderingKey } from '../history/index.js';
|
|
20
|
+
import type { EncryptedMedia, EncryptMediaOptions, MediaCache } from '../media/index.js';
|
|
21
|
+
import { type DeviceForgetOutcome, type DeviceInfo, type DeviceKeyRotationOutcome, type DeviceLineage, type DeviceMaintenanceKind, type EnrolmentApprovalOutcome, type EnrolmentPrompt, type EnrolmentRequestHandle, type EnrolmentRequestOptions } from '../account/index.js';
|
|
22
|
+
import { type InboxDisposition, type InboxRumorHandler } from '../inbox/index.js';
|
|
23
|
+
import { type KeyPackageOffer, type MaintenanceKind, type InvitationOutcome, type CleanupReference, type DeclineCandidate, type DeclineCandidatePage, type PendingInvitation, type ProposalCallback, type WelcomeOutcome } from '../invitations/index.js';
|
|
24
|
+
import { MarmotError } from '../shared/index.js';
|
|
25
|
+
import type { AccountStore, GroupStore, GroupStoreTx } from '../storage/index.js';
|
|
26
|
+
import { type BeforeCreateGroupGates, type CreateGroupGate } from './before-create-group.js';
|
|
27
|
+
import { type BeforePublishHook, type BeforePublishRegistry, type BeforePublishSkipped } from './before-publish-hooks.js';
|
|
28
|
+
import { type GroupRegistry, type GroupRuntime } from './group-runtime.js';
|
|
29
|
+
import type { AvailabilityObservation } from './group-availability.js';
|
|
30
|
+
import type { GroupSnapshot } from './group-snapshot.js';
|
|
31
|
+
import { type InboxRumorDelivery } from './inbox-send.js';
|
|
32
|
+
import { type LifecycleEventPayloads, type LifecycleEvents } from './lifecycle-events.js';
|
|
33
|
+
import { type EngineSeamsOverride } from './client-config.js';
|
|
34
|
+
import { type CleanupDispositionReport } from './admission-cleanup.js';
|
|
35
|
+
/** Consumer-supplied check run on every relay event before it is trusted (ADR-008). */
|
|
36
|
+
export type EventVerifier = (event: NostrEvent) => boolean | Promise<boolean>;
|
|
37
|
+
/**
|
|
38
|
+
* The consumer's ADR-007 stores — `{ account, groupFactory }` of a
|
|
39
|
+
* `WritableStores` (`@941design/marmot/storage`), opened under the lease.
|
|
40
|
+
*/
|
|
41
|
+
export interface ClientStores {
|
|
42
|
+
readonly account: AccountStore;
|
|
43
|
+
groupFactory(groupId: string): GroupStore;
|
|
44
|
+
}
|
|
45
|
+
/** Relay policy: `discover` resolves inbox relays via 10050/10002; `fixed` is single-relay mode. */
|
|
46
|
+
export interface RelayOptions {
|
|
47
|
+
readonly defaults: readonly string[];
|
|
48
|
+
readonly mode: 'discover' | 'fixed';
|
|
49
|
+
}
|
|
50
|
+
/** Injectable millisecond clock (grace window, deadlines, rate limits). */
|
|
51
|
+
export interface ClientClock {
|
|
52
|
+
now(): number;
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* Injectable scheduler for the client's deferred work: confirmation and
|
|
56
|
+
* publish retries, history re-requests and the engine's convergence
|
|
57
|
+
* settle-check. Defaults to `setTimeout` / `clearTimeout`.
|
|
58
|
+
*/
|
|
59
|
+
export interface ClientTimers {
|
|
60
|
+
set(callback: () => void, ms: number): unknown;
|
|
61
|
+
clear(handle: unknown): void;
|
|
62
|
+
}
|
|
63
|
+
export interface ClientOptions {
|
|
64
|
+
/** Defaults to `Date.now`. */
|
|
65
|
+
readonly clock?: ClientClock;
|
|
66
|
+
/** Consecutive history timeouts before a relay is excluded from history requests (AC-PIPE-14). Default 3. */
|
|
67
|
+
readonly historySilenceThreshold?: number;
|
|
68
|
+
/** KeyPackage `init_key` retention after consumption (AC-KP-3). Default 24 h. */
|
|
69
|
+
readonly graceWindowMs?: number;
|
|
70
|
+
/** Scheduler for retries and deferred work. Defaults to `setTimeout` / `clearTimeout`. */
|
|
71
|
+
readonly timers?: ClientTimers;
|
|
72
|
+
/** Deadline of each kind-445 history `requestWithDeadline` (AC-PIPE-7). Default 10 s. */
|
|
73
|
+
readonly historyTimeoutMs?: number;
|
|
74
|
+
/** Failed publishes after which a retryable intent goes terminal (`send-rejected` / `intentFailed`). Default 20. */
|
|
75
|
+
readonly maxPublishAttempts?: number;
|
|
76
|
+
/**
|
|
77
|
+
* AC-BAR-2: the one deadline (ms) under which an own commit's `onBeforePublish` barriers are awaited before its first
|
|
78
|
+
* publish. A barrier still pending at the deadline is abandoned (its signal aborts), the commit is published anyway
|
|
79
|
+
* and `beforePublishSkipped { reason: 'barrier-timeout' }` fires. An integer >= 1; default 10 000.
|
|
80
|
+
*/
|
|
81
|
+
readonly beforePublishTimeoutMs?: number;
|
|
82
|
+
/** Most kind-1059 wrap ids the persisted inbox seen-set keeps; the oldest are evicted first (AC-INBOX-4). Default 10 000. */
|
|
83
|
+
readonly seenSetCap?: number;
|
|
84
|
+
/**
|
|
85
|
+
* Most distinct enrolment requests one session id may have prompted within
|
|
86
|
+
* a minute; the rest are dropped silently (AC-DEV-5). Default 3.
|
|
87
|
+
*/
|
|
88
|
+
readonly enrolmentPromptRateLimit?: number;
|
|
89
|
+
/**
|
|
90
|
+
* Relay event-size budget (bytes of event JSON) of the gift wrap an own enrolment request is sent in:
|
|
91
|
+
* `devices.requestEnrolment` refuses a request whose wrap could exceed it (`invalid-options`,
|
|
92
|
+
* `details.reason: 'request-too-large'`, with `wrapBytes`) before anything is minted. A positive safe
|
|
93
|
+
* integer; default 65 536 (64 KiB, a common relay cap).
|
|
94
|
+
*/
|
|
95
|
+
readonly maxGiftWrapBytes?: number;
|
|
96
|
+
/**
|
|
97
|
+
* How long `group.leave()` (and each group of `devices.forget(ownLeafKey)`)
|
|
98
|
+
* waits for a peer's confirmed commit of the local leaf's SelfRemove before
|
|
99
|
+
* purging the group anyway (AC-ADMIN-6). Client-clock milliseconds; default 60 000.
|
|
100
|
+
*/
|
|
101
|
+
readonly leaveTimeoutMs?: number;
|
|
102
|
+
/**
|
|
103
|
+
* How long a proposal `onProposal` deferred stays deferred (AC-INVITE-4).
|
|
104
|
+
* Client-clock milliseconds from its first `defer`; default 86 400 000
|
|
105
|
+
* (24 h); `0` = never expires. The deadline is persisted with the deferral
|
|
106
|
+
* (no timer) and checked on every own-commit attempt, on group load, on
|
|
107
|
+
* each history pass of the group and on each inbox pass — never while the
|
|
108
|
+
* group is not caught up (no complete sync since load or since its live
|
|
109
|
+
* subscription last ended). `Infinity` also means never. Once it passed,
|
|
110
|
+
* the proposal is treated as `reject` (never auto-accepted) and
|
|
111
|
+
* `proposalExpired` fires.
|
|
112
|
+
*/
|
|
113
|
+
readonly proposalDeferralTimeoutMs?: number;
|
|
114
|
+
/**
|
|
115
|
+
* S20 (AC-ADMIN-6/-10): how long a removal of the local leaf stays revisable after the group's own state first
|
|
116
|
+
* shows it — a same-epoch sibling commit arriving inside it rewinds the removal (the device stays a member; a
|
|
117
|
+
* `leave()` resumes as a member) — before it settles: later input is then `self-evicted`, and a `leave()` /
|
|
118
|
+
* own-leaf `devices.forget` waiting on the removal performs `abandon()`. Client-clock milliseconds, a finite
|
|
119
|
+
* integer >= 0; default 10 000. `0` settles at the removal (the pre-S20 timing) — an opt-out that accepts the
|
|
120
|
+
* zombie leave: a device removed only on the losing branch of a race purges while the group still holds its
|
|
121
|
+
* leaf. No upper bound: values above `leaveTimeoutMs` only lengthen the post-removal wait, never the
|
|
122
|
+
* pre-removal one.
|
|
123
|
+
*/
|
|
124
|
+
readonly removalSettleMs?: number;
|
|
125
|
+
/**
|
|
126
|
+
* S5 (AC-RACE-2): how long `advanceQueue` and `invite()`'s proposal policy wait for the elected member's
|
|
127
|
+
* confirmed commit before an admin's own `send()`/`invite()` commits a staged SelfRemove-only batch another
|
|
128
|
+
* member is elected to commit (`decideAutoCommit`/`electionAtRest`, client/pipeline.ts) itself. Client-clock
|
|
129
|
+
* milliseconds, a finite integer >= 0; default 5000 (well under `leaveTimeoutMs`'s default 60000). `0` commits
|
|
130
|
+
* at once (the pre-S5 timing): an opt-out that accepts pre-empting the elected committer.
|
|
131
|
+
*/
|
|
132
|
+
readonly selfRemoveElectionWaitMs?: number;
|
|
133
|
+
/**
|
|
134
|
+
* S7 (AC-HYG-2): how long an invite's account record is kept once every one of its Welcome deliveries is
|
|
135
|
+
* `delivered` or `declined` — client-clock milliseconds after its last delivery settled. Until then
|
|
136
|
+
* `retryWelcome` can re-send a delivered Welcome and an invitee's decline is matched to it (`welcomeDeclined`);
|
|
137
|
+
* after it the record is deleted the next time the group is loaded, invited to, retried or declined in. A record
|
|
138
|
+
* with a pending, retryable or failed delivery is never deleted by age. A safe integer >= 0; default 30 days.
|
|
139
|
+
*/
|
|
140
|
+
readonly inviteRetentionMs?: number;
|
|
141
|
+
/**
|
|
142
|
+
* inbox-handler-time-budget: how long an inbox consumer callback (a `registerInboxHandler` handler or
|
|
143
|
+
* `onApplicationRumor`) may run before `handlerSlow` reports it — a diagnostic only: the handler is never detached
|
|
144
|
+
* and the inbox queue still waits for it (the "handlers must not await long work" contract stands). Client-clock
|
|
145
|
+
* milliseconds, a safe integer >= 0; default 30 000; `0` never reports.
|
|
146
|
+
*/
|
|
147
|
+
readonly inboxHandlerBudgetMs?: number;
|
|
148
|
+
/**
|
|
149
|
+
* S8 (AC-RATCH-1): how many generations the own application sender ratchet skips at the first own application
|
|
150
|
+
* message of a group after it is loaded from storage (encrypted once its first post-load sync opened the send
|
|
151
|
+
* gate). The loaded state may be a restored snapshot that never saw own messages sent after it, held only by a
|
|
152
|
+
* relay the first sync excluded as silent: skipping keeps the next message from re-using one of their
|
|
153
|
+
* generations (same key and nonce; members that read the earlier one refuse it). A safe integer in [32, 100];
|
|
154
|
+
* default 64. The skip is applied with that first message only — never persisted without it — so repeated loads
|
|
155
|
+
* with no send do not accumulate; and until a relay accepted an own application message at or after a recorded
|
|
156
|
+
* skip, a load of that same epoch state does not skip again (group-records.ts `ratchetSkipArmed`), so restarts whose
|
|
157
|
+
* first message is refused everywhere keep the gap within one margin plus the undelivered messages. Own messages
|
|
158
|
+
* the first post-load sync reads back from relays floor the skip (ingesting them advances the own ratchet), and one
|
|
159
|
+
* at or after an undelivered recorded skip marks it delivered and re-arms the skip (BACKLOG
|
|
160
|
+
* ratchet-skip-relay-derived-floor). Skips add up
|
|
161
|
+
* otherwise only for a member that misses messages: one that missed every own
|
|
162
|
+
* message of n load cycles in one epoch reads the next one while n × (margin + messages per cycle) + margin stays
|
|
163
|
+
* within the receivers' forward window (ts-mls `maximumForwardRatchetSteps`, 200); the upper bound (half of it)
|
|
164
|
+
* keeps any single skip, plus fewer than a margin of own messages a member did not receive, inside it. Own
|
|
165
|
+
* messages a restored snapshot can miss must stay fewer than the margin.
|
|
166
|
+
*/
|
|
167
|
+
readonly ratchetSkipMargin?: number;
|
|
168
|
+
}
|
|
169
|
+
export interface MarmotClientOptions {
|
|
170
|
+
/** Account-key signer; the client wraps it with `withSignerBudget(signer, budget)`. */
|
|
171
|
+
readonly signer: Signer;
|
|
172
|
+
/** `nostr-events` budget policy; `{ policy: 'none' }` is the explicit opt-out. Required. */
|
|
173
|
+
readonly budget: BudgetPolicy;
|
|
174
|
+
/** The only transport dependency (AC-API-4). */
|
|
175
|
+
readonly transport: TransportContract;
|
|
176
|
+
readonly stores: ClientStores;
|
|
177
|
+
readonly relays: RelayOptions;
|
|
178
|
+
readonly verifier?: EventVerifier;
|
|
179
|
+
/**
|
|
180
|
+
* The application's decision on a staged proposal another member sent,
|
|
181
|
+
* asked before this client builds a commit carrying it (AC-INVITE-4).
|
|
182
|
+
* Omitted: a non-admin member's Add or Remove is rejected, every other
|
|
183
|
+
* proposal accepted. A `defer` lasts at most
|
|
184
|
+
* `options.proposalDeferralTimeoutMs` (then `reject`, `proposalExpired`).
|
|
185
|
+
*/
|
|
186
|
+
readonly onProposal?: ProposalCallback;
|
|
187
|
+
/**
|
|
188
|
+
* Receives every inbox rumor `marmot` does not handle itself and no
|
|
189
|
+
* `registerInboxHandler` handler claimed — unmodified (AC-INBOX-2). Same
|
|
190
|
+
* delivery contract as an {@link InboxHandler}: at-least-once, so it MUST
|
|
191
|
+
* tolerate redelivery. Omitted: such rumors are dropped (`unhandled`).
|
|
192
|
+
*
|
|
193
|
+
* Handlers run on the inbox queue and block all inbox dispatch until they
|
|
194
|
+
* settle: do not await `group.send` or other long work — persist what you
|
|
195
|
+
* need and return, or fire-and-forget. Delivery is at-least-once; a throw
|
|
196
|
+
* counts toward the 10-retry cap and each retry re-decrypts the wrap.
|
|
197
|
+
*/
|
|
198
|
+
readonly onApplicationRumor?: InboxHandler;
|
|
199
|
+
/**
|
|
200
|
+
* S10 (AC-HIST-3): the rumor history backend — where accepted application messages are retained for
|
|
201
|
+
* `group.history()`, withdrawn on a rewind and purged on teardown. Optional: live delivery
|
|
202
|
+
* (`group.onNotification`) never depends on it.
|
|
203
|
+
*/
|
|
204
|
+
readonly history?: HistoryBackend;
|
|
205
|
+
/** S10 (AC-MEDIA-2): the media cache seam `encryptMedia`/`decryptMedia` keep ciphertexts in (no network, ever). */
|
|
206
|
+
readonly mediaCache?: MediaCache;
|
|
207
|
+
readonly options?: ClientOptions;
|
|
208
|
+
}
|
|
209
|
+
export interface MarmotClientEvents {
|
|
210
|
+
/** AC-INBOX-6: fires after the enrolment-approval transaction commits. */
|
|
211
|
+
enrolmentApproved: LifecycleEventPayloads['enrolmentApproved'];
|
|
212
|
+
/** AC-INBOX-6: fires after the forget transaction commits. */
|
|
213
|
+
deviceForgotten: LifecycleEventPayloads['deviceForgotten'];
|
|
214
|
+
/** AC-INBOX-6: fires after the created group's state and account index entry committed. */
|
|
215
|
+
groupCreated: LifecycleEventPayloads['groupCreated'];
|
|
216
|
+
/**
|
|
217
|
+
* A peer removed this device from the group and the removal settled (no longer revisable) — `{ groupId, actor? }`,
|
|
218
|
+
* `actor` the hex account identity of the admin whose removing commit was selected (as `group-disbanded` names it);
|
|
219
|
+
* absent when the committer cannot be resolved. The group and its history stay held, read-only; the application decides whether to `abandon()` it. Not fired for a
|
|
220
|
+
* removal this device requested (`leave()`, an own-leaf `devices.forget`, a teardown in progress or given up). At
|
|
221
|
+
* most once: a crash between the settle and the emit loses it (do not depend on it for correctness). A removal whose
|
|
222
|
+
* window passed while the client was not running is announced when the group is first loaded after the restart, so
|
|
223
|
+
* attach the listener before loading groups. A fenced group still announces its settled removal.
|
|
224
|
+
*/
|
|
225
|
+
groupRemoved: {
|
|
226
|
+
readonly groupId: string;
|
|
227
|
+
readonly actor?: string;
|
|
228
|
+
};
|
|
229
|
+
/**
|
|
230
|
+
* Epic marmot-device-key-rotation (S7, AC-ROT-8): `devices.rotateKey()` committed its prepare transaction — `{ rotationId, from,
|
|
231
|
+
* to, groups }`. Fires once per rotation, never for a failed prepare, at most once across a crash (a crash between the commit
|
|
232
|
+
* and the emit loses it: do not depend on it for correctness).
|
|
233
|
+
*/
|
|
234
|
+
deviceKeyRotated: LifecycleEventPayloads['deviceKeyRotated'];
|
|
235
|
+
/** Epic marmot-device-key-rotation (S7, AC-ROT-8): every group of the rotation is terminal — `{ rotationId, perGroupOutcome }`; fires once. */
|
|
236
|
+
deviceKeyRotationSettled: LifecycleEventPayloads['deviceKeyRotationSettled'];
|
|
237
|
+
/**
|
|
238
|
+
* S8 (AC-DEV-5, AC-DEV-9): an enrolment request of a new device of this
|
|
239
|
+
* account passed the replay, expiry and rate checks and is recorded — the
|
|
240
|
+
* approval prompt. Answer with `devices.approveEnrolment(requestId)`;
|
|
241
|
+
* `devices.pendingEnrolments()` lists the open ones.
|
|
242
|
+
*/
|
|
243
|
+
enrolmentRequested: EnrolmentPrompt;
|
|
244
|
+
/** S8 (AC-KP-7): another account offered a KeyPackage for a group this client holds (recorded; see `invitations.offers()`). */
|
|
245
|
+
keyPackageOffered: KeyPackageOffer;
|
|
246
|
+
authFailed: {
|
|
247
|
+
readonly relayUrl: string;
|
|
248
|
+
readonly error: unknown;
|
|
249
|
+
};
|
|
250
|
+
/**
|
|
251
|
+
* marmot-transport-connected-signal: the transport adapter reported a (re)connect to `relayUrl` through
|
|
252
|
+
* `transportEvents.connected` — the raw relay string as reported (ADR-014). How an extension such as
|
|
253
|
+
* `account-sync` learns of reconnects without its own wiring into the adapter.
|
|
254
|
+
*/
|
|
255
|
+
transportConnected: {
|
|
256
|
+
readonly relayUrl: string;
|
|
257
|
+
};
|
|
258
|
+
confirmBlocked: {
|
|
259
|
+
readonly groupId: string;
|
|
260
|
+
readonly intentId: string;
|
|
261
|
+
readonly error: unknown;
|
|
262
|
+
};
|
|
263
|
+
/**
|
|
264
|
+
* AC-HOOK-6, AC-BAR-2: an own commit was published although an `onBeforePublish` hook threw (`hook-error`), a
|
|
265
|
+
* barrier rejected (`barrier-failed`, with the `error`) or the `beforePublishTimeoutMs` deadline passed with a
|
|
266
|
+
* barrier pending (`barrier-timeout`). Best-effort by decision: the commit is never held back by a hook.
|
|
267
|
+
*/
|
|
268
|
+
beforePublishSkipped: BeforePublishSkipped;
|
|
269
|
+
/**
|
|
270
|
+
* A relay is excluded from this group's history requests for the session
|
|
271
|
+
* (AC-PIPE-14): `timeout` — it caused `historySilenceThreshold` consecutive
|
|
272
|
+
* history timeouts; `no-progress` — for that many consecutive passes it
|
|
273
|
+
* answered, but with nothing inside the requested window (e.g. it ignores
|
|
274
|
+
* `until`), so the history walk could not advance past it.
|
|
275
|
+
*/
|
|
276
|
+
relaySilent: {
|
|
277
|
+
readonly groupId: string;
|
|
278
|
+
readonly relayUrl: string;
|
|
279
|
+
readonly reason: 'timeout' | 'no-progress';
|
|
280
|
+
};
|
|
281
|
+
/**
|
|
282
|
+
* A relay returned a full page of history events all stamped with one
|
|
283
|
+
* second and then proved to hold more: events of that second beyond its
|
|
284
|
+
* cap cannot be paged to (NIP-01 `until` has one-second resolution) and
|
|
285
|
+
* may never be fetched from it. Fires once per relay and second per session.
|
|
286
|
+
*/
|
|
287
|
+
historyGap: {
|
|
288
|
+
readonly groupId: string;
|
|
289
|
+
readonly relayUrl: string;
|
|
290
|
+
readonly createdAt: number;
|
|
291
|
+
};
|
|
292
|
+
storeIncompatible: {
|
|
293
|
+
readonly key: string;
|
|
294
|
+
readonly error: MarmotError;
|
|
295
|
+
};
|
|
296
|
+
/**
|
|
297
|
+
* A durable intent went `terminal` with no `send()` caller left to reject: resumed after reload (AC-PIPE-3), or
|
|
298
|
+
* accepted `awaiting-sync` and then fenced (`fenced`) or refused after its release (AC-PIPE-15).
|
|
299
|
+
*/
|
|
300
|
+
intentFailed: {
|
|
301
|
+
readonly groupId: string;
|
|
302
|
+
readonly intentId: string;
|
|
303
|
+
readonly error: MarmotError;
|
|
304
|
+
};
|
|
305
|
+
/**
|
|
306
|
+
* A failed group operation could not roll the group's in-memory state back
|
|
307
|
+
* (`store-failed`, `cause` = the rollback failure); the group reloads its
|
|
308
|
+
* durable state before its next operation.
|
|
309
|
+
*/
|
|
310
|
+
groupStateFailed: {
|
|
311
|
+
readonly groupId: string;
|
|
312
|
+
readonly error: MarmotError;
|
|
313
|
+
};
|
|
314
|
+
/**
|
|
315
|
+
* A Welcome delivery went `failed` (no inbox relay, every relay refused it,
|
|
316
|
+
* or `maxPublishAttempts` publishes failed); `group.retryWelcome(inviteeRef)`
|
|
317
|
+
* re-delivers it (S5). Reasons from a rewind: `commit-withdrawn` (the invite commit lost a race; the Welcome was not yet published) and
|
|
318
|
+
* `delivered-on-abandoned-branch` (additive, epic marmot-rewound-own-commit-no-signal S4: the Welcome WAS delivered, its invite
|
|
319
|
+
* commit was abandoned and NOTHING re-delivers it automatically -- fired only (a) for an invite re-drive's commit whose root a restore of the
|
|
320
|
+
* original just brought back (the invitee holds the re-drive's branch, which the group left), and (b) for an own invite whose withdrawal writes no
|
|
321
|
+
* re-drive record (unreadable diff, or a marker without changes). Decided once, in the abandoning transition: when a re-drive that was written
|
|
322
|
+
* later loses the change, the application hears `own-change-lost` `{ member-added }` with its reason instead, not this. Never when the library
|
|
323
|
+
* re-drives the invite (the new Welcome can move the invitee), for an enrolment approval it re-issues, or for a forget. `retryWelcome` on such a
|
|
324
|
+
* delivery is refused (`send-rejected`, `details.reason: 'abandoned-branch'`). The invitee may sit on a branch the group left: remove it and invite it again with a
|
|
325
|
+
* fresh KeyPackage; `retryWelcome` does not apply, nothing failed to publish).
|
|
326
|
+
*/
|
|
327
|
+
welcomeFailed: {
|
|
328
|
+
readonly groupId: string;
|
|
329
|
+
readonly inviteeRef: string;
|
|
330
|
+
readonly reason: string;
|
|
331
|
+
};
|
|
332
|
+
/**
|
|
333
|
+
* A Welcome delivery that a rewind had failed (`welcomeFailed` with reason `commit-withdrawn`) was put back to
|
|
334
|
+
* `pending` because its invite commit is on the canonical path again; it is delivered in the background.
|
|
335
|
+
*/
|
|
336
|
+
welcomeRestored: {
|
|
337
|
+
readonly groupId: string;
|
|
338
|
+
readonly inviteeRef: string;
|
|
339
|
+
};
|
|
340
|
+
/**
|
|
341
|
+
* Reconciling the group's undelivered invite Welcomes with a rewind (or with the stored window on load) failed;
|
|
342
|
+
* the deliveries are left as they were and the next load tries again.
|
|
343
|
+
*/
|
|
344
|
+
welcomeReconcileFailed: {
|
|
345
|
+
readonly groupId: string;
|
|
346
|
+
readonly error: unknown;
|
|
347
|
+
};
|
|
348
|
+
/**
|
|
349
|
+
* S7 (AC-HYG-3): the invitee of a Welcome delivery declined it — a DECLINE rumor sealed by the delivery's
|
|
350
|
+
* invitee account, naming that Welcome's id (SHA-256 of the MLS Welcome) and group. Fires once per delivery,
|
|
351
|
+
* after it went `declined` durably (terminal: no further automatic or `retryWelcome` publish); a redelivered or
|
|
352
|
+
* repeated decline does not fire it again, nor does a decline from any other account. The rumor itself still
|
|
353
|
+
* reaches `onApplicationRumor` unchanged. `candidateId` (epic marmot-invitation-outcomes S3) is the delivery's
|
|
354
|
+
* stable candidate identity, the one `declineCandidate` and `invitations.declineCandidates()` carry. A decline
|
|
355
|
+
* whose `keyPackageRef` selects one delivery declines only that one; delivery status `declined` confers no cleanup
|
|
356
|
+
* authority — only the candidate's disposition does.
|
|
357
|
+
*/
|
|
358
|
+
welcomeDeclined: {
|
|
359
|
+
readonly groupId: string;
|
|
360
|
+
readonly inviteeRef: string;
|
|
361
|
+
readonly candidateId: string;
|
|
362
|
+
};
|
|
363
|
+
/**
|
|
364
|
+
* Epic marmot-invitation-outcomes S3 (SC-13): the decline evidence of one locally issued delivery changed — a new
|
|
365
|
+
* candidate (`ambiguous` or `actionable`), a late match after the delivery's record left retention, or a
|
|
366
|
+
* refinement (a selector naming it after an ambiguous decline: `actionable`, `qualified`, a higher `rev`, the same
|
|
367
|
+
* `cleanupRef`). Fires after the evidence was written durably, at most once per `(candidateId, rev)`; a crash in
|
|
368
|
+
* between loses it — `invitations.declineCandidates()` recovers every candidate. Subscribe before scanning and
|
|
369
|
+
* deduplicate by `(candidateId, rev)`.
|
|
370
|
+
*/
|
|
371
|
+
declineCandidate: DeclineCandidate;
|
|
372
|
+
/**
|
|
373
|
+
* Epic marmot-invitation-outcomes S5 (SC-12): the cleanup disposition of a candidate this session submitted, confirmed or saw
|
|
374
|
+
* withdrawn changed — `pending` once `removeAdmission` recorded it, `removed-revisable` once its own inline Remove confirmed,
|
|
375
|
+
* `removed-settled`, or back to `eligible` / `absent` when a rewind or a lost re-drive undid it. Best effort, after the change is
|
|
376
|
+
* durable: a crash, a restart or a listener added late can miss one — `invitations.cleanupDisposition(ref)` recovers the latest.
|
|
377
|
+
*/
|
|
378
|
+
cleanupDisposition: CleanupDispositionReport;
|
|
379
|
+
/**
|
|
380
|
+
* What the inbox did with one inbound kind-1059 wrap (S6): `joined`,
|
|
381
|
+
* `already-member`, `pending` (an unexpected Welcome, see
|
|
382
|
+
* `invitations.pending()`), `no-matching-keypackage`, `rejected` (terminal,
|
|
383
|
+
* with `reason`), `deferred` (retried by the next inbox pass; a throwing
|
|
384
|
+
* handler's `handler-failed` counts toward the processing-failure cap),
|
|
385
|
+
* `delivered` (S7: a `registerInboxHandler` handler or `onApplicationRumor`
|
|
386
|
+
* took it, `to` saying which) or `unhandled` (nothing takes that rumor
|
|
387
|
+
* kind). A wrap already in the seen-set produces none.
|
|
388
|
+
*/
|
|
389
|
+
inboxDisposition: InboxDisposition;
|
|
390
|
+
/**
|
|
391
|
+
* inbox-handler-time-budget: an inbox consumer callback (`surface`: a `registerInboxHandler` handler or
|
|
392
|
+
* `onApplicationRumor`) is still running `budgetMs` (`inboxHandlerBudgetMs`) after it was called for the rumor of
|
|
393
|
+
* `wrapId`. Diagnostic only — the handler keeps running and the inbox queue (Welcomes included) keeps waiting for
|
|
394
|
+
* it; fires at most once per call.
|
|
395
|
+
*/
|
|
396
|
+
handlerSlow: {
|
|
397
|
+
readonly surface: 'inboxHandler' | 'onApplicationRumor';
|
|
398
|
+
readonly rumorKind: number;
|
|
399
|
+
readonly wrapId: string;
|
|
400
|
+
readonly budgetMs: number;
|
|
401
|
+
};
|
|
402
|
+
/**
|
|
403
|
+
* A proposal `onProposal` deferred passed its deadline
|
|
404
|
+
* (`proposalDeferralTimeoutMs` after `deferredAt`, its first deferral, in
|
|
405
|
+
* client-clock ms) and was treated as `reject`: dropped from the staged set
|
|
406
|
+
* (durably, before this fires), so own commits are no longer refused
|
|
407
|
+
* `proposal-deferred` and queued rumors go out after the next commit
|
|
408
|
+
* (AC-INVITE-4). Once per proposal; a crash between the drop and the emit
|
|
409
|
+
* still emits it (on the next evaluation, at the latest the reload), and a
|
|
410
|
+
* crash right after the emit may emit it once more with the same payload —
|
|
411
|
+
* deduplicate by `(groupId, proposalRef)`.
|
|
412
|
+
*/
|
|
413
|
+
proposalExpired: {
|
|
414
|
+
readonly groupId: string;
|
|
415
|
+
readonly proposalRef: string;
|
|
416
|
+
readonly deferredAt: number;
|
|
417
|
+
};
|
|
418
|
+
/** A Welcome was joined (inbox auto-accept under `expectWelcome`, `accept(id)`), after the join committed. */
|
|
419
|
+
groupJoined: {
|
|
420
|
+
readonly groupId: string;
|
|
421
|
+
readonly invitationId: string;
|
|
422
|
+
};
|
|
423
|
+
/**
|
|
424
|
+
* A competing Welcome moved a group this client already held onto its branch (epic `marmot-welcome-race-joiner`):
|
|
425
|
+
* a second valid Welcome for the group named a branch the MIP-03 rule ranks above the held one, so the group was
|
|
426
|
+
* rebased onto it. `from` and `to` are the hex confirmation tags of the abandoned tip and of the Welcome's state;
|
|
427
|
+
* `invitationId` is the competing Welcome's. What the abandoned branch applied is withdrawn (`withdrawn`,
|
|
428
|
+
* `message-withdrawn` notifications) — messages sent on it are NOT re-sent; the application re-sends them. Fires
|
|
429
|
+
* once per switch (a crash between this report and the invitation's confirmation reports it again on the next pass:
|
|
430
|
+
* deduplicate by `invitationId`), also when the switch was decided in an inbox pass with no wrap in hand (the inbox
|
|
431
|
+
* disposition `branch-switched` is reported only when the switch ran inside a Welcome's dispatch); `groupJoined`
|
|
432
|
+
* does not fire again.
|
|
433
|
+
*/
|
|
434
|
+
groupBranchSwitched: {
|
|
435
|
+
readonly invitationId: string;
|
|
436
|
+
readonly groupId: string;
|
|
437
|
+
readonly from: string;
|
|
438
|
+
readonly to: string;
|
|
439
|
+
};
|
|
440
|
+
/**
|
|
441
|
+
* An invitation's maintenance — rotate-after-consume of the consumed
|
|
442
|
+
* KeyPackage, the decline rumor's delivery, or completing an interrupted
|
|
443
|
+
* join — failed permanently 10 times (the signer or user refused, a
|
|
444
|
+
* malformed record) and is given up: no further retries or signer prompts.
|
|
445
|
+
*/
|
|
446
|
+
maintenanceFailed: {
|
|
447
|
+
readonly invitationId: string;
|
|
448
|
+
readonly kind: MaintenanceKind | DeviceMaintenanceKind;
|
|
449
|
+
readonly reason: string;
|
|
450
|
+
/** `enrolment-approval` only: the groups the device joined before the approval was given up (enrolmentApproved names them too). */
|
|
451
|
+
readonly groups?: readonly string[];
|
|
452
|
+
};
|
|
453
|
+
}
|
|
454
|
+
export type MarmotClientEventName = keyof MarmotClientEvents;
|
|
455
|
+
/** What `group.send()` accepts: an application rumor, a proposal, a commit of pending proposals, or a self-update. */
|
|
456
|
+
export type GroupIntent = {
|
|
457
|
+
readonly type: 'application';
|
|
458
|
+
readonly rumor: Rumor;
|
|
459
|
+
} | {
|
|
460
|
+
readonly type: 'proposal';
|
|
461
|
+
readonly proposal: unknown;
|
|
462
|
+
} | {
|
|
463
|
+
readonly type: 'commit';
|
|
464
|
+
} | {
|
|
465
|
+
readonly type: 'self-update';
|
|
466
|
+
};
|
|
467
|
+
/** Per-event ingest outcome (AC-PIPE-4..7). */
|
|
468
|
+
export type IngestDisposition = {
|
|
469
|
+
readonly kind: 'applied';
|
|
470
|
+
readonly eventId: string;
|
|
471
|
+
} | {
|
|
472
|
+
readonly kind: 'application';
|
|
473
|
+
readonly eventId: string;
|
|
474
|
+
readonly rumor: Rumor;
|
|
475
|
+
readonly orderingKey: OrderingKey;
|
|
476
|
+
} | {
|
|
477
|
+
readonly kind: 'duplicate';
|
|
478
|
+
readonly eventId: string;
|
|
479
|
+
} | {
|
|
480
|
+
readonly kind: 'retryable';
|
|
481
|
+
readonly eventId: string;
|
|
482
|
+
readonly reason: string;
|
|
483
|
+
} | {
|
|
484
|
+
readonly kind: 'rejected';
|
|
485
|
+
readonly eventId: string;
|
|
486
|
+
readonly reason: string;
|
|
487
|
+
};
|
|
488
|
+
export type { OrderingKey } from '../history/index.js';
|
|
489
|
+
export type { GroupSnapshot } from './group-snapshot.js';
|
|
490
|
+
export type { InboxRumorDelivery } from './inbox-send.js';
|
|
491
|
+
/** `MarmotGroup.disbanded`: the selected disband (the `group-disbanded` notification's fields). */
|
|
492
|
+
export interface GroupDisbanded {
|
|
493
|
+
/** Hex account identity of the admin whose disband commit was selected. */
|
|
494
|
+
readonly actor: string;
|
|
495
|
+
/** The MLS epoch the disband commit was made at (its parent's epoch). */
|
|
496
|
+
readonly epoch: bigint;
|
|
497
|
+
/** Hex MLS confirmation tag of that parent state. */
|
|
498
|
+
readonly nodeTag: string;
|
|
499
|
+
/** Hex digest of the selected disband commit. */
|
|
500
|
+
readonly commitDigest: string;
|
|
501
|
+
/** Client-clock milliseconds at which this client recorded the settlement. */
|
|
502
|
+
readonly at: number;
|
|
503
|
+
}
|
|
504
|
+
export interface PendingIntent {
|
|
505
|
+
readonly intentId: string;
|
|
506
|
+
/**
|
|
507
|
+
* `awaiting-sync` (AC-PIPE-15): accepted by `send()` after the group was loaded, before its first post-load sync
|
|
508
|
+
* completed — nothing has been encrypted for it yet. Released (encrypted and published) once that sync completes;
|
|
509
|
+
* failed `fenced` via `intentFailed`, never published, when the sync fences the group (AC-HIST-4).
|
|
510
|
+
*/
|
|
511
|
+
readonly state: 'pending-publish' | 'pending-confirm' | 'queued' | 'awaiting-sync';
|
|
512
|
+
/** The `GroupIntent` type the record was created for. */
|
|
513
|
+
readonly kind: GroupIntent['type'];
|
|
514
|
+
}
|
|
515
|
+
export type { AppliedNotification, GroupDisbandedNotification, GroupNotification, HistoryBackend, HistoryEntry, LeafEquivocationNotification, MessageNotification, MessageWithdrawnNotification, WithdrawnNotification, } from '../history/index.js';
|
|
516
|
+
/**
|
|
517
|
+
* Why an `onConfirm` hook runs (AC-MX-1): the confirmed own intent's `GroupIntent` type, or `'create'` /
|
|
518
|
+
* `'join'` for a group this client just created (`groups.create`) or adopted from a Welcome. Its own union —
|
|
519
|
+
* `GroupIntent['type']` (what `send()` accepts) is not widened.
|
|
520
|
+
*/
|
|
521
|
+
export type ConfirmKind = GroupIntent['type'] | 'create' | 'join';
|
|
522
|
+
/**
|
|
523
|
+
* What an `onConfirm` hook receives. It runs INSIDE the transaction that persists the group state —
|
|
524
|
+
* a confirmation's, `groups.create`'s (`kind: 'create'`) or a Welcome adoption's (`kind: 'join'`, only when
|
|
525
|
+
* the adoption wrote the group): writes through `tx` commit atomically with that state, and a throw aborts the
|
|
526
|
+
* whole transaction — the confirmation (retried, AC-PIPE-2, AC-PIPE-13), the creation (`groups.create` rejects
|
|
527
|
+
* with the hook's error, nothing is stored) or the adoption (nothing is stored; the join is completed by a later
|
|
528
|
+
* inbox pass). Use `tx`, never the store itself (storage re-entrancy rule). Never run for a foreign commit's
|
|
529
|
+
* ingest, nor for a `groups.restore` adoption: a restore produces no `'create'`/`'join'` — its first hook run is
|
|
530
|
+
* the confirmation of the restore's own self-update (`kind: 'self-update'`).
|
|
531
|
+
*/
|
|
532
|
+
export interface ConfirmContext {
|
|
533
|
+
readonly groupId: string;
|
|
534
|
+
/** The confirmed intent's id; the group id for `'create'` / `'join'`. */
|
|
535
|
+
readonly intentId: string;
|
|
536
|
+
readonly kind: ConfirmKind;
|
|
537
|
+
/** Epoch of the persisted state. */
|
|
538
|
+
readonly epoch: bigint;
|
|
539
|
+
readonly tx: GroupStoreTx;
|
|
540
|
+
/** Notifications the confirmed commit produces (empty for application messages, `'create'` and `'join'`). */
|
|
541
|
+
readonly notifications: readonly AppliedNotification[];
|
|
542
|
+
/**
|
|
543
|
+
* AC-MX-1: the state this transaction persists (with its retained rewind window), as an opaque enveloped
|
|
544
|
+
* {@link GroupSnapshot} — what `groups.restore(groupId, snapshot)` needs to resume as this leaf. Store it
|
|
545
|
+
* through `tx` to keep it atomic with the state it describes. Built lazily on the first read and memoized (a
|
|
546
|
+
* hook that never reads it costs no serialization); readable only while the hooks run — a first read after the
|
|
547
|
+
* hook returned throws `transaction-closed`.
|
|
548
|
+
*/
|
|
549
|
+
readonly snapshot: GroupSnapshot;
|
|
550
|
+
/**
|
|
551
|
+
* AC-MX-6: set only on the confirmation of the commit `devices.forget` issues to remove another device's leaves
|
|
552
|
+
* from this group — the signature keys (hex) of the leaves it removes. Present while the hooks run, so a hook can
|
|
553
|
+
* act before anything of this confirmation leaves the device: `deviceForgotten` fires only once every group of
|
|
554
|
+
* the forget is settled, after this confirmation's own hooks (and the publishes they scheduled) ran.
|
|
555
|
+
*/
|
|
556
|
+
readonly forgetting?: {
|
|
557
|
+
readonly leafKeys: readonly string[];
|
|
558
|
+
};
|
|
559
|
+
}
|
|
560
|
+
export type ConfirmHook = (confirmation: ConfirmContext) => void | Promise<void>;
|
|
561
|
+
export interface LeafInfo {
|
|
562
|
+
readonly leafIndex: number;
|
|
563
|
+
readonly leafKey: string;
|
|
564
|
+
}
|
|
565
|
+
export type { EncryptedMedia, EncryptMediaOptions, MediaCache } from '../media/index.js';
|
|
566
|
+
export type { AvailabilityEndReason, AvailabilityObservation, FenceCause, GroupAvailability } from './group-availability.js';
|
|
567
|
+
export interface MarmotGroup {
|
|
568
|
+
readonly id: string;
|
|
569
|
+
readonly nostrGroupId: string;
|
|
570
|
+
readonly name: string;
|
|
571
|
+
/** The group's description (`marmot.group.profile.v1`); `''` for a group created without one. Changes with a committed `rename`. */
|
|
572
|
+
readonly description: string;
|
|
573
|
+
readonly admins: readonly string[];
|
|
574
|
+
readonly relays: readonly string[];
|
|
575
|
+
readonly epoch: bigint;
|
|
576
|
+
/**
|
|
577
|
+
* The peer disband that ended this group, once the convergence settlement selected it (BACKLOG
|
|
578
|
+
* `marmot-disband-settled-store-divergence`) — `undefined` while the group is live. Durable: a reload keeps it.
|
|
579
|
+
* A disbanded group does not sync, rejects input (`rejected`, reason `group-disbanded`) and refuses `send` and the
|
|
580
|
+
* other own-commit operations as well as `synced()` with `not-a-member` (details `reason: 'disbanded'`); reads,
|
|
581
|
+
* `history()`, `equivocations()` and `abandon()` / `destroy()` still work. The stored state stays the disband's
|
|
582
|
+
* parent (`epoch` does not move). Announced once by a `group-disbanded` notification.
|
|
583
|
+
*/
|
|
584
|
+
readonly disbanded: GroupDisbanded | undefined;
|
|
585
|
+
/**
|
|
586
|
+
* Intent -> publish -> confirm (AC-PIPE-1..3). An application rumor sent while proposals are staged
|
|
587
|
+
* is queued and resolves once published after the next confirmed commit (AC-INVITE-3); queued
|
|
588
|
+
* rumors go out in order, and one queued before an `invite()` is released at that commit's new
|
|
589
|
+
* epoch — readable by the new invitee. When the commit the queue makes goes terminal, it emits
|
|
590
|
+
* `intentFailed` and the send that triggered it rejects `send-rejected`; the rumor stays queued.
|
|
591
|
+
*
|
|
592
|
+
* AC-PIPE-15: on a group handle obtained by loading stored state (`groups.get`/`groups.list`), a send issued
|
|
593
|
+
* before the group's first post-load sync completed resolves once the intent is durably recorded
|
|
594
|
+
* `awaiting-sync` — nothing is encrypted yet (the stored state may be a restored, rolled-back snapshot). It
|
|
595
|
+
* is encrypted and published once that sync completes; its terminal failure is reported by `intentFailed`
|
|
596
|
+
* (`fenced` when the sync fences the group, AC-HIST-4).
|
|
597
|
+
*/
|
|
598
|
+
send(intent: GroupIntent): Promise<void>;
|
|
599
|
+
/**
|
|
600
|
+
* AC-PIPE-15: resolves once the group has completed its first sync since this client loaded it — every group
|
|
601
|
+
* relay returned EOSE or was excluded as silent (AC-PIPE-14); at once for a group this client instance created
|
|
602
|
+
* or joined, or that already synced. Until then `send()` records `awaiting-sync` intents and `invite`,
|
|
603
|
+
* `setAdmins`, `rename`, `removeMember`, `departAsAdmin`, `leave` and `devices.forget` are refused `commit-pending` (reason
|
|
604
|
+
* `awaiting-sync`). Never settles while no sync can complete (offline). Rejects `fenced` when the group is or
|
|
605
|
+
* becomes fenced (AC-HIST-4), `disposed` / `not-a-member` when the client is disposed / the group abandoned, and
|
|
606
|
+
* `no-lease` when the stores lost their lease before the group's first catch-up (at once once the loss is known,
|
|
607
|
+
* else when a background retry meets it; epic marmot-invitation-outcomes S1).
|
|
608
|
+
*/
|
|
609
|
+
synced(): Promise<void>;
|
|
610
|
+
/**
|
|
611
|
+
* Epic marmot-invitation-outcomes (S1, SC-10): observes the group's availability — the fence, the sync state and the
|
|
612
|
+
* membership as independent facts, and whether an own write may be attempted now. The current snapshot is delivered
|
|
613
|
+
* synchronously, before this returns, then every change in the order it happened, each with a strictly increasing
|
|
614
|
+
* `seq`. A fence is an ordinary observation: the subscription stays open (no fence is ever lifted in place, so within
|
|
615
|
+
* a client session no `clear` follows `fenced` — not even after a failed fence-marker write and the reload that
|
|
616
|
+
* follows). Exactly one `ended` closes it, with `final.writable` `false` (a fenced group stays fenced in it): reason
|
|
617
|
+
* `torn-down` (leave, abandon, destroy, or another teardown purge), `restore-undone` (a failed restore taken back),
|
|
618
|
+
* `disposed` (the client), `no-lease` (the account store's lease was released, closed or lost — immediately when the
|
|
619
|
+
* store implements `AccountStore.onLeaseEnded`). After that, a subscription gets the one `ended` at once and nothing
|
|
620
|
+
* more; this method itself never throws for a fenced, torn-down or disposed group. Exempt from the fenced refusal.
|
|
621
|
+
* Change notifications run outside every library frame (a listener may start group operations, which queue); what
|
|
622
|
+
* is delivered before this returns runs in the caller's own frame — subscribed from inside a library callback (an
|
|
623
|
+
* `onConfirm` hook, a store, …), a same-group operation the listener starts there is rejected `reentrant`, as one
|
|
624
|
+
* the callback started itself would be. A throwing listener is ignored. Returns the unsubscribe function (idempotent): no callback follows it. `invalid-options` when `listener`
|
|
625
|
+
* is not a function.
|
|
626
|
+
*/
|
|
627
|
+
observeAvailability(listener: (observation: AvailabilityObservation) => void): () => void;
|
|
628
|
+
ingest(events: readonly NostrEvent[]): Promise<readonly IngestDisposition[]>;
|
|
629
|
+
/**
|
|
630
|
+
* The durable outbound intents, read directly — NOT serialised behind the group's operation queue: an intent can
|
|
631
|
+
* vanish from the list a moment before `epoch` reflects its confirmed commit (the confirmation transaction deletes
|
|
632
|
+
* the record, then the confirming operation applies the state). Every group operation runs on that per-group queue,
|
|
633
|
+
* so `await group.ingest([])` afterwards is a barrier: once it resolves the confirmation is fully applied.
|
|
634
|
+
*/
|
|
635
|
+
pendingIntents(): Promise<readonly PendingIntent[]>;
|
|
636
|
+
members(): readonly string[];
|
|
637
|
+
memberCount(): number;
|
|
638
|
+
leaves(account: string): readonly LeafInfo[];
|
|
639
|
+
/**
|
|
640
|
+
* One commit adding every KeyPackage, then one Welcome per invitee; resolves with each invitee's
|
|
641
|
+
* Welcome outcome (AC-INVITE-1/2). Rumors queued before it (AC-INVITE-3) are released at the
|
|
642
|
+
* invite commit's new epoch, so the invitees can read them.
|
|
643
|
+
*
|
|
644
|
+
* Fork loss: a withdrawn invite commit is re-driven automatically from the retained KeyPackage events (`welcomeFailed`
|
|
645
|
+
* `commit-withdrawn`, `own-change-withdrawn` `{ member-added }`, then `own-change-reapplied` or `own-change-lost`); the re-driven
|
|
646
|
+
* Welcome has a new `inviteId` and the same `inviteeRef`. A manual re-invite of the same KeyPackage after the re-drive is refused
|
|
647
|
+
* `send-rejected` (the engine rejects a second leaf under that signature key); wait for the terminal.
|
|
648
|
+
*/
|
|
649
|
+
invite(keyPackages: readonly NostrEvent[]): Promise<readonly WelcomeOutcome[]>;
|
|
650
|
+
/**
|
|
651
|
+
* Re-wraps and re-publishes `inviteeRef`'s Welcome (its KeyPackageRef) — never a new commit (AC-INVITE-2). A delivery marked
|
|
652
|
+
* `welcomeFailed` `delivered-on-abandoned-branch` is refused `send-rejected` (`details.reason: 'abandoned-branch'`): remove the
|
|
653
|
+
* member and invite it again with a fresh KeyPackage.
|
|
654
|
+
*/
|
|
655
|
+
retryWelcome(inviteeRef: string): Promise<WelcomeOutcome>;
|
|
656
|
+
activeAdmins(): readonly string[];
|
|
657
|
+
isActiveAdmin(account: string): boolean;
|
|
658
|
+
isLastActiveAdmin(account: string): boolean;
|
|
659
|
+
/**
|
|
660
|
+
* Sets the admin list in ONE durable commit. Fork loss: re-driven per account (only the flips nobody else changed since the fork
|
|
661
|
+
* point survive, applied to the current tip's list); reported through `own-change-*` (`{ admin }` changes). `departAsAdmin`'s demotion
|
|
662
|
+
* commit is re-driven the same way; if the device's own leave lands first the flip is lost `stranded`.
|
|
663
|
+
*/
|
|
664
|
+
setAdmins(accounts: readonly string[]): Promise<void>;
|
|
665
|
+
/**
|
|
666
|
+
* Renames the group: ONE admin commit that replaces the group profile (`marmot.group.profile.v1`: name AND
|
|
667
|
+
* description). `description` omitted keeps the CURRENT description; `description: ''` clears it. An omitted
|
|
668
|
+
* description is resolved when the call is made and stored by value. A concurrent change is never merged: if another
|
|
669
|
+
* admin's profile commit is applied before this commit is built, the rename rejects `send-rejected` (stale epoch) and
|
|
670
|
+
* that profile stands; in a same-epoch race the fork rule keeps one whole profile. An unchanged profile still
|
|
671
|
+
* commits. `onConfirm` hooks see `kind: 'commit'`.
|
|
672
|
+
*
|
|
673
|
+
* Refusals, each with nothing recorded and the epoch unchanged: `invalid-options` for a `name` that is not a
|
|
674
|
+
* non-empty string of at most 256 UTF-8 bytes or a `description` that is not a string of at most 4096 UTF-8 bytes
|
|
675
|
+
* (byte limits, not character counts); `invalid-options` with `details.reason: 'not-admin'` for a caller that is
|
|
676
|
+
* not an admin (a non-admin proposes the rename instead: send `{ type: 'proposal', proposal:
|
|
677
|
+
* groupProfileProposal(...) }` and let an admin send `{ type: 'commit' }`); `commit-pending` while an own commit
|
|
678
|
+
* is pending. A caller that is not a member, or whose pre-sync gate is closed, is refused first, as for every own
|
|
679
|
+
* commit (`not-a-member`, `commit-pending` with `details.reason: 'awaiting-sync'`). An admin demoted between the
|
|
680
|
+
* call and the build is rejected `send-rejected`, like `setAdmins`.
|
|
681
|
+
*
|
|
682
|
+
* Fork loss: re-driven per component; if anyone else changed the profile since the fork point it is lost `concurrent-change`
|
|
683
|
+
* (never merged) and reported through `own-change-*`.
|
|
684
|
+
*
|
|
685
|
+
* While a group-profile (`0x8001`) proposal is staged on the group (another member's, or one of your own), `rename`
|
|
686
|
+
* is rejected `send-rejected` (`details.reason: 'staged-profile-update'`) with nothing recorded and the state
|
|
687
|
+
* unchanged, because a commit that carried the staged proposal and this rename would hold two profile updates;
|
|
688
|
+
* commit the staged proposal first (`send({ type: 'commit' })`).
|
|
689
|
+
*/
|
|
690
|
+
rename(name: string, options?: {
|
|
691
|
+
readonly description?: string;
|
|
692
|
+
}): Promise<void>;
|
|
693
|
+
/**
|
|
694
|
+
* Removes `account`: ONE admin commit that removes every leaf the account holds when the commit is built (the stored intent
|
|
695
|
+
* names the account). An admin may remove another admin in the same commit, with no demotion first: the engine's coupling
|
|
696
|
+
* splice drops the removed admin's entry atomically.
|
|
697
|
+
*
|
|
698
|
+
* Refusals, nothing recorded, epoch unchanged: `invalid-options` with `details.reason` `'malformed-account'`, `'self'`
|
|
699
|
+
* (use `departAsAdmin()` or `leave()`) or `'not-admin'`; `commit-pending` while an own commit is pending; `not-a-member` /
|
|
700
|
+
* `commit-pending` (`awaiting-sync`) first, as for every own commit. An account that holds no leaf (never a member, or
|
|
701
|
+
* already removed) resolves as a no-op. An admin demoted between the call and the build is rejected `send-rejected`.
|
|
702
|
+
*
|
|
703
|
+
* Staged proposals: a staged Remove or SelfRemove of the account's leaf is skipped (carried by reference). `send-rejected`,
|
|
704
|
+
* nothing recorded, when a staged Add admits a leaf of the account (`'staged-add-of-removed-account'`), when a staged Update
|
|
705
|
+
* names the account's leaf, or when a staged admin-list change still names a removed admin
|
|
706
|
+
* (`'staged-admin-policy-update'`): commit the staged proposal first (`send({ type: 'commit' })`) and retry. A staged
|
|
707
|
+
* admin-list change is committed together with the removal.
|
|
708
|
+
*
|
|
709
|
+
* Removed side (Q1 option a): each device keeps a tombstoned group (read-only, `members()` without the account, own
|
|
710
|
+
* commits refused `not-a-member`); its own group emits no `leaf-removed` notification (the remaining members' groups do).
|
|
711
|
+
* The app calls `abandon()` / `destroy()`. Success is final once the commit is canonical, or re-driven: if a same-epoch fork loss withdraws it, this device (only it)
|
|
712
|
+
* re-checks the removal against the winning tip and re-drives it as a fresh commit; the application hears `own-change-withdrawn`
|
|
713
|
+
* `{ member-removed }`, then `own-change-reapplied` or `own-change-lost` (`already-applied`, `reversed`, `concurrent-change`, `not-admin`,
|
|
714
|
+
* `stranded`, `attempts-exhausted`). `leaf-removal-withdrawn` is unchanged. A record that outlives a concurrent remove-and-re-add of the same device by another admin removes the account again.
|
|
715
|
+
*/
|
|
716
|
+
removeMember(account: string): Promise<void>;
|
|
717
|
+
/**
|
|
718
|
+
* Epic marmot-invitation-outcomes S5 (SC-11): removes exactly the ONE admission a declined delivery made — the leaf position the
|
|
719
|
+
* candidate's proven original Add put in this group — by `ref`, the candidate's cleanup reference. A reference confers no
|
|
720
|
+
* authority: every call re-derives the disposition from durable evidence and lineage.
|
|
721
|
+
*
|
|
722
|
+
* Resolves with a {@link CleanupDispositionReport}: `pending` (with the root `intentId`) when the cleanup was durably accepted —
|
|
723
|
+
* or was already in flight: a repeated, concurrent or lost-reply submit coalesces with it, with no resume, transport call or write
|
|
724
|
+
* — and otherwise the current disposition when it is not `eligible` (`removed-revisable`, `removed-settled`, `absent`,
|
|
725
|
+
* `insufficient-evidence`; nothing is recorded). An accepted cleanup is built, published and confirmed in the background; its
|
|
726
|
+
* commit re-checks the target on the actual parent and is dropped (never removing a replacement) when it no longer holds.
|
|
727
|
+
*
|
|
728
|
+
* Refusals enqueue nothing: `fenced`, `not-a-member` (`disbanded`), `invalid-options` (`details.reason`
|
|
729
|
+
* `malformed-reference`, `foreign-reference` — another account than the signer's or another group —, `unknown-reference`,
|
|
730
|
+
* `self` — the committer's own leaf; another device of the own account is a valid target —, `not-admin`), `confirm-blocked`,
|
|
731
|
+
* `commit-pending` (another own commit pending, or `awaiting-sync`: retryable), `send-rejected` with `details.retryable` for a
|
|
732
|
+
* staged proposal in the way (`staged-add-conflict`, `staged-removal-of-target`, `staged-admin-policy-update` — the last leaf of an
|
|
733
|
+
* admin account gets the account removal's admin coupling). After an uncertain failure, read
|
|
734
|
+
* `invitations.cleanupDisposition(ref)` before resubmitting.
|
|
735
|
+
*
|
|
736
|
+
* Fork loss: a withdrawn cleanup reads `pending` until its library re-drive ends; the application hears `own-change-withdrawn`
|
|
737
|
+
* `{ admission-removed }` (never `member-removed`), then `own-change-reapplied` or `own-change-lost` with the existing reasons. It is
|
|
738
|
+
* never re-driven as an account-wide removal.
|
|
739
|
+
*/
|
|
740
|
+
removeAdmission(ref: CleanupReference): Promise<CleanupDispositionReport>;
|
|
741
|
+
departAsAdmin(): Promise<void>;
|
|
742
|
+
leave(): Promise<void>;
|
|
743
|
+
abandon(): Promise<void>;
|
|
744
|
+
destroy(): Promise<void>;
|
|
745
|
+
/**
|
|
746
|
+
* Encrypts `bytes` as `encrypted-media-v1` under the current epoch's key (AC-MEDIA-1): `{ ciphertext, imeta,
|
|
747
|
+
* locator }` — `locator` the ciphertext's SHA-256 (hex), under which the media cache (if configured) keeps it.
|
|
748
|
+
* Nothing is uploaded: the application stores the ciphertext (e.g. Blossom) and sends a rumor carrying `imeta`.
|
|
749
|
+
*/
|
|
750
|
+
encryptMedia(bytes: Uint8Array, options?: EncryptMediaOptions): Promise<EncryptedMedia>;
|
|
751
|
+
/**
|
|
752
|
+
* Decrypts media described by `media.imeta`, trying every epoch the group retains. An empty `ciphertext` is
|
|
753
|
+
* looked up in the media cache by `locator` (`invalid-options` / `not-found` when absent).
|
|
754
|
+
*/
|
|
755
|
+
decryptMedia(media: EncryptedMedia): Promise<Uint8Array>;
|
|
756
|
+
/** The retained application rumors (the history backend's, in delivery order); none without a backend (AC-HIST-3). */
|
|
757
|
+
history(): AsyncIterable<Rumor>;
|
|
758
|
+
/**
|
|
759
|
+
* Live notifications (AC-HIST-2/3), each after the state it describes was persisted: `applied` / `withdrawn`
|
|
760
|
+
* (a commit's state changes, keyed by its digest; a rewind withdraws them under the same digest), `message`
|
|
761
|
+
* (an accepted application message with its `OrderingKey`) and `message-withdrawn`. Also `own-change-withdrawn` (at most once)
|
|
762
|
+
* and `own-change-reapplied` / `own-change-lost` (at least once, retained until the group's first listener) for own commits a fork
|
|
763
|
+
* loss withdrew. Returns an unsubscribe.
|
|
764
|
+
*/
|
|
765
|
+
onNotification(listener: (notification: GroupNotification) => void): () => void;
|
|
766
|
+
/**
|
|
767
|
+
* Every leaf equivocation this member has recorded for the group (ADR-016) — the durable source of truth behind the
|
|
768
|
+
* live `leaf-equivocation` notification, which is a hint delivered at most once per `(nodeTag, leafIndex)` and lost
|
|
769
|
+
* when no listener is attached or the process ends before dispatch. Ordered by `(epoch, nodeTag, leafIndex)`;
|
|
770
|
+
* `[]` when none. A direct read of the group store (not serialised behind the group's operation queue), available
|
|
771
|
+
* on a fenced group; rejects `disposed` / `not-a-member` like every other accessor.
|
|
772
|
+
*/
|
|
773
|
+
equivocations(): Promise<readonly LeafEquivocationNotification[]>;
|
|
774
|
+
}
|
|
775
|
+
export interface WelcomeManifest {
|
|
776
|
+
/** Hex MLS group id. */
|
|
777
|
+
readonly groupId: string;
|
|
778
|
+
/** Hex KeyPackageRef of the local KeyPackage the Welcome must consume. */
|
|
779
|
+
readonly keyPackageRef: string;
|
|
780
|
+
/** The account expected to send the Welcome (a member of the group). */
|
|
781
|
+
readonly sponsorAccount: string;
|
|
782
|
+
/** Client-clock milliseconds; a Welcome processed at or after it is not auto-accepted. */
|
|
783
|
+
readonly deadline: number;
|
|
784
|
+
}
|
|
785
|
+
/**
|
|
786
|
+
* A `registerInboxHandler` handler (and the shape of `onApplicationRumor`):
|
|
787
|
+
* receives the rumor as unwrapped and its kind-1059 wrap, both frozen.
|
|
788
|
+
*
|
|
789
|
+
* Handlers run on the inbox queue and block all inbox dispatch (Welcomes
|
|
790
|
+
* included) until they settle: do not await `group.send` or other long work —
|
|
791
|
+
* `send` resolves only once published, which can take as long as the next
|
|
792
|
+
* admin commit or a remote signer's approval. Persist what you need and
|
|
793
|
+
* return, or fire-and-forget.
|
|
794
|
+
*
|
|
795
|
+
* Delivery is at-least-once — the wrap is marked seen only after the handler
|
|
796
|
+
* resolved, so a crash or reload in between, or the wrap id's eviction from
|
|
797
|
+
* the bounded seen-set, redelivers the rumor: handlers MUST tolerate
|
|
798
|
+
* redelivery (AC-INBOX-4). A throw counts toward the 10-retry cap (then the
|
|
799
|
+
* wrap is dropped, `rejected('processing-failed')`) and each retry
|
|
800
|
+
* re-decrypts the wrap. Account-scope client operations called from inside a
|
|
801
|
+
* handler reject `reentrant` (ADR-013).
|
|
802
|
+
*/
|
|
803
|
+
export type InboxHandler = InboxRumorHandler;
|
|
804
|
+
export interface MarmotClient {
|
|
805
|
+
/** The account-key signer: the construction `signer` behind `withSignerBudget(signer, budget)`. Every account-key call goes through it. */
|
|
806
|
+
readonly signer: Signer;
|
|
807
|
+
/** Same value as the module export `permissions` (AC-API-7). */
|
|
808
|
+
readonly permissions: PermissionDeclaration;
|
|
809
|
+
readonly groups: {
|
|
810
|
+
create(name: string, options?: {
|
|
811
|
+
readonly relays?: readonly string[];
|
|
812
|
+
readonly admins?: readonly string[];
|
|
813
|
+
}): Promise<MarmotGroup>;
|
|
814
|
+
get(groupId: string): Promise<MarmotGroup | undefined>;
|
|
815
|
+
list(): Promise<readonly MarmotGroup[]>;
|
|
816
|
+
/**
|
|
817
|
+
* AC-MX-2: resumes as the leaf `snapshot` (an `onConfirm` hook's `ConfirmContext.snapshot`) was taken from:
|
|
818
|
+
* adopts it with its rewind window, runs the group's first sync (replaying every commit since from the group
|
|
819
|
+
* relays), commits a self-update and resolves the handle only once that self-update is confirmed — so the
|
|
820
|
+
* relays hold it before any application message from this client. Rejects `envelope-mismatch` (another engine
|
|
821
|
+
* / ts-mls build — a snapshot is restorable only by the build that took it —, or not a well-formed snapshot:
|
|
822
|
+
* a serialized state of another group than its payload names, a rewind window that is no tree below its tip
|
|
823
|
+
* within the rollback horizon), `invalid-options` (a snapshot whose serialized MLS state is of another group
|
|
824
|
+
* than `groupId`), `already-member` (the group is held or being restored) and
|
|
825
|
+
* `reentrant` (from an account-scope surface or a group's `onConfirm` hook) before anything is written; any
|
|
826
|
+
* later failure (`fenced` — also when the group is fenced after its first sync —, `not-a-member` — torn down
|
|
827
|
+
* meanwhile —, `send-rejected`, `disposed`) removes the adopted group again. Until it settles, `groups.get`
|
|
828
|
+
* of it waits (rejecting `reentrant` from inside a consumer surface) and `groups.list` skips it. Never settles
|
|
829
|
+
* while no sync can complete (offline), like `MarmotGroup.synced()`.
|
|
830
|
+
*/
|
|
831
|
+
restore(groupId: string, snapshot: GroupSnapshot): Promise<MarmotGroup>;
|
|
832
|
+
};
|
|
833
|
+
readonly keyPackages: {
|
|
834
|
+
create(options?: {
|
|
835
|
+
readonly relays?: readonly string[];
|
|
836
|
+
readonly lastResort?: boolean;
|
|
837
|
+
}): Promise<NostrEvent>;
|
|
838
|
+
list(): Promise<readonly NostrEvent[]>;
|
|
839
|
+
count(): Promise<number>;
|
|
840
|
+
rotate(ref: string): Promise<NostrEvent>;
|
|
841
|
+
forget(ref: string): Promise<void>;
|
|
842
|
+
observe(account: string, listener: (event: NostrEvent) => void): () => void;
|
|
843
|
+
/**
|
|
844
|
+
* S8 (AC-KP-7): mints a fresh KeyPackage and offers it to sponsor `to` for
|
|
845
|
+
* `groupId` — a gift-wrapped offer rumor on `to`'s inbox relays; the group
|
|
846
|
+
* id never appears outside the wrap.
|
|
847
|
+
*/
|
|
848
|
+
offer(options: {
|
|
849
|
+
readonly groupId: string;
|
|
850
|
+
readonly to: string;
|
|
851
|
+
}): Promise<{
|
|
852
|
+
readonly offerId: string;
|
|
853
|
+
readonly keyPackageEvent: NostrEvent;
|
|
854
|
+
}>;
|
|
855
|
+
};
|
|
856
|
+
readonly invitations: {
|
|
857
|
+
expectWelcome(manifest: WelcomeManifest): Promise<void>;
|
|
858
|
+
pending(): Promise<readonly PendingInvitation[]>;
|
|
859
|
+
accept(id: string): Promise<MarmotGroup>;
|
|
860
|
+
decline(id: string, options?: {
|
|
861
|
+
readonly declineRumor?: boolean;
|
|
862
|
+
}): Promise<void>;
|
|
863
|
+
/** S8: KeyPackage offers received for groups this client holds (optionally one group's), oldest first; admit one with `group.invite([offer.keyPackageEvent])`. */
|
|
864
|
+
offers(groupId?: string): Promise<readonly KeyPackageOffer[]>;
|
|
865
|
+
/**
|
|
866
|
+
* Epic marmot-invitation-outcomes S2: whether THIS invitation (a Welcome id) caused this device to join its group,
|
|
867
|
+
* read from durable evidence at one instant (ADR-019 D7, D9) — authoritative where `accept(id)` is not (an
|
|
868
|
+
* `accept` may return the held group's handle for a Welcome that was kept out). Runs on the inbox queue (behind the
|
|
869
|
+
* current inbox task) and works before `inbox.start()`. Rejects `reentrant` synchronously from inside an `onConfirm`
|
|
870
|
+
* / `onBeforePublish` / `verifier` / `onProposal` hook, an inbox handler, `onApplicationRumor` or any account-scope
|
|
871
|
+
* consumer surface — read it from an event listener (e.g. `groupJoined`) instead.
|
|
872
|
+
*/
|
|
873
|
+
outcome(id: string): Promise<InvitationOutcome>;
|
|
874
|
+
/**
|
|
875
|
+
* Epic marmot-invitation-outcomes S3 (SC-13): one page of the locally issued deliveries their invitee's account
|
|
876
|
+
* declined, recovered offline from this account store alone (no group is opened). Read-only: no publication, no
|
|
877
|
+
* intent, no pruning, no store write. Pages are ordered and bounded (`limit` clamped to `[1, 256]`, default 256);
|
|
878
|
+
* pass the previous page's `next` as `after` until `complete`. Each candidate appears at most once across the
|
|
879
|
+
* pages of one walk; one recorded meanwhile surfaces through the `declineCandidate` event — register it first.
|
|
880
|
+
* Rejects `reentrant` synchronously from inside an account-scope consumer surface (a store, signer or verifier
|
|
881
|
+
* call); allowed from group hooks, inbox handlers and event listeners.
|
|
882
|
+
*/
|
|
883
|
+
declineCandidates(options?: {
|
|
884
|
+
readonly after?: string;
|
|
885
|
+
readonly limit?: number;
|
|
886
|
+
}): Promise<DeclineCandidatePage>;
|
|
887
|
+
/**
|
|
888
|
+
* Epic marmot-invitation-outcomes S4 (SC-12): what this store's durable evidence proves about the admission a
|
|
889
|
+
* declined delivery made, by the candidate's cleanup reference — `eligible` (the proven original admission is
|
|
890
|
+
* present), `absent` (`add-off-path`: its Add is not on the selected path; `occupancy-ended`: the admission
|
|
891
|
+
* ended), or `insufficient-evidence` (`unresolved-selector`, `ambiguous-legacy`, `no-anchor`, `lineage-gap`).
|
|
892
|
+
* Read-only and offline: no group runtime, no publication, no intent, no store write; recompute it after branch
|
|
893
|
+
* changes. On a fenced group it still answers, with the last disposition the store proved (`lastKnown: true`).
|
|
894
|
+
* Rejects `invalid-options` (`details.reason`: `malformed-reference`, `foreign-reference` — another account than
|
|
895
|
+
* the signer's —, `unknown-reference`) with no effect. Rejects `reentrant` synchronously from inside an
|
|
896
|
+
* `onConfirm` / `onBeforePublish` / `verifier` / `onProposal` hook, a consumer group-store call or any
|
|
897
|
+
* account-scope consumer surface other than an inbox handler; allowed from inbox handlers and event listeners.
|
|
898
|
+
* Since S5 it also reads `pending` (a cleanup durably accepted, or a library re-drive of a withdrawn one, under the
|
|
899
|
+
* root `intentId`) and `removed-revisable` / `removed-settled` (the cleanup's own confirmed inline Remove, `commitDigest`).
|
|
900
|
+
*/
|
|
901
|
+
cleanupDisposition(ref: CleanupReference): Promise<CleanupDispositionReport>;
|
|
902
|
+
};
|
|
903
|
+
readonly inbox: {
|
|
904
|
+
start(): Promise<void>;
|
|
905
|
+
stop(): Promise<void>;
|
|
906
|
+
};
|
|
907
|
+
/** S8: the account's devices (one leaf signature key per client instance) and same-account enrolment (ADR-003). */
|
|
908
|
+
readonly devices: {
|
|
909
|
+
list(): Promise<readonly DeviceInfo[]>;
|
|
910
|
+
requestEnrolment(options: EnrolmentRequestOptions): Promise<EnrolmentRequestHandle>;
|
|
911
|
+
pendingEnrolments(): Promise<readonly EnrolmentPrompt[]>;
|
|
912
|
+
/**
|
|
913
|
+
* Approves a prompted enrolment request (ADR-003). Call it from application (UI) code: from inside an
|
|
914
|
+
* inbox handler or `onApplicationRumor` it inherits their account-scope frame and its `group.invite`
|
|
915
|
+
* rejects `reentrant` (ADR-013).
|
|
916
|
+
*/
|
|
917
|
+
approveEnrolment(requestId: string): Promise<EnrolmentApprovalOutcome>;
|
|
918
|
+
label(leafKey: string, label: string): Promise<void>;
|
|
919
|
+
forget(leafKey: string): Promise<DeviceForgetOutcome>;
|
|
920
|
+
/**
|
|
921
|
+
* Epic marmot-device-key-rotation (S7): re-keys this device. A fresh device signing key (its account identity proof signed
|
|
922
|
+
* once) becomes the device key in one transaction; every held group's own leaf is then re-keyed to it (a self-update commit
|
|
923
|
+
* per group), the KeyPackages signed with the old key are replaced and deleted, and `deviceKeyRotationSettled` fires when
|
|
924
|
+
* every group is terminal. Resolves after the prepare committed and one pass drove every group (`settled` tells whether it
|
|
925
|
+
* is finished; the rest continues in the background and after a restart). A rotation already open is returned. Rejects
|
|
926
|
+
* `invalid-options` with `details.reason`: `no-device-key` (nothing minted, no group), `device-forgetting` (this device's
|
|
927
|
+
* own forget is open), `rotation-unavailable`.
|
|
928
|
+
*/
|
|
929
|
+
rotateKey(): Promise<DeviceKeyRotationOutcome>;
|
|
930
|
+
/** The open rotation, else the last one (`status`: `rotating` / `rotated` / `gave-up`); `undefined` when the device never rotated. */
|
|
931
|
+
rotation(): Promise<DeviceKeyRotationOutcome | undefined>;
|
|
932
|
+
};
|
|
933
|
+
readonly extensions: {
|
|
934
|
+
/**
|
|
935
|
+
* Routes every inbox rumor of `kind` to `handler` instead of
|
|
936
|
+
* `onApplicationRumor` (AC-INBOX-5); `handler-exists` / `reserved-kind`.
|
|
937
|
+
* Handlers run on the inbox queue and block all inbox dispatch until they
|
|
938
|
+
* settle: do not await `group.send` or other long work — persist what you
|
|
939
|
+
* need and return, or fire-and-forget. Delivery is at-least-once; a throw
|
|
940
|
+
* counts toward the 10-retry cap and each retry re-decrypts the wrap.
|
|
941
|
+
*/
|
|
942
|
+
registerInboxHandler(kind: number, handler: InboxHandler): () => void;
|
|
943
|
+
onConfirm(hook: ConfirmHook): () => void;
|
|
944
|
+
/**
|
|
945
|
+
* AC-HOOK-1: registers a hook that runs for every own `commit` / `self-update` between its staging and its first
|
|
946
|
+
* publish, in its own transaction, handed the pending-tagged snapshot of the state the commit produces; the
|
|
947
|
+
* `PublishBarrier` it may return is awaited (best-effort, `beforePublishTimeoutMs`) before the publish. Returns
|
|
948
|
+
* the unregister function; throws `disposed` on a disposed client. A hook that throws, a barrier that rejects or
|
|
949
|
+
* times out never holds the commit back (`beforePublishSkipped`). From inside the hook or the barrier, a mutating
|
|
950
|
+
* operation on the group, `groups.restore`, `devices.*` and `sendInboxRumor` reject `reentrant`.
|
|
951
|
+
*/
|
|
952
|
+
onBeforePublish(hook: BeforePublishHook): () => void;
|
|
953
|
+
/**
|
|
954
|
+
* `groups.create()` waits until `gate()` resolves and aborts with its
|
|
955
|
+
* rejection; a gate resolving `{ once: true }` is not asked again by this
|
|
956
|
+
* client instance (AC-INBOX-7). Returns the unregister function.
|
|
957
|
+
*/
|
|
958
|
+
beforeCreateGroup(gate: CreateGroupGate): () => void;
|
|
959
|
+
/**
|
|
960
|
+
* AC-MX-3: gift-wraps `rumor` (the account's own, with its NIP-01 id) to `to` through the budgeted signer and
|
|
961
|
+
* publishes it once on `to`'s inbox relays (marmot's inbox resolution). Persists nothing, retries nothing:
|
|
962
|
+
* `{ status: 'delivered' | 'retryable' | 'failed', reason?, relays? }`. Rejects `reserved-kind` for a
|
|
963
|
+
* `RUMOR_KINDS` value (before any signer or transport call), `invalid-options` for a malformed input and
|
|
964
|
+
* `reentrant` from an account-scope surface or a group's `onConfirm` hook.
|
|
965
|
+
*/
|
|
966
|
+
sendInboxRumor(input: {
|
|
967
|
+
readonly to: string;
|
|
968
|
+
readonly rumor: Rumor;
|
|
969
|
+
}): Promise<InboxRumorDelivery>;
|
|
970
|
+
};
|
|
971
|
+
/**
|
|
972
|
+
* Sinks for transport-adapter callbacks the narrowed `TransportContract`
|
|
973
|
+
* cannot carry: wire `authFailed` into the adapter's `onAuthFailed` option
|
|
974
|
+
* and `connected` into its (re)connect callback. Re-emitted as client
|
|
975
|
+
* events (`authFailed`, `transportConnected`) with the raw relay string
|
|
976
|
+
* (ADR-014); no-ops once the client is disposed.
|
|
977
|
+
*/
|
|
978
|
+
readonly transportEvents: {
|
|
979
|
+
authFailed(relayUrl: string, error: unknown): void;
|
|
980
|
+
connected(relayUrl: string): void;
|
|
981
|
+
};
|
|
982
|
+
on<E extends MarmotClientEventName>(event: E, listener: (payload: MarmotClientEvents[E]) => void): () => void;
|
|
983
|
+
/** Releases listeners; every later call on this client throws `disposed`. Idempotent. */
|
|
984
|
+
dispose(): void;
|
|
985
|
+
}
|
|
986
|
+
/**
|
|
987
|
+
* Internal (tests only): the defects the integration properties' negative controls reintroduce into the commit re-drive (epic
|
|
988
|
+
* marmot-rewound-own-commit-no-signal, S6). Each one is a single guarded line in the production path; none is reachable from the public API.
|
|
989
|
+
*/
|
|
990
|
+
export interface RedriveFaultsForTest {
|
|
991
|
+
/** AC-PROP-2 (b): the re-drive commit is built WITHOUT the surviving changes' payload, while `own-change-reapplied` is still dispatched for them. */
|
|
992
|
+
readonly dropPayload?: boolean;
|
|
993
|
+
/** AC-PROP-4: the lost verdicts of a re-drive build are dispatched BEFORE the mint transaction commits (and again once it has). */
|
|
994
|
+
readonly dispatchLostBeforeMint?: boolean;
|
|
995
|
+
}
|
|
996
|
+
/** Resolved construction state later client-module stories build on. */
|
|
997
|
+
export interface ClientContext {
|
|
998
|
+
readonly signer: Signer;
|
|
999
|
+
readonly transport: TransportContract;
|
|
1000
|
+
readonly stores: ClientStores;
|
|
1001
|
+
readonly relays: RelayOptions;
|
|
1002
|
+
readonly verifier: EventVerifier | undefined;
|
|
1003
|
+
readonly onProposal: ProposalCallback | undefined;
|
|
1004
|
+
readonly clock: ClientClock;
|
|
1005
|
+
readonly historySilenceThreshold: number;
|
|
1006
|
+
readonly graceWindowMs: number;
|
|
1007
|
+
readonly timers: ClientTimers;
|
|
1008
|
+
readonly historyTimeoutMs: number;
|
|
1009
|
+
readonly maxPublishAttempts: number;
|
|
1010
|
+
/** AC-HOOK-1, AC-BAR-2: the `extensions.onBeforePublish` hooks and the barrier deadline. */
|
|
1011
|
+
readonly beforePublish: BeforePublishRegistry;
|
|
1012
|
+
readonly seenSetCap: number;
|
|
1013
|
+
readonly enrolmentPromptRateLimit: number;
|
|
1014
|
+
readonly maxGiftWrapBytes: number;
|
|
1015
|
+
readonly leaveTimeoutMs: number;
|
|
1016
|
+
/** S15 (AC-INVITE-4): deferral deadline of an `onProposal`-deferred proposal (ms; 0 = never). */
|
|
1017
|
+
readonly proposalDeferralTimeoutMs: number;
|
|
1018
|
+
/** S10: the optional history backend and media cache seams. */
|
|
1019
|
+
readonly history: HistoryBackend | undefined;
|
|
1020
|
+
readonly mediaCache: MediaCache | undefined;
|
|
1021
|
+
/** Internal, tests only: rewrites the engine seams (see {@link createMarmotClientWith}). */
|
|
1022
|
+
readonly engineSeamsOverride: EngineSeamsOverride | undefined;
|
|
1023
|
+
/** Internal, tests only: see {@link InternalClientOptions.engineOptions}. */
|
|
1024
|
+
readonly engineOptionsForTest: InternalClientOptions['engineOptions'];
|
|
1025
|
+
/** Internal: see {@link InternalClientOptions.finishPurgeBeforeJoin}. */
|
|
1026
|
+
readonly finishPurgeBeforeJoin: boolean;
|
|
1027
|
+
/** How long one history backend call may take before it counts as a failed attempt (ms). */
|
|
1028
|
+
readonly historyBackendTimeoutMs: number;
|
|
1029
|
+
/** S20: how long a removal of the local leaf stays revisable (client-clock ms; see client/group-removal.ts). */
|
|
1030
|
+
readonly removalSettleMs: number;
|
|
1031
|
+
/** S5 (AC-RACE-2): the elected-SelfRemove-committer bounded wait (client-clock ms; see client/pipeline.ts). */
|
|
1032
|
+
readonly selfRemoveElectionWaitMs: number;
|
|
1033
|
+
/** S7 (AC-HYG-2): how long a settled invite record is kept (client-clock ms; see invitations/invite.ts). */
|
|
1034
|
+
readonly inviteRetentionMs: number;
|
|
1035
|
+
/** inbox-handler-time-budget: when a running inbox consumer callback is reported `handlerSlow` (client-clock ms; 0 = never). */
|
|
1036
|
+
readonly inboxHandlerBudgetMs: number;
|
|
1037
|
+
/** S8 (AC-RATCH-1): own application ratchet skip at the first own message after a load (see client/pipeline.ts). */
|
|
1038
|
+
readonly ratchetSkipMargin: number;
|
|
1039
|
+
/** Internal (tests only): see {@link InternalClientOptions.disableSelfUpdateReenqueueForTest}. */
|
|
1040
|
+
readonly disableSelfUpdateReenqueueForTest: boolean;
|
|
1041
|
+
/** Internal (tests only): see {@link InternalClientOptions.disableRestoreRotationForTest}. */
|
|
1042
|
+
readonly disableRestoreRotationForTest: boolean;
|
|
1043
|
+
/** Internal (tests only): see {@link InternalClientOptions.disableRatchetSkipForTest}. */
|
|
1044
|
+
readonly disableRatchetSkipForTest: boolean;
|
|
1045
|
+
/** Internal (tests only): see {@link InternalClientOptions.redriveFaultsForTest}. */
|
|
1046
|
+
readonly redriveFaultsForTest: RedriveFaultsForTest | undefined;
|
|
1047
|
+
/** Internal (tests only): see {@link InternalClientOptions.exposeRuntimesForTest}. */
|
|
1048
|
+
readonly exposeRuntimesForTest: InternalClientOptions['exposeRuntimesForTest'];
|
|
1049
|
+
emit<E extends MarmotClientEventName>(event: E, payload: MarmotClientEvents[E]): void;
|
|
1050
|
+
/** AC-INBOX-6: the only emit path of every `LifecycleEventPayloads` member — after the commit. */
|
|
1051
|
+
readonly lifecycle: LifecycleEvents;
|
|
1052
|
+
/** AC-INBOX-7: the `beforeCreateGroup` gates `groups.create()` passes first. */
|
|
1053
|
+
readonly beforeCreateGroup: BeforeCreateGroupGates;
|
|
1054
|
+
/**
|
|
1055
|
+
* Epic marmot-device-key-rotation (S6, AC-NOTIF-6): where a group operation reads the device lineage from — the
|
|
1056
|
+
* account's recorded links, as the synchronous {@link DeviceLineage} snapshot `devices.lineage()` hands out (`isRetired`, `keysOf`). Late-bound
|
|
1057
|
+
* (the device service is built after the group registry that holds `ctx`): `read` is `undefined` until then, and
|
|
1058
|
+
* a failing or absent read only means no `retired-key-readded` is emitted.
|
|
1059
|
+
*/
|
|
1060
|
+
readonly deviceLineage: DeviceLineageSource;
|
|
1061
|
+
isDisposed(): boolean;
|
|
1062
|
+
}
|
|
1063
|
+
/** See {@link ClientContext.deviceLineage}. */
|
|
1064
|
+
export interface DeviceLineageSource {
|
|
1065
|
+
read: (() => Promise<DeviceLineage>) | undefined;
|
|
1066
|
+
}
|
|
1067
|
+
/** Internal accessor for tests; not re-exported. */
|
|
1068
|
+
export declare function getGroupRegistry(client: MarmotClient): GroupRegistry;
|
|
1069
|
+
/** Internal accessor for other client-module files and tests; not re-exported. */
|
|
1070
|
+
export declare function getClientContext(client: MarmotClient): ClientContext;
|
|
1071
|
+
export declare const BUDGET_NUMERIC_FIELDS: readonly ["concurrency", "minSpacingMs", "timeoutMs", "leaseMs"];
|
|
1072
|
+
export declare function createMarmotClient(options: MarmotClientOptions): MarmotClient;
|
|
1073
|
+
/** What {@link createMarmotClientWith} takes beyond the public options — never reachable from the package root. */
|
|
1074
|
+
export interface InternalClientOptions {
|
|
1075
|
+
/**
|
|
1076
|
+
* Rewrites the seams every engine of this client is built with — how a
|
|
1077
|
+
* test builds a client on the engine defaults to prove that a seam is
|
|
1078
|
+
* load-bearing (AC-ADMIN-8, AC-ADMIN-9).
|
|
1079
|
+
*/
|
|
1080
|
+
readonly engineSeams?: EngineSeamsOverride;
|
|
1081
|
+
/**
|
|
1082
|
+
* Extra options every engine of this client is built with, spread over marmot's own (never over `removal` or
|
|
1083
|
+
* `opaque`, the persisted records) — how a test chooses an engine option marmot does not expose (the OQ-1 hidden-credit
|
|
1084
|
+
* policy, or the opaque seam switched off). The opt-in itself is the one literal in `group-runtime.ts`, never an option.
|
|
1085
|
+
*/
|
|
1086
|
+
readonly engineOptions?: Partial<MarmotGroupEngineOptions<NostrEvent>>;
|
|
1087
|
+
/**
|
|
1088
|
+
* `false` skips finishing an interrupted purge before a Welcome's group is adopted — ONLY for the negative
|
|
1089
|
+
* control that shows why it is there (a resumed purge would delete the re-joined group). Default `true`.
|
|
1090
|
+
*/
|
|
1091
|
+
readonly finishPurgeBeforeJoin?: boolean;
|
|
1092
|
+
/** Internal (tests only): the history backend call timeout; default {@link HISTORY_BACKEND_TIMEOUT_MS}. */
|
|
1093
|
+
readonly historyBackendTimeoutMs?: number;
|
|
1094
|
+
/**
|
|
1095
|
+
* Internal (tests only), AC-RACE-3's negative control: `true` disables every drive of a re-enqueued
|
|
1096
|
+
* self-update (`driveReenqueuedSelfUpdate`, reached from the scheduled drive and from `resumePending`) — the withdrawn self-update's re-enqueued record is still written atomically
|
|
1097
|
+
* (group-history.ts `recordTransition`; that durability cannot be disabled from outside), but nothing
|
|
1098
|
+
* ever drives it, reproducing the pre-AC-RACE-1 symptom (the rotation never lands on the winning branch,
|
|
1099
|
+
* and no `intentFailed` is ever reported either — it is simply stuck, the "silently lost" bug this story
|
|
1100
|
+
* fixes). Default `false`.
|
|
1101
|
+
*/
|
|
1102
|
+
readonly disableSelfUpdateReenqueueForTest?: boolean;
|
|
1103
|
+
/**
|
|
1104
|
+
* Tests only: a successful `groups.restore` owes no device-key rotation (owner decision 13), for suites that count the
|
|
1105
|
+
* signer calls and relay events of a restore and are not about the rotation.
|
|
1106
|
+
*/
|
|
1107
|
+
readonly disableRestoreRotationForTest?: boolean;
|
|
1108
|
+
/**
|
|
1109
|
+
* Internal (tests only), AC-RATCH-1/3's negative control: `true` never asks the engine for the post-load ratchet
|
|
1110
|
+
* skip, so the first own application message after a load uses the restored state's next generation (the
|
|
1111
|
+
* behaviour before AC-RATCH-1). Default `false`.
|
|
1112
|
+
*/
|
|
1113
|
+
readonly disableRatchetSkipForTest?: boolean;
|
|
1114
|
+
/**
|
|
1115
|
+
* Internal (tests only), the negative controls of epic marmot-rewound-own-commit-no-signal's integration properties
|
|
1116
|
+
* (AC-PROP-2 (b), AC-PROP-4): each flag reintroduces ONE defect the corresponding property exists to catch. Absent: no effect.
|
|
1117
|
+
*/
|
|
1118
|
+
readonly redriveFaultsForTest?: RedriveFaultsForTest;
|
|
1119
|
+
/**
|
|
1120
|
+
* Internal (tests only), a mutation-gate test seam: called once at client construction with a read-only lookup
|
|
1121
|
+
* of the live per-group runtimes, so a test can drive pipeline internals on a real runtime. Absent: no effect.
|
|
1122
|
+
*/
|
|
1123
|
+
readonly exposeRuntimesForTest?: (get: (groupId: string) => GroupRuntime | undefined) => void;
|
|
1124
|
+
}
|
|
1125
|
+
/** Internal (tests only): `createMarmotClient` with {@link InternalClientOptions}. */
|
|
1126
|
+
export declare function createMarmotClientWith(options: MarmotClientOptions, internal: InternalClientOptions): MarmotClient;
|