@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,270 @@
|
|
|
1
|
+
import { type ClientState } from '@941design/marmot-engine/mls';
|
|
2
|
+
import type { Rumor } from '@941design/nostr-events/event';
|
|
3
|
+
import type { OwnChangeLostNotification, OwnChangeReappliedNotification, OwnChangeWithdrawnNotification } from './own-change.js';
|
|
4
|
+
import { type RetainedWindow } from './retained-window.js';
|
|
5
|
+
/** Per-message ordering key (AC-HIST-1). */
|
|
6
|
+
export interface OrderingKey {
|
|
7
|
+
/** The MLS-authenticated sender's account (its leaf credential identity). */
|
|
8
|
+
readonly account: string;
|
|
9
|
+
readonly leafIndex: number;
|
|
10
|
+
/** Epoch the message was encrypted under. */
|
|
11
|
+
readonly epoch: bigint;
|
|
12
|
+
/** The sender's application-ratchet generation (from the decrypted MLS sender data); -1 when it could not be read. */
|
|
13
|
+
readonly generation: number;
|
|
14
|
+
/**
|
|
15
|
+
* The accepted branch the message was delivered on: the hex MLS
|
|
16
|
+
* confirmation tag of the epoch state it decrypted under. A rewind that
|
|
17
|
+
* abandons that state withdraws the message (`message-withdrawn`).
|
|
18
|
+
*/
|
|
19
|
+
readonly acceptedDigest: string;
|
|
20
|
+
}
|
|
21
|
+
/** A state change a commit produced, keyed by the hex digest of that commit. */
|
|
22
|
+
export interface AppliedNotification {
|
|
23
|
+
readonly type: 'applied';
|
|
24
|
+
readonly commitDigest: string;
|
|
25
|
+
readonly kind: string;
|
|
26
|
+
}
|
|
27
|
+
/** A rewind superseded the commit `commitDigest`: each of its applied notifications, withdrawn (same digest and kind). */
|
|
28
|
+
export interface WithdrawnNotification {
|
|
29
|
+
readonly type: 'withdrawn';
|
|
30
|
+
readonly commitDigest: string;
|
|
31
|
+
readonly kind: string;
|
|
32
|
+
}
|
|
33
|
+
/** An accepted application message, live (AC-HIST-3: with or without a history backend). */
|
|
34
|
+
export interface MessageNotification {
|
|
35
|
+
readonly type: 'message';
|
|
36
|
+
/** The id of the kind-445 event that carried the message — not the rumor's id (`rumor.id`). */
|
|
37
|
+
readonly eventId: string;
|
|
38
|
+
readonly rumor: Rumor;
|
|
39
|
+
readonly orderingKey: OrderingKey;
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* A message delivered on a branch a rewind abandoned: it no longer belongs to
|
|
43
|
+
* the group's history. Also sent, once, for an OWN message whose send-time
|
|
44
|
+
* branch was abandoned before its publish was confirmed — never announced as
|
|
45
|
+
* `message`, though its `send()` may have resolved: no member can read it,
|
|
46
|
+
* and the application may send it again.
|
|
47
|
+
*/
|
|
48
|
+
export interface MessageWithdrawnNotification {
|
|
49
|
+
readonly type: 'message-withdrawn';
|
|
50
|
+
/** The kind-445 event id `message` announced (not the rumor's id). */
|
|
51
|
+
readonly eventId: string;
|
|
52
|
+
readonly acceptedDigest: string;
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* Branch selection found cryptographic evidence that one leaf authored two or more distinct commits from the same
|
|
56
|
+
* parent state (a direct equivocation, ADR-016): typically a restored stale snapshot of that leaf committing next to
|
|
57
|
+
* its real device. Announced once per `(nodeTag, leafIndex)` and group, after its record is durable — never again for
|
|
58
|
+
* the same evidence, across reloads. Informational: the group's branch selection has already run, and nothing is
|
|
59
|
+
* removed automatically (removing the leaf is an admin decision).
|
|
60
|
+
*/
|
|
61
|
+
export interface LeafEquivocationNotification {
|
|
62
|
+
readonly type: 'leaf-equivocation';
|
|
63
|
+
/** The equivocating leaf at the node. */
|
|
64
|
+
readonly leafIndex: number;
|
|
65
|
+
/** Hex account identity (credential pubkey) of that leaf at the node. */
|
|
66
|
+
readonly account: string;
|
|
67
|
+
/** Hex leaf signature key of that leaf at the node. */
|
|
68
|
+
readonly leafKey: string;
|
|
69
|
+
/** The node's MLS epoch (the parent epoch of the conflicting commits). */
|
|
70
|
+
readonly epoch: bigint;
|
|
71
|
+
/** Hex MLS confirmation tag of the node (the parent state of the conflicting commits). */
|
|
72
|
+
readonly nodeTag: string;
|
|
73
|
+
/** Hex digests of the leaf's conflicting child commits at the node: two or more, ascending. */
|
|
74
|
+
readonly commitDigests: readonly string[];
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* A commit on the canonical path removed one leaf (BACKLOG `marmot-leaf-removed-notification`): one notification per
|
|
78
|
+
* removed leaf, naming its account — unlike the engine's `memberRemoved` kind, which fires only when an account's
|
|
79
|
+
* LAST leaf leaves. So a same-account leaf removal (a sibling device forgotten) is visible as such. Emitted with the
|
|
80
|
+
* commit's `applied` notifications; a rewind that supersedes the commit emits `leaf-removal-withdrawn` for it.
|
|
81
|
+
*/
|
|
82
|
+
export interface LeafRemovedNotification {
|
|
83
|
+
readonly type: 'leaf-removed';
|
|
84
|
+
/** Hex digest of the removing commit (as its `applied` notifications carry it). */
|
|
85
|
+
readonly commitDigest: string;
|
|
86
|
+
/** Hex account identity (credential pubkey) of the removed leaf, at the commit's parent state. */
|
|
87
|
+
readonly account: string;
|
|
88
|
+
/** The removed leaf's index at the parent state. */
|
|
89
|
+
readonly leafIndex: number;
|
|
90
|
+
/** Hex leaf signature key of the removed leaf. */
|
|
91
|
+
readonly leafKey: string;
|
|
92
|
+
}
|
|
93
|
+
/** A rewind superseded the commit that removed this leaf: its `leaf-removed`, withdrawn (same fields). */
|
|
94
|
+
export interface LeafRemovalWithdrawnNotification {
|
|
95
|
+
readonly type: 'leaf-removal-withdrawn';
|
|
96
|
+
readonly commitDigest: string;
|
|
97
|
+
readonly account: string;
|
|
98
|
+
readonly leafIndex: number;
|
|
99
|
+
readonly leafKey: string;
|
|
100
|
+
}
|
|
101
|
+
/**
|
|
102
|
+
* A commit on the canonical path replaced the signature key of one leaf in place (a device key rotation): the leaf keeps its index and account and holds `toLeafKey` where it held `fromLeafKey`.
|
|
103
|
+
* One notification per rotated leaf, with the commit's `applied` ones, and never a `leaf-removed` for it. A rewind that
|
|
104
|
+
* supersedes the commit emits `leaf-key-rotation-withdrawn`; the notification is delivered again if the commit rejoins
|
|
105
|
+
* the canonical path.
|
|
106
|
+
*/
|
|
107
|
+
export interface LeafKeyRotatedNotification {
|
|
108
|
+
readonly type: 'leaf-key-rotated';
|
|
109
|
+
/** Hex account identity (credential pubkey) of the rotated leaf (unchanged by the rotation). */
|
|
110
|
+
readonly account: string;
|
|
111
|
+
/** The rotated leaf's index (the same before and after). */
|
|
112
|
+
readonly leafIndex: number;
|
|
113
|
+
/** Hex leaf signature key the leaf held at the commit's parent state. */
|
|
114
|
+
readonly fromLeafKey: string;
|
|
115
|
+
/** Hex leaf signature key the leaf holds after the commit. */
|
|
116
|
+
readonly toLeafKey: string;
|
|
117
|
+
/** Hex digest of the rotating commit (as its `applied` notifications carry it). */
|
|
118
|
+
readonly commitDigest: string;
|
|
119
|
+
}
|
|
120
|
+
/** A rewind superseded the commit that rotated this leaf's key: its `leaf-key-rotated`, withdrawn (same fields). */
|
|
121
|
+
export interface LeafKeyRotationWithdrawnNotification {
|
|
122
|
+
readonly type: 'leaf-key-rotation-withdrawn';
|
|
123
|
+
readonly account: string;
|
|
124
|
+
readonly leafIndex: number;
|
|
125
|
+
readonly fromLeafKey: string;
|
|
126
|
+
readonly toLeafKey: string;
|
|
127
|
+
readonly commitDigest: string;
|
|
128
|
+
}
|
|
129
|
+
/**
|
|
130
|
+
* A commit on the canonical path added a leaf of the LOCAL account (a `key_package`-source leaf) whose signature key the
|
|
131
|
+
* local device registry holds as a retired, non-head key of its lineage: a key rotated away from came back (a sibling or
|
|
132
|
+
* an old KeyPackage re-admitted it). Detection only: the commit is applied as any other, nothing is refused. Never
|
|
133
|
+
* emitted for an unknown key or for the head key. Not withdrawn by a rewind.
|
|
134
|
+
*/
|
|
135
|
+
export interface RetiredKeyReaddedNotification {
|
|
136
|
+
readonly type: 'retired-key-readded';
|
|
137
|
+
/** Hex account identity of the re-added leaf (the local account). */
|
|
138
|
+
readonly account: string;
|
|
139
|
+
readonly leafIndex: number;
|
|
140
|
+
/** Hex leaf signature key of the re-added leaf: a retired key of the local account's lineage. */
|
|
141
|
+
readonly leafKey: string;
|
|
142
|
+
/** Hex digest of the commit that added it. */
|
|
143
|
+
readonly commitDigest: string;
|
|
144
|
+
}
|
|
145
|
+
/**
|
|
146
|
+
* A peer's terminal disband commit (`group-lifecycle-v1`) was selected by the convergence settlement
|
|
147
|
+
* (BACKLOG `marmot-disband-settled-store-divergence`): the group is over. Emitted once, after the disband marker was
|
|
148
|
+
* persisted; the same fields stay readable as `MarmotGroup.disbanded` (also after a reload). Never withdrawn.
|
|
149
|
+
*/
|
|
150
|
+
export interface GroupDisbandedNotification {
|
|
151
|
+
readonly type: 'group-disbanded';
|
|
152
|
+
/** Hex account identity of the admin whose disband commit was selected. */
|
|
153
|
+
readonly actor: string;
|
|
154
|
+
/** The MLS epoch the disband commit was made at (its parent's epoch). */
|
|
155
|
+
readonly epoch: bigint;
|
|
156
|
+
/** Hex MLS confirmation tag of that parent state. */
|
|
157
|
+
readonly nodeTag: string;
|
|
158
|
+
/** Hex digest of the selected disband commit. */
|
|
159
|
+
readonly commitDigest: string;
|
|
160
|
+
}
|
|
161
|
+
export type GroupNotification = AppliedNotification | GroupDisbandedNotification | WithdrawnNotification | MessageNotification | MessageWithdrawnNotification | LeafEquivocationNotification | LeafRemovedNotification | LeafRemovalWithdrawnNotification | LeafKeyRotatedNotification | LeafKeyRotationWithdrawnNotification | RetiredKeyReaddedNotification | OwnChangeWithdrawnNotification | OwnChangeReappliedNotification | OwnChangeLostNotification;
|
|
162
|
+
/** The state changes of one commit, parent → child. */
|
|
163
|
+
export declare function commitNotifications(parent: ClientState, child: ClientState, digest: Uint8Array): {
|
|
164
|
+
readonly commitDigest: string;
|
|
165
|
+
readonly kind: string;
|
|
166
|
+
}[];
|
|
167
|
+
/**
|
|
168
|
+
* The leaves one commit removed, parent → child: a leaf whose signature key is on no leaf of the child state — except
|
|
169
|
+
* where the leaf replaced its own key in place (`leafKeySuccessions` reports its index: a key rotation or an update,
|
|
170
|
+
* not a removal). A Remove plus an Add of the same account at one index IS a removal: the child leaf came from a
|
|
171
|
+
* KeyPackage, which is no succession. Leaves without a readable account are skipped (no notification can name them).
|
|
172
|
+
* `leaf-removed` means a signature key left the group: a leaf whose key is still on some leaf of `child` is no removal,
|
|
173
|
+
* wherever that leaf sits. So a duplicate-leaf repair commit (leaf i rotates to key T and the same commit removes the
|
|
174
|
+
* stray same-account leaf that held T) names no removal for the stray leaf — the device's live key T stays — and the
|
|
175
|
+
* rotation of i is reported by {@link rotatedLeaves}.
|
|
176
|
+
* `child` must be exactly one commit after `parent`. Never throws.
|
|
177
|
+
*/
|
|
178
|
+
export declare function removedLeaves(parent: ClientState, child: ClientState): {
|
|
179
|
+
readonly account: string;
|
|
180
|
+
readonly leafIndex: number;
|
|
181
|
+
readonly leafKey: string;
|
|
182
|
+
}[];
|
|
183
|
+
/** One signature-key replacement a commit made, parent → child (see {@link rotatedLeaves}). */
|
|
184
|
+
export interface RotatedLeaf {
|
|
185
|
+
readonly account: string;
|
|
186
|
+
readonly leafIndex: number;
|
|
187
|
+
readonly fromLeafKey: string;
|
|
188
|
+
readonly toLeafKey: string;
|
|
189
|
+
}
|
|
190
|
+
/**
|
|
191
|
+
* The leaves that replaced their signature key in place between `parent` and `child`, ordered by leaf index: the
|
|
192
|
+
* engine's `leafKeySuccessions` (same account, same index, a different key, the child leaf written by the leaf itself)
|
|
193
|
+
* as `{ account, leafIndex, fromLeafKey, toLeafKey }`. A leaf whose account identity is not a valid x-only secp256k1
|
|
194
|
+
* key (the predicate reads only the bytes, not the curve) is never reported.
|
|
195
|
+
* `child` must be exactly one commit after `parent`: apply this per edge of a window, never to a tip pair (over a gap a
|
|
196
|
+
* Remove plus re-Add followed by a self-update reads as a rotation). Never throws.
|
|
197
|
+
*/
|
|
198
|
+
export declare function rotatedLeaves(parent: ClientState, child: ClientState): RotatedLeaf[];
|
|
199
|
+
/**
|
|
200
|
+
* The `key_package`-source leaves one commit added whose key `isRetiredKey(account, leafKey)` reports as a retired,
|
|
201
|
+
* non-head key of the local account's lineage — a retired key coming back. A leaf whose key is already on
|
|
202
|
+
* a leaf of `parent` is no Add. The predicate holds the local registry (this module does not) and decides which accounts
|
|
203
|
+
* and keys count: an unknown key, the head key and every other account answer `false`. Never throws, also when the
|
|
204
|
+
* predicate does.
|
|
205
|
+
*/
|
|
206
|
+
export declare function retiredKeyReadds(parent: ClientState, child: ClientState, isRetiredKey: (account: string, leafKey: string) => boolean): {
|
|
207
|
+
readonly account: string;
|
|
208
|
+
readonly leafIndex: number;
|
|
209
|
+
readonly leafKey: string;
|
|
210
|
+
}[];
|
|
211
|
+
export interface LeafTransitionOptions {
|
|
212
|
+
/**
|
|
213
|
+
* Whether `leafKey` is a retired, non-head key of the local account's lineage. Absent: no
|
|
214
|
+
* `retired-key-readded` is produced.
|
|
215
|
+
*/
|
|
216
|
+
readonly isRetiredKey?: (account: string, leafKey: string) => boolean;
|
|
217
|
+
}
|
|
218
|
+
/**
|
|
219
|
+
* The per-leaf changes moving the group from `before` to `after` applied and withdrew, over the same canonical-path
|
|
220
|
+
* nodes as {@link windowTransition}'s `applied` / `withdrawn`, oldest node first, each node judged on its own
|
|
221
|
+
* parent → child edge:
|
|
222
|
+
* - `applied` (commits that joined the path): `leaf-removed` per removed leaf, `leaf-key-rotated`
|
|
223
|
+
* per leaf that replaced its key in place, and — only with `options.isRetiredKey` — `retired-key-readded` per
|
|
224
|
+
* re-added retired key;
|
|
225
|
+
* - `withdrawn` (commits that left the path): `leaf-removal-withdrawn` and `leaf-key-rotation-withdrawn`, with the
|
|
226
|
+
* fields they were applied with. A `retired-key-readded` is never withdrawn.
|
|
227
|
+
* A commit that rejoins the path is applied again, so its rotation is delivered again.
|
|
228
|
+
*
|
|
229
|
+
* The returned arrays carry the leaf removals, the rotations and the retired-key re-adds alike: the caller spreads them
|
|
230
|
+
* into the transition's notifications as they are.
|
|
231
|
+
*/
|
|
232
|
+
export declare function leafTransition(before: RetainedWindow, beforeTip: ClientState, after: RetainedWindow, afterTip: ClientState, options?: LeafTransitionOptions): {
|
|
233
|
+
readonly applied: readonly (LeafRemovedNotification | LeafKeyRotatedNotification | RetiredKeyReaddedNotification)[];
|
|
234
|
+
readonly withdrawn: readonly (LeafRemovalWithdrawnNotification | LeafKeyRotationWithdrawnNotification)[];
|
|
235
|
+
};
|
|
236
|
+
/** One signature-key succession on the canonical path of a retained window (see {@link successionsInWindow}). */
|
|
237
|
+
export interface WindowSuccession extends RotatedLeaf {
|
|
238
|
+
/** Hex digest of the commit that made it. */
|
|
239
|
+
readonly commitDigest: string;
|
|
240
|
+
/** The group's id (its hex MLS group id): `MarmotGroup.id`. */
|
|
241
|
+
readonly groupId: string;
|
|
242
|
+
}
|
|
243
|
+
/**
|
|
244
|
+
* The signature-key successions on the window's canonical path, oldest first (within one commit, by leaf index): the
|
|
245
|
+
* concatenation of {@link rotatedLeaves} over every consecutive pair of canonical-path states, each with its commit
|
|
246
|
+
* digest and the group id. Nodes on abandoned fork branches contribute nothing. An edge whose parent or child state the
|
|
247
|
+
* window no longer holds (a root, a pruned snapshot, a cut link) contributes nothing: the feed is what the window can
|
|
248
|
+
* show, not a complete history. Never throws.
|
|
249
|
+
*/
|
|
250
|
+
export declare function successionsInWindow(window: RetainedWindow, tipState: ClientState): WindowSuccession[];
|
|
251
|
+
/**
|
|
252
|
+
* The signature-key successions the window shows on nodes OFF the canonical path (a rewind abandoned them), each judged on
|
|
253
|
+
* its own parent -> child edge like {@link successionsInWindow}'s: a rotation a fork carried and the canonical path does not.
|
|
254
|
+
* An edge whose parent or child state the window no longer holds contributes nothing. Order: unspecified. Never throws.
|
|
255
|
+
*/
|
|
256
|
+
export declare function abandonedSuccessionsInWindow(window: RetainedWindow, tipState: ClientState): RotatedLeaf[];
|
|
257
|
+
export interface WindowTransition {
|
|
258
|
+
/** Notifications of commits that left the canonical path (oldest first). */
|
|
259
|
+
readonly withdrawn: readonly WithdrawnNotification[];
|
|
260
|
+
/** Notifications of commits that joined it (oldest first). */
|
|
261
|
+
readonly applied: readonly AppliedNotification[];
|
|
262
|
+
/** Canonical states before the transition that are not canonical after it: messages delivered under them are withdrawn. */
|
|
263
|
+
readonly abandonedTags: readonly string[];
|
|
264
|
+
}
|
|
265
|
+
/**
|
|
266
|
+
* What moving the group from `before` (tip state `beforeTip`) to `after` (tip
|
|
267
|
+
* state `afterTip`) applied and withdrew. Only nodes both windows can name
|
|
268
|
+
* count: a commit pruned below the horizon is neither applied nor withdrawn.
|
|
269
|
+
*/
|
|
270
|
+
export declare function windowTransition(before: RetainedWindow, beforeTip: ClientState, after: RetainedWindow, afterTip: ClientState): WindowTransition;
|
|
@@ -0,0 +1,264 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Applied-change notifications keyed by commit digest, and their withdrawal
|
|
3
|
+
* on a rewind (AC-HIST-2), derived from the persisted rewind window rather
|
|
4
|
+
* than from the engine's in-memory notification ledger.
|
|
5
|
+
*
|
|
6
|
+
* The engine's ledger is lost with every rebuilt engine (a reload, a
|
|
7
|
+
* rollback), so a rewind after one withdrew nothing it had not itself
|
|
8
|
+
* recorded. Here, every persisted transition of a group compares the
|
|
9
|
+
* canonical path before and after it: a commit that left the canonical path
|
|
10
|
+
* is withdrawn, one that joined it is applied — each diffed parent → child
|
|
11
|
+
* with the engine's own `deriveStateNotifications`, so a withdrawal carries
|
|
12
|
+
* exactly the commit digest (and the kinds) its applied notifications did.
|
|
13
|
+
*/
|
|
14
|
+
import { deserializeClientState, getCredentialPubkey, getGroupIdHex, isValidAccountIdentity, leafKeySuccessions } from '@941design/marmot-engine/core';
|
|
15
|
+
import { deriveStateNotifications } from '@941design/marmot-engine/engine';
|
|
16
|
+
import { leafNodeSources, nodeTypes } from '@941design/marmot-engine/mls';
|
|
17
|
+
import { hexOf, hexToBytes } from './hex.js';
|
|
18
|
+
import { canonicalPath } from './retained-window.js';
|
|
19
|
+
/** The state changes of one commit, parent → child. */
|
|
20
|
+
export function commitNotifications(parent, child, digest) {
|
|
21
|
+
try {
|
|
22
|
+
return deriveStateNotifications({ parentState: parent, resultingState: child, commitDigest: digest }).map((n) => ({ commitDigest: hexOf(n.commitDigest), kind: n.kind }));
|
|
23
|
+
}
|
|
24
|
+
catch {
|
|
25
|
+
// A leaf whose identity is not a valid key: the engine logs and skips such a derivation too.
|
|
26
|
+
return [];
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
function stateOf(window, tipState, node) {
|
|
30
|
+
if (node === undefined)
|
|
31
|
+
return undefined;
|
|
32
|
+
if (node.tag === window.tipTag)
|
|
33
|
+
return tipState;
|
|
34
|
+
return node.snapshot === undefined ? undefined : deserializeClientState(node.snapshot);
|
|
35
|
+
}
|
|
36
|
+
function linkNotifications(window, tipState, node) {
|
|
37
|
+
if (node.digest === undefined || node.parentTag === undefined)
|
|
38
|
+
return [];
|
|
39
|
+
const parent = stateOf(window, tipState, window.nodes.get(node.parentTag));
|
|
40
|
+
const child = stateOf(window, tipState, node);
|
|
41
|
+
if (parent === undefined || child === undefined)
|
|
42
|
+
return [];
|
|
43
|
+
return commitNotifications(parent, child, hexToBytes(node.digest));
|
|
44
|
+
}
|
|
45
|
+
function leavesOf(state) {
|
|
46
|
+
const out = [];
|
|
47
|
+
for (let i = 0; i < state.ratchetTree.length; i += 2) {
|
|
48
|
+
const node = state.ratchetTree[i];
|
|
49
|
+
if (node?.nodeType !== nodeTypes.leaf)
|
|
50
|
+
continue;
|
|
51
|
+
let account;
|
|
52
|
+
try {
|
|
53
|
+
account = getCredentialPubkey(node.leaf.credential);
|
|
54
|
+
}
|
|
55
|
+
catch {
|
|
56
|
+
account = undefined;
|
|
57
|
+
}
|
|
58
|
+
out.push({ leafIndex: i / 2, leafKey: hexOf(node.leaf.signaturePublicKey), account, fromKeyPackage: node.leaf.leafNodeSource === leafNodeSources.key_package });
|
|
59
|
+
}
|
|
60
|
+
return out;
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* The leaves one commit removed, parent → child: a leaf whose signature key is on no leaf of the child state — except
|
|
64
|
+
* where the leaf replaced its own key in place (`leafKeySuccessions` reports its index: a key rotation or an update,
|
|
65
|
+
* not a removal). A Remove plus an Add of the same account at one index IS a removal: the child leaf came from a
|
|
66
|
+
* KeyPackage, which is no succession. Leaves without a readable account are skipped (no notification can name them).
|
|
67
|
+
* `leaf-removed` means a signature key left the group: a leaf whose key is still on some leaf of `child` is no removal,
|
|
68
|
+
* wherever that leaf sits. So a duplicate-leaf repair commit (leaf i rotates to key T and the same commit removes the
|
|
69
|
+
* stray same-account leaf that held T) names no removal for the stray leaf — the device's live key T stays — and the
|
|
70
|
+
* rotation of i is reported by {@link rotatedLeaves}.
|
|
71
|
+
* `child` must be exactly one commit after `parent`. Never throws.
|
|
72
|
+
*/
|
|
73
|
+
export function removedLeaves(parent, child) {
|
|
74
|
+
try {
|
|
75
|
+
const keys = new Set(leavesOf(child).map((l) => l.leafKey));
|
|
76
|
+
const replacedInPlace = new Set(leafKeySuccessions(parent, child).map((s) => s.leafIndex));
|
|
77
|
+
const out = [];
|
|
78
|
+
for (const leaf of leavesOf(parent)) {
|
|
79
|
+
if (leaf.account === undefined || keys.has(leaf.leafKey) || replacedInPlace.has(leaf.leafIndex))
|
|
80
|
+
continue;
|
|
81
|
+
out.push({ account: leaf.account, leafIndex: leaf.leafIndex, leafKey: leaf.leafKey });
|
|
82
|
+
}
|
|
83
|
+
return out;
|
|
84
|
+
}
|
|
85
|
+
catch {
|
|
86
|
+
return [];
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
/**
|
|
90
|
+
* The leaves that replaced their signature key in place between `parent` and `child`, ordered by leaf index: the
|
|
91
|
+
* engine's `leafKeySuccessions` (same account, same index, a different key, the child leaf written by the leaf itself)
|
|
92
|
+
* as `{ account, leafIndex, fromLeafKey, toLeafKey }`. A leaf whose account identity is not a valid x-only secp256k1
|
|
93
|
+
* key (the predicate reads only the bytes, not the curve) is never reported.
|
|
94
|
+
* `child` must be exactly one commit after `parent`: apply this per edge of a window, never to a tip pair (over a gap a
|
|
95
|
+
* Remove plus re-Add followed by a self-update reads as a rotation). Never throws.
|
|
96
|
+
*/
|
|
97
|
+
export function rotatedLeaves(parent, child) {
|
|
98
|
+
try {
|
|
99
|
+
return leafKeySuccessions(parent, child)
|
|
100
|
+
.filter((s) => isValidAccountIdentity(hexToBytes(s.account)))
|
|
101
|
+
.map((s) => ({ account: s.account, leafIndex: s.leafIndex, fromLeafKey: s.fromKey, toLeafKey: s.toKey }));
|
|
102
|
+
}
|
|
103
|
+
catch {
|
|
104
|
+
return [];
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
/**
|
|
108
|
+
* The `key_package`-source leaves one commit added whose key `isRetiredKey(account, leafKey)` reports as a retired,
|
|
109
|
+
* non-head key of the local account's lineage — a retired key coming back. A leaf whose key is already on
|
|
110
|
+
* a leaf of `parent` is no Add. The predicate holds the local registry (this module does not) and decides which accounts
|
|
111
|
+
* and keys count: an unknown key, the head key and every other account answer `false`. Never throws, also when the
|
|
112
|
+
* predicate does.
|
|
113
|
+
*/
|
|
114
|
+
export function retiredKeyReadds(parent, child, isRetiredKey) {
|
|
115
|
+
try {
|
|
116
|
+
const before = new Set(leavesOf(parent).map((l) => l.leafKey));
|
|
117
|
+
const out = [];
|
|
118
|
+
for (const leaf of leavesOf(child)) {
|
|
119
|
+
if (leaf.account === undefined || !leaf.fromKeyPackage || before.has(leaf.leafKey))
|
|
120
|
+
continue;
|
|
121
|
+
if (isRetiredKey(leaf.account, leaf.leafKey))
|
|
122
|
+
out.push({ account: leaf.account, leafIndex: leaf.leafIndex, leafKey: leaf.leafKey });
|
|
123
|
+
}
|
|
124
|
+
return out;
|
|
125
|
+
}
|
|
126
|
+
catch {
|
|
127
|
+
return [];
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
/** The parent → child states of the commit `node` stands for, when the window holds both. */
|
|
131
|
+
function linkEdge(window, tipState, node) {
|
|
132
|
+
if (node.digest === undefined || node.parentTag === undefined)
|
|
133
|
+
return undefined;
|
|
134
|
+
const parent = stateOf(window, tipState, window.nodes.get(node.parentTag));
|
|
135
|
+
const child = stateOf(window, tipState, node);
|
|
136
|
+
if (parent === undefined || child === undefined)
|
|
137
|
+
return undefined;
|
|
138
|
+
return { commitDigest: node.digest, parent, child };
|
|
139
|
+
}
|
|
140
|
+
const removalsOf = (edge) => removedLeaves(edge.parent, edge.child).map((leaf) => ({ commitDigest: edge.commitDigest, ...leaf }));
|
|
141
|
+
const rotationsOf = (edge) => rotatedLeaves(edge.parent, edge.child).map((leaf) => ({ commitDigest: edge.commitDigest, ...leaf }));
|
|
142
|
+
/** The canonical-path nodes a transition from `before` to `after` drops (oldest first) and adds (oldest first). */
|
|
143
|
+
function pathChange(before, after) {
|
|
144
|
+
const beforePath = canonicalPath(before);
|
|
145
|
+
const afterPath = canonicalPath(after);
|
|
146
|
+
const afterTags = new Set(afterPath.map((n) => n.tag));
|
|
147
|
+
const beforeTags = new Set(beforePath.map((n) => n.tag));
|
|
148
|
+
// Below the new window's floor: pruned, not abandoned.
|
|
149
|
+
const floor = afterPath[0]?.epoch ?? 0;
|
|
150
|
+
const left = beforePath.filter((node) => !afterTags.has(node.tag) && node.epoch >= floor);
|
|
151
|
+
const joined = afterPath.filter((node) => !beforeTags.has(node.tag) && node.parentTag !== undefined);
|
|
152
|
+
return { left, joined };
|
|
153
|
+
}
|
|
154
|
+
/**
|
|
155
|
+
* The per-leaf changes moving the group from `before` to `after` applied and withdrew, over the same canonical-path
|
|
156
|
+
* nodes as {@link windowTransition}'s `applied` / `withdrawn`, oldest node first, each node judged on its own
|
|
157
|
+
* parent → child edge:
|
|
158
|
+
* - `applied` (commits that joined the path): `leaf-removed` per removed leaf, `leaf-key-rotated`
|
|
159
|
+
* per leaf that replaced its key in place, and — only with `options.isRetiredKey` — `retired-key-readded` per
|
|
160
|
+
* re-added retired key;
|
|
161
|
+
* - `withdrawn` (commits that left the path): `leaf-removal-withdrawn` and `leaf-key-rotation-withdrawn`, with the
|
|
162
|
+
* fields they were applied with. A `retired-key-readded` is never withdrawn.
|
|
163
|
+
* A commit that rejoins the path is applied again, so its rotation is delivered again.
|
|
164
|
+
*
|
|
165
|
+
* The returned arrays carry the leaf removals, the rotations and the retired-key re-adds alike: the caller spreads them
|
|
166
|
+
* into the transition's notifications as they are.
|
|
167
|
+
*/
|
|
168
|
+
export function leafTransition(before, beforeTip, after, afterTip, options = {}) {
|
|
169
|
+
const { left, joined } = pathChange(before, after);
|
|
170
|
+
// One edge (two state loads at most) per node, whatever the extractors.
|
|
171
|
+
const withdrawn = left.flatMap((node) => {
|
|
172
|
+
const edge = linkEdge(before, beforeTip, node);
|
|
173
|
+
if (edge === undefined)
|
|
174
|
+
return [];
|
|
175
|
+
return [
|
|
176
|
+
...removalsOf(edge).map((r) => ({ type: 'leaf-removal-withdrawn', ...r })),
|
|
177
|
+
...rotationsOf(edge).map((r) => ({ type: 'leaf-key-rotation-withdrawn', ...r })),
|
|
178
|
+
];
|
|
179
|
+
});
|
|
180
|
+
const { isRetiredKey } = options;
|
|
181
|
+
const applied = joined.flatMap((node) => {
|
|
182
|
+
const edge = linkEdge(after, afterTip, node);
|
|
183
|
+
if (edge === undefined)
|
|
184
|
+
return [];
|
|
185
|
+
return [
|
|
186
|
+
...removalsOf(edge).map((r) => ({ type: 'leaf-removed', ...r })),
|
|
187
|
+
...rotationsOf(edge).map((r) => ({ type: 'leaf-key-rotated', ...r })),
|
|
188
|
+
...(isRetiredKey === undefined ? [] : retiredKeyReadds(edge.parent, edge.child, isRetiredKey).map((r) => ({ type: 'retired-key-readded', commitDigest: edge.commitDigest, ...r }))),
|
|
189
|
+
];
|
|
190
|
+
});
|
|
191
|
+
return { applied, withdrawn };
|
|
192
|
+
}
|
|
193
|
+
/**
|
|
194
|
+
* The signature-key successions on the window's canonical path, oldest first (within one commit, by leaf index): the
|
|
195
|
+
* concatenation of {@link rotatedLeaves} over every consecutive pair of canonical-path states, each with its commit
|
|
196
|
+
* digest and the group id. Nodes on abandoned fork branches contribute nothing. An edge whose parent or child state the
|
|
197
|
+
* window no longer holds (a root, a pruned snapshot, a cut link) contributes nothing: the feed is what the window can
|
|
198
|
+
* show, not a complete history. Never throws.
|
|
199
|
+
*/
|
|
200
|
+
export function successionsInWindow(window, tipState) {
|
|
201
|
+
try {
|
|
202
|
+
const groupId = getGroupIdHex(tipState);
|
|
203
|
+
const out = [];
|
|
204
|
+
// The previous path node's state is the parent of the next one: each snapshot is deserialized once.
|
|
205
|
+
let previous;
|
|
206
|
+
for (const node of canonicalPath(window)) {
|
|
207
|
+
const state = stateOf(window, tipState, node);
|
|
208
|
+
if (node.digest !== undefined && node.parentTag !== undefined && state !== undefined) {
|
|
209
|
+
const parent = previous?.tag === node.parentTag ? previous.state : stateOf(window, tipState, window.nodes.get(node.parentTag));
|
|
210
|
+
if (parent !== undefined)
|
|
211
|
+
out.push(...rotationsOf({ commitDigest: node.digest, parent, child: state }).map((r) => ({ ...r, groupId })));
|
|
212
|
+
}
|
|
213
|
+
previous = { tag: node.tag, state };
|
|
214
|
+
}
|
|
215
|
+
return out;
|
|
216
|
+
}
|
|
217
|
+
catch {
|
|
218
|
+
return [];
|
|
219
|
+
}
|
|
220
|
+
}
|
|
221
|
+
/**
|
|
222
|
+
* The signature-key successions the window shows on nodes OFF the canonical path (a rewind abandoned them), each judged on
|
|
223
|
+
* its own parent -> child edge like {@link successionsInWindow}'s: a rotation a fork carried and the canonical path does not.
|
|
224
|
+
* An edge whose parent or child state the window no longer holds contributes nothing. Order: unspecified. Never throws.
|
|
225
|
+
*/
|
|
226
|
+
export function abandonedSuccessionsInWindow(window, tipState) {
|
|
227
|
+
try {
|
|
228
|
+
const onPath = new Set(canonicalPath(window).map((n) => n.tag));
|
|
229
|
+
const out = [];
|
|
230
|
+
for (const node of window.nodes.values()) {
|
|
231
|
+
if (onPath.has(node.tag) || node.digest === undefined || node.parentTag === undefined)
|
|
232
|
+
continue;
|
|
233
|
+
const parent = stateOf(window, tipState, window.nodes.get(node.parentTag));
|
|
234
|
+
const child = stateOf(window, tipState, node);
|
|
235
|
+
if (parent !== undefined && child !== undefined)
|
|
236
|
+
out.push(...rotatedLeaves(parent, child));
|
|
237
|
+
}
|
|
238
|
+
return out;
|
|
239
|
+
}
|
|
240
|
+
catch {
|
|
241
|
+
return [];
|
|
242
|
+
}
|
|
243
|
+
}
|
|
244
|
+
/**
|
|
245
|
+
* What moving the group from `before` (tip state `beforeTip`) to `after` (tip
|
|
246
|
+
* state `afterTip`) applied and withdrew. Only nodes both windows can name
|
|
247
|
+
* count: a commit pruned below the horizon is neither applied nor withdrawn.
|
|
248
|
+
*/
|
|
249
|
+
export function windowTransition(before, beforeTip, after, afterTip) {
|
|
250
|
+
const { left, joined } = pathChange(before, after);
|
|
251
|
+
const withdrawn = [];
|
|
252
|
+
const abandonedTags = [];
|
|
253
|
+
for (const node of left) {
|
|
254
|
+
abandonedTags.push(node.tag);
|
|
255
|
+
for (const n of linkNotifications(before, beforeTip, node))
|
|
256
|
+
withdrawn.push({ type: 'withdrawn', commitDigest: n.commitDigest, kind: n.kind });
|
|
257
|
+
}
|
|
258
|
+
const applied = [];
|
|
259
|
+
for (const node of joined) {
|
|
260
|
+
for (const n of linkNotifications(after, afterTip, node))
|
|
261
|
+
applied.push({ type: 'applied', commitDigest: n.commitDigest, kind: n.kind });
|
|
262
|
+
}
|
|
263
|
+
return { withdrawn, applied, abandonedTags };
|
|
264
|
+
}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import type { CiphersuiteImpl, ClientState, Credential, MlsMessage } from '@941design/marmot-engine/mls';
|
|
2
|
+
import type { OrderingKey } from './notifications.js';
|
|
3
|
+
/**
|
|
4
|
+
* The generation `message` (an MLS PrivateMessage) was encrypted under,
|
|
5
|
+
* decrypting its sender data with `state`'s `sender_data_secret` — `state`
|
|
6
|
+
* must be at the message's epoch. `undefined` when it does not decrypt.
|
|
7
|
+
*/
|
|
8
|
+
export declare function senderGeneration(cs: CiphersuiteImpl, state: ClientState, message: MlsMessage): Promise<number | undefined>;
|
|
9
|
+
/** The MLS epoch a framed message names. */
|
|
10
|
+
export declare function messageEpoch(message: MlsMessage): bigint | undefined;
|
|
11
|
+
/**
|
|
12
|
+
* The ordering key of an application message the engine accepted:
|
|
13
|
+
* `senderCredential` is what ts-mls resolved against the message's own
|
|
14
|
+
* epoch's tree (the MLS-authenticated sender), `states` the engine's retained
|
|
15
|
+
* canonical states — the one at the message's epoch yields the generation and
|
|
16
|
+
* the accepted-branch digest.
|
|
17
|
+
*/
|
|
18
|
+
export declare function orderingKeyOf(input: {
|
|
19
|
+
readonly cs: CiphersuiteImpl;
|
|
20
|
+
readonly message: MlsMessage;
|
|
21
|
+
readonly senderCredential: Credential;
|
|
22
|
+
readonly senderLeafIndex: number;
|
|
23
|
+
readonly states: readonly ClientState[];
|
|
24
|
+
}): Promise<OrderingKey>;
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The ordering key of an accepted application message (AC-HIST-1):
|
|
3
|
+
* `{ account, leafIndex, epoch, generation, acceptedDigest }`, `account` being
|
|
4
|
+
* the MLS-authenticated sender's credential identity — never a transport or
|
|
5
|
+
* rumor-claimed author.
|
|
6
|
+
*
|
|
7
|
+
* ts-mls authenticates the sender but does not return the generation the
|
|
8
|
+
* message was encrypted under: it sits in the message's encrypted sender data
|
|
9
|
+
* (RFC 9420 §6.3.2), which ts-mls decrypts internally and does not export.
|
|
10
|
+
* {@link senderGeneration} decrypts it again with the epoch's
|
|
11
|
+
* `sender_data_secret` and the group's own cipher suite — the same
|
|
12
|
+
* derivation (`ExpandWithLabel(sender_data_secret, "key" | "nonce",
|
|
13
|
+
* ciphertext_sample, ...)`, AAD = `SenderDataAAD`) — so the value is exactly
|
|
14
|
+
* the one the sender's ratchet used.
|
|
15
|
+
*/
|
|
16
|
+
import { getCredentialPubkey } from '@941design/marmot-engine/core';
|
|
17
|
+
import { tagOf } from './retained-window.js';
|
|
18
|
+
const encoder = new TextEncoder();
|
|
19
|
+
/** MLS variable-length vector length prefix (RFC 9420 §2.1.2). */
|
|
20
|
+
function varint(n) {
|
|
21
|
+
if (n < 0x40)
|
|
22
|
+
return Uint8Array.of(n);
|
|
23
|
+
if (n < 0x4000)
|
|
24
|
+
return Uint8Array.of(0x40 | (n >> 8), n & 0xff);
|
|
25
|
+
return Uint8Array.of(0x80 | ((n >>> 24) & 0x3f), (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff);
|
|
26
|
+
}
|
|
27
|
+
function concat(...parts) {
|
|
28
|
+
const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
|
|
29
|
+
let offset = 0;
|
|
30
|
+
for (const p of parts) {
|
|
31
|
+
out.set(p, offset);
|
|
32
|
+
offset += p.length;
|
|
33
|
+
}
|
|
34
|
+
return out;
|
|
35
|
+
}
|
|
36
|
+
function opaque(bytes) {
|
|
37
|
+
return concat(varint(bytes.length), bytes);
|
|
38
|
+
}
|
|
39
|
+
function uint64(value) {
|
|
40
|
+
const out = new Uint8Array(8);
|
|
41
|
+
new DataView(out.buffer).setBigUint64(0, value);
|
|
42
|
+
return out;
|
|
43
|
+
}
|
|
44
|
+
function expandWithLabel(cs, secret, label, context, length) {
|
|
45
|
+
const info = concat(Uint8Array.of(length >> 8, length & 0xff), opaque(encoder.encode(`MLS 1.0 ${label}`)), opaque(context));
|
|
46
|
+
return cs.kdf.expand(secret, info, length);
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* The generation `message` (an MLS PrivateMessage) was encrypted under,
|
|
50
|
+
* decrypting its sender data with `state`'s `sender_data_secret` — `state`
|
|
51
|
+
* must be at the message's epoch. `undefined` when it does not decrypt.
|
|
52
|
+
*/
|
|
53
|
+
export async function senderGeneration(cs, state, message) {
|
|
54
|
+
if (!('privateMessage' in message))
|
|
55
|
+
return undefined;
|
|
56
|
+
const pm = message.privateMessage;
|
|
57
|
+
if (pm.epoch !== state.groupContext.epoch)
|
|
58
|
+
return undefined;
|
|
59
|
+
try {
|
|
60
|
+
const secret = state.keySchedule.senderDataSecret;
|
|
61
|
+
const sample = pm.ciphertext.length < cs.kdf.size ? pm.ciphertext : pm.ciphertext.subarray(0, cs.kdf.size);
|
|
62
|
+
const key = await expandWithLabel(cs, secret, 'key', sample, cs.hpke.keyLength);
|
|
63
|
+
const nonce = await expandWithLabel(cs, secret, 'nonce', sample, cs.hpke.nonceLength);
|
|
64
|
+
const aad = concat(opaque(pm.groupId), uint64(pm.epoch), Uint8Array.of(Number(pm.contentType)));
|
|
65
|
+
const plain = await cs.hpke.decryptAead(key, nonce, aad, pm.encryptedSenderData);
|
|
66
|
+
// SenderData = { uint32 leaf_index; uint32 generation; opaque reuse_guard[4] }
|
|
67
|
+
if (plain.length !== 12)
|
|
68
|
+
return undefined;
|
|
69
|
+
return new DataView(plain.buffer, plain.byteOffset, plain.byteLength).getUint32(4);
|
|
70
|
+
}
|
|
71
|
+
catch {
|
|
72
|
+
return undefined;
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
/** The MLS epoch a framed message names. */
|
|
76
|
+
export function messageEpoch(message) {
|
|
77
|
+
if ('privateMessage' in message)
|
|
78
|
+
return message.privateMessage.epoch;
|
|
79
|
+
if ('publicMessage' in message)
|
|
80
|
+
return message.publicMessage.content.epoch;
|
|
81
|
+
return undefined;
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* The ordering key of an application message the engine accepted:
|
|
85
|
+
* `senderCredential` is what ts-mls resolved against the message's own
|
|
86
|
+
* epoch's tree (the MLS-authenticated sender), `states` the engine's retained
|
|
87
|
+
* canonical states — the one at the message's epoch yields the generation and
|
|
88
|
+
* the accepted-branch digest.
|
|
89
|
+
*/
|
|
90
|
+
export async function orderingKeyOf(input) {
|
|
91
|
+
const epoch = messageEpoch(input.message) ?? input.states[0]?.groupContext.epoch ?? 0n;
|
|
92
|
+
const state = input.states.find((s) => s.groupContext.epoch === epoch);
|
|
93
|
+
const generation = state === undefined ? undefined : await senderGeneration(input.cs, state, input.message);
|
|
94
|
+
return Object.freeze({
|
|
95
|
+
account: getCredentialPubkey(input.senderCredential),
|
|
96
|
+
leafIndex: input.senderLeafIndex,
|
|
97
|
+
epoch,
|
|
98
|
+
generation: generation ?? -1,
|
|
99
|
+
acceptedDigest: state === undefined ? '' : tagOf(state),
|
|
100
|
+
});
|
|
101
|
+
}
|