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