@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,112 @@
|
|
|
1
|
+
import type { ClientState } from '@941design/marmot-engine/mls';
|
|
2
|
+
import { type OwnChange, type OwnCommitChange } from './own-change.js';
|
|
3
|
+
import { type RetainedWindow, type WindowNode } from './retained-window.js';
|
|
4
|
+
/**
|
|
5
|
+
* What an own commit's intent declared (DD2). `removed`: accounts (`removeAccounts`); `added`: the invitees' leaf
|
|
6
|
+
* signature keys (hex); `admins`: the admin list was set; `components`: app-data component ids (a rename declares
|
|
7
|
+
* the group-profile id). A commit can also fold in foreign staged proposals: those changes are the proposers' own, so
|
|
8
|
+
* they match nothing here and are never re-driven.
|
|
9
|
+
*/
|
|
10
|
+
export interface DeclaredChanges {
|
|
11
|
+
readonly removed?: readonly string[];
|
|
12
|
+
readonly added?: readonly string[];
|
|
13
|
+
readonly admins?: boolean;
|
|
14
|
+
readonly components?: readonly number[];
|
|
15
|
+
/**
|
|
16
|
+
* When set, the filter is this change list, matched by change identity (member-removed: account; member-added: leaf key;
|
|
17
|
+
* admin: account and direction; component: id) and the other members are ignored — a marker that already holds its changes.
|
|
18
|
+
*/
|
|
19
|
+
readonly only?: readonly OwnChange[];
|
|
20
|
+
}
|
|
21
|
+
/** The diff entries of `changes` the intent declared (DD2). A side effect of a declared change (an admin flip a removal caused) is dropped. */
|
|
22
|
+
export declare function intersectDeclared(changes: readonly OwnCommitChange[], declared: DeclaredChanges): OwnCommitChange[];
|
|
23
|
+
/**
|
|
24
|
+
* One change with its fork-point value (DD3) and, for an Add, the winner-side evidence (DD12). The members are exactly
|
|
25
|
+
* those `client/group-records.ts`'s `StoredOwnChange` carries, less the KeyPackage the client layer attaches to an Add.
|
|
26
|
+
*/
|
|
27
|
+
export type ForkedChange = {
|
|
28
|
+
readonly change: Extract<OwnChange, {
|
|
29
|
+
readonly type: 'component';
|
|
30
|
+
}>;
|
|
31
|
+
readonly data: Uint8Array | null;
|
|
32
|
+
readonly fork: {
|
|
33
|
+
readonly component: Uint8Array | null;
|
|
34
|
+
};
|
|
35
|
+
} | {
|
|
36
|
+
readonly change: Extract<OwnChange, {
|
|
37
|
+
readonly type: 'admin';
|
|
38
|
+
}>;
|
|
39
|
+
readonly fork: {
|
|
40
|
+
readonly admin: boolean;
|
|
41
|
+
};
|
|
42
|
+
} | {
|
|
43
|
+
readonly change: Extract<OwnChange, {
|
|
44
|
+
readonly type: 'member-removed';
|
|
45
|
+
}>;
|
|
46
|
+
readonly fork: {
|
|
47
|
+
readonly leafKeys: readonly string[];
|
|
48
|
+
};
|
|
49
|
+
readonly winnerRemovedTarget: boolean;
|
|
50
|
+
} | {
|
|
51
|
+
readonly change: Extract<OwnChange, {
|
|
52
|
+
readonly type: 'member-added';
|
|
53
|
+
}>;
|
|
54
|
+
readonly fork: {
|
|
55
|
+
readonly held: boolean;
|
|
56
|
+
};
|
|
57
|
+
readonly winnerHeldInvitee: boolean;
|
|
58
|
+
};
|
|
59
|
+
/** Why a withdrawn commit could not be broken down. */
|
|
60
|
+
export type BreakdownUnreadable =
|
|
61
|
+
/** The commit's node, its parent or the fork point has no state in the window (pruned, or never retained). */
|
|
62
|
+
'state-missing'
|
|
63
|
+
/** A retained snapshot (or the state read from it) does not deserialize. */
|
|
64
|
+
| 'state-unreadable'
|
|
65
|
+
/** {@link ownCommitChanges} returned `undefined`: a leaf credential or the admin policy of the pair does not decode. */
|
|
66
|
+
| 'diff-unreadable'
|
|
67
|
+
/** The fork point's admin policy is present but does not decode. */
|
|
68
|
+
| 'fork-unreadable';
|
|
69
|
+
export type WithdrawalBreakdown = {
|
|
70
|
+
readonly readable: true;
|
|
71
|
+
/** Declared changes only, in the diff's order. */
|
|
72
|
+
readonly changes: readonly ForkedChange[];
|
|
73
|
+
/** The fork node's epoch; absent exactly when `changes` is empty. */
|
|
74
|
+
readonly forkEpoch?: number;
|
|
75
|
+
} | {
|
|
76
|
+
readonly readable: false;
|
|
77
|
+
readonly reason: BreakdownUnreadable;
|
|
78
|
+
};
|
|
79
|
+
/**
|
|
80
|
+
* The fork point (DD13): the deepest node on both `before`'s canonical path and any of `afters`' (the persisted window
|
|
81
|
+
* and the one reaching down to `before`'s floor). `undefined` when they share none within the windows.
|
|
82
|
+
*/
|
|
83
|
+
export declare function forkPointNode(before: RetainedWindow, afters: readonly RetainedWindow[]): WindowNode | undefined;
|
|
84
|
+
/**
|
|
85
|
+
* Whether a state of the winning branch above `forkEpoch` holds `leafKey` (the Add's DD12 evidence). Read from the windows given:
|
|
86
|
+
* at withdrawal that is the winning branch's, at build time the current window (whose floor may have passed the fork point, in
|
|
87
|
+
* which case nothing is shown). Never throws: a state that cannot be read shows nothing.
|
|
88
|
+
*/
|
|
89
|
+
export declare function winnerHeldLeaf(leafKey: string, forkEpoch: number, afters: readonly RetainedWindow[], afterTip: ClientState): boolean;
|
|
90
|
+
/**
|
|
91
|
+
* Whether a commit of the winning branch above `forkEpoch` REMOVED `account` (DD4, amended; the member-removed sense of the diff): an
|
|
92
|
+
* edge on which the account held a leaf in the parent and holds NONE in the child. Losing one of several devices is no removal, nor is a
|
|
93
|
+
* rotation. The evidence that the winner deliberately removed the target, whatever it did afterwards. Reads the canonical edges (parent -> child) the windows
|
|
94
|
+
* still hold; an edge whose states the window no longer retains shows nothing. Never throws.
|
|
95
|
+
*/
|
|
96
|
+
export declare function winnerRemovedAccount(account: string, forkEpoch: number, windows: readonly RetainedWindow[], tip: ClientState): boolean;
|
|
97
|
+
/**
|
|
98
|
+
* Breaks down the withdrawn own commit at `node` (a node of `before`, abandoned by the transition to `afters`):
|
|
99
|
+
* 1. the diff is the commit's OWN parent against itself (DD13: on a dead branch O1 -> O2, O2's parent is O1);
|
|
100
|
+
* 2. it is intersected with `declared` (DD2); an empty result needs nothing else;
|
|
101
|
+
* 3. each surviving change gets its value at the fork point (the deepest node `before` and `afters` share). With no
|
|
102
|
+
* shared node within the windows (or none with a state in `before`) the breakdown is unreadable (`state-missing`).
|
|
103
|
+
* `afterTip` is the state of the new canonical tip. Never throws; an unreadable pair is reported, never read as "no change".
|
|
104
|
+
*/
|
|
105
|
+
export declare function breakdownWithdrawnCommit(input: {
|
|
106
|
+
readonly before: RetainedWindow;
|
|
107
|
+
readonly beforeTip: ClientState;
|
|
108
|
+
readonly afters: readonly RetainedWindow[];
|
|
109
|
+
readonly afterTip: ClientState;
|
|
110
|
+
readonly node: WindowNode;
|
|
111
|
+
readonly declared: DeclaredChanges;
|
|
112
|
+
}): WithdrawalBreakdown;
|
|
@@ -0,0 +1,196 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The withdrawal-time breakdown of a rewound own commit (epic marmot-rewound-own-commit-no-signal, S1; spec Design
|
|
3
|
+
* Decisions 2, 12, 13 and 16): the commit's changes (the S7 state diff of the commit's OWN parent and itself),
|
|
4
|
+
* intersected with the changes its intent declared, each with the value its subject had at the FORK POINT and the
|
|
5
|
+
* winner-side evidence the horizon would otherwise prune.
|
|
6
|
+
*
|
|
7
|
+
* Pure: it reads the retained windows and the states they hold and returns plain data. Everything that records,
|
|
8
|
+
* notifies or re-drives belongs to `client/`.
|
|
9
|
+
*/
|
|
10
|
+
import { deserializeClientState } from '@941design/marmot-engine/core';
|
|
11
|
+
import { successionsInWindow } from './notifications.js';
|
|
12
|
+
import { adminsOf, commitViewOf, holdsLeafKey, ownCommitChanges } from './own-change.js';
|
|
13
|
+
import { canonicalPath } from './retained-window.js';
|
|
14
|
+
/** The diff entries of `changes` the intent declared (DD2). A side effect of a declared change (an admin flip a removal caused) is dropped. */
|
|
15
|
+
export function intersectDeclared(changes, declared) {
|
|
16
|
+
if (declared.only !== undefined) {
|
|
17
|
+
const only = declared.only;
|
|
18
|
+
return changes.filter(({ change }) => only.some((o) => {
|
|
19
|
+
if (o.type !== change.type)
|
|
20
|
+
return false;
|
|
21
|
+
switch (change.type) {
|
|
22
|
+
case 'member-removed':
|
|
23
|
+
return o.type === 'member-removed' && o.account === change.account;
|
|
24
|
+
case 'member-added':
|
|
25
|
+
return o.type === 'member-added' && o.leafKey === change.leafKey;
|
|
26
|
+
case 'admin':
|
|
27
|
+
return o.type === 'admin' && o.account === change.account && o.admin === change.admin;
|
|
28
|
+
case 'component':
|
|
29
|
+
return o.type === 'component' && o.componentId === change.componentId;
|
|
30
|
+
}
|
|
31
|
+
}));
|
|
32
|
+
}
|
|
33
|
+
const removed = new Set(declared.removed ?? []);
|
|
34
|
+
const added = new Set(declared.added ?? []);
|
|
35
|
+
const components = new Set(declared.components ?? []);
|
|
36
|
+
return changes.filter(({ change }) => {
|
|
37
|
+
switch (change.type) {
|
|
38
|
+
case 'member-removed':
|
|
39
|
+
return removed.has(change.account);
|
|
40
|
+
case 'member-added':
|
|
41
|
+
return added.has(change.leafKey);
|
|
42
|
+
case 'admin':
|
|
43
|
+
return declared.admins === true;
|
|
44
|
+
case 'component':
|
|
45
|
+
return components.has(change.componentId);
|
|
46
|
+
}
|
|
47
|
+
});
|
|
48
|
+
}
|
|
49
|
+
function stateOf(window, tip, node) {
|
|
50
|
+
if (node === undefined)
|
|
51
|
+
return undefined;
|
|
52
|
+
if (node.tag === window.tipTag)
|
|
53
|
+
return tip;
|
|
54
|
+
return node.snapshot === undefined ? undefined : deserializeClientState(node.snapshot);
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* The fork point (DD13): the deepest node on both `before`'s canonical path and any of `afters`' (the persisted window
|
|
58
|
+
* and the one reaching down to `before`'s floor). `undefined` when they share none within the windows.
|
|
59
|
+
*/
|
|
60
|
+
export function forkPointNode(before, afters) {
|
|
61
|
+
const afterTags = new Set(afters.flatMap((w) => canonicalPath(w).map((n) => n.tag)));
|
|
62
|
+
return canonicalPath(before)
|
|
63
|
+
.filter((n) => afterTags.has(n.tag))
|
|
64
|
+
.at(-1);
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* `keys` closed under the leaf-key successions the winning branch shows for `account` (DD12): a key a winner rotated
|
|
68
|
+
* a member's leaf to is the same leaf continuing. Sorted, without duplicates.
|
|
69
|
+
*/
|
|
70
|
+
function closeUnderSuccessions(keys, account, afters, afterTip) {
|
|
71
|
+
const out = new Set(keys);
|
|
72
|
+
const edges = afters.flatMap((w) => successionsInWindow(w, afterTip)).filter((s) => s.account === account);
|
|
73
|
+
for (let grew = true; grew;) {
|
|
74
|
+
grew = false;
|
|
75
|
+
for (const e of edges) {
|
|
76
|
+
if (out.has(e.fromLeafKey) && !out.has(e.toLeafKey)) {
|
|
77
|
+
out.add(e.toLeafKey);
|
|
78
|
+
grew = true;
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
return [...out].sort();
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* Whether a state of the winning branch above `forkEpoch` holds `leafKey` (the Add's DD12 evidence). Read from the windows given:
|
|
86
|
+
* at withdrawal that is the winning branch's, at build time the current window (whose floor may have passed the fork point, in
|
|
87
|
+
* which case nothing is shown). Never throws: a state that cannot be read shows nothing.
|
|
88
|
+
*/
|
|
89
|
+
export function winnerHeldLeaf(leafKey, forkEpoch, afters, afterTip) {
|
|
90
|
+
try {
|
|
91
|
+
return winnerHeld(leafKey, forkEpoch, afters, afterTip);
|
|
92
|
+
}
|
|
93
|
+
catch {
|
|
94
|
+
return false;
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
function winnerHeld(leafKey, forkEpoch, afters, afterTip) {
|
|
98
|
+
for (const window of afters) {
|
|
99
|
+
for (const node of canonicalPath(window)) {
|
|
100
|
+
if (node.epoch <= forkEpoch)
|
|
101
|
+
continue;
|
|
102
|
+
const state = stateOf(window, afterTip, node);
|
|
103
|
+
if (state !== undefined && holdsLeafKey(commitViewOf(state), leafKey))
|
|
104
|
+
return true;
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
return false;
|
|
108
|
+
}
|
|
109
|
+
/**
|
|
110
|
+
* Whether a commit of the winning branch above `forkEpoch` REMOVED `account` (DD4, amended; the member-removed sense of the diff): an
|
|
111
|
+
* edge on which the account held a leaf in the parent and holds NONE in the child. Losing one of several devices is no removal, nor is a
|
|
112
|
+
* rotation. The evidence that the winner deliberately removed the target, whatever it did afterwards. Reads the canonical edges (parent -> child) the windows
|
|
113
|
+
* still hold; an edge whose states the window no longer retains shows nothing. Never throws.
|
|
114
|
+
*/
|
|
115
|
+
export function winnerRemovedAccount(account, forkEpoch, windows, tip) {
|
|
116
|
+
try {
|
|
117
|
+
for (const window of windows) {
|
|
118
|
+
for (const node of canonicalPath(window)) {
|
|
119
|
+
if (node.epoch <= forkEpoch || node.parentTag === undefined)
|
|
120
|
+
continue;
|
|
121
|
+
const parent = stateOf(window, tip, window.nodes.get(node.parentTag));
|
|
122
|
+
const child = stateOf(window, tip, node);
|
|
123
|
+
if (parent === undefined || child === undefined)
|
|
124
|
+
continue;
|
|
125
|
+
if (commitViewOf(parent).leaves.some((l) => l.account === account) && !commitViewOf(child).leaves.some((l) => l.account === account))
|
|
126
|
+
return true;
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
catch {
|
|
131
|
+
return false;
|
|
132
|
+
}
|
|
133
|
+
return false;
|
|
134
|
+
}
|
|
135
|
+
function forkedChangeOf(entry, fork, forkAdmins, forkEpoch, afters, afterTip) {
|
|
136
|
+
const change = entry.change;
|
|
137
|
+
switch (change.type) {
|
|
138
|
+
case 'component': {
|
|
139
|
+
const atFork = fork.dictionary.get(change.componentId);
|
|
140
|
+
return { change, data: entry.data, fork: { component: atFork === undefined ? null : new Uint8Array(atFork) } };
|
|
141
|
+
}
|
|
142
|
+
case 'admin':
|
|
143
|
+
return { change, fork: { admin: forkAdmins?.has(change.account.toLowerCase()) === true } };
|
|
144
|
+
case 'member-removed':
|
|
145
|
+
return {
|
|
146
|
+
change,
|
|
147
|
+
fork: {
|
|
148
|
+
leafKeys: closeUnderSuccessions(fork.leaves.filter((l) => l.account === change.account).map((l) => l.leafKey), change.account, afters, afterTip),
|
|
149
|
+
},
|
|
150
|
+
winnerRemovedTarget: winnerRemovedAccount(change.account, forkEpoch, afters, afterTip),
|
|
151
|
+
};
|
|
152
|
+
case 'member-added':
|
|
153
|
+
return { change, fork: { held: holdsLeafKey(fork, change.leafKey) }, winnerHeldInvitee: winnerHeld(change.leafKey, forkEpoch, afters, afterTip) };
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
/**
|
|
157
|
+
* Breaks down the withdrawn own commit at `node` (a node of `before`, abandoned by the transition to `afters`):
|
|
158
|
+
* 1. the diff is the commit's OWN parent against itself (DD13: on a dead branch O1 -> O2, O2's parent is O1);
|
|
159
|
+
* 2. it is intersected with `declared` (DD2); an empty result needs nothing else;
|
|
160
|
+
* 3. each surviving change gets its value at the fork point (the deepest node `before` and `afters` share). With no
|
|
161
|
+
* shared node within the windows (or none with a state in `before`) the breakdown is unreadable (`state-missing`).
|
|
162
|
+
* `afterTip` is the state of the new canonical tip. Never throws; an unreadable pair is reported, never read as "no change".
|
|
163
|
+
*/
|
|
164
|
+
export function breakdownWithdrawnCommit(input) {
|
|
165
|
+
const { before, beforeTip, afters, afterTip, node, declared } = input;
|
|
166
|
+
try {
|
|
167
|
+
const parentNode = node.parentTag === undefined ? undefined : before.nodes.get(node.parentTag);
|
|
168
|
+
const parent = stateOf(before, beforeTip, parentNode);
|
|
169
|
+
const child = stateOf(before, beforeTip, node);
|
|
170
|
+
if (parentNode === undefined || parent === undefined || child === undefined)
|
|
171
|
+
return { readable: false, reason: 'state-missing' };
|
|
172
|
+
const diff = ownCommitChanges(parent, child);
|
|
173
|
+
if (diff === undefined)
|
|
174
|
+
return { readable: false, reason: 'diff-unreadable' };
|
|
175
|
+
const declaredChanges = intersectDeclared(diff, declared);
|
|
176
|
+
if (declaredChanges.length === 0)
|
|
177
|
+
return { readable: true, changes: [] };
|
|
178
|
+
// No shared canonical node with a state in `before`: the fork point is unknown and so are the values. Unreadable, never a guess.
|
|
179
|
+
const forkNode = forkPointNode(before, afters);
|
|
180
|
+
const forkState = forkNode === undefined ? undefined : stateOf(before, beforeTip, forkNode);
|
|
181
|
+
if (forkNode === undefined || forkState === undefined)
|
|
182
|
+
return { readable: false, reason: 'state-missing' };
|
|
183
|
+
const forkView = commitViewOf(forkState);
|
|
184
|
+
const forkAdmins = adminsOf(forkView.dictionary);
|
|
185
|
+
if (forkAdmins === 'unreadable')
|
|
186
|
+
return { readable: false, reason: 'fork-unreadable' };
|
|
187
|
+
return {
|
|
188
|
+
readable: true,
|
|
189
|
+
changes: declaredChanges.map((c) => forkedChangeOf(c, forkView, forkAdmins, forkNode.epoch, afters, afterTip)),
|
|
190
|
+
forkEpoch: forkNode.epoch,
|
|
191
|
+
};
|
|
192
|
+
}
|
|
193
|
+
catch {
|
|
194
|
+
return { readable: false, reason: 'state-unreadable' };
|
|
195
|
+
}
|
|
196
|
+
}
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
import { type ClientState } from '@941design/marmot-engine/mls';
|
|
2
|
+
/** One unit of a (withdrawn) own commit. */
|
|
3
|
+
export type OwnChange =
|
|
4
|
+
/** Every leaf of `account` left the group. */
|
|
5
|
+
{
|
|
6
|
+
readonly type: 'member-removed';
|
|
7
|
+
readonly account: string;
|
|
8
|
+
}
|
|
9
|
+
/** One leaf was added: `leafKey` is its hex signature key (a second leaf of an existing member is a `member-added` too). */
|
|
10
|
+
| {
|
|
11
|
+
readonly type: 'member-added';
|
|
12
|
+
readonly account: string;
|
|
13
|
+
readonly leafKey: string;
|
|
14
|
+
}
|
|
15
|
+
/** `account`'s admin status is `admin` in the child and differs in the parent. */
|
|
16
|
+
| {
|
|
17
|
+
readonly type: 'admin';
|
|
18
|
+
readonly account: string;
|
|
19
|
+
readonly admin: boolean;
|
|
20
|
+
}
|
|
21
|
+
/** The app-data entry `componentId` differs (see `OwnCommitChange.data` for the child's value). */
|
|
22
|
+
| {
|
|
23
|
+
readonly type: 'component';
|
|
24
|
+
readonly componentId: number;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* Epic marmot-invitation-outcomes (SC-6): a scoped cleanup (`MarmotGroup.removeAdmission`) removed the ONE admission of decline
|
|
28
|
+
* candidate `candidateId` — the leaf of `account` its Add put in the group, `leafKey` being that leaf's signature key (hex) as the
|
|
29
|
+
* Add admitted it. Declared from the cleanup's intent, never derived from a state diff: a cleanup commit never reports
|
|
30
|
+
* `member-removed`, even when the removed leaf was the account's last, and is never re-driven as an account-wide removal.
|
|
31
|
+
*/
|
|
32
|
+
| {
|
|
33
|
+
readonly type: 'admission-removed';
|
|
34
|
+
readonly account: string;
|
|
35
|
+
readonly leafKey: string;
|
|
36
|
+
readonly candidateId: string;
|
|
37
|
+
};
|
|
38
|
+
/** Why a change was dropped instead of re-applied (`own-change-lost`). Closed set. */
|
|
39
|
+
export type OwnChangeLostReason = 'concurrent-change' | 'reversed' | 'already-applied' | 'not-admin' | 'stranded' | 'invalid-keypackage' | 'attempts-exhausted';
|
|
40
|
+
export declare const OWN_CHANGE_LOST_REASONS: readonly OwnChangeLostReason[];
|
|
41
|
+
/**
|
|
42
|
+
* A change with what the re-drive needs of the child state: for a `component` change the child's bytes, or `null`
|
|
43
|
+
* when the commit deleted the entry. Other kinds carry no `data`.
|
|
44
|
+
*/
|
|
45
|
+
export type OwnCommitChange = {
|
|
46
|
+
readonly change: Exclude<OwnChange, {
|
|
47
|
+
readonly type: 'component' | 'admission-removed';
|
|
48
|
+
}>;
|
|
49
|
+
} | {
|
|
50
|
+
readonly change: Extract<OwnChange, {
|
|
51
|
+
readonly type: 'component';
|
|
52
|
+
}>;
|
|
53
|
+
readonly data: Uint8Array | null;
|
|
54
|
+
};
|
|
55
|
+
/** An own commit's change left the canonical path with the commit (dispatched with the withdrawing transition). */
|
|
56
|
+
export interface OwnChangeWithdrawnNotification {
|
|
57
|
+
readonly type: 'own-change-withdrawn';
|
|
58
|
+
/** The root intent id of the original call (`reportedIntentIdOf`), shared by the original and every re-drive. */
|
|
59
|
+
readonly intentId: string;
|
|
60
|
+
/** Hex digest of the withdrawn commit. */
|
|
61
|
+
readonly commitDigest: string;
|
|
62
|
+
readonly change: OwnChange;
|
|
63
|
+
}
|
|
64
|
+
/** The change is in force again: its re-drive confirmed, or the original commit rejoined the canonical path. */
|
|
65
|
+
export interface OwnChangeReappliedNotification {
|
|
66
|
+
readonly type: 'own-change-reapplied';
|
|
67
|
+
readonly intentId: string;
|
|
68
|
+
/** Hex digest of the commit that carries the change now (the re-drive, or the original that came back). */
|
|
69
|
+
readonly commitDigest: string;
|
|
70
|
+
readonly change: OwnChange;
|
|
71
|
+
}
|
|
72
|
+
/** The change was dropped and will not be re-applied. */
|
|
73
|
+
export interface OwnChangeLostNotification {
|
|
74
|
+
readonly type: 'own-change-lost';
|
|
75
|
+
readonly intentId: string;
|
|
76
|
+
readonly change: OwnChange;
|
|
77
|
+
readonly reason: OwnChangeLostReason;
|
|
78
|
+
}
|
|
79
|
+
/** The facts of one MLS state the diff reads. */
|
|
80
|
+
export interface CommitView {
|
|
81
|
+
/** `app_data_dictionary` entries, component id -> bytes. */
|
|
82
|
+
readonly dictionary: ReadonlyMap<number, Uint8Array>;
|
|
83
|
+
/** Leaves at the state; `account` is undefined for a credential that does not decode (the diff is then unreadable). */
|
|
84
|
+
readonly leaves: readonly {
|
|
85
|
+
readonly leafIndex: number;
|
|
86
|
+
readonly leafKey: string;
|
|
87
|
+
readonly account: string | undefined;
|
|
88
|
+
}[];
|
|
89
|
+
}
|
|
90
|
+
export declare const sameBytes: (a: Uint8Array, b: Uint8Array) => boolean;
|
|
91
|
+
export declare function adminsOf(dictionary: ReadonlyMap<number, Uint8Array>): ReadonlySet<string> | 'unreadable' | undefined;
|
|
92
|
+
/**
|
|
93
|
+
* The pure core of {@link ownCommitChanges}: `replacedInPlace` are the leaf indices whose leaf replaced its own
|
|
94
|
+
* signature key in this commit (a leaf-key succession — neither a removal nor an add).
|
|
95
|
+
*/
|
|
96
|
+
export declare function diffCommitViews(parent: CommitView, child: CommitView, replacedInPlace: ReadonlySet<number>): OwnCommitChange[] | undefined;
|
|
97
|
+
/** Whether the view's tree holds a leaf carrying the signature key `leafKey` (hex): the one leaf-key membership test of the re-drive and its evidence. */
|
|
98
|
+
export declare function holdsLeafKey(view: Pick<CommitView, 'leaves'>, leafKey: string): boolean;
|
|
99
|
+
/** The facts of one MLS state the diff (and the fork-point values of a withdrawn own commit) read. */
|
|
100
|
+
export declare function commitViewOf(state: ClientState): CommitView;
|
|
101
|
+
/**
|
|
102
|
+
* The changes one commit made, parent → child (AC-DIFF-1; `child` must be exactly one commit after `parent`):
|
|
103
|
+
* - `member-removed` for each account whose every leaf the commit removed (an account that keeps or regains a leaf is
|
|
104
|
+
* no removal);
|
|
105
|
+
* - `member-added { account, leafKey }` for each leaf it added — also a second leaf of an account that already was a
|
|
106
|
+
* member;
|
|
107
|
+
* - `admin { account, admin }` for each account whose admin status differs (a set diff of the decoded policy, 0x8003;
|
|
108
|
+
* a present-but-undecodable policy on either side makes the pair unreadable; an absent one is an empty admin set);
|
|
109
|
+
* - `component { componentId }` with the child's bytes (`null`: deleted) for every other app-data entry whose bytes
|
|
110
|
+
* differ.
|
|
111
|
+
* Never reported: the lifecycle component (0x800c), the engine-managed 0x0001 / 0x0002 / 0x0004 entries, and a
|
|
112
|
+
* leaf-key succession (`leafKeySuccessions`: a leaf replacing its own key in place), which is no membership change.
|
|
113
|
+
* Output order: type rank non-decreasing (member-removed, member-added, admin, component); components by id.
|
|
114
|
+
*
|
|
115
|
+
* Seam contract: `undefined` means a state could not be read (its dictionary did not decode, a leaf credential does not decode, or a present admin policy does not decode) — distinct from
|
|
116
|
+
* `[]`, a readable pair with no changes. A caller must not treat `undefined` as "nothing changed". Pure; never throws.
|
|
117
|
+
*/
|
|
118
|
+
export declare function ownCommitChanges(parent: ClientState, child: ClientState): readonly OwnCommitChange[] | undefined;
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The pure change diff behind the own-commit re-drive (epic marmot-rewound-own-commit-no-signal, AC-DIFF-1, spec
|
|
3
|
+
* Design Decision 2) and the `own-change-*` notification types it feeds.
|
|
4
|
+
*
|
|
5
|
+
* A "change" is one unit of an own commit, derived from the state diff between the commit's parent and its child, not
|
|
6
|
+
* from the API call that made the commit. This module only derives the diff; intersecting it with what an intent
|
|
7
|
+
* declared, and everything that records or re-drives it, belongs to later stories.
|
|
8
|
+
*/
|
|
9
|
+
import { APP_COMPONENTS_COMPONENT_ID, decodeAdminPolicyV1, getCredentialPubkey, GROUP_ADMIN_POLICY_COMPONENT_ID, GROUP_LIFECYCLE_COMPONENT_ID, LAST_RESORT_COMPONENT_ID, leafKeySuccessions, SAFE_AAD_COMPONENT_ID, } from '@941design/marmot-engine/core';
|
|
10
|
+
import { getAppDataDictionary, nodeTypes } from '@941design/marmot-engine/mls';
|
|
11
|
+
import { hexOf } from './hex.js';
|
|
12
|
+
/**
|
|
13
|
+
* Every {@link OwnChangeLostReason}, for runtime validation. The union is spelled out
|
|
14
|
+
* (rather than derived from this array) so the public type does not reference an
|
|
15
|
+
* unexported value; the record type below makes a missing or extra entry a compile error.
|
|
16
|
+
*/
|
|
17
|
+
const OWN_CHANGE_LOST_REASON_SET = {
|
|
18
|
+
'concurrent-change': true,
|
|
19
|
+
reversed: true,
|
|
20
|
+
'already-applied': true,
|
|
21
|
+
'not-admin': true,
|
|
22
|
+
stranded: true,
|
|
23
|
+
'invalid-keypackage': true,
|
|
24
|
+
'attempts-exhausted': true,
|
|
25
|
+
};
|
|
26
|
+
export const OWN_CHANGE_LOST_REASONS = Object.keys(OWN_CHANGE_LOST_REASON_SET);
|
|
27
|
+
/**
|
|
28
|
+
* Components the diff never reports as `component` changes: the lifecycle component (its own flow), the
|
|
29
|
+
* engine-managed app-components list (0x0001), safe-AAD (0x0002) and last-resort (0x0004) entries, and the admin
|
|
30
|
+
* policy (0x8003), which is reported per account as `admin` and never as a `component` (an undecodable present policy makes the diff unreadable).
|
|
31
|
+
*/
|
|
32
|
+
const NON_COMPONENT_IDS = new Set([APP_COMPONENTS_COMPONENT_ID, SAFE_AAD_COMPONENT_ID, LAST_RESORT_COMPONENT_ID, GROUP_LIFECYCLE_COMPONENT_ID, GROUP_ADMIN_POLICY_COMPONENT_ID]);
|
|
33
|
+
export const sameBytes = (a, b) => a.length === b.length && a.every((v, i) => v === b[i]);
|
|
34
|
+
export function adminsOf(dictionary) {
|
|
35
|
+
const bytes = dictionary.get(GROUP_ADMIN_POLICY_COMPONENT_ID);
|
|
36
|
+
if (bytes === undefined)
|
|
37
|
+
return undefined;
|
|
38
|
+
try {
|
|
39
|
+
return new Set(decodeAdminPolicyV1(bytes).map((a) => a.toLowerCase()));
|
|
40
|
+
}
|
|
41
|
+
catch {
|
|
42
|
+
return 'unreadable';
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* The pure core of {@link ownCommitChanges}: `replacedInPlace` are the leaf indices whose leaf replaced its own
|
|
47
|
+
* signature key in this commit (a leaf-key succession — neither a removal nor an add).
|
|
48
|
+
*/
|
|
49
|
+
export function diffCommitViews(parent, child, replacedInPlace) {
|
|
50
|
+
// Unreadable is not "no change": a leaf whose credential does not decode, or a PRESENT admin policy that does not
|
|
51
|
+
// decode, on either side makes the whole diff unreadable. An ABSENT policy is an empty admin set.
|
|
52
|
+
if ([...parent.leaves, ...child.leaves].some((l) => l.account === undefined))
|
|
53
|
+
return undefined;
|
|
54
|
+
const parentAdmins = adminsOf(parent.dictionary);
|
|
55
|
+
const childAdmins = adminsOf(child.dictionary);
|
|
56
|
+
if (parentAdmins === 'unreadable' || childAdmins === 'unreadable')
|
|
57
|
+
return undefined;
|
|
58
|
+
const out = [];
|
|
59
|
+
const childAccounts = new Set(child.leaves.flatMap((l) => (l.account === undefined ? [] : [l.account])));
|
|
60
|
+
const removed = new Set();
|
|
61
|
+
for (const leaf of parent.leaves) {
|
|
62
|
+
if (leaf.account === undefined || childAccounts.has(leaf.account) || removed.has(leaf.account))
|
|
63
|
+
continue;
|
|
64
|
+
removed.add(leaf.account);
|
|
65
|
+
out.push({ change: { type: 'member-removed', account: leaf.account } });
|
|
66
|
+
}
|
|
67
|
+
const parentKeys = new Set(parent.leaves.map((l) => l.leafKey));
|
|
68
|
+
for (const leaf of child.leaves) {
|
|
69
|
+
if (leaf.account === undefined || parentKeys.has(leaf.leafKey) || replacedInPlace.has(leaf.leafIndex))
|
|
70
|
+
continue;
|
|
71
|
+
out.push({ change: { type: 'member-added', account: leaf.account, leafKey: leaf.leafKey } });
|
|
72
|
+
}
|
|
73
|
+
const before = parentAdmins ?? new Set();
|
|
74
|
+
const after = childAdmins ?? new Set();
|
|
75
|
+
for (const account of [...after].sort())
|
|
76
|
+
if (!before.has(account))
|
|
77
|
+
out.push({ change: { type: 'admin', account, admin: true } });
|
|
78
|
+
for (const account of [...before].sort())
|
|
79
|
+
if (!after.has(account))
|
|
80
|
+
out.push({ change: { type: 'admin', account, admin: false } });
|
|
81
|
+
const ids = new Set([...parent.dictionary.keys(), ...child.dictionary.keys()]);
|
|
82
|
+
for (const componentId of [...ids].sort((a, b) => a - b)) {
|
|
83
|
+
if (NON_COMPONENT_IDS.has(componentId))
|
|
84
|
+
continue;
|
|
85
|
+
const before = parent.dictionary.get(componentId);
|
|
86
|
+
const after = child.dictionary.get(componentId);
|
|
87
|
+
if (before !== undefined && after !== undefined && sameBytes(before, after))
|
|
88
|
+
continue;
|
|
89
|
+
if (before === undefined && after === undefined)
|
|
90
|
+
continue;
|
|
91
|
+
out.push({ change: { type: 'component', componentId }, data: after === undefined ? null : new Uint8Array(after) });
|
|
92
|
+
}
|
|
93
|
+
return out;
|
|
94
|
+
}
|
|
95
|
+
/** Whether the view's tree holds a leaf carrying the signature key `leafKey` (hex): the one leaf-key membership test of the re-drive and its evidence. */
|
|
96
|
+
export function holdsLeafKey(view, leafKey) {
|
|
97
|
+
return view.leaves.some((l) => l.leafKey === leafKey);
|
|
98
|
+
}
|
|
99
|
+
/** The facts of one MLS state the diff (and the fork-point values of a withdrawn own commit) read. */
|
|
100
|
+
export function commitViewOf(state) {
|
|
101
|
+
const dictionary = new Map();
|
|
102
|
+
for (const entry of getAppDataDictionary(state.groupContext.extensions) ?? [])
|
|
103
|
+
dictionary.set(entry.componentId, entry.data);
|
|
104
|
+
const leaves = [];
|
|
105
|
+
for (let i = 0; i < state.ratchetTree.length; i += 2) {
|
|
106
|
+
const node = state.ratchetTree[i];
|
|
107
|
+
if (node?.nodeType !== nodeTypes.leaf)
|
|
108
|
+
continue;
|
|
109
|
+
let account;
|
|
110
|
+
try {
|
|
111
|
+
account = getCredentialPubkey(node.leaf.credential);
|
|
112
|
+
}
|
|
113
|
+
catch {
|
|
114
|
+
account = undefined; // diffCommitViews reports the pair unreadable
|
|
115
|
+
}
|
|
116
|
+
leaves.push({ leafIndex: i / 2, leafKey: hexOf(node.leaf.signaturePublicKey), account });
|
|
117
|
+
}
|
|
118
|
+
return { dictionary, leaves };
|
|
119
|
+
}
|
|
120
|
+
/**
|
|
121
|
+
* The changes one commit made, parent → child (AC-DIFF-1; `child` must be exactly one commit after `parent`):
|
|
122
|
+
* - `member-removed` for each account whose every leaf the commit removed (an account that keeps or regains a leaf is
|
|
123
|
+
* no removal);
|
|
124
|
+
* - `member-added { account, leafKey }` for each leaf it added — also a second leaf of an account that already was a
|
|
125
|
+
* member;
|
|
126
|
+
* - `admin { account, admin }` for each account whose admin status differs (a set diff of the decoded policy, 0x8003;
|
|
127
|
+
* a present-but-undecodable policy on either side makes the pair unreadable; an absent one is an empty admin set);
|
|
128
|
+
* - `component { componentId }` with the child's bytes (`null`: deleted) for every other app-data entry whose bytes
|
|
129
|
+
* differ.
|
|
130
|
+
* Never reported: the lifecycle component (0x800c), the engine-managed 0x0001 / 0x0002 / 0x0004 entries, and a
|
|
131
|
+
* leaf-key succession (`leafKeySuccessions`: a leaf replacing its own key in place), which is no membership change.
|
|
132
|
+
* Output order: type rank non-decreasing (member-removed, member-added, admin, component); components by id.
|
|
133
|
+
*
|
|
134
|
+
* Seam contract: `undefined` means a state could not be read (its dictionary did not decode, a leaf credential does not decode, or a present admin policy does not decode) — distinct from
|
|
135
|
+
* `[]`, a readable pair with no changes. A caller must not treat `undefined` as "nothing changed". Pure; never throws.
|
|
136
|
+
*/
|
|
137
|
+
export function ownCommitChanges(parent, child) {
|
|
138
|
+
let views;
|
|
139
|
+
try {
|
|
140
|
+
views = [commitViewOf(parent), commitViewOf(child), new Set(leafKeySuccessions(parent, child).map((s) => s.leafIndex))];
|
|
141
|
+
}
|
|
142
|
+
catch {
|
|
143
|
+
return undefined;
|
|
144
|
+
}
|
|
145
|
+
return diffCommitViews(views[0], views[1], views[2]);
|
|
146
|
+
}
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The convergence policy every `marmot` engine runs: MIP-03 policy v1 with
|
|
3
|
+
* app-payload witnesses switched off, so the branch choice is structural
|
|
4
|
+
* only (commit depth, then tip committer, then tip digest) and the same on
|
|
5
|
+
* every member. A deliberate, documented deviation — rationale and interop
|
|
6
|
+
* impact in specs/epic-marmot-client/architecture.md, "Structural branch
|
|
7
|
+
* selection".
|
|
8
|
+
*
|
|
9
|
+
* Witnesses cannot make that choice consistently here: a witness is an
|
|
10
|
+
* application message that decrypts on a candidate branch, and a sender can
|
|
11
|
+
* never decrypt its own messages. In a same-epoch race each committer counts
|
|
12
|
+
* the other branch's messages but not its own branch's, so each prefers the
|
|
13
|
+
* other's commit. With `witnessQuorumSendersPerEpoch: 0` no branch scores a
|
|
14
|
+
* witness; `maxWitnessOverrideDepth: 0` keeps the policy valid (it must not
|
|
15
|
+
* exceed `maxRewindCommits`). The rollback horizon is unchanged.
|
|
16
|
+
*
|
|
17
|
+
* It lives in `history/` (re-exported by `client/client-config.ts`) so the
|
|
18
|
+
* persisted rewind window's horizon ({@link REWIND_HORIZON}) and the engines'
|
|
19
|
+
* selection horizon read ONE constant: a horizon change that moved only one of
|
|
20
|
+
* them would make selection narrower than retention (silently) or retention
|
|
21
|
+
* narrower than selection (unsafe). Changing the horizon itself (ADR-016
|
|
22
|
+
* AC-ARCH-3 recommends 3) is a build-wide protocol parameter decided in its own
|
|
23
|
+
* ADR — peers with different horizons diverge on retention. That ADR must also
|
|
24
|
+
* re-decide removal finality (ADR-017 R-6, AR-R7, AR-R8; its Evolution Trigger
|
|
25
|
+
* "The horizon changes"): the rule reaches h - 1 commits past the removal's
|
|
26
|
+
* parent and the replay loop costs h + 1 commits per round, so a shorter
|
|
27
|
+
* horizon shrinks both.
|
|
28
|
+
*/
|
|
29
|
+
import { type ConvergencePolicy, type HiddenCreditPolicy } from '@941design/marmot-engine/core';
|
|
30
|
+
export declare const MARMOT_CONVERGENCE_POLICY: ConvergencePolicy;
|
|
31
|
+
/** The rollback horizon `marmot`'s engines select with and its persisted rewind window retains. */
|
|
32
|
+
export declare const REWIND_HORIZON: number;
|
|
33
|
+
/**
|
|
34
|
+
* The hidden-credit policy of the branch-aware own-leaf fence (ADR-016 D6; epic `marmot-branch-aware-own-leaf-fence`,
|
|
35
|
+
* spec Design Decision 7, OQ-1): the one value `group-runtime.ts` hands every engine it builds. It decides how much
|
|
36
|
+
* credit the real device assumes for the branch of its own cloned leaf that it cannot open.
|
|
37
|
+
*
|
|
38
|
+
* - `conservative` (shipped until 2026-11-09, when the owner's OQ-1 answer took effect): the hidden subtree may carry up to `U` credit, so the
|
|
39
|
+
* device never stays on a branch the group may have abandoned. An attacker whose burst outgrows canonical's
|
|
40
|
+
* other-leaf credit still fences the real device, visibly, with the `leaf-equivocation` recorded (ADR-016 AR-6′).
|
|
41
|
+
* - `anchored-zero` (the default since 2026-11-09 — owner decision 17, OQ-1 (ii); the spec's recommendation): an opaque head by the device's own leaf, anchored at its parent,
|
|
42
|
+
* earns no hidden credit there, so the device stays on canonical whenever canonical carries other-leaf credit, at
|
|
43
|
+
* the price of staying behind if other members built on the clone's branch (told through its own record).
|
|
44
|
+
*
|
|
45
|
+
* Local to the device (no wire effect, no stored format): the default is this one constant. It is
|
|
46
|
+
* not a public option; tests choose the other value through the internal `engineOptions` hook of the client.
|
|
47
|
+
*/
|
|
48
|
+
export declare const MARMOT_HIDDEN_CREDIT_POLICY: HiddenCreditPolicy;
|